Kernel ABIalpha

The calling convention, manifest fields and linker rules for native kernels, ABI version 1.

This page specifies version 1 of the interface between a Motoko program and a native kernel. Writing a kernel walks through it with an example.

The kernel package's manifest#

A kernel package is a mops package whose mops.toml has a [kernel] table:

[kernel]
abi = 1
file = "kernel/crc32.kernel.toml"
source = "https://github.com/OWNER/REPO/tree/COMMIT/PATH"
commit = "COMMIT"

[kernel.functions]
"Crc32.digest" = { export = "crc32", args = ["Blob"], result = "Blob", result_bytes = 4 }

source, commit and the package's [package] version must each be one token: no spaces or control characters, at most 512 bytes. They are written into public metadata, and moxzi refuses a value that could split a line.

Each [kernel.functions] entry:

The Motoko function#

The function must be declared at the top level of its module, with plain named parameters:

When the application opts in, moxzi keeps the function's name, parameters and type and replaces its body with a call to the kernel. Every declared function must be replaced, so a build that opts into a kernel either calls the kernel or stops. It never quietly runs the Motoko body instead:

moxzi compares the parameter and result types when they're written as built-in type names, such as Blob or ?Text. When the function uses a type alias instead, the type checker checks it against the declared signature after the rewrite, and a mismatch is a type error at the same place.

moxzi checks a declared function when the program imports its module. A function in a module the program doesn't import is never called, so it isn't checked. When the program imports none of a kernel's modules, the build says so in a note and doesn't use the kernel.

Calling convention#

Kernels are wasm64. Every pointer and length is 64 bits.

Argument bytes are borrowed for the duration of the call. Don't write to them, and don't keep their addresses after you return.

The glue copies a variable-size result into a new Motoko Blob or Text. A fixed-size result is written straight into the new Blob.

What the program provides#

A kernel may import two functions from the program. The moxzi-kernel SDK wraps both.

The SDK makes kernel_alloc the crate's global allocator, so Vec and alloc work. Its dealloc does nothing, so a growing Vec keeps every buffer it outgrew until the call ends. Reserve capacity up front when you know the size.

The SDK's panic handler traps with native kernel panicked: followed by the panic message, truncated to 256 bytes.

Checks on results#

The glue checks what a kernel returns before Motoko code sees it. Each failed check traps the message, and the IC rolls the message back.

An overrun is detected by a guard word after the buffer, so it catches writes that run off the end. It doesn't catch writes anywhere else in memory. The check costs about 30 instructions for a fixed-size result and about 50 for a variable-size one.

What the linker refuses#

The linker checks every kernel before linking it, both locally and on the compiler canister. A kernel is refused if:

A kernel the program never calls isn't linked. Kernels are linked in order of package name, so the output doesn't depend on the order of [kernels].

State, memory and garbage collection#

• No collection during a call. The garbage collector never runs while a kernel executes, so argument addresses stay valid until it returns.
• Kernels are stateless. Return everything through the result. A kernel's static data is memory, so a static mut keeps its value between calls, but it is reset to the kernel's initial data by every upgrade, and the Motoko body has no such state. Programs that rely on it behave differently with and without the kernel.
• Shared stack. A kernel runs on the canister's stack, shared with the Motoko code that called it. Keep large buffers on the heap.
• Determinism. A kernel has no clock, no randomness and no system API. Avoid floating point: the linker doesn't refuse it, but the bit patterns of NaN results can differ between the Internet Computer and other hosts.

The kernel file#

moxzi kernel build writes a .kernel.toml file, because mops publishes only .mo, .did, .md and .toml files:

The comment lines at the top name the toolchain and linker that built it. moxzi checks that sha256 matches the decoded bytes every time it reads the file.

Metadata in a linked module#

A module built with kernels opted in has a public custom section, moxzi:kernels, with one line per kernel the module calls, and so contains. A kernel the program never calls isn't linked and isn't listed. When the program calls no kernel at all, the section is empty, or absent if the program imports none of the kernels' modules.

PACKAGE sha256:HEX abi=1 version=VERSION source=URL commit=COMMIT

The first two fields are the pin. version=, source= and commit= appear when the package declares them. The linker reads the section to refuse kernel bytes other than the pinned ones, and anyone can read it from a deployed canister. As wasm-tools print shows it:

(@custom "icp:public moxzi:kernels" (after data) "moxzi-hash sha256:d9e07eabd5c53e4567f6ce132857b52f7b0d3546f2443b73bdb3b07cf2244a2e abi=1 version=0.1.0 source=https://github.com/icdevsorg/moxzi-kernels/tree/main/kernels/moxzi-hash/rust commit=445b558869a5552956229d704011c40480e1854c\0a")

Limits#