docs: update

docs/pages/documentation/atomsim/atomsim.rst

@@ -23,6 +23,8 @@ The following figure depicts the architecture of AtomSim.
 
 .. image:: ../../../diagrams/atomsim_arch.png
 
+.. _atomsim_arch:
+
 AtomSim Architecture
 *********************
 AtomSim is designed in a modular fashion with a clear API between the layers. There are 3 main layers in AtomSim,
@@ -65,5 +67,4 @@ AtomSim Topics
 
    cli_args.rst
    atomsim_modes.rst
-   code_structure.rst
-   adding_target.rst
+   atomsim_developers_guide.rst

docs/pages/documentation/atomsim/atomsim_developers_guide.rst

@@ -0,0 +1,31 @@
+AtomSim Developer's Guide
+##########################
+
+AtomSim Code Structure
+=======================
+
+AtomSim is designed in a modular fashion to allow portability across platforms not just limited to RISC-V Atom. Checkout
+:ref:`AtomSim architecture<atomsim_arch>`. The source code for atomsim is located under ``RVATOM/sim`` folder. Atomsim
+comprises of an interactive frontend (implemented in ``interactive.cpp``), middle-end (implemented in ``simstate.cpp``)
+and a backends for different *soctargets* (implemened in ``backend_<soctarget>.cpp``). All AtomSim backends are
+implemented as a child-class of the *Backend* template class (implemented in ``backend.hpp``). The backend class
+implements the RTL facing side of AtomSim and is responsible for reading register values and driving any signals through
+the *Testbench* class (implemented in ``testbench.hpp``).
+
+Adding a New Backend to AtomSim
+================================
+
+- Adding new backend involves adding a new backend class that extends the *Backend* class (in ``backend.hpp``).
+- All soctarget backends must override all the methods marked with ``[** OVERRIDE **]`` comment in the *Backend* class
+  (parent) as bare-minimum.
+- The methods marked with ``[** MAY OVERRIDE **]`` can optionally be overriden in child classes depending on the intended
+  functionality.
+- To allow AtomSim to *peek* and *poke* into SoC memory, user must override the ``fetch()`` and ``store()`` methods.
+- The backend may optioanlly use the testbench class from (``testbench.hpp``) to implement the low-level RTL facing 
+  functionality.
+- Users can use the *BitbangUART* class is provided in the ``bitbang_uart.cpp`` to emulate a UART device being connected
+  to SoC. Additioanlly, the *Vuart* class is provided in ``vuart.cpp`` can be used to interface with linux serial ports.
+- Users may intend to not simulate the whole SoC in RTL and therefore they can create their own C++ modules to emulate 
+  some functionality and call them from their backends. One example of this is the :ref:`AtomBones<soctarget-atombones>`
+  soctarget which only simulates the processor in RTL, everything else like memories (implemented in ``memory.cpp``),
+  uart, etc. is emulated in C++.

docs/pages/documentation/atomsim/atomsim_modes.rst

@@ -3,175 +3,96 @@ AtomSim Simulation Modes
 
 .. _atomsim_normal_mode:
 
+AtomSim can be run in 2 modes, normal and interactive mode.
+
 Normal Mode
 ************
-In this mode of simulation, no debug information is printed. Only serial data recieved from the soc is printed to the 
-stdout. Using ``--verbose / -v`` flag shows additional useful information.
+In this mode of simulation, no debug information is printed. Optionally user can enable printing of UART traffic to
+stdout using ``--enable-uart-dump / -u`` CLI option while invoking atomsim. Using ``--verbose / -v`` flag shows
+additional useful information. Checkout :doc:`cli_args` for information on CLI options.
 
 .. code-block:: bash
   
   $ atomsim sw/examples/banner/banner.elf -v
-  Input File: hello-asm/hello.elf
-  Resetting..
-  Relaying uart-rx to stdout (Note: This mode does not support uart-tx)
+     ___  __             _____
+    / _ |/ /____  __ _  / __(_)_ _
+   / __ / __/ _ \/  ' \_\ \/ /  ' \
+  /_/ |_\__/\___/_/_/_/___/_/_/_/_/  v2.2
+  soctarget: hydrogensoc
+  Initializing ram
   Initialization complete!
-  Hello World!
-        -- from Assembly
-  
-  Haulting @ tick 931
+  EBreak hit at 0x2000007c
+  Exiting..
 
 
 .. _atomsim_debug_mode:
 
 Debug/Interactive Mode
 ***********************
-In this mode of simulation, Contents of Program counter (in both stages), Instruction register, instruction disassembly 
-and contents of registers (if verbosity is set) are printed to stdout. A console with symbol ``:`` is also displayed at 
-the bottom if screen for user to enter various commands to control the simulation. To step through one clock cycle, user 
-can simply press :kbd:`enter` key (without entering anything in console).
-
-To invoke interactive debug mode, invoke atomsim with `-d` & `-v` flag:
-
-::
-
-  $ ./build/bin/atomsim hello.elf -d -v
-  Segments found : 2
-  Loading Segment 0 @ 0x00000000 --- done
-  Loading Segment 1 @ 0x00010000 --- done
-  Entry point : 0x00000000
-  Initialization complete!
-  : 
-  -< 1 >--------------------------------------------
-  F-STAGE  |  pc : 0x00000034  (+4) () 
-  E-STAGE  V  pc : 0x00000000   ir : 0x00010517   [addi x1, 0x33f]
-  ---------------------------------------------------
-   x0  (zero) : 0x00000000   x16 (a6)   : 0x00000000  
-   x1  (ra)   : 0x00000000   x17 (a7)   : 0x00000000  
-   x2  (sp)   : 0x00000000   x18 (s2)   : 0x00000000  
-   x3  (gp)   : 0x00000000   x19 (s3)   : 0x00000000  
-   x4  (tp)   : 0x00000000   x20 (s4)   : 0x00000000  
-   x5  (t0)   : 0x00000000   x21 (s5)   : 0x00000000  
-   x6  (t1)   : 0x00033000   x22 (s6)   : 0x00000400  
-   x7  (t2)   : 0x00000000   x23 (s7)   : 0x00000000  
-   x8  (s0/fp): 0x00000000   x24 (s8)   : 0x00000000  
-   x9  (s1)   : 0x00000000   x25 (s9)   : 0x00000000  
-   x10 (a0)   : 0x00000000   x26 (s10)  : 0x00000000  
-   x11 (a1)   : 0x00000000   x27 (s11)  : 0x00000000  
-   x12 (a2)   : 0x00000000   x28 (t3)   : 0x00000000  
-   x13 (a3)   : 0x00000000   x29 (t4)   : 0x00000000  
-   x14 (a4)   : 0x00000000   x30 (t5)   : 0x00000000  
-   x15 (a5)   : 0x00000000   x31 (t6)   : 0x00000000  
-  : 
-
-
-Interacting With Debug Console
-===============================
-
-Displaying contents of a register
-----------------------------------
-Contents of register can be displayed simply typing its name (abi names are also supported) on the 
-console. ex:
-
-::
-
-  : reg x0
-  x0 = 0x000045cf
-  : reg ra
-  ra = 0x0000301e
-
-Use ':' to display a range of registers. ex:
-
-:: 
-
-  : x0 : x1
-
-
-Displaying Contents of a memory location
------------------------------------------
-::
-
-  : m <address> <sizetag>
-
-Address can be specified in hex or decimal.
-Use sizetag to specify the size of data to be fetched, b for byte, h for half-word and w for word 
-(default is word).
+Debug/Interactive mode of AtomSim presents a console interface to the user, allowing them to interact with the simulation
+in real-time. The console is similar to the GDB console and inherits many features from it like stepping, breakpoints etc.
 
-::
+To invoke AtomSim in interactive debug mode, invoke atomsim with ``--debug / -d`` flag.
 
-  : m 0x30 b
-  mem[0x30] = 01
-
-Use ':' to display contents of memory in a range. ex:
-
-::
-  
-  : m 0x32:0x38 w
-  mem[0x30] = 01 30 cf 21
-  mem[0x38] = 11 70 ab cf
-
-
-Generating VCD traces
-----------------------
-Tracing can be enabled by:
-
-::
-
-  : trace out.vcd
-  Trace enabled : "./out.vcd" opened for output.
-
-or by passing --trace <file> option while invoking atomsim.
-
-Tracing can be disabled by:
-
-::
- 
-  :notrace
-  Trace disabled
-
-
-Controlling execution
-----------------------
-You can advance the simulation by one clock cycle by pressing the enter-key. You can also execute 
-until a desired equality is reached:
-
-1. until value of a register <reg> becomes <value>
-   :: 
-
-     : until <reg> <value>
-
-2. until value of a memory address <address> becomes <value>
-   ::
-   
-     : until <address> <value>
-
-3. while <condition> is true
-   ::
-   
-     : while <condition>
+.. code-block:: bash
 
-4. Execute for specified number of ticks
-   ::
-   
-     : for <ticks>
-     
-5. You can continue execution indefinitely by:
-   ::
+     ___  __             _____
+    / _ |/ /____  __ _  / __(_)_ _
+   / __ / __/ _ \/  ' \_\ \/ /  ' \
+  /_/ |_\__/\___/_/_/_/___/_/_/_/_/  v2.2
+  [         1] PC: 0x00000000, IR: 0x00000013, _
+  atomsim>
 
-     : r
 
-6. To end the simulation from the debug prompt:
-   ::
-   
-     : q
+As shown above, AtomSim will display the current cycle count, PC value, Instruction Register value and its disassembly
+respectively. To see register file contents, users can use the ``info / i`` command in the AtomSim console.
 
-   or
-
-   ::
-   
-    : quit
+Alternatively, If invoked with both ``--debug / -d`` and ``--verbose / -v`` CLI options, AtomSim presents a more verbose
+interface with register file contents in each cycle.
 
-   .. note:: 
-      At any point during execution (even without -d), you can enter the interactive debug mode with :kbd:`ctrl` + :kbd:`c`.
+.. code-block:: bash
 
-7. Miscellaneous
-   verbose-on & verbose off commands can be used to turn on /off verbosity.
+     ___  __             ____
+    / _ |/ /____  __ _  / __(_)_ _
+   / __ / __/ _ \/  ' \_\ \/ /  ' \
+  /_/ |_\__/\___/_/_/_/___/_/_/_/_/  v2.2
+  soctarget: hydrogensoc
+  Initializing ram
+  Initialization complete!
+  ┌─[         1]─────────────────────────────────────────────┐
+  │ PC: 0x00000000    PC_f: 0x00010000     (    +65536   )   │
+  │ IR: 0x00000013    _                                      │
+  └──────────────────────────────────────────────────────────┘
+    x0  (zero) : 0x00000000    x16 (a6)   : 0x00000000
+    x1  (ra)   : 0x00000000    x17 (a7)   : 0x00000000
+    x2  (sp)   : 0x00000000    x18 (s2)   : 0x00000000
+    x3  (gp)   : 0x00000000    x19 (s3)   : 0x00000000
+    x4  (tp)   : 0x00000000    x20 (s4)   : 0x00000000
+    x5  (t0)   : 0x00000000    x21 (s5)   : 0x00000000
+    x6  (t1)   : 0x00000000    x22 (s6)   : 0x00000000
+    x7  (t2)   : 0x00000000    x23 (s7)   : 0x00000000
+    x8  (s0/fp): 0x00000000    x24 (s8)   : 0x00000000
+    x9  (s1)   : 0x00000000    x25 (s9)   : 0x00000000
+    x10 (a0)   : 0x00000000    x26 (s10)  : 0x00000000
+    x11 (a1)   : 0x00000000    x27 (s11)  : 0x00000000
+    x12 (a2)   : 0x00000000    x28 (t3)   : 0x00000000
+    x13 (a3)   : 0x00000000    x29 (t4)   : 0x00000000
+    x14 (a4)   : 0x00000000    x30 (t5)   : 0x00000000
+    x15 (a5)   : 0x00000000    x31 (t6)   : 0x00000000
+  atomsim>
+
+Try the ``help`` command to checkout the commands available in AtomSim console.
+
+Tips for using AtomSim in interactive mode
+===========================================
+- If simulation is run in normal mode, pressing :kbd:`ctrl` + :kbd:`c` returns AtomSim to interactive mode and pressing
+  :kbd:`ctrl` + :kbd:`c` in interactive mode terminates the simulation.
+- AtomSim has shorter aliases for most of the command names which can be seen in command help.
+- AtomSim console is based on the linux readline library which allows user to press :kbd:`up` / :kbd:`down` arrow keys
+  to cycle between previously entered commands.
+- If user presses :kbd:`enter` without entering a command, AtomSim executes the last executed command.
+- When entering numeric values in console such as addresses, users can specify in decimal, hexadecimal (by prefixing
+  the value with **0x**), or binary (by prefixng the value with **0b**).
+- Register names can be specified as physical register names (*x0, x1, x2 ...*) or their ABI names (*zero, ra, sp...*)
+- Some of effects of CLI arguments can be overridden in the AtomSim console, like enabling/disabling trace, verbosity etc.
+- Lastly, refer to the ``help`` command to find most up-to-date information related to the AtomSim console.