Building in the HHBSP

You can build a QNX hypervisor system from inside the HHBSP framework, with files in their default locations or custom locations in the HHBSP directory structure.

To build in the HHBSP framework, you must do the following:

Prepare the build configuration.
Modify the board-specific BSP and build the host (optional).
Modify and build QNX guests (optional).
Adjust the disk image settings (optional).
Build the hypervisor system.

You don't have to place the BSPs in their default locations in the HHBSP, or even in the HHBSP directory structure. You may place them elsewhere on your development host, as long as you set the relevant variables (either via the command line or by editing the configure.mk configuration file) to point to the locations you have chosen (see “Specify the component locations”).

For information about how to build the hypervisor host outside the HHBSP framework, see “Building the host” in this chapter.

Prepare the build configuration

Before you build your hypervisor system in the HHBSP framework, you need to set the board type, and specify the locations of the BSPs you will use in your build:

Make sure that your environment is properly set up for QOS 2.2.1+ builds, as required (see “Supported build environments”).
If you haven't done so already, set the variables to specify your board and the locations of your BSPs, either in the configure.mk file, or via the command line (see “Configuring an HHBSP build”).
If you haven't done so already, download and unzip the appropriate board-specific BSP into the directory referenced by BOARD_SPECIFIC_BSP_LOCATION. For example:
```
# unzip ~/Downloads/BSP_renesas-r-car-h3_br-710_be-710_SVN922638_JBN514.zip \
	-d $BOARD_SPECIFIC_BSP_LOCATION
```

When you have confirmed that your build environment is correctly set up and that you have the board-specific BSP for the host in the location where the build will look for it, you can build the hypervisor host and its guests.

Modify the board-specific BSP and build the host (optional)

If you need to modify the board-specific BSP for the host, you will need to build the host after you have made your changes:

Go to that BSP's root directory. Assuming that you have set BOARD_SPECIFIC_BSP_LOCATION:
```
# cd $BOARD_SPECIFIC_BSP_LOCATION
```
Make your changes to the BSP.
Build the host:
```
# make
```

Modify and build QNX guests (optional)

To build QNX guests, you need to download the architecture-specific guest BSPs, unzip them, and place them in the directories referenced by your QNX*_GUEST_BSP_LOCATION variables:

Go to your HHBSP's root directory:
```
# cd hhbsp
```
where hhbsp is your HHBSP root directory.
Download and unzip QNX guest BSPs into the locations referenced by the QNX7_GUEST_BSP_LOCATION variable, as needed. For example, for a QNX Neutrino 7.1 guest:
```
# unzip ~/Downloads/BSP_hypervisor-guest-x86_br-710_be-710_SVN917988_JBN3.zip \
	-d $QNX7_GUEST_BSP_LOCATION
```
Make your modifications to the QNX guest BSP buildfiles and save them.
Go to the root directory for each modified QNX guest BSP, and run make to rebuild the guest. For example, if you modified the QNX Neutrino 7.1 guest:
```
# cd $QNX7_GUEST_BSP_LOCATION
# make
```
Copy to the HHBSP images/guest_data/ directory the files needed to boot the guest.

Adjust the disk image settings (optional)

The HHBSP's image/disk_config/ directory includes:

*partition.build.template files that describe the contents of the individual disk partitions and filesystems
diskimage*.cfg files that describe the geometry of the disk image

If you need to adjust any of the disk image settings, open and modify these files. For more information about configuring disk images, see “Disk image partitions” in this chapter, and “diskimage configuration file” in the QNX Neutrino Utilities Reference.

Build the hypervisor system

When you have completed the relevant tasks described above, you can build your hypervisor host system:

Go to the HHBSP root directory.
Run make to build your system.

You should now be ready to use dd or a similar utility to transfer the disk image to removable media, which you can then use to move your disk image to your target board. For instructions, see “Transferring the disk image”.

CAUTION:

The disk image is a complete disk image; it includes a partition table and multiple partitions, so you must copy it directly to the raw disk device.

Don't write to your storage medium's partition file (e.g., /dev/sdb1 or /dev/rdisk3s1). Write to the raw device file.

For instructions on how to boot the hypervisor, see “Booting the QNX hypervisor host”.

How the build uses the buildfiles

When you run make to build a hypervisor system, the build process:

concatenates several buildfiles to create a final buildfile
uses the final buildfile to generate an IFS
puts the IFS in the bootable partition of the hypervisor system disk image

The order in which the build concatenates these buildfiles is:

Buildfiles in the $BOARD_SPECIFIC_BSP_LOCATION/images/ directory
Relevant board-specific hypervisor buildfiles (e.g., images/hypervisor-renesas-rcarh3.build)
The architecture-specific buildfile (e.g., images/hypervisor-common-arch.build, where arch is the board architecture, either arm or x86)
The common buildfile (images/hypervisor.common.build)

Note: The build doesn't concatenate all buildfiles in the $BOARD_SPECIFIC_BSP_LOCATION/images/ directory together. Rather, for each buildfile found in this directory, it effects a separate concatenation with the buildfiles in the other directories, to build an IFS for each buildfile in $BOARD_SPECIFIC_BSP_LOCATION/images/.

The order in which the buildfiles are concatenated is important. The scripts that run when the hypervisor boots expects this order.

The script that is invoked by running make in the HHBSP root directory to build a hypervisor system modifies the host BSP buildfiles (in the $BOARD_SPECIFIC_BSP_LOCATION directory). These modifications include, where needed:

adding to the buildfile's procnto line the hypervisor-specific and other required attributes (e.g., [+keeplinked module=aps-safety module=qvm-safety])
making any [+session] shells run in the background (&)
removing any -B options from startup drivers, so the startup will get the ACPI tables (x86); the hypervisor needs these tables

When the build process is complete, it leaves in the HHBSP's generated/ifs/ directory a copy of the buildfile it generated and used to build each IFS. If the build created three IFSs, there should be three of these generated buildfiles.

The build process names these files as follows: hypervisor_FINAL_info.build, where info is information that allows you to determine which generated buildfile was used to build which IFS. You can examine these generated buildfiles if you need to review and better understand exactly what went into a particular IFS.

The script attempts to keep existing attributes, so the final buildfile may include duplicate entries.

Buildfiles and IFSs

A single build process creates as many IFSs as there are buildfiles in the images/host_bsp/images/ directory.

Thus, if there are three buildfiles in this directory, the build assembles three distinct concatenations: one for each of these files; each file is placed in a separate concatenation with hypervisor.common.build, then the relevant board-specific hypervisor buildfiles. The result of the build is three different IFSs.

If you are only interested in a single IFS variant, remove the buildfiles for the IFSs you don't want from the images/host_bsp/images/ directory, or rename them so the build process doesn't find them.

What happens when you make a new hypervisor disk image?

Running make in the HHBSP root directory looks after getting any updated IFSs for the hypervisor host and for guests that are in the HHBSP directory structure, and calling mkxfs to produce a disk image.

The build uses the following updated files from the HHBSP directories:

buildfiles from the $BOARD_SPECIFIC_BSP_LOCATION/images/ (see “Contents of an HHBSP” in this chapter)
binaries from the $BOARD_SPECIFIC_BSP_LOCATION/install/ directory
IFSs and *.qvmconf VM configuration files from the $BOARD_SPECIFIC_BSP_LOCATION/guest_data/ directory

Linux guests

For Linux guests, the build process uses the contents of the entire images/guest_bsps/linux/arch directory (where arch is either arm or x86), which should include everything needed to run a Linux guest (Linux kernel, initrd file, etc.). For more information about building Linux guests, see “Building Linux and Android guests” in this chapter.