RegCube — reference (hives, keys, syscalls, persistence)

RegCube is the kernel-owned string configuration store: named hives, each holding key → value maps. Userland reads and writes through dedicated syscalls; persistence to disk is optional (explicit flush/load paths). It is not a programming language, not per-file metadata, and not a full ACID database — it is a deliberately small policy and capability registry for the OS and services.

Why “hive”? The name borrows the Registry “hive” metaphor (Windows-style top-level partitions) so contributors can guess the shape: several named buckets instead of one flat global keyspace. P1Start hives are much simpler than the Windows Registry: string keys, string values, in-memory primary, INI-like file export.

Related: file-types-open-pipeline.md (future handler overrides and MIME policy), settings-control-pattern.md (daemon / ctl / GUI), syscalls-reference.md syscall numbers.

1. Terminology

Term

Meaning

Hive

Top-level namespace string, e.g. HIVE_LOCAL_MACHINE. Kernel keeps a BTreeMap<hive, BTreeMap<key, value>>.

Key

Lookup string under a hive. Under HIVE_LOCAL_MACHINE, keys are usually hierarchical: domain/subkey (forward slashes, lower-case segments). Some legacy/theme keys are flat (theme_accent_primary) for historical deskgui settings.

Value

UTF-8-ish string stored as String in kernel; callers pass NUL-terminated pointers at the syscall boundary. Numbers, booleans, and enums are encoded as decimal or short tokens (1, 0, stretch, …).

RCB payload

Text serialization: sections [HIVENAME] and lines key=value (see §5).

Invariant: the kernel is authoritative; userland caches (e.g. deskgui RegCubeClient) are advisory and must be write-through on set (see §7).

2. Syscalls (userland ABI)

Implemented in src/sys/regcube.rs, exposed in src/kernel/syscalls.rs. libc/SDK wrappers: SDK/lib/cstd/src/sys.rs (sys_regcube_*).

#

Name

Role

104

sys_regcube_get

hive, key, user out_buf, max_len — copies value, returns length or error token (!0-style failure in practice).

105

sys_regcube_set

hive, key, val — all NUL-terminated; last writer wins per key.

106

sys_regcube_flush

Serializes entire in-memory RegCube to a VFS path (see generate_rcb_payload).

107

sys_regcube_load

Reads a file, parses RCB text, merges into hives (overwrites keys present in file).

All hive/key/value strings must be NUL-terminated in the C calling convention. Do not store large blobs; typical getters use ≤256 byte buffers in clients (see §8).

3. Persistence format (.rcb / text merge)

Kernel helper RegCube::generate_rcb_payload() (src/sys/regcube.rs) emits:

  • One line per hive: [HIVE_NAME]

  • Then key=value lines (no quoting rules; values are raw strings)

  • Lines starting with ; or # are ignored on parse (comments)

  • Empty lines ignored

parse_rcb_payload merges into memory; it is suitable for shipping defaults or operator snapshots, not for high-frequency logging.

4. Bootstrap — where initial values come from

Stage

Source

What it seeds

UEFI / early kernel

src/main.rs after RegCube init

Loads \System\Config\filetypes.csv → HIVE_FILE_EXTENSIONS, HIVE_FILE_ASSOCIATIONS (see parse_filetypes_csv). Loads \System\Config\hwcompat.csv → HIVE_HW_COMPAT. Seeds HIVE_FONTS, HIVE_I18N, HIVE_LOCAL_MACHINE keys input/legacy_ps2_kernel_path, network/legacy_kernel_driver (from boot.cfg / env), etc.

Services

p1-timesvc, p1-dispsvc, p1-powersvc, p1-luasvc, …

Publish …/svc_pid, apply policy keys, write status strings (see §9).

Operator

sys_regcube_load from Settings / regedit / scripts

Merges RCB snapshots at runtime.

5. Hive catalog (what each hive is for)

Hive

Purpose

Typical consumers

HIVE_LOCAL_MACHINE

Machine-wide policy — time, display, network mode, input stack, power, region, Lua policy, game-engine prefs, wallet stub metadata, and much of the desktop chrome (theme/mouse/wallpaper/audio keys used by deskgui).

Init, daemons, settings, deskgui, CLIs (timectl, dispctl, powerctl, luactl, gamectl, …).

HIVE_FILE_EXTENSIONS

Extension (without leading dot in CSV) → human description string (from filetypes.csv).

Legacy/shell UX, regedit snapshot, future type pickers.

HIVE_FILE_ASSOCIATIONS

Extension → handler token or path hint (editor, exec, \\System\\..., …). Seeded from CSV category heuristics + hard-coded overrides in parse_filetypes_csv.

open.elf and file.elf consult this hive first (extension key → mapped handler; see apps/coreutils/src/regcube_open.rs), then fall back to p1_media_types open_disposition_for_path. See file-types-open-pipeline.md.

HIVE_HW_COMPAT

PCI VVVV:DDDD (vendor:device, hex) → device name string.

Kernel/platform PCI bring-up, diagnostics.

HIVE_FONTS

Advertised font/emoji stack capabilities (bitmap/ttf engines, counts).

Diagnostics, Settings/regedit visibility — not the live font loader config.

HIVE_I18N

Advertised i18n/Bidi capabilities.

Same as fonts — capability flags, not user locale source of truth (locale lives under HIVE_LOCAL_MACHINE region/*).

Not a real hive (avoid): foundation-debt called out HIVE_SYSTEM_CACHE / VFS_DIR:* writes from older deskgui listing paths — do not treat as a SSOT; directory listing should stay RAM caches in the app (see docs/foundation-debt.md / platform-docs mirror).

6. HIVE_LOCAL_MACHINE — topic prefixes (naming convention)

New keys should use topic/subkey (lower case, / separators), matching existing services:

Prefix

Owned by / theme

Examples

network/

Init, stack selection

network/legacy_kernel_driver (0 kernel NIC, 1 legacy userspace netd path).

input/

Kernel + ps2d policy

input/legacy_ps2_kernel_path (0 ps2d, 1 kernel PS/2 queues).

time/

p1-timesvc, timectl

ntp_server, auto_sync, sync_interval_sec, last_sync_*, timezone_id, tz_offset_min, …

region/

settings, timectl

location, language, date_format.

display/

p1-dispsvc, dispctl, settings

resolution, refresh_hz, scale, brightness, auto_detect, scaling_mode, last_apply_status, active_workspace, svc_pid.

power/

p1-powersvc, powerctl

profile, sleep_timeout_sec, hibernate_enabled, auto_sleep, last_apply_status, svc_pid.

lua/

p1-luasvc, luactl

See lua-scripting-architecture.md §3 (svc_pid, req_script_path, enabled, …).

pxl/

Optional p1wallet stub

wallet_svc_pid, wallet_stub_version, stub_balance_pxl (see SDK/lib/cstd/src/pxl_wallet.rs).

game_engine/, games/

p1-gamesvc, gamectl, Settings

Proposed / partial — see game-engine-architecture.md §4.2.

Flat keys (deskgui chrome): theme_preset, mouse_sens_x, wallpaper_*, audio_*, … — listed in apps/deskgui/src/regcube_client.rs snapshot_for_editor. Prefer topic/subkey for new services; migrating old flat keys is a separate cleanup.

7. Strategy A — single façade in deskgui

Problem it solves: split-brain — some UI code calling sys_regcube_* directly while other code used mocks.

Rule: under apps/deskgui/src/, compositor-facing RegCube access should go through RegCubeClient (apps/deskgui/src/regcube_client.rs).

CI: scripts/check_no_os_registry_deskgui.ps1 fails if banned legacy registry strings reappear.

8. RegCubeClient contract (summary)

  • Reads: get_string / get_optional / get_f32 — cache first; on miss, syscall 104, insert on success (string getters).

  • Writes: set_string / set_f32 — syscall 105 first, then update cache (write-through).

  • Invalidation: invalidate_hive(hive) drops cache entries for that hive only (no kernel call).

  • Flush / load: pass through syscalls 106 / 107.

  • Buffer reality: syscall get path uses 256-byte stack buffers — keep values short (status strings, decimals, short paths).

9. Ecosystem settings pattern (required)

For control domains (time, display, network, power, game runtime, …):

  • p1-<domain>svc owns transitions and background policy.

  • <domain>ctl CLI and Settings GUI are frontends.

  • Both converge on the same RegCube keys documented here and in domain docs.

No hidden second source of truth for persisted policy.

10. Operational keys — quick index

The table below merges common keys; domain docs are authoritative for semantics.

Hive

Key(s)

Used by

HIVE_LOCAL_MACHINE

network/legacy_kernel_driver

Init, netd spawn decision, networking-architecture.md.

HIVE_LOCAL_MACHINE

input/legacy_ps2_kernel_path

Kernel boot, deskgui; platform-docs/docs/reference/userspace-input.md (Sphinx: Reference → Userspace input).

HIVE_LOCAL_MACHINE

time/*

p1-timesvc, timectl; see time-and-clock.md, syscalls-reference.md RegCube appendix rows.

HIVE_LOCAL_MACHINE

region/*

settings, timectl, deskgui clock formatting.

HIVE_LOCAL_MACHINE

display/*

p1-dispsvc, dispctl, settings, deskgui resolution polling.

HIVE_LOCAL_MACHINE

power/*

p1-powersvc, powerctl, settings.

HIVE_LOCAL_MACHINE

lua/*

p1-luasvc, luactl — lua-scripting-architecture.md.

HIVE_LOCAL_MACHINE

pxl/*

Optional p1wallet stub.

HIVE_LOCAL_MACHINE

game_engine/*, games/*

Planned — game-engine-architecture.md.

HIVE_LOCAL_MACHINE

Theme / mouse / wallpaper / audio / power_mode (flat)

deskgui, settings, regedit snapshot lists.

HIVE_FILE_EXTENSIONS

per extension

filetypes.csv import; advisor UIs.

HIVE_FILE_ASSOCIATIONS

per extension

Seeded associations; future overrides — file-types-open-pipeline.md.

HIVE_HW_COMPAT

VVVV:DDDD PCI IDs

hwcompat.csv, PCI naming.

HIVE_FONTS, HIVE_I18N

capability keys

Boot advertisement; regedit.

11. Edge cases

Case

Policy

Get failure

Returns default / empty / None per API; only successful gets populate cache.

Concurrent writers

Last writer wins at kernel; clients must write-through cache on set.

Oversized values

Fixed small buffers in many callers — do not store blobs; use a file path in RegCube if needed.

Typos in hive names

Unrelated hive → empty namespace; keys appear missing. Stick to this document’s literals.

12. See also

13. Changelog (document)

When

What

Current

Expanded hive catalog, terminology, syscalls, persistence, bootstrap, HIVE_LOCAL_MACHINE prefixes, operational index, explicit split from MIME/handler code (p1_media_types).

(When you add a hive or a stable service key, update §5, §6, or §10 in the same PR.)