Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 1 | # Code structure |
| 2 | |
| 3 | The Hafnium repository contains Hafnium itself, along with unit tests and |
| 4 | integration tests, a small client library for VMs, a Linux kernel module for the |
| 5 | primary VM, prebuilt binaries of tools needed for building it and running tests. |
| 6 | Everything is built with [GN](https://gn.googlesource.com/gn/). |
| 7 | |
| 8 | Hafnium 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 | |
| 13 | And 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 | |
| 19 | Each platform has a single associated architecture. |
| 20 | |
| 21 | The source tree is organised as follows: |
| 22 | |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 23 | * `build`: Common GN configuration, build scripts, and linker |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 24 | script. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 25 | * `docs`: Documentation |
| 26 | * `driver/linux`: Linux kernel driver for Hafnium, for use |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 27 | in the primary VM. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 28 | * `inc`: Header files... |
| 29 | * `hf`: ... internal to Hafnium |
| 30 | * `arch`: Architecture-dependent modules, which have |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 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. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 34 | * `plat`: Platform-dependent modules, which have a |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 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. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 38 | * `system`: ... which are included by the `stdatomic.h` |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 39 | which we use from Android Clang but not really needed, so we use dummy |
| 40 | empty versions. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 41 | * `vmapi/hf`: ... for the interface exposed to VMs. |
| 42 | * `kokoro`: Scripts and configuration for continuous integration |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 43 | and presubmit checks. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 44 | * `prebuilts`: Prebuilt binaries needed for building Hafnium |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 45 | or running tests. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 46 | * `project`: Configuration and extra code for each **project**. |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 47 | A project is a set of one or more _platforms_ (see above) that are built |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 48 | together. Hafnium comes with the `reference` project |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 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. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 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 |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 58 | run on a real architecture. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 59 | * `hftest`: A simple test framework that supports |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 60 | running tests standalone on bare metal, in VMs under Hafnium, or as |
| 61 | user-space binaries under Linux under Hafnium. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 62 | * `linux`: Tests which are run in a Linux VM under |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 63 | Hafnium. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 64 | * `vmapi`: Tests which are run in minimal test VMs under |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 65 | Hafnium. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 66 | * `arch`: Tests which are rely on specific |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 67 | architectural details such as the GIC version. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 68 | * `primary_only`: Tests which run only a |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 69 | single (primary) VM. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 70 | * `primary_with_secondaries`: |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 71 | Test which run with a primary VM and one or more secondary VMs to |
| 72 | test how they interact. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 73 | * `third_party`: Third party code needed for building |
Andrew Walbran | 32731a6 | 2019-11-13 18:04:31 +0000 | [diff] [blame] | 74 | Hafnium. |
Olivier Deprez | 7012881 | 2023-05-22 12:12:03 +0200 | [diff] [blame] | 75 | * `vmlib`: A small client library for VMs running under Hafnium. |