CHAPTER 4 - Using Break Point Commands

     04.00 Notationnal Conventions
     04.01 Introduction
     04.02 Setting Break Points
     04.03 Manipulating Break Points

04.00 Notationnal Conventions

     Section II contains syntax listings for each Soft-ICE command, and
     explanations and examples for each command. All numbers are in
     hexadecimal; any number can be an expression using +,-,/,*, or
     registers. All commands are case-insensitive. Words that are in
     italics the command syntax statements must be replaced by an actual
     value, rather than typing in the italicized word.

     The following notational conventions are used throughout this section

     [ ]
          Brackets enclose an optional syntax item.
     < >
          Angle brackets enclose a list of items or choices.
     x | y
          Vertical bars separate alternatives. Use item x or item y.
     count
          Count is a byte value that specifies the number of time break
          point conditions must be met before the actual break point
          occurs. If no count is specified, the default value is 1. Each
          time the Soft-ICE window is brought up, the counts are reset to
          the values originally specified.
     verb
          Verb is a value that specifies what type access the break point
          will apply to. It can be set to 'R' for reads, 'W' for write RW'
          for reads and writes, or 'X' for execute.
     address
          Address is a value that is made of two 16-bit words, separated by
          a colon. The first word is the segment address, and the second
          word is the segment offset. The addresses can be constructed of
          registers expressions, and symbols. The address may also contain
          the special characters "$", ".", and "@". See section 3-8
          (Command Syntax) for a description of these special characters.
     break-#
          Break-number is an identification number that identifies the
          break point to use when you are manipulating break points e.g.,
          editing, deleting, enabling, or disabling them). The break-number
          can be a hexadecimal digit from 0 to F.
     list
          List is a series of break-# separated by commas or spaces.
     mask
          Mask is a bitmask that is represented as: combination of 1's,
          0's, and X's. X's are don't-care bits.
     GT, LT GT and LT
          Command qualifiers that unsigned comparisons of values.

     Example : BPIO 21 W EQ M 1XXX XXXX

     This command will cause a break point to occur if port 21H is written
     to with the high order bit set.

04.01 Introduction

     Soft-ICE has break point capability that has traditionally only been
     available with hardware debuggers. The power and flexibility of the
     80386 chip allows advanced break point capability without additional
     hardware.

     Break points can be set on memory location reads and writes, memory
     range reads and writes, program execution and port accesses. Soft-ICE
     assigns a one-digit hexadecimal number (0-F) to each break point. This
     break-number is used to identify break points when you set delete,
     disable, enable, or edit them.

     All of Soft-ICE's break points are sticky. That means they don't
     disappear automatically after they've been used; you must
     intentionally clear or disable them using the BC or the BD commands.
     Soft-ICE can handle 16 break points at one time. You can have up to
     ten break points of a single type except for break points on memory
     location (BPMs), of which you can only have four, due to restrictions
     of the 80386 processor.

     Break points can be specified with a count parameter. The count
     parameter tells Soft-ICE how many times the break point should be
     ignored before the break point action occurs.

04.02 Setting Break Points

     BPM, BPMB, BPMW, BPMD Set break point on memory access or execution
     BPR Set break point on memory range
     BPIO Set break point on I/O port access
     BPINT Set break point on interrupt
     BPX Set/clear break point on execution
     CSIP Set CS:IP range qualifier
     BPAND Wait for multiple break points to occur

Set break point on memory access or execution

     Syntax :

          BPM[size]address[verb][qualifier value][C=count]

          Size :
               B(yte), W(ord), D(oubleword)
               The size is actually a range covered by this break point.
               For example, if double word is used, and the third byte of
               the double is modified, then a break point will occur. The
               size is also important if the optional qualifier is
               specified (see below).
          Verb :
               R, W, RW, or X
          Qualifier :
               EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
               M (Mask)
               These qualifiers are only applicable to the read and write
               break points.
          Value
               A byte, word, or double word value, depending on the size
               specified.

     Comments :

          The BPM commands allow you to set a break point on memory reads
          or writes or execution.

          If a verb is not specified, RW is the default. If a size is not
          specified, byte is the default.

          All of the verb types except X cause the program to execute the
          instruction that caused the break point. The current CS:IP will
          be the instruction after the break point. If the verb type is X,
          the current CS:IP will be the instruction where the break point
          was set.

          If R is specified, then the break point will occur on read access
          and on write operations that do not change the value of the
          memory location.

          If the verb type is R, W or RW, executing an instruction at the
          specified address will not cause the break point action to occur.

     Notes :

          If BPMW is used, the specified address must start on a word
          boundary. If BPMD is used, the specified address must point to a
          double word boundary.

     Example :

          BPM 1234:SI W EQ 10 C=3

          This command defines a break point on memory byte access. The
          third time that 10 hexadecimal is written to location 1234:SI,
          the break point action will occur.

          BPM CS:1235 X

          This command defines a break point on execution. The break point
          action will occur the first time that the instruction at address
          CS:1235 is reached. The current CS:IP will be the instruction
          where the break point was set.

          BPMW DS:FOO W EQ M 0XXX XXXX XXXX XXX1

          This command defines a word break point on memory write. The
          break point action will occur the first time that location DS:FOO
          has a value written to it that sets the high order bit to 0 and
          the low order bit to 1. The other bits can be any value.

          BPM DS:1000 W GT 5

          This command defines a byte break point on memory write. The
          break point action will occur the first time that location
          DS:1000 has a value written to it that is greater than 5.

Set break point on memory range

     Syntax :

          BPR start-address end-address [verb] [C=count]

          Start-address, end-address :
               start-address and end-address specify memory range.
          Verb :
               R, W, RW, T or TW

     Comments :

          The BPR command allows you to set a break point across a range of
          memory.

          All of the verb types except T or TW cause the program to execute
          the instruction that caused the break point. The current CS:IP
          will be the instruction after the break point.

          There is no range break point on execution. If a range break
          point is desired on execution, R must be used. An instruction
          fetch is considered a read for range break points.

          If a verb is not specified, W is the default.

          The range break point will degrade system performance in certain
          circumstances. Any read or write within the 4K page that contains
          the break point range is analyzed by Soft-ICE. This performance
          degradation is usually not noticeable, however, degradation could
          be extreme in exception cases.

          The T and TW verbs enable back trace ranges on the specified
          range. They do not cause break points, but instead log
          instruction information that can be displayed later with the SHOW
          or TRACE commands. For more information on back trace ranges, see
          chapter 9.

     Example :

          BPR B000:0 B000:1000 W

          This command defines a break point on memory range. The break
          point will occur if there are any writes to the monochrome
          adapter video memory region.

Set break point on I/O port access

     Syntax :

          BPIO port [verb] [qualifier value] [C=count]

          Port :
               A byte or word value.
          Verb :
               R (IN), W (OUT), or RW
          Qualifier :
               EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
               M (Mask)

     Comments :

          The BPIO command allows you to set a break point on I/O port
          reads or writes.

          If value is specified, it is compared with the actual data value
          read or written by the IN or OUT instruction causing the break
          point. The value may be a byte or a word. If the I/O is to a byte
          port, then the lower 8 bits are used in the comparison.

          The instruction pointer (CS:IP) will point to the instruction
          after the IN or OUT instruction that caused the break point.

          If a verb is not specified, RW is the default.

     Example :

          BPIO 21 W NE FF

          This command defines a break point on I/O port access. The break
          point will occur if the interrupt controller one mask register is
          written with a value other than FFH.

          BPIO 3FE R EQ M 11XX XXXX

          This command defines a byte break point on I/O port read. The
          break point action will occur the first time that I/0 port 3FE is
          read with a value that has the two high order bits set to 1. The
          other bits can be any value.

Set break point on interrupt

     Syntax :

          BPINT int-number [ < AL | AH | AX >= value] [C = count]

          Int-number :
               Interrupt number from 0 - FF hex
          Value :
               A byte or a word value

     Comments :

          The BPINT command allows breaking on the execution of a hardware
          or a software interrupt. By optionally qualifying the AX register
          with a value, specific DOS or BIOS calls can be easily isolated.

          If no value is specified, a break point will occur when the
          interrupt specified by int-number occurs. This interrupt can be a
          hardware, software, or internal interrupt.

          The optional value is compared with the specified register (AH,
          AL, or AX) when the interrupt occurs. If the value matches the
          specified register, then the break point will occur.

          When the break point occurs, if the interrupt was a hardware
          interrupt, the instruction pointer (CS:IP) will point to the
          first instruction within the interrupt routine. The INT? command
          can be used to see where execution was when the interrupt
          occurred. If the interrupt was a software interrupt, when the
          break point occurs, the instruction pointer (CS:IP) will point to
          the INT instruction causing the interrupt.

     Example :

          BPINT 21 AH=4C

          This command defines a break point on interrupt 21H The break
          point will occur when DOS function call 4CH (terminate program)
          is called.

Set/Clear break point on execution

     Syntax :

          BPX [address] [C=count]

     Comments :

          The BPX command allows you to set or clear a poin