Last updated: 2026-06-12

Inference Runtime

Kmd

All API Sections

Thin AMDGPU kernel-driver queries used by direct ZINC_RT tiers.

This file intentionally starts with capability discovery only. T2 UMQ queue creation needs the same UAPI definitions, but selection must first prove the kernel exposes compute user queues instead of relying on kernel version alone.

42 exports 0 methods src/zinc_rt/kmd.zig

42 exports shown

enum

QueryStatus

# 
pub const QueryStatus = enum

Outcome of probing the AMDGPU render node for compute user-queue support.

Each variant maps to a specific failure mode when discovering whether the kernel exposes the UMQ surface ZINC_RT tier 2 needs.

src/zinc_rt/kmd.zig:15

struct

ComputeUserqInfo

# 
pub const ComputeUserqInfo = struct

Compute user-queue capability metadata reported by the kernel.

Captures the slot count and the EOP (end-of-pipe) scratch buffer sizing the driver requires when creating a compute UMQ.

src/zinc_rt/kmd.zig:29

struct

QueryResult

# 
pub const QueryResult = struct

Combined result returned by `queryComputeUserq`.

Carries the discovery status plus optional capability info and the errno captured from the failing ioctl, when applicable.

src/zinc_rt/kmd.zig:38

constant

AMDGPU_HW_IP_COMPUTE

# 
pub const AMDGPU_HW_IP_COMPUTE: u32 = 1

AMDGPU HW IP type selector for the compute pipe used by `AMDGPU_INFO` queries.

src/zinc_rt/kmd.zig:48

constant

AMDGPU_INFO_HW_IP_INFO

# 
pub const AMDGPU_INFO_HW_IP_INFO: u32 = 0x02

`AMDGPU_INFO` sub-query that returns `DrmAmdgpuInfoHwIp` for a given HW IP.

src/zinc_rt/kmd.zig:50

constant

AMDGPU_INFO_UQ_FW_AREAS

# 
pub const AMDGPU_INFO_UQ_FW_AREAS: u32 = 0x24

`AMDGPU_INFO` sub-query that returns user-queue firmware area metadata (`DrmAmdgpuInfoUqMetadata`).

src/zinc_rt/kmd.zig:52

constant

AMDGPU_USERQ_OP_CREATE

# 
pub const AMDGPU_USERQ_OP_CREATE: u32 = 1

`DRM_AMDGPU_USERQ` op code that allocates a new user-mode queue.

src/zinc_rt/kmd.zig:54

constant

AMDGPU_USERQ_OP_FREE

# 
pub const AMDGPU_USERQ_OP_FREE: u32 = 2

`DRM_AMDGPU_USERQ` op code that releases a previously created user-mode queue.

src/zinc_rt/kmd.zig:56

constant

AMDGPU_GEM_DOMAIN_GTT

# 
pub const AMDGPU_GEM_DOMAIN_GTT: u64 = 0x2

GEM domain flag requesting allocation in system GTT memory.

src/zinc_rt/kmd.zig:59

constant

AMDGPU_GEM_DOMAIN_VRAM

# 
pub const AMDGPU_GEM_DOMAIN_VRAM: u64 = 0x4

GEM domain flag requesting allocation in device VRAM.

src/zinc_rt/kmd.zig:61

constant

AMDGPU_GEM_DOMAIN_DOORBELL

# 
pub const AMDGPU_GEM_DOMAIN_DOORBELL: u64 = 0x40

GEM domain flag requesting allocation in the MMIO doorbell aperture.

src/zinc_rt/kmd.zig:63

constant

AMDGPU_GEM_CREATE_CPU_GTT_USWC

# 
pub const AMDGPU_GEM_CREATE_CPU_GTT_USWC: u64 = 1 << 2

GEM creation flag asking the kernel to map GTT memory as CPU write-combined for fast streaming writes.

src/zinc_rt/kmd.zig:66

constant

AMDGPU_GEM_CREATE_VRAM_CLEARED

# 
pub const AMDGPU_GEM_CREATE_VRAM_CLEARED: u64 = 1 << 3

GEM creation flag asking the kernel to zero-fill VRAM allocations before returning the BO.

src/zinc_rt/kmd.zig:68

constant

AMDGPU_GEM_CREATE_VM_ALWAYS_VALID

# 
pub const AMDGPU_GEM_CREATE_VM_ALWAYS_VALID: u64 = 1 << 6

GEM creation flag keeping the BO permanently mapped in the device VM so it never needs revalidation.

src/zinc_rt/kmd.zig:70

constant

AMDGPU_VA_OP_MAP

# 
pub const AMDGPU_VA_OP_MAP: u32 = 1

`DRM_AMDGPU_GEM_VA` operation that binds a BO into the device virtual address space.

src/zinc_rt/kmd.zig:73

constant

AMDGPU_VM_PAGE_READABLE

# 
pub const AMDGPU_VM_PAGE_READABLE: u32 = 1 << 1

VA mapping flag granting GPU read access to the mapped range.

src/zinc_rt/kmd.zig:75

constant

AMDGPU_VM_PAGE_WRITEABLE

# 
pub const AMDGPU_VM_PAGE_WRITEABLE: u32 = 1 << 2

VA mapping flag granting GPU write access to the mapped range.

src/zinc_rt/kmd.zig:77

constant

AMDGPU_VM_PAGE_EXECUTABLE

# 
pub const AMDGPU_VM_PAGE_EXECUTABLE: u32 = 1 << 3

VA mapping flag granting GPU shader-execute access to the mapped range.

src/zinc_rt/kmd.zig:79

constant

AMDGPU_VM_MTYPE_DEFAULT

# 
pub const AMDGPU_VM_MTYPE_DEFAULT: u32 = 0 << 5

VA mapping flag selecting the default memory type (MTYPE) for the GPU page table entry.

src/zinc_rt/kmd.zig:81

struct

DrmAmdgpuGemCreateIn

# 
pub const DrmAmdgpuGemCreateIn = extern struct

Input layout for the `DRM_IOCTL_AMDGPU_GEM_CREATE` ioctl.

Mirrors the kernel UAPI struct describing the requested buffer size, alignment, domain mask, and creation flags.

src/zinc_rt/kmd.zig:91

struct

DrmAmdgpuGemCreateOut

# 
pub const DrmAmdgpuGemCreateOut = extern struct

Output layout returned by `DRM_IOCTL_AMDGPU_GEM_CREATE`, holding the freshly allocated BO handle.

src/zinc_rt/kmd.zig:99

union

DrmAmdgpuGemCreate

# 
pub const DrmAmdgpuGemCreate = extern union

Tagged union packing the in/out forms of the GEM-create ioctl into the same buffer the kernel reads and writes.

src/zinc_rt/kmd.zig:105

struct

DrmAmdgpuGemMmapIn

# 
pub const DrmAmdgpuGemMmapIn = extern struct

Input layout for `DRM_IOCTL_AMDGPU_GEM_MMAP`, identifying the BO to expose to userspace.

src/zinc_rt/kmd.zig:111

struct

DrmAmdgpuGemMmapOut

# 
pub const DrmAmdgpuGemMmapOut = extern struct

Output layout returned by `DRM_IOCTL_AMDGPU_GEM_MMAP` with the file offset to pass to `mmap`.

src/zinc_rt/kmd.zig:117

union

DrmAmdgpuGemMmap

# 
pub const DrmAmdgpuGemMmap = extern union

Tagged union packing the in/out forms of the GEM-mmap ioctl into one shared buffer.

src/zinc_rt/kmd.zig:122

struct

DrmAmdgpuGemVa

# 
pub const DrmAmdgpuGemVa = extern struct

Argument layout for `DRM_IOCTL_AMDGPU_GEM_VA`, the ioctl that maps a BO into the GPU virtual address space.

Encodes the BO handle, VA operation, page-permission flags, target VA range, and any syncobj fence handles.

src/zinc_rt/kmd.zig:129

struct

DrmAmdgpuInfo

# 
pub const DrmAmdgpuInfo = extern struct

Argument layout for `DRM_IOCTL_AMDGPU_INFO`, the generic info-query ioctl.

`return_pointer`/`return_size` describe a userspace output buffer; `query` selects a sub-query whose discriminator-specific parameters live in `query_data`.

src/zinc_rt/kmd.zig:145

struct

DrmAmdgpuInfoHwIp

# 
pub const DrmAmdgpuInfoHwIp = extern struct

Output buffer for `AMDGPU_INFO_HW_IP_INFO`.

Reports the HW IP version and capabilities, ring-buffer alignment requirements, the bitmask of available kernel rings, and the count of user-queue slots — tier 2 checks both `available_rings` and `userq_num_slots` to confirm UMQ support.

src/zinc_rt/kmd.zig:185

union

DrmAmdgpuInfoUqMetadata

# 
pub const DrmAmdgpuInfoUqMetadata = extern union

Output buffer for `AMDGPU_INFO_UQ_FW_AREAS`, sized per IP type.

Reports the per-queue scratch buffers the firmware needs: shadow/CSA areas for GFX, the EOP buffer for compute, and the CSA area for SDMA.

src/zinc_rt/kmd.zig:198

struct

DrmAmdgpuUserqIn

# 
pub const DrmAmdgpuUserqIn = extern struct

Input layout for the `DRM_IOCTL_AMDGPU_USERQ` ioctl.

Describes the create/free op, the target IP (compute, gfx, sdma), the doorbell BO handle and slot offset within it, the VA ranges of the queue ring buffer plus its read/write pointers, and a pointer to the IP-specific MQD blob.

src/zinc_rt/kmd.zig:217

struct

DrmAmdgpuUserqOut

# 
pub const DrmAmdgpuUserqOut = extern struct

Output layout returned by a successful `AMDGPU_USERQ_OP_CREATE`, containing the kernel-assigned queue id used by subsequent ioctls.

src/zinc_rt/kmd.zig:233

union

DrmAmdgpuUserq

# 
pub const DrmAmdgpuUserq = extern union

Tagged union packing the in/out forms of the user-queue ioctl into the same buffer.

src/zinc_rt/kmd.zig:239

struct

DrmAmdgpuUserqMqdComputeGfx11

# 
pub const DrmAmdgpuUserqMqdComputeGfx11 = extern struct

GFX11 compute MQD payload pointed at by `DrmAmdgpuUserqIn.mqd`.

Currently only the EOP scratch VA is required; matches the kernel's `drm_amdgpu_userq_mqd_compute_gfx11` layout.

src/zinc_rt/kmd.zig:246

struct

Bo

# 
pub const Bo = struct

Thin handle for a kernel-managed GEM buffer object.

Pairs the kernel GEM handle with the allocation size so callers can re-issue ioctls (mmap, VA map) without re-querying the size.

src/zinc_rt/kmd.zig:252

function

queryComputeUserq

# 
pub fn queryComputeUserq(render_node: []const u8) QueryResult

Probe an AMDGPU render node to decide whether the compute user-mode-queue surface is usable.

Opens the render node, asks the kernel for compute HW IP info plus user-queue firmware areas, and validates that the queue slots and EOP buffer parameters look sane.

Parameters

render_node
Absolute path to the DRI render node (e.g. `/dev/dri/renderD128`).

Returns

A `QueryResult` whose `status` field identifies the precise failure mode or `.available` on success, with `info` populated when compute UMQ is ready to use.

Notes

Returns `.unsupported_os` immediately on non-Linux builds without opening any file.

src/zinc_rt/kmd.zig:292

function

queryHwIp

# 
pub fn queryHwIp(file: std.fs.File, ip_type: u32) !DrmAmdgpuInfoHwIp

Issue `AMDGPU_INFO_HW_IP_INFO` for the given HW IP type on an open render-node file.

Parameters

file
Open file handle for the AMDGPU render node.
ip_type
IP selector constant such as `AMDGPU_HW_IP_COMPUTE`.

Returns

The kernel-filled `DrmAmdgpuInfoHwIp` for IP instance 0.

Notes

Returns `error.IoctlFailed` on failure; inspect `lastErrno()` for the captured errno.

src/zinc_rt/kmd.zig:342

function

createGem

# 
pub fn createGem(file: std.fs.File, size: u64, alignment: u64, domains: u64, flags: u64) !Bo

Allocate a GEM buffer object via `DRM_IOCTL_AMDGPU_GEM_CREATE`.

Parameters

file
Open file handle for the AMDGPU render node.
size
Buffer size in bytes.
alignment
Required base alignment in bytes.
domains
Bitmask of `AMDGPU_GEM_DOMAIN_*` constants selecting GTT, VRAM, or doorbell aperture.
flags
Bitmask of `AMDGPU_GEM_CREATE_*` creation flags (e.g. USWC, VRAM-cleared, always-valid).

Returns

A `Bo` wrapping the kernel GEM handle and the requested size for later mmap or VA-map calls.

src/zinc_rt/kmd.zig:377

function

mmapGem

# 
pub fn mmapGem(file: std.fs.File, bo: Bo, prot: u32) ![]align(std.heap.page_size_min) u8

Map a previously created GEM BO into the calling process's address space.

First queries the kernel for the BO's mmap offset, then issues a shared `mmap` against the render-node fd at that offset.

Parameters

file
Open file handle for the AMDGPU render node that owns the BO.
bo
The buffer object handle and size returned by `createGem`.
prot
Standard POSIX `PROT_*` page-protection flags.

Returns

A page-aligned byte slice covering the BO; the slice length equals `bo.size`.

src/zinc_rt/kmd.zig:398

function

mapGemVa

# 
pub fn mapGemVa(file: std.fs.File, bo: Bo, va: u64, flags: u32) !void

Bind a GEM BO into the device virtual address space at a caller-chosen VA.

Performs an `AMDGPU_VA_OP_MAP` over the full BO size starting at offset 0.

Parameters

file
Open file handle for the AMDGPU render node that owns the BO.
bo
The buffer object handle and size returned by `createGem`.
va
Target GPU virtual address; must satisfy the page alignment the kernel enforces.
flags
Bitmask of `AMDGPU_VM_PAGE_*` and `AMDGPU_VM_MTYPE_*` permission/cache flags.

src/zinc_rt/kmd.zig:422

function

createComputeUserq

# 
pub fn createComputeUserq( file: std.fs.File, doorbell_handle: u32, doorbell_offset: u32, queue_va: u64, queue_size: u64, rptr_va: u64, wptr_va: u64, eop_va: u64, flags: u32, ) !u32

Create a compute user-mode queue via `DRM_IOCTL_AMDGPU_USERQ`.

Builds a GFX11 compute MQD pointing at the caller-supplied EOP scratch VA and submits an `AMDGPU_USERQ_OP_CREATE`.

Parameters

file
Open file handle for the AMDGPU render node.
doorbell_handle
GEM handle of the doorbell BO the kernel will use to wake this queue.
doorbell_offset
Doorbell slot offset within the doorbell BO assigned to this queue.
queue_va
Device VA of the ring buffer backing the queue.
queue_size
Ring buffer size in bytes.
rptr_va
Device VA of the queue read-pointer word.
wptr_va
Device VA of the queue write-pointer word.
eop_va
Device VA of the end-of-pipe scratch buffer required by GFX11 compute firmware.
flags
Driver-specific creation flags forwarded as-is to the kernel.

Returns

The kernel-assigned queue id used in later doorbell rings and the matching `freeUserq` call.

src/zinc_rt/kmd.zig:445

function

freeUserq

# 
pub fn freeUserq(file: std.fs.File, queue_id: u32) !void

Release a user-mode queue previously returned by `createComputeUserq` via `AMDGPU_USERQ_OP_FREE`.

Parameters

file
Open file handle for the AMDGPU render node that owns the queue.
queue_id
Kernel-assigned queue id to free.

src/zinc_rt/kmd.zig:479

function

lastErrno

# 
pub fn lastErrno() ?linux.E

Return the errno captured by the most recent ioctl performed through this module.

Returns

The captured `linux.E` value, or `null` if the previous call succeeded or no call has been made yet.

Notes

The module clears the saved errno at the start of every ioctl, so the value is only meaningful immediately after an `error.IoctlFailed`.

src/zinc_rt/kmd.zig:505