Microsoft provides support for installing third party drivers that are not part of the Windows distribution at Windows Setup. Unfortunately, the documentation on this area is limited and scattered across many sources from Microsoft, so adding and debugging a driver for setup can be a major learning experience. This article brings together the information and procedures for installing drivers at Windows Setup and shows techniques needed to debug some of the problems when things go wrong.

First, remember that installation is not the place for debugging normal driver issues. Before trying to debug a driver at Windows Setup, be sure your driver is working correctly in a normal environment, including running it under the checked build with driver verifier. Having a solid INF file for installation is critical. Run ChkInf on your INF file and be sure to fix all of the complaints from the tool.

This article will show how to install the pcidrv sample from the Windows 2003 SP1 DDK and the incomplete1 function driver from the toaster driver samples in the DDK. Only the binaries from these drivers are used. The supporting files including the INF files can be downloaded from http://www.osronline.com/article.cfm?id=264.

Throughout the article, there are places with references to the I386 directory; this should be considered a placeholder for AMD64 (Opteron) or IA64 (Itanium). Additionally, the examples have been tested only on a IA32 platform. For 64-bit systems, I have attempted to identify the known differences, but there are no guarantees made here for 64-bit.

Microsoft defines two phases of system installation: text-mode setup and GUI-mode setup. The text-mode setup is depicted by the blue screen you see when you boot a Windows Installation CD-ROM. The GUI-mode setup comes into play after the reboot when the graphical display is present and most of the questions regarding an installation appear.

There are actually pre and post operations that impact installation, and the text-mode setup operates in two distinct phases. For the purposes of this article, it is better to look at setup as the following five phases:

This phase is optional; if you start your installation from a working Windows system, you are invoking winnt32.exe. This phase copies some initial files to the systems hard drive and supports the selection of a number of options for installation.

Using winnt32.exe to install the system provides two major benefits to the developer: support for a debug log on the install and the ability to modify some of the files copied from the CD-ROM to the hard drive.

When Windows boots for installation on a system, the initial phase of the system installation is text-mode setup. This phase runs with a blue screen and simple text-mode displays, hence the name text-mode setup.

The SetupLdr portion of text-mode setup is the initial copy phase that includes the option of installing additional drivers. SetupLdr is a modified version of ntldr that allows limited user interaction to install additional drivers or a different HAL. This copy phase puts together a limited version of Windows to use in the second half of text-mode setup. In earlier versions of Windows this phase was invoked by the three boot floppies.

Part way through text-mode setup, you will see a message indicating setup is starting Windows on the last line of the screen. This limited version of Windows installs only the minimum number of devices needed for operation, such as the keyboard, mouse, video adapter, and disk. These devices are defined by the Critical Device Database. This is the phase where questions are posed about installation versus upgrade versus recovery, and creating or choosing a partition to load the system occur.

After text-mode setup has completed, the system installation reboots Windows and proceeds with the GUI-mode setup phase of the installation. This is the phase where most of the inputs such as localization, networking, and passwords are requested. Setup installs most devices during GUI-mode setup.

GUI-mode setup runs similarly to a fully functional Windows. In fact, later in the article I describe how to run Windows programs during the installation. Drivers will install at GUI-mode setup with a standard INF and driver file package unless the installation requires user mode interaction.

The final phase of installation is the initial startup of the running system. The system provides support for running installation programs at this time. These operations are described in the GUI-mode setup section later in the article.

To install a driver to run during text-mode setup, the traditional approach is to use an installation floppy containing the following files:

The drivers specified in these files should not be part of the normal system distribution; if they are, the system will ignore your drivers in favor of the standard distribution. Note that these drivers can also be installed as part of an automated installation; this is described as part of the GUI-mode setup.

Txtsetup.oem is described in the DDK documentation. Unfortunately, this area of the documentation has a number of problems. The documentation describes the installation of SCSI drivers in a way that implies only SCSI can be installed. In actuality, most drivers can be installed during text-mode setup. Additionally, the documentation does not identify the restrictions needed for an automated installation. The following is a description of the txtsetup.oem file simplified to only discuss driver installation (the file can also install HAL’s) and expanded to cover the restrictions needed to work in any installation.

Txtsetup.oem follows the Microsoft format rules for an INF file, but with only five sections. The bold text in the descriptions below are keywords, the italic text are values to be supplied.

[Disks]
disk = "description",tagfile,directory

This section describes the installation disks. This is a required section. There can be multiple disk = lines, but most txtsetup.oem files only have one disk. The parameters are below.

This section is optional and describes the default installation. If this section is not present, the first entry in the [SCSI] section described below will be the default. Note that even though this identifies the default driver for the [SCSI] section, the driver does not need to be for a SCSI device. The parameters are:

This section provides the description of a driver used to prompt the user. This is a required section. These drivers do not need to be for a SCSI device. The [SCSI] section name is a legacy from previous versions of Windows that supported txtsetup.oem installation of display, keyboard, mouse, CD-ROM, as well as SCSI and Computer (HAL and ntdetect). There can be multiple entries in this section; all the descriptions will be displayed for the user. The parameters are:

This section describes the files to copy as part of the installation. This is a required section. There can be multiple entries for each line type (driver, inf and catalog). Note I do not describe installing a DLL file since it is not valid for SCSI with automated installations. Attempts have been made to install more than one driver and INF for a given ID, however, this does not work for an automated install, and is problematic for regular floppy installation. The parameters are:

This section describes the registry entries to create as part of the installation. This section is optional. There can be multiple value lines in the section. The parameters are:

This section associates plug and play hardware identifiers with a given service and driver. The section is not required for a floppy installation, but is required to do an automated installation of the driver. Multiple id lines are permitted. The parameters are:

All of the storage miniport samples in the DDK have installation time support as part of the sample files. The samples in the DDK provide an excellent basis for most device installations at text-mode setup.

A sample txtsetup.oem is provided below:

This sample txtsetup.oem will install a driver pcidrv.sys on the system using the pcidrv.inf and pcidrv.cat files. The [Disks] section is required and identifies there is one disk called disk1, the system will verify that this is the correct disk by the file pcidrv.txt in the root. The [SCSI] section identifies that there is only one driver package pcidrv on the disk and that the user will be prompted to install the Sample WDM Driver for PCI Device.

The pcidrv.sys referenced here is from the DDK, but the pcidrv.inf is a custom INF provided with the samples for this article.

Microsoft supports automated installations, and, in fact, a number of installation schemes require automation. Before you think this is not important to you, consider that many large companies use this as their only method of installing systems.

To automate the Windows installation process, a script file known as an answer file is used. The format of the answer file, called unattend.txt is documented in files that are part of deploy.cab found in the support directory of a Windows CD-ROM. For Windows 2000 there is a file unattend.doc, for Windows XP or 2003, two files, deploy.chm and ref.chm, contain the documentation. A complete discussion of the answer file is beyond the scope of this article. There is a tool, setupmgr.exe, in the deploy.cab to create a basic file for you. Running this tool will prompt you with many of the questions for installation and then create an answer file.

To automate an installation where you wish to add drivers, either at text-mode or GUI-mode time, the installation process is required to be fully automated. Running setupmgr will produce a file such as:

There are a couple of things to note on the above:

Before doing anything further with an automated installation, test that your file works. Take the answer file produced by setupmgr and rename it to winnt.sif. Put this file on a floppy and boot the system with the Windows installation CD, with the floppy with winnt.sif in the A: drive. Your system should install correctly.

To automate the installation of drivers, you need to create a custom CD-ROM. Note that there are advanced deployment methods such as a network installation that will also work, but are beyond the scope of the article and are not likely to be available to the average user. The sidebar to this article, Burning a Custom Windows CD, describes the basics of how to do this. To automate the installation from the CD, add the winnt.sif file to the I386 directory of the image.

To add drivers or other files to the CD, several changes must be made to the above answer file. The following descriptions are the simplest method for each variant, there are more complex methods you can explore if you work with answer files. In all cases, change the line OemPreinstall=No in the [Unattended] section to OemPreinstall=Yes.

We will start with miscellaneous files since these are the simplest of all. In the root of the CD, create a directory $OEM$ and under that directory create one or both directories $1 and $$. Any files or directories residing under $1 are moved as part of the text-mode installation from the CD-ROM to the root of the system drive. Similarly, files and directories in $$ are moved to the system directory. For example you could put the files needed for the DDK Traceview tool on the CD-ROM in

They will then be available on the disk at GUI-mode setup time in:

For a text-mode driver you must add two new sections to your answer file:

[MassStorageDrivers]

"Sample WDM Driver for PCI Device" = OEM

"LSI Logic C896 PCI SCSI Host Adapter"= RETAIL

"IDE CD-ROM (ATAPI 1.2)/PCI IDE Controller" = RETAIL

[OEMBootFiles]

pcidrv.sys

pcidrv.cat

pcidrv.inf

txtsetup.oem

The above example installs the pcidrv driver from the example txtsetup.oem that was given earlier. The [MassStorageDrivers] section contains one or more lines to match the description field of the [SCSI] section of txtsetup.oem, each ending with an = OEM. The section must also contain all the required mass storage driver strings for the system. The example above uses two drivers that are part of the regular system build; these drivers are denoted by an = RETAIL after the device description. The device description for these devices is located under the [SCSI] in txtsetup.sif in the I386 directory of the installation CD-ROM. If you do not add the retail drivers, the system will bug check with INACCESSIBLE_BOOT_DEVICE at the start of windows in text-mode setup.

The [OEMBootFiles] section must contain all the files that were described for the entries in txtsetup.oem, plus the txtsetup.oem file itself. The files in this section must not be zero length. I have found that the SetupLdr will accept zero length files, but the Windows portion of text-mode installation will not. The files need to go into three different directories. This requirement appears based on what the current directory is at various points in the installation process. Place the files in the following directories from the root of the CD-ROM:

GUI-mode drivers are a slight expansion of the miscellaneous file approach. GUI-mode drivers must be PNP capable, with a working INF file. To install them add the following line to the [Unattended] section of the answer file:

The path can have multiple folders specified with the line being no more than 4096 characters long. Setup adds "%SYSTEMROOT%\" to each folder name. In practice, it is easiest just to put all the drivers in a single folder. For an entry OemPnPDriversPath = ntinside, the drivers and their supporting files should be loaded into a directory on the CD-ROM image $OEM$\$$\ntinside.

You may also want to add DriverSigningPolicy=Ignore to the [Unattended] section to stop the warnings on unsigned drivers.

Now that you know how to get files into the system, the next logical step to take is to provide a way to run the applications. There are three approaches here, depending on when you wish the application to run.

Running a program while setup is going

To run a program during GUI-mode setup, add the following entries to the [GuiUnattended] section, DetachedProgram ="application path" and Arguments = "application arguments". If you had installed the devcon utility and an INF and driver in a directory ntinside in the root, you could invoke the program with:

The above is taken from this article’s examples and installs a virtual device driver as part of the system. For devcon to work properly you should also have an entry OemPnPDriversPath = ntinside as described in the previous section. Note the I have not been successful at using cmd.exe with a batch file at this point. If you get it to work please let me know.

Running a program after setup but before the reboot

The last phase of GUI-mode setup looks for a file cmdlines.txt in the $OEM$ directory and runs the programs specified with in it. The syntax for cmdlines.txt is:

Where each line is such as "command_1" is a command to execute. These commands run with no logged on user and no network. Any user specific information is written to the default user and inherited by all users of the system. These commands may not use the Windows Installer (i.e. no .msi files).

The easiest approach here is to create a batch file to run all the commands, since there is no way to use a quoted "" string in a command in cmdlines.txt. For example:

will run a batch file cmdline.bat you had on the CD-ROM in $OEM$\$1\system\runonce.bat. At the point the commands are being run, the environment variables are not available. You either need to use an explicit drive letter in the path or put the commands in the system32 directory. These programs can be cleaned up by the run once capability described in the next section. Be aware that the setupmgr has a dialog to setup a cmdlines.txt but it ignores when you choose CD setup.

Running a program after the reboot

Note that these applications run in the context of the logged on user. As in the previous section, the easiest approach is to create a batch file to run, such as:

This will cause the first logon to run a batch file runonce.bat you had on the CD-ROM in $OEM$\$1\ntinside\runonce.bat. Note, the syntax relative to the %SYSTEMROOT% since the %SYSTEMDRIVE% environment variable cannot be relied on at the time of execution.

There is no tool for checking txtsetup.oem except during an attempt to install the file on a system. Unfortunately, the copy part of installation where txtsetup.oem is processed performs limited checking. There are a number of things you can do wrong in the file that will cause the installation to hang with no indication of a problem. A hang example is having a misspelled keyword in the files section (for instance cat instead of catalog). If you are lucky, you will get an error such as:

A second screen indicating an error at some line in a source file will follow the initial report. There is no useful information on the second line for the typical developer. Also, note that while the error message indicates a problem in the INF file it is actually referring to txtsetup.oem.

You can also encounter situations where the installation will proceed normally, but your driver does not work. Use the techniques described below to try to find the problem. Be sure to verify that the system attempted to load your driver. If you see no indication that it did, then check your txtsetup.oem again, because the file is likely to have a problem.

First, before you attempt any debugging as part of installation, be sure your driver works and installs correctly under a running copy of the operating system. As indicated, installation is not the place to be debugging general driver issues. All the techniques for debugging an installation should use the checked build of the system. So fix your driver if it does not run cleanly with a checked build.

Some of the most common problems with installation involve plug and play interactions so break into the debugger early and turn on the device installation flags as shown below (see Knowledge Base Article 314743) for Windows XP and Windows 2003:

or for Windows 2000:

Trace the attempts to install your driver from the output of above, and use !devnode to see the state of the device node for your driver. Most of the other problems you will encounter are easily traceable with standard debugging techniques. Now you need to know how to start the debugger during installation. The next sections explain how to do this.

Text-mode setup presents problems with debugging. Windows starts up part way through the setup, so you cannot just modify the boot options as you would on a running system. The two approaches to invoke WinDbg on an installation are.

Windows 2003 F8

The debugger will activate during text mode setup of Windows Server 2003 with a single keystroke (see Knowledge Base Article 814334). When the system boots to the blue screen (at the time the F6 prompt occurs), press F8 and the system will add /debug to the boot options on an IA32 platform. This translates to:

On the AMD64 and IA64 platform the options for F8 are:

/debug /debugport=com1 /baudrate=115200

Modifying txtsetup.sif

If you are developing for XP or 2000, or want some other debug configuration than the default for 2003, you are going to need to change the file txtsetup.sif. The file contains the following line:

To invoke the debugger, modify the above line to remove the

/nodebug and add the desired debug switches, for example:

The above will run the debugger off COM1 at 115200 baud and cause the HAL to stop at a breakpoint in the beginning of its initialization. The /break makes it easy to activate the verbose debug tracing to aid in finding the problem. Note that if you are modifying the txtsetup.sif file for Windows Server 2003 you could instead modify the line starting with SetupDebugOptions=. This line in the file contains the options invoked when the F8 key is pressed during setup. Changing this, if you are building a custom CD-ROM will allow you to optionally use the F8 debugger control but use different debug options. Now that you know how to modify txtsetup.sif, you need to get the changes into the installation. There are two ways to do this: Winn32.exe installation or a custom CD-ROM.

Winnt32.exe Installation

This is the simpler approach, but there are manual steps that apply to each installation. For this method, invoke winnt32.exe by running:

If you go to the temp drive (this is C: unless you used the /tempdrive switch or selected advanced options to specify another drive) you will find the file txtsetup.sif. Change the permissions on the file so you can edit it, then modify the options as described above. The /debug4:install.log on the command line directs the installer to log information about the installation to a file install.log; in some situations, this can help to debug installation failures. Once the changes have been made, reboot the system and the debugger will be entered as part of loading the kernel for the text mode setup.

Custom CD Installation

For this method, follow the steps of the accompanying sidebar, Burning a Custom Windows CD. Once you have the image on the hard drive, edit the txtsetup.sif in the image directory’s i386 folder.

If you have fully tested your driver, it is much less likely to fail in GUI mode setup than in text-mode setup. You are in GUI-mode running a full Windows kernel, so debugging is relatively easy. The most likely problems here are that something was not setup properly from text-mode setup.

For GUI-mode setup you are running a standard Windows environment, so WinDBG’s driver replacement support is there. This will allow you to install a new driver on the fly. Also, the GUI-mode setup will restart if interrupted, allowing you to debug some problems without going through a full text-mode setup.

The GUI-mode portion of installation is initiated with ntldr just like a normal Windows boot. You should have a second partition with an existing OS on it, so just boot the other OS and edit the boot.ini. If you are trying to install multiple times, select to reinstall in the same partition and delete the Windows folder contents. This will keep the debug settings you previously set for the partition.

One thing you can do with a custom CD to aid GUI-mode setup is to increase the verbosity of Setupapi.log (see Setting SetupAPI Logging Levels in the DDK documentation).

In the image directory’s \I386 folder, edit Hivesft.inf and locate the following line:

After the line listed above, add the following line:

The value 0xC800FFFF may be any appropriate value for the registry entry. The example above will produce a very large amount of output in the debugger.

With an unattended installation, the displays showing the status of the installation are not normally shown. To enable them press SHIFT+F11. When GUI-mode setup is running, you can enter SHIFT+F10 to start a command prompt. This will allow you to perform a number of additional checks such as:

Unzip the accompanying zip file for the article from http://www.osronline.com into a directory. For purposes of this article, I will call the directory install_article. The first two examples show how to install the pcidrv sample at textmode setup time. To do this, build the checked version of the pcidrv sample and copy it to the image directory under the install_article example. The last example requires the pcidrv plus (a) a checked build of the incomplete1 driver from the toaster sample of the DDK, (b) a copy of devcon.exe from the DDK, and (c) dbgout.exe whose source and executable are provided with the article. Note: the CD-ROM examples copy files to the I386 directory, you will need to edit the scripts for 64-bit platforms.

When I tested the CD-ROM’s on Windows XP the following error to occurred:

File caused an unexpected error (0) at line 2108 in d:\xpclient\base\boot\setup\oemdisk.c

This error only occurs with Windows XP, and pressing any key will successfully continue the installation.

To create a floppy disk for installing pcidrv, run the batch file disk1.bat with arguments being the full paths to the install_article directory and the target directory for example:

will build a floppy with an appropriate image to install the driver from the sources located at c:\install_article.

A bit more work is required for a CD-ROM. First, go to the install_article\image directory and edit winnt1.sif. The file needs its [UserData] section edited to have a real installation key. Also, the [MassStorageDrivers] section should have all disk controllers on the test system added in as described in the article.

To create a Windows installation CD-ROM that will install pcidrv, run the batch file cdrom1.bat with arguments being the drive where the original Windows installation CD resides and the full paths to the install_article directory and the target directory. For example:

will build a CD-ROM image to install the driver from the Windows installation CD in d: and the sources located at c:\install_article. Before burning the CD you should edit the OsLoadOptions in txtsetup.sif as described in the article. Then follow the side bar "Burning a Custom Windows CD" to burn the modified image in the directory c:\image from the example line above.

Like in the above simple CD-ROM example, edit the winnt2.sif to fix the [UserData] and the [MassStorageDrivers] sections. The command cdrom2 will build a sample installation CD that:

Like the simple example, the command:

will build a CD-ROM image to install the driver from the Windows installation CD in d: and the sources located at c:\install_article. Again, fix the txtsetup.sif and follow the CD burning instructions.

Hopefully this article has given you an overview of the capabilities available to add a driver to the Windows installation process. I would like to thank Santosh Jodh of Microsoft and Jeannie Vineyard of Egenera for their technical contributions.

• Copy the CD-ROM directory structure to an image directory on your hard disk. I use "xcopy Q:\ c:\image /E /K /O /X /Y" where Q is my CD drive, and c:\image the directory I am using.
• Note for a later step the label of the CD-ROM you just copied (this is the text name that appears in the my computer display prior to the drive letter in parenthesis).
• If you have a service pack for the system, you can integrate this into the CD by running "update.exe /s:c:\image" where c:\image is the image directory. The update program is from the service pack, so you need to extract the files from the service pack executable. This technique is known as slipstreaming. There is a large amount of data from Microsoft on how to do this.
• Modify the image directory to suit your needs. Note that if you do not have enough space on the CD-ROM for you extra files, you can delete the SUPPORT and VALUEADD directories from the CD image.
• Start your CD burner program and select a bootable CD project with the following settings. Bootable CD type - No Emulation, Load Segment - 0x7c0, Sector Count - 4, and the boot image for your platform. You may want to make a copy of boot.bin before burning the CD; some versions of Easy CD Creator deleted the file after use.
• Set the CD label to be the same as the label of the CD-ROM you copied. The CD will not work correctly without this, and be careful not to add a space or other non-visible character.
• Indicate that the contents of the CD should be your image directory contents.
• Burn your CD-ROM.

Don Burn is a Windows system software architect and an MVP for the DDK, specializing in drivers and file systems, with over 25 years industry experience. He's currently consulting while developing fault-tolerant technology for Windows. Don can be reached at burn@acm.org.