Top Earlgrey

Specification

The datasheet and specification of Earlgrey is located here.

Top Earlgrey is being generated by the integration tool, topgen (util/topgen.py). Please do not revise any RTL file that lives in an *autogen/ directory. This applies both to all RTL files which make up the top design (under rtl/autogen/*.sv) as well as to all the auto-generated/templated IP blocks under ip_autogen/*.

How to (re)generate the top design

The full top design, including all auto-generated IPs, dv and sw collateral, and several others, is generated through topgen.py. To (re)generate it, run the command below from the project root directory:

util/topgen.py -t hw/top_earlgrey/data/top_earlgrey.hjson -s hw/top_earlgrey/data/top_earlgrey_seed.testing.hjson

In terms of the top level design hierarchy, it generates the files below (all in rtl/autogen/):

earlgrey_pd_{main,aon}.sv: Power domain level wrappers which instantiate all IPs that belong to the respective domain, including all required connections between them
top_earlgrey.sv: “Logic” top level design, which instantiates the power domain level wrappers described above, connects them with each other and feeds any signals through that are required at chip level (see below)
chip_earlgrey_{asic,cw340,verilator}.sv: The “definitive” top (chip) level of the design; one file per target (ASIC, CW340, Verilator), with target-specific cells, port list, and connections. Instantiates the top_earlgrey module described above as well as technology and target specific modules/cells such as, e.g., clock generators or physical pad cells

Adding new blocks into top level

Modify data/top_earlgrey.hjson to include a new module in the module section.
Modify data/xbar_{main,peri}.hjson for the TileLink connectivity.
Modify the inter_module, pinmux, and targets sections in case the newly added module requires connections to/from other modules or the chip level, that are not auto- generated (i.e., anything but TileLink bus ports, interrupts, alerts, comportable IO, wakeup requests, as well as clocks and resets)

Modify configurations

Main configuration for Top Earlgrey is in data/top_earlgrey.hjson. The users need to specify the list of peripherals, memories, crossbars, and the interrupts in the configuration file. The tool then reads relevant information from the each peripheral blocks’ configuration. For instance, if uart module is used, the tool reads hw/ip/uart/data/uart{_reg}.hjson and parses the information such as input/output, the size of its register space, and interrupts.

For the memories, the tool utilizes the type and instantiates relevant modules including the converter from TL-UL interface to the native interfaces (SRAM, ROM, eFlash). The user only needs to describe the base address and the memory size.

The crossbar should be defined in the separate file. Please take a look at data/xbar_main.hjson as an example. In the top configuration, it needs to define the xbar and the clock, then the tool calls tlgen library to create the crossbar design. Please remind that the instance name in the crossbar and that in the module field should be matched for topgen to create fields that tlgen uses.

Modify the template

The “main” top templates which make up the meat of the design are templates/earlgrey_pd_main.sv.tpl and templates/earlgrey_pd_aon.sv.tpl. However, in most cases, it isn’t required to modify these template files. For instance, to add a new IP to the design, the user just needs to add the IP to the module section of data/top_earlgrey.hjson and revise the crossbar connections in the crossbar configuration (i.e., in data/xbar_{main,peri}.hjson).