1Transfer List Compiler
2======================
3
4The Transfer List Compiler (tlc) is a host tool used by TF-A to generate transfer
5lists compliant with the v0.9 of the `Firmware Handoff specification`_. It enables
6developers to statically generate transfer list blobs containing any number of
7transfer entries.
8
9Getting Started
10~~~~~~~~~~~~~~~
11
12``tlc`` is installed by default with TF-A's poetry environment. All of it's
13dependencies are listed in `tools/tlc/pyproject.toml`_.
14
15To install ``tlc`` seperately, run the following command:
16
17.. code::
18
19    make -C tools/tlc install
20
21Creating a Transfer List
22~~~~~~~~~~~~~~~~~~~~~~~~
23
24To create an empty TL, you can use the ``create`` command.
25
26.. code::
27
28    tlc create tl.bin
29
30This commands generates a binary blob representing an empty TL, shown in the
31hexdump below.
32
33.. code::
34
35    $ hexdump tl.bin | head
36    0000000 b10b 4a0f 01a6 0318 0018 0000 1000 0000
37    0000010 0001 0000 0000 0000
38
39A common use-case this tool supports is the addition of TE's via the option
40``--entry``. This takes as input the tag ID and path to a binary blob to be
41included in the transfer list. The snippet below shows how to include an FDT in
42the TL.
43
44.. code::
45
46    tlc create --entry 1 fdt.dtb tl.bin
47
48Alternatively, addition of a device tree is supported through the option
49``--fdt``. This has the same effect as passing the device tree and it's tag ID
50through the ``--entry`` option.
51
52.. code::
53
54    tlc create --fdt fdt.dtb tl.bin
55
56.. note::
57
58    ``tlc`` makes no effort to verify the contents of a binary blob against the
59    provided tag ID. It only checks that the tags provided as input are within
60    range and that there is sufficient memory to include their TE's.
61
62You can also create a TL from a YAML config file.
63
64.. code ::
65
66    tlc create --from-yaml config.yaml tl.bin
67
68Printing the contents of a TL
69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71Support is provided for dumping the contents of a TL via the ``info`` command.
72This prints the header of the TL and all included TE's.
73
74.. code::
75
76    $ tlc info tl.bin
77    signature  0x4a0fb10b
78    checksum   0xe1
79    version    0x1
80    hdr_size   0x18
81    alignment  0x3
82    size       0x2a6f
83    total_size 0x4e20
84    flags      0x1
85    ----
86    id         0x1
87    data_size  0x2a47
88    hdr_size   0x8
89    offset     0x18
90    ----
91    id         0x0
92    data_size  0x0
93    hdr_size   0x8
94    offset     0x2a68
95
96The example above shows the dump produced by ``tlc`` for a 20Kb TL containing a
97device tree (tag_id=1) and a NULL entry (tag_id=0).
98
99Modifying the contents of an existing TL
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
102`tlc` supports removal of one or more entries from a TL through the ``remove``
103command. It takes as argument the filename, and one or more tag ID's, passed
104through the ``--tags`` option.  It produces a valid TL blob without those
105entries.
106
107
108For example, using the same blob as in the section above, we can remove the FDT
109TE with the command.
110
111.. code::
112
113    $ tlc remove --tags 1 tl.bin
114
115Using the ``info`` command, shows the the TE has been remove:
116
117.. code::
118
119    $ tlc info tl.bin
120
121    signature  0x4a0fb10b
122    checksum   0x38
123    version    0x1
124    hdr_size   0x18
125    alignment  0x3
126    size       0x20
127    total_size 0x4e20
128    flags      0x1
129    ----
130    id         0x0
131    data_size  0x0
132    hdr_size   0x8
133    offset     0x18
134
135Note that more than one entry can be removed at a time. The ``--tags`` option
136accepts multiple tag ID's.
137
138Conversely, TE's can be added to an existing TL. This is achieved through the
139`add` command.
140
141.. code::
142
143    $ tlc add --entry 1 fdt.dtb tl.bin
144
145
146The result of this modification is shown below:
147
148.. code::
149
150    $ tlc info tl.bin
151
152    signature  0x4a0fb10b
153    checksum   0xe1
154    version    0x1
155    hdr_size   0x18
156    alignment  0x3
157    size       0x2a6f
158    total_size 0x4e20
159    flags      0x1
160    ----
161    id         0x0
162    data_size  0x0
163    hdr_size   0x8
164    offset     0x18
165    ----
166    id         0x1
167    data_size  0x2a47
168    hdr_size   0x8
169    offset     0x20
170
171Unpacking a Transfer List
172~~~~~~~~~~~~~~~~~~~~~~~~~
173
174Given a transfer list, ``tlc`` also provides a mechanism for extracting TE data.
175Running the command ``unpack``, yields binary files containing data from all the TE's.
176
177.. code::
178
179    $ tlc create --size 20000 --fdt build/fvp/debug/fdts/fvp-base-gicv3-psci.dtb tl.bin
180    $ tlc unpack tl.bin
181    $ file te_1.bin
182    te_1.bin: Device Tree Blob version 17, size=10823, boot CPU=0, string block size=851, DT structure block size=9900
183
184Validate a Transfer List
185~~~~~~~~~~~~~~~~~~~~~~~~
186
187``tlc validate`` provides a quick and simple mechanism for checking wether the TL
188is compliant with version of the specification supported by the tool. It
189performs the following checks:
190
191#. Validates the signature.
192#. Ensures that the specified version is greater than or equal to the tool’s current version.
193#. Verifies alignment criteria for all TE’s.
194
195YAML Config File Format
196~~~~~~~~~~~~~~~~~~~~~~~
197
198Example YAML config file:
199
200.. code::
201
202    execution_state: aarch32
203    has_checksum: true
204    max_size: 4096
205    entries:
206            - tag_id: 258  # entry point info
207              ep_info:
208                      args:
209                              - 67112968
210                              - 67112960
211                              - 0
212                              - 0
213                              - 0
214                              - 0
215                              - 0
216                              - 0
217                      h:
218                              attr: 8
219                              type: 1
220                              version: 2
221                      pc: 67239936
222                      spsr: 467
223            - tag_id: 3  # memory layout
224              addr: 8
225              size: 8
226            - tag_id: 1,  # fdt
227              blob_file_path: "fdt.bin",
228
229`max_size` defaults to `0x1000`, `execution_state` defaults to `aarch64`, and `has_checksum`
230defaults to `true`.
231
232The fields of the YAML file should match the fields in the specification for the transfer list. You
233don't need to give the hdr_size or data_size fields. For example, a memory layout entry would have
234an entry like:
235
236.. code::
237
238    tag_id: 3
239    addr: 8
240    size: 8
241
242You can input blob files by giving paths to the current working directory. You can do this for any
243TE type. For example, an FDT layout would have an entry like:
244
245.. code::
246
247    tag_id: 1,
248    blob_file_path: "fdt.bin",
249
250You can input C-types by giving its fields. For example, an entry point
251info entry would have an entry like:
252
253.. code::
254
255    tag_id: 258
256    ep_info:
257            args:
258                    - 67112968
259                    - 67112960
260                    - 0
261                    - 0
262            h:
263                    attr: 8
264                    type: 1
265                    version: 2
266            lr_svc: 0
267            pc: 67239936
268            spsr: 467
269
270You can give the name of the tag instead of the tag id number. The valid tag names are in the
271`transfer_entry_formats` dict in `tools/tlc/tlc/tl.py`_. Some examples are:
272
273* empty
274* fdt
275* hob_block
276* hob_list
277
278You can input the attr field of entry_point_info as a string of flag
279names separated by `|`. The names are taken from ep_info_exp.h in TF-A.
280For example:
281
282.. code::
283
284    has_checksum: true
285    max_size: 4096
286    entries:
287    - tag_id: 0x102
288      ep_info:
289        args:
290        - 67112976
291        - 67112960
292        - 0
293        - 0
294        - 0
295        - 0
296        - 0
297        - 0
298        h:
299          attr: EP_NON_SECURE | EP_ST_ENABLE
300          type: 1
301          version: 2
302        pc: 67239936
303        spsr: 965
304
305--------------
306
307*Copyright (c) 2024, Arm Limited. All rights reserved.*
308
309.. _Firmware Handoff specification: https://github.com/FirmwareHandoff/firmware_handoff/
310.. _tools/tlc/pyproject.toml: https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/refs/heads/master/tools/tlc/pyproject.toml
311.. _tools/tlc/tlc/tl.py: https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/refs/heads/master/tools/tlc/tlc/tl.py
312