GKaszewski/k-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Gabriel Kaszewski
2026-10-18 13:13:53 +02:00
parent 38f20cc3c4
commit 5766c6f7f7
39 changed files with 272 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
crates/servers/display-server/Cargo.toml
View File

@@ -3,17 +3,10 @@ name = "display-server"
version = "0.1.0"
edition = "2024"
[[bin]]
name = "display-server"
test = false
bench = false
[features]
default = ["qemu-virt"]
qemu-virt = []
[dependencies]
types = { workspace = true }
userspace = { workspace = true }
userspace-rt = { workspace = true }
server-framework = { workspace = true }
port-framebuffer = { workspace = true }
[dev-dependencies]
driver-framebuffer-mock = { workspace = true }

66
crates/servers/display-server/src/adapters/mock.rs
View File

@@ -1,66 +0,0 @@
use crate::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;
}
}

2
crates/servers/display-server/src/adapters/mod.rs
View File

@@ -1,2 +0,0 @@
pub mod mock;
pub mod qemu_virtio;

160
crates/servers/display-server/src/adapters/qemu_virtio.rs
View File

@@ -1,160 +0,0 @@
use crate::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,
fb_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)),
fb_pa: core::ptr::read_volatile(p.add(2)),
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(_buffer_addr: usize) -> 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); // NEXT
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); // WRITE
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) {
// TRANSFER_TO_HOST_2D
unsafe {
let p = CMDBUF_VA as *mut u8;
core::ptr::write_bytes(p, 0, 512);
core::ptr::write_volatile(p as *mut u32, 0x0105); // TRANSFER_TO_HOST_2D
// rect at offset 24
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);
// offset at 40
core::ptr::write_volatile(p.add(40) as *mut u64, 0);
// resource_id at 48
core::ptr::write_volatile(p.add(48) as *mut u32, 1);
}
self.send_gpu_cmd(56, 24);
// RESOURCE_FLUSH
unsafe {
let p = CMDBUF_VA as *mut u8;
core::ptr::write_bytes(p, 0, 512);
core::ptr::write_volatile(p as *mut u32, 0x0106); // RESOURCE_FLUSH
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); // resource_id
}
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;
let buf = FB_VA + offset;
unsafe {
core::ptr::write_volatile(buf 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);
}
}

8
crates/servers/display-server/src/framebuffer.rs
View File

@@ -1,8 +0,0 @@
pub trait Framebuffer {
fn width(&self) -> u16;
fn height(&self) -> u16;
fn write_pixel(&mut self, x: u16, y: u16, color: u32);
fn fill_rect(&mut self, x: u16, y: u16, w: u16, h: u16, color: u32);
fn clear(&mut self, color: u32);
fn flush(&mut self);
}

14
crates/servers/display-server/src/lib.rs
View File

@@ -1,22 +1,8 @@
#![no_std]
pub mod adapters;
pub mod framebuffer;
pub mod protocol;
pub mod server;
#[cfg(test)]
#[path = "tests/mod.rs"]
mod tests;
pub fn run() -> ! {
#[cfg(feature = "qemu-virt")]
let fb = adapters::qemu_virtio::VirtioFramebuffer::new(0x10008000);
#[cfg(not(feature = "qemu-virt"))]
let fb = adapters::mock::MockFramebuffer::new(320, 240);
let mut srv = server::DisplayServer::new(fb);
server_framework::serve(&mut srv, 0);
loop { userspace::syscall::yield_now(); }
}

9
crates/servers/display-server/src/main.rs
View File

@@ -1,9 +0,0 @@
#![no_std]
#![no_main]
extern crate userspace_rt;
#[unsafe(no_mangle)]
extern "C" fn main() {
display_server::run();
}

2
crates/servers/display-server/src/server.rs
View File

@@ -1,6 +1,6 @@
use server_framework::Server;
use crate::framebuffer::Framebuffer;
use port_framebuffer::Framebuffer;
use crate::protocol::{DisplayRequest, DisplayResponse};
pub struct DisplayServer<F: Framebuffer> {

2
crates/servers/display-server/src/tests/server.rs
View File

@@ -1,4 +1,4 @@
use crate::adapters::mock::MockFramebuffer;
use driver_framebuffer_mock::MockFramebuffer;
use crate::protocol::{DisplayRequest, DisplayResponse};
use crate::server::DisplayServer;
use server_framework::Server;

1
crates/servers/input-server/Cargo.toml
View File

@@ -17,3 +17,4 @@ types = { workspace = true }
userspace = { workspace = true }
userspace-rt = { workspace = true }
server-framework = { workspace = true }
port-input-device = { workspace = true }

3
crates/servers/input-server/src/adapters/mock.rs
View File

@@ -1,5 +1,4 @@
use crate::input_device::InputDevice;
use crate::protocol::InputEvent;
use crate::input_device::{InputDevice, InputEvent};
pub struct MockInputDevice {
events: [Option<InputEvent>; 16],

3
crates/servers/input-server/src/adapters/qemu_uart.rs
View File

@@ -1,5 +1,4 @@
use crate::input_device::InputDevice;
use crate::protocol::{InputEvent, Key};
use crate::input_device::{InputDevice, InputEvent, Key};
const UART_BASE: usize = 0x10000000;
const UART_LSR: usize = 5;

7
crates/servers/input-server/src/input_device.rs
View File

@@ -1,6 +1 @@
use crate::protocol::InputEvent;
pub trait InputDevice {
fn poll(&mut self) -> Option<InputEvent>;
fn has_event(&self) -> bool;
}
pub use port_input_device::{InputDevice, InputEvent, Key, GamepadButton, Axis};

53
crates/servers/input-server/src/protocol.rs
View File

@@ -1,55 +1,5 @@
use server_framework::{Decode, Encode};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Key {
Up,
Down,
Left,
Right,
Enter,
Escape,
Space,
Backspace,
Tab,
Char(u8),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GamepadButton {
South,
East,
North,
West,
DpadUp,
DpadDown,
DpadLeft,
DpadRight,
Start,
Select,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Axis {
LeftX,
LeftY,
RightX,
RightY,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InputEvent {
KeyDown(Key),
KeyUp(Key),
PointerDown { id: u8, x: u16, y: u16 },
PointerMove { id: u8, x: u16, y: u16 },
PointerUp { id: u8, x: u16, y: u16 },
Scroll { dx: i16, dy: i16 },
GamepadButton { button: GamepadButton, pressed: bool },
GamepadAxis { axis: Axis, value: i16 },
}
pub use port_input_device::{Key, GamepadButton, Axis, InputEvent};
#[derive(Debug, PartialEq)]
pub enum InputRequest {
@@ -82,7 +32,6 @@ impl Decode for InputRequest {
}
}
// Event type tags for encoding
const EV_KEY_DOWN: usize = 1;
const EV_KEY_UP: usize = 2;
const EV_PTR_DOWN: usize = 3;

12
crates/servers/storage-server/Cargo.toml
View File

@@ -3,17 +3,9 @@ name = "storage-server"
version = "0.1.0"
edition = "2024"
[[bin]]
name = "storage-server"
test = false
bench = false
[features]
default = ["qemu-virt"]
qemu-virt = []
[dependencies]
types = { workspace = true }
userspace = { workspace = true }
userspace-rt = { workspace = true }
server-framework = { workspace = true }
port-block-device = { workspace = true }
driver-block-virtio = { workspace = true }

2
crates/servers/storage-server/src/adapters/mock_block.rs
View File

@@ -1,4 +1,4 @@
use crate::block_device::{BlockDevice, SectorId};
use port_block_device::{BlockDevice, SectorId};
const SECTOR_SIZE: usize = 512;
const MAX_SECTORS: usize = 64;

1
crates/servers/storage-server/src/adapters/mod.rs
View File

@@ -1,3 +1,2 @@
pub mod mock_block;
pub mod mock_fs;
pub mod virtio_blk;

183
crates/servers/storage-server/src/adapters/virtio_blk.rs
View File

@@ -1,183 +0,0 @@
use crate::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;
// Physical addresses are written to a known location by the adapter at boot
// Layout at 0x24000: [req_hdr_pa: u64, status_pa: u64, sector_buf_pa: u64]
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_read(offset: usize) -> u32 {
unsafe { core::ptr::read_volatile((MMIO_BASE + offset) as *const u32) }
}
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; }
// Write to the local VA — device reads via physical address
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);
// Sector buffer: use a fixed area at REQ_HDR_VA + 32
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;
}
// Copy from sector buffer VA to caller's buffer
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
}
}

19
crates/servers/storage-server/src/block_device.rs
View File

@@ -1,19 +0,0 @@
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SectorId(u32);
impl SectorId {
pub const fn new(id: u32) -> Self {
Self(id)
}
pub const fn raw(&self) -> u32 {
self.0
}
}
pub trait BlockDevice {
fn sector_size(&self) -> usize;
fn sector_count(&self) -> usize;
fn read_sector(&mut self, sector: SectorId, buf: &mut [u8]) -> bool;
fn write_sector(&mut self, sector: SectorId, buf: &[u8]) -> bool;
}

2
crates/servers/storage-server/src/fs/ext4.rs
View File

@@ -1,4 +1,4 @@
use crate::block_device::{BlockDevice, SectorId};
use port_block_device::{BlockDevice, SectorId};
use crate::filesystem::{DirEntry, FileHandle, FileName, FileSystem};
const SECTOR_SIZE: usize = 512;

2
crates/servers/storage-server/src/fs/fat16.rs
View File

@@ -1,4 +1,4 @@
use crate::block_device::{BlockDevice, SectorId};
use port_block_device::{BlockDevice, SectorId};
use crate::filesystem::{DirEntry, FileHandle, FileName, FileSystem};
const SECTOR_SIZE: usize = 512;

5
crates/servers/storage-server/src/lib.rs
View File

@@ -1,7 +1,6 @@
#![no_std]
pub mod adapters;
pub mod block_device;
pub mod filesystem;
pub mod fs;
pub mod protocol;
@@ -30,7 +29,7 @@ fn debug_print(s: &[u8]) {
pub fn run() -> ! {
debug_print(b"storage: started\n");
let device = adapters::virtio_blk::VirtioBlockDevice::new();
let device = driver_block_virtio::VirtioBlockDevice::new();
let fat16 = fs::fat16::Fat16::mount(device);
if fat16.is_none() {
debug_print(b"storage: FAT16 mount failed\n");
@@ -71,7 +70,7 @@ pub fn run() -> ! {
}
}
fn read_entire_file<B: block_device::BlockDevice>(
fn read_entire_file<B: port_block_device::BlockDevice>(
fat: &mut fs::fat16::Fat16<B>,
filename: &[u8],
out: &mut [u8],

9
crates/servers/storage-server/src/main.rs
View File

@@ -1,9 +0,0 @@
#![no_std]
#![no_main]
extern crate userspace_rt;
#[unsafe(no_mangle)]
extern "C" fn main() {
storage_server::run();
}

2
crates/servers/storage-server/src/tests/ext4.rs
View File

@@ -1,5 +1,5 @@
use crate::adapters::mock_block::MockBlockDevice;
use crate::block_device::{BlockDevice, SectorId};
use port_block_device::{BlockDevice, SectorId};
use crate::filesystem::{DirEntry, FileSystem};
use crate::fs::ext4::Ext4;

2
crates/servers/storage-server/src/tests/fat16.rs
View File

@@ -1,5 +1,5 @@
use crate::adapters::mock_block::MockBlockDevice;
use crate::block_device::{BlockDevice, SectorId};
use port_block_device::{BlockDevice, SectorId};
use crate::filesystem::{DirEntry, FileSystem};
use crate::fs::fat16::Fat16;