home *** CD-ROM | disk | FTP | other *** search
/ The Unsorted BBS Collection / thegreatunsorted.tar / thegreatunsorted / programming / misc_programming / addendum.280 < prev    next >
Text File  |  1995-07-16  |  18KB  |  562 lines
  1.                  ADDENDUM FOR SOFT-ICE (DOS) VERSION 2.8
  2.  
  3. This addendum contains all new commands, features and bug fixes in Soft-ICE
  4. for DOS since version 2.64.
  5.  
  6.  
  7.             INSTALLATION
  8.             ------------
  9.  
  10. To install the new version of Soft-ICE for DOS on your system, insert the
  11. floppy disk into your disk drive and: 
  12.  
  13.     -Copy all the files from the disk to the destination directory on
  14.        your hard drive.
  15.  
  16.     -Run EMMSETUP on S-ICE.EXE to configure the memory manager.
  17.      Syntax:
  18.         EMMSETUP S-ICE.EXE
  19.  
  20.     -Create a new CONFIG.SYS file for Soft-ICE for DOS.  A sample
  21.      one is included and is entitled CONFIG.ICE.
  22.  
  23.  
  24.  
  25.             NEW/MODIFIED COMMANDS
  26.             ---------------------
  27.  
  28. ---------------------------------------------------------------------
  29.  
  30.             P
  31.  
  32. P -- Program Step
  33.  
  34. Syntax:
  35.     P [ RET ]
  36.  
  37. Comments:
  38.  
  39. The P command is a logical program step.  One instruction at the current
  40. CS:IP is executed unless the instruction is a call, interrupt, loop, or 
  41. repeated string instruction.  In those cases, the entire routine or 
  42. iteration is completed before control is returned to Soft-ICE.
  43.  
  44. The P command uses a one-time execution break point.  The non-sticky
  45. execution break point uses an 80386 break point register, unless
  46. all break point registers have been allocated to sticky break points.  In
  47. that case, and INT 3 style break point is implemented.  When this case occurs, 
  48. the P and G commands will not work correctly in ROM.  An error message
  49. will be displayed if this is attempted.
  50.  
  51. In source mode, the P command steps to the next source statement.  If the 
  52. current statement is a procedure or function call, the P command steps over
  53. it.
  54.  
  55. If RET is specified, the P command will step until the next RET or IRET
  56. instruction.
  57.  
  58. ----------------------------------------------------------------------
  59.  
  60.             LINES
  61.  
  62.  
  63. LINES -- Change number of lines of the Soft-ICE display.
  64.  
  65. Syntax:
  66.     LINES [ 25 | 43 | 50 ]
  67.  
  68. Comments:
  69.  
  70. The LINES command changes Soft-ICE's character display mode.  It allows
  71. three different display modes: 25 line, 43 line, or 50 line mode.
  72. 43-line mode is only valid on VGA or EGA display adapters and 50-line
  73. mode is only valid on VGA adapters.
  74.  
  75. The default number of display lines is 25.  If your Soft-ICE display is
  76. on another computer connected by a serial cable, the display is fixed at 
  77. 25 lines.
  78.  
  79. ----------------------------------------------------------------------
  80.  
  81.             SERIAL
  82.  
  83.  
  84. SERIAL -- Redirect console to serial teminal.
  85.  
  86. Syntax:
  87.     SERIAL [ ON [ com-port] [ baud rate] | OFF ]
  88.  
  89.     com-port        This is a number from 1 to 4 that 
  90.                 corresponds to COM1 COM2, COM3, or COM4.
  91.                 The default is COM1.
  92.  
  93.     baud-rate        This is the baud rate to use for serial
  94.                 communications.  The default is to have
  95.                 Soft-ICE automatically determine the fastest
  96.                 possible baud rate that can be used.
  97.  
  98. Comments:
  99.     
  100. Debugging on a serial console requires a second IBM compatible PC running
  101. MSDOS.  Any PC will do, including 8088, 8086 or 80286 machines.  You must
  102. first attach the computer to your host machine with a null modem cable.
  103. Before using the SERIAL command, you must run the REMOTE.EXE program on the
  104. second PC.  The syntax of REMOTE.EXE is as follows:
  105.  
  106.     REMOTE ON com-port baud-rate
  107.  
  108. -----------------------------------------------------------------------
  109.  
  110.             WATCH
  111.  
  112. WATCH -- Add a watch expression.
  113.  
  114. Syntax:
  115.     WATCH [ size ] expression
  116.  
  117.     size        B,W,D,I,E,U,F,S,L,A
  118.  
  119.                   B - display a byte in hexadecimal format
  120.                   W - display a word in hexadecimal format
  121.                   D - display a dword in hexadecimal pointer format
  122.                   I - display a word in decimal (int) format
  123.                   E - display a dword in decimal (long int) format
  124.                   U - display a word in unsigned decimal format
  125.                   F - display a dword in unsigned decimal format
  126.                   S - display a 4-byte (float) FP real
  127.                   L - display an 8-byte (double) FP real
  128.             A - display a string of ASCII characters ( max 33 )
  129.  
  130. Comments:
  131.  
  132. The WATCH commands are used to display the results of expressions.  The 
  133. results of expression are displayed in the format of the size specified.
  134. If no size is specified, byte will be assumed.  The expressions being
  135. watched are displayed in the watch windows.  There can be up to eight
  136. watch expressions at a time.  Every time Soft-ICE screen is popped up,
  137. the watch window will display the expressions' current values.
  138.  
  139. Each line in the watch windows contains the following information:
  140.  
  141.     A watch number from 0 to 7.
  142.     
  143.     The hexadecimal address of the expression.
  144.  
  145.     The current value of the expression displayed in the appropriate
  146.     format.
  147.  
  148.     The expression being evaluated.
  149.  
  150. Examples:
  151.  
  152.     WATCHW FooVariable
  153.     WATCHD DS:ESI
  154.  
  155. ----------------------------------------------------------------------
  156.  
  157.             CWATCH
  158.  
  159. CWATCH -- Clear a watch expression.
  160.  
  161. Syntax:
  162.     CWATCH list | *
  163.  
  164.     list        This is a list of watch numbers from 0-7 seperated
  165.             by commas.  Watch-numbers are the numbers displayed
  166.             on the beginning of each line in the watch window.
  167.  
  168.     *        Clear all watch expressions.
  169.  
  170. Comments:
  171.  
  172. The CWATCH command is used to clear one or more watch expressions from the 
  173. watch window.  After clearing the expressions, the ones still remaining in
  174. the window are renumbered sequentially starting at 0.  If there are no more
  175. watch expressions, the window disappears.
  176.  
  177. -----------------------------------------------------------------------
  178.  
  179.             STKWIN
  180.  
  181. STKWIN -- Show or clear stack window
  182.  
  183. Syntax:
  184.     STKWIN [ ON | OFF ]
  185.  
  186. Comments:
  187.  
  188. The STKWIN command adds a stack window to the Soft-ICE screen.  Each line
  189. shows a 4 digit ( hex ) displacement from BP and the 4 digit ( hex ) value
  190. of the word at that address. You can scroll the stack window using the
  191. ALT-Down-Arrow keys.  You can only edit the higlighted line.  To change a
  192. value in the stack window, use the ES command.
  193.  
  194. -------------------------------------------------------------------------
  195.  
  196.             ES
  197.  
  198. ES -- Change highlighted value in stack window
  199.  
  200. Syntax:
  201.     ES [ hex value ]
  202.  
  203.     hex value            4 digit address to change
  204.  
  205. Comments:
  206.  
  207. The ES command will allow you to change stack values relative to BP in the
  208. stack window.  Similar to the E command.
  209.  
  210. --------------------------------------------------------------------------
  211.  
  212.             XRSET
  213.  
  214. XRSET -- Reset back trace history buffer
  215.  
  216. Syntax:
  217.     XRSET [ A | I | R ]
  218.  
  219.     A        Logs addresses only.
  220.     I        Logs addresses and opcodes.
  221.     R        Logs addresses, opcodes, and registers. 
  222.  
  223. Comments:
  224.  
  225. The XRSET command resets the back trace history buffer.  This command
  226. should be executed before setting a back trace range if there is 
  227. unwanted instruction information in the back trace buffer.
  228.  
  229. When using the I and R parameters, significantly more memory will be
  230. needed for the back trace buffer to store the information.  This memory
  231. is allocated on the Soft-ICE device line in CONFIG.SYS.
  232.  
  233. A program (BTLOG.EXE) was added to write the back trace buffer to a file
  234. in ASCII text. The amount of information written depends on the option
  235. chosen in the XRSET command used to set up the back trace. The syntax of
  236. this program is similar to the SHOW command:
  237.  
  238.                   BTLOG file-name start-line L length
  239.  
  240. -------------------------------------------------------------------------
  241.  
  242.             COLORS
  243.  
  244. COLORS -- Change the colors of the information windows in Soft-ICE
  245.  
  246. Syntax:
  247.     COLORS [ color | * ]
  248.  
  249.     color        A hex number representing a color to change to
  250.  
  251.     *        Skip changing the color for this field.
  252.  
  253. Comments:
  254.  
  255. The COLOR command accepts up to 12 parameters in the following order:
  256.  
  257.     normal - highlight - reverse        for Register Window
  258.     normal - highlight - reverse        for Data Window
  259.     normal - highlight - reverse        for Code Window
  260.     normal - highlight - reverse        for Command Window
  261.  
  262. The colors will only stay the way you change them until the computer is
  263. rebooted.  At that time, the colors will revert to the default colors.
  264. To change the colors on a permament basis, see the color line in
  265. S-ICE.DAT.
  266.  
  267. Example:
  268.  
  269.     COLORS * * * 4f 40 74 * * * 5d
  270.  
  271.         Would leave the register and code window attributes the 
  272.         same, would change the data window attributes to 4F for 
  273.         normal, 40 for highlight, and 74 for reverse, and would 
  274.         change the command window normal attribute to 5D, leaving 
  275.         the highlight and reverse attributes unchanged.
  276.  
  277.     
  278.     COLORS * * * * * * * * * 5d 40 74
  279.  
  280.     Would leave colors in all windows except the command window the
  281.     same.  Would change the normal color of the command window to
  282.     5d, the highlight to 40 and the reverse to 74.
  283.  
  284. -------------------------------------------------------------------------
  285.  
  286.             R
  287.  
  288. R -- Display or change register values
  289.  
  290. Syntax:
  291.     R [ register name [[=]value]]
  292.  
  293.     register name         Any of the following:
  294.                 EAX, AX, AH, AL
  295.                 EBX, BX, BH, BL
  296.                 ECX, CX, CH, CL
  297.                 EDX, DX, DH, DL
  298.                 EDI, DI, ESI, SI
  299.                 EBP, BP, ESP, SP
  300.                 CS, DS, ES, SS
  301.                 FS, GS, FL
  302.  
  303.     value            If register name is any name other than
  304.                 FL, value is a hex value or an expression.
  305.                 If register name is FL, value is a series
  306.                 of one or more of the following flag
  307.                 symbols, each optionalyy preceded by a plus
  308.                 or minus sign:
  309.                     O ( Overflow flag )
  310.                     D ( Direction flag )
  311.                     I ( Interrupt flag )
  312.                     S ( Sign flag )
  313.                     Z ( Zero flag )
  314.                     A ( Auxiliary carry flag )
  315.                     P ( Parity flag )
  316.                     C ( Carry flag )
  317.  
  318. Comments:
  319.  
  320. If no parameters are supplied, all register and flag values are displayed,
  321. as well as the instruction at the current CS:IP address.
  322.  
  323. If both register name and value are specified, the specifed register's
  324. contents are changed to the value.
  325.  
  326. ---------------------------------------------------------------------------
  327.  
  328.             SL
  329.  
  330. SL - Show window seperator lines
  331.  
  332. Syntax:
  333.  
  334.     SL
  335.  
  336. Comments:
  337.  
  338. The SL command puts borders between each of the data windows inside Soft-ICE.
  339. This command is particularly helpful for debugging on monochrome monitors.
  340. By default, the lines do not show.
  341.  
  342. ===========================================================================
  343.  
  344.  
  345.  
  346.             NEW FEATURES
  347.             ------------
  348.  
  349. Display FS and GS segment registers.
  350.  
  351. Highlight registers that have changed since the last time
  352. Soft-ICE was entered.
  353.  
  354. Display "JUMP" or "NO JUMP" when stepping through a
  355. program if the current instruction is a conditional jump.
  356.  
  357. Set breakpoints in VROOM overlays.
  358.  
  359. Display of local (stack) variables by name.
  360.  
  361. Changed BPR ... TW to work on data areas; this records 
  362. all instructions which write to that area.
  363.  
  364. Using .PTH & .SRC Files
  365.  
  366.     If there is no SET SRC=... statement within the 
  367.     environment, LDR.EXE will attempt to open a file named 
  368.     program-name.PTH. If such a file exists, LDR will read it 
  369.     and will use the paths specified within to look for the
  370.     source files. In version 2.71, this was modified to make 
  371.     LDR.EXE look for a program-name.PTH file first, so that it 
  372.     supersedes any SET SRC statement.
  373.  
  374.     Before loading the source files, LDR.EXE will attempt to 
  375.     open a file named program.SRC. This file should be a list of
  376.     the source files to load - if the file exists, only those 
  377.     source files listed within it will be loaded.
  378.  
  379.     The .PTH & .SRC files must be in the same directory as 
  380.     the program-name.EXE file. The syntax of a .PTH file is like
  381.     a path statement except that it has no "PATH = ", but just 
  382.     the paths. The following is an example:
  383.  
  384.         c:\ldr\new;d:\bcdos\engine;c:\sibcdos\ui;
  385.  
  386.     The format of a .SRC file is a list of source file names,
  387.     including extensions, each one on a separate line - for 
  388.     example:
  389.  
  390.         asm.asm
  391.         sym.asm
  392.         volume.cpp
  393.         mgraph.c
  394.  
  395.     Note that this file does not contain any drive or
  396.     directory information.
  397.  
  398.  
  399. Using Borland TDS Files for Debug Data
  400.  
  401.     If a Borland .EXE file does not contain debug data,
  402.     LDR.EXE will try to open a file named program-name.TDS in 
  403.     the same directory as the .EXE file. If such a file exists, 
  404.     it will read the debug data from this file. 
  405.     
  406.     A TDS file can be generated by running TDSTRIP with the 
  407.     /s switch on a .EXE file which contains Borland debug data.
  408.     
  409.  
  410. Passing Commands to Soft-ICE from LDR.EXE
  411.  
  412.     LDR.EXE can pass commands to Soft-ICE in either of two 
  413.     ways: directly from the command line, or from a file 
  414.     specified on the command line. In both cases, the command 
  415.     string is executed when Soft-ICE pops up at the start of the
  416.     application program. If you want the program to execute 
  417.     without stopping at the Soft-ICE screen, put an "X" as the 
  418.     last command in the string.
  419.  
  420.     To pass commands directly from the command line, the 
  421.     entire command string must be enclosed within slashes. The 
  422.     command string may include symbolic names and commands to 
  423.     set breakpoints. For example, the following string would set
  424.     a breakpoint on a variable named "base", set up the data
  425.     window to display this variable in word format, and then 
  426.     exit from Soft-ICE and begin executing the application 
  427.     program without popping up:
  428.  
  429.             ldr    /bpm base;dw base;x/     myprog
  430.  
  431.     Note that there is a slash both before and after the 
  432.     command string - this allows using spaces within commands. 
  433.     Also note that commands are separated by semicolons. The 
  434.     last command in the string does not need a trailing semi-
  435.     colon.
  436.  
  437.     To specify a file containing Soft-ICE commands, use a 
  438.     "/n" or "/N" switch in the LDR command line (There are no 
  439.     Soft-ICE commands which begin with "n" or "N", so this 
  440.     cannot be a direct command). There must NOT be a slash after
  441.     the file name - the first space after the filename is the 
  442.     terminator.
  443.  
  444.     The command file either must be in the current directory
  445.     or else the full path must be specified. The command string 
  446.     within the file may use either CR's or CRLF's or semicolons
  447.     as separators between commands. The size of the Soft-ICE 
  448.     command buffer limits the file length to 200 characters.
  449.     
  450.     The syntax would be something like the following:
  451.  
  452.             ldr   /nc:\prog\softice.cmd     myprog
  453.  
  454.  
  455. ==========================================================================
  456.  
  457.  
  458.             BUG FIXES
  459.             ---------
  460.  
  461. Show the application text screen when Video Memory is 
  462. being displayed rather than the Soft-ICE screen text as 
  463. was shown in earlier versions.
  464.  
  465. Show the correct program length in the MAP command when 
  466. drivers or TSR's are loaded high; also show the HMA area,
  467. and highlight only one block as the current program. The 
  468. previous versions got confused when anything was loaded
  469. high.
  470.  
  471. Added unassembly of the JECXZ instruction. Also fixed 
  472. display of special 32-bit instructions such as CWDE and 
  473. STOSD to show the correct mnemonic.
  474.  
  475. Fixed display of location being addressed to show a 
  476. dword when the operand size is 32-bits, and on LES, LDS, 
  477. LSS, LFS and LGS instructions.
  478.  
  479. Fixed display of location being addressed to show a 
  480. dword when instruction is a far jump or far call (opcode 
  481. FF).
  482.  
  483. Fixed problem with setting breakpoints in overlays that 
  484. were not yet loaded. BPX type breakpoints can now be set 
  485. at symbolic names within overlays. NOTE: The Addendum to 
  486. versions 2.5 and 2.6 states that module names can be used
  487. for setting breakpoints; this is not correct. Symbolic 
  488. names within the overlays must be used.
  489.  
  490. Fixed problem in displaying source within overlays when 
  491. more than one overlay is loaded.
  492.  
  493. Fixed the Assemble command to recognize 32-bit opcodes.
  494.  
  495. Fixed a keyboard problem caused by sending 60H out to 
  496. port 64H. This would hang any system that did not have a 
  497. PS2 mouse.
  498.  
  499. Fixed ALTSCR bug in Soft-ICE, where the ALT screen would
  500. go blank.
  501.  
  502. Fixed an error in the 910H back door command, which puts
  503. a null-terminated message in the Soft-ICE command window 
  504. where it is displayed when Soft-ICE pops up. The error 
  505. caused only part of the message to be displayed.
  506.  
  507. Changed LDR to put MSC7 public symbols into the module 
  508. which actually contains them. This allows breakpoints to 
  509. be set on symbol names within MSC7 overlays.
  510.  
  511. Fixed a problem where PUSHFD or POPFD instructions would
  512. cause a GP fault in Soft-ICE if run with BREAK ON. 
  513.  
  514. Changed processing of symbol names to allow them to 
  515. begin with "@", and to recognize unmangled names as well 
  516. as their complex mangled equivalents.
  517.  
  518. Fixed a problem where the IP register was treated as a 
  519. byte register when reading its contents, so a command such
  520. as "U CS:IP"  or  "D CS:IP"  would read only the lower 
  521. byte of IP, set the upper byte to 0 and display the code 
  522. or data at that address.
  523.  
  524. Fixed a problem in the small window mode where some 
  525. screens were not updated if the user exited to DOS and 
  526. popped up Soft-ICE again. Parts of the Soft-ICE screen 
  527. would still show the characters and attributes which had 
  528. been in those places on the DOS screen.
  529.  
  530. Fixed a bug which occurred only when the /EMM switch was
  531. used; if a TSR was loaded using LDR, and EXIT was keyed 
  532. when it popped up, and if the TSR then was loaded without 
  533. using LDR, Soft-ICE would pop up with a GP fault.
  534.  
  535. Fixed a bug where the Soft-ICE screen would be blank if 
  536. the application or DOS set the video page to something 
  537. other than page 0.
  538.  
  539. Fixed a bug in the A (assemble) command where the 
  540. generated code had the wrong registers. 
  541.  
  542. Fixed a bug in the BPIO handler when the operand of the 
  543. I/O instruction was EAX.
  544.  
  545. Fixed a bug in the MAP command when Soft-ICE was popped 
  546. up while loading a driver (either the initial load or 
  547. after a BOOT command). The DOS structures are incomplete 
  548. at this point, and Soft-ICE did not handle this problem 
  549. correctly.
  550.  
  551. Several problems associated with very large debug data,
  552. where segment limits were being exceeded, causing a GP 
  553. fault.
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.