Diagnostics Metal

Apple Silicon diagnostics and managed-model fit reporting for Metal.

The Metal diagnostics path inspects the default device, reports unified memory and feature support, and optionally projects how a selected GGUF or managed model fits once runtime allocations and KV reservation are included.

5 exports 0 methods src/diagnostics_metal.zig

5 exports shown

struct

Options

pub const Options = struct

Configuration for a Metal diagnostics run.

src/diagnostics_metal.zig:22

struct

ManagedModelInfo

pub const ManagedModelInfo = struct

Catalog metadata for a managed (downloadable) model.

src/diagnostics_metal.zig:36

struct

UnifiedFitEstimate

pub const UnifiedFitEstimate = struct

Estimated unified-memory breakdown for running a model on Apple Silicon.

src/diagnostics_metal.zig:120

function

run

pub fn run(opts: Options, allocator: std.mem.Allocator) !void

Run a four-step Metal preflight check (host environment, device, shader assets, model) and print a colour-coded report to stdout.

The steps are: (1) host OS and CPU arch, (2) Metal device capabilities and unified-memory budget, (3) shader source presence and MSL smoke compile, (4) GGUF or managed-model memory-fit estimate. Returns `error.DiagnosticsFailed` if any check resolves to `.fail`.

Parameters

opts: Diagnostic configuration: optional model path, context ceiling, managed-model entry, and shader directory.
allocator: Used for Metal device initialisation and GGUF header inspection.

Returns

`error.DiagnosticsFailed` when one or more checks emit a FAIL status; otherwise succeeds or propagates I/O errors.

src/diagnostics_metal.zig:199

function

estimateUnifiedFit

pub fn estimateUnifiedFit( inspection: ModelInspection, recommended_working_set_bytes: u64, total_memory_bytes: u64, requested_context_length: ?u32, ) UnifiedFitEstimate

Compute a conservative unified-memory breakdown for running a model on Apple Silicon.

Combines tensor weight bytes with the runtime shared-buffer and KV-cache cost at the resolved context length, then determines how many tokens could fit within the Metal working-set budget.

Parameters

inspection: GGUF model inspection result supplying tensor size and model config.
recommended_working_set_bytes: Metal driver's recommended working-set ceiling; falls back to `total_memory_bytes` when zero.
total_memory_bytes: Physical unified memory on the device.
requested_context_length: Optional caller-supplied context cap; when null the model's own `context_length` is used (clamped by the backend runtime cap).

Returns

A `UnifiedFitEstimate` with per-category byte breakdowns and derived fit status fields.

src/diagnostics_metal.zig:490