Filesystem & Schemes

The scheme abstraction (the kernel's VFS) and the btrfs filesystem integration.

src/btrfs/mod.rs

btrfs filesystem (Zig integration)

Rust FFI bindings to the Zig btrfs library (btrfs/), which is compiled to a static archive by build.rs and linked into the kernel. The kernel registers block-I/O callbacks with the Zig side and then drives mount, lookup, stat, read, and write operations across the C ABI boundary.

Return values follow the C convention used throughout the FFI layer: non-negative on success, negative -errno on failure (see the BTRFS_* constants).

BTRFS_OK const

const BTRFS_OK : i32

BTRFS_EINVAL const

const BTRFS_EINVAL : i32

BTRFS_ENOENT const

const BTRFS_ENOENT : i32

BTRFS_EIO const

const BTRFS_EIO : i32

BTRFS_ENOSYS const

const BTRFS_ENOSYS : i32

BlockReadFn type

pub type BlockReadFn = unsafe extern "C" fn(offset : u64, buf : * mut u8, len : usize) -> i32;

BlockWriteFn type

pub type BlockWriteFn = unsafe extern "C" fn(offset : u64, buf : * const u8, len : usize) -> i32;

btrfs_init extern fn

fn btrfs_init()

Initialise the Zig btrfs subsystem. Must be called once before any other btrfs operation.

btrfs_register_block_io extern fn

fn btrfs_register_block_io(read : BlockReadFn, write : BlockWriteFn)

Register the block-device read/write callbacks the filesystem uses for all backing-store I/O.

btrfs_mount extern fn

fn btrfs_mount(device_id : u64) -> i32

Mount the btrfs volume backed by the given block device id.

btrfs_unmount extern fn

fn btrfs_unmount() -> i32

Unmount the currently mounted volume.

btrfs_is_mounted extern fn

fn btrfs_is_mounted() -> c_int

Return non-zero if a volume is currently mounted.

btrfs_lookup extern fn

fn btrfs_lookup(path : * const u8, inode_out : * mut u64) -> i32

Resolve a path to an inode number, writing it to inode_out.

btrfs_stat extern fn

fn btrfs_stat(inode : u64, stat_buf : * mut u8, stat_len : usize) -> i32

Fill a stat buffer for the given inode.

init fn

fn init()

register_block_io fn

fn register_block_io(read : BlockReadFn, write : BlockWriteFn)

mount fn

fn mount(device_id : u64) -> Result<(), i32>

unmount fn

fn unmount() -> Result<(), i32>

is_mounted fn

fn is_mounted() -> bool

src/scheme/dtb.rs

DtbScheme struct

struct DtbScheme { /* … */ }

src/scheme/pipe.rs

pipe fn

fn pipe() -> Result<(usize, usize)>

PipeScheme struct

struct PipeScheme { /* … */ }

Pipe struct

struct Pipe { /* … */ }

src/scheme/time.rs

TimeScheme struct

struct TimeScheme { /* … */ }

src/scheme/memory.rs

MemoryScheme struct

struct MemoryScheme { /* … */ }

MemoryType enum

enum MemoryType {
    Writeback = 0,
    Uncacheable = 1,
    WriteCombining = 2,
    DeviceMemory = 3,
}

src/scheme/user.rs

UserInner struct

struct UserInner { /* … */ }

Response enum

enum Response {
    Regular,
    Fd,
}

UserInner::capture_user fn

fn capture_user<const READ : bool, const WRITE : bool>(&self, buf : UserSlice<READ, WRITE>,) -> Result<CaptureGuard<READ, WRITE>>

Map a readable structure to the scheme's userspace and return the pointer

CaptureGuard struct

struct CaptureGuard { /* … */ }

UserScheme struct

struct UserScheme { /* … */ }

UserInner has to be wrapped

Args trait

trait Args { /* … */ }

src/scheme/proc.rs

ProcScheme struct

struct ProcScheme { /* … */ }

foreach_addrsp fn

fn foreach_addrsp(mut f : impl FnMut(&Arc<AddrSpaceWrapper>))

src/scheme/acpi.rs

AcpiScheme struct

struct AcpiScheme { /* … */ }

A scheme used to access the RSDT or XSDT, which is needed for e.g. acpid to function.

register_kstop fn

fn register_kstop() -> bool

src/scheme/root.rs

RootScheme struct

struct RootScheme { /* … */ }

src/scheme/serio.rs

PS/2 unfortunately requires a kernel driver to prevent race conditions due to how status is utilized

serio_input fn

fn serio_input(index : usize, data : u8)

Add to the input queue

SerioScheme struct

struct SerioScheme { /* … */ }

src/scheme/debug.rs

debug_input fn

fn debug_input(data : u8)

Add to the input queue

debug_notify fn

fn debug_notify()

DebugScheme struct

struct DebugScheme { /* … */ }

src/scheme/sys/uname.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/context.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/scheme_num.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/iostat.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/stat.rs

resource fn

fn resource() -> Result<Vec<u8>>

Get the sys:stat data as displayed to the user.

src/scheme/sys/log.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/cpu.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/fdstat.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/syscall.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/scheme.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/exe.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/mempressure.rs

resource fn

fn resource() -> Result<Vec<u8>>

register_daemon fn

fn register_daemon(arg : &[u8]) -> Result<usize>

Write-side hook: register <pid> pins an OOM daemon for post-evacuation notification.

src/scheme/sys/block.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/irq.rs

resource fn

fn resource() -> Result<Vec<u8>>

src/scheme/sys/mod.rs

SysScheme struct

struct SysScheme { /* … */ }

System information scheme

src/scheme/event.rs

EventScheme struct

struct EventScheme { /* … */ }

src/scheme/btrfs.rs

file scheme — btrfs is the sole shipped block filesystem.

Paths are resolved against the mounted btrfs root via the file: scheme prefix. Kernel pseudo-schemes (proc:, sys:, etc.) remain available separately.

BtrfsScheme struct

struct BtrfsScheme { /* … */ }

src/scheme/irq.rs

irq_trigger fn

extern "C" fn irq_trigger(irq : u8)

Add to the input queue

IrqScheme struct

struct IrqScheme { /* … */ }

src/scheme/mod.rs

Schemes

A scheme is a primitive for handling filesystem syscalls in Helctic. Schemes accept paths from the kernel for open, and file descriptors that they generate are then passed for operations like close, read, write, etc.

The kernel validates paths and file descriptors before they are passed to schemes, also stripping the scheme identifier of paths if necessary.

SCHEME_MAX_SCHEMES const

const SCHEME_MAX_SCHEMES : usize

Limit on number of schemes

SchemeIter struct

struct SchemeIter { /* … */ }

SchemeList struct

struct SchemeList { /* … */ }

Scheme list type

SchemeList::new fn

fn new() -> Self

Create a new scheme list.

SchemeList::get fn

fn get(&self, id : SchemeId) -> Option<&KernelSchemes>

Get the nth scheme.

SchemeList::insert fn

fn insert(&mut self, ns : SchemeNamespace, name : &str, scheme_fn : impl FnOnce(SchemeId) -> KernelSchemes,) -> Result<SchemeId>

Create a new scheme.

SchemeList::remove fn

fn remove(&mut self, id : SchemeId)

Remove a scheme

schemes fn

fn schemes() -> RwLockReadGuard<'static, SchemeList>

Get the global schemes list, const

schemes_mut fn

fn schemes_mut() -> RwLockWriteGuard<'static, SchemeList>

Get the global schemes list, mutable

KernelScheme trait

trait KernelScheme { /* … */ }

OpenResult enum

enum OpenResult {
    SchemeLocal,
    External,
}

CallerCtx struct

struct CallerCtx { /* … */ }

KernelSchemes enum

enum KernelSchemes {
    Root,
    User,
    Global,
}

GlobalSchemes enum

enum GlobalSchemes {
    Debug = 1,
    Event,
    Memory,
    Pipe,
    Serio,
    Irq,
    Time,
    Sys,
    Proc,
    File,
    Acpi,
    Dtb,
}

MAX_GLOBAL_SCHEMES const

const MAX_GLOBAL_SCHEMES : usize

init_globals fn

fn init_globals()