[doc] Are there docs for the defines?

[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

• to use FPGA/Verilator external clock

PRIM_DEFAULT_IMPL

• Specifies primitives implementation based on technology:
• prim_pkg::ImplGeneric (default)
• prim_pkg::ImplXilinx
• prim_pkg::ImplXilinx_ultrascale

SYNTHESIS

• skips simulation specific code

VCS

• when using VCS tool

XCELIUM

• when using XCELIUM tool

VERILATOR

• when using Verilator tool

ANALOGSIM

• when defined AST_2_PAD Analog Output Signals are defined as output real instead of output wire

BUS_AIW, BUS_AUW, BUS_AW, BUS_DBW, BUS_DIW, BUS_DUW, BUS_DW, BUS_SZW

• overwrites sizes defined in top_pkg

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

[hcallahan-lowrisc]

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
			#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.	#2954
		Note. 32-bit TL-UL is the primary chip-level interconnect, which come from hw/top_earlgrey/rtl/top_pkg.sv	#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.	#7338
			opentitan/hw/ip/rom_ctrl/rtl/rom_ctrl.sv Lines 18 to 21 in aad711e // Disable all (de)scrambling operation. This disables both the scrambling block and the boot-time // checker. Don't use this in a real chip, but it's handy for small FPGA targets where we don't // want to spend area on unused scrambling. parameter bit SecDisableScrambling = 1'b0
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).	opentitan/hw/ip/prim_generic/rtl/prim_generic_ram_1r1w.sv Lines 34 to 42 in aad711e // For certain synthesis experiments we compile the design with generic models to get an unmapped // netlist (GTECH). In these synthesis experiments, we typically black-box the memory models 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. To this end, we exclude the entire logic in this module in // these runs with the following macro. `ifndef SYNTHESIS_MEMORY_BLACK_BOXING
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 :

opentitan/hw/top_earlgrey/dv/verilator/chip_sim.core

Line 84 in 3ede419

- PRIM_DEFAULT_IMPL=prim_pkg::ImplGeneric

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]

Wow, hey thanks! This is great! I'll need to go through it and ask you some questions. Would it work better if I created a doc and then shared it with you, so you just need to review/approve? That'd save you work, and then you can use it in your released docs. Erik Sent with [Proton Mail](https://proton.me/) secure email.

…

On Wednesday, July 17th, 2024 at 3:39 AM, Harry Callahan ***@***.***> wrote: Hey ***@***.***(https://github.com/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 [#1679](#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. [#2954](#2954) Note. 32-bit TL-UL is the primary chip-level interconnect, which come from hw/top_earlgrey/rtl/top_pkg.sv [#2948](#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. [#7338](#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 seting 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](https://opentitan.org/book/doc/getting_started/setup_verilator.html#use-bazel-to-run-software-on-a-verilator-simulation.) for some more details about one example. — Reply to this email directly, [view it on GitHub](#23904 (comment)), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/BDGSQOIVYGRDVDPSUK5S3VLZMZCVTAVCNFSM6AAAAABKJ2MZUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMZSHE4TENBWGQ). You are receiving this because you were mentioned.Message ID: ***@***.***>