1 #[cfg(test)]
2 pub mod fake;
3 
4 use crate::{Error, Result, PAGE_SIZE};
5 use core::{marker::PhantomData, ptr::NonNull};
6 
7 /// A physical address as used for virtio.
8 pub type PhysAddr = usize;
9 
10 /// A region of contiguous physical memory used for DMA.
11 #[derive(Debug)]
12 pub 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.
20 unsafe 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.
24 unsafe impl<H: Hal> Sync for Dma<H> {}
25 
26 impl<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.
new(pages: usize, direction: BufferDirection) -> Result<Self>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.
paddr(&self) -> usize45     pub fn paddr(&self) -> usize {
46         self.paddr
47     }
48 
49     /// Returns a pointer to the given offset within the DMA region.
vaddr(&self, offset: usize) -> NonNull<u8>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.
raw_slice(&self) -> NonNull<[u8]>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 
63 impl<H: Hal> Drop for Dma<H> {
drop(&mut self)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.
78 pub 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.
dma_alloc(pages: usize, direction: BufferDirection) -> (PhysAddr, NonNull<u8>)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`.
dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, pages: usize) -> i32100     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.
mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>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.
share(buffer: NonNull<[u8]>, direction: BufferDirection) -> PhysAddr130     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.
unshare(paddr: PhysAddr, buffer: NonNull<[u8]>, direction: BufferDirection)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)]
145 pub 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 }
153