hcallahan-lowrisc
commented
1 month ago Hey @lmg260a,
I put together an incomplete list of the macro defines we use in the project. There are probably a lot more, for things like include-guards etc.
This isn't really a table of all the use-cases, as that would be pretty complex! But it's a start, maybe I can explain some more things from here.
| ident | origin | meaning/use | link(s) |
|---|---|---|---|
| SYNTHESIS | Include/Exclude code specifically related to synthesis targets | ||
| FPGA_XILINX | Include/Exclude code specifically related to synthesis for Xilinx FPGAs | ||
| ANALOGSIM | Include/Exclude code specifically related to Analog Simulations | ||
| FORMAL | Ibex | Include/Exclude code specifically related to FPV | |
| YOSYS | Ibex | Include/Exclude code specifically related to Yosys flow | |
| PRIM_DEFAULT_IMPL | Defines the default technology-dependent realizations of abstract primitives | https://opentitan.org/book/hw/ip/prim/index.html#abstract-primitives | |
| https://github.com/lowRISC/opentitan/pull/1679 | |||
| VCS | Include/Exclude code for Synopsys VCS compatability | ||
| XCELIUM | Include/Exclude code for Cadence XCELIUM compatability | ||
| VERILATOR | Include/Exclude code for Verilator compatability | ||
| BUS_* | Allow overriding bus vector widths, used primarily to specialize the generic code for OpenTitan TL-UL. | https://github.com/lowRISC/opentitan/pull/2954 | |
Note. 32-bit TL-UL is the primary chip-level interconnect, which come from hw/top_earlgrey/rtl/top_pkg.sv |
https://github.com/lowRISC/opentitan/issues/2948 | ||
| CHECK_MISALIGNED | Ibex | (unused) Gates an assertion that there are no misaligned accesses | |
| DISABLE_ROM_INTEGRITY_CHECK | Chip-level define that can be used to remove the rom-scrambling feature for development/testing. | https://github.com/lowRISC/opentitan/pull/7338 | |
| https://github.com/lowRISC/opentitan/blob/aad711e1bc33a541503e9a7a5e006ec87bd7602b/hw/ip/rom_ctrl/rtl/rom_ctrl.sv#L18-L21 | |||
| IBEX_CUSTOM_PMP_RESET_VALUES | Ibex | Can be used to customize the reset state for the Ibex PMP system. | |
| RISCV_FORMAL | Ibex | Include/Exclude code for Ibex Verification using the RISC-V Formal Interface (RVFI) | https://ibex-core.readthedocs.io/en/latest/03_reference/rvfi.html |
| RV_CORE_IBEX_SIM_SRAM | Disconnect the TL data output of rv_core_ibex so that we can attach the simulation SRAM. | https://opentitan.org/book/hw/dv/sv/sim_sram/index.html | |
| UVM | Include/Exclude code specifically related to UVM Functional Simulations | ||
| SYNTHESIS_MEMORY_BLACK_BOXING | Black-boxes the 1p and 2p memory models (used for GTECH runs only). | https://github.com/lowRISC/opentitan/blob/aad711e1bc33a541503e9a7a5e006ec87bd7602b/hw/ip/prim_generic/rtl/prim_generic_ram_1r1w.sv#L34-L42 | |
| DV_FCOV_DISABLE | Used to exclude RTL that is only used to support the gathering of functional coverage. | ||
| FPV_ALERT_NO_SIGINT_ERR | Include/Exclude assertions that reject signal integrity errors in differential signalling schemes for alerts. | ||
| FPV_ON | Include/Exclude code specifically related to FPV | ||
| FPV_SEC_CM_ON | (unused) | ||
| GATE_LEVEL | Include/Exclude code specifically related to Gate-Level Simulation | ||
| PATTERN | (unused) | ||
| PRIM_ASSERT_SV | include-guard for some dv macros (hw/ip/prim/rtl/prim_assert.sv) used in the primatives library |
||
| PRIM_FLOP_MACROS_SV | include-guard for some flop macros (hw/ip/prim/rtl/prim_flop_macros.sv) used in the primatives library |
||
| AST_BYPASS_CLK | Bypass the Analog-Sensor-Top (AST) clock generation features to used a fixed FPGA / simulation clock input. | https://opentitan.org/book/hw/top_earlgrey/doc/design/index.html#clocking-and-reset | |
| __AST_PKG_SV | include-guard for ast_pkg.sv |
||
| __AST_BHV_PKG_SV | include-guard for ast_bhv_pkg.sv |
However, most of these you shouldn't have to manage yourself, as our project tooling (bazel/fusesoc) is responsible for configuring these values for the different types of flows we use.
For example, when using fusesoc to invoke a verilator chip sim, fusesoc will manage setting the parameters for you. See the following example :
https://github.com/lowRISC/opentitan/blob/3ede419497ee6f741c12c0fc1e6ca948a2a895e9/hw/top_earlgrey/dv/verilator/chip_sim.core#L84
OpenTitan has a ton of automation in it's build systems, which is really powerful, but absolutely can make it difficult to follow how all the flows stick together. For the verilator example, the simulation should be invoked using something like this : bazel test --test_output=streamed //sw/device/tests:uart_smoketest_sim_verilator. Also see this for some more details about one example.
lmg260a
Description
There doesn't appear to be any documentation of the various defines. This is what I've been able to reverse-engineer.
Could you please review & correct where wrong, and please tell me the use of the ones I couldn't figure out? Ideally, I'd like to see a table of use-cases, and the defines to use. Like: Xilinx synthesis: SYNTHESIS, FPGA_SYNTHESIS Lint: Property checking:
AST_BYPASS_CLK
PRIM_DEFAULT_IMPL
SYNTHESIS
VCS
XCELIUM
VERILATOR
ANALOGSIM
BUS_AIW, BUS_AUW, BUS_AW, BUS_DBW, BUS_DIW, BUS_DUW, BUS_DW, BUS_SZW
CHECK_MISALIGNED enables Assertion for misaligned memory access
DISABLE_ROM_INTEGRITY_CHECK Randomize the ROM image with valid ECC and digest. Subclasses that have an actual ROM image will load a "real" ROM image later. If the ROM integrity check is disabled, no digest needs to be calculated and we can just randomize the memory.
FORMAL, YOSYS used for Yosys-based formal flow to handle some limitations associated with it like missing support for passing unpacked arrays as ports note that: Yosys is a framework for RTL synthesis and is used in openTitan to formally verify the OTBN core using the tool Alma: Execution-aware Masking Verification. further details at: Formal Masking Verification Using Alma - OpenTitan Documentation
FPGA_XILINX for running on xilinx fpga IBEX_CUSTOM_PMP_RESET_VALUES to use custom pmp reset values from ibex_pmp_reset.svh file instead of ibex_pmp_reset_default.svh (these includes are in ibex_cs_registers.sv) RISCV_FORMAL, RV_CORE_IBEX_SIM_SRAM usage not clear but most probably used with verilator
UVM when using uvm SYNTHESIS_MEMORY_BLACK_BOXING Used for certain synthesis experiments in openTitan as follows: compile the design with generic models to get an unmapped netlist (GTECH). In these synthesis experiments, the memory models are black-boxed since these are going to be simulated using plain RTL models in netlist simulations. This can be done by analyzing and elaborating the design, and then removing the memory submodules before writing out the verilog netlist. However, memory arrays can take a long time to elaborate, and in case of two port rams they can even trigger elab errors due to multiple processes writing to the same memory variable concurrently. Accordingly, the logic is excluded using this macro Other defines with still unknown functionality: DMIDirectTAP
DV_FCOV_DISABLE
FPV_ALERT_NO_SIGINT_ERR
FPV_ON
FPV_SEC_CM_ON
GATE_LEVEL
PATTERN
PRIM_ASSERT_SV
PRIM_FLOP_MACROS_SV
__AST_BHV_PKG_SV
__AST_PKG_SV