blob: 4fb870ed35bbe1c8d8dae50fbdcaa0f945ab3ffc [file] [log] [blame] [view]
Andrew Scull23042042018-08-22 17:44:56 +01001# Getting started
2
Andrew Walbranb7849972019-11-15 15:23:43 +00003[TOC]
4
Andrew Scull23042042018-08-22 17:44:56 +01005## Getting the source code
6
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +01007```shell
Andrew Walbran05e5edc2020-06-17 16:50:45 +01008git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git && (cd hafnium && f=`git rev-parse --git-dir`/hooks/commit-msg ; curl -Lo $f https://review.trustedfirmware.org/tools/hooks/commit-msg ; chmod +x $f ; for m in `git rev-parse --git-dir`/modules/*; do cp $f $m/hooks/commit-msg; done)
Andrew Scull23042042018-08-22 17:44:56 +01009```
10
11To upload a commit for review:
12
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010013```shell
Andrew Scull23042042018-08-22 17:44:56 +010014git push origin HEAD:refs/for/master
15```
Andrew Walbran0ba13bb2019-05-13 10:57:25 +010016
Andrew Walbran05e5edc2020-06-17 16:50:45 +010017Browse source at https://review.trustedfirmware.org/plugins/gitiles/. Review CLs
18at https://review.trustedfirmware.org/.
Andrew Walbran0ba13bb2019-05-13 10:57:25 +010019
Andrew Scullb81de702019-07-09 13:46:50 +010020See details of [how to contribute](../CONTRIBUTING.md).
Andrew Scull23042042018-08-22 17:44:56 +010021
22## Compiling the hypervisor
23
Andrew Walbran10276722018-09-10 14:33:18 +010024Install prerequisites:
25
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010026```shell
Raghu Krishnamurthy3fe1f4b2021-03-20 19:46:13 -070027sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip
28pip3 install fdt
Andrew Walbran10276722018-09-10 14:33:18 +010029```
30
Andrew Scull23e93a82018-10-26 14:56:04 +010031By default, the hypervisor is built with clang for a few target platforms along
Alfredo Mazzinghib2bb1d32019-02-08 11:12:51 +000032with tests. Each project in the `project` directory specifies a root
33configurations of the build. Adding a project is the preferred way to extend
34support to new platforms. The target project that is built is selected by the
35`PROJECT` make variable, the default project is 'reference'.
Andrew Scull23042042018-08-22 17:44:56 +010036
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010037```shell
Alfredo Mazzinghib2bb1d32019-02-08 11:12:51 +000038make PROJECT=<project_name>
Andrew Scull23042042018-08-22 17:44:56 +010039```
40
David Brazdil5ecf75f2019-07-21 10:39:47 +020041The compiled image can be found under `out/<project>`, for example the QEMU
42image is at `out/reference/qemu_aarch64_clang/hafnium.bin`.
Andrew Scull23042042018-08-22 17:44:56 +010043
Andrew Scull23042042018-08-22 17:44:56 +010044## Running on QEMU
45
46You will need at least version 2.9 for QEMU. The following command line can be
47used to run Hafnium on it:
48
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010049```shell
Andrew Scull25d897e2019-06-27 12:57:02 +010050qemu-system-aarch64 -M virt,gic_version=3 -cpu cortex-a57 -nographic -machine virtualization=true -kernel out/reference/qemu_aarch64_clang/hafnium.bin
Andrew Scull23042042018-08-22 17:44:56 +010051```
52
53Though it is admittedly not very useful because it doesn't have any virtual
David Brazdila2358d42020-01-27 18:51:38 +000054machines to run.
Andrew Scull23042042018-08-22 17:44:56 +010055
David Brazdil0dbb41f2019-09-09 18:03:35 +010056Next, you need to create a manifest which will describe the VM to Hafnium.
David Brazdila2358d42020-01-27 18:51:38 +000057Follow the [Manifest](Manifest.md) instructions and build a DTB with:
Andrew Walbran05e5edc2020-06-17 16:50:45 +010058
David Brazdil0dbb41f2019-09-09 18:03:35 +010059```
60/dts-v1/;
David Brazdil0dbb41f2019-09-09 18:03:35 +010061
David Brazdila2358d42020-01-27 18:51:38 +000062/ {
David Brazdil0dbb41f2019-09-09 18:03:35 +010063 hypervisor {
Serban Constantinescubeb0ec72019-11-07 13:42:56 +000064 compatible = "hafnium,hafnium";
David Brazdil0dbb41f2019-09-09 18:03:35 +010065 vm1 {
66 debug_name = "Linux VM";
Andrew Scull72b43c02019-09-18 13:53:45 +010067 kernel_filename = "vmlinuz";
Serban Constantinescubeb0ec72019-11-07 13:42:56 +000068 ramdisk_filename = "initrd.img";
David Brazdil0dbb41f2019-09-09 18:03:35 +010069 };
70 };
71};
72```
73
Andrew Walbran05e5edc2020-06-17 16:50:45 +010074Follow the [Hafnium RAM disk](HafniumRamDisk.md) instructions to create an
75initial RAM disk for Hafnium with Linux as the primary VM.
David Brazdil0dbb41f2019-09-09 18:03:35 +010076
Andrew Scull23042042018-08-22 17:44:56 +010077The following command line will run Hafnium, with the RAM disk just created,
78which will then boot into the primary Linux VM:
79
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010080```shell
David Brazdila2358d42020-01-27 18:51:38 +000081qemu-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"
Andrew Scull23042042018-08-22 17:44:56 +010082```
83
84## Running tests
85
86After building, presubmit tests can be run with the following command line:
87
Andrew Walbran6f8fd4c2019-08-05 13:28:17 +010088```shell
Andrew Walbran219ceaf2020-01-10 15:44:29 +000089./kokoro/test.sh
Andrew Scull23042042018-08-22 17:44:56 +010090```
91
92Read about [testing](Testing.md) for more details about the tests.