arm-autonomy/arm-autonomy-host-image-minimal: Added multiconfig support

Added new documentation file arm-autonomy-multiconfig.md which explains how to set up a multiconfig build, where both the host and guest are built simultaneously in the same build dir. To enable this feature the dependency between host and guest is set in the image recipe, using the variables described in the documentation. Issue-Id: SCM-638 Signed-off-by: Nathan Dunne <Nathan.Dunne@arm.com> Change-Id: Iae315c128dc6d2b39281312bc1a2ab9b88f6241e Signed-off-by: Jon Mason <jon.mason@arm.com>
2026-05-07 04:58:57 +00:00 · 2020-11-17 12:59:21 +00:00
parent 42c4ba9c96
commit 214ec04498
3 changed files with 182 additions and 0 deletions
@@ -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.
@@ -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
@@ -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'")