Implementation:Ggml org Ggml Metal backend api

Metadata

Field	Value
Page Type	Implementation (API Header)
Knowledge Sources	GGML
Domains	ML_Infrastructure, Tensor_Computing, GPU_Computing
Last Updated	2026-02-10 12:00 GMT

Overview

Declares the Apple Metal GPU backend interface for running computation graphs on Apple GPUs via the Metal framework on macOS and iOS.

Description

ggml-metal.h (61 lines) provides the public API for the Metal backend, which is the primary GPU backend for Apple platforms. The header includes a historical comment describing the original design where ggml_metal_graph_compute() was the main entry point, though the current interface uses the standard GGML backend abstraction.

API functions:

ggml_backend_metal_init() -- creates and returns a Metal backend instance
ggml_backend_is_metal() -- identifies Metal backends
ggml_backend_metal_set_abort_callback() -- registers a callback for early termination of GPU computation
ggml_backend_metal_supports_family(backend, family) -- checks if the GPU supports a specific Metal GPU family (useful for feature-gating shader code based on hardware capabilities; see Apple's Metal Feature Set Tables)
ggml_backend_metal_capture_next_compute() -- enables GPU frame capture for the next ggml_backend_graph_compute() call, useful for debugging with Xcode's GPU debugger
ggml_backend_metal_reg() -- returns the backend registration handle

Memory buffers are mapped between host and device for kernel argument binding, leveraging Apple Silicon's unified memory architecture.

Usage

Include this header on Apple platforms to initialize the Metal GPU backend. This is the recommended backend for inference on Apple Silicon (M1, M2, M3, M4 series) and older macOS systems with discrete AMD GPUs.

Code Reference

Source Location

GGML repo, file: include/ggml-metal.h, 61 lines.

Signature

GGML_BACKEND_API ggml_backend_t ggml_backend_metal_init(void);
GGML_BACKEND_API bool ggml_backend_is_metal(ggml_backend_t backend);
GGML_BACKEND_API void ggml_backend_metal_set_abort_callback(
    ggml_backend_t backend,
    ggml_abort_callback abort_callback,
    void * user_data);
GGML_BACKEND_API bool ggml_backend_metal_supports_family(
    ggml_backend_t backend, int family);
GGML_BACKEND_API void ggml_backend_metal_capture_next_compute(
    ggml_backend_t backend);
GGML_BACKEND_API ggml_backend_reg_t ggml_backend_metal_reg(void);

Import

#include "ggml-metal.h"

Dependencies

ggml.h -- core GGML types
ggml-backend.h -- backend abstraction types
<stddef.h>, <stdbool.h> -- standard C types

I/O Contract

Inputs

Parameter	Type	Required	Description
`backend`	`ggml_backend_t`	Yes (for most functions)	Metal backend instance.
`abort_callback`	`ggml_abort_callback`	Yes (for set_abort_callback)	Function called to check if computation should be aborted.
`user_data`	`void *`	No	User data passed to the abort callback.
`family`	`int`	Yes (for supports_family)	Metal GPU family number to check support for.

Outputs

Output	Type	Description
Backend handle	`ggml_backend_t`	Initialized Metal backend instance.
Is Metal	`bool`	True if the provided backend is Metal-based.
Family support	`bool`	True if the GPU supports the specified Metal GPU family.
Registration	`ggml_backend_reg_t`	Registration handle for backend discovery.

Usage Examples

Metal Backend Initialization

#include "ggml-metal.h"

ggml_backend_t metal = ggml_backend_metal_init();

// Check for GPU family support (e.g., Apple7 = family 7)
if (ggml_backend_metal_supports_family(metal, 7)) {
    // Use advanced features available on M1+ chips
}

GPU Debugging with Frame Capture

#include "ggml-metal.h"

// Enable capture for the next compute call (for Xcode GPU debugger)
ggml_backend_metal_capture_next_compute(metal);
ggml_backend_graph_compute(metal, graph);

Abort Callback

#include "ggml-metal.h"

bool should_abort(void * data) {
    return *(bool *)data;
}

bool cancel_flag = false;
ggml_backend_metal_set_abort_callback(metal, should_abort, &cancel_flag);

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment