Microsoft KB Archive/148659

= How to Set Up Windows NT Debug Symbols =

Article ID: 148659

Article Last Modified on 11/1/2006

-

APPLIES TO


 * Microsoft Windows NT Workstation 3.5
 * Microsoft Windows NT Workstation 3.51
 * Microsoft Windows NT Server 3.5
 * Microsoft Windows NT Server 3.51

-



This article was previously published under Q148659



SUMMARY
Windows NT Debug Symbols must be set up if a computer needs to be remotely or locally debugged. This article provides instructions on how to set up Windows NT Debug Symbols.



Article Contents

 * What Are Symbols
 * Setting Up a Custom Symbol Tree
 * Single Processor vs. Multiprocessor
 * Custom HAL.DLL
 * After the Symbol Tree Is Created

What Are Symbols
Debug Symbol files (symbols) are required to do both kernel and user-mode debugging in Windows NT. Symbols provide a way to resolve global variables and function names in the loaded executable file.

Symbols are produced by the linker when a program is built. They are stripped out of the retail product and saved in a separate (.DBG) file. This considerably reduces file size which decreases file load time and thus increases system performance. Symbols represent Function\API names and global variables.

The .DBG file contains symbolic information for each file. They can be found on the SUPPORT\DEBUG\ \SYMBOLS directory of the Windows NT installation compact disc.

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

The SYMBOLS directory is divided up into seven subdirectories, called Extension Subdirectories (note that many of the symbol files in these directories match USER MODE components of Windows NT):

  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.

The symbols must match their respective files. Symbols from a different build give erroneous information. All of the symbol file link dates must match those on the computer being debugged.

Setting Up a Custom Symbol Trees
The Symbol Tree is the subdirectory tree on the host computer which contains the symbol files which match the remote computer being debugged.

 Create a Subdirectory on the host computer. For example:

MKDIR C:\SYMBOLS

 Always start with the base Windows NT version number. Copy the following files from the installation compact disc for the appropriate version:

XCOPY [CD Drive]:\SUPPORT\DEBUG\I386 C:\SYMBOLS /S.

 Copy the symbols for the appropriate Service Pack into the custom tree. Service Pack symbols can be found on FTP.MICROSOFT.COM.

For example, the symbols for Windows NT 3.51 Service Pack 4 can be downloaded from the following location:

\bussys\winnt\winnt-public\fixes\usa\NT351\ussp4\symbols

Download the file called SYM_351.EXE where X represents the platform (I for x86, A for Alpha, P for PPC).

Decompress the files into the symbol tree. For example:

SYM_351.EXE -d C:\SYMBOLS

 Copy any third-party patches, such as the Compaq SSD symbols, to the custom symbol tree. These symbols must be obtained from the third-party vendor. If Microsoft has supplied unique fixes for your installation, copy the DBG file supplied with the fix into the appropriate subdirectory (for example: SYS, EXE, DLL).

</li> If the computer is a single processor Intel system, the symbol tree is complete. Please see the "After the Symbol Tree is Created" section below.</li></ol>

Single Processor vs. Multiprocessor
Windows NT uses a special kernel for SMP systems. During installation this kernel is renamed. It is important that the DBF file is renamed for debugging.

<pre class="fixed_text">  NTOSKRNL.EXE  NTOSKRNL.DBG  = Single processor NTKRNLMP.EXE NTKRNLMP.DBG  = Multiple processors

If the system is a Multi-Processor, do the following:

<ol> Change the directory to the DLL component directory. For example:

CHDIR C:\SYMBOLS\DLL

</li> Rename the uniprocessor kernel to another filename. For example:

RENAME NTOSKRNL.DBG NTOSKRNL.UNI

</li> Copy the multiprocessor kernel over the uniprocessor kernel. For example:

COPY NTKRNLMP.DBG NTOSKRNL.DBG

</li></ol>

Custom HAL.DLL
Some hardware platforms require a special Hardware Abstraction Layer (HAL) Driver. Like the Kernel file, the custom HAL is renamed during the installation process. Here is a list of common HALs:

HAL files for I386 Computers:

<pre class="fixed_text">Filename                  Description --- HAL.DLL                   Standard HAL for Intel systems HAL486C.DLL               HAL for 486 c step processor HALAPIC.DLL               Uniprocessor version of HALMPS.DLL HALAST.DLL                HAL for AST SMP systems HALCBUS.DLL               HAL for Cbus systems HALMCA.DLL                HAL for MCA-based systems (PS\2 and others) HALMPS.DLL                HAL for most Intel multiprocessor systems HALNCR.DLL                HAL for NCR SMP computers HALOLI.DLL                HAL for Olivetti SMP computers HALSP.DLL                 HAL for Compaq Systempro HALWYSE7.DLL              HAL for Wyse7 systems

HAL files for DEC Alpha Computers:

Filename                  Description --- HAL0JENS.DLL              Digital DECpc AXP 150 HAL HALALCOR.DLL              Digital AlphaStation 600 Family HALAVANT.DLL              Digital AlphaStation 200\400 Family HAL HALEB64P.DLL              Digital AlphaPC64 HAL HALGAMMP.DLL              Digital AlphaServer 2x00 5\xxx Family HAL HALMIKAS.DLL              Digital AlphaServer 1000 Family Uniprocessor HAL HALNONME.DLL              Digital AXPpci 33 HAL HALQS.DLL                 Digital Multia MultiClient Desktop HAL HALSABMP.DLL              Digital AlphaServer 2x00 4\xxx Family HAL

HAL files for MIPS Computers:

Filename                  Description --- HALACR.DLL                ACER HAL HALDTI.DLL                DESKStation Evolution HALDUOMP.DLL              Microsoft-designed dual MP HAL HALFXS.DLL                MTI with a r4000 or r4400 HALFXSPC.DLL              MTI with a r4600 HALNECMP.DLL              NEC dual MP HALNTP.DLL                 NeTpower FASTseries HALR98MP.DLL              NEC 4 processor MP HALSNI4X.DLL               Siemens Nixdorf UP and MP HALTYNE.DLL                DESKstation Tyne

HAL files for PPC Computers:

Filename                  Description --- HALCARO.DLL               HAL for IBM-6070 HALEAGLE.DLL              HAL for Motorola PowerStack and Big Bend HALFIRE.DLL               Hal for Powerized_ES, Powerized_MX, and Powerized_MX MP HALPOLO.DLL               HAL for IBM-6030 HALPPC.DLL                HAL for IBM-6015 HALWOOD.DLL               HAL for IBM-6020

How to Determine Which HAL to Use:

During installation, a text log file is created. This file has a line which shows which HAL is installed during setup. If the HAL has changed after the original Setup, the SETUP.LOG does not reflect the change. To verify, do the following:


 * 1) Go to %SystemRoot%\REPAIR subdirectory.
 * 2) Run ATTRIB -R -H -S SETUP.LOG to make the file visible.
 * 3) Use Notepad to view SETUP.LOG and search for "Hal".

NOTE: This same technique can be useful to verify if a special kernel is also used.

Copy the HAL into the Symbol Tree:


 * 1) Change directory to \SYMBOLS\DLL.
 * 2) Rename HAL.DBG to HAL.X86.
 * 3) Copy the "Custom HLL.DBG" to HAL.DBG.

After the Symbol Tree Is Created
The symbol tree is now complete. For more information, query on the following word here in the Microsoft Knowledge Base:

debugref

Additional query words: 3.50 3.51 prodnt debugref

Keywords: KB148659

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.