Jan Axelson, USB Complete

Подождите немного. Документ загружается.

Chapter 9

236

the example, this value is USB\VID_0925&PID_1456. The hardware ID con-

tains the Vendor ID (0925h) and Product ID (1456h) from the device descrip-

tor in the device.

The KmdfLibraryVersion directive specifies a version number for the KMDF

library, which provides redistributable co-installer files used in installing the

driver. The version number can vary with the WDK build and must match the

version of the framework library used to develop the driver. The files

WdfCoInstaller01007.dll and WUDFUpdate_01007.dll also incorporate the ver-

sion number in their names and change with the library version. Chapter 14

has more about these files.

In the Dev_AddReg section, a WinUSB device should have a vendor-defined

device interface GUID as described in Chapter 8.

The Strings section can provide device-specific strings for the company name,

descriptions of the device and the driver service, and a name for the installation

media.

A catalog file contains cryptographic hash values that function as digital

thumbprints that identify the files in a driver package. The catalog file can also

contain a digital signature that the operating system uses to determine whether

the driver files have been altered since the signature was created. You can create

an unsigned catalog file with the Inf2Cat tool in the WDK. Chapter 17 has

more about digital signatures. The example INF file includes a commented-out

reference to the file MyCatFile.cat.

7UKPI&GXKEG+FGPVKHKECVKQP5VTKPIU

To identify possible drivers for a device, Windows searches the system’s INF

files for a device identification string that matches a string created from infor-

mation in the device’s descriptors. Types of device identification strings include

hardware IDs and compatible IDs.

+FGPVKHKECVKQP5VTKPIU1DVCKPGFHTQOC&GXKEG

Every USB device has a device ID, which is a hardware ID that the hub driver

creates from the Vendor ID, Product ID, bcdDevice, and as appropriate, other

values in the device descriptor. When assigning a driver, the device ID is the

best match. A device ID for a USB device has this form:

USB\Vid_xxxx&Pid_yyyy&Rev_zzzz

Matching a Driver to a Device

237

The values in xxxx, yyyy, and zzzz are four characters each, with xxxx =

idVendor, yyyy = idProduct, and zzzz = bcdDevice. The xxxx and yyyy values are

hexadecimal except for Windows Me, which uses decimal, and zzzz is in BCD

format.

For example, a device with Vendor ID = 0925h, Product ID = 1234h, and bcd-

Device = 0310 has this device ID:

USB\Vid_0925&Pid_1234&Rev_0310

Composite devices can specify a driver for each function. In this case, the device

has a device ID for each interface that represents a function. A device ID for an

interface has this form:

USB\Vid_xxxx&Pid_yyyy&Rev_zzzz&MI_ww

The 2-character value in ww equals bInterfaceNumber in the interface descrip-

tor for one of the device’s interfaces.

A HID-class device whose report descriptor contains more than one top-level

collection can have a device ID for each collection. A device ID for a collection

has this form with bb indicating the collection number:

USB\Vid_xxxx&Pid_yyyy&Rev_zzzz&MI_ww&Colbb

In addition to a device ID, some drivers create one or more hardware IDs and

compatible IDs for devices. A hardware ID has a similar format to a device ID

but represents a less precise match. For example, the ID may omit the bcdDe-

vice value:

USB\Vid_xxxx&Pid_yyyy

A hardware ID for a CDC device can use a Cdc_ value to specify a subclass.

This device ID specifies CDC subclass 08h (WMC wireless handset control

model):

USB\Vid_0925&Pid_0902&Rev_0210&Cdc_08

A compatible ID identifies a device by class and optional subclass and protocol

codes and may have any of the following forms:

USB\Class_aa&SubClass_bb&Prot_cc

USB\Class_aa&SubClass_bb

USB\Class_aa

The values aa, bb, and cc match values in the device descriptor or an interface

descriptor and are two characters each: aa is bDeviceClass or bInterfaceClass,

bb is bDeviceSubclass or bInterfaceSubclass, and cc is bDeviceProtocol or

bInterfaceProtocol. The values are expressed in hexadecimal, except for Win-

dows Me, which uses decimal.

Chapter 9

238

For example, the class code for HIDs is 03h, so HID-class devices have the fol-

lowing compatible ID:

USB\Class_03

Mass-storage devices and printers have additional class-specific compatible IDs

defined in the WDK documentation.

A compatible ID in an INF file indicates a less desirable but acceptable match.

Compatible IDs enable Windows to find and load a driver if the installation

can’t find an INF file with a matching device ID. A vendor’s INF file should not

contain a compatible ID.

1DVCKPKPI+FGPVKHKECVKQP5VTKPIUHTQOCP+0((KNG

In an INF file, each entry in a Models section has one or more hardware IDs.

The first hardware ID should be a device ID. Following the device ID may be

one or more hardware and compatible IDs separated by commas.

(KPFKPIC/CVEJ

In looking for the best match between the information retrieved from a device

and the information in INF files, the installer assigns a rank to every possible

match, with a lower numerical value indicating a better match. NT-based Win-

dows editions give more favorable ranks to signed drivers, and 64-bit Windows

editions require signed drivers. Windows 98 doesn’t check for signed drivers.

A signed driver has a catalog file with a digital signature that indicates that the

driver has passed Windows Hardware Quality Labs (WHQL) testing. Chapter

17 has more about WHQL testing. The best match is a device ID that matches

a hardware ID in a signed driver’s INF file. An installer that can’t find a match

starts the Found New Hardware wizard and gives the user a chance to specify a

location to look for the INF file.

Composite devices, which have multiple interfaces, are a special case. Because

each interface may require a different driver, selecting a driver using only the

Vendor ID and Product ID isn’t sufficient. Windows XP and later can use the

compatible ID USB\COMPOSITE, which loads the USB common class

generic parent driver. This driver creates device and compatible IDs for each

interface, and the installer assigns a driver to each interface. In earlier Windows

editions, the bus or hub driver handles this task.

Windows provides INF files for many devices and device classes, and devices

may provide their own INF files. To speed up searching, Windows creates a

precompiled INF (PNF) file during device installation and stores the file in the

Matching a Driver to a Device

239

same folder as the device’s INF file. The PNF file contains much of the same

information as the INF file but in a format that enables quicker searching.

9JGPVQ2TQXKFGCP+0((KNG

Not every device requires its own INF file. Many devices that use the system’s

class drivers can use the INF file that Windows provides for the class. These are

some INF files for USB classes included with Windows XP:

Because Windows XP and later prefer signed drivers, if you provide an

unsigned driver for a device in a supported class, Windows XP and later won’t

use your driver and instead will select a compatible ID from the class’s INF file.

An INF file is considered part of the driver package, so Windows XP and later

prefer a system-provided INF file for a system driver over an unsigned, ven-

dor-provided INF file for the same driver even if the vendor’s INF file contains

a matching hardware ID.

When the best match is an unsigned driver, operating-system settings can affect

whether Windows blocks installation, installs the driver with a warning, or

installs with no warning. To change the setting, in Windows Control Panel,

select System > Hardware > Driver Signing.

A device that uses a class driver can have a custom, signed INF file with ven-

dor-specific strings that display in the Device Manager. For example, the entry

for a HID can be a vendor-specific string instead of the default USB Human

Interface Device.

Many INF files provided with Windows contain sections with manufac-

turer-specific information. When a device passes WHQL tests, Microsoft can

add the device’s sections to an existing INF file or add a manufacturer-specific

INF file to the files distributed with Windows.

%NCUU +0((KNG

audio wdmaudio.inf

human interface device (HID) input.inf (hiddev.inf in Windows 98)

hub usb.inf

mass storage usbstor.inf

printer usbprint.inf

smart card smartcrd.inf

still image sti.inf

Chapter 9

240

Modems and USB virtual COM ports in the communications device class must

provide their own INF files even if they use system-supplied drivers. A device

that uses the WinUSB driver must have an INF file that contains the device’s

Vendor ID and Product ID. A device with a vendor-specific driver must have

an INF file.

6QQNUCPF&KCIPQUVKE#KFU

Microsoft provides tools to help in creating and testing INF files. The ChkINF

utility tests a file’s structure and syntax. Log files record events that occur during

device installation.

ChkINF is a Perl script that requires a Perl interpreter, available free from

www.activeware.com and other sources. The script runs from a command

prompt and creates an HTML page that annotates an INF file with errors and

warnings.

During device installation, the PnP manager and the Windows Setup and

Device Installer Services (SetupAPI) log events and errors to a text file. The log

can be very helpful when debugging problems with device installations. In

Windows XP, the data is in %windir%\setupapi.log. In Windows Vista, the data

is in %windir%\inf\SetupAPI.dev.log. The WDK documentation has more

about how to use the logging capability.

6KRUHQT7UKPI+0((KNGU

Here are some tips for using INF files during and after product development:

7UGC8CNKF8GPFQT+&

Firmware that you make available outside of a controlled environment must use

a Vendor ID assigned by the USB-IF. My example code uses the Vendor ID of

0925h, which is assigned to my company, Lakeview Research. The owner of the

Vendor ID is responsible for ensuring that each product and version has a

unique Vendor ID/Product ID pair. Borrowing someone else’s Vendor ID can

lead to conflicts if the owner of the ID uses the same values for a different

device.

(KPFKPI+0((KNGU

On installing a device with a new INF file, Windows copies the INF file to

%windir%\inf and may rename the file oem*.inf and create a .PNF file named

Matching a Driver to a Device

241

oem*pnf, where * is a number. Using numbered oem file names eliminates con-

flicts if multiple vendors provide INF files with the same name. To find INF

files that contain a specific Vendor ID and Product ID, go to Start > Search >

For Files or Folders, browse to %windir%\inf and search for the text

VID_xxxx&PID_yyyy, where xxxx is the device’s Vendor ID and yyyy is the Prod-

uct ID.

4GOQXKPI&GXKEG+PHQTOCVKQP

When experimenting with different settings in an INF file, you may find that

the operating system remembers information stored in the system registry from

a previous version of the INF file. If you want the installation to use a different

or changed INF file for a device (because you’ve changed the driver or device

firmware, for example), you may need to tell the operating system to forget

what it knows about the device. With the device installed, right-click its listing

in the Device Manager, and select Uninstall. In the inf directory, remove (but

save in another location if needed) any INF and PNF files that contain your

device’s Vendor ID and Product ID. You can then detach and reattach the

device, and installation will start fresh in searching for a driver.

9JCVVJG7UGT5GGU

What the user sees on attaching a USB device varies with the Windows edition,

the contents of the device’s INF file, the driver’s location, whether the driver has

a co-installer and is digitally signed, and whether the device has been attached

and enumerated previously and has a serial number.

&GXKEGCPF%NCUU+PUVCNNGTU

Device and class installers are DLLs that provide functions relating to device

installation. Windows provides default installers for devices in supported device

setup classes. On NT-based Windows editions, a device vendor can provide a

device co-installer that works along with a class co-installer to support opera-

tions specific to one or more devices in a class. A device co-installer can add

information to the registry, request additional configuration information from

the user, provide device-specific Property pages for the Device Manager to dis-

play, and perform other tasks relating to device installation. The WDK includes

the Driver Install Frameworks (DIFx) tools for creating Windows Installer

packages.

Chapter 9

242

5GCTEJKPIHQTC&TKXGT

On boot up or device attachment, after retrieving a device’s descriptors, the

operating system searches for a hardware key that matches information in the

descriptors. On success, the operating system can assign a driver to the device.

The hardware key’s Driver entry points to the driver key, which names the INF

file. The hardware key’s Service entry points to the service key, which has infor-

mation about the driver files.

On first attachment, no matching hardware key exists so Windows searches for

a match in the INF files. On finding none, the New Device Wizard starts. For

signed drivers, an installation program can use the SetupCopyOEMInf API to

copy the provided INF file to the INF folder on the user’s system. On finding a

matching INF file, Windows copies the file to %windir%\inf (if the file isn’t

already present), loads the driver(s) specified in the file if necessary, and adds

the appropriate keys to the system registry. The device then displays in the

Device Manager.

After installing a device, when installing additional devices that are identical

except for the serial number, Windows behaves differently depending on

whether the driver is digitally signed. When the driver is signed, Windows uses

administrative privileges to install the driver for additional devices after the

first, even if the current user doesn’t have these privileges. If the driver is

unsigned, Windows uses the privileges of the current user in deciding whether

to install the driver for additional devices.

When re-attaching a previously attached device, whether Windows finds a

driver key can depend on whether the device’s descriptors include a USB serial

number string. If the device doesn’t have a serial number, Windows finds the

hardware key only if the device is re-attached to a port where the device was

attached previously. If the device has a serial number, Windows finds the hard-

ware key no matter which port the device attaches to.

243



&GVGEVKPI&GXKEGU

This chapter shows how applications can obtain information about attached

devices, request a handle for communicating with a device, and detect when a

device is attached or removed. Each of these tasks involve using Windows API

functions and the device interface GUIDs introduced in Chapter 8. Because

many .NET programmers have limited experience with API functions, I begin

with a short tutorial on the topic.

#$TKGH)WKFGVQ%CNNKPI#2+(WPEVKQPU

You can do a lot of programming without ever calling a Windows API function.

Microsoft’s .NET Framework provides classes that support common tasks

including creating user interfaces, accessing files, manipulating text and graph-

ics, accessing common peripheral types, networking, security functions, and

exception handling. Internally, a class’s methods are likely to call API functions,

but the classes offer a safer, more secure, and more modular, object-oriented

way for programmers to accomplish the tasks. Languages that can use the .NET

Framework include Visual Basic, Visual C#, and Visual C++.

Chapter 10

244

But .NET’s classes don’t handle every task. Some applications must do things

that require calling API functions. A .NET application can use .NET classes

where possible and API calls where needed.

Because calling API functions can be an obscure art at times, this section

includes an introduction to the topic.

The code examples in this chapter assume the following Imports and using

statements:

8$ Imports Microsoft.Win32.SafeHandles

Imports System.Runtime.InteropServices

Instead of Imports statements, you can provide references to the namespaces in

the project’s properties, in the References tab. A reference to the System

namespace is in the properties by default.

8% using Microsoft.Win32.SafeHandles;

using System;

using System.Runtime.InteropServices;

/CPCIGFCPF7POCPCIGF%QFG

Managed code is program code that accesses properties, methods, and events of

the .NET Framework’s classes. Managed code compiles to the Microsoft Inter-

mediate Language (MSIL). When the application runs, .NET’s common lan-

guage runtime (CLR) environment executes the MSIL code.

Because all .NET languages use the same CLR, components written in different

.NET languages can easily interoperate. For example, a Visual Basic application

can call a function written in Visual C# without worrying about differences in

calling conventions. The CLR also simplifies programming by implementing

garbage collection to manage memory. In contrast, Windows API functions are

unmanaged code whose DLLs contain compiled machine code that executes

directly on the target CPU.

A Visual C++ application can compile to managed code, unmanaged code, or a

combination. The language incorporates a technology that enables managed

code to call API functions exactly as unmanaged code does.

For other .NET languages, managed code can call API functions by using

methods of the System.Runtime.InteropServices namespace. The namespace

supports the Platform Invocation Services, also known as PInvoke and

Detecting Devices

245

P/Invoke. The process of calling unmanaged functions from managed code is

called Interop.

6JG&..U

The DLLs included with Windows are typically stored in %System-

Root%\system32. The operating system searches this folder when an application

calls a DLL function. Header files and documentation for Windows API func-

tions are in the Windows Driver Kit (WDK) and Windows Software Develop-

ment Kit (SDK):

Header files contain declarations in C for the DLLs’ functions and define con-

stants, variables, structures, and other components the functions access. The

declarations enable applications to find the functions and pass parameters to

them.

A Visual Basic or Visual C# application must translate the declarations in the

header files from C to Visual Basic or Visual C# syntax and data types. Translat-

ing from C is more complicated than simple syntax changes because many of

the variable and structure types don’t have one-to-one equivalents in .NET. The

.NET code may also requires marshaling to enable passing data between man-

aged and umanaged code.

/CTUJCNKPI

Visual Basic and Visual C# applications must take special care to ensure that

any data passed to an unmanaged function survives the trip from managed to

unmanaged code, and back if needed. The .NET Framework provides the Mar-

shal class to help. Marshaling means doing whatever is needed to make the data

available. The class provides methods for allocating memory for variables to

pass to unmanaged code, copying data between unmanaged and managed

memory, and converting between managed and unmanaged data types. For

example, the PtrToStringAuto method accepts a pointer to a string in unman-

aged memory and returns the string being pointed to. This code retrieves a

(WPEVKQP &.. &QEWOGPVCVKQP

Find devices setupapi.dll WDK under Device Installation

Access devices that support

handle-based operations

kernel32.dll SDK under File Management

Receive notifications of device

attachment and removal

user32.dll SDK under Device Management