Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/islandcontroller/wch-riscv-devcontainer

VSCode Devcontainer for WCH RISC-V microcontroller development
https://github.com/islandcontroller/wch-riscv-devcontainer

openocd openwch risc-v riscv-toolchain vscode-devcontainer wch-link

Last synced: about 2 months ago
JSON representation

VSCode Devcontainer for WCH RISC-V microcontroller development

Awesome Lists containing this project

README 

        
# wch-riscv-devcontainer

[![License](https://img.shields.io/github/license/islandcontroller/wch-riscv-devcontainer)](LICENSE) [![GitHub](https://shields.io/badge/github-islandcontroller%2Fwch--riscv--devcontainer-black?logo=github)](https://github.com/islandcontroller/wch-riscv-devcontainer) [![Docker Hub](https://shields.io/badge/docker-islandc%2Fwch--riscv--devcontainer-blue?logo=docker)](https://hub.docker.com/r/islandc/wch-riscv-devcontainer) ![Docker Image Version (latest semver)](https://img.shields.io/docker/v/islandc/wch-riscv-devcontainer?sort=semver)



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



![Screenshot](scr.PNG)



### Packages

* [Microsoft .NET 6.0 Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) Version 6.0.33

* [MounRiver MRS Toolchain & Debugger](http://www.mounriver.com/download) Linux_x64 Version 1.92

  * includes WCH-custom GNU toolchain for RISC-V

  * includes WCH-custom OpenOCD debugger

* [MounRiver Studio SVD and ISP firmware files](http://www.mounriver.com/download) Update Version 1.91

  * ISP Firmware: Version `v31`

  * SVD files:

    - `CH32V003xx`

    - `CH32V103xx`

    - `CH32V203xx`

    - `CH32V208xx`

    - `CH32V303xx`

    - `CH32V305xx`

    - `CH32V307xx`

    - `CH56Xxx`

    - `CH57Xxx`

    - `CH58Xxx`

* [CH32X035 PIOC Assembler](https://github.com/openwch/ch32x035/tree/main/EVT/EXAM/PIOC/Tool_Manual/Tool) Version 3.1



* [CMake](https://cmake.org/download) Version 3.30.2

* [ch32-rs/wchisp](https://github.com/ch32-rs/wchisp/) Unversioned

* [ch32-rs/wlink](https://github.com/ch32-rs/wlink/) Unversioned



## System Requirements

* VSCode [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension

* (WSL only) [usbipd-win](https://learn.microsoft.com/en-us/windows/wsl/connect-usb)



## 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 `GCC 12.x riscv-none-elf` CMake Kit. 

  * Alternatively, a toolchain definition file is provided in: `$CMAKE_CONFIGS_PATH/gcc-riscv-none-elf.cmake`.

* 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



### 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](https://github.com/ch32-rs/wchisp/) for more information.



See the [WCH-Link User Manual](https://www.wch-ic.com/downloads/WCH-LinkUserManual_PDF.html) about updating your programmer and to determine which firmware file to use.



    wchisp flash /opt/wch/firmware/



### 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  -s 



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 [`wlink`GitHub repository](https://github.com/ch32-rs/wlink/) for more information.



    wlink flash 



### 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 



* Convert output binary to C-array



      xxd -i  



## 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`](LICENSE) file.



    SPDX-License-Identifier: MIT