Copy Link
Add to Bookmark
Report
Chapter 7
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
