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    ├── inc
19    │   ├── hf
20    │   │   ├── arch
21    │   │   ├── plat
22    │   │   └── ffa
23    │   └── vmapi
24    │       └── hf
25    ├── kokoro
26    ├── prebuilts
27    ├── project
28    ├── src
29    │   ├── arch
30    │   └── ffa
31    ├── test
32    │   ├── arch
33    │   ├── hftest
34    │   ├── inc
35    │   ├── linux
36    │   └── vmapi
37    ├── third_party
38    ├── tools
39    ├── vmlib
40    └── out
41
42- `build`: Common GN configuration, build scripts, and linker script.
43
44- `docs`: Documentation.
45
46- `driver/linux`: Linux kernel driver for Hafnium as the hypervisor, in the primary VM (More
47  details see legacy :ref:`Hypervisor` documentation).
48
49- `inc`: Header files.
50
51   - `hf`: internal to Hafnium.
52
53      - `arch`: Architecture-dependent modules, which have a common interface
54        but separate implementations per architecture. This includes details
55        of CPU initialisation, exception handling, timers, page table management,
56        and other system registers.
57
58      - `plat`: Platform-dependent modules, which have a common interface but
59        separate implementations per platform. This includes details of the boot
60        flow, and a UART driver for the debug log console.
61
62      - `ffa`: Interface for FF-A features.
63
64   - `vmapi/hf`: for the interface exposed to partitions.
65
66- `kokoro`: Scripts and configuration for continuous integration and presubmit checks.
67
68- `prebuilts`: Prebuilt binaries needed for building Hafnium or running tests.
69
70- `project`: Configuration and extra code for each project.
71  A project is a set of one or more platforms (see above) that are built
72  together. Hafnium comes with the `reference` project
73  for running it on some common emulators and development boards. To port
74  Hafnium to a new board, you can create a new project under this directory
75  with the platform or platforms you want to add, without affecting the core
76  Hafnium code.
77
78- `src`: Source code for Hafnium itself in C and assembly, and unit tests in C++.
79
80  - `arch`: Implementation of architecture-dependent modules.
81
82  - `ffa`: Abstraction over SPMC/hypervisor specific implementation details of FF-A features.
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   - `vmapi`: Tests which are run in minimal test partitions under Hafnium.
93
94      - `arch`: Tests which are rely on specific architectural details such as the GIC version.
95
96      - `primary_only`: Tests which run only a single (primary) partition.
97
98      - `primary_with_secondaries`: Test which run with a primary partition and one
99        or more secondary partitions to test how they interact.
100
101- `third_party`: Third party code needed for building Hafnium.
102
103- `vmlib`: A small client library for partitions running under Hafnium.
104
105- `out`: Output directory for the build artifacts.
106
107--------------
108
109*Copyright (c) 2023, Arm Limited. All rights reserved.*
110
111.. _gn: https://gn.googlesource.com/gn/
112