usb: device_next: Simple NCM driver for usb-next #72310

rgrr · 2024-05-04T06:28:24Z

I have ported a simple version of my TinyUSB NCM driver to Zephyr.

The driver has been kept very simple (one datagram per NTB and one buffer per direction). Current idea is not to optimize performance, focus is more on existence of an NCM driver for Zephyr.

To make the driver work with iperf (my testcase), CONFIG_NET_BUF_VARIABLE_DATA_SIZE=y must be used.

Discussion about this PR can be found in #71451.

2nd attempt, because I messed up the 1st PR completely, see previous one: #72305

Resolves: #71451

josuah

I am nowhere close to a maintainer, and this is an unsolicited review, but I am trying to anticipate some points in hope to save you some time.

To increase the chances to have this merged sooner than later, I suggest to:

give the coding style a look https://docs.zephyrproject.org/latest/contribute/guidelines.html#coding-style eventually applying clang-format -i to all C source/headers to save you time manually reformatting everything, and the result will be matching the expectations.
submit several pull-requests, for instance one with just the header definitions from the standard

Glad to see some interest in the USB stack!

Sorry for the shallow overview, I did not read CDC NCM yet...

subsys/usb/device_next/class/usbd_cdc_ncm.c

josuah · 2024-05-22T00:56:34Z

subsys/usb/device_next/class/usbd_cdc_ncm_private.h

@@ -0,0 +1,127 @@
+/*


This file is in zephyr/subsys, but for the other classes it looked like these definitions were submitted to zephyr/include: https://github.com/zephyrproject-rtos/zephyr/tree/main/include/zephyr/usb/class

Not sure about this one: if you have a look at https://github.com/zephyrproject-rtos/zephyr/tree/main/subsys/usb/device_next/class you will notice another "private" header which was the reason for me to put the NCM internals there. Perhaps I should rename it to "usbd_cdc_ncm_internal.h"?

Yes although every USB class also seems to have a header in include... Except CDC ECM!

But those header contain some kind of API. The NCM structs are internal and of no interest to externals. So they should be private/internal.

Ah understood! It looks like there is only a special case for CDC only, so maybe it is good to keep the declarations as local as possible...

zephyr/include/zephyr/usb/class/usb_cdc.h

Lines 149 to 211 in 95dde52

/** Header Functional Descriptor */

struct cdc_header_descriptor {

uint8_t bFunctionLength;

uint8_t bDescriptorType;

uint8_t bDescriptorSubtype;

uint16_t bcdCDC;

} __packed;

/** Union Interface Functional Descriptor */

struct cdc_union_descriptor {

uint8_t bFunctionLength;

uint8_t bDescriptorType;

uint8_t bDescriptorSubtype;

uint8_t bControlInterface;

uint8_t bSubordinateInterface0;

} __packed;

/** Call Management Functional Descriptor */

struct cdc_cm_descriptor {

uint8_t bFunctionLength;

uint8_t bDescriptorType;

uint8_t bDescriptorSubtype;

uint8_t bmCapabilities;

uint8_t bDataInterface;

} __packed;

/** Abstract Control Management Functional Descriptor */

struct cdc_acm_descriptor {

uint8_t bFunctionLength;

uint8_t bDescriptorType;

uint8_t bDescriptorSubtype;

uint8_t bmCapabilities;

} __packed;

/** Data structure for GET_LINE_CODING / SET_LINE_CODING class requests */

struct cdc_acm_line_coding {

uint32_t dwDTERate;

uint8_t bCharFormat;

uint8_t bParityType;

uint8_t bDataBits;

} __packed;

/** Data structure for the notification about SerialState */

struct cdc_acm_notification {

uint8_t bmRequestType;

uint8_t bNotificationType;

uint16_t wValue;

uint16_t wIndex;

uint16_t wLength;

uint16_t data;

} __packed;

/** Ethernet Networking Functional Descriptor */

struct cdc_ecm_descriptor {

uint8_t bFunctionLength;

uint8_t bDescriptorType;

uint8_t bDescriptorSubtype;

uint8_t iMACAddress;

uint32_t bmEthernetStatistics;

uint16_t wMaxSegmentSize;

uint16_t wNumberMCFilters;

uint8_t bNumberPowerFilters;

} __packed;

I am curious to read the result of it.

hmmm... not sure if I got your point...

Most of the descriptor stuff seems to be in usb_ch9.h. The class headers are one level below of that and contain class dependent stuff of the descriptors plus some API. So usb_cdc.h with its descriptor definitions is at the right place.

But nevertheless this is not completely clear, because e.g. msos_desc.h is at the same level as usb_ch9.h but clearly belongs to MSC. So perhaps everything is experimental and needs some cleanup.

But nevertheless this is not completely clear, because e.g. msos_desc.h is at the same level as usb_ch9.h but clearly belongs to MSC. So perhaps everything is experimental and needs some cleanup.

I find it really surprising that you mention that msos_desc.h "clearly belong to MSC", because it does not. It has really nothing to do with MSC and MSC device wouldn't benefit at all from msos_desc.h. The real benefit for msos_desc.h is to allow device to tell Windows that it wants WinUSB driver automatically installed. This is not needed at all for MSC, because MSC uses well-known Mass Storage class driver.

Sorry, yes you are right of course. Mixed several things up and to make it worse I have used in one of my projects this WinUSB mechanism to have "driverless" setup (i.e. without fiddling) under Win10.

Nevertheless the file should be still in the class subdirectory, or not?

subsys/usb/device_next/class/usbd_cdc_ncm.c

rgrr · 2024-05-22T04:41:25Z

I am nowhere close to a maintainer, and this is an unsolicited review, but I am trying to anticipate some points in hope to save you some time.

Many thanks for reviewing the code!

* give the coding style a look https://docs.zephyrproject.org/latest/contribute/guidelines.html#coding-style eventually applying `clang-format -i` to all C source/headers to save you time manually reformatting everything, and the result will be matching the expectations.

Currently working on this. Iterating thru the code until the runner no longer complains (which seems to be a painful process)

* submit several pull-requests, for instance one with just the header definitions from the standard

Unfortunately all those changes depend on each other. So there is no meaning of providing e.g. just the headers.

subsys/usb/device_next/class/usbd_cdc_ncm.c

josuah · 2024-05-22T09:59:41Z

I realize that a lot of my comments might as well be addressed to USB CDC ECM, and open questions for the USB stack in general. In hope you can get more folks offering some review soon. I can ping the #pr-help channel to draw attention on a pull request that needs some review when you wish.

josuah · 2024-05-22T10:43:45Z

I do like how this class is a thin wrapper between the Ethernet and USB Class APIs.

rgrr · 2024-05-22T11:41:41Z

I realize that a lot of my comments might as well be addressed to USB CDC ECM, and open questions for the USB stack in general. In hope you can get more folks offering some review soon. I can ping the #pr-help channel to draw attention on a pull request that needs some review when you wish.

Yes please, that would be very kind.

rgrr · 2024-05-22T11:48:05Z

I do like how this class is a thin wrapper between the Ethernet and USB Class APIs.

The ECM driver is even more direct (BTW Johann Fischer is the author of that). NCM has the capability to additionally packing multiple datagrams into one transfer block. But as stated in the intro this is currently not implemented.

Actually for me the nice thing is, that there are NCM drivers even for Win10.

subsys/usb/device_next/class/usbd_cdc_ncm.c

josuah · 2024-05-22T22:16:06Z

You might be asked to merge several commits together. If that were to happen, do feel free to reach me at me@josuah.net (or josuah.demangeon on the chat) so that we can get this as expected by the real reviewers.

jukkar · 2024-05-23T05:52:28Z

Please fix the commit subjects, now they are all the same which is not good. The commit subject should indicate what the commit is changing.

rgrr · 2024-05-23T06:07:13Z

Please fix the commit subjects, now they are all the same which is not good. The commit subject should indicate what the commit is changing.

Done that and squashed everything. Top be honest, commit message policy is not clear to me. If one does not use the special subject structure, then one of the CI checks complains, also it seems that only squashed PRs are merged, so the history of a PR seems to be irrelevant.

jukkar · 2024-05-23T08:25:42Z

it seems that only squashed PRs are merged, so the history of a PR seems to be irrelevant.

This is definitely not true, the commit history is very much relevant. The commit messages rules are actually very simple, the individual commits should contain logical changes related to each other. For new code, in many cases there is need to have only couple of commits, for example the actual feature in one, tests in another, samples in another. Sometimes it makes sense to split the feature to multiple commits each implementing sub-features. It really depends what is being submitted.

rgrr · 2024-05-23T08:42:19Z

it seems that only squashed PRs are merged, so the history of a PR seems to be irrelevant.

This is definitely not true, the commit history is very much relevant. The commit messages rules are actually very simple, the individual commits should contain logical changes related to each other. For new code, in many cases there is need to have only couple of commits, for example the actual feature in one, tests in another, samples in another. Sometimes it makes sense to split the feature to multiple commits each implementing sub-features. It really depends what is being submitted.

Thanks for the clarification, did not want to offend anybody.

I have to admit that I'm new to Zephyrs PR policy and thus have to get used to it.

josuah · 2024-05-23T11:46:42Z

https://docs.zephyrproject.org/latest/contribute/guidelines.html#commit-guidelines

josuah · 2024-05-25T14:08:07Z

subsys/usb/device_next/class/usbd_cdc_ncm.c

+	uint8_t ep;
+	int ret;
+
+	LOG_DBG("");


I suppose this would receive similar comment to this:
#53408 (comment)

A git commit --amend adding some short description of just a few words would allow keeping these.

removed every empty LOG_DBG(), wondering if anybody ever made the cost/environmental calculation of these CI runs caused by mini changes...

I read somewhere that scripts/rules were setup to avoid extra CI cycles, with manual or auto-run CI.

Maybe there can be rules to only auto-run CI when the PR is not in "draft" state.

This is a simple USB-NCM driver. It just has one NTB per direction and within the NTB only one datagram can be received/transmitted. Main goal is existance of an NCM driver, performance will follow in further steps. Signed-off-by: Hardy Griech <ntbox@gmx.net>

removed empty LOG_DBG() Signed-off-by: Hardy Griech <ntbox@gmx.net>

zephyrbot added area: Ethernet area: Networking area: USB Universal Serial Bus area: Samples Samples area: Devicetree Binding PR modifies or adds a Device Tree binding labels May 4, 2024

rgrr mentioned this pull request May 4, 2024

Draft: Simple NCM driver for usb-next #72305

Closed

zephyrbot requested review from decsny, galak, jfischer-no, jukkar, kartben, nashif, pdgendt, rlubos, ssharks, tbursztyka and tmon-nordic May 4, 2024 06:29

zephyrbot assigned jfischer-no May 4, 2024

rgrr mentioned this pull request May 4, 2024

Is there any interest in USB CDC-NCM driver? #71451

Open

rgrr changed the title ~~Draft: Simple NCM driver for usb-next (2nd try)~~ Draft: usb: device_next: Simple NCM driver for usb-next (2nd try) May 4, 2024

rgrr changed the title ~~Draft: usb: device_next: Simple NCM driver for usb-next (2nd try)~~ usb: device_next: Simple NCM driver for usb-next (2nd try) May 6, 2024

rgrr force-pushed the cdc-ncm2 branch from 5819631 to 3d9c25c Compare May 7, 2024 17:22

zephyrbot requested a review from lmajewski May 7, 2024 17:23

rgrr changed the title ~~usb: device_next: Simple NCM driver for usb-next (2nd try)~~ usb: device_next: Simple NCM driver for usb-next May 8, 2024

rgrr force-pushed the cdc-ncm2 branch 2 times, most recently from a4b0e57 to 94b376e Compare May 8, 2024 11:43

rgrr requested review from mmahadevan108, dleach02, anangl and JiafeiPan as code owners May 8, 2024 21:38

rgrr force-pushed the cdc-ncm2 branch from bdc5f4f to a0cf333 Compare May 21, 2024 16:43

josuah reviewed May 22, 2024

View reviewed changes

rgrr force-pushed the cdc-ncm2 branch from a0cf333 to 3430743 Compare May 22, 2024 04:46

rgrr requested a review from josuah May 22, 2024 04:47

jukkar requested review from jukkar and removed request for jukkar and josuah May 22, 2024 05:21

josuah reviewed May 22, 2024

View reviewed changes

subsys/usb/device_next/class/usbd_cdc_ncm.c Show resolved Hide resolved

gmarull removed their request for review May 22, 2024 11:54

josuah reviewed May 22, 2024

View reviewed changes

subsys/usb/device_next/class/usbd_cdc_ncm.c Show resolved Hide resolved

josuah reviewed May 22, 2024

View reviewed changes

subsys/usb/device_next/class/usbd_cdc_ncm.c Show resolved Hide resolved

rgrr force-pushed the cdc-ncm2 branch from 5267e9a to 1dd8659 Compare May 22, 2024 20:48

rgrr force-pushed the cdc-ncm2 branch from 1dd8659 to 3195492 Compare May 23, 2024 05:17

rgrr force-pushed the cdc-ncm2 branch from 3195492 to 2930894 Compare May 23, 2024 06:03

josuah reviewed May 25, 2024

View reviewed changes

rgrr force-pushed the cdc-ncm2 branch from 2930894 to a567af7 Compare May 25, 2024 16:20

rgrr added 2 commits June 3, 2024 08:19

usb: device_next: Simple NCM driver for usb-next

cfd9b86

removed empty LOG_DBG() Signed-off-by: Hardy Griech <ntbox@gmx.net>

rgrr force-pushed the cdc-ncm2 branch from a567af7 to cfd9b86 Compare June 3, 2024 06:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

usb: device_next: Simple NCM driver for usb-next #72310

usb: device_next: Simple NCM driver for usb-next #72310

rgrr commented May 4, 2024 •

edited by jfischer-no

Loading

josuah left a comment

josuah May 22, 2024

rgrr May 22, 2024

josuah May 22, 2024

rgrr May 22, 2024

josuah May 22, 2024

rgrr May 23, 2024

tmon-nordic May 23, 2024

rgrr May 23, 2024

rgrr commented May 22, 2024

josuah commented May 22, 2024

josuah commented May 22, 2024

rgrr commented May 22, 2024

rgrr commented May 22, 2024

josuah commented May 22, 2024

jukkar commented May 23, 2024

rgrr commented May 23, 2024

jukkar commented May 23, 2024

rgrr commented May 23, 2024

josuah commented May 23, 2024

josuah May 25, 2024

rgrr May 25, 2024

josuah Jun 3, 2024

	/** Header Functional Descriptor */
	struct cdc_header_descriptor {
	uint8_t bFunctionLength;
	uint8_t bDescriptorType;
	uint8_t bDescriptorSubtype;
	uint16_t bcdCDC;
	} __packed;

	/** Union Interface Functional Descriptor */
	struct cdc_union_descriptor {
	uint8_t bFunctionLength;
	uint8_t bDescriptorType;
	uint8_t bDescriptorSubtype;
	uint8_t bControlInterface;
	uint8_t bSubordinateInterface0;
	} __packed;

	/** Call Management Functional Descriptor */
	struct cdc_cm_descriptor {
	uint8_t bFunctionLength;
	uint8_t bDescriptorType;
	uint8_t bDescriptorSubtype;
	uint8_t bmCapabilities;
	uint8_t bDataInterface;
	} __packed;

	/** Abstract Control Management Functional Descriptor */
	struct cdc_acm_descriptor {
	uint8_t bFunctionLength;
	uint8_t bDescriptorType;
	uint8_t bDescriptorSubtype;
	uint8_t bmCapabilities;
	} __packed;

	/** Data structure for GET_LINE_CODING / SET_LINE_CODING class requests */
	struct cdc_acm_line_coding {
	uint32_t dwDTERate;
	uint8_t bCharFormat;
	uint8_t bParityType;
	uint8_t bDataBits;
	} __packed;

	/** Data structure for the notification about SerialState */
	struct cdc_acm_notification {
	uint8_t bmRequestType;
	uint8_t bNotificationType;
	uint16_t wValue;
	uint16_t wIndex;
	uint16_t wLength;
	uint16_t data;
	} __packed;

	/** Ethernet Networking Functional Descriptor */
	struct cdc_ecm_descriptor {
	uint8_t bFunctionLength;
	uint8_t bDescriptorType;
	uint8_t bDescriptorSubtype;
	uint8_t iMACAddress;
	uint32_t bmEthernetStatistics;
	uint16_t wMaxSegmentSize;
	uint16_t wNumberMCFilters;
	uint8_t bNumberPowerFilters;
	} __packed;

usb: device_next: Simple NCM driver for usb-next #72310

Are you sure you want to change the base?

usb: device_next: Simple NCM driver for usb-next #72310

Conversation

rgrr commented May 4, 2024 • edited by jfischer-no Loading

josuah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rgrr commented May 22, 2024

josuah commented May 22, 2024

josuah commented May 22, 2024

rgrr commented May 22, 2024

rgrr commented May 22, 2024

josuah commented May 22, 2024

jukkar commented May 23, 2024

rgrr commented May 23, 2024

jukkar commented May 23, 2024

rgrr commented May 23, 2024

josuah commented May 23, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rgrr commented May 4, 2024 •

edited by jfischer-no

Loading