======= rv-virt ======= RISC-V Toolchain ================ Any generic RISC-V toolchain can be used. It's recommended to use the same toolchain used by NuttX CI. Please refer to the `Docker container `_ and check for the current compiler version being used. For instance: .. code-block:: ############################################################################### # Build image for tool required by RISCV builds ############################################################################### FROM nuttx-toolchain-base AS nuttx-toolchain-riscv # Download the latest RISCV GCC toolchain prebuilt by xPack RUN mkdir riscv-none-elf-gcc && \ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ | tar -C riscv-none-elf-gcc --strip-components 1 -xz It uses the xPack's prebuilt toolchain based on GCC 13.2.0-2. RISC-V QEMU =========== Build and install ``qemu``:: $ git clone https://github.com/qemu/qemu $ cd qemu $ ./configure --target-list=riscv32-softmmu,riscv64-softmmu $ make $ sudo make install QEMU 7.2.9 or later and OpenSBI v1.1 or later (usually shipped with QEMU) is required, to support RISC-V "Sstc" Extension. It is also recommended to use the latest QEMU and OpenSBI. For users who wish to use their own OpenSBI, please refer to `OpenSBI repository `_. Configurations ============== All of the configurations presented below can be tested by running the following commands:: $ ./tools/configure.sh rv-virt: Where is the name of the configuration you want to use, i.e.: nsh, knsh32, knsh64... To build it, run the following command:: $ make -j$(nproc) or, with more verbosity:: $ make V=1 -j$(nproc) .. warning:: Some configurations require additional steps to be built. Please refer to the specific configurations to check it out Finally, to run it, use the following command: For 32-bit configurations:: $ qemu-system-riscv32 -semihosting -M virt,aclint=on -cpu rv32 -smp 8 -bios none -kernel nuttx -nographic And, for 64-bit configurations:: $ qemu-system-riscv64 -semihosting -M virt,aclint=on -cpu rv64 -smp 8 -bios none -kernel nuttx -nographic If testing with kernel build, remove the ``-bios none`` option. Kernel build requires SBI to function properly. citest ------ This configuration is the default configuration intended to be used by the automated testing on CI of 32-bit RISC-V using QEMU. To run it with QEMU, use the following command:: $ qemu-system-riscv32 -semihosting -M virt -cpu rv32 \ -drive index=0,id=userdata,if=none,format=raw,file=./fatfs.img \ -device virtio-blk-device,bus=virtio-mmio-bus.0,drive=userdata \ -bios none -kernel nuttx -nographic To run the CI scripts, use the following command:: $ ./nuttx/boards/risc-v/qemu-rv/rv-virt/configs/citest/run citest64 -------- Identical to the `citest`_ configuration, but for 64-bit RISC-V. fb -- Uses the VirtIO GPU driver to run the `fb` demo application on 32-bit RISC-V. To run it with QEMU, use the following command:: $ qemu-system-riscv32 -semihosting -M virt -cpu rv32 -smp 8 \ -chardev stdio,id=con,mux=on \ -serial chardev:con \ -device virtio-gpu-device,xres=640,yres=480,bus=virtio-mmio-bus.0 \ -mon chardev=con,mode=readline \ -bios none -kernel nuttx fb64 ---- Identical to the `fb`_ configuration, but for 64-bit RISC-V. To run it with QEMU, use the following command:: $ qemu-system-riscv64 -semihosting -M virt -cpu rv64 -smp 8 \ -chardev stdio,id=con,mux=on \ -serial chardev:con \ -device virtio-gpu-device,xres=640,yres=480,bus=virtio-mmio-bus.0 \ -mon chardev=con,mode=readline \ -bios none -kernel nuttx knetnsh64 --------- Similar to the `knsh32`_ configuration, but with networking support and 64-bit RISC-V. To run it with QEMU, use the following command:: $ dd if=/dev/zero of=./mydisk-1gb.img bs=1M count=1024 $ qemu-system-riscv64 -semihosting -M virt,aclint=on -cpu rv64 -smp 8 \ -global virtio-mmio.force-legacy=false \ -device virtio-serial-device,bus=virtio-mmio-bus.0 \ -chardev socket,telnet=on,host=127.0.0.1,port=3450,server=on,wait=off,id=foo \ -device virtconsole,chardev=foo \ -device virtio-rng-device,bus=virtio-mmio-bus.1 \ -netdev user,id=u1,hostfwd=tcp:127.0.0.1:10023-10.0.2.15:23,hostfwd=tcp:127.0.0.1:15001-10.0.2.15:5001 \ -device virtio-net-device,netdev=u1,bus=virtio-mmio-bus.2 \ -drive file=./mydisk-1gb.img,if=none,format=raw,id=hd \ -device virtio-blk-device,bus=virtio-mmio-bus.3,drive=hd \ -kernel ./nuttx/nuttx -nographic knetnsh64_smp ------------- Similar to the `knetnsh64`_ configuration, but with SMP support for 64-bit RISC-V. knsh32 ------ This is similar to the `nsh`_ configuration except that NuttX is built as a kernel-mode, monolithic module, and the user applications are built separately. It uses `hostfs` and QEMU in semi-hosting mode to load the user-space applications. This is intended to 32-bit RISC-V. To build it, use the following command:: $ make V=1 -j$(nproc) $ make export V=1 -j$(nproc) $ pushd ../apps $ ./tools/mkimport.sh -z -x ../nuttx/nuttx-export-*.tar.gz $ make import V=1 -j$(nproc) $ popd Run it with QEMU using the default command for 32-bit RISC-V. In `nsh`, applications can be run from the `/system/bin` directory:: nsh> /system/bin/hello .. _knsh32_paging: knsh32_paging ------------- Similar to ``knsh32_romfs``, but enabling on-demand paging: this configuration simulates a 4MiB device (using QEMU), but sets the number of heap pages equal to ``CONFIG_ARCH_HEAP_NPAGES=2048``. This means that each process's heap is 8MiB, whereas ``CONFIG_POSIX_SPAWN_DEFAULT_STACKSIZE`` is ``1048576`` (1MiB) represents the stack size of the processes (which is allocated from the process's heap). This configuration is used for 32-bit RISC-V which implements the Sv32 MMU specification and enables processes to have their own address space larger than the available physical memory. This is particularly useful for implementing a set of programming language interpreters. knsh32_romfs ------------ Similar to the `knsh32`_ configuration, but uses ROMFS instead of `hostfs`. A ROMFS image is generated and linked to the kernel. This requires re-running ``make``:: $ make V=1 -j$(nproc) $ make export V=1 -j$(nproc) $ pushd ../apps $ ./tools/mkimport.sh -z -x ../nuttx/nuttx-export-*.tar.gz $ make import V=1 -j$(nproc) $ ./tools/mkromfsimg.sh ../nuttx/arch/risc-v/src/board/romfs_boot.c $ popd $ make V=1 -j$(nproc) To run it, use the following command:: $ qemu-system-riscv32 -M virt,aclint=on -cpu rv32 -smp 8 -kernel nuttx -nographic In `nsh`, applications can be run from the `/system/bin` directory:: nsh> /system/bin/hello knsh64 ------ Similar to the `knsh32`_ configuration, but for 64-bit RISC-V. Run it with QEMU using the default command for 64-bit RISC-V. In `nsh`, applications can be run from the `/system/bin` directory:: nsh> /system/bin/hello ksmp64 ------ Identical to the `knsh64`_ configuration but with SMP support. netnsh ------ Similar to the `nsh`_ configuration, but with networking support for 32-bit RISC-V. To run it with QEMU, use the following command:: $ dd if=/dev/zero of=./mydisk-1gb.img bs=1M count=1024 $ qemu-system-riscv32 -semihosting -M virt,aclint=on -cpu rv32 -smp 8 \ -global virtio-mmio.force-legacy=false \ -device virtio-serial-device,bus=virtio-mmio-bus.0 \ -chardev socket,telnet=on,host=127.0.0.1,port=3450,server=on,wait=off,id=foo \ -device virtconsole,chardev=foo \ -device virtio-rng-device,bus=virtio-mmio-bus.1 \ -netdev user,id=u1,hostfwd=tcp:127.0.0.1:10023-10.0.2.15:23,hostfwd=tcp:127.0.0.1:15001-10.0.2.15:5001 \ -device virtio-net-device,netdev=u1,bus=virtio-mmio-bus.2 \ -drive file=./mydisk-1gb.img,if=none,format=raw,id=hd \ -device virtio-blk-device,bus=virtio-mmio-bus.3,drive=hd \ -bios none -kernel ./nuttx/nuttx -nographic netnsh64 -------- Similar to the `netnsh`_ configuration, but for 64-bit RISC-V. To run it with QEMU, use the following command:: $ dd if=/dev/zero of=./mydisk-1gb.img bs=1M count=1024 $ qemu-system-riscv64 -semihosting -M virt,aclint=on -cpu rv64 -smp 8 \ -global virtio-mmio.force-legacy=false \ -device virtio-serial-device,bus=virtio-mmio-bus.0 \ -chardev socket,telnet=on,host=127.0.0.1,port=3450,server=on,wait=off,id=foo \ -device virtconsole,chardev=foo \ -device virtio-rng-device,bus=virtio-mmio-bus.1 \ -netdev user,id=u1,hostfwd=tcp:127.0.0.1:10023-10.0.2.15:23,hostfwd=tcp:127.0.0.1:15001-10.0.2.15:5001 \ -device virtio-net-device,netdev=u1,bus=virtio-mmio-bus.2 \ -drive file=./mydisk-1gb.img,if=none,format=raw,id=hd \ -device virtio-blk-device,bus=virtio-mmio-bus.3,drive=hd \ -bios none -kernel ./nuttx/nuttx -nographic netnsh64_smp ------------ Similar to the `netnsh64`_ configuration, but with SMP support for 64-bit RISC-V. To run it with QEMU, use the following command:: $ dd if=/dev/zero of=./mydisk-1gb.img bs=1M count=1024 $ qemu-system-riscv64 -semihosting -M virt,aclint=on -cpu rv64 -smp 8 \ -global virtio-mmio.force-legacy=false \ -device virtio-serial-device,bus=virtio-mmio-bus.0 \ -chardev socket,telnet=on,host=127.0.0.1,port=3450,server=on,wait=off,id=foo \ -device virtconsole,chardev=foo \ -device virtio-rng-device,bus=virtio-mmio-bus.1 \ -netdev user,id=u1,hostfwd=tcp:127.0.0.1:10023-10.0.2.15:23,hostfwd=tcp:127.0.0.1:15001-10.0.2.15:5001 \ -device virtio-net-device,netdev=u1,bus=virtio-mmio-bus.2 \ -drive file=./mydisk-1gb.img,if=none,format=raw,id=hd \ -device virtio-blk-device,bus=virtio-mmio-bus.3,drive=hd \ -bios none -kernel ./nuttx/nuttx -nographic netnsh_smp ---------- Similar to the `netnsh`_ configuration, but with SMP support for 32-bit RISC-V. To run it with QEMU, use the following command:: $ dd if=/dev/zero of=./mydisk-1gb.img bs=1M count=1024 $ qemu-system-riscv32 -semihosting -M virt,aclint=on -cpu rv32 -smp 8 \ -global virtio-mmio.force-legacy=false \ -device virtio-serial-device,bus=virtio-mmio-bus.0 \ -chardev socket,telnet=on,host=127.0.0.1,port=3450,server=on,wait=off,id=foo \ -device virtconsole,chardev=foo \ -device virtio-rng-device,bus=virtio-mmio-bus.1 \ -netdev user,id=u1,hostfwd=tcp:127.0.0.1:10023-10.0.2.15:23,hostfwd=tcp:127.0.0.1:15001-10.0.2.15:5001 \ -device virtio-net-device,netdev=u1,bus=virtio-mmio-bus.2 \ -drive file=./mydisk-1gb.img,if=none,format=raw,id=hd \ -device virtio-blk-device,bus=virtio-mmio-bus.3,drive=hd \ -bios none -kernel ./nuttx/nuttx -nographic nsh --- Configures the NuttShell (nsh) located at examples/nsh. This NSH configuration is focused on low-level, command-line driver testing. This configuration is used for 32-bit RISC-V nsh64 ----- Identical to the `nsh`_ configuration, but for 64-bit RISC-V. smp --- Similar to the `nsh`_ configuration, but with SMP support. This configuration is used for 32-bit RISC-V smp64 ----- Similar to the `nsh`_ configuration, but with SMP support This configuration is used for 64-bit RISC-V RISC-V GDB Debugging ==================== First of all, make sure to select ``CONFIG_DEBUG_SYMBOLS=y`` in `menuconfig`. After building the kernel (and the applications, in kernel mode), use the toolchain's GDB to debug RISC-V applications. For instance, if you are using the xPack's prebuilt toolchain, you can use the following command to start GDB:: $ riscv-none-elf-gdb-py3 -ix tools/gdb/__init__.py --tui nuttx To use QEMU for debugging, one should add the parameters ``-s -S`` to the QEMU command line. For instance:: $ qemu-system-riscv32 -semihosting -M virt,aclint=on -cpu rv32 -smp 8 -bios none -kernel nuttx -nographic -s -S Then, in GDB, use the following command to connect to QEMU:: $ target extended-remote localhost:1234 Debugging Applications in Kernel Mode ------------------------------------- In kernel mode, only the kernel symbols are loaded by default. If needed, one should also load the application symbols using the following command:: $ add-symbol-file
``address`` refers to the ``.text`` section of the application and can be retrieved from the ELF file using the following command:: $ riscv-none-elf-readelf -WS | grep .text For instance, to check the ``.text`` section address of the ``hello`` application, use the following command:: $ riscv-none-elf-readelf -WS ../apps/bin/hello | grep .text [ 1] .text PROGBITS c0000000 001000 0009e0 00 AX 0 0 2 .. note:: Pay attention that ``riscv-none-elf-readelf`` refers to your toolchain's readelf utility. Adjust accordingly if you are using a different toolchain. Then, look for the ``.text`` section address and use the ``c0000000`` as the address to load the symbols. For instance, if you want to load the ``hello`` application, you can use the following command in GDB:: $ add-symbol-file ../apps/bin/hello 0xc0000000 Then, you can set breakpoints, step through the code, and inspect the memory and registers of the applications too.