Commit aecbcb6e authored by Rémi Duraffort's avatar Rémi Duraffort
Browse files

Merge branch 'feature_uuu_doc' into 'master'

doc : uuu deploy/boot methods

See merge request lava/lava!1009
parents f9a2403b 06a4d382
......@@ -1158,3 +1158,118 @@ The template would then need:
- select:
items:
- 'boot from eMMC'
.. _boot_method_uuu_menu:
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
------------
``uuu`` is not provided as a dependency within LAVA, you need to install it manually over all Slaves.
You can get the latest release here : https://github.com/NXPmicro/mfgtools/releases/latest
.. code-block:: bash
# INSTALLATION SCRIPT
wget https://github.com/NXPmicro/mfgtools/releases/download/<UUU_VERSION>/uuu
chmod a+x uuu
mv uuu /bin/uuu
Device configuration
--------------------
To use ``uuu`` the :term:`device` template must specify two variables :
.. code-block:: jinja
{% set uuu_usb_otg_path = '2:143' %}
{% set uuu_corrupt_boot_media_command = ['mmc dev 1', 'mmc erase 0 0x400'] %}
* ``uuu_corrupt_boot_media_command`` : a list of commands to execute on the platform within u-boot to corrupt the primary boot media.
On the next reboot, serial download protocol must be available on the platform to flash future images using uuu.
* ``uuu_usb_otg_path`` : can be obtained using the command ``uuu -lsusb`` :
.. code-block:: shell
$ 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
Usage
-----
Following the same syntax of ``uuu`` tool, commands are specified using a pair <Protocol, Command>.
``commands`` field is then a list of dictionary with only one pair of <Protocol, Command>.
A special Protocol named ``uuu`` is defined to used build-int scripts.
.. note:: Images passed to uuu commands must be first deployed using the ``uuu`` deploy action if used with overlay.
Using the following :
.. code-block:: yaml
- 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
Both ``boot`` and ``system`` keyword are stored as images name that you can reference within ``uuu`` boot method commands.
.. warning::
``boot`` image is required by uuu boot method to perform USB serial download availability check.
The USB serial availability check consist to try to write in memory a valid bootloader image using this command ``uuu {boot}``.
If the command does not terminate within 10 seconds, primary boot-media will be erased using ``uuu_corrupt_boot_media_command``.
Using built-in scripts
^^^^^^^^^^^^^^^^^^^^^^
Example definition :
.. code-block:: yaml
- boot:
method: uuu
commands:
- uuu: -b sd_all {boot} {system}
Non-exhaustive list of available built-in scripts :
.. code-block:: yaml
- 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
Using commands
^^^^^^^^^^^^^^
Example code :
.. code-block:: yaml
- boot:
method: uuu
commands :
- SDPS: boot -f {boot}
- FB: continue
- FB: done
\ No newline at end of file
.. index:: deploy to uuu
.. _deploy_to_uuu:
to: uuu
************
.. index:: deploy to uuu images
.. _deploy_to_uuu_images:
uuu specific deploy method is very similar with :ref:`deploy_to_fastboot` method, with a required ``boot`` partition.
Partitions are usable within uuu boot method using the partition name.
.. code-block:: yaml
- 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. :
.. code-block:: yaml
- deploy:
to: uuu
images:
boot:
url: https://.../imx-boot-sd.bin-flash
- boot:
method: uuu
commands:
- uuu: -b sd {boot}
.. _deploy_to_uuu_images_url:
.. include:: actions-deploy-images-url.rsti
.. _deploy_to_uuu_images_compression:
compression
^^^^^^^^^^^
.. include:: actions-deploy-images-compression.rsti
.. _deploy_to_uuu_images_apply-overlay:
apply-overlay
^^^^^^^^^^^^^
Use this to apply LAVA specific overlays to image.
.. code-block:: yaml
- deploy:
to: uuu
images:
system:
url: http://example.com/system.img.xz
compression: xz
apply-overlay: true
.. _deploy_to_uuu_images_sparse:
sparse
^^^^^^
.. code-block:: yaml
- 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.
.. seealso:: :ref:`deploy_to_uuu_images_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.
.. code-block:: yaml
- deploy:
to: uuu
images:
system:
url: http://example.com/system.ext4.xz
compression: xz
sparse: false
.. seealso:: The sparse image format is defined in sparse_format_ in the
Android platform source code.
.. _sparse_format: https://android.googlesource.com/platform/system/core/+/master/libsparse/sparse_format.h
.. _deploy_to_uuu_images_md5sum:
md5sum
^^^^^^
.. include:: actions-deploy-images-md5sum.rsti
.. _deploy_to_uuu_images_sha256sum:
sha256sum
^^^^^^^^^
.. include:: actions-deploy-images-sha256sum.rsti
sha512sum
^^^^^^^^^
.. include:: actions-deploy-images-sha512sum.rsti
......@@ -68,6 +68,7 @@ Parameter List
.. include:: actions-deploy-to-tftp.rsti
.. include:: actions-deploy-to-usb.rsti
.. include:: actions-deploy-to-vemsd.rsti
.. include:: actions-deploy-to-uuu.rsti
.. index:: deploy os
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment