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