hvisor Hardware Adaptation Development Manual 🧑🏻‍💻

wheatfox (wheatfox17@icloud.com) 2025.3.17

Design Principles

1. Code and board configuration separation: No platform_xxx related cfg should appear inside src of hvisor itself.
2. Platform independence: Introduce the previous hvisor-deploy architecture, orderly store information about various architectures and boards in the platform directory.
3. Board directory index:
   • Uniformly use platform/$ARCH/$BOARD as the dedicated directory for the board.
   • Each board's unique BID (Board ID) adopts the ARCH/BOARD format, such as aarch64/qemu-gicv3.
4. Simplified compilation: Support using BID=xxx/xxx to directly specify the board, while also compatible with ARCH=xxx BOARD=xxx style.
5. Structured configuration: Each board directory contains the following files:
   • linker.ld - Link script
   • platform.mk - QEMU startup Makefile and hvisor.bin handling
   • board.rs - Board definition Rust code
   • configs/ - JSON configurations for hvisor-tool startup zones
   • cargo/
     • features - Specific cargo features corresponding to the board, including drivers, functions, etc.
     • config.template.toml - Template for .cargo/config, maintained by each board
   • test/ - (Optional) QEMU related test code, including unit tests, system tests, etc.
   • image/ - Startup file directory, containing multiple subdirectories:
     • bootloader/ - (Optional) Used for local QEMU operation and unittest/systemtest testing
     • dts/ - (Optional) Device tree source files for zones 0, 1, 2, …
     • its/ - (Optional) Used for generating U-Boot FIT image (hvisor aarch64 zcu102)
     • acpi/ - (Optional) ACPI device tree source code for x86 platform (hvisor x86_64)
     • kernel/ - (Optional) Kernel Image suitable for the target platform
     • virtdisk/ - (Optional) Virtual disk files, such as rootfs, etc.

Code Implementation Details

Auto-generate .cargo/config.toml

• Generated by tools/gen_cargo_config.sh, ensuring dynamic updates to the linker.ld configuration.
• config.template.toml uses placeholders like __ARCH__, __BOARD__, replaced by gen_cargo_config.sh to generate .cargo/config.toml.

build.rs Automatically Symlink board.rs

• build.rs is responsible for symlinking platform/$ARCH/$BOARD/board.rs to src/platform/__board.rs.
• Avoids Makefile handling, triggered only when env variables change, reducing unnecessary full recompilations.

Select drivers through Cargo features

• Avoid platform_xxx directly appearing in src/, switch to configuration based on features.
• cargo/features uniformly stores configurations of board drivers, functions, etc.

Overview of features Corresponding to Each Board

Development and Compilation Guide

Compile Different Boards

make ARCH=aarch64 BOARD=qemu-gicv3
make BID=aarch64/qemu-gicv3  # Use BID shorthand
make BID=aarch64/imx8mp
make BID=loongarch64/ls3a5000
make BID=x86_64/qemu

Adapt New Boards

1. Determine features: Refer to existing features for classification, add required drivers and configurations.
2. Create platform/$ARCH/$BOARD directory:
   • Add linker.ld, board.rs, features, etc.
3. Compile Test:

make BID=xxx/new_board

features Design Principles

• Minimize hierarchy:
  • For example, cpu-a72 instead of board_xxx, to facilitate reuse across multiple boards.
• Clear driver/function classification:
  • irqchip (gicv3, plic, ...)
  • uart (pl011, imx_uart, ...)
  • iommu, pci, pt_layout_xxx, ...