[PATCH v6] docs/user: add docs for riscv/kendrytek210 BSP variant
Alan Cudmore
alan.cudmore at gmail.com
Tue Apr 4 02:09:41 UTC 2023
This patch adds the documentation for building and running RTEMS on the Kendryte K210 RISC-V SoC.
The generic riscv introducion was re-arranged to list the multilib variants then the specific
hardware targets. In addition a couple of errors were fixed for the generic QEMU commands.
V2 corrected a typo, expanded K210 Console UART parameters, and addded a hyperlink to renode.io install
instructions.
V3 clarified the multilib variant description, clarified the multilib variant reference platform, and
corrected capitalization on SiFive.
V4 improves the instructions for running the K210 BSP on the Renode.io simulator.
V5 cleaned up the text to be no more than 80 characters per line.
V6 applied word wrap to paragraphs and replaced hard coded RTEMS major versions with macros.
Closes #4876
---
user/bsps/bsps-riscv.rst | 240 ++++++++++++++++++++++++++++++---------
1 file changed, 188 insertions(+), 52 deletions(-)
diff --git a/user/bsps/bsps-riscv.rst b/user/bsps/bsps-riscv.rst
index 41f369f..b4bdf7b 100644
--- a/user/bsps/bsps-riscv.rst
+++ b/user/bsps/bsps-riscv.rst
@@ -8,7 +8,8 @@ riscv (RISC-V)
riscv
=====
-This BSP offers 12 variants:
+**Each variant in this first group corresponds to a GCC multilib option with
+different RISC-V standard extensions.**
* rv32i
@@ -30,23 +31,26 @@ This BSP offers 12 variants:
* rv64imafdc
-* frdme310arty
+Each variant reflects an ISA with ABI and code model choice. All rv64 BSPs have
+medany code model by default, while rv32 BSPs are medlow. The reason is that
+RV32 medlow can access the entire 32-bit address space, while RV64 medlow can
+only access addresses below 0x80000000. With RV64 medany, it's possible to
+perform accesses above 0x80000000. The BSP must be started in machine mode.
-* mpfs64imafdc
+The reference platforms for the rv* variants include the QEMU `virt` and
+`spike` machines and the Spike RISC-V ISA simulator.
-Each rv* variant corresponds to a GCC multilib. A particular variant reflects an
-ISA with ABI and code model choice. All rv64 BSPs have medany code model by
-default, while rv32 BSPs are medlow. The reason is that RV32 medlow can access
-the entire 32-bit address space, while RV64 medlow can only access addresses
-below 0x80000000. With RV64 medany, it's possible to perform accesses above
-0x80000000.
+**The BSP also provides the following variants for specific hardware targets:**
-The BSP must be started im machine mode.
+* frdme310arty - The reference platform for this variant is the Arty FPGA board
+ with the SiFive Freedom E310 reference design.
-The reference platform for this BSP is the QEMU `virt` machine.
+* mpfs64imafdc - The reference platform for this variant is the Microchip
+ PolarFire SoC Icicle Kit.
+
+* kendrytek210 - The reference platform for this variant is the Kendryte K210
+ SoC on the Sipeed MAiX BiT or Maixduino board.
-The reference platform for the mpfs64imafdc BSP variant is the Microchip
-PolarFire SoC Icicle Kit.
Build Configuration Options
---------------------------
@@ -77,33 +81,41 @@ configuration INI file. The ``waf`` defaults can be used to inspect the values.
The path to the header file containing the device tree blob.
``BSP_CONSOLE_BAUD``
- The default baud for console driver devices (default 115200).
+ The default baud for console driver devices (default is 115200).
``RISCV_MAXIMUM_EXTERNAL_INTERRUPTS``
The maximum number of external interrupts supported by the BSP (default
- 64).
+ is 64).
``RISCV_ENABLE_HTIF_SUPPORT``
Enable the Host/Target Interface (HTIF) support (enabled by default).
``RISCV_CONSOLE_MAX_NS16550_DEVICES``
- The maximum number of NS16550 devices supported by the console driver (2
- by default).
+ The maximum number of NS16550 devices supported by the console driver
+ (default is 2).
+
+``RISCV_ENABLE_SIFIVE_UART_SUPPORT``
+ Enable the SiFive console UART (disabled by default).
``RISCV_RAM_REGION_BEGIN``
- The begin of the RAM region for linker command file (default is 0x80000000).
+ The begin of the RAM region for linker command file
+ (default is 0x80000000).
``RISCV_RAM_REGION_SIZE``
The size of the RAM region for linker command file (default 64MiB).
``RISCV_ENABLE_FRDME310ARTY_SUPPORT``
Enables support sifive Freedom E310 Arty board if defined to a non-zero
- value,otherwise it is disabled (disabled by default)
+ value,otherwise it is disabled (disabled by default).
``RISCV_ENABLE_MPFS_SUPPORT``
Enables support Microchip PolarFire SoC if defined to a non-zero
value, otherwise it is disabled (disabled by default).
+``RISCV_ENABLE_KENDRYTE_K210_SUPPORT``
+ Enables support for the Kendtryte K210 SoC if defined to a non-zero
+ value, otherwise it is disabled (disabled by default).
+
``RISCV_BOOT_HARTID``
The boot hartid (processor number) of risc-v cpu by default 0.
@@ -123,15 +135,15 @@ The clock driver uses the CLINT timer.
Console Driver
--------------
-The console driver supports devices compatible to
+The console driver supports devices compatible to:
* "ucb,htif0" (depending on the ``RISCV_ENABLE_HTIF_SUPPORT`` BSP option),
-* "ns16550a" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option), and
+* "ns16550a" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option),
-* "ns16750" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option).
+* "ns16750" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option), and
-* "sifive,uart0" (see ``RISCV_ENABLE_FRDME310ARTY_SUPPORT`` BSP option).
+* "sifive,uart0" (see ``RISCV_ENABLE_SIFIVE_UART_SUPPORT`` BSP option).
They are initialized according to the device tree. The console driver does not
configure the pins or peripheral clocks. The console device is selected
@@ -145,43 +157,48 @@ and spike machines. For instance, to run the ``rv64imafdc`` BSP with the
following "config.ini" file.
.. code-block:: none
+
[riscv/rv64imafdc]
Run the following QEMU command.
.. code-block:: shell
+
$ qemu-system-riscv64 -M virt -nographic -bios $RTEMS_EXE
$ qemu-system-riscv64 -M spike -nographic -bios $RTEMS_EXE
Spike
----
-All of the BSP variants that start with rv can be run on Spike.
-For instance, to run the ``rv64imafdc`` BSP with the following
-"config.ini" file.
+
+All of the BSP variants that start with rv can be run on Spike. For instance,
+to run the ``rv64imafdc`` BSP with the following "config.ini" file.
.. code-block:: none
+
[riscv/rv64imafdc]
Run the following Spike command.
.. code-block:: shell
+
$ spike --isa=rv64imafdc $RTEMS_EXE
-Unlike QEMU, Spike supports enabling/disabling a subset of the imafdc extensions
-and has support for further RISC-V extensions as well. A fault will be triggered
-if an executable built with rv64imafdc RISC-V's -march option run on Spike with
---isa=rv64i option. If no --isa option is specified, the default is rv64imafdc.
+Unlike QEMU, Spike supports enabling/disabling a subset of the imafdc
+extensions and has support for further RISC-V extensions as well. A fault will
+be triggered if an executable built with rv64imafdc RISC-V's -march option run
+on Spike with --isa=rv64i option. If no --isa option is specified, the default
+is rv64imafdc.
Microchip PolarFire SoC
-----------------------
-The PolarFire SoC is the 4x 64-bit RISC-V U54 cores and a 64-bit RISC-V
-E51 monitor core SoC from the Microchip.
+The PolarFire SoC is the 4x 64-bit RISC-V U54 cores and a 64-bit RISC-V E51
+monitor core SoC from the Microchip.
The ``mpfs64imafdc`` BSP variant supports the U54 cores but not the E51 because
-the E51 monitor core is reserved for the first stage bootloader
-(Hart Software Services). In order to boot from the first U54 core,
-``RISCV_BOOT_HARTID`` is set to 1 by default.
+the E51 monitor core is reserved for the first stage bootloader (Hart Software
+Services). In order to boot from the first U54 core, ``RISCV_BOOT_HARTID`` is
+set to 1 by default.
The device tree blob is embedded in the ``mpfs64imafdc`` BSP variant by default
with the ``BSP_DTB_IS_SUPPORTED`` enabled and the DTB header path
@@ -204,14 +221,14 @@ Build RTEMS.
.. code-block:: shell
- $ ./waf configure --prefix=$HOME/rtems-start/rtems/6
+ $ ./waf configure --prefix=$HOME/rtems-start/rtems/@rtems-ver-major@
$ ./waf
Convert .exe to .elf file.
.. code-block:: shell
- $ riscv-rtems6-objcopy build/riscv/mpfs64imafdc/testsuites/smptests/smp01.exe build/riscv/mpfs64imafdc/testsuites/smptests/smp01.elf
+ $ riscv-rtems at rtems-ver-major@-objcopy build/riscv/mpfs64imafdc/testsuites/smptests/smp01.exe build/riscv/mpfs64imafdc/testsuites/smptests/smp01.elf
Generate a payload for the `smp01.elf` using the `hss-payload-generator <https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator>`_.
@@ -277,14 +294,135 @@ Serial terminal UART1 displays the SMP example messages
*** END OF TEST SMP 1 ***
+Kendryte K210
+-------------
+
+The Kendryte K210 SoC is a dual core 64-bit RISC-V SoC with an AI NPU, built in
+SRAM, and a variety of peripherals. Currently just the console UART, interrupt
+controller, and timer are supported.
+
+The device tree blob is embedded in the ``kendrytek210`` BSP variant by
+default. When the kendrytek210 BSP variant is selected,
+``BSP_DTB_IS_SUPPORTED`` enabled and the DTB header path
+``BSP_DTB_HEADER_PATH`` is set to ``bsp/kendryte-k210-dtb.h``.
+
+The ``kendrytek210`` BSP variant has been tested on the following simulator and
+boards:
+
+* Renode.io simulator using the Kendrtye k210 model
+* Sipeed MAiX BiT board
+* Sipeed Maixduino board
+* Sipeed MAiX Dock board
+
+**Building the Kendryte K210 BSP**
+
+Configuration file ``config.ini``:
+
+.. code-block:: none
+
+ [riscv/kendrytek210]
+ RTEMS_SMP = True
+
+Build RTEMS:
+
+.. code-block:: shell
+
+ $ ./waf configure --prefix=$HOME/rtems-start/rtems/@rtems-ver-major@
+ $ ./waf
+
+**Flash an executable to a supported K210 board**
+
+Binary images can be flashed to the Sipeed boards through the USB port using
+the ``kflash.py`` utility available from the python pip utility.
+
+.. code-block:: shell
+
+ $ riscv-rtems at rtems-ver-major@-objcopy -Obinary ticker.exe ticker.bin
+ $ kflash.py --uart /dev/ttyUSB0 ticker.bin
+
+After the image is flashed, the RTEMS image will automatically boot. It will
+also run when the board is reset or powered through the USB cable. The USB port
+provides the power and console UART. Plug the USB cable into a host PC and
+bring up a terminal emulator at 115200 baud, 8 data bits, 1 stop bit, no
+parity, and no flow control. On Linux the UART device is often
+``/dev/ttyUSB0``.
+
+**Run a RTEMS application on the Renode.io simulator**
+
+RTEMS executables compiled with the kendrytek210 BSP can run on the renode.io
+simulator using the built-in K210 model. The simulator currently supports the
+console UART, interrupt controller, and timer.
+
+To install renode.io please refer to the `installation instructions <https://github.com/renode/renode#installation>`_.
+Once installed, save the following file as `k210_rtems.resc`.
+
+.. code-block:: shell
+
+ using sysbus
+
+ $bin?=@ticker.exe
+
+ mach create "K210"
+
+ machine LoadPlatformDescription @platforms/cpus/kendryte_k210.repl
+
+ showAnalyzer uart
+
+ sysbus Tag <0x50440000 0x10000> "SYSCTL"
+ sysbus Tag <0x50440018 0x4> "pll_lock" 0xFFFFFFFF
+ sysbus Tag <0x5044000C 0x4> "pll1"
+ sysbus Tag <0x50440008 0x4> "pll0"
+ sysbus Tag <0x50440020 0x4> "clk_sel0"
+ sysbus Tag <0x50440028 0x4> "clk_en_cent"
+ sysbus Tag <0x5044002c 0x4> "clk_en_peri"
+
+ macro reset
+ """
+ sysbus LoadELF $bin
+ """
+ runMacro $reset
+
+After saving the above file in in the same directory as your RTEMS ELF images,
+start renode and load the `k210_rtems.resc` script to start the emulation.
+
+.. code-block:: shell
+
+ (monitor) s @k210_rtems.resc
+
+You should see a renode UART window and the RTEMS ticker example output. If you
+want to run a different RTEMS image, you can edit the file or enter the
+following on the renode console.
+
+.. code-block:: shell
+
+ (monitor) $bin=@smp08.exe
+ (monitor) s @k210_rtems.resc
+
+The above example will run the SMP08 example instead of ticker.
+
+**Generating the Device Tree Header**
+
+The kendrytek210 BSP uses a built in device tree blob. If additional peripheral
+support is added to the BSP, the device tree may need to be updated. After
+editing the device tree source, compile it to a device tree blob with the
+following command:
+
+.. code-block:: shell
+
+ $ dtc -O dtb -b 0 -o kendryte-k210.dtb kendryte-k210.dts
+
+The dtb file can then be converted to a C array using the rtems-bin2c tool.
+The data for the device tree binary can then replace the existing device tree
+binary data in the ``kendryte-k210-dtb.h`` header file.
+
noel
====
-This BSP supports the `NOEL-V <https://gaisler.com/noel-v>`_ systems from Cobham
-Gaisler. The NOEL-V is a synthesizable VHDL model of a processor that
-implements the RISC-V architecture. It is part of the open source
-`GRLIB <https://gaisler.com/grlib>`_ IP Library. The following BSP
-variants correspond to common NOEL-V configurations:
+This BSP supports the `NOEL-V <https://gaisler.com/noel-v>`_ systems from
+Cobham Gaisler. The NOEL-V is a synthesizable VHDL model of a processor that
+implements the RISC-V architecture. It is part of the open source `GRLIB
+<https://gaisler.com/grlib>`_ IP Library. The following BSP variants correspond
+to common NOEL-V configurations:
* noel32im
@@ -296,20 +434,18 @@ variants correspond to common NOEL-V configurations:
* noel64imafdc
-The start of the memory is set to 0x0 to match a standard NOEL-V system,
-but can be changed using the ``RISCV_RAM_REGION_BEGIN`` configuration
-option. The size of the memory is taken from the information available
-in the device tree.
+The start of the memory is set to 0x0 to match a standard NOEL-V system, but
+can be changed using the ``RISCV_RAM_REGION_BEGIN`` configuration option. The
+size of the memory is taken from the information available in the device tree.
Reference Designs
-----------------
-The BSP has been tested with NOEL-V reference designs for
-`Digilent Arty A7 <https://gaisler.com/noel-artya7>`_,
-`Microchip PolarFire Splash Kit <https://gaisler.com/noel-pf>`_,
-and `Xilinx KCU105 <https://gaisler.com/noel-xcku>`_.
-See the accompanying quickstart guide for each reference design
-to determine which BSP configuration to use.
+The BSP has been tested with NOEL-V reference designs for `Digilent Arty A7
+<https://gaisler.com/noel-artya7>`_, `Microchip PolarFire Splash Kit
+<https://gaisler.com/noel-pf>`_, and `Xilinx KCU105
+<https://gaisler.com/noel-xcku>`_. See the accompanying quickstart guide for
+each reference design to determine which BSP configuration to use.
Build Configuration Options
---------------------------
--
2.25.1
More information about the devel
mailing list