[PATCH 14/49] dtoc: Add a header comment to each generated file

[Simon Glass]

It is currently fairly obvious what the two generated files are for, but
this will change as more are added. It is helpful for readers to describe
the purpose of each file.

Add a header commment field to OutputFile and use it to generate a comment
at the top of each file.

Signed-off-by: Simon Glass <sjg at chromium.org>
---

 tools/dtoc/dtb_platdata.py | 30 ++++++++++++++++++++----------
 tools/dtoc/test_dtoc.py    |  6 ++++--
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/tools/dtoc/dtb_platdata.py b/tools/dtoc/dtb_platdata.py
index e12aaa5399f..b3d777e0c5e 100644
--- a/tools/dtoc/dtb_platdata.py
+++ b/tools/dtoc/dtb_platdata.py
@@ -56,8 +56,10 @@ class Ftype(IntEnum):
 
 # This holds information about each type of output file dtoc can create
 # type: Type of file (Ftype)
-# fname: Filename excluding directory, e.g. 'dt-platdata.c'
-OutputFile = collections.namedtuple('OutputFile', ['ftype', 'fname'])
+# fname: Filename excluding directory, e.g. 'dt-plat.c'
+# hdr_comment: Comment explaining the purpose of the file
+OutputFile = collections.namedtuple('OutputFile',
+                                    ['ftype', 'fname', 'hdr_comment'])
 
 # This holds information about a property which includes phandles.
 #
@@ -331,15 +333,20 @@ class DtbPlatdata():
         self._lines = []
         return lines
 
-    def out_header(self):
-        """Output a message indicating that this is an auto-generated file"""
+    def out_header(self, outfile):
+        """Output a message indicating that this is an auto-generated file
+
+        Args:
+            outfile: OutputFile describing the file being generated
+        """
         self.out('''/*
  * DO NOT MODIFY
  *
- * This file was generated by dtoc from a .dtb (device tree binary) file.
+ * %s.
+ * This was generated by dtoc from a .dtb (device tree binary) file.
  */
 
-''')
+''' % outfile.hdr_comment)
 
     def get_phandle_argc(self, prop, node_name):
         """Check if a node contains phandles
@@ -646,7 +653,6 @@ class DtbPlatdata():
                     value: Prop object with field information
 
         """
-        self.out_header()
         self.out('#include <stdbool.h>\n')
         self.out('#include <linux/libfdt.h>\n')
 
@@ -789,7 +795,6 @@ class DtbPlatdata():
         See the documentation in doc/driver-model/of-plat.rst for more
         information.
         """
-        self.out_header()
         self.out('/* Allow use of U_BOOT_DRVINFO() in this file */\n')
         self.out('#define DT_PLATDATA_C\n')
         self.out('\n')
@@ -823,8 +828,12 @@ class DtbPlatdata():
 # key: Command used to generate this file
 # value: OutputFile for this command
 OUTPUT_FILES = {
-    'struct': OutputFile(Ftype.HEADER, 'dt-structs-gen.h'),
-    'platdata': OutputFile(Ftype.SOURCE, 'dt-platdata.c'),
+    'struct':
+        OutputFile(Ftype.HEADER, 'dt-structs-gen.h',
+                   'Defines the structs used to hold devicetree data'),
+    'platdata':
+        OutputFile(Ftype.SOURCE, 'dt-platdata.c',
+                   'Declares the U_BOOT_DRIVER() records and platform data'),
     }
 
 
@@ -872,6 +881,7 @@ def run_steps(args, dtb_file, include_disabled, output, output_dirs,
                              (cmd, ', '.join(sorted(OUTPUT_FILES.keys()))))
         plat.setup_output(outfile.ftype,
                           outfile.fname if output_dirs else output)
+        plat.out_header(outfile)
         if cmd == 'struct':
             plat.generate_structs(structs)
         elif cmd == 'platdata':
diff --git a/tools/dtoc/test_dtoc.py b/tools/dtoc/test_dtoc.py
index dbd4e3bf1d4..2e4dd2b24d2 100755
--- a/tools/dtoc/test_dtoc.py
+++ b/tools/dtoc/test_dtoc.py
@@ -32,7 +32,8 @@ OUR_PATH = os.path.dirname(os.path.realpath(__file__))
 HEADER = '''/*
  * DO NOT MODIFY
  *
- * This file was generated by dtoc from a .dtb (device tree binary) file.
+ * Defines the structs used to hold devicetree data.
+ * This was generated by dtoc from a .dtb (device tree binary) file.
  */
 
 #include <stdbool.h>
@@ -41,7 +42,8 @@ HEADER = '''/*
 C_HEADER = '''/*
  * DO NOT MODIFY
  *
- * This file was generated by dtoc from a .dtb (device tree binary) file.
+ * Declares the U_BOOT_DRIVER() records and platform data.
+ * This was generated by dtoc from a .dtb (device tree binary) file.
  */
 
 /* Allow use of U_BOOT_DRVINFO() in this file */
-- 
2.29.2.729.g45daf8777d-goog