add CP210x USB class implementation #97648

matsievskiysv · 2025-10-15T17:09:26Z

Add CP210x USB class implementation.
CP210x is the USB to serial converter, wildly used to emulate serial
devices in MCUs and supported by major operating systems. It has the
advantage over CDC ACM of using only two USB endpoints. This makes the
dramatic difference in some cases: for example, STM32F40x boards may
emulate three CP210x instances but only one CDC ACM instance.
USB device implementation heavily borrows from CDC ACM code, and for the
most part differs in control message handling.

Only a subset of functions is currently implemented. Missing functionality
includes

most flow control functions;
error reporting;
special character handling.

Implementation has a known problem: when device only sends data (e.g. usb
console sample), closing the terminal emulation program (i.e. screen or
picocom) hangs the process.

github-actions · 2025-10-15T17:10:11Z

Hello @matsievskiysv, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

Add CP210x USB class implementation. CP210x is the USB to serial converter, wildly used to emulate serial devices in MCUs and supported by major operating systems. It has the advantage over CDC ACM of using only two USB endpoints. This makes the dramatic difference in some cases: for example, STM32F40x boards may emulate three CP210x instances but only one CDC ACM instance. USB device implementation heavily borrows from CDC ACM code, and for the most part differs in control message handling. Only a subset of functions is currently implemented. Missing functionality includes * most flow control functions; * error reporting; * special character handling. Implementation has a known problem: when device only sends data (e.g. usb console sample), closing the terminal emulation program (i.e. screen or picocom) hangs the process. Signed-off-by: Sergey Matsievskiy <[email protected]>

Add CP210x loopback sample. Signed-off-by: Sergey Matsievskiy <[email protected]>

matsievskiysv · 2025-10-15T17:49:40Z

There're 5 chechpatch warnings and 8 checks, that should be ignored:

Checkpatch messages

Camel case names reflect field names in the specification.

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:432: CHECK:CAMELCASE: Avoid CamelCase: <ulProvCapabilities>
#432: FILE: include/zephyr/usb/class/usb_cp210x.h:347:
+       } ulProvCapabilities;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:444: CHECK:CAMELCASE: Avoid CamelCase: <ulSettableParams>
#444: FILE: include/zephyr/usb/class/usb_cp210x.h:359:
+       } ulSettableParams;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:468: CHECK:CAMELCASE: Avoid CamelCase: <ulSettableBaud>
#468: FILE: include/zephyr/usb/class/usb_cp210x.h:383:
+       } ulSettableBaud;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:479: CHECK:CAMELCASE: Avoid CamelCase: <wSettableData>
#479: FILE: include/zephyr/usb/class/usb_cp210x.h:394:
+       } wSettableData;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:504: CHECK:CAMELCASE: Avoid CamelCase: <ulErrors>
#504: FILE: include/zephyr/usb/class/usb_cp210x.h:419:
+       } ulErrors;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:516: CHECK:CAMELCASE: Avoid CamelCase: <ulHoldReasons>
#516: FILE: include/zephyr/usb/class/usb_cp210x.h:431:
+       } ulHoldReasons;

False positive misspells

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:564: WARNING:TYPO_SPELLING: 'rsource' may be misspelled - perhaps 'resource'?
#564: FILE: subsys/usb/device_next/Kconfig:110:
+rsource "app/Kconfig.cp210x_serial"

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:697: WARNING:TYPO_SPELLING: 'nd' may be misspelled - perhaps 'and'?
#697: FILE: subsys/usb/device_next/app/cp210x_serial.c:44:
+       struct usbd_config_node *cfg_nd;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:700: WARNING:TYPO_SPELLING: 'nd' may be misspelled - perhaps 'and'?
#700: FILE: subsys/usb/device_next/app/cp210x_serial.c:47:
+       cfg_nd = &cp210x_serial_fs_config;

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:702: WARNING:TYPO_SPELLING: 'nd' may be misspelled - perhaps 'and'?
#702: FILE: subsys/usb/device_next/app/cp210x_serial.c:49:
+       err = usbd_add_configuration(uds_ctx, speed, cfg_nd);

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:778: WARNING:TYPO_SPELLING: 'rsource' may be misspelled - perhaps 'resource'?
#778: FILE: subsys/usb/device_next/class/Kconfig:16:
+rsource "Kconfig.cp210x"

Reused from CDC ACM code

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:739: CHECK:OPEN_ENDED_LINE: Lines should not end with a '('
#739: FILE: subsys/usb/device_next/app/cp210x_serial.c:86:
+       IF_ENABLED(CONFIG_HWINFO, (

1b1dfc3f175b64dd5b66ec1f24e0ba72219a8780:2219: CHECK:MACRO_ARG_REUSE: Macro argument reuse 'n' - possible side-effects?
#2219: FILE: subsys/usb/device_next/class/usbd_cp210x.c:1372:

sonarqubecloud · 2025-10-15T18:10:15Z

Quality Gate passed

Issues
12 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
3.9% Duplication on New Code

See analysis details on SonarQube Cloud

tmon-nordic · 2025-10-16T11:52:44Z

subsys/usb/device_next/app/Kconfig.cp210x_serial

+config CP210X_SERIAL_VID
+	hex "USB device Vendor ID"
+	default 0x1BA4
+	help
+	  Must be one of the well-known CP210X VIDs for kernel to use the
+	  appropriate driver. VID-PID pairs may be obtained from Linux's
+	  cp210x driver source.
+
+config CP210X_SERIAL_PID
+	hex "USB device Product ID"
+	default 0x0002
+	help
+	  Must be one of the well-known CP210X PIDs for kernel to use the
+	  appropriate driver. VID-PID pairs may be obtained from Linux's
+	  cp210x driver source.


Is there any particular reason why you have chosen to impersonate cp210x and not any other serial device?

Note that abusing VID/PID numbers violates USB-IF membership agreement

Vendor ID (VID) Number. Company hereby applies for a USB Vendor ID Number and agrees to the following: The USB Implementers Forum is the authority which assigns and maintains all USB Vendor ID Numbers. Each Vendor ID Number is assigned to one company for its sole and exclusive use, along with associated Product ID Numbers. They may not be sold, transferred, or used by others, directly or indirectly, except in special circumstances and then only upon prior written approval by USB-IF. Unauthorized use of assigned or
unassigned USB Vendor ID Numbers and associated Product ID Numbers are strictly prohibited.

tmon-nordic · 2025-10-16T12:05:54Z

dts/bindings/serial/zephyr,cp210x-uart.yaml

+
+description: USB CP210X UART
+
+compatible: "zephyr,cp210x-uart"


~~If the goal is to not require interrupt endpoint, then why you don't make the CDC ACM interrupt endpoint optional?~~

Universal Serial Bus Class Definitions for Communications Devices Revision 1.2 (Errata 1)
3.4.1 Communications Class Interface

The Communications Class defines a Communications Class interface consisting of a management
element and optionally a notification element. The management element configures and controls the
device, and consists of endpoint 0. The notification element transports events to the host, and in most
cases, consists of a interrupt endpoint.

3.5.1 Communications Class Endpoint Requirements

The Communications Class interface requires one endpoint, a management element. It optionally can
have an additional endpoint, the notification element. The management element uses the default
endpoint for all standard and Communications Class-specific requests. The notification element normally
uses an interrupt endpoint.

~~Therefore it is not mandatory for CDC ACM device to use interrupt endpoint.~~

~~Working on making CDC ACM interrupt endpoint optional, and checking interoperability issues with different hosts would IMHO be more fruitful than abusing cp210x drivers.~~

Linux's cdc-acm driver is a bit hard for me to understand, but it looks like the interrupt endpoint is mandatory. However, in some cases the driver does look for the endpoints in the alternate configurations, which is worth checking out.

abusing cp210x drivers

I wouldn't call it abuse. More of an emulation=)

Linux's cdc-acm driver is a bit hard for me to understand, but it looks like the interrupt endpoint is mandatory.

Linux CDC ACM driver is just an implementation, not the specification. The specification states that notification element is optional. If what you want to achieve is to have Zephyr application having something that shows as tty under Linux, and consumes two endpoints per instance, then I would suggest:

~~make the notification endpoint optional in Zephyr CDC ACM implementation~~

~~send PATCH to linux kernel to not require interrupt notification endpoint~~

I see no reason why either of the above would be rejected. I am fairly confident that the interrupt endpoint is optional. If it is not, then please point me to relevant section in https://www.usb.org/document-library/class-definitions-communication-devices-12

Turns out I was wrong, 3.2.2 Abstract Control Model

A Communications Class interface of type Abstract Control Model will consist of a minimum of two
pipes; one is used to implement the management element and the other to implement a notification
element. In addition, the device can use two pipes to implement channels over which to carry unspecified
data, typically over a Data Class interface.

So while CDC itself does not require notification element, ACM does require it. :(

abusing cp210x drivers

I wouldn't call it abuse. More of an emulation=)

However you name it, doing so will lead to a device that cannot pass USB certification.

zephyrbot added area: USB Universal Serial Bus area: Samples Samples area: UART Universal Asynchronous Receiver-Transmitter area: Devicetree Bindings area: Build System area: Devicetree area: Boards/SoCs labels Oct 15, 2025

zephyrbot requested review from 57300, JarmouniA, dcpleung, decsny, jeremybettis, jfischer-no, kartben, mbolivar, nashif, nordicjm, rruuaanng, tejlmand and tmon-nordic October 15, 2025 17:11

zephyrbot assigned jfischer-no Oct 15, 2025

Sergey Matsievskiy added 2 commits October 15, 2025 20:33

samples: usb: add CP210x sample

bd0c800

Add CP210x loopback sample. Signed-off-by: Sergey Matsievskiy <[email protected]>

matsievskiysv force-pushed the cp210x-class branch from d5da28e to bd0c800 Compare October 15, 2025 17:42

tmon-nordic reviewed Oct 16, 2025

View reviewed changes

tmon-nordic requested changes Oct 16, 2025

View reviewed changes

matsievskiysv closed this Oct 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add CP210x USB class implementation #97648

add CP210x USB class implementation #97648

Uh oh!

matsievskiysv commented Oct 15, 2025

Uh oh!

github-actions bot commented Oct 15, 2025

Uh oh!

matsievskiysv commented Oct 15, 2025

Uh oh!

sonarqubecloud bot commented Oct 15, 2025

Uh oh!

tmon-nordic Oct 16, 2025

Uh oh!

tmon-nordic Oct 16, 2025 •

edited

Loading

Uh oh!

matsievskiysv Oct 16, 2025

Uh oh!

tmon-nordic Oct 16, 2025 •

edited

Loading

Uh oh!

tmon-nordic Oct 16, 2025

Uh oh!

tmon-nordic Oct 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		description: USB CP210X UART

		compatible: "zephyr,cp210x-uart"

add CP210x USB class implementation #97648

add CP210x USB class implementation #97648

Uh oh!

Conversation

matsievskiysv commented Oct 15, 2025

Uh oh!

github-actions bot commented Oct 15, 2025

Uh oh!

matsievskiysv commented Oct 15, 2025

Uh oh!

sonarqubecloud bot commented Oct 15, 2025

Quality Gate passed

Uh oh!

tmon-nordic Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

tmon-nordic Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matsievskiysv Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

tmon-nordic Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmon-nordic Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

tmon-nordic Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tmon-nordic Oct 16, 2025 •

edited

Loading

tmon-nordic Oct 16, 2025 •

edited

Loading