Boot Action Reference¶

login_prompt¶

The prompt to match when the system requires a login. This prompt needs to be unique across the entire boot sequence, so typically includes : and should be quoted. If the hostname of the device is included in the prompt, this can be included in the login_prompt:

- boot:
  auto_login:
    login_prompt: 'login:'
    username: root

username¶

Whenever a login_prompt is specified, a username will also be required. The username should either be root or a user with sudo access without needing a password.

password_prompt¶

If the login requires a password as well as a username, the password_prompt must be specified:

- boot:
    auto_login:
      login_prompt: 'login:'
      username: root
      password_prompt: 'Password:'
      password: rootme

password¶

Whenever a password_prompt is specified, a password will also be required.

login_commands¶

A list of arbitrary login_commands can be run after the initial login and before setting the shell prompt. This is typically used to make a regular user become root with su. For example:

- boot:
    auto_login:
      login_prompt: 'login:'
      username: user
      password_prompt: 'Password:'
      password: pass
      login_commands:
      - sudo su

Specifying commands in full¶

During testing and development, it can sometimes be useful to use a different set of boot commands instead of what is listed in the jinja2 template for the device-type. This allows test writers to change boot commands beyond the scope of existing overrides. To work sensibly in the LAVA environment, these commands will still need to include the placeholders such that temporary paths etc. can be substituted in when the test job is started.

In this example (for an x86 test machine using iPXE), the commands change the root argument to the kernel to boot from a SATA drive which has been configured separately. (For example, by the admins or by test writers from a hacking session.)

Appending to the kernel command line¶

A test job may require extra kernel command line options to enable or disable particular functionality. The job context can be used to append strings to the kernel command line:

context:
  extra_kernel_args: vsyscall=native

job context is a top level element of LAVA job definition. It is not a part of boot section.

Values need to be separated by whitespace and will be added to the command line with a prefix of a single space and a suffix of a single space.

The possible values which can be used are determined solely by the support available within the kernel provided to the DUT.

Depending on the boot method, it may also be possible to add specific options, for example to append values to the NFS options using extra_nfsroot_args:

context:
  extra_nfsroot_args: ,rsize=4096 nfsrootdebug

bootloader¶

The bootloader method is used to power-on the DUT, interrupt the bootloader, and wait for the bootloader prompt.

In order to interrupt the bootloader, the bootloader type should be specified in the bootloader parameter:

- boot
    method: bootloader
    bootloader: u-boot
    commands: []
    prompts: ['=>']

The commands parameter is required but can be kept empty. If some commands should be sent to the bootloader before the end of the action, give the list in the commands parameter.

cmsis-dap¶

The cmsis-dap boot method takes no arguments or parameters.

- boot
    method: cmsis-dap
    timeout:
      minutes: 10

depthcharge¶

The depthcharge boot method takes no arguments or parameters. It is used to boot the downloaded kernel image, and optionally a device tree and a ramdisk. The files are converted into an FIT (U-Boot Flattened Image Tree format) image suitable to be booted by Coreboot using the Depthcharge payload, typically used by Chrome OS devices. It also creates a separate text file with the kernel command line which is made available to the DUT over TFTP alongside the FIT image.

- boot:
    method: depthcharge
    commands: nfs

- deploy:
    kernel:
      url: http://storage.kernelci.org/mainline/master/v4.18-1283-g10f3e23f07cb/arm/multi_v7_defconfig/zImage
    ramdisk:
      url: http://storage.kernelci.org/images/rootfs/debian/stretchtests/20180627.0/armhf/rootfs.cpio.gz
      compression: gz

docker¶

Boot a docker image already deployed by a deploy to docker action.

- boot:
   method: docker
   command: bash
   prompts:
   - 'root@lava:'
   timeout:
     minutes: 2

fastboot¶

The fastboot boot method takes no arguments or parameters.

- boot:
    method: fastboot
    namespace: droid
    prompts:
      - 'root@(.*):/#'
      - 'hikey:/'
    timeout:
      minutes: 15

- boot:
    method: fastboot
    commands:
    - --set-active=a

fastboot-nfs¶

The fastboot-nfs boot is a method that allow you specify a nfs rootfs in a Android boot image via LXC image build and boot using fastboot boot method.

The job needs a require set of 3 primary actions:

• Deploy rootfs over NFS
• Download Kernel and DTB to LXC
• Create Android boot image with NFS details provided by NFS_{ROOTFS,SERVER_IP} environment variables

device_type: dragonboard-410c

job_name: lxc-fastboot-nfs
timeouts:
  job:
    hours: 1
  action:
    minutes: 30
priority: medium
visibility: public

metadata:
  docs-source: actions-boot-qemu-nfs
  docs-filename: doc/v2/examples/test-jobs/fastboot-nfs.yaml

protocols:
  lava-lxc:
    name: lxc-fastboot-nfs-test
    template: debian
    distribution: debian
    release: buster
    arch: amd64
    mirror: http://mirror.bytemark.co.uk/debian
    verbose: true

actions:
- deploy:
    namespace: tlxc
    timeout:
      minutes: 10
    to: lxc
    packages:
     - mkbootimg
     - fastboot
    os: debian

- deploy:
    namespace: target
    timeout:
      minutes: 5
    to: nfs
    nfsrootfs:
      url: http://releases.linaro.org/96boards/dragonboard410c/linaro/openembedded/19.01/rpb/rpb-console-image-dragonboard-410c-20190130223248-110.rootfs.tar.xz
      compression: xz
    modules:
      url: http://releases.linaro.org/96boards/dragonboard410c/linaro/openembedded/19.01/rpb/modules--4.14-r0-dragonboard-410c-20190130223248-110.tgz
      compression: gz

- boot:
    namespace: tlxc
    prompts:
    - 'root@(.*):/#'
    timeout:
      minutes: 5
    method: lxc

- deploy:
    timeout:
      minutes: 40
    to: download
    namespace: target
    images:
      kernel:
        url: http://releases.linaro.org/96boards/dragonboard410c/linaro/openembedded/19.01/rpb/Image.gz--4.14-r0-dragonboard-410c-20190130223248-110.bin
        compression:
      dtb:
        url: http://releases.linaro.org/96boards/dragonboard410c/linaro/openembedded/19.01/rpb/Image.gz--4.14-r0-apq8016-sbc-20190130223248-110.dtb
        compression:

- test:
    namespace: tlxc
    timeout:
      minutes: 10
    definitions:
    - from: inline
      name: test-testdef
      path: inline/test-testdef
      repository:
        metadata:
          description: test definition env
          format: Lava-Test Test Definition 1.0
          name: test-testdef
        run:
          steps:
          - env
          - echo "$NFS_ROOTFS"
          - echo "$NFS_SERVER_IP"
          - cd /lava-lxc/
          - cp Image.gz--4.14-r0-dragonboard-410c-20190130223248-110.bin Image.gz+dtb # OE image already has dtb appended
          - mkbootimg --kernel Image.gz+dtb --cmdline "root=/dev/nfs rw nfsroot=$NFS_SERVER_IP:$NFS_ROOTFS ip=dhcp console=tty0 console=ttyMSM0,115200n8" -o boot.img
          - ls /lava-lxc/

- deploy:
    timeout:
      minutes: 40
    to: fastboot
    namespace: target
    images:
      boot:
        url: lxc:///boot.img
    protocols:
        lava-lxc:
        - action: fastboot-deploy
          request: pre-power-command
          timeout:
              minutes: 2

- boot:
    namespace: target
    prompts:
    - 'root@(.*):[/~]#'
    timeout:
      minutes: 15
    method: fastboot
    protocols:
      lava-lxc:
      - action: auto-login-action
        request: pre-os-command
        timeout:
          minutes: 2

grub¶

The grub boot method takes no arguments or parameters.

- boot:
    method: grub
    commands: ramdisk

grub-efi¶

The grub-efi boot method takes no arguments or parameters. However, in most cases, starting Grub from UEFI requires using the uefi-menu as well.

- boot:
    timeout:
      minutes: 4
    prompts:
      - 'root@stretch:'
    method: grub-efi
    commands: nfs
    auto_login:
      login_prompt: "login:"
      username: root

Download or view the complete example: examples/test-jobs/mustang-grub-efi.yaml

ipxe¶

The ipxe boot method takes no arguments or parameters.

- boot:
    method: ipxe
    commands: ramdisk
    prompts:
    - 'root@debian:~#'
    - '/ #'

lxc¶

- boot:
    method: lxc
    prompts:
    - 'root@(.*):/#'
    timeout:
      minutes: 5

openocd¶

The openocd boot method takes no arguments or parameters.

The method works by passing through the command line options for the openocd command. It downloads and runs the executable specified by binary in the job definition. It also allows an openocd script file to be downloaded from the location specified by openocd_script in the job definition, if a custom script file should be used instead of the one specified by the device type.

board_selection_cmd can be used in the device-type to specify a command to pass the board id/serial number to OpenOCD. See OpenOCD documentation for details on the command to set the serial number for the interface your device type is using.

- boot:
    method: openocd
    timeout:
      minutes: 3

minimal¶

The minimal method is used to power-on the DUT and to let the DUT boot without any interaction.

- boot
    method: minimal
    prompts:
    - 'root@debian:~#'
    - '/ #'

By default LAVA will reset the board power when executing this action. Users can skip this step by adding reset: false. This can be useful when testing bootloader in interactive tests and then booting to the OS.

- boot
    method: minimal
    reset: false

musca¶

The musca method is used to boot musca devices. Unlike the minimal boot, the board has to be powered on before the serial will be available as the board is powered by the USB that provides the serial connection also. Therefore, the board is powered on then connection to the serial is made. Optionally, prompts can be used to check for serial output before continuing.

- boot:
    method: musca

pyocd¶

The pyocd boot method takes no arguments or parameters.

- boot:
    method: pyocd
    timeout:
      minutes: 10

jlink¶

The jlink boot method takes no arguments or parameters.

- boot:
    method: jlink
    timeout:
      minutes: 10

new_connection¶

The new_connection boot method takes no arguments or parameters. This method can be used to switch to a new connection, allowing a test to isolate test and kernel messages (if the kernel and the device are both appropriately configured).

- boot:
    # make the connection to the second uart for use in the test shell
    namespace: isolation
    connection: uart0
    method: new_connection

- test:
    namespace: hikey-oe
    connection-namespace: isolation
    timeout:
      minutes: 5
    definitions:
    - repository: http://git.linaro.org/lava-team/lava-functional-tests.git
      from: git
      path: lava-test-shell/smoke-tests-basic.yaml
      name: smoke-tests-basic-oe

qemu¶

The qemu method is used to boot the downloaded image from the deployment action using QEMU. This runs the QEMU command line on the dispatcher. Only certain elements of the command line are available for modification using the job context. The available values can vary depending on local admin configuration. For example, many admins restrict the available memory of each QEMU device, so the memory option in the job context may be ignored.

context:
  arch: aarch64
  memory: 2048
  # comment out or change to user if the dispatcher does not support bridging.
  # netdevice: tap
  extra_options:
  - -smp
  - 1
  - -global
  - virtio-blk-device.scsi=off
  - -device virtio-scsi-device,id=scsi
  - --append "console=ttyAMA0 root=/dev/vda rw"

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. buster. Information on the available versions of qemu in Debian is available at https://tracker.debian.org/pkg/qemu

- boot:
    method: qemu
    media: tmpfs

qemu-nfs¶

The qemu-nfs method is used to boot a downloaded kernel with a root filesystem deployed on the worker. Only certain elements of the command line are available for modification using the job context. The available values can vary depending on local admin configuration. For example, many admins restrict the available memory of each QEMU device, so the memory option in the job context may be ignored.

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. buster. Information on the available versions of qemu in Debian is available at https://tracker.debian.org/pkg/qemu

QEMU can be used with an NFS using the qemu-nfs method and the nfs media:

- boot:
    timeout:
      minutes: 4
    method: qemu-nfs
    connection: serial
    auto_login:
      login_prompt: 'login:'
      username: root
    prompts:
      - 'root@(.*):'

When using qemu-nfs, the hostname element of the prompt will vary according to the worker running QEMU:

- boot:
    timeout:
      minutes: 4
    method: qemu-nfs
    connection: serial
    auto_login:
      login_prompt: 'login:'
      username: root
    prompts:
      - 'root@(.*):'

- boot:
    timeout:
      minutes: 4
    method: qemu-nfs
    connection: serial
    auto_login:
      login_prompt: 'login:'
      username: root
    prompts:
      - 'root@(.*):'

qemu-iso¶

The qemu-iso method is used to boot the downloaded installer from the deployment action using QEMU. This runs the QEMU command line on the dispatcher. Only certain elements of the command line are available for modification using the job context.

The version of qemu installed on the dispatcher is a choice made by the admin. Generally, this will be the same as the version of qemu available from Debian in the same suite as the rest of the packages installed on the dispatcher, e.g. buster. Information on the available versions of qemu in Debian is available at https://tracker.debian.org/pkg/qemu

- boot:
    method: qemu-iso
    media: img
    timeout:
      minutes: 20
    connection: serial
    auto_login:
      login_prompt: 'login:'
      username: root
      password_prompt: 'Password:'
      password: root
    prompts:
    - 'root@debian:~#'

- boot:
    method: qemu-iso
    media: img

transfer_overlay¶

An overlay is a tarball of scripts which run the LAVA Test Shell for the test job. The tarball also includes the git clones of the repositories specified in the test job submission and the LAVA helper scripts. Normally, this overlay is integrated into the test job automatically. In some situations, for example when using a command list to specify an alternative rootfs, it is necessary to transfer the overlay from the worker to the device using commands within the booted system prior to starting to run the test shell.

Some overlay tarballs can be quite large. The LAVA TestShell helpers are tiny shell scripts but the git repositories cloned for your test shell definitions can become large over time. Additionally, if your test shell definition clones the git repo of source code, those clones will also appear in the overlay tarball.

The overlay is transferred before any test shell operations can occur, so the method of transferring and then unpacking the overlay must work without any further setup of the rootfs. All dependencies must be pre-installed and all configuration must be in place (possibly using a hacking session). This includes the network configuration - the worker offers an apache host to download the overlay and LAVA can populate the URL but the device must automatically configure the networking immediately upon boot and the network must work straight away.

- boot:
    transfer_overlay:
      download_command: wget -S --progress=dot:giga
      unpack_command: tar -C / -xzf

- boot:
    transfer_overlay:
      download_command: cd /tmp ; wget
      unpack_command: tar -C / -xzf

u-boot¶

The u-boot method boots the downloaded files using U-Boot commands.

uefi-menu¶

The uefi-menu method selects a pre-defined menu in the UEFI configuration for the device. In most cases, this is used to execute a different bootloader. For example, a fastboot device can execute fastboot from a menu item or a device could execute an PXE menu item to download and execute Grub.

UEFI menus will renumber themselves each time a new item is added or removed, so LAVA must be able to match the description of the menu item and then identify the correct selector to be able to send the correct character to execute that menu option. This means that the admins must create the same menu structures on each device of the same device type and correlate the text content of the menu with the jinja2 templates.

To use uefi-menu, the device must offer a menu from which items can be selected using a standard regular expression: 'a-zA-Z0-9\s\:', for example:

[1] bootloader
[2] boot from eMMC
[3] Boot Manager
[4] Reboot

The device type template would need to specify the separator (whitespace in the example) as well as how to identify the item matching the requested selector:

- boot:
    method: uefi-menu
    parameters:
      item_markup:
      - "["
      - "]"
      item_class: '0-9'
      separator: ' '

This allows LAVA to match a menu item matching \[[0-9]\] ['a-zA-Z0-9\s\:'] and select the correct selector when the menu item string matches one (and only one) line output by the UEFI menu. In this example, the selector must be a digit.

The template must then also specify which menu item to select, according to the commands set in the testjob:

- boot:
    method: uefi-menu
    commands: fastboot

The template would then need:

- boot:
    method: uefi-menu
    parameters:
      fastboot:
      - select:
          items:
          - 'boot from eMMC'

uuu¶

Integration of NXP uuu the flashing tool utility for i.mx platform.

See the complete documentation of uuu / mfgtools on GitHub https://github.com/NXPmicro/mfgtools/wiki

# INSTALLATION SCRIPT
wget https://github.com/NXPmicro/mfgtools/releases/download/<UUU_VERSION>/uuu
chmod a+x uuu
mv uuu /bin/uuu

{% set uuu_usb_otg_path = '2:143' %}
{% set uuu_corrupt_boot_media_command = ['mmc dev 1', 'mmc erase 0 0x400'] %}

$ uuu -lsusb
uuu (Universal Update Utility) for nxp imx chips -- libuuu_1.3.102-1-gddf2649
Connected Known USB Devices
    Path       Chip    Pro     Vid     Pid     BcdVersion
    ==================================================
    2:143      MX8MQ   SDP:    0x1FC9 0x012B   0x0001

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

- boot:
    method: uuu
    commands:
    - uuu: -b sd_all {boot} {system}

- uuu: -b emmc {boot}                 # Write bootloader to emmc
- uuu: -b emmc_all {boot} {system}    # Write bootloader & rootfs to emmc
- uuu: -b sd {boot}                   # Write bootloader to sd card
- uuu: -b sd_all {boot} {system}      # Write bootloader & rootfs to sd card

- boot:
    method: uuu
    commands :
    - SDPS: boot -f {boot}
    - FB: continue
    - FB: done