Книга: Writing Windows WDM Device Drivers

INF File Section Hierarchy

INF File Section Hierarchy

The sections in an INF file are arranged in a hierarchy. Table 11.2 shows that the Version, Strings, SourceDisksNames, SourceDisksFiles, and DestinationDirs sections are at the top level.

The Manufacturer section has a list of manufacturers (i.e., a list of manufacturer names and their section names). Table 11.2 has two manufacturers, Abc Inc and Xyz Ltd. Each manufacturer has a section that lists the product models that this INF file describes. Each product model defines various IDs and an installation section base name.

The Models section for Abc, Inc. is called Abc.Inc. This section has entries for each product that it sells. The entry for Product1 specifies that the Product1.Install section contains the main installation instructions. In this case, an optional Product1.Install.Services section has also been included. More optional install sections can be included.

The Product1.Install section has entries that point to yet more sections. The Product1.CopyFiles section lists the files to copy. The Product1.AddReg section lists the entries that must be made in the registry. Further sections at this level can be added for other installation options.

The Product1.Install.Services section is only used in Windows 2000 to specify a service entry.

Table 11.2 INF file section hierarchy

[Version]
[Strings]
[SourceDisksNames]
[SourceDisksFiles]
[DestinationDirs]
[Manufacturer]
Abc, Inc.=Abc.Inc
Xyz Ltd=Xyz.Ltd
 [Abc.Inc]
 Product 1=Product1.Install.HardwareId
 Product 2=Product2.Install.HardwareId
  [Product1.Install]
  CopyFiles=Product1.CopyFiles
  AddReg=Product1.AddReg
  [Product1.CopyFiles]
  …
  [Product1.AddReg]
  …
 [Product1.Install.Services]
 AddService=Product1,0x00000002,Product1.Service
  [Product1.Service]
 …
 [Product2.Install]
  …
 …
 [Xyz.Ltd]
  …

The quickest way to explain how an INF file works is to use a real example. Listing 11.1 shows the INF file for the Wdm1 driver, Wdm1free.Inf.

It kicks off with a Version section, which says that all the drivers and devices installed by this INF file belong to the Unknown device class. The Provider entry is set to %WDMBook%. The Strings section at the end replaces %WDMBook% with its full name, WDM Book.

The SourceDisksNames section lists the installation disks. The first and only disk is labelled "Wdm1 build directory." The SourceDisksFiles section covers W98 and specifies that the only driver file, Wdm1.sys, is found on installation disk 1 and is found in subdirectory obji386free. These options make it easy to install the Wdm1 driver directly from its development location. For a commercial release, it is simpler to put the driver files in the root directory. The SourceDisksFiles.x86 section covers W2000 and specifies that Wdm1.sys is found in the objfrei386 subdirectory.

The Manufacturer section lists just one manufacturer, again called WDM Book. There is just one product model defined here in the WDM.Book section. The Wdm1 model name %Wdm1% is the one that is shown to the user, "WDM Book: Wdm1 Example, free build". The %Wdm1% model has a Hardware ID of *wdmBookWdml. Hardware IDs are covered later.

The Wdm1.Install section has the instructions for installing the Wdm1 driver in Windows 98. The files to copy are listed in the Wdm1.Files.Driver section and the registry entries are listed in the Wdm1.AddReg section.

Legacy non-Plug and Play devices may also have LogConfig sections to specify the resources that a device needs. See Chapter 15 for an example of this.

The Wdm1.Files.Driver section simply lists the files that must be installed. The DestinationDirs section specifies where the files listed in the Wdm1.Files.Driver section should go.

The Wdm1.AddReg section specifies that two registry entries should be created for the driver, DevLoader with *ntkern and NTMPDriver with Wdm1.sys. These entries are described in detail later.

That wraps it up for a Windows 98 installation. I shall look at the remaining Windows 2000 sections later.

Listing 11.1 Wdm1free.inf

; Wdm1free.Inf – install information file
; Copyright © 1998,1999 Chris Cant, PHD Computer Consultants Ltd
[Version]
Signature="$Chicago$"
Class=Unknown
Provider=%WDMBook%
DriverVer=04/26/1999,1.0.6.0
[Manufacturer]
%WDMBook% = WDM.Book
[WDM.Book]
%Wdm1%=Wdm1.Install, *wdmBookWdm1
[DestinationDirs]
Wdm1.Files.Driver=10,System32Drivers
Wdm1.Files.Driver.NTx86=10,System32Drivers
[SourceDisksNames]
1="Wdml build directory",,,
[SourceDisksFiles]
Wdm1.sys=1,obji386free
[SourceDisksFiles.x86]
Wdm1.sys=1,objfrei386
; Windows 98
[Wdm1.Install]
CopyFiles=Wdm1.Files.Driver
AddReg=Wdm1.AddReg
[Wdm1.AddReg]
HKR,,DevLoader,,*ntkern
HKR,,NTMPDriver,,Wdm1.sys
[Wdm1.Files.Driver]
Wdm1.sys
; Windows 2000
[Wdm1.Install.NTx86]
CopyFiles=Wdm1.Files.Driver.NTx86
[Wdm1.Files.Driver.NTx86]
Wdm1.sys,,,%COPYFLG_NOSKIP%
[Wdm1.Install.NTx86.Services]
AddService = Wdm1, %SPSVCINST_ASSOCSERVICE%, Wdm1.Service
[Wdm1.Service]
DisplayName = %Wdm1.ServiceName%
ServiceType = %SERVICE_KERNEL_DRIVER%
StartType = %SERVICE_DEMAND_START%
ErrorControl = %SERVICE_ERROR_NORMAL%
ServiceBinary = %10%System32DriversWdm1.sys
; Strings
[Strings]
WDMBook="WDM Book"
Wdm1="WDM Book: Wdm1 Example, free build"
Wdm1.ServiceName="WDM Book Wdm1 Driver"
SPSVCINST_ASSOCSERVICE=0x00000002 ; Driver service is associated with device being installed
COPYFLG_NOSKIP=2 ; Do not allow user to skip file
SERVICE_KERNEL_DRIVER=1
SERVICE_AUTO_START=2
SERVICE_DEMAND_START=3
SERVICE_ERROR_NORMAL=1

DestinationDirs Section

Each line in the DestinationDirs section specifies the base directory for files listed in a CopyFiles section.

The W2000 DDK lists the directory codes. For Windows 2000, code 12 means System32 drivers in the Windows directory, but in Windows 98, it means System32ioSubsys. However, WDM drivers must be installed in the Windows System32drivers directory in both versions of Windows. Therefore, code 10 (for the Windows directory) must be used, with System32Drivers specified as a subdirectory.

The Wdm1.Files.Driver entry is therefore set to 10,System32Drivers, where 10 is code for the Windows directory (e.g., C:Windows or C:WINNT). The second field is the subdirectory to add to this base directory. Therefore, the Wdm1 driver files are stored in the Windows System32Drivers directory.

AddReg Section

An AddReg section specifies what entries to add to the registry. Each line specifies an entry of the form:

reg_root,[subkey],[value_entry_name],[flags],[value]

reg_root specifies the root registry key, from the list in Table 11.3. The optional subkey field specifies a subkey off the root key. value_entry_name is the entry name to add, flags indicates the entry type, and value is its value, flags can be omitted for REG_SZ values.

Table 11.3 Possible AddReg reg_root values

HKR is the most useful root registry key. It specifies the "relevant" registry entry for the section in which it appears. In the case of the Wdm1.AddReg section, it is the driver key. In Windows 98 for the Wdm1 driver, this key is HKLMSystemCurrentControlSetServicesClassUnknown000. The 0000 will be replaced with the appropriate Unknown device number.

For the Wdm1.AddReg section, the default installer consequently adds DevLoader and NTMP-Driver values to this key. The DDK does not state why these particular entries are necessary; just do it. This driver key ends up with other values, as you can see if you inspect it using RegEdit.

In this INF file, Windows 2000 does not use the Wdm1.AddReg section. Instead, as I shall show, the Wdm1.Service section makes some different registry entries for the driver (in HKLMSystemCurrentControlSetServicesWdm1).

Other Registry Entries

The installation process also creates various entries for the Wdm1 device that was just installed. The INF file does not have to alter or add to these entries.

In Windows 98, the device has a registry key at HKLMEnumRootUnknown000, with 0000 changed to a different Unknown device number, if appropriate. In Windows 2000, the device registry key is HKLMSystemCurrentControlSetControlClass{4D36E97E…}000, where {4D36E97E… } is the GUID for Unknown type devices.

When the Wdm1 driver runs, it also registers its device interface with GUID {C0CF0640-5F6E-11d2-B677-00C0DFE4C1F3}, WDM1_GUID. In both Windows 98 and Windows 2000, the registry key for this is HKLMSystemCurrentControlSetControlDeviceClasses{C0CF0640…}. There are various subkeys for each device and their associated symbolic links.

Windows 98 remembers that the INF file has been installed in the registry. The HKLMSoftwareMicrosoftWindowsCurrentVersionSetupSetupXINFOEM Name key has a value C:W98INFOTHERWDM BookWDM1.INF set to "WDM BookWDM1.INF". This entry is not deleted if you remove the Wdm1 device.

The InfEdit program in the Windows 98 DDK can be used to edit simple INF files. InfEdit does not display its main menu in Windows 2000 and is, therefore, unusable there.

As Figure 11.1 shows, InfEdit displays the section names as folders in a tree in its left-hand pane. The entries in each section are shown in the right-hand pane. InfEdit lists all the possible section names and entries. Or, at least, all the ones that were possible when the program was written.

The InfEdit program has some distinct drawbacks, so I would advise against its use. I asked it to read the Wdm1Free.INF file. When it wrote the file out again, it had lost the SourceDisksNames subdirectory information. All the strings were replaced with new unhelpful names. It displayed all the Windows 2000 specific sections in a Miscellaneous Sections category. Worse, it did not recognize the strings within these sections and deleted them from the Strings section.

Figure 11.1 InfEdit program

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