/*++ Copyright (c) 2013 Minoca Corp. All Rights Reserved Module Name: usb.h Abstract: This header contains definitions for interacting with USB devices. Author: Evan Green 15-Jan-2013 --*/ // // ------------------------------------------------------------------- Includes // // // ---------------------------------------------------------------- Definitions // #ifndef USB_API #define USB_API __DLLIMPORT #endif // // Define the maximum size of a USB hub descriptor. // #define USB_HUB_DESCRIPTOR_MAX_SIZE 39 // // Define the maximum descriptor size. // #define USB_MAX_DESCRIPTOR_SIZE 0xFF // // Define the hub descriptor type. // #define USB_HUB_DESCRIPTOR_TYPE 0x29 // // Define the values in the Setup Packet's RequestType field. // #define USB_SETUP_REQUEST_TO_HOST (1 << 7) #define USB_SETUP_REQUEST_TO_DEVICE (0 << 7) #define USB_SETUP_REQUEST_STANDARD (0x0 << 5) #define USB_SETUP_REQUEST_CLASS (0x1 << 5) #define USB_SETUP_REQUEST_VENDOR (0x2 << 5) #define USB_SETUP_REQUEST_DEVICE_RECIPIENT 0x0 #define USB_SETUP_REQUEST_INTERFACE_RECIPIENT 0x1 #define USB_SETUP_REQUEST_ENDPOINT_RECIPIENT 0x2 #define USB_SETUP_REQUEST_OTHER_RECIPIENT 0x3 // // Define the USB standard requests. // #define USB_REQUEST_GET_STATUS 0x0 #define USB_REQUEST_CLEAR_FEATURE 0x1 #define USB_REQUEST_SET_FEATURE 0x3 #define USB_REQUEST_SET_ADDRESS 0x5 #define USB_REQUEST_GET_DESCRIPTOR 0x6 #define USB_REQUEST_SET_DESCRIPTOR 0x7 #define USB_REQUEST_GET_CONFIGURATION 0x8 #define USB_REQUEST_SET_CONFIGURATION 0x9 #define USB_REQUEST_GET_INTERFACE 0xA #define USB_REQUEST_SET_INTERFACE 0xB #define USB_REQUEST_SYNCH_FRAME 0xC // // Define the USB feature selectors. // #define USB_FEATURE_ENDPOINT_HALT 0x0 #define USB_FEATURE_DEVICE_REMOTE_WAKEUP 0x1 #define USB_FEATURE_DEVICE_TEST_MODE 0x2 // // Define standard Device requests. // #define USB_DEVICE_REQUEST_GET_STATUS USB_REQUEST_GET_STATUS #define USB_DEVICE_REQUEST_CLEAR_FEATURE USB_REQUEST_CLEAR_FEATURE #define USB_DEVICE_REQUEST_SET_FEATURE USB_REQUEST_SET_FEATURE #define USB_DEVICE_REQUEST_SET_ADDRESS USB_REQUEST_SET_ADDRESS #define USB_DEVICE_REQUEST_GET_DESCRIPTOR USB_REQUEST_GET_DESCRIPTOR #define USB_DEVICE_REQUEST_SET_DESCRIPTOR USB_REQUEST_SET_DESCRIPTOR #define USB_DEVICE_REQUEST_GET_CONFIGURATION USB_REQUEST_GET_CONFIGURATION #define USB_DEVICE_REQUEST_SET_CONFIGURATION USB_REQUEST_SET_CONFIGURATION // // Define the USB device status bits. // #define USB_DEVICE_STATUS_SELF_POWERED 0x1 #define USB_DEVICE_STATUS_REMOTE_WAKEUP 0x2 // // Define standard Interface requests. // #define USB_INTERFACE_REQUEST_GET_STATUS USB_REQUEST_GET_STATUS #define USB_INTERFACE_REQUEST_CLEAR_FEATURE USB_REQUEST_CLEAR_FEATURE #define USB_INTERFACE_REQUEST_SET_FEATURE USB_REQUEST_SET_FEATURE #define USB_INTERFACE_GET_INTERFACE USB_REQUEST_GET_INTERFACE #define USB_INTERFACE_SET_INTERFACE USB_REQUEST_SET_INTERFACE // // Define standard Endpoint requests. // #define USB_ENDPOINT_REQUEST_GET_STATUS USB_REQUEST_GET_STATUS #define USB_ENDPOINT_REQUEST_CLEAR_FEATURE USB_REQUEST_CLEAR_FEATURE #define USB_ENDPOINT_REQUEST_SET_FEATURE USB_REQUEST_SET_FEATURE #define USB_ENDPOINT_REQUEST_SYNCH_FRAME USB_REQUEST_SYNCH_FRAME // // Define the endpoint address bits in a USB endpoint descriptor. // #define USB_ENDPOINT_ADDRESS_DIRECTION_IN 0x80 #define USB_ENDPOINT_ADDRESS_MASK 0x0F // // Define the attributes bits in a USB endpoint descriptor. // #define USB_ENDPOINT_ATTRIBUTES_TYPE_MASK 0x03 #define USB_ENDPOINT_ATTRIBUTES_TYPE_CONTROL 0x00 #define USB_ENDPOINT_ATTRIBUTES_TYPE_ISOCHRONOUS 0x01 #define USB_ENDPOINT_ATTRIBUTES_TYPE_BULK 0x02 #define USB_ENDPOINT_ATTRIBUTES_TYPE_INTERRUPT 0x03 // // Define the USB endpoint status bits. // #define USB_ENDPOINT_STATUS_HALT 0x1 // // Define USB Hub characteristics flags. // #define USB_HUB_CHARACTERISTIC_POWER_SWITCHING_MASK 0x03 #define USB_HUB_CHARACTERISTIC_POWER_GANGED 0x00 #define USB_HUB_CHARACTERISTIC_POWER_INDIVIDUAL 0x01 #define USB_HUB_CHARACTERISTIC_OVER_CURRENT_MASK 0x0C #define USB_HUB_CHARACTERISTIC_OVER_CURRENT_GLOBAL 0x00 #define USB_HUB_CHARACTERISTIC_OVER_CURRENT_INDIVIDUAL 0x04 #define USB_HUB_CHARACTERISTIC_OVER_CURRENT_NONE 0x08 #define USB_HUB_CHARACTERISTIC_TT_THINK_MASK 0x30 #define USB_HUB_CHARACTERISTIC_TT_THINK_8_FS_TIMES 0x00 #define USB_HUB_CHARACTERISTIC_TT_THINK_16_FS_TIMES 0x10 #define USB_HUB_CHARACTERISTIC_TT_THINK_24_FS_TIMES 0x20 #define USB_HUB_CHARACTERISTIC_TT_THINK_32_FS_TIMES 0x30 #define USB_HUB_CHARACTERISTIC_INDICATORS_SUPPORTED 0x80 // // Define USB language IDs. // #define USB_LANGUAGE_ENGLISH_US 0x0409 // // USB Hub definitions // // // Define the size of various hub transfers. // #define USB_HUB_MAX_CONTROL_TRANSFER_SIZE \ (USB_HUB_DESCRIPTOR_MAX_SIZE + sizeof(USB_SETUP_PACKET)) #define USB_HUB_MAX_PORT_COUNT 127 #define USB_HUB_MAX_INTERRUPT_SIZE \ (ALIGN_RANGE_UP(USB_HUB_MAX_PORT_COUNT + 1, BITS_PER_BYTE) / BITS_PER_BYTE) // // Define Hub class feature selectors (that go in the Value of the setup // packet). // #define USB_HUB_FEATURE_C_HUB_LOCAL_POWER 0 #define USB_HUB_FEATURE_C_HUB_OVER_CURRENT 1 #define USB_HUB_FEATURE_PORT_CONNECTION 0 #define USB_HUB_FEATURE_PORT_ENABLE 1 #define USB_HUB_FEATURE_PORT_SUSPEND 2 #define USB_HUB_FEATURE_PORT_OVER_CURRENT 3 #define USB_HUB_FEATURE_PORT_RESET 4 #define USB_HUB_FEATURE_PORT_POWER 8 #define USB_HUB_FEATURE_PORT_LOW_SPEED 9 #define USB_HUB_FEATURE_C_PORT_CONNECTION 16 #define USB_HUB_FEATURE_C_PORT_ENABLE 17 #define USB_HUB_FEATURE_C_PORT_SUSPEND 18 #define USB_HUB_FEATURE_C_PORT_OVER_CURRENT 19 #define USB_HUB_FEATURE_C_PORT_RESET 20 #define USB_HUB_FEATURE_PORT_TEST 21 #define USB_HUB_FEATURE_PORT_INDICATOR 22 // // Define hub status bits. // #define USB_HUB_HUB_STATUS_LOCAL_POWER (1 << 0) #define USB_HUB_HUB_STATUS_OVER_CURRENT (1 << 1) #define USB_HUB_HUB_STATUS_CHANGE_SHIFT 16 // // Define port status bits. // #define USB_HUB_PORT_STATUS_DEVICE_CONNECTED (1 << 0) #define USB_HUB_PORT_STATUS_ENABLED (1 << 1) #define USB_HUB_PORT_STATUS_SUSPENDED (1 << 2) #define USB_HUB_PORT_STATUS_OVER_CURRENT (1 << 3) #define USB_HUB_PORT_STATUS_RESET (1 << 4) #define USB_HUB_PORT_STATUS_POWERED_ON (1 << 8) #define USB_HUB_PORT_STATUS_LOW_SPEED (1 << 9) #define USB_HUB_PORT_STATUS_HIGH_SPEED (1 << 10) #define USB_HUB_PORT_STATUS_TEST (1 << 11) #define USB_HUB_PORT_STATUS_SOFTWARE_INDICATORS (1 << 12) #define USB_HUB_PORT_STATUS_CHANGE_SHIFT 16 // // Define indicator values. // #define USB_HUB_INDICATOR_AUTOMATIC (0 << 8) #define USB_HUB_INDICATOR_AMBER (1 << 8) #define USB_HUB_INDICATOR_GREEN (2 << 8) #define USB_HUB_INDICATOR_OFF (3 << 8) #define USB_HUB_INDICATOR_MASK (0xFF << 8) // // Define well-known USB device IDs. // #define USB_ROOT_HUB_DEVICE_ID "UsbRootHub" #define USB_COMPOUND_DEVICE_CLASS_ID "UsbCompoundDevice" #define USB_HID_CLASS_ID "UsbHid" #define USB_BOOT_KEYBOARD_CLASS_ID "UsbBootKeyboard" #define USB_BOOT_MOUSE_CLASS_ID "UsbBootMouse" #define USB_MASS_STORAGE_CLASS_ID "UsbMassStorage" #define USB_HUB_CLASS_ID "UsbHub" // // Define the required subclass and protocol for this device to be a keyboard // or mouse that follows the boot protocol. // #define USB_HID_BOOT_INTERFACE_SUBCLASS 1 #define USB_HID_BOOT_KEYBOARD_PROTOCOL 1 #define USB_HID_BOOT_MOUSE_PROTOCOL 2 // // Define USB HID standard requests. // #define USB_HID_GET_REPORT 0x01 #define USB_HID_GET_IDLE 0x02 #define USB_HID_GET_PROTOCOL 0x03 #define USB_HID_SET_REPORT 0x09 #define USB_HID_SET_IDLE 0x0A #define USB_HID_SET_PROTOCOL 0x0B // // Define USB HID report value fields. // #define USB_HID_RERPOT_VALUE_TYPE_MASK (0xFF << 8) #define USB_HID_REPORT_VALUE_TYPE_SHIFT 8 #define USB_HID_REPORT_VALUE_TYPE_INPUT 1 #define USB_HID_REPORT_VALUE_TYPE_OUTPUT 2 #define USB_HID_REPORT_VALUE_TYPE_FEATURE 3 #define USB_HID_REPORT_VALUE_ID_MASK (0xFF << 0) #define USB_HID_REPORT_VALUE_ID_SHIFT 0 // // Define the USB HID protocol request values. // #define USB_HID_PROTOCOL_VALUE_BOOT 0 #define USB_HID_PROTOCOL_VALUE_REPORT 1 // // Define USB Transfer flags. // // // Set this flag to continue trying if a transfer comes up short. // #define USB_TRANSFER_FLAG_NO_SHORT_TRANSFERS 0x00000001 // // Set this flag to prevent an interrupt from firing when the packet completes. // This is usually only used for internal intermediate transfers. // #define USB_TRANSFER_FLAG_NO_INTERRUPT_ON_COMPLETION 0x00000002 // // Set this flag for non-synchronous transfers from a paging USB mass storage // device. // #define USB_TRANSFER_FLAG_PAGING_DEVICE 0x00000004 // // Set this flag to force a short, zero-length transfer to be sent if the // payload is a multiple of the max packet size for the endpoint. // #define USB_TRANSFER_FLAG_FORCE_SHORT_TRANSFER 0x00000008 // // Define the maximum size of a USB string descriptor. // #define USB_STRING_DESCRIPTOR_MAX_SIZE 0xFF // // ------------------------------------------------------ Data Type Definitions // typedef enum _USB_DEVICE_SPEED { UsbDeviceSpeedInvalid, UsbDeviceSpeedLow, UsbDeviceSpeedFull, UsbDeviceSpeedHigh, UsbDeviceSpeedSuper, } USB_DEVICE_SPEED, *PUSB_DEVICE_SPEED; typedef enum _USB_TRANSFER_TYPE { UsbTransferTypeInvalid, UsbTransferTypeControl, UsbTransferTypeInterrupt, UsbTransferTypeBulk, UsbTransferTypeIsochronous, UsbTransferTypeCount } USB_TRANSFER_TYPE, *PUSB_TRANSFER_TYPE; typedef enum _USB_TRANSFER_DIRECTION { UsbTransferDirectionInvalid, UsbTransferDirectionIn, UsbTransferDirectionOut, UsbTransferBidirectional, UsbTransferDirectionCount } USB_TRANSFER_DIRECTION, *PUSB_TRANSFER_DIRECTION; typedef enum _USB_DESCRIPTOR_TYPE { UsbDescriptorTypeDevice = 0x01, UsbDescriptorTypeConfiguration = 0x02, UsbDescriptorTypeString = 0x03, UsbDescriptorTypeInterface = 0x04, UsbDescriptorTypeEndpoint = 0x05, UsbDescriptorTypeDeviceQualifier = 0x06, UsbDescriptorTypeOtherSpeedConfiguration = 0x07, } USB_DESCRIPTOR_TYPE, *PUSB_DESCRIPTOR_TYPE; typedef enum _USB_INTERFACE_CLASS { UsbInterfaceClassAudio = 0x01, UsbInterfaceClassCdcControl = 0x02, UsbInterfaceClassHid = 0x03, UsbInterfaceClassPhysical = 0x05, UsbInterfaceClassImage = 0x06, UsbInterfaceClassPrinter = 0x07, UsbInterfaceClassMassStorage = 0x08, UsbInterfaceClassCdcData = 0x0A, UsbInterfaceClassSmartCard = 0x0B, UsbInterfaceClassContentSecurity = 0x0D, UsbInterfaceClassVideo = 0x0E, UsbInterfaceClassPersonalHealthcare = 0x0F, UsbInterfaceClassAudioVideo = 0x10, UsbInterfaceClassDiagnosticDevice = 0xDC, UsbInterfaceClassWireless = 0xE0, UsbInterfaceClassMiscellaneous = 0xEF, UsbInterfaceClassApplicationSpecific = 0xFE, UsbInterfaceClassVendor = 0xFF, } USB_INTERFACE_CLASS, *PUSB_INTERFACE_CLASS; typedef enum _USB_DEVICE_CLASS { UsbDeviceClassUseInterface = 0x00, UsbDeviceClassCdcControl = 0x02, UsbDeviceClassHid = 0x03, UsbDeviceClassHub = 0x09, UsbDeviceClassDiagnosticDevice = 0xDC, UsbDeviceClassMiscellaneous = 0xEF, UsbDeviceClassVendor = 0xFF, } USB_DEVICE_CLASS, *PUSB_DEVICE_CLASS; typedef enum _USB_ERROR { UsbErrorNone, UsbErrorTransferNotStarted, UsbErrorTransferCancelled, UsbErrorTransferAllocatedIncorrectly, UsbErrorTransferSubmittedWhileStillActive, UsbErrorTransferIncorrectlyFilledOut, UsbErrorTransferFailedToSubmit, UsbErrorTransferStalled, UsbErrorTransferDataBuffer, UsbErrorTransferBabbleDetected, UsbErrorTransferNakReceived, UsbErrorTransferCrcOrTimeoutError, UsbErrorTransferBitstuff, UsbErrorTransferMissedMicroFrame, UsbErrorTransferBufferNotAligned, UsbErrorTransferDeviceNotConnected, UsbErrorTransferDeviceIo, UsbErrorShortPacket, UsbErrorCount } USB_ERROR, *PUSB_ERROR; typedef struct _USB_TRANSFER USB_TRANSFER, *PUSB_TRANSFER; typedef struct _USB_DEVICE USB_DEVICE, *PUSB_DEVICE; /*++ Structure Description: This structure defines the format of the USB Device Descriptor, as defined by the USB specification. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is a device descriptor. UsbSpecification - Stores a binary coded decimal number indicating the revision of the USB specification this device conforms to. Class - Stores the class code that the device conforms to. Most class specifications choose to identify at the interface level as opposed to here at the device level. Subclass - Stores the subclass code that the device conforms to. Protocol - Stores the protocol number of the class/subclass that the device conforms to. MaxPacketSize - Stores the maximum supported size of packets on this default endpoint. Valid values are 8, 16, 32, and 64. VendorId - Stores the vendor identification number (VID) of the device. ProductId - Stores the product identification number (PID) of the device. DeviceRevision - Stores a binary coded decimal hardware revision number. ManufacturerStringIndex - Stores the index of the Manufacturer String Descriptor. ProductStringIndex - Stores the index of the Product Name String Descriptor. SerialNumberIndex - Stores the index of the Serial Number String Descriptor. ConfigurationCount - Stores the number of configurations this device supports. --*/ typedef struct _USB_DEVICE_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; USHORT UsbSpecification; UCHAR Class; UCHAR Subclass; UCHAR Protocol; UCHAR MaxPacketSize; USHORT VendorId; USHORT ProductId; USHORT DeviceRevision; UCHAR ManufacturerStringIndex; UCHAR ProductStringIndex; UCHAR SerialNumberStringIndex; UCHAR ConfigurationCount; } PACKED USB_DEVICE_DESCRIPTOR, *PUSB_DEVICE_DESCRIPTOR; /*++ Structure Description: This structure defines the format of the USB Configuration Descriptor, as defined by the USB specification. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is a configuration descriptor. TotalLength - Stores the total length of all the data returned (which includes the interfaces and endpoints). InterfaceCount - Stores the number of interfaces in this configuration. ConfigurationValue - Stores the index of this configuration. StringIndex - Stores the index of the string descriptor describing this configuration. Attributes - Stores various attributes about this configuration, mostly centered around power. MaxPower - Stores the maximum power consumption of this configuration, in 2mA units. --*/ typedef struct _USB_CONFIGURATION_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; USHORT TotalLength; UCHAR InterfaceCount; UCHAR ConfigurationValue; UCHAR StringIndex; UCHAR Attributes; UCHAR MaxPower; } PACKED USB_CONFIGURATION_DESCRIPTOR, *PUSB_CONFIGURATION_DESCRIPTOR; /*++ Structure Description: This structure defines the format of the USB Interface Descriptor, as defined by the USB specification. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is an interface descriptor. InterfaceNumber - Stores the index of this interface. AlternateNumber - Stores the alternate index of this interface. EndpointCount - Stores the number of endpoints in this interface, not counting endpoint zero. Class - Stores the class code of the interface (assigned by the USB organization). Subclass - Stores the subclass code of the interface (assigned by the USB organization). Protocol - Stores the protocol code of the interface (assigned by the USB organization). StringIndex - Stores the index of the string descriptor describing the interface. --*/ typedef struct _USB_INTERFACE_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; UCHAR InterfaceNumber; UCHAR AlternateNumber; UCHAR EndpointCount; UCHAR Class; UCHAR Subclass; UCHAR Protocol; UCHAR StringIndex; } PACKED USB_INTERFACE_DESCRIPTOR, *PUSB_INTERFACE_DESCRIPTOR; /*++ Structure Description: This structure defines the format of the USB Endpoint Descriptor, as defined by the USB specification. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is an endpoint descriptor. EndpointAddress - Stores the address and direction of this endpoint. Attributes - Stores a bitfield of attributes of the endpoint. MaxPacketSize - Stores the maximum packet size this endpoint is capable of sending or receiving. Interval - Stores the interval for polling data transfer. This value is in frame counts, and is ignored for Control endpoints. Isochronous endpoints must set this to 1, interrupt endpoints may range from 1 to 255, and Bulk OUT endpoints range from 0 to 255 to speceified the maximum NAK rate. --*/ typedef struct _USB_ENDPOINT_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; UCHAR EndpointAddress; UCHAR Attributes; USHORT MaxPacketSize; UCHAR Interval; } PACKED USB_ENDPOINT_DESCRIPTOR, *PUSB_ENDPOINT_DESCRIPTOR; /*++ Structure Description: This structure defines the format of the USB String Descriptor, as defined by the USB specification. The string itself immediately follows this descriptor structure. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is a string descriptor. --*/ typedef struct _USB_STRING_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; } PACKED USB_STRING_DESCRIPTOR, *PUSB_STRING_DESCRIPTOR; /*++ Structure Description: This structure defines the format of the Setup Packet, as defined by the USB specification. Members: RequestType - Stores a bitfield indicating the transfer direction, transfer type, and recipient. Request - Stores the request value. Value - Stores the value associated with the request. Index - Stores the index associated with the request. Length - Stores the number of bytes to transfer if there is a data phase. --*/ /*++ Structure Description: This structure defines the format of the USB Hub Descriptor, as defined by the USB specification. Members: Length - Stores the length of the structure. DescriptorType - Stores a constant indicating that this is a hub descriptor. PortCount - Stores the number of downstream ports in this hub. HubCharacteristics - Stores a bitfield of hub characteristics. See USB_HUB_CHARACTERISTIC_* definitions. PowerDelayIn2ms - Stores the time, in 2ms intervals, from the time the power-on sequence begins on a port until the power is good on that port. Software uses this value to determine how long to wait before accessing a powered-on port. HubCurrent - Stores the maximum current requirements of the hub controller electronics in mA. DeviceRemovable - Stores a variable-length byte array indicating if a port has a removable device attached. Within a byte, if no port exists for a given location, the field representing the port characteristics returns 0. Each bit is set if the corresponding port is non-removable, and is clear if the port has a removable device. --*/ typedef struct _USB_HUB_DESCRIPTOR { UCHAR Length; UCHAR DescriptorType; UCHAR PortCount; USHORT HubCharacteristics; UCHAR PowerUpDelayIn2ms; UCHAR HubCurrent; UCHAR DeviceRemovable[ANYSIZE_ARRAY]; } PACKED USB_HUB_DESCRIPTOR, *PUSB_HUB_DESCRIPTOR; /*++ Structure Description: This structure defines a USB setup packet. Members: RequestType - Stores the properties of the request. Request - Stores the particular type of request in the packet. Value - Stores request-specific parameters for the device. Index - Stores request-specific parameters for the device. Length - Stores the length of the data to be transferred. --*/ typedef struct _USB_SETUP_PACKET { UCHAR RequestType; UCHAR Request; USHORT Value; USHORT Index; USHORT Length; } PACKED USB_SETUP_PACKET, *PUSB_SETUP_PACKET; /*++ Structure Description: This structure defines a USB device description. Members: ListEntry - Stores pointers to the next and previous device descriptions in the parent's child list. Descriptor - Stores the device descriptor. ChildListHead - Stores the head of the list of children of this device. --*/ typedef struct _USB_DEVICE_DESCRIPTION { LIST_ENTRY ListEntry; USB_DEVICE_DESCRIPTOR Descriptor; LIST_ENTRY ChildListHead; } USB_DEVICE_DESCRIPTION, *PUSB_DEVICE_DESCRIPTION; /*++ Structure Description: This structure defines a USB configuration description. Members: Descriptor - Stores the configuration descriptor. Index - Stores the index number of the configuration. InterfaceListHead - Stores the head of the list of interfaces in this configuration. --*/ typedef struct _USB_CONFIGURATION_DESCRIPTION { USB_CONFIGURATION_DESCRIPTOR Descriptor; UCHAR Index; LIST_ENTRY InterfaceListHead; } USB_CONFIGURATION_DESCRIPTION, *PUSB_CONFIGURATION_DESCRIPTION; /*++ Structure Description: This structure defines a USB interface description. Members: ListEntry - Stores pointers to the next and previous interfaces in the parent configuration. Descriptor - Stores the interface descriptor. EndpointListHead - Stores the head of the list of endpoints in this interface. --*/ typedef struct _USB_INTERFACE_DESCRIPTION { LIST_ENTRY ListEntry; USB_INTERFACE_DESCRIPTOR Descriptor; LIST_ENTRY EndpointListHead; } USB_INTERFACE_DESCRIPTION, *PUSB_INTERFACE_DESCRIPTION; /*++ Structure Description: This structure defines a USB endpoint description. Members: ListEntry - Stores pointers to the next and previous endpoints in the parent interface. Descriptor - Stores the endpoint descriptor. --*/ typedef struct _USB_ENDPOINT_DESCRIPTION { LIST_ENTRY ListEntry; USB_ENDPOINT_DESCRIPTOR Descriptor; } USB_ENDPOINT_DESCRIPTION, *PUSB_ENDPOINT_DESCRIPTION; typedef VOID (*PUSB_TRANSFER_CALLBACK) ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine is called when an asynchronous I/O request completes with success, failure, or is cancelled. Arguments: Transfer - Supplies a pointer to the transfer that completed. Return Value: None. --*/ /*++ Structure Description: This structure stores information about a USB transfer request. Members: Direction - Stores the direction of the USB transfer. This must be consistent with the endpoint being sent to. Status - Stores the completion status of the request. Length - Stores the length of the request, in bytes. LengthTransferred - Stores the number of bytes that have actually been transferred. CallbackRoutine - Stores a pointer to a routine that will be called back when the transfer completes. UserData - Stores an area where the user can store a pointer's worth of data, usually used by the callback routine to identify a request. Buffer - Stores a pointer to the data buffer. BufferPhysicalAddress - Stores the physical address of the data buffer. BufferActualLength - Stores the actual length of the buffer, in bytes. The buffer must be at least as large as the length, and must be aligned to a flushable boundary. Flags - Stores a bitfield of flags regarding the transaction. See USB_TRANSFER_FLAG_* definitions. Error - Stores a more detailed and USB specific error code. --*/ struct _USB_TRANSFER { USB_TRANSFER_DIRECTION Direction; KSTATUS Status; ULONG Length; ULONG LengthTransferred; PUSB_TRANSFER_CALLBACK CallbackRoutine; PVOID UserData; PVOID Buffer; PHYSICAL_ADDRESS BufferPhysicalAddress; ULONG BufferActualLength; ULONG Flags; USB_ERROR Error; }; // // -------------------------------------------------------------------- Globals // // // -------------------------------------------------------- Function Prototypes // USB_API KSTATUS UsbDriverAttach ( PDEVICE Device, PDRIVER Driver, PHANDLE UsbCoreHandle ); /*++ Routine Description: This routine attaches a USB driver to a USB device, and returns a USB core handle to the device, used for all USB communications. This routine must be called at low level. Arguments: Device - Supplies a pointer to the OS device object representation of the USB device. Driver - Supplies a pointer to the driver that will take ownership of the device. UsbCoreHandle - Supplies a pointer where the USB Core device handle will be returned. Return Value: Status code. --*/ USB_API KSTATUS UsbEnumerateDeviceForInterface ( HANDLE UsbCoreHandle, PUSB_INTERFACE_DESCRIPTION InterfaceDescription, PDEVICE *ChildDevice ); /*++ Routine Description: This routine enumerates a child OS device on the requested device and interface combination. With this interface multiple drivers can independently operate interfaces of a shared USB device. Arguments: UsbCoreHandle - Supplies the core handle to the device containing the interface to share. InterfaceDescription - Supplies a pointer to the interface to enumerate a device for. ChildDevice - Supplies a pointer to an OS device that will come up to claim the given interface. This device should be returned in Query Children calls sent to the parent device so the device can properly enumerate. Return Value: Status code. --*/ USB_API PUSB_INTERFACE_DESCRIPTION UsbGetDesignatedInterface ( PDEVICE Device, HANDLE UsbCoreHandle ); /*++ Routine Description: This routine returns the interface for which the given pseudo-device was enumerated. This routine is used by general class drivers (like Hub or Mass Storage) that can interact with an interface without necessarily taking responsibility for the entire device. Arguments: Device - Supplies a pointer to the OS device object representation of the USB device. UsbCoreHandle - Supplies the core handle to the device. Return Value: Returns a pointer to the interface this pseudo-device is supposed to take ownership of. If the device only has one interface, then that interface is returned. NULL if the OS device was not enumerated for any one particular interface. --*/ USB_API KSTATUS UsbGetDeviceSpeed ( PUSB_DEVICE Device, PUSB_DEVICE_SPEED Speed ); /*++ Routine Description: This routine returns the connected speed of the given USB device. Arguments: Device - Supplies a pointer to the device. Speed - Supplies a pointer where the device speed will be returned. Return Value: Status code. --*/ USB_API VOID UsbDetachDevice ( HANDLE UsbCoreHandle ); /*++ Routine Description: This routine detaches a USB device from the USB core by marking it as disconnected, and cancelling all active transfers belonging to the device. It does not close the device. Arguments: UsbCoreHandle - Supplies the core handle to the device that is to be removed. Return Value: None. --*/ USB_API KSTATUS UsbReadDeviceString ( PUSB_DEVICE Device, UCHAR StringNumber, USHORT Language, PUSB_STRING_DESCRIPTOR Buffer ); /*++ Routine Description: This routine reads a string descriptor from a USB device. Arguments: Device - Supplies a pointer to the device to read from. StringNumber - Supplies the string descriptor index of the string to read. Language - Supplies the language code. Buffer - Supplies a pointer where the string descriptor and data will be returned. This buffer must be the size of the maximum string descriptor, which is 256 bytes. Return Value: Status code. --*/ USB_API HANDLE UsbDeviceOpen ( PUSB_DEVICE Device ); /*++ Routine Description: This routine attempts to open a USB device for I/O. Arguments: Device - Supplies a pointer to the device to open. Return Value: Returns a handle to the device upon success. INVALID_HANDLE if the device could not be opened. --*/ USB_API VOID UsbDeviceClose ( HANDLE UsbDeviceHandle ); /*++ Routine Description: This routine closes an open USB handle. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. Return Value: None. --*/ USB_API PUSB_TRANSFER UsbAllocateTransfer ( HANDLE UsbDeviceHandle, UCHAR EndpointNumber, ULONG MaxTransferSize, ULONG Flags ); /*++ Routine Description: This routine allocates a new USB transfer structure. This routine must be used to allocate transfers. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. EndpointNumber - Supplies the endpoint number that the transfer will go to. MaxTransferSize - Supplies the maximum length, in bytes, of the transfer. Attempts to submit a transfer with lengths longer than this initialized length will fail. Longer transfer sizes do require more resources as they are split into subpackets, so try to be reasonable. Flags - Supplies a bitfield of flags regarding the transaction. See USB_TRANSFER_FLAG_* definitions. Return Value: Returns a pointer to the new USB transfer on success. NULL when there are insufficient resources to complete the request. --*/ USB_API VOID UsbDestroyTransfer ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine destroys an allocated transfer. This transfer must not be actively transferring. Arguments: Transfer - Supplies a pointer to the transfer to destroy. Return Value: None. --*/ USB_API KSTATUS UsbSubmitTransfer ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine submits a USB transfer. The routine returns immediately, indicating only whether the transfer was submitted successfully. When the transfer actually completes, the callback routine will be called. Arguments: Transfer - Supplies a pointer to the transfer to destroy. Return Value: STATUS_SUCCESS if the transfer was submitted to the USB host controller's queue. STATUS_INVALID_PARAMETER if one or more of the transfer fields is not properly filled out. Failing status codes if the request could not be submitted. --*/ USB_API KSTATUS UsbSubmitSynchronousTransfer ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine submits a USB transfer, and does not return until the transfer is completed successfully or with an error. This routine must be called at low level. Arguments: Transfer - Supplies a pointer to the transfer to destroy. Return Value: STATUS_SUCCESS if the transfer was submitted to the USB host controller's queue. STATUS_INVALID_PARAMETER if one or more of the transfer fields is not properly filled out. Failing status codes if the request could not be submitted. --*/ USB_API KSTATUS UsbSubmitPolledTransfer ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine submits a USB transfer, and does not return until the transfer is completed successfully or with an error. This routine is meant to be called in critical code paths at high level. Arguments: Transfer - Supplies a pointer to the transfer to submit. Return Value: Status code. --*/ USB_API KSTATUS UsbCancelTransfer ( PUSB_TRANSFER Transfer, BOOL Wait ); /*++ Routine Description: This routine cancels a USB transfer, waiting for the transfer to enter the inactive state before returning. Must be called at low level. Arguments: Transfer - Supplies a pointer to the transfer to cancel. Wait - Supplies a boolean indicating that the caller wants to wait for the transfer the reach the inactive state. Specify TRUE if unsure. Return Value: Returns STATUS_SUCCESS if the transfer was successfully cancelled. Returns STATUS_TOO_LATE if the transfer was not cancelled, but moved to the inactive state. --*/ USB_API KSTATUS UsbInitializePagingDeviceTransfers ( VOID ); /*++ Routine Description: This routine initializes the USB core to handle special paging device transfers that are serviced on their own work queue. Arguments: None. Return Value: Status code. --*/ USB_API ULONG UsbTransferAddReference ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine adds a reference to a USB transfer. Arguments: Transfer - Supplies a pointer to the transfer that is to be referenced. Return Value: Returns the old reference count. --*/ USB_API ULONG UsbTransferReleaseReference ( PUSB_TRANSFER Transfer ); /*++ Routine Description: This routine releases a reference on a USB transfer. Arguments: Transfer - Supplies a pointer to the transfer that is to be dereferenced. Return Value: Returns the old reference count. --*/ USB_API KSTATUS UsbGetStatus ( HANDLE UsbDeviceHandle, UCHAR RequestRecipient, USHORT Index, PUSHORT Data ); /*++ Routine Description: This routine gets the status from the given device, interface, or endpoint, as determined based on the request type and index. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. RequestRecipient - Supplies the recipient of this get status request. Index - Supplies the index of this get status request. This can be zero for devices, an interface number, or an endpoint number. Data - Supplies a pointer that receives the status from the request. Return Value: Status code. --*/ USB_API KSTATUS UsbSetFeature ( HANDLE UsbDeviceHandle, UCHAR RequestRecipient, USHORT Feature, USHORT Index ); /*++ Routine Description: This routine sets the given feature for a device, interface or endpoint, as specified by the request type and index. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. RequestRecipient - Supplies the recipient of this clear feature request. Feature - Supplies the value of this clear feature request. Index - Supplies the index of this clear feature request. This can be zero for devices, an interface number, or an endpoint number. Return Value: Status code. --*/ USB_API KSTATUS UsbClearFeature ( HANDLE UsbDeviceHandle, UCHAR RequestType, USHORT FeatureSelector, USHORT Index ); /*++ Routine Description: This routine sets the configuration to the given configuration value. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. RequestType - Supplies the type of this clear feature request. FeatureSelector - Supplies the value of this clear feature request. Index - Supplies the index of this clear feature request. This can be zero for devices, an interface number, or an endpoint number. Return Value: Status code. --*/ USB_API ULONG UsbGetConfigurationCount ( HANDLE UsbDeviceHandle ); /*++ Routine Description: This routine gets the number of possible configurations in a given device. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. Return Value: Returns the number of configurations in the device. --*/ USB_API KSTATUS UsbGetConfiguration ( HANDLE UsbDeviceHandle, UCHAR ConfigurationNumber, BOOL NumberIsIndex, PUSB_CONFIGURATION_DESCRIPTION *Configuration ); /*++ Routine Description: This routine gets a configuration out of the given device. This routine will send a blocking request to the device. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. ConfigurationNumber - Supplies the index or configuration value of the configuration to get. NumberIsIndex - Supplies a boolean indicating whether the configuration number is an index (TRUE) or a specific configuration value (FALSE). Configuration - Supplies a pointer where a pointer to the desired configuration will be returned. Return Value: Status code. --*/ USB_API PUSB_CONFIGURATION_DESCRIPTION UsbGetActiveConfiguration ( HANDLE UsbDeviceHandle ); /*++ Routine Description: This routine gets the currently active configuration set in the device. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. Return Value: Returns a pointer to the current configuration. NULL if the device is not currently configured. --*/ USB_API KSTATUS UsbSetConfiguration ( HANDLE UsbDeviceHandle, UCHAR ConfigurationNumber, BOOL NumberIsIndex ); /*++ Routine Description: This routine sets the configuration to the given configuration value. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. ConfigurationNumber - Supplies the configuration index or value to set. NumberIsIndex - Supplies a boolean indicating whether the configuration number is an index (TRUE) or a specific configuration value (FALSE). Return Value: Status code. --*/ USB_API KSTATUS UsbClaimInterface ( HANDLE UsbDeviceHandle, UCHAR InterfaceNumber ); /*++ Routine Description: This routine claims an interface, preparing it for I/O use. An interface can be claimed more than once. This routine must be called at low level. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. InterfaceNumber - Supplies the number of the interface to claim. Return Value: Status code. --*/ USB_API VOID UsbReleaseInterface ( HANDLE UsbDeviceHandle, UCHAR InterfaceNumber ); /*++ Routine Description: This routine releases an interface that was previously claimed for I/O. After this call, the caller that had claimed the interface should not use it again without reclaiming it. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. InterfaceNumber - Supplies the number of the interface to release. Return Value: Status code. --*/ USB_API KSTATUS UsbSendControlTransfer ( HANDLE UsbDeviceHandle, USB_TRANSFER_DIRECTION TransferDirection, PUSB_SETUP_PACKET SetupPacket, PVOID Buffer, ULONG BufferLength, PULONG LengthTransferred ); /*++ Routine Description: This routine sends a syncrhonous control transfer to or from the given USB device. Arguments: UsbDeviceHandle - Supplies a pointer to the device to talk to. TransferDirection - Supplies whether or not the transfer is to the device or to the host. SetupPacket - Supplies a pointer to the setup packet. Buffer - Supplies a pointer to the buffer to be sent or received. This does not include the setup packet, this is the optional data portion only. BufferLength - Supplies the length of the buffer, not including the setup packet. LengthTransferred - Supplies a pointer where the number of bytes that were actually transfered (not including the setup packet) will be returned. Return Value: Status code. --*/ USB_API PVOID UsbGetDeviceToken ( PUSB_DEVICE Device ); /*++ Routine Description: This routine returns the system device token associated with the given USB device. Arguments: Device - Supplies a pointer to a USB device. Return Value: Returns a system device token. --*/ USB_API BOOL UsbIsPolledIoSupported ( HANDLE UsbDeviceHandle ); /*++ Routine Description: This routine returns a boolean indicating whether or not the given USB device's controller supports polled I/O mode. Polled I/O should only be used in dire circumstances. That is, during system failure when a crash dump file needs to be written over USB Mass Storage at high run level with interrupts disabled. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. Return Value: Returns a boolean indicating if polled I/O is supported (TRUE) or not (FALSE). --*/ USB_API KSTATUS UsbResetEndpoint ( HANDLE UsbDeviceHandle, UCHAR EndpointNumber ); /*++ Routine Description: This routine resets the given endpoint for the given USB device. This includes resetting the data toggle to DATA 0. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. EndpointNumber - Supplies the number of the endpoint to be reset. Return Value: Status code. --*/ USB_API KSTATUS UsbFlushEndpoint ( HANDLE UsbDeviceHandle, UCHAR EndpointNumber, PULONG TransferCount ); /*++ Routine Description: This routine flushes the given endpoint for the given USB device. This includes busily waiting for all active transfers to complete. This is only meant to be used at high run level when preparing to write a crash dump file using USB Mass Storage. Arguments: UsbDeviceHandle - Supplies the handle returned when the device was opened. EndpointNumber - Supplies the number of the endpoint to be reset. TransferCount - Supplies a pointer that receives the total number of transfers that were flushed. Return Value: Status code. --*/