docs/tools/transfer-list-compiler.rst

Transfer List Compiler
======================

The Transfer List Compiler (tlc) is a host tool used by TF-A to generate transfer
lists compliant with the v0.9 of the `Firmware Handoff specification`_. It enables
developers to statically generate transfer list blobs containing any number of
transfer entries.

Getting Started
~~~~~~~~~~~~~~~

``tlc`` is installed by default with TF-A's poetry environment. All of it's
dependencies are listed in `tools/tlc/pyproject.toml`_.

To install ``tlc`` seperately, run the following command:

.. code::

    make -C tools/tlc install

Creating a Transfer List
~~~~~~~~~~~~~~~~~~~~~~~~

To create an empty TL, you can use the ``create`` command.

.. code::

    tlc create tl.bin

This commands generates a binary blob representing an empty TL, shown in the
hexdump below.

.. code::

    $ hexdump tl.bin | head
    0000000 b10b 4a0f 01a6 0318 0018 0000 1000 0000
    0000010 0001 0000 0000 0000

A common use-case this tool supports is the addition of TE's via the option
``--entry``. This takes as input the tag ID and path to a binary blob to be
included in the transfer list. The snippet below shows how to include an FDT in
the TL.

.. code::

    tlc create --entry 1 fdt.dtb tl.bin

Alternatively, addition of a device tree is supported through the option
``--fdt``. This has the same effect as passing the device tree and it's tag ID
through the ``--entry`` option.

.. code::

    tlc create --fdt fdt.dtb tl.bin

.. note::

    ``tlc`` makes no effort to verify the contents of a binary blob against the
    provided tag ID. It only checks that the tags provided as input are within
    range and that there is sufficient memory to include their TE's.

You can also create a TL from a YAML config file.

.. code ::

    tlc create --from-yaml config.yaml tl.bin

Printing the contents of a TL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Support is provided for dumping the contents of a TL via the ``info`` command.
This prints the header of the TL and all included TE's.

.. code::

    $ tlc info tl.bin
    signature  0x4a0fb10b
    checksum   0xe1
    version    0x1
    hdr_size   0x18
    alignment  0x3
    size       0x2a6f
    total_size 0x4e20
    flags      0x1
    ----
    id         0x1
    data_size  0x2a47
    hdr_size   0x8
    offset     0x18
    ----
    id         0x0
    data_size  0x0
    hdr_size   0x8
    offset     0x2a68

The example above shows the dump produced by ``tlc`` for a 20Kb TL containing a
device tree (tag_id=1) and a NULL entry (tag_id=0).

Modifying the contents of an existing TL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`tlc` supports removal of one or more entries from a TL through the ``remove``
command. It takes as argument the filename, and one or more tag ID's, passed
through the ``--tags`` option.  It produces a valid TL blob without those
entries.


For example, using the same blob as in the section above, we can remove the FDT
TE with the command.

.. code::

    $ tlc remove --tags 1 tl.bin

Using the ``info`` command, shows the the TE has been remove:

.. code::

    $ tlc info tl.bin

    signature  0x4a0fb10b
    checksum   0x38
    version    0x1
    hdr_size   0x18
    alignment  0x3
    size       0x20
    total_size 0x4e20
    flags      0x1
    ----
    id         0x0
    data_size  0x0
    hdr_size   0x8
    offset     0x18

Note that more than one entry can be removed at a time. The ``--tags`` option
accepts multiple tag ID's.

Conversely, TE's can be added to an existing TL. This is achieved through the
`add` command.

.. code::

    $ tlc add --entry 1 fdt.dtb tl.bin


The result of this modification is shown below:

.. code::

    $ tlc info tl.bin

    signature  0x4a0fb10b
    checksum   0xe1
    version    0x1
    hdr_size   0x18
    alignment  0x3
    size       0x2a6f
    total_size 0x4e20
    flags      0x1
    ----
    id         0x0
    data_size  0x0
    hdr_size   0x8
    offset     0x18
    ----
    id         0x1
    data_size  0x2a47
    hdr_size   0x8
    offset     0x20

Unpacking a Transfer List
~~~~~~~~~~~~~~~~~~~~~~~~~

Given a transfer list, ``tlc`` also provides a mechanism for extracting TE data.
Running the command ``unpack``, yields binary files containing data from all the TE's.

.. code::

    $ tlc create --size 20000 --fdt build/fvp/debug/fdts/fvp-base-gicv3-psci.dtb tl.bin
    $ tlc unpack tl.bin
    $ file te_1.bin
    te_1.bin: Device Tree Blob version 17, size=10823, boot CPU=0, string block size=851, DT structure block size=9900

Validate a Transfer List
~~~~~~~~~~~~~~~~~~~~~~~~

``tlc validate`` provides a quick and simple mechanism for checking wether the TL
is compliant with version of the specification supported by the tool. It
performs the following checks:

#. Validates the signature.
#. Ensures that the specified version is greater than or equal to the tool’s current version.
#. Verifies alignment criteria for all TE’s.

YAML Config File Format
~~~~~~~~~~~~~~~~~~~~~~~

Example YAML config file:

.. code::

    execution_state: aarch32
    has_checksum: true
    max_size: 4096
    entries:
            - tag_id: 258  # entry point info
              ep_info:
                      args:
                              - 67112968
                              - 67112960
                              - 0
                              - 0
                              - 0
                              - 0
                              - 0
                              - 0
                      h:
                              attr: 8
                              type: 1
                              version: 2
                      pc: 67239936
                      spsr: 467
            - tag_id: 3  # memory layout
              addr: 8
              size: 8
            - tag_id: 1,  # fdt
              blob_file_path: "fdt.bin",

`max_size` defaults to `0x1000`, `execution_state` defaults to `aarch64`, and `has_checksum`
defaults to `true`.

The fields of the YAML file should match the fields in the specification for the transfer list. You
don't need to give the hdr_size or data_size fields. For example, a memory layout entry would have
an entry like:

.. code::

    tag_id: 3
    addr: 8
    size: 8

You can input blob files by giving paths to the current working directory. You can do this for any
TE type. For example, an FDT layout would have an entry like:

.. code::

    tag_id: 1,
    blob_file_path: "fdt.bin",

You can input C-types by giving its fields. For example, an entry point
info entry would have an entry like:

.. code::

    tag_id: 258
    ep_info:
            args:
                    - 67112968
                    - 67112960
                    - 0
                    - 0
            h:
                    attr: 8
                    type: 1
                    version: 2
            lr_svc: 0
            pc: 67239936
            spsr: 467

You can give the name of the tag instead of the tag id number. The valid tag names are in the
`transfer_entry_formats` dict in `tools/tlc/tlc/tl.py`_. Some examples are:

* empty
* fdt
* hob_block
* hob_list

You can input the attr field of entry_point_info as a string of flag
names separated by `|`. The names are taken from ep_info_exp.h in TF-A.
For example:

.. code::

    has_checksum: true
    max_size: 4096
    entries:
    - tag_id: 0x102
      ep_info:
        args:
        - 67112976
        - 67112960
        - 0
        - 0
        - 0
        - 0
        - 0
        - 0
        h:
          attr: EP_NON_SECURE | EP_ST_ENABLE
          type: 1
          version: 2
        pc: 67239936
        spsr: 965

--------------

*Copyright (c) 2024, Arm Limited. All rights reserved.*

.. _Firmware Handoff specification: https://github.com/FirmwareHandoff/firmware_handoff/
.. _tools/tlc/pyproject.toml: https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/refs/heads/master/tools/tlc/pyproject.toml
.. _tools/tlc/tlc/tl.py: https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/refs/heads/master/tools/tlc/tlc/tl.py