WinUSB Functions for Pipe Policy Modification

Bulk (OUT)

Interrupt (OUT)

Bulk (IN)

Interrupt (IN)

Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)

Bulk (IN)

Interrupt (IN)

Bulk (IN)

Interrupt (IN)

Bulk (IN)

Interrupt (IN)

Bulk (IN)

Interrupt (IN)

Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)

Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)

If enabled (policy parameter value is TRUE or nonzero), every write request that is a multiple of the maximum packet size supported by the endpoint, is followed by a zero-length packet.

After sending data to the host controller, WinUSB sends a write request with a zero-length packet and then completes the request that was created by WinUsb_WritePipe.

• If enabled (policy parameter value is TRUE or nonzero), a stall condition is cleared automatically. This policy parameter does not affect control pipes.

  When a read request fails and the host controller returns a status other than STATUS_CANCELLED or STATUS_DEVICE_NOT_CONNECTED, WinUSB resets the pipe before completing the failed request. Resetting the pipe clears the stall condition without interrupting the data flow. Data continues to flow in the endpoints as long as new transfers keep arriving from the device. A new transfer can include one that was in the queue when the stall occurred.

  Enabling this policy does not significantly impact performance.

• If disabled (policy parameter value is FALSE or zero), all transfers that arrive to the endpoint after the stalled transfer fail until the caller manually resets the endpoint's pipe by calling WinUsb_ResetPipe.

• If set to zero (default), transfers will not time out because the host controller will not cancel the transfer. In this case, the transfer waits indefinitely until it is manually canceled or the transfer completes normally.
• If set to a nonzero value (time-out interval), the host controller starts a timer when it receives the transfer request. When the timer exceeds the set time-out interval, the request is canceled.

  A minor performance penalty will occur due to timer management.

  Note  Requests do not time out while waiting in a WinUSB queue.

  In Windows Vista, for all transfers (except transfers with RAW_IO enabled), WinUSB queues the request until all previous transfers on the destination endpoint have been completed. The host controller does not include the queuing time in the calculation of the time-out interval.

  With RAW_IO enabled, WinUSB does not queue the request. Instead, it passes the request directly to the USB stack, whether the USB stack is busy processing previous transfers. If the USB stack is busy, it can delay processing the new request. Note that this can cause a time-out.

• If enabled (policy parameter value is TRUE or nonzero), the host controller will not complete a read operation immediately after it receives a short packet. Instead, it completes the operation only if:
  • An error occurs.
  • The request is canceled.
  • All the requested bytes have been received.
• If disabled (policy parameter value is FALSE or zero), the host controller completes a read operation after it has read the requested number of bytes or has received a short packet.

Use if your application wants to read a few bytes to determine how many total bytes to read.

• If disabled (policy parameter value is FALSE or zero) and the device returns more data than was requested, WinUSB completes the request with an error.
• If enabled (policy parameter value is TRUE or nonzero) and the device returns more data than was requested, WinUSB can (depending on AUTO_FLUSH settings) add the excess data from the read request to the beginning of the next read request or discard the excess data.

  If enabled, WinUSB immediately completes read requests for zero bytes successfully and will not send the requests down the stack.

The device can send more data than was requested, and your application does not require any additional data. This is possible if the size of your request buffer is a multiple of the maximum endpoint packet size.

AUTO_FLUSH defines WinUSB's behavior when ALLOW_PARTIAL_READS is enabled. If ALLOW_PARTIAL_READS is disabled, the AUTO_FLUSH value is ignored by WinUSB.

WinUSB can either discard the remaining data or send it with the caller's next read request.

• If enabled (policy parameter value is TRUE or nonzero), WinUSB discards the extra bytes without any error code.
• If disabled (policy parameter value is FALSE or zero), WinUSB saves the extra bytes, adds them to the beginning of the caller's next read request, and then sends the data to the caller in the next read operation.

RAW_IO imposes certain restrictions on the buffer that is passed by the caller in WinUsb_ReadPipe:

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

If enabled, transfers bypass queuing and error handling to boost performance for multiple read requests. WinUSB handles read requests as follows:

• A request that is not a multiple of the maximum endpoint packet size fails.
• A request that is greater than the maximum transfer size supported by WinUSB fails.
• All well-formed requests are immediately sent down to the USB core stack to be scheduled in the host controller.