[meta-arm,2/2] arm-autonomy/arm-autonomy-host-image-minimal: Added multiconfig support

Submitted by Nathan Dunne on Nov. 17, 2020, 12:59 p.m. | Patch ID: 178108

Details

Message ID 20201117125921.13879-2-Nathan.Dunne@arm.com
State New
Headers show

Commit Message

Nathan Dunne Nov. 17, 2020, 12:59 p.m.
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
---
 .../documentation/arm-autonomy-multiconfig.md | 161 ++++++++++++++++++
 .../documentation/arm-autonomy-quickstart.md  |   3 +
 .../images/arm-autonomy-host-image-minimal.bb |  18 ++
 3 files changed, 182 insertions(+)
 create mode 100644 meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md

-- 
2.17.1
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1387): https://lists.yoctoproject.org/g/meta-arm/message/1387
Mute This Topic: https://lists.yoctoproject.org/mt/78314968/1003190
Group Owner: meta-arm+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/meta-arm/unsub [mhalstead@linuxfoundation.org]
-=-=-=-=-=-=-=-=-=-=-=-

Patch hide | download patch | download mbox

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 0000000..8c33501
--- /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 13b588f..2aa42d3 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 47a07cd..74e37ca 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
@@ -50,6 +50,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'")