ixgbe-driver 0.1.1

//! Hardware Abstraction Layer (HAL) for the ixgbe driver.
//!
//! This module defines the [`IxgbeHal`] trait, which must be implemented by the platform
//! specific code to integrate the ixgbe driver with a given operating system or bare-metal
//! environment.
//!
//! # The HAL Interface
//!
//! The HAL trait provides three categories of functionality:
//!
//! 1. **DMA Memory Management**: Allocating and freeing physically contiguous memory
//!    that the NIC can access directly
//!
//! 2. **MMIO Address Translation**: Converting between physical and virtual addresses
//!    for accessing device registers
//!
//! 3. **Timing/Waiting**: Blocking execution for a specified duration
//!
//! # Example Implementation
//!
//! ```rust,ignore
//! use core::ptr::NonNull;
//! use core::time::Duration;
//! use ixgbe_driver::hal::IxgbeHal;
//! use ixgbe_driver::memory::PhysAddr;
//!
//! struct MyHal;
//!
//! unsafe impl IxgbeHal for MyHal {
//!     fn dma_alloc(size: usize) -> (PhysAddr, NonNull<u8>) {
//!         // Platform-specific DMA allocation
//!         todo!()
//!     }
//!
//!     unsafe fn dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, size: usize) -> i32 {
//!         // Platform-specific DMA deallocation
//!         todo!()
//!     }
//!
//!     unsafe fn mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8> {
//!         // Map MMIO physical address to virtual
//!         todo!()
//!     }
//!
//!     unsafe fn mmio_virt_to_phys(vaddr: NonNull<u8>, size: usize) -> PhysAddr {
//!         // Map MMIO virtual address to physical
//!         todo!()
//!     }
//!
//!     fn wait_until(duration: Duration) -> Result<(), &'static str> {
//!         // Block for the specified duration
//!         todo!()
//!     }
//! }
//! ```

use crate::memory::PhysAddr;
use core::ptr::NonNull;
use core::time::Duration;

/// 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.
pub unsafe trait IxgbeHal
where
    Self: Sized,
{
    /// Allocates and zeroes the given number of contiguous physical memory of DMA memory for Ixgbe NIC
    /// 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_](https://doc.rust-lang.org/std/ptr/index.html#safety) pointer, aligned to
    /// 2, and won't alias any other allocations or references in the program until it
    /// is deallocated by `dma_dealloc`. The pages must be zeroed.
    fn dma_alloc(size: usize) -> (PhysAddr, NonNull<u8>);

    /// 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. `size` 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 dma_dealloc(paddr: PhysAddr, vaddr: NonNull<u8>, size: usize) -> i32;

    /// 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_](https://doc.rust-lang.org/std/ptr/index.html#safety) 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 mmio_phys_to_virt(paddr: PhysAddr, size: usize) -> NonNull<u8>;

    /// Converts a virtual address used by the driver to access MMIO to a physical address which the
    /// device can use.
    ///
    /// # Safety
    ///
    ///
    unsafe fn mmio_virt_to_phys(vaddr: NonNull<u8>, size: usize) -> PhysAddr;

    /// Wait until reaching the given deadline.
    fn wait_until(duration: Duration) -> Result<(), &'static str>;
}