From 228c9b862923782ec3a01d5fd97ee38b8c8db4e0 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 7 Aug 2022 16:33:25 -0600 Subject: [PATCH] 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 --- 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 ae4305c99e..782bff1f8d 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 a07a588864..e3767aefa7 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.39.5