summaryrefslogtreecommitdiff
path: root/docs/library
diff options
context:
space:
mode:
Diffstat (limited to 'docs/library')
-rw-r--r--docs/library/machine.USBDevice.rst20
1 files changed, 15 insertions, 5 deletions
diff --git a/docs/library/machine.USBDevice.rst b/docs/library/machine.USBDevice.rst
index 82897b280..e02d3c02d 100644
--- a/docs/library/machine.USBDevice.rst
+++ b/docs/library/machine.USBDevice.rst
@@ -130,15 +130,25 @@ Methods
Second argument is a memoryview to read the USB control request
data for this stage. The memoryview is only valid until the
- callback function returns.
+ callback function returns. Data in this memoryview will be the same
+ across each of the three stages of a single transfer.
+
+ A successful transfer consists of this callback being called in sequence
+ for the three stages. Generally speaking, if a device wants to do
+ something in response to a control request then it's best to wait until
+ the ACK stage to confirm the host controller completed the transfer as
+ expected.
The callback should return one of the following values:
- - ``False`` to stall the endpoint and reject the transfer.
+ - ``False`` to stall the endpoint and reject the transfer. It won't
+ proceed to any remaining stages.
- ``True`` to continue the transfer to the next stage.
- - A buffer object to provide data for this stage of the transfer.
- This should be a writable buffer for an ``OUT`` direction transfer, or a
- readable buffer with data for an ``IN`` direction transfer.
+ - A buffer object can be returned at the SETUP stage when the transfer
+ will send or receive additional data. Typically this is the case when
+ the ``wLength`` field in the request has a non-zero value. This should
+ be a writable buffer for an ``OUT`` direction transfer, or a readable
+ buffer with data for an ``IN`` direction transfer.
- ``xfer_cb`` - This callback is called whenever a non-control
transfer submitted by calling :func:`USBDevice.submit_xfer` completes.