Repository navigation
usb: add IsoEndpointIn and IsoInSlot for scheduled isochronous IN - #7559
Conversation
|
This pull request is a draft, so it isn't in the review queue yet. Mark it as ready for review when you'd like someone to look at it. |
7b9b7f0 to
18b1795
Compare
|
Tested on a NUCLEO-WBA65RI (synopsys OTG HS, high speed), head 18b1795, which sits on #7558 and #7561. The device writes one 64-byte packet per microframe with write_iso and puts a sequence number in each. The host tool polls the endpoint with libusb.
The same head also passes the control checks I ran on #7558, with transfers up to 400 bytes. Not covered: full speed, iso OUT, and the other drivers, which use the default write_iso and report nothing missed. |
18b1795 to
41f2303
Compare
|
@GrantM11235 let me know what you think... I'll look at this again after I get some rest 😪 |
|
May want to look at #7440, which is RP specific but seems to be an optimization for packet streaming, removing 1ms of latency per packet and avoiding delivery of stale buffered packets. Alters the contract for Also: does isochronous need a way to access/sync to the frame clock, for UAC for example? |
41f2303 to
1138229
Compare
|
@cryptographix both of these are the right questions. #7440. That change returns from an isochronous IN
#7440 can become an RP The cost is the same one #7440 describes. The next packet has to be queued within the frame after Frame clock. Not in this PR, on purpose. UAC pacing wants that clock while the packet is being prepared, not only when |
|
Re-ran the same NUCLEO-WBA65RI test (synopsys OTG HS, high speed) on head 1138229, which returns from
|
|
I'm still not a fan of putting this in the existing Endpoint traits, and I especially don't like the default impl that just doesn't really work right. I also think it's a little weird that you can't tell what happened to the last packet without sending a new packet. How does this work with intervals other than 1 (micro)frame? In the linux host side api, transfers are scheduled to happen at the next interval, not the next (micro)frame. What happens to a packet that is submitted too late? In the linux host side api, it depends on whether the |
|
On the default impl I see two ways I see to fix it: On the of the last packet: that's fair. Would an accessor on the endpoint or a status returned with the next scheduled packet fit better? On the Intervals: you're right. Periodic iso should schedule at the next service interval, derived from the endpoint's interval, not the next microframe. On late submission: I'd propose Linux's URB_ISO_ASAP behaviour as the model: by default a packet that misses its interval is dropped and counted, and the caller can opt in to sending it at the next interval. Is that the policy you want? I'll hold this out of the queue for now.... |
With the revised
Seems cleaner. You could then add Are you thinking about including a scheduler / multiple buffers in the new trait? Using existing |
|
I don't think the missing packet count is actually required, and it conflates two distinct errors:
The first case is hard to detect and handle because it happens some time after the write call returns. But we don't actually need to handle it aside from silently dropping the packet, which is perfectly normal for isochronous transfers. The second case is much easier because it can be detected before the write call returns, so we can just return an error. enum IsoError {
/// The data was not sent because it was submitted too late. It would have been sent at this frame in the past
TooLate(FrameNum)
/// The data to be sent is larger than the maximum transfer size for the endpoint
BufferOverflow,
/// The endpoint is disabled
Disabled,
}
trait IsoEndpointIn {
/// Schedules a packet to be sent at the next service interval.
/// `Ok(frame)` means the packet has been sent at this frame or is scheduled to be sent at this frame in the future.
async fn write(&mut self, buf: &[u8]) -> Result<FrameNum, IsoError>;
}If the device gets behind, it can catch up by repeatedly trying to send packets until it gets I'm not sure if Queue Depth
As far as I understand it, #7440 just changes the queue depth from one to zero. Because it's a tradeoff between slack, latency, and memory usage, I think that the queue depth should be configurable by the user. I don't think that class drivers need to care about the queue depth, but maybe there are cases where they need to be able to query it. |
|
This is what I think should happen when the endpoint is enabled: There needs to be a way to await for the first IN token, like After we see the first IN token, we know the initial frame number and we can start accepting packets into the queue, with the first one scheduled to be sent at frame number Note that we can't start queuing packets before we get the first IN token, because we don't know what frame they will be scheduled for. This is a problem because we are reporting the frame number when the packet is queued instead of after it is sent. |
|
@GrantM11235 and @leftger - the proposed scheduled model works for me, so I prototyped it on RP2350, with a synth streaming UAC1 audio to macOS: The API shape I protoed abstracts the frame counter into pub trait IsoEndpointIn: Endpoint {
/// Waits until the next packet can be queued, and numbers its slot. Cancel-safe.
async fn ready(&mut self) -> Result<IsoSlot, EndpointError>;
/// Queues one packet for `slot`, without waiting.
fn write_slot(&mut self, slot: IsoSlot, data: &[u8]) -> Result<(), IsoWriteError>;
}
impl IsoSlot {
pub const fn index(&self) -> u32; // service interval number, from the bus clock
pub const fn skipped(&self) -> u32; // slots the writer left unfilled
}
pub enum IsoWriteError { TooLate, BufferOverflow, Disabled }Details:
Doing it this way seems to eliminate the need for Results on RP2350 at a 1 ms interval:
Tested only on RP - FS with 1 queued packet and no intervals above 1 ms Does this work for you? |
|
@GrantM11235 @cryptographix:
Synopsys arms one packet at a time. There's no |
|
@leftger, looking good! Do we really want "incorrect" defaults in trait or should drivers only implement Two x We map Reworked and tested my RP impl. with no issues. Can send as a follow-on PR when this lands. Test Results: | Stream open | 300.1 s | |
|
I really like the idea of asynchronously reserving a slot, then writing to it synchronously. By changing the API a bit, it is possible to prevent some errors like using a slot with a different endpoint or trying to reserve two slots and using them out of order. pub enum IsochronousWriteError {
TooLate,
BufferOverflow,
Disabled,
}
pub trait IsochronousInSlot {
// TODO: should it be possible to reuse the slot if this returns `BufferOverflow`?
fn write(self, data: &[u8]) -> Result<(), IsochronousWriteError>;
// Even better, we can write directly into the HALs buffer, which is the size of the max packet.
// This may eliminate a copy, and we can get rid of `BufferOverflow`.
// (Unless the closure returns a nonsense length, but we can just panic in that case)
fn write_with(self, f: impl FnOnce(&mut [u8]) -> usize) -> Result<(), IsochronousWriteError>;
// `if slot.skipped.is_some()` is slightly nicer than `if slot.skipped != 0`
fn skipped(&self) -> Option<NonZeroU32>;
// the index number is an implementation detail, it doesn't need to be exposed
}
/// Isochronous IN Endpoint trait.
pub trait IsochronousEndpointIn: Endpoint {
// TODO: does this need a lifetime?
type Slot: IsochronousInSlot;
/// # Cancel Safety
///
/// If the future or the slot is dropped, the slot should become available again
async fn ready(&mut self) -> Result<Self::Slot, EndpointDisabledError>;
// or the function could also wait for the endpoint to be enabled
async fn ready(&mut self) -> Self::Slot;
}I've changed my mind about exposing the frame number to the class driver. As long as the HAL handles the scheduling and can report any skipped slots, the class driver doesn't need to know the exact frame number. That means the HALs don't need to agree on how many bits to use, or how to handle frames vs microframes.
I don't think that works for intervals other than 1. For an interval of 2, the host can decide whether to use the even or odd frames, and there is no way to know that until the first IN token comes in. I think it's possible to work around that though, as long as we don't tell the class driver which frame we will use. We would schedule the first packet for frame 0, then reschedule it for frame 1 if there wasn't an IN token. If there is still no IN token, we need to drop the first packet and schedule the second packet for frame 2, then frame 3, etc. After we get an IN token, we can lock in and only schedule for the correct even or odd frame. This shouldn't change as long as the endpoint stays enabled.
In that case, maybe the behavior of skipped slots needs to be implementation defined. Based on the datasheet for the STM32F411 USB OTG (synopsys?), it sounds like the hardware always responds to IN tokens for disabled/unarmed endpoints with an empty packet, and it doesn't look like there is a way to change that. Maybe the RP should try to match that behavior in software for consistency?
I don't think we should have any bad default impls, I think we should plan to have proper support in all the HAL drivers (there aren't that many, right?) by the time we release the new version. If any of the major impls can't support it, it's better if we know about it before the release so we can change the API to fit. I haven't looked very hard at the actual changes in this PR yet, partly because it currently has a lot of backwards compatibility stuff that I am hoping will be removed, if possible.
I don't think so |
Add IsoEndpointIn and borrowing IsoInSlot traits in embassy-usb-driver with no fallback defaults, and implement them across all four embassy device drivers: synopsys-otg (STM32 OTG / nRF54 USBHS), embassy-rp, embassy-stm32 (non-OTG USB), and embassy-nrf (USBD EP8). - ready() asynchronously reserves a borrowing Slot<'_> for the next service interval and returns EndpointDisabledError when disabled. - IsoInSlot::write(self, data) synchronously queues one packet for the slot, returning IsoWriteError (TooLate, BufferOverflow, Disabled). - IsoInSlot::skipped() returns Option<NonZeroU32> for empty intervals left by a late writer; uncollected packets are dropped silently. - IsoSchedule locks the host polling phase on the first completed IN transfer for intervals > 1 instead of assuming frame % interval == 0. - UAC IN classes expose ready() and update write_packet() to return Result<Option<NonZeroU32>, IsoWriteError> without mapping TooLate to Disabled.
ba9aa8d to
8812b1e
Compare
|
@GrantM11235 @cryptographix Rebased onto
|
|
Hold on, I have a few more suggestions |
|
I think we've covered the major overarching issues. I think we're getting into the realm of diminishing returns. Any other issues can be covered by a follow-up PR. |
Rebased onto current
main. All backwards-compatibility shims and default fallback trait methods have been removed.An isochronous IN packet that the host does not poll for in its service interval should be dropped rather than sent late, so the writer can move on to fresh data.
EndpointIn::write_transferis the wrong shape for that:needs_zlpand multi-packet chunking do not apply to isochronous transfers, and it has no way to schedule by service interval or report intervals left empty by a late writer.API (
embassy-usb-driver)IsoEndpointIn: Endpoint(no fallback defaults):type Slot<'a>: IsoInSlot where Self: 'afn queue_depth(&self) -> u8async fn ready(&mut self) -> Result<Self::Slot<'_>, EndpointDisabledError>— asynchronously reserves a borrowing slot for the next service interval. Cancel-safe: dropping the future or slot leaves nothing armed.IsoInSlot:fn skipped(&self) -> Option<NonZeroU32>— empty service intervals left by the writer before this slot (uncollected packets dropped by the controller are not counted).fn write(self, data: &[u8]) -> Result<(), IsoWriteError>— synchronously queues one packet for the slot, returningTooLate,BufferOverflow, orDisabled.iso::IsoSchedule: helper for drivers that tracks wraps, skipped intervals, and host polling phase lock forinterval > 1.Drivers & Classes
embassy-usb-synopsys-otg(STM32 OTG FS/HS, nRF54 USBHS):ready()waits until the previous packet has been sent or dropped, TX FIFO has space, and the target tick is one tick away;IsoSlot::write()arms synchronously. Forinterval > 1,XFRClocks the host's polling phase andIISOIXFRprobes remaining ticks of an unlocked interval with 0-byte ZLPs.embassy-rp(RP2040 / RP2350): usesDEV_SOF+SOF_RD, disarms uncollected packets on expiry at SOF, arms FS ISO IN withDATA0, and locks phase onbuff_status.embassy-stm32(non-OTG USBusb_v1–usb_v4): usesFNR.FN+ISTR.SOF, zeroes both PMA lengths when idle or expired so uncollected packets are dropped and unarmed polls receive a ZLP, and locks phase onCTR_TX.embassy-nrf(USBD EP8): usesFRAMECNTR+EVENTS_SOFwith synchronous EasyDMA load inIsoSlot::write(); hardware latches ISOIN at SOF and sendsZeroDataZLPs when unarmed.embassy-usb(UAC):Stream,Feedback, andLineInStreamexposeready()and updatewrite_packet()to returnResult<Option<NonZeroU32>, IsoWriteError>without mappingTooLatetoDisabled. UAC examples updated accordingly.