mirrors/meta-arm
1
0
Fork 0
mirror of https://git.yoctoproject.org/meta-arm synced 2026-06-02 01:20:09 +00:00
Code Issues Projects Releases Wiki Activity

autonomy/docs: Documentation updates and fixes

Browse Source 
Issue-Id: SCM-2038
Signed-off-by: Nathan Dunne <Nathan.Dunne@arm.com>
Change-Id: Ida94958b63c78097be6402be019d65a80260f297
Signed-off-by: Jon Mason <jon.mason@arm.com>
This commit is contained in:
Nathan Dunne
2021-03-31 09:25:56 +01:00
committed by Jon Mason
parent a52d805faf
commit f65c5c4217
15 changed files with 204 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md
+54 -25
View File
@@ -32,16 +32,16 @@ Ensure it has all the required layers in bblayers.conf as listed in
Add multiconfig
----------------
Here are the steps required to make the project build both the host and any
number of guests as required.
The steps required to make the project build both the host and any
number of guests as required are:
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
These files will contain any configurations that are specific to either the
host or the guest. The resulting directory tree should be:
```
-- conf
@@ -73,7 +73,7 @@ MC_GUEST_INITRAMFS_IMAGE ?= ""
#MC_GUEST_INITRAMFS_IMAGE_BUNDLE = "1"
#MC_GUEST_INITRAMFS_IMAGE = "${MC_GUEST_IMAGERECIPE}"
# These variables are set automatically, don't edit them!
# These variables are set automatically, don't override 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"
@@ -114,9 +114,10 @@ IMAGE_FSTYPES += "${@ 'cpio' if d.getVar('MC_GUEST_INITRAMFS_IMAGE_BUNDLE',d) el
# 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`
To modify the MACHINE or INITRAMFS variables change the equivalent
config in local.conf rather than modifying this file directly. You can also
append any other config desired for the guest after "ANY OTHER GUEST CONFIG",
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.
@@ -127,6 +128,8 @@ Make sure not to change `${DEPLOY_DIR_IMAGE}` to anything other than
TMPDIR = "${TOPDIR}/${MC_HOST}"
DISTRO_FEATURES += " arm-autonomy-host"
# ANY OTHER HOST CONFIG
```
Building the image
@@ -137,31 +140,56 @@ 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 first time this is run you may see a warning related to the SRC_URI:
```
Unable to get checksum for xenguest-extern-guests SRC_URI entry foo.xenguest: file could not be found
```
The deployed image including the guest will be in `host/deploy/images/`
This is expected, and only indicates that the guest image has not yet been
generated when the host parses the SRC_URI. By the time it is needed by the
host recipe fetch task it will be present.
During the build you should see that guest tasks are also being executed 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 final host image including the guests will be deployed 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.
`ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS` just needs to pass the argument
'guestcount=#' to install symlink copies of the xenguest file on the host.
Documentation for the guestcount parameter can be found in
documentation/arm-autonomy-quickstart.md in the section titled
'Include guests directly in the host image'. This will ensure that the guest
is still only built once, despite resulting in multiple copies on the target.
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. Ensure that the name
of the multiconfig conf file does not contain any hyphens (-), since this
will create errors when it becomes part of a function name.
If guests are required to have different configurations, each will need its own
config file, e.g. 'netguest.conf'. Ensure that the name of the conf file does
not contain any hyphens, as this will create errors when it becomes part of a
function name. In this file the values of TMPDIR, MACHINE, DISTRO_FEATURES etc.
should be the same as above, but with the prefix "MC_GUEST_*" modified to
something different to avoid collisions (e.g. MC_GUEST_2_*).
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.
As before, your additional config for the guest type should
follow "ANY OTHER GUEST CONFIG"
In your local.conf, everything between `---Guest Config Start---` and
`---Guest Config End---` will need to be duplicated for each desired guest type.
All copies of variables that start `MC_GUEST` must be modified with the same
prefix as in the new guest config file (e.g. `MC_GUEST_2_*`).
Each chunk of guest config in local.conf has automatic guest variables
(found after the line "These variables are set automatically...").
These should all use the same prefix as their chunk in their values,
for example:
```
MC_GUEST_2_FILENAME_PREFIX = "${@ 'Image-initramfs' if d.getVar('MC_GUEST_2_INITRAMFS_IMAGE_BUNDLE',d) else '${MC_GUEST_2_IMAGERECIPE}' }"
```
Guest with provisioned disk
----------------
@@ -174,11 +202,12 @@ AUTONOMY_HOST_EXTRA_PARTITION = "part --label provisioned-guest --source rawcopy
--sourceparams=file=${TOPDIR}/${MC_GUEST}/deploy/images/${MC_GUEST_MACHINE}/${MC_GUEST_FILENAME_PREFIX}-${MC_GUEST_MACHINE}.ext4"
```
inside host.conf file.
inside your host.conf file.
The rest of the configuration has to be appended to guest.conf file:
```
# ANY OTHER GUEST CONFIG
XENGUEST_IMAGE_DISK_SIZE = "0"
XENGUEST_IMAGE_SRC_URI_XEN_CONFIG = "file://\${TOPDIR}/path/to/rootdisk.cfg"
XENGUEST_IMAGE_DISK_DEVICE = "_GUEST_DISK_DEVICE_"
@@ -187,7 +216,7 @@ IMAGE_ROOTFS_SIZE = "102400"
IMAGE_FSTYPES = "ext4"
```
content of rootdisk.cfg"
Example content of rootdisk.cfg:
```
disk = ["phy:_GUEST_DISK_DEVICE_,xvda,w"]
meta-arm-autonomy/documentation/arm-autonomy-quickstart.md
+68 -33
View File
@@ -1,9 +1,9 @@
arm-autonomy Quick Start
==================
This documentation is explaining how to quickly start with arm-autonomy layer
This documentation explains how to quickly start with the arm-autonomy layer,
and the main features provided.
You will find in the documentation directory some more detailed documentation
In the documentation directory you will find some more detailed documentation
for each of the functionalites provided by this layer.
What to use this layer for?
@@ -110,7 +110,8 @@ 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:
To boot the system using a u-boot base board for machines other than FVP-Base
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)
@@ -119,54 +120,88 @@ To boot the system using an u-boot base board you will need to:
In this example the addresses might need to be adapted depending on your board.
For arm-autonomy host on FVP-Base u-boot has been modified such that
For arm-autonomy host on FVP-Base, u-boot has been modified such that
`booti 0x84000000 - 0x83000000` is the default boot command. If FVP-Base is your
MACHINE target there should be no need to interfere with u-boot.
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.
The guest projects are not target specific and will instead 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.
2. Optionally add layers required to build the guest image, and any features you
need.
3. edit conf/local.conf to add `arm-autonomy-guest` to the DISTRO_FEATURES and
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.
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, as well as a file "xenguest.env" containing the
variables used to configure the guest image.
variables used to configure and generate the guest image.
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
`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
images generated by guest projects.
The layer provides a way to directly include one or more images generated by
guest projects in the host project.
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.
add set the value of 'ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS' to the list of
paths to xenguest images you want to include in your host.
There are 4 supported formats for ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS
entries:
- http/https url
- "https://[url]:[port]/foo.xenguest;md5sum=..."
- file:// absolute local path from root
- "file:///xenguests/bar.xenguest"
- file:// path relative to FILESEXTRAPATHS
- "file://relative/baz.xenguest"
- plain absolute local path from root
- "/xenguests/absolute/xyzzy.xenguest"
It is not recommended to use other bitbake URL types, as they may result in
undefined behaviour.
A semicolon seperated list of install arguments can follow each image path:
- guestname : the name that will be attached when the image is imported
(default: [filename, without extension])
- guestcount : the number of copies of the guest to install, with
incrementing numbers appended to the name
(default: 1)
Any other arguments, for example an md5sum, will be assumed to be fetch
arguments, and will be appended to the path in the SRC_URI.
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"
ARM_AUTONOMY_HOST_IMAGE_EXTERN_GUESTS = "\
https://[url]:[port]/base.xenguest;md5sum=[checksum];guestname=http \
file:///guests/base.xenguest;guestname=file_abs \
file://foo/base.xenguest;guestname=file_rel;guestcount=2 \
/guests/foo/bar/base.xenguest;guestname=no_fetcher \ "
```
This will add the guest and name it `myguest` on the host project image and
the xenguest-manager will automatically boot it during startup.
Documentation for setting up a multiconfig build can be found in:
meta-arm-autonomy/documentation/arm-autonomy-multiconfig.md
Add support for your board
--------------------------
@@ -187,7 +222,7 @@ 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
The xenguest-manager creates guest storage drives 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.
@@ -196,37 +231,37 @@ 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.
xenguest-network bridge creates a bridge on the host and adds network
interfaces to it so that guests 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
Check `recipes-extended/xenguest/xenguest-network.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.
xenguest-network puts the host network interfaces in a bridge and configures 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
XENGUEST_NETWORK_BRIDGE_CONFIG in your 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 look for the file in ${WORKDIR}, so you will need to add it to
the SRC_URI in your bbappend.
The recipe will also substitute `###BRIDGE_NAME###` with the bridge name
configured in ${XENGUEST_NETWORK_BRIDGE_NAME}.
configured in ${XENGUEST_NETWORK_BRIDGE_NAME} when the config file is installed.
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.
Please also read xenguest-network.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.
xen-devicetree modifies 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.
meta-arm-autonomy/documentation/n1sdp-image-customization.md
+1 -1
View File
@@ -28,7 +28,7 @@ perform a couple of customizations in the generated wic image:
The `arm-autonomy-n1sdp-efidisk.wks.in` and `arm-autonomy-n1sdp-grub.cfg` files
are located at `meta-arm-autonomy/dynamic-layers/meta-arm-bsp/wic`.
Other variables can also be custmized to set what files need to be included
Other variables can also be customized to set what files need to be included
in the wic image boot partition. Please refer to
`meta-arm-autonomy/dynamic-layers/meta-arm-bsp/conf/machine/n1sdp-extra-settings.inc`
for more details.
meta-arm-autonomy/documentation/xen-devicetree.md
+2 -1
View File
@@ -56,7 +56,8 @@ The following parameters are available:
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.
if the machine you 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
meta-arm-autonomy/documentation/xenguest-manager.md
+27 -13
View File
@@ -7,7 +7,7 @@ Introduction
xenguest-manager is a tool to manage Xenguest images generated by
[xenguest-mkimage](xenguest-mkimage.md).
On a Xen Dom0 system it will:
On a Xen Dom0 system it can:
- 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).
@@ -48,6 +48,7 @@ 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).
This config will be written to a file xenguest-manager.conf in /etc/xenguest/.
The following parameters are available:
@@ -68,13 +69,22 @@ The following parameters are available:
name).
This is set by default to "/usr/share/guests".
- XENGUEST_MANAGER_LOG_LEVEL: Set the default log level for xenguest manager. Must
be one of ERROR, INFO, VERBOSE (default: ERROR). The extra will be
- XENGUEST_MANAGER_LOG_LEVEL: Set the default log level for xenguest manager.
Must be one of ERROR, INFO, VERBOSE (default: ERROR). The logs will be
written to /var/log/xenguest.
If a verbosity argument (-v or -vv) is passed to xenguest-manager directly, it
will override the setting in xenguest-manager.conf
Since /var/log is by default a volatile location, extra configuration is
required if logs are desired to be kept between reboots:
VOLATILE_LOG_DIR="no"
Read more here: https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-VOLATILE_LOG_DIR
When this is enabled, logrotate will monitor the file to ensure it does not
grow excessively large. See recipes-extended/xenguest/files/logrotate-xenguest
Init scripts
------------
@@ -103,26 +113,30 @@ and variables from the parent file's scope, including:
Takes an optional log level and a message body
e.g. log ERROR "blah"
Options for log level: ERROR, INFO, VERBOSE, and FATAL, which
will call exit 1 immediately after logging the message
Options for log level: ERROR, INFO, VERBOSE,
and FATAL which will call exit 1 immediately after logging
the message at level ERROR.
- log_command() : Used to call a shell command and log that it has been
called, as well as capturing both stdout and stderr.
By default the command output is dumped to the logfile as an error
if the command returns a status > 0, or as a verbose message if the
whole script is running in verbose mode. An optional log level can
be passed to alter the level the log should be if the command returns
a status >0,
By default the command output is dumped to the logfile as an
error if the command returns a status > 0, or as a verbose
message if the whole script is running in verbose mode.
An optional log level can be passed to alter the level the
log should be if the command returns a status >0, which may
be useful if the command is expected to return a non-zero
result.
e.g. log_command INFO "ls -lh ~"
Options for log level: ERROR, INFO, and VERBOSE
Attempting to call any other functions from xenguest_manager in an init script may
result in a fatal error, from which cleanup is not guarenteed.
Attempting to call any other functions from xenguest_manager in an init script
may result in a fatal error, from which cleanup is not guarenteed.
Sourcing also allows the script to access params.cfg.
Init scripts also have access to config variables defined in params.cfg.
An example of how to create the directory and install an init shell script can
be found in:
meta-arm-autonomy/documentation/xenguest-mkimage.md
+7 -7
View File
@@ -4,9 +4,9 @@ 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.
xenguest-mkimage is a tool to create and modify images to be used as a 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
@@ -15,8 +15,8 @@ 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.
complex configurations by providing the ability to have init scripts embedded
inside the image that will be executed on the host when the guest is started.
Xenguest images content
-----------------------
@@ -35,7 +35,7 @@ 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).
example the kernel image 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
@@ -47,7 +47,7 @@ contains scripts called at a different time:
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.
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.