-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
11 changed files
with
956 additions
and
162 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
Oops, something went wrong.