github ↗
docs menu
on this page

Module Rig_nv_abi.Method

Channel methods.

Channel methods.

A channel runs pushbuffers. In a pushbuffer, a header word names a subchannel, a method and a count; the count words after it are the arguments of that method and of the methods after it, one each. A channel has eight subchannels, each bound to an engine by set_object. Semaphore methods run on every channel, whatever engines its subchannels bind.

Each value of this module is the words of one operation, headers included, as a Template.t. An operand that may be unknown when encoding, such as an address or a payload, is a Template.operand; an operand the operation fixes, such as a class, is an integer.

Addresses are the GPU's virtual addresses. Compute methods are those of the compute classes from AMPERE_COMPUTE_B (0xc7c0) on, copy methods those of the copy classes from AMPERE_DMA_COPY_B (0xc7b5) on.

Engines

#type engine =
  1. #| Compute
    (*

    The compute engine, on subchannel 1.

    *)
  2. #| Copy
    (*

    The copy engine, on subchannel 4.

    *)

The type for the engines a channel binds.

#val set_object : engine -> int -> Template.t

set_object e cls binds the engine of class cls to e's subchannel. A channel runs no method of e before it.

Semaphores

A semaphore is a 64-bit word in memory, 8-byte aligned, below 2{^40}.

A stamped release (release_stamp, copy_release_stamp, Qmd.release) also writes a stamp into the 8 bytes at addr + 8, and its addr must be 16-byte aligned. The stamp is the GPU's timer in nanoseconds, an unsigned 64-bit integer in little-endian order. The timer is a clock of the GPU: a reader converts its times to the host clock (CLOCK_MONOTONIC) by the offset between the two, measured with a stamp the GPU writes between two readings of the host clock.

acquire addr v stops the channel until the semaphore w at addr is at least v in circular order: until w - v, computed modulo 2{^64}, is below 2{^63}.

release addr v waits for the channel's earlier work to complete, every engine idle, then writes the 64-bit v into the semaphore at addr, so that any reader who sees v, the host and other devices included, sees the work's writes. The channel's later methods run after the write.

release_stamp addr v is release that also writes a stamp at addr + 8 (Semaphores).

#val interrupt : Template.t

interrupt raises a non-stalling interrupt when the channel reaches it, without waiting, so it may reach the host before the write of a release just before it is visible.

Compute

#val shared_memory_window : Template.operand -> Template.t

shared_memory_window addr makes kernels' shared memory appear at the address addr.

#val local_memory_window : Template.operand -> Template.t

local_memory_window addr makes kernels' local memory appear at the address addr.

#val local_memory : Template.operand -> per_tpc:Template.operand -> Template.t

local_memory addr ~per_tpc gives kernels the local memory at addr, per_tpc bytes for each texture processing cluster (Local_memory.t.per_tpc), and lets every streaming multiprocessor use it. Launches scheduled after it use it. A launch scheduled before it must have completed: a release separates them, and the caller keeps the memory until the launches that use it complete.

#val invalidate_caches : Template.t

invalidate_caches invalidates the compute engine's instruction, data and constant caches, which would hide earlier writes, the host's and other devices' included, from launches scheduled after it. It does not wait for the engine's work to complete.

#val wait_for_idle : Template.t

wait_for_idle holds the compute engine's later methods until the launches scheduled before it have completed. A launch scheduled after it reads what those wrote.

#val schedule : Template.operand -> Template.t

schedule addr schedules the launch descriptor at addr, 256-byte aligned and below 2{^40}, and the descriptors chained to it (Qmd.t.chain). The channel goes on without waiting for the launches: launches scheduled one after another run at the same time, and only a chain orders them.

Copies

#val max_copy : int

max_copy is the most bytes one copy moves, of one row of a box, and of one fill, 2{^31}.

copy ~dst ~src n copies the n bytes at src to dst on the copy engine, in one launch of one line. n is at most max_copy; a longer copy is several, at increasing offsets.

box ~dst ~src ~dst_pitch ~src_pitch ~rows n copies rows rows of n bytes on the copy engine, row i from src + i * src_pitch to dst + i * dst_pitch, in one multi-line launch. n is at most max_copy, and rows and each pitch below 2{^32}; a larger box is several.

#type component =
  1. #| One
    (*

    One byte.

    *)
  2. #| Four
    (*

    Four bytes.

    *)

The type for the sizes of a fill's components.

fill c ~dst v n writes n components of c's size from dst on the copy engine, each holding the low bytes of the 32-bit v, least significant first, in one launch that reads no memory. n components take at most max_copy bytes.

copy_release addr v writes the 64-bit v into the 8 bytes at addr, 8-byte aligned, once the copy engine's earlier copies are complete, so that any reader who sees v, the host and other devices included, sees their writes.

#val copy_release_stamp : Template.operand -> Template.operand -> Template.t

copy_release_stamp addr v is copy_release that also writes a stamp at addr + 8 (Semaphores).