Skip to content

Commit

Permalink
docs: update
Browse files Browse the repository at this point in the history
  • Loading branch information
@saursin
saursin committed Jan 16, 2024
1 parent 82c6b53 commit e6108c1
Show file tree
Hide file tree
Showing 11 changed files with 956 additions and 162 deletions.
2 changes: 1 addition & 1 deletion docs/diagrams/AtomBones.drawio
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<mxfile host="Electron" modified="2024-01-15T19:12:16.438Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/22.1.2 Chrome/114.0.5735.289 Electron/25.9.4 Safari/537.36" etag="eXcUi6uI4NrGV3BOpQla" version="22.1.2" type="device">
<mxfile host="Electron" modified="2024-01-15T22:39:26.389Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/22.1.2 Chrome/114.0.5735.289 Electron/25.9.4 Safari/537.36" etag="lhEtyTG7v3GwLPToCexG" version="22.1.2" type="device">
<diagram name="Page-1" id="AxxHWK4P5G7_AUV5sOG4">
<mxGraphModel dx="918" dy="656" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
Expand Down
635 changes: 635 additions & 0 deletions docs/diagrams/RISCVAtom_arch.drawio
View file

Large diffs are not rendered by default.

Binary file added docs/diagrams/RISCVAtom_arch.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,14 @@ to setup an environment to build and test the RISC-V Atom project. Please feel f
:maxdepth: 1
:caption: Documentation & User Manual

pages/documentation/riscv_atom/riscv_atom.rst
pages/documentation/riscv_atom.rst
pages/documentation/soc_targets.rst
pages/documentation/memory_map.rst
pages/documentation/bootloader.rst
pages/documentation/atomsim/atomsim.rst
pages/documentation/scar.rst
pages/documentation/convelf.rst
pages/documentation/libcatom.rst
pages/documentation/bootloader.rst
pages/documentation/build_flow.rst
pages/documentation/performance.rst
pages/documentation/fpga_results.rst
Expand Down
85 changes: 61 additions & 24 deletions docs/pages/documentation/atomsim/cli_args.rst
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,66 @@
AtomSim CLI Argument Reference
###############################
The following are the arguments that may be passed to the AtomSim executable.
Following are the arguments that may be passed to the AtomSim executable.

.. code-block:: text
Usage:
$ atomsim [OPTION...] input_file
+---------------+---------------------+--------------------------------------------------+----------------------------------------+
| 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 |
+---------------+---------------------+--------------------------------------------------+----------------------------------------+

Config options:
--maxitr arg Specify maximum simulation iterations (default: 10000000)
--vuart arg use provided virtual uart port (default: Null)
--vuart-baud arg Specify virtual uart port baudrate (default: 9600)

Debug options:
-v, --verbose Turn on verbose output
-d, --debug Start in debug mode
-t, --trace Enable VCD tracing
--trace-dir arg Specify trace directory (default: build/trace)
--dump-dir arg Specify dump directory (default: build/trace)
--ebreak-dump Enable processor state dump at hault
--signature arg Enable signature sump at hault (Used for riscv
compliance tests) (default: "")
General options:
-h, --help Show this message
--version Show version information
--simtarget Show current AtomSim Target
-i, --input arg Specify an input file
.. note::
For most up-to-date information, run ``atomsim --help`` command.
64 changes: 63 additions & 1 deletion docs/pages/documentation/bootloader.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,66 @@
RISC-V Atom Bootloader
#######################

TBA xmsend script
The RISC-V Atom bootloader is a **stage-0** bootloader. It is loaded in the BootROM and executable as the first thing
after reset. The source code for Atom bootloader is located in ``RVATOM/sw/bootloader`` subdirectory. The bootloader can
be built manually using the following *make* command.

.. code-block::
$ cd sw/bootloader
$ make soctarget=hydrogensoc
During run-time, the bootloader uses RAM to implement stack. it includes code for platform initialization, loading
executable and control transfer. Bootloader provides various *bootmodes* to the user allowing the user to control the
boot process.

Following is a list of actions that are performed step-by-step during the boot process:

#. Upon reset the control is transferred to reset vector, which by default points to start of BootROM.
#. CPU starts executing the stage-0 bootloader.
#. Bootloader performs common initialization.
#. Bootloader then performs any platform specific initializations.
#. Bootloader reads the *bootmode* pins and decides the bootmode.
#. Actions are performed according to bootmode, which includes loading the executable into RAM from correct source.
#. Finally, the control is transferred to User program.


Bootmodes
**********

RISC-V Atom bootloader mainly supports 4 boot modes:

+----------+---------------+----------------------------------------------------------------------+
| Pinval | Bootmode | Function |
+==========+===============+======================================================================+
| ``0b00`` | FLASHBoot | Loads a binary image into RAM from FLASH memory using SPI |
+----------+---------------+----------------------------------------------------------------------+
| ``0b01`` | Jump to RAM | Jumps to RAM, without memory initialization |
+----------+---------------+----------------------------------------------------------------------+
| ``0b10`` | UARTBoot | Loads a binary image into RAM from UART stream using XMODEM protocol |
+----------+---------------+----------------------------------------------------------------------+
| ``0b11`` | Infinite Loop | Executes an infinite loop |
+----------+---------------+----------------------------------------------------------------------+

FLASHBoot
==========
In this bootmode, user must write the binary image for the program directly in FLASH memory at a predefined offset value.
During boot, this binary image will be copied as it is to the RAM and will be executed. FLASHBoot requires the SPI IP to
communicate with FLASH memory and will give an boot-panic error if its missing.

UARTBoot
=========
In this mode, the bootloader obtains the program binary image from UART using the
`XMODEM protocol <https://en.wikipedia.org/wiki/XMODEM>`_. It supports XMODEM CRC16 with default packet size of 128 bytes.

Transferring files over UART
-----------------------------
RISC-V Atom project provides the ``xmsend.py`` python script that can be used to transmit binary files over UART. *xmsend*
can be used as follows.

.. code-block:: bash
$ xmsend.py -b 115200 -p /dev/ttyUSB0 firmware.bin
.. tip::
Make sure that no other process (like screen) is using the serial port before invoking the xmsend script.
43 changes: 41 additions & 2 deletions docs/pages/documentation/memory_map.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,45 @@
RISC-V Atom Memory Map and Boot Flow
#####################################
Memory Map and Boot Flow
#########################

Memory Map
***********

The following image shows the memory map of Atom-based SoCs.

.. image:: /diagrams/memory_map.png

The column **C** shows the memory map template for all RISC-V Atom based SoCs. Column **D** and **E** show the memory map
for AtomBones and HydrogenSoC respectively.

Boot Flow
**********
Upon reset, the core jumps to the reset vector (default: ``0x10000``) which points to the start of BootROM. RISC-V Atom
BootROM includes a **stage-0 bootloader** that is automatically built and included when building the AtomSim or running FPGA
builds. The stage-0 bootloader uses RAM for stack. It initializes the platform, loads the user program in RAM and finally
transfers control to the user program. The user program often includes a **stage-1 bootloader** which sets up the runtime
environment and standard library before executing the application.

.. graphviz::

digraph G {
rankdir=LR;
reset_vec [label="Reset Vector", shape=rect, style=filled, fillcolor=white];
subgraph cluster_0 {
style=filled;
fillcolor=gray;
label="BootROM";
stage0_bl [label="Stage-0\nBootloader", shape=rect, style=filled, fillcolor=yellow];
}
subgraph cluster_1 {
style=filled;
fillcolor=gray;
label="RAM";
stage1_bl [label="Stage-1\nBootloader", shape=rect, style=filled, fillcolor=orange];
prog [shape=rect, label="User Program", style=filled, fillcolor=cyan];
stage1_bl -> prog [label="launch"];
}
reset_vec -> stage0_bl;
stage0_bl -> stage1_bl;
}

To know more about the stage-0 bootloader, see :doc:`this</pages/documentation/bootloader>` page.
Loading

0 comments on commit e6108c1

Please sign in to comment.