user_driver/lib.rs
1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Infrastructure for implementing PCI drivers in user mode.
5
6// UNSAFETY: Manual memory management around buffers and mmap.
7#![expect(unsafe_code)]
8#![expect(missing_docs)]
9
10use inspect::Inspect;
11use interrupt::DeviceInterrupt;
12use memory::MemoryBlock;
13use std::sync::Arc;
14
15pub mod backoff;
16pub mod interrupt;
17pub mod lockmem;
18pub mod memory;
19pub mod page_allocator;
20pub mod vfio;
21
22/// An interface to access device hardware.
23pub trait DeviceBacking: 'static + Send + Inspect {
24 /// An object for accessing device registers.
25 type Registers: 'static + DeviceRegisterIo + Inspect;
26
27 /// Returns a device ID for diagnostics.
28 fn id(&self) -> &str;
29
30 /// Maps a BAR.
31 fn map_bar(&mut self, n: u8) -> anyhow::Result<Self::Registers>;
32
33 /// DMA Client for the device.
34 fn dma_client(&self) -> Arc<dyn DmaClient>;
35
36 /// Returns the maximum number of interrupts that can be mapped.
37 fn max_interrupt_count(&self) -> u32;
38
39 /// Maps a MSI-X interrupt for use, returning an object that can be used to
40 /// wait for the interrupt to be signaled by the device.
41 ///
42 /// `cpu` is the CPU that the device should target with this interrupt.
43 ///
44 /// This can be called multiple times for the same interrupt without disconnecting
45 /// previous mappings. The last `cpu` value will be used as the target CPU.
46 fn map_interrupt(&mut self, msix: u32, cpu: u32) -> anyhow::Result<DeviceInterrupt>;
47
48 /// Unmaps and disables all previously mapped interrupts.
49 ///
50 /// Default implementation is a no-op for backends that do not support interrupt unmapping.
51 fn unmap_all_interrupts(&mut self) -> anyhow::Result<()> {
52 Ok(())
53 }
54}
55
56/// Access to device registers.
57pub trait DeviceRegisterIo: Send + Sync {
58 /// Returns the length of the register space.
59 fn len(&self) -> usize;
60 /// Reads a `u32` register.
61 fn read_u32(&self, offset: usize) -> u32;
62 /// Reads a `u64` register.
63 fn read_u64(&self, offset: usize) -> u64;
64 /// Writes a `u32` register.
65 fn write_u32(&self, offset: usize, data: u32);
66 /// Writes a `u64` register.
67 fn write_u64(&self, offset: usize, data: u64);
68}
69
70/// Device interfaces for DMA.
71pub trait DmaClient: Send + Sync + Inspect {
72 /// Allocate a new DMA buffer. This buffer must be zero initialized.
73 ///
74 /// TODO: string tag for allocation?
75 /// TODO: contiguous vs non-contiguous? (both on the request side, and if
76 /// a request contiguous allocation cannot be fulfilled)
77 fn allocate_dma_buffer(&self, total_size: usize) -> anyhow::Result<MemoryBlock>;
78
79 /// Attach all previously allocated memory blocks.
80 fn attach_pending_buffers(&self) -> anyhow::Result<Vec<MemoryBlock>>;
81}