docs/tools/transfer-list-compiler.rst - filogic/atf - Gitiles

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