Example for Ibex tracer usage

doc/examples.rst

@@ -0,0 +1,9 @@
+.. _examples:
+
+Examples
+========
+
+Tracer Simulation
+-----------------
+
+How to run a simple testbench to test the tracer is described in ``examples/sim/README.md``.

doc/index.rst

@@ -18,6 +18,7 @@ Ibex User Manual
    debug
    tracer
    rvfi
+   examples
 
 
 .. toctree::

doc/introduction.rst

@@ -50,6 +50,7 @@ The control and status registers are explained in :ref:`cs-registers`.
 :ref:`debug-support` gives a brief overview on the debug infrastructure.
 :ref:`tracer` gives a brief overview of the tracer module.
 For information regarding formal verification support, check out :ref:`rvfi`.
+:ref:`examples` gives an overview of how Ibex can be used.
 
 
 History

examples/sim/README.md

@@ -0,0 +1,26 @@
+# Ibex tracer simulation example
+
+## Overview
+
+This examples shows the usage of the module `ibex_core_tracer` which forwards
+all port signals to the `ibex_core` and a subset of signals to `ibex_tracer`.
+The tracer will create a file with a stream of executed instructions.
+
+## Prerequisites
+
+For this example, `modelsim` must be available and the following environment
+variable must point to the path of installation:
+
+```
+export MODEL_TECH=/path/to/modelsim/bin
+```
+
+## Usage
+
+Run the following command in the top level directory.
+
+```
+fusesoc --cores-root=. run --target=sim lowrisc:ibex:top_tracer_sim
+```
+
+The trace output can be found in `build/lowrisc_ibex_top_tracer_sim_0.1/sim-modelsim/trace_core_00_0.log`.

examples/sim/rtl/prim_clock_gating.sv

@@ -0,0 +1,24 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Dummy clock gating module
+
+module prim_clock_gating (
+    input        clk_i,
+    input        en_i,
+    input        test_en_i,
+    output logic clk_o
+);
+
+  logic clk_en;
+
+  always_latch begin
+    if (clk_i == 1'b0) begin
+      clk_en <= en_i | test_en_i;
+    end
+  end
+
+  assign clk_o = clk_i & clk_en;
+
+endmodule

examples/sim/tb/ibex_tracer_tb.sv

@@ -0,0 +1,111 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Sample testbench for Ibex tracer
+// The `nop` instruction is the only input
+
+module ibex_tracer_tb;
+  logic         clk         = 1'b0;
+  logic         rst_n       = 1'b0;
+  logic [31:0]  instr_rdata = 32'h00000013;
+  logic [31:0]  data_rdata  = 32'h00000000;
+
+  initial begin: clock_gen
+    forever begin
+      #5ns clk = 1'b0;
+      #5ns clk = 1'b1;
+    end
+  end
+
+  initial begin: reset_gen
+    rst_n = 1'b0;
+    #160ns rst_n = 1'b1;
+    #400ns $finish;
+  end
+
+  initial begin: instr_gen
+    #200ns instr_rdata = 32'h00000013;
+    #10ns instr_rdata = 32'h00000093;
+    #10ns instr_rdata = 32'h00400113;
+    #10ns instr_rdata = 32'hff810113;
+    #10ns instr_rdata = 32'h13410d13;
+    #10ns instr_rdata = 32'he1070713;
+    #10ns instr_rdata = 32'hfff7c793;
+    #10ns instr_rdata = 32'h00000013;
+    #10ns instr_rdata = 32'h002d2c23;
+    #10ns instr_rdata = 32'h00000013;
+    #10ns instr_rdata = 32'h000d2083;
+          data_rdata  = 32'h22222222;
+    #10ns instr_rdata = 32'h60008113;
+    #10ns instr_rdata = 32'h00000013;
+    #10ns instr_rdata = 32'h00000113;
+    #10ns instr_rdata = 32'h00000013;
+    #10ns instr_rdata = 32'h00000013;
+  end
+
+  ibex_core_tracer ibex_i (
+    .clk_i              (clk),
+    .rst_ni             (rst_n),
+
+    .test_en_i          (1'b0),
+
+    // Core ID, Cluster ID and boot address are considered more or less static
+    .core_id_i          (4'b0),
+    .cluster_id_i       (6'b0),
+    .boot_addr_i        (32'b0),
+
+    // Instruction memory interface
+    .instr_req_o        (),
+    .instr_gnt_i        (1'b1),
+    .instr_rvalid_i     (1'b1),
+    .instr_addr_o       (),
+    .instr_rdata_i      (instr_rdata),
+
+    // Data memory interface
+    .data_req_o         (),
+    .data_gnt_i         (1'b1),
+    .data_rvalid_i      (1'b1),
+    .data_we_o          (),
+    .data_be_o          (),
+    .data_addr_o        (),
+    .data_wdata_o       (),
+    .data_rdata_i       (data_rdata),
+    .data_err_i         (1'b0),
+
+    // Interrupt inputs
+    .irq_i              (1'b0),
+    .irq_id_i           (5'b0),
+    .irq_ack_o          (),
+    .irq_id_o           (),
+
+    // Debug Interface
+    .debug_req_i        (1'b0),
+
+    // RISC-V Formal Interface
+    .rvfi_valid         (),
+    .rvfi_order         (),
+    .rvfi_insn          (),
+    .rvfi_trap          (),
+    .rvfi_halt          (),
+    .rvfi_intr          (),
+    .rvfi_mode          (),
+    .rvfi_rs1_addr      (),
+    .rvfi_rs2_addr      (),
+    .rvfi_rs1_rdata     (),
+    .rvfi_rs2_rdata     (),
+    .rvfi_rd_addr       (),
+    .rvfi_rd_wdata      (),
+    .rvfi_pc_rdata      (),
+    .rvfi_pc_wdata      (),
+    .rvfi_mem_addr      (),
+    .rvfi_mem_rmask     (),
+    .rvfi_mem_wmask     (),
+    .rvfi_mem_rdata     (),
+    .rvfi_mem_wdata     (),
+
+    // CPU Control Signals
+    .fetch_enable_i     (1'b1)
+  );
+
+endmodule

examples/sim/top_tracer_sim.core

@@ -0,0 +1,25 @@
+CAPI=2:
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+name: "lowrisc:ibex:top_tracer_sim:0.1"
+description: "Ibex tracer example for modelsim"
+filesets:
+  files_tb:
+    depend:
+      - lowrisc:ibex:tracer
+    files:
+      - rtl/prim_clock_gating.sv
+      - tb/ibex_tracer_tb.sv
+    file_type: systemVerilogSource
+
+targets:
+  sim:
+    default_tool: modelsim
+    filesets:
+      - files_tb
+    toplevel:
+      - ibex_tracer_tb
+    tools:
+      modelsim:
+        vlog_options: [-timescale=1ns/1ns]