From 351ad49b3afebeaa25ce471e8e5b82e6b97b5915 Mon Sep 17 00:00:00 2001 From: Chris Dickens Date: Tue, 18 Aug 2020 10:14:50 -0700 Subject: [PATCH] Documentation: Add section regarding transfer length limitations Closes #204 Signed-off-by: Chris Dickens --- libusb/io.c | 19 +++++++++++++------ libusb/sync.c | 6 +++++- libusb/version_nano.h | 2 +- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/libusb/io.c b/libusb/io.c index 3eedf44..18fe755 100644 --- a/libusb/io.c +++ b/libusb/io.c @@ -458,14 +458,21 @@ if (r == 0 && actual_length == sizeof(data)) { * libusb_get_iso_packet_buffer() and libusb_get_iso_packet_buffer_simple() * functions may help you here. * - * Note: Some operating systems (e.g. Linux) may impose limits on the - * length of individual isochronous packets and/or the total length of the - * isochronous transfer. Such limits can be difficult for libusb to detect, - * so the library will simply try and submit the transfer as set up by you. - * If the transfer fails to submit because it is too large, + * \section asynclimits Transfer length limitations + * + * Some operating systems may impose limits on the length of the transfer data + * buffer or, in the case of isochronous transfers, the length of individual + * isochronous packets. Such limits can be difficult for libusb to detect, so + * in most cases the library will simply try and submit the transfer as set up + * by you. If the transfer fails to submit because it is too large, * libusb_submit_transfer() will return * \ref libusb_error::LIBUSB_ERROR_INVALID_PARAM "LIBUSB_ERROR_INVALID_PARAM". * + * The following are known limits for control transfer lengths. Note that this + * length includes the 8-byte setup packet. + * - Linux (4,096 bytes) + * - Windows (4,096 bytes) + * * \section asyncmem Memory caveats * * In most circumstances, it is not safe to use stack memory for transfer @@ -1446,7 +1453,7 @@ static int remove_from_flying_list(struct usbi_transfer *itransfer) * \returns LIBUSB_ERROR_NOT_SUPPORTED if the transfer flags are not supported * by the operating system. * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than - * the operating system and/or hardware can support + * the operating system and/or hardware can support (see \ref asynclimits) * \returns another LIBUSB_ERROR code on other failure */ int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer) diff --git a/libusb/sync.c b/libusb/sync.c index eac7572..9ec279f 100644 --- a/libusb/sync.c +++ b/libusb/sync.c @@ -91,7 +91,7 @@ static void sync_transfer_wait_for_completion(struct libusb_transfer *transfer) * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected * \returns LIBUSB_ERROR_BUSY if called from event handling context * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than - * the operating system and/or hardware can support + * the operating system and/or hardware can support (see \ref asynclimits) * \returns another LIBUSB_ERROR code on other failures */ int API_EXPORTED libusb_control_transfer(libusb_device_handle *dev_handle, @@ -267,6 +267,8 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle, * \ref libusb_packetoverflow * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected * \returns LIBUSB_ERROR_BUSY if called from event handling context + * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than + * the operating system and/or hardware can support (see \ref asynclimits) * \returns another LIBUSB_ERROR code on other failures */ int API_EXPORTED libusb_bulk_transfer(libusb_device_handle *dev_handle, @@ -319,6 +321,8 @@ int API_EXPORTED libusb_bulk_transfer(libusb_device_handle *dev_handle, * \ref libusb_packetoverflow * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected * \returns LIBUSB_ERROR_BUSY if called from event handling context + * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than + * the operating system and/or hardware can support (see \ref asynclimits) * \returns another LIBUSB_ERROR code on other error */ int API_EXPORTED libusb_interrupt_transfer(libusb_device_handle *dev_handle, diff --git a/libusb/version_nano.h b/libusb/version_nano.h index 8a29e15..0c22d52 100644 --- a/libusb/version_nano.h +++ b/libusb/version_nano.h @@ -1 +1 @@ -#define LIBUSB_NANO 11540 +#define LIBUSB_NANO 11541 -- 2.7.4