diff --git a/doc/getting_started.rst b/doc/getting_started.rst new file mode 100644 index 00000000..afe9ac12 --- /dev/null +++ b/doc/getting_started.rst @@ -0,0 +1,28 @@ +.. _getting-started: + +Getting Started with Ibex +========================= + +This page discusses initial steps and requirements to start using Ibex in your design. + +Register File +------------- + +Ibex comes with two different register file implementations. +Depending on the target technology, either the implementation in ``ibex_register_file_ff.sv`` or the one in ``ibex_register_file_latch.sv`` should be selected. +For more information about the two register file implementations and their trade-offs, check out :ref:`register-file`. + +Clock Gating Cell +----------------- + +Ibex requires clock gating cells. +This cells are usually specific to the selected target technology and thus not provided as part of the RTL design. +It is assumed that the clock gating cell is wrapped in a module called ``prim_clock_gating`` that has the following ports: + +* ``clk_i``: Clock Input +* ``en_i``: Clock Enable Input +* ``test_en_i``: Test Enable Input (activates the clock even though ``en_i`` is not set) +* ``clk_o``: Gated Clock Output + +Inside Ibex, clock gating cells are used both in ``ibex_core.sv`` and ``ibex_register_file_latch.sv``. +For more information on the expected behavior of the clock gating cell when using the latch-based register file check out :ref:`register-file`. diff --git a/doc/index.rst b/doc/index.rst index 738bc879..1d6fef39 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,6 +6,7 @@ Ibex User Manual :caption: Contents: introduction + getting_started integration instruction_fetch load_store_unit diff --git a/doc/introduction.rst b/doc/introduction.rst index 87e948e0..ccd6c0f9 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -40,6 +40,7 @@ Since latches are not well supported on FPGAs, it is crucial to select the flip- Contents -------- +:ref:`getting-started` discusses the requirements and initial steps to start using Ibex. :ref:`core-integration` provides the instantiation template and gives descriptions of the design parameters as well as the input and output ports. The instruction and data interfaces of Ibex are explained in :ref:`instruction-fetch` and :ref:`load-store-unit`, respectively. The two register-file flavors are described in :ref:`register-file`. diff --git a/doc/register_file.rst b/doc/register_file.rst index e7dcbcdc..60b16846 100644 --- a/doc/register_file.rst +++ b/doc/register_file.rst @@ -6,22 +6,58 @@ Register File Ibex has either 31 or 15 32-bit registers if the RV32E extension is disabled or enabled, respectively. Register ``x0`` is statically bound to 0 and can only be read, it does not contain any sequential logic. -There are two flavors of register file available: +There are two flavors of register file available, both having their own benefits and trade-offs. -1. Latch based -2. Flip-flop based +Flip-Flop-Based Register File +----------------------------- -While the latch-based register file is recommended for ASICs, the flip-flop-based register file is recommended for FPGA synthesis, although both are compatible with either synthesis target. -Note the flip-flop-based register file is significantly larger than the latch-based register-file for an ASIC implementation. +The flip-flop-based register file uses regular, positive-edge-triggered flip-flops to implement the registers. + +This makes it the **first choice for FPGA synthesis** or when simulating the design using Verilator. + +To select the flip-flop-based register file, make sure to use the source file ``ibex_register_file_ff.sv`` in your project. Latch-Based Register File ------------------------- -The latch-based register file contains manually instantiated clock gating cells to keep the clock inactive when the latches are not written. +The latch-based register file uses level-sensitive latches to implement the registers. -It is assumed that there is a clock gating cell for the target technology that is wrapped in a module called ``prim_clock_gating`` and has the following ports: +This allows for significant area savings compared to an implementation using regular flip-flops and thus makes the latch-based register file the **first choice for ASIC implementations**. +Simulation of the latch-based register file is possible using commercial tools. -* ``clk_i``: Clock Input -* ``en_i``: Clock Enable Input -* ``test_en_i``: Test Enable Input (activates the clock even though en_i is not set) -* ``clk_o``: Gated Clock Output +.. note:: The latch-based register file cannot be simulated using Verilator. + +The latch-based register file can also be used for FPGA synthesis, but this is not recommended as FPGAs usually do not well support latches. + +To select the latch-based register file, make sure to use the source file ``ibex_register_file_latch.sv`` in your project. +In addition, a technology-specific clock gating cell must be provided to keep the clock inactive when the latches are not written. +This cell must be wrapped in a module called ``prim_clock_gating``. +For more information regarding the clock gating cell, checkout :ref:`getting-started`. + +.. note:: The latch-based register file requires the gated clock to be enabled in the cycle after the write enable ``we_a_i`` signal was set high. + This can be achieved by latching ``we_a_i`` in the clock gating cell during the low phase of ``clk_i``. + + The resulting behavior of the latch-based register file is visualized in :numref:`timing`. + The input data ``wdata_a_i`` is sampled into a flip-flop-based register ``wdata_a_q`` using ``clk_int``. + The actual latch-based registers ``mem[1]`` and ``mem[2]`` are transparent during high phases of ``mem_clk[1]`` and ``mem_clk[2]``, respectively. + Their content is sampled from ``wdata_a_q`` on falling edges of these clocks. + + .. wavedrom:: + :name: timing + :caption: Latch-based register file operation + + {"signal": + [ + {"name": "clk_i", "wave": "hlhlhlhl"}, + {"name": "we_a_i", "wave": "0.1...0."}, + {"name": "waddr_a_i", "wave": "xx=.=.xx", "data": ["1","2"]}, + {"name": "wdata_a_i", "wave": "xx=.=.xx", "data": ["Data1","Data2"]}, + {"name": "clk_int", "wave": "0...HlHl"}, + {"name": "wdata_a_q", "wave": "xxxx=.=.", "data": ["Data1", "Data2"]}, + {"name": "mem_clk[1]", "wave": "0...hL.."}, + {"name": "mem[1]", "wave": "xxxx=...", "data": ["Data1"]}, + {"name": "mem_clk[2]", "wave": "0.....hL"}, + {"name": "mem[2]", "wave": "xxxxxx=.", "data": ["Data2"]} + ], + "config": { "hscale": 2 } + } diff --git a/rtl/ibex_register_file_ff.sv b/rtl/ibex_register_file_ff.sv index 18cd9def..308decb5 100644 --- a/rtl/ibex_register_file_ff.sv +++ b/rtl/ibex_register_file_ff.sv @@ -15,7 +15,8 @@ // // // Description: Register file with 31 or 15x 32 bit wide registers. // // Register 0 is fixed to 0. This register file is based on // -// flip flops. // +// flip flops. Use this register file when targeting FPGA // +// synthesis or Verilator simulation. // // // //////////////////////////////////////////////////////////////////////////////// @@ -23,7 +24,8 @@ * RISC-V register file * * Register file with 31 or 15x 32 bit wide registers. Register 0 is fixed to 0. - * This register file is based on flip flops. + * This register file is based on flip flops. Use this register file when + * targeting FPGA synthesis or Verilator simulation. */ module ibex_register_file #( parameter bit RV32E = 0, diff --git a/rtl/ibex_register_file_latch.sv b/rtl/ibex_register_file_latch.sv index 61bf9637..06d6aec1 100644 --- a/rtl/ibex_register_file_latch.sv +++ b/rtl/ibex_register_file_latch.sv @@ -17,6 +17,9 @@ // Description: Register file with 31 or 15x 32 bit wide registers. // // Register 0 is fixed to 0. This register file is based on // // latches and is thus smaller than the flip-flop based RF. // +// It requires a target technology-specific clock gating // +// cell. Use this register file when targeting ASIC // +// synthesis or event-based simulators. // // // //////////////////////////////////////////////////////////////////////////////// @@ -25,7 +28,8 @@ * * Register file with 31 or 15x 32 bit wide registers. Register 0 is fixed to 0. * This register file is based on latches and is thus smaller than the flip-flop - * based RF. + * based RF. It requires a target technology-specific clock gating cell. Use this + * register file when targeting ASIC synthesis or event-based simulators. */ module ibex_register_file #( parameter bit RV32E = 0, @@ -144,4 +148,11 @@ module ibex_register_file #( end end +`ifdef VERILATOR + initial begin + $display("Latch-based register file not supported for Verilator simulation"); + $fatal; + end +`endif + endmodule