diff --git a/docs/pages/documentation/atomsim/adding_target.rst b/docs/pages/documentation/atomsim/adding_target.rst deleted file mode 100644 index 020bb8b3..00000000 --- a/docs/pages/documentation/atomsim/adding_target.rst +++ /dev/null @@ -1,4 +0,0 @@ -Adding a New Target to AtomSim -############################### - -This is a placeholder \ No newline at end of file diff --git a/docs/pages/documentation/atomsim/atomsim.rst b/docs/pages/documentation/atomsim/atomsim.rst index 493c67e6..2cd27ee5 100644 --- a/docs/pages/documentation/atomsim/atomsim.rst +++ b/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 diff --git a/docs/pages/documentation/atomsim/atomsim_developers_guide.rst b/docs/pages/documentation/atomsim/atomsim_developers_guide.rst new file mode 100644 index 00000000..3a04a4d2 --- /dev/null +++ b/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`. 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_.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 which only simulates the processor in RTL, everything else like memories (implemented in ``memory.cpp``), + uart, etc. is emulated in C++. \ No newline at end of file diff --git a/docs/pages/documentation/atomsim/atomsim_modes.rst b/docs/pages/documentation/atomsim/atomsim_modes.rst index 21fdb2f8..0192b70e 100644 --- a/docs/pages/documentation/atomsim/atomsim_modes.rst +++ b/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 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 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 becomes - :: - - : until - -2. until value of a memory address
becomes - :: - - : until
- -3. while is true - :: - - : while +.. code-block:: bash -4. Execute for specified number of ticks - :: - - : for - -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. diff --git a/docs/pages/documentation/atomsim/cli_args.rst b/docs/pages/documentation/atomsim/cli_args.rst index 017b4fc1..a338ae6d 100644 --- a/docs/pages/documentation/atomsim/cli_args.rst +++ b/docs/pages/documentation/atomsim/cli_args.rst @@ -2,64 +2,64 @@ AtomSim CLI Argument Reference ############################### Following are the arguments that may be passed to the AtomSim executable. -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| Short Option | Long Option | Function | Default value | -+===============+=====================+==================================================+========================================+ -| **General Options** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -h | --help | Show this message | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --version | Show version information | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --soctarget | Show current AtomSim SoC target | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --no-color | Don't show colored output | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --no-banner | Don't show banner | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -i | --input arg | Specify an input file | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| **Debugging Options** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -v | --verbose | Turn on verbose output | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -d | --debug | Start in debug mode | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -t | --trace | Enable VCD tracing | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --trace-file arg | Specify trace file | trace.vcd | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --dump-file arg | Specify dump file | dump.txt | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --ebreak-dump | Enable processor state dump at hault | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --signature arg | Enable signature dump at hault | | -| | | (Used for riscv compliance tests) | "" | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| **Sim Config Options** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --maxitr arg | Specify maximum simulation iterations | 1000000 | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| **Backend Config Options (Common)** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -u | --enable-uart-dump | Enable dumping UART data (from soc) to stdout | | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -p | --vuart-port arg | serial port for virtual UART | "" | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| -b | --vuart-baud arg | serial baud rate for virtual UART | 115200 | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| **Backend Config Options (AtomBones)** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --bootrom-size arg | Specify size of bootrom to simulate (in KB) | 8 | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --bootrom-image arg | Specify bootrom hex image | ${RVATOM}/sw/bootloader/bootloader.hex | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --ram-size arg | Specify size of RAM memory to simulate (in KB) | 81920 | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| **Backend Config Options (HydrogenSoC)** | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ -| | --bootmode arg | Specify bootmode signal | 1 | -+---------------+---------------------+--------------------------------------------------+----------------------------------------+ ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| Option | Long Option | Function | Default value | ++========+=====================+================================================+========================================+ +| **General Options** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -h | --help | Show this message | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --version | Show version information | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --soctarget | Show current AtomSim SoC target | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --no-color | Don't show colored output | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --no-banner | Don't show banner | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -i | --input arg | Specify an input file | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| **Debugging Options** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -v | --verbose | Turn on verbose output | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -d | --debug | Start in debug mode | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -t | --trace | Enable VCD tracing | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --trace-file arg | Specify trace file | trace.vcd | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --dump-file arg | Specify dump file | dump.txt | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --ebreak-dump | Enable processor state dump at hault | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --signature arg | Enable signature dump at hault | | +| | | (Used for riscv compliance tests) | "" | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| **Sim Config Options** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --maxitr arg | Specify maximum simulation iterations | 1000000 | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| **Backend Config Options (Common)** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -u | --enable-uart-dump | Enable dumping UART data (from soc) to stdout | | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -p | --vuart-port arg | serial port for virtual UART | "" | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| -b | --vuart-baud arg | serial baud rate for virtual UART | 115200 | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| **Backend Config Options (AtomBones)** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --bootrom-size arg | Specify size of bootrom to simulate (in KB) | 8 | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --bootrom-image arg | Specify bootrom hex image | ${RVATOM}/sw/bootloader/bootloader.hex | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --ram-size arg | Specify size of RAM memory to simulate (in KB) | 81920 | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| **Backend Config Options (HydrogenSoC)** | ++--------+---------------------+------------------------------------------------+----------------------------------------+ +| | --bootmode arg | Specify bootmode signal | 1 | ++--------+---------------------+------------------------------------------------+----------------------------------------+ .. note:: diff --git a/docs/pages/documentation/atomsim/code_structure.rst b/docs/pages/documentation/atomsim/code_structure.rst deleted file mode 100644 index 927af680..00000000 --- a/docs/pages/documentation/atomsim/code_structure.rst +++ /dev/null @@ -1,4 +0,0 @@ -AtomSim Code Structure -####################### - -This is a Placeholder \ No newline at end of file diff --git a/docs/pages/documentation/build_flow.rst b/docs/pages/documentation/build_flow.rst index a639a8ac..630b30ef 100644 --- a/docs/pages/documentation/build_flow.rst +++ b/docs/pages/documentation/build_flow.rst @@ -1,4 +1,28 @@ RISC-V Atom Build Flow ####################### -TBA \ No newline at end of file +RISC-V Atom project uses a Make base build flow, assisted by the ``cfgparse.py`` script and JSON config files located +under ``rtl/config`` directory. There exists a JSON config file for each / a group of RTL components which specifies +how to compile them, any required flags, macros etc. This implies, each soctarget or a variation of an soctarget has a +JSON which is used to build it. + +This approach has many advantages over a static approach of incorporating everything in the Makefiles. The ``cfgparse.py`` +is used to parse the json files and extract all the necessary information to build a target like compiler flags, source +files etc. Not only that, cfgparse script allows JSON files to include dependency information on other JSON files, variable +substitution and polymorphism. + +Some Information on the Structure of JSON config files +******************************************************* + +#. One JSON file can depend on one or more JSON files (specified in ``includes`` attribute), allowing all of them to be + parsed together. +#. A JSON file can specify parameters in the ``params`` attribute which can be used as variables in conditional statements + throughout the script. +#. Parameters in the included JSON files can be overridden by the parameters in the JSON file which included it. +#. A conditional statement can be specified as ``[?:]``, where if the condition is true, ``A`` is + substituted in the string, else ``B`` is substituted in the string. Users are free to omit A, B, or both depending on + the requirement. +#. JSON config files support basic polymorphism. They can inherit attributes from the another JSON file using the + ``extends`` attribute. This is useful when users want to specify a special configuration of an existing configuration + without duplicating the contents of the original file. +#. Parameters in the *child* config files override parameters in the parent *config* file. diff --git a/docs/pages/documentation/scar.rst b/docs/pages/documentation/scar.rst index 69f5cb9c..98319cca 100644 --- a/docs/pages/documentation/scar.rst +++ b/docs/pages/documentation/scar.rst @@ -1,62 +1,86 @@ SCAR: Search Compile Assert Run ################################ -SCAR is a processor verification framework in python. SCAR performs a set of assembly level tests to verify the processor implementation. Each assembly test checks for one particular functionality of the processor. SCAR does this by examining a state dump file after the processor is done with executing a test code. This state dump file then checked assuming a set of assertions in the form of expected register values. These assertions are provided in the assembly file itself. SCAR is also used to verify the ISA-compliance. +SCAR is a processor verification framework in python. SCAR performs a set of assembly level tests to verify the processor +implementation. Each assembly test checks for one particular functionality of the processor. SCAR does this by examining +a state dump file after the processor is done with executing a test code. This state dump file then checked assuming a +set of assertions in the form of expected register values. These assertions are provided in a separate assertion file. +SCAR is also used to verify the ISA-compliance. + +SCAR is located in ``RVATOM/test/scar`` directory. SCAR Workflow ************** +As the name suggests: + +#. **Search:** SCAR searches for all the available assembly level tests specified in a config JSON file. The config JSON + file also specifies the corresponding assertion files. +#. **Compile:** SCAR then compiles all the tests with a user-defined linker script. +#. **Execute:** In this step, The elf files are executed on the target simulator with a special flag which creates a + state dump file after execution terminates. SCAR createsa ``work`` directory to store all the outputs. +#. **Verify:** Finally, Assertions are read from the assertion file and are then used to verify the register values in + the generated state dump file. + +Once you're finished building the RISC-V Atom project, SCAR can be invoked from the ``RVATOM`` directory itself using the +``scar`` target in the Makefile (see make help). Following is a demo output of a run of SCAR framework on hydrogensoc. + +.. code-block:: bash + + +------------------------------------------------------------------------------+ + | SCAR Verification Report | + +------------------------------------------------------------------------------+ + Date: 2024-02-04 19:23:21 + + 0). add64 - Passed All Assertions Passed + 1). addi - Passed All Assertions Passed + 2). add - Passed All Assertions Passed + 3). andi - Passed All Assertions Passed + 4). and - Passed All Assertions Passed + 5). auipc - Passed All Assertions Passed + 6). beq - Passed All Assertions Passed + 7). bge - Passed All Assertions Passed + 8). bgeu - Passed All Assertions Passed + 9). blt - Passed All Assertions Passed + 10). bltu - Passed All Assertions Passed + 11). bne - Passed All Assertions Passed + 12). function_call - Passed All Assertions Passed + 13). jalr - Passed All Assertions Passed + 14). jal - Passed All Assertions Passed + 15). li - Passed All Assertions Passed + 16). load_store_byte - Passed All Assertions Passed + 17). load_store_hw - Passed All Assertions Passed + 18). lui - Passed All Assertions Passed + 19). lw - Passed All Assertions Passed + 20). mv - Passed All Assertions Passed + 21). ori - Passed All Assertions Passed + 22). or - Passed All Assertions Passed + 23). slli - Passed All Assertions Passed + 24). sll - Passed All Assertions Passed + 25). slti - Passed All Assertions Passed + 26). sltiu - Passed All Assertions Passed + 27). slt - Passed All Assertions Passed + 28). sltu - Passed All Assertions Passed + 29). srai - Passed All Assertions Passed + 30). sra - Passed All Assertions Passed + 31). srli - Passed All Assertions Passed + 32). srl - Passed All Assertions Passed + 33). stack - Passed All Assertions Passed + 34). storew - Passed All Assertions Passed + 35). sub - Passed All Assertions Passed + 36). sw - Passed All Assertions Passed + 37). xori - Passed All Assertions Passed + 38). xor - Passed All Assertions Passed + ================================================================================ + Passed tests : 39 / 39 + Ignored tests : 0 / 39 + Failed tests : 0 / 39 -#. **Search:** SCAR searches for all the available assembly level test in the directory and makes a list -#. **Compile:** It then compiles all the found tests with a user-defined linker script. -#. **Execute:** In this step, The elf files are executed on the target simulator which creates a state dump file after execution. -#. **Verify:** Finally, Assertions are read from the assembly file containing the test. These are then used to check for mismatches in the generated state dump file. - - -Assembly test format -********************* -The assembly file must satisfy the following criteria: - -#. File must have a ``_start`` label before the start of code. -#. File must have a ``ebreak`` instraction after the end of code. -#. File must have an assertion section at the bottom with the following format. - -Assertion Section Format -======================== -The assembly file must contain a set of assertions at the bottom in the following format: - -:: - - .global _start - _start: - - li t0, 0x00d01010 - li t1, 0x1ddc1044 - li t2, 0xdeadbeef - li t3, 0x22101301 - li t4, 0xfaf01569 - li t5, 0x078b102a - li t6, 0xdae013c0 - - add a0, t0, t1 - add a1, t1, t2 - add a2, t2, t3 - add a3, t3, t4 - add a4, t4, t5 - add a5, t5, t6 - - nop - nop - ebreak - - # $-ASSERTIONS-$ - # eq a0 0x1eac2054 - # eq a1 0xfc89cf33 - # eq a2 0x00bdd1f0 - # eq a3 0x1d00286a - # eq a4 0x027b2593 - # eq a5 0xe26b23ea - - -State-Dump file format -======================= -[TODO] \ No newline at end of file +How to Create Your Own Tests? +****************************** +#. Assembly file containing the test source code must have a ``_start`` label before the start of code. +#. Assembly file must have a ``ebreak`` instraction after the end of code, this triggers the simulation to terminate. +#. Each test file must have a corresponding assertion file (``*.asrt``) both of which need to be specified in the JSON + config file. +#. The assertion file uses a python like syntax to specify one expressions per line; which could use physical register + names (x0, x1, x2...) or ABI names (zero, ra, sp) as variables. +#. State dump file generated by simulator must have one key value pair per line. diff --git a/docs/pages/overview/introduction.rst b/docs/pages/overview/introduction.rst index 75b8a16f..bb0e67ab 100644 --- a/docs/pages/overview/introduction.rst +++ b/docs/pages/overview/introduction.rst @@ -41,7 +41,7 @@ Following is list of various components of the RISC-V Atom project. .. card:: RISC-V Atom CPU :link-type: doc - :link: /pages/documentation/riscv_atom/riscv_atom + :link: /pages/documentation/riscv_atom A simple 32-bit RISC-V processor.