[util] Fix docstrings and arg names in `util/make_new_dif.py`.
As part of an effort to clean up the `util/make_new_dif.py`
documentation, as described in #8142, this commit makes the docstrings
and command line argument names more descriptive.
Signed-off-by: Timothy Trippel <ttrippel@google.com>
diff --git a/util/make_new_dif.py b/util/make_new_dif.py
index d626c85..7d06753 100755
--- a/util/make_new_dif.py
+++ b/util/make_new_dif.py
@@ -5,16 +5,24 @@
"""make_new_dif.py is a script for instantiating templates needed to begin
development on a new DIF.
-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".
+To instantiate the files for a new IP named ip_ctrl, run the command:
+
+$ util/make_new_dif.py --ip-name-snake "ip_ctrl" --ip-name-long "IP Controller"
+
+where "IP Controller" is a documentation-friendly name for the IP.
+For example, compare "pwrmgr" and "Power Manager".
It will instantiate:
-- `sw/device/lib/dif/dif_template.h.tpl` as the DIF Header (into dif_<ip>.h).
+- `sw/device/lib/dif/dif_template.h.tpl` as the DIF Header boilerplate
+ (into `dif_<ip>.h`), which should be manually edited/enhanced.
- `sw/device/lib/dif/templates/dif_autogen.h.tpl` as the autogenerated DIF
- Header (into dif_<ip>_autogen.h).
-- `doc/project/sw_checklist.md.tpl` as the DIF Checklist (into dif_<ip>.md).
+ Header (into `dif_<ip>_autogen.h`).
+- `sw/device/lib/dif/templates/dif_autogen.c.tpl` as the autogenerated DIF
+ implementation (into `dif_<ip>_autogen.c`).
+- `sw/device/lib/dif/templates/dif_autogen_unittest.cc.tpl` as the
+ autogenerated DIF unit tests (into `dif_<ip>_autogen_unittest.cc`).
+- `doc/project/sw_checklist.md.tpl` as the DIF Checklist (into dif_<ip>.md),
+ which should be manually edited.
See both templates for more information.
@@ -53,15 +61,16 @@
parser.add_argument(
"--mode",
"-m",
- choices=["single", "batch"],
- default="single",
+ choices=["new", "regen"],
+ default="new",
required=True,
- help="mode to generate DIF code; use 'single' if no DIF code exists.")
- parser.add_argument("--ip",
+ help="mode to generate DIF code. Use 'new' if no DIF code exists."
+ "Use 'rege' to regenerate all auto-generated DIFs for all IPs.")
+ parser.add_argument("--ip-name-snake",
"-i",
help="the short name of the IP, in snake_case.")
- parser.add_argument("--peripheral",
- "-p",
+ parser.add_argument("--ip-name-long",
+ "-l",
help="the documentation-friendly name of the IP.")
parser.add_argument("--only",
choices=ALL_PARTS,
@@ -73,12 +82,12 @@
# Parse CMD line args.
ips = []
- # Check for batch generation mode (used in CI check:
- # ci/scripts/check-generated.sh")
- if args.mode == "batch":
+ # Check for regeneration mode (used in CI check:
+ # ci/scripts/check-generated.sh)
+ if args.mode == "regen":
if len(args.only) != 1 or args.only[0] != "autogen":
raise RuntimeError(
- "can only batch generate completely auto-generated code.")
+ "can only regenerate DIF code that is auto-generated.")
# Create list of IPs to re-generate DIF code for.
for autogen_src_filename in glob.iglob(
str(REPO_TOP / "sw/device/lib/dif/autogen/*.c")):
@@ -87,12 +96,11 @@
# case snake mode (i.e., uart).
ip_name_snake = Path(autogen_src_filename).stem[4:-8]
# NOTE: ip.name_long_* not needed for auto-generated files which
- # are the only files (re-)generated in batch mode.
+ # are the only files (re-)generated in regen mode.
ips.append(Ip(ip_name_snake, "AUTOGEN"))
else:
- assert (
- args.ip and args.peripheral and
- "ERROR: must pass --ip and --peripheral options in 'single' mode.")
+ assert args.ip_name_snake and args.ip_name_long, \
+ "ERROR: pass --ip-name-snake and --ip-name-long when --mode=new."
ips.append(Ip(args.ip, args.peripheral))
# Default to generating all parts.
