Deploy commands
This is an example block - the actual data values here are known not to work as
the deploy step is for a panda but the boot step in the next example
comes from a working cubietruck job.
This example uses a device configuration where UUID-required is True.
For simplicity, this example also omits the initial deployment and boot, at the
start of this block, the device is already running a kernel with a ramdisk or
rootfs which provides enough support to complete this second deployment.
# secondary media - use the first deploy to get to a system which can deploy the next
# in testing, assumed to already be deployed
- deploy:
timeout:
minutes: 10
to: usb
# not a real job, just used for unit tests
compression: gz
image:
url: https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.gz
device: SanDisk_Ultra # needs to be exposed in the device-specific UI
download: /usr/bin/wget
Ensure that the deploy action has sufficient time to download the
decompressed image and write that image directly to the media using
STDOUT. In the example, the deploy timeout has been set to ten minutes - in
a test on the panda, the actual time required to write the specified image
to a USB device was around 6 minutes.
Note the deployment strategy - to: usb. This is a direct mapping to the
kernel interface used to deploy and boot this image. The bootloader must
also support reading files over this interface.
The compression method used by the specified image is explicitly set.
The image is downloaded and decompressed by the dispatcher, then made
available to the device to retrieve and write to the specified media.
The device is specified as a label so that the correct UUID can be
constructed from the device configuration data.
The download tool is specified as a full path which must exist inside the
currently deployed system. This tool will be used to retrieve the
decompressed image from the dispatcher and pass STDOUT to the writer tool,
dd by default. If the download tool is the default /usr/bin/wget,
LAVA will add the following options:
--no-check-certificate --no-proxy --connect-timeout=30 -S
--progress=dot:giga -O - If different download tools are required for
particular images, these can be specified, however, if those tools require
options, the test writer can either ensure that a script exists in the image
which wraps those options or file a bug to have the alternative tool options
supported.
The default writer tool is dd but it is possible to specify an alternative
one. In particular, bmaptool is usually a much better choice for USB or SD
card devices. It will typically flash the image faster and extend the lifetime
of the storage media. It needs a .bmap file which contains a block map
alongside the actual image file. For this reason, two files need to be
downloaded and stored in the same directory on the dispatcher. The example
below illustrates how to do this:
# secondary media deployment using bmaptool
- deploy:
timeout:
minutes: 10
to: usb
# not a real job, just used for illustrative purposes
compression: gz
images:
image:
url: https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.gz
bmap:
url: https://releases.linaro.org/12.02/ubuntu/leb-panda/panda-ubuntu-desktop.img.bmap
uniquify: false
device: SanDisk_Ultra # needs to be exposed in the device-specific UI
writer:
tool: /usr/bin/bmaptool
options: copy {DOWNLOAD_URL} {DEVICE}
prompt: 'bmaptool: info'
tool:
prompts: ['copying time: [0-9ms\.\ ]+, copying speed [0-9\.]+ MiB\/sec']
The images list needs to contain one image entry and can have others
as well such as bmap in this case. They will all be downloaded
separately to the dispatcher and made available to the board via HTTP. The
URL of the image file is available in the job definition as
{DOWNLOAD_URL}. The URL of the other images will need to be determined
by other means. Say, the image file could be a manifest with the list
of the actual binary images (not the case with this bmaptool example).
Each item in the images list is normally downloaded into a separate
sub-directory such as image or bmap in this example. As the
bmaptool expects both files to be in the same path, the uniquify:
false option is used so all the files are downloaded directly at the root
of the job’s storage-deploy-* directory. Please note that if several
image files have the same name, they will overwrite each other when
uniquify is set to false. For this reason, if not specified in the
job it will be set to true by default.
To use an alternative writer tool, the writer parameters are used. The
absolute path to the tool must be provided with tool as well as the
options required to call it. The prompt is used to detect that the
flashing has started.
The writer tool will normally also be responsible for downloading the
image file, hence the {DOWNLOAD_URL} option passed to it in the example.
It is also possible to provide both download and writer parameters,
in which case the standard output of the downloader tool will be piped into
the standard input of the writer tool.
The tool prompts parameter is to detect when the writer tool has
completed the flashing operation. When LAVA has matched a prompt with the
tool output, it will then proceed with the secondary boot action. The
prompts parameters defaults are to match the output of dd, so they
should be defined appropriately when using an alternative writer tool.
The kernel inside the initial deployment MUST support UUID when deployed on
a device where UUID is required, as it is this kernel which needs to make
/dev/disk/by-id/$path exist for dd to use. Remember not to quote the
UUID:
root_uuid: UUID=159d17cc-697c-4125-95a0-a3775e1deabe
Boot commands
- boot:
method: u-boot
commands: usb
parameters:
shutdown-message: "reboot: Restarting system"
# these files are part of the image already deployed and are known to the test writer
kernel: /boot/vmlinuz-3.16.0-4-armmp-lpae
ramdisk: /boot/initrd.img-3.16.0-4-armmp-lpae.u-boot
dtb: /boot/dtb-3.16.0-4-armmp-lpae'
root_uuid: UUID=159d17cc-697c-4125-95a0-a3775e1deabe # comes from the supplied image.
boot_part: 1 # the partition on the media from which the bootloader can read the kernel, ramdisk & dtb
prompts:
- 'linaro-test'
- 'root@debian:~#'
The kernel and (if specified) the ramdisk and dtb paths are the
paths used by the bootloader to load the files in order to boot the image
deployed onto the secondary media. These are not necessarily the same as
the paths to the same files as they would appear inside the image after
booting, depending on whether any boot partition is mounted at a particular
mountpoint.
The root_uuid is the full option for the root= command to the kernel,
including the UUID= prefix.
The boot_part is the number of the partition from which the bootloader can
read the files to boot the image. This will be combined with the device
configuration interface name and device_id to create the command to the
bootloader, e.g.:
"setenv loadfdt 'load usb 0:1 ${fdt_addr_r} /boot/dtb-3.16.0-4-armmp-lpae''",
The dispatcher does NOT analyze the incoming image - internal UUIDs inside an
image do not change as the refactored dispatcher does not break up or
reorganize the partitions. Therefore, the UUIDs of partitions inside the image
MUST be declared by the job submissions.
