libusbK 
3.0
Library Documentation
© 2011 Travis Lee Robinson. All rights reserved.
Pipe Policy Management

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

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

Pipe Policies

Note:
The policies described in the table are valid only for the specified endpoints. Setting the policy on other endpoints has no effect on libusbK's behavior for read or write requests.
Policy number Policy name Description Endpoint (direction) Default
0x01 SHORT_PACKET_TERMINATE Terminates every write request with a zero-length packet. Bulk (OUT)
Interrupt (OUT)
Off
0x02 AUTO_CLEAR_STALL Automatically clears a stalled pipe without stopping the data flow. Bulk (IN)
Interrupt (IN)
Off
0x03 PIPE_TRANSFER_TIMEOUT Waits for a time-out interval before canceling the request. Bulk (IN)
Bulk (OUT)
Interrupt (IN)
Interrupt (OUT)
5 seconds for control; 0 for others
0x04 IGNORE_SHORT_PACKETS Completes a read request based on the number of bytes read. Bulk (IN)
Interrupt (IN)
Off
0x05 ALLOW_PARTIAL_READS Allows read requests from a device that returns more data than requested by the caller. Bulk (IN)
Interrupt (IN)
On
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)
Off
0x07 RAW_IO Bypasses queuing and error handling to boost performance for multiple read requests. Bulk (IN)
Interrupt (IN)
Off
0x08 MAXIMUM_TRANSFER_SIZE Gets the maximum size of a USB transfer supported by libusbK. 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)
Off
0x30 SIMUL_PARALLEL_REQUESTS Maximum number of transfers that can be asynchronously delivered at a time. Available in version 1.9 and later versions of KMDF. Requires \b RAW_IO. http://msdn.microsoft.com/en-us/library/windows/hardware/ff552359%28v=vs.85%29.aspx. Bulk (IN)
Bulk (OUT)
Interrupt (IN)
Interrupt (OUT)
ISO (IN)
ISO (OUT)
Unlimited
0x20 ISO_START_LATENCY TODO: ISO (IN)
ISO (OUT)
8 for full speed, 32 for high speed
0x21 ISO_ALWAYS_START_ASAP TODO: ISO (IN)
ISO (OUT)
On for OUT endpoints, Off for IN endpoints
0x22 ISO_NUM_FIXED_PACKETS TODO: ISO (OUT) 0 (disabled)

Behavior and Best Practices

Note:
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 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 is followed by a zero-length packet to the endpoint's pipe.
After sending all of the requested data to the host controller, libusbK sends a write request with a zero-length packet and then completes the request that was created by UsbK_WritePipe.
AUTO_CLEAR_STALL You 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, libusbK 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 UsbK_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.
Requests do not time out while waiting in a libusbK queue.
In Windows Vista, for all transfers (except transfers with RAW_IO enabled), libusbK 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, libusbK does not queue the request. Instead, it passes the request directly to the USB stack, whether or not 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_PACKETS RAW_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 specified number of bytes or has received a short packet.
ALLOW_PARTIAL_READS The 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, libusbK completes the request with an error.
  • If enabled (policy parameter value is TRUE or nonzero) and the device returns more data than was requested, libusbK 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, libusbK immediately completes read requests for zero bytes successfully and will not 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 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 libusbK's behavior when ALLOW_PARTIAL_READS is enabled. If ALLOW_PARTIAL_READS is disabled, the AUTO_FLUSH value is ignored by libusbK.
libusbK 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), libusbK discards the extra bytes without any error code.
  • If disabled (policy parameter value is FALSE or zero), libusbK 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 UsbK_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 UsbK_GetPipePolicy.
If enabled, transfers bypass queuing and error handling to boost performance for multiple read requests. libusbK 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 libusbK 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 does not preserve its data toggle state across suspend. On resume from suspend, libusbK resets the endpoint before it allows the caller to send new requests to the endpoint.
SIMUL_PARALLEL_REQUESTS TODO: TODO:
ISO_START_LATENCY TODO: TODO:
ISO_ALWAYS_START_ASAP TODO: TODO:
ISO_NUM_FIXED_PACKETS TODO: TODO: