ixgbe_driver/
hal.rs

1//! Hardware Abstraction Layer (HAL) for the ixgbe driver.
2//!
3//! This module defines the [`IxgbeHal`] trait, which must be implemented by the platform
4//! specific code to integrate the ixgbe driver with a given operating system or bare-metal
5//! environment.
6//!
7//! # The HAL Interface
8//!
9//! The HAL trait provides three categories of functionality:
10//!
11//! 1. **DMA Memory Management**: Allocating and freeing physically contiguous memory
12//!    that the NIC can access directly
13//!
14//! 2. **MMIO Address Translation**: Converting between physical and virtual addresses
15//!    for accessing device registers
16//!
17//! 3. **Timing/Waiting**: Blocking execution for a specified duration
18//!
19//! # Example Implementation
20//!
21//! ```rust,ignore
22//! use core::ptr::NonNull;
23//! use core::time::Duration;
24//! use ixgbe_driver::hal::IxgbeHal;
25//! use ixgbe_driver::memory::PhysAddr;
26//!
27//! struct MyHal;
28//!
29//! unsafe impl IxgbeHal for MyHal {
30//!     fn dma_alloc(size: usize) -> (PhysAddr, NonNull<u8>) {
31//!         // Platform-specific DMA allocation
32//!         todo!()
33//!     }
34//!
35//!     unsafe fn dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, size: usize) -> i32 {
36//!         // Platform-specific DMA deallocation
37//!         todo!()
38//!     }
39//!
40//!     unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8> {
41//!         // Map MMIO physical address to virtual
42//!         todo!()
43//!     }
44//!
45//!     unsafe fn mmio_virt_to_phys(vaddr: NonNull<u8>, size: usize) -> PhysAddr {
46//!         // Map MMIO virtual address to physical
47//!         todo!()
48//!     }
49//!
50//!     fn wait_until(duration: Duration) -> Result<(), &'static str> {
51//!         // Block for the specified duration
52//!         todo!()
53//!     }
54//! }
55//! ```
56
57use crate::memory::PhysAddr;
58use core::ptr::NonNull;
59use core::time::Duration;
60
61/// The interface which a particular hardware implementation must implement.
62///
63/// # Safety
64///
65/// Implementations of this trait must follow the "implementation safety" requirements documented
66/// for each method. Callers must follow the safety requirements documented for the unsafe methods.
67pub unsafe trait IxgbeHal
68where
69    Self: Sized,
70{
71    /// Allocates and zeroes the given number of contiguous physical memory of DMA memory for Ixgbe NIC
72    /// use.
73    ///
74    /// Returns both the physical address which the device can use to access the memory, and a
75    /// pointer to the start of it which the driver can use to access it.
76    ///
77    /// # Implementation safety
78    ///
79    /// Implementations of this method must ensure that the `NonNull<u8>` returned is a
80    /// [_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety) pointer, aligned to
81    /// 2, and won't alias any other allocations or references in the program until it
82    /// is deallocated by `dma_dealloc`. The pages must be zeroed.
83    fn dma_alloc(size: usize) -> (PhysAddr, NonNull<u8>);
84
85    /// Deallocates the given contiguous physical DMA memory pages.
86    ///
87    /// # Safety
88    ///
89    /// The memory must have been allocated by `dma_alloc` on the same `Hal` implementation, and not
90    /// yet deallocated. `size` must be the same number passed to `dma_alloc` originally, and both
91    /// `paddr` and `vaddr` must be the values returned by `dma_alloc`.
92    unsafe fn dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, size: usize) -> i32;
93
94    /// Converts a physical address used for MMIO to a virtual address which the driver can access.
95    ///
96    /// This is only used for MMIO addresses within BARs read from the device, for the PCI
97    /// transport. It may check that the address range up to the given size is within the region
98    /// expected for MMIO.
99    ///
100    /// # Implementation safety
101    ///
102    /// Implementations of this method must ensure that the `NonNull<u8>` returned is a
103    /// [_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety) pointer, and won't alias any
104    /// other allocations or references in the program.
105    ///
106    /// # Safety
107    ///
108    /// The `paddr` and `size` must describe a valid MMIO region. The implementation may validate it
109    /// in some way (and panic if it is invalid) but is not guaranteed to.
110    unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>;
111
112    /// Converts a virtual address used by the driver to access MMIO to a physical address which the
113    /// device can use.
114    ///
115    /// # Safety
116    ///
117    ///
118    unsafe fn mmio_virt_to_phys(vaddr: NonNull<u8>, size: usize) -> PhysAddr;
119
120    /// Wait until reaching the given deadline.
121    fn wait_until(duration: Duration) -> Result<(), &'static str>;
122}
ixgbe_driver/hal.rs

ixgbe_driver/
hal.rs
