16.8.5 Using the RegistryPath Parameters

NT drivers for some types of devices must rely entirely on the value entries under \..\Machine\System\CurrentControlSet\Services\DriverName\Parameters at RegistryPath (see Figure 16.6) when they are loaded because their calls to IoQueryDeviceDescription (see Section 16.8.2.1) do not provide sufficient hardware configuration information, because HalGetBusDataByOffset or HalGetBusData cannot return sufficient information (particularly for ISA-type buses), or because the device itself does not supply everything the driver needs to initialize itself and to claim hardware resources in the registry, as described in Section 16.8.3.

Relying on a system administrator or end user to set up necessary subkeys and/or value entries under \DriverName\Parameters can present the driver writer with challenges, such as the following:

• A system administrator or user who sets up value entries for one or more subkeys under the driver’s Parameters key can supply an entirely arbitrary subkey name from the driver writer’s point of view.

• User-supplied value entries under Parameters subkeys can specify a user-assigned name for the corresponding device, so the driver must create a symbolic link between the generic NT name of its device object and the corresponding user-assigned name, as described in Section 16.9.

• Any driver that has no limit on the number of devices of a particular type it can support must create an undefined number of named device objects and, possibly, symbolic links for user-assigned names in any particular machine.

Such a driver can use the registry when it initializes to determine how many devices it must support, find any user-supplied Parameters subkey value entries (possibly under user-chosen names for the subkeys) for particular devices, supply default hardware configuration value entries if necessary, and to find any user-assigned Win32-visible name(s) for its device(s).

To do this, an NT driver can call the following general sequence of support routines:

1. Call ZwOpenKey to get a handle for the Parameters subkey, using the RegistryPath pointer, shown in Figure 16.6.

2. Call ZwEnumerateKey with the handle to determine how many logical (such as parallel or serial ports) or physical devices the driver supports in the machine. This routine can be called repeatedly until it returns STATUS_NO_MORE_ENTRIES, thereby determining a count of subkeys and returning KEY_BASIC_INFORMATION about each subkey. The returned information includes the name of the subkey so the driver can supply the required key name parameter to RtlQueryRegistryValues.

3. With each named subkey, call RtlQueryRegistryValues to find any user-supplied hardware configuration values for the device and to find any user-assigned Win32 name for the device. If a subkey has no value entry except its name, the driver can supply default hardware configuration value entries for that subkey.

4. Call ZwClose with the handle, obtained in Step 1, when the driver has consumed the information available in the Parameters subkeys.

5. After the driver has successfully claimed hardware resources and initialized its physical device(s), the driver must set up a symbolic link between any user-assigned Win32 subsystem name or driver-determined default name for each Win32-visible device and the corresponding NT device object name, as described in Section 16.9.

6. After the driver has created any necessary symbolic links, call ZwOpenKey to get a handle for the device-type specific DriverClassName subkey (or ..\Other) under the DeviceMap (see Section 16.8.3) and call RtlWriteRegistryValue to set up aliased names under the driver’s DeviceMap subkey(s).

7. Call ZwClose to release the handle(s) of the DeviceMap\DriverClassName subkey(s).

Note that driver-supplied configuration information under the key \Registry\Machine\Hardware\DeviceMap, shown in Figure 16.6, about the NT names of driver-created device objects can be useful both to higher-level drivers and to anyone who uses regedt32 to modify or create Win32-visible names for add-on devices in a Windows NT machine.

Any NT driver that has an Unload routine is responsible for releasing the symbolic links it has created as described in Section 16.9 and for “erasing” the aliased names it wrote into the registry (see Step 6), as well as for freeing any resources it claimed in the registry, as described in Section 16.8.3. For more information about the Unload routine, see also Chapters 4 and 15.

Note also that NT drivers of floppy and CD-ROM devices from which the system itself can be loaded must set up a symbolic link between the system-defined ARC name for the device and the NT device object name. For more information about this requirement for NT floppy and CD-ROM device drivers, see also Section 16.9.2.