home *** CD-ROM | disk | FTP | other *** search
/ Reverse Code Engineering RCE CD +sandman 2000 / ReverseCodeEngineeringRceCdsandman2000.iso / RCE / +Sandman / si-ug-chapter04.txt < prev    next >
Text File  |  2000-05-25  |  21KB  |  590 lines
  1. CHAPTER 4 - Using Break Point Commands
  2.  
  3.      04.00 Notationnal Conventions
  4.      04.01 Introduction
  5.      04.02 Setting Break Points
  6.      04.03 Manipulating Break Points
  7.  
  8. 04.00 Notationnal Conventions
  9.  
  10.      Section II contains syntax listings for each Soft-ICE command, and
  11.      explanations and examples for each command. All numbers are in
  12.      hexadecimal; any number can be an expression using +,-,/,*, or
  13.      registers. All commands are case-insensitive. Words that are in
  14.      italics the command syntax statements must be replaced by an actual
  15.      value, rather than typing in the italicized word.
  16.  
  17.      The following notational conventions are used throughout this section
  18.  
  19.      [ ]
  20.           Brackets enclose an optional syntax item.
  21.      < >
  22.           Angle brackets enclose a list of items or choices.
  23.      x | y
  24.           Vertical bars separate alternatives. Use item x or item y.
  25.      count
  26.           Count is a byte value that specifies the number of time break
  27.           point conditions must be met before the actual break point
  28.           occurs. If no count is specified, the default value is 1. Each
  29.           time the Soft-ICE window is brought up, the counts are reset to
  30.           the values originally specified.
  31.      verb
  32.           Verb is a value that specifies what type access the break point
  33.           will apply to. It can be set to 'R' for reads, 'W' for write RW'
  34.           for reads and writes, or 'X' for execute.
  35.      address
  36.           Address is a value that is made of two 16-bit words, separated by
  37.           a colon. The first word is the segment address, and the second
  38.           word is the segment offset. The addresses can be constructed of
  39.           registers expressions, and symbols. The address may also contain
  40.           the special characters "$", ".", and "@". See section 3-8
  41.           (Command Syntax) for a description of these special characters.
  42.      break-#
  43.           Break-number is an identification number that identifies the
  44.           break point to use when you are manipulating break points e.g.,
  45.           editing, deleting, enabling, or disabling them). The break-number
  46.           can be a hexadecimal digit from 0 to F.
  47.      list
  48.           List is a series of break-# separated by commas or spaces.
  49.      mask
  50.           Mask is a bitmask that is represented as: combination of 1's,
  51.           0's, and X's. X's are don't-care bits.
  52.      GT, LT GT and LT
  53.           Command qualifiers that unsigned comparisons of values.
  54.  
  55.      Example : BPIO 21 W EQ M 1XXX XXXX
  56.  
  57.      This command will cause a break point to occur if port 21H is written
  58.      to with the high order bit set.
  59.  
  60. 04.01 Introduction
  61.  
  62.      Soft-ICE has break point capability that has traditionally only been
  63.      available with hardware debuggers. The power and flexibility of the
  64.      80386 chip allows advanced break point capability without additional
  65.      hardware.
  66.  
  67.      Break points can be set on memory location reads and writes, memory
  68.      range reads and writes, program execution and port accesses. Soft-ICE
  69.      assigns a one-digit hexadecimal number (0-F) to each break point. This
  70.      break-number is used to identify break points when you set delete,
  71.      disable, enable, or edit them.
  72.  
  73.      All of Soft-ICE's break points are sticky. That means they don't
  74.      disappear automatically after they've been used; you must
  75.      intentionally clear or disable them using the BC or the BD commands.
  76.      Soft-ICE can handle 16 break points at one time. You can have up to
  77.      ten break points of a single type except for break points on memory
  78.      location (BPMs), of which you can only have four, due to restrictions
  79.      of the 80386 processor.
  80.  
  81.      Break points can be specified with a count parameter. The count
  82.      parameter tells Soft-ICE how many times the break point should be
  83.      ignored before the break point action occurs.
  84.  
  85. 04.02 Setting Break Points
  86.  
  87.      BPM, BPMB, BPMW, BPMD Set break point on memory access or execution
  88.      BPR Set break point on memory range
  89.      BPIO Set break point on I/O port access
  90.      BPINT Set break point on interrupt
  91.      BPX Set/clear break point on execution
  92.      CSIP Set CS:IP range qualifier
  93.      BPAND Wait for multiple break points to occur
  94.  
  95. Set break point on memory access or execution
  96.  
  97.      Syntax :
  98.  
  99.           BPM[size]address[verb][qualifier value][C=count]
  100.  
  101.           Size :
  102.                B(yte), W(ord), D(oubleword)
  103.                The size is actually a range covered by this break point.
  104.                For example, if double word is used, and the third byte of
  105.                the double is modified, then a break point will occur. The
  106.                size is also important if the optional qualifier is
  107.                specified (see below).
  108.           Verb :
  109.                R, W, RW, or X
  110.           Qualifier :
  111.                EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
  112.                M (Mask)
  113.                These qualifiers are only applicable to the read and write
  114.                break points.
  115.           Value
  116.                A byte, word, or double word value, depending on the size
  117.                specified.
  118.  
  119.      Comments :
  120.  
  121.           The BPM commands allow you to set a break point on memory reads
  122.           or writes or execution.
  123.  
  124.           If a verb is not specified, RW is the default. If a size is not
  125.           specified, byte is the default.
  126.  
  127.           All of the verb types except X cause the program to execute the
  128.           instruction that caused the break point. The current CS:IP will
  129.           be the instruction after the break point. If the verb type is X,
  130.           the current CS:IP will be the instruction where the break point
  131.           was set.
  132.  
  133.           If R is specified, then the break point will occur on read access
  134.           and on write operations that do not change the value of the
  135.           memory location.
  136.  
  137.           If the verb type is R, W or RW, executing an instruction at the
  138.           specified address will not cause the break point action to occur.
  139.  
  140.      Notes :
  141.  
  142.           If BPMW is used, the specified address must start on a word
  143.           boundary. If BPMD is used, the specified address must point to a
  144.           double word boundary.
  145.  
  146.      Example :
  147.  
  148.           BPM 1234:SI W EQ 10 C=3
  149.  
  150.           This command defines a break point on memory byte access. The
  151.           third time that 10 hexadecimal is written to location 1234:SI,
  152.           the break point action will occur.
  153.  
  154.           BPM CS:1235 X
  155.  
  156.           This command defines a break point on execution. The break point
  157.           action will occur the first time that the instruction at address
  158.           CS:1235 is reached. The current CS:IP will be the instruction
  159.           where the break point was set.
  160.  
  161.           BPMW DS:FOO W EQ M 0XXX XXXX XXXX XXX1
  162.  
  163.           This command defines a word break point on memory write. The
  164.           break point action will occur the first time that location DS:FOO
  165.           has a value written to it that sets the high order bit to 0 and
  166.           the low order bit to 1. The other bits can be any value.
  167.  
  168.           BPM DS:1000 W GT 5
  169.  
  170.           This command defines a byte break point on memory write. The
  171.           break point action will occur the first time that location
  172.           DS:1000 has a value written to it that is greater than 5.
  173.  
  174. Set break point on memory range
  175.  
  176.      Syntax :
  177.  
  178.           BPR start-address end-address [verb] [C=count]
  179.  
  180.           Start-address, end-address :
  181.                start-address and end-address specify memory range.
  182.           Verb :
  183.                R, W, RW, T or TW
  184.  
  185.      Comments :
  186.  
  187.           The BPR command allows you to set a break point across a range of
  188.           memory.
  189.  
  190.           All of the verb types except T or TW cause the program to execute
  191.           the instruction that caused the break point. The current CS:IP
  192.           will be the instruction after the break point.
  193.  
  194.           There is no range break point on execution. If a range break
  195.           point is desired on execution, R must be used. An instruction
  196.           fetch is considered a read for range break points.
  197.  
  198.           If a verb is not specified, W is the default.
  199.  
  200.           The range break point will degrade system performance in certain
  201.           circumstances. Any read or write within the 4K page that contains
  202.           the break point range is analyzed by Soft-ICE. This performance
  203.           degradation is usually not noticeable, however, degradation could
  204.           be extreme in exception cases.
  205.  
  206.           The T and TW verbs enable back trace ranges on the specified
  207.           range. They do not cause break points, but instead log
  208.           instruction information that can be displayed later with the SHOW
  209.           or TRACE commands. For more information on back trace ranges, see
  210.           chapter 9.
  211.  
  212.      Example :
  213.  
  214.           BPR B000:0 B000:1000 W
  215.  
  216.           This command defines a break point on memory range. The break
  217.           point will occur if there are any writes to the monochrome
  218.           adapter video memory region.
  219.  
  220. Set break point on I/O port access
  221.  
  222.      Syntax :
  223.  
  224.           BPIO port [verb] [qualifier value] [C=count]
  225.  
  226.           Port :
  227.                A byte or word value.
  228.           Verb :
  229.                R (IN), W (OUT), or RW
  230.           Qualifier :
  231.                EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
  232.                M (Mask)
  233.  
  234.      Comments :
  235.  
  236.           The BPIO command allows you to set a break point on I/O port
  237.           reads or writes.
  238.  
  239.           If value is specified, it is compared with the actual data value
  240.           read or written by the IN or OUT instruction causing the break
  241.           point. The value may be a byte or a word. If the I/O is to a byte
  242.           port, then the lower 8 bits are used in the comparison.
  243.  
  244.           The instruction pointer (CS:IP) will point to the instruction
  245.           after the IN or OUT instruction that caused the break point.
  246.  
  247.           If a verb is not specified, RW is the default.
  248.  
  249.      Example :
  250.  
  251.           BPIO 21 W NE FF
  252.  
  253.           This command defines a break point on I/O port access. The break
  254.           point will occur if the interrupt controller one mask register is
  255.           written with a value other than FFH.
  256.  
  257.           BPIO 3FE R EQ M 11XX XXXX
  258.  
  259.           This command defines a byte break point on I/O port read. The
  260.           break point action will occur the first time that I/0 port 3FE is
  261.           read with a value that has the two high order bits set to 1. The
  262.           other bits can be any value.
  263.  
  264. Set break point on interrupt
  265.  
  266.      Syntax :
  267.  
  268.           BPINT int-number [ < AL | AH | AX >= value] [C = count]
  269.  
  270.           Int-number :
  271.                Interrupt number from 0 - FF hex
  272.           Value :
  273.                A byte or a word value
  274.  
  275.      Comments :
  276.  
  277.           The BPINT command allows breaking on the execution of a hardware
  278.           or a software interrupt. By optionally qualifying the AX register
  279.           with a value, specific DOS or BIOS calls can be easily isolated.
  280.  
  281.           If no value is specified, a break point will occur when the
  282.           interrupt specified by int-number occurs. This interrupt can be a
  283.           hardware, software, or internal interrupt.
  284.  
  285.           The optional value is compared with the specified register (AH,
  286.           AL, or AX) when the interrupt occurs. If the value matches the
  287.           specified register, then the break point will occur.
  288.  
  289.           When the break point occurs, if the interrupt was a hardware
  290.           interrupt, the instruction pointer (CS:IP) will point to the
  291.           first instruction within the interrupt routine. The INT? command
  292.           can be used to see where execution was when the interrupt
  293.           occurred. If the interrupt was a software interrupt, when the
  294.           break point occurs, the instruction pointer (CS:IP) will point to
  295.           the INT instruction causing the interrupt.
  296.  
  297.      Example :
  298.  
  299.           BPINT 21 AH=4C
  300.  
  301.           This command defines a break point on interrupt 21H The break
  302.           point will occur when DOS function call 4CH (terminate program)
  303.           is called.
  304.  
  305. Set/Clear break point on execution
  306.  
  307.      Syntax :
  308.  
  309.           BPX [address] [C=count]
  310.  
  311.      Comments :
  312.  
  313.           The BPX command allows you to set or clear a point-and-shoot
  314.           execution break point in source. When the cursor is in the code
  315.           window the address is not required. The execution break point is
  316.           set at the address of the current cursor location. If an
  317.           execution break point has already been set at the address of the
  318.           current cursor location, then the break point is cleared.
  319.  
  320.           If the code window is not visible or the cursor is not in the
  321.           code window then the address must be specified. If an offset only
  322.           is specified then the current CS register value used as the
  323.           segment.
  324.  
  325.      Technical Note :
  326.  
  327.           BPX uses an interrupt 3 style of break point unless the specified
  328.           address is ROM. This is used instead of a break point register to
  329.           make more execution break points available. If your circumstances
  330.           require the use of a break point register for some reason (code
  331.           not loaded yet for example) you can set an execution break point
  332.           with the BPM command.
  333.  
  334.      Example :
  335.  
  336.           BPX.1234
  337.  
  338.           This sets an execution break point at source line 1234.
  339.  
  340. Set CS:IP range qualifier
  341.  
  342.      Syntax :
  343.  
  344.           CSIP [OFF | [NOT] start-address end-address]
  345.  
  346.           NOT :
  347.                When NOT is specified, the break point will only occur if
  348.                the CS:IP pointer is outside the specified range.
  349.           OFF :
  350.                Turns off CS:IP checking
  351.  
  352.      Comments :
  353.  
  354.           The CSIP command causes a break point to be dependent upon the
  355.           location of the instruction pointer when the break point
  356.           conditions are met. This function is often useful when a program
  357.           is suspected of accidentally modifying code outside of its
  358.           boundaries.
  359.  
  360.           When break point conditions are met, the CS:IP registers are
  361.           compared with a specified range. If they are within the range,
  362.           the break point is activated. To activate the break point when
  363.           CS:IP is outside the range, use the NOT parameter.
  364.  
  365.           When a CSIP range is specified, it applies to ALL break points
  366.           that are currently active.
  367.  
  368.           If no parameters are specified, the current CSIP range is
  369.           displayed.
  370.  
  371.      Example :
  372.  
  373.           CSIP NOT F000:0 FFFF:0
  374.  
  375.           This command causes the break points to occur only the CS:IP is
  376.           NOT in the ROM BIOS when the break point conditions are met.
  377.  
  378. Wait for multiple break points to occur
  379.  
  380.      Syntax :
  381.  
  382.           BPAND list | * | OFF
  383.  
  384.           List :
  385.                A series of break-numbers separated by commas or spaces
  386.           * :
  387.                ANDs together all break points
  388.  
  389.      Comments :
  390.  
  391.           The BPAND command does a logical AND of two or more break points,
  392.           activating the break point only when conditions for all break
  393.           points are met.
  394.  
  395.           Sometimes conditions arise when you don't want a break point to
  396.           occur until several different conditions are met. The BPAND
  397.           command allows specifying two or more break points that must
  398.           occur before the action is generated. This function allows more
  399.           complex break point conditions to be set.
  400.  
  401.           Each time the BPAND command is used, the specified break point
  402.           numbers are added to the list until BPAND OFF is used.
  403.  
  404.           You can tell which of the break-numbers are ANDed together by
  405.           listing the break points with the BL command. The break points
  406.           that are ANDed together will have an ampersand (&) after their
  407.           break-number.
  408.  
  409.           Once break points have been ANDed together, each remains ANDed
  410.           until it is cleared, or until BPAND is turned off.
  411.  
  412.      Example :
  413.  
  414.           BPAND 0,2,3
  415.  
  416.           This command causes the conditions of the break points 0, 2, and
  417.           3 to be logically tied together. The break occurs only when the
  418.           conditions of all three are met. For example, if the conditions
  419.           of break points 2 and 3 have both been met at least once, but the
  420.           conditions of break point 0 have not been met at all yet, then
  421.           the action will not occur until break point 0 conditions are met.
  422.  
  423. 04.03 Manipulating Break Points
  424.  
  425.      Soft-ICE provides several commands for manipulating break points.
  426.      Manipulation commands allow listing, modifying, deleting, enabling,
  427.      and disabling of break points. Break points are identified by
  428.      break-numbers which are hexadecimal digits from 0 to F. The break
  429.      point manipulation commands are:
  430.  
  431.      BD Disable break points
  432.      BE Enable break points
  433.      BL List break points
  434.      BPE Edit break point
  435.      BPT Use break point as a template
  436.      BC Clear break points
  437.  
  438. Disable break points
  439.  
  440.      Syntax :
  441.  
  442.           BD list | *
  443.  
  444.           List :
  445.                A series of break-numbers separated by commas or spaces
  446.           * :
  447.                Disables all break points
  448.  
  449.      Comments :
  450.  
  451.           The BD command is used to temporarily deactivate break points.
  452.           The break points can be reactivated with the BE (Enable break
  453.           points) command.
  454.  
  455.           You can tell which of the break-numbers are disabled by listing
  456.           the break points with the BL command. The break points that are
  457.           disabled will have an asterisk (*) after their break-number.
  458.  
  459.      Example :
  460.  
  461.           BD 1,3
  462.  
  463.           This command temporarily disables break points 1 and 3.
  464.  
  465. Enable break points
  466.  
  467.      Syntax :
  468.  
  469.           BE list | *
  470.  
  471.           List :
  472.                A series of break-numbers separated by commas or spaces
  473.           * :
  474.                Enables all break points
  475.  
  476.      Comments :
  477.  
  478.           The BE command is used to reactivate break points that were
  479.           deactivated by the BD (Disable break points) command.
  480.  
  481.           Note that a break point is automatically enabled when defined.
  482.  
  483.      Example :
  484.  
  485.           BE 3 his command enables break point 3.
  486.  
  487. List break points
  488.  
  489.      Syntax :
  490.  
  491.           BL
  492.  
  493.      Comments :
  494.  
  495.           The BL command displays all break points that are currently set.
  496.           For each break point, BL lists the break-number, break point
  497.           conditions, break point state, and count.
  498.  
  499.           The state of a break point is either enabled or disabled. If the
  500.           break point is disabled, an asterisk (*) is displayed after its
  501.           break-number. If an enabled break point was used in a BPAND
  502.           command, an ampersand (&) is displayed after its break-number.
  503.           The break point that most recently caused an action to occur is
  504.           highlighted.
  505.  
  506.           The BL command has no parameters.
  507.  
  508.      Example :
  509.  
  510.           BL
  511.  
  512.           This command displays all the break points that have been
  513.           defined. A sample display, which shows four break points,
  514.           follows:
  515.  
  516.            0) BPMB 1234:0000 W EQ 0010 C=03
  517.            1)*BPR B000:0000 B000:1000 W C=01
  518.            2) BPIO 0021 W NE 00FF C=01
  519.            3) BPINT 21 AH=4C C=01
  520.  
  521.           Note that in this example, break point 1 is preceded with an
  522.           asterisk (*), showing that it has been disabled.
  523.  
  524. Edit break point
  525.  
  526.      Syntax :
  527.  
  528.           BPE break-number
  529.  
  530.      Comments :
  531.  
  532.           The BPE command loads the break point description into the edit
  533.           line for modification. The command can then be edited using the
  534.           editing keys, and re-entered by pressing the ENTER . This command
  535.           offers a quick way to modify the parameters of an existing break
  536.           point.
  537.  
  538.      Example :
  539.  
  540.           BPE 1
  541.  
  542.           This command moves a description of break point 1 into the edit
  543.           line and removes break point 1. Pressing the ENTER key will cause
  544.           the break point to be re-entered.
  545.  
  546. Use break point as a template
  547.  
  548.      Syntax :
  549.  
  550.           BPT break-number
  551.  
  552.      Comments :
  553.  
  554.           The BPT command uses an existing break point description as a
  555.           template for a new break point.
  556.  
  557.           A description of the existing break point is loaded into the edit
  558.           line. The break point referenced by break-number is not altered.
  559.           This command offers a quick way to create a new break point that
  560.           is similar to an existing break point.
  561.  
  562.      Example :
  563.  
  564.           BPT 3
  565.  
  566.           This command moves a template of break point 3 into the edit
  567.           line. When the ENTER key is pressed, a new break point is added.
  568.  
  569. Clear break points
  570.  
  571.      Syntax :
  572.  
  573.           BC list | *
  574.  
  575.           List :
  576.                A series of break-numbers separated by commas or spaces
  577.           * :
  578.                ANDs together all break points
  579.  
  580.      Comments :
  581.  
  582.           The BC command is used to permanently delete one or more break
  583.           points.
  584.  
  585.      Example :
  586.  
  587.           BC *
  588.  
  589.           This command clears all break points.
  590.