leandrof/u-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

binman: Add rST references for binman entry types

Browse Source 
Add references in the documentation for each entry type, so we can refer
to them from other documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass 2022-08-07 16:33:25 -06:00 committed by Heinrich Schuchardt
parent 37c42b7270
commit 228c9b8629
2 changed files with 150 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
tools/binman/entries.rst
View File

@ -11,6 +11,8 @@ features to produce new behaviours.
.. _etype_atf_bl31:
Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
-----------------------------------------------------
@ -25,6 +27,8 @@ about ATF.
.. _etype_atf_fip:
Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
-------------------------------------------------------------------
@ -179,6 +183,8 @@ FIPs so that binman and other tools can access the entire image correctly.
.. _etype_blob:
Entry: blob: Arbitrary binary blob
----------------------------------
@ -201,6 +207,8 @@ data.
.. _etype_blob_dtb:
Entry: blob-dtb: A blob that holds a device tree
------------------------------------------------
@ -210,6 +218,8 @@ obtained from the list of available device-tree files, managed by the
.. _etype_blob_ext:
Entry: blob-ext: Externally built binary blob
---------------------------------------------
@ -223,6 +233,8 @@ See 'blob' for Properties / Entry arguments.
.. _etype_blob_ext_list:
Entry: blob-ext-list: List of externally built binary blobs
-----------------------------------------------------------
@ -237,6 +249,8 @@ Args:
.. _etype_blob_named_by_arg:
Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
-----------------------------------------------------------------------------------------
@ -255,6 +269,8 @@ See cros_ec_rw for an example of this.
.. _etype_blob_phase:
Entry: blob-phase: Section that holds a phase binary
----------------------------------------------------
@ -264,6 +280,8 @@ entry; similarly for SPL.
.. _etype_cbfs:
Entry: cbfs: Coreboot Filesystem (CBFS)
---------------------------------------
@ -416,6 +434,8 @@ both of size 1MB.
.. _etype_collection:
Entry: collection: An entry which contains a collection of other entries
------------------------------------------------------------------------
@ -429,6 +449,8 @@ the image, not necessarily child entries.
.. _etype_cros_ec_rw:
Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
--------------------------------------------------------------------------------
@ -440,6 +462,8 @@ updating the EC on startup via software sync.
.. _etype_fdtmap:
Entry: fdtmap: An entry which contains an FDT map
-------------------------------------------------
@ -488,6 +512,8 @@ without the fdtmap header, so it can be viewed with `fdtdump`.
.. _etype_files:
Entry: files: A set of files arranged in a section
--------------------------------------------------
@ -504,6 +530,8 @@ at run-time so you can obtain the file positions.
.. _etype_fill:
Entry: fill: An entry which is filled to a particular byte value
----------------------------------------------------------------
@ -520,6 +548,8 @@ byte value of a region.
.. _etype_fit:
Entry: fit: Flat Image Tree (FIT)
---------------------------------
@ -803,6 +833,8 @@ U-Boot SPL can then load the firmware (U-Boot proper) and all the loadables
.. _etype_fmap:
Entry: fmap: An entry which contains an Fmap section
----------------------------------------------------
@ -828,6 +860,8 @@ CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
.. _etype_gbb:
Entry: gbb: An entry which contains a Chromium OS Google Binary Block
---------------------------------------------------------------------
@ -847,6 +881,8 @@ README.chromium for how to obtain the required keys and tools.
.. _etype_image_header:
Entry: image-header: An entry which contains a pointer to the FDT map
---------------------------------------------------------------------
@ -866,6 +902,8 @@ first/last in the entry list.
.. _etype_intel_cmc:
Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
-----------------------------------------------------
@ -879,6 +917,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_descriptor:
Entry: intel-descriptor: Intel flash descriptor block (4KB)
-----------------------------------------------------------
@ -900,6 +940,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_fit:
Entry: intel-fit: Intel Firmware Image Table (FIT)
--------------------------------------------------
@ -911,6 +953,8 @@ At present binman only supports a basic FIT with no microcode.
.. _etype_intel_fit_ptr:
Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
--------------------------------------------------------------
@ -919,6 +963,8 @@ This entry contains a pointer to the FIT. It is required to be at address
.. _etype_intel_fsp:
Entry: intel-fsp: Intel Firmware Support Package (FSP) file
-----------------------------------------------------------
@ -936,6 +982,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_fsp_m:
Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
--------------------------------------------------------------------
@ -953,6 +1001,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_fsp_s:
Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
---------------------------------------------------------------------
@ -970,6 +1020,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_fsp_t:
Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
----------------------------------------------------------------------
@ -986,6 +1038,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_ifwi:
Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
--------------------------------------------------------------
@ -1020,6 +1074,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_me:
Entry: intel-me: Intel Management Engine (ME) file
--------------------------------------------------
@ -1040,6 +1096,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_mrc:
Entry: intel-mrc: Intel Memory Reference Code (MRC) file
--------------------------------------------------------
@ -1054,6 +1112,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_refcode:
Entry: intel-refcode: Intel Reference Code file
-----------------------------------------------
@ -1068,6 +1128,8 @@ See README.x86 for information about x86 binary blobs.
.. _etype_intel_vbt:
Entry: intel-vbt: Intel Video BIOS Table (VBT) file
---------------------------------------------------
@ -1081,6 +1143,8 @@ See README.x86 for information about Intel binary blobs.
.. _etype_intel_vga:
Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
---------------------------------------------------------
@ -1096,6 +1160,8 @@ See README.x86 for information about Intel binary blobs.
.. _etype_mkimage:
Entry: mkimage: Binary produced by mkimage
------------------------------------------
@ -1130,6 +1196,8 @@ this example which also produces four arguments::
.. _etype_opensbi:
Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
----------------------------------------------
@ -1143,6 +1211,8 @@ https://github.com/riscv/opensbi for more information about OpenSBI.
.. _etype_powerpc_mpc85xx_bootpg_resetvec:
Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
-----------------------------------------------------------------------------------------
@ -1155,11 +1225,13 @@ placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
.. _etype_pre_load:
Entry: pre-load: Pre load image header
--------------------------------------
Properties / Entry arguments:
- key-path: Path of the directory that store key (provided by the environment variable KEY_PATH)
- pre-load-key-path: Path of the directory that store key (provided by the environment variable PRE_LOAD_KEY_PATH)
- content: List of phandles to entries to sign
- algo-name: Hash and signature algo to use for the signature
- padding-name: Name of the padding (pkcs-1.5 or pss)
@ -1193,6 +1265,8 @@ For example, this creates an image with a pre-load header and a binary::
.. _etype_scp:
Entry: scp: System Control Processor (SCP) firmware blob
--------------------------------------------------------
@ -1203,6 +1277,8 @@ This entry holds firmware for an external platform-specific coprocessor.
.. _etype_section:
Entry: section: Entry that contains other entries
-------------------------------------------------
@ -1338,6 +1414,8 @@ available. This is set by the `SetAllowMissing()` method, if
.. _etype_tee_os:
Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
---------------------------------------------------------------
@ -1351,6 +1429,8 @@ https://github.com/OP-TEE/optee_os for more information about OP-TEE.
.. _etype_text:
Entry: text: An entry which contains text
-----------------------------------------
@ -1399,6 +1479,8 @@ by setting the size of the entry to something larger than the text.
.. _etype_u_boot:
Entry: u-boot: U-Boot flat binary
---------------------------------
@ -1420,6 +1502,8 @@ Note that this entry is automatically replaced with u-boot-expanded unless
.. _etype_u_boot_dtb:
Entry: u-boot-dtb: U-Boot device tree
-------------------------------------
@ -1435,6 +1519,8 @@ binman to know which entries contain a device tree.
.. _etype_u_boot_dtb_with_ucode:
Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
-----------------------------------------------------------------------------------
@ -1451,6 +1537,8 @@ it available to u-boot-ucode.
.. _etype_u_boot_elf:
Entry: u-boot-elf: U-Boot ELF image
-----------------------------------
@ -1462,6 +1550,8 @@ relocated to any address for execution.
.. _etype_u_boot_env:
Entry: u-boot-env: An entry which contains a U-Boot environment
---------------------------------------------------------------
@ -1471,6 +1561,8 @@ Properties / Entry arguments:
.. _etype_u_boot_expanded:
Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
------------------------------------------------------------------------------
@ -1486,6 +1578,8 @@ image, so that the entries positions are provided to the running U-Boot.
.. _etype_u_boot_img:
Entry: u-boot-img: U-Boot legacy image
--------------------------------------
@ -1500,6 +1594,8 @@ applications.
.. _etype_u_boot_nodtb:
Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
--------------------------------------------------------------------
@ -1514,6 +1610,8 @@ section containing u-boot and u-boot-dtb
.. _etype_u_boot_spl:
Entry: u-boot-spl: U-Boot SPL binary
------------------------------------
@ -1541,6 +1639,8 @@ unless --no-expanded is used or the node has a 'no-expanded' property.
.. _etype_u_boot_spl_bss_pad:
Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
---------------------------------------------------------------------
@ -1563,6 +1663,8 @@ binman uses that to look up the BSS address.
.. _etype_u_boot_spl_dtb:
Entry: u-boot-spl-dtb: U-Boot SPL device tree
---------------------------------------------
@ -1575,6 +1677,8 @@ to activate.
.. _etype_u_boot_spl_elf:
Entry: u-boot-spl-elf: U-Boot SPL ELF image
-------------------------------------------
@ -1586,6 +1690,8 @@ be relocated to any address for execution.
.. _etype_u_boot_spl_expanded:
Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
--------------------------------------------------------------------------------------
@ -1609,6 +1715,8 @@ this is non-empty (and not 'n' or '0') then this expanded entry is selected.
.. _etype_u_boot_spl_nodtb:
Entry: u-boot-spl-nodtb: SPL binary without device tree appended
----------------------------------------------------------------
@ -1633,6 +1741,8 @@ binman uses that to look up symbols to write into the SPL binary.
.. _etype_u_boot_spl_with_ucode_ptr:
Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
----------------------------------------------------------------------------
@ -1643,6 +1753,8 @@ process.
.. _etype_u_boot_tpl:
Entry: u-boot-tpl: U-Boot TPL binary
------------------------------------
@ -1670,6 +1782,8 @@ unless --no-expanded is used or the node has a 'no-expanded' property.
.. _etype_u_boot_tpl_bss_pad:
Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
---------------------------------------------------------------------
@ -1692,6 +1806,8 @@ binman uses that to look up the BSS address.
.. _etype_u_boot_tpl_dtb:
Entry: u-boot-tpl-dtb: U-Boot TPL device tree
---------------------------------------------
@ -1704,6 +1820,8 @@ to activate.
.. _etype_u_boot_tpl_dtb_with_ucode:
Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
----------------------------------------------------------------------------
@ -1714,6 +1832,8 @@ process.
.. _etype_u_boot_tpl_elf:
Entry: u-boot-tpl-elf: U-Boot TPL ELF image
-------------------------------------------
@ -1725,6 +1845,8 @@ be relocated to any address for execution.
.. _etype_u_boot_tpl_expanded:
Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
--------------------------------------------------------------------------------------
@ -1748,6 +1870,8 @@ this is non-empty (and not 'n' or '0') then this expanded entry is selected.
.. _etype_u_boot_tpl_nodtb:
Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
----------------------------------------------------------------
@ -1772,6 +1896,8 @@ binman uses that to look up symbols to write into the TPL binary.
.. _etype_u_boot_tpl_with_ucode_ptr:
Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
----------------------------------------------------------------------------
@ -1780,6 +1906,8 @@ process.
.. _etype_u_boot_ucode:
Entry: u-boot-ucode: U-Boot microcode block
-------------------------------------------
@ -1830,6 +1958,8 @@ Entry types that have a part to play in handling microcode:
.. _etype_u_boot_with_ucode_ptr:
Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
--------------------------------------------------------------------
@ -1846,6 +1976,8 @@ complicated. Otherwise it is the same as the u-boot entry.
.. _etype_vblock:
Entry: vblock: An entry which contains a Chromium OS verified boot block
------------------------------------------------------------------------
@ -1869,6 +2001,8 @@ and kernel are genuine.
.. _etype_x86_reset16:
Entry: x86-reset16: x86 16-bit reset code for U-Boot
----------------------------------------------------
@ -1885,6 +2019,8 @@ For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
.. _etype_x86_reset16_spl:
Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
--------------------------------------------------------
@ -1901,6 +2037,8 @@ For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
.. _etype_x86_reset16_tpl:
Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
--------------------------------------------------------
@ -1917,6 +2055,8 @@ For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
.. _etype_x86_start16:
Entry: x86-start16: x86 16-bit start-up code for U-Boot
-------------------------------------------------------
@ -1935,6 +2075,8 @@ For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
.. _etype_x86_start16_spl:
Entry: x86-start16-spl: x86 16-bit start-up code for SPL
--------------------------------------------------------
@ -1953,6 +2095,8 @@ For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
.. _etype_x86_start16_tpl:
Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
--------------------------------------------------------

5
tools/binman/entry.py
View File

@ -750,6 +750,11 @@ features to produce new behaviours.
first_line = lines[0]
rest = [line[4:] for line in lines[1:]]
hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
# Create a reference for use by rST docs
ref_name = f'etype_{module.__name__[6:]}'.lower()
print('.. _%s:' % ref_name)
print()
print(hdr)
print('-' * len(hdr))
print('\n'.join(rest))