feat: wire sovereign.init as JSON-RPC method — first diesel engine RPC

sovereign.init: opens BAR0 via sysfs, runs staged sovereign_init pipeline
(bar0_probe → pmc_enable → memory_training → falcon_boot → gr_init → verify),
returns per-stage results with timing. Uses StubGspBridge for now.

MappedBar::from_sysfs_rw(): new constructor enabling BAR0 access without full
VFIO device open (iommufd FDs not needed for BAR0-only stages).

Hardware validated (Exp 197):
- Titan V (warm): stages 1-3 OK in 88ms, warm detection working
- K80 x2 (cold VFIO): stages 1-2 OK, PRAMIN dead (DEVINIT replay needed)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ecoPrimal

crates/core/cylinder/src/vfio/device/mapped_bar.rs

@@ -181,6 +181,54 @@ impl RegisterAccess for MappedBar {
     }
 }
 
+impl MappedBar {
+    /// Create a `MappedBar` from a sysfs PCI BAR0 resource file (read-write).
+    ///
+    /// Opens `/sys/bus/pci/devices/{bdf}/resource0` with `O_RDWR` and mmaps it.
+    /// The file descriptor is leaked intentionally — the mapping lives for the
+    /// duration of the `MappedBar` lifetime and the kernel reclaims on drop
+    /// via `MmioRegion`'s unmap.
+    pub fn from_sysfs_rw(bdf: &str, size: usize) -> Result<Self, DriverError> {
+        let path = crate::linux_paths::sysfs_pci_device_file(bdf, "resource0");
+        let file = std::fs::OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&path)
+            .map_err(|e| {
+                DriverError::MmapFailed(Cow::Owned(format!(
+                    "sysfs BAR0 open failed for {bdf}: {e}"
+                )))
+            })?;
+
+        let raw = unsafe {
+            rustix::mm::mmap(
+                std::ptr::null_mut(),
+                size,
+                rustix::mm::ProtFlags::READ | rustix::mm::ProtFlags::WRITE,
+                rustix::mm::MapFlags::SHARED,
+                &file,
+                0,
+            )
+        }
+        .map_err(|e| {
+            DriverError::MmapFailed(Cow::Owned(format!(
+                "sysfs BAR0 mmap failed for {bdf}: {e}"
+            )))
+        })?;
+
+        if raw.is_null() {
+            return Err(DriverError::MmapFailed(Cow::Borrowed(
+                "sysfs BAR0 mmap returned null",
+            )));
+        }
+
+        // Leak the file descriptor — the mmap keeps the mapping alive.
+        std::mem::forget(file);
+        let region = unsafe { MmioRegion::new(raw.cast::<u8>(), size) };
+        Ok(Self { region })
+    }
+}
+
 /// Test-only constructor backed by heap memory.
 #[cfg(test)]
 impl MappedBar {

crates/server/src/pure_jsonrpc/handler/core/mod.rs

@@ -98,6 +98,7 @@ pub const DIRECT_JSONRPC_METHODS: &[&str] = &[
     "device.vfio.roundtrip",
     "device.gr.init",
     "compute.context.init",
+    "sovereign.init",
     "mmio.read32",
     "mmio.write32",
     "mmio.batch",

crates/server/src/pure_jsonrpc/handler/mod.rs

@@ -15,6 +15,7 @@ pub mod method_gate;
 mod mmio;
 mod resources;
 mod silicon;
+mod sovereign;
 mod transport;
 mod workload;
 
@@ -378,6 +379,8 @@ impl JsonRpcHandler {
                 return self.dispatch.device_gr_init(params).await;
             }
 
+            "sovereign.init" => return sovereign::sovereign_init(params),
+
             "mmio.read32" => return mmio::mmio_read32(params),
             "mmio.write32" => return mmio::mmio_write32(params),
             "mmio.batch" => return mmio::mmio_batch(params),
@@ -472,6 +475,7 @@ impl JsonRpcHandler {
             "device_vfio_open" => self.dispatch.device_vfio_open(params).await,
             "device_vfio_roundtrip" => self.dispatch.device_vfio_roundtrip(params).await,
             "device_gr_init" => self.dispatch.device_gr_init(params).await,
+            "sovereign_init" => sovereign::sovereign_init(params),
             "mmio_read32" => mmio::mmio_read32(params),
             "mmio_write32" => mmio::mmio_write32(params),
             "mmio_batch" => mmio::mmio_batch(params),

crates/server/src/pure_jsonrpc/handler/sovereign.rs

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//! Sovereign GPU initialization JSON-RPC handler.
+//!
+//! Exposes `sovereign.init` — the staged diesel-engine pipeline that brings a
+//! VFIO-bound GPU from cold/warm state to compute-ready.
+
+use crate::pure_jsonrpc::types::JsonRpcError;
+use serde_json::Value;
+use tracing::info;
+
+const DEFAULT_BAR0_SIZE: usize = 16 * 1024 * 1024;
+
+/// `sovereign.init` — Run the full sovereign init pipeline on a GPU.
+///
+/// Opens BAR0 via sysfs, runs `cylinder::sovereign_init` stages, returns
+/// per-stage results. The GPU must be VFIO-bound (or unbound) with BAR0
+/// accessible via `/sys/bus/pci/devices/{bdf}/resource0`.
+///
+/// Params:
+/// - `bdf` (required): PCI BDF address (e.g. `"0000:4b:00.0"`)
+/// - `halt_before` (optional): Stop before a stage (`"pmc_enable"`, `"hbm2_training"`,
+///   `"kepler_pgraph_ungate"`, `"falcon_boot"`, `"gr_init"`, `"verify"`)
+/// - `skip_gr_init` (optional, default false): Skip GR init stage
+/// - `golden_state_path` (optional): Path to golden-state JSON for HBM2 replay
+/// - `vbios_rom_path` (optional): Path to raw VBIOS ROM dump
+/// - `sm_version` (optional): SM version override (auto-detected if omitted)
+/// - `fbpa_count` (optional): FBPA partition count override (auto-detected)
+pub fn sovereign_init(params: Option<&Value>) -> Result<Value, JsonRpcError> {
+    let bdf = params
+        .and_then(|p| p.get("bdf"))
+        .and_then(Value::as_str)
+        .ok_or_else(|| JsonRpcError::invalid_params("Missing 'bdf' string parameter"))?;
+
+    info!(bdf = %bdf, "sovereign.init: opening BAR0");
+
+    let bar0 = toadstool_cylinder::vfio::device::MappedBar::from_sysfs_rw(bdf, DEFAULT_BAR0_SIZE)
+        .map_err(|e| {
+            JsonRpcError::internal_error(format!(
+                "BAR0 open failed for {bdf}: {e}. Ensure vfio-pci is bound and resource0 is accessible."
+            ))
+        })?;
+
+    let mut opts: toadstool_cylinder::vfio::sovereign_init::SovereignInitOptions =
+        if let Some(p) = params {
+            serde_json::from_value(p.clone()).unwrap_or_default()
+        } else {
+            Default::default()
+        };
+
+    if let Some(path) = opts.golden_state_path.as_ref() {
+        match std::fs::read_to_string(path) {
+            Ok(json_str) => {
+                if let Ok(pairs) =
+                    serde_json::from_str::<Vec<(usize, u32)>>(&json_str)
+                {
+                    opts.golden_state = Some(pairs);
+                }
+            }
+            Err(e) => {
+                info!(path = %path, error = %e, "golden_state_path read failed, continuing without");
+            }
+        }
+    }
+
+    if let Some(path) = opts.vbios_rom_path.as_ref() {
+        match std::fs::read(path) {
+            Ok(rom) => {
+                opts.vbios_rom = Some(rom);
+            }
+            Err(e) => {
+                info!(path = %path, error = %e, "vbios_rom_path read failed, continuing without");
+            }
+        }
+    }
+
+    let bridge = toadstool_cylinder::nv::gsp_bridge::StubGspBridge;
+
+    info!(bdf = %bdf, halt_before = ?opts.halt_before, "sovereign.init: starting pipeline");
+
+    let result = toadstool_cylinder::vfio::sovereign_init::sovereign_init(
+        &bar0, bdf, &opts, &bridge,
+    );
+
+    info!(
+        bdf = %bdf,
+        all_ok = result.all_ok,
+        compute_ready = result.compute_ready,
+        total_ms = result.total_ms,
+        stages = result.stages.len(),
+        warm_detected = result.warm_detected,
+        "sovereign.init: pipeline complete"
+    );
+
+    serde_json::to_value(&result)
+        .map_err(|e| JsonRpcError::internal_error(format!("serialization failed: {e}")))
+}