home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / forth / compiler / fpc / bxd.doc next >
Text File  |  1986-12-11  |  12KB  |  305 lines
  1.  
  2.           b r a n d X  S Y M B O L I C  D E B U G G E R
  3.                          version 2.1
  4.  
  5.                       by  Sonam G Gyato
  6.  
  7.  
  8. INTRODUCTION:
  9.  
  10. This program is a full-screen software debugger for the IBM
  11. PC/XT series of personal computers. Even though it has been
  12. specifically written for these machines, it will also work on
  13. others that are 100% compatible.
  14.  
  15. This release supports both the MONOCHROME (MDA) and the COLOR
  16. GRAPHICS (CGA) display adaptors (not the EGA). For example,
  17. you can trace through a graphics program, a pixel at a time.
  18. bXd is able to do this by trapping the BIOS video calls found in
  19. the IBM machines. Therefore, it is very important for non-IBM
  20. users, that your computer's BIOS routines be very similar to
  21. that of IBMs.
  22.  
  23. For proper operation, it is important that all video related
  24. calls go via DOS or BIOS routines. In the case of the CGA
  25. users, bXd screen always uses memory locations BB00:0 to BBFF:F
  26. (in 80x25 text modes, this is the last of the four display
  27. pages). Therefore you can write to the screen directly for the
  28. first three pages, but for the last one you have to go via DOS
  29. or BIOS routines.
  30.  
  31. Some of the other major features of this program are
  32.     - Hardware Reset Switch
  33.       This gives the user the ability to trap any runaway program
  34.       dead in its track. It is really of great help.
  35.  
  36.     - Specify addresses by symbolic names
  37.       bXd supports symbolic names by reading in files generated
  38.       by your linker. Two formats are supported. One of them
  39.       being the format generated by the MSDOS linker.
  40.  
  41.     - Online HELP
  42.       Detailed help on the different commands are available.
  43.       First time users are encouraged to go through them all
  44.       atleast once.
  45.  
  46. When developing a new product, one of the biggest problems faced
  47. by designers is the balance between the ability and the
  48. complexity of the program. Make it simple to use...it has
  49. little power, make it powerful...it becomes difficult to use.
  50.  
  51. I hope that users will find out that I have followed the middle
  52. road. Even though this program will be used by mostly computer
  53. literate people, I have made the program easy to learn and use.
  54. At the same time, it has commands powerful enough to debug
  55. programs easily.
  56.  
  57.  
  58.  
  59. LOADING bXd:
  60.  
  61. Below is the format of invoking bXd from the DOS prompt.
  62.  
  63.      A>bXd [userprog[.COM]] [user_arguments] [<userCON.txt]
  64.  
  65. 1.   The first argument is the optional name of the program to be
  66.      debugged. If no extension is given, then a COM file is
  67.      assumed. In the case of EXE files, you have to specify the
  68.      extension explicitly.
  69.  
  70.      If a filename is given, then bXd tries to load the symbol
  71.      file associated with it.
  72.      More on the symbol file format later.
  73.  
  74. 2.   The second set of arguments is what will be passed to your
  75.      program as its command line. This text is found at offset
  76.      81H in your programs PSP (read DOS tech manual for more
  77.      information on PSPs).
  78.  
  79. 3.   The last argument enables you to redirect the input and
  80.      output to another device besides the console. This might be
  81.      of some help if you're debugging a program that expects
  82.      input from DOS console i/o routines.
  83.  
  84.  
  85.      EX:  A>bXd userprog
  86.  
  87.      In the above case, bXd will load the file <USERPROG.COM> and
  88.      try to load the symbol file. After that it will print the
  89.      status of the file loading procedure (whether the file was
  90.      found or not...etc) and then prompt you will "press any
  91.      key."
  92.  
  93.      After pressing a key, then the bXd debug screen will be
  94.      displayed.
  95.  
  96.  
  97.  
  98.  
  99. SCREEN FORMAT:
  100.  
  101. The bXd screen is divided into 6 different windows.
  102.  
  103.  
  104.      +------------------------------------------+
  105.      | DATA                                     |
  106.      +-----------------------+------------+-----+
  107.      | CODE                  | REGISTER   |     |
  108.      |                       |            +-----+
  109.      |                       |            |STACK|
  110.      |                       |            |     |
  111.      +-----------------------+------------+-----+
  112.      | USER                  | CURNT WINDOW HELP|
  113.      +-----------------------+------------------+
  114.  
  115.      USER
  116.      This is the window from which all commands are issued. There
  117.      are two ways to give the commands -
  118.        -  Command Line Input
  119.           this is the method implemented by most debuggers. You
  120.           type in a line consisting of a command identifier
  121.           alphabet and optional arguments.
  122.        -  Single Key Input
  123.           the second method is via special keys like the
  124.           function and cursor keys.
  125.  
  126.      CODE
  127.      The program code is disassembled in this window. You can
  128.      scroll the information from the USER window with the cursor
  129.      keys.
  130.  
  131.      REGISTER
  132.      The current user register values are displayed here. All the
  133.      values are in hex.
  134.  
  135.      DATA
  136.      Memory is displayed in this window in both hex-ascii and
  137.      ascii format. You can scroll the information from the USER
  138.      window with the <cntrl-PgUp> and <cntrl-PgDn> keys.
  139.  
  140.      STACK
  141.      The current values pointed to by the STACK POINTER (SP)
  142.      register is displayed. The value at the bottom it the word
  143.      pointed to by SS:SP and all the values above it are the
  144.      contents of successive memory locations.
  145.  
  146.      CURRENT WINDOW HELP
  147.      This window displays a brief HELP text on the current
  148.      window. The current window is the window in which the cursor
  149.      is positioned. The default is the USER window.
  150.  
  151.  
  152.  
  153. COMMANDS
  154.  
  155. There is online HELP available on all the commands. From the USER
  156. window, press function key FK1. Pressing that key, will display
  157. the HELP menu in the CODE window. Using the CURNT WINDOW HELP,
  158. you can get help on all the commands.
  159.  
  160.      Single Key Input Commands:
  161.  
  162.      FK1  Display the HELP menu.
  163.  
  164.      FK2  Display the current user screen.
  165.           This is the screen to which all the console output will
  166.           go. If the current mode happens to be graphics, then
  167.           the screen will be displayed in that mode. Once
  168.           displayed, press any key to return to the debugger.
  169.  
  170.           For CGA users, if you're in a text mode and wish to see
  171.           another page; instead of pressing FK2, press the shift
  172.           key and a function key ranging from 1 to 8 (FK1-FK8).
  173.           If the current display mode is 40x25 text modes then
  174.           all the eight keys are valid. In 80x25 text modes, only
  175.           the first four function keys are valid.
  176.  
  177.      FK5  Toggle the current condition for the INT and REPx
  178.           instructions.
  179.           Default is OFF.
  180.  
  181.      FK6  Toggle the current condition for the CALL instructions.
  182.           Default is ON.
  183.  
  184.      FK7  Single step one instruction.
  185.           The INT, REPx and the CALL instructions are treated in
  186.           a special way. You can trace through or bypass them.
  187.  
  188.           The current trace conditions for these instructions are
  189.           displayed at the bottom of the debug screen. The
  190.           condition for the INT and REPx instructions are linked
  191.           (meaning that one condition controls both instrs). If
  192.           the condition is YES, then the instructions will be
  193.           traced through. If the condition is NO, then the
  194.           interim instructions are skipped.
  195.  
  196.      FK8  Edit breakpoints.
  197.           There are ten breakpoints available. You can select a
  198.           particular brkpt to edit by using the cursor keys.
  199.  
  200.           There are five fields for each brkpt. You can select a
  201.           particular field by using the TAB (next field) and the
  202.           shift-TAB (previous field) keys.
  203.  
  204.           ON/OFF    Press the SPACE key to toggle the current state.
  205.           SEGMENT   Segment value of the breakpoint address
  206.                     default is the current code segment value.
  207.           OFFSET    offset value.
  208.           HIT       number of times the above addr needs to be
  209.                     executed before a brkpt is signalled.
  210.                     default is 1.
  211.           CONTROL   For each brkpt, one or two control conditions can
  212.                     be set. Each condition consists of two
  213.                     operands and a binary operator. The operands
  214.                     can be either register names or hex
  215.                     constants. If two such conditions are
  216.                     specified, then both have to be met before a
  217.                     brkpt is signalled.
  218.  
  219.                     When editing, type in the condition and press
  220.                     the RETURN key, If there is a syntax error,
  221.                     then cursor will be positioned under the
  222.                     wrong letter. Below are few examples using
  223.                     the eight operators allowed.
  224.  
  225.                                          Brkpt signalled when...
  226.                     AX == 4;............ AX is equal to 4
  227.                     DH != BH;........... DH is not equal to BH
  228.                     CX & 0001;.......... bit#0 of CX is set
  229.                     FL ^ 2;............. bit#1 of FLAG is reset
  230.                     AX > 8;AX < 10...... AX gtr than 8 AND if less than 10
  231.                     DH >= BH;456 <= AX.. DH gtr than equal to BH
  232.                                          AND
  233.                                          456 is less than equal to AX
  234.  
  235.      Command Line Input:
  236.  
  237.      This is the format most are familiar with. It consists of a
  238.      command id followed by an optional argument. This argument,
  239.      which is actually an address, can be specified in various
  240.      ways. You can specify an offset value or a segment value
  241.      (terminated by colon) or a value with both segment and
  242.      offset (separated by colon).
  243.  
  244.      The values can be typed as hex constant, register names or
  245.      as symbolic names (provided a symbol file has be read). Also
  246.      the binary operators + and - are allowed.
  247.  
  248.      Below are few examples using the Display command.
  249.  
  250.           d ds:100
  251.           d ds:MAIN
  252.           d es-1:
  253.           d bp+si
  254.  
  255.      For information on individual commands, refer to the
  256.      online help facility.
  257.  
  258.  
  259. SYMBOL FILE FORMAT:
  260.  
  261. When the user program is loaded for debugging, bXd tries to load
  262. the symbol file associated with that program. These files are
  263. usually generated by your linker. This version can read in upto
  264. 200 labels and supports two different file formats.
  265.  
  266. The first, is a file having the same name as the program but with
  267. the extension SYM. For example, if the program name is PROG.EXE,
  268. then the symbol file associated with it would be PROG.SYM.
  269.  
  270. The format of the file is lines consisting of hex constants,
  271. space and the ascii symbolic name associated with it. Below is
  272. such an example. Note that underscore and dollar characters are
  273. valid.
  274.  
  275.      034F nmi_
  276.      03C7 wrt_reg
  277.      04DB continue
  278.      046C wrt$hex
  279.      052B start
  280.  
  281. The second format is the file that is generated by the MSDOS
  282. linker and assumes the file extension MAP. This will be of use
  283. to many users because this linker comes free with your DOS disk
  284. and is used by many compilers and assemblers.
  285.  
  286. bXd will try to load a file of the SYM format file first. If that is
  287. not found then it tries the MAP format file.
  288.  
  289.  
  290.  
  291. REGISTRATION INFORMATION:
  292.  
  293. If you use this software regularly and haven't registered, please
  294. do so. The fee is thirty five dollars. For that, you receive the
  295. latest version, instructions on how to build the switch, help
  296. with the internals of the program and personal thanks.
  297.  
  298. Please send the fee to:
  299.  
  300.                           Sonam G Gyato
  301.                    7018 Bergenline Avenue, 2a
  302.                      North Bergen, NJ 07047
  303.  
  304. [SGG 6 Nov, 1986]
  305.