[PATCH] arm-autonomy: Update quick start guide

* [PATCH] arm-autonomy: Update quick start guide
@ 2020-03-27 10:55 Bertrand Marquis
  2020-03-27 15:31 ` [meta-arm] " Diego Sueiro
  0 siblings, 1 reply; 3+ messages in thread
From: Bertrand Marquis @ 2020-03-27 10:55 UTC (permalink / raw)
  To: meta-arm; +Cc: nd

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 <bertrand.marquis@arm.com>
---
 .../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 2b92996..c688600 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.
 
-- 
2.17.1


^ permalink raw reply related	[flat|nested] 3+ messages in thread