.. index:: deploy to tftp

.. _deploy_to_tftp:

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.

.. include:: examples/test-jobs/standard-armmp-ramdisk-bbb.yaml
     :code: yaml
     :start-after: # DEPLOY_BLOCK
     :end-before: # TEST_BLOCK

.. _deploy_to_tftp_kernel:

kernel
======

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

.. _deploy_to_tftp_kernel_type:

type
----
.. include:: actions-deploy-kernel-type.rsti

.. _deploy_to_tftp_kernel_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_dtb:

dtb
===

Device Tree Blob.

.. _deploy_to_tftp_dtb_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_dtbo:

dtbo
====

Device Tree Overlay Blob.

.. _deploy_to_tftp_dtbo_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_modules:

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.

.. _deploy_to_tftp_modules_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_modules_archive:

archive
-------
.. include:: actions-deploy-images-archive.rsti

.. _deploy_to_tftp_modules_compression:

compression
-----------
.. include:: actions-deploy-images-compression.rsti

.. _deploy_to_tftp_ramdisk:

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

.. include:: examples/test-jobs/standard-armmp-ramdisk-bbb.yaml
     :code: yaml
     :start-after: # DEPLOY_BLOCK
     :end-before: # BOOT_BLOCK

.. _deploy_to_tftp_ramdisk_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_ramdisk_archive:

archive
-------
.. include:: actions-deploy-images-archive.rsti

.. _deploy_to_tftp_ramdisk_compression:

compression
-----------
.. include:: actions-deploy-images-compression.rsti

.. index:: ramdisk header

.. _deploy_to_tftp_ramdisk_header:

header
------

If a header is already applied, the ``header`` value **must** specify the type
of header, e.g. ``u-boot``. This header will be removed before unpacking, ready
for the LAVA overlay files.

.. _deploy_to_tftp_nfsrootfs:

nfsrootfs
=========

.. include:: examples/test-jobs/standard-armmp-nfs-bbb.yaml
     :code: yaml
     :start-after: # DEPLOY_BLOCK
     :end-before: # BOOT_BLOCK

.. _deploy_to_tftp_nfsrootfs_url:

url *
-----
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tftp_nfsrootfs_archive:

archive
-------
.. include:: actions-deploy-images-archive.rsti

.. _deploy_to_tftp_nfsrootfs_compression:

compression
-----------
.. include:: actions-deploy-images-compression.rsti

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

.. code-block:: yaml

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

.. _deploy_to_tftp_persistent_nfs:

persistent_nfs
==============

A persistent NFS URL can be used instead of a compressed tarball. See
:ref:`persistence` for the limitations of persistent storage.

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

.. _deploy_to_tftp_persistent_address:

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:

.. code-block:: yaml

  - 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"

.. index:: deploy to tmpfs

.. _deploy_to_tmpfs:

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:

.. include:: examples/test-jobs/qemu-amd64-standard-stretch.yaml
     :code: yaml
     :start-after: # DEPLOY_BLOCK
     :end-before: # BOOT_BLOCK

.. _deploy_to_tmpfs_images:

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.

.. _deploy_to_tmpfs_images_label:

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.

.. include:: examples/test-jobs/qemu-amd64-standard-stretch.yaml
     :code: yaml
     :start-after: # DEPLOY_BLOCK
     :end-before: # BOOT_BLOCK

.. index:: image_arg

.. _deploy_to_tmpfs_images_image_arg:

image_arg
^^^^^^^^^

The ``image_arg`` determines how QEMU handles the image. The arguments **must**
include a placeholder :ref:`deploy_to_tmpfs_images_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.

.. _deploy_to_tmpfs_images_url:

url *
^^^^^
.. include:: actions-deploy-images-url.rsti

.. _deploy_to_tmpfs_archive:

archive
^^^^^^^
.. include:: actions-deploy-images-archive.rsti

.. _deploy_to_tmpfs_images_compression:

compression
^^^^^^^^^^^
.. include:: actions-deploy-images-compression.rsti

.. _deploy_to_tmpfs_images_md5sum:

md5sum
^^^^^^
.. include:: actions-deploy-images-md5sum.rsti

.. _deploy_to_tmpfs_images_sha256sum:

sha256sum
^^^^^^^^^
.. include:: actions-deploy-images-sha256sum.rsti

sha512sum
^^^^^^^^^
.. include:: actions-deploy-images-sha512sum.rsti
