PacketFive | Cnuas Virtual AI/HPC Infrastructure CnuasDev, Datasheet Device access library and the pluggable compute backend family Document DS-CNU-012 Revision G Issued 15 August 2026 Status Published ============================================================================== Item Value --------- ------------------------------------------------------ Part libcnuasdev.so Type Device access library SONAME libcnuasdev.so.0, current build libcnuasdev.so.0.1.0 Package cnuas-libcnuasrt Version v0.2.0-25-gc54883d Repo PacketFive/CnuasGPU 1. Overview CnuasDev is the thin layer between CnuasRT and the cnuasgpu.ko character device. It turns the ioctl and mmap protocol of the driver into a small C interface, so the runtime never issues a raw ioctl and tools that need device facts without the full runtime have somewhere lighter to link against. This datasheet also specifies the compute backend ABI, because the backend shared objects are built and shipped alongside the device library and share its release cadence. Key features - Device enumeration and per device information without opening the runtime. - Explicit allocate, free, and copy against device memory. - Direct memory mapping of device memory into the host address space. - A published backend ABI so a new instruction set is a new shared object rather than a rebuild of the runtime. - Backend selection at first use with an environment variable override. - A CnuasLink transport that speaks frames rather than raw ioctls, with the wire format available as a standalone unit that needs no device. 2. Application programming interface Every symbol below is exported by libcnuasdev.so.0.1.0. Group Function Purpose ------------- --------------------------- ------------------------------------------------------- Discovery cnuasdev_get_device_count Count the /dev/cnuasgpuN nodes present Handle cnuasdev_open Open a device by index and return a handle Handle cnuasdev_close Release a handle and any allocations tied to it Information cnuasdev_query_info Identity, geometry, and memory figures for the device Memory cnuasdev_alloc Reserve a device memory range Memory cnuasdev_free Release a device memory range Memory cnuasdev_memcpy Copy between host and device memory Mapping cnuasdev_mmap Map device memory into the calling address space Mapping cnuasdev_munmap Undo a mapping Diagnostics cnuasdev_status_str Text for a cnuasdev_status_t code CnuasLink cnuasdev_link_id Local fabric identifier, cached after first use CnuasLink cnuasdev_link_status Whether the switch is reachable and a frame is staged CnuasLink cnuasdev_link_send Encode and send a frame, filling in the local source CnuasLink cnuasdev_link_recv Receive one frame and decode it CnuasLink cnuasdev_link_send_raw Send bytes that are already a frame CnuasLink cnuasdev_link_recv_raw Receive bytes without decoding CnuasLink cnuaslink_frame_encode Build a frame in a caller buffer CnuasLink cnuaslink_frame_decode Validate and parse a received frame CnuasLink cnuaslink_frame_type_str Text for a frame type 2a. CnuasLink transport The transport is a synchronous wrapper over the three LINK ioctls. It is the lowest layer that speaks frames rather than bytes and is the foundation CnuasCCL is expected to build on. Parameter Value ------------------- ----------------------------------------------------------------- Header cnuaslink_frame.h Frame header size 12 bytes, fixed Maximum frame 65536 bytes Maximum payload 65524 bytes Byte order Little endian for every multi byte field Identifier range 1 to 65534; 0 and 65535 are reserved Receive timeout 0 polls, 4294967295 waits without limit, otherwise milliseconds Two properties of the fabric shape what can be built on top and are stated here so callers do not have to rediscover them. Receive is not demultiplexed by peer, so a frame from any sender satisfies any waiting receive and a caller expecting a specific peer must check the source itself. Discovery and keepalive frames train the forwarding table but are never forwarded, so neither can carry a message to another rank. Both points are treated at length in the CnuasCCL bootstrap design. The wire format is defined normatively in the CnuasLink repository. The copy in cnuaslink_frame.h is a restatement, because the two live in separate repositories, and lib/test/cnuaslink_frame_smoke asserts the encoded bytes against literals so that a drift between them fails a test rather than producing frames the switch discards. 3. Device memory model Parameter Value -------------- ------------------------------------------------------------- Backing PCI BAR1 of the CnuasGPU device, RAM backed in the emulator Default size 256 MiB, set by the devmem_size device property Allocator Bump pointer, page aligned, allocated in the kernel driver Reclaim On explicit free and on close of the file descriptor Host mapping Write combining, through mmap on the character device Accounting devmem_size and devmem_used are published in sysfs THE ALLOCATOR IS DELIBERATELY SIMPLE Allocation advances a pointer and does not coalesce freed ranges. A process that allocates and frees in a long loop will exhaust the device memory window even though its live footprint is small. Close and reopen the handle to reset. A free list allocator is roadmap work. 4. Character device interface Item Value ------------------ ---------------------------------------------------------------------------------------------------- Node /dev/cnuasgpuN, one per device Class /sys/class/cnuasgpu/ Sysfs attributes gpu_id, sm_count, devmem_size, devmem_used, link_up, link_rx_ready Operations ioctl for information, allocate, free, copy, and the three CnuasLink calls; mmap for direct access 5. Compute backend ABI Backends are standalone shared objects named libcnuasrt-${name}.so. Each one exports a single vtable symbol, cnuas_compute_backend, that carries a name, an ABI version pair, a capability mask, and the kernel function pointers. Parameter Value ------------------ --------------------------------------------------------------------------------------- Vtable symbol cnuas_compute_backend ABI version Major 0, minor 2 Shipped backends libcnuasrt-scalar.so, libcnuasrt-avx2.so, libcnuasrt-avx512.so, libcnuasrt-cnuasir.so Selection Highest capability backend the host processor supports Discovery dlopen at first compute call Capability bits Bit Meaning Implemented -------------------------------------------------------------------------------- ----------------------------------------------------------------- --------------------------------- CNUAS_CCAP_VEC_F32 32 bit float vector kernels Yes CNUAS_CCAP_GEMM_F32 32 bit float matrix multiply Yes CNUAS_CCAP_GEMM_NT_F32 32 bit float matrix multiply with the second operand transposed Yes, except the CnuasIR backend CNUAS_CCAP_REDUCE Reduction primitives Yes CNUAS_CCAP_ACTIVATION_F32 Elementwise activations and row wise softmax Yes, except the CnuasIR backend CNUAS_CCAP_CNUASIR_EXEC Executes CnuasIR Yes, the CnuasIR backend only CNUAS_CCAP_X86_AVX2 Host uses AVX2 code paths Yes CNUAS_CCAP_X86_AVX512 Host uses AVX-512 code paths Yes CNUAS_CCAP_GEMM_F16, CNUAS_CCAP_GEMM_BF16 Reduced precision matrix multiply Reserved CNUAS_CCAP_CONV2D_F32 Convolution Reserved CNUAS_CCAP_FFT_C32 Complex transform Reserved CNUAS_CCAP_TENSOR_CORE Tensor tile unit Reserved CNUAS_CCAP_ARM_NEON, CNUAS_CCAP_ARM_SVE, CNUAS_CCAP_RISCV_RVV, CNUAS_CCAP_FPGA Non x86 hosts and offload Reserved Reserved bits are defined in the header so that the ABI does not have to change when the corresponding kernels land. No shipped backend sets a reserved bit. CNUAS_CCAP_ACTIVATION_F32 covers the rectifier, Gaussian error linear unit, sigmoid linear unit, logistic, hyperbolic tangent and a row wise softmax. The CnuasIR backend is the one exception: it runs its kernels as interpreted CnuasIR bytecode, and the exponential those activations need is not in the CnuasIR v0.1 subset, so it advertises the bit as absent rather than falling back to host code behind the caller's back. All six activations are vectorised in the AVX2 and AVX-512 backends. The vector kernels are one macro parameterised algorithm in lib/compute/common/cnuas_activations_simd.h, instantiated once per instruction set so that the two cannot drift apart. They have been checked by sweeping all 2^32 binary32 bit patterns per function against a double precision oracle, on AVX2 and, on AVX-512 hardware, on AVX-512, with identical error figures on both. Two properties of that sweep are worth carrying in a datasheet. relu is bit exact; sigmoid is within 3 ulp, tanh within 1, and silu and gelu are within the published conformance tolerances. And gelu is judged by absolute rather than relative error, because for negative arguments the identity it is built on cancels catastrophically and no finite precision implementation can hold relative accuracy through that cancellation. The AVX-512 activations are the first dependency in the tree on the DQ subset. avx512_probe() accordingly checks DQ as well as F and FMA; a part with F but not DQ, such as Knights Landing, would otherwise have selected the backend and then taken an illegal instruction fault. The six activation entry points were added in ABI minor 2, and sgemm_nt in ABI minor 3. Each occupies the front of the previously reserved area, so the vtable size and every earlier field offset are unchanged, and a backend compiled against an earlier minor still loads with those pointers null. Callers must therefore test the capability bit, or the pointer, before calling. sgemm_nt computes row-major C = alpha * A * B' + beta * C with B stored N by K. It exists because that is the shape an inference graph produces, a weight matrix held one row per output neuron applied to a batch of activations, and a caller without it must materialise the transpose in scratch first. In the vectorised backends it reuses the blocking, the microkernel and the edge handling of sgemm unchanged; only the operand packing reads a different address. It is exposed publicly as cnuasSgemmNT, and through cnuasblasSgemm as CNUASBLAS_OP_T on the first operand. Selection controls Environment variable Effect ----------------------- --------------------------------------------- CNUAS_COMPUTE_BACKEND Load the named backend, bypassing detection CNUAS_BACKEND_DIR Override the backend search directory CNUAS_COMPUTE_LIST List discovered backends CNUAS_COMPUTE_VERBOSE Explain the selection decision Device backend selection The device axis is independent of the compute axis above: it decides where device memory lives, not which instruction set runs. Environment variable Effect ---------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- CNUAS_DEVICE_BACKEND host serves device memory from process memory; device requires the character device and never falls back. Unset selects the character device when a /dev/cnuasgpuN node is present and the in-process arena otherwise, announcing the automatic case once on stderr. Any other value is reported and ignored. CNUAS_HOST_ARENA_MB Arena size for the host backend, default 512 The host backend needs no kernel module, no /dev/cnuasgpuN and no guest. It presents one device, allocates by bump pointer with 64 byte alignment, and reclaims only the most recent block, matching the driver rather than improving on it so that code which works against it also works against the device. It reproduces the interface of the device and not its timing, so it is a correctness and bring up vehicle rather than a performance model. Allocation is mutex guarded, because collectives run their ranks as real threads. Source is lib/libcnuasdev/cnuasdev_host.c. 6. Validation Feature Test Device required ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------ ----------------------------- Information ioctl, allocate, copy round trip, free driver/test/cnuasgpu_smoke.c Yes Backend vtable numerics per instruction set lib/test/compute_backend_smoke.c No Every activation over the whole binary32 domain, 2^32 inputs each lib/test/activation_exhaustive.c No, and out of band by cost Host device backend: enumeration, alignment, copies in all three directions, bounds rejection, exhaustion, and mapping lifetime lib/test/cnuasdev_host_smoke.c No Public runtime activation entry points end to end lib/test/cnuasrt_activation_smoke.c Host backend Backend shared object ABI, capabilities, and numerics lib/test/compute_so_smoke.c No CnuasLink wire format, golden bytes, round trip, and every rejection lib/test/cnuaslink_frame_smoke.c No CnuasLink send and receive against a live switch driver/test/cnuasgpu_link_test.c Yes Matrix multiply against llama.cpp's CPU reference, 648 shapes and types test-backend-ops via integration/ggml Host backend Transposed matrix multiply, against a double precision oracle and bit for bit against sgemm on an explicitly transposed operand lib/test/compute_backend_smoke.c No CNUASBLAS_OP_T producing the same product as the untransposed call lib/test/cnuasblas_smoke.c Host stub A backend built against ABI minor 2 loading into a minor 3 loader, presenting sgemm_nt as null, and the public transposed entry points declining rather than faulting Out of band, backends rebuilt from a reverted header No The tests that need no emulated device make up the fastest regression signal in the accelerator stack, and all of them run under make -C lib check. The host device backend widened that set: tests which need a device but not a real one now run there too, so only the multi device test remains gated on a guest. 7. Integration information Item Value ---------------- --------------------------------------------------------------------------------------------------------------- Repo PacketFive/CnuasGPU Submodule path src/cnuasgpu Source lib/libcnuasdev/, lib/compute/ Headers cnuasdev.h, cnuaslink_frame.h, cnuas_compute_ops.h Debian package cnuas-libcnuasrt Depends on cnuasgpu.ko and a CnuasGPU PCI device for the character device path; nothing beyond libc for the host backend Language C Build Make 8. Revision history Revision Notes ---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- G Device backend selection became automatic: the host arena is used when no character device node is present, device forces the character device, and host forces the arena. Behaviour is unchanged wherever a node exists, so this cannot mask a missing kernel module in a guest. Driven by an integration finding rather than by preference; Ollama passes only three variables to the process that loads the accelerator, so a mode reachable only by variable was not reachable at all. F Compute backend ABI raised to minor 3 for sgemm_nt, with the matching CNUAS_CCAP_GEMM_NT_F32 bit, the cnuasSgemmNT runtime entry point and CNUASBLAS_OP_T support in cnuasblasSgemm. Added the two section 6 validation rows. The gap was found by the ggml integration, which had been transposing its weights into scratch to work around it, and which no longer does. The minor 2 to minor 3 compatibility was verified by rebuilding two backends from a reverted header and loading them, not by inspection of the struct. A First publication. Symbol list taken from the dynamic symbol table of libcnuasdev.so.0.1.0, capability bits from cnuas_compute_ops.h. B Added the CnuasLink transport and wire format of roadmap milestone 8.2a, section 2a and the new symbols in section 2. Frame parameters taken from cnuaslink_frame.h and cross checked against the switch header. E Records the vectorised activations and their exhaustive verification, the AVX-512 DQ probe, and the ggml integration row in section 6. Error figures are measured from full sweeps on AVX2 and on AVX-512 hardware. D Records the host device backend of roadmap milestone 8.3e, the section 5 selection controls and the section 6 validation. Behaviour is taken from lib/libcnuasdev/cnuasdev_host.c and verified by running the two tests with the backend selected and deselected. C Compute backend ABI raised to minor 2 for the activation entry points of roadmap milestone 8.3d. The capability table records CNUAS_CCAP_REDUCE and CNUAS_CCAP_CNUASIR_EXEC as set by shipped backends, and lists libcnuasrt-cnuasir.so. Bits are taken from cnuas_compute_ops.h and cross checked against the .caps initialiser of every backend. ============================================================================== PacketFive, Packet Five Networks Ltd., Dublin, Ireland. Cnuas Virtual AI/HPC Infrastructure is published at https://github.com/PacketFive/cnuas under the Apache License 2.0; read it at https://github.com/PacketFive/cnuas/blob/main/LICENSE. Cnuas Virtual AI/HPC Infrastructure is emulation software. It is not affiliated with, endorsed by, or derived from any hardware vendor, and every device it models is a software artefact. The work is published by its authors in a personal capacity and is not sponsored or endorsed by any employer. Specifications describe the referenced revision of the software and may change without notice. Contact info@packetfive.com.