context levels for device drivers, device context and open context, which the operating system passes in each appropriate function call to the driver so that the driver can associate internal resources and allocated memory regions with each caller.
The stream interface consists of 12 functions: XXX_Init, XXX_Open, XXX_Read, XXX_Write, XXX_Seek, XXX_IOControl, XXX_PowerUp, XXX_PowerDown, XXX_PreClose, XXX_Close, XXX_PreDeinit, and XXX_Deinit. Not all functions are mandatory (such as XXX_PreClose and XXX_PreDeinit), yet any functions that the stream device driver implements must be exposed from the driver DLL to Device Manager. To export these functions, you must define them in the .def file of the DLL subproject. You should also adjust the DLL subproject's Sources file to ensure that the driver DLL can make platform-dependent function calls.
Lesson 3: Configuring and Loading a Driver
In general, you have two options to load a stream driver under Windows Embedded CE 6.0. You can instruct Device Manager to load the driver automatically during the boot sequence by configuring driver settings in the HKEY_LOCAL_MACHINEDriversBuiltIn registry key, or you can load the driver dynamically through a direct call to ActivateDeviceEx. Either way, Device Manager can load the device driver with the same registry flags and settings. The key difference is that you receive a handle to the driver when using ActivateDeviceEx, which you can use later in a call to DeactivateDevice. Especially during the development stage, it might be advantageous to load a driver dynamically through ActivateDeviceEx so that you can unload the driver, install an updated version, and then reload the driver without having to restart the operating system. You can also use DeactivateDevice to unload drivers loaded automatically based on entries under the BuiltIn registry key, but you cannot reload them without calling ActivateDeviceEx directly.
After this lesson, you will be able to:
¦ Identify the mandatory registry settings for a device driver.
¦ Access the registry settings from within a driver.
¦ Load a driver at startup or on demand in an application.
¦ Load a driver in user space or kernel space.
Estimated lesson time: 25 minutes.
Device Driver Load Procedure
Whether you load a device driver statically or dynamically, the ActivateDeviceEx function is always involved. A dedicated driver named the Bus Enumerator (BusEnum) calls ActivateDeviceEx for every driver registered under HKEY_LOCAL_MACHINEDriversBuiltIn just as you can call ActivateDeviceEx directly, passing in an alternate registry path for the driver settings in the lpszDevKey parameter.
Device Manager uses the following procedure to load device drivers at boot time:
1. Device Manager reads the HKEY_LOCAL_MACHINEDriversRootKey entry to determine the location of the device driver entries in the registry. The default value of the RootKey entry is DriversBuiltIn.
2. Device Manager reads the Dll registry value at the location specified in the RootKey location (HKEY_LOCAL_MACHINEDriversBuiltIn) to determine the enumerator DLL to load. By default, this is the bus enumerator (BusEnum.dll). The bus enumerator is a stream driver that exports the Init and Deinit functions.
3. The bus enumerator runs at startup to scan the RootKey registry location for subkeys that refer to additional buses and devices. It can be run again later with a different RootKey to load more drivers. The bus enumerator examines the Order value in each subkey to determine the load order.
4. Starting with the lowest Order values, the bus enumerator iterates through the subkeys and calls ActivateDeviceEx passing in the current driver's registry path (that is, HKEY_LOCAL_MACHINEDriversBuiltIn <
5. ActivateDeviceEx loads the driver DLL registered in the DLL value located in the driver's subkey, and then creates a subkey for the driver under the HKEY_LOCAL_MACHINEDriversActive registry key to keep track of all currently loaded drivers.
Figure 6-4 shows a typical registration under the HKEY_LOCAL_MACHINEDriversBuiltIn registry key for an audio device driver.
Figure 6-4 An audio device driver registration
Registry Settings to Load Device Drivers
If you use ActivateDeviceEx to load your driver dynamically, you are not required to place the driver's registry settings in a subkey under HKEY_LOCAL_MACHINEDriversBuiltIn. You can use an arbitrary path, such as HKEY_LOCAL_MACHINESampleDriver. However, the registry values for the driver are the same in both cases. Table 6-3 lists general registry entries that you can specify for a device driver in the driver's registry subkey (see Figure 6-4 for sample values).
Table 6-3 General registry entries for device drivers
| Registry Entry | Type | Description |
|---|---|---|
| Prefix | REG_SZ | A string value that contains the driver's three-letter name. This is the value that replaces XXX in the stream interface functions. Applications also use this prefix to open a context of the driver through CreateFile. |
| Dll | REG_SZ | This is the name of the DLL that Device Manager loads to load the driver. Note that this is the only mandatory registry entry for a driver. |
| Index | REG_DWORD | This is the number appended to the driver prefix to create the driver's file name. For example, if this value is 1, applications can access this driver through a call to CreateFile(L'XXX1:'…) or |
