Deploy Action Reference

In general, the deployments do not modify the downloaded files. Where the LAVA scripts and test definitions need to be added, these are first prepared as a standalone tarball. Exceptions are described where relevant in each section.

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.

Required parameters

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 *

to: docker

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

image

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

  • name: name of the docker image to pull
  • local: True if the image is local, False by default.

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.

partition

The partition is a text which specifies the partition to which the image will get flashed using fastboot command in subsequent deploy action.

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

    images:
      rootfs:
        url: http://images.validation.linaro.org/builds.96boards.org/releases/dragonboard410c/linaro/debian/16.06/linaro-jessie-developer-qcom-snapdragon-arm64-20160630-110.img.gz
        compression: gz
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://
compression

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

Allowed values

  • gz
  • bz2
  • xz
archive

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

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.

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.:

        url: http://images.validation.linaro.org/builds.96boards.org/snapshots/hikey/linaro/aosp-master/357/system.img.xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a
        compression: xz
    protocols:
      lava-lxc:
      - action: fastboot-deploy
        request: pre-power-command
        timeout:
          minutes: 2

label

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

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://

compression

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

Allowed values

  • gz
  • bz2
  • xz

archive

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

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.

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.:

        url: http://images.validation.linaro.org/builds.96boards.org/snapshots/hikey/linaro/aosp-master/357/system.img.xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a
        compression: xz
    protocols:
      lava-lxc:
      - action: fastboot-deploy
        request: pre-power-command
        timeout:
          minutes: 2

to: fastboot

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.

    images:
      ptable:
        url: http://images.validation.linaro.org/builds.96boards.org/snapshots/reference-platform/components/uefi/latest/release/hikey/ptable-aosp-8g.img
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.

Allowed values

  • gz
  • bz2
  • xz
reboot

If there is a need to restart or reboot the DUT after flashing boot 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.

archive: tar
apply-overlay

Use this to apply LAVA specific overlays to image.

apply-overlay: true
sparse

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.

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.

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.:

        url: http://images.validation.linaro.org/builds.96boards.org/snapshots/hikey/linaro/aosp-master/357/system.img.xz
        sha256sum: e0e82b5adfae84ff97f4f6488e5b4c64b0dfc7ad8a37b4bcbb887d9f85a6be0a
        compression: xz
    protocols:
      lava-lxc:
      - action: fastboot-deploy
        request: pre-power-command
        timeout:
          minutes: 2

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.

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 images are compressed as a tarball (.tar.*), these images need the archive option specified to unpack the image correctly.

archive: tar
compression

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

Allowed values

  • gz
  • bz2
  • xz
image_arg

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

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://

preseed

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

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://

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.

kernel: /install.amd/vmlinuz

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.

initrd: /install.amd/initrd.gz

console

console argument to pass to QEMU.

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

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.

    packages:
    - android-tools-adb
    - android-tools-fastboot

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

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.

    kernel:
      url: http://snapshots.linaro.org/components/lava/standard/debian/jessie/armhf/1/vmlinuz

Supported schema

  • http://
  • https://
  • file://

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.

    dtb:
      url: http://snapshots.linaro.org/components/lava/standard/debian/jessie/armhf/1/dtbs/am335x-boneblack.dtb

Supported schema

  • http://
  • https://
  • file://

modules

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

initrd

The initrd contains all necessary files, deamons 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.
    initrd:
      url: http://fix.me/initramfs-netboot-image-raspberrypi3.ext4.gz.u-boot
      allow_modify: false

url *

Supported schema

  • http://
  • https://
  • file://

nbdroot

    nbdroot:
      url: http://fix.me/rootfs.ext4.xz

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://

archive

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

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
  • gz
  • bz2
  • xz

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.

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.

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.

  1. Download scripts and binaries to transfer to the device

  2. Copy the downloaded artifacts into the LXC.

  3. Ensure that power to the device is OFF

  4. 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'] %}
    
  5. 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.

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.

protocols

# DEPLOY_SSH_BLOCK
- 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: 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

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.

    kernel:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/vmlinuz-4.9.0-4-armmp
      type: zimage

Supported schema

  • http://
  • https://
  • file://

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.

    dtb:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/dtbs/am335x-boneblack.dtb

Supported schema

  • http://
  • https://
  • file://

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.

    modules:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/modules.tar.gz
      compression: gz

Supported schema

  • http://
  • https://
  • file://

archive

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

archive: tar

compression

The compression method must be specified so that the modules can be unpacked.

Allowed values

  • gz
  • bz2
  • xz

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).

-4.9.0-4-armmp
      type: zimage
    ramdisk:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/initrd.img-4.9.0-4-armmp
      compression: gz
    # modules

url *

Supported schema

  • http://
  • https://
  • file://
    modules:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/modules.tar.gz
      compression: gz

archive

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

archive: tar

compression

The compression method must be specified so that the modules can be unpacked.

Allowed values

  • gz
  • bz2
  • xz

nfsrootfs

    kernel:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/vmlinuz-4.9.0-4-armmp
      type: zimage
    ramdisk:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/initrd.img-4.9.0-4-armmp
      compression: gz
    modules:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/modules.tar.gz
      compression: gz
    nfsrootfs:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/stretch-armhf-nfs.tar.gz
      compression: gz
    dtb:
      url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/armhf/3/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://

archive

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

archive: tar

compression

The NFS is unpacked into a temporary directory onto the dispatcher in a location supported by NFS exports. The compression method must be specified so that the NFS can be unpacked.

Allowed values

  • gz
  • bz2
  • xz

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.

persistent_nfs

A persistent NFS URL can be used instead of a compressed tarball. See Persistence for the limitations of persistent storage. The creation and maintenance of the persistent location is solely the responsibility of the test writer.

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:

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://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/amd64/2/stretch.img.gz
          sha256sum: b5cdb3b9e65fec2d3654a05dcdf507281f408b624535b33375170d1e852b982c
          compression: gz
    root_partition: 1

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.

    images:
        rootfs:
          image_arg: -drive format=raw,file={rootfs}
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://
archive

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

archive: tar
compression

If the image is compressed, the compression method must be specified if any test actions are defined in the job.

Allowed values

  • gz
  • bz2
  • xz
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.

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.:

          image_arg: -drive format=raw,file={rootfs}
          url: http://images.validation.linaro.org/snapshots.linaro.org/components/lava/standard/debian/stretch/amd64/2/stretch.img.gz
          sha256sum: b5cdb3b9e65fec2d3654a05dcdf507281f408b624535b33375170d1e852b982c
          compression: gz
    root_partition: 1

# BOOT_BLOCK

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 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://

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

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 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://

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.

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://

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.

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.

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