1Project Structure
2=================
3
4The Hafnium repository contains Hafnium source code, along with testing code related to integration
5tests, and unit tests.
6To aid with the integration tests, the repository also contains a small client library
7for partitions and prebuilt binaries of tools needed for the  build and running the tests.
8The build system is supported by `gn`_.
9
10Each platform has a single associated architecture.
11
12The source tree is organised as follows:
13
14::
15
16    ├── build
17    ├── docs
18    ├── driver
19    │   └── linux
20    ├── inc
21    │   ├── hf
22    │   │   ├── arch
23    │   │   └── plat
24    │   ├── system
25    │   └── vmapi
26    │       └── hf
27    ├── kokoro
28    ├── prebuilts
29    ├── project
30    ├── src
31    │   ├── arch
32    ├── test
33    │   ├── arch
34    │   ├── hftest
35    │   ├── inc
36    │   ├── linux
37    │   └── vmapi
38    ├── third_party
39    ├── tools
40    ├── vmlib
41    └── out
42
43- `build`: Common GN configuration, build scripts, and linker script.
44
45- `docs`: Documentation.
46
47- `driver/linux`: Linux kernel driver for Hafnium as the hypervisor, in the primary VM (More
48  details see legacy :ref:`Hypervisor` documentation).
49
50- `inc`: Header files.
51
52   - `hf`: internal to Hafnium.
53
54      - `arch`: Architecture-dependent modules, which have a common interface
55        but separate implementations per architecture. This includes details
56        of CPU initialisation, exception handling, timers, page table management,
57        and other system registers.
58
59      - `plat`: Platform-dependent modules, which have a common interface but
60        separate implementations per platform. This includes details of the boot
61        flow, and a UART driver for the debug log console.
62
63   - `system`: which are included by the `stdatomic.h` which we use from
64     Android Clang but not really needed, so we use dummy empty versions.
65
66   - `vmapi/hf`: for the interface exposed to partitions.
67
68- `kokoro`: Scripts and configuration for continuous integration and presubmit checks.
69
70- `prebuilts`: Prebuilt binaries needed for building Hafnium or running tests.
71
72- `project`: Configuration and extra code for each project.
73  A project is a set of one or more platforms (see above) that are built
74  together. Hafnium comes with the `reference` project
75  for running it on some common emulators and development boards. To port
76  Hafnium to a new board, you can create a new project under this directory
77  with the platform or platforms you want to add, without affecting the core
78  Hafnium code.
79
80- `src`: Source code for Hafnium itself in C and assembly, and unit tests in C++.
81
82  - `arch`: Implementation of architecture-dependent modules.
83
84- `test`: Integration tests
85
86   - `arch`: Tests for components of Hafnium that need to be run on a real architecture.
87
88   - `hftest`: A simple test framework that supports running tests standalone on bare
89     metal, in partitions under Hafnium. Also as user-space binaries under Linux, but these are
90     not yet integrated with system where Hafnium is the SPMC.
91
92   - `linux`: Tests which are run in a Linux partition under Hafnium as normal world hypervisor.
93
94   - `vmapi`: Tests which are run in minimal test partitions under Hafnium.
95
96      - `arch`: Tests which are rely on specific architectural details such as the GIC version.
97
98      - `primary_only`: Tests which run only a single (primary) partition.
99
100      - `primary_with_secondaries`: Test which run with a primary partition and one
101        or more secondary partitions to test how they interact.
102
103- `third_party`: Third party code needed for building Hafnium.
104
105- `vmlib`: A small client library for partitions running under Hafnium.
106
107- `out`: Output directory for the build artifacts.
108
109--------------
110
111*Copyright (c) 2023, Arm Limited. All rights reserved.*
112
113.. _gn: https://gn.googlesource.com/gn/
114