refactor: extract ports/drivers/bins layers — clean dependency inversion

Separate abstractions from implementations following DIP:

  servers/              drivers/
      │                     │
      ▼                     ▼
    ports/  (trait-only crates, zero deps)

New crates:

ports/ (abstractions):
  - port-framebuffer: Framebuffer trait
  - port-block-device: BlockDevice trait + SectorId
  - port-input-device: InputDevice trait + InputEvent types

drivers/ (implementations depend on ports/):
  - driver-framebuffer-virtio: VirtIO GPU framebuffer
  - driver-framebuffer-mock: test double
  - driver-block-virtio: VirtIO block device

bins/ (composition roots wire server + driver):
  - display-qemu: DisplayServer<VirtioFramebuffer>
  - storage-qemu: storage server with VirtIO block

Servers no longer own their hardware traits or driver code.
Neither server nor driver depends on the other — both point
inward to the port abstraction.

crates/drivers/block/virtio/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "driver-block-virtio"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+port-block-device = { workspace = true }

crates/drivers/block/virtio/src/lib.rs

@@ -0,0 +1,139 @@
+#![no_std]
+
+use port_block_device::{BlockDevice, SectorId};
+
+const QUEUE_SIZE: usize = 8;
+const SECTOR_SIZE: usize = 512;
+
+const MMIO_BASE: usize = 0x20000;
+const VQUEUE_VA: usize = 0x21000;
+const REQ_HDR_VA: usize = 0x23000;
+const PHYS_INFO_VA: usize = 0x24000;
+
+#[repr(C)]
+#[derive(Clone, Copy)]
+struct VirtqDesc {
+    addr: u64,
+    len: u32,
+    flags: u16,
+    next: u16,
+}
+
+#[repr(C)]
+struct VirtqAvail {
+    flags: u16,
+    idx: u16,
+    ring: [u16; QUEUE_SIZE],
+    used_event: u16,
+}
+
+#[repr(C)]
+#[derive(Clone, Copy)]
+struct VirtqUsedElem {
+    id: u32,
+    len: u32,
+}
+
+#[repr(C)]
+struct VirtqUsed {
+    flags: u16,
+    idx: u16,
+    ring: [VirtqUsedElem; QUEUE_SIZE],
+}
+
+#[repr(C)]
+struct VirtioBlkReqHeader {
+    req_type: u32,
+    reserved: u32,
+    sector: u64,
+}
+
+fn mmio_write(offset: usize, val: u32) {
+    unsafe { core::ptr::write_volatile((MMIO_BASE + offset) as *mut u32, val) }
+}
+
+fn descs() -> *mut VirtqDesc { VQUEUE_VA as *mut VirtqDesc }
+fn avail() -> *mut VirtqAvail { (VQUEUE_VA + QUEUE_SIZE * 16) as *mut VirtqAvail }
+fn used() -> *mut VirtqUsed { (VQUEUE_VA + 0x1000) as *mut VirtqUsed }
+fn req_header() -> *mut VirtioBlkReqHeader { REQ_HDR_VA as *mut VirtioBlkReqHeader }
+fn req_status() -> *mut u8 { (REQ_HDR_VA + 16) as *mut u8 }
+
+struct PhysAddrs {
+    req_hdr: u64,
+    status: u64,
+    sector_buf: u64,
+}
+
+fn read_phys_addrs() -> PhysAddrs {
+    unsafe {
+        let base = PHYS_INFO_VA as *const u64;
+        PhysAddrs {
+            req_hdr: core::ptr::read_volatile(base),
+            status: core::ptr::read_volatile(base.add(1)),
+            sector_buf: core::ptr::read_volatile(base.add(2)),
+        }
+    }
+}
+
+pub struct VirtioBlockDevice {
+    phys: PhysAddrs,
+}
+
+impl VirtioBlockDevice {
+    pub fn new() -> Self {
+        Self { phys: read_phys_addrs() }
+    }
+}
+
+impl BlockDevice for VirtioBlockDevice {
+    fn sector_size(&self) -> usize { SECTOR_SIZE }
+    fn sector_count(&self) -> usize { 0xFFFF }
+
+    fn read_sector(&mut self, sector: SectorId, buf: &mut [u8]) -> bool {
+        if buf.len() < SECTOR_SIZE { return false; }
+
+        unsafe {
+            let hdr = req_header();
+            (*hdr).req_type = 0;
+            (*hdr).reserved = 0;
+            (*hdr).sector = sector.raw() as u64;
+
+            core::ptr::write_volatile(req_status(), 0xFF);
+
+            let sector_buf_va = (REQ_HDR_VA + 32) as *mut u8;
+
+            let d = descs();
+            (*d.add(0)) = VirtqDesc { addr: self.phys.req_hdr, len: 16, flags: 1, next: 1 };
+            (*d.add(1)) = VirtqDesc { addr: self.phys.sector_buf, len: SECTOR_SIZE as u32, flags: 2 | 1, next: 2 };
+            (*d.add(2)) = VirtqDesc { addr: self.phys.status, len: 1, flags: 2, next: 0 };
+
+            let a = avail();
+            let avail_idx = core::ptr::read_volatile(&(*a).idx);
+            (*a).ring[(avail_idx as usize) % QUEUE_SIZE] = 0;
+            core::sync::atomic::fence(core::sync::atomic::Ordering::SeqCst);
+            core::ptr::write_volatile(&mut (*a).idx, avail_idx.wrapping_add(1));
+            core::sync::atomic::fence(core::sync::atomic::Ordering::SeqCst);
+
+            mmio_write(0x050, 0);
+
+            let expected = avail_idx.wrapping_add(1);
+            let u = used();
+            let mut timeout = 10_000_000u32;
+            while core::ptr::read_volatile(&(*u).idx) != expected {
+                core::hint::spin_loop();
+                timeout -= 1;
+                if timeout == 0 { return false; }
+            }
+
+            if core::ptr::read_volatile(req_status()) != 0 { return false; }
+
+            core::ptr::copy_nonoverlapping(sector_buf_va, buf.as_mut_ptr(), SECTOR_SIZE);
+        }
+
+        true
+    }
+
+    fn write_sector(&mut self, _sector: SectorId, _buf: &[u8]) -> bool {
+        false
+    }
+}

crates/drivers/framebuffer/mock/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "driver-framebuffer-mock"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+port-framebuffer = { workspace = true }

crates/drivers/framebuffer/mock/src/lib.rs

@@ -0,0 +1,63 @@
+#![no_std]
+
+use port_framebuffer::Framebuffer;
+
+pub struct MockFramebuffer {
+    width: u16,
+    height: u16,
+    pixels: [(u16, u16, u32); 4096],
+    pixel_count: usize,
+    flushed: bool,
+}
+
+impl MockFramebuffer {
+    pub fn new(width: u16, height: u16) -> Self {
+        Self {
+            width,
+            height,
+            pixels: [(0, 0, 0); 4096],
+            pixel_count: 0,
+            flushed: false,
+        }
+    }
+
+    pub fn pixel_count(&self) -> usize {
+        self.pixel_count
+    }
+
+    pub fn was_flushed(&self) -> bool {
+        self.flushed
+    }
+
+    pub fn pixel_at(&self, index: usize) -> (u16, u16, u32) {
+        self.pixels[index]
+    }
+}
+
+impl Framebuffer for MockFramebuffer {
+    fn width(&self) -> u16 { self.width }
+    fn height(&self) -> u16 { self.height }
+
+    fn write_pixel(&mut self, x: u16, y: u16, color: u32) {
+        if self.pixel_count < self.pixels.len() {
+            self.pixels[self.pixel_count] = (x, y, color);
+            self.pixel_count += 1;
+        }
+    }
+
+    fn fill_rect(&mut self, x: u16, y: u16, w: u16, h: u16, color: u32) {
+        for dy in 0..h {
+            for dx in 0..w {
+                self.write_pixel(x + dx, y + dy, color);
+            }
+        }
+    }
+
+    fn clear(&mut self, _color: u32) {
+        self.pixel_count = 0;
+    }
+
+    fn flush(&mut self) {
+        self.flushed = true;
+    }
+}

crates/drivers/framebuffer/virtio/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "driver-framebuffer-virtio"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+port-framebuffer = { workspace = true }

crates/drivers/framebuffer/virtio/src/lib.rs

@@ -0,0 +1,146 @@
+#![no_std]
+
+use port_framebuffer::Framebuffer;
+
+const GPU_MMIO_VA: usize = 0x20000;
+const VQUEUE_VA: usize = 0x21000;
+const CMDBUF_VA: usize = 0x23000;
+const PHYSINFO_VA: usize = 0x24000;
+const FB_VA: usize = 0x100000;
+const FB_BPP: usize = 4;
+const QUEUE_SIZE: usize = 8;
+
+struct PhysInfo {
+    cmd_pa: u64,
+    resp_pa: u64,
+    width: u64,
+    height: u64,
+}
+
+fn read_phys_info() -> PhysInfo {
+    unsafe {
+        let p = PHYSINFO_VA as *const u64;
+        PhysInfo {
+            cmd_pa: core::ptr::read_volatile(p),
+            resp_pa: core::ptr::read_volatile(p.add(1)),
+            width: core::ptr::read_volatile(p.add(3)),
+            height: core::ptr::read_volatile(p.add(4)),
+        }
+    }
+}
+
+fn mmio_write(offset: usize, val: u32) {
+    unsafe { core::ptr::write_volatile((GPU_MMIO_VA + offset) as *mut u32, val) }
+}
+
+pub struct VirtioFramebuffer {
+    width: u16,
+    height: u16,
+    stride: usize,
+    phys: PhysInfo,
+}
+
+impl VirtioFramebuffer {
+    pub fn new() -> Self {
+        let phys = read_phys_info();
+        let width = phys.width as u16;
+        let height = phys.height as u16;
+        let stride = width as usize * FB_BPP;
+        Self { width, height, stride, phys }
+    }
+
+    fn send_gpu_cmd(&self, cmd_len: u32, resp_len: u32) {
+        unsafe {
+            let desc0 = VQUEUE_VA as *mut u8;
+            core::ptr::write_volatile(desc0 as *mut u64, self.phys.cmd_pa);
+            core::ptr::write_volatile(desc0.add(8) as *mut u32, cmd_len);
+            core::ptr::write_volatile(desc0.add(12) as *mut u16, 1);
+            core::ptr::write_volatile(desc0.add(14) as *mut u16, 1);
+
+            let desc1 = desc0.add(16);
+            core::ptr::write_volatile(desc1 as *mut u64, self.phys.resp_pa);
+            core::ptr::write_volatile(desc1.add(8) as *mut u32, resp_len);
+            core::ptr::write_volatile(desc1.add(12) as *mut u16, 2);
+            core::ptr::write_volatile(desc1.add(14) as *mut u16, 0);
+
+            let avail = VQUEUE_VA + QUEUE_SIZE * 16;
+            let avail_idx = core::ptr::read_volatile((avail + 2) as *const u16);
+            core::ptr::write_volatile(
+                (avail + 4 + (avail_idx as usize % QUEUE_SIZE) * 2) as *mut u16,
+                0,
+            );
+            core::sync::atomic::fence(core::sync::atomic::Ordering::SeqCst);
+            core::ptr::write_volatile((avail + 2) as *mut u16, avail_idx.wrapping_add(1));
+            core::sync::atomic::fence(core::sync::atomic::Ordering::SeqCst);
+
+            mmio_write(0x050, 0);
+
+            let used = VQUEUE_VA + 4096;
+            let expected = avail_idx.wrapping_add(1);
+            let mut timeout = 10_000_000u32;
+            while core::ptr::read_volatile((used + 2) as *const u16) != expected {
+                core::hint::spin_loop();
+                timeout -= 1;
+                if timeout == 0 { return; }
+            }
+        }
+    }
+
+    fn transfer_and_flush(&self, x: u32, y: u32, w: u32, h: u32) {
+        unsafe {
+            let p = CMDBUF_VA as *mut u8;
+            core::ptr::write_bytes(p, 0, 512);
+            core::ptr::write_volatile(p as *mut u32, 0x0105);
+            core::ptr::write_volatile(p.add(24) as *mut u32, x);
+            core::ptr::write_volatile(p.add(28) as *mut u32, y);
+            core::ptr::write_volatile(p.add(32) as *mut u32, w);
+            core::ptr::write_volatile(p.add(36) as *mut u32, h);
+            core::ptr::write_volatile(p.add(40) as *mut u64, 0);
+            core::ptr::write_volatile(p.add(48) as *mut u32, 1);
+        }
+        self.send_gpu_cmd(56, 24);
+
+        unsafe {
+            let p = CMDBUF_VA as *mut u8;
+            core::ptr::write_bytes(p, 0, 512);
+            core::ptr::write_volatile(p as *mut u32, 0x0106);
+            core::ptr::write_volatile(p.add(24) as *mut u32, x);
+            core::ptr::write_volatile(p.add(28) as *mut u32, y);
+            core::ptr::write_volatile(p.add(32) as *mut u32, w);
+            core::ptr::write_volatile(p.add(36) as *mut u32, h);
+            core::ptr::write_volatile(p.add(40) as *mut u32, 1);
+        }
+        self.send_gpu_cmd(48, 24);
+    }
+}
+
+impl Framebuffer for VirtioFramebuffer {
+    fn width(&self) -> u16 { self.width }
+    fn height(&self) -> u16 { self.height }
+
+    fn write_pixel(&mut self, x: u16, y: u16, color: u32) {
+        if x >= self.width || y >= self.height { return; }
+        let offset = (y as usize) * self.stride + (x as usize) * FB_BPP;
+        unsafe { core::ptr::write_volatile((FB_VA + offset) as *mut u32, color); }
+    }
+
+    fn fill_rect(&mut self, x: u16, y: u16, w: u16, h: u16, color: u32) {
+        for dy in 0..h {
+            for dx in 0..w {
+                self.write_pixel(x + dx, y + dy, color);
+            }
+        }
+    }
+
+    fn clear(&mut self, color: u32) {
+        let total = self.width as usize * self.height as usize;
+        let buf = FB_VA as *mut u32;
+        for i in 0..total {
+            unsafe { core::ptr::write_volatile(buf.add(i), color); }
+        }
+    }
+
+    fn flush(&mut self) {
+        self.transfer_and_flush(0, 0, self.width as u32, self.height as u32);
+    }
+}