home *** CD-ROM | disk | FTP | other *** search
/ Reverse Code Engineering RCE CD +sandman 2000 / ReverseCodeEngineeringRceCdsandman2000.iso / RCE / +Sandman / si-ug-chapter07.txt < prev    next >
Text File  |  2000-05-25  |  14KB  |  332 lines
  1. CHAPTER 7 - Symbolic and Source Level Debugging
  2.  
  3.      07.01 Introduction
  4.      07.02 Preparing for Symbolic or Source Debugging
  5.      07.02.01 Preparing for Symbolic Debugging Only
  6.      07.02.02 Preparing for Symbolic and Source Level Debugging
  7.      07.03 Reserving Memory for Symbols and Source Files
  8.      07.04 Loading Programs and Symbol Files
  9.      07.04.01 Loading Program, Symbols and Source
  10.      07.04.02 Loading Only Symbols and Source Files
  11.      07.04.03 Loading a Program With No Symbols or Source
  12.      07.05 Debugging With Symbols
  13.      07.06 Debugging With Source
  14.      07.06.01 Using Line Numbers
  15.      07.06.02 Using Source Mode in the Code Window
  16.  
  17. 07.01 Introduction
  18.  
  19.      Soft-ICE can load programs, symbol tables and source files for
  20.      enhanced debugging. Symbolic debugging allows you to set break points
  21.      and reference variables with symbol names rather than specifying
  22.      numeric addresses. Source level debugging allows you to step through
  23.      your program at the source code level rather than assembly code level.
  24.  
  25.      Symbol and source line number information is extracted from the link
  26.      map file. The link map must be compatible with Microsoft's linker
  27.      version 3.60 or greater.
  28.  
  29.      Symbols and source files reside in extended memory. You must have
  30.      sufficient extended memory for the symbols and source files. Source
  31.      files are not paged from the disk as in many debuggers. This allows
  32.      Soft-ICE to provide complete system debugging in source level, You can
  33.      debug T&SR's interrupt routines and other systems level code at the
  34.      source level.
  35.  
  36.      Note : You cannot use symbolic or source level debugging unless
  37.      Soft-ICE has been loaded as a device driver in CONFIG.SYS.
  38.  
  39. 07.02 Preparing for Symbolic or Source Debugging
  40.  
  41.      Before debugging a program with symbols or source you must create a
  42.      symbol file. This is a binary file that contains symbol and line
  43.      number information in a format that Soft-ICE can understand. This file
  44.      is created with the utility MSYM.EXE. MSYM.EXE reads in your link map
  45.      to create a symbol file with the extension (.SYM).
  46.  
  47. 07.02.01 Preparing for Symbolic Debugging Only
  48.  
  49.      To prepare a program for symbolic debugging only, you must do the
  50.      following steps:
  51.  
  52.      1. Compile or assemble your program.
  53.  
  54.      2. Link your program with the proper switches to create a .MAP file
  55.      that contains a list of public symbols. If you are using Microsoft's
  56.      linker, the /MA switch is the proper switch to use. This .MAP file
  57.      must be identical to the .MAP file produced by Microsoft's linker,
  58.      version 3.60 or greater.
  59.  
  60.      3. Create a.SYM file by running MSYM.EXE. The syntax for using
  61.      MSYM.EXE is:
  62.  
  63.      MSYM program-name [.extension]
  64.  
  65.      If the extension is not supplied MSYM assumes the extension is .MAP.
  66.      MSYM reads in a map file as in and writes out a symbol file as output.
  67.      The symbol has the name program-name.SYM.
  68.  
  69.      Note : Before compiling or assembling your program you may want to
  70.      make some additional symbols public. Only public symbols are supported
  71.      with Soft-ICE symbolic debugging. The way to make a variable or a
  72.      label public varies, depending upon which language you are using.
  73.  
  74.      In 8086 assembly language, simply use the PUBLIC directive followed by
  75.      the locally defined symbols you wish to make public. For example:
  76.  
  77.      PUBLIC FOO, LOOP1, STATUS
  78.  
  79.      In C language, all procedure names and static variables are defined
  80.      outside a block are public.
  81.  
  82.      For other languages, refer to your language manual for details.
  83.  
  84. 07.02.02 Preparing for Symbolic and Source Level Debugging
  85.  
  86.      To prepare a program for both symbolic and source debugging, you must
  87.      do the following steps:
  88.  
  89.      1. Compile or assemble each module that you wish debug at the source
  90.      level with the appropriate switch to put line number information into
  91.      the object files. With Microsoft languages you can use either the /Zi
  92.      or the /Zd switches. You may not want to do this with all files,
  93.      because the combined file sizes of the symbol file and all the source
  94.      files compiled with these switches must fit into the amount of
  95.      extended memory you have reserved with the /SYM loading switch in
  96.      CONFIG.SYS.
  97.  
  98.      2. Link your program with the proper switches to create a .MAP file
  99.      that contains source line numbers and a list of public symbols. If you
  100.      are using Microsoft's linker, the /LI and /MA switches are the proper
  101.      switches to use. This .MAP file must be identical to the.MAP file
  102.      produced by Microsoft's linker, version 3.60 or greater.
  103.  
  104.      3. Create a.SYM file by running MSYM.EXE. The syntax for using
  105.      MSYM.EXE is :
  106.  
  107.      MSYM program-name [.extension]
  108.  
  109.      If the extension is not supplied MSYM assumes the extension is.MAP.
  110.      MSYM reads in a map file as input and writes out a symbol file as
  111.      output. The symbol file has the name program-name.SYM.
  112.  
  113. 07.03 Reserving Memory for Symbols and Source Files
  114.  
  115.      Before loading programs, symbol files and source files you must
  116.      reserve extended memory for them. Extended memory is reserved when you
  117.      load Soft- ICE in CONFIG.SYS. Before reserving extended memory you may
  118.      want to add up the file sizes of the .SYM file and all of the source
  119.      files that you want to load. You must reserve at least this much
  120.      extended memory. You must use the
  121.  
  122.      /SYM loading switch when loading S-ICE.EXE. A sample line in
  123.      CONFIG.SYS for loading Soft-ICE and reserving space for symbols and
  124.      source files is:
  125.  
  126.      DEVICE = S-ICE.EXE /SYM 1024
  127.  
  128.      This example loads Soft-ICE into extended memory and reserves 1
  129.      megabyte of memory for symbols and source files. See section 6.3
  130.      (Loading Soft-ICE as a Loadable Device Driver) for more details on
  131.      reserving memory.
  132.  
  133. 07.04 Loading Programs and Symbol Files
  134.  
  135.      The Soft-ICE utility LDR.EXE is used for loading programs, symbol
  136.      files and source files. For symbolically debugging application
  137.      programs and T&SR programs you will typically use LDR.EXE to load the
  138.      program, symbols and source files in one step. For debugging loadable
  139.      device drivers, ROMs and other system components you will typically
  140.      use LDR.EXE to load the symbol file and source files only. The syntax
  141.      for LDR.EXE is :
  142.  
  143.      LDR program-name | program-name.SYM | program-name.extension
  144.  
  145. 07.04.01 Loading Program, Symbols and Source
  146.  
  147.      To load your program, symbols and source files in one step, you must
  148.      use LDR.EXE in the form:
  149.  
  150.      LDR program-name
  151.  
  152.      Notice that program-name does not have a file extension. If no file
  153.      extension is supplied, then LDR.EXE will do the following:
  154.  
  155.      1. Load program-name.SYM into extended memory
  156.  
  157.      2. Load source files into extended memory. This step is done only if
  158.      source records exist in the .SYM file.
  159.  
  160.      3. Load program-name.EXE into memory at the location it would have
  161.      loaded if it had been loaded directly from the DOS prompt.
  162.  
  163.      4. Bring up Soft-ICE with the instruction pointer at first instruction
  164.      of your program. If it is a C program and source is loaded for the
  165.      file containing , _MAIN, then the source for that file will be visible
  166.      in the code window.
  167.  
  168. 07.04.02 Loading Only Symbols and Source Files
  169.  
  170.      If you wish to load only symbols and source files (for debugging a
  171.      loadable device driver for example) you must use LDR.EXE in the form:
  172.  
  173.      LDR program-name.SYM
  174.  
  175.      Notice that the.SYM extension is specified. This will load the .SYM
  176.      file and source files into extended memory. When symbols are loaded by
  177.      this method your program or device driver symbols are assumed to be
  178.      referenced from 0:0. Since this is rarely the case you will need to
  179.      use the Soft-ICE command SYMLOC to locate the symbols. See the
  180.      description of the SYMLOC command in section 5.10 for a complete
  181.      description. An example of loading a symbol file called DRIVER.SYM is:
  182.  
  183.      LDR DRIVER.SYM
  184.  
  185. 07.04.03 Loading a Program With No Symbols or Source
  186.  
  187.      To load a program file without loading the associated symbol file you
  188.      must use LDR.EXE in the form:
  189.  
  190.      LDR program-name.extension
  191.  
  192.      Notice that the file extension is present. Typically the file
  193.      extension will be.EXE or.COM. When a file extension specified LDR.EXE
  194.      will load the program and bring up Soft-ICE with the instruction
  195.      pointer at the first instruction of the program. An example of loading
  196.      a program with symbols and source is:
  197.  
  198.      LDR TEST.EXE
  199.  
  200.      Notes : LDR.EXE saves a copy of the interrupt vector table
  201.      automatically when it loads your program. This is equivalent to doing
  202.      a VECS S command. If you are going to exit your program before it runs
  203.      to completion, you can do an EXIT R to exit the program and restore
  204.      the interrupt vector table.
  205.  
  206.      Using LDR.EXE to load only the program-name.EXE is often useful for
  207.      restarting your program while in the middle of a source level
  208.      debugging session. To restart, the EXIT R command to abort the current
  209.      session. Then use LDR.EXE to reload your.EXE file. The symbols: source
  210.      do not have to be loaded since they remain in extended memory.
  211.  
  212.      If LDR.EXE gives you the message "Out of space loading symbol
  213.      information", this means that you did not reserve enough extended
  214.      memory with the /SYM loading switch in CONFIG.SYS.
  215.  
  216.      If LDR.EXE does not find your source files on the same directory as
  217.      the program you are loading, LDR.EXE will prompt you for the path
  218.      names where it can find the source files. If you have source files on
  219.      several directories or are loading a program frequently this becomes
  220.      cumbersome. You can eliminate the need for prompting by using the DOS
  221.      environment variable SRC. LDR.EXE uses this environment variable to
  222.      find source files before prompting the user. The syntax for setting
  223.      the environment variable from the DOS prompt is:
  224.  
  225.      SET SRC = directory;directory;...;directory
  226.  
  227.      Each of the specified directories will be searched before the user is
  228.      prompted.
  229.  
  230.      Limitations : Soft-ICE supports symbols for only one program at a
  231.      time. If you load a new .SYM file, the existing one is overwritten.
  232.      Soft-ICE does not follow overlays or Microsoft Windows segment
  233.      movement. Soft-ICE recognizes public symbols and line numbers only. It
  234.      does not support local variables.
  235.  
  236. 07.05 Debugging With Symbols
  237.  
  238.      After you have loaded your program and.SYM file you can begin
  239.      debugging your program symbolically. In general a symbol can be used
  240.      in any command in place of an address.
  241.  
  242.      Symbols are also used by several Soft-ICE commands when addresses are
  243.      displayed. For example, the U command displays symbol names of labels
  244.      and procedures as it encounters them. There are two commands that are
  245.      helpful when you are symbolically debugging:
  246.  
  247.      SYM: Use the SYM command to get a listing of symbol names and values,
  248.      or to change the value a symbol.
  249.  
  250.      SYMLOC: Use the SYMLOC command to relocate the base of all of your
  251.      symbols. You would need to use the SYMLOC command when:
  252.  
  253.      1. Loading symbols for a loadable device driver
  254.  
  255.      2. Loading symbols for a T&SR that has already been loaded
  256.  
  257.      3. Your program moves itself to a location other than it original
  258.      location.
  259.  
  260.      See section 5. 10 for a complete description of these commands.
  261.  
  262. 07.06 Debugging With Source
  263.  
  264.      When source files are loaded, Soft-ICE allows you to view and step
  265.      through your source code as you are debugging. Soft-ICE offers two
  266.      different modes of source level debugging: mixed mode and source mode.
  267.      Use the SRC command to switch between modes.
  268.  
  269.      Mixed mode shows source lines and the assembly language produced by
  270.      those source lines intermixed on the display. Mixed mode is useful
  271.      when you must debug at the assembly level, but use the source lines
  272.      for reference. Mixed mode is allowed whether the code window visible
  273.      or not.
  274.  
  275.      Source mode strictly shows source lines on the display. Source level
  276.      debugging requires the code window to be visible.
  277.  
  278. 07.06.01 Using Line Numbers
  279.  
  280.      Line numbers can be used in place of addresses in several commands. To
  281.      differentiate a line number from an actual address, place a . (period)
  282.      in front of the number. For example, to set an execution break point
  283.      at source line 45 type:
  284.  
  285.      BPX .450
  286.  
  287. 07.06.02 Using Source Mode in the Code Window
  288.  
  289.      The code window must be visible to enter source mode. If not visible,
  290.      use the WC command to make it visible. Once you are in source mode you
  291.      can use Soft-ICE commands switch to a different source file, view
  292.      source at any location in the file, scroll through the file, search
  293.      for strings in the file, and set break points in the file. For a
  294.      complete description of the following commands see their command
  295.      descriptions in chapters 4 and 5. The following list is a brief
  296.      overview of commands that are useful when debugging source code:
  297.  
  298.      Make the code window visible (if it is not already) with WC command.
  299.  
  300.      Toggle between source, mixed, and code modes with the SRC command.
  301.  
  302.      Place a source file in the code window with the FILE command. For
  303.      example change from the current file to file MAIN.C enter:
  304.  
  305.      FILE MAIN.C
  306.  
  307.      Display source at a specific location within the source file with the
  308.      U command. To change the view to a specific line number or memory
  309.      address use the U command. You can specify actual addresses or line
  310.      numbers as a parameter to the command. For example, to view source in
  311.      the code window starting at source line 450 enter:
  312.  
  313.      U .450
  314.  
  315.      Locate the current instruction in the code window with the . (period)
  316.      command.
  317.  
  318.      Search for a specific character string with the S command. For
  319.      example, to search for the string "Hello World" starting at line 100
  320.      in the current source file enter:
  321.  
  322.      SS 100 "Hello World"
  323.  
  324.      Move the cursor to the code window (if it is not) with the EC command.
  325.  
  326.      Scroll the source with the keys up, down, PaqeUp, PageDn.
  327.  
  328.      Set point-and-shoot break points with the BPX command. Simply place
  329.      the cursor on the source line that you wish to break on, then enter:
  330.  
  331.      BPX
  332.