| # 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. |