API Reference

Core

The hypervisor entry point and boot-time initialization logic.

group Core

Hypervisor core — entry point, scheduler, and exception handling.

Enums

enum class ValidateError : uint32_t

Error codes returned by validate().

Values:

enumerator None

No error; package is valid.

enumerator NullPackage

Null package pointer passed.

enumerator TooSmall

Region is smaller than the minimum header size.

enumerator BadMagic

magic field does not match HV_GUEST_BOOT_PKG_MAGIC.

enumerator BadVersion

version field is not HV_GUEST_BOOT_PKG_VERSION.

enumerator BadHeaderSize

header_size field is not HV_GUEST_BOOT_PKG_HEADER_SIZE.

enumerator BadTotalSize

total_size does not match the firmware-reported size.

enumerator BadHeaderCrc

Header CRC32 check failed.

enumerator BadPayloadCrc

Payload CRC32 check failed.

enumerator UnsupportedBootProtocol

boot_protocol is not HV_GUEST_BOOT_PKG_BOOT_PROTOCOL_LINUX_ARM64.

enumerator UnknownFlags

flags contains bits not in HV_GUEST_BOOT_PKG_KNOWN_FLAGS.

enumerator MissingKernel

kernel_size is zero.

enumerator MissingDtb

dtb_size is zero.

enumerator BadInitrdFlag

INITRD_PRESENT flag is inconsistent with initrd_size.

enumerator BadKernelOffset

kernel_offset is not HV_GUEST_BOOT_PKG_HEADER_SIZE.

enumerator BadDtbOffset

dtb_offset is not 4 KiB aligned.

enumerator BadInitrdOffset

initrd_offset is not 4 KiB aligned.

enumerator BadTotalLayout

Component offsets/sizes do not sum to total_size.

enumerator ComponentOutOfBounds

A component range extends past total_size.

enumerator GuestLayoutOverflow

Components do not fit in the fixed guest RAM layout.

enum class LoadError : uint32_t

Error codes returned by loadLinuxGuest().

Values:

enumerator None

No error; guest loaded successfully.

enumerator MissingFirmwarePackage

MemoryMap::bootPackageBase or bootPackageSize is zero.

enumerator InvalidPackage

Package validation failed; see validateError for detail.

enumerator GuestLayoutOverflow

IPA layout calculation failed for the validated package.

enumerator GuestRamAllocationFailed

PMM could not allocate a contiguous 256 MiB block.

enumerator GuestDtbPatchFailed

Guest DTB placeholder patching failed.

Functions

MemoryMap parseDtb(uintptr_t dtb)

Parse a Flattened Device Tree blob and extract key memory regions.

Walks the DTB structure block to locate the main RAM node and selected reserved-memory children used by TF-A or secure monitor firmware.

Parameters:

dtb – Physical address of the DTB blob passed in at boot.

Returns:

Parsed MemoryMap. isValid is set only when the main memory region was found and decoded successfully. bootPackageBase and bootPackageSize are populated from the /chosen/linux,initrd-start and /chosen/linux,initrd-end properties when present (the Raspberry Pi firmware writes these after loading the guest package).

void hmain(uintptr_t dtb)

Main hypervisor entry point (called from boot.S).

Uses C linkage so the assembly boot code can branch to it by name without C++ name mangling.

Warning

Must never return. The assembly boot stub has no return address — falling off the end of hmain() is undefined behaviour.

struct PackageView

#include <bootpkg.h>

Decoded view of a validated v1 package header.

Populated by validate() when the package passes all checks. Offsets are byte offsets from the start of the firmware-loaded region.

Public Members

uint64_t totalSize

Total firmware-loaded byte count.

uint32_t bootProtocol

Boot protocol identifier (e.g.

HV_GUEST_BOOT_PKG_BOOT_PROTOCOL_LINUX_ARM64).

uint32_t flags

Package modifier flags.

uint64_t kernelOffset

Byte offset of the kernel component from the package start.

uint64_t kernelSize

Size in bytes of the kernel component.

uint64_t dtbOffset

Byte offset of the guest DTB component.

uint64_t dtbSize

Size in bytes of the guest DTB component.

uint64_t initrdOffset

Byte offset of the initrd component, or zero if absent.

uint64_t initrdSize

Size in bytes of the initrd component, or zero if absent.

uint64_t entryOffset

Entry point offset from the kernel load IPA.

const char *buildId

NUL-terminated build identifier string from the header, or empty string.

struct GuestLayout

#include <bootpkg.h>

Resolved guest IPA layout for a validated v1 package.

Computed by calculateGuestLayout() from a PackageView. All addresses are guest IPAs within the fixed 256 MiB guest RAM region.

Public Members

uint64_t guestIpaBase

Guest IPA base (always GUEST_IPA_BASE in v1).

uint64_t guestRamSize

Total guest RAM size (always GUEST_RAM_SIZE in v1).

uint64_t kernelIpa

IPA at which the kernel Image is loaded.

uint64_t kernelSize

Size in bytes of the kernel component.

uint64_t entryIpa

Guest entry IPA (kernelIpa + entryOffset).

uint64_t dtbIpa

IPA at which the guest DTB is placed.

uint64_t dtbSize

Size in bytes of the guest DTB component.

uint64_t initrdIpa

IPA at which the initrd is placed, or zero if absent.

uint64_t initrdSize

Size in bytes of the initrd, or zero if absent.

struct LoadedGuest

#include <bootpkg.h>

Hypervisor-facing descriptor for a successfully loaded Linux guest.

Returned by loadLinuxGuest() and consumed by Vm::init() to configure stage-2 mappings and seed the vCPU entry state.

Public Members

uint64_t guestRamHostPa

Host physical base of the allocated guest RAM block.

uint64_t guestIpaBase

Guest IPA base (mirrors GuestLayout::guestIpaBase).

uint64_t guestRamSize

Size in bytes of the guest RAM allocation.

uint64_t entryIpa

Guest IPA of the first instruction executed by the vCPU.

uint64_t dtbIpa

Guest IPA of the DTB passed to Linux in x0.

struct ValidateResult

#include <bootpkg.h>

Result of a validate() call.

Public Members

bool isValid

True only when validation succeeded and package is populated.

ValidateError error

First validation error encountered, or ValidateError::None.

PackageView package

Decoded package metadata; valid only when isValid is true.

struct LoadResult

#include <bootpkg.h>

Result of a loadLinuxGuest() call.

Public Members

bool isLoaded

True only when the guest was loaded and guest is populated.

LoadError error

High-level load error, or LoadError::None.

ValidateError validateError

Validation error when error is LoadError::InvalidPackage.

LoadedGuest guest

Loaded guest descriptor; valid only when isLoaded is true.

struct MemoryMap

#include <dtb.h>

Boot-time physical memory layout parsed from the DTB.

Contains the primary RAM range plus reserved regions needed by the hypervisor before the MMU and dynamic allocation are available.

Public Members

uint64_t memBase

Base physical address of the main RAM region.

uint64_t memSize

Size in bytes of the main RAM region.

uint64_t atfBase

Base physical address of the TF-A reserved region.

uint64_t atfSize

Size in bytes of the TF-A reserved region.

uint64_t dtbBase

Base physical address of the DTB blob.

uint64_t dtbSize

Total size in bytes of the DTB blob.

uint64_t bootPackageBase

Base PA of the firmware-loaded guest package, from /chosen/linux,initrd-start.

Zero if absent.

uint64_t bootPackageSize

Size in bytes of the firmware-loaded guest package (initrd-end minus initrd-start).

Zero if absent.

bool isValid

True only if all fields were successfully parsed.

Memory Management

Boot-time physical memory discovery and contiguous page allocation.

PMM

Physical page allocator using the buddy allocation algorithm.

group PMM

Physical page allocator using the buddy allocation algorithm.

Functions

void init(const MemoryMap &map)

Initialise the buddy allocator from a DTB memory map.

Parameters:

map – Physical memory regions discovered from the device tree.

uint64_t allocPages(uint32_t order)

Allocate a power-of-2 block of physical pages.

Parameters:

order – Block size exponent: allocates PAGE_SIZE * 2^order bytes.

Returns:

Physical base address of the allocated block, or 0 on failure.

void freePages(uint64_t addr, uint32_t order)

Return a previously allocated block to the free pool.

Parameters:

• addr – Physical base address returned by allocPages().

• order – Must match the order passed to allocPages().

void dumpState()

Print a human-readable summary of the free-list state.

MMU

Host stage-1 and guest stage-2 translation interfaces.

group MMU

Host stage-1 and guest stage-2 MMU interfaces and helpers.

Functions

void init()

Build EL2 translation tables and enable stage-1 translation.

inline void *paToVa(uint64_t pa)

Convert a host physical address to an EL2-accessible pointer.

HyperBerry currently uses an identity direct map for RAM. Keeping this helper at the boundary avoids spreading that assumption through loaders.

Parameters:

pa – Host physical address.

Returns:

EL2 virtual address for the same byte.

void mapRange(uint64_t va, uint64_t pa, uint64_t size, uint64_t flags)

Map a physical range into EL2 VA space using 2 MiB blocks.

Parameters:

• va – Virtual base address.

• pa – Physical base address.

• size – Mapping size in bytes (multiple of 2 MiB).

• flags – Descriptor flags excluding the output-address bits.

void unmapRange(uint64_t va, uint64_t size)

Remove mappings for a virtual range and flush affected TLBs.

Parameters:

• va – Virtual base address.

• size – Range size in bytes (multiple of 2 MiB).

void tlbFlushAll()

Invalidate all EL2 stage-1 TLB entries.

void tlbFlushVa(uint64_t va)

Invalidate a single EL2 VA translation from the TLB.

Parameters:

va – Virtual address within the page to flush.

class GuestMmu

#include <guestMmu.h>

Per-guest stage-2 MMU.

Owns the stage-2 root table and VMID. enable() programs VTTBR_EL2 and sets HCR_EL2.VM=1. Shared by all vCPUs that belong to the same guest (ARM semantics: one stage-2 table per VM, distinguished at the TLB by VMID).

Public Functions

void init(uint64_t ipaBase, uint64_t hostPaBase, uint64_t sizeBytes)

Allocate the stage-2 root table, program VTCR_EL2, and map a contiguous guest IPA range to host physical memory.

Parameters:

• ipaBase – Start of the guest IPA region.

• hostPaBase – Start of the backing host physical region.

• sizeBytes – Size of the region (must be 2 MiB aligned).

void mapBlock(uint64_t ipa, uint64_t pa, bool isDevice)

Install one 2 MiB stage-2 block descriptor.

Parameters:

• ipa – Intermediate physical address (2 MiB aligned).

• pa – Target physical address.

• isDevice – True selects device-nGnRnE memory attributes, false selects normal write-back cacheable memory.

void mapPage(uint64_t ipa, uint64_t pa, bool isDevice)

Install one 4 KiB stage-2 page descriptor.

Parameters:

• ipa – Intermediate physical address (4 KiB aligned).

• pa – Target physical address (4 KiB aligned).

• isDevice – True selects device-nGnRnE memory attributes, false selects normal write-back cacheable memory.

void enable(uint8_t vmid)

Commit this stage-2 context: program VTTBR_EL2 with vmid, flush stage-2 TLB, and set HCR_EL2.VM=1.

Parameters:

vmid – Non-zero VMID. Each live VM must have a unique VMID.

void tlbFlushAllGuest()

Invalidate all stage-1 & stage-2 TLB entries for this VMID.

Heap

PMM-backed kernel heap lifecycle used by global C++ allocation.

Page Tables

Shared page-table walk and allocation helpers used by both MMU paths.

Functions

static inline uint64_t *pte_next_table(uint64_t entry)

static inline int pte_is_valid(uint64_t entry)

static inline int pte_is_table(uint64_t entry)

static inline int pte_is_block(uint64_t entry)

Defines

PTE_VALID

PTE_TABLE

PTE_BLOCK

PTE_AF

PTE_ADDR_MASK

SIZE_4KB

SIZE_2MB

SIZE_1GB

SIZE_8GB

SIZE_16GB

L0_INDEX(addr)

L1_INDEX(addr)

L2_INDEX(addr)

L3_INDEX(addr)

Exception Handling

EL2 exception vector table, context save/restore, and handler stubs.

group Exception Handling

EL2 exception vector table, context save/restore, and handler stubs.

Hypercalls

AArch64 HVC dispatch for lower-EL guest exits. The guest-provided SMCCC function ID is read from x0; supported standard-service calls are currently handled as PSCI requests.

Enums

enum class HvcResult : uint64_t

Result returned after dispatching a guest HVC call.

Values:

enumerator Handled

The call was handled and the guest can resume.

enumerator Unhandled

The call was recognized as an HVC exit but is not implemented.

enumerator Halt

The guest requested shutdown, such as PSCI SYSTEM_OFF.

enumerator Reset

The guest requested reset, such as PSCI SYSTEM_RESET.

Typedefs

using ExceptionContext = hv::array<uint64_t, 31>

Functions

HvcResult handleHvcAarch64(ExceptionContext &gpr)

Dispatch an AArch64 HVC call from the guest register context.

The function ID is read from x0 in the saved general-purpose register array. Supported standard-service calls are routed to the local PSCI handler; unsupported owners return HvcResult::Unhandled.

Parameters:

gpr – Saved guest registers x0-x30. Return values are written back into this array using the SMCCC register convention.

Returns:

Dispatch status describing whether the guest can resume or must stop.

SMCCC

Function-ID field definitions, Owner Entity Numbers, standard return codes, and small helpers used by HVC dispatch.

namespace SMCCC

SMCCC function-ID fields, owner numbers, return codes, and helpers.

Functions

constexpr uint32_t getOwner(uint64_t funcId)

Extract the Owner Entity Number from an SMCCC function ID.

Parameters:

funcId – Raw SMCCC function ID from x0.

Returns:

Owner Entity Number field.

constexpr bool isFastCall(uint64_t funcId)

Check whether an SMCCC function ID uses the fast-call type.

Parameters:

funcId – Raw SMCCC function ID from x0.

Returns:

true when the call type is SMCCC::TYPE_FAST.

Variables

constexpr uint32_t OEN_SHIFT = 24

OEN field start bit in an SMCCC function ID.

constexpr uint32_t OEN_MASK = 0x3F

OEN field mask after shifting.

constexpr uint32_t TYPE_SHIFT = 31

Call-type field start bit in an SMCCC function ID.

constexpr uint32_t TYPE_MASK = 0x1

Call-type field mask after shifting.

constexpr uint32_t TYPE_YIELDING = 0

Yielding call type.

constexpr uint32_t TYPE_FAST = 1

Fast call type.

constexpr uint32_t OWNER_ARCH = 0

Architecture service owner number.

constexpr uint32_t OWNER_CPU = 1

CPU service owner number.

constexpr uint32_t OWNER_SIP = 2

Silicon Partner service owner number.

constexpr uint32_t OWNER_OEM = 3

OEM service owner number.

constexpr uint32_t OWNER_STANDARD = 4

Standard service owner number, used here for PSCI.

constexpr uint32_t OWNER_STANDARD_HYP = 5

Standard hypervisor service owner number.

constexpr uint32_t OWNER_VENDOR_HYP = 6

Vendor hypervisor service owner number.

constexpr uint32_t OWNER_TRUSTED_APP = 48

Trusted Application service owner number.

constexpr uint32_t OWNER_TRUSTED_OS = 50

Trusted OS service owner number.

constexpr int32_t SUCCESS = 0

SMCCC success return code.

constexpr int32_t NOT_SUPPORTED = -1

SMCCC unsupported-function return code.

constexpr int32_t NOT_REQUIRED = -2

SMCCC not-required return code.

constexpr int32_t INVALID_PARAMETER = -3

SMCCC invalid-parameter return code.

Virtualization

vCPU

Guest CPU context, EL1 register save/restore helpers, and guest entry glue.

group Virtual CPU

Guest CPU context, EL1 register save/restore, and guest entry glue.

struct El2State

#include <vcpu.h>

EL2 exception-return state: elr_el2, spsr_el2.

struct El1SysRegs

#include <vcpu.h>

EL1 system register context (SCTLR_EL1, TTBRn_EL1, etc).

class Vcpu

#include <vcpu.h>

Per-guest virtual CPU context.

Layout-critical: the first three sub-structs are indexed from vcpu.S via the VCPU_*_OFFSET constants above. Fields below the “asm contract line” comment are free to reorder.

Layout-critical data is public so low-level trap routing can pass register state directly to dispatch modules without copying. Keep all data members in this single access group to preserve standard-layout.

Public Functions

void init(uint64_t entrypoint)

Initialise this vCPU for first entry into EL1.

Zeroes all state, then seeds:

• elr_el2 ← entrypoint

• spsr_el2 ← EL1h with all DAIF bits masked

• sctlr_el1 ← hardware reset value with M/C/I/A/SA cleared

Parameters:

entrypoint – Guest physical address to resume at on first eret.

void saveEl1SysRegs()

Save EL1 system registers from hardware into this context.

Note

Call site must have DAIF masked. Meaningful only on AArch64.

void restoreEl1SysRegs()

Restore EL1 system registers from this context into hardware.

Note

SCTLR_EL1 is restored last, after TTBR/TCR/MAIR, with an intervening isb. Call site must have DAIF masked.

uint64_t getElr() const noexcept

Return the saved guest PC (ELR_EL2).

void setPc(uint64_t pc)

Overwrite the saved guest PC (ELR_EL2).

void skipInstruction()

Advance ELR_EL2 by 4 bytes (skip faulting instruction).

void setGuestSp(uint64_t sp)

Set the guest SP_EL1 (stack pointer seen by the guest at EL1).

uint64_t getGpReg(uint64_t off) const noexcept

Read a saved GPR by offset.

Parameters:

off – One of the VCPU_GPREG_* constants.

void setGpReg(uint64_t off, uint64_t val)

Write a saved GPR by offset.

Parameters:

• off – One of the VCPU_GPREG_* constants.

• val – Value to store.

inline uint32_t getId() const noexcept

Opaque vCPU identifier assigned by the scheduler.

inline void setId(uint32_t vcpuId)

Set the vCPU identifier (scheduler-only).

Public Static Functions

static Vcpu *getCurrentVcpu()

Return the Vcpu pointer parked in TPIDR_EL2 on this pCPU.

Note

Returns nullptr on hosted (non-AArch64) builds.

static void scheduleNext()

Stub scheduler entry.

Replaced by real scheduler later.

VM

Per-guest container that owns one stage-2 MMU context and one guest vCPU.

class Vm

Public Functions

void init(const char *name, uint64_t ipaBase, uint64_t guestRamHostPa, uint64_t sizeBytes, uint8_t vmid, uint64_t guestEntry, uint64_t guestDtb)

Build this VM’s stage-2 mappings and seed its vCPU.

Order is significant: stage-2 tables are constructed first so they are in place before the vCPU’s first entry. VTTBR_EL2 / HCR_EL2.VM are committed in run(), after vCPU state is seeded.

Parameters:

• name – Guest kernel or VM name retained for diagnostics.

• ipaBase – Guest IPA base.

• guestRamHostPa – Host physical base backing guest RAM.

• sizeBytes – Size of the guest RAM region.

• vmid – Non-zero VMID (unique across live VMs).

• guestEntry – Guest IPA at which to resume on first eret.

• guestDtb – Guest IPA of the Linux device tree blob.

void run()

Enable stage-2 and enter the guest.

Note

Does not return; the guest runs forever or traps back via the exception path, which is owned by vcpu.S / exceptions.S.

const char *getName() const noexcept

Return the guest kernel name passed to init().

uint8_t getVmId() const noexcept

Return the guest vm ID passed to init().

Drivers

Uart

PL011 UART driver for early debug output. Supports QEMU virt and physical Raspberry Pi 5 targets via a compile-time base address.

group Uart

PL011 UART driver for early debug output.

Supports both the QEMU virt machine and physical Raspberry Pi 5 hardware, with the UART base selected from the active BSP definition at compile time.

Enums

enum class UART_REG : uint8_t

PL011 register offsets from b::UART_BASE.

Values:

enumerator DR

enumerator FR

enumerator IBRD

enumerator FBRD

enumerator LCRH

enumerator CR

enumerator ICR

Variables

constexpr char hex[] = "0123456789ABCDEF"

Uppercase hexadecimal digit lookup table used by writeHex().

class Uart

#include <uart.h>

Static PL011 UART driver for early serial I/O.

Public Static Functions

static void init()

Initialize the PL011 UART.

Note

Must be called before print().

static void println(const char *str)

Transmit a null-terminated string.

Note

Each character is sent via putc(), which spins on the TX FIFO. For large strings this blocks proportionally.

Parameters:

str – Pointer to the null-terminated string to send.

static void print(const char *str)

Transmit a null-terminated string.

Note

Each character is sent via putc(), which spins on the TX FIFO. For large strings this blocks proportionally.

Parameters:

str – Pointer to the null-terminated string to send.

static void putc(const char ch)

Transmit a single character over the UART.

Warning

Busy-waits until the TX FIFO has space. Do not call from an interrupt context or time-critical path.

Parameters:

ch – Character to send.

static void writeHex(uint64_t val)

Write a 64-bit value as a 16-digit hexadecimal string.

Note

Always emits exactly 16 hex digits (zero-padded). Does not print a “0x” prefix &#8212; callers must add it themselves.

Parameters:

val – The value to print.

Gic

ARM GICv2 Distributor and CPU Interface driver.

group Gic

ARM GICv2 Distributor and CPU Interface driver.

class Gic

#include <gic.h>

GICv2 Distributor and CPU Interface access helpers.

Public Static Functions

static void init()

Initialize the GICD and GICC.

Note

Must be called once before any interrupt management.

static void enableIrq(uint32_t id)

Enable a physical interrupt at the Distributor.

Parameters:

id – GIC interrupt ID (SPI, PPI, or SGI).

static void disableIrq(uint32_t id)

Disable a physical interrupt at the Distributor.

Parameters:

id – GIC interrupt ID.

static IrqAck ackIrq()

Acknowledge the highest-priority pending interrupt via GICC_IAR.

Returns:

Acknowledgement token plus decoded interrupt ID.

static void endIrq(IrqAck irq)

Signal end-of-interrupt by writing GICC_EOIR.

Parameters:

irq – Acknowledgement token returned by ackIrq().

static int injectIrq(uint32_t virtId, uint32_t id)

Inject a virtual interrupt into a guest via a GICH List Register.

Parameters:

• virtId – Virtual interrupt ID to present to the guest.

• id – Physical interrupt ID backing the virtual interrupt.

Returns:

0 on success, -1 if no free List Register is available.

static bool hasPendingIrq()

Check whether any virtual interrupt is pending in the GICH.

Returns:

true if at least one virtual interrupt is pending.

static void enableMainIrq(bool isEnable)

Enable or disable the CPU Interface via GICC_CTLR.

Parameters:

isEnable – true to enable, false to disable.

static void setPriorityLevel(uint32_t id, uint8_t priority)

Set the priority level for a physical interrupt.

Parameters:

• id – GIC interrupt ID to configure.

• priority – Priority value (0 = highest, 255 = lowest).

static void cpuReset()

Reset the GICC to its power-on state for this CPU.

struct IrqAck

#include <gic.h>

HV Library

Freestanding C++ utility headers with no standard library dependency.

Panic

Fatal exception reporting for unrecoverable EL2 errors.

hv_panic() prints an error message, emits a full exception register dump, and halts the current CPU indefinitely.

Functions

void hv_panic(const char *msg)

Memory Primitives

Freestanding C memory helpers used when no hosted libc is available, including memcpy() and memset().

memcpy() copies n bytes from src to dest and returns dest.

memset() fills n bytes at dest with the low byte of c and returns dest.

Array

Freestanding fixed-size container used in exception context state.

template<typename T, size_t N>
struct array

Fixed-size aggregate array with STL-compatible interface.

Note

This is an aggregate &#8212; it has no user-declared constructors, so brace initialization and zero-initialization work as expected.

Template Parameters:

• T – Element type.

• N – Number of elements (compile-time constant).

Public Functions

inline constexpr reference operator[](size_type i)

Access element at index i (no bounds checking).

inline constexpr reference front()

Return reference to the first element.

inline constexpr reference back()

Return reference to the last element.

inline constexpr pointer data()

Return pointer to contiguous underlying storage.

inline constexpr size_type size() const

Return the number of elements.

inline constexpr size_type max_size() const

Return the maximum number of elements (same as size).

inline constexpr bool empty() const

Return true when N is zero.

inline constexpr iterator begin()

Return iterator to the first element.

inline constexpr const_iterator cbegin() const

Return const iterator to the first element.

inline constexpr iterator end()

Return iterator one past the last element.

inline constexpr const_iterator cend() const

Return const iterator one past the last element.

inline constexpr void fill(const T &value)

Assign value to every element in the array.

Public Members

T m_data[N]

Raw storage for N elements of type T.

registerDump()

Prints a full exception-state register dump to UART for diagnostics.

Human-readable register dump for exception diagnostics.

BSP

Compile-time board constants selected by the active target. This is a top-level hardware description group, not part of the freestanding helper library.

Selection Wrapper

bsp.h picks exactly one board definition based on the build: BSP_QEMU, BSP_RPI5, or BSP_FVP.

QEMU virt

Base addresses exposed today:

• b::UART_BASE = 0x09000000

• b::GIC_DISTRIBUTOR_BASE = 0x08000000

• b::GIC_CPU_BASE = 0x08010000

• b::GIC_HV_BASE = 0x08030000

• b::GIC_VCPU_BASE = 0x08040000

• b::HV_MMIO_BASE = 0x08000000

• b::HV_MMIO_SIZE = 0x38000000

Raspberry Pi 5

Base addresses exposed today:

• b::UART_BASE = 0x107D001000

• b::GIC_DISTRIBUTOR_BASE = 0x107fff9000

• b::GIC_CPU_BASE = 0x107fffa000

• b::GIC_HV_BASE = 0x107fffc000

• b::GIC_VCPU_BASE = 0x107fffe000

• b::HV_MMIO_BASE = 0x107D000000

• b::HV_MMIO_SIZE = 0x200000000

Arm FVP Base RevC

Base addresses exposed today:

• b::HOST_DTB_BASE = 0x88000000

• b::UART_BASE = 0x1C090000

• b::GIC_DISTRIBUTOR_BASE = 0x2F000000

• b::GIC_CPU_BASE = 0x2C000000

• b::GIC_HV_BASE = 0x2C010000

• b::GIC_VCPU_BASE = 0x2C02F000

• b::HV_MMIO_BASE = 0x2F000000

• b::HV_MMIO_SIZE = 0x00200000

• b::PLATFORM_MMIO_BASE = 0x1C000000

• b::PLATFORM_MMIO_SIZE = 0x00200000

• b::GIC_ITS_MMIO_BASE = 0x2F200000

• b::GIC_ITS_MMIO_SIZE = 0x00200000