[doc,design] Mention the need to run cmdgen

When generating top and top-dependent IPs it is necessary to run cmdgen. Add a mention of this in doc/contributing/doc/README.md and doc/contributing/hw/design.md. Signed-off-by: Guillermo Maturana <[email protected]>
lowRISC · Dec 4, 2024 · d5fb029 · d5fb029
1 parent 020beeb
commit d5fb029
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 3 deletions.
diff --git a/doc/contributing/doc/README.md b/doc/contributing/doc/README.md
@@ -33,7 +33,7 @@ Commonly one will run the following, which will go through every markdown file i
 ./util/cmdgen.py -u '**/*.md'
 ```
 
-If run, the following snippet will have the register tables of the AES block (output by `util/regtool.py -d ./hw/ip/aes/data/aes.hjson`) inserted into it.
+For example, when cmdgen is run with the '-u' flag, the following snippet will result in the insertion of the AES register tables between the BEGIN and END lines.
 
 ````md
 # Registers
@@ -46,7 +46,11 @@ If run, the following snippet will have the register tables of the AES block (ou
 *Note, one should remove the `#` before the commands.
 This is there so that `CMDGEN` doesn't generate registers in this file.*
 
-The `CMDGEN` tool can also be invoked by the `./hw/Makefile` using the target `cmdgen`.
+The `CMDGEN` tool can also be invoked by the `./hw/Makefile` using the target `cmdgen`, from the top of the repo
+
+```sh
+make -C hw cmdgen
+```
 
 [mdBook]: https://rust-lang.github.io/mdBook/
 [rustdoc]: https://doc.rust-lang.org/rustdoc/index.html
diff --git a/doc/contributing/hw/design.md b/doc/contributing/hw/design.md
@@ -107,9 +107,24 @@ The sections below show how to do items 2-4.
 $ make -C hw top
 ```
 
-After you revise the IP `.hjson`, IP top module, IP register interface, and DV testbench `tb.sv`, you can re-generate top-levels with the command above.
+After you revise the IP `.hjson`, IP top module, IP register interface, and DV testbench `tb.sv`, you can re-generate top-levels and some top-dependent IPs with the commands above.
 This reads the `.hjson` file and updates the interrupt signal and re-generates the PLIC module if needed.
 
+### Update MD Files
+
+Some `*.md` files generate contents using the `util/cmdgen.py` tool described at [CMDGEN](../doc/README.md##cmdgen).
+These files are generated using cmdgen via make.
+
+```console
+$ make -C hw cmdgen
+```
+
+Generating both top and cmdgen can be done conveniently with
+
+```console
+$ make -C hw top_and_cmdgen
+```
+
 ### New DIF
 
 Unfortunately, re-generating TOP does not resolve everything.