├── runtime.txt ├── requirements.txt ├── netlify.toml ├── source ├── fit-logo.png ├── fit-favicon.png ├── references.rst ├── rst_prolog ├── index.rst ├── revhistory.rst ├── acknowledgements.rst ├── license.rst ├── chapter1-introduction.rst ├── fit-logo.svg ├── conf.py ├── chapter3-usage.rst └── chapter2-source-file-format.rst ├── NOTICE ├── Makefile ├── CONTRIBUTIONS ├── .github └── workflows │ └── ci.yml ├── writers-guide.rst ├── README.md └── LICENSE /runtime.txt: -------------------------------------------------------------------------------- 1 | 3.8 2 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | Sphinx==7.1.2 2 | -------------------------------------------------------------------------------- /netlify.toml: -------------------------------------------------------------------------------- 1 | [build] 2 | publish = "build/singlehtml" 3 | command = "make singlehtml" 4 | -------------------------------------------------------------------------------- /source/fit-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-source-firmware/flat-image-tree/HEAD/source/fit-logo.png -------------------------------------------------------------------------------- /source/fit-favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-source-firmware/flat-image-tree/HEAD/source/fit-favicon.png -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | 2 | Flattened Image Tree Specification 3 | 4 | Portions of this specification were developed by the following companies: 5 | 6 | Copyright 2016 Semihalf (Marian Balakowicz ) 7 | -------------------------------------------------------------------------------- /source/references.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | References 4 | ========== 5 | 6 | .. [dtspec] Devicetree Specification 7 | https://www.devicetree.org/specifications 8 | .. [VBE] Verified Boot for Embedded (VBE) 9 | https://docs.u-boot.org/en/latest/develop/vbe.html 10 | -------------------------------------------------------------------------------- /source/rst_prolog: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | .. Revision of the specification 4 | 5 | .. |fitspec-major| replace:: 0 6 | .. |fitspec-minor| replace:: 8 7 | 8 | .. General Macros 9 | 10 | .. |spec| replace:: FITSpec 11 | .. |spec-fullname| replace:: Flattened Image Tree Specification 12 | .. |dtspec| replace:: Devicetree Specification 13 | .. |VBE| replace:: Verified Boot for Embedded (VBE) 14 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | .. Flattened Image Tree (FIT) Specification documentation master file 2 | 3 | SPDX-License-Identifier: Apache-2.0 4 | 5 | |spec-fullname| |SpecVersion| 6 | ============================= 7 | 8 | .. toctree:: 9 | :numbered: 10 | :maxdepth: 3 11 | 12 | license 13 | acknowledgements 14 | revhistory 15 | chapter1-introduction 16 | chapter2-source-file-format 17 | chapter3-usage 18 | references 19 | 20 | .. 21 | Indices and tables 22 | ================== 23 | 24 | * :ref:`genindex` 25 | * :ref:`modindex` 26 | * :ref:`search` 27 | -------------------------------------------------------------------------------- /source/revhistory.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | Revision History 4 | ================ 5 | 6 | .. _revision-history: 7 | .. tabularcolumns:: | p{1.5cm} p{2.25cm} p{11.50cm} | 8 | .. table:: Revision History 9 | 10 | ========= =========== ==================================================== 11 | Revision Date Description 12 | ========= =========== ==================================================== 13 | 0.8 2023-AUG-9 Initial prerelease version. Imported text from U-Boot 14 | source tree. 15 | ========= =========== ==================================================== 16 | -------------------------------------------------------------------------------- /source/acknowledgements.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | Acknowledgements 4 | ================ 5 | 6 | FIT (Flattened Image Tree) was developed in 2008 by Marian Balakowicz and 7 | Bartlomiej Sieka of :index:`Semihalf`, under the guidance of Wolfgang Denk, 8 | founder of Denx Software Engineering and creator of U-Boot. 9 | 10 | Since then, :index:`FIT` has been maintained and extended by the U-Boot 11 | community to deal with the developing needs of Open Source firmware. 12 | 13 | This specification builds on this previous work. 14 | 15 | FIT has stood the test of time due to its simplicity and extensibility. 16 | This specification aims to build on this work and provide a means for 17 | further improvement with a wider group of collaborators. 18 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: Apache-2.0 2 | # 3 | # Minimal makefile for Sphinx documentation 4 | # 5 | 6 | # You can set these variables from the command line. 7 | SPHINXOPTS = 8 | SPHINXBUILD = sphinx-build 9 | SOURCEDIR = source 10 | BUILDDIR = build 11 | LATEXDIFF = latexdiff 12 | 13 | all: latexpdf html 14 | 15 | # Put it first so that "make" without argument is like "make help". 16 | help: 17 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 18 | @echo " latexdiff to make LaTeX files including changebars against previous release" 19 | 20 | .PHONY: all help latexdiff Makefile 21 | 22 | latexdiff: latex 23 | @echo "Generating LaTeX changebars..." 24 | $(LATEXDIFF) --type=UNDERLINE --config VERBATIMENV=sphinxVerbatim \ 25 | $(BUILDDIR)/latex-previous/flat-image-tree-specification.tex \ 26 | $(BUILDDIR)/latex/flat-image-tree-specification.tex \ 27 | > $(BUILDDIR)/latex/flat-image-tree-specification-changebars.tex 28 | @echo "Running LaTeX files through pdflatex..." 29 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 30 | @echo 31 | @echo "latexdiff finished; the PDF files are in $(BUILDDIR)/latex." 32 | 33 | # Catch-all target: route all unknown targets to Sphinx using the new 34 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 35 | %: Makefile 36 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 37 | -------------------------------------------------------------------------------- /CONTRIBUTIONS: -------------------------------------------------------------------------------- 1 | Developer Certificate of Origin 2 | Version 1.1 3 | 4 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 5 | 660 York Street, Suite 102, 6 | San Francisco, CA 94110 USA 7 | 8 | Everyone is permitted to copy and distribute verbatim copies of this 9 | license document, but changing it is not allowed. 10 | 11 | 12 | Developer's Certificate of Origin 1.1 13 | 14 | By making a contribution to this project, I certify that: 15 | 16 | (a) The contribution was created in whole or in part by me and I 17 | have the right to submit it under the open source license 18 | indicated in the file; or 19 | 20 | (b) The contribution is based upon previous work that, to the best 21 | of my knowledge, is covered under an appropriate open source 22 | license and I have the right under that license to submit that 23 | work with modifications, whether created in whole or in part 24 | by me, under the same open source license (unless I am 25 | permitted to submit under a different license), as indicated 26 | in the file; or 27 | 28 | (c) The contribution was provided directly to me by some other 29 | person who certified (a), (b) or (c) and I have not modified 30 | it. 31 | 32 | (d) I understand and agree that this project and the contribution 33 | are public and that a record of the contribution (including all 34 | personal information I submit with it, including my sign-off) is 35 | maintained indefinitely and may be redistributed consistent with 36 | this project or the open source license(s) involved. 37 | -------------------------------------------------------------------------------- /source/license.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | Copyright 4 | ========= 5 | 6 | | Copyright 2008 Marian Balakowicz 7 | | Copyright 2008 Bartlomiej Sieka 8 | | Copyright 2022 Simon Glass 9 | 10 | THIS SPECIFICATION PROVIDED "AS IS" AND WITHOUT ANY WARRANTY 11 | OF ANY KIND, INCLUDING, WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED 12 | WARRANTY OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 13 | PARTICULAR PURPOSE. IN NO EVENT SHALL LINARO OR ANY MEMBER OF 14 | LINARO BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, EXEMPLARY, 15 | PUNITIVE, OR CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST 16 | PROFITS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17 | 18 | Questions pertaining to this document, or the terms or conditions of its 19 | provision, should be addressed to: 20 | 21 | | Open Source Firmware Foundation 22 | | 530 Lawrence Expy 23 | | PMB 992 24 | | Sunnyvale, CA 94085 25 | | United States 26 | 27 | License Information 28 | ------------------- 29 | 30 | Licensed under the Apache License, Version 2.0 (the "License"); 31 | you may not use this file except in compliance with the License. 32 | You may obtain a copy of the License at 33 | 34 | http://www.apache.org/licenses/LICENSE-2.0 35 | 36 | Unless required by applicable law or agreed to in writing, software 37 | distributed under the License is distributed on an "AS IS" BASIS, 38 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 39 | See the License for the specific language governing permissions and 40 | limitations under the License. 41 | 42 | .. raw:: latex 43 | 44 | \newpage 45 | 46 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: Github Action CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - '**' 7 | tags: 8 | - 'v*' 9 | pull_request: 10 | branches: 11 | master 12 | 13 | jobs: 14 | build: 15 | runs-on: ubuntu-latest 16 | 17 | steps: 18 | - uses: actions/checkout@v4 19 | with: 20 | fetch-depth: 0 21 | 22 | - name: install 23 | run: | 24 | sudo apt-get update 25 | sudo apt-get install latexmk libalgorithm-diff-perl texlive texlive-latex-extra texlive-humanities graphviz 26 | pip3 install --user mako 27 | pip3 install --user typing 28 | pip3 install --user Sphinx 29 | pip3 install --user codespell 30 | 31 | - name: build pdf 32 | run: | 33 | make latexpdf 34 | git fetch --tags --force # Needed to make git-describe work 35 | mv build/latex/fit-specification.pdf build/latex/fit-specification-$(git describe).pdf 36 | - name: build html 37 | run: make html 38 | - name: build singlehtml 39 | run: make singlehtml 40 | 41 | - name: upload 42 | uses: actions/upload-artifact@v4 43 | with: 44 | name: artifacts 45 | path: | 46 | build/latex/fit-specification-*.pdf 47 | 48 | - name: deploy 49 | uses: peaceiris/actions-gh-pages@v4 50 | with: 51 | github_token: ${{ secrets.GITHUB_TOKEN }} 52 | publish_dir: ./build/singlehtml 53 | 54 | - name: release 55 | uses: softprops/action-gh-release@v2 56 | if: startsWith(github.ref, 'refs/tags/') 57 | with: 58 | files: build/latex/fit-specification-*.pdf 59 | env: 60 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 61 | -------------------------------------------------------------------------------- /source/chapter1-introduction.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | .. _chapter-introduction: 4 | 5 | Introduction 6 | ============ 7 | 8 | Purpose and Scope 9 | ----------------- 10 | 11 | The number of elements playing a role in the kernel booting process has 12 | increased over time and now typically includes the devicetree, 13 | :index:`kernel image ` and 14 | possibly a ramdisk image. Generally, all must be placed in the system memory and 15 | booted together. 16 | 17 | For firmware images a similar process has taken place, with various binaries 18 | loaded at different addresses, such as ARM's :index:`ATF`, :index:`OpenSBI`, 19 | :index:`FPGA` and :index:`U-Boot` itself. 20 | 21 | FIT provides a flexible and extensible format to deal with this complexity. It 22 | provides support for multiple components. It also supports multiple 23 | configurations, so that the same FIT can be used to boot multiple boards, with 24 | some components in common (e.g. kernel) and some specific to that board (e.g. 25 | devicetree). 26 | 27 | This specification, the |spec-fullname| (|spec|), 28 | provides a suitable format which can be used to describe any set of files 29 | along with grouping and selection mechanisms. 30 | 31 | * :numref:`Chapter %s ` introduces the purpose and 32 | background of |spec|. 33 | * :numref:`Chapter %s ` introduces the FIT concept 34 | and describes its logical structure and standard properties. 35 | certain classes of devices and specific device types. 36 | * :numref:`Chapter %s ` describes how FIT is used in bootloaders 37 | to handle booting Operating Systems as well as firmware. 38 | 39 | **Conventions Used in this Document** 40 | 41 | The word *shall* is used to indicate mandatory requirements strictly to 42 | be followed in order to conform to the standard and from which no 43 | deviation is permitted (*shall* equals *is required to*). 44 | 45 | The word *should* is used to indicate that among several possibilities 46 | one is recommended as particularly suitable, without mentioning or 47 | excluding others; or that a certain course of action is preferred but 48 | not necessarily required; or that (in the negative form) a certain 49 | course of action is deprecated but not prohibited (*should* equals *is 50 | recommended that*). 51 | 52 | The word *may* is used to indicate a course of action permissible within 53 | the limits of the standard (*may* equals *is permitted*). 54 | 55 | Examples of devicetree constructs are frequently shown in *Devicetree 56 | Syntax* form. See [dtspec]_ for a description of this. 57 | 58 | Relationship to |dtspec| 59 | ------------------------ 60 | 61 | |spec| is based on the :index:`Devicetree Specification`, in that it uses the 62 | same structure and shares some concepts. 63 | 64 | 32-bit and 64-bit Support 65 | ------------------------- 66 | 67 | The |spec| supports CPUs with both :index:`32-bit` and :index:`64-bit` 68 | addressing capabilities. Where applicable, sections of the |spec| describe any 69 | requirements or considerations for 32-bit and 64-bit addressing. 70 | 71 | 72 | Definition of Terms 73 | ------------------- 74 | 75 | .. glossary:: 76 | 77 | DTB 78 | Devicetree blob. Compact binary representation of the devicetree. 79 | 80 | DTC 81 | Devicetree compiler. An open source tool used to create DTB files 82 | from DTS files. 83 | 84 | DTS 85 | Devicetree syntax. A textual representation of a devicetree 86 | consumed by the DTC. See Appendix A Devicetree Source Format 87 | (version 1). 88 | -------------------------------------------------------------------------------- /source/fit-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 19 | 39 | 41 | 44 | 48 | 49 | 50 | 54 | 56 | 63 | FIT 74 | 81 | 88 | 95 | } 107 | 108 | 109 | 110 | -------------------------------------------------------------------------------- /writers-guide.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: Apache-2.0 2 | 3 | This document uses the Sphinx implementation of reStructured Text (RST). RST is 4 | a flexible markup language with lots of options for laying out text. To keep 5 | thinks simple, this file describes the conventions used by this project. As 6 | much as possible, use these methods for markup. 7 | 8 | Source Text Style 9 | ================= 10 | The reStructuredText marking is very human-friendly and readable as is, 11 | but most people will read the pdf or html output instead of the source files. 12 | To make changes to the content easier to find, 13 | use "semantic linefeeds" when writing as described by Brian Kernighan: 14 | 15 | Hints for Preparing Documents 16 | 17 | Most documents go through several versions (always more than you expected) 18 | before they are finally finished. 19 | Accordingly, you should do whatever possible to make the job of changing them easy. 20 | 21 | First, when you do the purely mechanical operations of typing, 22 | type so subsequent editing will be easy. 23 | Start each sentence on a new line. 24 | Make lines short, and break lines at natural places, 25 | such as after commas and semicolons, rather than randomly. 26 | Since most people change documents by rewriting phrases and adding, 27 | deleting and rearranging sentences, 28 | these precautions simplify any editing you have to do later. 29 | 30 | Brian W. Kernighan, 1974 31 | 32 | Source : http://rhodesmill.org/brandon/2012/one-sentence-per-line/ 33 | 34 | Tables 35 | ====== 36 | Use the simplified markup for tables as shown below. Use the tabularcolumns 37 | directive for controlling how tables are layed out in pdf output. For 38 | consistency, tables in this document shoud be specified without internal 39 | vertical columns separators are preferred. (ie. Only use the | specifier on the 40 | outsides of the table, such as with ``.. tabularcolumns:: | l l J|`` instead of 41 | ``.. tabularcolumns:: | l | l | J |``. Column specifiers will be one of the 42 | following. 43 | 44 | When possible, use only ``l,c,r,L,R,C,J`` specifiers and the renderer will 45 | automatically figure out the columns widths. However, if a table is longer than 46 | a page, or has complex content, then you must manually specify each column 47 | width with the ``p{width}`` specifier. Long tables must also include the 48 | ``:class: longtable`` directive as shown below. 49 | 50 | =========== ====================================== 51 | Specifier Behaviour 52 | =========== ====================================== 53 | l minimum width left-justified column 54 | c minimum width centered column 55 | r minimum width right-justified column 56 | p{'width'} paragraph column with text vertically aligned at the top 57 | L flush left column with automatic width 58 | R flush right column with automatic width 59 | C centered column with automatic width 60 | J justified column with automatic width 61 | \| Vertical line 62 | || Double vertical line 63 | =========== ====================================== 64 | 65 | Use ``:numref:`` to reference a table from the document text. For example: 66 | ``:numref:`table_example_simple``` 67 | 68 | .. tabluarcolumns:: l l J 69 | .. _table_example_simple: 70 | .. table:: Example of simple table 71 | 72 | ========== =============== ========== 73 | Heading 1 Heading 2 Heading 3 74 | ========== =============== ========== 75 | row 1 two row cell 3 76 | entry 77 | row 2 data more 78 | ========== =============== ========== 79 | 80 | .. tabluarcolumns:: | p{3cm} p{1cm} p{10cm} | 81 | .. _table_example_columns: 82 | .. table:: Example of table needing explicit formatting 83 | 84 | ========== =============== ========== 85 | Heading 1 Heading 2 Heading 3 86 | ========== =============== ========== 87 | row 1 two row cell 3 88 | entry 89 | row 2 data more 90 | 91 | :: * embedded 92 | * list 93 | code * of 94 | block * items 95 | ========== =============== ========== 96 | 97 | .. tabluarcolumns:: | p{3cm} p{1cm} p{10cm} | 98 | .. _table_example_simple: 99 | .. table:: Example of table that spans multiple pages 100 | :class: longtable 101 | 102 | ========== =============== ========== 103 | Heading 1 Heading 2 Heading 3 104 | ========== =============== ========== 105 | row 1 two row cell 3 106 | entry 107 | row 2 data more 108 | ========== =============== ========== 109 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Document master project for the Flattened Image Tree Specification # 2 | 3 | The latest release of the specification can be found at 4 | https://github.com/open-source-firmware/flat-image-tree 5 | 6 | This [repository](https://github.com/open-source-firmware/flat-image-tree) holds 7 | the source for the generation of the Flattened Image Tree Specification using 8 | Sphinx and LaTeX. 9 | 10 | ## Mailing list: flat-image-tree@lists.osfw.foundation ## 11 | * Use this mailing list for submitting questions and general discussion 12 | * Sign up to the mailing list at https://lists.osfw.foundation/g/flat-image-tree 13 | * For patches, please read the [Contributions section](#contributions) 14 | 15 | ## Build Instructions 16 | 17 | Requirements: 18 | * Sphinx: http://sphinx-doc.org/contents.html 19 | * version 1.2.3 or later 20 | * LaTeX (and pdflatex, and various LaTeX packages) 21 | * Graphviz (in particular, "dot"): http://www.graphviz.org/ 22 | 23 | On Debian and Ubuntu: 24 | 25 | >``` 26 | ># apt-get install python-sphinx texlive texlive-latex-extra libalgorithm-diff-perl \ 27 | > texlive-humanities texlive-generic-recommended graphviz \ 28 | > texlive-generic-extra 29 | >``` 30 | > 31 | >If the version of python-sphinx installed is too old, then an additional 32 | >new version can be installed with the Python package installer: 33 | > 34 | >``` 35 | >$ apt-get install python-pip 36 | >$ pip install --user --upgrade Sphinx 37 | >$ export SPHINXBUILD=~/.local/bin/sphinx-build 38 | >``` 39 | > 40 | >You will need latexdiff v1.2.1 or later to create the changebars PDF version 41 | >of the document. 42 | >Until distributions catch up with the latest release you will need to install 43 | >it directly from the github repo. 44 | > 45 | >``` 46 | >$ git clone https://github.com/ftilmann/latexdiff 47 | >$ export PATH=$PWD/latexdiff/:$PATH 48 | >``` 49 | > 50 | >Export SPHINXBUILD (see above) if Sphinx was installed with pip --user, then follow Make commands below 51 | 52 | On Mac OS X: 53 | 54 | > Install [MacTeX](http://tug.org/mactex/) 55 | > 56 | > Install pip if you do not have it: 57 | >``` 58 | >$ sudo easy_install pip 59 | >``` 60 | >Install Sphinx 61 | >``` 62 | >pip install --user --upgrade Sphinx 63 | >Or 64 | >sudo pip install --upgrade Sphinx 65 | >``` 66 | > 67 | >If you are using [brew](http://brew.sh) then you can install graphviz like this: 68 | >``` 69 | >brew install graphviz 70 | >``` 71 | >If you are using [macports](https://www.macports.org/) then you can install graphviz like this: 72 | >``` 73 | >$ sudo port install graphviz 74 | >``` 75 | 76 | Make commands: 77 | 78 | >``` 79 | >$ make latexpdf # For generating pdf 80 | >$ make html # For generating a hierarchy of html pages 81 | >$ make singlehtml # For generating a single html page 82 | >``` 83 | 84 | Output goes in ./build subdirectory. 85 | 86 | ## License ## 87 | This project is licensed under the Apache V2 license. More information can be found 88 | in the LICENSE and NOTICE file or online at: 89 | 90 | http://www.apache.org/licenses/LICENSE-2.0 91 | 92 | ## Contributions ## 93 | Patches should be submitted via a pull request at 94 | https://github.com/open-source-firmware/flat-image-tree/pull 95 | 96 | Contributions to the Flattened Image Tree Specification are managed by the 97 | gatekeeper, Lean Sheng Tan 98 | 99 | Anyone can contribute to the Flattened Image Tree Specification. Contributions 100 | to this project should conform to the `Developer Certificate of Origin` as 101 | defined at http://elinux.org/Developer_Certificate_Of_Origin. Commits to this 102 | project need to contain the following line to indicate the submitter accepts the 103 | DCO: 104 | ``` 105 | Signed-off-by: Your Name 106 | ``` 107 | By contributing in this way, you agree to the terms as follows: 108 | ``` 109 | Developer Certificate of Origin 110 | Version 1.1 111 | 112 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 113 | 660 York Street, Suite 102, 114 | San Francisco, CA 94110 USA 115 | 116 | Everyone is permitted to copy and distribute verbatim copies of this 117 | license document, but changing it is not allowed. 118 | 119 | 120 | Developer's Certificate of Origin 1.1 121 | 122 | By making a contribution to this project, I certify that: 123 | 124 | (a) The contribution was created in whole or in part by me and I 125 | have the right to submit it under the open source license 126 | indicated in the file; or 127 | 128 | (b) The contribution is based upon previous work that, to the best 129 | of my knowledge, is covered under an appropriate open source 130 | license and I have the right under that license to submit that 131 | work with modifications, whether created in whole or in part 132 | by me, under the same open source license (unless I am 133 | permitted to submit under a different license), as indicated 134 | in the file; or 135 | 136 | (c) The contribution was provided directly to me by some other 137 | person who certified (a), (b) or (c) and I have not modified 138 | it. 139 | 140 | (d) I understand and agree that this project and the contribution 141 | are public and that a record of the contribution (including all 142 | personal information I submit with it, including my sign-off) is 143 | maintained indefinitely and may be redistributed consistent with 144 | this project or the open source license(s) involved. 145 | ``` 146 | 147 | ## Automatic publication 148 | 149 | This document is automatically published to the Open Source Firmware Foundation website at https://fitspec.osfw.foundation/. 150 | 151 | 152 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: Apache-2.0 2 | # -*- coding: utf-8 -*- 3 | # 4 | # Flattened Image Tree (FIT) Specification documentation build configuration 5 | # file 6 | # Based on file in devicetree.org 7 | # 8 | # This file does only contain a selection of the most common options. For a 9 | # full list see the documentation: 10 | # http://www.sphinx-doc.org/en/master/config 11 | 12 | # -- Path setup -------------------------------------------------------------- 13 | 14 | # If extensions (or modules to document with autodoc) are in another directory, 15 | # add these directories to sys.path here. If the directory is relative to the 16 | # documentation root, use os.path.abspath to make it absolute, like shown here. 17 | # 18 | import os 19 | import sys 20 | import time 21 | import subprocess 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | sys.path.append(os.path.abspath('extensions')) 25 | 26 | # -- Project information ----------------------------------------------------- 27 | 28 | project = u'Flattened Image Tree Specification' 29 | copyright = u'2023, Marian Balakowicz ' 30 | author = u'Marian Balakowicz ' 31 | 32 | # The short X.Y version 33 | try: 34 | version = str(subprocess.check_output(["git", "describe", "--dirty"]), 'utf-8').strip() 35 | except: 36 | version = "unknown-rev" 37 | # The full version, including alpha/beta/rc tags 38 | release = version 39 | 40 | 41 | # -- General configuration --------------------------------------------------- 42 | 43 | # If your documentation needs a minimal Sphinx version, state it here. 44 | # 45 | needs_sphinx = '1.2.3' 46 | 47 | # Add any Sphinx extension module names here, as strings. They can be 48 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 49 | # ones. 50 | extensions = [ 51 | 'sphinx.ext.todo', 52 | 'sphinx.ext.graphviz' 53 | ] 54 | 55 | # Add any paths that contain templates here, relative to this directory. 56 | templates_path = ['_templates'] 57 | 58 | # The suffix(es) of source filenames. 59 | # You can specify multiple suffix as a list of string: 60 | # 61 | # source_suffix = ['.rst', '.md'] 62 | source_suffix = '.rst' 63 | 64 | # The master toctree document. 65 | master_doc = 'index' 66 | 67 | # The language for content autogenerated by Sphinx. Refer to documentation 68 | # for a list of supported languages. 69 | # 70 | # This is also used if you do content translation via gettext catalogs. 71 | # Usually you set "language" from the command line for these cases. 72 | language = 'en' 73 | 74 | # There are two options for replacing |today|: either, you set today to some 75 | # non-false value, then it is used: 76 | #today = '' 77 | # Else, today_fmt is used as the format for a strftime call. 78 | today_fmt = '%d %B %Y' 79 | 80 | # List of patterns, relative to source directory, that match files and 81 | # directories to ignore when looking for source files. 82 | # This pattern also affects html_static_path and html_extra_path. 83 | exclude_patterns = [] 84 | 85 | # Include at the beginning of every source file that is read 86 | with open('rst_prolog', 'rb') as pr: 87 | rst_prolog = pr.read().decode('utf-8') 88 | 89 | rst_epilog = """ 90 | .. |SpecVersion| replace:: {versionnum} 91 | """.format( 92 | versionnum = version, 93 | ) 94 | 95 | # The name of the Pygments (syntax highlighting) style to use. 96 | pygments_style = 'sphinx' 97 | 98 | numfig = True 99 | 100 | highlight_language = 'none' 101 | 102 | 103 | # -- Options for HTML output ------------------------------------------------- 104 | 105 | # The theme to use for HTML and HTML Help pages. See the documentation for 106 | # a list of builtin themes. 107 | # 108 | html_theme = 'alabaster' 109 | 110 | # Theme options are theme-specific and customize the look and feel of a theme 111 | # further. For a list of options available for each theme, see the 112 | # documentation. 113 | html_theme_options = { 114 | 'github_user': 'open-source-firmware', 115 | 'github_repo': 'flat-image-tree', 116 | } 117 | 118 | # The name of an image file (relative to this directory) to place at the top 119 | # of the sidebar. 120 | html_logo = "fit-logo.svg" 121 | 122 | # The name of an image file (relative to this directory) to use as a favicon of 123 | # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 124 | # pixels large. 125 | html_favicon = "fit-favicon.png" 126 | 127 | # Add any paths that contain custom static files (such as style sheets) here, 128 | # relative to this directory. They are copied after the builtin static files, 129 | # so a file named "default.css" will overwrite the builtin "default.css". 130 | # html_static_path = ['_static'] 131 | 132 | # Custom sidebar templates, must be a dictionary that maps document names 133 | # to template names. 134 | # 135 | # The default sidebars (for documents that don't match any pattern) are 136 | # defined by theme itself. Builtin themes are using these templates by 137 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', 138 | # 'searchbox.html']``. 139 | # 140 | # html_sidebars = {} 141 | 142 | 143 | # -- Options for HTMLHelp output --------------------------------------------- 144 | 145 | # Custom sidebar templates, maps document names to template names. 146 | html_sidebars = { 147 | '**': [ 148 | 'about.html', 149 | 'navigation.html', 150 | 'relations.html', 151 | 'searchbox.html', 152 | ] 153 | } 154 | 155 | # Output file base name for HTML help builder. 156 | htmlhelp_basename = 'FITSpecificationdoc' 157 | 158 | 159 | # -- Options for LaTeX output ------------------------------------------------ 160 | 161 | latex_elements = { 162 | 'classoptions': ',oneside', 163 | 'babel': '\\usepackage[english]{babel}', 164 | 'sphinxsetup': 'hmargin=2cm', 165 | 166 | # The paper size ('letterpaper' or 'a4paper'). 167 | # 168 | 'papersize': 'a4paper', 169 | 170 | # The font size ('10pt', '11pt' or '12pt'). 171 | # 172 | # 'pointsize': '10pt', 173 | 174 | # Additional stuff for the LaTeX preamble. 175 | # 176 | # 'preamble': '', 177 | 178 | # Latex figure (float) alignment 179 | # 180 | 'figure_align': 'H', 181 | } 182 | 183 | # Release numbers with a qualifier (ex. '-rc', '-pre') get a watermark. 184 | if '-' in release: 185 | latex_elements['preamble'] = '\\usepackage{draftwatermark}\\SetWatermarkScale{.45}\\SetWatermarkText{%s}' % (release) 186 | 187 | # Grouping the document tree into LaTeX files. List of tuples 188 | # (source start file, target name, title, 189 | # author, documentclass [howto, manual, or own class]). 190 | latex_documents = [ 191 | (master_doc, 'fit-specification.tex', 192 | u'Flattened Image Tree (FIT) Specification', 193 | u'github.com/open-source-firmware/flat-image-tree', 'manual'), 194 | ] 195 | 196 | # The name of an image file (relative to this directory) to place at the top of 197 | # the title page. 198 | latex_logo = "fit-logo.png" 199 | 200 | # -- Options for manual page output ------------------------------------------ 201 | 202 | # One entry per manual page. List of tuples 203 | # (source start file, name, description, authors, manual section). 204 | man_pages = [ 205 | (master_doc, 'fit-specification', u'Flattened Image Tree (FIT) Specification', 206 | [author], 1) 207 | ] 208 | 209 | 210 | # -- Options for Texinfo output ---------------------------------------------- 211 | 212 | # Grouping the document tree into Texinfo files. List of tuples 213 | # (source start file, target name, title, author, 214 | # dir menu entry, description, category) 215 | texinfo_documents = [ 216 | (master_doc, 'fit-specification', u'Flattened Image Tree (FIT) Specification', 217 | author, 'FITSpecification', 'Flattened Image Tree specification.', 218 | 'Miscellaneous'), 219 | ] 220 | 221 | 222 | # -- Options for Epub output ------------------------------------------------- 223 | 224 | # Bibliographic Dublin Core info. 225 | epub_title = project 226 | 227 | # The unique identifier of the text. This can be a ISBN number 228 | # or the project homepage. 229 | # 230 | # epub_identifier = '' 231 | 232 | # A unique identification for the text. 233 | # 234 | # epub_uid = '' 235 | 236 | # A list of files that should not be packed into the epub file. 237 | epub_exclude_files = ['search.html'] 238 | 239 | 240 | # -- Extension configuration ------------------------------------------------- 241 | 242 | # -- Options for todo extension ---------------------------------------------- 243 | 244 | # If true, `todo` and `todoList` produce output, else they produce nothing. 245 | todo_include_todos = False 246 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright 2016-2021 Arm, Ltd. 191 | Copyright 2016,2017 Linaro, Ltd. 192 | Copyright 2008,2011 Power.org, Inc 193 | Copyright 2008,2011 Freescale Semiconductor, Inc. 194 | Copyright 2008,2011 International Business Machines Corporation 195 | 196 | Licensed under the Apache License, Version 2.0 (the "License"); 197 | you may not use this file except in compliance with the License. 198 | You may obtain a copy of the License at 199 | 200 | http://www.apache.org/licenses/LICENSE-2.0 201 | 202 | Unless required by applicable law or agreed to in writing, software 203 | distributed under the License is distributed on an "AS IS" BASIS, 204 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 205 | See the License for the specific language governing permissions and 206 | limitations under the License. 207 | -------------------------------------------------------------------------------- /source/chapter3-usage.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0+ 2 | 3 | .. _chapter-usage: 4 | 5 | Flattened Image Tree (FIT) Usage 6 | ================================ 7 | 8 | Introduction 9 | ------------ 10 | 11 | This section describes how FIT is typically used. This is not necessarily 12 | proscriptive but may be useful for those implementing this specification. 13 | 14 | Boot process 15 | ------------ 16 | 17 | At some point in the boot process, the bootloader select and boot an Operating 18 | System. To do this, it follows these steps: 19 | 20 | #. Load a FIT into memory 21 | #. Select a configuration to boot 22 | #. Load the images from the selected configuration 23 | #. Fix up the devicetree 24 | #. Jump to the OS 25 | 26 | Each of these is now dealt with in turn. 27 | 28 | Load a FIT into memory 29 | ~~~~~~~~~~~~~~~~~~~~~~ 30 | 31 | The bootloader provides a way to select a FIT to load into memory. This is 32 | typically on boot media available to the bootloader, such as eMMC or UFS. 33 | 34 | There may be multiple FITs available. The mechanism for locating and selecting 35 | a FIT is not defined by this specification. See for example [VBE]_. 36 | 37 | The bootloader may load the entire FIT into memory at once, before processing 38 | it. For simple applications where there are just a few images, this is the 39 | easiest approach. 40 | 41 | Where there are many configuration and several images, such that only a subset 42 | of the available images will actually be used on any one boot, it is inefficient 43 | to load the entire FIT, since most of the loaded data will not be used. In this 44 | case, an external-data FIT can be used. See :ref:`Externaldata`. 45 | 46 | In this case, the bootloader reads the FDT header (say 64 bytes), checks that 47 | it is valid, then reads enough more bytes to bring in ``totalsize`` bytes 48 | (``totalsize`` is the second 32-bit word in the header). Typically this will be 49 | a few KB of data, consisting just of the FIT metadata. Later, the bootloader can 50 | read more data from the FIT as it needs to load each image. 51 | 52 | Another case that sometimes comes up is loading images from a FIT into internal 53 | SRAM, which may be very limited. In that case it may be useful to align images 54 | on a storage-device's block boundary (see ``-B`` flag in :ref:`Externaldata`). 55 | The bootloader can then avoid needing bounce buffers and other complications. 56 | 57 | Select a configuration to boot 58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 | 60 | The FIT typically contains more than one configuration. It is common to use a 61 | separate configuration for each supported model. The configuration contains 62 | a ``compatible`` stringlist which indicates which models the configuration is 63 | compatible with. 64 | 65 | The bootloader itself typically has a compatible stringlist, indicating the 66 | model that it is running on. For U-Boot this is in the root node of the 67 | devicetree used by U-Boot, typically exactly the same devicetree as is used by 68 | Linux for that model. For other bootloaders, the stringlist may be hard-coded, 69 | or obtained by some other means. 70 | 71 | The bootloader should loop through each configuration to find the best match to 72 | its own compatible string. The best match is the configuration which matches 73 | earliest string in the bootloader's compatible stringlist. 74 | 75 | For example, imagine the bootloader has ``compatible = "foo,bar", "bim,bam"`` 76 | and the FIT has two configurations:: 77 | 78 | config-1 { 79 | compatible = "foo,bar"; 80 | fdt = "fdt-1"; 81 | ... 82 | }; 83 | config-2 { 84 | compatible = "bim,bam", "baz,biz"; 85 | fdt = "fdt-2"; 86 | ... 87 | }; 88 | 89 | Here, the bootloader chooses ``config-1`` since it is a better match. The first 90 | string in the bootloader's compatible list, ``"foo,bar"``, matches a compatible 91 | string in the root of ``fdt1``. Although ``"bim,bam"`` in ``fdt2`` matches the 92 | second string, this isn't as good a match as ``fdt1``. 93 | 94 | In U-Boot this algorithm is handled by ``fit_conf_find_compat()`` and enabled 95 | by the ``CONFIG_FIT_BEST_MATCH`` option. 96 | 97 | Sometime models have multiple PCB revisions or different minor variants, often 98 | referred to as SKUs. For this reason, bootloaders may want to select 99 | configurations in a finer-grained way. In this case, rather than using the 100 | compatible stringlist in its devicetree, if any, it constructs a single string 101 | using the base name along with any available suffixes, each beginning with a 102 | hyphen. The best match algorithm is then run using that string. 103 | 104 | The following compatible-string suffixes may be used to this end. They must be 105 | provided in this order ( is an integer >= 0): 106 | 107 | ``-rev`` 108 | Board revision number, typically referring to a revision of the PCB to fix 109 | a problem or adjust component selection. The intention is that the board is 110 | the same design, just with some minor fixes or improvements. The first 111 | revision is typically ``rev0``. 112 | 113 | ``-sku`` 114 | Board variant, called a SKU (Stock-Keeping Unit) which is a unique code that 115 | identifies a model variant. This may encode differences in the display, 116 | WiFi and the like, but where the same PCB design (and revision) is used. 117 | The base SKU is typically ``sku0``. 118 | 119 | Examples:: 120 | 121 | compatible = "google,kevin-rev15"; 122 | compatible = "google,kevin-rev15-sku2"; 123 | 124 | When matching, the bootloader should build the most specific string it can using 125 | any available revision / SKU information, then try to match that. If the most 126 | specific string fails (e.g. ``"google,kevin-rev15-sku2"``), it should fall back 127 | to just ``"google,kevin-rev15"`` and then ``"google,kevin-sku2"``. If nothing 128 | matches, then it should try without any additions, i.e. ``"google,kevin"``. 129 | 130 | This multi-stage process uses the same 'best match' approach as above. Each 131 | attempt finds the best match given the compatible string being searched. Where 132 | a stage does not find any match, the next stage begins. As soon as a match is 133 | found, searching stops, using the best match found in the stage. 134 | 135 | Other suffixes may be added in future. 136 | 137 | 138 | Load the images from the selected configuration 139 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 140 | 141 | The configuration contains a number of images. One of these is the OS itself. 142 | Another is typically a devicetree blob, which provides information about 143 | available devices, useful for the OS as it boots and runs. Another image may be 144 | a ramdisk (or initrd) which provides an initial root disk for the OS to use, 145 | before it is able to access the real root disk. 146 | 147 | The bootloader reads each image from the FIT and 'loads' it to the correct 148 | address. This address may be provided by the image's ``load`` property 149 | (see :ref:`prop_load`), but if not provided, the bootloader can load it to any 150 | suitable address. In some cases it may be possible to avoid loading the image 151 | and just refer to the image data within the FIT itself. 152 | 153 | Fix up the devicetree 154 | ~~~~~~~~~~~~~~~~~~~~~ 155 | 156 | Many Operating Systems use devicetree blobs for configuration. As a result, most 157 | bootloaders provide a way to update the devicetree in the FIT before passing it 158 | to the OS. This may be used to pass command-line parameters to Linux, to select 159 | the console device to use, or to pass the ramdisk to the OS. It is also common 160 | to enable or disable certain devicetree nodes based on the hardware 161 | in use. 162 | 163 | The fixups required depend on the OS and its expectations. The result is a 164 | devicetree slightly modified from the FIT version. 165 | 166 | Jump to the OS 167 | ~~~~~~~~~~~~~~ 168 | 169 | Once everything is ready, the bootloader jumps to the OS. At this point the FIT 170 | is no longer in use. The OS typically does not see the FIT itself and only cares 171 | about the images that were loaded. At this point, the FIT has served its 172 | purpose. 173 | 174 | Firmware usage 175 | -------------- 176 | 177 | As firmware has become more complex, with multiple binaries loaded at each 178 | phase of the boot, it has become common to use FIT to load firmware. 179 | 180 | In this case, there is the concept of a boot phase (see :ref:`prop_phase`), 181 | indicating which phase each image is for. 182 | 183 | In this case the bootloader itself is likely split into multiple phases. For 184 | U-Boot, a common approach is for SPL (Secondary Program Loader) to load U-Boot 185 | proper, along with :index:`ATF` and any other images required by U-Boot proper. 186 | 187 | FIT processing for firmware images is no different from the approach described 188 | above, except that any image with a ``phase`` property is only loaded if the 189 | phase matches the phase being loaded. So, for example, SPL loads U-Boot proper 190 | so will only load images with a phase of "u-boot". If TPL is in use (the phase 191 | before SPL), then TPL will only load images with a phase of "spl". This allows 192 | all images to be provided in a single FIT, with each phase pulling out what is 193 | needed as the boot proceeds. 194 | 195 | .. _multi_step: 196 | 197 | Multi-step loading 198 | ------------------ 199 | 200 | The most common use of a FIT is where each configuration contains everything 201 | needed to boot. For example, on ARM systems a configuration contains a kernel, 202 | devicetree(s) and a ramdisk if needed. This approach is widely used on embedded 203 | systems. 204 | 205 | This approach is not always desirable, however, particularly when the firmware 206 | and the OS are supplied by different parties. In that case, the devicetree may 207 | be provided by the firmware with the other pieces coming from the OS. This 208 | means that FIT may omit the devicetree images. 209 | 210 | With devicetree in particular, it is common for the OS to provide its own 211 | version, or perhaps a devicetree overlay to add some new nodes and properties. 212 | 213 | Obviously if the OS has to provide a devicetree for every device, the OS files 214 | would become very large. A middle path could be that the hardware vendor 215 | provides a FIT on a boot partition, containing devicetrees for hardware 216 | supported by that vendor. Then the bootloader can load that FIT to get just the 217 | devicetree, followed by the main FIT to load the OS. 218 | 219 | To enable this last case, add a :ref:`load_only` property to the configuration. 220 | This signals to the bootloader that it should not require an executable (i.e. 221 | kernel or firmware), nor should it try to boot with this configuration. Booting 222 | then becomes a two-step process: load one FIT to obtain the devicetree, then 223 | another to obtain the OS. Only the second FIT is booted. 224 | 225 | Specifically, the 'load-only' property adjusts the meaning of loading a FIT, so 226 | that implementors should follow the following behaviour: 227 | 228 | =================== ================== ==================== 229 | 'load-only' present Executable present Behaviour 230 | =================== ================== ==================== 231 | no no Raise an error 232 | yes no Only load the images 233 | no yes Execute binary 234 | yes yes Execute binary 235 | =================== ================== ==================== 236 | 237 | Security 238 | -------- 239 | 240 | FIT has robust security features. When enabled, each FIT configuration has 241 | one or more signatures. These protect the configuration and the images it 242 | refers to. The bootloader must check the signatures against a public key which 243 | it has stored elsewhere. 244 | 245 | If any configuration fails its signature check, then it must be ignored. Images 246 | must each include a suitable hash node, so that images are actually protected 247 | against modification. Once each image is loaded, its hash must be computed and 248 | checked against the hash in the FIT. 249 | 250 | For more information on FIT security, see 251 | `U-Boot's documentation `_. 252 | The mechanism is also widely covered in conference talks, some of which are 253 | listed at `elinux.org `_. 254 | 255 | .. sectionauthor:: Simon Glass 256 | -------------------------------------------------------------------------------- /source/chapter2-source-file-format.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0+ 2 | 3 | .. _chapter-source-file-format: 4 | 5 | Flattened Image Tree (FIT) Format 6 | ================================= 7 | 8 | Introduction 9 | ------------ 10 | 11 | FIT consists of a devicetree blob with nodes and properties following a certain 12 | schema. Therefore this document defines FIT by providing FDT (Flat Device Tree) 13 | bindings. These describe the final form of the FIT at the moment when it is 14 | used. The user perspective may be simpler, as some of the properties (like 15 | timestamps and hashes) are filled in automatically by available tooling, such 16 | as `mkimage`. 17 | 18 | To avoid confusion with the :index:`kernel FDT ` the following 19 | naming convention is used: 20 | 21 | FIT 22 | Flattened Image Tree 23 | 24 | FIT is formally a flattened devicetree (in the libfdt meaning), which 25 | conforms to bindings defined in this document. 26 | 27 | :index:`.its` 28 | image tree source 29 | 30 | :index:`.fit` 31 | flattened image tree blob 32 | 33 | This was previously known as :index:`.itb` but has been renamed to `.fit`. 34 | 35 | Image-building procedure 36 | ~~~~~~~~~~~~~~~~~~~~~~~~ 37 | 38 | The following picture shows how the FIT is prepared. Input consists of 39 | image source file (.its) and a set of data files. Image is created with the 40 | help of standard :index:`U-Boot mkimage ` tool which in 41 | turn uses dtc (device tree compiler) to produce image tree blob (.fit). The 42 | resulting .fit file is the actual binary of a new FIT:: 43 | 44 | tqm5200.its 45 | + 46 | vmlinux.bin.gz mkimage + dtc xfer to target 47 | eldk-4.2-ramdisk --------------> tqm5200.fit --------------> boot 48 | tqm5200.dtb /|\ 49 | | 50 | 'new FIT' 51 | 52 | Steps: 53 | 54 | #. Create .its file, automatically filled-in properties are omitted 55 | 56 | #. Call :index:`mkimage` tool on .its file 57 | 58 | #. mkimage calls dtc to create .fit image and assures that 59 | missing properties are added 60 | 61 | #. .fit (new FIT) is uploaded onto the target and used therein 62 | 63 | 64 | Unique identifiers 65 | ~~~~~~~~~~~~~~~~~~ 66 | 67 | To identify FIT sub-nodes representing images, hashes, configurations (which 68 | are defined in the following sections), the "unit name" of the given sub-node 69 | is used as its identifier as it assures uniqueness without additional 70 | checking required. 71 | 72 | .. index:: External data 73 | 74 | .. _ExternalData: 75 | 76 | External data 77 | ~~~~~~~~~~~~~ 78 | 79 | FIT is normally built initially with image data in the 'data' property of each 80 | image node. It is also possible for this data to reside outside the FIT itself. 81 | This allows the 'FDT' part of the FIT to be quite small, so that it can be 82 | loaded and scanned without loading a large amount of data. Then when an image is 83 | needed it can be loaded from an external source. 84 | 85 | External FITs use 'data-offset' or 'data-position' instead of 'data'. 86 | 87 | The :index:`mkimage` tool can convert a FIT to use external data using the `-E` 88 | argument, optionally using `-p` to specific a fixed position. 89 | 90 | It is often desirable to align each image to a block size or cache-line size 91 | (e.g. 512 bytes), so that there is no need to copy it to an 92 | :index:`aligned address` when reading the image data. The mkimage tool provides 93 | a `-B` argument to support this. 94 | 95 | Root-node properties 96 | -------------------- 97 | 98 | The root node of the FIT should have the following layout:: 99 | 100 | / o image-tree 101 | |- description = "image description" 102 | |- timestamp = <12399321> 103 | |- #address-cells = <1> 104 | | 105 | o images 106 | | | 107 | | o image-1 {...} 108 | | o image-2 {...} 109 | | ... 110 | | 111 | o configurations 112 | |- default = "conf-1" 113 | | 114 | o conf-1 {...} 115 | o conf-2 {...} 116 | ... 117 | 118 | Optional property 119 | ~~~~~~~~~~~~~~~~~ 120 | 121 | description 122 | Textual description of the FIT 123 | 124 | Mandatory property 125 | ~~~~~~~~~~~~~~~~~~ 126 | 127 | :index:`timestamp` 128 | Last image modification time being counted in seconds since 129 | 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. 130 | 131 | Conditionally mandatory property 132 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133 | 134 | :index:`#address-cells` 135 | Number of 32bit cells required to represent entry and 136 | load addresses supplied within sub-image nodes. May be omitted when no 137 | entry or load addresses are used. 138 | 139 | Mandatory nodes 140 | ~~~~~~~~~~~~~~~ 141 | 142 | :index:`images` 143 | This node contains a set of sub-nodes, each of them representing 144 | single component sub-image (like :index:`kernel`, :index:`ramdisk`, etc.). 145 | At least one sub-image is required. 146 | 147 | :index:`configurations` 148 | Contains a set of available configuration nodes and 149 | defines a default configuration. 150 | 151 | 152 | '/images' node 153 | -------------- 154 | 155 | This node is a container node for component sub-image nodes. Each sub-node of 156 | the '/images' node should have the following layout:: 157 | 158 | o image-1 159 | |- description = "component sub-image description" 160 | |- data = /incbin/("path/to/data/file.bin") 161 | |- type = "sub-image type name" 162 | |- arch = "ARCH name" 163 | |- os = "OS name" 164 | |- compression = "compression name" 165 | |- load = <00000000> 166 | |- entry = <00000000> 167 | | 168 | o hash-1 {...} 169 | o hash-2 {...} 170 | ... 171 | 172 | Mandatory properties 173 | ~~~~~~~~~~~~~~~~~~~~ 174 | 175 | description 176 | Textual description of the component sub-image 177 | 178 | :index:`type` 179 | Name of component sub-image type. Supported types are: 180 | 181 | ==================== ================== 182 | Sub-image type Meaning 183 | ==================== ================== 184 | invalid Invalid Image 185 | aisimage Davinci AIS image 186 | atmelimage ATMEL ROM-Boot Image 187 | copro Coprocessor Image 188 | fdt_legacy legacy Image with Flat Device Tree 189 | filesystem Filesystem Image 190 | firmware Firmware 191 | firmware_ivt Firmware with HABv4 IVT 192 | flat_dt Flat Device Tree 193 | fpga FPGA Device Image (bitstream file, vendor specific) 194 | gpimage TI Keystone SPL Image 195 | imx8image NXP i.MX8 Boot Image 196 | imx8mimage NXP i.MX8M Boot Image 197 | imximage Freescale i.MX Boot Image 198 | kernel Kernel Image 199 | kernel_noload Kernel Image (no loading done) 200 | kwbimage Kirkwood Boot Image 201 | lpc32xximage LPC32XX Boot Image 202 | mtk_image MediaTek BootROM loadable Image 203 | multi Multi-File Image 204 | mxsimage Freescale MXS Boot Image 205 | omapimage TI OMAP SPL With GP CH 206 | pblimage Freescale PBL Boot Image 207 | pmmc TI Power Management Micro-Controller Firmware 208 | ramdisk RAMDisk Image 209 | rkimage Rockchip Boot Image 210 | rksd Rockchip SD Boot Image 211 | rkspi Rockchip SPI Boot Image 212 | script Script 213 | socfpgaimage Altera SoCFPGA CV/AV preloader 214 | socfpgaimage_v1 Altera SoCFPGA A10 preloader 215 | spkgimage Renesas SPKG Image 216 | standalone Standalone Program 217 | stm32image STMicroelectronics STM32 Image 218 | sunxi_egon Allwinner eGON Boot Image 219 | sunxi_toc0 Allwinner TOC0 Boot Image 220 | tee Trusted Execution Environment Image 221 | tfa-bl31 Trusted Firmware-A BL31 Image 222 | ublimage Davinci UBL image 223 | vybridimage Vybrid Boot Image 224 | x86_setup x86 setup.bin 225 | zynqimage Xilinx Zynq Boot Image 226 | zynqmpbif Xilinx ZynqMP Boot Image (bif) 227 | zynqmpimage Xilinx ZynqMP Boot Image 228 | ==================== ================== 229 | 230 | compression 231 | :index:`Compression` used by included data. If no compression is used, the 232 | compression property should be set to "none". If the data is compressed but 233 | it should not be uncompressed by the loader 234 | (e.g. :index:`compressed ramdisk ` for which the image is intended. 378 | 379 | "spl" 380 | image is an SPL image 381 | 382 | "u-boot" 383 | image is a U-Boot image 384 | 385 | Optional nodes 386 | ~~~~~~~~~~~~~~ 387 | 388 | hash-1 389 | Each hash sub-node represents a separate hash or checksum 390 | calculated for node's data according to specified algorithm. 391 | 392 | signature-1 393 | Each signature sub-node represents a separate signature 394 | calculated for node's data according to specified algorithm. 395 | 396 | .. index:: Hash nodes 397 | 398 | Hash nodes 399 | ---------- 400 | 401 | :: 402 | 403 | o hash-1 404 | |- algo = "hash or checksum algorithm name" 405 | |- value = [hash or checksum value] 406 | 407 | Mandatory properties 408 | ~~~~~~~~~~~~~~~~~~~~ 409 | 410 | algo 411 | :index:`Algorithm` name. Supported algorithms and their value sizes are: 412 | 413 | ==================== ============ ========================================= 414 | Sub-image type Size (bytes) Meaning 415 | ==================== ============ ========================================= 416 | crc16-ccitt 2 Cyclic Redundancy Check 16-bit 417 | (Consultative Committee for International 418 | Telegraphy and Telephony) 419 | crc32 4 Cyclic Redundancy Check 32-bit 420 | md5 16 Message Digest 5 (MD5) 421 | sha1 20 Secure Hash Algorithm 1 (SHA1) 422 | sha256 32 Secure Hash Algorithm 2 (SHA256) 423 | sha384 48 Secure Hash Algorithm 2 (SHA384) 424 | sha512 64 Secure Hash Algorithm 2 (SHA512) 425 | ==================== ============ ========================================= 426 | 427 | value 428 | Actual checksum or hash value. 429 | 430 | Image-signature nodes 431 | --------------------- 432 | 433 | :: 434 | 435 | o signature-1 436 | |- algo = "algorithm name" 437 | |- key-name-hint = "key name" 438 | |- value = [hash or checksum value] 439 | 440 | 441 | Mandatory properties 442 | ~~~~~~~~~~~~~~~~~~~~ 443 | 444 | _`FIT Algorithm`: 445 | 446 | algo 447 | :index:`Algorithm` name. Supported algorithms and their value sizes are 448 | shown below. Note that the hash is specified separately from the signing 449 | algorithm, so it is possible to mix and match any SHA algorithm with any 450 | signing algorithm. The size of the signature relates to the signing 451 | algorithm, not the hash, since it is the hash that is signed. 452 | 453 | ==================== ============ ========================================= 454 | Sub-image type Size (bytes) Meaning 455 | ==================== ============ ========================================= 456 | sha1,rsa2048 256 SHA1 hash signed with 2048-bit 457 | Rivest–Shamir–Adleman algorithm 458 | sha1,rsa3072 384 SHA1 hash signed with 2048-bit RSA 459 | sha1,rsa4096 512 SHA1 hash signed with 2048-bit RSA 460 | sha1,ecdsa256 32 SHA1 hash signed with 256-bit Elliptic 461 | Curve Digital Signature Algorithm 462 | sha256,... 463 | sha384,... 464 | sha512,... 465 | ==================== ============ ========================================= 466 | 467 | key-name-hint 468 | Name of key to use for signing. The keys will normally be in 469 | a single directory (parameter -k to mkimage). For a given key , its 470 | private key is stored in .key and the certificate is stored in 471 | .crt. 472 | 473 | sign-images 474 | A list of images to sign, each being a property of the conf 475 | node that contains them. The default is "kernel,fdt" which means that these 476 | two images will be looked up in the config and signed if present. This is 477 | used by mkimage to determine which images to sign. 478 | 479 | The following properties are added as part of signing, and are mandatory: 480 | 481 | value 482 | Actual signature value. This is added by mkimage. 483 | 484 | hashed-nodes 485 | A list of nodes which were :index:`hashed ` by the 486 | signer. Each is a string - the full path to node. A typical value might be:: 487 | 488 | hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", 489 | "/images/kernel/hash-1", "/images/fdt-1", 490 | "/images/fdt-1/hash-1"; 491 | 492 | hashed-strings 493 | The start and size of the :index:`string ` region of 494 | the FIT that was hashed. The start is normally 0, indicating the first byte 495 | of the string table. The size indicates the number of bytes hashed as part 496 | of signing. 497 | 498 | The following properties are added as part of signing, and are optional: 499 | 500 | timestamp 501 | Time when image was signed (standard Unix time_t format) 502 | 503 | signer-name 504 | Name of the signer (e.g. "mkimage") 505 | 506 | signer-version 507 | Version string of the signer (e.g. "2013.01") 508 | 509 | comment 510 | Additional information about the signer or image 511 | 512 | padding 513 | The padding algorithm, it may be pkcs-1.5 or pss, 514 | if no value is provided we assume pkcs-1.5 515 | 516 | 517 | '/configurations' node 518 | ---------------------- 519 | 520 | The 'configurations' node creates convenient, labeled 521 | :index:`boot configurations `, 522 | which combine together :index:`kernel images ` with their 523 | :index:`ramdisks` and fdt blobs. 524 | 525 | The 'configurations' node has the following structure:: 526 | 527 | o configurations 528 | |- default = "default configuration sub-node unit name" 529 | | 530 | o config-1 {...} 531 | o config-2 {...} 532 | ... 533 | 534 | 535 | Optional property 536 | ~~~~~~~~~~~~~~~~~ 537 | 538 | default 539 | Selects one of the configuration sub-nodes as a default configuration. 540 | 541 | Mandatory nodes 542 | ~~~~~~~~~~~~~~~ 543 | 544 | configuration-sub-node-unit-name 545 | At least one configuration sub-node is required. 546 | 547 | Optional nodes 548 | ~~~~~~~~~~~~~~ 549 | 550 | signature-1 551 | Each signature sub-node represents a separate signature 552 | calculated for the configuration according to specified algorithm. 553 | 554 | 555 | Configuration nodes 556 | ------------------- 557 | 558 | Each configuration has the following structure:: 559 | 560 | o config-1 561 | |- description = "configuration description"; 562 | |- kernel = "kernel sub-node unit name"; 563 | |- cmdline = "command line for next boot stage"; 564 | |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]; 565 | |- ramdisk = "ramdisk sub-node unit-name"; 566 | |- loadables = "loadables sub-node unit-name" [, ...]; 567 | |- script = "script sub-node unit-name"; 568 | |- compatible = "vendor,board-style device tree compatible string"; 569 | o signature-1 {...} 570 | 571 | Mandatory properties 572 | ~~~~~~~~~~~~~~~~~~~~ 573 | 574 | description 575 | Textual configuration description. 576 | 577 | Conditionally mandatory property 578 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 579 | 580 | kernel or firmware 581 | Unit name of the corresponding :index:`kernel` or :index:`firmware` 582 | (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, 583 | control is passed to the firmware image. For `load_only`_ images, these two 584 | properties are optional. 585 | 586 | 587 | Optional properties 588 | ~~~~~~~~~~~~~~~~~~~ 589 | 590 | cmdline 591 | Command line passed to the next boot stage, e.g. the operating system 592 | kernel. The value is an UTF-8 encoded string. 593 | 594 | fdt 595 | Unit name of the corresponding fdt blob (component image node of a 596 | "fdt type"). Additional fdt overlay nodes can be supplied which signify 597 | that the resulting device tree blob is generated by the first base fdt 598 | blob with all subsequent overlays applied. 599 | 600 | fpga 601 | Unit name of the corresponding fpga bitstream blob 602 | (component image node of a "fpga type"). 603 | 604 | loadables 605 | Unit name containing a list of additional binaries to be 606 | loaded at their given locations. "loadables" is a comma-separated list 607 | of strings. :index:`U-Boot` will load each binary at its given load address 608 | (see :ref:`prop_load`) and may optionally invoke additional post-processing 609 | steps on this binary based on its component image node type. 610 | 611 | ramdisk 612 | Unit name of the corresponding ramdisk to be loaded at the given location. 613 | 614 | script 615 | The image to use when loading a :index:`U-Boot` script (for use with the 616 | source command). 617 | 618 | compatible 619 | The root compatible string of the bootloader device tree that 620 | this configuration shall automatically match. If this property is not 621 | provided, the compatible string will be 622 | extracted from the fdt blob instead. This is only possible if the fdt is 623 | not compressed, so images with compressed fdts that want to use compatible 624 | string matching must always provide this property. 625 | 626 | Note that U-Boot requires the :index:`CONFIG_FIT_BEST_MATCH` option to be 627 | enabled for this matching to work. 628 | 629 | .. _load_only: 630 | 631 | load-only 632 | Indicates that this configuration does not necessarily contain an executable 633 | image, i.e. kernel or firmware. The configuration's images may be loaded 634 | into memory for use by the executable image, which comes from another 635 | configuration or FIT. See see :ref:`multi_step`. 636 | 637 | The FDT blob is required to properly boot FDT-based kernel, so the minimal 638 | configuration for 2.6 FDT kernel is (kernel, fdt) pair. 639 | 640 | Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases 641 | 'struct bd_info' must be passed instead of FDT blob, thus fdt property *must 642 | not* be specified in a configuration node. 643 | 644 | 645 | Configuration-signature nodes 646 | ----------------------------- 647 | 648 | :: 649 | 650 | o signature-1 651 | |- algo = "algorithm name" 652 | |- key-name-hint = "key name" 653 | |- sign-images = "path1", "path2"; 654 | |- value = [hash or checksum value] 655 | |- hashed-strings = <0 len> 656 | 657 | 658 | Mandatory properties 659 | ~~~~~~~~~~~~~~~~~~~~ 660 | 661 | algo 662 | See `FIT Algorithm`_. 663 | 664 | key-name-hint 665 | Name of key to use for signing. The keys will normally be in 666 | a single directory (parameter -k to mkimage). For a given key , its 667 | private key is stored in .key and the certificate is stored in 668 | .crt. 669 | 670 | The following properties are added as part of signing, and are mandatory: 671 | 672 | value 673 | Actual signature value. This is added by mkimage. 674 | 675 | The following properties are added as part of signing, and are optional: 676 | 677 | timestamp 678 | Time when image was signed (standard Unix time_t format) 679 | 680 | signer-name 681 | Name of the signer (e.g. "mkimage") 682 | 683 | signer-version 684 | Version string of the signer (e.g. "2013.01") 685 | 686 | comment 687 | Additional information about the signer or image 688 | 689 | padding 690 | The padding algorithm, it may be pkcs-1.5 or pss, 691 | if no value is provided we assume pkcs-1.5 692 | 693 | 694 | .. sectionauthor:: Marian Balakowicz 695 | .. sectionauthor:: External data additions, 25/1/16 Simon Glass 696 | --------------------------------------------------------------------------------