The NT Insider 2001 Archive
| Published: 30-Jan-03| Modified: 30-Jan-03
The 411 on Driver 911: Resources for Driver Writers
Just Checking: Installing a Partially Checked Build
X-DMA: Extreme DMA for Performance
Properly Pending IRPs: IRP Handling For the Rest of Us
Tunneling: Name Tunneling in Windows 2000 File Systems
Keeping Secrets: Windows NT Security (Part III)
Property: Adding Property Pages to Device Drivers
Buddy Drivers: Methods for Driver to Driver Communication
File Systems & XP: New File Systems Material in Windows XP
The 411 on Driver 911: Resources for Driver Writers
The NT Insider, Vol 8, Issue 1, Jan-Feb 2001 | Published: 15-Feb-01| Modified: 01-Nov-02
It seems a bunch of you-all are new to the Windows NT/2K/XP driver development game. This means you probably don’t know about the main resources that are available for getting help and staying up to date on what’s happening in the field. Here’s a quick list:
Microsoft Knowledge Base – Frequently visit http://support.microsoft.com and check out recent knowledge based articles. In fact, using the MS web site, you can view all the Windows 2000® related KB articles for the past 7 or 14 days. You can also do this from he OSR web site (http://www.osr.com, and click on “Resources”) where we narrow the search down a bit to stuff that's more likely to be of interest to driver writers.
The NT Insider – Well, if you’re reading this, you’re halfway there at least.
Latest Windows DDK Docs On-Line – Go to http://www.osr.com and click on “DDK Documentation On Line”. By special arrangement with Microsoft, you can find the very latest DDK documentation on line here. Note the DDK docs we have online currently reflect both Win2K and Windows XP®. They are therefore more recent than the version in the current Win2K DDK, containing updates and corrections. Just leave it open on your desktop. That’s what the developers here at OSR do.
NTDEV – This is probably the best resource around for getting questions answered on kernel-mode development. You must be a member to participate. To join, go to http://www.osr.com, and click on “List Server”. You can access this group as either a traditional listsrv-type mailing list, or as a member-only usenet newsgroup (point your newsreader at lists.osr.com). The MS DDK support team (and folks from OSR) are members of this group, and often answer questions.
WINDBG – A very quiet list for help on everybody’s favorite debugger. Also available as a member-only newsgroup. Sign up from http://www.osr.com, and click on “List Server”. The WinDbg dev team answers questions here when they have time.
NTFSD – The definitive group for file systems help. Also accessible as a member-only newsgroup. Sign up from http://www.osr.com, and click on “List Server”. MS FS devs are regular contributors here.
comp.os.ms-windows.programmer.nt.kernel-mode – Usenet news group, similar to the NTDEV list mentioned above. Not available as a listsrv type mailing list. Very broad participation.
http://www.microsoft.com/ddk – Download the latest DDK. Get the latest news/
happenings in DDK-land.
http://www.microsoft.com/ddk/debugging – Get the latest version of WinDbg.
http://support.microsoft.com/support/ddk – The DDK support team’s site. This is a good place to look for pointers to KB articles, and solutions to common problems. Also, you’ll find additional DDK samples to download on these pages.
Ask Hector! – When you’re weary…feeling small. When tears are in your eyes and you’ve exhausted all other possibilities for help… We may be able to save you. Send email to OSR’s Consultant-at-Large, Hector Rodriguez, and ask him your question. Because he knows all things carnal, ooops I mean kernel, the chances of getting your toughest questions answered are very good. Just be patient: Hector travels almost all the time (aside from being OSR’s spiritual leader, he’s also a world-renowned bon-vivant and UN certified peacekeeper – We figure it gives him something to do in his spare time). Send email to . The only caveat is that Hector’s a way busy guy. It’s usually best to do your homework before asking Hector a question. He’s getting old and can be, ah, cranky, at times.
Just Checking - Installing a Partially Checked Build
The NT Insider, Vol 8, Issue 1, Jan-Feb 2001 | Published: 15-Feb-01| Modified: 08-Jan-02
The checked build of the operating system has lots of additional cross-checks, what we at OSR call “reasonableness checks”, that are performed on operating system data structures and function call arguments passed from drivers. No driver has been sufficiently tested for release until it run on the checked build without displaying obvious problems. In addition, the checked build can be invaluable in assisting driver developers in identifying and locating difficult-to-find problems.
Of course, there are a few issues with running the checked build of the operating system. One of the biggest issues is that the checked build is both larger and slower than the free build. Another issue is that to install the entire operating system checked build, you must maintain a completely separate operating system installation. This means you have to keep things (like registry parameters and versions of the driver being tested) in-synch between the free and checked installations on your system. This can get annoying, in fact.
One solution to these problems is to install just part of the checked build. In this article, we describe how to install just a checked operating system image and checked HAL. See the upcoming release of the Windows DDK for more information on using the checked build.
Partial Checked Installation
An alternative to installing the complete checked build on the target system is to manually install only the checked versions of the operating system image and HAL. This procedure will result in an additional boot option that lets you start the system using just the checked operating system image and HAL, but the free versions of all other system components.
One advantage to this approach, as opposed to installing the complete checked build, is that drivers get the benefit of the operating system and HAL debug cross-checks while performance impact on the entire system is minimized (due to the fact that free versions of system components other than the operating system image and HAL are being used). Another advantage of installing only the checked operating system image and HAL is that this allows a single installation (and thus one system directory, one set of executable components, and one set of registry parameters) to utilize either the checked or the free versions of the operating system image and HAL as determined at boot time.
Installing a Checked OS Image and HAL
Installing the checked versions of the operating system image and HAL involves copying the appropriate files from the checked distribution kit to new, unique, file names in the %systemroot%\system32\ directory. There are two important guidelines to keep in mind when installing checked operating system and HAL images on an otherwise free installation:
1. The operating system image and HAL must be kept in synch at all times. Therefore, if a checked version of the operating system image is used, the checked version of the HAL must be also be used (and vice versa). Failure to keep the operating system image and HAL in synch can result in rendering the system on which they are installed unbootable.
2. Take special care not to overwrite the free versions of the operating system image and the HAL that are installed by default in the installation of the free build. Overwriting the free versions of the operating system image and HAL can result in the system becoming unbootable, and can make it difficult to recover from errors. Therefore, always be careful to copy the checked versions of the operating system image and HAL to unique files names in the %systemroot%\system32 directory.
As long as you keep the above guidelines in mind (and edit carefully!) installing the checked versions of the operating system image and HAL is easy. Now we continue in further detail.
Step 1: Identifying the Files to Install
There are several different versions of the operating system and HAL images supplied as part of the Windows XP distribution kit. These different versions exist to properly support specific combinations of processor and system hardware. When Windows XP is installed, the installation procedure automatically identifies which operating system image and HAL image to use, and copies the appropriate files to the %systemroot%\system32 directory of the system being installed.
The original names of the operating system image files as stored on the distribution media may include one or more of the following,:
NTOSKRNL.EXE - Uniprocessor IA32 architecture systems with 4GB of physical memory or less.
NTKRNLPA.EXE - Uniprocessor IA32 architecture systems with PAE support, that is, more than 4GB of physical memory installed.
NTKRNLMP.EXE - Multiprocessor IA32 architecture systems with 4GB of physical memory or less.
NTKRPAMP.EXE - Multiprocessor IA32 architecture systems with PAE support, that is, more than 4GB of physical memory.
When copied to the %systemroot%\system32\ directory by the Windows XP installation procedure, the operating system image files and HAL use fixed, well known, names. This makes it easy for the loader to locate these files at boot time. The well-known names for these files are:
NTOSKRNL.EXE - Operating system image for IA32 systems with 4GB or less of physical memory;
NTKRNLPA.EXE - Operating system image for IA32 systems with more than 4GB of physical memory.
HAL.DLL - Loadable HAL image.
During system installation, the installation procedure creates each of these files by copying the file appropriate for the system’s hardware from the distribution kit, and renaming it from its original name to one of the fixed names above.
The first step in installing the checked operating system image and HAL is to determine the original names of the images that were copied to your system during system installation. You do this by examining the file %systemroot%\repair\setup.log. An example of this file is shown in Figure 1. This file is used during the system installation process to copy files from the distribution medium to the %systemroot%\system32 directory.
Again, regardless of which of the above files is installed, the non-PAE operating system image file is always called NTOSKRNL.EXE and the PAE operating system image file is always called NTKRNLPA.EXE when they are copied to the %systemroot%\System32\ directory. You can identify which operating system image files were installed on your system by searching setup.log for the above file names. Make a note of which operating system image files are used on your system, because you will need to copy the checked versions of these same files from the checked distribution kit. You will find the standard, well known, name of the operating system image file on the left of the equals sign, and it’s original name from the distribution medium immediately to the right of the equals sign on the same line.
In the example setup.log file shown in Figure 1 you can see that two operating system image files were copied to the \winnt\system32\ directory (which is %systemroot%\System32\) during installation. The file ntkrpamp.exe is copied from the distribution medium to ntkrnlpa.exe and the file ntkrnlmp.exe is copied from the distribution medium to ntoskrnl.exe.
[Paths]
TargetDirectory = "\WINNT"
TargetDevice = "\Device\Harddisk0\Partition1"
SystemPartitionDirectory = "\"
SystemPartition = "\Device\Harddisk0\Partition1"
[Signature]
Version = "WinNt5.1"
[Files.SystemPartition]
NTDETECT.COM = "NTDETECT.COM","f41f"
ntldr = "ntldr","3e8b5"
arcsetup.exe = "arcsetup.exe","379db"
arcldr.exe = "arcldr.exe","2eca9"
[Files.WinNt]
\WINNT\system32\drivers\kbdclass.sys = "kbdclass.sys","e259"
\WINNT\system32\drivers\mouclass.sys = "mouclass.sys","7e78"
\WINNT\system32\drivers\uhcd.sys = "uhcd.sys","10217"
\WINNT\system32\drivers\usbd.sys = "usbd.sys","5465"
(…several similar lines omitted…)
\WINNT\system32\framebuf.dll = "framebuf.dll","10c84"
\WINNT\system32\hal.dll = "halmacpi.dll","2bedf"
\WINNT\system32\ntkrnlpa.exe = "ntkrpamp.exe","1d66a6"
\WINNT\system32\ntoskrnl.exe = "ntkrnlmp.exe","1ce5c5"
\WINNT\inf\mdmrpci.inf = "mdmrpci.inf","96a3"
Figure 1 — Example of %systemroot%\repair\setup.log
Like the file for the operating system image, the file containing the HAL in the %systemroot%\system32 directory is always named hal.dll. And, again like the operating system image, because the HAL varies with the hardware platform on which Windows XP is installed, the HAL file may have been renamed during the installation process. To find the original name of the HAL file, examine setup.log just as you did for the operating system image file. You will see the file name hal.dll on the left of the equals sign, and the original file name on the right of the equals sign on the same line. For example, in Figure 1 you will see that the hal.dll installed on this system was originally named halmacpi.dll. Carefully make note of the original name of the HAL file.
Warning!
Some HAL files have deceptively similar names. For example, halacpi.dll and halapic.dll are two commonly used HALs. Be careful to use the correct version of the HAL for your system. Selecting the wrong HAL will result in a system that is not bootable.
Once you have identified which operating system image and HAL files are installed on your machine, you’re ready to copy the checked versions of these files to the %systemroot%\system32\ directory.
Step 2: Copying the Checked Files
Now that you know which files to copy, you will need to copy the checked versions of these files to unique file names in the %systemroot%\system32\ directory. Find the files you have identified in the checked distribution kit. Then copy these files to the %systemroot%\system32\ directory of your system, giving them new, unique, file names. The copies of these files may be named just about anything you like, however the file names must adhere to the 8.3 naming convention. One way to ensure unique, 8.3-compliant, file names is to rename the file types from their original file types (.dll or .exe) to .chk when they are copied. Thus, using the example started previously, we would copy files from the checked distribution kit as follows:
Original File Name on Checked Distribution / File Name Copied to in%systemroot%\system32\
Ntkrnlmp.exe / ntkrnlmp.chk
ntkrpamp.exe / ntkrpamp.chk
halmapic.dll / halmapic.chk
Some files in the checked distribution are provided in compressed form. These files are indicated with an underscore character as the last character in their file type. For example, if you look for the file halapic.dll in the checked build distribution, but you find the file halapic.dl_ you have found the correct file but it is compressed.
To decompress compressed files from the checked distribution, use the expand utility found in the %systemroot%\system32\ directory. For example, to expand halapic.dl_ and name the expanded file halapic.chk you can use the following command from a command prompt window: