USB: notifications overhaul

[carlescufi]

USB notifications currently use callbacks. This issue is to document the requirements of USB notifications to be able to decide which mechanism to use in the new, overhauled USB support (both Device and Host).

Notification examples/types:

• Device connected to Vbus (presence of voltage in Vbus). Could then trigger power management logic
• Device is configured
• Device is suspended
• Device is resumed
• Class-specific notifications
  • Interface active (eg. network interface up)
  • CDC ACM line state change request arrived from the Host (even if the line state itself doesn't change)
  • Audio stream started

High-frequency events such as SoF are not going through this notification mechanism.
Data itself is not going through the notification mechanism.
Notifications are purely informational: i.e. they are not designed to ask the user/app for a response to be included in a response packet to a request packet from the USB Host. Those instead will go through the class-specific synchronous internal callback API.

Requirements of USB notifications:

• Intended only for USB users/clients. USB classes (including custom ones) use a synchronous internal callback API
• Intended only for notification purposes, not as a mechanism to execute any action that then maps to a "response packet over the wire"
• One-way notifications
• Pub/sub: Multiple listener/observer support
• Common publishing mechanism for class implementations as well as core USB stack notifications
• Execution in a context that does not impact the USB functionality
• Try to avoid immediate context-switch upon posting of a notification, instead the USB stack should be able to enqueue multiple notifications without being swapped out, and then the thread/context that processes the notifications and invokes the listeners gets to run
• Notifications shall not be dropped/lost (except potentially isochronous ones). Instead, the USB stack should block/NAK or error out (depending on which decision is taken wrt the synchronicity) if the event "slots" run out. Once the app has processed an event and freed it, the host can proceed.

Options available:

~~a. Traditional synchronous callbacks

• Block the USB stack execution until the notification has been acknowledged (i.e. callback returns)
• Called always from the same context (never from ISR or driver thread): the main USB context~~

b. Traditional callbacks, with the following provisions in order to fulfill the requirements:

• Callback registration both at compile-time (i.e. places the callback in a linker sections) and runtime (i.e. the linker section is extended with a linked list in RAM)
• Dedicated workqueue/thread/context to execute the callbacks
• Linked List of events instead of FIFO to avoid rescheduling
• Potentially configurable execution context (dedicated workqueue, user-supplied workqueue or even other mechanisms)

c. An event manager/bus

• Event Manager: event manager: Implement event manager  #38611
• Zbus: zbus: Add Zephyr message bus #48509
• VBUS: dec1695
  • Effectively a simple Workqueue+registration+callback mechanism

CC @desowin @anangl @gmarull

[rodrigopex]

Synchronous (callback + multiple listeners) and asynchronous (pub/sub) notifications can be done easily using Zbus. I can help to design that if you guys need it.

[jfischer-no]

Synchronous (callback + multiple listeners)

It should be generally not synchronous, it is not stated anywhere.

and asynchronous (pub/sub) notifications can be done easily using Zbus.

We know it otherwise it would not be in the list, though easily is subjective 😉 .

[desowin]

How to handle control transfer application specific hooks? For example the reporter of #50759 wants to have application code executed on every SET_CONTROL_LINE_STATE request. I believe the best way to way to achieve it is to have callback execute in USB stack context and it would be application developer responsibility to write reasonable code in the callback.

I believe it is important to execute control transfer related code synchronously (i.e. stack waits for application provided code to finish) due to Universal Serial Bus Specification Revision 2.0 9.2.6 Request Processing:

The device is expected to “complete” processing of the request before it allows the Status stage to complete successfully. Some requests initiate operations that take many milliseconds to complete. For requests such as this, the device class is required to define a method other than Status stage completion to indicate that the operation has completed.

There would be protocol violation if the application specific control transfer code is executed asynchronously in lower priority thread (and it is not a request with other method to indicate operation status). That is, the application code executing on the host would think that operation fully finished before it really had.

High-level communications overview for those who are familiar with Zephyr, but not with USB

Transfer direction is always from host perspective, that is OUT = host to device, IN = device to host. Every communication is initiated by host and takes place between host and device (there is no device-to-device communication). Endpoint is essentially a data buffer. OUT endpoints can be written to by host, IN endpoints can be read by host.

USB in general is perfectly suited for relatively slow devices. The device limits the flow rate by sending NAK if:

• the software did not put any data in IN endpoint buffer,
• device cannot receive packet in OUT endpoint buffer because software did not read (and process) the previously written packet (in HS there is PING/NYET, but overall idea is the same),
• didn't complete control transfer request handling (status stage).

The NAK is automatically sent by USB device controller without any software intervention (otherwise it would be impossible to respect the timeout at the device connector: 6.5 bit times on Full-Speed = 541.5 ns, 192 bit times on High-Speed = 400 ns).

All the software has to do in order to not lose any non-isochronous (i.e. not live streamed audio/video) data is not lying about its endpoint state. For bulk transfers, e.g. CDC ACM or Mass Storage, the time after which the host gives up is pretty long. For example if the device doesn't want to lose any CDC ACM data from host all it has to do is to not make the OUT endpoint available for new packet before the device can process and/or buffer next OUT packet somewhere.

[jfischer-no]

How to handle control transfer application specific hooks? For example the reporter of #50759 wants to have application code executed on every SET_CONTROL_LINE_STATE request. I believe the best way to way to achieve it is to have callback execute in USB stack context and it would be application developer responsibility to write reasonable code in the callback.

Again, neither that, nor #50759 is about hooks in request processing. Generally there will be no user hooks in request processing, there is simply no reason for it. Here and in #50759 it is about notifying user that something has taken place, user has no direct influence on it.

[zephyrbot]

Hi @jfischer-no,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. Please confirm the issue is correctly assigned and re-assign it otherwise.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

@carlescufi you are also encouraged to help moving this issue forward by providing additional information and confirming this request/issue is still relevant to you.

Thanks!