Sysfs & DRM Interface

Admiral exposes a virtual sysfs interface to workload containers at /sys/admiral and low-level platform interfaces on ARM development boards. The architecture bridges the host-level Bluetooth/Network daemon with workload containers, enabling zero-cost, lock-free IPC via read-only bind mounts of standard tmpfs assets.

---

1. Workload Container Interface: /sys/admiral

Inside any running workload container, the system registers static device identification nodes and dynamic network status states at /sys/admiral.

Directory Tree

/sys/admiral/
├── device_id                       # Cryptographically unique hardware identity
├── fleet_id                        # Bound Fleet UUID
├── org_id                          # Bound Organization UUID
└── bluetooth/                      # Live Bluetooth & Network states (Preserved Inodes)
    ├── advertising                 # 'true' | 'false' (BLE setup advertisements active)
    ├── ident                       # Dynamic BLE name (e.g., ADM-QWERT123)
    ├── link_type                   # Comma-separated active links (e.g., wifi,ethernet)
    ├── network_status              # 'connected' | 'connecting' | 'disconnected'
    ├── pairing_status              # 'unprovisioned' | 'configuring' | 'paired' | 'fully_provisioned'
    └── prov_state                  # Raw provisioning state byte (0–4, or 255)

---

2. Dynamic State Nodes (/sys/admiral/bluetooth/)

These virtual files are updated atomically on the host using in-place truncation (O_TRUNC). This preserves file inodes, allowing containerized processes to watch them with inotify (e.g., IN_MODIFY) without breaking the file listener on each write.

ident

• Format: Plaintext string (ADM-[BASE32_HASH])
• Description: The unique 8-character Base32 identifier generated from 5 bytes of entropy derived from the board's hardware serial number. Matches the broadcast legacy local name in BLE advertisement packets.

advertising

• Format: Plaintext boolean (true or false)
• Description: Indicates whether the BLE Provisioning GATT server is actively transmitting setup beacons. Transitions to false automatically when the device becomes fully provisioned or the setup advertisement times out.

prov_state

• Format: String integer (0, 1, 2, 3, 4, or 255)
• Description: Reflects the raw internal provisioning state machine value:

Value	State	Description
0	Unprovisioned	Waiting for first secure pairing key or Wi-Fi credential
1	Wi-Fi Configured	Host accepted credentials and is attempting handshake
2	Wi-Fi Connected	Handshake success, waiting for DHCP context
3	Cloud Paired	Ephemeral X25519 secure tunnel active, cloud pairing token acquired
4	Fully Provisioned	WPA Supplicant credentials sealed, BLE shutdown initiated
255	Error State	See GATT error register

pairing_status

• Format: Plaintext string enumeration
• Description: Human-readable mapping of the active provisioning step. Mirrors prov_state for consumers that prefer a string representation.

Value	Meaning
unprovisioned	No credentials received
configuring	Credentials received, connecting
paired	Cloud pairing token acquired
fully_provisioned	Setup complete, BLE offline

network_status

• Format: Plaintext string enumeration
• Description: Network reachability derived from active link detection across all interfaces.

Value	Meaning
disconnected	No IP interface is bound to the routing tables
connecting	Interfaces are up but negotiating with a DHCP server
connected	Routable IP addresses successfully assigned

link_type

• Format: Plaintext comma-separated string
• Description: Identifies the physical links currently provisioned with active unicast routing.
• Values: none, wifi, ethernet, cellular, or combinations such as wifi,ethernet

---

3. DRM Splash Controller (ARM Dev Boards)

ARM development boards running the Admiral Kernel expose a low-level sysfs handle for display plane multiplexing between the boot splash and userspace rendering contexts.

• Node: /sys/class/drm/card0/splash_enable
• Permission: Read-Write (host/kernel context only)

Value	Effect
0	Disabled. Yields the primary display plane (CRTC) and framebuffers back to standard DRM/KMS userspace processes (Wayland compositors, custom UI engines, TUI output).
1	Enabled. Locks the display plane to render the boot splash from early RAM-disk or kernel image space, preventing boot TTY text or raw console logs from bleeding onto physical panels during workload initialization or restarts.

# Release boot splash — expose workload TUI/UI output
echo 0 > /sys/class/drm/card0/splash_enable

# Enforce display shielding during workload container hot-reloads
echo 1 > /sys/class/drm/card0/splash_enable

---

4. Watcher Patterns

Because sysfs nodes are written atomically with inode preservation, workload services can react to state changes using inotify-based file watchers rather than polling loops.

Shell

#!/bin/sh
STATE_FILE="/sys/admiral/bluetooth/network_status"

echo "Current status: $(cat $STATE_FILE)"

while inotifywait -e modify "$STATE_FILE"; do
    NEW_STATE=$(cat "$STATE_FILE")
    echo "Network state changed to: $NEW_STATE"
    if [ "$NEW_STATE" = "connected" ]; then
        /app/register_workload.sh
    fi
done

Go

package main

import (
	"log"
	"os"

	"github.com/fsnotify/fsnotify"
)

const TargetNode = "/sys/admiral/bluetooth/pairing_status"

func main() {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatalf("Failed to initialize fsnotify: %v", err)
	}
	defer watcher.Close()

	if err = watcher.Add(TargetNode); err != nil {
		log.Fatalf("Failed to register watch path: %v", err)
	}

	log.Println("Monitoring pairing status transitions...")
	for {
		select {
		case event, ok := <-watcher.Events:
			if !ok {
				return
			}
			if event.Has(fsnotify.Write) {
				data, err := os.ReadFile(TargetNode)
				if err == nil {
					log.Printf("Pairing state updated: %s", string(data))
				}
			}
		case err, ok := <-watcher.Errors:
			if !ok {
				return
			}
			log.Printf("Watcher error: %v", err)
		}
	}
}