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