diff --git a/meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md b/meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md new file mode 100644 index 00000000..8c335014 --- /dev/null +++ b/meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md @@ -0,0 +1,161 @@ +arm-autonomy Multiconfig Build Environment Instructions +================== + +This documentation explains how to simplify the process of building hosts +and guests in a single bitbake command, rather than in seperate build +folders. You can read more about multiconfig in the bitbake documentation: + + - [bitbake user manual](https://www.yoctoproject.org/docs/latest/bitbake-user-manual/bitbake-user-manual.html) + +To achieve a multiconfig build, a number of different config files need to +be created in a single build directory. + +Create a new project +---------------- + +Before you start, you will need to follow the instructions in +"Create a project" from the quickstart guide, to create a new project +directory with + ``` + oe-init-build-env my-mc-project + ``` +Ensure it has all the required layers in bblayers.conf as listed in +`arm-autonomy-quickstart.md`. The result should be a directory containing: + +``` +-- conf + | -- bblayers.conf + | -- local.conf + | -- templateconf.cfg +``` + +Add multiconfig +---------------- + +Here are the steps required to make the project build both the host and any +number of guests as required. + +1. Create a new directory under `conf/` named `multiconfig/` + +2. Create two new files in this directory: +`multiconfig/host.conf` +`multiconfig/guest.conf` +These files will contain any configurations that a specific to either the +host or the guest + +``` +-- conf + | -- bblayers.conf + | -- local.conf + | -- templateconf.cfg + | -- multiconfig + | -- host.conf + | -- guest.conf +``` + +3. In `local.conf` the following config variables must be added: + +``` +MACHINE ?= "fvp-base" + +# ---Guest Config Start--- # +MC_GUEST = "guest" + +MC_GUEST_NAME = "guest1" + +MC_GUEST_IMAGERECIPE = "core-image-minimal" +MC_GUEST_MACHINE = "arm64-autonomy-guest" + +MC_GUEST_INITRAMFS_IMAGE_BUNDLE ?= "" +MC_GUEST_INITRAMFS_IMAGE ?= "" + +# Uncomment for initramfs +#MC_GUEST_INITRAMFS_IMAGE_BUNDLE = "1" +#MC_GUEST_INITRAMFS_IMAGE = "${MC_GUEST_IMAGERECIPE}" + +# These variables are set automatically, don't edit them! +MC_GUEST_FILENAME_PREFIX = "${@ 'Image-initramfs' if d.getVar('MC_GUEST_INITRAMFS_IMAGE_BUNDLE',d) else '${MC_GUEST_IMAGERECIPE}' }" + +MC_GUEST_FILENAME = "${MC_GUEST_FILENAME_PREFIX}-${MC_GUEST_MACHINE}.xenguest" + +MC_GUEST_DEP = "${@ 'virtual/kernel:do_deploy' if d.getVar('MC_GUEST_INITRAMFS_IMAGE_BUNDLE',d) else '${MC_GUEST_IMAGERECIPE}:do_image_complete'}" + +MC_DOIMAGE_MCDEPENDS += "mc:${MC_HOST}:${MC_GUEST}:${MC_GUEST_DEP} " + +BBMULTICONFIG += "${MC_GUEST} " + +ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS += "file://${TOPDIR}/${MC_GUEST}/deploy/images/${MC_GUEST_MACHINE}/${MC_GUEST_FILENAME};guestname=${MC_GUEST_NAME} " +# ---Guest Config End--- # + +# ---Host Config Start--- # +MC_HOST = "host" + +BBMULTICONFIG += "${MC_HOST} " +# ---Host Config End--- # +``` + +These variables will be used in both of the multiconf files. `MC_HOST` and +`MC_GUEST` should not be altered without renaming the conf files, but most +`MC_GUEST_*` variables can be customised if you desire. + +4. Next set the contents of `multiconfig/guest.conf`: + +``` +TMPDIR = "${TOPDIR}/${MC_GUEST}" + +MACHINE = "${MC_GUEST_MACHINE}" +DISTRO_FEATURES += " arm-autonomy-guest" + +INITRAMFS_IMAGE_BUNDLE = "${MC_GUEST_INITRAMFS_IMAGE_BUNDLE}" +INITRAMFS_IMAGE = "${MC_GUEST_INITRAMFS_IMAGE}" + +IMAGE_FSTYPES += "${@ 'cpio' if d.getVar('MC_GUEST_INITRAMFS_IMAGE_BUNDLE',d) else ''}" + +# ANY OTHER GUEST CONFIG +``` + +This contents shouldn't be changed directly, rather change the equivalent +config in local.conf. You can append any other config desired for the +guest at this point, for example `XENGUEST_IMAGE_DISK_SIZE` + +Make sure not to change `${DEPLOY_DIR_IMAGE}` to anything other than +`${TMPDIR}/deploy/images`, as this is assumed by local.conf. + +5. Lastly set the contents of `multiconfig/host.conf`: + +``` +TMPDIR = "${TOPDIR}/${MC_HOST}" + +DISTRO_FEATURES += " arm-autonomy-host" +``` + +Building the image +---------------- + +To build the multiconfig image the command is: +``` +bitbake mc:host:arm-autonomy-host-image-minimal +``` + +You should see that this triggers guest tasks to be built in +parallel. Once the build completes the guest will already be in the +rootfs of the host thanks to `ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUEST` + +The deployed image including the guest will be in `host/deploy/images/` + + +Multiple Guests +---------------- + +To have multiple guests with the same config the line which appends to +`ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUEST` just needs to be duplicated with +a different guestname. + +To have different config for each guest, each will need its own config +file similar to guest.conf, ensuring TMPDIR is set to a different path, +and everything between `---Guest Config Start---` and +`---Guest Config End---` will need to be duplicated. + +Any copies of variables that start `MC_GUEST` must be altered to avoid +collisions (e.g. `MC_GUEST_2_*`), and the name of the conf file must also +be added to BBMULTICONFIG. diff --git a/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md b/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md index 13b588f8..2aa42d3c 100644 --- a/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md +++ b/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md @@ -147,6 +147,9 @@ To create a guest project: The build will create a ".xenguest" image that can be use on an host project with the xenguest-manager. +The guest can also be built as a 'multiconfig' sub project of the host, see +`meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md` for more information + Include guests directly in the host image ----------------------------------------- The layer provides a way to directly include in the host project one or several diff --git a/meta-arm-autonomy/recipes-core/images/arm-autonomy-host-image-minimal.bb b/meta-arm-autonomy/recipes-core/images/arm-autonomy-host-image-minimal.bb index 0a90abb4..50378b14 100644 --- a/meta-arm-autonomy/recipes-core/images/arm-autonomy-host-image-minimal.bb +++ b/meta-arm-autonomy/recipes-core/images/arm-autonomy-host-image-minimal.bb @@ -54,6 +54,24 @@ EXTRA_IMAGEDEPENDS += "xen" # Build xen-devicetree to produce a xen ready devicetree EXTRA_IMAGEDEPENDS += "xen-devicetree" +# Documentation for setting up a multiconfig build can be found in: +# meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md + +# In a multiconfig build this variable will hold a dependency string, which differs based +# on whether the guest has initramfs or not. +# It may have a space seperated list of dependency strings if mulitple guest types are +# configured +MC_DOIMAGE_MCDEPENDS ?= "" +# Example value: mc:host:guest:core-image-minimal:do_image_complete + +# In a multiconfig build the host task 'do_image' has a dependency on multiconfig guest. +# This ensures that the guest image file already exists when it is needed by the host +DO_IMAGE_MCDEPENDS := "${@ '${MC_DOIMAGE_MCDEPENDS}' if d.getVar('BBMULTICONFIG') else ''}" + +# Apply mc dependency. Empty string if multiconfig not enabled +do_image[mcdepends] += "${DO_IMAGE_MCDEPENDS}" + + python __anonymous() { if bb.utils.contains('DISTRO_FEATURES', 'arm-autonomy-host', False, True, d): raise bb.parse.SkipRecipe("DISTRO_FEATURES does not contain 'arm-autonomy-host'")