Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions packages/usb/usb-core/usb/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 24 additions & 0 deletions tests/test_usb_host_streams.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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")
Expand Down Expand Up @@ -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)
Expand Down