Struct BootHandoff

#[repr(C, align(64))]
pub struct BootHandoff {

    pub magic: u64,
    pub version: u32,
    pub size: u32,
    pub nic_mmio_base: u64,
    pub nic_pci_bus: u8,
    pub nic_pci_device: u8,
    pub nic_pci_function: u8,
    pub nic_type: u8,
    pub mac_address: [u8; 6],
    pub _nic_pad: [u8; 2],
    pub blk_mmio_base: u64,
    pub blk_pci_bus: u8,
    pub blk_pci_device: u8,
    pub blk_pci_function: u8,
    pub blk_type: u8,
    pub blk_sector_size: u32,
    pub blk_total_sectors: u64,
    pub dma_cpu_ptr: u64,
    pub dma_bus_addr: u64,
    pub dma_size: u64,
    pub tsc_freq: u64,
    pub stack_top: u64,
    pub stack_size: u64,
    pub framebuffer_base: u64,
    pub framebuffer_width: u32,
    pub framebuffer_height: u32,
    pub framebuffer_stride: u32,
    pub framebuffer_format: u32,
    pub memory_map_ptr: u64,
    pub memory_map_size: u32,
    pub memory_map_desc_size: u32,
    pub nic_transport_type: u8,
    pub _transport_pad: [u8; 3],
    pub nic_notify_off_multiplier: u32,
    pub nic_common_cfg: u64,
    pub nic_notify_cfg: u64,
    pub nic_isr_cfg: u64,
    pub nic_device_cfg: u64,
    pub blk_transport_type: u8,
    pub _blk_transport_pad: [u8; 3],
    pub blk_notify_off_multiplier: u32,
    pub blk_common_cfg: u64,
    pub blk_notify_cfg: u64,
    pub blk_isr_cfg: u64,
    pub blk_device_cfg: u64,
    pub _reserved: [u8; 8],
}

Data passed from UEFI boot phase to bare-metal phase.

This structure is populated before ExitBootServices and consumed after. All pointers must remain valid post-EBS.

Safety

• All pointers must point to memory that survives ExitBootServices
• DMA region must be allocated via PCI I/O Protocol for IOMMU compatibility
• Structure must be placed in EfiLoaderData or EfiBootServicesData memory

Fields

magic: u64

Magic number for validation: “MORPHEUS” = 0x5355_4548_5052_4F4D

version: u32

Structure version (currently 1)

size: u32

Structure size in bytes (for forward compatibility)

nic_mmio_base: u64

VirtIO/NIC MMIO base address (from PCI BAR)

nic_pci_bus: u8

PCI bus number

nic_pci_device: u8

PCI device number

nic_pci_function: u8

PCI function number

nic_type: u8

NIC type: 0=None, 1=VirtIO, 2=Intel, 3=Realtek, 4=Broadcom

mac_address: [u8; 6]

MAC address (6 bytes, may be zeros if not yet read)

_nic_pad: [u8; 2]

Padding for alignment

blk_mmio_base: u64

Block device MMIO base address (legacy) or common_cfg (PCI Modern)

blk_pci_bus: u8

Block device PCI bus number

blk_pci_device: u8

Block device PCI device number

blk_pci_function: u8

Block device PCI function number

blk_type: u8

Block device type: 0=None, 1=VirtIO-blk, 2=NVMe, 3=AHCI

blk_sector_size: u32

Block device sector size (typically 512)

blk_total_sectors: u64

Block device total sectors

dma_cpu_ptr: u64

CPU pointer for software access

dma_bus_addr: u64

Bus address for device DMA (may differ from CPU addr with IOMMU)

dma_size: u64

Region size in bytes (minimum 2MB)

tsc_freq: u64

Calibrated TSC frequency (ticks per second) MUST be calibrated at boot using UEFI Stall(). NO HARDCODED VALUES.

stack_top: u64

Top of stack (highest address, stack grows down)

stack_size: u64

Stack size in bytes (minimum 64KB)

framebuffer_base: u64

Framebuffer base address for debug output (0 if unavailable)

framebuffer_width: u32

Framebuffer width in pixels

framebuffer_height: u32

Framebuffer height in pixels

framebuffer_stride: u32

Framebuffer stride (bytes per row)

framebuffer_format: u32

Framebuffer pixel format: 0=BGR, 1=RGB

memory_map_ptr: u64

Pointer to UEFI memory map (copied before EBS)

memory_map_size: u32

Memory map size in bytes

memory_map_desc_size: u32

Memory map descriptor size

nic_transport_type: u8

Transport type: 0=MMIO, 1=PCI Modern, 2=PCI Legacy

_transport_pad: [u8; 3]

Padding

nic_notify_off_multiplier: u32

Notify offset multiplier (from VIRTIO_PCI_CAP_NOTIFY)

nic_common_cfg: u64

Common cfg address (BAR base + cap offset)

nic_notify_cfg: u64

Notify cfg address (BAR base + cap offset)

nic_isr_cfg: u64

ISR cfg address (BAR base + cap offset)

nic_device_cfg: u64

Device cfg address (BAR base + cap offset)

blk_transport_type: u8

Transport type: 0=MMIO, 1=PCI Modern, 2=PCI Legacy

_blk_transport_pad: [u8; 3]

Padding

blk_notify_off_multiplier: u32

Notify offset multiplier (from VIRTIO_PCI_CAP_NOTIFY)

blk_common_cfg: u64

Common cfg address (BAR base + cap offset) - same as blk_mmio_base for PCI Modern

blk_notify_cfg: u64

Notify cfg address (BAR base + cap offset)

blk_isr_cfg: u64

ISR cfg address (BAR base + cap offset)

blk_device_cfg: u64

Device cfg address (BAR base + cap offset)

_reserved: [u8; 8]

Implementations

impl BootHandoff

pub const MAGIC: u64 = 6_004_781_855_055_957_837u64

Magic number constant

pub const VERSION: u32 = 1u32

Current version constant

pub const SIZE: u32 = 256u32

Expected structure size

pub const fn new() -> Self

Create a zeroed handoff structure with magic and version set.

pub fn validate(&self) -> Result<(), HandoffError>

Validate the handoff structure.

Returns

• Ok(()) if valid
• Err(HandoffError) describing the first validation failure

pub fn validate_network_only(&self) -> Result<(), HandoffError>

Validate for network-only operation (block device optional).

pub fn has_block_device(&self) -> bool

Check if block device is configured.

pub fn has_framebuffer(&self) -> bool

Check if framebuffer is available.

pub unsafe fn dma_region(&self) -> (*mut u8, u64, u64)

Get DMA region as raw pointer and size.

Safety

The returned pointer is only valid if the handoff has been validated.

pub fn ms_to_ticks(&self, ms: u64) -> u64

Convert milliseconds to TSC ticks.

pub fn ticks_to_ms(&self, ticks: u64) -> u64

Convert TSC ticks to milliseconds.

pub fn us_to_ticks(&self, us: u64) -> u64

Convert microseconds to TSC ticks.

pub fn ticks_to_us(&self, ticks: u64) -> u64

Convert TSC ticks to microseconds.

Trait Implementations

impl Clone for BootHandoff

fn clone(&self) -> BootHandoff

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BootHandoff

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BootHandoff

fn default() -> Self

Returns the “default value” for a type.

impl Copy for BootHandoff