binman: Tidy up some docs and comments
Fix a few missing comments and tidy up some existing ones.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/tools/binman/README b/tools/binman/README
index 32d8919..f3a979e 100644
--- a/tools/binman/README
+++ b/tools/binman/README
@@ -409,8 +409,8 @@
as a single output file.
This feature provides a way of creating hierarchical images. For example here
-is an example with two copies of U-Boot. One is read-only (ro), intended to be
-written only in the factory. Another is read-write (rw), so that it can be
+is an example image with two copies of U-Boot. One is read-only (ro), intended
+to be written only in the factory. Another is read-write (rw), so that it can be
upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
and can be programmed:
@@ -597,7 +597,7 @@
a reasonably simple and sound design but has expanded greatly over the
years. In particular its handling of x86 images is convoluted.
-Quite a few lessons have been learned which are hopefully be applied here.
+Quite a few lessons have been learned which are hopefully applied here.
Design notes
diff --git a/tools/binman/ftest.py b/tools/binman/ftest.py
index 06b8132..9e12df5 100644
--- a/tools/binman/ftest.py
+++ b/tools/binman/ftest.py
@@ -150,7 +150,8 @@
"""Run binman with a given test file
Args:
- fname: Device tree source filename to use (e.g. 05_simple.dts)
+ fname: Device-tree source filename to use (e.g. 05_simple.dts)
+ debug: True to enable debugging output
"""
args = ['-p', '-I', self._indir, '-d', self.TestFile(fname)]
if debug:
@@ -165,10 +166,10 @@
Args:
fname: Filename of .dts file to read
- outfile: Output filename for compiled device tree binary
+ outfile: Output filename for compiled device-tree binary
Returns:
- Contents of device tree binary
+ Contents of device-tree binary
"""
if not self._output_setup:
tools.PrepareOutputDir(self._indir, True)
@@ -189,7 +190,7 @@
Raises an assertion failure if binman returns a non-zero exit code.
Args:
- fname: Device tree source filename to use (e.g. 05_simple.dts)
+ fname: Device-tree source filename to use (e.g. 05_simple.dts)
use_real_dtb: True to use the test file as the contents of
the u-boot-dtb entry. Normally this is not needed and the
test contents (the U_BOOT_DTB_DATA string) can be used.
@@ -221,7 +222,15 @@
TestFunctional._MakeInputFile('u-boot.dtb', U_BOOT_DTB_DATA)
def _DoReadFile(self, fname, use_real_dtb=False):
- """Helper function which discards the device-tree binary"""
+ """Helper function which discards the device-tree binary
+
+ Args:
+ fname: Device-tree source filename to use (e.g. 05_simple.dts)
+ use_real_dtb: True to use the test file as the contents of
+ the u-boot-dtb entry. Normally this is not needed and the
+ test contents (the U_BOOT_DTB_DATA string) can be used.
+ But in some test we need the real contents.
+ """
return self._DoReadFileDtb(fname, use_real_dtb)[0]
@classmethod
@@ -270,13 +279,13 @@
pos += entry.size
def GetFdtLen(self, dtb):
- """Get the totalsize field from a device tree binary
+ """Get the totalsize field from a device-tree binary
Args:
- dtb: Device tree binary contents
+ dtb: Device-tree binary contents
Returns:
- Total size of device tree binary, from the header
+ Total size of device-tree binary, from the header
"""
return struct.unpack('>L', dtb[4:8])[0]
@@ -326,7 +335,7 @@
str(e.exception))
def testMissingDt(self):
- """Test that an invalid device tree file generates an error"""
+ """Test that an invalid device-tree file generates an error"""
with self.assertRaises(Exception) as e:
self._RunBinman('-d', 'missing_file')
# We get one error from libfdt, and a different one from fdtget.
@@ -334,7 +343,7 @@
'No such file or directory'], str(e.exception))
def testBrokenDt(self):
- """Test that an invalid device tree source file generates an error
+ """Test that an invalid device-tree source file generates an error
Since this is a source file it should be compiled and the error
will come from the device-tree compiler (dtc).
diff --git a/tools/binman/image.py b/tools/binman/image.py
index 1d23496..74bc46f 100644
--- a/tools/binman/image.py
+++ b/tools/binman/image.py
@@ -30,6 +30,11 @@
_size: Image size in bytes, or None if not known yet
_filename: Output filename for image
_sections: Sections present in this image (may be one or more)
+
+ Args:
+ test: True if this is being called from a test of Images. This this case
+ there is no device tree defining the structure of the section, so
+ we create a section manually.
"""
def __init__(self, name, node, test=False):
self._node = node