[doc/rm] Crossbar Tool
Add `tlgen.py`, more generally `util/tlgen`, document to help
understanding how the crossbar is being generated in OpenTitan and its
usage.
To generate tlgen selfdoc, validate has checker logic inside. The
checking structure (control group) is slightly changed from its in
reggen. The change makes validate to run recursively and generate the
doc recursively.
This document addresses the issue #340.
diff --git a/util/tlgen/doc.py b/util/tlgen/doc.py
new file mode 100644
index 0000000..1c0bf83
--- /dev/null
+++ b/util/tlgen/doc.py
@@ -0,0 +1,94 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+"""TileLink-Uncached Lightweight Xbar self document
+"""
+import logging as log
+
+from .validate import *
+
+doc_intro = """
+
+(start of output generated by `{}`)
+
+The tables describe each key and the type of the value. The following
+types are used:
+
+Type | Description
+---- | -----------
+"""
+
+doc_tail = """
+
+(end of output generated by `{}`)
+
+"""
+
+
+def print_control(control, heading):
+ """Print a control group and its subgroup recursively
+ """
+ subgroup = [] # added if the field hit sub control group
+
+ outstr = '#' * heading + ' ' + control['name'] + '\n'
+ outstr += '\n'
+
+ outstr += control['description']
+ outstr += '\n\n'
+
+ items = {**control['required'], **control['optional'], **control['added']}
+
+ if len(items) > 0:
+ outstr += """
+Field | Kind | Type | Description
+----- | ---- | ---- | ------------
+"""
+ for k, v in items.items():
+ if k in control['required']:
+ kind = "required"
+ elif k in control['optional']:
+ kind = "optional"
+ else:
+ kind = "added by tool"
+
+ v_type = val_types[v[0]][0]
+
+ if v[0] == 'lg':
+ subgroup.append(v[1])
+ log.error(val_types[v[0]])
+ outstr += '{} | {} | {} | List of {} group\n'.format(
+ k, kind, v_type, k)
+ continue
+ elif v[0] == 'g':
+ if not isinstance(v[1], str):
+ subgroup.append(v[1])
+ outstr += '{} | {} | {} | {} group\n'.format(
+ k, kind, v_type, k)
+ continue
+
+ # Generic string print
+ outstr += '{} | {} | {} | {}\n'.format(k, kind, v_type, v[1])
+
+ outstr += "\n\n"
+ # recursive subgroup
+ for e in subgroup:
+ outstr += print_control(e, heading)
+
+ return outstr
+
+
+def selfdoc(heading, cmd=""):
+ # heading : markdown header depth
+ # value type
+ outstr = doc_intro.format(cmd)
+
+ for k, v in val_types.items():
+ outstr += v[0] + " | " + v[1] + "\n"
+
+ # root + subgroup
+ outstr += print_control(root, heading)
+
+ # connections: Needs custom as the key are hosts (can vary)
+ outstr += doc_tail.format(cmd)
+
+ return outstr
