Attention
Build System
An EWAOL build can be configured by setting the target platform via the
MACHINE
BitBake variable, the desired distribution image features via the
DISTRO_FEATURES
BitBake variable, and customizing those features via
feature-specific modifiable variables.
This page first overviews EWAOL’s support for the kas build tool. Each available distribution image feature and each supported target platform is then defined together with their associated kas configuration files, followed by any other additional customization options. The process for building without kas is then briefly described.
kas Build Tool Support
The kas build tool enables automatic fetch and inclusion of layer sources, as well as parameter and feature specification for building target images. To enable this, kas configuration files in the YAML format are passed to the tool to provide the necessary definitions.
These kas configuration files are modular, where passing multiple files will result in an image produced with their combined configuration. Further, kas configuration files can extend other kas configuration files, thereby enabling specialized configurations that inherit common configurations.
The meta-ewaol-config/kas
directory contains kas configuration files that
support building images via kas for the EWAOL project, and fall into three
ordered categories:
Architecture Configs
Build Modifier Configs
Target Platform Configs
To build an EWAOL distribution image via kas, it is required to provide one Architecture Config and one Target Platform Config, unless otherwise stated in their descriptions below. Additional Build Modifiers are optional, and depend on the target use-case. Currently, it is necessary that kas configuration files are provided in order: the Architecture Config is defined first, then additional build features via zero or more Build Modifier Configs, and finally the Target Platform Config.
The kas configuration files to enable builds for a supported target platform or to configure each EWAOL distribution image feature, are described in their relevant sections below: Target Platforms and Distribution Image Features, respectively. Example usage of these kas configuration files can be found in the Build section of the User Guide.
Note
If a kas configuration file does not set a particular build parameter, the parameter will take its default value.
Target Platforms
There are currently two supported target platforms (corresponding to the
MACHINE
BitBake variable), each with an associated kas configuration file,
as follows.
N1SDP
Corresponding value for
MACHINE
variable:n1sdp
.Target Platform Config:
meta-ewaol-config/kas/n1sdp.yml
.This supported target platform is the Neoverse N1 System Development Platform (N1SDP), implemented in the meta-arm-bsp Yocto BSP layer.
To enable this, the
n1sdp.yml
Target Platform Config includes common configuration from themeta-ewaol-config/kas/include/arm-machines.yml
kas configuration file, which defines the BSPs, layers, and dependencies required when building for then1sdp
.
AVA
Corresponding value for
MACHINE
variable:ava
.Target Platform Config:
meta-ewaol-config/kas/ava.yml
.This supported target platform is the AVA Developer Platform (AVA), implemented in the meta-adlink-ampere Yocto BSP layer.
Distribution Image Features
For a particular target platform, the available EWAOL distribution image
features (corresponding to the contents of the DISTRO_FEATURES
BitBake
variable) are detailed in this section, along with any associated kas
configuration files, and any associated customization options relevant for that
feature.
EWAOL Architectures
EWAOL distribution images can be configured via kas using Architecture Configs. These include a set of common configuration from a base EWAOL kas configuration file:
meta-ewaol-config/kas/include/ewaol-base.yml
This kas configuration file defines the base EWAOL layer dependencies and their
software sources, as well as additional build configuration variables. It also
includes the meta-ewaol-config/kas/include/ewaol-release.yml
kas
configuration file, where the layers dependencies are pinned for any
corresponding EWAOL release.
Baremetal Architecture
Corresponding value in
DISTRO_FEATURES
variable:ewaol-baremetal
.Architecture Config:
meta-ewaol-config/kas/baremetal.yml
.This EWAOL distribution image feature:
Enables the
ewaol-baremetal-image
build target, to build an EWAOL baremetal distribution image.Is incompatible with the
ewaol-virtualization
distribution image feature.The Architecture Config for this distribution image feature automatically appends
ewaol-baremetal
toDISTRO_FEATURES
and sets the sets the build target toewaol-baremetal-image
.To build EWAOL baremetal distribution image, provide the Baremetal Architecture Config to the kas build command. For example, to build an EWAOL baremetal distribution image for the N1SDP hardware target platform, run the following command:
kas build meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/n1sdp.yml
Virtualization Architecture
Corresponding value in
DISTRO_FEATURES
variable:ewaol-virtualization
.Architecture Config:
meta-ewaol-config/kas/virtualization.yml
.This EWAOL distribution image feature:
Enables the
ewaol-virtualization-image
build target, to build an EWAOL virtualization distribution image.Includes the Xen hypervisor into the software stack.
Enables Xen specific configs required by kernel.
Includes all necessary packages and adjustments to the Control VM’s root filesystem to support management of Xen Guest VMs.
Uses BitBake Multiple Configuration Build.
Includes a single Guest VM based on the
generic-arm64
MACHINE
, by default.Is incompatible with the
ewaol-baremetal
distribution image feature.The Architecture Config for this distribution image feature automatically appends
ewaol-virtualization
toDISTRO_FEATURES
and sets the sets the build target toewaol-virtualization-image
.To build EWAOL virtualization distribution image, provide the Virtualization Architecture Config to the kas build command. For example, to build an EWAOL virtualization distribution image for the N1SDP hardware target platform, run the following command:
kas build meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/n1sdp.yml
Customization
Configurable build-time variables for the Guest VM are defined
within the meta-ewaol-distro/conf/multiconfig/ewaol-guest-vm.conf
file and
the meta-ewaol-distro/conf/distro/include/ewaol-guest-vm.inc
which it
includes.
The following list shows the standard set of available variables for the Control
VM and the single default Guest VM, together with the default values (where
MB
and KB
refer to Megabytes and Kilobytes, respectively):
EWAOL_GUEST_VM_INSTANCES: "1" # Number of Guest VM instances EWAOL_GUEST_VM1_NUMBER_OF_CPUS: "4" # Number of CPUs for Guest VM1 EWAOL_GUEST_VM1_MEMORY_SIZE: "6144" # Memory size for Guest VM1 (MB) EWAOL_GUEST_VM1_ROOTFS_EXTRA_SPACE: "" # Extra storage space for Guest VM1 (KB) EWAOL_CONTROL_VM_MEMORY_SIZE: "2048" # Memory size for Control VM (MB) EWAOL_CONTROL_VM_ROOTFS_EXTRA_SPACE: "0" # Extra storage space for Control VM (KB), added as additional space above the storage necessary to support all Guest VMs root filesystems
The variables may be set either within an included kas configuration file
(see meta-ewaol-config/kas/virtualization.yml
for example usage), the
environment, or manually via, for example, local.conf
. The
EWAOL_*_ROOTFS_EXTRA_SPACE
variables apply their values to the relevant
IMAGE_ROOTFS_EXTRA_SPACE
BitBake variable.
Adding Extra EWAOL Guest VM Instances
It is possible to deploy multiple EWAOL Guest VM instances on the virtualization
distribution image, each one based on the same kernel and image recipe. The
number of Guest VM instances built for and included on the virtualization
distribution image can be set via the EWAOL_GUEST_VM_INSTANCES
variable.
Guest VM instances can be independently configured via BitBake variables which
reference the Guest VM’s integer instance index, from 1 to the value of
EWAOL_GUEST_VM_INSTANCES
, inclusive. For example, variables with a prefix
EWAOL_GUEST_VM1_
apply to the first Guest VM, variables with a prefix
EWAOL_GUEST_VM2_
apply to the second Guest VM, and so on. All Guest VM
instances use the same default configuration, apart from the hostname, which is
generated for each Guest VM by appending the instance index to the
EWAOL_GUEST_VM_HOSTNAME
BitBake variable. By default, the first Guest VM
will have a hostname ewaol-guest-vm1
, the second will have a hostname
ewaol-guest-vm2
, and so on. An example of configuring a second Guest VM
instance using the kas tool is given in
meta-ewaol-config/kas/include/second-guest-vm-parameters.yml
, although
these variables will only be used if EWAOL_GUEST_VM_INSTANCES
is set to
build two or more Guest VMs.
Configuring Guest VM PCI Device Passthrough
An EWAOL virtualization distribution image running on the AVA Developer Platform is capable of supporting Xen PCI passthrough, allowing Guest VMs to be assigned exclusive use of a single PCI device. This capability is not enabled by default, and requires the following Build Modifier Config:
Build Modifier Config:
meta-ewaol-config/kas/xen_pci_passthrough.yml
.This Build Modifier Config appends
xen-pci-passthrough
toMACHINE_FEATURES
.
Note
Xen PCI device passthrough is currently only supported on the AVA Developer Platform.
With the capability enabled, it is then possible to assign a single PCI device to a Guest VM by configuring an additional environment variable, provided for the corresponding Guest VM. This environment variable and its default value when the Build Modifier Config is provided to enable Xen PCI passthrough support is as follows:
EWAOL_GUEST_VM1_PCI_PASSTHROUGH_DEVICE: "0000:01:00.0" # PCI device ID to be assigned
As described in the previous section, this example environment variable customizes the first Guest VM only, but other Guest VMs may be configured similarly (if they have been defined).
By default, the Build Modifier Config assigns the first PCI ethernet network
device (which has device ID 0000:01:00.0
) for exclusive use by the first
Guest VM.
Warning
The PCI device IDs configured for PCI passthrough are not validated as part of the EWAOL build system, and it is therefore the responsibility of the user to ensure that the device IDs are valid, and that multiple Guest VMs have not been assigned exclusive use of the same PCI device.
Other EWAOL Features
Developer Support
Corresponding value in
DISTRO_FEATURES
variable:ewaol-devel
.This EWAOL distribution image feature:
Is default if not set with any other EWAOL-specific
DISTRO_FEATURES
.Includes packages appropriate for development image builds, such as the
debug-tweaks
package, which sets an empty root password for simplified development access.
Run-Time Integration Tests
Corresponding value in
DISTRO_FEATURES
variable:ewaol-test
.Build Modifier Config:
meta-ewaol-config/kas/tests.yml
.This EWAOL distribution image feature:
Includes the EWAOL test suites provided to validate the image is running successfully with the expected EWAOL functionalities.
The Build Modifier for this distribution image feature automatically includes the Yocto Package Test (ptest) framework in the image, configures the inclusion of
meta-ewaol-tests
as a Yocto layer source for the build, and appends theewaol-test
feature toDISTRO_FEATURES
for the build.To include run-time integration tests on an EWAOL distribution image, provide the Build Modifier Config to the kas build command.
For example, to include the tests on an EWAOL distribution image for the N1SDP hardware target platform, run the following commands depending on the target architecture:
Baremetal architecture for N1SDP:
kas build meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/tests.yml:meta-ewaol-config/kas/n1sdp.yml
Virtualization architecture for N1SDP:
kas build meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/tests.yml:meta-ewaol-config/kas/n1sdp.yml
Each suite of run-time integration tests and specific customizable variables associated with each suite are detailed separately, at Run-Time Integration Tests.
Security Hardening
Corresponding value in
DISTRO_FEATURES
variable:ewaol-security
.Build Modifier Config:
meta-ewaol-config/kas/security.yml
.This EWAOL distribution image feature:
Configures user accounts, packages, remote access controls and other image features to provide extra security hardening for the EWAOL distribution image.
To include extra security hardening on an EWAOL distribution image, provide the Build Modifier Config to the kas build command, which appends the
ewaol-security
feature toDISTRO_FEATURES
for the build.For example, to include it on the EWAOL distribution image for the N1SDP hardware target platform, run the following commands depending on the target architecture:
Baremetal architecture for N1SDP:
kas build meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/security.yml:meta-ewaol-config/kas/n1sdp.yml
Virtualization architecture for N1SDP:
kas build meta-ewaol-config/kas/virtualization.yml:meta-ewaol-config/kas/security.yml:meta-ewaol-config/kas/n1sdp.yml
The security hardening is described in more detail at Security Hardening.
Software Development Kit (SDK)
Corresponding value in
DISTRO_FEATURES
variable:ewaol-sdk
.Build Modifier Config:
meta-ewaol-config/kas/baremetal-sdk.yml
andmeta-ewaol-config/kas/virtualization-sdk.yml
, for the baremetal architecture and virtualization architecture, respectively.This EWAOL distribution image feature:
Adds the EWAOL Software Development Kit (SDK) which includes packages and image features to support on-target software development activities.
Enables two additional SDK build targets,
ewaol-baremetal-sdk-image
andewaol-virtualization-sdk-image
, each only compatible with the corresponding architecture’s distribution image feature.The Build Modifier for this distribution image feature automatically appends
ewaol-sdk
toDISTRO_FEATURES
, and sets the appropriate build target with the necessary configuration from the relevant Architecture Config included by default, meaning it is not necessary to explicitly supply an Architecture Config to the kas build tool if passing an SDK Build Modifier Config.To include the SDK on an EWAOL distribution image, provide the appropriate SDK Build Modifier Config to the kas build command.
For example, to include the SDK on an EWAOL distribution image for the N1SDP hardware target platform, run the following commands depending on the target architecture:
Baremetal architecture for N1SDP:
kas build meta-ewaol-config/kas/baremetal-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
Virtualization architecture for N1SDP:
kas build meta-ewaol-config/kas/virtualization-sdk.yml:meta-ewaol-config/kas/n1sdp.yml
The SDK itself is described in more detail at Software Development Kit (SDK).
Additional Distribution Image Customizations
An additional set of customization options are available for EWAOL distribution images, which don’t fall under a distinct distribution image feature. These customizations are listed below, grouped by the customization target.
Filesystem Customization
Adding Extra Rootfs Space
The size of the root filesystem can be extended via the
EWAOL_ROOTFS_EXTRA_SPACE
BitBake variable, which defaults to 2000000
Kilobytes. The value of this variable is appended to the
IMAGE_ROOTFS_EXTRA_SPACE
BitBake variable.
For an EWAOL virtualization distribution image, additional variables are
provided which apply to the different root filesystems as described in
Virtualization Architecture Customization.
By default, the Control VM’s rootfs size is increased at build-time to support
the sum of all Guest VM rootfs sizes. The customizable
EWAOL_CONTROL_VM_ROOTFS_EXTRA_SPACE
variable therefore corresponds just to
the space allocated for the Control VM rootfs, in addition to the size necessary
to support the Guest VM(s). Increasing EWAOL_ROOTFS_EXTRA_SPACE
when
building an EWAOL virtualization distribution image increases
both the Guest VM(s) and Control VM rootfs size, which means that increasing
this variable will result in the Control VM rootfs size expanding by more than
the set value.
Filesystem Compilation Tuning
The EWAOL filesystem by default uses the generic armv8a-crc
tune for
aarch64
based target platforms. This reduces build times by increasing the
sstate-cache reused between different image types and target platforms. This
optimization can be disabled by setting EWAOL_GENERIC_ARM64_FILESYSTEM
to
"0"
. The tune used when EWAOL_GENERIC_ARM64_FILESYSTEM
is enabled can
be changed by setting EWAOL_GENERIC_ARM64_DEFAULTTUNE
, which configures the
DEFAULTTUNE
BitBake variable for the aarch64
based target platforms
builds. See DEFAULTTUNE for more information.
In summary, the relevant variables and their default values are:
EWAOL_GENERIC_ARM64_FILESYSTEM: "1" # Enable generic file system (1 or 0). EWAOL_GENERIC_ARM64_DEFAULTTUNE: "armv8a-crc" # Value of DEFAULTTUNE if generic file system enabled.
Their values can be set by passing them as environmental variables. For example, the optimization can be disabled using:
EWAOL_GENERIC_ARM64_FILESYSTEM="0" kas build meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/n1sdp.yml
Manual BitBake Build Setup
In order to build an EWAOL distribution image without the kas build tool directly via BitBake, it is necessary to prepare a BitBake project as follows:
Configure dependent Yocto layers in
bblayers.conf
.Configure the
DISTRO
asewaol
inlocal.conf
.Configure the image
DISTRO_FEATURES
, including the EWAOL Architecture (ewaol-baremetal
orewaol-virtualization
), inlocal.conf
.
Assuming correct environment configuration, the BitBake build can then be run for the desired image target corresponding to one of the following:
ewaol-baremetal-image
ewaol-baremetal-sdk-image
ewaol-virtualization-image
ewaol-virtualization-sdk-image
As the kas build configuration files within the meta-ewaol-config/kas/
directory define the recommended build settings for each feature. Any additional
functionalities may therefore be enabled by reading these configuration files
and manually inserting their changes into the BitBake build environment.