ch32 USBHD/USBHS driver implementation by Copper280z · Pull Request #893 · ZigEmbeddedGroup/microzig

Copper280z · 2026-01-31T20:28:31Z

This adds a new driver for the ch32 USBHD/USBHS peripheral, USB_OTG_FS peripheral, and examples for the ch32v307, and ch32v203 boards.

… once per packet

…terface

…pt endpoints

…into origin/umain

…oards. ch32 USBHS still sends packets twice.

…ual mode. CDC Works without extra packets!

…ed code in usb_cdc.zig

github-actions · 2026-01-31T20:28:57Z

Lint Results

Found 12 issues on changed lines in 4 files:

examples/wch/ch32v/src/usb_cdc.zig: 1 issue
port/wch/ch32v/src/hals/clocks.zig: 1 issue
port/wch/ch32v/src/hals/usbfs.zig: 5 issues
port/wch/ch32v/src/hals/usbhs.zig: 5 issues

…32v203 board.

…ng to board definitions, add max packet size to usb device hal.

examples/wch/ch32v/src/usb_cdc.zig

port/wch/ch32v/src/hals/clocks.zig

port/wch/ch32v/src/hals/usbfs.zig

port/wch/ch32v/src/hals/usbhs.zig

github-actions · 2026-02-06T01:52:52Z

port/wch/ch32v/src/hals/usbhs.zig

+    _reserved1: u2 = 0,
+});
+
+fn baseAddr() usize {


Please change to base_addr, in MicroZig we use snake case for function names.

this one actually makes sense

Grazfather

Reviewed everything except for the HALs themselves (since this is a draft). Will get to those when you think they're ready.

Grazfather · 2026-02-10T01:09:03Z

core/src/core/usb.zig

                .bcd_usb = config.bcd_usb,
                .device_triple = config.device_triple,
-                .max_packet_size0 = @max(config.max_supported_packet_size, 64),
+                .max_packet_size0 = @min(config.max_supported_packet_size, 64),


I could find it in the spec, but this is correct now. For LS and FS devices endpoint 0 can be 8 to 64 bytes, for HS it's always 64.

Unofficial, but useful reference: https://www.beyondlogic.org/usbnutshell/usb4.shtml

Grazfather · 2026-02-10T01:09:18Z

examples/wch/ch32v/build.zig

        .{ .target = mb.ports.ch32v.boards.ch32v203.nano_ch32v203, .name = "nano_ch32v203_blinky", .file = "src/board_blinky.zig" },
+        .{ .target = mb.ports.ch32v.boards.ch32v203.nano_ch32v203, .name = "nano_ch32v203_usb_cdc", .file = "src/usb_cdc.zig" },
        .{ .target = mb.ports.ch32v.boards.ch32v203.suzuduino_uno_v1b, .name = "suzuduino_blinky", .file = "src/board_blinky.zig" },
+        .{ .target = mb.ports.ch32v.boards.ch32v203.suzuduino_uno_v1b, .name = "suzuduino_usb_cdc", .file = "src/usb_cdc.zig" },


is this one tested?

nano_ch32v203 is tested, suzuduino is not, but the way the peripheral and pins work there's no board specific configuration. It automatically configures the pins, and there's only one option for the pair, so if usb is exposed on the board and there's an external crystal, it should work.

More testing is always better though, so test away.

Grazfather · 2026-02-10T01:09:37Z

examples/wch/ch32v/build.zig

        .{ .target = mb.ports.ch32v.boards.ch32v203.lana_tny, .name = "lana_tny_spi_loopback", .file = "src/spi_loopback.zig" },
        .{ .target = mb.ports.ch32v.boards.ch32v203.lana_tny, .name = "lana_tny_spi_flash_w25q", .file = "src/spi_flash_w25q.zig" },
        .{ .target = mb.ports.ch32v.boards.ch32v203.lana_tny, .name = "lana_tny_sharp_niceview", .file = "src/sharp_niceview.zig" },
+        .{ .target = mb.ports.ch32v.boards.ch32v203.lana_tny, .name = "lana_tny_usb_cdc", .file = "src/usb_cdc.zig" },


and this one? I have this so I can test it for you.

Same as above, there's only one set of pins, and the peripheral configures them automatically, but more testing is better, so please do so!

As mentioned on discord: This device has the x6 bin which is the 'usbd' variant of the usbfs, so it's not (yet) supported.

Grazfather · 2026-02-10T01:10:21Z

port/wch/ch32v/src/hals/ch32v20x.zig

 pub const usart = @import("usart.zig");
 pub const spi = @import("spi.zig");
 pub const dma = @import("dma.zig");
+pub const usb = @import("usbfs.zig");


Can you add this in the test block as well

Also, as you noticed: Some variants of this have both USBD and USBHD. Somewhat confusingly you're calling hal.usb usbfs here, but for 3xx usb is hs and usbfs is ufbfs.

Grazfather · 2026-02-10T01:10:57Z

port/wch/ch32v/src/hals/ch32v30x.zig

 /// HSI (High Speed Internal) oscillator frequency
 /// This is the fixed internal RC oscillator frequency for CH32V30x
 pub const hsi_frequency: u32 = 8_000_000; // 8 MHz
+pub const hse_frequency: u32 = 8_000_000; // 8 MHz


This should be board level, since it's external to the chip and may not be present.

Grazfather · 2026-02-10T01:12:16Z

port/wch/ch32v/src/hals/clocks.zig

+/// selects whether the USBHS 48MHz clock comes from the system PLL clock or the USB PHY,
+/// and enables the AHB clock gate for USBHS.
+///
+/// Note: The SVD names bit31 as `USBFSSRC`, but the reference manual


Can we patch this? Which SVD? All of them?

At this point it's unclear which name is correct. I should probably either remove the comment or figure it out.

Grazfather · 2026-02-10T01:15:20Z

examples/wch/ch32v/src/usb_cdc.zig

+const tog_pin = gpio.Pin.init(0, 14);
+const mco_pin = gpio.Pin.init(0, 8);


Might as well keep with the comments e.g. PA14 and PA8

These will be removed before I mark it as ready, MCO and toggle are things I was using for testing. MCO is useful for validating PLL stuff with a scope.

Grazfather · 2026-02-10T01:16:15Z

examples/wch/ch32v/src/usb_cdc.zig

+    .configurations = &.{.{
+        .attributes = .{ .self_powered = false },
+        .max_current_ma = 50,
+        .Drivers = struct { serial: USB_Serial },


Could you maybe copy some of the extra comments I added to the cdc example for rpi?

Grazfather · 2026-02-10T01:16:41Z

examples/wch/ch32v/src/usb_cdc.zig

+pub var usb_dev: hal.usb.Polled(
+    .{},
+) = undefined;


Suggested change

pub var usb_dev: hal.usb.Polled(

.{},

) = undefined;

pub var usb_dev: hal.usb.Polled(.{}) = undefined;

Grazfather · 2026-02-10T01:18:25Z

examples/wch/ch32v/src/usb_cdc.zig

+            // pins.tog.put(0);
+            usb_dev.poll(false, &usb_controller);
+            // pins.tog.put(1);


gets rid of toggle pins completely or uncomment these please

piotrfila and others added 30 commits January 10, 2026 14:54

neccessary -> necessary and fix linter bot issue

d272589

scan unhandled buffer linearly

3e3b6de

redo endpoint handling

b587b46

separate getting usb rx data and requesting more

a653711

make CdcClassDriver rx interrupt-safe

9504866

add usb packet length type

52ea727

make CdcClass driver tx interrupt-safe

b655989

allow partial usb tx and require calling ep_writev and ep_listen only…

503c998

… once per packet

documentation and configurable handler names

93ce596

first draft of an example driver that explains the comptime driver in…

f210076

…terface

more error checking around interfaces and string descriptors

942aa42

endpoint_open -> ep_open for consistency

340d9c3

style fixes

9eabcab

appease linter bot

870f0d6

add u32 little endian wrapper

2a79c78

respect endianness in setup packet and shortcuts for bulk and interru…

f553d34

…pt endpoints

start at ch32v usb

27edab3

cleanum usb examples

2ed6b4d

change the example usb driver to a simple echo

cd4e348

assign endpoints and interfaces (more) automatically

0959d37

better handling of device class, subclass and protocol

36f02ea

separate usb device and controller

b7bed05

more convenient descriptor creation

93cbc87

handle bus resets correctly

55921cc

fix startup

f373714

more examples cleanup

bbe968f

add BOS descriptor

baee980

simplify setup packet handling

ae7d203

add usb device logging

a6e8c89

better use scoped logging

66f0116

Copper280z added 22 commits January 21, 2026 23:55

Fix data toggle config

00fe33b

Fixed data toggles, CDC Data flows!

2011590

comment out some logging

9865fe3

Merge branch 'origin/umain' of https://github.com/Copper280z/microzig …

985d6e8

…into origin/umain

Refactor ch32 USB logging and enhance clock configuration for CH32V b…

c337146

…oards. ch32 USBHS still sends packets twice.

Refactor USBHS interrupt handling and switch toggle management to man…

baed799

…ual mode. CDC Works without extra packets!

Refactor USB polling logic into a separate function and clean up unus…

df4e181

…ed code in usb_cdc.zig

Merge remote-tracking branch 'upstream/main' into ch32_usb

dc8ec01

update for latest usb core changes

ad686c3

remove unfinished usbd driver

fce6646

revert to upstream with minimal updates for usbhs

8a0e752

revert changes to uart_log

57f498f

remove old example driver

8b9704c

cleanup

0049e03

cleanup usbhs clock setup

01624dc

more cleanup

19cc7f3

revert board clock setup to one that works on current upstream.

493c041

revert most of clocks.zig to upstream.

02ce566

mirror rp2xxx better

349fb6a

revert usart changes, cleanup example to match rp2xxx better

e0cef46

adjust comment

0717b51

get rid of regs function, change a log call

b9892ab

Copper280z added 3 commits February 2, 2026 22:43

usbfs works

0a2bde0

Add usbfs clock setup function, add support for v203 chips and nanoch…

e322393

…32v203 board.

Add more example build defs, clean up dev noise, add usb product stri…

026395f

…ng to board definitions, add max packet size to usb device hal.

github-actions bot reviewed Feb 6, 2026

View reviewed changes

Copper280z added 2 commits February 5, 2026 20:53

remove zigscient rootid tag

a4927cc

clear IRQ flags after work is done to ensure clean NAK/ACK transition.

0480805

Grazfather reviewed Feb 10, 2026

View reviewed changes

		const tog_pin = gpio.Pin.init(0, 14);
		const mco_pin = gpio.Pin.init(0, 8);

Conversation

Copper280z commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lint Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Grazfather left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copper280z commented Jan 31, 2026 •

edited

Loading

github-actions bot commented Jan 31, 2026 •

edited

Loading