Muokkaa

WinUSB functions for pipe policy modification

  • Artikkeli

To enable applications to get and set an endpoint pipe's default policy parameters, Winusb.dll exposes the WinUsb_GetPipePolicy function to retrieve the pipe's default policy. The WinUsb_SetPipePolicy function allows an application to set the policy parameter to a new value.

WinUSB allows you to modify its default behavior by applying policies to an endpoint's pipe. By using these policies, you can configure WinUSB to best match your device to its capabilities. The following table provides a list of the pipe policies supported by WinUSB.

Note

The policies described in the table are valid only for the specified endpoints. Setting the policy on other endpoints has no effect on WinUSB's behavior for read or write requests.

Policy number Policy name Description Endpoint (direction) Default value
0x01 SHORT_PACKET_TERMINATE Sends a zero length packet for a write request in which the buffer is a multiple of the maximum packet size supported by the endpoint. Bulk (OUT)

Interrupt (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Automatically clears a stalled pipe without stopping the data flow. Bulk (IN)

Interrupt (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Waits for a time-out interval, in milliseconds, before canceling the request. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 5 seconds (5000 milliseconds) for control; 0 for others
0x04 IGNORE_SHORT_PACKETS Completes a read request when a short packet is received or a certain number of bytes are read. If the file size is unknown, the request is terminated at a short packet. Bulk (IN)

Interrupt (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Allows read requests from a device that returns more data than requested by the caller. Bulk (IN)

Interrupt (IN)		 TRUE
0x06 AUTO_FLUSH Saves the excess data from the read request and adds it to the next read request or discards the excess data. Bulk (IN)

Interrupt (IN)		 FALSE
0x07 RAW_IO Bypasses queuing and error handling to boost performance for multiple read requests. Bulk (IN)

Interrupt (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Gets the maximum size of a USB transfer supported by WinUSB. This is a read-only policy that can be retrieved by calling WinUsb_GetPipePolicy. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)
0x09 RESET_PIPE_ON_RESUME Resets the endpoint's pipe after resuming from suspend before accepting new requests. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 FALSE

The following table identifies best practices for how to use each of the pipe policies and describes the resulting behavior when the policy is enabled.

Policy Enable if... Behavior
SHORT_PACKET_TERMINATE(0x01) The device requires the OUT transfers to be terminated with a zero-length packet. Most devices don't have this requirement. 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.
AUTO_CLEAR_STALL You don't want the failed transfers to leave the endpoint in a stalled state. This policy is useful only when you have multiple pending read requests to the endpoint when RAW_IO is disabled.
  • If enabled (policy parameter value is TRUE or nonzero), a stall condition is cleared automatically. This policy parameter doesn't 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 doesn't 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.
PIPE_TRANSFER_TIMEOUT You expect transfers to an endpoint to complete within a specific time.
  • If set to zero (default), transfers won't time out because the host controller won't cancel the transfer. In this case, the transfer waits indefinitely until it's 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 occurs due to timer management.

    Requests don't 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 doesn't include the queuing time in the calculation of the time-out interval.

    With RAW_IO enabled, WinUSB doesn't 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. This can cause a time-out.
IGNORE_SHORT_PACKETS RAW_IO is disabled and you don't want short packets to complete the read requests.
  • If enabled (policy parameter value is TRUE or nonzero), the host controller won't 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.
ALLOW_PARTIAL_READS The device can send more data than requested if the size of your request buffer is a multiple of the maximum endpoint packet size.

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 won't send the requests down the stack.
AUTO_FLUSH ALLOW_PARTIAL_READS policy is enabled.

The device can send more data than was requested, and your application doesn't require any other 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 Performance is a priority and the application submits simultaneous read requests to the same endpoint.

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 isn't 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.


Enabling this setting significantly improves the performance of multiple read requests by reducing the delay between the last packet of one transfer and the first packet of the next transfer.
RESET_PIPE_ON_RESUME The device doesn't preserve its data toggle state across suspend. On resume from suspend, WinUSB resets the endpoint before it allows the caller to send new requests to the endpoint.