Search › A-Z › L › Longan Nano

Longan Nano

2019 Open source · CC0 On-board only Online

The Sipeed Longan Nano is a tiny, popular RISC-V dev board built on the GigaDevice GD32VF103CBT6 — a Nuclei "Bumblebee" RV32IMAC core (RISC-V RV32I + M + A + C) at 108 MHz with 128 KB flash and 32 KB SRAM — emulated from scratch in the browser on a from-scratch RISC-V core. Uniquely for this site it is a visual bare-metal target: it runs REAL compiled firmware that drives an on-board 0.96" 160x80 ST7735S colour LCD over SPI0 (colour bars, a streamed gradient bitmap, text), the active-low RGB LED (PC13/PA1/PA2) and a USART0 serial console — with nothing invented: no breadboard, no fake audio (a Longan Nano has no speaker, so it is honestly silent). Because the whole chip is ordinary JavaScript, it plugs into this site's shared debugger: the real RISC-V disassembler, live x0-x31 and the machine CSRs, side-effect-free FLASH / SRAM / peripheral memory at the real addresses, single-instruction step, execution breakpoints and write-watchpoints.

Longan Nano at Sipeed ↗

Runs on: Web browser

Longan Nano Online Emulator

Play Longan Nano using JavaScript directly in your browser.

Configurations

ConfigurationEmulatorMachineOSLegal
LCD Colour BarsLongan NanoLongan NanoopenOpen ⛶
LCD Image (gradient)Longan NanoLongan NanoopenOpen ⛶
RGB LEDLongan NanoLongan NanoopenOpen ⛶
UART HelloLongan NanoLongan NanoopenOpen ⛶

Chips

GigaDevice GD32VF103

Notes

Embedding

This is a two-layer stack: a real RISC-V CPU core underneath, and a from-scratch GD32VF103 SoC + Longan Nano board on top. It loads real RV32IMAC flash images and runs them on the actual on-chip peripherals — RCU clock gating, the GPIO ports, SPI0 (driving the LCD) and USART0 — at their real addresses. The firmware is genuine compiled machine code, not a shim.

  • The CPU. rv32.js is a from-scratch RISC-V interpreter that executes RV32IMAC: the RV32I integer base with all 32 registers x0..x31, the "M" multiply/divide the GD32VF103 has in hardware, the "A" atomics (LR/SC + the AMO read-modify-writes), the "C" 16-bit compressed encodings the compiler emits throughout, plus the Zicsr CSR ops and machine-mode traps (ecall/ebreak/mret).
  • Real reset. The Nuclei core boots executing from the flash base 0x08000000 (also aliased at 0x00000000), where the startup's first instruction is j handle_reset — so the very first instruction fetched is the jump to the reset code, exactly like the silicon.
  • The board, in JavaScript. longan-nano-board.js maps FLASH/SRAM/peripherals at their real GD32VF103 addresses, answers the RCU clock-ready bits, folds GPIO BOP/BC into OCTL, models an ST7735S LCD controller behind SPI0 (D/C on PB0, CS on PB2) so firmware pixels render on the 160x80 screen, captures USART0 output to a serial console, and reflects the RGB LED and BOOT button.
PieceKindWhat it does
LONGANNANO.create(canvas)factoryBuild the RV32IMAC core + the GD32VF103 memory map + peripherals + the ST7735S LCD.
load(bytes) / reset()methodCopy the flat image into FLASH; reset sets PC = 0x08000000 (Nuclei boot) and SP to the top of SRAM.
runFrame()methodStep a batch of instructions and advance the SysTimer counter.
ledColor() / getSerial()methodThe on-board RGB LED state and the accumulated USART0 output.
present()methodDraw the ST7735S framebuffer, the RGB LED, the BOOT button and the serial console.

Debugger integration

longan-nano-debug.js reads window.EMU_BOOT and hands the shared debugger a genuine RISC-V RV32IMAC machine — the same core the firmware runs on, exposed instruction-accurately.

  • Registers. registers() reads all 32 registers x0-x31 (with their ABI names zero/ra/sp/gp/tp/t0../a0../s0../t3..), pc, and the machine CSRs mstatus/mtvec/mepc/mcause live each refresh; the general registers and pc each have a set() that writes straight back into the core (x0 stays hard-wired to zero).
  • Disassembly. FLASH is decoded with the shared riscv decoder (the RISC-V disassembler, which handles the RV32I base plus M, A and the compressed encodings), so the code window shows real RISC-V mnemonics at the real reset address 0x08000000.
  • Single-step. Step calls transport.stepInsn, which advances the core exactly one RISC-V instruction (16- or 32-bit); pc and the registers update after each step.
  • Breakpoints & watchpoints. Execution breakpoints are a pc set the run-loop checks before each instruction; write watchpoints wrap the board's memory-write path and pause when a watched address is written (e.g. SPI0->DATA at 0x4001300C or a GPIO OCTL). Both are real.
  • Controller. The on-board BOOT button (PA8) is wired into the Controller panel; pressing it drives the GPIOA input the firmware polls.
  • Memory map. Three chips read the real address space side-effect-free: FLASH (program, disassembled, 0x08000000), SRAM (0x20000000), and the peripheral block (0x40000000 — RCU, GPIOA/B/C, SPI0, USART0).

Architecture

The Sipeed Longan Nano is a tiny, popular RISC-V dev board built on the GigaDevice GD32VF103CBT6: a Nuclei "Bumblebee" (N200-class) RV32IMAC core at 108 MHz with 128 KB flash and 32 KB SRAM, wrapped around an STM32F1-style peripheral map. Uniquely for this site it is a visual bare-metal target: the board carries an on-board colour LCD. This build models the chip and board from scratch on a from-scratch RISC-V core.

  • Nuclei RV32IMAC CPU — runs the real compiled RISC-V image with all 32 registers, hardware multiply/divide (M), atomics (A) and the compressed encodings (C). FLASH is at 0x08000000, SRAM at 0x20000000, peripherals at 0x40000000. On reset the core executes from the flash base, whose first instruction is j handle_reset.
  • SPI0 + ST7735S LCD — the standout peripheral. Firmware clocks command and pixel bytes out SPI0->DATA; the D/C pin (PB0) selects command vs data and CS (PB2) selects the panel. The board models the ST7735S command set (CASET/RASET address window, RAMWR pixel stream, DISPON) and renders the RGB565 pixels into a 160x80 framebuffer shown on screen — so real drawing code (colour bars, a streamed gradient bitmap, text from a 5x7 font) appears on the emulated display.
  • RGB LED — the on-board LED with R on PC13, G on PA1 and B on PA2, all active-low (a pin driven low lights that colour). Firmware toggles it through the atomic GPIO BOP/BC registers.
  • RCU (Reset & Clock Unit, 0x40021000) — the firmware gates each peripheral's clock through APB2EN before touching it; the board answers the clock-ready bits so real clock-setup code proceeds.
  • USART0 (0x40013800) — the serial port (TX on PA9). Every byte written to DATA is captured onto the on-screen serial console.
  • BOOT button — modelled as a readable input on PA8 (idle high, pressed low) and wired into the Controller panel.
  • Content. Four original CC0 bare-metal C programs compiled with clang for rv32imac: LCD Colour Bars, LCD Image, RGB LED and UART Hello. No proprietary firmware is used.
  • Honest limits. A Longan Nano has no on-board audio (no speaker/DAC), so this emulator is genuinely silent with no sound path. The A (atomics) extension is implemented and advertised in misa but the bundled polling firmware does not exercise it. The ADC, I2C, the TIMER units, DMA, the ECLIC interrupt controller and the microSD slot are not modelled; the firmware polls RCU, GPIO, SPI0 and USART0.