1# Getting started
2
3[TOC]
4
5## Getting the source code
6
7```shell
8git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git && { cd hafnium && f="$(git rev-parse --git-dir)"; curl -Lo "$f/hooks/commit-msg" https://review.trustedfirmware.org/tools/hooks/commit-msg && { chmod +x "$f/hooks/commit-msg"; git submodule --quiet foreach "cp \"\$toplevel/$f/hooks/commit-msg\" \"\$toplevel/$f/modules/\$path/hooks/commit-msg\""; }; }
9```
10
11To upload a commit for review:
12
13```shell
14git push origin HEAD:refs/for/master
15```
16
17Browse source at https://review.trustedfirmware.org/plugins/gitiles/. Review CLs
18at https://review.trustedfirmware.org/.
19
20See details of [how to contribute](../CONTRIBUTING.md).
21
22## Compiling the hypervisor
23
24Install prerequisites:
25
26```shell
27sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip
28pip3 install fdt
29```
30
31Before building, provide the LLVM/clang toolchain and dtc tool in the PATH
32environment variable. To use the default prebuilt toolchain (used by the
33Hafnium CI):
34
35```shell
36PATH=$PWD/prebuilts/linux-x64/clang/bin:$PWD/prebuilts/linux-x64/dtc:$PATH
37```
38
39By default, the hypervisor is built with clang for a few target platforms along
40with tests. Each project in the `project` directory specifies a root
41configurations of the build. Adding a project is the preferred way to extend
42support to new platforms. The target project that is built is selected by the
43`PROJECT` make variable, the default project is 'reference'.
44
45```shell
46make PROJECT=<project_name>
47```
48
49The compiled image can be found under `out/<project>`, for example the QEMU
50image is at `out/reference/qemu_aarch64_clang/hafnium.bin`.
51
52The presence of assertions in the final build can be set using the `ENABLE_ASSERTIONS`
53make variable, by default this is set to `true`, meaning asserts are included in the build.
54
55```shell
56make ENABLE_ASSERTIONS=<true|false>
57```
58If you wish to change the value of the make variables you may need to first use:
59
60```shell
61make clobber
62```
63So the `args.gn` file will be regenerated with the new values.
64
65## Running on QEMU
66
67You will need at least version 2.9 for QEMU. The following command line can be
68used to run Hafnium on it:
69
70```shell
71qemu-system-aarch64 -M virt,gic_version=3 -cpu cortex-a57 -nographic -machine virtualization=true -kernel out/reference/qemu_aarch64_clang/hafnium.bin
72```
73
74Though it is admittedly not very useful because it doesn't have any virtual
75machines to run.
76
77Next, you need to create a manifest which will describe the VM to Hafnium.
78Follow the [Manifest](Manifest.md) instructions and build a DTB with:
79
80```
81/dts-v1/;
82
83/ {
84	hypervisor {
85		compatible = "hafnium,hafnium";
86		vm1 {
87			debug_name = "Linux VM";
88			kernel_filename = "vmlinuz";
89			ramdisk_filename = "initrd.img";
90		};
91	};
92};
93```
94
95Follow the [Hafnium RAM disk](HafniumRamDisk.md) instructions to create an
96initial RAM disk for Hafnium with Linux as the primary VM.
97
98The following command line will run Hafnium, with the RAM disk just created,
99which will then boot into the primary Linux VM:
100
101```shell
102qemu-system-aarch64 -M virt,gic_version=3 -cpu cortex-a57 -nographic -machine virtualization=true -kernel out/reference/qemu_aarch64_clang/hafnium.bin -initrd initrd.img -append "rdinit=/sbin/init"
103```
104
105## Running tests
106
107After building, presubmit tests can be run with the following command line:
108
109```shell
110./kokoro/test.sh
111```
112
113Read about [testing](Testing.md) for more details about the tests.
114