WinUSB Functions for Pipe Policy Modification

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 that are 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 numberPolicy nameDescriptionEndpoint (direction)Default value
0x01SHORT_PACKET_TERMINATESends 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
0x02AUTO_CLEAR_STALLAutomatically clears a stalled pipe without stopping the data flow.

Bulk (IN)

Interrupt (IN)

FALSE
0x03PIPE_TRANSFER_TIMEOUTWaits for a time-out interval before canceling the request.

Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)

5 seconds for control; 0 for others
0x04IGNORE_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
0x05ALLOW_PARTIAL_READSAllows read requests from a device that returns more data than requested by the caller.

Bulk (IN)

Interrupt (IN)

TRUE
0x06AUTO_FLUSHSaves 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
0x07RAW_IOBypasses queuing and error handling to boost performance for multiple read requests.

Bulk (IN)

Interrupt (IN)

FALSE
0x08MAXIMUM_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)

0x09RESET_PIPE_ON_RESUMEResets 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.

PolicyEnable if...Behavior
SHORT_PACKET_TERMINATE(0x01) The device requires the OUT transfers to be terminated with a zero-length packet. Most devices do not 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_STALLYou do not 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 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.
PIPE_TRANSFER_TIMEOUT You expect transfers to an endpoint to complete within a specific time.
  • 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.

IGNORE_SHORT_PACKETSRAW_IO is disabled and you do not want short packets to complete the read requests.
  • 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.
ALLOW_PARTIAL_READSThe device can send more data than requested. This is possible 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 will not send the requests down the stack.

AUTO_FLUSHALLOW_PARTIAL _READS policy is enabled.

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_IOPerformance 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 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.
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_RESUMEThe device does not 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.

 

Related topics

WinUSB Power Management
WinUSB Architecture and Modules
Choosing a driver model for developing a USB client driver
WinUSB (Winusb.sys) Installation
How to Access a USB Device by Using WinUSB Functions
WinUSB Functions
WinUsb_GetPipePolicy
WinUsb_SetPipePolicy
WinUSB

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft