Module Rig.Image

Code loaded on a device.

#type device := t

#type t

The type for loaded images: a binary in a device's format, whose functions that device's work runs.

#val load : device -> string -> (t, string) Stdlib.result

load d binary loads binary on d, such as a code object for AMD, a cubin for NV, a CUDA module for CUDA, a metallib for Metal or a relocatable ELF object for host (Linking). Each call loads binary again, so that each image's module variables are its own. Where d's memory holds the code, it counts in d's budget, and load places it there after the work submitted on d before it. Where d's copy engine copies it, load returns without waiting for that work or the copy, and work that runs the image follows the copy. The image stays loaded while it is reachable. A call on d that finds it collected (Reclamation) unloads it once the work submitted on d before that call is done.

It is Error why if d's driver rejects binary, where why is d's name, then the driver's reason. d stays usable.

Raises Invalid_argument if d is an io device, which loads no code, or its driver places the code in d's memory (Place in Rig_edge.code) where d has no copy engine and the host does not address that memory; and Lost if d is lost or its driver faults during the load.

#val device : t -> device

device i is the device i is loaded on.

#type func

The type for a function of a loaded image. A function keeps its image reachable.

#val resolve : t -> string -> func option

resolve i f is i's function f, made ready to launch, or None if i has none. The first resolve of f makes what its launches need, such as its scratch.

Raises Invalid_argument if i's device cannot run f (Rig_edge.Driver.entry), Out_of_memory if the device has no memory for what f's launches need after the rounds of reclamation (Reclamation), and Lost if i's device is lost.

#val prepare : t -> string -> unit

prepare i f may start making i's function f ready to launch, and returns without waiting. The first resolve of f waits for what it started and returns or raises what it would have. Preparing each function a program launches before resolving any lets a device that makes them slowly, as Metal compiles a pipeline, make them concurrently; on another device it does nothing. It does nothing if i has no function f, or f was resolved or prepared, and may wait while another domain resolves a function of i. What it starts is i's until i unloads, which waits for none of it.

Raises Lost if i's device is lost.

#val name : func -> string

name fn is fn's name in its image.

#val image : func -> t

image fn is the image fn belongs to.

#val params : func -> int option

params fn is the number of parameter bytes, from byte 0, that fn reads, or None if its driver does not know it. A launch of fn must give at least that many (Submission.launch).

#val threads : func -> int option

threads fn is the most threads a group of fn may have, or None if its driver does not know it. Submission.Run.threads refuses more.

Raw function values

This value serves code that refers to a function outside a launch's parameters, such as an indirect command buffer, a CUDA graph over a module's functions, or host code that calls another image's function. rig cannot see where such code keeps a value, so it cannot keep the image loaded for it. Except for these uses, a launch is better given a function's value by an entry ref (Submission.entry), which keeps the image.

#val entry : func -> int

entry fn is the value by which compiled code refers to fn (the code of Rig_edge.Driver.entry), such as a kernel descriptor's address, a CUfunction, an MTLComputePipelineState or the address of a host function.

Warning. The value is valid only while fn is reachable. Work that uses it must keep fn reachable until the work is done, for example with the keep of its submission (Submission.make).