1# 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
23*   `build`: Common GN configuration, build scripts, and linker
24    script.
25*   `docs`: Documentation
26*   `driver/linux`: Linux kernel driver for Hafnium, for use
27    in the primary VM.
28*   `inc`: Header files...
29    *   `hf`: ... internal to Hafnium
30        *   `arch`: Architecture-dependent modules, which have
31            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.
34        *   `plat`: Platform-dependent modules, which have a
35            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.
38    *   `system`: ... which are included by the `stdatomic.h`
39        which we use from Android Clang but not really needed, so we use dummy
40        empty versions.
41    *   `vmapi/hf`: ... for the interface exposed to VMs.
42*   `kokoro`: Scripts and configuration for continuous integration
43    and presubmit checks.
44*   `prebuilts`: Prebuilt binaries needed for building Hafnium
45    or running tests.
46*   `project`: Configuration and extra code for each **project**.
47    A project is a set of one or more _platforms_ (see above) that are built
48    together. Hafnium comes with the `reference` project
49    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.
53*   `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
58        run on a real architecture.
59    *   `hftest`: A simple test framework that supports
60        running tests standalone on bare metal, in VMs under Hafnium, or as
61        user-space binaries under Linux under Hafnium.
62    *   `linux`: Tests which are run in a Linux VM under
63        Hafnium.
64    *   `vmapi`: Tests which are run in minimal test VMs under
65        Hafnium.
66        *   `arch`: Tests which are rely on specific
67            architectural details such as the GIC version.
68        *   `primary_only`: Tests which run only a
69            single (primary) VM.
70        *   `primary_with_secondaries`:
71            Test which run with a primary VM and one or more secondary VMs to
72            test how they interact.
73*   `third_party`: Third party code needed for building
74    Hafnium.
75*   `vmlib`: A small client library for VMs running under Hafnium.
76