blob: 130f3e1202996d029480076d8f09414721dae0f2 [file] [log] [blame] [view]
Andrew Walbran32731a62019-11-13 18:04:31 +00001# Code structure
2
3The Hafnium repository contains Hafnium itself, along with unit tests and
4integration tests, a small client library for VMs, a Linux kernel module for the
5primary VM, prebuilt binaries of tools needed for building it and running tests.
6Everything is built with [GN](https://gn.googlesource.com/gn/).
7
8Hafnium can be built for an **architecture**, currently including:
9
10* `aarch64`: 64-bit Armv8
11* `fake`: A dummy architecture used for running unit tests on the host system.
12
13And for a **platform**, such as:
14
15* `aem_v8a_fvp`: The Arm [Fixed Virtual Platform](FVP.md) emulator.
16* `qemu_aarch64`: QEMU emulating an AArch64 device.
17* `rpi4`: A Raspberry Pi 4 board.
18
19Each platform has a single associated architecture.
20
21The source tree is organised as follows:
22
Olivier Deprez70128812023-05-22 12:12:03 +020023* `build`: Common GN configuration, build scripts, and linker
Andrew Walbran32731a62019-11-13 18:04:31 +000024 script.
Olivier Deprez70128812023-05-22 12:12:03 +020025* `docs`: Documentation
26* `driver/linux`: Linux kernel driver for Hafnium, for use
Andrew Walbran32731a62019-11-13 18:04:31 +000027 in the primary VM.
Olivier Deprez70128812023-05-22 12:12:03 +020028* `inc`: Header files...
29 * `hf`: ... internal to Hafnium
30 * `arch`: Architecture-dependent modules, which have
Andrew Walbran32731a62019-11-13 18:04:31 +000031 a common interface but separate implementations per architecture.
32 This includes details of CPU initialisation, exception handling,
33 timers, page table management, and other system registers.
Olivier Deprez70128812023-05-22 12:12:03 +020034 * `plat`: Platform-dependent modules, which have a
Andrew Walbran32731a62019-11-13 18:04:31 +000035 common interface but separate implementations per platform. This
36 includes details of the boot flow, and a UART driver for the debug
37 log console.
Olivier Deprez70128812023-05-22 12:12:03 +020038 * `system`: ... which are included by the `stdatomic.h`
Andrew Walbran32731a62019-11-13 18:04:31 +000039 which we use from Android Clang but not really needed, so we use dummy
40 empty versions.
Olivier Deprez70128812023-05-22 12:12:03 +020041 * `vmapi/hf`: ... for the interface exposed to VMs.
42* `kokoro`: Scripts and configuration for continuous integration
Andrew Walbran32731a62019-11-13 18:04:31 +000043 and presubmit checks.
Olivier Deprez70128812023-05-22 12:12:03 +020044* `prebuilts`: Prebuilt binaries needed for building Hafnium
Andrew Walbran32731a62019-11-13 18:04:31 +000045 or running tests.
Olivier Deprez70128812023-05-22 12:12:03 +020046* `project`: Configuration and extra code for each **project**.
Andrew Walbran32731a62019-11-13 18:04:31 +000047 A project is a set of one or more _platforms_ (see above) that are built
Olivier Deprez70128812023-05-22 12:12:03 +020048 together. Hafnium comes with the `reference` project
Andrew Walbran32731a62019-11-13 18:04:31 +000049 for running it on some common emulators and development boards. To port
50 Hafnium to a new board, you can create a new project under this directory
51 with the platform or platforms you want to add, without affecting the core
52 Hafnium code.
Olivier Deprez70128812023-05-22 12:12:03 +020053* `src`: Source code for Hafnium itself in C and assembly, and
54 unit tests in C++.
55 * `arch`: Implementation of architecture-dependent modules.
56* `test`: Integration tests
57 * `arch`: Tests for components of Hafnium that need to be
Andrew Walbran32731a62019-11-13 18:04:31 +000058 run on a real architecture.
Olivier Deprez70128812023-05-22 12:12:03 +020059 * `hftest`: A simple test framework that supports
Andrew Walbran32731a62019-11-13 18:04:31 +000060 running tests standalone on bare metal, in VMs under Hafnium, or as
61 user-space binaries under Linux under Hafnium.
Olivier Deprez70128812023-05-22 12:12:03 +020062 * `linux`: Tests which are run in a Linux VM under
Andrew Walbran32731a62019-11-13 18:04:31 +000063 Hafnium.
Olivier Deprez70128812023-05-22 12:12:03 +020064 * `vmapi`: Tests which are run in minimal test VMs under
Andrew Walbran32731a62019-11-13 18:04:31 +000065 Hafnium.
Olivier Deprez70128812023-05-22 12:12:03 +020066 * `arch`: Tests which are rely on specific
Andrew Walbran32731a62019-11-13 18:04:31 +000067 architectural details such as the GIC version.
Olivier Deprez70128812023-05-22 12:12:03 +020068 * `primary_only`: Tests which run only a
Andrew Walbran32731a62019-11-13 18:04:31 +000069 single (primary) VM.
Olivier Deprez70128812023-05-22 12:12:03 +020070 * `primary_with_secondaries`:
Andrew Walbran32731a62019-11-13 18:04:31 +000071 Test which run with a primary VM and one or more secondary VMs to
72 test how they interact.
Olivier Deprez70128812023-05-22 12:12:03 +020073* `third_party`: Third party code needed for building
Andrew Walbran32731a62019-11-13 18:04:31 +000074 Hafnium.
Olivier Deprez70128812023-05-22 12:12:03 +020075* `vmlib`: A small client library for VMs running under Hafnium.