From 7ae5f315b34454d1a993e7e96e94d26da6e28e6c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 1 Jun 2018 09:38:19 -0600 Subject: [PATCH] binman: Tidy up some docs and comments Fix a few missing comments and tidy up some existing ones. Signed-off-by: Simon Glass --- tools/binman/README | 6 +++--- tools/binman/ftest.py | 29 +++++++++++++++++++---------- tools/binman/image.py | 5 +++++ 3 files changed, 27 insertions(+), 13 deletions(-) diff --git a/tools/binman/README b/tools/binman/README index 32d89194dd..f3a979e217 100644 --- a/tools/binman/README +++ b/tools/binman/README @@ -409,8 +409,8 @@ of these, and place binaries in them independently. The image is still produced 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 @@ Binman takes a lot of inspiration from a Chrome OS tool called 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 06b8132f01..9e12df5d79 100644 --- a/tools/binman/ftest.py +++ b/tools/binman/ftest.py @@ -150,7 +150,8 @@ class TestFunctional(unittest.TestCase): """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 @@ class TestFunctional(unittest.TestCase): 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 @@ class TestFunctional(unittest.TestCase): 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 @@ class TestFunctional(unittest.TestCase): 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 @@ class TestFunctional(unittest.TestCase): 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 @@ class TestFunctional(unittest.TestCase): 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 @@ class TestFunctional(unittest.TestCase): '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 1d234965fa..74bc46fd30 100644 --- a/tools/binman/image.py +++ b/tools/binman/image.py @@ -30,6 +30,11 @@ class Image: _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 -- 2.25.1