Core Integration

The main module is named ibex_top and can be found in ibex_top.sv. Note that the core logic is split-out from the register file and RAMs under ibex_top. This is to facilitate a dual-core lockstep implementation (see Security Features).

Register File

Ibex comes with three different register file implementations that can be selected using the enumerated parameter RegFile defined in rtl/ibex_pkg.sv. Depending on the target technology, either the flip-flop-based (“ibex_pkg::RegFileFF”, default), the latch-based (“ibex_pkg::RegFileLatch”) or an FPGA-targeted (“ibex_pkg::RegFileFPGA”) implementation should be selected. For more information about the three register file implementations and their trade-offs, check out Register File.

Identification CSRs

The RISC-V Privileged Architecture specifies several read-only CSRs that identify the vendor and micro-architecture of a CPU. These are mvendorid, marchid and mimpid. The fixed, read-only values for these CSRs are defined in rtl/ibex_pkg.sv. Implementers should carefully consider appropriate values for these registers. Ibex, as an open source implementation, has an assigned architecture ID (marchid) of 22. (Allocations are specified in marchid.md of the riscv-isa-manual repository.) If significant changes are made to the micro-architecture a different architecture ID should be used. The vendor ID and implementation ID (mvendorid and mimpid) both read as 0 by default, meaning non-implemented. Implementers may wish to use other values here. Please see the RISC-V Privileged Architecture specification for more details on what these IDs represent and how they should be chosen.

Primitives

Ibex uses a number of primitive modules (that are held outside the rtl/ which contains the Ibex RTL). Full implementations of these primitives are provided in the Ibex repository but implementors may wish to provide their own implementations. Some of the primitives are only used for specific Ibex configurations so can be ignored/removed if you’re not using one of those configurations.

The mandatory primitives (used by all configurations) are:

prim_buf - A buffer, used to ensure security critical logic isn’t optimized out in synthesis (by applying suitable constraints to prim_buf). In configurations where SecureIbex == 0 it must exist but can be implemented as a straight passthrough.
prim_clock_gating - A clock gate.

The configuration dependent primitives are:

prim_clock_mux2 - A clock mux, used by the lockstep duplicate core. Required where SecureIbex == 1.
prim_flop - A flip flop, used to ensure security critical logic isn’t optimized out in synthesis (by applying suitable constraints to prim_flop). Required where SecureIbex == 1.
prim_ram_1p - A single ported RAM. Required where ICache == 1.
prim_ram_1p_scr - A single ported RAM which scrambles its contents with cryptographic primitives. Required where ICache == 1 and SecureIbex == 1.
prim_lfsr - Linear feedback shift register, used for pseudo random number generation for dummy instruction insertion. Required where SecureIbex == 1.
prim_onehot_check - Checks a onehot signal is correct, for detecting fault injection attacks. Required where SecureIbex == 1.
prim_secded_X - Various primitives to encode and decode SECDED (single error correct, double error detect) error detection and correction codes. Required where SecureIbex == 1.

Primitives exclusively used by other primitives:

prim_present / prim_prince / prim_subst_perm - Cryptographic primitives used by prim_ram_1p_scr.
prim_ram_1p_adv - Wrapper around prim_ram_1p that adds support for ECC, used by prim_ram_1p_scr.

RTL File List

Ibex flows use FuseSoC to gather needed RTL files and run builds. If you want to use Ibex without FuseSoC the following FuseSoC command will copy all the needed files into a build directory.

fusesoc --cores-root . run --target=lint --setup --build-root ./build/ibex_out lowrisc:ibex:ibex_top

FuseSoC uses Python and it can be installed using pip.

pip3 install -U -r python-requirements.txt

Ibex uses a custom fork of FuseSoC, so you must install it via this method rather than installing FuseSoC separately.

The RTL will be in ./build/ibex_out/src which is further divided into different sub-directories. A file list containing paths to all of the RTL files can be found in ./build/ibex_out/ibex-verilator/lowrisc_ibex_ibex_top_0.1.vc.

Instantiation Template

ibex_top #(
    .PMPEnable        ( 0                                ),
    .PMPGranularity   ( 0                                ),
    .PMPNumRegions    ( 4                                ),
    .MHPMCounterNum   ( 0                                ),
    .MHPMCounterWidth ( 40                               ),
    .RV32E            ( 0                                ),
    .RV32M            ( ibex_pkg::RV32MFast              ),
    .RV32B            ( ibex_pkg::RV32BNone              ),
    .RegFile          ( ibex_pkg::RegFileFF              ),
    .ICache           ( 0                                ),
    .ICacheECC        ( 0                                ),
    .ICacheScramble   ( 0                                ),
    .BranchPrediction ( 0                                ),
    .SecureIbex       ( 0                                ),
    .RndCnstLfsrSeed  ( ibex_pkg::RndCnstLfsrSeedDefault ),
    .RndCnstLfsrPerm  ( ibex_pkg::RndCnstLfsrPermDefault ),
    .DbgTriggerEn     ( 0                                ),
    .DmHaltAddr       ( 32'h1A110800                     ),
    .DmExceptionAddr  ( 32'h1A110808                     )
) u_top (
    // Clock and reset
    .clk_i                  (),
    .rst_ni                 (),
    .test_en_i              (),
    .scan_rst_ni            (),
    .ram_cfg_i              (),

    // Configuration
    .hart_id_i              (),
    .boot_addr_i            (),

    // Instruction memory interface
    .instr_req_o            (),
    .instr_gnt_i            (),
    .instr_rvalid_i         (),
    .instr_addr_o           (),
    .instr_rdata_i          (),
    .instr_rdata_intg_i     (),
    .instr_err_i            (),

    // Data memory interface
    .data_req_o             (),
    .data_gnt_i             (),
    .data_rvalid_i          (),
    .data_we_o              (),
    .data_be_o              (),
    .data_addr_o            (),
    .data_wdata_o           (),
    .data_wdata_intg_o      (),
    .data_rdata_i           (),
    .data_rdata_intg_i      (),
    .data_err_i             (),

    // Interrupt inputs
    .irq_software_i         (),
    .irq_timer_i            (),
    .irq_external_i         (),
    .irq_fast_i             (),
    .irq_nm_i               (),

    // Debug interface
    .debug_req_i            (),
    .crash_dump_o           (),

    // Special control signals
    .fetch_enable_i         (),
    .alert_minor_o          (),
    .alert_major_internal_o (),
    .alert_major_bus_o      (),
    .core_sleep_o           ()
);

Parameters

Name	Type/Range	Default	Description
`PMPEnable`	bit	0	Enable PMP support
`PMPGranularity`	int (0..31)	0	Minimum granularity of PMP address matching
`PMPNumRegions`	int (1..16)	4	Number implemented PMP regions (ignored if PMPEnable == 0)
`MHPMCounterNum`	int (0..10)	0	Number of performance monitor event counters
`MHPMCounterWidth`	int (64..1)	40	Bit width of performance monitor event counters
`RV32E`	bit	0	RV32E mode enable (16 integer registers only)
`RV32M`	ibex_pkg::rv32m_e	RV32MFast	M(ultiply) extension select: “ibex_pkg::RV32MNone”: No M-extension “ibex_pkg::RV32MSlow”: Slow multi-cycle multiplier, iterative divider “ibex_pkg::RV32MFast”: 3-4 cycle multiplier, iterative divider “ibex_pkg::RV32MSingleCycle”: 1-2 cycle multiplier, iterative divider
`RV32B`	ibex_pkg::rv32b_e	RV32BNone	B(itmanipulation) extension select: “ibex_pkg::RV32BNone”: No B-extension “ibex_pkg::RV32BBalanced”: Sub-extensions Zba, Zbb, Zbs, Zbf and Zbt “ibex_pkg::RV32BOTEarlGrey”: All sub-extensions except Zbe “ibex_pkg::RV32BFull”: All sub-extensions
`RegFile`	ibex_pkg::regfile_e	RegFileFF	Register file implementation select: “ibex_pkg::RegFileFF”: Generic flip-flop-based register file “ibex_pkg::RegFileFPGA”: Register file for FPGA targets “ibex_pkg::RegFileLatch”: Latch-based register file for ASIC targets
`BranchTargetALU`	bit	0	Enables branch target ALU removing a stall cycle from taken branches
`WritebackStage`	bit	0	Enables third pipeline stage (writeback) improving performance of loads and stores
`ICache`	bit	0	Enable instruction cache instead of prefetch buffer
`ICacheECC`	bit	0	Enable SECDED ECC protection in ICache (if ICache == 1)
`ICacheScramble`	bit	0	Enabling this parameter replaces tag and data RAMs of ICache with scrambling RAM primitives.
`BranchPrediction`	bit	0	EXPERIMENTAL Enable Static branch prediction
`SecureIbex`	bit	0	Enable various additional features targeting secure code execution. Note: SecureIbex == 1’b1 and RV32M == ibex_pkg::RV32MNone is an illegal combination.
`RndCnstLfsrSeed`	lfsr_seed_t	see above	Set the starting seed of the LFSR used to generate dummy instructions (only relevant when SecureIbex == 1’b1)
`RndCnstLfsrPerm`	lfsr_perm_t	see above	Set the permutation applied to the output of the LFSR used to generate dummy instructions (only relevant when SecureIbex == 1’b1)
`DbgTriggerEn`	bit	0	Enable debug trigger support (one trigger only)
`DmHaltAddr`	int	0x1A110800	Address to jump to when entering Debug Mode
`DmExceptionAddr`	int	0x1A110808	Address to jump to when an exception occurs while in Debug Mode

Any parameter marked EXPERIMENTAL when enabled is not verified to the same standard as the rest of the Ibex core.

Note that Ibex uses SystemVerilog enum parameters e.g. for RV32M and RV32B. This is well supported by most tools but some care is needed when overriding these parameters at the top level:

Synopsys VCS does not support overriding enum and string parameters at the top level via command line. As a workaround, SystemVerilog defines are used in Ibex top level files simulated with VCS. These defines can be set via command line.
Yosys does not support overriding enum parameters at the top level by setting enum names. Instead, the enum values need to be used.

Interfaces

Signal(s)	Width	Dir	Description
`clk_i`	1	in	Clock signal
`rst_ni`	1	in	Active-low asynchronous reset
`test_en_i`	1	in	Test input, enables clock and allows test control of reset.
`scan_rst_ni`	1	in	Test controlled reset. If DFT not used, tie off to 1.
`ram_cfg_i`	10	in	RAM configuration inputs, routed to the icache RAMs
`hart_id_i`	32	in	Hart ID, usually static, can be read from Hardware Thread ID (mhartid) CSR
`boot_addr_i`	32	in	First program counter after reset = `boot_addr_i` + 0x80, see Exceptions and Interrupts
`instr_*`	Instruction fetch interface, see Instruction Fetch
`data_*`	Load-store unit interface, see Load-Store Unit
`irq_*`	Interrupt inputs, see Exceptions and Interrupts
`scramble_*`	Scrambling key interface, see Instruction Cache
`debug_*`	Debug interface, see Debug Support
`crash_dump_o`	A set of signals that can be captured on reset to aid crash debugging.
`double_fault_seen_o`	A double fault was observed, see Double Fault Detection
`fetch_enable_i`	4	in	Allow the core to fetch instructions. If this bit is set low, the core will pause fetching new instructions and immediately halt once any in-flight instructions in the ID/EX and WB stages have finished. A multi-bit encoding scheme is used. See IbexMuBiOn / IbexMuBiOff in `rtl/ibex_pkg.sv`
`core_sleep_o`	1	out	Core in WFI with no outstanding data or instruction accesses. Deasserts if an external event (interrupt or debug req) wakes the core up
`alert_minor_o`	1	out	Core has detected a fault which it can safely recover from. Can be used by a system to log errors over time and detect tampering / attack. This signal is a pulse, one cycle per alert.
`alert_major_internal_o`	1	out	Core has detected an internal fault which cannot be recovered from. Can be used by a system to reset the core and possibly take other remedial action. This signal is a pulse, but might be set for multiple cycles per alert.
`alert_major_bus_o`	1	out	Core has detected a bus fault which cannot be recovered from. Can be used by a system to reset the core and possibly take other remedial action. This signal is a pulse, but might be set for multiple cycles per alert.