Device Drivers Lab

/// Calculate the ECAM offset given a bus and slot number
const fn ecam_offset(bus: u8, slot: u8) -> usize {
    let bus = bus as usize;
    let slot = slot as usize;
    debug_assert!(slot >> 5 == 0, "Slot (device) is more than 5 bits");
    // We don't need to assert bus since it's 8 bits to start with.
    bus << 20 | slot << 15
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/// Spec: PCI § 6.1 -- the first 16 bytes, common to type 0 and type 1.
#[repr(C)]
pub struct CommonEcam {
    pub vendor_id: u16,
    pub device_id: u16,
    pub command: u16,
    pub status: u16,
    pub revision_id: u8,
    pub class_code: [u8; 3],
    pub cache_line_size: u8,
    pub latency_timer: u8,
    pub header_type: u8,
    pub bist: u8, // built-in self test
}
impl CommonEcam {
    /// Wrap a PCI ECAM base (from ACPI) at the given bus and slot
    pub fn new(base: VirtualAddress, bus: u8, slot: u8) -> &'static mut Self {
        let ptr = base.add(ecam_offset(bus, slot)).as_mut_ptr();
        unsafe { ptr.as_mut_unchecked() }
    }

    pub fn is_present(&self) -> bool {
        self.vendor_id != 0xFFFF
    }

    pub fn is_device(&self) -> bool {
        // Bit 7 is the multi-function flag; the type is bits [6:0].
        (self.header_type & 0x7F) == 0
    }
}

1
2
3
4
5
6
7
8
9
/// Spec: PCI § 6.7 -- the first two bytes of every capability.
///
/// Capabilities extend beyond this, but `id` and `next` are always
/// the first two fields, which is enough to walk the list.
#[repr(C)]
pub struct Capability {
    pub id: u8,   // Capability identifier
    pub next: u8, // Byte offset (from config space base) of the next capability
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
/// Spec: `virtio_pci_cap` (Virtio § 4.1.4)
#[repr(C)]
pub struct Capability {
    pub id: u8,           // PCI_CAP_ID_VNDR (0x09)
    pub next: u8,         // Same as the PCI next pointer
    pub cap_length: u8,   // Length of this capability, including id and next
    pub cfg_type: u8,     // VirtIO configuration type (1 through 5)
    pub bar: u8,          // BAR *index*. Feed this to get_bar().
    pub padding: [u8; 3], // Pad to a full dword
    pub offset: u32,      // Byte offset within that BAR
    pub length: u32,      // Length of the structure at that offset
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/// Common configuration for all VirtIO devices
pub const COMMON_CFG: u8 = 1;
/// Notification configuration
pub const NOTIFY_CFG: u8 = 2;
/// Interrupt service routine (ISR) configuration
pub const ISR_CFG: u8 = 3;
/// Device-specific configuration (different for every VirtIO device)
pub const DEVICE_CFG: u8 = 4;
/// Alternate PCI configuration access
pub const PCI_CFG: u8 = 5;

1
2
3
4
5
6
7
8
/// Spec: `virtio_pci_notify_cap` (Virtio § 4.1.4.4)
///
/// This is a *capability*, not the register in the BAR.
#[repr(C)]
pub struct NotifyCapability {
    pub cap: Capability,
    pub notify_offset_multiplier: u32,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/// # Byte offset within the notify BAR for a given queue.
///
/// ## Arguments
///
/// * `offset` -- `offset` from the notify `Capability`.
/// * `queue_notify_offset` -- `queue_notify_offset` read from `CommonCfg`
///   *after* selecting the queue.
/// * `multiplier` -- `notify_offset_multiplier` from `NotifyCapability`.
pub const fn notify_offset(offset: u32, queue_notify_offset: u32, multiplier: u32) -> usize {
    offset as usize + queue_notify_offset as usize * multiplier as usize
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Spec: Virtio § 2.1 -- device status bits.
pub const STATUS_RESET: u8       = 0;
pub const STATUS_ACKNOWLEDGE: u8 = 1 << 0;
pub const STATUS_DRIVER: u8      = 1 << 1;
pub const STATUS_DRIVER_OK: u8   = 1 << 2;
pub const STATUS_FEATURES_OK: u8 = 1 << 3;
pub const STATUS_NEEDS_RESET: u8 = 1 << 6;
pub const STATUS_FAILED: u8      = 1 << 7;

// Spec: Virtio § 6 -- reserved feature bits. Note these are *bit numbers*,
// and they are above 31, so they live in feature word 1.
pub const F_INDIRECT_DESC: u32   = 28;
pub const F_EVENT_IDX: u32       = 29;
pub const F_VERSION_1: u32       = 32;
pub const F_ACCESS_PLATFORM: u32 = 33;
pub const F_RING_PACKED: u32     = 34;
pub const F_IN_ORDER: u32        = 35;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/// # Drain every completion the device has published.
///
/// Called from the IRQ handler. `seen_device` is *our* record of how far
/// into the used ring we have looked; the device's `index` is how far it
/// has written. The gap between them is the work to do.
///
/// Both counters are free-running u16s that wrap at 65,536, so the
/// comparison must be a plain inequality and the increment must wrap.
/// Never `%` the counters themselves
pub fn drain(&mut self) {
    // Acquire load: everything the device wrote before publishing this
    // index must be visible to us now. See the memory ordering sidebar.
    let device_index = self.device_ring_index();

    while self.seen_device != device_index {
        let slot = (self.seen_device as usize) % (self.size as usize);
        let element = self.device_ring_element(slot);

        // `element.id` is the *head* descriptor of the completed chain,
        // and `element.length` is how many bytes the device wrote into it.
        let head = element.id as u16;
        let written = element.length as usize;

        // Hand off to whatever was waiting on this chain, then reclaim
        // the descriptors. Order matters: the completion handler may still
        // need to read the buffers the descriptors point at.
        self.complete(head, written);
        self.free_chain(head);

        self.seen_device = self.seen_device.wrapping_add(1);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/// Our bookkeeping for one split virtqueue.
///
/// The three addresses are the *virtual* addresses of regions whose
/// *physical* addresses we wrote into the device's queue registers.
#[derive(Debug)]
pub struct Queue {
    pub desc: VirtualAddress,
    pub driver: VirtualAddress,
    pub device: VirtualAddress,
    pub size: u16,

    /// Next slot in the driver ring we will publish into.
    pub next_driver: u16,
    /// How far into the device ring we have consumed.
    pub seen_device: u16,

    /// Head of our descriptor free list.
    pub free_head: u16,

    /// Per-head-descriptor record of work in flight, indexed by descriptor
    /// index. This is what lets the IRQ handler answer "what was this?"
    /// when the used ring hands it back a bare head index.
    pub inflight: Vec<Option<InFlight>>,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
pub const SECTOR_SIZE: usize = 512;
pub const SECTOR_MASK: usize = SECTOR_SIZE - 1;

// Spec: Virtio § 5.2.6 -- request types. These go driver-to-device, so an
// enum is defensible here; see the enum sidebar for why the *status* byte
// coming back is a different story.
pub const BLK_T_IN: u32           = 0;  // read
pub const BLK_T_OUT: u32          = 1;  // write
pub const BLK_T_FLUSH: u32        = 4;
pub const BLK_T_GET_ID: u32       = 8;
pub const BLK_T_GET_LIFETIME: u32 = 10;
pub const BLK_T_DISCARD: u32      = 11;
pub const BLK_T_WRITE_ZEROES: u32 = 13;
pub const BLK_T_SECURE_ERASE: u32 = 14;

/// Spec: `virtio_blk_req` header (Virtio § 5.2.6)
///
/// Pointed at by the *first* descriptor of the chain. Device-read-only,
/// so `DESC_WRITE` must be clear on that descriptor.
#[repr(C)]
pub struct RequestHeader {
    pub request_type: u32,
    pub reserved: u32,
    /// Byte offset divided by SECTOR_SIZE.
    pub start_sector: u64,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
pub const BLK_S_OK: u8          = 0;
pub const BLK_S_IOERR: u8       = 1;
pub const BLK_S_UNSUPPORTED: u8 = 2;
/// Not a device value. Ours, to detect "never written".
pub const BLK_S_SENTINEL: u8    = 111;

/// Spec: the status byte of `virtio_blk_req` (Virtio § 5.2.6)
///
/// Typed as `u8` and not as an enum, deliberately: the *device* writes
/// this field, so it can contain a value with no valid discriminant.
/// See the enum sidebar.
#[repr(C)]
pub struct Status {
    pub status: u8,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/// Spec: `virtio_input_event` (Virtio § 5.8.6)
///
/// Exactly 8 bytes. Every descriptor you post to the event queue points
/// at one of these.
#[repr(C)]
#[derive(Copy, Clone, Debug, Default)]
pub struct Event {
    pub event_type: u16,
    pub code: u16,
    pub value: u32,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/// Spec: `virtio_gpu_ctrl_hdr` (Virtio § 5.7.6.8)
///
/// Prefixes every control-queue command *and* every response.
///
/// `ctrl_type` is a raw u32 and not an enum precisely because the device
/// writes it in the response direction. See the enum sidebar.
#[repr(C)]
pub struct CtrlHeader {
    pub ctrl_type: u32,
    pub flags: u32,
    pub fence_id: u64,
    pub ctx_id: u32,
    pub padding: u32,
}

// Spec: Virtio § 5.7.6.8. 2D commands.
pub const CMD_GET_DISPLAY_INFO: u32        = 0x0100;
pub const CMD_RESOURCE_CREATE_2D: u32      = 0x0101;
pub const CMD_RESOURCE_UNREF: u32          = 0x0102;
pub const CMD_SET_SCANOUT: u32             = 0x0103;
pub const CMD_RESOURCE_FLUSH: u32          = 0x0104;
pub const CMD_TRANSFER_TO_HOST_2D: u32     = 0x0105;
pub const CMD_RESOURCE_ATTACH_BACKING: u32 = 0x0106;
pub const CMD_RESOURCE_DETACH_BACKING: u32 = 0x0107;
// Cursor commands begin at 0x0300.
// Success responses begin at 0x1100; OK_NODATA is 0x1100,
// OK_DISPLAY_INFO is 0x1101.
// Error responses begin at 0x1200.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
/// Spec: `virtio_gpu_resource_create_2d` (Virtio § 5.7.6.3)
#[repr(C)]
pub struct ResourceCreate2d {
    pub header: CtrlHeader,
    pub resource_id: u32,
    pub format: u32,
    pub width: u32,
    pub height: u32,
}

/// Spec: `virtio_gpu_set_scanout` (Virtio § 5.7.6.9)
#[repr(C)]
pub struct SetScanout {
    pub header: CtrlHeader,
    pub rect: Rect,
    pub scanout_id: u32,
    pub resource_id: u32,
}

/// Spec: `virtio_gpu_resource_attach_backing` (Virtio § 5.7.6.5)
///
/// Followed in the *data* descriptor by `num_entries` `MemEntry` values.
#[repr(C)]
pub struct ResourceAttachBacking {
    pub header: CtrlHeader,
    pub resource_id: u32,
    pub num_entries: u32,
}

/// Spec: `virtio_gpu_mem_entry` (Virtio § 5.7.6.5)
#[repr(C)]
pub struct MemEntry {
    /// *Physical* address of one physically contiguous run of framebuffer.
    pub addr: u64,
    pub length: u32,
    pub padding: u32,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Spec: `virtio_gpu_formats` (Virtio § 5.7.6.3)
pub const FORMAT_B8G8R8A8: u32 = 1;
pub const FORMAT_B8G8R8X8: u32 = 2;
pub const FORMAT_A8R8G8B8: u32 = 3;
pub const FORMAT_X8R8G8B8: u32 = 4;
pub const FORMAT_R8G8B8A8: u32 = 67; // use this one
pub const FORMAT_X8B8G8R8: u32 = 68;
pub const FORMAT_A8B8G8R8: u32 = 121;
pub const FORMAT_R8G8B8X8: u32 = 134;

pub const DEFAULT_FORMAT: u32 = FORMAT_R8G8B8A8;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
#[repr(C)]
#[derive(Debug, Copy, Clone, Default, Eq, PartialEq)]
pub struct Pixel {
    pub r: u8,
    pub g: u8,
    pub b: u8,
    pub a: u8,
}
impl Pixel {
    pub const fn new(r: u8, g: u8, b: u8, a: u8) -> Self {
        Self { r, g, b, a }
    }
}

/// Spec: `virtio_gpu_rect` (Virtio § 5.7.6.2)
#[repr(C)]
#[derive(Debug, Copy, Clone, Default, Eq, PartialEq)]
pub struct Rect {
    pub x: u32,
    pub y: u32,
    pub width: u32,
    pub height: u32,
}
impl Rect {
    pub const fn new(x: u32, y: u32, width: u32, height: u32) -> Self {
        Self { x, y, width, height }
    }
    /// Get the coordinates as (x1, y1), (x2, y2)
    pub fn get_coords(&self) -> ((u32, u32), (u32, u32)) {
        let x1y1 = (self.x, self.y);
        let x2y2 = (self.width + self.x, self.height + self.y)
        (x1y1, x2y2)
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
/// Driver-side framebuffer. The device-side resource is its mirror.
pub struct Framebuffer {
    pages: Vec<PageAllocation>,
    width: u32,
    height: u32,
    resource_id: u32,
    /// Accumulated dirty region, or None if nothing has changed.
    dirty: Option<Rect>,
}

impl Framebuffer {
    /// Bounds-checked single pixel write. Every drawing primitive should
    /// go through here, or through something that has already clipped.
    pub fn set(&mut self, x: u32, y: u32, p: Pixel) { todo!() }

    /// Union `r` into the dirty region.
    pub fn invalidate(&mut self, r: Rect) { todo!() }

    /// TRANSFER_TO_HOST_2D + RESOURCE_FLUSH over the dirty region, then
    /// clear it. No-op if nothing is dirty.
    pub fn flush(&mut self) { todo!() }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
/// Spec: `virtio_gpu_transfer_to_host_2d` (Virtio § 5.7.6.11)
#[repr(C)]
pub struct TransferToHost2d {
    pub header: CtrlHeader,
    pub rect: Rect,
    pub offset: u64,
    pub resource_id: u32,
    pub padding: u32,
}

/// Spec: `virtio_gpu_resource_flush` (Virtio § 5.7.6.12)
#[repr(C)]
pub struct ResourceFlush {
    pub header: CtrlHeader,
    pub rect: Rect,
    pub resource_id: u32,
    pub padding: u32,
}

/// Byte offset into the driver framebuffer of the pixel at (left, top),
/// for a framebuffer whose row stride is `width` pixels.
const fn transfer_offset(top: u64, left: u64, width: u64) -> u64 {
    const PIXEL: u64 = core::mem::size_of::<Pixel>() as u64;
    left * PIXEL + top * width * PIXEL
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
/// # Draw a line from (x1,y1) to (x2,y2)
///
/// Bresenham's algorithm. Tracks an accumulated error term and steps
/// whichever axis keeps the error smallest.
///
/// ## Arguments
///
/// * `x1`, `y1` -- starting column and row.
/// * `x2`, `y2` -- ending column and row.
/// * `screen_width` -- row stride of `framebuffer`, in pixels.
/// * `framebuffer` -- the pixel array to draw into.
/// * `color` -- the line color.
pub fn draw_line(
    x1: usize,
    y1: usize,
    x2: usize,
    y2: usize,
    screen_width: usize,
    framebuffer: &mut [Pixel],
    color: Pixel,
) {
    let mut start_x = x1 as isize;
    let end_x = x2 as isize;
    let mut start_y = y1 as isize;
    let end_y = y2 as isize;
    let dx = x2.abs_diff(x1) as isize;
    let dy = -(y2.abs_diff(y1) as isize);

    // Step direction on each axis: right-to-left or left-to-right,
    // top-to-bottom or bottom-to-top.
    let sx = if x1 >= x2 { -1_isize } else { 1 };
    let sy = if y1 >= y2 { -1_isize } else { 1 };

    // Accumulated error in dx + dy.
    let mut error = dx + dy;
    loop {
        let pixel_location = start_y as usize * screen_width + start_x as usize;
        if pixel_location >= framebuffer.len() {
            debugln!(
                "Pixel location {} exceeded framebuffer size {}.",
                pixel_location,
                framebuffer.len()
            );
            break;
        }
        framebuffer[pixel_location] = color;

        let e2 = 2 * error;
        // Error exceeds the y delta, so stepping x keeps us closest.
        if e2 >= dy {
            if start_x == end_x {
                break;
            }
            error += dy;
            start_x += sx;
        }
        // Error is within the x delta, so step y as well.
        if e2 <= dx {
            if start_y == end_y {
                break;
            }
            error += dx;
            start_y += sy;
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/// # Fill a rectangle
///
/// ## Arguments
///
/// * `screen_width`, `screen_height` -- full drawing surface dimensions.
/// * `buffer` -- the pixel buffer.
/// * `rect` -- the region to fill.
/// * `fill` -- the fill color.
pub fn fill_rect(
    screen_width: u32,
    screen_height: u32,
    buffer: &mut [Pixel],
    rect: Rect,
    fill: Pixel,
) {
    let width = screen_width as usize;
    let height = screen_height as usize;

    let top = rect.y as usize;
    let bottom = core::cmp::min((rect.y + rect.height) as usize, height);
    let left = rect.x as usize;
    let right = core::cmp::min((rect.x + rect.width) as usize, width);

    for row in top..bottom {
        for col in left..right {
            buffer[row * width + col] = fill;
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
/// # Stroke (outline) a rectangle
///
/// Drawn as four filled rectangles, one per edge.
///
/// ## Arguments
///
/// * `screen_width`, `screen_height` -- full drawing surface dimensions.
/// * `buffer` -- the pixel buffer.
/// * `rect` -- the region to outline.
/// * `line_color` -- the edge color.
/// * `line_size` -- edge thickness in pixels.
pub fn stroke_rect(
    screen_width: u32,
    screen_height: u32,
    buffer: &mut [Pixel],
    rect: Rect,
    line_color: Pixel,
    line_size: u32,
) {
    // Top edge
    let r = Rect::new(rect.x, rect.y, rect.width, line_size);
    fill_rect(screen_width, screen_height, buffer, r, line_color);

    // Bottom edge
    let r = Rect::new(rect.x, rect.y + rect.height, rect.width, line_size);
    fill_rect(screen_width, screen_height, buffer, r, line_color);

    // Left edge
    let r = Rect::new(rect.x, rect.y, line_size, rect.height);
    fill_rect(screen_width, screen_height, buffer, r, line_color);

    // Right edge
    let r = Rect::new(
        rect.x + rect.width,
        rect.y,
        line_size,
        rect.height + line_size,
    );
    fill_rect(screen_width, screen_height, buffer, r, line_color);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
pub fn test(screen_width: u32, screen_height: u32, framebuffer: &mut [Pixel]) {
    let r1 = Rect::new(0, 0, screen_width, screen_height);
    let r2 = Rect::new(100, 100, screen_width - 150, screen_height - 150);

    let bg = Pixel::new(255, 130, 0, 255); // UT orange
    let fg = Pixel::new(88, 89, 91, 255);  // Smokey gray

    fill_rect(screen_width, screen_height, framebuffer, r1, bg);
    stroke_rect(screen_width, screen_height, framebuffer, r2, fg, 10);
}

// Assumes `terminal.fnt` is in `src/`
pub static TERMINAL_FONT: &[u8] = include_bytes!("terminal.fnt");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
use crate::TERMINAL_FONT;

const GLYPH_WIDTH: usize = 8;
const GLYPH_HEIGHT: usize = 16;
const STRING_SCALE_WIDTH: usize = 5;
const STRING_SCALE_HEIGHT: usize = 5;

/// # Draw a single character into a framebuffer
///
/// ## Arguments
///
/// * `c` -- the ASCII byte to draw.
/// * `row`, `col` -- position in *character cells*, not pixels.
/// * `screen_width` -- row stride of `framebuffer`, in pixels.
/// * `framebuffer` -- the pixel buffer.
/// * `fgcolor` -- color for set bits.
/// * `bgcolor` -- color for clear bits.
pub fn draw_char(
    c: u8,
    row: u32,
    col: u32,
    screen_width: u32,
    framebuffer: &mut [Pixel],
    fgcolor: Pixel,
    bgcolor: Pixel,
) {
    // One byte per glyph row, GLYPH_HEIGHT rows per glyph, ASCII order.
    let pos = c as usize * GLYPH_HEIGHT;

    let row = (row as usize) * GLYPH_HEIGHT * STRING_SCALE_HEIGHT;
    let col = (col as usize) * GLYPH_WIDTH * STRING_SCALE_WIDTH;
    let width = screen_width as usize;

    for i in 0..GLYPH_HEIGHT {
        for j in 0..GLYPH_WIDTH {
            // Bit 7 is the leftmost pixel, so index from the high bit.
            let bit = 1 << (7 - j);
            let color = if 0 != TERMINAL_FONT[pos + i] & bit {
                fgcolor
            } else {
                bgcolor
            };
            // Scale by replicating each font pixel into a block.
            for k in 0..STRING_SCALE_WIDTH {
                for l in 0..STRING_SCALE_HEIGHT {
                    let at = (row + i * STRING_SCALE_HEIGHT + l) * width
                           + (col + j * STRING_SCALE_WIDTH + k);
                    if at < framebuffer.len() {
                        framebuffer[at] = color;
                    }
                }
            }
        }
    }
}