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