blob: d1bf259b0df4cf2b95da06c2f7e6a78e7840ae03 [file] [log] [blame] [view]
# Top Matcha
## Specification
The specification of Matcha is located [here](./doc/specification.md).
<!-- TODO: Add ./doc folder and specification documents -->
## Tool: TopGen_Matcha
Note: The topgen_matcha tool, which is leveraged from the OpenTitan project
with some modifications, is used to generate Top_Matcha.
Please do not revise the following auto-generated files, which are included
in the repository for browsing purposes:
- rtl/autogen/top_matcha.sv
- crossbar modules
- interrupt controller
### How to create top module
Top module `rtl/autogen/top_matcha.sv` is created by above `topgen_matcha.py`.
Current top module is created with below command.
```console
../../m matcha_hw_generate_all
```
or you call the script directly, such as:
```console
../../util/topgen_matcha.py -t data/top_matcha.hjson -o . -v
```
It generates the files below:
- `rtl/autogen/top_matcha.sv` and `rtl/autogen/chip_matcha_[asic|nexus].sv`:
Top module generated from the template
`../../util/topgen_matacha/templates/*.sv.tpl` with the configuration files
`data/top_matcha.hjson` and `data/xbar_*.hjson`.
- `ip/xbar_*/rtl/xbar_*.sv`:
Crossbar module. Currently, Matcha has four crossbars: main, peri, smc, and dbg.
`tlgen' library is used to generate these files.
- `ip_autogen/rv_plic/rtl/rv_plic*.sv`:
Interrupt controller module for Security core.
- `ip_autogen/rv_plic_smc/rtl/rv_plic_smc*.sv`:
Interrupt controller module for SMC core.
### Adding new blocks into top level
Modify `data/top_matcha.hjson` to include new modules
- If the new block has interrupts, also add to the `interrupt_module` definition.
Modify the crossbar `xbar_*.hjson` for the host / device connectivity.
### Modify configurations
Main configuration for Top_Matcha is in `data/top_matcha.hjson`. Users must specify
the list of peripherals, memories, crossbars, and interrupts in the configuration
file. The tool then reads relevant information from the configuration of each
peripheral block. For example, if the `dma` module is used, the tool reads
`hw/matcha/hw/top_matcha/ip/dma/data/dma.hjson` and parses information such as
input/output, the size of its register space, and interrupts.
The peripherals can be instantiated by `module` which is defined with multiple parameters.
Among them, there are two parameters is explained below:
The fist one is "intr_to". Because Top_Matcha has two RISC-V cores (`sec` and `smc`)
and each has its own interrupt controller (PLIC), new peripherals whose interrupts need
to be sent to the `smc` core instead of the default SEC core must add a parameter called
`intr_to` to the module definition section.
Another parameter is "attr" which define types of modules supported:
// normal(default): Normal, non-templated modules that will be instantiated
// templated: These modules are templated and must be run through topgen
// ipgen: These modules are the same as templated but use the new ipgen flow
// reggen_top: These modules are not templated, but need to have reggen run
// because they live exclusively in hw/top_* instead of hw/ip_*.
// These modules are also instantiated in the top level.
// reggen_only: Similar to reggen_top, but are not instantiated in the top level.
Please see "top_matcha.hjson" for examples usages of both `attr` and `intr_to`.
For memories, the tool uses the `type` to instantiate relevant modules, including
the converter from the TL-UL interface to the native interfaces (SRAM, ROM, eFlash).
Users only need to specify the base address and the memory size.
Crossbars should be defined in separate files. See data/xbar_main.hjson for an
example. In the top configuration, users must define the crossbar and the clock.
The tool then calls the tlgen library to create the crossbar design. Note that
the instance name in the crossbar must match the instance name in the module
field for topgen to create fields that tlgen uses.
### Modify the template
Main top template file is `../../util/topgen_matcha/tempaltes/toplevel.sv.tpl`.
In most cases, it is not required to modify the template file. For example, to
add a new IP into the top, the user only needs to add the IP to the `module`
field and revise the crossbar connections in the crossbar configuration.
There may be some cases where the template needs to be revised. Currently, a few
modules are hard-coded, such as RISC-V core and the debug module. If any of these
modules need to be revised or if any new modules do not match the
comportability spec, they must be manually instantiated in the template file.