.. _core-integration: 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 :ref:`security`). Below, the instantiation template is given and the parameters and interfaces are described. Instantiation Template ---------------------- .. code-block:: verilog 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 | *EXPERIMENTAL* - Enables branch target ALU removing a stall | | | | | cycle from taken branches | +------------------------------+---------------------+------------+-----------------------------------------------------------------------+ | ``WritebackStage`` | bit | 0 | *EXPERIMENTAL* - Enables third pipeline stage (writeback) | | | | | improving performance of loads and stores | +------------------------------+---------------------+------------+-----------------------------------------------------------------------+ | ``ICache`` | bit | 0 | *EXPERIMENTAL* Enable instruction cache instead of prefetch | | | | | buffer | +------------------------------+---------------------+------------+-----------------------------------------------------------------------+ | ``ICacheECC`` | bit | 0 | *EXPERIMENTAL* Enable SECDED ECC protection in ICache (if | | | | | ICache == 1) | +------------------------------+---------------------+------------+-----------------------------------------------------------------------+ | ``ICacheScramble`` | bit | 0 | *EXPERIMENTAL* 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 | *EXPERIMENTAL* 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 :ref:`csr-mhartid` CSR | +----------------------------+-------------------------+-----+----------------------------------------+ | ``boot_addr_i`` | 32 | in | First program counter after reset | | | | | = ``boot_addr_i`` + 0x80, | | | | | see :ref:`exceptions-interrupts` | +----------------------------+-------------------------+-----+----------------------------------------+ | ``instr_*`` | Instruction fetch interface, see :ref:`instruction-fetch` | +----------------------------+------------------------------------------------------------------------+ | ``data_*`` | Load-store unit interface, see :ref:`load-store-unit` | +----------------------------+------------------------------------------------------------------------+ | ``irq_*`` | Interrupt inputs, see :ref:`exceptions-interrupts` | +----------------------------+-------------------------+-----+----------------------------------------+ | ``scramble_*`` | Scrambling key interface, see :ref:`icache` | +----------------------------+------------------------------------------------------------------------+ | ``debug_*`` | Debug interface, see :ref:`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 :ref:`double-fault-detect` | +----------------------------+-------------------------+-----+----------------------------------------+ | ``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 | | | | | :file:`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. | +----------------------------+-------------------------+-----+----------------------------------------+