Skip to content

Latest commit

 

History

History
134 lines (98 loc) · 6.23 KB

build.md

File metadata and controls

134 lines (98 loc) · 6.23 KB
Raw

Build Instructions

These instructions for building the Gunyah Hypervisor can be used for both local builds or building within a Docker container.

Build Environment

Ensure your build environment is correctly setup. See Setup Instructions.

Always ensure you have activated the gunyah-venv before running configure or building.

. gunyah-venv/bin/activate

Download the source code

The following repositories are needed to build a Gunyah Hypervisor image:

These should all be cloned into the same top-level directory (this assumed in the Docker setup).

git clone https://github.com/quic/gunyah-hypervisor.git hyp
  • Resource Manager — The privileged root VM and VM manager supporting the Gunyah Hypervisor.
git clone https://github.com/quic/gunyah-resource-manager.git resource-manager
git clone https://github.com/quic/gunyah-c-runtime.git musl-c-runtime

Build Configuration

The build system has several configuration parameters that must be set:

  • platform: selects the target hardware platform
  • featureset: selects a named hypervisor architecture configuration
  • quality: specifies the build quality, e.g. debug, production etc., which modify the build, such as including runtime assertions, compiler optimisations etc.

These parameters must be set on the build system's command line; if one or more of them is left unset, the build system will print the known values for the missing parameter and abort. You may specify a comma-separated list to select multiple values for a parameter, or all to select every valid combination. You may also specify simply all=true, which is equivalent to specifying all for every parameter that is not otherwise specified. The when multiple options are selected, each combination (variant) will be built in separate output directories under the build directory.

Each project may be built using ninja or scons and the process for build configuration depends on the selected build tool used. See the sections below.

Building

The Gunyah Hypervisor, Resource Manager and C runtime are built separately, each following the similar build instructions below. These separate images need to be packaged together into a final boot image.

IMPORTANT! If making hypervisor public API changes, these changes will need to be updated in the Resource Manager and Runtime sources.

Building with Ninja

To configure the build for use with Ninja, run ./configure.py <configuration> in the top-level source repository of the component, specifying the desired configuration parameters.

For example, in each of the Gunyah Hypervisor, Resource Manager and Gunyah C Runtime source directories, run:

./configure.py platform=qemu featureset=gunyah-rm-qemu quality=production

or to build all available configurations for the QEMU platform:

./configure.py platform=qemu all=true

This will create a build directory and Ninja build rules file for each enabled build variant. Generally, the configure step only needs to be run once.

ninja

Run ninja to build. There is usually no need to specify -j or similar, as Ninja will select this automatically. Ninja also will incrementally re-build if run again after making code changes.

Note, if configuration files are modified, Ninja will rerun the configuration tool with the previous parameters. However, you must manually rerun the configuration step if you rename or delete an existing module or configuration parameter, as Ninja will refuse to run if a build configuration file is missing.

To build a specific file (for example, a single variant when multiple variants have been configured), specify its full name as the target on the ninja command line.

To clean the build, run ninja -t clean. It should not be necessary to do this routinely.

Building with SCons

To perform a standalone SCons build, run scons, specifying the configuration parameters. For example, to build debug builds of all available feature sets for the QEMU platform:

scons platform=qemu featureset=all quality=debug

Note, configuration parameters must be specified on every time you perform a SCons build; configuration is not cached.

To clean the build, run scons -c all=true, or use configuration parameters to select a specific variant to clean. It should not be necessary to do this routinely.

Producing a Boot Image

Once you have built the Gunyah Hypervisor, Resource Manager and C Runtime, a boot image needs be generated.

To reduce the size of the boot image, the generated binaries of Resource Manager and C Runtime need to be stripped with the following commands:

$LLVM/bin/llvm-strip -o <path-to-resource-manager-src>/build/resource-manager.strip <path-to-resource-manager-src>/build/resource-manager
$LLVM/bin/llvm-strip -o <path-to-c-runtime-src>/build/runtime.strip <path-to-c-runtime-src>/build/runtime

The individual executables generated by building Gunyah Hypervisor, Resource Manager, and Gunyah C Runtime need to be integrated into a single hypvm.elf boot image.

You will need the pyelftools Python module. This should be installed in the gunyah python virtual-env. However, it is available from its upstream project:

cd <tools-directory>
git clone https://github.com/eliben/pyelftools.git

To generate hypvm.elf boot image run these steps (substituting <path>s for each tool / executable):

cd <path-to-gunyah-hypervisor-src>
tools/elf/package_apps.py \
 -a <path-to-resource-manager-src>/build/resource-manager.strip \
 -r <path-to-c-runtime-src>/build/runtime.strip \
 <path-to-gunyah-hypervisor-src>/build/qemu/gunyah-rm-qemu/production/hyp.elf \
 -o <path-to-destination>/hypvm.elf

Note, you may wish to pick a different hypervisor hyp.elf from a different build variant (i.e. build/qemu/gunyah-rm-qemu/debug/).