commit 6211349dbe2bde6626b19a4c44ed4f1c4d8a6896
author Andreas Kurth <adk@lowrisc.org> Mon Feb 13 14:50:22 2023 +0100
committer Andreas Kurth <github@akurth.net> Tue Feb 21 14:39:12 2023 +0100
tree a9e2ba90e8db11da8d9b5d0fb30b901ac5a919d2
parent 3638f4d6b9b6dff9e19f9ec055245419b4dd6413

[hw,doc] Add human-readable name to all blocks

This commit adds a human-readable name to every hardware block under
`hw/ip` that has a `data/<name>.hjson` file except `trial1`.

This name is intended for use in titles and sentences of documentation.
Each name was thus chosen such that it:
1. is unique among the names of all hardware blocks in OpenTitan (e.g.,
   'SPI' alone is not sufficient when there is an SPI device and an SPI
   host and those are two different blocks);
2. is sufficient for referring to the hardware block without requiring a
   companion word (e.g., 'OpenTitan Big Number' does not work because it
   cannot be used in a sentence without a companion word: "[...] can be
   used on the OpenTitan Big Number [accelerator/hardware block/IP?]" --
   we want to avoid this ambiguity);
3. is concrete rather than abstract, because the name identifies a
   concrete hardware block which implements a specification and it does
   not identify the specification in general (e.g., 'AES' alone is not
   suitable because it identifies an algorithm/specification);
4. is close to the name of the module in code, which is the value of the
   `name` field (e.g., 'ADC Controller' is closer to `adc_ctrl` than
   'ADC Control Interface');
5. contains acronyms only if we expect those acronyms to be widely known
   in the industry (e.g., AES, I2C, SPI, or UART, but not CSRNG or EDN),
   because readers who are not familiar with this project should be able
   to get an idea of a hardware block from its name (also see footnote
   1).

This commit also updates the one-line and one-paragraph descriptions of
a hardware block to align them with the name (also see footnote 2).  We
capitalize the name in sentences exactly as in the `human_name` field to
emphasize that it is not just a noun but the name of a specific hardware
block.  As such, we use the name without articles (neither definite
'the' nor indefinite 'a'/'an') and without companion words (e.g.,
'hardware block' or 'IP').  (If it helps you, imagine the hardware block
that you're referring to as a person.)

For blocks that have their `.hjson` generated from a template
(`.hjson.tpl`), this commit updates the template and the generated
`.hjson`.  This commit also updates the `.hjson`s of the
top-level-specific blocks.

The new field that contains the human-readable name, `human_name`, is
added to `util/reggen` as optional.

Footnotes:
1. In the future, we may add a separate, optional field that defines an
   acronym that can be used to identify to a hardware block in contexts
   where readers are already somewhat familiar with the block.
2. Updating *all* documents to uniformly use the agreed names is out of
   scope of this commit, but we strongly encourage using them as
   described above in all new text.  We expect we'll update existing
   documents over time.

Signed-off-by: Andreas Kurth <adk@lowrisc.org>