Chris Cant - Writing Windows WDM Device Drivers

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 HKLM\System\CurrentControlSet\Services\Class\Unknown\0000. 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 HKLM\System\CurrentControlSet\Services\Wdm1).

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 HKLM\Enum\Root\Unknown\0000, with 0000 changed to a different Unknown device number, if appropriate. In Windows 2000, the device registry key is HKLM\System\CurrentControlSet\Control\Class\{4D36E97E…}\0000, 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 HKLM\System\CurrentControlSet\Control\DeviceClasses\{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 HKLM\Software\Microsoft\Windows\CurrentVersion\Setup\SetupX\INF\OEM Name key has a value C:\W98\INF\OTHER\WDM 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

You can create a single INF file that handles all the necessary details for the different Windows 2000 platforms and Windows 98.

The Version section Signature entry value is not used to determine the supported platforms. Instead, each platform has a different install section indicating what to do for that platform. The sections have a common base name, with additional "decoration" characters at the end of the section name to indicate the platform. If there are no section platform variants, the basic section covers all W2000 platforms and W98.

If there are sections with different platform variants, the following rules apply. If there is no decoration, the section covers W98. .NTx86 covers the W2000 x86 platform. .NTalpha covers the W2000 alpha platform. . NT covers all W2000 platforms. You need to supply only the relevant sections.

This install section covers all platforms:

[Abc_Install]

…

These two sections handle Windows 98 and Windows 2000 x86 cases.

[Def_Install] ; Windows 98

…

[Def_Install .NTx86]

; Windows 2000 x86 platform

…

Note that the Windows 98 setup code needs commas for all the optional values, while Windows 2000 can survive without them. For example, in the SourceDisksFiles section, each entry is documented as

filename = diskid[,[subdir][,size]]

The filename entry has two optional values. If you are going to leave these out in an INF file, make sure that you put two commas in, so that it works in Windows 98.

filename=diskid,,

The Wdm1free.INF installation file in Listing 11.1 has separate installation instructions for Windows 2000.

The base section name for the Wdm1 device installation is Wdm1.Install. As there is a section named Wdm1.Install.NTx86 present, this section's instructions are used for the Windows 2000 x86 platform.

Wdm1.Install.NTx86 has just a CopyFiles directive. The Wdm1.Files. Driver.NTx86 section lists just Wdm1.sys, as before. This time, %COPYFLG_NOSKIP% is specified in the fourth field.

This indicates that the user cannot skip this file. There is no point in skipping the driver file in a Wdm1 installation. Note how the COPYFLG_NOSKIP string is used to hide the value 2.

[Wdm1.Files.Driver.NTx86]

Wdm1.sys,,,%COPYFLG_NOSKIP%

[Strings]

COPYFLG_NOSKIP=2 ; Do not allow user to skip file

Windows 2000 Service Registry Entries

A Windows 2000 device driver needs to be installed as a service. This means creating a registry key with the same name as the driver executable in HKLM\System\CurrentControlSet\Services\.

The default installer finds the Wdm1.Install.NTx86.Services section. It first adds the relevant decoration .NTx86 and then adds .Services. This section lists the services that must be added. The service is called Wdm1. The %SPSVCINST_ASSOCSERVICE% value means that the service is associated with a device. The final field says that the Wdm1.Service section has the service registry details.

[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%\System32\Drivers\Wdm1.sys

A Windows 2000 service key must have ServiceType, StartType, ErrorControl, and ServiceBinary entries. These eventually appear as Type, Start, ErrorControl, and ImagePath registry entries, respectively. A DisplayName value and registry entry are usually added, as well.

The ServiceType entry must be %SERVICE_KERNEL_DRIVER% (1) for a kernel mode driver. Various other bits can be set such as %SERVICE_FILE_SYSTEM_DRIVER% (2).