/wlink

An open source WCH-Link library/command line tool written in Rust.

Primary LanguageRustApache License 2.0Apache-2.0

wlink - WCH-Link(RV) command line tool

Crates.io Crates.io docs.rs GitHub release

Note This tool is still in development and not ready for production use.

Feature Support

  • Flash firmware, support Intel HEX, ELF and raw binary format
  • Erase chip
  • Halt, resume, reset support
  • Read chip info
  • Read chip memory(flash)
  • Read/write chip register - very handy for debugging
  • Code-Protect & Code-Unprotect for supported chips
  • SDI print support, requires 2.10+ firmware
  • Serial port watching for a smooth development experience
  • Windows native driver support, no need to install libusb manually (requires x86 build)

Tested On

Probes

Current firmware version: 2.11 (aka. v31).

NOTE: The firmware version is not the same as the version shown by WCH's toolchain. Because WCH calculates the version number by major * 10 + minor, so the firmware version 2.10 is actually v30 0x020a.

  • WCH-Link CH549 - the first version, reflash required when switching mode
  • WCH-LinkE CH32V305 - the recommended debug probe
  • WCH-LinkW CH32V208 - wireless version
  • WCH-Link? CH32V203

MCU

Note A common misunderstanding is that the CH32V2 and CH32V3 series has fewer flash! No it's not. The CH32V203 series has 224K available flash. The CH32V208 and CH32V30x series has 480K available flash. The number in the datasheet is the "zero-wait-state" flash size, which is not the same as the "available" flash size.

Install

cargo install --git https://github.com/ch32-rs/wlink or download a binary from the Nightly Release page.

Note On Linux, you should install libudev and libusb development lib first. Like sudo apt install libudev-dev libusb-1.0-0-dev on Ubuntu.

Arch Linux

Arch Linux users can install wlink-git via the AUR.

yay -Syu wlink

Usage

Note For help of wire connection for specific chips, please refer to docs subdirectory.

> # Flash firmware.bin to Code FLASH at address 0x08000000
> wlink flash --address 0x08000000 ./firmware.bin
12:10:26 [INFO] WCH-Link v2.10 (WCH-Link-CH549)
12:10:26 [INFO] Attached chip: CH32V30X(0x30700518)
12:10:26 [INFO] Flashing 8068 bytes to 0x08000000
12:10:27 [INFO] Flash done
12:10:28 [INFO] Now reset...
12:10:28 [INFO] Resume executing...

> # Flash firmware.bin to System FLASH, enable SDI print, then watch serial port
> wlink flash --enable-sdi-print --watch-serial firmware.bin
02:54:34 [INFO] WCH-Link v2.11 (WCH-LinkE-CH32V305)
02:54:34 [INFO] Attached chip: CH32V003 [CH32V003F4P6] (ChipID: 0x00300500)
02:54:34 [INFO] Flash already unprotected
02:54:34 [INFO] Flash protected: false
02:54:35 [INFO] Flash done
02:54:35 [INFO] Now reset...
02:54:35 [INFO] Now connect to the WCH-Link serial port to read SDI print
Hello world from ch32v003 SDI print!
led toggle
led toggle
...


> # Dump Code FLASH, for verification
> # use `-v` or `-vv` for more logs
> wlink -v dump 0x08000000 100
18:31:18 [DEBUG] (1) wlink::device: Acquired libusb context.
18:31:18 [DEBUG] (1) wlink::device: Claimed interface 0 of USB device.
18:31:18 [INFO] WCH-Link v2.8 (WCH-LinkE-CH32V305)
18:31:18 [DEBUG] (1) wlink::operations: attached chip: ChipInfo { chip_family: CH32V20X, chip_type: "0x20360510" }
18:31:18 [DEBUG] (1) wlink::operations: Chip UID: cd-ab-b4-ae-45-bc-c6-16
18:31:18 [DEBUG] (1) wlink::operations: flash protected: false
18:31:18 [DEBUG] (1) wlink::operations: SRAM CODE mode: 3
18:31:18 [DEBUG] (1) wlink::operations: RISC-V core version: Some("WCH-V4B")
18:31:18 [INFO] Read memory from 0x08000000 to 0x08000064
08000000:   b7 00 00 08  67 80 80 00  73 50 40 30  73 50 40 34   ×00•g××0sP@0sP@4
08000010:   81 40 01 41  81 41 01 42  81 42 01 43  81 43 01 44   ×@•A×A•B×B•C×C•D
08000020:   81 44 81 46  01 47 81 47  01 48 81 48  01 49 81 49   ×D×F•G×G•H×H•I×I
08000030:   01 4a 81 4a  01 4b 81 4b  01 4c 81 4c  01 4d 81 4d   •J×J•K×K•L×L•M×M
08000040:   01 4e 81 4e  01 4f 81 4f  97 01 00 18  93 81 81 7b   •N×N•O×Oו0•×××{
08000050:   f3 23 40 f1  b7 02 00 00  93 82 02 00  63 f4 72 00   ×#@×ו00×ו0c×r0
08000060:   6f 00 c0 29                                          o0×)


> # Dump System FLASH, BOOT_28KB
> wlink dump 0x1FFF8000 0x7000
....


> # Dump all general purpose registers
> wlink regs
16:24:20 [INFO] Dump GPRs
dpc(pc):   0x2000011a
x0   zero: 0x00000000
x1     ra: 0x49c85c07
x2     sp: 0x20002800
x3     gp: 0x206e24c4
x4     tp: 0x9add07a3
x5     t0: 0xb4a9b38a
....


> # Set dpc(pc) to System Flash
> wlink write-reg 0x7b1 0x000009a8

References