CHAPTER 7 - Symbolic and Source Level Debugging 07.01 Introduction 07.02 Preparing for Symbolic or Source Debugging 07.02.01 Preparing for Symbolic Debugging Only 07.02.02 Preparing for Symbolic and Source Level Debugging 07.03 Reserving Memory for Symbols and Source Files 07.04 Loading Programs and Symbol Files 07.04.01 Loading Program, Symbols and Source 07.04.02 Loading Only Symbols and Source Files 07.04.03 Loading a Program With No Symbols or Source 07.05 Debugging With Symbols 07.06 Debugging With Source 07.06.01 Using Line Numbers 07.06.02 Using Source Mode in the Code Window 07.01 Introduction Soft-ICE can load programs, symbol tables and source files for enhanced debugging. Symbolic debugging allows you to set break points and reference variables with symbol names rather than specifying numeric addresses. Source level debugging allows you to step through your program at the source code level rather than assembly code level. Symbol and source line number information is extracted from the link map file. The link map must be compatible with Microsoft's linker version 3.60 or greater. Symbols and source files reside in extended memory. You must have sufficient extended memory for the symbols and source files. Source files are not paged from the disk as in many debuggers. This allows Soft-ICE to provide complete system debugging in source level, You can debug T&SR's interrupt routines and other systems level code at the source level. Note : You cannot use symbolic or source level debugging unless Soft-ICE has been loaded as a device driver in CONFIG.SYS. 07.02 Preparing for Symbolic or Source Debugging Before debugging a program with symbols or source you must create a symbol file. This is a binary file that contains symbol and line number information in a format that Soft-ICE can understand. This file is created with the utility MSYM.EXE. MSYM.EXE reads in your link map to create a symbol file with the extension (.SYM). 07.02.01 Preparing for Symbolic Debugging Only To prepare a program for symbolic debugging only, you must do the following steps: 1. Compile or assemble your program. 2. Link your program with the proper switches to create a .MAP file that contains a list of public symbols. If you are using Microsoft's linker, the /MA switch is the proper switch to use. This .MAP file must be identical to the .MAP file produced by Microsoft's linker, version 3.60 or greater. 3. Create a.SYM file by running MSYM.EXE. The syntax for using MSYM.EXE is: MSYM program-name [.extension] If the extension is not supplied MSYM assumes the extension is .MAP. MSYM reads in a map file as in and writes out a symbol file as output. The symbol has the name program-name.SYM. Note : Before compiling or assembling your program you may want to make some additional symbols public. Only public symbols are supported with Soft-ICE symbolic debugging. The way to make a variable or a label public varies, depending upon which language you are using. In 8086 assembly language, simply use the PUBLIC directive followed by the locally defined symbols you wish to make public. For example: PUBLIC FOO, LOOP1, STATUS In C language, all procedure names and static variables are defined outside a block are public. For other languages, refer to your language manual for details. 07.02.02 Preparing for Symbolic and Source Level Debugging To prepare a program for both symbolic and source debugging, you must do the following steps: 1. Compile or assemble each module that you wish debug at the source level with the appropriate switch to put line number information into the object files. With Microsoft languages you can use either the /Zi or the /Zd switches. You may not want to do this with all files, because the combined file sizes of the symbol file and all the source files compiled with these switches must fit into the amount of extended memory you have reserved with the /SYM loading switch in CONFIG.SYS. 2. Link your program with the proper switches to create a .MAP file that contains source line numbers and a list of public symbols. If you are using Microsoft's linker, the /LI and /MA switches are the proper switches to use. This .MAP file must be identical to the.MAP file produced by Microsoft's linker, version 3.60 or greater. 3. Create a.SYM file by running MSYM.EXE. The syntax for using MSYM.EXE is : MSYM program-name [.extension] If the extension is not supplied MSYM assumes the extension is.MAP. MSYM reads in a map file as input and writes out a symbol file as output. The symbol file has the name program-name.SYM. 07.03 Reserving Memory for Symbols and Source Files Before loading programs, symbol files and source files you must reserve extended memory for them. Extended memory is reserved when you load Soft- ICE in CONFIG.SYS. Before reserving extended memory you may want to add up the file sizes of the .SYM file and all of the source files that you want to load. You must reserve at least this much extended memory. You must use the /SYM loading switch when loading S-ICE.EXE. A sample line in CONFIG.SYS for loading Soft-ICE and reserving space for symbols and source files is: DEVICE = S-ICE.EXE /SYM 1024 This example loads Soft-ICE into extended memory and reserves 1 megabyte of memory for symbols and source files. See section 6.3 (Loading Soft-ICE as a Loadable Device Driver) for more details on reserving memory. 07.04 Loading Programs and Symbol Files The Soft-ICE utility LDR.EXE is used for loading programs, symbol files and source files. For symbolically debugging application programs and T&SR programs you will typically use LDR.EXE to load the program, symbols and source files in one step. For debugging loadable device drivers, ROMs and other system components you will typically use LDR.EXE to load the symbol file and source files only. The syntax for LDR.EXE is : LDR program-name | program-name.SYM | program-name.extension 07.04.01 Loading Program, Symbols and Source To load your program, symbols and source files in one step, you must use LDR.EXE in the form: LDR program-name Notice that program-name does not have a file extension. If no file extension is supplied, then LDR.EXE will do the following: 1. Load program-name.SYM into extended memory 2. Load source files into extended memory. This step is done only if source records exist in the .SYM file. 3. Load program-name.EXE into memory at the location it would have loaded if it had been loaded directly from the DOS prompt. 4. Bring up Soft-ICE with the instruction pointer at first instruction of your program. If it is a C program and source is loaded for the file containing , _MAIN, then the source for that file will be visible in the code window. 07.04.02 Loading Only Symbols and Source Files If you wish to load only symbols and source files (for debugging a loadable device driver for example) you must use LDR.EXE in the form: LDR program-name.SYM Notice that the.SYM extension is specified. This will load the .SYM file and source files into extended memory. When symbols are loaded by this method your program or device driver symbols are assumed to be referenced from 0:0. Since this is rarely the case you will need to use the Soft-ICE command SYMLOC to locate the symbols. See the description of the SYMLOC command in section 5.10 for a complete description. An example of loading a symbol file called DRIVER.SYM is: LDR DRIVER.SYM 07.04.03 Loading a Program With No Symbols or Source To load a program file without loading the associated symbol file you must use LDR.EXE in the form: LDR program-name.extension Notice that the file extension is present. Typically the file extension will be.EXE or.COM. When a file extension specified LDR.EXE will load the program and bring up Soft-ICE with the instruction pointer at the first instruction of the program. An example of loading a program with symbols and source is: LDR TEST.EXE Notes : LDR.EXE saves a copy of the interrupt vector table automatically when it loads your program. This is equivalent to doing a VECS S command. If you are going to exit your program before it runs to completion, you can do an EXIT R to exit the program and restore the interrupt vector table. Using LDR.EXE to load only the program-name.EXE is often useful for restarting your program while in the middle of a source level debugging session. To restart, the EXIT R command to abort the current session. Then use LDR.EXE to reload your.EXE file. The symbols: source do not have to be loaded since they remain in extended memory. If LDR.EXE gives you the message "Out of space loading symbol information", this means that you did not reserve enough extended memory with the /SYM loading switch in CONFIG.SYS. If LDR.EXE does not find your source files on the same directory as the program you are loading, LDR.EXE will prompt you for the path names where it can find the source files. If you have source files on several directories or are loading a program frequently this becomes cumbersome. You can eliminate the need for prompting by using the DOS environment variable SRC. LDR.EXE uses this environment variable to find source files before prompting the user. The syntax for setting the environment variable from the DOS prompt is: SET SRC = directory;directory;...;directory Each of the specified directories will be searched before the user is prompted. Limitations : Soft-ICE supports symbols for only one program at a time. If you load a new .SYM file, the existing one is overwritten. Soft-ICE does not follow overlays or Microsoft Windows segment movement. Soft-ICE recognizes public symbols and line numbers only. It does not support local variables. 07.05 Debugging With Symbols After you have loaded your program and.SYM file you can begin debugging your program symbolically. In general a symbol can be used in any command in place of an address. Symbols are also used by several Soft-ICE commands when addresses are displayed. For example, the U command displays symbol names of labels and procedures as it encounters them. There are two commands that are helpful when you are symbolically debugging: SYM: Use the SYM command to get a listing of symbol names and values, or to change the value a symbol. SYMLOC: Use the SYMLOC command to relocate the base of all of your symbols. You would need to use the SYMLOC command when: 1. Loading symbols for a loadable device driver 2. Loading symbols for a T&SR that has already been loaded 3. Your program moves itself to a location other than it original location. See section 5. 10 for a complete description of these commands. 07.06 Debugging With Source When source files are loaded, Soft-ICE allows you to view and step through your source code as you are debugging. Soft-ICE offers two different modes of source level debugging: mixed mode and source mode. Use the SRC command to switch between modes. Mixed mode shows source lines and the assembly language produced by those source lines intermixed on the display. Mixed mode is useful when you must debug at the assembly level, but use the source lines for reference. Mixed mode is allowed whether the code window visible or not. Source mode strictly shows source lines on the display. Source level debugging requires the code window to be visible. 07.06.01 Using Line Numbers Line numbers can be used in place of addresses in several commands. To differentiate a line number from an actual address, place a . (period) in front of the number. For example, to set an execution break point at source line 45 type: BPX .450 07.06.02 Using Source Mode in the Code Window The code window must be visible to enter source mode. If not visible, use the WC command to make it visible. Once you are in source mode you can use Soft-ICE commands switch to a different source file, view source at any location in the file, scroll through the file, search for strings in the file, and set break points in the file. For a complete description of the following commands see their command descriptions in chapters 4 and 5. The following list is a brief overview of commands that are useful when debugging source code: Make the code window visible (if it is not already) with WC command. Toggle between source, mixed, and code modes with the SRC command. Place a source file in the code window with the FILE command. For example change from the current file to file MAIN.C enter: FILE MAIN.C Display source at a specific location within the source file with the U command. To change the view to a specific line number or memory address use the U command. You can specify actual addresses or line numbers as a parameter to the command. For example, to view source in the code window starting at source line 450 enter: U .450 Locate the current instruction in the code window with the . (period) command. Search for a specific character string with the S command. For example, to search for the string "Hello World" starting at line 100 in the current source file enter: SS 100 "Hello World" Move the cursor to the code window (if it is not) with the EC command. Scroll the source with the keys up, down, PaqeUp, PageDn. Set point-and-shoot break points with the BPX command. Simply place the cursor on the source line that you wish to break on, then enter: BPX