From d014a11545115004a7e74e4a060ec6cd97f3a5de Mon Sep 17 00:00:00 2001 From: Martin Ling Date: Thu, 1 Sep 2022 13:19:05 +0200 Subject: docs: Clear endpoint halt issued after cancellation only for macOS < 10.5 Also remove comment about possible endpoint halt, which seems not correct, as discussed in issue #1110. References #1110 Closes #1117 Signed-off-by: Tormod Volden --- libusb/io.c | 32 +++++++++++++++++--------------- libusb/version_nano.h | 2 +- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/libusb/io.c b/libusb/io.c index 2f38d67..e4753fc 100644 --- a/libusb/io.c +++ b/libusb/io.c @@ -311,11 +311,11 @@ if (r == 0 && actual_length == sizeof(data)) { * libusb_cancel_transfer() is asynchronous/non-blocking in itself. When the * cancellation actually completes, the transfer's callback function will * be invoked, and the callback function should check the transfer status to - * determine that it was cancelled. On macOS and iOS it is not possible to - * cancel a single transfer. In this case cancelling one tranfer on an endpoint - * will cause all transfers on that endpoint to be cancelled. In some cases - * the call may cause the endpoint to stall. A call to \ref libusb_clear_halt - * may be needed. + * determine that it was cancelled. + * + * On macOS and iOS it is not possible to cancel a single transfer. In this + * case cancelling one transfer on an endpoint will cause all transfers on + * that endpoint to be cancelled. * * Freeing the transfer after it has been cancelled but before cancellation * has completed will result in undefined behaviour. @@ -1588,16 +1588,18 @@ int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer) * \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED * "LIBUSB_TRANSFER_CANCELLED" for each transfer that was cancelled. - * - Calling this function also sends a \c ClearFeature(ENDPOINT_HALT) request - * for the transfer's endpoint. If the device does not handle this request - * correctly, the data toggle bits for the endpoint can be left out of sync - * between host and device, which can have unpredictable results when the - * next data is sent on the endpoint, including data being silently lost. - * A call to \ref libusb_clear_halt will not resolve this situation, since - * that function uses the same request. Therefore, if your program runs on - * Darwin and uses a device that does not correctly implement - * \c ClearFeature(ENDPOINT_HALT) requests, it may only be safe to cancel - * transfers when followed by a device reset using + * - When built for macOS versions prior to 10.5, this function sends a + * \c ClearFeature(ENDPOINT_HALT) request for the transfer's endpoint. + * (Prior to libusb 1.0.27, this request was sent on all Darwin systems.) + * If the device does not handle this request correctly, the data toggle + * bits for the endpoint can be left out of sync between host and device, + * which can have unpredictable results when the next data is sent on + * the endpoint, including data being silently lost. A call to + * \ref libusb_clear_halt will not resolve this situation, since that + * function uses the same request. Therefore, if your program runs on + * macOS < 10.5 (or libusb < 1.0.27), and uses a device that does not + * correctly implement \c ClearFeature(ENDPOINT_HALT) requests, it may + * only be safe to cancel transfers when followed by a device reset using * \ref libusb_reset_device. * * \param transfer the transfer to cancel diff --git a/libusb/version_nano.h b/libusb/version_nano.h index 99985a0..f30d8ef 100644 --- a/libusb/version_nano.h +++ b/libusb/version_nano.h @@ -1 +1 @@ -#define LIBUSB_NANO 11756 +#define LIBUSB_NANO 11757 -- cgit v1.2.1