Clarify application scenarios of register file versions

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`.

doc/index.rst

@@ -6,6 +6,7 @@ Ibex User Manual
    :caption: Contents:
 
    introduction
+   getting_started
    integration
    instruction_fetch
    load_store_unit

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`.

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
+Flip-Flop-Based Register File
-2. Flip-flop based
+-----------------------------
 
-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.
+The flip-flop-based register file uses regular, positive-edge-triggered flip-flops to implement the registers.
-Note the flip-flop-based register file is significantly larger than the latch-based register-file for an ASIC implementation.
+
+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
+.. note:: The latch-based register file cannot be simulated using Verilator.
-* ``en_i``: Clock Enable Input
+
-* ``test_en_i``: Test Enable Input (activates the clock even though en_i is not set)
+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.
-* ``clk_o``: Gated Clock Output
+
+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 }
+       }

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,

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