[PATCH 1/2] binman: Add rST references for binman entry types

Simon Glass sjg at chromium.org
Mon Aug 8 00:33:25 CEST 2022 

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

Signed-off-by: Simon Glass <sjg at chromium.org>
---

 tools/binman/entries.rst | 146 ++++++++++++++++++++++++++++++++++++++-
 tools/binman/entry.py    |   5 ++
 2 files changed, 150 insertions(+), 1 deletion(-)

diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index ae4305c99e4..782bff1f8d9 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -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
 --------------------------------------------------------
 
diff --git a/tools/binman/entry.py b/tools/binman/entry.py
index a07a5888643..e3767aefa73 100644
--- a/tools/binman/entry.py
+++ b/tools/binman/entry.py
@@ -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))
-- 
2.37.1.559.g78731f0fdb-goog

More information about the U-Boot mailing list