home *** CD-ROM | disk | FTP | other *** search
/ Hackers Toolkit v2.0 / Hackers_Toolkit_v2.0.iso / HTML / archive / Texts / cracking / si-ug-chapter03.txt < prev    next >
Text File  |  1999-11-04  |  38KB  |  814 lines
  1. CHAPTER 3 - Debugging In 30 Minutes
  2.  
  3.      03.01 Introduction
  4.      03.02 Popping Up the Window
  5.      03.03 Returning From the Window
  6.      03.04 Changing the Window Size
  7.      03.05 Moving the Window
  8.      03.06 Line Editing Keystrokes
  9.      03.07 Interactive Status Line
  10.      03.08 Command Syntax
  11.      03.08.01 Specifying Memory Addresses
  12.      03.09 Function Keys
  13.      03.10 Help
  14.      03.11 Tutorial
  15.  
  16. 03.01 Introduction
  17.  
  18.      All interaction with Soft-ICE takes place through a window that can be
  19.      popped up at any time. All Soft-ICE commands fit in a small window,
  20.      but the window can be enlarged to full screen. You will typically use
  21.      the small window when using Soft-ICE as an assistant to another
  22.      debugger, and the large window when using Soft-ICE in stand-alone
  23.      mode.
  24.  
  25.      The window initially comes up in full screen mode if you are using the
  26.      Soft-ICE configuration file (S-ICE DAT) that was included on the
  27.      distribution diskette.
  28.  
  29. 03.02 Popping Up the Window
  30.  
  31.      You can bring up the window at any time after installing Soft-ICE. You
  32.      initially bring up Soft-ICE by pressing the CTRL D keys. However, this
  33.      sequence can be changed by using the ALTKEY command (see section 5.8).
  34.  
  35. 03.03 Returning From the Window
  36.  
  37.      Return to the original display by using the X command or the key
  38.      sequence that you used to invoke Soft-ICE. Any break points that you
  39.      set while working in Soft-ICE will be armed at this point.
  40.  
  41. 03.04 Changing the Window Size
  42.  
  43.      You can modify both the width and the height of the Soft-ICE window.
  44.      Changing the window size is particularly useful in stand-alone mode
  45.      when you are displaying code memory.
  46.  
  47.      The window height can vary from 8 to 25 lines tall. To change the
  48.      window height, use the following key sequences:
  49.  
  50.      ALT UP      : makes the window taller
  51.      ALT DOWN    : makes the window shorter
  52.  
  53.      To change the window width, use the WIN command (see section 5.9).
  54.      Entering WIN with no parameters toggles between the following two
  55.      modes:
  56.  
  57.      WIDE mode   : full screen width
  58.      NARROW mode : 46 characters wide
  59.  
  60.      Some commands (D, E, R, U) take advantage of the extra width by
  61.      displaying more information when the window is in wide mode.
  62.  
  63. 03.05 Moving the Window
  64.  
  65.      The Soft-ICE window is movable and can be positioned anywhere on the
  66.      screen. This is particularly useful when the window is in narrow mode.
  67.      Move the window anytime you need to view information on the screen
  68.      behind the window. The following key sequences move the window:
  69.  
  70.      CTRL UP     : moves the window one row up
  71.      CTRL DOWN   : moves the window one row down
  72.      CTRL RIGHT  : moves the window one column right
  73.      CTRL LEFT   : moves the window one column left
  74.  
  75. 03.06 Line Editing Keystrokes
  76.  
  77.      Soft-ICE's easy-to-use line editor allows you to recall and edit
  78.      previous commands. The line editor functions are similar to those of
  79.      the popular CED line editor. The following key sequences help you edit
  80.      commands in the command window :
  81.  
  82.      LEFT        : moves the cursor to the right
  83.      RIGHT       : moves the cursor to the left
  84.      INS         : toggles insert mode
  85.      DEL         : deletes the current character
  86.      HOME        : moves the cursor to start of the line
  87.      END         : moves the cursor to the end of the line
  88.      UP          : displays the previous command
  89.      DOWN        : displays the next command
  90.      SHIFT       : scroll one line up in display
  91.      SHIFT       : scroll one line down in display
  92.      PAGE UP     : scroll one page up in display
  93.      PAGE DN     : scroll one page down in display
  94.      BKSP        : deletes the previous character
  95.      ESC         : cancels the current command
  96.  
  97.      There are special key assignments when the cursor is in the data
  98.      window or the code window. These are described in the sections for the
  99.      E and EC command respectively. One special assignment of note is the
  100.      SHIFT UP and SHIFT DOWN keys while the cursor is in the code window.
  101.      These keys are re-assigned so they have the functions that UP and DOWN
  102.      normally have. This way you can recall previous commands while the
  103.      cursor is in the code window.
  104.  
  105. 03.07 Interactive Status Line
  106.  
  107.      A status line at the bottom of the window provides interactive help
  108.      with command syntax.
  109.  
  110. 03.08 Command Syntax
  111.  
  112.      Soft-ICE is a command-driven debugging tool. To interact with
  113.      Soft-ICE, you enter commands, which can optionally be modified by
  114.      parameters.
  115.  
  116.      All commands are text strings that are one to six characters in length
  117.      and are case insensitive. AlI parameters are either ASCII strings or
  118.      expressions.
  119.  
  120.      Expressions are typically numbers, but can also be combinations of
  121.      numbers and operators (e.g., + - / *). All numbers are displayed in
  122.      hexadecimal format. Byte parameters are 2 digits long, word parameters
  123.      are 4, and double word parameters are 2 word parameters separated by a
  124.      colon (:). Here are some examples of parameters:
  125.  
  126.      12          : byte parameter
  127.      10FF        : word parameter
  128.      E000:0100   : double word parameter
  129.  
  130.      Registers can be used in place of bytes or words in an expression. For
  131.      example, the command 'U CS:IP-10' will start unassembling instructions
  132.      ten bytes before the current instruction pointer address. The
  133.      following register name may be used in an expression: AL, AH, AX, BL,
  134.      BH, BX, CL, CH, CX, DL, DH, DX, DI, SI, BP, SP, IP, CS, DS, ES, SS, or
  135.      FL
  136.  
  137. 03.08.01 Specifying Memory Addresses
  138.  
  139.      Many Soft-ICE commands require memory addresses as parameters. A
  140.      memory address is a value that is made of two 16-bit words, separated
  141.      by a colon. The first word is the segment address, and the second word
  142.      is the segment offset.
  143.  
  144.      Public symbols can be used in place of an address in any Soft-ICE
  145.      command. The public symbols must have been loaded with the Soft-ICE
  146.      program loader (LDR.EXE). See chapter 7 (Symbols and Source) for a
  147.      complete description of using public symbols.
  148.  
  149.      The Soft-ICE expression evaluator recognizes several special
  150.      characters in conjunction with addresses. These special characters
  151.      are:
  152.  
  153.      $           : Current CS:IP.
  154.      @address    : Double Word Indirection
  155.      .number     : Source Line Number
  156.  
  157.      The $ character can be used in place of CS:IP when typing the address
  158.      of the current instruction pointer.
  159.  
  160.      The @ character allows you to refer to the double word pointed to by
  161.      the address. You can have multiple levels of @'s.
  162.  
  163.      If the . character precedes an address, the address will be
  164.      interpreted as a source line number in the current file, rather than
  165.      an actual address. This is only valid when source files are loaded.
  166.      The address is interpreted as a decimal number in this case. Examples:
  167.  
  168.      U.1234      : This command starts unassembling instructions at source
  169.                    line 1234 decimal.
  170.      U $-10      : This command unassembles instructions starting 10 bytes
  171.                    prior to the current instruction pointer.
  172.      G @SS:SP    : Assume you are at the first instruction of an interrupt
  173.                    routine. Entering this command will set a temporary break
  174.                    point at the return address on the stack and skip the
  175.                    interrupt routine.
  176.  
  177. 03.09 Function Keys
  178.  
  179.      Function keys can be assigned to any command string that can be typed
  180.      into Soft-ICE. Function keys can be assigned from the command line or
  181.      pre-initialized through the Soft-ICE definition file S-ICE.DAT.
  182.  
  183.      The default S-ICE.DAT that comes on the Soft-ICE distribution diskette
  184.      has definitions for all 12 function keys. You can change any of these
  185.      definitions at any time. They are intended as examples, but they are
  186.      designed to make easy for users of Microsoft's CodeView, Thee default
  187.      assignments are:
  188.  
  189.      F1  : Displays general help                             "^H;"
  190.      F2  : Toggles the register window                       "^WR;"
  191.      F3  : Changes current source mode                       "^SRC;"
  192.      F4  : Restores screen                                   "^RS;"
  193.      F5  : Returns to your program                           "^X;"
  194.      F6  : Toggles cursor between command window code window "^EC;"
  195.      F7  : Goes to current cursor line                       "^HERE;"
  196.      F8  : Single steps                                      "^T;"
  197.      F9  : Sets break point at current cursor line           "^BPX;"
  198.      F10 : Program steps                                     "^P;"
  199.      F11 : Go to return address (large model)                "^G @SS:SP;"
  200.      F12 : Displays Soft-ICE version number                  "^VER;"
  201.  
  202.      A caret (^) preceding a command makes it invisible, a semi-colon (;)
  203.      following a command represents a carriage return. You can display the
  204.      current function key assignments by entering the command:
  205.  
  206.      FKEY
  207.  
  208.      To use a function key simply press the function key instead of
  209.      entering the command. To program function keys see section 5.8 for a
  210.      description of the FKEY command, or chapter 6 for a description of
  211.      pre-initializing function keys in S-ICE.DAT.
  212.  
  213. 03.10 Help
  214.  
  215.      The help command displays a short description, a syntax expression,
  216.      and an example of each command. To display help information, enter:
  217.  
  218.      ? or H : displays short descriptions of all commands and operators
  219.      ? command or H command : displays more detailed information on the
  220.                               specified command, syntax, and an example
  221.      ? expression or H expression : displays the value of the expression
  222.                                     in hexadecimal, decimal and ASCII
  223.  
  224. 03.11 Tutorial
  225.  
  226.      The following tutorial demonstrates a few of the features Soft-ICE and
  227.      gives you the opportunity to try using Soft-ICE. Soft-ICE can be used
  228.      in conjunction with another debugger or as a stand-alone debugger. The
  229.      tutorial demonstrates using Soft-ICE as an assistant to the DOS
  230.      debugger, DEBUG, and then shows how Soft-ICE can be used as a
  231.      stand-alone debugger with source and symbols loaded. DEBUG can be
  232.      found on the PCDOS or MSDOS system diskette. If you do not have DEBUG,
  233.      you can use another debugger in its place, or Soft-ICE can be used as
  234.      a stand-alone debugger.
  235.  
  236.      Users who need to use Soft-ICE for a reverse engineering project, or
  237.      for debugging DOS loadable device drivers or Terminate and Stay
  238.      Resident programs should go through this tutorial too. Even though
  239.      examples of these types of programs are not demonstrated directly, you
  240.      will get an overview of debugging with Soft-ICE. It is recommended
  241.      that you experiment with Soft-ICE and your particular environment
  242.      before beginning a real project.
  243.  
  244.      A short assembly language program with a subtle flaw is used to
  245.      demonstrate hardware-style break points. The sample program has been
  246.      kept intentionally short and to-the-point for those not very familiar
  247.      with assembly language. The tutorial is designed to give you a peek at
  248.      Soft-ICE features. Feel free to experiment on your own after going
  249.      through the tutorial.
  250.  
  251.      Since Soft-ICE is very flexible, it allows you to load in the way that
  252.      is best for your system. Go through the installation procedures in
  253.      section 2.2 before continuing with the tutorial.
  254.  
  255.      If you do not have extended memory on your system, you must load
  256.      Soft-ICE from the command line. When loading Soft-ICE from the command
  257.      line you can not load symbols or source files. In this case you must
  258.      improvise in the last section of the tutorial where Soft-ICE is used
  259.      as a stand-alone debugger.
  260.  
  261.      Soft-ICE can be loaded from the DOS prompt or loaded as a device
  262.      driver in CONFIG.SYS. For the purpose of this tutorial you should
  263.      install Soft-ICE in CONFIG.SYS with at least 50K of extended memory
  264.      reserved for symbols and source files. Soft-ICE should be the first
  265.      device driver installed in CONFIG.SYS. The device installation line
  266.      should look like:
  267.  
  268.      DEVICE = drive: path\S -ICE.EXE /SYM 50
  269.  
  270.      The /SYM 50 parameter instructs Soft-ICE to reserve 50 kilobytes of
  271.      extended memory for symbols and source file This is not enough to
  272.      solve most real world problems, but will work for our sample program.
  273.      You must re-boot your system after placing this line in CONFIG.SYS.
  274.  
  275.      When you re-boot your system Soft-ICE displays a copyright notice, a
  276.      registration number, the name of the person who owns this copy of
  277.      Soft-ICE, and the amount a extended memory reserved for each Soft-ICE
  278.      component. On a system with 384K of extended memory the initial screen
  279.      looks like:
  280.  
  281.       Soft-ICE Exact /Out Rage Pirates Registration # SI123456
  282.       (C) Nu-Mega Technologies 1987-1989 All Rights Reserved.
  283.       Soft-ICE Version 2.00
  284.       Soft-ICE is loaded from 00132000H up to 00160000H.
  285.       50K of symbol space reserved.
  286.       10K of back trace space reserved.
  287.       200 K of extended memory available.
  288.  
  289.      The "Soft-ICE is loaded ..." message tells you the exact area of
  290.      memory that Soft-ICE and its components are occupying. If you are on a
  291.      Compaq or Compaq clone and have included the word COMPAQ in your
  292.      S-ICE.DAT file you would also see a message saying "Using high memory
  293.      from XXXXXXXX to 00FE0000H".
  294.  
  295.      The next line tells you how much symbol space has been reserved. This
  296.      space is used for both symbols and source files.
  297.  
  298.      The next line tells you how much memory has been reserved for back
  299.      trace history. This amount defaults to 10K. This memory area is used
  300.      by the SNAP command and the BPR command with the T or TW options.
  301.  
  302.      The last line tells you how much memory is left for regular extended
  303.      memory. This memory can be used by other programs, such as HIMEM,
  304.      SMARTDRIVE, VDISK, etc.
  305.  
  306.      Change directories to the hard drive directory where you loaded all
  307.      the files from your distribution diskette. Remember, this directory
  308.      must be accessible from your alternate path list.
  309.  
  310.      Before we get into heavy debugging, let's bring the Soft-ICE window up
  311.      and give it a test drive. Clear the screen by entering : CLS and bring
  312.      up the Soft-ICE window by pressing : CTRL D.
  313.  
  314.      The Soft-ICE window is now on the screen. If you have file S-ICE.DAT
  315.      accessible from your path then the Soft-ICE window will occupy the
  316.      entire screen. It will be divided into four sections. From top to
  317.      bottom, these sections are the register window, the data window, the
  318.      code window, and the command window. If S-ICE.DAT was not found then
  319.      you will have a small window in the center of the screen. This also
  320.      means that other components needed for the tutorial have not been
  321.      loaded.
  322.  
  323.      If the small window is visible you should:
  324.  
  325.      1. Exit from Soft-ICE by entering X.
  326.      2. Unload Soft-ICE by entering S-ICE /U.
  327.      3. Copy the file S-ICE.DAT from the distribution diskette to a
  328.      directory accessible from your current path.
  329.      4. Restart the demo.
  330.  
  331.      We will now switch to the small window. The small window is very
  332.      convenient for using Soft-ICE as an assistant to another debugger.
  333.      Enter : WIN
  334.  
  335.      This will make a small command window in the center of the screen.
  336.      Several Soft-ICE commands are visible on this screen. These are
  337.      remnants of the initialization string in S-ICE.DAT that originally set
  338.      up Soft-ICE in the full screen mode. You will notice a prompt symbol
  339.      (:) and a status line at the bottom of the window.
  340.  
  341.      The Soft-ICE window can be moved around on the screen, and the window
  342.      size can be adjusted. Move the window around the screen by pressing:
  343.  
  344.      CTRL UP     : moves the window one row up
  345.      CTRL DOWN   : moves the window one row down
  346.      CTRL RIGHT  : moves the window one column right
  347.      CTRL LEFT   : moves the window one column left
  348.  
  349.      Change the window size so that it fills the whole screen by entering :
  350.      WIN. You will notice that the original screen is back. Change back to
  351.      the small window by entering WIN again. Make the window taller or
  352.      shorter by pressing :
  353.  
  354.      ALT UP      : makes the window taller
  355.      ALT DOWN    : makes the window shorter
  356.  
  357.      Now try what comes naturally when you're in front of a new program and
  358.      you don't have the foggiest notion of what to do next, ask for help.
  359.      Get a help display by entering : ?
  360.  
  361.      Notice how the display stops and waits for a keystroke before
  362.      scrolling any information off the screen. Look at the status line at
  363.      the bottom of the window. The status line displays the instructions:
  364.      "Any Key To Continue, ESC to Cancel ". Now press any key to continue
  365.      displaying more the help information. Continue pressing the key until
  366.      the prompt (:) reappears.
  367.  
  368.      Scroll back through the help information by pressing : SHIFT.
  369.      Previously displayed information in the command window can be scrolled
  370.      with the shift up, shift down, page up and page down keys. Try a
  371.      variety of these keys to scroll through the help information.
  372.  
  373.      The Soft-ICE help facility gives you an overview of each command. If
  374.      you enter a question mark (?) followed by a command name, you see a
  375.      display showing the command syntax, a short description of the
  376.      command, and an example. Try experimenting with help by entering
  377.      commands in this format: ? command.
  378.  
  379.      For example, ? ALTKEY. Pay attention to the status line prompts on the
  380.      bottom line of the screen if you get confused.
  381.  
  382.      The help command also allows you to evaluate hexadecimal expressions.
  383.      For example, enter : ? 10*2+42. The resulting display shows you the
  384.      value of the expression, first in hexadecimal, then decimal, then in
  385.      ASCII representation : 0062 00098 "b"
  386.  
  387.      We brought up the window with the CTRL D key sequence. That's all
  388.      right for some, but you may prefer to use another key sequence. We are
  389.      now going to enter a command to change the key sequence required to
  390.      bring up the window. We'll do this one step at a time, so you can get
  391.      used to the status line at the bottom of the window.
  392.  
  393.      Type the letter 'A'. The status line displays a list of all the
  394.      commands starting with the letter 'A'. Finish typing the word
  395.      'ALTKEY'. The status line now displays a short description of the
  396.      /ALTKEY command Press the space bar. The status line now shows the
  397.      required syntax for the /ALTKEY command. Type the letters 'ALT D' then
  398.      press ENTER to enter the entire command : ALTKEY ALTD
  399.  
  400.      You just changed the window pop up key sequence to ALT D. From now on,
  401.      you must press the ALT D key sequence to pop up the window. This is
  402.      assumed throughout the remainder of the tutorial. Now let's test the
  403.      previous command. To exit from the window, press : ALT D
  404.  
  405.      The Soft-ICE window just disappeared. To return to the Soft-ICE
  406.      window, release the ALT key, then press: ALT D The window returned.
  407.  
  408.      To see some previous commands, press: the UP key a few times. Notice
  409.      that Soft-ICE remembers commands that have been entered. Try editing
  410.      one just for fun. Some of the editing keys are:
  411.  
  412.      INS         : toggles insert mode
  413.      DEL         : deletes the current character
  414.      HOME        : moves the cursor to start of the line
  415.      END         : moves the cursor to the end of the line
  416.      LEFT        : Moves the cursor one column to the right
  417.      RIGHT       : Moves the cursor one column to the left
  418.  
  419.      When insert mode is on, notice that the cursor is in a block shape.
  420.  
  421.      Now that you are somewhat familiar with the environment let's try some
  422.      more commands. Erase the command you were editing by pressing the HOME
  423.      key, then pressing the DEL key until the command is gone. Enter : WR.
  424.  
  425.      The WR command makes the register window visible. The register window
  426.      displays the contents of the 8086 registers. Notice that the register
  427.      values reflect the location where the code was executing when you
  428.      invoked Soft-ICE.
  429.  
  430.      The WR command is assigned to the function key F2 in the Soft-ICE
  431.      initialization file S-ICE.DAT. Press the F2 key several times and you
  432.      will see the register window toggle on and off. Leave the register
  433.      window visible.
  434.  
  435.      Extend the vertical size of the Soft-ICE window by holding down the
  436.      ALT and the until the window is the entire length of the screen.
  437.      Notice the values of the CS and IP registers in the register window,
  438.      then enter : MAP
  439.  
  440.      The MAP command displays a system memory map. The area of the current
  441.      instruction pointer (CS:IP) is highlighted. If you have a complex
  442.      memory map you may have to press a key a few times until the until the
  443.      prompt reappears.
  444.  
  445.      Now try the following sequence a few times, noticing the (CS:IP)
  446.      registers in the register window. ALT D, release ALT and D, ALT D
  447.  
  448.      Each time you bring the Soft-ICE window back up you will notice that
  449.      the CS and IP registers have changed. When CS and IP change you can
  450.      enter the MAP command again to see if the instruction pointer now
  451.      points to a different area. This little exercise demonstrates that
  452.      Soft-ICE is a system level debugger that pops up wherever the
  453.      instruction pointer happens to be when you press the Soft-ICE hot key
  454.      sequence. The instruction pointer is continuously changing because
  455.      there is a lot of activity happening behind the scenes even when you
  456.      are at the DOS prompt, such as timer interrupts, DOS device driver
  457.      polling, DOS busy waiting other interrupts, etc.
  458.  
  459.      Press the F12 function key. The F12 function key defaults to be
  460.      assigned to the Soft-ICE VER command. It displays the Soft-ICE
  461.      copyright message and the version number.
  462.  
  463.      We will now assign the F12 function key to the Soft-ICE RS command.
  464.      Enter : RS. This will temporarily show the program screen without the
  465.      Soft-ICE window. Press the space bar to get back to get back the
  466.      Soft-ICE window. Enter : FKEY F12 RS;
  467.  
  468.      This assigns the RS command to the F12 key. The semi-colon represents
  469.      the ENTER key. Press the F12 key. Repeat this a few times to toggle
  470.      between the Soft-ICE window and the program screen. Now make sure the
  471.      Soft-ICE window is displayed, by pressing the F12 key if necessary.
  472.      You will notice RS displayed several times in the window. There is one
  473.      occurrence for each time you pressed the F12 key to show the program
  474.      screen.
  475.  
  476.      Clear the Soft-ICE window by entering : CLS. Enter : FKEY F12 ^RS;.
  477.      The ^ symbol assigns the RS command to the F12 key, but makes it an
  478.      invisible command. Press the F12 key several times. Notice that the RS
  479.      command no longer displays in the Soft-ICE window. You can also assign
  480.      a sequence of Soft-ICE commands to a function key. Remember to place a
  481.      carriage return between each command.
  482.  
  483.      Now let's prepare to use Soft-ICE as an assistant to the MSDOS DEBUG
  484.      utility. Get rid of the register window by pressing the F2 then shrink
  485.      the window size down to about 6 lines by Using ALT. Enter : ACTION
  486.      INT3
  487.  
  488.      This command tells Soft-ICE to generate interrupt 3's when break point
  489.      conditions are met. That's how Soft-ICE will communicate with DEBUG.
  490.      The default setting is HERE. ACTION HERE will cause control to return
  491.      directly to Soft-ICE. Use ACTION HERE when using Soft-ICE as a
  492.      stand-alone debugger.
  493.  
  494.      For those of you not using DEBUG with this tutorial you might have to
  495.      improvise now. CODEVIEW works with ACTION NMI. Most other debuggers
  496.      will work with ACTION set to INT3. If your debugger doesn't, and you
  497.      need help improvising, refer to the complete description ACTION (see
  498.      section 5.4).
  499.  
  500.      To make the Soft-ICE window disappear again, enter : X. This is an
  501.      alternative method to exit from Soft-ICE. This especially useful in
  502.      function key definitions.
  503.  
  504.      Now that you are familiar with some of the basics of using Soft-ICE,
  505.      let's learn some details by debugging the sample program (SAMPLE.ASM).
  506.      SAMPLE.ASM is a simple program written in assembly language by a
  507.      programmer named Jed. The program reads a keystroke from DOS and
  508.      displays a message telling whether the keystroke was a space.
  509.  
  510.      To run the program SAMPLE, at the DOS prompt, enter : SAMPLE
  511.  
  512.      Now press the space bar. Press several keys. Jed's program obviously
  513.      has a problem! Jed has spent hours studying this source code and is
  514.      certain there are no flaws in his logic. However, Jed borrowed some
  515.      'helper' routines from his friend Jake (get_key, is_space?). Jed is
  516.      somewhat suspect these routines but he cannot find the bug. The source
  517.      code for Jed's program looks like this:
  518.  
  519.              Page    55,80
  520.              Title   Sample
  521.  
  522.      DATA Segment Public 'Data'
  523.      pad             db      12H dup(O)
  524.      char            db      0
  525.      answer          db      0
  526.      space_msg       db      'The Character is a SPACE',0DH,0AH,'$'
  527.      no_space_msg    db      'The Character is NOT a'
  528.                      db      'SPACE',0DH,0AH,'$'
  529.      DATA Ends
  530.  
  531.      STACK Segment Stack 'Stack'
  532.              Dw          128 Dup (?)                         ;Program stack
  533.      STACK Ends
  534.  
  535.      CODE Segment Public 'Code'
  536.              Assume CS:CODE,DS:DATA,ES:Nothing,SS:STACK
  537.  
  538.      start:
  539.              mov     ax,DATA                                 ; Set up segments
  540.              mov     es,ax
  541.              mov     ds,ax
  542.  
  543.      main_loop:                                              ; Main Program Loop
  544.              call    get_key
  545.              call    is_space
  546.              cmp     answer,0
  547.              je      no_space
  548.  
  549.      ; It's a space, so display the space message
  550.              mov     ah,9
  551.              mov     dx,offset space_msg
  552.              int     21H
  553.              jmp     main_loop
  554.  
  555.      ; It's NOT a space, so display the no space message
  556.      no_space:
  557.              mov     ah,9
  558.              mov     dx,offset no_space_msg
  559.              int     21H
  560.              jmp     main_loop
  561.  
  562.      ;----------------------------------------------------------;
  563.      ; JAKE'S ROUTINES                                          ;
  564.      ;----------------------------------------------------------;
  565.      ; Get Key Routine (one of Jake's routines)
  566.  
  567.      get_key proc
  568.              mov     ah,8
  569.              int     21H
  570.              mov     char,al
  571.              ret
  572.      get_key endp
  573.  
  574.      ; Check if character is a space (one of Jake's routines)
  575.      is_space proc
  576.              cmp     char,20H
  577.              jne     not_space
  578.              mov     answer, 1
  579.              ret
  580.      not_space:
  581.              mov     cs:answer,0
  582.              ret
  583.      is_space endp
  584.  
  585.      CODE Ends
  586.  
  587.              End.
  588.  
  589.      Jed has been using DEBUG but has not been able to pinpoint the
  590.      problem. As a recommendation from his nephew Jethro, Jed has purchased
  591.      Soft-ICE. He was somewhat reluctant to use it because he had tried a
  592.      hardware-assisted debugger but could never get it working quite right.
  593.      He was willing to try Soft-ICE because he could continue to use DEBUG
  594.      -- the only debugger he really understood.
  595.  
  596.      Press CTRL C to break out of the program. Enter the following
  597.      commands:
  598.  
  599.      DEBUG drive:\pathname\SAMPLE. EXE
  600.      U
  601.      R
  602.  
  603.      In the hours Jed has spent trying to find this elusive bug, he has had
  604.      the suspicion that something is overwriting his code in some subtle
  605.      way. With Soft-ICE, Jed decides to set a range break point across his
  606.      code segment. Press : ALT D. The Soft-ICE window is back. Move the
  607.      window (by using CTRL and the Arrow keys) until DEBUG's register
  608.      display is visible.
  609.  
  610.      It's time to set our first break point. Enter : BPR code-seg:0
  611.      code-seg:25 W
  612.  
  613.      Code-seg is the value in the CS register as displayed by the DEBUG R
  614.      command.
  615.  
  616.      The BPR command sets a memory-range break point. The length of Jed's
  617.      code segment is 25H bytes, so the memory range specified goes from the
  618.      beginning of his code segment to the end. The W tells Soft-ICE to
  619.      break on a write. We want to catch any unexpected writes to Jed's
  620.      code.
  621.  
  622.      Enter : BL
  623.  
  624.      The BL command displays all break points. The display from BL looks
  625.      similar to the following display :
  626.  
  627.      0) BPR code-seg:0000 code-seg:0025 W C = 01
  628.  
  629.      The 0 is the identifier for this break point. The range and W are
  630.      displayed as they were entered, and the count (since none was
  631.      specified) defaults to one. Now comes the moment of truth. Press ALT D
  632.      The window disappears again. To run SAMPLE from DEBUG, enter : G.
  633.  
  634.      Press the space bar. Ok so far. Now press a non-space key. Our break
  635.      point just woke up DEBUG. The registers and single unassembled
  636.      instruction are displayed. Enter : U cs:address
  637.  
  638.      Address is the value of the IP register minus 10 hexadecimal. Since
  639.      DEBUG is rather primitive, the value of the IP register minus 10
  640.      hexadecimal must be calculated by hand. The instruction pointer is
  641.      pointing one instruction past the instruction that caused the break
  642.      point. By going back ten hexadecimal instructions, DEBUG should sync
  643.      up. The instruction at offset 3BH is:
  644.  
  645.      CS:
  646.      MOV BYTE PTR [13],0
  647.  
  648.      Jed says,"There it is! I just knew Jake's helper routines were the
  649.      problem! His code segment override instruction is writing a zero byte
  650.      right over my code! Who knows what that's doing!". Enter : U 0
  651.  
  652.      Location 13H happens to be the offset of a conditional jump
  653.      instruction. The relative offset of the conditional jump is being set
  654.      to zero. If you are an 8086 guru, you obviously know that the JE will
  655.      ALWAYS fall through if the relative offset is zero. What a subtle BUG!
  656.  
  657.      Now we will take a quick look at how this problem would be solved
  658.      using Soft-ICE as a stand-alone debugger. But first we must exit from
  659.      debug.
  660.  
  661.      Before exiting the debugger, it's always a good idea to disable all
  662.      the break points, unless ACTION is set to HERE. If you do not do this,
  663.      when a break point occurs and ACTION tries to return to a debugger
  664.      that is not loaded, the results are unpredictable. We've changed the
  665.      ACTION to INT3, so we have to disable the break point. To bring up the
  666.      window, press : ALT D. List the break point by entering : BL
  667.  
  668.      Notice that the break point description line is highlighted. The
  669.      highlighted break point is the last break point that occurred. Notice
  670.      that the break point number is 0. To disable break point zero, enter :
  671.      BD 0
  672.  
  673.      List the break point again by entering : BL. The asterisk (*) after
  674.      the break point number shows that the break point is disabled. To
  675.      clear the break point, enter : BC 0
  676.  
  677.      Enter BL again. Notice that there are no break point lines displayed.
  678.      Exit from Soft-ICE, then exit from the debugger, by entering :
  679.  
  680.      X
  681.      Q
  682.  
  683.      The next part of the tutorial demonstrates how Soft-ICE can be used to
  684.      find the same problem as a stand-alone debugger. Soft-ICE will be used
  685.      as a source level debugger. To prepare Soft-ICE to debug at source
  686.      level it must have been installed in your CONFIG.SYS file, and
  687.      extended memory allocated for symbols and source files. Soft-ICE can
  688.      only be used as a source level debugger if you have extended memory on
  689.      your system. If you do not have extended memory you may still want to
  690.      read through the rest of the tutorial to see the capabilities of
  691.      Soft-ICE with extended memory. If you have not loaded S-ICE.EXE in
  692.      your CONFIG.SYS file with memory reserved for symbols, do so at this
  693.      time.
  694.  
  695.      To debug the sample program with Soft-ICE as a stand-alone debugger we
  696.      must use the Soft-ICE program loader (LDR.EXE). To load the sample
  697.      program (SAMPLE.EXE), the symbol file (SAMPLE.SYM) and the source file
  698.      (SAMPLE.ASM) enter at the DOS prompt :LDR SAMPLE
  699.  
  700.      You are now in Soft-ICE with SAMPLE.EXE loaded into memory. Notice
  701.      that Soft-ICE occupies the full screen. Soft-ICE switches to its wide
  702.      mode whenever a program loaded. The source from SAMPLE.ASM should be
  703.      visible in the code window. In addition, the register window and the
  704.      DATA windows are visible.
  705.  
  706.      Step through one instruction by pressing F10. Notice that the reverse
  707.      video bar moves to the next instruction to be executed after a program
  708.      step.
  709.  
  710.      Press F6. This places the cursor in the code window. Now experiment
  711.      with the Up, Down, pageUp, and pageDn keys to move the cursor and
  712.      scroll the source file. Move the cursor down to line 42 with the DOWN
  713.      key. Press F9.
  714.  
  715.      We have just set an execution break point on line 42. The line should
  716.      be highlighted, showing you that a break point has been set on it.
  717.      Enter : BL. This shows the break point that we have just set.
  718.  
  719.      Now press ALT D. This exits Soft-ICE, and causes the sample program to
  720.      execute until it encounters the break point on line 42. Soft-ICE
  721.      should immediately come back, with the reverse video bar on line 42.
  722.  
  723.      Press F6 again. This will bring the cursor back to the command window.
  724.      Now enter : BC *. This will clear all the break points (there should
  725.      only be one set). Now exit from Soft-ICE by pressing ALT D. You are
  726.      back to the sample program. Type a few keys just to make sure it is
  727.      still broken.
  728.  
  729.      Now pop Soft-ICE back up with ALT D. Since the bug has already
  730.      occurred, we want to restart the program. Enter : EXIT RD. This
  731.      command forces the sample program to exit. The R tells Soft-ICE to
  732.      restore the interrupt vectors to the state they were when the sample
  733.      program was loaded with LDR. The D tells Soft-ICE to delete any
  734.      currently pending break points. The R and the D are not necessary in
  735.      this case, but it is good to get in the habit of specifying them when
  736.      exiting a program that was loaded with LDR.EXE.
  737.  
  738.      You are now back at the DOS prompt. Reload the program by entering :
  739.      LDR SAMPLE.EXE
  740.  
  741.      Notice the suffix.EXE was specified this time. When the suffix is
  742.      specified, Soft-ICE does not attempt to load a symbol file or source
  743.      file. In this case the symbol file and source file are already in
  744.      memory. Enter : SYM. This displays the public symbols of the sample
  745.      program. Press Esc to get back to the prompt.
  746.  
  747.      We will now set a range break point similar to the one we set while
  748.      using Soft-ICE as an assistant to debug. This time we will use symbols
  749.      to set the break point. Enter : BPR START .82 W. This will set a range
  750.      break point in our code segment from the symbol START to line 82 of
  751.      the source file. Enter : BL. You can verify that the break point has
  752.      been set properly.
  753.  
  754.      Press ALT D. Press a non-space key. We're back in Soft-ICE. Notice
  755.      that the current instruction (the line with the reverse video bar) is
  756.      the instruction after the one that caused the break point.
  757.  
  758.      To see the actual code press the F3 key. This places Soft-ICE in mixed
  759.      mode. Notice that the reverse video bar covers 2 lines. This is the
  760.      actual code line and the source code line of the current instruction.
  761.      Press the F3 key again. We are now in code mode. No source lines are
  762.      visible. The instruction above the reverse video bar is the
  763.      instruction that caused the range break point to go off. Press the F3
  764.      key again to get back to source mode.
  765.  
  766.      Now we will fix the bug in the sample program. Exit the sample program
  767.      and go back to the DOS prompt by entering : EXIT RD. Re-load the
  768.      sample program by entering : LDR SAMPLE. EXE. Set the code window in
  769.      code mode by pressing the F3 key twice.
  770.  
  771.      Un-assemble at the broken routine by entering : U not_space.
  772.  
  773.      We will now use the Soft-ICE interactive assembler to fix the problem.
  774.      Enter: A not_space. Soft-ICE will prompt you with the address. Enter:
  775.      NOP
  776.  
  777.      Press ENTER to exit from the assembler. Notice in the code window that
  778.      there is a NOP instruction in place of the CS over-ride at offset
  779.      003BH. Press the F3 key to get back to source mode, (the source code
  780.      of course is not modified). Press ALT D to run the mended sample
  781.      program. Enter spaces and some non-spaces characters. It works! You
  782.      fixed the bug! To get out of Jed's program, and return to DOS, press :
  783.      CTRL C
  784.  
  785.      Now we're going to demonstrate another feature of Soft-ICE. Enter :
  786.      LDR SAMPLE.EXE. This will load the sample program in one more time.
  787.      Enter : RIP HANG_EXAMPLE
  788.  
  789.      The first two displayed instructions are:
  790.  
  791.      CLI
  792.      JMP $
  793.  
  794.      Notice that the jump instruction jumps to itself. This infinite loop
  795.      would normally hang the system in an unrecoverable fashion. Enter :
  796.      BREAK ON. We have just turned on BREAK mode. BREAK mode will cause the
  797.      system to run slightly slower, but will allow Soft-ICE to come up even
  798.      when the system would normal be hung.
  799.  
  800.      Exit from Soft-ICE by pressing ALT D. Your system is now hung. For
  801.      those non-believers, press : CTRL ALT DEL
  802.  
  803.      Nothing happens! It is definitely hung. Now press ALT D. The Soft-ICE
  804.      window is back! To get out of the infinite loop, enter : EXIT RD. You
  805.      are now back at DOS. Try a few directories to get a feel for the
  806.      performance degradation. Many people feel comfortable leaving BREAK ON
  807.      as a configuration default.
  808.  
  809.      Turn BREAK mode off again by entering : BREAK OFF. Do a few
  810.      directories to get a comparison of the speed. That's it! Have fun!
  811.      It's time to start experimenting and debugging on your own. Browse
  812.      through the rest of the manual and refer to specific sections when
  813.      necessary.
  814.