home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / progasm / ad86v322.arj / D05.DOC < prev    next >
Text File  |  1988-05-20  |  13KB  |  264 lines
  1. CHAPTER 5   COMMAND LANGUAGE
  2.  
  3. In addition to immediate-execution assembly language commands,
  4. there is a set of commands recognized by the debugger.  They are
  5. identified by the first keyword on the line being a single letter
  6. (i.e., the second character of the line is a non-letter, usually
  7. a comma or ENTER).
  8.  
  9.  
  10. General Operands to Debugger Commands
  11.  
  12. Most of the debugger commands consist of their single-letter
  13. identifier, followed by a comma, followed by one or more general
  14. operands, separated by commas.  General operands can be one of
  15. the following:
  16.  
  17.    a. a numeric constant, whose format is just as in the assembly
  18.       language (leading zero means default hex, otherwise default
  19.       decimal)
  20.  
  21.    b. a register name
  22.  
  23.    c. a user symbol from the assembly language program being
  24.       debugged.
  25.  
  26.  
  27. Format of Debugger Command Examples
  28.  
  29. Many of the examples given below will be given in double quotes.
  30. Note that the double quotes are not part of the command.  You are
  31. encouraged to try out the example on the debugger, by typing the
  32. string within the quotes, not including the quotes, and always
  33. followed by the ENTER key. Note further that the double-quoted
  34. string may be broken across two lines of this manual, but that
  35. does not mean you should type an ENTER where the string is broken
  36. --debugger commands always consist of a single line, always
  37. terminated by ENTER.
  38.  
  39.  
  40. The Debugger Command Set
  41.  
  42. Following is a description of the debugger commands recognized:
  43.  
  44. B  sets and clears the fixed breakpoints of the program.  The
  45.    debugger has four breakpoints.  Two are transitory; they are
  46.    automatically cleared after each return from the program to
  47.    the debugger.  They can be set by the G command. The other two
  48.    are fixed-- they will remain in effect until you explicitly
  49.    clear them.  The fixed breakpoints are controlled by this B
  50.    command.
  51.  
  52.    You follow the B with zero, one, or two general operands.  If
  53.    there are zero operands (the B is followed immediately by an
  54.    ENTER), then both fixed breakpoints are cleared.  If there are
  55.    one or two operands, then the fixed breakpoints are set to the
  56.    operands.
  57.                                                               5-2
  58.  
  59.    Note that previously-set breakpoints can be implicitly
  60.    cleared, by overwriting them with other breakpoints.  If your
  61.    B command has one operand, and there was one breakpoint
  62.    previously set, the debugger sets the unused breakpoint, so
  63.    that both remain in effect.  If your B command has one
  64.    operand, and both breakpoints were previously set, the most
  65.    recently set breakpoint is saved, and the older breakpoint is
  66.    overwritten.
  67.  
  68.    The status screen, displayed by typing Ctrl-S, shows you the
  69.    B-command breakpoints in effect.
  70.  
  71.    Examples: if you type "b,numout", the debugger will set a
  72.    breakpoint at location NUMOUT, which should be a label in the
  73.    program being debugged. You may start and stop the program
  74.    many times, and the breakpoint will stay there.  You may even
  75.    allow the program to stop at NUMOUT repeatedly; the breakpoint
  76.    is not cleared even if the program stops there.  If you
  77.    subsequently type the command "b,01000", then there will be
  78.    breakpoints at both NUMOUT and location hex 01000.  If you
  79.    then type "b,01200", the first breakpoint NUMOUT is
  80.    overwritten; the two breakpoints now in effect are 01000 and
  81.    01200.  The 01000 breakpoint will be next in line to be
  82.    overwritten.  You may clear both breakpoints by typing "b".
  83.    There is no way to clear one breakpoint at a time.
  84.  
  85.  
  86. D  sets or clears a data breakpoint.  This command is available
  87.    only to registered D86 users running on a 386-based machine. A
  88.    data breakpoint causes the program to trap to the debugger
  89.    whenever a specified memory location is accessed.  The trap
  90.    occurs after the instruction causing the access, so you should
  91.    press the Up-arrow key to see the instruction.
  92.  
  93.    You follow the "D" with a comma, followed by a specification
  94.    parameter.  The parameter consists of up to three characters,
  95.    at most one each from the following categories:
  96.  
  97.    1. A letter giving the size of the memory element being
  98.       checked: B for byte, W for word, D for doubleword, or a
  99.       minus sign if you are clearing the breakpoint.  Default is
  100.       B.
  101.  
  102.    2. The letter R if you wish to trap if the memory location is
  103.       either written to or read from.  If you leave the R out,
  104.       the trap will occur only if the memory location is written
  105.       to.
  106.  
  107.    3. A digit, (0,1,2, or 3) giving the number of the 386
  108.       breakpoint register you are using to set the trap.  Default
  109.       is 0.
  110.                                                               5-3
  111.  
  112.    You terminate the specification parameter with a comma, then
  113.    provide one or two numbers to specify the memory location you
  114.    are trapping. If you provide two numbers, the first is the
  115.    segment register value and the second is the offset.  If you
  116.    provide only one number, it is the offset-- the value of DS is
  117.    used as the segment register value. As with all value
  118.    parameters in D86, you can give a register name or a label
  119.    instead of a number.  You can also leave out the address
  120.    entirely, to preserve the previous address setting of that
  121.    breakpoint register.
  122.  
  123.    Note that the 386 requires Word and Doubleword breakpoints to
  124.    be aligned in memory.  If you provide an odd address for a
  125.    Word breakpoint, the 386 will ignore the bottom bit of your
  126.    address.  Similarly, the 386 will ignore the bottom two bits
  127.    of your address for a Doubleword breakpoint.
  128.  
  129.    Examples: D,R1,ES,0400 sets a byte data read-or-write
  130.    breakpoint, using the 386's register number 1, at memory
  131.    location ES:0400.  D,-1 would clear that breakpoint.  D,R1
  132.    would set it again with its previous value.  D,W,MY_VAR sets a
  133.    Word breakpoint, using the 386's register number 0, at
  134.    location DS:MY_VAR-- the trap will occur if either byte of the
  135.    variable MY_VAR is written to (but MY_VAR should be aligned to
  136.    an even address for this to work).
  137.  
  138.    If the D command is enabled, you'll get a one-line display of
  139.    the data breakpoint registers in the status window (invoked
  140.    via Ctrl-S).  The registers are presented in order: 0,1,2,3.
  141.    The breakpoint type is given, followed by the 5-digit absolute
  142.    memory address of the breakpoint.
  143.  
  144.  
  145. F  finds a string of memory bytes.  The memory to be searched
  146.    starts at the current CS:IP location.  The string being sought
  147.    is contained in memory at the CS:IP location marked with the
  148.    last Shift-F7 command.  The number of bytes in the target
  149.    string is given as the first operand to the F command.  For
  150.    example, "F,1" finds the next instance of a single byte value
  151.    after the current CS:IP.  If the marked location points to a
  152.    NOP, "F,1" will find the next NOP code.
  153.  
  154.    If you provide a second operand to F, it is a "retreat
  155.    number".  For example, "F 2,10" assumes that you are looking
  156.    for a 2-byte sequence, and you have retreated 10 bytes from
  157.    the starting location for your search.  When the string is
  158.    found, F will retreat 10 bytes from that string.  That way you
  159.    can view the instructions that preceded the found string.  I
  160.    use this feature when I am searching for BIOS and DOS
  161.    interrupt calls in a program.  I want to retreat before the
  162.    calls, to see what function numbers were loaded into
  163.    registers.  I can use the F3 key to repeat the searches,
  164.    giving me a sequence of disassembly displays with the
  165.    interrupt in the middle.
  166.                                                               5-4
  167.  
  168.    F with no operands returns CS:IP to the marked location, in
  169.    case you want to use F7 to deposit another string to be
  170.    searched.
  171.  
  172.    If you have never pressed Shift-F7 in this session, the marked
  173.    location is 0C000 of the program's starting segment.  That's
  174.    often a good "scratchpad" area for small programs, far from
  175.    both the program and the stack.
  176.  
  177.  
  178. G  starts the user program.  You can give one or two operands to
  179.    G, specifying locations within the program at which you wish
  180.    to return to the debugger.  These are "transitory
  181.    breakpoints"; both of them are cleared when the program
  182.    returns to the debugger for any reason.
  183.  
  184.    Whenever you start the program, at least one instruction from
  185.    the program will be executed, even if there is a breakpoint at
  186.    the current instruction pointer location.  This means you can
  187.    set a breakpoint at the current location; instructing the
  188.    program to return to the debugger the next time it gets back
  189.    to the current location.
  190.  
  191.  
  192. J  jumps to the location indicated by the operand, within the
  193.    current code segment.  J is useful when you are exploring
  194.    memory outside of your program's memory area.  In that case,
  195.    the immediate JMP command is executed from a buffer within
  196.    your program's original code segment.  JMP would therefore
  197.    return you to that segment.  J will keep you in the distant
  198.    segment.
  199.  
  200.  
  201. L  creates a disassembly listing, with addresses, hex bytes, and
  202.    disassembled code.  You can output either the entire COM
  203.    program, or a section of memory beginning with the current
  204.    CS:IP location.  You omit the first operand if you want the
  205.    entire COM program.  If you want a section of memory, you
  206.    provide the offset beyond the memory section as the first
  207.    operand.  You give the name of the output file for the listing
  208.    as the second operand.  If you omit the second operand, the
  209.    listing goes to the printer.  Examples: L,,FOO.LST outputs the
  210.    entire COM program to FOO.LST.  L,0200,SEG.LST outputs the
  211.    section of memory from CS:IP up to CS:0200 to SEG.LST.
  212.                                                               5-5
  213.  
  214. O  sets a special fixed breakpoint.  Whenever your program calls
  215.    MSDOS via INT 021, the debugger will monitor the function
  216.    number passed in the AH register.  If the function number
  217.    falls within the range specified by this command, the program
  218.    will trap back to the debugger.  If you give two operands to
  219.    O, the operands are the lower and upper bounds for the range
  220.    of trapped functions.  If you give one operand, only that
  221.    function number will be trapped.  If you give no operands, any
  222.    previous O-trap setting is cleared.
  223.  
  224.    For example, note that function 3F hex is the READ function
  225.    for MSDOS version 2.  If you want to trap whenever this READ
  226.    function is invoked, you can issue the command O,03F and then
  227.    start up your program with the G command.  Another example:
  228.    suppose you want to insure that a program does not make any of
  229.    the new Version 3 DOS calls, 59 hex and above.  You can issue
  230.    the command O,059,0FF and then start your program.
  231.  
  232.    NOTE: if the second operand is less than the first, then the
  233.    range wraps around through zero.  For example, O,059,030 traps
  234.    on 059 through 0FF, and also 0 through 030-- both version 3
  235.    and version 1 calls.
  236.  
  237.    SECOND NOTE: The EXIT function, hex 4C is always trapped by
  238.    D86, regardless of your O-command settings.  The only way you
  239.    should be able to exit from D86 is via the Q-command.  (If you
  240.    do succeed in exiting some other way, I want to hear about it.
  241.    In that case, D86 will become very confused if you reinvoke it
  242.    before rebooting the computer.)
  243.  
  244.  
  245. Q  exits the debugger and goes back to the operating system.
  246.  
  247.  
  248. W  writes the program (if it was a COM format) and the symbol
  249.    table back to the disk.  In this present version, you don't
  250.    have any options as to what to name the files.  The program
  251.    name given when D86 was invoked is always used, except that
  252.    the files are always written to the current directory.  The
  253.    program file has the same extension as the file that was
  254.    loaded, and the symbols file has the SYM extension.
  255.  
  256.    D86 writes the program from location 0100 in the original code
  257.    segment, up to the end-of-file location saved when the program
  258.    was loaded, and possibly extended by a patch-memory operation
  259.    while at the end of the program.  Any symbols added while in
  260.    the patch-memory mode are saved in the symbols file, so that
  261.    you can "reverse engineer" programs for which you do not have
  262.    source, and save the symbol table results you have gleaned.
  263.  
  264.