Metal libraries

MetalLib(; functions, kwargs...)
MetalLib(lib::MetalLib; kwargs...)
read(io_or_path, MetalLib)

A Metal library (.metallib file): a container of MetalLibFunctions with their AIR modules and metadata. Libraries can be built from scratch, read from a file or stream, and written with write(io_or_path, lib). The second form copies lib, replacing the fields given as keyword arguments.

Reading and writing a library without changing it reproduces it byte for byte, including parts of the format Metal.jl does not decode: unknown tags are kept as raw bytes and written back in their original position, and the layout of the original file (tag order, group size conventions, shared modules and reflection entries) is remembered. Edits are supported in a bounded way: functions can be added, removed or replaced, and their metadata changed. The writer then recomputes offsets and sizes, the hashes of new modules, and the UUID of the library (unless you set a new one): a library that was read keeps its UUID only as long as it is written back unchanged. Tags Metal.jl does not decode are not updated by edits.

Malformed input throws a MetalLibFormatError.

MetalLibFunction(; name, air_module, air_version, metal_version, kwargs...)
MetalLibFunction(fun::MetalLibFunction; kwargs...)

A function in a MetalLib: its name and type, its AIR module (LLVM bitcode) with the AIR and Metal language versions it targets, and its metadata. The second form copies fun, replacing the fields given as keyword arguments.

Fields:

• name, type (a ProgramType, METALLIB_COMPUTE_FUNCTION by default);
• air_module, air_version, metal_version;
• constants: the function constants (FunctionConstants) the function declares;
• debug_info: a DebugInfo with the line and file of the function's definition;
• dependencies: paths of the files the function was linked from;
• source_id: the identifier of the embedded source archive the function comes from;
• reflection_data: an AIRR reflection flatbuffer, as emitted by Apple's toolchain.

FunctionConstant(name, datatype, index, required)

A function constant declared by a MetalLibFunction: its name, data type (an MTLDataType), index, and whether a value must be provided for it (constants an MSL function only uses after checking is_function_constant_defined are not required).

DebugInfo(line, path)

Where a MetalLibFunction was defined: a line number and the path of the source file.

MetalLibFormatError

Thrown when reading a Metal library that is malformed or that uses parts of the format Metal.jl does not support. offset is the position in the library where the problem was detected, if known.

Metal.reflection(mod::LLVM.Module, entry::String)

Derive the reflection data of the function entry of an AIR module from the module's metadata, like Apple's linker does. The result can be encoded with Metal.reflection_data.

Only kernels and visible functions are supported, with buffer (incl. threadgroup memory) and built-in arguments. Other functions or arguments (e.g. textures) throw an error, as does malformed metadata.

An argument is unused if the metadata says so (as in modules Apple's linker linked), or if the module does not use it. Arguments that only dead code uses count as used.

The function constants are those of the library function (see MetalLibFunction). For a module that is shared by several functions, that may include constants the function doesn't use, which Apple's linker would have removed.

The module's LLVM context must be active.

Metal.reflection(fun::MetalLibFunction)
Metal.reflection(data::Vector{UInt8})

Decode the reflection data of a library function, as stored by Apple's toolchain, or nothing if the function has none (Metal.jl does not generate it). The result is the root ReflectionObject of the data, a :Reflection: its nodes describe the function, its arguments and the types involved, and lists like kernel_functions refer to them by NodeId.

julia> r = Metal.reflection(lib.functions[1]);julia> kernel = r[only(r.kernel_functions)];julia> [r[arg].name for arg in kernel.arguments]2-element Vector{String}: "a" "i"

Malformed data throws a FlatBufferError.

Metal.reflection_data(root::ReflectionObject)

Encode reflection data, the inverse of Metal.reflection: root is a :Reflection, e.g. as decoded, or built with the ReflectionObject constructor. Nodes that were decoded as an UnknownReflectionNode cannot be encoded.

Metal.ReflectionObject

A table or struct of the reflection data of a library function (see Metal.reflection). nameof(obj) is its type in Apple's schema, without the namespace (e.g. :BufferArg or :KernelFunction), and its fields are available as properties, in the order of the schema.

Fields that the data does not contain are nothing, except for numbers and booleans, which then have their default value. Structs that only wrap a number (like UIntValue) are used by the schema for optional values, so a nothing there means "not specified" rather than 0.

References between nodes are NodeId objects; index the reflection root with them to get the node they refer to.

Metal.ReflectionEnum

A value of an enumeration in reflection data: type is the enumeration, name the name of the value, or nothing if the schema doesn't know it, and value its number.

Metal.UnknownReflectionNode

A node of a kind the schema doesn't know: tag is its type, offset where its table starts in the reflection data.

FlatBufferError(msg, offset)

An error decoding a FlatBuffer: offset is the position in the buffer where it was found.