Merge pull request #37 from saursin/dpi

Add DPI Logger

Makefile

@@ -60,6 +60,7 @@ Target = atombones
 # Verilog Configs
 VC = verilator
 VFLAGS = -cc -Wall --relative-includes --trace -D__ATOMSIM_SIMULATION__
+#VFLAGS += -DDPI_LOGGER -DLOG_RVATOM_JUMP
 
 verilog_files =  $(rtl_dir)/Timescale.vh
 verilog_files += $(rtl_dir)/core/Utils.vh 
@@ -208,8 +209,11 @@ $(cobject_dir)/verilated_vcd.o: /usr/share/verilator/include/verilated_vcd_c.cpp
 	@echo "$(COLOR_GREEN)Compiling cpp include [$<]...$(COLOR_NC)"
 	$(CC) $(CFLAGS) $^ -o $@
 
+$(cobject_dir)/util_dpi.o: $(rtl_dir)/dpi/util_dpi.cpp
+	$(CC) $(CFLAGS) $(INCLUDES) $< -o $@
+
 # Link & Create executable
-$(bin_dir)/$(sim_executable): $(vobject_dir)/V$(verilog_topmodule)__ALLcls.o $(vobject_dir)/V$(verilog_topmodule)__ALLsup.o $(cobject_dir)/atomsim.o $(cobject_dir)/verilated.o $(cobject_dir)/verilated_vcd.o
+$(bin_dir)/$(sim_executable): $(vobject_dir)/V$(verilog_topmodule)__ALLcls.o $(vobject_dir)/V$(verilog_topmodule)__ALLsup.o $(cobject_dir)/atomsim.o $(cobject_dir)/verilated.o $(cobject_dir)/verilated_vcd.o $(cobject_dir)/util_dpi.o
 	@echo "$(COLOR_GREEN)Linking shared object and driver to create executable...$(COLOR_NC)"
 	$(CC) $^ -o $@ $(LFLAGS)
 

docs/index.rst

@@ -35,6 +35,7 @@ RISC-V Atom Documentation & User Manual
    :maxdepth: 2
    :caption: User Manual:
 
+   pages/user-manual/rtl.rst
    pages/user-manual/atomsim.rst
    pages/user-manual/convelf.rst
    pages/user-manual/scar.rst

docs/pages/getting-started/examples.rst

@@ -1,7 +1,7 @@
 **********
 Examples
 **********
-Atom comes with a wide range of examples programs out-of-the-box to test. These examples programs reside 
+The RISC-V Atom project consists of a wide range of examples programs out-of-the-box to test. These examples programs reside 
 in `RVATOM/sw/examples` directory.
 
 Switch to examples directory
@@ -20,7 +20,7 @@ provided makefile as following.
 
   $ make target=atombones ex=hello-asm
 
-The above command should generate a `hello.elf` file in the `hello-asm directory`. Now fire up atomsim and 
+The above command should generate a `hello.elf` file in the `hello-asm` directory. Now fire up atomsim and 
 provide the generated elf file as argument.
 
 ::
@@ -33,7 +33,13 @@ This should output:
   Hello World!
       -- from Assembly
 
-We can test other examples also in the similar fashion.
+We can test other examples also in the similar fashion by using the following syntax:
+:: bash
+
+  $ make target=<TARGET> ex=<EXAMPLE>
+
+Run `make help` to get more information about supported targets an examples.
+
 
 Banner
 =======

docs/pages/user-manual/rtl.rst

@@ -0,0 +1,72 @@
+*****************
+RISC-V Atom RTL
+*****************
+RISC-V Atom is written in Verilog. Its RTL is divided into 2 categories, core and uncore, 
+both of which reside in the `rtl` directory in `core` and `uncore` subdirectories respectively.
+
+Rtl directory
+==============
+The top level verilog modules (atombones & hydrogensoc) are present in the `rtl` directory. Each 
+of these top level modules are configured by their respective configure headers (<name>_Config.vh file).
+These configuration headers contain the macros used in the top-module definitions to control the 
+generation of various sub-components and their parameters.
+
+
+Core directory
+---------------
+`core` directory contains the the *core* components of the CPU such as register file, alu, 
+decode unit etc. It also contains verilog header files like `Defs.vh` and `Utils.vh`. `Defs.vh`
+defines various signal eunumerations and other parameters internal to the processor. `Utils.vh` 
+defines some useful utility macros.
+
+
+Uncore directory
+-----------------
+The `uncore` subdirectory contains all the peripheral components such as uart, gpio, ram, rom etc. 
+This also includes the wishbone wrappers of some non-wishbone components. SoC implementations of the 
+Atom processor usually instantiate these hardware modules in their implementations.
+
+RTL Features
+=============
+
+DPI Logger
+-----------
+DPI Logger is a SystemVerilog DPI based logging mechanism provided with the RTL. It can be used to 
+dump useful run-time debug information such as PC values, Jump addresses, Loads and Stores, etc.
+into a log file. This module is present in the `rtl/dpi` subdirectory.
+
+To enable DPI Logger simply define `DPI_LOGGER` macro in the topmodule or in the Makefile VFLAGS variable
+as `-DDPI_LOGGER`. This will trigger the inclusion of the `rtl/dpi/util_dpi.vh` header in `rtl/core/Utils.vh`. 
+User is free include the `rtl/core/Utils.vh` header file in any verilog file that needs to be debugged.
+
+To log information, user first needs to call the `dpi_trace_start()` function somewhere in the rtl as following.
+
+.. code-block:: verilog
+  
+  initial begin
+    dpi_trace_start();
+  end
+
+Then the `dpi_trace()` function can be used to dump information. Its syntax is exactly same as the verilog 
+`$display` system funciton. Example of logging the jump is provided in the `AtomRV.v` file and is also shown 
+below.
+
+.. code-block:: verilog
+
+    `ifdef DPI_LOGGER
+        initial begin
+            dpi_logger_start();     // begin logging
+        end
+    `endif
+
+    `ifdef LOG_RVATOM_JUMP
+    always @(posedge clk_i) begin
+        if(jump_decision)   // on some trigger condition
+            dpi_logger("Jump  address=0x%x\n", {alu_out[31:1], 1'b0});      // dump information
+    end
+    `endif
+
+For logging the Jumps, user must also define the `LOG_ATOMRV_JUMP` macro in a similar way. This will generate a 
+"run.log" file in the current directory containt all the dumped information.
+
+

rtl/core/AtomRV.v

@@ -12,6 +12,7 @@
 ///////////////////////////////////////////////////////////////////
 
 `include "../Timescale.vh"
+`include "Utils.vh"
 `include "Defs.vh"
 
 `include "Decode.v"
@@ -163,6 +164,19 @@ module AtomRV
     assign imem_addr_o = ProgramCounter;
 
 
+    `ifdef DPI_LOGGER
+        initial begin
+            dpi_logger_start();
+        end
+    `endif
+
+    `ifdef LOG_RVATOM_JUMP
+    always @(posedge clk_i) begin
+        if(jump_decision)
+            dpi_logger("Jump  address=0x%x\n", {alu_out[31:1], 1'b0});
+    end
+    `endif
+
     //----------------------------------------------------------
     // PIPELINE REGISTERS
     //----------------------------------------------------------

rtl/core/Utils.vh

@@ -1,6 +1,12 @@
 `ifndef __UTILS_H__
 `define __UTILS_H__
 
+`ifdef verilator
+`ifdef DPI_LOGGER
+`include "../dpi/util_dpi.vh"
+`endif
+`endif
+
 /////////////////////////////////////////////////////////////
 // Function-like utility macros
 

rtl/dpi/util_dpi.cpp

@@ -0,0 +1,69 @@
+#include <cstdio>
+#include <iostream>
+#include <fstream>
+#include <string>
+
+#include "svdpi.h"
+#include "verilated_vpi.h"
+
+#ifdef TARGET_ATOMBONES
+#include "../../build/vobj_dir/VAtomBones__Dpi.h"
+#else
+#ifdef TARGET_HYDROGENSOC
+#include "../../build/vobj_dir/VHydrogenSoC__Dpi.h"
+#else
+#error rtl/dpi.cpp: Unknown Target
+#endif
+#endif
+
+
+extern "C" {
+    extern void dpi_logger(const char* format);
+    extern void dpi_logger_start();
+    extern void dpi_logger_stop();
+}
+
+
+class DPI_Logger
+{
+    public:
+    bool enabled = false;
+    std::fstream  logfile;
+
+    void enable()
+    {
+        logfile.open("run.log", std::ios::out | std::ios::trunc);
+        enabled = true;
+    }
+
+    void disable()
+    {
+        logfile.close();
+        enabled = false;
+    }
+
+    void log_dump(std::string s)
+    {
+        if(enabled)
+            logfile << s << std::flush;
+    }
+} dpi_logger_instance;
+
+
+
+void dpi_logger(const char* format)
+{
+    if (!dpi_logger_instance.enabled)
+        return;
+    dpi_logger_instance.log_dump(format);
+}
+
+void dpi_logger_start()
+{
+    dpi_logger_instance.enable();
+}
+
+void dpi_logger_stop()
+{
+    dpi_logger_instance.disable();
+}

rtl/dpi/util_dpi.vh

@@ -0,0 +1,9 @@
+`ifndef __UTIL_DPI__
+`define __UTIL_DPI__
+
+// dpi_logger
+import "DPI-C" function void dpi_logger(input string format /*verilator sformat*/);
+import "DPI-C" function void dpi_logger_start();
+import "DPI-C" function void dpi_logger_stop();
+
+`endif //__UTIL_DPI__

sw/examples/banner/banner.c

@@ -1,5 +1,6 @@
 #include <stdio.h>
 #include <stdlib.h>
+#include <defs.h>
 
 char * banner = 
 "\n"
@@ -31,4 +32,9 @@ char * banner =
 int main()
 {
     puts(banner);
+
+    printf("ROM size: %d\tbytes\t(%d KB)\n", MEM_ROM_SIZE, MEM_ROM_SIZE/1024);
+    printf("RAM size: %d\tbytes\t(%d KB)\n", MEM_RAM_SIZE, MEM_RAM_SIZE/1024);
+
+    printf("exiting...\n");
 }

sw/examples/random/random.c

@@ -3,18 +3,21 @@
 
 void main()
 {
+    printf("Printing 10 Random numbers using seed %d: \n", rand_seed);
     int i=0;
     for(i=0; i<10; i++)
     {   
+        putchar('\t');
         putint(rand(), 10, false);
         putchar('\n');
     }
 
     srand(0x50505);
-    putchar('\n');
+    printf("\nPrinting 10 Random numbers using seed %d: \n", 0x50505);
 
     for(i=0; i<10; i++)
     {   
+        putchar('\t');
         putint(rand(), 10, false);
         putchar('\n');
     }