diff options
Diffstat (limited to 'bsp/meta-arm/meta-arm-autonomy/documentation')
5 files changed, 564 insertions, 0 deletions
diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md b/bsp/meta-arm/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md new file mode 100644 index 00000000..2a457c16 --- /dev/null +++ b/bsp/meta-arm/meta-arm-autonomy/documentation/arm-autonomy-quickstart.md @@ -0,0 +1,225 @@ +arm-autonomy Quick Start +================== + +This documentation is explaining how to quickly start with arm-autonomy layer +and the main features provided. +You will find in the documentation directory some more detailed documentation +for each of the functionalites provided by this layer. + +What to use this layer for? +--------------------------- +Using this layer, you can easily and rapidly create a system based on Xen with +one or more guests created using Yocto. + +For this you will need to create at least 2 Yocto projects: +- a host project: This one will compile Xen and create a Linux system to be + used as Xen Dom0. The Linux system will contain all functionalities required + to start and manage guests. +- one or several guest projects: Those will create Linux systems with the + required Linux kernel configuration to run as Xen DomU. + +Prepare your system +------------------- + +First you must download the Yocto layers needed: + - [meta-openembedded](https://git.openembedded.org/meta-openembedded) + - [poky](https://git.yoctoproject.org/poky) + - [meta-virtualization](https://git.yoctoproject.org/meta-virtualization) + - [meta-arm](https://git.yoctoproject.org/meta-arm) + - all other layers you might want to use + +For each of the downloaded layer make sure you checkout the release of Yocto +you want to use (for example zeus using `git checkout zeus`). + +Please follow [Yocto documentation](https://www.yoctoproject.org/docs/latest/brief-yoctoprojectqs/brief-yoctoprojectqs.html) +in order to have the required dependencies. + + +Create a project +---------------- + +Here are the main steps to create an arm-autonomy project: + +1. create a new Yocto project using `oe-init-build-env` in a new directory: + ``` + oe-init-build-env my-project + ``` + +2. Add `meta-arm/meta-arm-autonomy` layer to the list of layers of your + project in the `conf/bblayers.conf`. Also add any other layers you + might need (for example `meta-arm/meta-arm-bsp` and `meta-arm/meta-arm` to + use Arm boards like Juno or FVP emulator). You can achieve this by using + the `bitbake-layers add-layer layerdir [layerdir ...]` command. + For example: + ``` + export LAYERDIR_BASE="/home/user/arm-autonomy/" + bitbake-layers add-layer $LAYERDIR_BASE/meta-poky $LAYERDIR_BASE/meta-yocto-bsp \ + $LAYERDIR_BASE/meta-openembedded/meta-oe $LAYERDIR_BASE/meta-openembedded/meta-python \ + $LAYERDIR_BASE/meta-openembedded/meta-filesystems $LAYERDIR_BASE/meta-openembedded/meta-networking \ + $LAYERDIR_BASE/meta-virtualization $LAYERDIR_BASE/meta-arm/meta-arm-autonomy \ + $LAYERDIR_BASE/meta-arm/meta-arm $LAYERDIR_BASE/meta-arm/meta-arm-bsp + ``` + + Example of a `conf/bblayers.conf`: + ``` + BBLAYERS ?= " \ + /home/user/arm-autonomy/poky/meta \ + /home/user/arm-autonomy/poky/meta-poky \ + /home/user/arm-autonomy/poky/meta-yocto-bsp \ + /home/user/arm-autonomy/meta-openembedded/meta-oe \ + /home/user/arm-autonomy/meta-openembedded/meta-python \ + /home/user/arm-autonomy/meta-openembedded/meta-filesystems \ + /home/user/arm-autonomy/meta-openembedded/meta-networking \ + /home/user/arm-autonomy/meta-virtualization \ + /home/user/arm-autonomy/meta-arm/meta-arm-autonomy \ + /home/user/arm-autonomy/meta-arm/meta-arm \ + /home/user/arm-autonomy/meta-arm/meta-arm-bsp \ + " + ``` + +Those steps will have to be done for each project you will have to create. + +Host project +------------ +The host project will build Xen and the Dom0 Linux. It will be the only project +that will be specific to the board (MACHINE) you will be running on. + +To create a host project: +1. Follow the steps of "Create a project" + +2. Add the layers in `bblayers.conf` required to build a Yocto project for the + board you want to use. + For example to use Arm FVP Base emulator, add `meta-arm/meta-arm` and + `meta-arm/meta-arm-bsp`. + +3. edit conf/local.conf to add `arm-autonomy-host` to the DISTRO_FEATURES and + set MACHINE to the board you want to use. + For example, add the following lines: + ``` + MACHINE = "fvp-base" + DISTRO_FEATURES += "arm-autonomy-host" + ``` + +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 +in meta-arm-autonomy to include only the Linux configuration required to run +a xen guest. + +To create a guest project: + +1. Follow the steps of "Create a project" + +2. Optionaly add layers required to build the image and features you need. + +3. edit conf/local.conf to add `arm-autonomy-guest` to the DISTRO_FEATURES and + set MACHINE to `arm64-autonomy-guest`: + ``` + MACHINE = "arm64-autonomy-guest" + DISTRO_FEATURES += "arm-autonomy-guest" + ``` + +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. + diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md b/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md new file mode 100644 index 00000000..a44dca78 --- /dev/null +++ b/bsp/meta-arm/meta-arm-autonomy/documentation/xen-devicetree.md @@ -0,0 +1,104 @@ +Xen device tree +=============== + +Introduction +------------ + +xen-devicetree recipe can be used to modify an existing Device Tree Blob, +produced by Linux kernel or another recipe, to include in it entries required +to start Xen and a Dom0 Linux on top of it. + +The recipe will do the following processing: +- generate a xen.dtsi file with entries required for xen based on parameters +- turn DTBs in ${XEN_DEVICETREE_DTBS} back to dts +- include in xen.dtsi and all other dtsi from + ${XEN_DEVICETREE_DTSI_MERGE} (check Bitbake parameters for more information + on this). +- use dtc to create a new DTB file + +The recipe will generate new files in deploy/images and name them with the +extension "-xen.dtb". +For example **machine.dtb** will generate **machine-xen.dtb**. + +Entries added to the DTBs +------------------------- + +When a DTB is processed by the recipe, the following block is added: +``` + chosen { + xen,dom0-bootargs = "VAL"; + xen,xen-bootargs = "VAL"; + + modules { + #size-cells = <0x00000001>; + #address-cells = <0x00000001>; + + module@0 { + reg = <VAL VAL>; + compatible = "multiboot,module"; + }; + }; + }; +``` +Each occurence of **VAL** is replaced by the content of the variables listed in +this documentation. + +Bitbake parameters +------------------ + +Several parameters are available to configure the xen-devicetree during Yocto +project compilation (those can be set in your project local.conf, for exmple). + +The following parameters are available: + +- XEN_DEVICETREE_DEPEND: This variable can be used to indicate which recipe + task is generating the DTBs that xen-devicetree will modify. This makes sure + the xen devicetrees are properly regenerated if the source DTBs are changed. + This variable is set by default to "virtual/kernel:do_deploy" to use DTBs + generated during the compilation of the Linux kernel. This must be changed + if the machine your are using is not using a DTB listed in KERNEL_DEVICETREE. + +- XEN_DEVICETREE_DTBS: This should be set to the list of DTBs you want to be + modified by xen-devicetree. Those must be files that xen-devicetree can find + in the ${DEPLOY_DIR_IMAGE} directory using only the basename of the entries. + For example "mydir/board.dtb" will make the recipe look for + ${DEPLOY_DIR_IMAGE}/board.dtb. + This variable is set by default to "${KERNEL_DEVICETREE}" to process the DTBs + generated by the Linux kernel. + +- XEN_DEVICETREE_DOM0_MEM: Memory size to allocate to Dom0. + This variable is only used if XEN_DEVICETREE_XEN_BOOTARGS has a value + containing "dom0_mem=${XEN_DEVICETREE_DOM0_MEM}" as the memory assigned to + dom0 is defined using Xen boot arguments. + This variable is set by default to "1024M". + +- XEN_DEVICETREE_DOM0_BOOTARGS: Boot arguments to pass to Dom0 Linux when + booting it. + This variable is set by default to "console=hvc0 earlycon=xen". + +- XEN_DEVICETREE_XEN_BOOTARGS: this variable should be set with the boot + arguments to be passed to Xen on boot. + This variable is set by default to + "noreboot dom0_mem=${XEN_DEVICETREE_DOM0_MEM}". + +- XEN_DEVICETREE_DOM0_ADDR: This is the address from which the Linux kernel to + be used for Dom0 will be copied. When using u-boot, this is the address at + which you will load the kernel Image before starting Xen. + This variable is set by default to "0x80080000". + +- XEN_DEVICETREE_DOM0_SIZE: This is the size of the kernel loaded at + ${XEN_DEVICETREE_DOM0_ADDR}. Xen will copy this amount of data inside the + guest before starting it so the size must be at least equal to the kernel + size but can be bigger. You must be careful not to have a value too big as it + could slow down boot or copy other parts with it (like the DTB). + You might need to increase this if you use a kernel with a bundled initramfs. + This variable is set by default to "0x01000000". + +- XEN_DEVICETREE_DTSI_MERGE: This variable contains the list of dtsi files that + must be included inside the generated DTB file. By default the only one + include is the "xen.dtsi" generated by the recipe. + If your board or project needs to include more fixes or entries in the DTB, + this variable can be appended from a bbappend file to include other dtsi. The + files must be inside the recipe workspace during Yocto compilation. + You can check xen-devicetree.bbappend for an example. + diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-manager.md b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-manager.md new file mode 100644 index 00000000..387af944 --- /dev/null +++ b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-manager.md @@ -0,0 +1,67 @@ +Xenguest Manager +================ + +Introduction +------------ + +xenguest-manager is a tool to manage Xenguest images generated by +[xenguest-mkimage](xenguest-mkimage.md). + +On a Xen Dom0 system it will: +- create a xen guest from a xenguest image: extract its components, create a + disk for the guest using LVM volumes. +- start/stop a xen guest (during init or using xenguest-manager directly). +- check guest status + +xenguest-manager is composed of 2 shell scripts: +- xenguest-manager which can be used from command line to start/stop/check +guests and create or remove guest using xenguest images. +- xenguest-init which is called during init to automatically create and start +some guests as part of the host init process. + +Usage +----- + +xenguest-manager must be called like this: +`xenguest-manager OPERATION [OPTIONS]` +The following operations are available: +- create XENGUEST_IMAGE [GUESTNAME]: create a guest from a xenguest image file + as guest GUESTNAME. If GUESTNAME is not given the image file name is used + without the xenguest extension. +- remove GUESTNAME: remove the guest GUESTNAME. +- start GUESTNAME: start the guest GUESTNAME. +- stop GUESTNAME: stop the guest GUESTNAME (this is using `xl stop` which is + sending a stop signal to the running guest). +- kill GUESTNAME: force stopping the guest GUESTNAME. +- list: list the available guests. +- status [GUESTNAME]: print the current status of GUESTNAME. If GUESTNAME is + not given, print the status of all guests. + +For a detailed help on available options please use: +`xenguest-manager --help` + +Bitbake parameters +------------------ + +Several parameters are available to configure the xenguest manager during Yocto +project compilation (those can be set in your project local.conf, for example). + +The following parameters are available: + +- XENGUEST_MANAGER_VOLUME_DEVICE: This is the device path used by the + xenguest-manager on the device to create LVM disks when guests have a disk + configuration. + This is set by default to "/dev/sda2". + +- XENGUEST_MANAGER_VOLUME_NAME: This is the LVM volume name that the + xenguest-manager will create and use to create guest LVM disks. + This is set by default to "vg-xen". + +- XENGUEST_MANAGER_GUEST_DIR: This is the directory on Dom0 where the + xenguest-manager will look for xenguest images to create during init. That's + the place where xenguest images can be added to have them automatically + created during next Dom0 boot. The xenguests found there will only be created + if they were not already before (the basename of the files is used as guest + name). + This is set by default to "/usr/share/guests". + diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-mkimage.md b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-mkimage.md new file mode 100644 index 00000000..3dcc28b4 --- /dev/null +++ b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-mkimage.md @@ -0,0 +1,119 @@ +Xenguest mkimage +================ + +Introduction +------------ + +xenguest-mkimage is a tool to create and modify images to be used as Guest with +Xen. It defines a format to store completely defined guests as a file or as +a directory and provides options to create and modify those images. + +A xenguest image contains all elements required to create a xen guest. +This is the base elements like a Xen configuration and a Linux kernel binary +but also some more advanced elements like init scripts or a disk definition. + +The format is made to be deployable easily by storing everything in a single +file and provide tools to easily manipulate the images. It can also easily be +extended to have features like encryption or signature of images, updates or +complex configurations by providing features to have init script that will be +executed on the host embedded inside the image. + +Xenguest images content +----------------------- + +### params.cfg + +This file contains parameters that can be used by tools to configure some +functionalities on the host. This can be used by init scripts to have +configurable parameters as it is sourced before calling init scripts. + +### guest.cfg and guest.d + +guest.cfg is the main xen configuration and guest.d contains optional +configuration parts. All those will be merged into one final xen configuration +before starting the guest. + +### files +This directory contains files that can be used by the xen configuration, for +example the binary of the kernel referenced in xen configuration). +This is where the kernel binary, the dtb or a ramdisk will be stored. + +### init.pre, init.d and init.post +These directories contain init scripts that will be executed on the host +during the guest startup. Those must be shell scripts and each directory +contains scripts called at a different time: + - init.pre: scripts executed before the guest is created. This can be used + to prepare some features required to create the guest in xen or to + generate part of the xen configuration dynamically. + - init.d: scripts executed when the guest has been created but before it is + started. This can be used to do some xenstore operations or configure the + guest behaviour using xl, for example. + - init.post: scripts executed just after starting the guest. This can be + used to configure things created by xen for the guest like network + network interfaces. + +When a directory contains several scripts, those will be called in alphabetical +order. + +### disk.cfg and disk-files +disk.cfg contains the guest disk description (disk size and disk partitions). +The file contains the following entries: +- `DISK_SIZE=X`: size of the disk to create in GB +- `DISK_PARTX=SIZE:FS:CONTENT`: create a partition number X (1 to 4) with a + size of SIZE GB, format it with filesystem FS (can be ext2, ext3, ext4, vfat + or swap) and extract CONTENT as initial partition content + (.tar[.gz|.xz|.bz2] file or img[.gz|.bz2] file to be dumped in the partition). FS and + CONTENT can be empty. + +The disk-files contain files to be used for initializing the disk partitions +content. Those should be used to create a LVM or a physical disk and initialize +it (create partitions, format them and put the initial content). + +Usage +----- + +xenguest-mkimage is a shell script which must be called like this: +`xenguest-mkimage OPERATION XENGUEST [OPTIONS]` + +### Operations +- create: create a xenguest image. If XENGUEST is an existing empty directory, + the image is created as a directory otherwise it will be created as a file. +- check: verify that XENGUEST is a valid xenguest image. +- update: modify a xenguest image (see --help for a list of operations). +- pack: pack a xenguest image directory into a xenguest image file. The file to + be created must be given as 3rd argument. +- extract: extract a xenguest image file into a directory. The destination + directory must be given as 3rd argument. +- dump-xenconfig: dump xenguest image xen configuration. +- dump-diskconfig: dump xenguest image disk configuration. +- dump-paramsconfig: dump xenguest image parameters configuration. + +For a detailed help on available operations, please use: +`xenguest-mkimage --help` + +### Options +- --kernel=FILE: add kernel FILE as guest kernel. This is both adding the file + to the image and modifying the xen configuration to use it. +- --xen-memory=SIZE: set the guest memory size in MB. +- --xen-extra: add a kernel command line argument. This can be called several + times to add several command line options. +- --xen-device-tree=FILE: add dtb FILE as device tree. This both adding the + file to the image and modifying the xen configuration to use it. +- --init-script=FILE: add guest init script. The script is embedded inside the + image file. Several script can be added and the basename of FILE is used to + distinguish them (calling the option twice with the same file will update the + script in the image with the second one). + --disk-size=SIZE: set the guest disk size to SIZE in GB. Calling this with 0 + disable the guest disk. +- --disk-add-part=NUM:SIZE:FS:CONTENT: This is adding a partition to the + xenguest image disk. The partition is described with the arguments: + - NUM: partition number. + - SIZE: partition size in GB. + - FS: filesystem to format the partition with. This can be ext2, ext3, ext4, + vfat of swap. If empty the partition is not formated. + - CONTENT: tar of img file to use to initialize the partition. The file must + be added to the image using --disk-add-file=FILE:CONTENT. + +For a detailed help on available options, please use: +`xenguest-mkimage OPERATION --help` + diff --git a/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-network-bridge.md b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-network-bridge.md new file mode 100644 index 00000000..6653fe81 --- /dev/null +++ b/bsp/meta-arm/meta-arm-autonomy/documentation/xenguest-network-bridge.md @@ -0,0 +1,49 @@ +xenguest network bridge +======================= + +Introduction +------------ + +xenguest-network-bridge is creating a network bridge to allow some guests to +have a direct connection to the external network. +To do this, a bridge is created on the host using brctl with the network +interfaces added to it so that the bridge is connected to the external network. +It is also adding a guest init script which will, for guests configured to use +it, create a virtual network interface for the guest and connect it to the +network bridge on the host. + +Usage +----- + +On the host the package xenguest-network-bridge must be included in your image. + +On the xenguest image of your guest, the parameter NETWORK_BRIDGE must be set +to 1 (using xenguest-mkimage --set-param=NETWORK_BRIDGE=1). + +Bitbake parameters +------------------ +Several parameters are available to configure the xenguest network bridge +during Yocto project compilation (those can be set in your project local.conf, +for example). + +The following parameters are available: + +- XENGUEST_NETWORK_BRIDGE_NAME: This variable defines the name of the network + bridge that is created on the host during init. + This is set by default to "xenbr0". + +- XENGUEST_NETWORK_BRIDGE_MEMBERS: This variable defines the list of network + interfaces that are added to the bridge when it is created on the host during + init. + This is set by default to "eth0". + +- XENGUEST_NETWORK_BRIDGE_CONFIG: This variable defines the configuration file + to use to configure the bridge network. By default it points to have file + configuring the network using dhcp. + You can provide a different file using a bbappend and make this variable + point to it if you want to customize your network configuration. + +- XENGUEST_IMAGE_NETWORK_BRIDGE: This variable can be set to 0 or 1 on guest + projects to enable or not the connection of the guest to the host bridge. + This is set by default to "1". + |