virtio_drivers/
hal.rs

Help
1#[cfg(test)]
2pub mod fake;
3
4use crate::{Error, Result, PAGE_SIZE};
5use core::{marker::PhantomData, ptr::NonNull};
6
7/// A physical address as used for virtio.
8pub type PhysAddr = usize;
9
10/// A region of contiguous physical memory used for DMA.
11#[derive(Debug)]
12pub struct Dma<H: Hal> {
13    paddr: usize,
14    vaddr: NonNull<u8>,
15    pages: usize,
16    _hal: PhantomData<H>,
17}
18
19// SAFETY: DMA memory can be accessed from any thread.
20unsafe impl<H: Hal> Send for Dma<H> {}
21
22// SAFETY: `&Dma` only allows pointers and physical addresses to be returned. Any actual access to
23// the memory requires unsafe code, which is responsible for avoiding data races.
24unsafe impl<H: Hal> Sync for Dma<H> {}
25
26impl<H: Hal> Dma<H> {
27    /// Allocates the given number of pages of physically contiguous memory to be used for DMA in
28    /// the given direction.
29    ///
30    /// The pages will be zeroed.
31    pub fn new(pages: usize, direction: BufferDirection) -> Result<Self> {
32        let (paddr, vaddr) = H::dma_alloc(pages, direction);
33        if paddr == 0 {
34            return Err(Error::DmaError);
35        }
36        Ok(Self {
37            paddr,
38            vaddr,
39            pages,
40            _hal: PhantomData,
41        })
42    }
43
44    /// Returns the physical address of the start of the DMA region, as seen by devices.
45    pub fn paddr(&self) -> usize {
46        self.paddr
47    }
48
49    /// Returns a pointer to the given offset within the DMA region.
50    pub fn vaddr(&self, offset: usize) -> NonNull<u8> {
51        assert!(offset < self.pages * PAGE_SIZE);
52        NonNull::new((self.vaddr.as_ptr() as usize + offset) as _).unwrap()
53    }
54
55    /// Returns a pointer to the entire DMA region as a slice.
56    pub fn raw_slice(&self) -> NonNull<[u8]> {
57        let raw_slice =
58            core::ptr::slice_from_raw_parts_mut(self.vaddr(0).as_ptr(), self.pages * PAGE_SIZE);
59        NonNull::new(raw_slice).unwrap()
60    }
61}
62
63impl<H: Hal> Drop for Dma<H> {
64    fn drop(&mut self) {
65        // Safe because the memory was previously allocated by `dma_alloc` in `Dma::new`, not yet
66        // deallocated, and we are passing the values from then.
67        let err = unsafe { H::dma_dealloc(self.paddr, self.vaddr, self.pages) };
68        assert_eq!(err, 0, "failed to deallocate DMA");
69    }
70}
71
72/// The interface which a particular hardware implementation must implement.
73///
74/// # Safety
75///
76/// Implementations of this trait must follow the "implementation safety" requirements documented
77/// for each method. Callers must follow the safety requirements documented for the unsafe methods.
78pub unsafe trait Hal {
79    /// Allocates and zeroes the given number of contiguous physical pages of DMA memory for VirtIO
80    /// use.
81    ///
82    /// Returns both the physical address which the device can use to access the memory, and a
83    /// pointer to the start of it which the driver can use to access it.
84    ///
85    /// # Implementation safety
86    ///
87    /// Implementations of this method must ensure that the `NonNull<u8>` returned is a
88    /// [_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety) pointer, aligned to
89    /// [`PAGE_SIZE`], and won't alias any other allocations or references in the program until it
90    /// is deallocated by `dma_dealloc`. The pages must be zeroed.
91    fn dma_alloc(pages: usize, direction: BufferDirection) -> (PhysAddr, NonNull<u8>);
92
93    /// Deallocates the given contiguous physical DMA memory pages.
94    ///
95    /// # Safety
96    ///
97    /// The memory must have been allocated by `dma_alloc` on the same `Hal` implementation, and not
98    /// yet deallocated. `pages` must be the same number passed to `dma_alloc` originally, and both
99    /// `paddr` and `vaddr` must be the values returned by `dma_alloc`.
100    unsafe fn dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, pages: usize) -> i32;
101
102    /// Converts a physical address used for MMIO to a virtual address which the driver can access.
103    ///
104    /// This is only used for MMIO addresses within BARs read from the device, for the PCI
105    /// transport. It may check that the address range up to the given size is within the region
106    /// expected for MMIO.
107    ///
108    /// # Implementation safety
109    ///
110    /// Implementations of this method must ensure that the `NonNull<u8>` returned is a
111    /// [_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety) pointer, and won't alias any
112    /// other allocations or references in the program.
113    ///
114    /// # Safety
115    ///
116    /// The `paddr` and `size` must describe a valid MMIO region. The implementation may validate it
117    /// in some way (and panic if it is invalid) but is not guaranteed to.
118    unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>;
119
120    /// Shares the given memory range with the device, and returns the physical address that the
121    /// device can use to access it.
122    ///
123    /// This may involve mapping the buffer into an IOMMU, giving the host permission to access the
124    /// memory, or copying it to a special region where it can be accessed.
125    ///
126    /// # Safety
127    ///
128    /// The buffer must be a valid pointer to a non-empty memory range which will not be accessed by
129    /// any other thread for the duration of this method call.
130    unsafe fn share(buffer: NonNull<[u8]>, direction: BufferDirection) -> PhysAddr;
131
132    /// Unshares the given memory range from the device and (if necessary) copies it back to the
133    /// original buffer.
134    ///
135    /// # Safety
136    ///
137    /// The buffer must be a valid pointer to a non-empty memory range which will not be accessed by
138    /// any other thread for the duration of this method call. The `paddr` must be the value
139    /// previously returned by the corresponding `share` call.
140    unsafe fn unshare(paddr: PhysAddr, buffer: NonNull<[u8]>, direction: BufferDirection);
141}
142
143/// The direction in which a buffer is passed.
144#[derive(Copy, Clone, Debug, Eq, PartialEq)]
145pub enum BufferDirection {
146    /// The buffer may be read or written by the driver, but only read by the device.
147    DriverToDevice,
148    /// The buffer may be read or written by the device, but only read by the driver.
149    DeviceToDriver,
150    /// The buffer may be read or written by both the device and the driver.
151    Both,
152}
virtio_drivers/hal.rs

virtio_drivers/
hal.rs
