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

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 ---

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))