├── .github └── workflows │ ├── daily.yml │ └── main.yml ├── .gitignore ├── DCO ├── LICENSE ├── Makefile ├── README.md ├── contributing.rst ├── maintainers.rst └── source ├── _static └── css │ └── custom.css ├── assets └── redirect.html ├── conf.py ├── glossary.rst ├── images ├── boot_phases.svg └── handoff_list_diagram.svg ├── index.rst ├── introduction.rst ├── references.rst ├── register_conventions.rst ├── templates └── versions.html └── transfer_list.rst /.github/workflows/daily.yml: -------------------------------------------------------------------------------- 1 | name: Nightly Sphinx Build and Link Check 2 | 3 | on: 4 | schedule: 5 | - cron: "0 2 * * *" 6 | # This allows the job to be manually triggered. 7 | workflow_dispatch: 8 | 9 | jobs: 10 | build-and-check-links: 11 | name: "Build PDF and HTML documentation" 12 | runs-on: ubuntu-24.04 13 | steps: 14 | - uses: actions/checkout@v4 15 | - uses: actions/setup-python@v5 16 | - name: Install dependencies 17 | run: | 18 | sudo apt-get update 19 | sudo apt-get install -y librsvg2-bin \ 20 | python3-sphinx latexmk texlive-latex-extra \ 21 | python3-sphinxcontrib.svg2pdfconverter sphinx-multiversion \ 22 | python3-sphinx-rtd-theme 23 | 24 | - name: Build Sphinx documentation 25 | run: | 26 | make html latexpdf 27 | 28 | - name: Check for broken links 29 | run: | 30 | sphinx-build -b linkcheck source/ _build/linkcheck 31 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: Build specification 2 | on: 3 | push: 4 | branches: [main] 5 | pull_request: 6 | branches: [main] 7 | 8 | permissions: 9 | contents: write 10 | 11 | jobs: 12 | build-docs: 13 | name: "Build PDF and HTML documentation" 14 | runs-on: ubuntu-24.04 15 | steps: 16 | - uses: actions/checkout@v4 17 | - uses: actions/setup-python@v5 18 | - name: Install Packages 19 | run: | 20 | sudo apt-get update 21 | sudo apt-get install -y librsvg2-bin \ 22 | python3-sphinx latexmk texlive-latex-extra \ 23 | python3-sphinxcontrib.svg2pdfconverter sphinx-multiversion \ 24 | python3-sphinx-rtd-theme 25 | 26 | - name: Generate PDF Documentation 27 | run: | 28 | make latexpdf 29 | 30 | - name: Generate HTML Documentation 31 | run: | 32 | if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then 33 | git fetch --tags 34 | 35 | sphinx-multiversion source build/html 36 | cp source/assets/redirect.html build/html/index.html 37 | else 38 | make html 39 | fi 40 | 41 | - name: Archive PDF 42 | uses: actions/upload-artifact@v4 43 | with: 44 | name: firmware_handoff.pdf 45 | path: build/latex/firmware_handoff.pdf 46 | 47 | - name: Deploy to GitHub Pages 48 | uses: peaceiris/actions-gh-pages@v3 49 | if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} 50 | with: 51 | publish_branch: gh-pages 52 | github_token: ${{ secrets.GITHUB_TOKEN }} 53 | publish_dir: build/html 54 | force_orphan: true 55 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | *.swp 3 | *.swo 4 | source/images/*.pdf 5 | -------------------------------------------------------------------------------- /DCO: -------------------------------------------------------------------------------- 1 | Developer Certificate of Origin 2 | Version 1.1 3 | 4 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 5 | 6 | Everyone is permitted to copy and distribute verbatim copies of this 7 | license document, but changing it is not allowed. 8 | 9 | 10 | Developer's Certificate of Origin 1.1 11 | 12 | By making a contribution to this project, I certify that: 13 | 14 | (a) The contribution was created in whole or in part by me and I 15 | have the right to submit it under the open source license 16 | indicated in the file; or 17 | 18 | (b) The contribution is based upon previous work that, to the best 19 | of my knowledge, is covered under an appropriate open source 20 | license and I have the right under that license to submit that 21 | work with modifications, whether created in whole or in part 22 | by me, under the same open source license (unless I am 23 | permitted to submit under a different license), as indicated 24 | in the file; or 25 | 26 | (c) The contribution was provided directly to me by some other 27 | person who certified (a), (b) or (c) and I have not modified 28 | it. 29 | 30 | (d) I understand and agree that this project and the contribution 31 | are public and that a record of the contribution (including all 32 | personal information I submit with it, including my sign-off) is 33 | maintained indefinitely and may be redistributed consistent with 34 | this project or the open source license(s) involved. 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-ShareAlike 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-ShareAlike 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. Share means to provide material to the public by any means or 126 | process that requires permission under the Licensed Rights, such 127 | as reproduction, public display, public performance, distribution, 128 | dissemination, communication, or importation, and to make material 129 | available to the public including in ways that members of the 130 | public may access the material from a place and at a time 131 | individually chosen by them. 132 | 133 | l. Sui Generis Database Rights means rights other than copyright 134 | resulting from Directive 96/9/EC of the European Parliament and of 135 | the Council of 11 March 1996 on the legal protection of databases, 136 | as amended and/or succeeded, as well as other essentially 137 | equivalent rights anywhere in the world. 138 | 139 | m. You means the individual or entity exercising the Licensed Rights 140 | under this Public License. Your has a corresponding meaning. 141 | 142 | 143 | Section 2 -- Scope. 144 | 145 | a. License grant. 146 | 147 | 1. Subject to the terms and conditions of this Public License, 148 | the Licensor hereby grants You a worldwide, royalty-free, 149 | non-sublicensable, non-exclusive, irrevocable license to 150 | exercise the Licensed Rights in the Licensed Material to: 151 | 152 | a. reproduce and Share the Licensed Material, in whole or 153 | in part; and 154 | 155 | b. produce, reproduce, and Share Adapted Material. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. Additional offer from the Licensor -- Adapted Material. 186 | Every recipient of Adapted Material from You 187 | automatically receives an offer from the Licensor to 188 | exercise the Licensed Rights in the Adapted Material 189 | under the conditions of the Adapter's License You apply. 190 | 191 | c. No downstream restrictions. You may not offer or impose 192 | any additional or different terms or conditions on, or 193 | apply any Effective Technological Measures to, the 194 | Licensed Material if doing so restricts exercise of the 195 | Licensed Rights by any recipient of the Licensed 196 | Material. 197 | 198 | 6. No endorsement. Nothing in this Public License constitutes or 199 | may be construed as permission to assert or imply that You 200 | are, or that Your use of the Licensed Material is, connected 201 | with, or sponsored, endorsed, or granted official status by, 202 | the Licensor or others designated to receive attribution as 203 | provided in Section 3(a)(1)(A)(i). 204 | 205 | b. Other rights. 206 | 207 | 1. Moral rights, such as the right of integrity, are not 208 | licensed under this Public License, nor are publicity, 209 | privacy, and/or other similar personality rights; however, to 210 | the extent possible, the Licensor waives and/or agrees not to 211 | assert any such rights held by the Licensor to the limited 212 | extent necessary to allow You to exercise the Licensed 213 | Rights, but not otherwise. 214 | 215 | 2. Patent and trademark rights are not licensed under this 216 | Public License. 217 | 218 | 3. To the extent possible, the Licensor waives any right to 219 | collect royalties from You for the exercise of the Licensed 220 | Rights, whether directly or through a collecting society 221 | under any voluntary or waivable statutory or compulsory 222 | licensing scheme. In all other cases the Licensor expressly 223 | reserves any right to collect such royalties. 224 | 225 | 226 | Section 3 -- License Conditions. 227 | 228 | Your exercise of the Licensed Rights is expressly made subject to the 229 | following conditions. 230 | 231 | a. Attribution. 232 | 233 | 1. If You Share the Licensed Material (including in modified 234 | form), You must: 235 | 236 | a. retain the following if it is supplied by the Licensor 237 | with the Licensed Material: 238 | 239 | i. identification of the creator(s) of the Licensed 240 | Material and any others designated to receive 241 | attribution, in any reasonable manner requested by 242 | the Licensor (including by pseudonym if 243 | designated); 244 | 245 | ii. a copyright notice; 246 | 247 | iii. a notice that refers to this Public License; 248 | 249 | iv. a notice that refers to the disclaimer of 250 | warranties; 251 | 252 | v. a URI or hyperlink to the Licensed Material to the 253 | extent reasonably practicable; 254 | 255 | b. indicate if You modified the Licensed Material and 256 | retain an indication of any previous modifications; and 257 | 258 | c. indicate the Licensed Material is licensed under this 259 | Public License, and include the text of, or the URI or 260 | hyperlink to, this Public License. 261 | 262 | 2. You may satisfy the conditions in Section 3(a)(1) in any 263 | reasonable manner based on the medium, means, and context in 264 | which You Share the Licensed Material. For example, it may be 265 | reasonable to satisfy the conditions by providing a URI or 266 | hyperlink to a resource that includes the required 267 | information. 268 | 269 | 3. If requested by the Licensor, You must remove any of the 270 | information required by Section 3(a)(1)(A) to the extent 271 | reasonably practicable. 272 | 273 | b. ShareAlike. 274 | 275 | In addition to the conditions in Section 3(a), if You Share 276 | Adapted Material You produce, the following conditions also apply. 277 | 278 | 1. The Adapter's License You apply must be a Creative Commons 279 | license with the same License Elements, this version or 280 | later, or a BY-SA Compatible License. 281 | 282 | 2. You must include the text of, or the URI or hyperlink to, the 283 | Adapter's License You apply. You may satisfy this condition 284 | in any reasonable manner based on the medium, means, and 285 | context in which You Share Adapted Material. 286 | 287 | 3. You may not offer or impose any additional or different terms 288 | or conditions on, or apply any Effective Technological 289 | Measures to, Adapted Material that restrict exercise of the 290 | rights granted under the Adapter's License You apply. 291 | 292 | 293 | Section 4 -- Sui Generis Database Rights. 294 | 295 | Where the Licensed Rights include Sui Generis Database Rights that 296 | apply to Your use of the Licensed Material: 297 | 298 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 299 | to extract, reuse, reproduce, and Share all or a substantial 300 | portion of the contents of the database; 301 | 302 | b. if You include all or a substantial portion of the database 303 | contents in a database in which You have Sui Generis Database 304 | Rights, then the database in which You have Sui Generis Database 305 | Rights (but not its individual contents) is Adapted Material, 306 | 307 | including for purposes of Section 3(b); and 308 | c. You must comply with the conditions in Section 3(a) if You Share 309 | all or a substantial portion of the contents of the database. 310 | 311 | For the avoidance of doubt, this Section 4 supplements and does not 312 | replace Your obligations under this Public License where the Licensed 313 | Rights include other Copyright and Similar Rights. 314 | 315 | 316 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 317 | 318 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 319 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 320 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 321 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 322 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 323 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 324 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 325 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 326 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 327 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 328 | 329 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 330 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 331 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 332 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 333 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 334 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 335 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 336 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 337 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 338 | 339 | c. The disclaimer of warranties and limitation of liability provided 340 | above shall be interpreted in a manner that, to the extent 341 | possible, most closely approximates an absolute disclaimer and 342 | waiver of all liability. 343 | 344 | 345 | Section 6 -- Term and Termination. 346 | 347 | a. This Public License applies for the term of the Copyright and 348 | Similar Rights licensed here. However, if You fail to comply with 349 | this Public License, then Your rights under this Public License 350 | terminate automatically. 351 | 352 | b. Where Your right to use the Licensed Material has terminated under 353 | Section 6(a), it reinstates: 354 | 355 | 1. automatically as of the date the violation is cured, provided 356 | it is cured within 30 days of Your discovery of the 357 | violation; or 358 | 359 | 2. upon express reinstatement by the Licensor. 360 | 361 | For the avoidance of doubt, this Section 6(b) does not affect any 362 | right the Licensor may have to seek remedies for Your violations 363 | of this Public License. 364 | 365 | c. For the avoidance of doubt, the Licensor may also offer the 366 | Licensed Material under separate terms or conditions or stop 367 | distributing the Licensed Material at any time; however, doing so 368 | will not terminate this Public License. 369 | 370 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 371 | License. 372 | 373 | 374 | Section 7 -- Other Terms and Conditions. 375 | 376 | a. The Licensor shall not be bound by any additional or different 377 | terms or conditions communicated by You unless expressly agreed. 378 | 379 | b. Any arrangements, understandings, or agreements regarding the 380 | Licensed Material not stated herein are separate from and 381 | independent of the terms and conditions of this Public License. 382 | 383 | 384 | Section 8 -- Interpretation. 385 | 386 | a. For the avoidance of doubt, this Public License does not, and 387 | shall not be interpreted to, reduce, limit, restrict, or impose 388 | conditions on any use of the Licensed Material that could lawfully 389 | be made without permission under this Public License. 390 | 391 | b. To the extent possible, if any provision of this Public License is 392 | deemed unenforceable, it shall be automatically reformed to the 393 | minimum extent necessary to make it enforceable. If the provision 394 | cannot be reformed, it shall be severed from this Public License 395 | without affecting the enforceability of the remaining terms and 396 | conditions. 397 | 398 | c. No term or condition of this Public License will be waived and no 399 | failure to comply consented to unless expressly agreed to by the 400 | Licensor. 401 | 402 | d. Nothing in this Public License constitutes or may be interpreted 403 | as a limitation upon, or waiver of, any privileges and immunities 404 | that apply to the Licensor or You, including from the legal 405 | processes of any jurisdiction or authority. 406 | 407 | 408 | ======================================================================= 409 | 410 | Creative Commons is not a party to its public 411 | licenses. Notwithstanding, Creative Commons may elect to apply one of 412 | its public licenses to material it publishes and in those instances 413 | will be considered the “Licensor.” The text of the Creative Commons 414 | public licenses is dedicated to the public domain under the CC0 Public 415 | Domain Dedication. Except for the limited purpose of indicating that 416 | material is shared under a Creative Commons public license or as 417 | otherwise permitted by the Creative Commons policies published at 418 | creativecommons.org/policies, Creative Commons does not authorize the 419 | use of the trademark "Creative Commons" or any other trademark or logo 420 | of Creative Commons without its prior written consent including, 421 | without limitation, in connection with any unauthorized modifications 422 | to any of its public licenses or any other arrangements, 423 | understandings, or agreements concerning use of licensed material. For 424 | the avoidance of doubt, this paragraph does not form part of the 425 | public licenses. 426 | 427 | Creative Commons may be contacted at creativecommons.org. 428 | 429 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | IMG_DIR = source/images 5 | IMG_SRC = $(wildcard $(IMG_DIR)/*.svg) 6 | IMG_TGT = $(patsubst %.svg,%.pdf,$(IMG_SRC)) 7 | 8 | # You can set these variables from the command line. 9 | SPHINXOPTS = 10 | SPHINXBUILD = sphinx-build 11 | SOURCEDIR = source 12 | BUILDDIR = build 13 | 14 | # Put it first so that "make" without argument is like "make help". 15 | help: 16 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 17 | 18 | .PHONY: help Makefile images 19 | 20 | images: $(IMG_TGT) 21 | 22 | %svg:; 23 | 24 | %.pdf: %.svg 25 | @rsvg-convert -f pdf -o $@ $< 26 | 27 | # Catch-all target: route all unknown targets to Sphinx using the new 28 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 29 | %: Makefile images 30 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 31 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Build Status](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/main.yml/badge.svg)](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/main.yml) 2 | [![Daily Status](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/daily.yml/badge.svg)](https://github.com/FirmwareHandoff/firmware_handoff/actions/workflows/daily.yml) 3 | [![Release Version](https://img.shields.io/github/v/release/FirmwareHandoff/firmware_handoff?label=release)](https://github.com/FirmwareHandoff/firmware_handoff/releases) 4 | 5 | This repository contains the Firmware Handoff specification, which defines a 6 | data structure to transfer essential configuration information between firmware 7 | stages during platform initialization. 8 | 9 | The documentation is generated using the Sphinx framework. A version of this 10 | specification, rendered in HTML, is available 11 | [here](https://firmwarehandoff.github.io/firmware_handoff/). 12 | 13 | Project dependencies 14 | ==================== 15 | 16 | For an Ubuntu development machine, install the following packages to build the specification: 17 | 18 | - `librsvg2-bin` 19 | - `python3-sphinx` 20 | - `python3-sphinxcontrib.svg2pdfconverter` 21 | - `python3-sphinx-rtd-theme` 22 | - `sphinx-multiversion` 23 | - `latexmk` 24 | - `texlive-latex-extra` 25 | 26 | **Note:** This list has been tested on Ubuntu 22.04 LTS and 24.04 LTS running on AArch64 and AMD64. 27 | 28 | Building the document 29 | ===================== 30 | 31 | The following are use to generate the specification: 32 | 33 | - pdf: 34 | 35 | ``` sh 36 | make latexpdf 37 | ``` 38 | 39 | - html: 40 | 41 | ``` sh 42 | make html 43 | ``` 44 | 45 | The output of these build commands goes into subdirectory `build`. 46 | 47 | Status 48 | ====== 49 | 50 | The first release of the specification has been published. We are currently in 51 | the implementation phase, looking at various target projects, including U-Boot, 52 | coreboot, TF-A and Tianocore. Once this is done we will review the result to see 53 | if any serious flaws have come to light, meaning that changes are needed. If 54 | so, these will be undertaken in each project. 55 | 56 | By the end of 2024, the spec will be considered stable and will be published 57 | as version 1. From there on, backwards compatibility will be maintained. 58 | -------------------------------------------------------------------------------- /contributing.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | Contributing 5 | ============ 6 | 7 | The master copy of this project is hosted on GitHub: 8 | https://github.com/FirmwareHandoff/firmware_handoff 9 | 10 | Developer Certificate of Origin certification 11 | --------------------------------------------- 12 | 13 | Anyone may contribute to the FirmwareHandoff project. Contributions are 14 | licensed under CC-BY-SA-4.0 (see LICENSE_) and must be made with a Development 15 | Certificate of Origin (see DCO_) attestation. 16 | 17 | To help track the origin of contributions, this project uses the same DCO 18 | "sign-off" process as used by the Linux kernel. The sign-off is a simple line, 19 | at the end of the explanation for the patch, which certifies that you wrote it 20 | or otherwise have the right to pass it on as an open-source patch. 21 | Any contribution must contain the sign-off line at the end of the explanation in every patch message. 22 | The following is an example of a sign-off line:: 23 | 24 | Signed-off-by: Random J Developer 25 | 26 | Criteria for patch merge 27 | ------------------------ 28 | 29 | Any contribution must be assessed by the maintainers (see Maintainers_). 30 | A contribution must be acknowledged by every maintainer before being merged. 31 | 32 | This specification adopts a lower-case variation of RFC2119. 33 | The Language used to specify requirements and recommendations must comply with [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). 34 | 35 | .. _DCO: DCO 36 | .. _LICENSE: LICENSE 37 | .. _Maintainers: maintainers.rst 38 | 39 | -------------------------------------------------------------------------------- /maintainers.rst: -------------------------------------------------------------------------------- 1 | .. |M| replace:: **Mail** 2 | .. |G| replace:: **GitHub ID** 3 | 4 | :|M|: Dan Handley 5 | :|G|: `danh-arm`_ 6 | :|M|: Manish Pandey 7 | :|G|: `manish-pandey-arm`_ 8 | :|M|: Ilias Apalodims 9 | :|G|: `apalos`_ 10 | :|M|: Rob Herring 11 | :|G|: `robherring`_ 12 | :|M|: Simon Glass 13 | :|G|: `sjg20`_ 14 | :|M|: Jose Marinho 15 | :|G|: `jmarinho`_ 16 | 17 | .. _danh-arm: https://github.com/danh-arm 18 | .. _manish-pandey-arm: https://github.com/manish-pandey-arm 19 | .. _apalos: https://github.com/apalos 20 | .. _robherring: https://github.com/robherring 21 | .. _sjg20: https://github.com/sjg20 22 | .. _jmarinho: https://github.com/jmarinho 23 | -------------------------------------------------------------------------------- /source/_static/css/custom.css: -------------------------------------------------------------------------------- 1 | /* 2 | * SPDX-License-Identifier: CC-BY-SA-4.0 3 | * SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 4 | */ 5 | 6 | /* 7 | * Set the white-space property of tables to normal. 8 | * With this setting sequences of whitespace inside 9 | * a table will collapse into a single whitespace, 10 | * and text will wrap when necessary. 11 | */ 12 | 13 | .wy-table-responsive table td { 14 | white-space: normal; 15 | } 16 | -------------------------------------------------------------------------------- /source/assets/redirect.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Redirecting to main branch 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Configuration file for the Sphinx documentation builder. 4 | # 5 | # This file does only contain a selection of the most common options. For a 6 | # full list see the documentation: 7 | # http://www.sphinx-doc.org/en/master/config 8 | 9 | # -- Path setup -------------------------------------------------------------- 10 | 11 | # If extensions (or modules to document with autodoc) are in another directory, 12 | # add these directories to sys.path here. If the directory is relative to the 13 | # documentation root, use os.path.abspath to make it absolute, like shown here. 14 | # 15 | # import os 16 | # import sys 17 | # sys.path.insert(0, os.path.abspath('.')) 18 | 19 | 20 | # -- Project information ----------------------------------------------------- 21 | 22 | project = "Firmware Handoff" 23 | copyright = "2022-2025, Firmware handoff contributors" 24 | author = "Firmware handoff contributors" 25 | 26 | # The short X.Y version 27 | version = "1.0" 28 | # The full version, including alpha/beta/rc tags 29 | release = "1.0" 30 | 31 | 32 | # -- General configuration --------------------------------------------------- 33 | 34 | # If your documentation needs a minimal Sphinx version, state it here. 35 | # 36 | # needs_sphinx = '1.0' 37 | 38 | # Add any Sphinx extension module names here, as strings. They can be 39 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 40 | # ones. 41 | extensions = [ 42 | "sphinx.ext.imgmath", 43 | ] 44 | 45 | # Add any paths that contain templates here, relative to this directory. 46 | templates_path = ["templates"] 47 | 48 | # The suffix(es) of source filenames. 49 | # You can specify multiple suffix as a list of string: 50 | # 51 | # source_suffix = ['.rst', '.md'] 52 | source_suffix = ".rst" 53 | 54 | # The master toctree document. 55 | master_doc = "index" 56 | 57 | # The language for content autogenerated by Sphinx. Refer to documentation 58 | # for a list of supported languages. 59 | # 60 | # This is also used if you do content translation via gettext catalogs. 61 | # Usually you set "language" from the command line for these cases. 62 | language = "en" 63 | 64 | # List of patterns, relative to source directory, that match files and 65 | # directories to ignore when looking for source files. 66 | # This pattern also affects html_static_path and html_extra_path. 67 | exclude_patterns = [] 68 | 69 | # The name of the Pygments (syntax highlighting) style to use. 70 | pygments_style = None 71 | 72 | linkcheck_ignore = [r'https://uefi\.org/specs/.*',] 73 | 74 | # -- Options for HTML output ------------------------------------------------- 75 | 76 | # The theme to use for HTML and HTML Help pages. See the documentation for 77 | # a list of builtin themes. 78 | # 79 | html_theme = "sphinx_rtd_theme" 80 | 81 | # Theme options are theme-specific and customize the look and feel of a theme 82 | # further. For a list of options available for each theme, see the 83 | # documentation. 84 | # 85 | # html_theme_options = {} 86 | 87 | # Custom sidebar templates, must be a dictionary that maps document names 88 | # to template names. 89 | # 90 | # The default sidebars (for documents that don't match any pattern) are 91 | # defined by theme itself. Builtin themes are using these templates by 92 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', 93 | # 'searchbox.html']``. 94 | # 95 | 96 | html_sidebars = {} 97 | 98 | # Path to _static directory 99 | html_static_path = ["_static"] 100 | 101 | # Path to css file relative to html_static_path 102 | html_css_files = [ 103 | "css/custom.css", 104 | ] 105 | 106 | # -- Options for HTMLHelp output --------------------------------------------- 107 | 108 | # Output file base name for HTML help builder. 109 | htmlhelp_basename = "firmware_handoffdoc" 110 | 111 | 112 | # -- Options for LaTeX output ------------------------------------------------ 113 | 114 | latex_elements = { 115 | "pointsize": "11pt", 116 | "extraclassoptions": "openany,oneside", 117 | # The paper size ('letterpaper' or 'a4paper'). 118 | # 119 | # 'papersize': 'letterpaper', 120 | # The font size ('10pt', '11pt' or '12pt'). 121 | # 122 | # 'pointsize': '10pt', 123 | # Additional stuff for the LaTeX preamble. 124 | # 125 | # 'preamble': '', 126 | # Latex figure (float) alignment 127 | # 128 | # 'figure_align': 'htbp', 129 | } 130 | 131 | # Grouping the document tree into LaTeX files. List of tuples 132 | # (source start file, target name, title, 133 | # author, documentclass [howto, manual, or own class]). 134 | latex_documents = [ 135 | ( 136 | master_doc, 137 | "firmware_handoff.tex", 138 | "Firmware Handoff Specification", 139 | "", 140 | "manual", 141 | ), 142 | ] 143 | 144 | 145 | # -- Options for manual page output ------------------------------------------ 146 | 147 | # One entry per manual page. List of tuples 148 | # (source start file, name, description, authors, manual section). 149 | man_pages = [ 150 | (master_doc, "firmware_handoff", "Firmware_handoff Documentation", [author], 1) 151 | ] 152 | 153 | 154 | # -- Options for Texinfo output ---------------------------------------------- 155 | 156 | # Grouping the document tree into Texinfo files. List of tuples 157 | # (source start file, target name, title, author, 158 | # dir menu entry, description, category) 159 | texinfo_documents = [ 160 | ( 161 | master_doc, 162 | "firmware_handoff", 163 | "Firmware_handoff Documentation", 164 | author, 165 | "firmware_handoff", 166 | "One line description of project.", 167 | "Miscellaneous", 168 | ), 169 | ] 170 | 171 | 172 | # -- Options for Epub output ------------------------------------------------- 173 | 174 | # Bibliographic Dublin Core info. 175 | epub_title = project 176 | 177 | # The unique identifier of the text. This can be a ISBN number 178 | # or the project homepage. 179 | # 180 | # epub_identifier = '' 181 | 182 | # A unique identification for the text. 183 | # 184 | # epub_uid = '' 185 | 186 | # A list of files that should not be packed into the epub file. 187 | epub_exclude_files = ["search.html"] 188 | 189 | # -- Custom project configs --------------------------------------------------- 190 | 191 | numfig = True 192 | numfig_secnum_depth = 0 193 | 194 | 195 | # Add the extension 196 | extensions += [ 197 | "sphinx.ext.autosectionlabel", 198 | "sphinxcontrib.rsvgconverter", 199 | "sphinx_multiversion", 200 | ] 201 | 202 | # Make sure the target is unique 203 | autosectionlabel_prefix_document = True 204 | 205 | # -- Extension configuration ------------------------------------------------- 206 | -------------------------------------------------------------------------------- /source/glossary.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | Glossary 5 | ======== 6 | 7 | This glossary provides definitions for terms and abbreviations used in the 8 | Firmware Handoff documentation. 9 | 10 | .. glossary:: 11 | :sorted: 12 | 13 | AArch32 14 | 32-bit execution state of the Arm A-profile architecture 15 | 16 | AArch64 17 | 64-bit execution state of the Arm A-profile architecture 18 | 19 | ACPI 20 | Advanced Configuration and Power Interface 21 | 22 | AP 23 | Application Processor 24 | 25 | Blob List 26 | Bloblist is an U-boot implementation of the Firmware Handoff protocol 27 | 28 | DT 29 | Device Tree 30 | 31 | FDT 32 | Flattened Device Tree 33 | 34 | FF-A 35 | Firmware Framework for Arm A-profile 36 | 37 | HOB 38 | Hand-Off Block 39 | 40 | MMIO 41 | Memory-Mapped I/O 42 | 43 | OP-TEE 44 | Open Portable Trusted Execution Environment 45 | 46 | OS 47 | Operating System 48 | 49 | PI 50 | Platform Initialization 51 | 52 | SP 53 | Secure Partition 54 | 55 | SPM 56 | Secure Partition Manager 57 | 58 | SPMC 59 | Secure Partition Manager Core 60 | 61 | SPMD 62 | Secure Partition Manager Dispatcher 63 | 64 | SPMCATTR 65 | Attribute defined in the SPMC Manifest 66 | 67 | Tag-ID 68 | An Identifier to determine content of Transfer Entry 69 | 70 | TCG-EFI 71 | Trusted Computing Group Extensible Firmware Interface 72 | 73 | TE 74 | Transfer Entry 75 | 76 | TF-A 77 | Trusted Firmware-A 78 | 79 | TL 80 | Transfer List 81 | 82 | TFAFFAMB 83 | TF-A Secure Partition Manager: FF-A Manifest Binding 84 | 85 | TPM 86 | Trusted Platform Module 87 | 88 | TPM CRB 89 | Trusted Platform Module Command Response Buffer 90 | -------------------------------------------------------------------------------- /source/images/boot_phases.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | Board 16 | Controller 17 | 18 | 19 | 20 | 21 | 22 | Immutable 23 | 24 | 25 | 26 | Application Processor 27 | 28 | 29 | 30 | 31 | Secure 32 | Platform 33 | Firmware 34 | 35 | 36 | 37 | 38 | 39 | OS 40 | Bootloader 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | -------------------------------------------------------------------------------- /source/images/handoff_list_diagram.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 21 | 23 | 24 | 26 | image/svg+xml 27 | 29 | 30 | 31 | 32 | 55 | 57 | div.MathJax_SVG_Display { position: static; } 59 | span.MathJax_SVG { position: static !important; } 60 | .MathJax_Hover_Frame {border-radius: .25em; -webkit-border-radius: .25em; -moz-border-radius: .25em; -khtml-border-radius: .25em; box-shadow: 0px 0px 15px #83A; -webkit-box-shadow: 0px 0px 15px #83A; -moz-box-shadow: 0px 0px 15px #83A; -khtml-box-shadow: 0px 0px 15px #83A; border: 1px solid #A6D ! important; display: inline-block; position: absolute} 62 | .MathJax_Menu_Button .MathJax_Hover_Arrow {position: absolute; cursor: pointer; display: inline-block; border: 2px solid #AAA; border-radius: 4px; -webkit-border-radius: 4px; -moz-border-radius: 4px; -khtml-border-radius: 4px; font-family: 'Courier New',Courier; font-size: 9px; color: #F0F0F0} 63 | .MathJax_Menu_Button .MathJax_Hover_Arrow span {display: block; background-color: #AAA; border: 1px solid; border-radius: 3px; line-height: 0; padding: 4px} 64 | .MathJax_Hover_Arrow:hover {color: white!important; border: 2px solid #CCC!important} 65 | .MathJax_Hover_Arrow:hover span {background-color: #CCC!important} 66 | 67 | #MathJax_About {position: fixed; left: 50%; width: auto; text-align: center; border: 3px outset; padding: 1em 2em; background-color: #DDDDDD; color: black; cursor: default; font-family: message-box; font-size: 120%; font-style: normal; text-indent: 0; text-transform: none; line-height: normal; letter-spacing: normal; word-spacing: normal; word-wrap: normal; white-space: nowrap; float: none; z-index: 201; border-radius: 15px; -webkit-border-radius: 15px; -moz-border-radius: 15px; -khtml-border-radius: 15px; box-shadow: 0px 10px 20px #808080; -webkit-box-shadow: 0px 10px 20px #808080; -moz-box-shadow: 0px 10px 20px #808080; -khtml-box-shadow: 0px 10px 20px #808080; filter: progid:DXImageTransform.Microsoft.dropshadow(OffX=2, OffY=2, Color='gray', Positive='true')} 69 | #MathJax_About.MathJax_MousePost {outline: none} 70 | .MathJax_Menu {position: absolute; background-color: white; color: black; width: auto; padding: 2px; border: 1px solid #CCCCCC; margin: 0; cursor: default; font: menu; text-align: left; text-indent: 0; text-transform: none; line-height: normal; letter-spacing: normal; word-spacing: normal; word-wrap: normal; white-space: nowrap; float: none; z-index: 201; box-shadow: 0px 10px 20px #808080; -webkit-box-shadow: 0px 10px 20px #808080; -moz-box-shadow: 0px 10px 20px #808080; -khtml-box-shadow: 0px 10px 20px #808080; filter: progid:DXImageTransform.Microsoft.dropshadow(OffX=2, OffY=2, Color='gray', Positive='true')} 71 | .MathJax_MenuItem {padding: 2px 2em; background: transparent} 72 | .MathJax_MenuArrow {position: absolute; right: .5em; padding-top: .25em; color: #666666; font-size: .75em} 73 | .MathJax_MenuActive .MathJax_MenuArrow {color: white} 74 | .MathJax_MenuArrow.RTL {left: .5em; right: auto} 75 | .MathJax_MenuCheck {position: absolute; left: .7em} 76 | .MathJax_MenuCheck.RTL {right: .7em; left: auto} 77 | .MathJax_MenuRadioCheck {position: absolute; left: 1em} 78 | .MathJax_MenuRadioCheck.RTL {right: 1em; left: auto} 79 | .MathJax_MenuLabel {padding: 2px 2em 4px 1.33em; font-style: italic} 80 | .MathJax_MenuRule {border-top: 1px solid #CCCCCC; margin: 4px 1px 0px} 81 | .MathJax_MenuDisabled {color: GrayText} 82 | .MathJax_MenuActive {background-color: Highlight; color: HighlightText} 83 | .MathJax_MenuDisabled:focus, .MathJax_MenuLabel:focus {background-color: #E8E8E8} 84 | .MathJax_ContextMenu:focus {outline: none} 85 | .MathJax_ContextMenu .MathJax_MenuItem:focus {outline: none} 86 | #MathJax_AboutClose {top: .2em; right: .2em} 87 | .MathJax_Menu .MathJax_MenuClose {top: -10px; left: -10px} 88 | .MathJax_MenuClose {position: absolute; cursor: pointer; display: inline-block; border: 2px solid #AAA; border-radius: 18px; -webkit-border-radius: 18px; -moz-border-radius: 18px; -khtml-border-radius: 18px; font-family: 'Courier New',Courier; font-size: 24px; color: #F0F0F0} 89 | .MathJax_MenuClose span {display: block; background-color: #AAA; border: 1.5px solid; border-radius: 18px; -webkit-border-radius: 18px; -moz-border-radius: 18px; -khtml-border-radius: 18px; line-height: 0; padding: 8px 0 6px} 90 | .MathJax_MenuClose:hover {color: white!important; border: 2px solid #CCC!important} 91 | .MathJax_MenuClose:hover span {background-color: #CCC!important} 92 | .MathJax_MenuClose:hover:focus {outline: none} 93 | 94 | .MathJax_Preview .MJXf-math {color: inherit!important} 96 | 97 | #MathJax_Zoom {position: absolute; background-color: #F0F0F0; overflow: auto; display: block; z-index: 301; padding: .5em; border: 1px solid black; margin: 0; font-weight: normal; font-style: normal; text-align: left; text-indent: 0; text-transform: none; line-height: normal; letter-spacing: normal; word-spacing: normal; word-wrap: normal; white-space: nowrap; float: none; -webkit-box-sizing: content-box; -moz-box-sizing: content-box; box-sizing: content-box; box-shadow: 5px 5px 15px #AAAAAA; -webkit-box-shadow: 5px 5px 15px #AAAAAA; -moz-box-shadow: 5px 5px 15px #AAAAAA; -khtml-box-shadow: 5px 5px 15px #AAAAAA; filter: progid:DXImageTransform.Microsoft.dropshadow(OffX=2, OffY=2, Color='gray', Positive='true')} 99 | #MathJax_ZoomOverlay {position: absolute; left: 0; top: 0; z-index: 300; display: inline-block; width: 100%; height: 100%; border: 0; padding: 0; margin: 0; background-color: white; opacity: 0; filter: alpha(opacity=0)} 100 | #MathJax_ZoomFrame {position: relative; display: inline-block; height: 0; width: 0} 101 | #MathJax_ZoomEventTrap {position: absolute; left: 0; top: 0; z-index: 302; display: inline-block; border: 0; padding: 0; margin: 0; background-color: white; opacity: 0; filter: alpha(opacity=0)} 102 | 103 | .MathJax_Preview {color: #888; display: contents} 105 | #MathJax_Message {position: fixed; left: 1em; bottom: 1.5em; background-color: #E6E6E6; border: 1px solid #959595; margin: 0px; padding: 2px 8px; z-index: 102; color: black; font-size: 80%; width: auto; white-space: nowrap} 106 | #MathJax_MSIE_Frame {position: absolute; top: 0; left: 0; width: 0px; z-index: 101; border: 0px; margin: 0px; padding: 0px} 107 | .MathJax_Error {color: #CC0000; font-style: italic} 108 | 109 | .MJXp-script {font-size: .8em} 111 | .MJXp-right {-webkit-transform-origin: right; -moz-transform-origin: right; -ms-transform-origin: right; -o-transform-origin: right; transform-origin: right} 112 | .MJXp-bold {font-weight: bold} 113 | .MJXp-italic {font-style: italic} 114 | .MJXp-scr {font-family: MathJax_Script,'Times New Roman',Times,STIXGeneral,serif} 115 | .MJXp-frak {font-family: MathJax_Fraktur,'Times New Roman',Times,STIXGeneral,serif} 116 | .MJXp-sf {font-family: MathJax_SansSerif,'Times New Roman',Times,STIXGeneral,serif} 117 | .MJXp-cal {font-family: MathJax_Caligraphic,'Times New Roman',Times,STIXGeneral,serif} 118 | .MJXp-mono {font-family: MathJax_Typewriter,'Times New Roman',Times,STIXGeneral,serif} 119 | .MJXp-largeop {font-size: 150%} 120 | .MJXp-largeop.MJXp-int {vertical-align: -.2em} 121 | .MJXp-math {display: inline-block; line-height: 1.2; text-indent: 0; font-family: 'Times New Roman',Times,STIXGeneral,serif; white-space: nowrap; border-collapse: collapse} 122 | .MJXp-display {display: block; text-align: center; margin: 1em 0} 123 | .MJXp-math span {display: inline-block} 124 | .MJXp-box {display: block!important; text-align: center} 125 | .MJXp-box:after {content: " "} 126 | .MJXp-rule {display: block!important; margin-top: .1em} 127 | .MJXp-char {display: block!important} 128 | .MJXp-mo {margin: 0 .15em} 129 | .MJXp-mfrac {margin: 0 .125em; vertical-align: .25em} 130 | .MJXp-denom {display: inline-table!important; width: 100%} 131 | .MJXp-denom > * {display: table-row!important} 132 | .MJXp-surd {vertical-align: top} 133 | .MJXp-surd > * {display: block!important} 134 | .MJXp-script-box > * {display: table!important; height: 50%} 135 | .MJXp-script-box > * > * {display: table-cell!important; vertical-align: top} 136 | .MJXp-script-box > *:last-child > * {vertical-align: bottom} 137 | .MJXp-script-box > * > * > * {display: block!important} 138 | .MJXp-mphantom {visibility: hidden} 139 | .MJXp-munderover, .MJXp-munder {display: inline-table!important} 140 | .MJXp-over {display: inline-block!important; text-align: center} 141 | .MJXp-over > * {display: block!important} 142 | .MJXp-munderover > *, .MJXp-munder > * {display: table-row!important} 143 | .MJXp-mtable {vertical-align: .25em; margin: 0 .125em} 144 | .MJXp-mtable > * {display: inline-table!important; vertical-align: middle} 145 | .MJXp-mtr {display: table-row!important} 146 | .MJXp-mtd {display: table-cell!important; text-align: center; padding: .5em 0 0 .5em} 147 | .MJXp-mtr > .MJXp-mtd:first-child {padding-left: 0} 148 | .MJXp-mtr:first-child > .MJXp-mtd {padding-top: 0} 149 | .MJXp-mlabeledtr {display: table-row!important} 150 | .MJXp-mlabeledtr > .MJXp-mtd:first-child {padding-left: 0} 151 | .MJXp-mlabeledtr:first-child > .MJXp-mtd {padding-top: 0} 152 | .MJXp-merror {background-color: #FFFF88; color: #CC0000; border: 1px solid #CC0000; padding: 1px 3px; font-style: normal; font-size: 90%} 153 | .MJXp-scale0 {-webkit-transform: scaleX(.0); -moz-transform: scaleX(.0); -ms-transform: scaleX(.0); -o-transform: scaleX(.0); transform: scaleX(.0)} 154 | .MJXp-scale1 {-webkit-transform: scaleX(.1); -moz-transform: scaleX(.1); -ms-transform: scaleX(.1); -o-transform: scaleX(.1); transform: scaleX(.1)} 155 | .MJXp-scale2 {-webkit-transform: scaleX(.2); -moz-transform: scaleX(.2); -ms-transform: scaleX(.2); -o-transform: scaleX(.2); transform: scaleX(.2)} 156 | .MJXp-scale3 {-webkit-transform: scaleX(.3); -moz-transform: scaleX(.3); -ms-transform: scaleX(.3); -o-transform: scaleX(.3); transform: scaleX(.3)} 157 | .MJXp-scale4 {-webkit-transform: scaleX(.4); -moz-transform: scaleX(.4); -ms-transform: scaleX(.4); -o-transform: scaleX(.4); transform: scaleX(.4)} 158 | .MJXp-scale5 {-webkit-transform: scaleX(.5); -moz-transform: scaleX(.5); -ms-transform: scaleX(.5); -o-transform: scaleX(.5); transform: scaleX(.5)} 159 | .MJXp-scale6 {-webkit-transform: scaleX(.6); -moz-transform: scaleX(.6); -ms-transform: scaleX(.6); -o-transform: scaleX(.6); transform: scaleX(.6)} 160 | .MJXp-scale7 {-webkit-transform: scaleX(.7); -moz-transform: scaleX(.7); -ms-transform: scaleX(.7); -o-transform: scaleX(.7); transform: scaleX(.7)} 161 | .MJXp-scale8 {-webkit-transform: scaleX(.8); -moz-transform: scaleX(.8); -ms-transform: scaleX(.8); -o-transform: scaleX(.8); transform: scaleX(.8)} 162 | .MJXp-scale9 {-webkit-transform: scaleX(.9); -moz-transform: scaleX(.9); -ms-transform: scaleX(.9); -o-transform: scaleX(.9); transform: scaleX(.9)} 163 | .MathJax_PHTML .noError {vertical-align: ; font-size: 90%; text-align: left; color: black; padding: 1px 3px; border: 1px solid} 164 | 165 | .MathJax_SVG_Display {text-align: center; margin: 1em 0em; position: relative; display: block!important; text-indent: 0; max-width: none; max-height: none; min-width: 0; min-height: 0; width: 100%} 167 | .MathJax_SVG .MJX-monospace {font-family: monospace} 168 | .MathJax_SVG .MJX-sans-serif {font-family: sans-serif} 169 | #MathJax_SVG_Tooltip {background-color: InfoBackground; color: InfoText; border: 1px solid black; box-shadow: 2px 2px 5px #AAAAAA; -webkit-box-shadow: 2px 2px 5px #AAAAAA; -moz-box-shadow: 2px 2px 5px #AAAAAA; -khtml-box-shadow: 2px 2px 5px #AAAAAA; padding: 3px 4px; z-index: 401; position: absolute; left: 0; top: 0; width: auto; height: auto; display: none} 170 | .MathJax_SVG {display: inline; font-style: normal; font-weight: normal; line-height: normal; font-size: 100%; font-size-adjust: none; text-indent: 0; text-align: left; text-transform: none; letter-spacing: normal; word-spacing: normal; word-wrap: normal; white-space: nowrap; float: none; direction: ltr; max-width: none; max-height: none; min-width: 0; min-height: 0; border: 0; padding: 0; margin: 0} 171 | .MathJax_SVG * {transition: none; -webkit-transition: none; -moz-transition: none; -ms-transition: none; -o-transition: none} 172 | .MathJax_SVG > div {display: inline-block} 173 | .mjx-svg-href {fill: blue; stroke: blue} 174 | .MathJax_SVG_Processing {visibility: hidden; position: absolute; top: 0; left: 0; width: 0; height: 0; overflow: hidden; display: block!important} 175 | .MathJax_SVG_Processed {display: none!important} 176 | .MathJax_SVG_test {font-style: normal; font-weight: normal; font-size: 100%; font-size-adjust: none; text-indent: 0; text-transform: none; letter-spacing: normal; word-spacing: normal; overflow: hidden; height: 1px} 177 | .MathJax_SVG_test.mjx-test-display {display: table!important} 178 | .MathJax_SVG_test.mjx-test-inline {display: inline!important; margin-right: -1px} 179 | .MathJax_SVG_test.mjx-test-default {display: block!important; clear: both} 180 | .MathJax_SVG_ex_box {display: inline-block!important; position: absolute; overflow: hidden; min-height: 0; max-height: none; padding: 0; border: 0; margin: 0; width: 1px; height: 60ex} 181 | .mjx-test-inline .MathJax_SVG_left_box {display: inline-block; width: 0; float: left} 182 | .mjx-test-inline .MathJax_SVG_right_box {display: inline-block; width: 0; float: right} 183 | .mjx-test-display .MathJax_SVG_right_box {display: table-cell!important; width: 10000em!important; min-width: 0; max-width: none; padding: 0; border: 0; margin: 0} 184 | .MathJax_SVG .noError {vertical-align: ; font-size: 90%; text-align: left; color: black; padding: 1px 3px; border: 1px solid} 185 | 186 | 187 | 189 | 197 | 202 | TE[0] 206 | 207 | 214 | 221 | 228 | 235 | 243 | 249 | TE[0].hdr_size + 253 | TE[0].data_size 257 | 258 | 267 | 276 | 285 | 292 | tl_base_pa 296 | 297 | 304 | tl_base_pa + TL.used_size 308 | 309 | 317 | 323 | TL header 327 | 328 | 335 | 342 | 349 | 356 | 364 | 370 | TE[n] 374 | 375 | 382 | 389 | 396 | 403 | 410 | TL.hdr_size 414 | 418 | 419 | 426 | 433 | 440 | 447 | 455 | 461 | TE[1] 465 | 466 | 473 | 480 | 487 | 494 | 501 | 508 | TE[0].base_pa = tl_base_pa + TL.hdr_size 512 | 513 | 520 | TE[1].base_pa = align8(   TE[0].base_pa +TE[0].hdr_size + TE[0].data_size) 533 | 540 | 547 | TE[n].base_pa = align8(   TE[n - 1].base_pa + TE[n - 1].hdr_size + TE[n - 1].data_size) 560 | 561 | 568 | 575 | 582 | tl_base_pa + TL.total_size 586 | 587 | 594 | 600 | TE[1].hdr_size + 604 | TE[1].data_size 608 | 609 | 615 | TE[n].hdr_size + 619 | TE[n].data_size 623 | 624 | 625 | 626 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | Firmware handoff specification 5 | ============================== 6 | 7 | .. toctree:: 8 | :numbered: 9 | :maxdepth: 3 10 | :caption: Contents 11 | 12 | introduction.rst 13 | transfer_list.rst 14 | register_conventions.rst 15 | references 16 | glossary 17 | -------------------------------------------------------------------------------- /source/introduction.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | Introduction 5 | ============ 6 | 7 | A platform initialization procedure may involve the execution of a sequence of 8 | firmware stages. It is assumed that only the primary boot core is active during 9 | the transition point between firmware stages, the remaining cores must be held 10 | at reset. The distinct firmware stages have specific responsibilities 11 | and can originate from separate codebases. As a platform initializes, the 12 | different firmware stages will generate information about the platform 13 | configuration and architecture. 14 | Examples of the information generated during boot are the platform memory map and 15 | device configuration. 16 | This information can be required by later 17 | firmware stages and thus must be propagated along the boot chain. This 18 | document defines a data structure which is used to handoff information between 19 | the different firmware stages involved in the platform initialization. 20 | 21 | 22 | Platform initialisation stages 23 | ------------------------------ 24 | 25 | An example of a feasible platform-boot architecture is shown in 26 | :numref:`fig_boot_phases`. This example is provided to introduce the firmware 27 | stage concept. Platforms are free to adopt any other boot architecture. 28 | 29 | .. _fig_boot_phases: 30 | .. figure:: images/boot_phases.svg 31 | :alt: Example boot architecture 32 | 33 | Example boot architecture 34 | 35 | 36 | Depending on the platform, the cold-boot initialization may start from a Board 37 | Controller which then releases the Application Processor (AP) into execution. 38 | 39 | The boot process on the AP may conceptually be broken apart into the following 40 | stages: 41 | 42 | * Immutable 43 | 44 | * Firmware stage obtained from read only memory. The immutable stage loads and authenticates the next stage into RAM and may perform some AP initialization. 45 | 46 | * Secure Platform Firmware 47 | 48 | * Firmware stage that is executed in a privileged level. It may be responsible for loading additional firmware images and may perform platform configurations. The stage may be subdivided into other sub-stages. The stage should terminate with the transition to the OS Bootloader. 49 | 50 | * OS Bootloader 51 | 52 | * The firmware stage that executes before the OS. It should be responsible for configuring the platform, loading and transferring the execution to the OS. This stage may be composed of several sub-stages. 53 | 54 | 55 | Any stage in the AP boot procedure may produce information which is consumed by 56 | a later stage. 57 | This specification defines the concept of *Transfer List* [#BlobList]_ (TL -- 58 | :numref:`sec_tl`). A firmware stage can append information to the TL. 59 | Any information produced by a firmware stage, meant to be 60 | consumed by a later firmware stage, must be contained in an entry 61 | (:numref:`sec_tl`) in the TL or be directly accessible via the information 62 | contained in one of the entries in the TL. 63 | A firmware stage transfers the execution flow to a next firmware stage at a point termed the 64 | *handoff boundary*. The TL is transferred between stages at the *handoff boundary*. 65 | For a particular *handoff boundary*, the firmware stage that hands 66 | off the list to a next stage is termed the *Sender*. The firmware stage 67 | receiving the list is termed the *Receiver*. The *Receiver* may update fields in 68 | any entry in the list and is allowed to remove entries. 69 | 70 | 71 | .. note:: 72 | 73 | If a firmware phase fails, the execution flow on the previous stage 74 | should resume from the handoff point. It is recommended that a previous 75 | phase keeps information on the execution flow prior to handoff either 76 | explicitly or implicitly in a link register. 77 | 78 | .. rubric:: Footnotes 79 | 80 | .. [#BlobList] The Transfer List specification has its origin in the Blob List implementation developed by the U-Boot community. In some codebases, the term Blob List may be employed. The Blob List and Transfer List terms are interchangeable, the Transfer List and Blob List implementations are fully compatible and equivalent. 81 | -------------------------------------------------------------------------------- /source/references.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | .. raw:: latex 5 | 6 | \cleardoublepage 7 | \begingroup 8 | \renewcommand\chapter[1]{\endgroup} 9 | \phantomsection 10 | 11 | .. _refs: 12 | 13 | References 14 | ========== 15 | 16 | .. [DT] `Devicetree Specification v0.4 `__ 17 | 18 | .. [PI] UEFI Platform Initialization, `PI v1.8A `__ 19 | 20 | .. [ACPI] Advanced Configuration and Power Interface (ACPI) Specification, `ACPI v6.5 `__ 21 | 22 | .. [ArmARM] Arm® Architecture Reference Manual for the A-profile architecture, `ARM DDI0487 issue L.a `__ 23 | 24 | .. [OPTEECore] `OP-TEE Core Architecture v4.5 `__ 25 | 26 | .. [TFAFFAMB] TF-A Secure Partition Manager: `FF-A manifest binding to device tree v2.12 `__ 27 | 28 | .. [TCG_EFI] `Trusted Computing Group EFI Protocol Specification v15 `__ 29 | 30 | .. [TF_BL31] `Data structures used in the BL31 cold boot interface v2.12 `__ 31 | 32 | .. [SPMCATTR] `The SPMC manifest v2.12: `__ 33 | -------------------------------------------------------------------------------- /source/register_conventions.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | .. _handoff_arch_bindings: 5 | 6 | Register usage at handoff boundary 7 | ================================== 8 | 9 | This section specifies the architecture bindings for the TL exchange at the 10 | handoff boundary. 11 | 12 | Arm Architecture bindings 13 | ------------------------- 14 | 15 | The Receiver of a TL can be in the AArch32 or AArch64 execution state [ArmARM]_. 16 | The register convention to be used at the handoff boundary is determined by the 17 | execution state of the Receiver. 18 | If the Receiver is in the AArch64 execution state, then the convention listed 19 | in :numref:`aarch64_receiver` is used. If the Receiver is in the AArch32 execution state, 20 | then the convention listed in :numref:`aarch32_receiver` is used. 21 | 22 | 23 | .. _aarch64_receiver: 24 | 25 | AArch64 Receiver 26 | ^^^^^^^^^^^^^^^^ 27 | 28 | A Sender must use the register convention listed in :numref:`tab_aarch64_convention` when handing off to an AArch64 receiver. 29 | In this register convention, the pointer to the 64-bit tl_base_pa address is passed on register X3. 30 | 31 | Register X2 must be set to `0`. 32 | 33 | The 32 least significant bits in register X1 contains the TL signature. The 34 | *signature* provides guarantees to a receiver that X3 holds the *tl_base_pa*. The 35 | bits [39:32] of X1 contain the version of the register convention being used. 36 | :numref:`tab_aarch64_convention` specifies the version 1 of the AArch64 handoff register convention. 37 | 38 | Register X0 must hold a pointer to the hardware description devicetree, if the 39 | transfer list contains an FDT entry. This field is set to `0` if an fdt entry is 40 | absent from the transfer list. 41 | 42 | 43 | .. _tab_aarch64_convention: 44 | 45 | .. table:: AArch64 register assignment at the handoff boundary 46 | :widths: 2 8 47 | 48 | +--------------+-------------------------------------------------------------+ 49 | | Register | Data present at the handoff boundary | 50 | +==============+=============================================================+ 51 | | X0 | Compatibility location for passing a platform description | 52 | | | devicetree. `0` if devicetree is not present. If an fdt | 53 | | | entry (tag_id=1) exists in the TL, then X0 must point to the| 54 | | | fdt contained in that entry. | 55 | +--------------+-------------------------------------------------------------+ 56 | | X1 | X1 is divided into the following fields: | 57 | | | | 58 | | | - X1[31:0]: set to the TL signature (`0x4a0f_b10b`) | 59 | | | - X1[39:32]: version of the register convention used. Set to| 60 | | | 1 for the AArch64 convention specified in this document. | 61 | | | - X1[63:40]: reserved, must be zero. | 62 | | | | 63 | +--------------+-------------------------------------------------------------+ 64 | | X2 | Reserved, must be zero. | 65 | +--------------+-------------------------------------------------------------+ 66 | | X3 | tl_base_pa | 67 | +--------------+-------------------------------------------------------------+ 68 | 69 | 70 | .. _aarch32_receiver: 71 | 72 | AArch32 Receiver 73 | ^^^^^^^^^^^^^^^^ 74 | 75 | A Sender must use the register convention listed in 76 | :numref:`tab_aarch32_convention` when handing off to an AArch32 receiver. In 77 | this register convention, the pointer to the 32-bit 78 | tl_base_pa address is passed on register R3. 79 | Register R1 contains the TL signature, to provide guarantees to a receiver that 80 | R3 holds the tl_base_pa. 81 | 82 | The 24 least significant bits in register R1 contains the 24 least significant 83 | bits of TL signature. The signature provides guarantees to a receiver that X3 84 | holds the tl_base_pa. The 8 most significant bits of R1 contain the version of 85 | the register convention being used. :numref:`tab_aarch32_convention` specifies the version `1` of the AArch32 86 | handoff register convention. 87 | 88 | Register R2 must hold a pointer to the hardware description devicetree, if the 89 | transfer list contains an FDT entry. This field is set to `0` if an fdt entry is 90 | absent from the transfer list. 91 | 92 | .. _tab_aarch32_convention: 93 | 94 | .. table:: AArch32 register assignment at the handoff boundary 95 | :widths: 2 8 96 | 97 | +--------------+-------------------------------------------------------------+ 98 | | Register | Data present at the handoff boundary | 99 | +==============+=============================================================+ 100 | | R0 | Reserved, must be zero. | 101 | +--------------+-------------------------------------------------------------+ 102 | | R1 | R1 is divided into the following fields: | 103 | | | | 104 | | | - R1[23:0]: set to the 24 least significant bits of TL | 105 | | | signature (`0x0f_b10b`). | 106 | | | - R1[31:24]: version of the register convention used. Set to| 107 | | | `1` for the AArch32 convention specified in this document.| 108 | | | | 109 | +--------------+-------------------------------------------------------------+ 110 | | R2 | Compatibility location for passing a platform description | 111 | | | devicetree. `0` if devicetree is not present. If an fdt | 112 | | | entry (tag_id=1) exists in the TL, then R2 must point to the| 113 | | | fdt contained in that entry. | 114 | +--------------+-------------------------------------------------------------+ 115 | | R3 | tl_base_pa | 116 | +--------------+-------------------------------------------------------------+ 117 | -------------------------------------------------------------------------------- /source/templates/versions.html: -------------------------------------------------------------------------------- 1 | {%- if current_version %} 2 |
3 | 4 | Other Versions 5 | v: {{ current_version.name }} 6 | 7 | 8 |
9 | {%- if versions.tags %} 10 |
11 |
Tags
12 | {%- for item in versions.tags %} 13 |
{{ item.name }}
14 | {%- endfor %} 15 |
16 | {%- endif %} 17 | {%- if versions.branches %} 18 |
19 |
Branches
20 | {%- for item in versions.branches %} 21 |
{{ item.name }}
22 | {%- endfor %} 23 |
24 | {%- endif %} 25 |
26 |
27 | {%- endif %} 28 | -------------------------------------------------------------------------------- /source/transfer_list.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 2 | .. SPDX-FileCopyrightText: Copyright The Firmware Handoff Specification Contributors 3 | 4 | .. default-role:: code 5 | 6 | .. _sec_tl: 7 | 8 | Transfer list 9 | ============= 10 | 11 | The TL must have a TL header which must be followed by one or more Transfer 12 | Entries (TE). The whole TL must be contiguous in physical address space. The TL 13 | header and all the TEs are 8-byte aligned (we use `align8()` to denote this). 14 | The TL header specifies the number of bytes occupied by the 15 | TL. The TEs are defined in :numref:`sec_tl_entry_hdr` and 16 | :numref:`sec_std_entries`. Each TE carries a header which contains an 17 | identifier, `tag_id`, that must be used to determine the content of the associated 18 | TE. The TL header is located at `tl_base_pa`. The `tl_base_pa` is passed in the 19 | register allocated for that handoff boundary (as specified in 20 | :numref:`handoff_arch_bindings`). A 21 | depiction of the TL is present in :numref:`fig_list` , there the first TE in 22 | the list (TE[0]) is shown to start at the end of the TL header 23 | (`tl_base_pa + 8`). The second TE in the list (TE[1]) starts at the next multiple 24 | of 8, after the end of the TE[0]. 25 | 26 | 27 | .. _fig_list: 28 | .. figure:: images/handoff_list_diagram.svg 29 | :alt: Transfer list example 30 | :scale: 85% 31 | 32 | Transfer list example 33 | 34 | Transfer list requirements 35 | -------------------------- 36 | 37 | **R1:** The `tl_base_pa` address must be non-zero and at an 8-byte aligned boundary. 38 | 39 | **R2:** All fields defined in this specification must be stored in memory with little-endian byte order. 40 | 41 | **R3:** The base address of a TE must be the 8-byte aligned address immediately after the end of the previous entry (or TL header, if the TE is the first entry on the TL). 42 | 43 | **R4:** When relocating the TL, the offset from `tl_base_pa` to the nearest alignment boundary specified by the `alignment` field in the TL header must be preserved. 44 | 45 | Transfer list header 46 | -------------------- 47 | 48 | A TL must begin with a TL header. The layout of the TL header is shown in 49 | :numref:`tab_tl_header`. The presence of a TL header may be verified by 50 | inspecting the signature field which must contain the `0x4a0f_b10b` value. The 51 | version field determines the contents of the handoff start header. The version 52 | will only be changed, by an update to this specification, when new TL header or 53 | TE header fields are defined (i.e. not when allocating new tag IDs), and all 54 | changes will be backwards-compatible to older readers. 55 | 56 | .. _tab_tl_header: 57 | .. list-table:: TL header 58 | :widths: 2 2 2 9 59 | :header-rows: 1 60 | 61 | * - Field 62 | - Size (bytes) 63 | - Offset (bytes) 64 | - Description 65 | 66 | * - signature 67 | - 0x4 68 | - 0x0 69 | - The value of signature must be `0x4a0f_b10b`. 70 | 71 | * - checksum 72 | - 0x1 73 | - 0x4 74 | - If enabled by the flags, the checksum is used to provide basic protection against something overwriting the TL in memory. The checksum is set to a value such that the xor over every byte in the {`tl_base_pa`, …, `tl_base_pa + used_size - 1`} address range, is equal to `0`. For the purposes of this calculation, the value of this checksum field in the TL header must be assumed as `0`. Note that the checksum must include the TL header, all TEs and the inter-TE padding, but must not include the range reserved for future TE additions up to total_size. The values of inter-TE padding bytes are not defined by this specification and may be uninitialized memory. (This means that multiple TLs with exactly the same size and contents may still have different checksum values.). If checksums are not used, this must be `0`. 75 | 76 | * - version 77 | - 0x1 78 | - 0x5 79 | - The version of the TL header. This field must be set to |current_version| for the TL header layout described in this version of the table. Code that encounters a TL with a version higher than it knows to support may still read the TL and all its TEs, and assume that it is backwards-compatible to previous versions (ignoring any extra bytes in a potentially larger TL or TE header). However, code may not append new entries to a TL unless it knows how to append entries for the specified version. 80 | 81 | * - hdr_size 82 | - 0x1 83 | - 0x6 84 | - The size of this TL header in bytes. This field is set to `0x18` for the TL header layout described in this version of the table. 85 | 86 | * - alignment 87 | - 0x1 88 | - 0x7 89 | - The maximum alignment required by any TE in the TL, specified as a power of two. For a newly created TL, the alignment requirement is `8` so this value should be set to `3`. It must be updated whenever a new TE is added with a larger requirement than the current value. 90 | 91 | * - used_size 92 | - 0x4 93 | - 0x8 94 | - The number of bytes within the TL that are used by TEs. This field accounts for the size of the TL header plus the size of all the entries contained in the TL. It must be a multiple of `8` (i.e. it includes the inter-TE padding after the end of the last TE). This field must be updated when any entry is added to the TL. 95 | 96 | * - total_size 97 | - 0x4 98 | - 0xc 99 | - The number of bytes occupied by the entire TL, including any spare space at the end, after `used_size`. Any entry producer must check if there is sufficient space before adding an entry to the list. Firmware can resize and/or relocate the TL and update this field accordingly, provided that the TL requirements are respected. This field must be a multiple of `8`. 100 | 101 | * - flags 102 | - 0x4 103 | - 0x10 104 | - Flags word. See below for contents. 105 | 106 | * - reserved 107 | - 0x4 108 | - 0x14 109 | - Reserved word. Must be set to `0` or ignored. 110 | 111 | 112 | TL Flags 113 | ^^^^^^^^ 114 | 115 | The TL flags word is intended to signal properties relating to the TL as a 116 | whole. Future flag values may be added according to the rules of the `version` 117 | field. 118 | 119 | .. list-table:: Flags 120 | :widths: 2 2 8 121 | :header-rows: 1 122 | 123 | * - Bit 124 | - Name 125 | - Description 126 | 127 | * - 0 128 | - has_checksum 129 | - A value of `1` (true) indicates that this TL uses checksums. The checksum 130 | field must be valid at the point of handoff. 131 | 132 | * - 31:1 133 | - unused 134 | - Reserved for future use. Must be `0`. 135 | 136 | 137 | .. _sec_tl_entry_hdr: 138 | 139 | TL entry header 140 | --------------- 141 | 142 | All TEs must start with an entry header followed by a data section. 143 | 144 | Note: the size of an entry (hdr_size + data_size) is not mandatorily an 8-byte 145 | multiple. When traversing the TL firmware must compute the next TE address following 146 | R3. 147 | 148 | For example, assume the current TE is `te` and its address is `te_base_addr`. Using 149 | C language notation, a derivation of the base address of the next TE 150 | (next_base_addr) is the following: 151 | 152 | .. code-block:: C 153 | 154 | next_base_addr = align8(te_base_addr + te.hdr_size + te.data_size) 155 | 156 | The TE header is defined in :numref:`tab_te_header`. 157 | 158 | .. _tab_te_header: 159 | 160 | .. list-table:: TE header 161 | :widths: 2 2 2 8 162 | :header-rows: 1 163 | 164 | * - Field 165 | - Size (bytes) 166 | - Offset (bytes) 167 | - Description 168 | 169 | * - tag_id 170 | - 0x3 171 | - 0x0 172 | - The entry type identifier. 173 | 174 | * - hdr_size 175 | - 0x1 176 | - 0x3 177 | - The size of this entry header in bytes. This field must be set to `8` for the TE header layout described in this version of the table. 178 | 179 | * - data_size 180 | - 0x4 181 | - 0x4 182 | - The exact size of the data content in bytes, not including inter-TE padding. May be `0`. 183 | 184 | 185 | TL Contents 186 | ----------- 187 | 188 | Tags are expected to have a simple layout (representable by a C structure) and 189 | each tag should only represent data for a single logical concept. Data for 190 | multiple distinct concepts should be split across different tags, even if 191 | they're always expected to appear together on the first platform adding the tag 192 | (to encourage reusability in different situations). Alternatively, complex data 193 | may be represented in a different kind of well-established handoff data 194 | structure (e.g. FDT [DT]_, HOB [PI]_) that is inserted into the TL as a single 195 | TE. Tag layouts (including the meaning of all 196 | fields) are considered stable after being added to this specification and must 197 | never be changed in a backwards-incompatible way. If a backwards-incompatible 198 | change is desired, a new tag ID should be allocated for the new version of the 199 | layout instead. 200 | 201 | Tag layouts may be changed in a backwards-compatible manner by allowing new 202 | valid values in existing fields (including reserved fields), as long as the 203 | original layout definition clearly defined how unknown values in those fields 204 | should be handled, and the rest of the TE would still be considered valid and 205 | correct for older readers that consider the new values unknown. TE layouts may 206 | also be expanded by adding new fields at the end, with the same restrictions. 207 | TEs should not contain explicit version numbers and instead just use the 208 | `data_size` value to infer how many fields exist. TE layouts which have been 209 | changed like this must clearly document which fields or valid values were added 210 | at a later time, and in what order. 211 | 212 | It is strongly recommended that entries of a given type are 213 | unique in the TL. If firmware designs require multiple TE instances of a given 214 | type, then that TE type definition should provide sufficient information for 215 | the TE consumer to disambiguate between all TE instances. That information can 216 | be, for example, a sub-type field or contained within a self-describing data 217 | blob. 218 | 219 | The TL must not hold pointers or addresses within its entries, which refer to 220 | anything in the TL. These can make it difficult to relocate the TL. TL 221 | relocation typically happens in later phases of the boot when there is more 222 | memory available, which is needed for adding larger entries. 223 | 224 | The TL may hold pointers or addresses which refer to regions outside the TL, if 225 | this is necessary. For example, the MMIO address of a device may be included in 226 | a TE. But in general, pointers and addresses should be avoided. Instead, the 227 | data structure itself should generally be contained within the TL. This approach 228 | provides the greatest flexibility for later boot stages to handle memory as they 229 | wish, since relocating the TL is fairly simple and self-contained, without 230 | needing to consider relocating other data structures strewn around the memory. 231 | 232 | Where pointers or addresses are needed due to some project-specific restriction, 233 | a separate TE should generally be created for that purpose, rather than mixing 234 | pointers with other data. Of course there may be exceptions where two pointers 235 | belong together, or there is a pointer and a size which belong together. In any 236 | case, the PR should clearly document the need for these pointers. 237 | 238 | 239 | Entry-type allocation 240 | --------------------- 241 | 242 | Tag IDs must be allocated in this specification before use. A new tag ID can be 243 | allocated by submitting a pull request to this repository that adds a 244 | description of the respective TE data layout to this specification. Tag IDs do 245 | not have to be allocated in order. Submitters are encouraged to try to group 246 | tag IDs together in logical clusters at 16 or 256-aligned boundaries (e.g. all 247 | tags related to a particular chipset or to a particular firmware project could 248 | use adjacent tag numbers), but there are no predefined ranges and no 249 | reservations of tag ranges for specific use. 250 | 251 | The `{0xff_f000, ..., 0xff_ffff}` range is reserved for non-standardized use. 252 | Anyone is free to use tags from that range for any custom TE layout without 253 | adding their definitions to this specification first. The use of this range is 254 | *strongly discouraged* for anything other than local experiments or code that 255 | will only ever be used in closed-source components owned by the entity 256 | controlling the entire final firmware image. In particular, a creator of a TE 257 | that just contains platform-specific data or internal structures specific to 258 | a single firmware implementation, should allocate a standardized tag for it 259 | in this specification -- using the non-standardized range is strongly 260 | discouraged. Since standards often emerge organically, the goal is to 261 | create unique tag IDs for everything just in case it turns out to be useful in 262 | more applications than initially anticipated. Basically, whenever you're 263 | submitting code for a new TE layout to any public open-source project, that's 264 | probably a good indication that you should allocate a tag ID for it in this 265 | specification. 266 | 267 | .. _tab_tag_id_ranges: 268 | 269 | .. list-table:: Tag ID ranges 270 | :widths: 3 8 271 | :header-rows: 1 272 | 273 | * - tag ID range 274 | - Description 275 | 276 | * - 0x0 -- 0x7f_ffff 277 | - Standardized range. Any tag ID in this range must first be allocated in this specification before being used. The allocation of the tag ID requires the entry layout to be defined as well. 278 | 279 | * - 0x80_0000 -- 0xff_efff 280 | - Reserved. (Can later be used to extend standardized range if necessary.) 281 | 282 | * - 0xff_f000 -- 0xff_ffff 283 | - Non-standardized range. Tag IDs in this range may be used without allocation in this specification. This range should not be used for anything other than local experimentation or closed-source components that are entirely under the control of a single platform firmware integrator. Tags in this range are not tracked in this repository and PRs to add tag definitions for this range will not be accepted. 284 | 285 | 286 | .. _sec_operations: 287 | 288 | Standard operations 289 | ------------------- 290 | 291 | This section describes the valid operations that may be performed on a TL in 292 | more detail, in order to clarify how to use the various fields and to serve as a 293 | guideline for implementation. 294 | 295 | Validating a TL header 296 | ^^^^^^^^^^^^^^^^^^^^^^ 297 | 298 | .. default-role:: code 299 | 300 | Inputs: 301 | 302 | - `tl_base_addr`: Base address of the existing TL. 303 | 304 | #. Compare `tl.signature` (`tl_base_addr + 0x0`) to `0x4a0f_b10b`. On a mismatch, 305 | abort (this is not a valid TL). 306 | 307 | #. Compare `tl.version` (`tl_base_addr + 0x5`) to the expected version 308 | (currently |current_version|). If there is an exact match, the TL is valid 309 | for all operations outlined in this section. If `tl.version` is larger, the 310 | TL is valid for reading but must not be modified or relocated. If 311 | `tl.version` is smaller, either abort or switch to code designed to 312 | interpret the respective previous version of this specification (note that 313 | the version number `0x0` is illegal and processing should always abort if it 314 | is found). 315 | 316 | #. *(optional)* Check that `tl.used_size` (`tl_base_addr + 0x8`) is smaller or equal 317 | to `tl.total_size` (`tl_base_addr + 0xc`), and that `tl.total_size` is smaller or 318 | equal to the size of the total area reserved for the TL (if known). If not, 319 | abort (TL is corrupted). 320 | 321 | #. *(optional)* If `has_checksum`, check that the xor of `tl.used_size` bytes 322 | starting at `tl_base_addr` is 0x0. If not, abort (TL is corrupted). 323 | 324 | Reading a TL 325 | ^^^^^^^^^^^^ 326 | 327 | Inputs: 328 | 329 | - `tl_base_addr`: Base address of the existing TL. 330 | 331 | #. Calculate `te_base_addr` as `align8(tl_base_addr + tl.hdr_size)`. (Do not 332 | hardcode the value for `tl.hdr_size`!) 333 | 334 | #. While `te_base_addr - tl_base_addr` is smaller or equal to `tl.used_size`: 335 | 336 | #. *(optional)* Check that `te_base_addr + te.hdr_size + te.data_size - tl_base_addr` 337 | is smaller or equal to `tl.used_size`, otherwise abort (the TL is corrupted). 338 | 339 | #. If `te.tag_id` (`te_base_addr + 0x0`) is a known tag, interpret the data 340 | at `te_base_addr + te.hdr_size` accordingly. (Do not hardcode the value 341 | for `te.hdr_size`, even for known tags!) Otherwise, ignore the tag and 342 | proceed with the next step. 343 | 344 | #. Add `align8(te.hdr_size + te.data_size)` to `te_base_addr`. 345 | 346 | Adding a new TE 347 | ^^^^^^^^^^^^^^^ 348 | 349 | Inputs: 350 | 351 | - `tl_base_addr`: Base address of the TL to add a TE to. 352 | - `new_tag_id`: ID number of the tag for the new TE. 353 | - `new_data_size`: Size in bytes of the data to be encapsulated in the TE. 354 | - [data]: Data to be copied into the TE or generated on the fly. 355 | 356 | #. *(optional)* Follow the steps in `Reading a TL`_ to look for a TE where 357 | `te.tag_id` is `0x0` (XFERLIST_VOID) and `te.data_size` is greater or equal 358 | to `new_data_size`. If found: 359 | 360 | #. Remember `te.data_size` as `old_void_data_size`. 361 | 362 | #. Use the `te_base_addr` of this tag for the rest of the operation. 363 | 364 | #. If `has_checksum`, xor the `align8(new_data_size + 0x8)` bytes starting at 365 | `te_base_addr` with `tl.checksum`. 366 | 367 | #. Skip the next step (step 2) with all its substeps. 368 | 369 | #. Calculate `te_base_addr` as `tl_base_addr + tl.used_size`. 370 | 371 | #. If `tl.total_size - tl.used_size` is smaller than `align8(new_data_size + 0x8)`, 372 | abort (not enough room to add TE). 373 | 374 | #. If `has_checksum`, xor the 4 bytes from `tl_base_addr + 0x8` with 375 | `tl_base_addr + 0xc` from `tl.checksum`. 376 | 377 | #. Add `align8(new_data_size + 0x8)` to `tl.used_size`. 378 | 379 | #. If `has_checksum`, xor the 4 bytes from `tl_base_addr + 0x8` to 380 | `tl_base_addr + 0xc` with `tl.checksum`. 381 | 382 | #. Set `te.tag_id` (`te_base_addr + 0x0`) to `new_tag_id`. 383 | 384 | #. Set `te.hdr_size` (`te_base_addr + 0x3`) to `8`. 385 | 386 | #. Set `te.data_size` (`te_base_addr + 0x4`) to `new_data_size`. 387 | 388 | #. Copy or generate the TE data into `te_base_addr + 0x8`. 389 | 390 | #. If `has_checksum`, xor the `align8(new_data_size + 0x8)` bytes starting at 391 | `te_base_addr` with `tl.checksum`. 392 | 393 | #. If an existing XFERLIST_VOID TE was chosen to be overwritten in step 1, and 394 | `old_void_data_size - new_data_size` is greater or equal to `0x8`: 395 | 396 | #. Use `te_base_addr + align8(new_data_size + 0x8)` as the new `te_base_addr` 397 | for a new XFERLIST_VOID tag. 398 | 399 | #. If `has_checksum`, xor the 8 bytes from `te_base_addr` to 400 | `te_base_addr + 0x8` with `tl.checksum`. 401 | 402 | #. Set `te.tag_id` (`te_base_addr + 0x0`) to `0x0` (XFERLIST_VOID). 403 | 404 | #. Set `te.hdr_size` (`te_base_addr + 0x3`) to `0x8`. 405 | 406 | #. Set `te.data_size` (`te_base_addr + 0x4`) to 407 | `old_void_data_size - align8(new_data_size) - 0x8`. 408 | 409 | #. If `has_checksum`, xor the 8 bytes from `te_base_addr` to 410 | `te_base_addr + 0x8` with `tl.checksum`. 411 | 412 | Adding a new TE with special data alignment requirement 413 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 414 | 415 | Inputs: 416 | 417 | - `tl_base_addr`: Base address of the TL to add a TE to. 418 | - `new_tag_id`: ID number of the tag for the new TE. 419 | - `new_alignment`: The alignment boundary as a power of `2` that the data must be aligned to. 420 | - `new_data_size`: Size in bytes of the data to be encapsulated in the TE. 421 | - [data]: Data to be copied into the TE or generated on the fly. 422 | 423 | #. Calculate `alignment_mask` as `(1 << new_alignment) - 1`. 424 | 425 | #. If `(tl_base_addr + tl.used_size + 0x8) & alignment_mask` is not `0x0`, follow the 426 | steps in `Adding a new TE`_ with the following inputs (bypass the option to 427 | overwrite an existing XFERLIST_VOID TE): 428 | 429 | #. `tl_base_addr` remains the same 430 | 431 | #. `new_tag_id` is `0x0` (XFERLIST_VOID) 432 | 433 | #. `new_data_size` is `(1 << new_alignment) - ((tl_base_addr + tl.used_size + 0x8) & alignment_mask) - 0x8`. 434 | 435 | #. No data (i.e. just don't touch the bytes that form the data portion for this TE). 436 | 437 | #. Follow the steps in `Adding a new TE`_ with the original inputs (again bypass 438 | the option to overwrite an existing XFERLIST_VOID TE). 439 | 440 | #. If `new_alignment` is larger than `tl.alignment`: 441 | 442 | #. If `has_checksum`, xor `tl.alignment` with `tl.checksum`. 443 | 444 | #. Set `tl.alignment` to `new_alignment`. 445 | 446 | #. If `has_checksum`, xor `tl.alignment` with `tl.checksum`. 447 | 448 | Creating a TL 449 | ^^^^^^^^^^^^^ 450 | 451 | Inputs: 452 | 453 | - `tl_base_addr`: Base address where to place the new TL. 454 | - `available_size`: Available size in bytes to reserve for the TL after `tl_base_addr`. 455 | 456 | #. Check that `available_size` is larger than `0x18` (the assumed `tl.hdr_size`), otherwise abort. 457 | 458 | #. Set `tl.signature` (`tl_base_addr + 0x0`) to `0x4a0f_b10b`. 459 | 460 | #. Set `tl.checksum` (`tl_base_addr + 0x4`) to `0x0` (for now). 461 | 462 | #. Set `tl.version` (`tl_base_addr + 0x5`) to |current_version|. 463 | 464 | #. Set `tl.hdr_size` (`tl_base_addr + 0x6`) to `0x18`. 465 | 466 | #. Set `tl.alignment` (`tl_base_addr + 0x7`) to `0x3`. 467 | 468 | #. Set `tl.used_size` (`tl_base_addr + 0x8`) to `0x18` (the assumed `tl.hdr_size`). 469 | 470 | #. Set `tl.total_size` (`tl_base_addr + 0xc`) to `available_size`. 471 | 472 | #. If checksums are to be used, set `tl.flags` (`tl_base_addr + 0x10`) to `1`, 473 | else `0`. This is the value of `has_checksum`. 474 | 475 | #. If `has_checksum`, calculate the checksum as the xor of all bytes from 476 | `tl_base_addr` to `tl_base_addr + tl.hdr_size`, and write the result to 477 | `tl.checksum`. 478 | 479 | Relocating a TL 480 | ^^^^^^^^^^^^^^^ 481 | 482 | Inputs: 483 | 484 | - `tl_base_addr`: Base address of the existing TL. 485 | - `target_base`: Base address of the target region to relocate into. 486 | - `target_size`: Size in bytes of the target region to relocate into. 487 | 488 | #. Calculate `alignment_mask` as `(1 << tl.alignment) - 1`. 489 | 490 | #. Calculate the current `alignment_offset` as `tl_base_addr & alignment_mask`. 491 | 492 | #. Calculate `new_tl_base` as `(target_base & ~alignment_mask) + alignment_offset`. 493 | 494 | #. If `new_tl_base` is below `target_base`, add `alignment_mask + 1` to `new_tl_base`. 495 | 496 | #. If `new_tl_base - target_base + tl.used_size` is larger than `target_size`, abort 497 | (not enough space to relocate). 498 | 499 | #. Copy `tl.used_size` bytes from `tl_base_addr` to `new_tl_base`. 500 | 501 | #. If `has_checksum`, xor the 4 bytes from `new_tl_base + 0xc` 502 | to `new_tl_base + 0x10` with `tl.checksum` (`new_tl_base + 0x4`). 503 | 504 | #. Set `tl.total_size` (`new_tl_base + 0xc`) to `target_size - (new_tl_base - target_base)`. 505 | 506 | #. If `has_checksum`, xor the 4 bytes from `new_tl_base + 0xc` to 507 | `new_tl_base + 0x10` with `tl.checksum` (`new_tl_base + 0x4`). 508 | 509 | 510 | .. _sec_std_entries: 511 | 512 | Standard transfer entries 513 | ------------------------- 514 | 515 | The following entry types are currently defined: 516 | 517 | - empty entry: tag_id = `0` (:numref:`void_entry`). 518 | - fdt entry: tag_id = `1` (:numref:`fdt_entry`). 519 | - single HOB block entry: tag_id = `2` (:numref:`hob_block_entry`). 520 | - HOB list entry: tag_id = `3` (:numref:`hob_list_entry`). 521 | - ACPI table aggregate entry: tag_id = `4` (:numref:`acpi_aggr_entry`). 522 | - TPM event log entry: tag_id = `5` (:numref:`tpm_evlog_entry`). 523 | - TPM CRB base entry: tag_id = `6` (:numref:`tpm_crb_base_entry`). 524 | - Entries related to Trusted Firmware (:numref:`tf_entries`). 525 | 526 | .. _void_entry: 527 | 528 | Empty entry layout (XFERLIST_VOID) 529 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 530 | 531 | The empty or void entry should not contain any information to be consumed by any firmware stage. 532 | The intent of the void entry type is to remove information from the list without needing to 533 | relocate subsequent entries, or to create padding for entries that require a specific alignment. 534 | Void entries may be freely overwritten with new TEs, provided the resulting TL remains valid 535 | (i.e. a void entry can only be overwritten by a TE of equal or smaller size; if the size is more 536 | than 8 bytes smaller, a new void entry must be created behind the new TE to cover the remaining 537 | space up to the next TE). 538 | 539 | .. _tab_void: 540 | .. list-table:: Empty type layout 541 | :widths: 2 2 2 8 542 | :header-rows: 1 543 | 544 | * - Field 545 | - Size (bytes) 546 | - Offset (bytes) 547 | - Description 548 | 549 | * - tag_id 550 | - 0x3 551 | - 0x0 552 | - The tag_id field must be set to `0`. 553 | 554 | * - hdr_size 555 | - 0x1 556 | - 0x3 557 | - |hdr_size_desc| 558 | 559 | * - data_size 560 | - 0x4 561 | - 0x4 562 | - The size of the void space in bytes. May be `0`. For XFERLIST_VOID, 563 | data_size *MUST* be a multiple of `8` (i.e. there must be no space left to 564 | inter-TE padding after this TE). 565 | 566 | * - void_data 567 | - data_size 568 | - hdr_size 569 | - Void content 570 | 571 | 572 | .. _fdt_entry: 573 | 574 | FDT entry layout (XFERLIST_FDT) 575 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 576 | 577 | The fdt is defined in [DT]_. The FDT TE contains the fdt in the data section. 578 | The intent of the FDT entry is to carry the hardware description devicetree in 579 | the flattened devicetree (FDT) [DT]_ representation. 580 | 581 | .. _tab_fdt: 582 | .. list-table:: FDT type layout 583 | :widths: 2 2 2 8 584 | :header-rows: 1 585 | 586 | * - Field 587 | - Size (bytes) 588 | - Offset (bytes) 589 | - Description 590 | 591 | * - tag_id 592 | - 0x3 593 | - 0x0 594 | - The tag_id field must be set to `1`. 595 | 596 | * - hdr_size 597 | - 0x1 598 | - 0x3 599 | - |hdr_size_desc| 600 | 601 | * - data_size 602 | - 0x4 603 | - 0x4 604 | - The size of the FDT in bytes. 605 | 606 | * - fdt 607 | - data_size 608 | - hdr_size 609 | - The fdt field contains the hardware description fdt. 610 | 611 | 612 | .. _hob_block_entry: 613 | 614 | HOB block entry layout (XFERLIST_HOB_B) 615 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 616 | 617 | The HOB is defined in [PI]_. This entry type encapsulates a single HOB block. 618 | The intent of the HOB block entry is to hold a single HOB block. A complete HOB 619 | list can then be constructed, by a receiver, by obtaining all the HOB blocks in 620 | the TL and following the HOB list requirements defined in [PI]_. 621 | 622 | .. _tab_hob_block: 623 | .. list-table:: HOB block type layout 624 | :widths: 2 2 2 8 625 | :header-rows: 1 626 | 627 | * - Field 628 | - Size (bytes) 629 | - Offset (bytes) 630 | - Description 631 | 632 | * - tag_id 633 | - 0x3 634 | - 0x0 635 | - The tag_id field must be set to `2`. 636 | 637 | * - hdr_size 638 | - 0x1 639 | - 0x3 640 | - |hdr_size_desc| 641 | 642 | * - data_size 643 | - 0x4 644 | - 0x4 645 | - The size of the HOB block in bytes. 646 | 647 | * - hob_block 648 | - data_size 649 | - hdr_size 650 | - Holds a single HOB block. 651 | 652 | 653 | .. _hob_list_entry: 654 | 655 | HOB list entry layout (XFERLIST_HOB_L) 656 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 657 | 658 | The HOB list is defined in [PI]_. The HOB list starts with a PHIT block and can 659 | contain an arbitrary number of HOB blocks. This entry type encapsulates a 660 | complete HOB list. An enclosed HOB list must respect the HOB list constraints 661 | specified in [PI]_. 662 | 663 | .. _tab_hob_list: 664 | .. list-table:: HOB list type layout 665 | :widths: 2 2 2 8 666 | :header-rows: 1 667 | 668 | * - Field 669 | - Size (bytes) 670 | - Offset (bytes) 671 | - Description 672 | 673 | * - tag_id 674 | - 0x3 675 | - 0x0 676 | - The tag_id field must be set to `3`. 677 | 678 | * - hdr_size 679 | - 0x1 680 | - 0x3 681 | - |hdr_size_desc| 682 | 683 | * - data_size 684 | - 0x4 685 | - 0x4 686 | - The size of the HOB list in bytes. 687 | 688 | * - hob_list 689 | - data_size 690 | - hdr_size 691 | - Holds a complete HOB list. 692 | 693 | 694 | .. _acpi_aggr_entry: 695 | 696 | ACPI table aggregate entry layout (XFERLIST_ACPI_AGGR) 697 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 698 | 699 | This entry type holds one or more ACPI tables. The first table must start at 700 | offset `hdr_size` from the start of the entry. Since ACPI tables usually have an 701 | alignment requirement larger than 8, writers may first need to create an 702 | XFERLIST_VOID padding entry so that the subsequent `te_base_addr + te.hdr_size` 703 | will be correctly aligned. Any subsequent ACPI tables must be located at the 704 | next 16-byte aligned address following the preceding ACPI table. Note that each 705 | ACPI table has a `Length` field in the ACPI table header [ACPI]_, which must be 706 | used to determine the end of the ACPI table. The `data_size` value must be set 707 | such that the last ACPI table in this entry ends at offset 708 | `hdr_size + data_size` from the start of the entry. 709 | 710 | .. _tab_acpi_aggr: 711 | .. list-table:: ACPI table aggregate type layout 712 | :widths: 2 2 2 8 713 | :header-rows: 1 714 | 715 | * - Field 716 | - Size (bytes) 717 | - Offset (bytes) 718 | - Description 719 | 720 | * - tag_id 721 | - 0x3 722 | - 0x0 723 | - The tag_id field must be set to `4`. 724 | 725 | * - hdr_size 726 | - 0x1 727 | - 0x3 728 | - |hdr_size_desc| 729 | 730 | * - data_size 731 | - 0x4 732 | - 0x4 733 | - The size of all included ACPI tables + padding in bytes. 734 | 735 | * - acpi_tables 736 | - data_size 737 | - hdr_size 738 | - One or more ACPI tables. 739 | 740 | 741 | .. _tpm_evlog_entry: 742 | 743 | TPM event log table entry layout (XFERLIST_EVLOG) 744 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 745 | This entry type holds TPM-related information for a platform. The TPM event log 746 | info is a region containing a TPM event log as defined by TCG EFI Protocol 747 | Specification [TCG_EFI]_. 748 | 749 | .. _tab_tpm_evlog: 750 | .. list-table:: TPM event log type layout 751 | :widths: 2 2 4 8 752 | :header-rows: 1 753 | 754 | * - Field 755 | - Size (bytes) 756 | - Offset (bytes) 757 | - Description 758 | 759 | * - tag_id 760 | - 0x3 761 | - 0x0 762 | - The tag_id field must be set to `5`. 763 | 764 | * - hdr_size 765 | - 0x1 766 | - 0x3 767 | - |hdr_size_desc| 768 | 769 | * - data_size 770 | - 0x4 771 | - 0x4 772 | - The size of the event log in bytes + sizeof(flags) i.e. `0x4`. 773 | 774 | * - flags 775 | - 0x4 776 | - hdr_size 777 | - flags are intended to signal properties of this TE. Bit 0 is 778 | need_to_replay flag. Some firmware components may compute measurements 779 | to be extended into a TPM and add them to the TPM event log, but those 780 | components are unable to access the TPM themselves. In this case, the 781 | component should set the "need_to_replay" flag so that the next 782 | component in the boot chain is aware that the PCRs have not been 783 | extended. A component with access to the TPM would replay the event log 784 | by reading each measurement recorded and extending it into the TPM. Once 785 | the measurements are extended into the TPM, then the "need_to_replay" 786 | flag must be cleared if the transfer list is passed to additional 787 | firmware components. Default value is `0`. Other bits should be set to 788 | zero. 789 | 790 | * - event_log 791 | - data_size - 0x4 792 | - hdr_size + 0x4 793 | - Holds a complete event log. 794 | 795 | 796 | .. _tpm_crb_base_entry: 797 | 798 | TPM CRB base address table entry layout (XFERLIST_TPM_CRB_BASE) 799 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 800 | The CRB info defines the address of a region of memory that has been carved out 801 | and reserved for use as a TPM Command Response Buffer interface. 802 | 803 | .. _tab_tpm_crb_base: 804 | .. list-table:: TPM CRB base type layout 805 | :widths: 4 2 4 8 806 | :header-rows: 1 807 | 808 | * - Field 809 | - Size (bytes) 810 | - Offset (bytes) 811 | - Description 812 | 813 | * - tag_id 814 | - 0x3 815 | - 0x0 816 | - The tag_id field must be set to `6`. 817 | 818 | * - hdr_size 819 | - 0x1 820 | - 0x3 821 | - |hdr_size_desc| 822 | 823 | * - data_size 824 | - 0x4 825 | - 0x4 826 | - This value should be set to `0xc`` i.e. `sizeof(crb_base_address) + sizeof(crb_size)`. 827 | 828 | * - crb_base_address 829 | - 0x8 830 | - hdr_size 831 | - The physical base address of a region of memory reserved for use as a 832 | TPM's Command Response Buffer region. 833 | 834 | * - crb_size 835 | - 0x4 836 | - hdr_size + 0x8 837 | - Size of CRB. 838 | 839 | 840 | .. _tf_entries: 841 | 842 | Entries related to Trusted Firmware 843 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 844 | 845 | The following entry types are defined for Trusted Firmware projects, 846 | including TF-A, OP-TEE and Hafnium. 847 | 848 | .. _tf_entries_summary: 849 | .. list-table:: Summary of Trusted Firmware Entries 850 | :header-rows: 1 851 | 852 | * - Tag ID 853 | - Description 854 | 855 | * - :ref:`0x100 ` 856 | - OP-TEE Pageable Part Address 857 | 858 | * - :ref:`0x101 ` 859 | - DT Formatted SPMC Manifest 860 | 861 | * - :ref:`0x102 ` 862 | - AArch64 Entry Point Info 863 | 864 | * - :ref:`0x103 ` 865 | - FF-A SP Binary 866 | 867 | * - :ref:`0x104 ` 868 | - RW Memory Layout (64-bit) 869 | 870 | * - :ref:`0x105 ` 871 | - Mbed-TLS Heap Info 872 | 873 | * - :ref:`0x106 ` 874 | - DT Formatted FF-A Manifest 875 | 876 | * - :ref:`0x107 ` 877 | - RW Memory Layout (32-bit) 878 | 879 | * - :ref:`0x108 ` 880 | - AArch32 Entry Point Info 881 | 882 | **OP-TEE pageable part address entry layout (XFERLIST_OPTEE_PAGEABLE_PART_ADDR)** 883 | 884 | This entry type holds the address of OP-TEE pageable part which is described in 885 | [OPTEECore]_. 886 | This address (of type 'uint64_t') is used when OPTEED (OP-TEE Dispatcher) 887 | is the Secure Payload Dispatcher, indicating where to load the pageable image of 888 | the OP-TEE OS. 889 | 890 | .. _tab_optee_pageable_part_address: 891 | .. list-table:: OP-TEE pageable part address type layout 892 | :widths: 2 2 2 8 893 | :header-rows: 1 894 | 895 | * - Field 896 | - Size (bytes) 897 | - Offset (bytes) 898 | - Description 899 | 900 | * - tag_id 901 | - 0x3 902 | - 0x0 903 | - The tag_id field must be set to `0x100`. 904 | 905 | * - hdr_size 906 | - 0x1 907 | - 0x3 908 | - |hdr_size_desc| 909 | 910 | * - data_size 911 | - 0x4 912 | - 0x4 913 | - The size (in bytes) of the address of OP-TEE pageable part which must be set to `8`. 914 | 915 | * - pp_addr 916 | - 0x8 917 | - hdr_size 918 | - Holds the address of OP-TEE pageable part 919 | 920 | **DT formatted SPMC manifest entry layout (XFERLIST_DT_SPMC_MANIFEST)** 921 | 922 | This entry type holds the SPMC (Secure Partition Manager Core) manifest image 923 | which is in DT format [DT]_ and described in [SPMCATTR]_. 924 | This manifest contains the SPMC attribute node consumed by the SPMD 925 | (Secure Partition Manager Dispatcher) at boot time. 926 | It may also contain some information for the SPMC implementation, to 927 | initialize itself. 928 | 929 | .. _tab_dt_spmc_manifest: 930 | .. list-table:: DT formatted SPMC manifest type layout 931 | :widths: 2 2 2 8 932 | :header-rows: 1 933 | 934 | * - Field 935 | - Size (bytes) 936 | - Offset (bytes) 937 | - Description 938 | 939 | * - tag_id 940 | - 0x3 941 | - 0x0 942 | - The tag_id field must be set to `0x101`. 943 | 944 | * - hdr_size 945 | - 0x1 946 | - 0x3 947 | - |hdr_size_desc| 948 | 949 | * - data_size 950 | - 0x4 951 | - 0x4 952 | - The size of SPMC manifest in bytes. 953 | 954 | * - spmc_man 955 | - data_size 956 | - hdr_size 957 | - Holds a SPMC manifest image in DT format. 958 | 959 | .. _64_bit_ep_info: 960 | 961 | **AArch64 executable entry point information (XFERLIST_EXEC_EP_INFO64)** 962 | 963 | This entry type holds the AArch64 variant of `entry_point_info`. 964 | `entry_point_info` is a TF-A-specific data structure [TF_BL31]_ used to 965 | represent the execution state of an image; that is, the state of general purpose 966 | registers, PC, and SPSR. 967 | 968 | This information is used by clients to setup the execution environment of 969 | subsequent images. A concrete example is the execution of a bootloader such as 970 | U-Boot in non-secure mode. In TF-A, the runtime firmware BL31 uses an 971 | `entry_point_info` structure corresponding to the bootloader, to setup the 972 | general and special purpose registers. Following conventions 973 | outlined in :ref:`aarch64_receiver`, the general purpose registers consumed 974 | by the bootloader contain the base addresses of the device tree, and transfer 975 | list; along with the transfer list signature. 976 | 977 | In practice, control might be transferred from BL31 to any combination of 978 | software running in Secure, Non-Secure, or Realm modes. 979 | 980 | .. _tab_entry_point_info: 981 | .. list-table:: Entry point info type layout 982 | :widths: 2 5 2 6 983 | :header-rows: 1 984 | 985 | * - Field 986 | - Size (bytes) 987 | - Offset (bytes) 988 | - Description 989 | 990 | * - tag_id 991 | - 0x3 992 | - 0x0 993 | - The tag_id field must be set to `0x102`. 994 | 995 | * - hdr_size 996 | - 0x1 997 | - 0x3 998 | - |hdr_size_desc| 999 | 1000 | * - data_size 1001 | - 0x4 1002 | - 0x4 1003 | - Size of the `entry_point_info` structure in bytes. 1004 | 1005 | * - ep_info_hdr 1006 | - 0x8 1007 | - hdr_size 1008 | - Header of type :ref:`param_header` containing 1009 | information about this structure. The type must be `0x1`, version `0x2`, 1010 | and size `0x58`. 1011 | 1012 | * - pc 1013 | - 0x8 1014 | - hdr_size + 0x8 1015 | - Program counter (entry point into image). 1016 | 1017 | * - spsr 1018 | - 0x4 1019 | - hdr_size + 0x10 1020 | - Saved Program Status Register. 1021 | 1022 | * - x0 1023 | - 0x8 1024 | - hdr_size + 0x18 1025 | - Register X0. 1026 | 1027 | * - x1 1028 | - 0x8 1029 | - hdr_size + 0x20 1030 | - Register X1. 1031 | 1032 | * - x2 1033 | - 0x8 1034 | - hdr_size + 0x28 1035 | - Register X2. 1036 | 1037 | * - x3 1038 | - 0x8 1039 | - hdr_size + 0x30 1040 | - Register X3. 1041 | 1042 | * - x4 1043 | - 0x8 1044 | - hdr_size + 0x38 1045 | - Register X4. 1046 | 1047 | * - x5 1048 | - 0x8 1049 | - hdr_size + 0x40 1050 | - Register X5. 1051 | 1052 | * - x6 1053 | - 0x8 1054 | - hdr_size + 0x48 1055 | - Register X6. 1056 | 1057 | * - x7 1058 | - 0x8 1059 | - hdr_size + 0x50 1060 | - Register X7. 1061 | 1062 | The structures header contains an attributes field which is used to encode the image's 1063 | execution state (i.e., Secure, Non-Secure, or Realm). 1064 | 1065 | .. _tab_param_header: 1066 | .. list-table:: Layout of ``param_header``. 1067 | 1068 | * - Field 1069 | - Size (bytes) 1070 | - Offset (bytes) 1071 | - Description 1072 | 1073 | * - type 1074 | - 0x1 1075 | - 0x0 1076 | - Type of the structure. 1077 | 1078 | * - version 1079 | - 0x1 1080 | - 0x1 1081 | - Version of the structure. 1082 | 1083 | * - size 1084 | - 0x2 1085 | - 0x2 1086 | - Size of the structure in bytes. 1087 | 1088 | * - attr 1089 | - 0x4 1090 | - 0x4 1091 | - Structure attributes. 1092 | 1093 | **FF-A SP binary (XFERLIST_FFA_SP_BINARY)** 1094 | 1095 | This entry holds a reference to an FF-A Secure Partition (SP) binary. 1096 | 1097 | This TE type is for an SPMC implementation to identify which entry 1098 | relates to the SP's binary, such that it can install the binary and 1099 | hand-over execution. 1100 | 1101 | .. _tab_ffa_sp_binary: 1102 | .. list-table:: An FF-A SP binary type layout 1103 | :widths: 2 2 2 8 1104 | :header-rows: 1 1105 | 1106 | * - Field 1107 | - Size (bytes) 1108 | - Offset (bytes) 1109 | - Description 1110 | 1111 | * - tag_id 1112 | - 0x3 1113 | - 0x0 1114 | - The tag_id field must be set to `0x103`. 1115 | 1116 | * - hdr_size 1117 | - 0x1 1118 | - 0x3 1119 | - |hdr_size_desc| 1120 | 1121 | * - data_size 1122 | - 0x4 1123 | - 0x4 1124 | - The size of the SP binary in bytes. 1125 | 1126 | * - ffa_sp_binary 1127 | - data_size 1128 | - hdr_size 1129 | - Holds the FF-A SP binary. 1130 | 1131 | .. _64_bit_mem_layout: 1132 | 1133 | **Read-Write Memory Layout Entry Layout (XFERLIST_RW_MEM_LAYOUT64)** 1134 | 1135 | This entry type holds a structure that describes the layout of a read-write 1136 | memory region. 1137 | 1138 | For example, TF-A uses it to convey to BL2 the extent of memory it has available 1139 | to perform read-write operations on. BL2 maps the memory described by the layout 1140 | into its memory map during platform setup. If other memory types are required 1141 | (i.e. read-only memory) separate TEs should be defined. 1142 | 1143 | .. _tab_rw_mem_layout: 1144 | .. list-table:: Layout for a RW memory layout entry 1145 | :widths: 2 5 5 6 1146 | :header-rows: 1 1147 | 1148 | * - Field 1149 | - Size (bytes) 1150 | - Offset (bytes) 1151 | - Description 1152 | 1153 | * - tag_id 1154 | - 0x3 1155 | - 0x0 1156 | - The tag_id field must be set to `0x104`. 1157 | 1158 | * - hdr_size 1159 | - 0x1 1160 | - 0x3 1161 | - |hdr_size_desc| 1162 | 1163 | * - data_size 1164 | - 0x4 1165 | - 0x4 1166 | - The size of the layout in bytes. 1167 | 1168 | * - addr 1169 | - 0x8 1170 | - hdr_size 1171 | - The base address of the memory region. 1172 | 1173 | * - size 1174 | - 0x8 1175 | - hdr_size + 0x8 1176 | - The size of the memory region. 1177 | 1178 | **DT formatted FF-A manifest entry layout (XFERLIST_DT_FFA_MANIFEST)** 1179 | 1180 | This entry type holds the FF-A manifest image which is in DT format [DT]_, 1181 | as described in [TFAFFAMB]_. 1182 | This manifest contains the SP (Secure Partition) configuration, consumed 1183 | by the SPMC at boot time. 1184 | 1185 | It may also contain some information to the SP itself. 1186 | 1187 | .. _tab_dt_ffa_manifest: 1188 | .. list-table:: DT formatted FF-A manifest type layout 1189 | :widths: 2 2 2 8 1190 | :header-rows: 1 1191 | 1192 | * - Field 1193 | - Size (bytes) 1194 | - Offset (bytes) 1195 | - Description 1196 | 1197 | * - tag_id 1198 | - 0x3 1199 | - 0x0 1200 | - The tag_id field must be set to `0x106`. 1201 | 1202 | * - hdr_size 1203 | - 0x1 1204 | - 0x3 1205 | - |hdr_size_desc| 1206 | 1207 | * - data_size 1208 | - 0x4 1209 | - 0x4 1210 | - The size of FF-A manifest in bytes. 1211 | 1212 | * - ffa_manifest 1213 | - data_size 1214 | - hdr_size 1215 | - Holds a FF-A manifest image in DT format. 1216 | 1217 | **Mbed-TLS heap information (XFERLIST_MBEDTLS_HEAP_INFO)** 1218 | 1219 | Specifies the location and size of a memory region, carved out for 1220 | stack-based memory allocation in Mbed-TLS. The buffer address and size are 1221 | passed to later stages for initialisation of Mbed-TLS. 1222 | 1223 | .. _tab_mbedtls_heap_info: 1224 | .. list-table:: Mbed-TLS heap info type layout 1225 | :widths: 4 2 4 8 1226 | :header-rows: 1 1227 | 1228 | * - Field 1229 | - Size (bytes) 1230 | - Offset (bytes) 1231 | - Description 1232 | 1233 | * - tag_id 1234 | - 0x3 1235 | - 0x0 1236 | - The tag_id field must be set to `0x105`. 1237 | 1238 | * - hdr_size 1239 | - 0x1 1240 | - 0x3 1241 | - |hdr_size_desc| 1242 | 1243 | * - data_size 1244 | - 0x4 1245 | - 0x4 1246 | - This value should be set to `0x10`` i.e. `sizeof(heap_address) + sizeof(heap_size)`. 1247 | 1248 | * - heap_address 1249 | - 0x8 1250 | - hdr_size 1251 | - The address of memory to be used as the heap. 1252 | 1253 | * - heap_size 1254 | - 0x8 1255 | - hdr_size + 0x8 1256 | - Size of memory region. 1257 | 1258 | **Read-Write Memory Layout Entry Layout (XFERLIST_RW_MEM_LAYOUT32)** 1259 | 1260 | This entry type holds the 32-bit variant of 1261 | :ref:`XFERLIST_RW_MEM_LAYOUT64<64_bit_mem_layout>`. It is a structure used to 1262 | describe the layout of a read-write memory region. TF-A utilizes this entry type 1263 | to notify BL2 of the available memory for read-write operations. Note, for other 1264 | memory types, such as read-only memory, distinct entries should be created. 1265 | 1266 | .. _tab_rw_mem_layout32: 1267 | .. list-table:: Layout for a RW memory layout entry (32-bit variant) 1268 | :widths: 2 5 5 6 1269 | 1270 | * - Field 1271 | - Size (bytes) 1272 | - Offset (bytes) 1273 | - Description 1274 | 1275 | * - tag_id 1276 | - 0x3 1277 | - 0x0 1278 | - The tag_id field must be set to `0x107`. 1279 | 1280 | * - hdr_size 1281 | - 0x1 1282 | - 0x3 1283 | - |hdr_size_desc| 1284 | 1285 | * - data_size 1286 | - 0x4 1287 | - 0x4 1288 | - The size of the layout in bytes. 1289 | 1290 | * - addr 1291 | - 0x4 1292 | - hdr_size 1293 | - The 32-bit base address of the memory region. 1294 | 1295 | * - size 1296 | - 0x4 1297 | - hdr_size + 0x4 1298 | - The size of the memory region. 1299 | 1300 | **AArch32 executable entry point information (XFERLIST_EXEC_EP_INFO32)** 1301 | 1302 | This entry type holds the 32-bit variant of the `entry_point_info` 1303 | structure. `entry_point_info` is a TF-A-specific data structure [TF_BL31]_ used 1304 | to represent the execution state of an image; that is, the state of general 1305 | purpose registers, PC, and SPSR. 1306 | 1307 | This information is used by clients to setup the execution environment of 1308 | subsequent images. It's usage is identical to the 64-bit form represented by 1309 | :ref:`XFERLIST_EXEC_EP_INFO64<64_bit_ep_info>`. 1310 | 1311 | .. _tab_entry_point_info32: 1312 | .. list-table:: Entry point info type layout (32-bit variant) 1313 | :widths: 2 3 3 6 1314 | 1315 | * - Field 1316 | - Size (bytes) 1317 | - Offset (bytes) 1318 | - Description 1319 | 1320 | * - tag_id 1321 | - 0x3 1322 | - 0x0 1323 | - The tag_id field must be set to `0x108`. 1324 | 1325 | * - hdr_size 1326 | - 0x1 1327 | - 0x3 1328 | - |hdr_size_desc| 1329 | 1330 | * - data_size 1331 | - 0x4 1332 | - 0x4 1333 | - Size of the `entry_point_info` structure in bytes. 1334 | 1335 | * - ep_info_hdr 1336 | - 0x8 1337 | - hdr_size 1338 | - Header of type :ref:`param_header` containing 1339 | information about this structure. The type must be `0x1`, version `0x2`, 1340 | and size `0x24`. 1341 | 1342 | * - pc 1343 | - 0x4 1344 | - hdr_size + 0x8 1345 | - Program counter (entry point into image). 1346 | 1347 | * - spsr 1348 | - 0x4 1349 | - hdr_size + 0xc 1350 | - Saved Program Status Register. 1351 | 1352 | * - lr_svc 1353 | - 0x4 1354 | - hdr_size + 0x10 1355 | - Link register. 1356 | 1357 | * - r0 1358 | - 0x4 1359 | - hdr_size + 0x14 1360 | - Register R0. 1361 | 1362 | * - r1 1363 | - 0x4 1364 | - hdr_size + 0x18 1365 | - Register R1. 1366 | 1367 | * - r2 1368 | - 0x4 1369 | - hdr_size + 0x1c 1370 | - Register R2. 1371 | 1372 | * - r3 1373 | - 0x4 1374 | - hdr_size + 0x20 1375 | - Register R3. 1376 | 1377 | .. |hdr_size_desc| replace:: The size of this entry header in bytes must be set to `8`. 1378 | .. |current_version| replace:: `0x1` 1379 | --------------------------------------------------------------------------------