islandc/wch-riscv-devcontainer repository overview

⁠wch-riscv-devcontainer

WCH-IC RISC-V development and debugging environment inside a VSCode devcontainer.

⁠Packages

• MounRiver Studio II (MRS2)⁠ Version 2.5.0
  • WCH-custom GNU toolchain for RISC-V Version 15.2.0
  • WCH-custom OpenOCD Version 0.11.0
  • ISP Firmware Version v41
  • SVD files
• CH32X035 PIOC Assembler⁠ Version 3.1
• CMake⁠ Version 4.4.2
• ch32-rs/wchisp⁠ Version 0.3.0
• ch32-rs/wlink⁠ Version 0.1.2

⁠System Requirements

• VSCode Dev Containers⁠ extension
• (WSL only) usbipd-win⁠

⁠Usage

• Include this repo as .devcontainer in the root of your project
• Connect debug probe
  • (WSL only) attach to WSL using usbipd attach --wsl --busid <...>. This needs to be completed before starting the Dev Container.
• Select Dev Containers: Reopen in Container

For CMake projects:

• Upon prompt, select the WCH RISC-V Toolchain x.x CMake Kit.
  • The toolchain file is located at /opt/gcc-riscv-none-elf/gcc-riscv-none-elf.cmake⁠
  • The CMake Kit definition for VS Code is located at /opt/devcontainer/cmake-tools-kits.json⁠
• Run CMake: Configure
• Build using CMake: Build [F7]

⁠CMake+IntelliSense Notes

Upon first run, an error message may appear in Line 1, Column 1. Try re-running CMake configuration, or run a build. If the file is a .h header file, it needs to be #include'd into a C module.

⁠UDEV Rules installation

In order to use USB debug probes within the container, some udev rules need to be installed on the host machine. A setup script has been provided to aid with installation.

• Run setup-devcontainer inside the container

• Close the container, and re-open the work directory on your host

• Run the install-rules script inside .vscode/setup/ on your host machine

  cd .vscode/setup
  sudo ./install-rules
  

  Copy

⁠WCH-Link Firmware Update

Firmware update files are provided in /opt/wch/firmware/ and can be programmed using the wchisp utility. See the wchisp GitHub repository⁠ for more information.

See the WCH-Link User Manual⁠ about updating your programmer and to determine which firmware file to use.

wchisp flash /opt/wch/firmware/<isp-specific firmware file>

⁠OpenOCD Config File

Configuration files for the OpenOCD debugger are included in /opt/openocd/bin/. To start the debugger, run the following command inside the devcontainer terminal:

openocd -f /opt/openocd/bin/wch-riscv.cfg

⁠Peripheral Description Files Notes

Peripheral description files (SVD) for RISC-V MCUs are provided in /opt/wch/.

⁠Serial Monitor

To access the WCH-Link serial monitor inside the devcontainer, use the cu command as shown below:

cu -l <serial port device> -s <baudrate>

e.g. "cu -l /dev/ttyACM0 -s 115200".

To close the connection, press RETURN/ESC/Ctrl-C, type "~." (tilde, dot) and wait for 3 seconds.

⁠Flashing a target with pre-built image

To flash a target with a pre-built firmware image, use the included wlink utility. See the wlinkGitHub repository⁠ for more information.

wlink flash <hexfile>

⁠Running PIOC (CH53x) assembler

The CH32X035 PIOC uses a custom CPU architecture, hence at the moment only the WCH-provided assembler can be used to build PIOC binaries. In order to run the assembler, a 32-bit WINE installation inside the container is required (~1 GiB installation).

• Run setup-devcontainer --install-wine inside the container.

• Run the compiler with

  wasm53b <asm file name>
  

  Copy

• Convert output binary to C-array

  xxd -i <binary file name> <C source file name>
  

  Copy

⁠Building

To build the image yourself, either download the Linux MounRiver Studio II (MRS2)⁠ package manually and place it in the build directory, or enable the download in the dockerfile⁠:

ARG MOUNRIVER_URL="http://file-oss.mounriver.com/upgrade/MounRiverStudio_Linux_X64_V${MOUNRIVER_VERSION}.tar.xz"
#ARG MOUNRIVER_URL="/tmp/MounRiverStudio_Linux_X64_V${MOUNRIVER_VERSION}.tar.xz"
...

# Download and install package
RUN curl -sLO ${MOUNRIVER_URL}
#COPY MounRiverStudio_Linux_X64_V${MOUNRIVER_VERSION}.tar.xz /tmp
...

⁠Licensing

If not stated otherwise, the contents of this project are licensed under The MIT License. The full license text is provided in the LICENSE⁠ file.

SPDX-License-Identifier: MIT