Deploy Action Reference — LAVA 2021.05 documentation

Deploy action roles ¶

Download files required by the job to the dispatcher, decompressing only if requested.
Prepare a LAVA overlay tarball containing the test definitions and LAVA API scripts, only if a Test Action Reference action is defined.
Depending on the deployment, apply the LAVA overlay tarball to the deployment.
Deploy does not support repeat blocks but does support Retry on failure.

Every deployment must specify a to parameter. This value is then used to select the appropriate strategy class for the deployment which, in turn, will require other parameters to provide the data on how to deploy to the requested location. Additionally, all the required parameters are marked with a *

Overlays ¶

LAVA can insert user provided overlays into your images right after the download step.

In the url block, you can add a dictionary called overlays that will list the overlays to add to the given resource.

- deploy:
    images:
      rootfs:
        url: http://example.com/rootfs.ext4.xz
        compression: xz
        format: ext4
        overlays:
          modules:
            url: http://example.com/modules.tar.xz
            compression: xz
            format: tar
            path: /

In order to insert overlay into an image, you should specify the image format. Currently LAVA supports cpio (newc format) and ext4 images.

The overlays should be archived using tar. The path is relative to the root of the image to update. This path is required.

Parameter List ¶

Contents

Deploy Action Reference
- Deploy action roles
- Required parameters
- Overlays
- Parameter List
- to: docker
  - os
  - image
    - name
    - local
- to: download
  - images
    - label
      - url *
      - compression
      - archive
      - md5sum
      - sha256sum
      - sha512sum
- to: fastboot
  - images
    - partition
      - compression
      - reboot
      - archive
      - apply-overlay
      - sparse
      - md5sum
      - sha256sum
      - sha512sum
- to: fvp
  - images
    - url *
    - overlays
      - partition *
      - ramdisk
- to: iso-installer
  - images
    - iso
    - preseed
  - iso
- to: lxc
  - packages
- to: musca
  - images
    - test_binary
      - url *
- to: nbd
  - kernel
    - url *
    - type
  - dtb
    - url *
  - modules
  - initrd
    - url *
  - nbdroot
    - url *
    - archive
      - compression
    - md5sum
    - sha256sum
      - sha512sum
- to: recovery
- to: sata
  - kernel *
  - ramdisk
  - dtb *
  - UUID *
  - boot_part *
- to: ssh
  - connection
  - protocols
- to: tftp
  - kernel
    - type
    - url *
  - dtb
    - url *
  - modules
  - ramdisk
    - url *
    - archive
    - compression
    - header
  - nfsrootfs
  - persistent_nfs
    - address *
- to: tmpfs
  - images
    - label
      - image_arg
      - url *
      - archive
      - compression
      - md5sum
      - sha256sum
      - sha512sum
- to: usb
  - kernel *
  - ramdisk
  - dtb *
  - UUID *
  - boot_part *
- to: vemsd
  - recovery_image
    - url *
    - compression
- to: mps
  - images
    - recovery_image
      - url *
      - compression
    - test_binary
      - url *
      - rename
- to: uuu
  - images
    - partition
      - compression
      - apply-overlay
      - sparse
      - md5sum
      - sha256sum
      - sha512sum
- os *

to: docker ¶

Pull a docker image from the official or a private docker hub.

- deploy:
    to: docker
    os: debian
    image: debian:stretch

os ¶

Optional parameter to let LAVA know which OS the container is running

image ¶

Either the name of the docker image to pull or a dictionary with:

name ¶

Name of the docker image to pull

local ¶

true if the image is local, false by default.

- deploy:
    to: docker
    os: debian
    image:
      name: my-local-docker-debian-image
      local: true

to: download ¶

Download is a special type of deployment in which the files specified in the URL are downloaded as in any other deployment type and does nothing more. If there is a LXC protocol requested then the downloaded files are copied to LAVA_LXC_HOME. These downloaded files can then be referred by the URL scheme lxc:/// in subsequent actions.

images ¶

Download deployments support images to be downloaded and saved along with copying to LAVA_LXC_HOME when LXC protocol is available. The list of images will depend on the test job and the test device.

label ¶

The label is arbitrary text, that refers to the image key that will get downloaded as specified in url *

- deploy:
    to: download
    images:
      rootfs:
        url: http://example.com/rootfs.img.gz
        compression: gz

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

md5sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        md5sum: d8784b27867b3dcad90cbea66eacc264

sha256sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

sha512sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha512sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

to: fastboot ¶

See also

Deploying test images using LXC

images ¶

Fastboot deployments support a range of images to be downloaded and deployed to the device. The list of images will depend on the test job and the test device. The available elements determine the command arguments passed to fastboot inside the LXC i.e., the partition to be flashed.

partition ¶

The partition is a text string which specifies the partition to which the image will be flashed using the fastboot command.

In the example, the partition to be flashed on the DUT is system.

Note

The partition text is passed to fastboot command as given in the job, for example, fastboot flash system /lava-lxc/rootfs.img, hence take caution to pass the right partition name.

- deploy:
    timeout:
      minutes: 15
    namespace: droid
    to: fastboot
    images:
      ptable:
        url: http://example.com/hikey/ptable-aosp-8g.img
        reboot: hard-reset
      boot:
        url: http://example.com/hikey/boot.img.xz
        compression: xz
        reboot: hard-reset
      cache:
        url: http://example.com/hikey/cache.img.xz
        compression: xz
      userdata:
        url: http://example.com/hikey/userdata.img.xz
        compression: xz
      system:
        url: http://example.com/hikey/system.img.xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a
        compression: xz
    protocols:
      lava-lxc:
      - action: fastboot-deploy
        request: pre-power-command
        timeout:
          minutes: 2

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

reboot ¶

If there is a need to restart or reboot the DUT after flashing partition image, then the method must be specified.

Allowed values

hard-reset
fastboot-reboot
fastboot-reboot-bootloader

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

apply-overlay ¶

Use this to apply LAVA specific overlays to image.

- deploy:
    to: fastboot
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        apply-overlay: true

sparse ¶

- deploy:
    to: fastboot
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sparse: true

The default value for this parameter is true. Some system images are shipped as sparse images which needs special handling with tools such as simg2img and img2simg, in order to apply LAVA specific overlays to it. By default LAVA assumes the image to which apply-overlay is specified is a sparse image.

See also

apply-overlay

If the image is not a sparse image then this should be explicitly mentioned, so that LAVA will treat the image as non-sparse ext4 image.

- deploy:
    to: fastboot
    images:
      system:
        url: http://example.com/system.ext4.xz
        compression: xz
        sparse: false

See also

The sparse image format is defined in sparse_format in the Android platform source code.

md5sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        md5sum: d8784b27867b3dcad90cbea66eacc264

sha256sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

sha512sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha512sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

to: fvp ¶

Allows running of FVP (or Fixed Virtual Platforms) from a Docker container. Generally speaking, FVP are launched in Docker and UART output is served over a telnet connection locally. A pattern is given in the job definition to find the port of the UART from the FVP output. LAVA will then connect via telnet to view UART output.

- deploy:
    namespace: docker
    to: fvp
    images:
      disk:
        url: http://fileserver/path/to/fvp/grub-busybox.img
        # Remaining settings allow adding overlay to the
        # ramdisk on second partition of
        # image file.
        overlays:
        - partition: 1
          ramdisk: ramdisk.img
        # Alternatively, add overlay into rootfs in first partition
        # overlays:
        # - partition: 0

images ¶

A dictionary of images.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

overlays ¶

A list of places to apply overlays. Either this will be applied to a partition on a disk image, or can be applied to a ramdisk contained in a partition on that disk image.

partition *¶

Either the root partition on the disk, or the partition that contains the ramdisk. LAVA decides which this is from whether the ramdisk option is present at the same level. 0-based index.

ramdisk ¶

The path to the ramdisk file relative to the root of the partition specified.

to: iso-installer ¶

Provides QEMU operations using an operating system installer into a new image and then boot into the installed image to run the specified test definitions.

Note

Currently only tested with Debian Installer.

- deploy:
    timeout:
      minutes: 4
    to: iso-installer
    os: debian_installer
    images:
      # the iso and the preseed file can be very tightly coupled.
      iso:
        url: http://example.com/debian-8.3.0-amd64-CD-1.iso
        image_arg: -drive file={iso},index=2,media=cdrom,readonly
      preseed:
        url: http://example.com/debian-8.3.0-cd1-preseed.cfg
    iso:
      kernel: /install.amd/vmlinuz
      initrd: /install.amd/initrd.gz
      installation_size: 2G

images ¶

The ISO and the preseed file can be tightly coupled but point releases of a stable release will typically continue to work with existing preseed files. LAVA tests of the installer tend to only install the base system in order to test kernel functionality rather than the operating system itself.

iso ¶

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

image_arg ¶

QEMU requires ,media=cdrom,readonly to handle the ISO correctly.

- deploy:
    to: iso-installer
    images:
      iso:
        url: http://example.com/debian.iso
        image_arg: -drive file={iso},index=2,media=cdrom,readonly

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

preseed ¶

Debian Installer can retrieve settings from a preseed file to allow the installation to proceed without prompting for information.

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

iso ¶

kernel ¶

Take an absolute path specified by the test writer to copy the kernel out of the specified iso so that necessary kernel options can be added to the default ISO boot commands.

Paths to pull from the ISO need to start with / as the top level of the mounted ISO.

Paths to pull from the ISO must also be unique.

- deploy:
    to: iso-installer
    iso:
      kernel: /install.amd/vmlinuz
      initrd: /install.amd/initrd.gz

initrd ¶

Take an absolute path specified by the test writer to copy the kernel out of the specified iso so that necessary kernel options can be added to the default ISO boot commands.

Paths to pull from the ISO need to start with / as the top level of the mounted ISO.

Paths to pull from the ISO must also be unique.

- deploy:
    to: iso-installer
    iso:
      kernel: /install.amd/vmlinuz
      initrd: /install.amd/initrd.gz

console ¶

console argument to pass to QEMU.

- deploy:
    to: iso-installer
    iso:
      console: ttyS0,38400,n8

installation_size ¶

Size of the empty image to be provided to the installer. Typically a maximum of 5G. Use megabytes for a smaller image, although ~1G is likely to be the smallest practical size

- deploy:
    to: iso-installer
    iso:
      installation_size: 2G

to: lxc ¶

Deploys / creates a LXC, based on the parameters specified as part of the LXC protocol.

packages ¶

List of packages that should be installed as part of LXC creation.

Note

Applies only to: lxc deploy action.

In the example, android-tools-adb and android-tools-fastboot are the packages that should be installed as part of LXC creation.

- deploy:
    namespace: tlxc
    timeout:
      minutes: 5
    to: lxc
    packages:
    - android-tools-adb
    - android-tools-fastboot

to: musca ¶

This deployment method allows deployment of software to musca devices. Currently supported musca devices: musca a, musca b1 and musca s1.

The board is powered on and the mass storage device is mounted. The test binary is copied to the MSD and then the MSD is unmounted. When the board processes it, the MSD will be re-exposed to the dispatcher, at which point this is re-mounted and LAVA will check for the presence of a FAIL.TXT file, in case of errors.

Note

Some initial setup steps are required to ensure that the Musca device serves it’s MSD when it is powered on. Check here for details on how to setup the board to auto-boot when it is programmed or turned on. Ensure DETAILS.TXT on the MSD shows “Auto Reset” and “Auto Power” are activated.

Note

LAVA won’t deploy firmware to the Musca board and so it must be fixed per device. Firmware used is available here.

- deploy:
    to: musca
    images:
      test_binary:
        url: https://community.arm.com/cfs-file/__key/communityserver-wikis-components-files/00-00-00-00-10/MuscaBlinky_5F00_v002.hex

images ¶

test_binary ¶

Download test binary to the Musca device.

url *¶

Specifies the URL to download. All downloads are check-summed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

to: nbd ¶

Used to support NBDroot deployments, e.g. using a initrd with nbd-client and pivot_root. Files are downloaded to a temporary directory on the worker, the rootfs is shared through xnbd-server and the filenames are substituted into the bootloader commands specified in the device configuration or overridden in the job. The files to download typically include a kernel but can also include any file which the substitution commands need for this deployment. URL support is handled by the python requests module.

- deploy:
    timeout:
      minutes: 4
    to: nbd
    kernel:
      url: http://example.com/vmlinuz
      type: zimage
    initrd:
      url: http://example.com/initramfs.ext4.gz.u-boot
    nbdroot:
      url: http://example.com/rootfs.ext4.xz
      compression: xz
    dtb:
      url: http://example.com/dtb.dtb

kernel ¶

To deploy images using NBDroot, arguments will be downloaded to a configured directory.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

type ¶

Specifies the type of kernel being downloaded. Some bootloaders, for example U-Boot, use this information to determine the load addresses and boot commands. Certain device types may also need the downloaded file to be converted to a uImage.

Supported types

image
zimage
uimage

(Replaces the previous support for specifying the boot type (bootm, booti or bootz).

dtb ¶

Device Tree Blob

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

modules ¶

This is not supported in the deployment strategy. Modules must be part of the filesystem already.

initrd ¶

The initrd contains all necessary files, daemons and scripts to bring-up the nbd-client and pivot_root to the final rootfs. There are a few important aspects:

The nbdroot filesystem will not be modified prior to the boot. The filesystems are using security labels and this would alternate the fs. The lava test shell needs to be extracted at runtime with transfer_overlay.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

nbdroot ¶

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

The NBD filesystem image is unpacked into a temporary directory onto the dispatcher in a location supported by NBD server. The compression method must be specified so that the filesystem can be unpacked.

Allowed values

none
bz2
gz
xz
zstd

md5sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        md5sum: d8784b27867b3dcad90cbea66eacc264

sha256sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

sha512sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha512sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

to: recovery ¶

Deployment to recovery allows the use of device dictionary commands and an LXC test shell to automate recovery mode operations on some DUTs.

Successful use of recovery deployments require support by the admins and by the test writers.

Note

In recovery mode, the device may have different identifiers and might no longer be unique. This can result in requiring a new device-type template and only creating one device of this type on any one worker. Not all devices can support automated recovery mode.

Additionally, recovery deployments are blind - there is udev support to add the device to the LXC but no serial connection, so no output will be read from the DUT. All tools and libraries required to execute the recovery test shell need to be added to the LXC. For example, using an earlier test shell inside the LXC.

Download scripts and binaries to transfer to the device
Copy the downloaded artifacts into the LXC.
Ensure that power to the device is OFF

Execute the recovery_mode_command to use relays or similar to put the device into recovery mode, in a dedicated namespace.

{% set recovery_mode_command = [
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 1 -s off',
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 2 -s on'] %}

Apply power.

- boot:
    namespace: recovery
    timeout:
      minutes: 5
    method: recovery
    commands: recovery

The test job would then define a test action which executes the scripts using the downloaded files and completes recovery. This script may have to wait for the device to appear and as the device may then have an unpredictable device node name, an action to create a symlink with a known name is likely to be required. The use of LXC ensures that only one suitable device exists, as long as the device configuration and recovery mode operations only require a single device matching the check in the recovery script.

Example: for the HiKey 6220, the recovery mode operations could be executed as steps in the test shell as follows:

run:
  steps:
  - find /dev/ -name 'ttyUSB*' -xdev -type c -quit -exec ln -s {} /dev/recovery ';'
  - python /lava-lxc/hisi-idt.py --img1=/lava-lxc/l-loader.bin -d /dev/recovery
  # fastboot should wait for the device to reset here
  # udev rule copes with adding it to the LXC once it appears
  - fastboot flash ptable /lava-lxc/ptable-linux.img
  - fastboot flash ptable /lava-lxc/fip.bin
  - fastboot flash ptable /lava-lxc/nvme.img
  # next boot action takes care of exiting from recovery mode

Important

Make these commands portable so that the same script can be used to deploy new firmware to the device outside of LAVA. When using a test shell to handle firmware deployments, make sure that a failure of any test shell command fails the job by using lava-test-raise.

command(){
    if [ -n "$(which lava-test-case || true)" ]; then
        echo $2
        $2 && lava-test-case "$1" --result pass || lava-test-raise "$1"
    else
        echo $2
        $2
    fi
}

Then call the function with two arguments, the test case name (with no spaces) and the command to execute (with substitutions for the parameterized variables for the files which were downloaded by the test job):

command 'hisi-idt-l-loader' "python ${SCRIPT} --img1=${LOADER} -d /dev/recovery"

Take note of the quoting in this shell example. The first parameter can use single quotes but the second parameter must use double quotes " so that the values of $SCRIPT and $LOADER are substituted. Portable scripts are free to use whatever language you prefer.

See also

Write portable test definitions

Examples for hikey 6220:

When the test shell exits, the device is reset using a second boot recovery operation.

- boot:
    namespace: recovery
    timeout:
      minutes: 5
    method: recovery
    commands: exit

A recovery_exit_command must be specified in the device dictionary.

{% set recovery_exit_command = [
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 1 -s on',
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 2 -s off'] %}

Test jobs can terminate early (either through bugs or cancellation), so it is important to include the recovery_exit support in the power_off_command so that the device is left in a suitable state for the next test job in the queue.

{% set power_off_command = ['/usr/bin/pduclient --daemon calvin --hostname pdu --command off --port 04',
'sleep 30',
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 1 -s on',
'/home/neil/lava-lab/shared/lab-scripts/eth008_control -a 10.15.0.171 -r 2 -s off'] %}

The additional command may take some time to complete, so the timeout of the power_off action may also need extending in the device-type template.

{% set action_timeout_power_off = 60 %}

to: sata ¶

Deploy unchanged images to secondary SATA media. Any bootloader inside the image will not be used. Instead, the files needed for the boot are specified in the deployment. The entire physical device is available to the secondary deployment. Secondary relates to the expected requirement of a primary boot (e.g. ramdisk or NFS) which provides a suitable working environment to deploy the image directly to the secondary device. See Secondary media.

Not all devices support SATA media.

The test writer needs to provide the following information about the image:

kernel *¶

kernel: The path, within the image, to the kernel which will be used by the bootloader.

ramdisk ¶

ramdisk: (optional). If used, must be a path, within the image, which the bootloader can use.

dtb *¶

dtb: The path, within the image, to the dtb which will be used by the bootloader.

UUID *¶

UUID: The UUID of the partition which contains the root filesystem of the booted image.

boot_part *¶

boot_part: the partition on the media from which the bootloader can read the kernel, ramdisk & dtb.

Note

If the image mounts the boot partition at a mounpoint below the root directory of the image, the path to files within that partition must not include that mountpoint. The bootloader will read the files directly from the partition.

to: ssh ¶

SSH methods can support two types of deployment.

See also

Primary remote connection and SSH as the primary remote connection as an example of the primary ssh connection.

See also

Secondary Connection

connection ¶

protocols ¶

- deploy:
    role:
    - guest
    connection: ssh
    protocols:
      lava-multinode:
      - action: prepare-scp-overlay
        request: lava-wait
        # messageID matches hostID
        messageID: ipv4
        message:
          # the key of the message matches value of the host_key
          # the value of the message gets substituted
          ipaddr: $ipaddr
        timeout:  # delay_start timeout
          minutes: 21
    timeout:
      minutes: 22
    to: ssh

to: tftp ¶

Used to support TFTP deployments, e.g. using U-Boot. Files are downloaded to a temporary directory in the TFTP tree and the filenames are substituted into the bootloader commands specified in the device configuration or overridden in the job. The files to download typically include a kernel but can also include any file which the substitution commands need for this deployment. URL support is handled by the python requests module.

- deploy:
    timeout:
      minutes: 4
    to: tftp
    kernel:
      url: http://example.com/vmlinuz-4.9.0-4-armmp
      type: zimage
    ramdisk:
      url: http://example.com/initrd.img-4.9.0-4-armmp.gz
      compression: gz
    # modules
    modules:
      url: http://example.com/modules.tar.gz
      compression: gz
    # despite this being a Debian initramfs, it is not a complete Debian rootfs, so use oe compatibility
    dtb:
      url: http://example.com/am335x-boneblack.dtb

# BOOT_BLOCK
- boot:
    method: u-boot
    commands: ramdisk
    prompts:
    # escape the brackets to ensure that the prompt does not match
    # kernel debug lines which may mention initramfs
    - '\(initramfs\)'
    timeout:
      minutes: 2

kernel ¶

To deploy images using TFTP, arguments will be downloaded to a configured tftp directory.

type ¶

Specifies the type of kernel being downloaded. Some bootloaders, for example U-Boot, use this information to determine the load addresses and boot commands. Certain device types may also need the downloaded file to be converted to a uImage.

Supported types

image
zimage
uimage

(Replaces the previous support for specifying the boot type (bootm, booti or bootz).

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

dtb ¶

Device Tree Blob.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

modules ¶

A tarball of kernel modules for the supplied kernel. The file must be a tar file and the compression method must be specified. If the kernel requires these modules to be able to locate the rootfs, e.g. when using NFS or if certain required filesystem drivers are only available as modules, the ramdisk can be unpacked and the modules added. Modules may also be required to run tests within the ramdisk itself.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

ramdisk ¶

The ramdisk needs to be unpacked and modified in either of the following two use cases:

the lava test shell is expected to run inside the ramdisk, or
the deployment needs modules to be added to the ramdisk, for example to allow the device to load the network driver to be able to locate the NFS.

To unpack the ramdisk, the test writer needs to specify details about how the ramdisk is prepared and used. If these details are not provided, the ramdisk will not be unpacked (potentially causing the test to fail in the above two use cases).

- deploy:
    timeout:
      minutes: 4
    to: tftp
    kernel:
      url: http://example.com/vmlinuz-4.9.0-4-armmp
      type: zimage
    ramdisk:
      url: http://example.com/initrd.img-4.9.0-4-armmp.gz
      compression: gz
    # modules
    modules:
      url: http://example.com/modules.tar.gz
      compression: gz
    # despite this being a Debian initramfs, it is not a complete Debian rootfs, so use oe compatibility
    dtb:
      url: http://example.com/am335x-boneblack.dtb

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

nfsrootfs ¶

- deploy:
    timeout:
      minutes: 10
    to: tftp
    kernel:
      url: http://example.com/vmlinuz-4.9.0-4-armmp
      type: zimage
    ramdisk:
      url: http://example.com/initrd.img-4.9.0-4-armmp.gz
      compression: gz
    modules:
      url: http://example.com/modules.tar.gz
      compression: gz
    nfsrootfs:
      url: http://example.com/stretch-armhf-nfs.tar.gz
      compression: gz
    dtb:
      url: http://example.com/dtbs/am335x-boneblack.dtb

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

Note

Additional NFS mount options can be added via job definition context i.e. nfsvers argument which specifies which version of the NFS protocol to use.

context:
  extra_nfsroot_args: ",nolock,nfsvers=3"

persistent_nfs ¶

A persistent NFS URL can be used instead of a compressed tarball. See Persistence for the limitations of persistent storage.

Known Caveats

modules are not extracted into the persistent NFS mount
job definition must have a test action

Warning

LAVA does not shut down the device or attempt to unmount the NFS filesystem when the job finishes; the device is simply powered off. The test writer needs to ensure that any background processes started by the test have been stopped before the test finishes.

address *¶

Specifies the address to use for the persistent filesystem.

The address must include the IP address of the NFS server and the full path to the directory which contains the root filesystem, separated by a single colon. In the YAML, all values containing a colon must be quoted:

- deploy:
    to: tftp
    kernel:
      url: http://example.com/vmlinuz-4.9.0-4-armmp
      type: zimage
    persistent_nfs:
      address: "127.0.0.1:/var/lib/lava/dispatcher/tmp/armhf/stretch"

to: tmpfs ¶

Used to support QEMU device types which run on a dispatcher. The file is downloaded to a temporary directory and made available as one or more images, appending specified arguments to a predetermined QEMU command line:

- deploy:
    timeout:
      minutes: 4
    to: tmpfs
    images:
        rootfs:
          image_arg: -drive format=raw,file={rootfs}
          url: http://example.com/stretch.img.gz
          sha256sum: b5cdb3b9e65fec2d3654a05dcdf507281f408b624535b33375170d1e852b982c
          compression: gz

images ¶

To deploy images using QEMU, arguments need to be prepared and then modified to include the downloaded location of the image files. The test writer needs to specify the format of the image and other image-specific arguments for QEMU along with a placeholder label which is unique for this test job.

label ¶

The label is arbitrary text, used to match the other parameters to the placeholder so that the final value can be substituted in place of the placeholder.

In the example, the label is rootfs and the url includes the matching placeholder {rootfs}. If the final location of the downloaded image is /tmp/tmp.rG542e/large-stable-6.img then the final argument passed to QEMU would include -drive format=raw,file=/tmp/tmp.rG542e/large-stable-6.img.

Note

Take note of the syntax. Single brace before and after the label and no whitespace. This is test job syntax, not Jinja.

- deploy:
    timeout:
      minutes: 4
    to: tmpfs
    images:
        rootfs:
          image_arg: -drive format=raw,file={rootfs}
          url: http://example.com/stretch.img.gz
          sha256sum: b5cdb3b9e65fec2d3654a05dcdf507281f408b624535b33375170d1e852b982c
          compression: gz

image_arg ¶

The image_arg determines how QEMU handles the image. The arguments must include a placeholder label which exactly matches the key of the same block in the list of images. The actual location of the downloaded file will then replace the placeholder. Multiple images can be supplied but the test writer is responsible for ensuring that the image_arg make sense to QEMU.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

archive ¶

Some system images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the system image correctly.

- deploy:
    images:
      boot:
        url: http://example.com/boot.tar.xz
        compression: xz
        archive: tar

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

md5sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        md5sum: d8784b27867b3dcad90cbea66eacc264

sha256sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

sha512sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha512sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

to: usb ¶

Deploy unchanged images to secondary USB media. Any bootloader inside the image will not be used. Instead, the files needed for the boot are specified in the deployment. The entire physical device is available to the secondary deployment. Secondary relates to the expected requirement of a primary boot (e.g. ramdisk or NFS) which provides a suitable working environment to deploy the image directly to the secondary device. See Secondary media.

Not all devices support USB media.

The test writer needs to provide the following information about the image:

kernel *¶

kernel: The path, within the image, to the kernel which will be used by the bootloader.

ramdisk ¶

ramdisk: (optional). If used, must be a path, within the image, which the bootloader can use.

dtb *¶

dtb: The path, within the image, to the dtb which will be used by the bootloader.

UUID *¶

UUID: The UUID of the partition which contains the root filesystem of the booted image.

boot_part *¶

boot_part: the partition on the media from which the bootloader can read the kernel, ramdisk & dtb.

Note

If the image mounts the boot partition at a mounpoint below the root directory of the image, the path to files within that partition must not include that mountpoint. The bootloader will read the files directly from the partition.

The UUID can be obtained by writing the image to local media and checking the contents of /dev/disk/by-uuid

The ramdisk may need adjustment for some bootloaders (like U-Boot), so mount the local media and use something like:

mkimage -A arm -T ramdisk -C none -d /mnt/boot/init.. /mnt/boot/init..u-boot

to: vemsd ¶

VEMSD or Versatile Express MicroSD is a deployment method to write a new recovery image.

recovery_image ¶

Download the URL ready to be unpacked onto the MicroSD.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

compression ¶

If the image is compressed, the compression method must be specified.

zip files are downloaded without decompression and unpacked directly onto the filesystem of the VEMSD.

gz files are required to be a .tar.gz and will be decompressed during download and then unpacked onto the filesystem of the VEMSD.

Allowed values

gz
zip

to: mps ¶

MPS is a deployment method used by the MPS2 device which is similar to the support for to: vemsd

images ¶

recovery_image ¶

Download the URL ready to be unpacked onto the USB filesystem of the MPS2 device.

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

compression ¶

If the image is compressed, the compression method must be specified.

zip files are downloaded without decompression and unpacked directly onto the filesystem of the USB filesystem of the MPS2.

gz files are required to be a .tar.gz and will be decompressed during download and then unpacked onto the filesystem of the VEMSD.

Allowed values

gz
zip

test_binary ¶

Download test binary to MPS device and rename if required.

Multiple test binaries can be flashed in the same deploy action by listing all of them. The keys should start with test_binary_.

- deploy:
    to: mps
    images:
      recovery_image:
        url: mps2_sse200_an512.tar.gz
        compression: gz
      test_binary_1:
        url: tfm_sign.bin
      test_binary_2:
        url: mcuboot.bin

url *¶

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

rename ¶

Renames the test_binary if required

If the recovery_image expects to flash a specific image and the file downloaded is not named this way, this option will save it with a different name on the board.

If not specified, the the test_binary is copied as-is, no renaming takes place.

- deploy:
    to: mps
    images:
      recovery_image:
        url: mps2_sse200_an512.tar.gz
        compression: gz
      test_binary_1:
        url: tfm_sign_20191121.bin
        renam: tfm_sign.bin

to: uuu ¶

uuu specific deploy method is very similar with to: fastboot method, with a required boot partition. Partitions are usable within uuu boot method using the partition name.

- deploy:
    to: uuu
    images:
      boot:
        url: https://.../imx-boot-sd.bin-flash
      system:
        url: https://../imx-image-multimedia.rootfs.wic

images ¶

uuu deployments support a range of images to be downloaded and deployed to the device. The list of images will depend on the test job and the test device.

Warning

Partition boot is required by any uuu boot method.

partition ¶

The partition is a text string which specifies the partition to which the image will be flashed using uuu commands.

Note

Each partition can be referenced using {partition_name} within uuu boot method e.g. :

- deploy:
    to: uuu
    images:
      boot:
        url: https://.../imx-boot-sd.bin-flash
- boot:
    method: uuu
    commands:
    - uuu: -b sd {boot}

Specifies the URL to download. All downloads are checksummed using md5sum and sha256sum

URLs are checked during the test job validation to ensure that the file can be downloaded. Missing files will cause the test job to end as Incomplete.

URLs must use one of the supported schemes, the first element of the URL.

Supported schema

http://
https://
file://
lxc://

compression ¶

If the image is compressed, the compression method must be specified. If image is compressed but compression method is not specified it will be downloaded as uncompressed.

Allowed values

bz2
gz
xz
zstd

apply-overlay ¶

Use this to apply LAVA specific overlays to image.

- deploy:
    to: uuu
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        apply-overlay: true

sparse ¶

- deploy:
    to: uuu
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sparse: true

The default value for this parameter is true. Some system images are shipped as sparse images which needs special handling with tools such as simg2img and img2simg, in order to apply LAVA specific overlays to it. By default LAVA assumes the image to which apply-overlay is specified is a sparse image.

See also

apply-overlay

If the image is not a sparse image then this should be explicitly mentioned, so that LAVA will treat the image as non-sparse ext4 image.

- deploy:
    to: uuu
    images:
      system:
        url: http://example.com/system.ext4.xz
        compression: xz
        sparse: false

See also

The sparse image format is defined in sparse_format in the Android platform source code.

md5sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        md5sum: d8784b27867b3dcad90cbea66eacc264

sha256sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

sha512sum ¶

The checksum of the file to download can be provided, and if so it will be checked against the downloaded content. This can help to detect multiple potential problems such as misconfigured caching or corrupted downloads. If compression is used, the checksum to specify is the checksum of the compressed file, irrespective of whether that file is decompressed later.:

- deploy:
    images:
      system:
        url: http://example.com/system.img.xz
        compression: xz
        sha512sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a

os *¶

The operating system of the image may be specified if the LAVA scripts need to use the LAVA install helpers to install packages or identify other defaults in the deployment data. However, this support is deprecated for most use cases.

If os is used, the value does not have to be exact. A similar operating system can be specified, based on how the test job operates. If the test shell definition uses the deprecated LAVA install helpers (by defining install: steps), then any os value which provides the same installation tools will work. For example, operating systems which are derivatives of Debian can use os: debian without needing explicit support for each derivative because both will use apt and dpkg.

See also

Rely less on install: steps

Test jobs which execute operating system installers will require the deployment data for that installer, so os will need to be specified in those test jobs. When the Lava install helpers are removed, the elements of deployment data which are required for installers will be retained.

Portable test definitions do not need to specify os at all, as long as the test definition is not expected to run on a DUT running Android.

Important

Please read the notes on Write portable test definitions - all test writers are strongly encouraged to drop all use of the LAVA install helpers as this support is deprecated and is expected to be removed by moving to support for an updated Lava-Test Test Definition.

Not all deployment methods support all types of operating system.
Not all devices can support all operating systems.

Allowed values

android : If your android test job executes a Lava Test Shell on the DUT then os: android will be needed so that the Android shell is used instead of /bin/sh. Many AOSP images do not include busybox or other support for a shell on the DUT, so test jobs using those images drive the test from the LXC by using adb. The deployment to the LXC does not need to specify os as long as the test shell is portable.
ubuntu : deprecated - compatible with debian.
debian
lede
fedora
centos : deprecated - compatible with fedora.
debian_installer
centos_installer
oe