binman: Incorporate entry documentation
Update this to avoid sphinx warnings and incorporate it into the new
documentaiton tree.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/tools/binman/cmdline.py b/tools/binman/cmdline.py
index 0c0f489..95f9ba2 100644
--- a/tools/binman/cmdline.py
+++ b/tools/binman/cmdline.py
@@ -69,7 +69,7 @@
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 96%
rename from tools/binman/README.entries
rename to tools/binman/entries.rst
index 0d9105e..2d79850 100644
--- a/tools/binman/README.entries
+++ b/tools/binman/entries.rst
@@ -106,7 +106,7 @@
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 @@
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 @@
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 @@
};
};
- 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
- 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 @@
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 @@
<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 @@
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 @@
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 6cdbaa0..baf9c3e 100644
--- a/tools/binman/etype/cbfs.py
+++ b/tools/binman/etype/cbfs.py
@@ -22,7 +22,7 @@
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 @@
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 @@
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 @@
};
};
- 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 @@
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 6ca88a1..2339fee 100644
--- a/tools/binman/etype/fdtmap.py
+++ b/tools/binman/etype/fdtmap.py
@@ -53,24 +53,24 @@
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.
diff --git a/tools/binman/etype/fit.py b/tools/binman/etype/fit.py
index 1a7cbd7..c4fa711 100644
--- a/tools/binman/etype/fit.py
+++ b/tools/binman/etype/fit.py
@@ -22,7 +22,7 @@
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 @@
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 @@
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 @@
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 @@
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 1a0e481..c2ede64 100644
--- a/tools/binman/etype/intel_ifwi.py
+++ b/tools/binman/etype/intel_ifwi.py
@@ -37,10 +37,10 @@
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 8fddc88..f8c491d 100644
--- a/tools/binman/etype/mkimage.py
+++ b/tools/binman/etype/mkimage.py
@@ -19,7 +19,7 @@
- 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 2f862bd..cce1500 100644
--- a/tools/binman/etype/section.py
+++ b/tools/binman/etype/section.py
@@ -22,11 +22,13 @@
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 a69c2a4..45dfcc4 100644
--- a/tools/binman/etype/text.py
+++ b/tools/binman/etype/text.py
@@ -25,7 +25,7 @@
<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 @@
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 @@
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 2dad43d..5ed94ab 100644
--- a/tools/binman/setup.py
+++ b/tools/binman/setup.py
@@ -7,6 +7,6 @@
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'])