METAL-NT(1) | Metal | METAL-NT(1) |
metal-nt - metal native translator
metal-nt [options] [filename]
metal-nt is a tool translating AIR virtual code to native code. The translation process is driven by the input file kind and an optional script, specified via the -N option. Each file kind has an associated script kind. Each script kind supports multiple formats. In particular, for those scripts backed by a FlatBuffer, both the JSON and binary representation of the FlatBuffer are valid script formats.
The translation of an assembly or object file produces a target specific assembly file, or a MachO MH_OBJECT file. AIR assembly/objects scripts can be used to customize the translation process. They are both backed by FlatBuffers. The file extensions of the FlatBuffer JSON representations are .aira-json and .airo-json. The file extensions of the FlatBuffer binary representations are .aira and .airo.
The translation of an executable MetalLib results in a MachO MH_GPU_EXECUTE file. Each qualified function in the MetalLib is translated independently. An AIR function script can be used to customize the translation process of a single qualified function. AIR functions scripts are backed by FlatBuffers. The file extension for the Flatbuffer JSON encoding is .airf-json. The file extension of the Flatbuffer binary encoding is .airf. If a function script is not specified, all the qualified functions in the MetalLib are translated. This still results in a single MachO being generated, containing the translation of all the qualified functions.
The translation of a MetalLib dynamic library produces a MachO MH_GPU_DYLIB. An AIR dynamic library script can be used to customize the translation process. Such script is backed by a Flatbuffer. The file extension of the JSON encoding is .aird-json. The file extension of the binary encoding is .aird.
A pipeline can be created by invoking metal-nt with an executable MetalLib and an AIR pipeline script. AIR pipeline scripts are backed by Flatbuffers. The Flatbuffer JSON encoding file extension is .airp-json. The Flatbuffer binary encoding file extension is .airp. The provided MetalLib must contains all the qualified functions referenced by the AIR pipeline script. The output of a pipeline translation is a MachO MH_GPU_EXECUTE.
Plugins implementing translation to binary code might provide support for builtin scripts. Such kind of scripts does not require any assembly, object, or MetalLib file input. The output of a builtin translation is a MachO MH_GPU_EXECUTE. The file extension and contents of builtin scripts are specific to each plugin. Refer to each plugin documentation for more information.
Metal pipelines scripts describe how to create a pipeline using a syntax that mirrors the one provided by the Metal.framework API. They are backed by Flatbuffers. The JSON encoding file extension is .mtlp-json. The binary encoding file extension is .mtlp.
Metal pipelines scripts are way more expressive than AIR pipeline scripts. Qualified functions of a specific MetalLib can be directly referenced from a Metal pipelines script, removing the need of providing a MetalLib argument to metal-nt. They also allow to specialize qualified functions and to stitch them together prior of pipeline creation.
The output of a Metal pipelines script translation is a MachO of type MH_GPU_EXECUTE that contains the translation of all the pipelines described by the Metal pipelines script.
Specifying a newer min or SDK version allows to assume features of that OS or SDK in the output file. The format of <min_version> and <sdk_version> is a version number such as 16.0 or 16.2.
${TOOLCHAIN}/lib/air-nt/config.yaml Default configuration file
To build Metal pipelines:
$ metal-nt -arch amdgpu_gfx600 foobar-air64.metallib -N foobar.mtlp-json -o foobar.metallib
To build a Metal dynamic library:
$ metal-nt -arch amdgpu_gfx600 libfoo-air64.metallib -o libfoo.metallib
To build Metal pipelines without directly referencing any MetalLib:
$ metal-nt -arch amdgpu_gfx600 -L my-libs-dir -N foobar.mtlp-json
To report bugs, please visit <https://developer.apple.com/bug-reporting/>.
metal-arch(1) metal-pipelines-script(5)
Metal Shading Language Specification: <https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf>
2014-2023, The Metal Team
July 5, 2023 | 15 |