windows: Add option for WinUSB RAW_IO endpoint policy

Add support for enabling or disabling the WinUSB RAW_IO pipe policy for
a given endpoint, which is documented here:

https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb-functions-for-pipe-policy-modification

This is necessary to increase performance. Without this option the
WinUSB backend will only queue one inbound operation at a time, even if
the libusb async API is used to submit multiple transfers.

For real-time sampling devices with high sample rates and small buffers,
the use of RAW_IO combined with queued async transfers is essential to
maintaining the necessary throughput and avoiding lost samples or buffer
overruns.

Examples of devices affected include Cypress FX2 based logic analyzers
accessed using Sigrok, and the HackRF software defined radio.

The new option must be set by calling libusb_set_option with the arguments:

libusb_set_option(ctx, LIBUSB_OPTION_WINUSB_RAW_IO, dev_handle,
                  endpoint_address, enable, max_transfer_size_ptr)

where the types of the variadic arguments are:

libusb_device_handle *dev_handle;
unsigned int endpoint_address;
unsigned int enable;
unsigned int *max_transfer_size_ptr;

The dev_handle and endpoint_address parameters must identify a valid IN
endpoint on an open device. If enable is nonzero, RAW_IO is enabled,
otherwise it is disabled. Unless max_transfer_size_ptr is NULL, then on
a successful call to enable RAW_IO, the pointer destination will be
written with the MAXIMUM_TRANSFER_SIZE value for the endpoint.

Whilst RAW_IO is enabled for an endpoint, all transfers on that endpoint
must meet the following two requirements:

- The buffer length must be a multiple of the maximum endpoint packet size.
- The length must be less than or equal to the MAXIMUM_TRANSFER_SIZE value.

This option should not be changed when any transfer is in progress on
the specified endpoint.

This option only affects the WinUSB backend. On other backends it is
ignored and returns LIBUSB_ERROR_NOT_SUPPORTED, without modifying the
value pointed to by max_transfer_size_ptr.

A great deal of credit is due to Petteri Aimonen and Patrick Stewart for
previous work, and to everyone else who participated in discussions.

Fixes #490
Closes #1208

1 files changed, 1 insertions, 1 deletions

diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index ade020c..1874d60 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 11770
+#define LIBUSB_NANO 11771