U.S. patent application number 10/837444 was filed with the patent office on 2005-11-03 for generic usb drivers.
This patent application is currently assigned to Microsoft Corporation. Invention is credited to Aull, Randall E., Bhesania, Firdosh K..
Application Number | 20050246723 10/837444 |
Document ID | / |
Family ID | 34939567 |
Filed Date | 2005-11-03 |
United States Patent
Application |
20050246723 |
Kind Code |
A1 |
Bhesania, Firdosh K. ; et
al. |
November 3, 2005 |
Generic USB drivers
Abstract
Techniques are disclosed to provide generic USB drivers. More
particularly, a generic USB device driver architecture is described
which enables development through a user-mode USB library that
accesses a generic kernel-mode driver. In a described
implementation, a method includes loading a kernel-mode generic
device driver in response to a plug-in event of a device. A user
software component accesses the device by utilizing routines
provided by the generic user-mode library (e.g., a dynamic link
library (DLL)) that communicates with the generic device
driver.
Inventors: |
Bhesania, Firdosh K.;
(Kirkland, WA) ; Aull, Randall E.; (Kenmore,
WA) |
Correspondence
Address: |
LEE & HAYES PLLC
421 W RIVERSIDE AVENUE SUITE 500
SPOKANE
WA
99201
|
Assignee: |
Microsoft Corporation
Redmond
WA
|
Family ID: |
34939567 |
Appl. No.: |
10/837444 |
Filed: |
April 29, 2004 |
Current U.S.
Class: |
719/321 ;
719/328 |
Current CPC
Class: |
G06F 9/4411
20130101 |
Class at
Publication: |
719/321 ;
719/328 |
International
Class: |
G06F 009/46 |
Claims
What is claimed is:
1. A method comprising: loading a kernel-mode generic device driver
in response to a plug-in event of a device; and a user software
component accessing the device by utilizing a plurality of routines
provided by a generic user-mode library, the generic user-mode
library being communicatively coupled to the generic device driver,
wherein a separate generic device driver is loaded for each
plugged-in device or for each functionality supported by the
device.
2. A method as recited in claim 1, wherein the plurality of
routines are implemented as application programming interfaces
(APIs).
3. A method as recited in claim 1, wherein the device is a
universal serial bus (USB) device.
4. A method as recited in claim 1, wherein the plug-in event is
detected by a plug and play (PNP) module.
5. A method as recited in claim 1, further comprising loading a
device driver corresponding to an extracted device ID, the
extracted device ID corresponding to the plugged-in device, wherein
the generic device driver facilitates communication between the
loaded device driver and the user software component.
6. A method as recited in claim 5, wherein the device ID is
extracted by a core stack coupled to the plugged-in device through
a data communication bus.
7. A method comprising: extracting a device ID in response to a
plug-in event; loading a device driver corresponding to the
extracted device ID; and loading a generic device driver to
facilitate communication between the loaded device driver and a
user software component.
8. A method as recited in claim 7, wherein a separate generic
device driver is loaded for each device ID or for each
functionality supported by a device corresponding to the device
ID.
9. A method as recited in claim 7, wherein the device ID identifies
a universal serial bus (USB) device.
10. A method as recited in claim 7, wherein the extracting is
performed by a core stack.
11. A method as recited in claim 7, wherein the extracting is
performed by a core stack and the core stack is coupled to a data
communication bus to communicate with a plurality of devices.
12. A method as recited in claim 7, wherein the extracting is
performed by a core stack and at least one user software component
communicates with a plurality of devices through a hub coupled to
the core stack.
13. A method as recited in claim 7, wherein the generic device
driver is loaded in a kernel mode.
14. A method as recited in claim 7, wherein the user software
component resides in a user mode.
15. A method as recited in claim 7, wherein the plug-in event is
detected by a plug and play (PNP) module.
16. A method as recited in claim 7, wherein the plug-in event is
detected by a plug and play (PNP) module and the PNP module matches
the extracted device ID to the device driver.
17. A method as recited in claim 7, further comprising registering
a unique ID corresponding to the extracted device ID.
18. A method as recited in claim 7, further comprising accessing a
device corresponding to the extracted device ID.
19. A method as recited in claim 7, further comprising the user
software component communicating with the generic device driver
through a generic user-mode library.
20. A method as recited in claim 7, further comprising the user
software component communicating with the generic device driver
through a generic user-mode library, the user-mode library
comprising a plurality of routines to facilitate communication with
a device corresponding to the device ID.
21. A method as recited in claim 20, wherein the routines are
implemented as application programming interfaces (APIs).
22. An apparatus comprising: a computing device; and a device
coupled to the computing device, wherein a kernel-mode generic
device driver is loaded in response to coupling the device to the
computing device and a user software component accesses the device
by utilizing a plurality of routines provided by a generic
user-mode library, the generic user-mode library being
communicatively coupled to the generic device driver, and wherein a
separate generic device driver is loaded for each device or for
each functionality supported by the device.
23. An apparatus as recited in claim 22, wherein the plurality of
routines are implemented as application programming interfaces
(APIs).
24. An apparatus as recited in claim 22, wherein the device is a
universal serial bus (USB) device.
25. One or more computer-readable media having instructions stored
thereon that, when executed, direct a machine to perform acts
comprising: loading a kernel-mode generic device driver in response
to a plug-in event of a device; and a user software component
accessing the device by utilizing a plurality of routines provided
by a generic user-mode library, the generic user-mode library being
communicatively coupled to the generic device driver, wherein a
separate generic device driver is loaded for each plugged-in device
or for each functionality supported by the device.
26. One or more computer-readable media as recited in claim 25,
wherein the plurality of routines are implemented as application
programming interfaces (APIs).
27. One or more computer-readable media as recited in claim 25,
wherein the device is a universal serial bus (USB) device.
28. One or more computer-readable media as recited in claim 25,
wherein the plug-in event is detected by a plug and play (PNP)
module.
29. One or more computer-readable media as recited in claim 25,
further comprising loading a device driver corresponding to an
extracted device ID, the extracted device ID corresponding to the
plugged-in device, wherein the generic device driver facilitates
communication between the loaded device driver and the user
software component.
Description
COPYRIGHT NOTICE
[0001] A portion of the disclosure of this patent document contains
material which is subject to copyright protection. The copyright
owner has no objection to the facsimile reproduction by anyone of
the patent document or the patent disclosure, as it appears in the
Patent and Trademark Office patent file or records, but otherwise
reserves all copyright rights whatsoever. .COPYRGT.2004 Microsoft
Corporation. All rights reserved.
TECHNICAL FIELD
[0002] The present invention generally relates to digital
communications and, in an implementation, to generic universal
serial bus (USB) drivers.
BACKGROUND
[0003] As computers become more commonplace, an ever-increasing
number of functionalities are incorporated into a single computer
system. Often, the additional functionality is provided by
attaching an external device to the computer system. In turn, the
external device communicates with the computer system to provide
the additional functionality.
[0004] The Universal serial bus (USB) has become a standard
communication channel for connecting external devices to a computer
system. USB allows a number of devices to be connected to a same
computer system simultaneously, while providing relatively high
bandwidth. For example, the latest commonly available version of
USB (e.g., USB 2.0) can transfer up to 480 Mbps (mega bits per
second).
[0005] Vendors who provide USB devices are generally required to
provide device drivers to enable access to these devices. Commonly,
a device driver is a program and set of data that allows a computer
system to access the device (e.g., read data from the device, write
data to the device, send commands to the device, and receive status
data from the device).
[0006] Currently, most USB device vendors are required to provide
kernel-mode device drivers for their devices. Generally, a kernel
is the central part of an operating system (OS) which remains
active and in control of a computer system while the OS is running.
For example, the kernel provides the necessary services (such as
memory and process management) to the computer system. As a result,
kernel-mode drivers can easily cause an unrecoverable system-wide
crash in the event of the smallest of malfunctions (or bugs).
Additionally, implementing USB drivers in kernel-mode necessitates
investment of time and energy in programming complicated
kernel-mode drivers, in addition to extra hardware or software
required for testing the kernel-mode driver. Furthermore, when
upgrading an OS, incompatible or outdated kernel-mode device driver
may cause a crash and prevent a successful system upgrade.
SUMMARY
[0007] Techniques are disclosed to provide a generic USB driver.
More particularly, a generic USB device driver architecture is
described, which enables development through a user-mode USB
library that communicates with a generic kernel-mode driver.
[0008] In a described implementation, a method includes loading a
kernel-mode generic device driver in response to a plug-in event of
a device. A user software component accesses the device by
utilizing routines provided by a generic user-mode library (e.g., a
dynamic link library (DLL)) that communicates with the generic
device driver.
[0009] In another implementation, a separate generic device driver
is loaded for each plugged-in device, or for each functionality
supported by a device.
[0010] In some implementations, articles of manufacture are
provided as computer program products. One implementation of a
computer program product provides a computer program storage medium
readable by a computer system and encoding a computer program.
Another implementation of a computer program product may be
provided in a computer data signal embodied in a carrier wave by a
computing system and encoding the computer program.
[0011] Moreover, the computer program product encodes a computer
program for a computer process executing on a computer system. The
computer process loads a kernel-mode generic device driver in
response to a plug-in event of a device (as may be detected by a
plug and play module). A user software component accesses the
device by utilizing routines provided by a generic user-mode
library (e.g., a dynamic link library (DLL)).
[0012] Other implementations are also described and recited
herein.
BRIEF DESCRIPTION OF THE DRAWINGS
[0013] The detailed description is described with reference to the
accompanying figures. In the figures, the left-most digit(s) of a
reference number identifies the figure in which the reference
number first appears. The use of the same reference numbers in
different figures indicates similar or identical items.
[0014] FIG. 1 illustrates an exemplary system for a generic device
driver.
[0015] FIG. 2 illustrates an exemplary a system with multiple
instances of generic device drivers for multiple devices.
[0016] FIG. 3 illustrates an exemplary method for utilizing generic
device drivers.
[0017] FIG. 4 illustrates an exemplary method for handling I/O in
generic device drivers.
[0018] FIG. 5 illustrates an exemplary method for providing power
management in generic device drivers.
[0019] FIG. 6 illustrates a general computer environment, which can
be used to implement the techniques described herein.
DETAILED DESCRIPTION
[0020] The following disclosure describes techniques to provide a
generic device driver architecture. More specifically, Techniques
are disclosed to provide generic USB drivers. More particularly,
the architecture utilizes a user-mode USB library which accesses a
generic kernel-mode driver. The architecture, in part, reduces the
development time of device drivers, improves the end-user
experience (e.g., by limiting system-wide crashes whether during
normal operations or an upgrade process), and centralize testing
and debugging. The architecture may also be utilized to improve
input-output (I/O) handling, security, and power management as will
be further discussed herein. Moreover, the techniques discussed
herein may be implemented as software, firmware, hardware, and/or
combinations thereof.
[0021] Overview of Generic Drivers
[0022] FIG. 1 illustrates an exemplary system 100 for a generic
device driver. The direction of the arrows in FIGS. 1 and 2 herein
indicate direction of data flow in accordance with an
implementation. The system 100 includes a kernel-mode environment
102 and a user-mode environment 104. The kernel-mode environment
102 includes a USB core stack 106 which may be a portion of the OS
and enables communication with USB devices at the hardware level.
The USB core stack 106 may facilitate hub functionality as will be
further discussed with reference to FIG. 2. The USB core stack 106
is coupled to a generic USB driver 108. The generic USB driver 108
manages the I/O of the USB device, and, more generally exposes the
USB device to the user-mode environment 104.
[0023] The user-mode environment 104 includes a generic USB
user-mode library 110 and a user software component 112.
Accordingly, the user software component 112 is a user-mode
software component in an implementation. The generic USB user-mode
library 110 provides routines (or application programming
interfaces (APIs)) which may be utilized by the USB user software
component 112 to communicate with or control the USB device. In an
implementation, the generic USB user-mode library 110 is a DLL.
Accordingly, the USB user software component 112 may manage a USB
device from the user-mode environment 104 by invoking routines in
the user mode rather than the kernel mode. A number of exemplary
APIs will be further discussed below under the same title.
[0024] Such an implementation is envisioned to reduce system-wide
crashes because if the USB user software component 112 (or a
routine provided by the generic USB user-mode library 110) crashes,
the kernel's operation remain unaffected. Additionally, such a
system (100) reduces the development time of device drivers and
centralize testing and debugging (in part, because only one
computer system is needed to test the USB interface, i.e., even
when a user-mode software component crashes, the system remains
operational).
[0025] In one implementation, data corresponding to the
communication interface between USB core stack 106 and the generic
USB driver 108 is published to developers or otherwise available
publicly, as well as information regarding the interface between
the USB user software component 112 and the generic USB user-mode
library 110. In an implementation, the information regarding the
interface between the generic USB driver 108 and the generic USB
user-mode library 110 need not be published.
[0026] Generic Drivers for Multiple Devices
[0027] FIG. 2 illustrates an exemplary a system 200 with multiple
instances of generic device drivers for multiple devices. The
system 200 includes the kernel-mode environment 102, user-mode
environment 104, USB core stack 106, generic USB user-mode library
110, and the USB user software component 112.
[0028] The system 200 includes a USB bus 202 to communicate data
(as will be further discussed with reference to FIG. 6 below). A
USB bus is but one example and other types of data communication
buses (such as a wired or wireless communication bus, e.g.,
Bluetooth, small computer system interface (SCSI), and the like)
may be utilizes in the system 200.
[0029] As illustrated in FIG. 2, the USB bus 202 is coupled to the
USB core stack 106 (as discussed with respect to FIG. 1). The USB
core stack 106 is in turn coupled to a physical device object (PDO)
to facilitate communication with a USB hub 206. The USB hub 206
allows multiple USB devices to be handled in the kernel-mode
environment 102. Accordingly, it is envisioned that the generic USB
drivers (108) may be coupled between the kernel-mode environment
102 and the user-mode environment 104.
[0030] As illustrated in FIG. 2, multiple PDOs may be utilized to
facilitate communication with various drivers (e.g., the generic
USB driver 108 and a USB composite driver 208). The user
environment 104 may communicate with each generic USB driver (108)
through functionality discovered and/or identified by globally
unique identifiers (GUID) 210. Each GUID 210 uniquely identifies
its USB interface/function. In one exemplary implementation, the
format for the GUID key in the OS registry file and/or driver file
(e.g., information file (INF)), such as the Windows OS available
through Microsoft Corporation of Redmond, Wash., is as follows:
[0031]
HKR,,DeviceInterfaceGUID,,"{058815B2-9805-47d3-B7D5-ABC464D3CA06}"
[0032] Accordingly, each GUID 210 identifies functionality
supported by the corresponding device which may be utilized by the
USB user-mode software component 112. For example, a user-mode
software component will search for any drivers that expose their
GUID of interest to find the device(s) that support the desired
functionality. A USB user software component 112 may then
communicate with a USB device through the generic USB user-mode
library 110 as discussed with reference to FIG. 1.
[0033] It is envisioned that multiple USB hubs (206) may be
utilized to permit communication with multiple USB devices or
functionalities incorporated within a single USB device. For
example, a USB hub (206) may be utilized to allow access to
different functionalities within a keyboard with multimedia command
buttons, in addition to key stroke buttons or integrated pointing
devices (e.g., joystick and or touch pad).
[0034] Generic Device Driver Operation
[0035] FIG. 3 illustrates an exemplary method 300 for utilizing
generic device drivers. Upon occurrence of a plug-in event (302)
which may be detected by a plug and play (PNP) module (e.g.,
residing in the OS), a core stack (e.g., 106 of FIGS. 1 and 2)
extracts a device ID corresponding to the plugged-in device. The
extracted device ID is provided or detected by the PNP module (306)
and the PNP module matches the extracted device ID with a generic
driver (308) (e.g., 108 of FIG. 2).
[0036] The matched generic driver (e.g., 108 of FIGS. 1 and 2) is
loaded (310) to facilitate communication between the loaded device
driver of stage 310 and a user software component (e.g., 112 of
FIGS. 1 and 2). In a stage 312, a unique ID is registered (such as
discussed with reference to 210 of FIG. 2). Finally, the plugged-in
device may be accessed (314) by the user software component through
the generic device driver.
[0037] In an implementation, it is envisioned that the PNP module
matches the extracted device ID to the generic device driver (e.g.,
where the generic device driver is compatible with the plugged-in
device), rather than another device ID. This in turn eliminates the
need for loading any additional drivers. Accordingly, in one
implementation, a kernel-mode generic device driver is loaded in
response to a plug-in event of a device and a user software
component accesses the device by utilizing routines provided by the
generic user-mode library. The generic user-mode library is
communicatively coupled to the generic device driver. The routines
may be implemented as APIs (which will be further discussed below
under the title "exemplary APIs"). Furthermore, a separate generic
device driver may be loaded for each plugged-in device (or
functionalities supported by the device).
[0038] I/O Handling in Generic Device Drivers
[0039] FIG. 4 illustrates an exemplary method 400 for handling I/O
in generic device drivers. In an implementation, the method 400
enables a user software component (e.g., 112 of FIGS. 1 and 2) to
leave hardware-specific I/O handling to the generic device drivers
(e.g., 110 of FIGS. 1 and 2) by calling a few routines. For
example, the user software component may simply issue initialize,
read/write, and release commands provided through the generic USB
user-mode library (e.g., 110 of FIG. 1), and leave the specific
data length considerations, data fragmentation, and/or data
reassembly to the generic device driver.
[0040] For example, the initialization may reset the generic USB
device driver's state and behavior to a default and prepare the
generic USB device driver to handle further operations. The reading
may read data from a specific endpoint on the corresponding device
and the writing may write data to a specific endpoint on the
corresponding device. The release may clean up all resources
claimed during the session that was started with the
initialization.
[0041] With respect to data length considerations, a USB input
(i.e., data from the device to a host or computing system discussed
with reference to FIG. 5) endpoint can transfer anywhere from 0
bytes up to that endpoint's specified maximum packet size at a
time, so the software on the host system needs to be prepared to
receive up to this maximum size for each packet in the transfer
(where a transfer is made up of multiple packets). If a user-mode
software component (e.g., 112 of FIGS. 1 and 2) requests a transfer
that is not a multiple of this maximum packet size, then the
generic USB device driver may automatically adjust the size of this
transfer. Accordingly, if the user software component requests a
data transfer with a length insufficient to handle all possible
data transfer sizes from the device, the length of the data
transfer is increased. This may be accomplished by splitting the
client's (the client being the user-mode software component) buffer
into at least two separate transfers (this is also referred to as
"segmentation"). The first transfer size may be the largest
multiple of maximum packet size ("MaxPacket" hereinafter) that is
less than the client's requested transfer size. The buffer for this
first transfer is the first N*MaxPacket (where this value is the
size of this first sub-transfer) of the client's buffer, so no
memory copy is required. The second transfer is MaxPacket bytes.
The buffer for this second transfer is a newly allocated buffer in
an implementation. Once both transfers are complete, the data from
the second transfer is copied back into the client's buffer until
either the client buffer is full, or a short packet is reached. If
any data is left over from the second transfer after the copy, it
may or may not be saved away for the next transfer request, based
on the pipe policy for that endpoint. It is also envisioned that if
there is a short packet in the first transfer, the second transfer
may never be issued.
[0042] Moreover, a USB host controller, in conjunction with the USB
core stack (e.g., 106 of FIGS. 1 and 2), often may only handle
transfer buffers up to a specific size. This size may be different
for different host controller implementations. The generic USB
device driver takes these size limits into account and if a
client's transfer request exceeds this limit, the transfer is split
into two or more transfers where all are less than or equal to this
limit. In one implementation, there are no buffer copies required
to implement this as each sub-transfer's buffer is just a part of
the client's original buffer.
[0043] As illustrated in FIG. 4, the method 400 initializes in a
stage 402, e.g., by defining a data structure utilized to access
the device. The initialization stage may reset the policy settings
to default values (as will be further discussed below with
reference to exemplary APIs, such as WinUsb_Initialize). The
initialization stage enables the generic user-mode library (e.g.,
the DLL associated with 110 of FIGS. 1 and 2) to run in one
implementation.
[0044] The method 400 defines the pipe policy (404) which may
define the behavior of the generic device driver including, for
example, time outs, end of packets, auto recovery from error,
packet termination guidelines, short packet handling, partial reads
such as used for reading headers prior to the actual data to
anticipate the amount of data that is to be transferred, discarding
extra data that is of no interest, and/or raw data handling (which
indicates that a user software component is guaranteeing proper
data handling), as will be further discussed below with reference
to exemplary APIs, such as WinUsb_SetPipePolicy. In an
implementation, each endpoint may have a pipe in a generic USB
driver that is individually configurable.
[0045] Some of these exemplary pipe behavior settings are further
discussed below in accordance with various implementations:
[0046] Time-out--this pipe policy may be set for a specific
endpoint and result in cancellation of any transfer for that
endpoint which is not completed within the specified amount of
time.
[0047] Packet termination guidelines--some USB device protocols
require that the host computing system mark the end of an output
transfer (from host to device) with a short-packet (a packet less
than that endpoint's specified threshold maximum packet size). If
the client's transfer is a multiple of that maximum packet size,
then a zero length packet is sent. This may be done automatically
for the user software component (or client), so that the client
does not need to worry about the maximum packet size, or whether or
not the transfer is a multiple of this size.
[0048] Auto-recovery from error--if there is a transfer error on
the USB bus for a specific transfer on a specific endpoint,
automatic recovery mechanisms may be enabled to attempt to clear
the error condition, so that further transfers are permitted to be
issued. It is also envisioned that an error condition may be
non-recoverable (i.e., no further transfers will occur).
[0049] Short packet handling--generally, when a short packet is
received from a specific endpoint on a USB device, the transfer is
completed by the USB core stack (e.g., 106 of FIGS. 1 and 2).
Sometimes the user software component does not intend for this to
cause completion of the transfer, but would rather keep reading
from the device until the specified number of bytes is received. In
one implementation, this can be handled by configuring the generic
USB device driver to ignore such events and keep reading data. This
may be implemented by re-issuing the pre-maturely completed
transfer with the buffer pointing to one byte passed the last
received byte.
[0050] Partial read--some device protocols include a header at the
beginning of a transfer that includes information about the data,
including size information, transfer type, etc. Some clients may
wish to read only this header before determining how to handle the
rest of the transfer. To handle such a scenario, the client may set
the behavior for the corresponding pipe (for which the transfer is
targeted) to allow the client to read just the header, and then the
generic USB device driver may save away any additional data
received after the header in that packet, such that it will be
added to the beginning of the client's subsequent transfer.
[0051] Discarding extra data--if a device sends more data in a
packet than a client requested, the client may configure the
generic USB device driver behavior for that endpoint to discard
that extra data, or save it to be added to the beginning of a
subsequent transfer.
[0052] Raw data--some clients would rather manage transfer
limitations themselves in order to bypass the automatic behavior
corrections of the generic USB device driver, for example, to
improve performance with respect to specific device features. These
clients may configure the generic USB device driver behavior for a
specific endpoint, so that rather than correcting the client's
behavior, it instead requires correct client behavior. Accordingly,
this approach allows all the well-behaved client requests to be
passed directly to the core USB stack.
[0053] In one implementation, the user software component may then
define a first-in, first-out (FIFO) buffer policy (406) (e.g., for
a specific pipe (endpoint)) and start filing the FIFO from the
device (408), as will be further discussed below with reference to
exemplary APIs, such as WinUsb_SetFifoPolicy and WinUSB_StartFifo.
The FIFO may then be read (e.g., by calling WinUsb_ReadFifo API
discussed below). In one implementation, one FIFO is provided for
each pipe. It is also envisioned that data may be read by using
WinUsb_ReadPipe. Accordingly, a FIFO is not required for reading
data. However, a FIFO may be used for a specific class of devices
which may generate data at an arbitrary time, or that constantly
streams data, for example.
[0054] The pipe is then read or written to in a stage 410.
Moreover, as detailed below, other APIs are available for handling
I/O which enable a user software component to more finely control
the I/O functions. For example, in an implementation, if the device
responds with a packet that is too large for the client buffer, the
data is added at the beginning of the next transfer (if this option
is enabled, for example, by Allow_Partial_Reads).
[0055] Exemplary APIs
[0056] One or more exemplary APIs are illustrated below which may
be utilized in the Microsoft Windows.RTM. environment to provide
the routines discussed with reference to FIGS. 1 and 2. For
example, routines (e.g., in generic USB user-mode library 110 of
FIGS. 1 and 2) may support the following actions (as will be
further discussed below):
[0057] querying for the USB descriptors: device, configuration,
interface and string;
[0058] enumerating USB device interfaces associated with a GUID
device interface class, and filter them by means of a
vendor-supplied callback routine;
[0059] selectively activating some interfaces of a USB device and
leaving others deactivated;
[0060] generating standard control transfer requests; and/or
[0061] transmit control, bulk, interrupt, and isochronous data.
[0062] The exemplary APIs discussed below are prefaced by "WinUSB"
to indicate that they correspond to a generic USB device driver for
the Microsoft Windows.RTM. OS. It is envisioned that other naming
conventions may be utilized. Also, a sample call, parameter, and
return values for each API is highlighted below.
[0063] 1. WinUsb_Initialize
[0064] The WinUsb_Initialize function initializes the WinUsb data
structures. Note that the policy settings are reset to the default
values when this function is called. An exemplary method for
calling this API is:
[0065] BOOL_stdcall
[0066] WinUsb_Initialize(
[0067] IN HANDLE DeviceHandle,
[0068] OUT PWINUSB_INTERFACE_HANDLE InterfaceHandle
[0069] );
[0070] Parameters
DeviceHandle
[0071] The handle to the device that was returned by a routine to
create a file (e.g., CreateFile). WinUsb uses overlapped I/O so a
flag (e.g., FILE_FLAG_OVERLAPPED) should be specified in the
CreateFile call.
InterfaceHandle
[0072] This is the interface handle that can be used for all other
WinUSB API function calls. This is an opaque handle that is
generated by WinUSB.
[0073] Return Value
[0074] This function returns TRUE if it succeeded. Otherwise, it
returns FALSE, and the logged error can be retrieved by calling
GetLastError.
[0075] 2. WinUsb_Free
[0076] The WinUsb_Free function frees all the resources that were
allocated by WinUsb_Initialize. An exemplary method for calling
this API is:
[0077] BOOL_stdcall
[0078] WinUsb_Free(
[0079] IN WINUSB_INTERFACE_HANDLE InterfaceHandle
[0080] );
[0081] Parameters
InterfaceHandle
[0082] This is the interface handle that was returned by
WinUsb_Initialize.
[0083] Return Value
[0084] This function returns TRUE if it succeeded. Otherwise, it
returns FALSE, and the logged error can be retrieved by calling
GetLastError.
[0085] 3. WinUsb_QueryAlternateInterface
[0086] The WinUsb_QueryAlternateInterface function returns the
first alternate interface descriptor for a particular interface
handle. An exemplary method for calling this API is:
[0087] BOOL_stdcall
[0088] WinUsb_QueryAlternateInterface(
[0089] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0090] IN UCHAR AlternateInterfaceNumber,
[0091] OUT PUSB_INTERFACE_DESCRIPTOR UsbAltInterfaceDescriptor
[0092] );
[0093] Parameters
InterfaceHandle
[0094] This is the interface handle that was returned by
WinUsb_Initialize.
AlternateInterfaceNumber
[0095] This is a value that indicates the alternate interface to
return. A value of 0 indicates the first alternate interface, a
value of 1 indicates the second alternate interface, and so
forth.
UsbAltInterfaceDescriptor
[0096] A pointer to a caller-allocated USB_INTERFACE_DESCRIPTOR
structure.
[0097] Return Value
[0098] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0099] 4. WinUsb_QueryDeviceInformation
[0100] The WinUsb_QueryDeviceInformation function returns
information about the physical device that is associated with a
WINUSB interface. An exemplary method for calling this API is:
[0101] BOOL_stdcall
[0102] WinUsb_QueryDeviceInformation(
[0103] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0104] IN ULONG InformationType,
[0105] IN OUT PULONG BufferLength,
[0106] OUT PVOID Buffer
[0107] );
[0108] Parameters
InterfaceHandle
[0109] This is the interface handle that was returned by
WinUsb_Initialize.
InformationType
[0110] This is a value that specifies which interface information
value to retrieve.
BufferLength
[0111] This the length, in bytes, of Buffer, or the maximum number
of bytes to read. This parameter may be set to the actual number of
bytes that were copied into Buffer.
Buffer
[0112] This is a caller-allocated buffer that receives the
requested value.
[0113] Return Value
[0114] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0115] Notes
[0116] The following list describes the possible InformationType
values.
DEVICE_SPEED (0x01)
[0117] This request will return one of the following values, based
on the speed of the device.
[0118] LowSpeed (0x01)
[0119] FullSpeed (0x02)
[0120] High-Speed (0x03)
PHYSICAL_DEVICE_ID (0x02)
[0121] This value contains the physical device identifier of the
device.
[0122] 5. WinUsb_GetDescriptor
[0123] The WinUsb_GetDescriptor function returns a requested
descriptor. An exemplary method for calling this API is:
[0124] BOOL_stdcall
[0125] WinUsb_GetDescriptor(
[0126] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0127] IN UCHAR DescriptorType,
[0128] IN UCHAR Index,
[0129] IN USHORT LanguageID,
[0130] OUT PUCHAR Buffer,
[0131] IN ULONG BufferLength,
[0132] OUT PULONG LengthTransferred
[0133] );
[0134] Parameters
InterfaceHandle
[0135] This is the interface handle that was returned by
WinUsb_Initialize.
DescriptorType
[0136] This is a value that specifies the type of descriptor to
return. For the standard values, reference may be made to the USB
specification which is available at http://www.usb.org.
Index
[0137] This is the descriptor index, which is documented in the USB
specification.
LanguageID
[0138] This is a value that specifies the language identifier, if
the requested descriptor is a string descriptor.
Buffer
[0139] This is a caller-allocated buffer that receives the
requested descriptor.
BufferLength
[0140] This is the length, in bytes, of Buffer, or the maximum
number of bytes to read.
LengthTransferred
[0141] This receives the actual number of bytes that were copied
into Buffer.
[0142] Return Value
[0143] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0144] 6. WinUsb_SetCurrentAlternateInterface
[0145] The WinUsb_SetCurrentAlternateInterface function selects a
specified alternate interface setting for an interface. An
exemplary method for calling this API is:
[0146] BOOL_stdcall
[0147] WinUsb_SetCurrentAlternateInterface(
[0148] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0149] IN UCHAR InterfaceNumber
[0150] );
[0151] Parameters
InterfaceHandle
[0152] This is the interface handle that was returned by
WinUsb_Initialize.
InterfaceNumber
[0153] This is the value contained in the bInterfaceNumber member
of the PUSB_INTERFACE_DESCRIPTOR structure, which was populated by
WinUsb_QueryAlternateInterface.
[0154] Return Value
[0155] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0156] 7. WinUsb_GetCurrentAlternateInterface
[0157] The WinUsb_GetCurrentAlternateInterface function gets the
current alternate interface setting for an interface. An exemplary
method for calling this API is:
[0158] BOOL_stdcall
[0159] WinUsb_GetCurrentAlternateInterface(
[0160] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0161] OUT PUCHAR InterfaceNumber
[0162] );
[0163] Parameters
InterfaceHandle
[0164] This is the interface handle returned from
WinUsb_Initialize
InterfaceNumber
[0165] This is a pointer to a UCHAR that will receive the currently
selected alternate interface.
[0166] Return Value
[0167] This function returns TRUE, if the function succeeds and
populates the structure. Otherwise, it returns FALSE and the logged
error can be retrieved by a call to GetLastError.
[0168] 8. WinUsb_QueryPipe
[0169] The WinUsb_QueryPipe function returns the pipe information
for a specified pipe that is associated with an interface. Note
that the default control pipe may not be returned. An exemplary
method for calling this API is:
[0170] BOOL_stdcall
[0171] WinUsb_QueryPipe(
[0172] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0173] IN UCHAR AlternateInterfaceNumber,
[0174] IN UCHAR PipeIndex,
[0175] OUT PWINUSB_PIPE_INFORMATION PipeInformation
[0176] );
[0177] Parameters
InterfaceHandle
[0178] This is the interface handle that was returned by
WinUsb_Initialize.
AlternateInterfaceNumber
[0179] This is a value that specifies the alternate interface to
which the information is to be return.
PipeIndex
[0180] This is a value that specifies the pipe to which the
information is returned. This value is not the same as the PipeId
in one implementation. Instead, it represents the pipe in the
interface's list. A value of 0 signifies the first pipe, a value of
1 signifies the second pipe, and so forth. This value should be
less than bNumEndpoints in the interface's descriptor.
PipeInformation
[0181] This is a pointer to a caller-allocated
WINUSB_PIPE_INFORMATION structure.
[0182] Return Value
[0183] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0184] Notes
[0185] The definition of the WINUSB_PIPE_INFORMATION structure may
be as follows:
[0186] typedef struct_WINUSB_PIPE_INFORMATION {
[0187] USBD_PIPE_TYPE PipeType;
[0188] UCHAR PipeId;
[0189] USHORT MaximumPacketSize;
[0190] UCHAR Interval;
[0191] } WINUSB_PIPE_INFORMATION, *PWINUSB_PIPE_INFORMATION;
[0192] The PipeId member is the USB 8-bit (hexadecimal) endpoint
address, which consists of a 7-bit address and a direction bit.
[0193] 9. WinUsb_SetPipePolicy
[0194] The WinUsb_SetPipePolicy function sets the policy for a
specific pipe (endpoint). An exemplary method for calling this API
is:
[0195] BOOL_stdcall
[0196] WinUsb_SetPipePolicy(
[0197] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0198] IN UCHAR PipeID,
[0199] IN ULONG PolicyType,
[0200] IN ULONG ValueLength,
[0201] IN ULONG_PTR Value
[0202] );
[0203] Parameters
InterfaceHandle
[0204] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0205] This is the pipe identifier of the pipe to set the policy
for.
PolicyType
[0206] This is a value that specifies the policy parameter to
change.
ValueLength
[0207] This is the length, in bytes, of the buffer that Value
points to, or zero if Value does not point to a buffer.
Value
[0208] The new value for the policy parameter that is specified by
PolicyType.
[0209] Return Value
[0210] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0211] Notes
[0212] The following list describes the possible PolicyType
values:
SHORT_PACKET_TERMINATE (0x01)
[0213] If Value is TRUE (nonzero), every WRITE(OUT) request that is
a multiple of the maximum packet size for the endpoint is
terminated with a zero-length packet. The default is FALSE.
AUTO_CLEAR_STALL (0x02)
[0214] If Value is TRUE (nonzero), a stall PID will be ignored and,
unless first-in, first-out (FIFO) buffering is being used, an error
will be returned. In this case, however, the pipe will not be
halted and data will continue to flow. This parameter has no effect
on CONTROL pipes. Note that the host automatically clears the
device stall condition. The default is FALSE.
PIPE_TRANSFER_TIMEOUT (0x03)
[0215] Value is the amount of time, in milliseconds that a transfer
should be cancelled after. A value of zero signifies an infinite
amount of time. The default is an infinite amount of time.
IGNORE_SHORT_PACKETS (0x04)
[0216] If Value is TRUE (nonzero), a read operation will not
complete when a short packet is received. Instead, the operation
will complete only when the specified number of bytes is read. If
Value is FALSE, a read operation will complete when either the
specified number of bytes is read or a short packet is received.
The default is FALSE.
ALLOW_PARTIAL_READS (0x05)
[0217] If Value is FALSE (zero), the read request will fail if the
device returns more data than was requested. If Value is TRUE, the
extra data is saved, and it is returned at the beginning of the
data for the following read request. The default is TRUE.
AUTO_FLUSH (0x06)
[0218] If Value is FALSE (zero) and the device returns more data
than was requested, the remaining data will be discarded. If Value
is TRUE, the behavior depends on the value of ALLOW_PARTIAL_READS.
Either the data will be saved and then returned at the beginning of
the data for the following read request, or the request will fail.
The default is FALSE.
Raw_IO (0x07)
[0219] This enables a user software component (such as 112 of FIGS.
1-2) to guarantee proper data handling. If the data provided by the
user software component is in improper format, the data may be
flushed.
[0220] 10. WinUsb_GetPipePolicy
[0221] The WinUsb_GetPipePolicy function gets the policy for a
specific pipe (endpoint). An exemplary method for calling this API
is:
[0222] BOOL_stdcall
[0223] WinUsb_GetPipePolicy(
[0224] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0225] IN UCHAR PipeID,
[0226] IN ULONG PolicyType,
[0227] IN OUT PULONG ValueLength,
[0228] OUT PVOID Value
[0229] );
[0230] Parameters
InterfaceHandle
[0231] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0232] This is the pipe identifier of the pipe to get the policy
for.
PolicyType
[0233] This is a value that specifies the policy parameter to
get.
ValueLength
[0234] This is a pointer to the length of the buffer that Value
points to. On output, this parameter receives the length of the
data that was copied into the Value buffer.
Value
[0235] This is a pointer to a buffer that receives the specified
pipe policy value.
[0236] Return Value
[0237] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0238] 11. WinUsb_SetFifoPolicy
[0239] The WinUsb_SetFifoPolicy function sets the policy for a
specific pipe (endpoint). An exemplary method for calling this API
is:
[0240] BOOL_stdcall
[0241] WinUsb_SetFifoPolicy(
[0242] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0243] IN UCHAR PipeID,
[0244] IN ULONG PolicyType,
[0245] IN ULONG ValueLength,
[0246] IN ULONG_PTR Value
[0247] );
[0248] Parameters
InterfaceHandle
[0249] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0250] This is the pipe identifier of the pipe to set the policy
for.
PolicyType
[0251] This is a value that specifies the policy parameter to
change.
ValueLength
[0252] This is the length, in bytes, of the buffer that Value
points to, or zero if Value does not point to a buffer.
Value
[0253] This is the new value for the policy parameter that is
specified by PolicyType.
[0254] Return Value
[0255] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0256] Notes
[0257] The following list describes the possible PolicyType
values.
FIFO_SIZE (0x01)
[0258] Value is the size, in bytes, of the FIFO input buffer. The
default value is 16.times.MaxPacketSize. If this limit is reached,
data will be lost.
NOTIFICATION_THRESHOLD (0x03)
[0259] Value is the number of bytes that should be present in the
FIFO buffer before the callback function is called. If
IGNORE_SHORT_PACKETS is FALSE and a short packet is encountered,
the callback function will be called anyway.
[0260] 12. WinUsb_GetFifoPolicy
[0261] The WinUsb_GetFifoPolicy function gets the policy for a
specific pipe (endpoint). An exemplary method for calling this API
is:
[0262] BOOL_stdcall
[0263] WinUsb_GetFifoPolicy(
[0264] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0265] IN UCHAR PipeID,
[0266] IN ULONG PolicyType,
[0267] IN OUT PULONG ValueLength,
[0268] OUT PVOID Value
[0269] );
[0270] Parameters
InterfaceHandle
[0271] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0272] This is the pipe identifier of the pipe to get the policy
for.
PolicyType
[0273] This is a value that specifies the policy parameter to
get.
ValueLength
[0274] This is a pointer to the length of the buffer that Value
points to. On output, this parameter receives the length of the
data that was copied into the Value buffer.
Value
[0275] This is a pointer to a buffer that receives the specified
FIFO policy parameter.
[0276] Return Value
[0277] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0278] 13. WinUsb_StartFifo
[0279] The WinUsb_StartFifo function starts the automatic read
mechanism that reads data from the device into a FIFO buffer. When
data is added to this buffer, the FifoDataNotification function is
called, which notifies the client of the presence of the data. The
client can then issue requests to read data from the FIFO buffer.
An exemplary method for calling this API is:
[0280] BOOL_stdcall
[0281] WinUsb_StartFifo(
[0282] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0283] IN UCHAR PipeID,
[0284] IN PWINUSB_NOTIFICATION_CALLBACK FifoDataNotification,
[0285] IN PVOID FifoDataNotificationContext
[0286] );
[0287] Parameters
InterfaceHandle
[0288] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0289] This is the pipe identifier of the pipe to affect.
FifoDataNotification
[0290] This is an optional callback function to be called when the
notification threshold is reached.
FifoDataNotificationContext
[0291] This is an optional context to be passed to the
FifoDataNotification callback function.
[0292] Return Value
[0293] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0294] Notes
[0295] The PWINUSB_NOTIFICATION_CALLBACK type declaration is as
follows:
[0296] typedef
[0297] VOID
[0298] (*PWINUSB_NOTIFICATION_CALLBACK)(
[0299] WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0300] UCHAR PipeID,
[0301] ULONG NotificationType,
[0302] PVOID NotificationParameter,
[0303] PVOID Context
[0304] );
[0305] One possible value for the NotificationType member is
FifoDataAvailable (0x01). This value indicates that the FIFO buffer
contains enough data for a ReadFifo request of
NOTIFICATION_THRESHOLD bytes to complete immediately. As such, the
NotificationParameter member can be ignored.
[0306] 14. WinUsb_StopFifo
[0307] The WinUsb_StopFifo function stops the automatic read
mechanism. An exemplary method for calling this API is:
[0308] BOOL_stdcall
[0309] WinUsb_StopFifo(
[0310] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0311] IN UCHAR PipeID
[0312] );
[0313] Parameters
InterfaceHandle
[0314] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0315] This is the pipe identifier of the pipe to affect.
[0316] Return Value
[0317] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0318] 15. WinUsb_ReadFifo
[0319] The WinUsb_ReadFifo function reads data from a pipe's FIFO
buffer. Note that the USB packet size does not factor in to the
transfer for a read request. If the device responds with a packet
that is too large for the client buffer, the data is added at the
beginning of the next transfer if ALLOW_PARTIAL_READS is TRUE. If
ALLOW_PARTIAL_READS is FALSE, the read request will fail. An
exemplary method for calling this API is:
[0320] BOOL_stdcall
[0321] WinUsb_ReadFifo(
[0322] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0323] IN UCHAR PipeID,
[0324] OUT PUCHAR Buffer,
[0325] IN ULONG BufferLength,
[0326] OUT PULONG LengthTransferred,
[0327] IN LPOVERLAPPED Overlapped
[0328] );
[0329] Parameters
InterfaceHandle
[0330] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0331] This is the identifier of the pipe to read from.
Buffer
[0332] This is a caller-allocated buffer to read the data into.
BufferLength
[0333] This is the length, in bytes, of Buffer, or the maximum
number of bytes to read.
LengthTransferred
[0334] This is a pointer to a ULONG that receives the actual number
of bytes that were copied into Buffer.
Overlapped
[0335] This is an optional pointer to an OVERLAPPED structure,
which is used for asynchronous operations. If this parameter is
specified, this function will immediately return, and the event is
signaled when the operation is complete.
[0336] Return Value
[0337] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0338] 16. WinUsb_ReadPipe
[0339] The WinUsb_ReadPipe function reads data from the pipe. Note
that the USB packet size does not factor in to the transfer for a
read request. If the device responds with a packet that is too
large for the client buffer, the data is added at the beginning of
the next transfer if ALLOW_PARTIAL_READS is TRUE. If
ALLOW_PARTIAL_READS is FALSE, the read request will fail. An
exemplary method for calling this API is:
[0340] BOOL_stdcall
[0341] WinUsb_ReadPipe(
[0342] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0343] IN UCHAR PipeID,
[0344] IN PUCHAR Buffer,
[0345] IN ULONG BufferLength,
[0346] OUT PULONG LengthTransferred,
[0347] IN LPOVERLAPPED Overlapped
[0348] );
[0349] Parameters
InterfaceHandle
[0350] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0351] This is the identifier of the pipe to read from.
Buffer
[0352] This is a caller-allocated buffer to read the data into.
BufferLength
[0353] This is the length, in bytes, of Buffer, or the maximum
number of bytes to read.
LengthTransferred
[0354] This is a pointer to a ULONG that receives the actual number
of bytes that were copied into Buffer.
Overlapped
[0355] This is an optional pointer to an OVERLAPPED structure,
which is used for asynchronous operations. If this parameter is
specified, this function will immediately return, and the event is
signaled when the operation is complete.
[0356] Return Value
[0357] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0358] 17. WinUsb_WritePipe
[0359] The WinUsb_WritePipe function writes data to the pipe. An
method for calling this API is:
[0360] BOOL_stdcall
[0361] WinUsb_WritePipe(
[0362] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0363] IN UCHAR PipeID,
[0364] IN PUCHAR Buffer,
[0365] IN ULONG BufferLength,
[0366] OUT PULONG LengthTransferred,
[0367] IN LPOVERLAPPED Overlapped
[0368] );
[0369] Parameters
InterfaceHandle
[0370] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0371] This is the identifier of the pipe to write to.
Buffer
[0372] This is a caller-allocated buffer that contains the data to
write.
BufferLength
[0373] This is the number of bytes to write.
LengthTransferred
[0374] This is a pointer to a ULONG that receives the actual number
of bytes that were written to the pipe.
Overlapped
[0375] This is an optional pointer to an OVERLAPPED structure,
which is used for asynchronous operations. If this parameter is
specified, this function will return, and the event is signaled
when the operation is complete.
[0376] Return Value
[0377] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0378] 18. WinUsb_ControlTransfer
[0379] The WinUsb_ControlTransfer function transmits data over the
default control endpoint. An exemplary method for calling this API
is:
[0380] BOOL_stdcall
[0381] WinUsb_ControlTransfer(
[0382] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0383] IN WINUSB_SETUP_PACKET SetupPacket,
[0384] IN PUCHAR Buffer,
[0385] IN ULONG BufferLength,
[0386] OUT PULONG LengthTransferred,
[0387] IN LPOVERLAPPED Overlapped
[0388] );
[0389] Parameters
InterfaceHandle
[0390] This is the interface handle that was returned by
WinUsb_Initialize.
SetupPacket
[0391] This is the 8-byte setup packet.
Buffer
[0392] This is a caller-allocated buffer that contains the data to
transfer.
BufferLength
[0393] This is the number of bytes to transfer, not including the
setup packet.
LengthTransferred
[0394] This is a pointer to a ULONG that receives the actual number
of transferred bytes.
Overlapped
[0395] This is an optional pointer to an OVERLAPPED structure,
which is used for asynchronous operations. If this parameter is
specified, this function will immediately return, and the event is
signaled when the operation is complete.
[0396] Return Value
[0397] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0398] Notes
[0399] The WINUSB_SETUP_PACKET structure declaration is as
follows:
[0400] typedef struct_WINUSB_SETUP_PACKET {
[0401] UCHAR RequestType;
[0402] UCHAR Request;
[0403] USHORT Value;
[0404] USHORT Index;
[0405] USHORT Length;
[0406] } WINUSB_SETUP_PACKET, *PWINUSB_SETUP_PACKET;
[0407] 19. WinUsb_ResetPipe
[0408] The WinUsb_ResetPipe function resets the data toggle and
clears the stall condition on a pipe. An exemplary method for
calling this API is:
[0409] BOOL_stdcall
[0410] WinUsb_ResetPipe(
[0411] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0412] IN UCHAR PipeID
[0413] );
[0414] Parameters
InterfaceHandle
[0415] This the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0416] This is the identifier of the control pipe.
[0417] Return Value
[0418] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0419] 20. WinUsb_AbortPipe
[0420] The WinUsb_AbortPipe function aborts all the pending
transfers for a pipe. An exemplary method for calling this API
is:
[0421] BOOL_stdcall
[0422] WinUsb_AbortPipe(
[0423] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0424] IN UCHAR PipeID
[0425] );
[0426] Parameters
InterfaceHandle
[0427] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0428] This is the identifier of the control pipe.
[0429] Return Value
[0430] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0431] 21. WinUsb_FlushPipe
[0432] The WinUsb_FlushPipe function discards any data that was
saved as a result of the device returning more data than the client
requested. An exemplary method for calling this API is:
[0433] BOOL_stdcall
[0434] WinUsb_FlushPipe(
[0435] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0436] IN UCHAR PipeID
[0437] );
[0438] Parameters
InterfaceHandle
[0439] This is the interface handle that was returned by
WinUsb_Initialize.
PipeID
[0440] This is the identifier of the control pipe.
[0441] Return Value
[0442] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0443] Power Management
[0444] FIG. 5 illustrates an exemplary method 500 for providing
power management in generic device drivers. In an implementation,
the method 500 enables a computing system (such as that discussed
with reference to FIG. 6) to enter a low-power state while devices
(such as those discussed with reference to FIGS. 1-4) are attached
to it.
[0445] A power management policy is defined for the attached
device(s) (502), e.g., through the generic USB user-mode library
(e.g., 110 of FIG. 1). The power policy may include provisions on
whether automatic suspension is allowed, whether the device may be
automatically awakened, and/or whether a minimum delay threshold is
set for suspending the device (as is further discussed with
reference to the exemplary APIs, such as
WinUsb_SetInterfacePowerPolicy).
[0446] More specifically, the automatic suspension may involve
detecting when a device has become "idle," possibly meaning that
there has not been a transfer in a specified amount of time, at
which point the generic USB driver (e.g., 108 of FIGS. 1 and 2) may
suspend the device to save power. In an implementation, the generic
USB driver will automatically detect when the device needs to be
powered back up, and will do so at the appropriate times.
[0447] With respect to automatically awakening the computing
system, a client (such as 112 of FIGS. 1 and 2) may configure the
generic USB device driver's behavior to allow the device to wake
the computing system from a low-power state (e.g., standby or
hibernation). In an implementation, the generic USB device driver
will handle all operations required to prepare the device and the
computing system for this capability.
[0448] Furthermore, the delay threshold time period may be set such
that a client (such as 112 of FIGS. 1 and 2) may specify an amount
of time that the generic USB device driver needs to guarantee will
pass after the last transfer before suspending the device.
Accordingly, the delay threshold may specify a time period after a
data transfer and the computing system waits for the time period
after the data transfer to pass before the device enters the
suspend mode.
[0449] Once condition(s) for entering a suspend mode are met (e.g.,
in accordance with the power policy in effect) (504), the device
enters a low-power state (506). This in turn allows the computing
system to which the device is attached (whether through wires or
wirelessly as discussed previously) to enter a low-power state
(508).
[0450] The method 500 is envisioned to allow power savings even in
situations where multiple devices are attached to a computing
system by utilizing the functionality provided by the generic
device drivers discussed herein. Namely, in absence of a generic
device driver configuration, multiple devices attached to the
computing system may not enter their suspend modes simultaneously
or for a sufficient period of time to enable effective overall
power saving by the computing system.
[0451] In various implementations, the following list summarizes
the behavior across power management states:
[0452] All pipe handles, interface handles, locks, and alternate
settings are preserved across power management events.
[0453] Any transfers that are in progress are suspended during a
low-power state, and they are resumed when the system is working.
If the client (i.e., the user software component 112) is using the
FIFO buffer, that buffer is restarted after the power management
callback.
[0454] If a device-specific configuration should be restored, the
client (i.e., the user software component 112) should do so when
the system returns to working. This can be determined from the
WM_POWERBROADCAST message.
[0455] The client (i.e., the user software component 112) may
indicate that the interface is idle by calling
WINUSB_SetInterfaceIdle to support a selective suspend. The caller
can specify that the device should be enabled for a remote wakeup
while idle. No direct action is implied by this call.
[0456] Moreover, as detailed below, other APIs are available for
handling power management which enable a user software component to
more finely control the power management functions.
[0457] 1. WinUsb_SetInterfacePowerPolicy
[0458] The WinUsb_SetInterfacePowerPolicy function sets the power
policy for the device. An exemplary method for calling this API
is:
[0459] BOOL_stdcall
[0460] WinUsb_SetInterfacePowerPolicy(
[0461] WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0462] ULONG PolicyType,
[0463] ULONG ValueLength,
[0464] ULONG_PTR Value
[0465] );
[0466] Parameters
InterfaceHandle
[0467] This is the interface handle that was returned by
WinUsb_Initialize.
PolicyType
[0468] This is a value that specifies the policy parameter to
change.
ValueLength
[0469] This is the length, in bytes, of the buffer that Value
points to, or zero if Value does not point to a buffer.
Value
[0470] This is the new value for the policy parameter that is
specified by PolicyType.
[0471] Return Value
[0472] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0473] Notes
[0474] The following list describes the possible PolicyType
values:
AUTO_SUSPEND (0x01)
[0475] If Value is TRUE (nonzero), the device will be suspended
when no transfers are pending. The default is TRUE.
ENABLE_WAKE (0x02)
[0476] Set Value to TRUE if the device supports WAKE. The default
is FALSE.
SUSPEND_DELAY (0x03)
[0477] Value is the minimum amount of time, in milliseconds, that
the driver should wait after any transfer before it can suspend the
device. The default is five seconds.
[0478] 2. WinUsb_GetInterfacePowerPolicy
[0479] The WinUsb_GetInterfacePowerPolicy function gets the power
policy for the device. An exemplary method for calling this API
is:
[0480] BOOL_stdcall
[0481] WinUsb_GetInterfacePowerPolicy(
[0482] IN WINUSB_INTERFACE_HANDLE InterfaceHandle,
[0483] IN ULONG PolicyType,
[0484] IN OUT PULONG ValueLength,
[0485] OUT PVOID Value
[0486] );
[0487] Parameters
InterfaceHandle
[0488] This is the interface handle that was returned by
WinUsb_Initialize.
PolicyType
[0489] This is a value that specifies the policy parameter to
get.
ValueLength
[0490] This is a pointer to the length of the buffer that Value
points to. On output, this parameter receives the length of the
data that was copied into the Value buffer.
Value
[0491] This is a pointer to a buffer that receives the specified
power policy value.
[0492] Return Value
[0493] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0494] 3. WinUsb_EnableInterfaceIdle
[0495] The WinUsb_EnableInterfaceIdle function indicates that an in
interface is idle so that the operating system can power down the
device (USB suspend). This is how user-mode clients support a
selective suspend. Any access (read or write) to one of the pipes
automatically brings the interface out of the idle state, so no
query of the idle state is provided. Calling this function does not
guarantee that the device will be suspended; it is merely a
suggestion that the device is currently capable of supporting USB
suspend state. If the FIFO buffer is running, it will continue to
run until the device is actually suspended. An exemplary method for
calling this API is:
[0496] BOOL_stdcall
[0497] WinUsb_EnableInterfaceIdle(
[0498] WINUSB_INTERFACE_HANDLE InterfaceHandle
[0499] );
[0500] Parameters
InterfaceHandle
[0501] This is the interface handle that was returned by
WinUsb_Initialize.
[0502] Return Value
[0503] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0504] 4. WinUsb_DisableInterfaceIdle
[0505] The WinUsb_DisableInterfaceldle function either prevents the
device from being suspended or wakes up the device if it has
already been suspended. An exemplary method for calling this API
is:
[0506] BOOL_stdcall
[0507] WinUsb_DisableInterfaceIdle(
[0508] WINUSB_INTERFACE_HANDLE InterfaceHandle
[0509] );
[0510] Parameters
InterfaceHandle
[0511] The interface handle that was returned by
WinUsb_Initialize.
[0512] Return Value
[0513] This function returns TRUE if it succeeded and populated the
structure. Otherwise, it returns FALSE, and the logged error can be
retrieved by calling GetLastError.
[0514] Security
[0515] In one implementation, security is provided through the
named device object created by a IoRegisterDeviceInterface in the
generic device driver 108. Security attributes can be specified for
this symbolic link limiting who can open it.
[0516] In such an implementation, only one user software component
(e.g., 112) can have the link opened at any given time, so when a
software component opens the link no other software components can
access the interface unless that software component gets the actual
handle.
[0517] It is envisioned that the control pipe for a physical device
may be shared among multiple interfaces (e.g., for different
functionalities supported by the device), so a user software
component may be able to send control commands to another
interface. This may require certain restrictions on control
transfers in an implementation. Additionally, security access on a
symbolic link may be handled by setting the security attributes on
the PDO (204).
[0518] General Computing Environment
[0519] FIG. 6 illustrates a general computer environment 600, which
can be used to implement the techniques described herein. For
example, the computer environment 600 may be utilized to run the OS
including the generic device driver (108), the generic user-mode
library (110), and/or the user software component (112). The
computer environment 600 is only one example of a computing
environment and is not intended to suggest any limitation as to the
scope of use or functionality of the computer and network
architectures. The computer environment 600 should also not be
interpreted as having any dependency or requirement relating to any
one or a combination of components illustrated in the exemplary
computer environment 600.
[0520] Computer environment 600 includes a general-purpose
computing device in the form of a computer 602. The components of
computer 602 can include, but are not limited to, one or more
processors or processing units 604 (optionally including a
cryptographic processor or co-processor), a system memory 606, and
a system bus 608 that couples various system components including
the processor 604 to the system memory 606.
[0521] The system bus 608 represents one or more of any of several
types of bus structures, including a memory bus or memory
controller, a peripheral bus, an accelerated graphics port, and a
processor or local bus using any of a variety of bus architectures.
By way of example, such architectures can include an Industry
Standard Architecture (ISA) bus, a Micro Channel Architecture (MCA)
bus, an Enhanced ISA (EISA) bus, a Video Electronics Standards
Association (VESA) local bus, and a Peripheral Component
Interconnects (PCI) bus also known as a Mezzanine bus.
[0522] Computer 602 typically includes a variety of
computer-readable media. Such media can be any available media that
is accessible by computer 602 and includes both volatile and
non-volatile media, removable and non-removable media.
[0523] The system memory 606 includes computer-readable media in
the form of volatile memory, such as random access memory (RAM)
610, and/or non-volatile memory, such as read only memory (ROM)
612. A basic input/output system (BIOS) 614, containing the basic
routines that help to transfer information between elements within
computer 602, such as during start-up, is stored in ROM 612. RAM
610 typically contains data and/or program modules that are
immediately accessible to and/or presently operated on by the
processing unit 604.
[0524] Computer 602 may also include other removable/non-removable,
volatile/non-volatile computer storage media. By way of example,
FIG. 6 illustrates a hard disk drive 616 for reading from and
writing to a non-removable, non-volatile magnetic media (not
shown), a magnetic disk drive 618 for reading from and writing to a
removable, non-volatile magnetic disk 620 (e.g., a "floppy disk"),
and an optical disk drive 622 for reading from and/or writing to a
removable, non-volatile optical disk 624 such as a CD-ROM, DVD-ROM,
or other optical media. The hard disk drive 616, magnetic disk
drive 618, and optical disk drive 622 are each connected to the
system bus 608 by one or more data media interfaces 626.
Alternatively, the hard disk drive 616, magnetic disk drive 618,
and optical disk drive 622 can be connected to the system bus 608
by one or more interfaces (not shown).
[0525] The disk drives and their associated computer-readable media
provide non-volatile storage of computer-readable instructions,
data structures, program modules, and other data for computer 602.
Although the example illustrates a hard disk 616, a removable
magnetic disk 620, and a removable optical disk 624, it is to be
appreciated that other types of computer-readable media which can
store data that is accessible by a computer, such as magnetic
cassettes or other magnetic storage devices, flash memory cards,
CD-ROM, digital versatile disks (DVD) or other optical storage,
random access memories (RAM), read only memories (ROM),
electrically erasable programmable read-only memory (EEPROM), and
the like, can also be utilized to implement the exemplary computing
system and environment.
[0526] Any number of program modules can be stored on the hard disk
616, magnetic disk 620, optical disk 624, ROM 612, and/or RAM 610,
including by way of example, an operating system 626, one or more
application programs 628, other program modules 630, and program
data 632. Each of such operating system 626, one or more
application programs 628, other program modules 630, and program
data 632 (or some combination thereof) may implement all or part of
the resident components that support the distributed file
system.
[0527] A user can enter commands and information into computer 602
via input devices such as a keyboard 634 and a pointing device 636
(e.g., a "mouse"). Other input devices 638 (not shown specifically)
may include a microphone, joystick, game pad, satellite dish,
serial port, scanner, and/or the like. These and other input
devices are connected to the processing unit 604 via input/output
interfaces 640 that are coupled to the system bus 608, but may be
connected by other interface and bus structures, such as a parallel
port, game port, or a USB (such as discussed with reference to
FIGS. 1 and 2). The USB port may be utilized to connect a camera,
personal digital assistant (PDA), MP3 device, video capture device,
a flash card reader, and the like to the computer environment
600.
[0528] A monitor 642 or other type of display device can also be
connected to the system bus 608 via an interface, such as a video
adapter 644. In addition to the monitor 642, other output
peripheral devices can include components such as speakers (not
shown) and a printer 646 which can be connected to computer 602 via
the input/output interfaces 640.
[0529] Computer 602 can operate in a networked environment using
logical connections to one or more remote computers, such as a
remote computing device 648. By way of example, the remote
computing device 648 can be a personal computer, portable computer,
a server, a router, a network computer, a peer device or other
common network node, game console, and the like. The remote
computing device 648 is illustrated as a portable computer that can
include many or all of the elements and features described herein
relative to computer 602.
[0530] Logical connections between computer 602 and the remote
computer 648 are depicted as a local area network (LAN) 650 and a
general wide area network (WAN) 652. Such networking environments
are commonplace in offices, enterprise-wide computer networks,
intranets, and the Internet.
[0531] When implemented in a LAN networking environment, the
computer 602 is connected to a local network 650 via a network
interface or adapter 654. When implemented in a WAN networking
environment, the computer 602 typically includes a modem 656 or
other means for establishing communications over the wide network
652. The modem 656, which can be internal or external to computer
602, can be connected to the system bus 608 via the input/output
interfaces 640 or other appropriate mechanisms. It is to be
appreciated that the illustrated network connections are exemplary
and that other means of establishing communication link(s) between
the computers 602 and 648 can be employed.
[0532] In a networked environment, such as that illustrated with
computing environment 600, program modules depicted relative to the
computer 602, or portions thereof, may be stored in a remote memory
storage device. By way of example, remote application programs 658
reside on a memory device of remote computer 648. For purposes of
illustration, application programs and other executable program
components such as the operating system are illustrated herein as
discrete blocks, although it is recognized that such programs and
components reside at various times in different storage components
of the computing device 602, and are executed by the data
processor(s) of the computer.
[0533] Various modules and techniques may be described herein in
the general context of computer-executable instructions, such as
program modules, executed by one or more computers or other
devices. Generally, program modules include routines, programs,
objects, components, data structures, etc. that perform particular
tasks or implement particular abstract data types. Typically, the
functionality of the program modules may be combined or distributed
as desired in various implementations.
[0534] An implementation of these modules and techniques may be
stored on or transmitted across some form of computer-readable
media. Computer-readable media can be any available media that can
be accessed by a computer. By way of example, and not limitation,
computer-readable media may include "computer storage media" and
"communications media."
[0535] "Computer storage media" includes volatile and non-volatile,
removable and non-removable media implemented in any method or
technology for storage of information such as computer-readable
instructions, data structures, program modules, or other data.
Computer storage media includes, but is not limited to, RAM, ROM,
EEPROM, flash memory or other memory technology, CD-ROM, digital
versatile disks (DVD) or other optical storage, magnetic cassettes,
magnetic tape, magnetic disk storage or other magnetic storage
devices, or any other medium which can be used to store the desired
information and which can be accessed by a computer.
[0536] "Communication media" typically includes computer-readable
instructions, data structures, program modules, or other data in a
modulated data signal, such as carrier wave or other transport
mechanism. Communication media also includes any information
delivery media. The term "modulated data signal" means a signal
that has one or more of its characteristics set or changed in such
a manner as to encode information in the signal. By way of example,
and not limitation, communication media includes wired media such
as a wired network or direct-wired connection, and wireless media
such as acoustic, radio frequency (RF), infrared, Wi-Fi, cellular,
Bluetooth enabled, and other wireless media. Combinations of any of
the above are also included within the scope of computer-readable
media.
[0537] In one implementation, the hardware device whose information
is accessed (such as discussed with reference to FIGS. 1 and 2) may
be any device coupled with components of the general computer
environment 600 (such as the processing units 604). Also, the
hardware device may be a peripheral device of the general computer
environment 600 (such as the mouse 636, keyboard 634, printer 646,
and the like).
CONCLUSION
[0538] Thus, although the invention has been described in language
specific to structural features and/or methodological acts, it is
to be understood that the invention defined in the appended claims
is not necessarily limited to the specific features or acts
described. For example, the techniques described herein may be
applied to wired or wireless communication channels (such as
Bluetooth, small computer system interface (SCSI), and the like).
Accordingly, the specific features and acts are disclosed as
exemplary forms of implementing the claimed invention.
* * * * *
References