Книга: Writing Windows WDM Device Drivers

USBDI URB Reference

USBDI URB Reference

All these URBs use standard USB control transfers over the default pipe. I will later explain the details of how to set or clear features, or do class or vendor defined control transfers over the default pipe.

Get Descriptor

Function codes URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Build routine UsbBuildGetDescriptorRequest

URB Structure _URB_CONTROL_DESCRIPTOR_REQUEST

Use this function to get any descriptor from a device. The DescriptorType URB field determines which descriptor is retrieved. A suitably sized buffer must be provided. If asking for a configuration descriptor, specify an appropriate value for the URB Index field. If you are getting a string descriptor, specify a LanguageId field, as well.

If you ask for a configuration descriptor, you also get all the associated interface, endpoint, and class– and vendor-defined descriptors.

Other Get/Set Descriptors

Function codes URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT URB_FUNCTION_SET_DESCRIPTOR_TO_OTHER

Build routine none available

URB Structure _URB_CONTROL_DESCRIPTOR_REQUEST

This function gets or sets other descriptors.

Get Status

Function codes URB_FUNCTION_GET_STATUS_FROM_DEVICE URB_FUNCTION_GET_STATUS_FROM_INTERFACE URB_FUNCTION_GET_STATUS_FROM_ENDPOINT URB_FUNCTION_GET_STATUS_FROM_OTHER

Build routine UsbBuildGetStatusRequest

URB Structure _URB_CONTROL_GET_STATUS_REQUEST

This function gets a status word.

The device status word has self-powered and remote wakeup bits (USB_GETSTATUS_SELF_POWERED and USB_GETSTATUS_REMOTE_WAKEUP_ENABLED are the bit masks). The interface status currently has no bits defined. The endpoint status word has its bit zero set if the Halt feature has been set.

Select Configuration

Function codes URB_FUNCTION_SELECT_CONFIGURATION

Build routine USBD_CreateConfigurationRequestEx UsbBuildSelectConfigurationRequest

URB Structure _URB_SELECT_CONFIGURATION

Use USBD_CreateConfigurationRequestEx to select a configuration and an interface, as described earlier.

If deselecting a configuration, use the simpler UsbBuildSelectConfigurationRequest to pass a NULL configuration descriptor.

Get Configuration

Function codes URB_FUNCTION_GET_CONFIGURATION

Build routine none available

URB Structure _URB_CONTROL_GET_CONFIGURATION_REQUEST

This function gets the current configuration descriptors.

Select Alternate Interface

Function codes URB_FUNCTION_SELECT_INTERFACE

Build routine UsbBuildSelectInterfaceRequest

URB Structure _URB_SELECT_INTERFACE

Use this URB function code to select an interface's alternate setting. Pass the configuration handle, the interface number, and the alternate setting.

Changing to an alternate interface setting discards any queued data on the interface endpoints.

Get Interface

Function codes URB_FUNCTION_GET_INTERFACE

Build routine none available

URB Structure _URB_CONTROL_GET_INTERFACE_REQUEST

This function gets the current alternate interface setting for an interface in the current configuration.

Reset Pipe

Function codes URB_FUNCTION_RESET_PIPE

Build routine none available

URB Structure _URB_HEADER

This function can clear a stall condition on the pipe with the given PipeHandle.

Do Control Transfer

Function codes URB_FUNCTION_CONTROL_TRANSFER

Build routine none available

URB Structure _URB_CONTROL_TRANSFER

This function can transmit or receive data on a control pipe with the given PipeHandle. Fill the SetupPacket 8-byte array with the information for the SETUP packet. The TransferBuffer fields specify the extra data. The USBD_TRANSFER_DIRECTION_IN bit in the TransferFlags field specifies the direction in which the extra data flows. Specify the USBD_SHORT_TRANSFER_OK flag bit if a short input transfer is acceptable.

Do not use his function for transfers over the default pipe.

Do Bulk or Interrupt Transfer

Function codes URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Build routine UsbBuildInterruptOrBulkTransferRequest

URB Structure _URB_BULK_OR_INTERRUPT_TRANSFER

Use this function to transmit or receive data on a bulk pipe, or receive data on an interrupt pipe. Specify the pipe using the PipeHandle field. The TransferBuffer fields specify the data. The USBD_TRANSFER_DIRECTION_IN bit in the TransferFlags field specifies the direction in which the data flows. Specify the USBD_SHORT_TRANSFER_OK flag bit if a short input transfer is acceptable.

Do Isochronous Transfer

Function codes URB_FUNCTION_ISOCH_TRANSFER

Build routine none available

URB Structure _URB_ISOCH_TRANSFER

Use this function to request an isochronous transfer. The TransferBuffer fields specify the data. The data block is split into one or more packets. The number of packets is given in NumberOfPackets. IsoPacket is an array of USBD_ISO_PACKET_DESCRIPTOR structures. Each of these specifies where a packet is in the transfer buffer (i.e., the Offset into the buffer, the Length, and the Status on return of the packet).

GET_ISO_URB_SIZE returns the number of bytes required to hold an isochronous request of the given number of packets.

If the START_ISO_TRANSFER_ASAP bit is set in TransferFlags field, the transfer is started as soon as possible. Otherwise, specify the 32-bit ULONG StartFrame number on which you want the transfer to start, within 1,000 frames of the current frame. The USBD_TRANSFER_ DIRECTION_IN flag bit specifies the direction of data transfer.

Cancel

Function codes URB_FUNCTION_ABORT_PIPE

Build routine none available

URB Structure _URB_PIPE_REQUEST

This function cancels all requests on the pipe with the given PipeHandle.

Set/Clear Feature

Function codes URB_FUNCTION_SET_FEATURE_TO_DEVICE URB_FUNCTION_SET_FEATURE_TO_INTERFACE URB_FUNCTION_SET_FEATURE_TO_ENDPOINT URB_FUNCTION_SET_FEATURE_TO_OTHER URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Build routine UsbBuildFeatureRequest

URB Structure _URB_CONTROL_FEATURE_REQUEST

This function sets or clears a feature, in a control transfer over the default pipe. Specify a feature code.

Vendor/Class

Function codes URB_FUNCTION_VENDOR_DEVICE URB_FUNCTION_VENDOR_INTERFACE URB_FUNCTION_VENDOR_ENDPOINT URB_FUNCTION_VENDOR_OTHER URB_FUNCTION_CLASS_DEVICE URB_FUNCTION_CLASS_INTERFACE URB_FUNCTION_CLASS_ENDPOINT URB_FUNCTION_CLASS_OTHER

Build routine UsbBuildVendorRequest

URB Structure _URB_CONTROL_VENDOR_OR_CLASS_REQUEST

Use this function to issue a vendor or class-specific command to a device, interface, endpoint, or other device-defined target, in a control transfer over the default pipe.

The TransferBuffer fields specify the data. The USBD_TRANSFER_DIRECTION_IN bit in the TransferFlags field specifies the direction in which the data flows. Specify the USBD_SHORT_ TRANSFER_OK flag bit if a short input transfer is acceptable.

The ReservedBits field is usually zero, but if it is a value between 4 and 31 this value is used for bits 4 to 0 in the SETUP packet bmRequestType field (see Table 20.3 in the last chapter).

The Request, Value, Index, and TransferBuffer fields are set appropriately for the vendor– or class-defined request.

Request Control of Frame Length

Function codes URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

Build routine none available

URB Structure _URB_FRAME_LENGTH_CONTROL

Use this function to request control of the frame length (i.e., SOF mastership).

Only one client can have control of frame length at any time.

Get Current Frame Length

Function codes URB_FUNCTION_GET_FRAME_LENGTH

Build routine none available

URB Structure _URB_GET_FRAME_LENGTH

Use this function to get the current frame length in the FrameLength field. It also indicates in FrameNumber the first frame in which the frame length can be changed.

Set Current Frame Length

Function codes URB_FUNCTION_SET_FRAME_LENGTH

Build routine none available

URB Structure _URB_SET_FRAME_LENGTH

Use this function to specify the amount to change the current frame length (i.e., 1 or –1 in the FrameLengthDelta field).

You must have control of frame length to issue this URB.

Get Current Frame Number

Function codes URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Build routine none available

URB Structure _URB_GET_CURRENT_FRAME_NUMBER

Use this function to get the current frame number in FrameNumber.

Gets Beginning Frame of Pattern Transfer

Function codes URB_FUNCTION_SYNC_FRAME

Build routine none available

URB Structure _URB_CONTROL_SYNC_FRAME_REQUEST

This function retrieves the beginning frame of a pattern transfer from an isochronous pipe.

This function is documented, but both the function code and the URB structure are not defined in the W98 and W2000 DDK USB headers.

Оглавление книги