[util] Instantiate DIF Checklist Too
The SW Checklist was also originally created as a Mako template. This
commit ensures it will be instantated by the `make_new_dif.py` script in
addition to the header template.
Given these changes, it seemed prudent to move the docs into the script,
and document the script in `sw/lib/device/dif/README.md`.
This introduces the `--only` flag which can be used to restrict the
templates that are instantiated, and removes the `--template` flag to
specify a singular template path.
Breaking Change: The `--output` flag now chooses a directory for the
output files, rather than a single file location.
Signed-off-by: Sam Elliott <selliott@lowrisc.org>
diff --git a/util/make_new_dif.py b/util/make_new_dif.py
index 38fb415..7f9f48f 100755
--- a/util/make_new_dif.py
+++ b/util/make_new_dif.py
@@ -3,14 +3,27 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-# make_new_dif.py is a script for quickly applying replacement operations to
-# dif_template.h.tpl. See sw/device/lib/dif/dif_template.h.tpl for more
-# information.
+# make_new_dif.py is a script for instantiating templates needed to begin
+# development on a new DIF.
#
-# The produced file may still require spell-checking and general cleaning-up.
+# To instantiate the files for a new IP named my_ip, run the command
+# $ util/make_new_dif.py --ip my_ip --peripheral "my peripheral"
+# where "my peripheral" is a documentation-friendly name for your peripheral.
+# Compare "pwrmgr" and "power manager".
+#
+# It will instantiate:
+# - `sw/device/lib/dif/dif_template.h.tpl` as the DIF Header (into dif_<ip>.h).
+# - `doc/project/sw_checklist.md.tpl` as the DIF Checklist (into dif_<ip>.md).
+#
+# See both templates for more information.
+#
+# You can also use the `--only=header` or `--only=checklist` to instantiate a
+# subset of the templates. This can be passed multiple times, and including
+# `--only=all` will instantiate every template.
+#
+# The produced files will still need some cleaning up before they can be used.
import argparse
-
from pathlib import Path
from mako.template import Template
@@ -19,10 +32,11 @@
# calls to get back to the top.
REPO_TOP = Path(__file__).resolve().parent.parent
+ALL_PARTS = ["header", "checklist"]
+
def main():
dif_dir = REPO_TOP / 'sw/device/lib/dif'
- template_file = dif_dir / 'dif_template.h.tpl'
parser = argparse.ArgumentParser()
parser.add_argument('--ip',
@@ -37,18 +51,25 @@
'--handle-param',
'-a',
default='handle',
- help='an optional name to replace the `handle` perameter name')
- parser.add_argument('--template',
- '-t',
- type=Path,
- default=template_file,
- help='where to find the header template')
+ help='an optional name to replace the `handle` parameter name')
+ parser.add_argument('--only',
+ choices=['all'] + ALL_PARTS,
+ default=[],
+ action='append',
+ help='only create some files; defaults to all.')
parser.add_argument('--output',
'-o',
type=Path,
- help='where to write the header; defaults to dif_ip.h')
+ default=dif_dir,
+ help='directory to place the output files into.')
args = parser.parse_args()
+
+ if len(args.only) == 0:
+ args.only += ['all']
+ if 'all' in args.only:
+ args.only += ALL_PARTS
+
ip_snake = args.ip
ip_camel = ''.join([word.capitalize() for word in args.ip.split('_')])
ip_upper = ip_snake.upper()
@@ -59,22 +80,47 @@
periph_upper = periph_lower[0].upper() + periph_lower[1:]
handle = args.handle_param
- with args.template.open('r') as f:
- template = Template(f.read())
+ if len(args.only) > 0:
+ args.output.mkdir(exist_ok=True)
- header = template.render(
- ip_snake=ip_snake,
- ip_camel=ip_camel,
- ip_upper=ip_upper,
- periph_lower=periph_lower,
- periph_upper=periph_upper,
- handle=handle,
- )
+ if "header" in args.only:
+ header_template_file = args.output / 'dif_template.h.tpl'
- dif_file = args.output or dif_dir / 'dif_{}.h'.format(ip_snake)
- with dif_file.open('w') as f:
- f.write(header)
- print('Template sucessfuly written to {}.'.format(str(dif_file)))
+ with header_template_file.open('r') as f:
+ header_template = Template(f.read())
+
+ header_out_file = dif_dir / 'dif_{}.h'.format(ip_snake)
+ with header_out_file.open('w') as f:
+ f.write(
+ header_template.render(
+ ip_snake=ip_snake,
+ ip_camel=ip_camel,
+ ip_upper=ip_upper,
+ periph_lower=periph_lower,
+ periph_upper=periph_upper,
+ handle=handle,
+ ))
+
+ print('DIF header successfully written to {}.'.format(
+ str(header_out_file)))
+
+ if "checklist" in args.only:
+ checklist_template_file = REPO_TOP / 'doc/project/sw_checklist.md.tpl'
+
+ with checklist_template_file.open('r') as f:
+ markdown_template = Template(f.read())
+
+ checklist_out_file = args.output / 'dif_{}.md'.format(ip_snake)
+ with checklist_out_file.open('w') as f:
+ f.write(
+ markdown_template.render(
+ ip_name=ip_snake,
+ dif_name=ip_snake,
+ display_name=periph_upper,
+ ))
+
+ print('DIF Checklist successfully written to {}.'.format(
+ str(checklist_out_file)))
if __name__ == '__main__':
