[util,ipgen] Improve docs, exception handling, and simplicity

Render ip description now requires an hjson.tpl file: it used to
accept a non-template one, but those have already been removed
from the repo.

Part of lowRISC#8440

Signed-off-by: Guillermo Maturana <[email protected]>

util/ipgen/README.md

@@ -1,4 +1,4 @@
-# Ipgen: Generate IP blocks from IP templates
+# Ipgen: Generate IP Blocks From IP Templates
 
 Ipgen is a tool to produce IP blocks from IP templates.
 
@@ -10,34 +10,32 @@ Ipgen is a command-line tool and a library.
 Users wishing to instantiate an IP template or query it for template parameters will find the command-line application useful.
 For use in higher-level scripting, e.g. within [topgen](../topgen/README.md) using ipgen as Python library is recommended.
 
-
 ## Anatomy of an IP template
 
 An IP template is a directory with a well-defined directory layout, which mostly mirrors the standard layout of IP blocks.
 
 An IP template directory has a well-defined structure:
 
 * The IP template name (`<templatename>`) equals the directory name.
-* The directory contains a file `data/<templatename>.tpldesc.hjson` containing all configuration information related to the template.
-* The directory also contains zero or more files ending in `.tpl`.
-  These files are Mako templates and rendered into a file in the same relative location without the `.tpl` file extension.
+* The directory contains a template description file `data/<templatename>.tpldesc.hjson` containing descriptions of the configurable parameters.
+  The "default" field of these descriptions are expected to be overriden via the actual configuration parameters.
+* The directory also contains some files ending in `.tpl`.
+  These files are Mako templates and are rendered into a file in the same relative location without the `.tpl` file extension.
 
 ### The template description file
 
 Each IP template comes with a description itself.
-This description is contained in the `data/<templatename>.tpldesc.hjson` file in the template directory.
-The file is written in Hjson.
-
-It contains a top-level dictionary, the keys of which are documented next.
+This description is contained in the hjson file `data/<templatename>.tpldesc.hjson` in the template directory.
 
-#### List of template parameters: `template_param_list`
-
-Keys within `template_param_list`:
+It contains a list of parameter objects.
+These objects are dictionaries with the following required keys:
 
 * `name` (string): Name of the template parameter.
 * `desc` (string): Human-readable description of the template parameter.
-* `type` (string): Data type of the parameter. Valid values: `int`, `str`
-* `default` (string|int|object): The default value of the parameter. The data type should match the `type` argument. As convenience, strings are converted into integers on demand (if possible).
+* `type` (string): Data type of the parameter. Valid values: `bool`, `int`, `str`, `object`.
+* `default` (bool|string|int|dict): The default value of the parameter.
+  The type of this should match the `type` argument.
+  For convenience, strings are converted into integers on demand (if possible).
 
 #### Example template description file
 
@@ -69,17 +67,22 @@ Templates are written in the [Mako templating language](https://www.makotemplate
 All template parameters are available in the rendering context.
 For example, a template parameter `src` can be used in the template as `${src}`.
 
-Furthermore, the following functions are available:
-
-* `instance_vlnv(vlnv)`: Transform a FuseSoC core name, expressed as VLNV string, into an instance-specific name.
-  The `vendor` is set to `lowrisc`, the `library` is set to `opentitan`, and the `name` is prefixed with the instance name.
-  The optional version segment is retained.
-  Use this function on the `name` of all FuseSoC cores which contain sources generated from templates and which export symbols into the global namespace.
+### VLNV support
 
-### Templating FuseSoC core files
+The `instance_vlnv` function is available to process VLNV strings, which is useful for template core files.
+A VLNV string has the form vendor:library:name[:version] where the version is optional.
+The `instance_vlnv` function is given a vlnv and outputs a transformed vlnv as follows:
 
-FuseSoC core files can be templated just like any other file.
-Especially handy is the `instance_vlnv()` template function, which transforms a placeholder VLNV (a string in the form `vendor:library:name:version`) into a instance-specific one.
+- The vendor string becomes `lowrisc`.
+- The library string becomes `opentitan`.
+- The name is processed as follows:
+  - If the `module_instance_name` parameter exists, the name must start
+    with it as a prefix, and that is replaced by the `instance_name`
+    renderer value.
+  - If the name starts with the template name, it is replaced by the
+    `instance_name` value.
+  - Otherwise the `instance_name` is pefixed to the name.
+- The optional version is preserved.
 
 For example, a `rv_plic.core.tpl` file could look like this:
 
@@ -88,13 +91,13 @@ CAPI=2:
 name: ${instance_vlnv("lowrisc:ip:rv_plic")}
 ```
 
-After processing, the `name` key is set to e.g. `lowrisc:opentitan:top_earlgrey_rv_plic`.
+After processing, the VLNV could become `lowrisc:opentitan:top_earlgrey_rv_plic`.
 
 The following rules should be applied when creating IP templates:
 
 * Template and use an instance-specific name for all FuseSoC cores which reference templated source files (e.g. SystemVerilog files).
 * Template and use an instance-specific name at least the top-level FuseSoC core.
-* If a FuseSoC core with an instance-specific name exposes a well-defined public interface (see below), add a `provides: lowrisc:ip_interfaces:<name>` line to the core file to allow other cores to refer to it without knowing the actual core name.
+* If a FuseSoC core with an instance-specific name exposes a well-defined public interface (see below), add a `virtual: lowrisc:ip_interfaces:<name>` line to the core file to allow non-instance-specific cores to refer to it without knowing the actual core name.
 
 #### Templating core files to uphold the "same name, same interface" principle
 
@@ -212,7 +215,7 @@ What is supported and required for most IP templates is the modification of the
 
 Each template may be used to generate only once IP block for each top-level design.
 The generated IP block can still be instantiated multiple times from SystemVerilog, including with different SystemVerilog parameters passed to it.
-It is not possible, however, to, for example, use one IP block template to produce two different flash controllers with different template parameters.
+However, it is not possible to use one IP block template to produce two different flash controllers with different template parameters.
 
 IP templates generally contain code which exports symbols into the global namespace of the design: names of SystemVerilog modules and packages, defines, names of FuseSoC cores, etc.
 Such names need to be unique for each design, i.e. we cannot have multiple SystemVerilog modules with the same name in one design.

util/ipgen/lib.py

@@ -72,6 +72,7 @@ def _parse_template_parameter(where: str, raw: object) -> TemplateParameter:
                          f'{", ".join(TemplateParameter.VALID_PARAM_TYPES)}.')
 
     r_default = rd.get('default')
+    param_type: Union[bool, int, str, Dict[str, Any]]
     if param_type == 'bool':
         default = check_bool(r_default, f'default field of {name}, (a boolean parameter)')
     elif param_type == 'int':
@@ -134,8 +135,8 @@ def from_template_path(cls, template_path: Path) -> 'IpTemplate':
         - The IP template name (TEMPLATE_NAME) is equal to the directory name.
         - It contains a file 'data/TEMPLATE_NAME.tpldesc.hjson' containing all
           configuration information related to the template.
-        - It contains zero or more files ending in '.tpl'. These files are
-          Mako templates and rendered into an file in the same location without
+        - It contains some files ending in '.tpl', which are Mako templates
+          and are rendered into a file in the same relative location without
           the '.tpl' file extension.
         """