6.1.1. Get started

6.1.1.1. Getting the source code

git 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\""; }; }

To upload a commit for review:

git push origin HEAD:refs/for/master

Browse source at https://review.trustedfirmware.org/plugins/gitiles/. Review CLs at https://review.trustedfirmware.org/.

6.1.1.2. Compiling the hypervisor

Install prerequisites:

sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip
pip3 install fdt

Before building, provide the LLVM/clang toolchain and dtc tool in the PATH environment variable. To use the default prebuilt toolchain (used by the Hafnium CI):

PATH=$PWD/prebuilts/linux-x64/clang/bin:$PWD/prebuilts/linux-x64/dtc:$PATH

By default, the hypervisor is built with clang for a few target platforms along with tests. Each project in the project directory specifies a root configurations of the build. Adding a project is the preferred way to extend support to new platforms. The target project that is built is selected by the PROJECT make variable, the default project is ‘reference’.

make PROJECT=<project_name>

The compiled image can be found under out/<project>, for example the QEMU image is at out/reference/qemu_aarch64_clang/hafnium.bin.

The presence of assertions in the final build can be set using the ENABLE_ASSERTIONS make variable, by default this is set to true, meaning asserts are included in the build.

make ENABLE_ASSERTIONS=<true|false>

If you wish to change the value of the make variables you may need to first use:

make clobber

So the args.gn file will be regenerated with the new values.

6.1.1.3. Running on QEMU

You will need at least version 2.9 for QEMU. The following command line can be used to run Hafnium on it:

qemu-system-aarch64 -M virt,gic_version=3 -cpu cortex-a57 -nographic -machine virtualization=true -kernel out/reference/qemu_aarch64_clang/hafnium.bin

Though it is admittedly not very useful because it doesn’t have any virtual machines to run.

Next, you need to create a manifest which will describe the VM to Hafnium. Follow the Manifest instructions and build a DTB with:

/dts-v1/;

/ {
	hypervisor {
		compatible = "hafnium,hafnium";
		vm1 {
			debug_name = "Linux VM";
			kernel_filename = "vmlinuz";
			ramdisk_filename = "initrd.img";
		};
	};
};

Follow the Hafnium RAM disk instructions to create an initial RAM disk for Hafnium with Linux as the primary VM.

The following command line will run Hafnium, with the RAM disk just created, which will then boot into the primary Linux VM:

qemu-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"

6.1.1.4. Running tests

After building, presubmit tests can be run with the following command line:

./kokoro/test.sh

Read about testing for more details about the tests.