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