Update this to avoid sphinx warnings and incorporate it into the new documentaiton tree.
Signed-off-by: Simon Glass sjg@chromium.org ---
tools/binman/README.rst | 11 ++- tools/binman/cmdline.py | 2 +- tools/binman/{README.entries => entries.rst} | 79 +++++++++++--------- tools/binman/etype/cbfs.py | 10 +-- tools/binman/etype/fdtmap.py | 30 ++++---- tools/binman/etype/fit.py | 19 +++-- tools/binman/etype/intel_ifwi.py | 8 +- tools/binman/etype/mkimage.py | 2 +- tools/binman/etype/section.py | 6 +- tools/binman/etype/text.py | 6 +- tools/binman/setup.py | 2 +- 11 files changed, 95 insertions(+), 80 deletions(-) rename tools/binman/{README.entries => entries.rst} (97%)
diff --git a/tools/binman/README.rst b/tools/binman/README.rst index 9348a3e8e1d..5df5de4d8e3 100644 --- a/tools/binman/README.rst +++ b/tools/binman/README.rst @@ -786,12 +786,17 @@ the 'warning' line in scripts/Makefile.lib to see what it has found::
Entry Documentation -------------------- +===================
For details on the various entry types supported by binman and how to use them, -see README.entries. This is generated from the source code using: +see entries.rst which is generated from the source code using: + + binman entry-docs >tools/binman/entries.rst + +.. toctree:: + :maxdepth: 2
- binman entry-docs >tools/binman/README.entries + entries.rst
Managing images diff --git a/tools/binman/cmdline.py b/tools/binman/cmdline.py index 0c0f48951f6..95f9ba27fbd 100644 --- a/tools/binman/cmdline.py +++ b/tools/binman/cmdline.py @@ -69,7 +69,7 @@ controlled by a description in the board device tree.''' default=False, help='Update the binman node with offset/size info')
entry_parser = subparsers.add_parser('entry-docs', - help='Write out entry documentation (see README.entries)') + help='Write out entry documentation (see entries.rst)')
list_parser = subparsers.add_parser('ls', help='List files in an image') list_parser.add_argument('-i', '--image', type=str, required=True, diff --git a/tools/binman/README.entries b/tools/binman/entries.rst similarity index 97% rename from tools/binman/README.entries rename to tools/binman/entries.rst index b5032381c7f..cb89570d5b2 100644 --- a/tools/binman/README.entries +++ b/tools/binman/entries.rst @@ -106,7 +106,7 @@ is not used, it supports compression and storing ELF files.
CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
-The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.: +The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
cbfs { size = <0x100000>; @@ -122,7 +122,7 @@ This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb. Note that the size is required since binman does not support calculating it. The contents of each entry is just what binman would normally provide if it were not a CBFS node. A blob type can be used to import arbitrary files as -with the second subnode below: +with the second subnode below::
cbfs { size = <0x100000>; @@ -168,7 +168,7 @@ cbfs-type: This is an ELF file that has been loaded (i.e. mapped to memory), so appears in the CBFS as a flat binary. The input file must be an ELF image, for example this puts "u-boot" (the ELF image) into a 'stage' - entry: + entry::
cbfs { size = <0x100000>; @@ -178,7 +178,7 @@ cbfs-type: }; };
- You can use your own ELF file with something like: + You can use your own ELF file with something like::
cbfs { size = <0x100000>; @@ -211,7 +211,7 @@ not support other file types (e.g. payload), adding multiple files (like the particular offset in the CBFS and a few other things.
Of course binman can create images containing multiple CBFSs, simply by -defining these in the binman config: +defining these in the binman config::
binman { @@ -279,24 +279,24 @@ sizes are included. Note that the -u option must be provided to ensure that binman updates the FDT with the position of each entry.
-Example output for a simple image with U-Boot and an FDT map: +Example output for a simple image with U-Boot and an FDT map::
-/ { - image-name = "binman"; - size = <0x00000112>; - image-pos = <0x00000000>; - offset = <0x00000000>; - u-boot { - size = <0x00000004>; + / { + image-name = "binman"; + size = <0x00000112>; image-pos = <0x00000000>; offset = <0x00000000>; + u-boot { + size = <0x00000004>; + image-pos = <0x00000000>; + offset = <0x00000000>; + }; + fdtmap { + size = <0x0000010e>; + image-pos = <0x00000004>; + offset = <0x00000004>; + }; }; - fdtmap { - size = <0x0000010e>; - image-pos = <0x00000004>; - offset = <0x00000004>; - }; -};
If allow-repack is used then 'orig-offset' and 'orig-size' properties are added as necessary. See the binman README. @@ -344,7 +344,7 @@ input provided. Nodes for the FIT should be written out in the binman configuration just as they would be in a file passed to mkimage.
-For example, this creates an image containing a FIT with U-Boot SPL: +For example, this creates an image containing a FIT with U-Boot SPL::
binman { fit { @@ -374,7 +374,7 @@ that you want to generates nodes for two files: file1.dtb and file2.dtb The fit,fdt-list property (see above) indicates that of-list should be used. If the property is missing you will get an error.
-Then add a 'generator node', a node with a name starting with '@': +Then add a 'generator node', a node with a name starting with '@'::
images { @fdt-SEQ { @@ -389,7 +389,7 @@ files. All the properties you specify will be included in the node. This node acts like a template to generate the nodes. The generator node itself does not appear in the output - it is replaced with what binman generates.
-You can create config nodes in a similar way: +You can create config nodes in a similar way::
configurations { default = "@config-DEFAULT-SEQ"; @@ -406,8 +406,10 @@ each of your two files.
Available substitutions for '@' nodes are:
- SEQ Sequence number of the generated fdt (1, 2, ...) - NAME Name of the dtb as provided (i.e. without adding '.dtb') +SEQ: + Sequence number of the generated fdt (1, 2, ...) +NAME + Name of the dtb as provided (i.e. without adding '.dtb')
Note that if no devicetree files are provided (with '-a of-list' as above) then no nodes will be generated. @@ -416,10 +418,11 @@ The 'default' property, if present, will be automatically set to the name if of configuration whose devicetree matches the 'default-dt' entry argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'.
-Available substitutions for '@' property values are: +Available substitutions for '@' property values are
- DEFAULT-SEQ Sequence number of the default fdt,as provided by the - 'default-dt' entry argument +DEFAULT-SEQ: + Sequence number of the default fdt,as provided by the 'default-dt' entry + argument
Properties (in the 'fit' node itself): fit,external-offset: Indicates that the contents of the FIT are external @@ -633,10 +636,10 @@ Each subnode describes an entry which is placed into the IFWFI with a given sub-partition (and optional entry name).
Properties for subnodes: - ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP" - ifwi-entry - entry name t use, e.g. "IBBL" - ifwi-replace - if present, indicates that the item should be replaced - in the IFWI. Otherwise it is added. + - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP" + - ifwi-entry: entry name t use, e.g. "IBBL" + - ifwi-replace: if present, indicates that the item should be replaced + in the IFWI. Otherwise it is added.
See README.x86 for information about x86 binary blobs.
@@ -726,7 +729,7 @@ Properties / Entry arguments: - args: Other arguments to pass
The data passed to mkimage is collected from subnodes of the mkimage node, -e.g.: +e.g.::
mkimage { args = "-n test -T imximage"; @@ -766,11 +769,13 @@ This entry holds firmware for an external platform-specific coprocessor. Entry: section: Entry that contains other entries -------------------------------------------------
-Properties / Entry arguments: (see binman README for more information) +Properties / Entry arguments: (see binman README for more information): pad-byte: Pad byte to use when padding sort-by-offset: True if entries should be sorted by offset, False if - they must be in-order in the device tree description + they must be in-order in the device tree description + end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) + skip-at-start: Number of bytes before the first entry starts. These effectively adjust the starting offset of entries. For example, if this is 16, then the first entry would start at 16. An entry @@ -808,7 +813,7 @@ Properties / Entry arguments: <text>: The text to place in the entry (overrides the above mechanism). This is useful when the text is constant.
-Example node: +Example node::
text { size = <50>; @@ -821,7 +826,7 @@ You can then use:
and binman will insert that string into the entry.
-It is also possible to put the string directly in the node: +It is also possible to put the string directly in the node::
text { size = <8>; @@ -829,7 +834,7 @@ It is also possible to put the string directly in the node: message = "a message directly in the node" };
-or just: +or just::
text { size = <8>; diff --git a/tools/binman/etype/cbfs.py b/tools/binman/etype/cbfs.py index 6cdbaa085f5..baf9c3e45b7 100644 --- a/tools/binman/etype/cbfs.py +++ b/tools/binman/etype/cbfs.py @@ -22,7 +22,7 @@ class Entry_cbfs(Entry):
CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
- The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.: + The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
cbfs { size = <0x100000>; @@ -38,7 +38,7 @@ class Entry_cbfs(Entry): Note that the size is required since binman does not support calculating it. The contents of each entry is just what binman would normally provide if it were not a CBFS node. A blob type can be used to import arbitrary files as - with the second subnode below: + with the second subnode below::
cbfs { size = <0x100000>; @@ -84,7 +84,7 @@ class Entry_cbfs(Entry): This is an ELF file that has been loaded (i.e. mapped to memory), so appears in the CBFS as a flat binary. The input file must be an ELF image, for example this puts "u-boot" (the ELF image) into a 'stage' - entry: + entry::
cbfs { size = <0x100000>; @@ -94,7 +94,7 @@ class Entry_cbfs(Entry): }; };
- You can use your own ELF file with something like: + You can use your own ELF file with something like::
cbfs { size = <0x100000>; @@ -127,7 +127,7 @@ class Entry_cbfs(Entry): particular offset in the CBFS and a few other things.
Of course binman can create images containing multiple CBFSs, simply by - defining these in the binman config: + defining these in the binman config::
binman { diff --git a/tools/binman/etype/fdtmap.py b/tools/binman/etype/fdtmap.py index 6ca88a100e5..2339feeba8d 100644 --- a/tools/binman/etype/fdtmap.py +++ b/tools/binman/etype/fdtmap.py @@ -53,24 +53,24 @@ class Entry_fdtmap(Entry): Note that the -u option must be provided to ensure that binman updates the FDT with the position of each entry.
- Example output for a simple image with U-Boot and an FDT map: - - / { - image-name = "binman"; - size = <0x00000112>; - image-pos = <0x00000000>; - offset = <0x00000000>; - u-boot { - size = <0x00000004>; + Example output for a simple image with U-Boot and an FDT map:: + + / { + image-name = "binman"; + size = <0x00000112>; image-pos = <0x00000000>; offset = <0x00000000>; + u-boot { + size = <0x00000004>; + image-pos = <0x00000000>; + offset = <0x00000000>; + }; + fdtmap { + size = <0x0000010e>; + image-pos = <0x00000004>; + offset = <0x00000004>; + }; }; - fdtmap { - size = <0x0000010e>; - image-pos = <0x00000004>; - offset = <0x00000004>; - }; - };
If allow-repack is used then 'orig-offset' and 'orig-size' properties are added as necessary. See the binman README. diff --git a/tools/binman/etype/fit.py b/tools/binman/etype/fit.py index 1a7cbd7cec7..c4fa711b850 100644 --- a/tools/binman/etype/fit.py +++ b/tools/binman/etype/fit.py @@ -22,7 +22,7 @@ class Entry_fit(Entry): Nodes for the FIT should be written out in the binman configuration just as they would be in a file passed to mkimage.
- For example, this creates an image containing a FIT with U-Boot SPL: + For example, this creates an image containing a FIT with U-Boot SPL::
binman { fit { @@ -52,7 +52,7 @@ class Entry_fit(Entry): The fit,fdt-list property (see above) indicates that of-list should be used. If the property is missing you will get an error.
- Then add a 'generator node', a node with a name starting with '@': + Then add a 'generator node', a node with a name starting with '@'::
images { @fdt-SEQ { @@ -67,7 +67,7 @@ class Entry_fit(Entry): node acts like a template to generate the nodes. The generator node itself does not appear in the output - it is replaced with what binman generates.
- You can create config nodes in a similar way: + You can create config nodes in a similar way::
configurations { default = "@config-DEFAULT-SEQ"; @@ -84,8 +84,10 @@ class Entry_fit(Entry):
Available substitutions for '@' nodes are:
- SEQ Sequence number of the generated fdt (1, 2, ...) - NAME Name of the dtb as provided (i.e. without adding '.dtb') + SEQ: + Sequence number of the generated fdt (1, 2, ...) + NAME + Name of the dtb as provided (i.e. without adding '.dtb')
Note that if no devicetree files are provided (with '-a of-list' as above) then no nodes will be generated. @@ -94,10 +96,11 @@ class Entry_fit(Entry): if of configuration whose devicetree matches the 'default-dt' entry argument, e.g. with '-a default-dt=sun50i-a64-pine64-lts'.
- Available substitutions for '@' property values are: + Available substitutions for '@' property values are
- DEFAULT-SEQ Sequence number of the default fdt,as provided by the - 'default-dt' entry argument + DEFAULT-SEQ: + Sequence number of the default fdt,as provided by the 'default-dt' entry + argument
Properties (in the 'fit' node itself): fit,external-offset: Indicates that the contents of the FIT are external diff --git a/tools/binman/etype/intel_ifwi.py b/tools/binman/etype/intel_ifwi.py index 1a0e481c198..c2ede641aa5 100644 --- a/tools/binman/etype/intel_ifwi.py +++ b/tools/binman/etype/intel_ifwi.py @@ -37,10 +37,10 @@ class Entry_intel_ifwi(Entry_blob_ext): sub-partition (and optional entry name).
Properties for subnodes: - ifwi-subpart - sub-parition to put this entry into, e.g. "IBBP" - ifwi-entry - entry name t use, e.g. "IBBL" - ifwi-replace - if present, indicates that the item should be replaced - in the IFWI. Otherwise it is added. + - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP" + - ifwi-entry: entry name t use, e.g. "IBBL" + - ifwi-replace: if present, indicates that the item should be replaced + in the IFWI. Otherwise it is added.
See README.x86 for information about x86 binary blobs. """ diff --git a/tools/binman/etype/mkimage.py b/tools/binman/etype/mkimage.py index 8fddc881187..f8c491d5d0a 100644 --- a/tools/binman/etype/mkimage.py +++ b/tools/binman/etype/mkimage.py @@ -19,7 +19,7 @@ class Entry_mkimage(Entry): - args: Other arguments to pass
The data passed to mkimage is collected from subnodes of the mkimage node, - e.g.: + e.g.::
mkimage { args = "-n test -T imximage"; diff --git a/tools/binman/etype/section.py b/tools/binman/etype/section.py index 2f862bddf0f..cce1500b4e5 100644 --- a/tools/binman/etype/section.py +++ b/tools/binman/etype/section.py @@ -22,11 +22,13 @@ from patman.tools import ToHexSize class Entry_section(Entry): """Entry that contains other entries
- Properties / Entry arguments: (see binman README for more information) + Properties / Entry arguments: (see binman README for more information): pad-byte: Pad byte to use when padding sort-by-offset: True if entries should be sorted by offset, False if - they must be in-order in the device tree description + they must be in-order in the device tree description + end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) + skip-at-start: Number of bytes before the first entry starts. These effectively adjust the starting offset of entries. For example, if this is 16, then the first entry would start at 16. An entry diff --git a/tools/binman/etype/text.py b/tools/binman/etype/text.py index a69c2a4ec48..45dfcc401e4 100644 --- a/tools/binman/etype/text.py +++ b/tools/binman/etype/text.py @@ -25,7 +25,7 @@ class Entry_text(Entry): <text>: The text to place in the entry (overrides the above mechanism). This is useful when the text is constant.
- Example node: + Example node::
text { size = <50>; @@ -38,7 +38,7 @@ class Entry_text(Entry):
and binman will insert that string into the entry.
- It is also possible to put the string directly in the node: + It is also possible to put the string directly in the node::
text { size = <8>; @@ -46,7 +46,7 @@ class Entry_text(Entry): message = "a message directly in the node" };
- or just: + or just::
text { size = <8>; diff --git a/tools/binman/setup.py b/tools/binman/setup.py index 2dad43d4937..5ed94abdaf9 100644 --- a/tools/binman/setup.py +++ b/tools/binman/setup.py @@ -7,6 +7,6 @@ setup(name='binman', scripts=['binman'], packages=['binman', 'binman.etype'], package_dir={'binman': ''}, - package_data={'binman': ['README.rst', 'README.entries']}, + package_data={'binman': ['README.rst', 'entries.rst']}, classifiers=['Environment :: Console', 'Topic :: Software Development :: Embedded Systems'])