My Longan Nano board has arrived and I tried to run Rust on it. It's a great success and here's how.
Nano is a RISC-V microcontroller (GD32VF103) with impressive GPIO capabilities and connectivity - it has a serial, JTAG and USB Type-C ports plus numerous GPIO pins on breakout connectors. It is also very well documented: there are board schematics, CPU and Peripheral datasheets, and numerous programming examples.
I'm on OSX so your mileage may vary. I started from a blog post here.
I use 📦 cargo-xbuild 
I added some handy changes to the source code here - it is not yet merged as of time of this writing.
With these changes in hand you can simply build a debug version of the example using make.
Next step is to write it to the device. Nano supports DFU protocol of the USB standard which makes it almost easy. Almost, because you need to build a DFU util with Nano support first.
Now you have /usr/local/opt/gd32-dfu-utils/bin/dfu-util which you can use to flash your device.
Add the following to your Makefile to make it even easier:
: Don't forget to use tabs to indent the make commands, otherwise make will complain.
Now actually flashing the device goes as simple as the following:
- Plug your device using USB Type-C cable to your laptop.
- Hold BOOT0 button on the device and press RESET0 button once - this will switch the device to DFU mode.
- Run
make dfuto download the firmware to the device.
You should see the green LED blinking.
Note that I did not use riscv-gnu-toolchain for building as it is generally not required - cargo-binutils can do everything by using the LLVM tools.
JTAG debugger
Since I have a JLink I will write the configuration steps from JLink standpoint.
First of all, figure out the necessary wiring.
Func | JLink Pin | Wire color | Target pin
------+-----------+------------+-----------
TCK | 9 | yellow | JTCK
TMS | 7 | brown | JTMS
TDI | 5 | green | JTDI
TDO | 13 | orange | JTDO
VTref | 1 | white | 3V3
GND | 4 | black | GND
You may choose your own wiring colors of course, I just settled for these and try to keep them consistent between boards.
The OpenOCD for macOS that is bundled with Nano did not work, so I went and built a new one from git.
# This shall clone you a branch called nuclei-cjtag - check that it did
The config file from bundled openocd is however working, so you can copy it from there. I will post it here to save you unnecessary downloads:
openocd_jlink.cfg:
adapter_khz 1000
reset_config srst_only
adapter_nsrst_assert_width 100
interface jlink
jlink usb 0
transport select jtag
set _CHIPNAME riscv
jtag newtap $_CHIPNAME cpu -irlen 5 -expected-id 0x1000563d
set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME riscv -chain-position $_TARGETNAME
$_TARGETNAME configure -work-area-phys 0x20000000 -work-area-size 20480 -work-area-backup 0
# Work-area is a space in RAM used for flash programming
if else
# Allow overriding the Flash bank size
if else
# flash size will be probed
set _FLASHNAME $_CHIPNAME.flash
flash bank $_FLASHNAME gd32vf103 0x08000000 0 0 0 $_TARGETNAME
riscv set_reset_timeout_sec 1
init
halt
Place this file SOMEWHERE and add the following target to your Makefile:
:
With JLink connected to your machine, run make ocd to connect to the device.
)
))
))
))
)))
;
GDB
I built GDB from the riscv-gnu-toolchain sources. While it can step through the instructions and show register contents, it for some reason couldn't properly work with disassembly and source code navigation. I will work more on getting it to work correctly and will update this post when done.
)
)
<http://www.gnu.org/software/gdb/bugs/>.
<http://www.gnu.org/software/gdb/documentation/>.
()
The OpenOCD side at the same time shows GDB connection:
Info : accepting 'gdb' connection on tcp/3333
Info : device id = 0x19060410
Info : flash_size_in_kb = 0x00000080
Info : flash size = 128kbytes
Info : dropped 'gdb' connection
LLDB
Build instructions based on sifive/riscv-llvm.
LLDB at this moment DOES NOT SUPPORT riscv, so it cannot be used.
General GD32VF103 info
longan-nano-gd32vf103 has lots of information.