Document Hafnium architecture and code structure.
Bug: 123318812
Change-Id: If78d6c2ff4ab95f8dbbe5ce38c727b45ec201a03
diff --git a/docs/CodeStructure.md b/docs/CodeStructure.md
new file mode 100644
index 0000000..b3fa8d6
--- /dev/null
+++ b/docs/CodeStructure.md
@@ -0,0 +1,75 @@
+# Code structure
+
+The Hafnium repository contains Hafnium itself, along with unit tests and
+integration tests, a small client library for VMs, a Linux kernel module for the
+primary VM, prebuilt binaries of tools needed for building it and running tests.
+Everything is built with [GN](https://gn.googlesource.com/gn/).
+
+Hafnium can be built for an **architecture**, currently including:
+
+* `aarch64`: 64-bit Armv8
+* `fake`: A dummy architecture used for running unit tests on the host system.
+
+And for a **platform**, such as:
+
+* `aem_v8a_fvp`: The Arm [Fixed Virtual Platform](FVP.md) emulator.
+* `qemu_aarch64`: QEMU emulating an AArch64 device.
+* `rpi4`: A Raspberry Pi 4 board.
+
+Each platform has a single associated architecture.
+
+The source tree is organised as follows:
+
+* [`build`](../build): Common GN configuration, build scripts, and linker
+ script.
+* [`docs`](.): Documentation
+* [`driver/linux`](../driver/linux): Linux kernel driver for Hafnium, for use
+ in the primary VM.
+* [`inc`](../inc): Header files...
+ * [`hf`](../inc/hf): ... internal to Hafnium
+ * [`arch`](../inc/hf/arch): Architecture-dependent modules, which have
+ a common interface but separate implementations per architecture.
+ This includes details of CPU initialisation, exception handling,
+ timers, page table management, and other system registers.
+ * [`plat`](../inc/hf/plat): Platform-dependent modules, which have a
+ common interface but separate implementations per platform. This
+ includes details of the boot flow, and a UART driver for the debug
+ log console.
+ * [`system`](../inc/system): ... which are included by the `stdatomic.h`
+ which we use from Android Clang but not really needed, so we use dummy
+ empty versions.
+ * [`vmapi/hf`](../inc/vmapi/hf): ... for the interface exposed to VMs.
+* [`kokoro`](../kokoro): Scripts and configuration for continuous integration
+ and presubmit checks.
+* [`prebuilts`](../prebuilts): Prebuilt binaries needed for building Hafnium
+ or running tests.
+* [`project`](../project): Configuration and extra code for each **project**.
+ A project is a set of one or more _platforms_ (see above) that are built
+ together. Hafnium comes with the [`reference`](../project/reference) project
+ for running it on some common emulators and development boards. To port
+ Hafnium to a new board, you can create a new project under this directory
+ with the platform or platforms you want to add, without affecting the core
+ Hafnium code.
+* [`src`](../src): Source code for Hafnium itself in C and assembly, and
+ [unit tests](Testing.md) in C++.
+ * [`arch`](../src/arch): Implementation of architecture-dependent modules.
+* [`test`](../test): [Integration tests](Testing.md)
+ * [`arch`](../test/arch): Tests for components of Hafnium that need to be
+ run on a real architecture.
+ * [`hftest`](../test/hftest): A simple test framework that supports
+ running tests standalone on bare metal, in VMs under Hafnium, or as
+ user-space binaries under Linux under Hafnium.
+ * [`linux`](../test/linux): Tests which are run in a Linux VM under
+ Hafnium.
+ * [`vmapi`](../test/vmapi): Tests which are run in minimal test VMs under
+ Hafnium.
+ * [`arch`](../test/vmapi/arch): Tests which are rely on specific
+ architectural details such as the GIC version.
+ * [`primary_only`](../test/vmapi/primary_only): Tests which run only a
+ single (primary) VM.
+ * [`primary_with_secondaries`](../test/vmapi/primary_with_secondaries):
+ Test which run with a primary VM and one or more secondary VMs to
+ test how they interact.
+* [`third_party`](../third_party): Third party code needed for building
+ Hafnium.
+* [`vmlib`](../vmlib): A small client library for VMs running under Hafnium.