Hafnium

Code structure

The Hafnium repository contains Hafnium itself, along with unit tests and integration tests, a small client library for VMs, a Linux kernel module for the primary VM, prebuilt binaries of tools needed for building it and running tests. Everything is built with GN.

Hafnium can be built for an architecture, currently including:

  • aarch64: 64-bit Armv8
  • fake: A dummy architecture used for running unit tests on the host system.

And for a platform, such as:

  • aem_v8a_fvp: The Arm Fixed Virtual Platform emulator.
  • qemu_aarch64: QEMU emulating an AArch64 device.
  • rpi4: A Raspberry Pi 4 board.

Each platform has a single associated architecture.

The source tree is organised as follows:

  • build: Common GN configuration, build scripts, and linker script.
  • docs: Documentation
  • driver/linux: Linux kernel driver for Hafnium, for use in the primary VM.
  • inc: Header files...
    • hf: ... internal to Hafnium
      • arch: Architecture-dependent modules, which have a common interface but separate implementations per architecture. This includes details of CPU initialisation, exception handling, timers, page table management, and other system registers.
      • plat: Platform-dependent modules, which have a common interface but separate implementations per platform. This includes details of the boot flow, and a UART driver for the debug log console.
    • system: ... which are included by the stdatomic.h which we use from Android Clang but not really needed, so we use dummy empty versions.
    • vmapi/hf: ... for the interface exposed to VMs.
  • kokoro: Scripts and configuration for continuous integration and presubmit checks.
  • prebuilts: Prebuilt binaries needed for building Hafnium or running tests.
  • project: Configuration and extra code for each project. A project is a set of one or more platforms (see above) that are built together. Hafnium comes with the reference project for running it on some common emulators and development boards. To port Hafnium to a new board, you can create a new project under this directory with the platform or platforms you want to add, without affecting the core Hafnium code.
  • src: Source code for Hafnium itself in C and assembly, and unit tests in C++.
    • arch: Implementation of architecture-dependent modules.
  • test: Integration tests
    • arch: Tests for components of Hafnium that need to be run on a real architecture.
    • hftest: A simple test framework that supports running tests standalone on bare metal, in VMs under Hafnium, or as user-space binaries under Linux under Hafnium.
    • linux: Tests which are run in a Linux VM under Hafnium.
    • vmapi: Tests which are run in minimal test VMs under Hafnium.
      • arch: Tests which are rely on specific architectural details such as the GIC version.
      • primary_only: Tests which run only a single (primary) VM.
      • primary_with_secondaries: Test which run with a primary VM and one or more secondary VMs to test how they interact.
  • third_party: Third party code needed for building Hafnium.
  • vmlib: A small client library for VMs running under Hafnium.