usb: Allow partial packet writes, add error checking and documentation #848

piotrfila · 2026-01-10T23:44:16Z

Changes:

usb_start_tx -> ep_writev, now returns number of bytes written
usb_start_rx -> ep_readv and ep_listen: This makes it easier to make interrupt-safe drivers
More error checking when constructing descriptors
First attempt at documenting the usb driver comptime interface
The drivers now assume ACKs are handled automatically. This is the case for the rp2xxx usb controller but I have no idea if other controllers also handle it that way.

… once per packet

…terface

github-actions

🔍 Lint Results

Found 1 issue on changed lines in 1 file:

core/src/core/usb/drivers/cdc.zig: 1 issue

ℹ️ Additional issues on unchanged lines

The following 14 issue(s) exist but are not on lines changed in this PR:

core/src/core/usb.zig:357: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb.zig:359: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb.zig:429: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/cdc.zig:217: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:93: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:103: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:116: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/types.zig:149: Suggestion: Rename `U16Le` to `U16_Le`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
examples/raspberrypi/rp2xxx/src/custom_clock_config.zig:11: TODO style comments need to have a linked microzig issue on the same line.
examples/raspberrypi/rp2xxx/src/usb_cdc.zig:14: Suggestion: Rename `UsbSerial` to `USB_Serial`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:11: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:64: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:183: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:223: TODO style comments need to have a linked microzig issue on the same line.

core/src/core/usb/drivers/cdc.zig

Updating with new lint results

github-actions

🔍 Lint Results

ℹ️ Additional issues on unchanged lines

The following 14 issue(s) exist but are not on lines changed in this PR:

core/src/core/usb.zig:358: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb.zig:360: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb.zig:430: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/cdc.zig:216: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:93: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:103: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/drivers/hid.zig:116: TODO style comments need to have a linked microzig issue on the same line.
core/src/core/usb/types.zig:149: Suggestion: Rename `U16Le` to `U16_Le`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
examples/raspberrypi/rp2xxx/src/custom_clock_config.zig:11: TODO style comments need to have a linked microzig issue on the same line.
examples/raspberrypi/rp2xxx/src/usb_cdc.zig:14: Suggestion: Rename `UsbSerial` to `USB_Serial`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:11: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:64: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:183: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:223: TODO style comments need to have a linked microzig issue on the same line.

github-actions

🔍 Lint Results

ℹ️ Additional issues on unchanged lines

The following 6 issue(s) exist but are not on lines changed in this PR:

core/src/core/usb/descriptor/hid.zig:17: Suggestion: Rename `Hid` to `HID`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
examples/raspberrypi/rp2xxx/src/custom_clock_config.zig:11: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:11: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:64: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:183: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:223: TODO style comments need to have a linked microzig issue on the same line.

…pt endpoints

github-actions

🔍 Lint Results

Found 6 issues on changed lines in 1 file:

core/src/core/usb/types.zig: 6 issues

ℹ️ Additional issues on unchanged lines

The following 8 issue(s) exist but are not on lines changed in this PR:

core/src/core/usb/descriptor/hid.zig:17: Suggestion: Rename `Hid` to `HID`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
examples/raspberrypi/rp2xxx/src/custom_clock_config.zig:11: TODO style comments need to have a linked microzig issue on the same line.
examples/raspberrypi/rp2xxx/src/usb_hid.zig:83: TODO style comments need to have a linked microzig issue on the same line.
examples/raspberrypi/rp2xxx/src/usb_hid.zig:14: Suggestion: Rename `HidDriver` to `HID_Driver`, it _should_ be more in line with our [style guidelines](https://microzig.tech/docs/contributing/). This automation is not perfect so take it with a grain of salt.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:11: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:64: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:183: TODO style comments need to have a linked microzig issue on the same line.
port/raspberrypi/rp2xxx/src/hal/clocks/common.zig:223: TODO style comments need to have a linked microzig issue on the same line.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const SubclassCdc = enum(u8) {


Suggestion: Rename SubclassCdc to Subclass_CDC, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const ProtocolCdc = enum(u8) {


Suggestion: Rename ProtocolCdc to Protocol_CDC, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const SubclassCdcData = enum(u8) {


Suggestion: Rename SubclassCdcData to Subclass_CDC_Data, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const ProtocolCdcData = enum(u8) {


Suggestion: Rename ProtocolCdcData to Protocol_CDC_Data, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const SubclassHid = enum(u8) {


Suggestion: Rename SubclassHid to Subclass_HID, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-13T18:39:59Z

core/src/core/usb/types.zig

+        _,
+    };
+
+    pub const ProtocolHid = enum(u8) {


Suggestion: Rename ProtocolHid to Protocol_HID, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

Updating with new lint results

github-actions

🔍 Lint Results

Found 12 issues on changed lines in 1 file:

core/src/core/usb/types.zig: 12 issues

github-actions · 2026-01-17T13:37:58Z

core/src/core/usb/types.zig

+        pub const Unspecified = Default;
+        pub const Audio = Default;
+
+        pub const Cdc = enum(u8) {


Suggestion: Rename Cdc to CDC, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:58Z

core/src/core/usb/types.zig

+            _,
+        };
+
+        pub const Hid = enum(u8) {


Suggestion: Rename Hid to HID, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:58Z

core/src/core/usb/types.zig

+
+        pub const Hub = Default;
+
+        pub const CdcData = enum(u8) {


Suggestion: Rename CdcData to CDC_Data, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:58Z

core/src/core/usb/types.zig

+        pub const PersonalHealthcare = Default;
+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const USBTypeCBridge = Default;


Suggestion: Rename USBTypeCBridge to USB_Type_C_Bridge, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const USBTypeCBridge = Default;
+        pub const USBBulkDisplayProtocol = Default;


Suggestion: Rename USBBulkDisplayProtocol to USB_BulkDisplayProtocol, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+            _,
+        };
+
+        pub const Hid = enum(u8) {


Suggestion: Rename Hid to HID, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+
+        pub const Hub = Default;
+
+        pub const CdcData = enum(u8) {


Suggestion: Rename CdcData to CDC_Data, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+        pub const PersonalHealthcare = Default;
+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const USBTypeCBridge = Default;


Suggestion: Rename USBTypeCBridge to USB_Type_C_Bridge, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const USBTypeCBridge = Default;
+        pub const USBBulkDisplayProtocol = Default;


Suggestion: Rename USBBulkDisplayProtocol to USB_BulkDisplayProtocol, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:37:59Z

core/src/core/usb/types.zig

+        pub const BillboardDevice = Default;
+        pub const USBTypeCBridge = Default;
+        pub const USBBulkDisplayProtocol = Default;
+        pub const MCTPoverUSBProtocolEndpoint = Default;


Suggestion: Rename MCTPoverUSBProtocolEndpoint to MCT_Pover_USB_ProtocolEndpoint, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

Updating with new lint results

github-actions

🔍 Lint Results

Found 4 issues on changed lines in 1 file:

core/src/core/usb/types.zig: 4 issues

github-actions · 2026-01-17T13:43:35Z

core/src/core/usb/types.zig

+        pub const PersonalHealthcare = Default;
+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const TypeCBridge = Default;


Suggestion: Rename TypeCBridge to Type_C_Bridge, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:43:35Z

core/src/core/usb/types.zig

+        pub const BillboardDevice = Default;
+        pub const TypeCBridge = Default;
+        pub const BulkDisplayProtocol = Default;
+        pub const MCTP_over_USB_ProtocolEndpoint = Default;


Suggestion: Rename MCTP_over_USB_ProtocolEndpoint to MCTP_Over_USB_ProtocolEndpoint, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:43:35Z

core/src/core/usb/types.zig

+        pub const PersonalHealthcare = Default;
+        pub const AudioVideoDevice = Default;
+        pub const BillboardDevice = Default;
+        pub const TypeCBridge = Default;


Suggestion: Rename TypeCBridge to Type_C_Bridge, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-17T13:43:35Z

core/src/core/usb/types.zig

+        pub const BillboardDevice = Default;
+        pub const TypeCBridge = Default;
+        pub const BulkDisplayProtocol = Default;
+        pub const MCTP_over_USB_ProtocolEndpoint = Default;


Suggestion: Rename MCTP_over_USB_ProtocolEndpoint to MCTP_Over_USB_ProtocolEndpoint, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

All lint issues have been resolved

github-actions

🔍 Lint Results

Found 3 issues on changed lines in 3 files:

core/src/core/usb/drivers/cdc.zig: 1 issue
core/src/core/usb/drivers/example.zig: 1 issue
core/src/core/usb/drivers/hid.zig: 1 issue

github-actions · 2026-01-18T13:25:12Z

core/src/core/usb/drivers/cdc.zig

-
-const utilities = @import("../../../utilities.zig");
+const assert = std.debug.assert;
+const EpNum = usb.types.Endpoint.Num;


Suggestion: Rename EpNum to EP_Num, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-18T13:25:12Z

core/src/core/usb/drivers/example.zig

@@ -0,0 +1,99 @@
+const std = @import("std");
+const usb = @import("../../usb.zig");
+const EpNum = usb.types.Endpoint.Num;


Suggestion: Rename EpNum to EP_Num, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

github-actions · 2026-01-18T13:25:12Z

core/src/core/usb/drivers/hid.zig

 const usb = @import("../../usb.zig");
-const descriptor = usb.descriptor;
-const types = usb.types;
+const EpNum = usb.types.Endpoint.Num;


Suggestion: Rename EpNum to EP_Num, it should be more in line with our style guidelines. This automation is not perfect so take it with a grain of salt.

All lint issues have been resolved

port/raspberrypi/rp2xxx/src/hal/usb.zig

piotrfila added 12 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

github-actions bot previously requested changes Jan 10, 2026

View reviewed changes

core/src/core/usb/drivers/cdc.zig Outdated Show resolved Hide resolved

style fixes

9eabcab

github-actions bot reviewed Jan 10, 2026

View reviewed changes

appease linter bot

870f0d6

github-actions bot reviewed Jan 11, 2026

View reviewed changes

piotrfila added 2 commits January 11, 2026 17:08

add u32 little endian wrapper

2a79c78

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

f553d34

…pt endpoints

piotrfila marked this pull request as draft January 12, 2026 18:37

piotrfila added 4 commits January 13, 2026 15:43

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

github-actions bot previously requested changes Jan 13, 2026

View reviewed changes

piotrfila added 4 commits January 13, 2026 20:22

separate usb device and controller

b7bed05

more convenient descriptor creation

93cbc87

handle bus resets correctly

55921cc

more examples cleanup

bbe968f

piotrfila added 5 commits January 17, 2026 13:19

add BOS descriptor

baee980

simplify setup packet handling

ae7d203

add usb device logging

a6e8c89

better use scoped logging

66f0116

reorganize ClassSubclassProtocol

f07fe5c

github-actions bot previously requested changes Jan 17, 2026

View reviewed changes

adhere more to style guidelines

c40f907

github-actions bot previously requested changes Jan 17, 2026

View reviewed changes

...again

b9f61f5

piotrfila added 2 commits January 18, 2026 13:55

add enums to CDC

4c399ef

cleanup

3f494d0

github-actions bot previously requested changes Jan 18, 2026

View reviewed changes

piotrfila added 2 commits January 18, 2026 13:26

Merge branch 'main' into usb-driver-rework

5079a5b

EpNum -> EP_Num and fix pins in examples

6474eab

piotrfila marked this pull request as ready for review January 18, 2026 13:39

piotrfila marked this pull request as draft January 18, 2026 16:55

implement GetStatus

6f6ba02

piotrfila marked this pull request as ready for review January 18, 2026 21:17

driver handler type safety

872e794

Copper280z reviewed Jan 19, 2026

View reviewed changes

port/raspberrypi/rp2xxx/src/hal/usb.zig Outdated Show resolved Hide resolved

piotrfila added 2 commits January 19, 2026 17:55

inline get_setup_packet()

aa8034d

fix ep_writev only using the first buffer

7667ea7

usb: Allow partial packet writes, add error checking and documentation #848

Are you sure you want to change the base?

usb: Allow partial packet writes, add error checking and documentation #848

Uh oh!

Conversation

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

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

🔍 Lint Results

piotrfila commented Jan 10, 2026 •

edited

Loading