updated documentation

README.md

@@ -12,7 +12,9 @@ Brief description of the modules:
 * Registers: Implements the register file, PC register & CSR registers
 * RISC_V_execute: Executes ISA instructions
 * Instruction: Decodes instruction and acces to any instruction field
-* Simulation: Top-level entity that builds & starts the simulation
+* Simulator: Top-level entity that builds & starts the simulation
+* BusCtrl: Simple bus manager
+* Trace: Simple trace peripheral
 
 Current performance is about 284500 instructions / sec in a Core-i5@2.2Ghz
 

inc/BusCtrl.h

@@ -1,8 +1,8 @@
-/*!
-   \file Trace.h
-   \brief Basic TLM-2 Trace module
-   \author Màrius Montón
-   \date September 2018
+/**
+   @file BusCtrl.h
+   @brief Basic TLM-2 Bus controller
+   @author Màrius Montón
+   @date September 2018
 */
 
 #ifndef __BUSCTRL_H__
@@ -25,22 +25,54 @@ using namespace sc_core;
 using namespace sc_dt;
 using namespace std;
 
-
+/**
+ * Memory mapped Trace peripheral address
+ */
 #define TRACE_MEMORY_ADDRESS 0x40000000
-
+/**
+ * @brief Simple bus controller
+ *
+ * This module manages instructon & data bus. It has 2 target ports,
+ * cpu_instr_socket and cpu_data_socket that receives accesses from CPU and
+ * has 2 initiator ports to access main Memory and Trace module.
+ * It will be expanded with more ports when required (for DMA,
+ * other peripherals, etc.)
+ */
 class BusCtrl: sc_module {
 public:
-    // TLM-2 socket, defaults to 32-bits wide, base protocol
+    /**
+     * @brief TLM target socket CPU instruction memory bus
+     */
     tlm_utils::simple_target_socket<BusCtrl> cpu_instr_socket;
+
+    /**
+     * @brief TLM target socket CPU data memory bus
+     */
     tlm_utils::simple_target_socket<BusCtrl> cpu_data_socket;
-    tlm_utils::simple_initiator_socket<BusCtrl> data_memory_socket;
+
+    /**
+     * @brief TLM initiator socket Main memory bus
+     */
+    tlm_utils::simple_initiator_socket<BusCtrl> memory_socket;
+
+    /**
+     * @brief TLM initiator socket Trace module
+     */
     tlm_utils::simple_initiator_socket<BusCtrl> trace_socket;
 
 
-    // Constructor
+    /**
+     * @brief constructor
+     * @param name module's name
+     */
+
     BusCtrl(sc_module_name name);
 
-    // TLM-2 blocking transport method
+    /**
+     * @brief TLM-2 blocking mechanism
+     * @param trans transtractino to perform
+     * @param delay delay associated to this transaction
+     */
     virtual void b_transport( tlm::tlm_generic_payload& trans, sc_time& delay );
 
 private:

inc/Trace.h

@@ -21,7 +21,11 @@
 using namespace sc_core;
 using namespace sc_dt;
 using namespace std;
-
+/**
+ * @brief Simple trace peripheral
+ *
+ * This peripheral outputs to cout any character written to its unique register
+ */
 class Trace: sc_module {
 public:
     // TLM-2 socket, defaults to 32-bits wide, base protocol

src/BusCtrl.cpp

@@ -4,7 +4,7 @@ SC_HAS_PROCESS(BusCtrl);
 BusCtrl::BusCtrl(sc_module_name name): sc_module(name)
   ,cpu_instr_socket("cpu_instr_socket")
   ,cpu_data_socket("cpu_data_socket")
-  ,data_memory_socket("data_memory_socket")
+  ,memory_socket("memory_socket")
   ,trace_socket("trace_socket")
    {
     cpu_instr_socket.register_b_transport(this, &BusCtrl::b_transport);
@@ -14,13 +14,13 @@ BusCtrl::BusCtrl(sc_module_name name): sc_module(name)
 
 
 void BusCtrl::b_transport( tlm::tlm_generic_payload& trans, sc_time& delay ) {
-    tlm::tlm_command cmd = trans.get_command();
+    //tlm::tlm_command cmd = trans.get_command();
     sc_dt::uint64    adr = trans.get_address() / 4;
 
     if (adr == TRACE_MEMORY_ADDRESS / 4) {
       trace_socket->b_transport(trans, delay);
     } else {
-      data_memory_socket->b_transport(trans, delay);
+      memory_socket->b_transport(trans, delay);
     }
 
 #if 0

src/Simulator.cpp

@@ -1,3 +1,10 @@
+/*!
+   \file Simulator.cpp
+   \brief Top level simulation entity
+   \author Màrius Montón
+   \date September 2018
+*/
+
 #define SC_INCLUDE_DYNAMIC_PROCESSES
 
 #include "systemc"
@@ -18,7 +25,14 @@ using namespace std;
 
 string filename;
 
-SC_MODULE(Top)
+/**
+ * @class Simulator
+ * This class instiates all necessary modules, connects its ports and starts
+ * the simulation.
+ *
+ * @brief Top simulation entity
+ */
+SC_MODULE(Simulator)
 {
   CPU    *cpu;
   Memory *MainMemory;
@@ -28,7 +42,7 @@ SC_MODULE(Top)
   uint32_t start_PC;
   sc_signal<bool> IRQ;
 
-  SC_CTOR(Top)
+  SC_CTOR(Simulator)
   {
     MainMemory = new Memory("Main_Memory", filename);
     start_PC = MainMemory->getPCfromHEX();
@@ -41,13 +55,13 @@ SC_MODULE(Top)
     cpu->instr_bus.bind(Bus->cpu_instr_socket);
     cpu->exec->data_bus.bind(Bus->cpu_data_socket);
 
-    Bus->data_memory_socket.bind(MainMemory->socket);
+    Bus->memory_socket.bind(MainMemory->socket);
     Bus->trace_socket.bind(trace->socket);
     //cpu->interrupt.bind(IRQ);
   }
 
-  ~Top() {
-    cout << "Top destructor" << endl;
+  ~Simulator() {
+    cout << "Simulator destructor" << endl;
     delete cpu;
     delete MainMemory;
     delete Bus;
@@ -55,7 +69,7 @@ SC_MODULE(Top)
   }
 };
 
-Top *top;
+Simulator *top;
 
 void intHandler(int dummy) {
   delete top;
@@ -74,7 +88,7 @@ int sc_main(int argc, char* argv[])
   }
   filename = argv[1];
 
-  top = new Top("top");
+  top = new Simulator("top");
   sc_start();
   return 0;
 }