You are currently offline, waiting for your internet to reconnect

Windows NT Debug Symbol Setup Information

This article was previously published under Q138258
This article provides detailed information on how to set up Microsoft Windows NT Symbol Trees, as well as advanced setup tips and tricks.

Article Contents

  • General Information
  • Setting up Custom Symbol Trees
  • Single Processor vs. Multi Processor
  • Custom HAL.DLL
  • Using Symbols in Debugger
  • Verifying the Symbols
  • Advanced Symbol Verification
  • Checked Versions

General Information

Debug Symbol files (symbols) are required to do both kernel and user-modedebugging in Windows NT. Symbols provide a way to reference globalvariables and function names in the loaded executable.

Symbols are produced by the linker. They are stripped out of retailproductand saved in a separate (.DBG) file. This considerably reduces file sizewhich decreases file load time and thus increases system performance. Italso reduces the number of install floppies. Symbols representFunction/APInames and global variables.

The .DBG File contains symbolic information for each file. They can befound on the installation CD-ROM in \Support\Debug\[i386 | mips]\Symbols.They can also be found on the NT build server. The location is\\Ntbuilds\Release\Usa\Build###\[x86 | mips |alpha]\Fre.srv\symbols.

The Symbols directory is divided up into seven subdirectories, calledExtensionSubdirectories (note that many of the symbol files in these directoriesareUser mode):

COM - symbols for all files ending in .COM go here
CPL - symbols for all files ending in .CPL go here.
DLL - symbols for all files ending in .DLL go here
DRV - symbols for all files ending in .DRV go here
EXE - symbols for all files ending in .EXE go here
SCR - symbols for all files ending in .SCR go here
SYS - symbols for all files ending in .SYS go here.

Symbols must match file versions:

Symbols from a different build give erroneous information and senddevelopers chasing shadows and waste considerable time. Double check withthe customer what build the customer is running and if the customer has any patches installed.The Kernel Stop Screen displays the build number of the kernel.

Patched Builds:

Patched builds such as Service Packs require a special set of symbols,thatis a combination of the base build and the patched symbols.

Setting Up Custom Symbol Trees

Remember that symbols must match the files installed on a customer'scomputer. You often have to create a custom set of symbols just for aparticular customer.

NOTE: Complete Symbol Trees can take up over 30 MB of disk space.
  1. Create a subdirectory to store your customer symbol set. For example:

  2. Always start with the base Windows NT version number. Copy the following files from the installation CD-ROM for the appropriate version:

  3. Copy symbols for the appropriate Service Pack binary files over your custom tree. Service Pack symbols can be found on the servers listed in the section below titled "Symbol Locations."
  4. Copy any third-party patches such as Compaq SSD symbols over to your custom symbol tree. You may need to get these symbols from the vendor. NOTE: Steps 3 and 4 may need to be reversed depending on the order that they were installed by the customer. Match the customer's steps.
  5. If the server has hotfixes installed, you need to obtain the matching symbol for that hotfix. If a symbol file is not provided with the hotfix, you need to contact Microsoft Product Support Services to inquire about the availability of these symbols. Copy the updated symbol over your custom symbol tree. Make sure that you place it in the correct subfolder (for example, Sys, exe, dll, etc.).

Single Processor vs. Multi Processor

Windows NT uses a special kernel for SMP systems. During installation thiskernel is renamed. It is important that you also rename the SYMBOL.DBGfile for debugging.
NTOSKRNL.EXE NTOSKRNL.DBG = Single processor NTKRNLMP.EXE. NTKRNLMP.DBG = Multiple processors

  1. If you have a multi-processor system do the following. Under your custom symbol tree in \SYMBOLS\EXE there are two kernel files. Rename NTOSKRNL.DBG to NTOSKRNL.UNI.

Custom HAL.DLL

Some hardware platforms require a special Hardware Abstraction LayerDriver. Like the Kernel file, the custom HAL is renamed during theinstallation process. Here is a list of common HALs:

HAL files for I386 Computers:
              UncompressedFilename      Size (bytes) Description-------------------------------------------------------------------------HAL.DLL       48,416       Standard HAL for Intel systemsHAL486C.DLL   47,376       HAL for 486 c step processorHALAPIC.DLL   63,616       Uniprocessor version of HALMPS.DLLHALAST.DLL    46,416       HAL for AST SMP systemsHALCBUS.DLL   79,776       HAL for Cbus systemsHALMCA.DLL    45,488       HAL for MCA-based systems (PS/2 and others)HALMPS.DLL    65,696       HAL for most Intel multiprocessor systemsHALNCR.DLL    79,392       HAL for NCR SMP machinesHALOLI.DLL    40,048       HAL for Olivetti SMP machinesHALSP.DLL     52,320       HAL for Compaq SystemproHALWYSE7.DLL  40,848       HAL for Wyse7 systemsHAL files for DEC Alpha Computers:              UncompressedFilename      Size (bytes) Description--------------------------------------------------------------------------HAL0JENS.DLL  56,800       Digital DECpc AXP 150 HALHALALCOR.DLL  69,120       Digital AlphaStation 600 FamilyHALAVANT.DLL  66,752       Digital AlphaStation 200/400 Family HALHALEB64P.DLL  70,528       Digital AlphaPC64 HALHALGAMMP.DLL  72,896       Digital AlphaServer 2x00 5/xxx Family HALHALMIKAS.DLL  67,040       Digital AlphaServer 1000 Family UniprocessorHALHALNONME.DLL  65,376       Digital AXPpci 33 HALHALQS.DLL     65,088       Digital Multia MultiClient Desktop HALHALSABMP.DLL  72,736       Digital AlphaServer 2x00 4/xxx Family HALHAL files for MIPS Computers:              UncompressedFilename      Size (bytes) Description--------------------------------------------------------------------------HALACR.DLL    43,648       ACER HALHALDTI.DLL    68,288       DESKStation EvolutionHALDUOMP.DLL  41,728       Microsoft-designed dual MP HALHALFXS.DLL    42,016       MTI with a r4000 or r4400HALFXSPC.DLL  42,176       MTI with a r4600HALNECMP.DLL  44,736       NEC dual MPHALNTP.DLL    116,000      NeTpower FASTseriesHALR98MP.DLL  127,232      NEC 4 processor MPHALSNI4X.DLL  95,520       Siemens Nixdorf UP and MPHALTYNE.DLL   68,032       DESKstation TyneHAL files for PPC Computers:              UncompressedFilename      Size (bytes) Description--------------------------------------------------------------------------HALCARO.DLL   169,504      HAL for IBM-6070HALEAGLE.DLL  206,208      HAL for Motorola PowerStack and Big BendHALFIRE.DLL   136,576      Hal for Powerized_ES,                                   Powerized_MX, and                                   Powerized_MX MPHALPOLO.DLL   169,152      HAL for IBM-6030HALPPC.DLL    169,184      HAL for IBM-6015HALWOOD.DLL   95,616       HAL for IBM-6020

How to Determine Which HAL to Use:

During installation a text log file is created. This file can inform you about the original name of the HAL.
  1. Go to %systemroot%\REPAIR subdirectory.
  2. Run ATTRIB -R -H -S SETUP.LOG to make the file visible.
  3. Bring up the file in Microsoft Notepad and search for HAL.
NOTE: This same technique can be useful to verify if a special kernelis also used.

Go to Setup HAL Symbol:
  1. Go to your custom symbol tree under \SYMBOLS\DLL.
  2. Rename HAL.DBG to HAL.X86.
  3. Copy the "Custom HLL.DBG" to HAL.DBG.

Using Symbols in the Debugger

A Windows NT Debugger, such as I386KD.EXE, looks for symbols in thefollowing locations:
_NT_ALT_SYMBOL_PATH system environment variable
_NT_SYMBOL_PATH system environment variable

These locations are set via system environment variables. They are usuallyconfigured by a debug batch file using the SET command. The_NT_ALT_SYMBOL_PATH is optional. For example:

NOTE: The symbols directory is the directory directly above the extensionsubdirectories (that is, if the kernel symbol file, NTOSKRNL.DBG, islocated at C:\DEBUG\511\I386\SYMBOLS\EXE\NTOSKRNL.DBG. The _NT_SYMBOL_PATHshould be set to C:\DEBUG\511\I386\SYMBOLS

How to Use Paths:

A good use of these various paths is for keeping static symbol trees foreach Windows NT version. You simply point your symbol paths to eachversionand Service Pack as needed. For example, for a 1057 system with SP2installed you could use the following:

The debugger attempts to use the Service Pack symbols first. [The ServicePack symbols do not include the base build symbols in this case, only theSP symbols.] If the debugger does not find a particular symbol in the SPtree it looks it up in the 1057 symbol tree.

Search Order:

The various symbol paths are searched in the order listed above. The firstsymbol file with the correct name that is encountered is used. In theexample above, _NT_ALT_SYMBOL_PATH=c:\NT351-SP2\SYMBOLS is the first onesearched.

Environment Variable Override:

I386KD supports a command line switch "-y" where you can specify a symbolpath. However, using this switch overrides your existing environmentvariables.

Change Path on the Fly:

You can change the symbol search path at any time in the debugger byissuing "!Sympath" command. For example:

Verifying the Symbols


Once you have gotten to the "kd>" prompt for the first time, you must type"!RELOAD". This causes the symbolic information to be reloaded andsynchronized. If you get the error "PsLoadedModuleList is NULL!", youprobably have the wrong symbols loaded. Be sure you have the correctHAL.DBG and NTOSKRNL.DBG file installed for the computer that you aredebugging.


Symbols can also be verified by typing "!PROCESS" if you get the error,"Can't find process list head", you probably have the wrong symbolsloaded.


If the Stack Trace has gaps in the function name list, this indicates thatyou are missing symbols. Missing functions could also indicate a corruptstack but this is somewhat rare. Double check your symbols beforedeclaringa corrupt stack. Also, look at the return addresses on the stack. Theyshould all be greater than 8000000.


Incorrect symbols can be corrected by going to another command window,copying the correct symbols and doing a !reload on the debugger or byspecifying the correct path with !SYMPATH symbol_path.

Advanced Symbol Verification

Sometimes customers do not know what driver versions they have installedon their computers. Perhaps they installed a hotfix for NTFS but theydo not know which bug number. You may need to manually determine which .DBGfiles are needed.

The best way to absolutely verify if target and dbg's match is to viewtheir check sum value. This value is stored inside the file header.

Note: To learn more about operating system file format search MSDN for"Portable Execution File Format." The PE header contains version numbers,link date\time, etc.

The general plan here is to first find out the check sum of the customersfiles and then find a dbg file that has a matching check sum.

There are many ways to extract the chksum from the target and the dbg.If you have access to the files, you can use the following. This exampleassumes you are interested in the file NTOSKRNL.


This utility can be found in the NT Build subdirectory \MSTOOLS:


This utility can be found in the Visual C bin directory:

If you are using a debugger on a system or a crash dump, you can find thechecksum of the target file by viewing the file header in memory.
  1. !DRIVERS - Will give you driver base address.
  2. dd baseaddr+d8 L1

Checked Versions

If you install debug checked versions of Windows NT files you need tomake special arrangements for they dbg symbol files. Some hotfix checkedbuilds have the symbolic information built into the target file. Inthese cases, just make a copy of the file and name it *.DBG. Place thefile in the normal symbol sub directory, that is, \SYMBOLS\EXE.

All publicly released check builds have separate dbg files just like thefree releases. However, the dbg for checked and free versions aredifferent. For example, the MS NT DDK contains a complete checked build ofNT. It also contains a complete symbol set to go with it.

NOTE: Checked versions of the NT kernel are the same for bothMultiprocessor and Uniprocessor systems.

Symbol Locations

Retail Product:

prodnt debugref

Article ID: 138258 - Last Review: 11/01/2006 04:55:00 - Revision: 2.1

  • Microsoft Windows NT Advanced Server 3.1
  • Microsoft Windows NT Server 3.5
  • Microsoft Windows NT Server 3.51
  • Microsoft Windows NT Server 4.0 Standard Edition
  • Microsoft Windows NT Workstation 3.1
  • Microsoft Windows NT Workstation 3.5
  • Microsoft Windows NT Workstation 3.51
  • Microsoft Windows NT Workstation 4.0 Developer Edition
  • Microsoft Windows NT Advanced Server 3.1
  • kbusage KB138258