Testing the Driver

< BACK  NEXT >

[oR]

Even though the Minimal driver is far from being useful, its operation can be verified in several ways. In particular, it can be tested to ensure that it

• Compiles and links successfully

• Loads and unloads without crashing the system

• Creates device objects and Win32 symbolic links

• Releases any resources when it unloads

While these goals may not seem very ambitious, they are an important milestone in beginning the construction of the rest of a truly useful driver.

Testing Procedure

While a description of the production-level installation of the device driver must be left until chapter 16, a manual installation of the Minimal driver can be performed now. The disk accompanying this book includes a useful tool that makes this job much easier.

Visual C++ Device Driver AppWizard

In the Tools folder of the accompanying disk, there is a file called DDAppWiz.awx. This file is the result of building a custom AppWizard project for Visual C++. When properly installed, it allows the creation of the new project that sets up the Visual C++ environment for Windows 2000 device driver development. For example, it modifies the linker settings to specify the -driver switch. It supplies the correct list of DDK libraries to the linker. It specifies the required load address of 0x10000. In short, it makes the construction of the Windows 2000 device driver project about as simple as starting an MFC application.

To install this AppWizard, it is necessary to copy DDAppWiz.awx into the appropriate Visual Studio directory. The exact location varies based on the installation directory chosen for Visual Studio. Typically, the correct target directory for the AppWizard file is \Program Files\Microsoft Visual Studio\Common\MSDev98\Template. The correct directory can be confirmed by examining a file called Readme.txt in the target. Once the file is correctly copied, selecting File, then New, and then Project should reveal a new option for Windows 2000 device driver development.

Indeed, a Developer Studio Project and Workspace environment is supplied in the chapter 6 folder of the disk. The Minimal.dsw workspace can be opened directly and the build attempted. The example code listed in this chapter is already included in this project.

The Windows 2000 DDK

The Windows 2000 Device Driver Kit must be installed on a development system in order to build device drivers. As mentioned in chapter 1, the DDK is available for download from the Microsoft.com site. By default, it installs into a folder named NTDDK. If another folder name is chosen during installation of the DDK, the Project settings supplied by the device driver AppWizard must be modified.

The DDK allows for two different build environments, checked and free. The checked build environment is analogous to the Debug build environment of Visual C++, while the free build environment is analogous to the Release setting. As such, two different sets of libraries are supplied with the DDK, Libfre and Libchk. For the initial build of the Minimal project, it is suggested that a checked build be performed. This is easily done by selecting the Debug project target.

Results of the Driver Build

Once a driver is successfully built, a file ending with a .SYS extension is created. In the case of the Minimal driver, the file is called Minimal.SYS. This file must be copied to the appropriate Windows directory before it can be loaded. The target directory is typically \WINNT\System32\Drivers. The WINNT portion of the name varies based on the name selected during the Windows 2000 installation.

The project settings supplied by the AppWizard include a post-build step, which copies the driver to the appropriate directory. It is important to keep the results of each build in sync with the Drivers directory.

Installing a Kernel-Mode Driver Manually

Merely copying the driver file to its target directory is not enough to complete the installation of the new device driver. For non-WDM drivers, appropriate entries must be made into the system Registry before the driver can be loaded.

A list of available device drivers is kept in the Registry path HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services. Each driver is listed with a separate subkey whose name must be the same as the Driver.SYS file, without the .SYS extension.

For each driver subkey, three Registry DWORD values must be supplied: ErrorControl, Start, and Type. These entries describe when the driver is loaded (e.g., boot or on-demand), how it reports errors (e.g., MsgBox), and a very generic description of the type of driver (kernel-mode or file system). For the Minimal driver, it is suggested that the values be set as follows:

ErrorControl = 1

Start = 3

Type = 1

Optionally, a DisplayName value can be set, which is the name shown in the Computer Management Console window when using its Device Manager.

A file, Minimal.reg, sets the subkey name and values automatically. Simply double-click the filename from Windows Explorer. A reboot of Windows 2000 is necessary after adding a new device driver using this method. Once the Registry entries have been established, however, the driver can be replaced at will without need of further reboots.

Loading the Driver

Once the driver is known to the system, it may or may not start automatically when the system boots. The Start value in the driver's Registry key specifies this behavior. A Start value of 3 specifies demand-loading for a driver. With versions of NT prior to Windows 2000, the Control Panel could be used to start and stop on-demand drivers. With the advance of WDM drivers, Windows 2000 has delegated this task to the Computer Management Console which can be activated from Control Panel.

The dynamic loading of device drivers is largely handled by a system component known as the Service Control Manager (SCM). The SCM pro- vides many services for software components that run under Windows 2000. For example, it starts, stops, and controls services. A service is a process that runs outside the context of a logged-on user. It is analogous to a Unix daemon.

A Control Panel applet supplied with NT 4 was a simple front-end for the SCM. In Windows 2000 it has been replaced with a Device Manager group of the Computer Management Console plug-in (part of the Microsoft Management Console (MMC) initiative). The Computer Management tool provides useful information for loaded device drivers and a (somewhat) hidden mechanism to manually load and unload kernel-mode drivers such as Minimal.

The CD included with this book includes a simple tool, DriverControl.exe in the CD's Tools folder. This utility registers a legacy driver with the SCM. It must be used before the Computer Management Console can recognize the new driver. Simply type the name of the driver (e.g., Minimal) into the Driver Name box and click Start.

Windows 2000 Computer Management Console

Once the Minimal driver has been successfully built and copied to the Drivers directory, the new Computer Management Console can be used to verify the presence of the driver. To use the standard tool, click Start, Settings, then Control Panel, and then choose the Computer Management option. A familiar navigation pane is displayed on the left that includes a list of System Tools. One of these tools is the Device Manager. Expanding its group allows the display of the list of devices currently installed for the system. To see devices that are not Plug and Play compatible, right-click the Devices group, choose View, and select Show hidden devices. The Minimal driver should appear in the non-WDM drivers of the right pane. See Figure 6.2 for a display showing the DisplayName for the Minimal driver.

Figure 6.2. Computer Management Console.

By double-clicking the appropriate DisplayName and then selecting the Driver tab, the Minimal driver can be started and stopped. See Figure 6.3.

Figure 6.3. Starting and stopping a device driver.

Additionally, the System Information group beneath the System Tools group can be used to display information about the Minimal driver. Expand System Information, then select Drivers.

The WINOBJ Utility

WINOBJ is a utility that is supplied with the Win32 Platform SDK (not with the DDK). This tool allows the user to view the internal namespace of the Windows 2000 Object Manager. For device driver authors, WINOBJ is useful because it displays the contents of the Drivers, Devices, and ?? directories.

WINOBJ has not been a well-supported utility by Microsoft. It still contains many quirks that have been present for many versions of Windows NT. A much-improved version of WINOBJ is supplied at the site http://www.sysinternals.com. The improved version of WINOBJ, available at the site, works well with Windows 2000. The site also contains many useful utilities for device driver authors. A sample screen of WINOBJ with two Minimal devices (MIN1 and MIN2) is shown in Figure 6.4.

Figure 6.4. WINOBJ from http://www.sysinternals.com.

Using WINOBJ, a properly installed version of the Minimal driver should reveal the name Minimal0 under the Device directory, the name Min1 under the ?? directory, and the driver name Minimal under the Driver directory. When the driver is stopped, the names Minimal0 and Min1 should disappear. Do not forget to refresh the view of these directories.

< BACK  NEXT >