User–Kernel ABI (Application Binary Interface)

GuardBSD defines a compact, architecture-neutral ABI used by all three microkernels (µK-Space, µK-Time, µK-IPC). The ABI describes register usage, calling conventions, binary layout of system structures, and message formats used by IPC.

This documentation reflects the GuardBSD 1.0.0 (Winter Saga) specification.

Boot ABI Structures


#[repr(C)]
pub struct BootInfo {
    pub magic: u32,
    // Future fields (memory map, init data, caps, etc.)
}

The BootInfo struct is minimal and intentionally stable across versions. Additional fields will be appended at the end to preserve ABI compatibility.

Calling Conventions

System calls use highly optimized architecture-specific calling conventions.

Syscall semantics are the same across architectures.
Only register assignments differ.

Register ABI


| Architecture | Syscall Number |               Arguments               | Return Value | Error Register |
|--------------|----------------|----------------------------------------|--------------|----------------|
| **x86_64**   |     `rax`      | `rdi`, `rsi`, `rdx`, `r10`, `r8`, `r9` |    `rax`     |     `rdx`      |
| **aarch64**  |     `x8`       | `x0`, `x1`, `x2`, `x3`, `x4`, `x5`     |     `x0`     |      `x1`      |

x86_64 Example


mov rax, 4              ; SYS_WRITE
mov rdi, 1              ; fd = stdout
mov rsi, message
mov rdx, 13
int 0x80                ; syscall

AArch64 Example


mov x8, #4              ; SYS_WRITE
mov x0, #1              ; fd
mov x1, message
mov x2, #13
svc #0

IPC Message ABI

IPC in GuardBSD uses a strict binary layout optimized for:

  • zero-copy paths when possible,
  • 4 KB message payload alignment,
  • capability passing,
  • predictable parsing by µK-IPC.

Source reference: IPC protocol specification.

Message Structure


#[repr(C)]
pub struct Message {
    pub header: MessageHeader,
    pub payload: [u8; 4096],
}

Message Header ABI


#[repr(C)]
pub struct MessageHeader {
    pub msg_type: u32,
    pub payload_len: u32,
    pub sender_cap: u32,
    pub reply_cap:  u32,
}

Payload must not exceed 4096 bytes.
Larger data transfers must use shared memory capabilities.

Binary Layout


0x00  u32  msg_type
0x04  u32  payload_len
0x08  u32  sender_cap
0x0C  u32  reply_cap
0x10  [0..4096] payload

Capability ABI

Capabilities are represented as unforgeable tokens granting access to:

  • memory regions,
  • IPC ports,
  • threads,
  • processes,
  • devices.

Reference: capability system spec.

Capability Structure


#[repr(C)]
pub struct Capability {
    pub object_id: u64,
    pub cap_type:  CapType,
    pub rights:    Rights,
    pub guard:     Option<u64>,
}

Capability Handle


#[repr(transparent)]
pub struct CapHandle(pub u32);

Handles are per-process indices into the capability table.

ABI for System Call Numbers

Based on the kernel syscall table.


1   exit
3   read
4   write
5   open
6   close
7   getpid
8   stat
9   rename
10  unlink
11  sync
20–24   µK-IPC ports
25–28   capability operations
29–31   IPC sync/reply
40–42   kernel logging transport

Negative return values correspond to -errno.
libgbsd converts raw error codes to Error enum variants.

Memory Layout & Alignment Requirements

General ABI Rules

  • All kernel and IPC structs use #[repr(C)].
  • All 64-bit integer fields are 8-byte aligned.
  • Capabilities and message headers are naturally aligned.
  • Messages are padded to 4096 bytes to match VM page size.

Virtual Memory ABI

Provided by µK-Space.


pub type PhysAddr = u64;
pub type VirtAddr = usize;

pub struct PageFlags(u64); // RWX bits, no-execute, etc.

ABI Stability Policy

GuardBSD v1.0.0 guarantees:

Stable ABI

  • Syscall numbers
  • MessageHeader layout
  • Capability layout
  • Calling conventions

Backwards-Compatible Extensions

  • additional fields appended at end of structs
  • new syscall numbers at end of group
  • optional extended message flags

Not Allowed

  • reordering struct fields
  • removing existing fields
  • redefining binary layout

Related Documentation Links