docs: build the Hafnium Hypervisor documentation
The Hafnium Hypervisor documentation is kept as a legacy provided this
component is still used for test purposes within the Hafnium CI.
As the original files are .md files as opposed to .rst files for the
remaining of the project, adjust tags to permit building with sphinx.
Signed-off-by: Olivier Deprez <olivier.deprez@arm.com>
Change-Id: I5fc138cf7bc2de1276823c0739cbca6d136f26dd
diff --git a/docs/appendix.rst b/docs/appendix.rst
new file mode 100644
index 0000000..364fa49
--- /dev/null
+++ b/docs/appendix.rst
@@ -0,0 +1,11 @@
+Appendix
+========
+
+.. toctree::
+ :maxdepth: 1
+
+ hypervisor/index
+
+--------------
+
+*Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/hypervisor/Architecture.md b/docs/hypervisor/Architecture.md
index a723906..0c68622 100644
--- a/docs/hypervisor/Architecture.md
+++ b/docs/hypervisor/Architecture.md
@@ -32,8 +32,6 @@
and is likely to be more latency-sensitive as it is running user-facing tasks.
Some of the differences between primary and secondary VMs are explained below.
-[TOC]
-
## Security model
Hafnium runs a set of VMs without trusting any of them. Neither do the VMs trust
@@ -72,7 +70,7 @@
## VM model
-A [VM](../inc/hf/vm.h) in Hafnium consists of:
+A [VM](../../inc/hf/vm.h) in Hafnium consists of:
* A set of memory pages owned by and/or available to the VM, stored in the
stage 2 page table managed by Hafnium.
@@ -84,7 +82,7 @@
* Some internal state maintained by Hafnium (locks, mailbox wait lists,
mailbox state, log buffer).
-Each [vCPU](../inc/hf/vcpu.h) also has:
+Each [vCPU](../../inc/hf/vcpu.h) also has:
* A set of saved registers, for when it isn't being run on a physical CPU.
* A current state (switched off, ready to run, running, waiting for a message
diff --git a/docs/hypervisor/CodeStructure.md b/docs/hypervisor/CodeStructure.md
index b3fa8d6..130f3e1 100644
--- a/docs/hypervisor/CodeStructure.md
+++ b/docs/hypervisor/CodeStructure.md
@@ -20,56 +20,56 @@
The source tree is organised as follows:
-* [`build`](../build): Common GN configuration, build scripts, and linker
+* `build`: Common GN configuration, build scripts, and linker
script.
-* [`docs`](.): Documentation
-* [`driver/linux`](../driver/linux): Linux kernel driver for Hafnium, for use
+* `docs`: Documentation
+* `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
+* `inc`: Header files...
+ * `hf`: ... internal to Hafnium
+ * `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
+ * `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`
+ * `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
+ * `vmapi/hf`: ... for the interface exposed to VMs.
+* `kokoro`: Scripts and configuration for continuous integration
and presubmit checks.
-* [`prebuilts`](../prebuilts): Prebuilt binaries needed for building Hafnium
+* `prebuilts`: Prebuilt binaries needed for building Hafnium
or running tests.
-* [`project`](../project): Configuration and extra code for each **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
+ together. Hafnium comes with the `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
+* `src`: Source code for Hafnium itself in C and assembly, and
+ unit tests in C++.
+ * `arch`: Implementation of architecture-dependent modules.
+* `test`: Integration tests
+ * `arch`: Tests for components of Hafnium that need to be
run on a real architecture.
- * [`hftest`](../test/hftest): A simple test framework that supports
+ * `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
+ * `linux`: Tests which are run in a Linux VM under
Hafnium.
- * [`vmapi`](../test/vmapi): Tests which are run in minimal test VMs under
+ * `vmapi`: Tests which are run in minimal test VMs under
Hafnium.
- * [`arch`](../test/vmapi/arch): Tests which are rely on specific
+ * `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
+ * `primary_only`: Tests which run only a
single (primary) VM.
- * [`primary_with_secondaries`](../test/vmapi/primary_with_secondaries):
+ * `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
+* `third_party`: Third party code needed for building
Hafnium.
-* [`vmlib`](../vmlib): A small client library for VMs running under Hafnium.
+* `vmlib`: A small client library for VMs running under Hafnium.
diff --git a/docs/hypervisor/FVP.md b/docs/hypervisor/FVP.md
index 8790bee..fde4016 100644
--- a/docs/hypervisor/FVP.md
+++ b/docs/hypervisor/FVP.md
@@ -22,7 +22,7 @@
$ make && kokoro/test.sh --fvp
```
-See the `FvpDriver` class in [`hftest.py`](../test/hftest/hftest.py) for details
+See the `FvpDriver` class in [`hftest.py`](../../test/hftest/hftest.py) for details
on how this works.
## Other resources
diff --git a/docs/hypervisor/GettingStarted.md b/docs/hypervisor/GetStarted.md
similarity index 97%
rename from docs/hypervisor/GettingStarted.md
rename to docs/hypervisor/GetStarted.md
index 09706b1..812fb09 100644
--- a/docs/hypervisor/GettingStarted.md
+++ b/docs/hypervisor/GetStarted.md
@@ -1,6 +1,4 @@
-# Getting started
-
-[TOC]
+# Get started
## Getting the source code
@@ -17,8 +15,6 @@
Browse source at https://review.trustedfirmware.org/plugins/gitiles/. Review CLs
at https://review.trustedfirmware.org/.
-See details of [how to contribute](../CONTRIBUTING.md).
-
## Compiling the hypervisor
Install prerequisites:
diff --git a/docs/hypervisor/HermeticBuild.md b/docs/hypervisor/HermeticBuild.md
index aee1444..51c4999 100644
--- a/docs/hypervisor/HermeticBuild.md
+++ b/docs/hypervisor/HermeticBuild.md
@@ -13,8 +13,6 @@
default settings. For now, running the hermetic build locally is intended
primarily to reproduce issues in pre-submit tests.
-[TOC]
-
## Installing Docker
### Stable
diff --git a/docs/hypervisor/Manifest.md b/docs/hypervisor/Manifest.md
index bb4cdff..b6a6cdb 100644
--- a/docs/hypervisor/Manifest.md
+++ b/docs/hypervisor/Manifest.md
@@ -1,7 +1,5 @@
# Hafnium Manifest
-[TOC]
-
## Format
The format of the manifest is a simple DeviceTree overlay:
diff --git a/docs/hypervisor/PreparingLinux.md b/docs/hypervisor/PreparingLinux.md
index 3332096..9654960 100644
--- a/docs/hypervisor/PreparingLinux.md
+++ b/docs/hypervisor/PreparingLinux.md
@@ -3,8 +3,6 @@
To boot Linux, a kernel image (`vmlinuz`) and a suitable initial RAM disk
(`initrd.img`) need to be created.
-[TOC]
-
## Build the kernel
The Linux kernel for the primary VM can be built using the following
diff --git a/docs/hypervisor/README.md b/docs/hypervisor/README.md
deleted file mode 100644
index 6d0f715..0000000
--- a/docs/hypervisor/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Documentation index
-
-* [README](../README.md)
-* [Contributing](../CONTRIBUTING.md)
-* [Style guide](StyleGuide.md)
-* [Change log](ChangeLog.md)
-
-## Building and running Hafnium
-* [Getting started](GettingStarted.md)
-* [Building a RAM disk with VMs for Hafnium to run](HafniumRamDisk.md)
-* [Manifest format](Manifest.md)
-* [Building a Linux image for Hafnium](PreparingLinux.md)
-* [Building Hafnium hermetically with Docker](HermeticBuild.md)
-* [Running Hafnium under Arm FVP](FVP.md)
-
-## Design details
-* [Architecture](Architecture.md)
-* [Code structure](CodeStructure.md)
-* [Test infrastructure](Testing.md)
-* [The interface Hafnium provides to VMs](VmInterface.md)
-* [Scheduler VM expectations](SchedulerExpectations.md)
diff --git a/docs/hypervisor/SchedulerExpectations.md b/docs/hypervisor/SchedulerExpectations.md
index c25018f..f27e587 100644
--- a/docs/hypervisor/SchedulerExpectations.md
+++ b/docs/hypervisor/SchedulerExpectations.md
@@ -4,8 +4,6 @@
responsible for scheduling the other VMs. There are some particular expectations
on this VM that are required for the rest of the system to function normally.
-[TOC]
-
## Scheduling
The scheduler VM is responsible for scheduling the vCPUs of all the other VMs.
diff --git a/docs/hypervisor/StyleGuide.md b/docs/hypervisor/StyleGuide.md
index 1619971..50215a1 100644
--- a/docs/hypervisor/StyleGuide.md
+++ b/docs/hypervisor/StyleGuide.md
@@ -15,8 +15,6 @@
tooling conflicts with what is in this document we accept what the tooling
requires, and try to improve it if possible.
-[TOC]
-
## Clarifications
* Yes, it does mean all variables are declared, C90-style, at the top of
@@ -66,11 +64,11 @@
## Coding practices
* Function macros should be functions instead, that way you get types.
-* Lock ordering is described at the top of [`api.c`](../src/api.c).
+* Lock ordering is described at the top of [`api.c`](../../src/api.c).
* Use opaque types to avoid implicit casts when it will help avoid mistakes.
- e.g. [`addr.h`](../inc/hf/addr.h)
+ e.g. [`addr.h`](../../inc/hf/addr.h)
* Avoid inline casting. C doesn't give much protection so be formal about the
- transformations. e.g. [`addr.h`](../inc/hf/addr.h)
+ transformations. e.g. [`addr.h`](../../inc/hf/addr.h)
* If a function acquires a resource, there must be a single exit path to free
the resource. Tracking down multiple exit points is hard and requires
duplicated code which is harder. This may require splitting functions into
@@ -119,7 +117,7 @@
printf-style format strings and arguments.
The log level of a build is controlled by the `log_level` argument defined in
-[`BUILDCONFIG.gn`](../build/BUILDCONFIG.gn). This defaults to `INFO` for debug
+[`BUILDCONFIG.gn`](../../build/BUILDCONFIG.gn). This defaults to `INFO` for debug
builds and tests, meaning that all levels except `VERBOSE` will be logged. It is
recommended to set the log level to `NOTICE` for production builds, to reduce
binary size and log spam.
diff --git a/docs/hypervisor/Testing.md b/docs/hypervisor/Testing.md
index 6f889f8..fe8baba 100644
--- a/docs/hypervisor/Testing.md
+++ b/docs/hypervisor/Testing.md
@@ -1,7 +1,5 @@
# Testing
-[TOC]
-
## Overview
Hafnium has 4 main kinds of tests:
diff --git a/docs/hypervisor/VmInterface.md b/docs/hypervisor/VmInterface.md
index 63f5e60..d5a9447 100644
--- a/docs/hypervisor/VmInterface.md
+++ b/docs/hypervisor/VmInterface.md
@@ -13,8 +13,6 @@
The interface documented here is what is planned for the first release of
Hafnium, not necessarily what is currently implemented.
-[TOC]
-
## CPU scheduling
The primary VM will have one vCPU for each physical CPU, and control the
diff --git a/docs/hypervisor/index.rst b/docs/hypervisor/index.rst
new file mode 100644
index 0000000..7531076
--- /dev/null
+++ b/docs/hypervisor/index.rst
@@ -0,0 +1,26 @@
+Hypervisor
+==========
+
+.. note::
+
+ Following sections cover the legacy Hafnium Hypervisor implementation.
+ As a disclaimer, the Hypervisor is maintained as a legacy component used for
+ test purposes in the Hafnium CI. It shall not be used to build a product and
+ the support is not guaranteed.
+
+.. toctree::
+ :maxdepth: 1
+
+ GetStarted
+ Architecture
+ CodeStructure
+ FVP
+ HafniumRamDisk
+ HermeticBuild
+ Maintainers
+ Manifest
+ PreparingLinux
+ SchedulerExpectations
+ StyleGuide
+ Testing
+ VmInterface
diff --git a/docs/index.rst b/docs/index.rst
index f14f87f..99a1ffe 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,11 @@
Hafnium Documentation
=====================
-Hafnium documentation template.
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+
+ appendix
--------------