From ad6a6758177d9ac9290048c1d8073fca4c0c102e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 27 Mar 2020 10:55:13 +0000 Subject: [PATCH] arm-autonomy: Update quick start guide Add more documentation to the quick start guide: - to include guests images in host image - to boot the host image - to adapt the layer to new boards Change-Id: I07ff13190daf404476d28803f43f330fc190cddc Issue-Id: SCM-767 Signed-off-by: Bertrand Marquis Reviewed-by: Diego Sueiro Reviewed-by: Vineeth Raveendran Signed-off-by: Jon Mason --- .../documentation/arm-autonomy-quickstart.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md b/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md index 2b92996a..c6886004 100644 --- a/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md +++ b/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md @@ -91,6 +91,19 @@ To create a host project: 4. build the image using `bitbake arm-autonomy-host-image-minimal` +The project will generate a Linux kernel, a root filesystem, a Xen binary and +a DTB modified to include the required entries to boot Xen and Linux as Dom0 +(this DTB has the extension `-xen.dtb`). + +To boot the system using an u-boot base board you will need to: +- Load the kernel (by default at 0x80080000 unless you modify + XEN_DEVICETREE_DOM0_ADDR value) +- Load the xen device tree (for example at 0x83000000) +- Load the xen-efi binary (for example at 0x84000000) +- run using `booti 0x84000000 - 0x83000000` + +In this example the addresses might need to be adapted depending on your board. + Guest project ------------- The guest projects are not target specific and will use a Yocto MACHINE defined @@ -113,4 +126,89 @@ To create a guest project: 4. build the image you want. For example `bitbake core-image-minimal` +The build will create a ".xenguest" image that can be use on an host project +with the xenguest-manager. + +Include guests directly in the host image +----------------------------------------- +The layer provides a way to directly include in the host project one or several +images generated by guest projects. + +To use this feature, you must edit your host project `local.conf` file and +add set ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS to the list of xenguest images +you want to include in your host. Each xenguest image must be given using a +full path to it. +For example: +``` +ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS = "/home/user/guest-project/tmp/deploy/images/arm64-autonomy-guest/core-image-minimal-arm64-autonomy-guest.xenguest;guestname=myguest" +``` +This will add the guest and name it `myguest` on the host project image and +the xenguest-manager will automatically boot it during startup. + +Add support for your board +-------------------------- +Most of arm-autonomy layer is board independent but some functionalities +might need to be customized for your board: + +### Add the kernel configuration for the host +The layer is using KERNEL_FEATURES to add drivers required to be a Xen Dom0 +system. +Depending on the kernel used by your BSP and how it is configured you might +need to add the required drivers to your kernel configuration: +- if KERNEL_FEATURES system is supported by your kernel, make sure that the +file `recipes-kernel/linux/linux-arm-autonomy.inc` from the layer is included +by your kernel recipe. +- if it is not supported, you must add the proper drivers inside your kernel +(modules are possible but they must be loaded before xenguest-manager is +started). You can find the complete list of the kernel configuration elements +required in `recipes-kernel/linux/arm-autonomy-kmeta/features/arm-autonomy/xen-host.cfg`. + +### Define the drive and partition to use for the LVM volume +The xenguest-manager is creating disk hard drive using LVM on an empty +partition. The default value is set to use /dev/sda2. +You can change this for your board by setting XENGUEST_MANAGER_VOLUME_DEVICE. + +Check `recipes-extended/xenguest/xenguest-manager.bbappend` for examples. + +Please also read xenguest-manager.md. + +### Define the interface to add to xenguest network bridge +xenguest-network bridge is creating a bridge on the host and adds network +interfaces to it so that guest connected to it have access to external network. +By default `eth0` is set as the list of interfaces to be added to the bridge. +Depending on your board or use case you might want to use an other interface +or use multiple interfaces. +You can change this for your board by setting XENGUEST_NETWORK_BRIDGE_MEMBERS. + +Check `recipes-extended/xenguest/xenguest-network-bridge.bbappend` for +exmaples. + +Please also read xenguest-network-bridge.md. + +### Define the network configuration of the xenguest network bridge +xenguest network bridge is putting the host network interfaces in a bridge +and is configuring it by default to use dhcp. +If you need a different type of configuration you can set +XENGUEST_NETWORK_BRIDGE_CONFIG in a xenguest-network-bridge.bbappend to use +a different file. +The recipe will look for the file in ${WORKDIR} so you will need to add it to +SRC_URI in your bbappend. +The recipe will also substitute `###BRIDGE_NAME###` with the bridge name +configured in ${XENGUEST_NETWORK_BRIDGE_NAME}. + +You can find an example configuration file in +`recipes-extended/xenguest/files/xenguest-network-bridge-dhcp.cfg.in`. + +Please also read xenguest-network-bridge.md. + +### Customize Dom0 and Xen boot arguments for you board +xen-devicetree is writting inside the generated DTB Xen and Linux boot +arguments as long as the address where Dom0 Linux kernel can be found. +You might need to have different values for your board or depending on your +use case. + +You can find examples to customize this in +`recipes-extended/xen-devicetree/xen-devicetree.bbappend`. + +Please also read xen-devicetree.md.