From 6a46e32df240d36beab0e4afcbfa5b2012cae261 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Sat, 21 Nov 2026 14:33:11 -0600 Subject: [PATCH] usb.core: a read that times out keeps its transfer, so no packet is lost With usbhost firmware that leaves a timed-out IN transfer armed, the default read's quarter-second steps and a raising timeout no longer cancel a transfer the device is filling. The docstring says so, and the tests pin that the default read rides through timeouts and returns a zero-length packet as 0. --- packages/usb/usb-core/usb/core.py | 15 +++++++++++---- tests/test_usb_host_streams.py | 24 ++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/packages/usb/usb-core/usb/core.py b/packages/usb/usb-core/usb/core.py index cfc8ff85..3cab3561 100644 --- a/packages/usb/usb-core/usb/core.py +++ b/packages/usb/usb-core/usb/core.py @@ -403,14 +403,21 @@ def write(self, endpoint, data, timeout=None): def read(self, endpoint, size_or_buffer, timeout=None, *, raise_on_timeout=True): """Read from a bulk or interrupt IN endpoint: into a buffer, giving the count, or up to a size, giving an array. timeout None or 0 waits - for data, a quarter-second at a time so Ctrl-C still works. + for data, a quarter-second at a time so Ctrl-C still works. A + zero-length packet ends the read and gives 0. + + A read that times out leaves its transfer armed, and the next read + of the endpoint collects it, so a packet that arrives as the timeout + passes isn't lost. The next read can then return fewer bytes than + it asks for, as any read can. (On a firmware whose usbhost predates + this, a read that raises USBTimeoutError cancels its transfer, and + a packet arriving just then can be lost.) With ``raise_on_timeout=False`` (as in CircuitPython), a timeout returns 0 instead of raising USBTimeoutError, and a read into a buffer allocates nothing: poll an interrupt endpoint with a short - timeout and "no report yet" costs no garbage. The transfer stays - armed between such reads, so a report that lands in between is - kept for the next one. + timeout and "no report yet" costs no garbage. A zero-length packet + also returns 0. A negative timeout, with ``raise_on_timeout=False``, doesn't wait at all: the read returns what the armed transfer has brought, or 0 at diff --git a/tests/test_usb_host_streams.py b/tests/test_usb_host_streams.py index 27f5c42c..73585826 100644 --- a/tests/test_usb_host_streams.py +++ b/tests/test_usb_host_streams.py @@ -88,6 +88,7 @@ def reset(self, blob, ranges=(48000, 48000, 0), probe_payload=944, refuse_claim= self.streams = {} self.probe = bytearray(34) self.report = None + self.replies = [] # scripted reads: bytes, or None for a timeout self.gone = None # an errno once the device is unplugged self.host_poll = self._host_poll # absent on a firmware that predates it @@ -110,6 +111,14 @@ def host_stats(self): def host_xfer(self, dev_id, ep, buf, timeout, raise_on_timeout=True): self.calls.append(("xfer", ep, timeout, raise_on_timeout)) + if self.replies: + reply = self.replies.pop(0) + if reply is None: + if raise_on_timeout: + raise OSError(110, "ETIMEDOUT") + return 0 + buf[:len(reply)] = reply + return len(reply) if self.report is None: if raise_on_timeout: raise OSError(110, "ETIMEDOUT") @@ -716,6 +725,21 @@ def test_the_default_still_raises(self): with self.assertRaises(usb.core.USBTimeoutError): self.dev.read(self.ep, bytearray(8), timeout=5) + def test_a_read_without_a_timeout_waits_through_quarter_seconds(self): + host.replies = [None, None, b"\x05\x06\x07"] + buf = bytearray(8) + self.assertEqual(self.dev.read(self.ep, buf), 3) + self.assertEqual(buf[:3], b"\x05\x06\x07") + steps = [c for c in host.calls if c[0] == "xfer"] + self.assertEqual(steps, [("xfer", self.ep, 250, True)] * 3) + + def test_a_zero_length_packet_ends_a_read_without_a_timeout(self): + # The host raises on a timeout and leaves the transfer armed, so a + # zero-length packet is told apart from "nothing yet" and returned. + host.replies = [None, b"", b"\x01"] + self.assertEqual(self.dev.read(self.ep, bytearray(8)), 0) + self.assertEqual(host.replies, [b"\x01"]) + def test_the_descriptor_is_read_once_not_per_read(self): buf = bytearray(8) self.dev.read(self.ep, buf, timeout=1, raise_on_timeout=False)