Trait Hal

pub unsafe trait Hal {
    // Required methods
    fn dma_alloc(
        pages: usize,
        direction: BufferDirection,
    ) -> (PhysAddr, NonNull<u8>);
    unsafe fn dma_dealloc(
        paddr: PhysAddr,
        vaddr: NonNull<u8>,
        pages: usize,
    ) -> i32;
    unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>;
    unsafe fn share(
        buffer: NonNull<[u8]>,
        direction: BufferDirection,
    ) -> PhysAddr;
    unsafe fn unshare(
        paddr: PhysAddr,
        buffer: NonNull<[u8]>,
        direction: BufferDirection,
    );
}

The interface which a particular hardware implementation must implement.

Safety

Implementations of this trait must follow the “implementation safety” requirements documented for each method. Callers must follow the safety requirements documented for the unsafe methods.

Required Methods

fn dma_alloc( pages: usize, direction: BufferDirection, ) -> (PhysAddr, NonNull<u8>)

Allocates and zeroes the given number of contiguous physical pages of DMA memory for VirtIO use.

Returns both the physical address which the device can use to access the memory, and a pointer to the start of it which the driver can use to access it.

Implementation safety

Implementations of this method must ensure that the NonNull<u8> returned is a valid pointer, aligned to PAGE_SIZE, and won’t alias any other allocations or references in the program until it is deallocated by dma_dealloc. The pages must be zeroed.

unsafe fn dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, pages: usize) -> i32

Deallocates the given contiguous physical DMA memory pages.

Safety

The memory must have been allocated by dma_alloc on the same Hal implementation, and not yet deallocated. pages must be the same number passed to dma_alloc originally, and both paddr and vaddr must be the values returned by dma_alloc.

unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>

Converts a physical address used for MMIO to a virtual address which the driver can access.

This is only used for MMIO addresses within BARs read from the device, for the PCI transport. It may check that the address range up to the given size is within the region expected for MMIO.

Implementation safety

Implementations of this method must ensure that the NonNull<u8> returned is a valid pointer, and won’t alias any other allocations or references in the program.

Safety

The paddr and size must describe a valid MMIO region. The implementation may validate it in some way (and panic if it is invalid) but is not guaranteed to.

unsafe fn share(buffer: NonNull<[u8]>, direction: BufferDirection) -> PhysAddr

Shares the given memory range with the device, and returns the physical address that the device can use to access it.

This may involve mapping the buffer into an IOMMU, giving the host permission to access the memory, or copying it to a special region where it can be accessed.

Safety

The buffer must be a valid pointer to a non-empty memory range which will not be accessed by any other thread for the duration of this method call.

unsafe fn unshare( paddr: PhysAddr, buffer: NonNull<[u8]>, direction: BufferDirection, )

Unshares the given memory range from the device and (if necessary) copies it back to the original buffer.

Safety

The buffer must be a valid pointer to a non-empty memory range which will not be accessed by any other thread for the duration of this method call. The paddr must be the value previously returned by the corresponding share call.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors