Use gdb to download linux images and debug

This document guides customers how to download the image to the fpga board through jtag to run, to avoid burning flash every time debugging, especially the image that has just been transplanted, which may have more problems. Improve debugging efficiency.

This is mainly for BOOT_MODE=flash mode, to avoid you have to download freeloader.elf to flash for a long time due to flash programing is time costing for large size freeloader.elf

software：Nuclei Linux SDK dev_nuclei_5.10_v2 branch #2 hardware：ux900 bitfile + vcu118 or ku060

Here we just take one linux sdk branch and our evaluation board as example, you can take reference for your own development board.

You should always follow this guidance to port linux to your SoC, see #21

Compile SDK

Assume you don't have a SPI can access to SDCard.

Assume you are using a RV64 CPU.

If you are using a RV32 CPU, need to change ux to u for below CORE settings

If you are not using evalsoc, please set SOC=, change <yoursoc> to the real soc name of yours
You have to choose BOOT_MODE=flash, pass it in each make, or directly update it in Makefile
CORE parameter should be matched with your bitfile, if your bitfile is not support double float, you should set CORE=ux900, otherwise CORE=ux900fd
Then modify the Makefile's BOOT_MODE, CORE and SOC according to above settings
according to your hardware to set CPU frequency CPU_HZ

more detail info about compile sdk, please refer to Nuclei Linux SDK README

Before you build SDK, make sure you have not build SDK before with a different CORE and BOOT_MODE settings

Here I am using evalsoc, so the work folder is work/evalsoc

Here I assume you have modified the Makefile as request above.

IMPORTANT, if you need to change CORE/SOC/BOOT_MODE, please rename work folder to other name such as work_20240308, and build it again.

BOOT_MODE=flash is always required for this case.

make CPU_HZ=50000000 freeloader -j16

After compiling, you will see the output image in the nuclei-linux-sdk/work/evalsoc/freeloader/ directory:

nuclei-linux-sdk$ ls work/evalsoc/freeloader/
fdt.dtb         freeloader.dasm  freeloader.map  kernel.bin  opensbi.bin          u-boot.bin
freeloader.bin  freeloader.elf   initrd.bin      memory.lds

Maybe the first time you are not be able to bring up linux for your SoC using the freeloader.elf, you can try to use gdb to help to speed up your program speed via directly load opensbi/uboot/linux/dtb to ddr memory and can debug linux.

config gdb download script

See https://sourceware.org/gdb/documentation/ for gdb usage.

You can configure gdb download script based on your soc hardware.
the gdb script reset hardware before download image using monitor reset halt
restore command can fill image into ddr, if you don't want to download some image, you can add # to the beginning to the line to comment it.
- eg. If you just want to download opensbi, uboot and dtb, you can comment out kernel and rootfs image
- dtb is always required.
generally focusing on below a few parameters:
- ddr_base: config your soc ddr base address
- thread_num: config your smp core numbers，core should be found by openocd, if openocd config file only connect 1 core, you should set thread_num to 1
- Please check the TODO items in the script file

[!NOTE] If you want to use smp cores, please update your openocd configuration file to support smp, contact with our AE for help in updating this smp openocd configuration file.

set $opensbi_base=$ddr_base + 0x0
set $uboot_base=$ddr_base + 0x200000
set $fdt_base=$ddr_base + 0x8000000
set $kernel_base=$ddr_base + 0x3000000
set $rootfs_base=$ddr_base + 0x8300000

each image load address should be same with nuclei-linux-sdk/freeloader/freeloader.S

if your change freeloader.S image load address, you should change gdb script accordingly.

download images to ddr

place your gdb download script to nuclei-linux-sdk/work/evalsoc/freeloader/ directory

nuclei-linux-sdk/work/evalsoc/freeloader$ ls
fdt.dtb         freeloader.dasm  freeloader.map  kernel.bin           memory.lds   u-boot.bin
freeloader.bin  freeloader.elf   initrd.bin      load_image.gdb_init  opensbi.bin

startup gdb

NOTE: Each time, you have made changes to code, and want to reboot, you need to rebuild images, and download it again, and debug it.

[!NOTE] If you are still debugging it, we strongly recommend you execute the command list in the gdb script line by line for single core version(no need to have the while loop in it) to help you debug which command is failing.

First startup openocd, then execute gdb from nuclei-linux-sdk/work/evalsoc/freeloader/ directory to connect openocd.

load_image.gdb_init is modified based on gdb download script of previous steps

nuclei-linux-sdk/work/evalsoc/freeloader/$ riscv64-unknown-linux-gnu-gdb
GNU gdb (GDB) 13.2.90.20230712-git
Copyright (C) 2023 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-pc-linux-gnu --target=riscv64-unknown-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
# 192.168.40.52:3333 is my port, please change to your correct port
(gdb) target remote 192.168.40.52:3333
Remote debugging using 192.168.40.52:3333
warning: No executable has been specified and target does not support
determining executable automatically.  Try using the "file" command.
warning: multi-threaded target stopped without sending a thread-id, using first non-exited thread
0xffffffff8000334e in ?? ()
(gdb) source load_image.gdb_init
JTAG tap: riscv.cpu tap/device found: 0x16000a6d (mfg: 0x536 (Nuclei System Technology Co Ltd), part: 0x6000, ver: 0x1)
init hardware....
[Switching to thread 1 (Thread 1)]
#0  0x0000000020000000 in ?? ()
[Switching to thread 2 (Thread 2)]
#0  0x0000000020000000 in ?? ()
[Switching to thread 1 (Thread 1)]
#0  0x0000000020000000 in ?? ()
load image ....
Restoring binary file opensbi.bin into memory (0x80000000 to 0x80041e98)
Restoring binary file u-boot.bin into memory (0x80200000 to 0x802678a0)
Restoring binary file fdt.dtb into memory (0x88000000 to 0x88001377)
Restoring binary file kernel.bin into memory (0x83000000 to 0x8342a885)
Restoring binary file initrd.bin into memory (0x88300000 to 0x88a71926)
start run ....
(gdb)

Above load_image.gdb_init script will do continue in the end of the script, you can remove it, if you want to execute it in gdb by yourself.

If you want to debug in IDE, you can refer to https://github.com/Nuclei-Software/nuclei-linux-sdk/wiki/Debug-Linuxsdk-using-NucleiStudio

If you are now able to execute in gdb, and successfully bring up linux with several tries, then you can rebuild freeloader and program the freeloader.elf, you may be able to bring up now.

Nuclei-Software / nuclei-linux-sdk