

                              Insight 1.20


                            Short description.


                       Recent changes - 04.02.2007


   Copyright (c) Victor Gamayunov, Sergey Pimenov, 1993, 96, 97, 2002








    This Description is not detailed and full manual for the work with
  debugger. It  contains  information  on  the  main  differences  and
  features of this debugger.  The  Description  is  not  intended  for
  beginners, which have no skill of the work with applications of such
  type. So here described only the  purpose  of  the  menu  items  and
  keyboard shortcuts and do  not  described  cardinal  principles  and
  methods of the debugging and "debugging" programs.

    The differences between versions of the debugger are described  in
  the file called whatsnew.txt. Also in this file  is  found  list  of
  fixed bugs and documented errors.








  1. CONTENTS




  1.       Contents

  2.       Copyright and license

  3.       Running debugger
  3.1.     System requirements
  3.2.     Command line parameters

  4.       Short description of debugger's interface
  4.1.     Main windows of debugger
  4.2.     Menu system
  4.3.     Keyboard usage
  4.4.     Dialog windows
  4.5.     Numerical constants and addresses

  5.       Description of debugger's windows
  5.1.     Code/assembler window
  5.1.1.   Code window
  5.1.2.   Disassembler
  5.1.3.   Assembler
  5.2.     Dump window
  5.3.     Registers window
  5.4.     Flags window
  5.5.     Stack window

  6.       Configuration
  6.1.     Disassembler mode
  6.2.     Screen mode

  7.       Debugging
  7.1.     Loading a program
  7.2.     Running a program
  7.3.     Breakpoints

  8.       Code and data navigation
  8.1.     Go to address
  8.2.     Data watch
  8.3.     Code marks and Data marks

  9.       Working with data
  9.1.     Search/Fill string
  9.2.     Data searching
  9.3.     Copying memory block
  9.4.     Filling memory block
  9.5.     Writing memory block to a file
  9.6.     Reading memory block from a file

  10.      Appendix 1: menu system
  10.1.    Main menu
  10.2.    Code window menu
  10.3.    Dump window menu
  10.4.    Registers window menu
  10.5.    Flags window menu

  11.      Appendix 2: keyboard shortcuts
  11.1.    Code window
  11.2.    Dump window
  11.3.    Registers window
  11.4.    Flags window

  12.      Comments, suggestions, bug reports





  2. COPYRIGHT AND LICENSE



  Insight, real-mode debugger for MS-DOS / PC-DOS / FreeDOS.

  Copyright (c) Victor Gamayunov, Sergey Pimenov, 1993, 96, 97, 2002.

  Improvements by Oleg O. Chukaev, 2006, 2007.

    This program is free software;  you  can  redistribute  it  and/or
  modify it under the terms of  the  GNU  General  Public  License  as
  published by the Free Software Foundation; either version 2  of  the
  License, or (at your option) any later version.

    This program is distributed in the hope that it  will  be  useful,
  but WITHOUT ANY WARRANTY;  without  even  the  implied  warranty  of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR  PURPOSE.  See  the  GNU
  General Public License for more details.

    You should have received a copy of the GNU General Public  License
  along with  this  program;  if  not,  write  to  the  Free  Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
  USA





  3. RUNNING DEBUGGER





  3.1. System requirements


    The debugger can be executed  on  any  x86-family  computer  under
  control of MS-DOS version 3.3 and above (and compatible with  them).
  For functioning is required (extremely desirable) color monitor  and
  EGA, VGA or SVGA videocard. Probably, CGA can be used, but when work
  with such adapter will appear the "snow" effect. The mouse will  not
  help in work.

    The debugger requires  about  30KB  of  free  disc  space  and  on
  documentation twice as large. When working debugger  occupies  about
  45KB of RAM.



  3.2. Command line parameters


    Command line syntax:

       insight [options] [progname [progparams]]

       options     - debugger's options;

       progname    - name of program to debug;

       progparams  - command line parameters for program to debug.


    Possible options of the debugger:

        Option                      Purpose
     
           /?       show short help
           /h       same as /?
           /r       terminate and stay resident in memory
           /u       unload resident debugger
           /e       assume EGA adapter installed

                               Table 3.1

    If debugger ran without key "/r", it is possible to leave it in
  memory residently, using menu item File|Resident.





  4. SHORT DESCRIPTION OF DEBUGGER'S INTERFACE





  4.1. Main windows of debugger


    Debugger's screen divided into 5 windows:  Code/Assembler  window,
  Dump window, Registers window, Flags window and  Stack  window.  Any
  windows (except for the stack window) can be active. The main window
  is a window  of  the  code.  Transition  to  any  other  window  and
  activation of main menu possible only from the code window with help
  of Edit menu or keyboard combinations. In the Table 4.1  are  showed
  corresponding keyboard combinations and menu items. To return to the
  code window, press Esc or Enter.

                Window         Menu            Keys
            
              Assembler    Edit|Assembler     Shift+A
              Dump         Edit|Dump          Shift+D
              Registers    Edit|Registers     Shift+R
              Flags        Edit|Flags         Shift+F

                               Table 4.1



  4.2. Menu system


    The debugger's menu system consists of the  main  menu  and  local
  menus of the windows. The main menu (Fig. 4.1) is hidden in inactive
  state, it can be activated with the keystroke of Alt or F10.
  Work with menu produced in the usual way.

    The local menu is activated by pressing  Alt+F10  combinations  in
  corresponding window.

    The detailed description of the purpose of the main and local menu
  items located in corresponding sections, and a short description  of
  all menus - in chapter 10.

     File   Edit   Run   Breakpoints   Options   Window
     ^      ^      ^     ^             ^         ^
                                             commands for work
                                               w/ the main window
                                    options submenu
                       commands for working with breakpoints
                  commands for running and tracing the program
            commands for switching to different windows
      commands for exiting, loading new program, etc.


   Ŀ
    File 
   Ŀ
    Load...     F3   load new program into debugger
    New              terminate debugging
   Ĵ
    About...         show information about debugger
   Ĵ
    Resident         exit from debugger leaving it in memory
    Exit     Alt+X   exit from debugger
   
     

   Ŀ
    Edit 
   Ŀ
    Assembler  Shift+A   switch to assembler mode
    Dump       Shift+D   go to dump window
    Registers  Shift+R   go to registers window
    Flags      Shift+F   go to flags window
   
     

   Ŀ
    Run 
   Ŀ
    Run            Ctrl+F9   run program
    Go to cursor        F4   run program to cursor
    Trace into          F7   execute single instruction
    Step over           F8   execute single instr., skip over
    Animate...               [not yet implemented]      calls
   Ĵ
    Arguments...             set command line arguments
    Program reset  Ctrl+F2   reload program
   
     

   Ŀ
    Breakpoints 
   Ŀ
    Set/Clear      F2   set / clear breakpoint
    Activity   Alt+F2   enable / disable breakpoint
    Edit...             [not yet implemented]
   Ĵ
    Enable  all         enable all breakpoints
    Disable all         disable all breakpoints
    Delete  all         delete all breakpoints
   
     

   Ŀ
    Options 
   Ŀ
    CPU for disassembler     set disassembler mode
    Screen swapping          set screen mode
    Configuration...          [not yet implemented]
   
     

   Ŀ
    Window 
   Ŀ
    Refresh display     F5   redraw debugger's screen
    User screen     Alt+F5   show program's screen
   
     

                                Fig. 4.1



  4.3. Keyboard usage


    For performing majority of actions quicker and comfortably to  use
  the special combinations of the keys. The list  of  all  combination
  and their purposes located in chapter 11, but minute  description  -
  in chapters of this Description.  Some actions can be executed  with
  the help of such combination only, but some seldom  executed actions
  - only at the main menu (eg, some tunings).



  4.4. Dialog windows


    In debugger are used dialog windows, which contains usual for such
  sort of the windows  elements:  buttons,  input  lines,  etc,  which
  little differ on its purpose and  operation  from  analogue  in  the
  other applications. For work with these element  are  used  standard
  ways, but keyboard combinations Alt+letter are not  supported.  Also
  does not work the overwrite mode in the input lines.



  4.5. Numerical constants and addresses


    Everywhere  in  debugger  are  used  only   positive   hexadecimal
  constants. Use decimal and binary numbers  are  not  provided.  When
  writing the constants it is not necessary to use  some  prefixes  or
  suffixes. Value of the constant can not be more than  FFFF  (65535).
  For example, valid constant will be 0, 10,  1245,  C0DE,  00FF,  but
  inadmissible - 0xFFFF, 12h, 111111, etc.

    The  addresses  in  dialog  windows  are  written  in   the   form
  "segment:offset".  The  segment  and  offset  are   an   unnecessary
  parameters and can be omitted.  Value of the offset  should  not  be
  enclosed in brackets. As a segment and  offset  simple  arithmetical
  expressions can be specified, using only operations "+" and "-".  In
  these expressions is allowed use of the numeric constants, values of
  some 16-bit registers  (ax, bx, cx, dx, si, di, bp, sp, ip, fl)  and
  values of segment registers (cs, ds, es, ss, fs, gs).  When use  the
  registers names in calculation of the address are used values, which
  are found in registers.


    Examples  of  the  correct  addresses:  cs:100,  FFFF:0,   ds:417,
  es:di+100, ds:si-1, es:di+bx-5, ax.

    The address expressions, which are used in  assembler  instruction
  (the Search  window,  the  Fill  Block  window,  the  code/assembler
  window), can contain only numeric constants,  because  the  register
  names is translated into instructions.





  5. DESCRIPTION OF DEBUGGER'S WINDOWS





  5.1. Code/assembler window


  5.1.1. Code window

    The code window is the main working window of the  debugger  (Fig.
  5.1). It displays disassembled in accordance with  chosen  processor
  (6.1) instructions, breakpoints, editing the  commands  produced  in
  this window.

         AuthenticAMD 486  Debugger N82538874.S04a ͸
        014A  F8             clc                              
        014B  C3             ret                              
        014C  83C303         add     bx,0003                  
        014F  E2F2           loop    0143                    
        0151  F9             stc                              
        0152  C3             ret                              
        0153  E8A31C         call    1DF9                     
        0156  3445           xor     al,45                    
        01588B1E9078       mov     bx,[7890]               5
        015C  38876967       cmp     [bx+6769],al             
        0160  7408           jz      016A                    
        0162  33DB           xor     bx,bx                    
        0164  38066967       cmp     [6769],al                
        0168  75E7           jnz     0151                    
        016A  43             inc     bx                       
        016B  891E9078       mov     [7890],bx                
        016F  80FB05         cmp     bl,05                    
         15CB:0158  DS:7890 = 2601  DS:SI 

                                Fig. 5.1

    In higher part of code window is displayed type of the  processor,
  name of the debugger and its version number. For  processors,  which
  do not support the CPUID instruction,  model  of  the  processor  is
  displayed, for rest - a string, given by this instruction, and model
  number.  For  instance,  for  Intel  Pentium   will   be   displayed
  "GenuineIntel 586".

    The address of instruction under cursor appears in lower  part  of
  code window. For commands, that refers to memory  cell(s),  in  that
  place displayed  contents  of  that  cell(s).  Also  in  that  place
  displayed the state  of  data  watch  mode  (8.2).  The  numbers  in
  rightmost column of code window are  remembered  positions  of  code
  window (8.3).


  5.1.2. Disassembler

    The disassembler allows to view the instructions of the program in
  one of four modes: 8086/8088, 80286, 80386 and 80486.  The  mode  is
  assigned at menu Options|CPU for disassembler (6.1).

    For more demonstrative displaying of instruction the simple  color
  highlighting is used - an address of instruction, opcodes,  mnemonic
  of the instruction and  numeric  constants  displayed  in  different
  colors. Instructions, on which is installed  breakpoints  (7.3)  and
  their activity also displayed in different colors.  For jmp and call
  instruction is  in  addition  indicated  (in  the  form  of  arrows)
  direction  of  transmissions  of  control.  For   conditional   jump
  instructions, if that arrows have a brighter color then jump  occurs
  when that instructions executed.

    When target of the jump  instruction  is  the  same  or  the  next
  instruction, dollar-sign is used  to  display  target  address.  For
  example, jmp $+2.

    The segment prefixes, which are used in instructions  by  default,
  are omitted.

    The Ctrl+Left and Ctrl+Right combinations will change the  initial
  address  of  code  window  on  -1  and  +1  accordingly.   Use  this
  possibility if disassembler has wrong   detected  the  beginning  of
  command.


  5.1.3. Assembler

    The assembler allows to work only with  instruction  of  8086/8088
  processors and with two data instructions - db and dw. For switching
  to assembler mode is used item Edit|Assembler  in  main  menu,  item
  Assembler in local menu of code window or combination  Shift+A,  for
  exit - Enter or  Esc  keys.  If  exiting  with  the  Esc  key,  then
  instruction, which changed last, is restored.

    In assembler it is unnecessary to  enter  the  prefixes,  used  by
  default. Possible use of $ symbol at the addresses of transition.

    Note that assembler works with  8086/8088  instruction  only,  but
  disassembler can disassemble even the 80486 instructions. So if  you
  are found in the assembler  mode  and  press  Enter  on  80286-80486
  instruction, then assembler will try to process it  even  though  it
  was not edited, but was  produced  by  disassembler.  Message  about
  error will be issued as a result.



  5.2. Dump window


    The dump window (Fig. 5.2) is located under the  code  window  and
  shows the data, residing on chosen address, in two  form  -  in  the
  hexadecimal form (on the left) and in the  character  form  (on  the
  right). Being in this window possible to edit memory content in  any
  of these two forms. Moving from one type to the other is realized by
  Tab key. The  Ctrl+Left  and  Ctrl+Right  combinations  changes  the
  initial address of dump window on -1 and +1.

    Current byte marked by color highlighting in both parts of window,
  flickering cursor indicates that part, in which is realized editing.
  Changed bytes can't be restored.

 15CB:6DF8  DS:7872 = 5500 
            B  C  D  E  F  0  1  2  3  4  5  6  7  8  9  A
15CB:713B  4D 65 6D 6F 72 79 20 61 6C 6C 6F 63 61 74 69 6F   Memory allocatio
15CB:714B  6E 20 65 72 72 6F 72 24 43 61 6E 27 74 20 72 65   n error$Can't re
15CB:715B  6C 65 61 73 65 20 64 65 62 75 67 67 65 72 20 6D   lease debugger m
15CB:716B  65 6D 6F 72 79 24 44 65 62 75 67 67 65 72 20 6E   emory$Debugger n
15CB:717B  6F 74 20 66 6F 75 6E 64 20 69 6E 20 6D 65 6D 6F   ot found in memo

                                Fig. 5.2



  5.3. Registers window


    The registers window (Fig. 5.3) can work in two modes - 16-bit (a)
  and 32-bit (b). The second mode  possible  only  on  computers  with
  processor 80386 and above. Mode can be changed with item  "16/32-bit
  regs" in local menu of code or registers window, or with  Ctrl+R  in
  that windows. When working in 32-bit mode, registers window  have  a
  greater size, while size of the stack window reduced.

    AX=0000  SI=0100  CS=15CB            EAX=0000:0000     CS=15CB
    BX=0000  DI=FFFC  DS=15CB            EBX=0000:0000     DS=15CB
    CX=00FF  BP=091C  ES=15CB            ECX=0000:00FF     ES=15CB
    DX=15CB  SP=FFFC  SS=15CB            EDX=0000:15CB     SS=15CB
                                         ESI=0000:0100     FS=0000
    IP=0100        Flags=7202            EDI=0000:FFFC     GS=0000
                
                                          EBP=0000:091C     IP=0100
                                          ESP=0000:FFFC  Flags=7202
                                          

                a.                                       b.
                               Fig. 5.3

    Being in  registers  window   possible  to  change  their  values,
  entering value directly or  using  special  commands.  To  increment
  contents of the register choose the item Increment in local menu  or
  press Ctrl+I, to decrement - choose  the  item  Decrement  or  press
  Ctrl+D. The Register is clears by command Zero or Ctrl+Z.

    That registers, which value  is  changed,  displayed  with  bright
  color.  Initial value of the register  can  be  restored  after  all
  changes. For restoring the value of  one  of  the  registers  it  is
  necessary to set the cursor on this register  and  choose  the  item
  Restore in local menu of registers window or press Ctrl+O.  Thereby,
  possible restore value of any register.  For restoring the values of
  all registers is used item Restore all in local menu of registers or
  code window, or keyboard combination Ctrl+A  in  the  same  windows.
  Herewith restored values of all  registers,  except  for  CS:IP  and
  flags register. For restoring CS:IP  possible  to  use  the  command
  Restore or special command Restore CS:IP (the  combination  Ctrl+C).
  For restoring the flags register there is  also  special  menu  item
  Restore flags, which corresponds to the combination Ctrl+T.

    After performing the step of the program or at interruption of the
  execution on  breakpoint,  changed  registers  displayed  with  same
  bright color. Values of registers can be restored.  After  switching
  to registers or flags window such restoring will become impossible.



  5.4. Flags window


    The flags window (Fig. 5.4) changes its location depending on mode
  of registers window. When register window displays 32-bit registers,
  this window located on several lines lower.

    The flags window allows to change values  of  separate  flags.  If
  flag is set then it displayed as 1, if  cleared  -  as  0.  You  can
  directly assign value to flag or  switch  it  to  opposite  by  item
  Toggle in local menu or by pressing spacebar. The item Restore flags
  in local menu or Ctrl+T will restore all flags.

                      
                       OF DF IF SF ZF AF PF CF
                        0  0  1  0  0  0  0  0
                      

                                Fig. 5.4



  5.5. Stack window


    The stack window (Fig. 5.5) can't  be  activated.  It  shows  only
  several values, which are found on top of the stack.  When  register
  window displays 32-bit registers, this  window  becomes  less  on  3
  lines, than when displaying 16-bit registers.

                       
                        Stack: SS:000A  088C
                               SS:0008  F01D
                               SS:0006  FEF0
                               SS:0004  9A00
                               SS:0002  A000
                               SS:0000  20CD
                               SS:FFFE  0000
                        SS:SP SS:FFFC  0000
                       

                                Fig. 5.5





  6. CONFIGURATION





  6.1. Disassembler mode


    The disassembler of the debugger can disassemble the  instructions
  of the processor i486. In some cases, it is necessary to display the
  instructions of determined processor only, for  example,  8086.  The
  menu Options|CPU  for  disassembler  serves  for  changing  mode  of
  disassembler.

   Ŀ
    Options 
   Ŀ
    CPU for disassembler   
    Screen swappĿ
    Configuratio 8086/8088     8086 mode
   ĳ 80286         80286 mode
     ۳ 80386         80386 mode
                  80486         80486 mode
                 Ĵ
                  Auto detect   automatically detect type
                       of processor
                   

                                Fig. 6.1

    In this menu (Fig. 6.1) possible to choose the necessary  type  of
  the processor, or point Options|CPU for disassembler|Auto detect. In
  the last case, the mode of disassembler is depends on  type  of  the
  processor of the computer, on which debugger executed. For processor
  i486  and  above  used  80486  mode.  When  starting  the  debugger,
  disassembler mode is defined automatically.



  6.2. Screen mode


    The debugger works with screen directly, preventions of the "snow"
  effect on CGA videocard is not  produced.  If  videocard  compatible
  with VGA, then debugger works in mode 80x25.  The  debugged  program
  can work in any videomode.  The VGA registers, screen of the program
  and fonts are saved when switching on screen  of  the  debugger  and
  restored at inverse switching. If videocard incompatible with VGA or
  key "/e" was specified, then only screen  of  the  debugged  program
  (4000 bytes) saved.  When working in text mode with  amount  of  the
  lines greater than 25, window of the debugger will  be  situated  in
  higher part of the screen, lower part will  contain  information  of
  the program ("garbage").  When work with applications, which use the
  graphics mode, is used mode switching without clearing  videomemory.
  Usually herewith partly spoils the higher part of the screen of  the
  program.

    When debugging the program  possible  to  specify  the  way,  what
  debugger must  work  with  screen  of  the  debugged  program.  This
  possible do at menu Options|Screen swapping (Fig. 6.2).

   Ŀ
    Options 
   Ŀ
    CPU for disassembler   
    Screen swapping        
    Configuration.Ŀ
   ĳ None       do not switch screen
     ۳ Smart      switch screen on certain
                    Always    Ŀ  instructions
                       switch screen on each step
                     

                                Fig. 6.2

    In mode Always debugger is switched  on  screen  of  the  debugged
  program on any start the program on execution (single step,  run  to
  cursor, etc.). In mode None only  information  of  the  debugger  is
  displayed on the screen, when starting the  program,  debugger  does
  not switch to its screen. In mode Smart screens are switched only in
  certain cases: when starting the program, when running to cursor and
  when executing instruction, which  can  change  the  screen  of  the
  program.

    At any time possible to look the screen of the  debugged  program,
  by choosing menu item Window|User screen or by  pressed  Alt+F5.  If
  the program execution has brought about  damage  of  the  debugger's
  screen,  then  screen   redraw   possible   by   using   menu   item
  Window|Refresh display or by pressing F5.





  7. DEBUGGING





  7.1. Loading a program


    You can load the program in debugger by specifying its name  (with
  extension!) and parameters in command line (3.2) or  by  using  item
  File|Load in main menu (F3). In the last case  you  can  choose  the
  file in dialog window Load a File. In this dialog possible to choose
  the file from list of the files of the current directory, or specify
  the path to the necessary file in the input line Name.

    When loading the  program  at  dialog  window  Load  a  File,  the
  parameters of the program must be specified apart, in dialog  window
  Arguments, which is called by  command  Run|Arguments.  This  dialog
  window is used if it is necessary to change the command line of  the
  program.

    If it is necessary to load in  debugger  the  program,  which  was
  right before debugged or is debugged, again, then  choose  the  menu
  item Run|Program reset or press Ctrl+F2.  Herewith  stops  debugging
  the program, program is loaded again, breakpoints and  command  line
  are saved. The other way to break the program execution  -  use  the
  menu item File|New. In this case the debugging of the program stops,
  the program is not loaded again, all  breakpoints  deleted,  command
  line cleared.



  7.2. Running a program


    To start the program you can choose the menu item Run|Run or press
  Ctrl+F9. Program is executed until termination or  until  breakpoint
  (int 3 instruction). For single step execution use the commands Run|
  Trace into (F7) and Run|Step over (F8). If the second command  used,
  then call, int, loop instructions and work  with  strings  does  not
  traced as when use the first command.  If  some  procedure  contains
  breakpoint, then stop on it will occur. The command Run|Go to cursor
  (F4) allows to execute the area of the program  before  instruction,
  on which cursor is found in code window.

    If it is necessary  to  assign  new  value  to  CS:IP,  then  this
  possible in two ways  -  assign values  to  registers  in  registers
  window or move cursor to necessary instruction in  code  window  and
  press Ctrl+N (the item New CS:IP in local menu) and this instruction
  will become the new current instruction.



  7.3. Breakpoints


    The debugger allows to set up to 10 breakpoints. Set breakpoint by
  pressing F2 (or  by  choosing  menu  item  Breakpoints|Set/Clear) on
  chosen instruction. If given instruction already contain breakpoint,
  then this breakpoint will be removed. Breakpoints are highlighted in
  the code window.

    It is possible to temporary disable the breakpoint (the breakpoint
  does not deleted, but program will not stop on it). To do  this  set
  code window cursor on  breakpoint  and  press  Alt+F2  (Breakpoints|
  Activity). The next pressing  Alt+F2  will  enable  the  breakpoint.
  Disabled breakpoints are highlighted with another color.

    As a  matter  of  convenience  possible  to  use  the  menu  items
  Breakpoints|Delete all for deleting  all  breakpoints,  Breakpoints|
  Disable all - for disabling all breakpoints  and  Breakpoints|Enable
  all - for enabling all breakpoints.





  8. CODE AND DATA NAVIGATION





  8.1. Go to address


    For code and data are used different commands of the transition to
  necessary address, moreover one commands are issued from code window,
  others - from dump window, but the third - from both code  and  dump
  windows.

    If it is necessary to display in code window  destination  address
  of jump, call or int instruction, then it is necessary to choose the
  item Code position|Follow in local menu of  code  window,  or  press
  Ctrl+F or Enter.  You can directly specify the  initial  address  of
  code  window  in  dialog   window   Goto   caused   by   item   Code
  position|Address (Ctrl+G). To return to the current instruction  use
  the item Code position|Origin (Ctrl+O or Ctrl+Enter).

    All transition in code window are remembered in special  stack  so
  it is possible to return to previous position using menu  item  Code
  position|Previous (Ctrl+P or Backspace).  This stack uses the memory
  area, which is also used for the other purposes. Because of this can
  occur the situation, when part of stack data will be  corrupted.  In
  this case debugger will show warning and will clean the stack.

    Under active dump window you can to position the  code  window  on
  the address, which contained in bytes under cursor. In this case two
  bytes interpreted as new offset for disassembler (near  pointer)  or
  as new segment for disassembler (far pointer with  offset  0).  Four
  bytes interpreted as offset and segment  of  the  new  address  (far
  pointer). To set new address of dump window you can select item Dump
  follow from local menu of dump window, or press Ctrl+F.  In appeared
  submenu the item Near code allows to set the  new  offset  for  code
  window, Far code - a new offset and segment, Code segment  -  a  new
  segment and offset 0.

    You can specify initial address  of  the  dump  window  in  dialog
  window Goto using menu item  Dump  position|Address  (Ctrl+D).  This
  menu item exist in local menus of both code  and  dump  windows.  If
  instruction, on which is located cursor of code  window,  refers  to
  memory cell, then address of this cell can be used  as  initial  for
  dump window - use the  item  Dump  position|Reference  (Alt+=).  The
  additional items of local menus of code and dump windows  allows  to
  use contents of some registers pairs as a  new  initial  address  of
  dump window. See the Table 8.1.

           Menu item      Keys             Purpose
         
           Dump DS:SI     Alt+D     set window to DS:SI
           Dump ES:DI     Alt+E     set window to ES:DI
           Dump SS:BP     Alt+S     set window to SS:BP
           Dump CS:IP     Alt+C     set window to CS:IP
           Dump ES:BX     Alt+B     set window to ES:BX
           Dump ES:SI     Alt+I     set window to ES:SI
           Dump DS:DX     Alt+F     set window to DS:DX
           Dump DS:DI     Alt+J     set window to DS:DI
           Dump DX:AX     Alt+A     set window to DX:AX
           Dump code      Alt+L     set window to address
                                    of current instruction
                                    in code window
           User screen    Alt+U     set window to address
                                    of buffer with data
                                    from user screen

                               Table 8.1

    You can use address under dump window cursor as initial address of
  dump window, similarly to positioning code window. Choose menu  item
  Near data, Far data or Data segment from submenu Dump follow,  which
  also invoked by Ctrl+F.



  8.2. Data watch


    If it is necessary to  watch  the  memory,  on  which  points  the
  changing registers pair, then possible  the  use  of  data  watching
  function. When this function turned on the data window automatically
  positioned in accordance with a chosen registers pair.  For example,
  at examination of the work with string can be needed  to  view  that
  byte, on which DS:SI points. Data watching allows automatically  set
  dump window to necessary address after each step.

    To turn this mode on it is necessary to set dump window using  one
  of the combinations from Table 8.1, then press Ctrl+W or choose  the
  item Data watch in local menu of code window. After  this  the  dump
  window will be updated automatically. The repeated  pressing  Ctrl+W
  switches this mode off.



  8.3. Code marks and Data marks


    It is possible to save current position of code or dump window. Up
  to 10 positions can be saved. Work with marks possible in  the  code
  window only. To save position of code  window  you  need  to  go  to
  required address and set cursor to required instruction.  Then press
  Alt and numeral - a number of mark.  Number  of  the  mark  will  be
  displayed in the rightmost column of code  window.  To  go  to  mark
  press corresponding number. To move the mark to new place simply set
  this mark in new place. To delete mark press Shift and corresponding
  number.

    To set mark in dump window press Shift+Alt+number. Marks  in  dump
  window are not displayed. Moving to mark and removing the  mark  are
  produced similarly.





  9. WORKING WITH DATA





  9.1. Search/Fill string


    In the Search (9.2) and Fill (9.4)  dialog  windows  necessary  to
  specify the data for searching or  filling.  As  such  data  can  be
  specified hexadecimal  byte  values,  the  sequences  of  characters
  (strings) and instructions. Semicolon must  follows  each  assembler
  instruction, bytes and strings must  be  separated  with  spaces  or
  semicolons.  The  strings  are  enclosed  in  quotation   marks   or
  apostrophes. If there is an apostrophe in string, that  line  it  is
  necessary to enclose in quotation  marks,  but  if  quotation  marks
  present in the string - in apostrophes. When meet both symbols it is
  necessary to split the string on several. For example, the following
  search/fill strings are valid:

    90 nop; nop

    1 2; 3 "abc" '"'

    cmp ax,1; 90

    If string contains  the  assembler  instructions,  using  relative
  addressing (for example, call  near  or  jmp  near),  that  as  base
  address is used current value of CS:IP.



  9.2. Data searching


    Search window appears  after  pressing  Ctrl+S  or  choosing  item
  Search bytes in local  menu  of  code  or  dump  window.  If  it  is
  necessary to find the next copy of  the  same  data,  use  the  item
  Search again (Ctrl+L) of local menu.

    In the input line "Search for" it is  necessary  to  specify  data
  (9.1), in the input line "Address" - an initial address of searching,
  among flags "Options" - choose  necessary.  They  have  a  following
  purpose:

    Ignore case - ignore differences in case of characters;

    Backward - unless it  is  set,  search  for  data  from  specified
  address to the end  of  memory,  but  if  it  is  set  -  search  to
  beginning of memory (searching in reverse direction);

    Exclude HMA - if this flag is not set, then data are  searched  in
  all memory, including HMA, above 1MB. If A20 is  not  enabled,  that
  will occur transition to beginning of the memory. If  this  flag  is
  set, then data are searched only within 1MB. This  flag  meaningless
  when searching in reverse direction.

    Result in code - if this flag is not set then dump window will  be
  set to beginning of found data, if this flag is set - code window.



  9.3. Copying memory block


    The debugger allows to copy  the  memory  areas,  fill  them  with
  specified bytes, write them to file and read  them  from  file.  For
  work with blocks (memory areas) is intended special local menu (Fig.
  9.1), which can be called by  pressing  Ctrl+B  from  code  or  dump
  window or from local menu of dump window.

  Ŀ
   Copy...       copy memory block
   Fill...       fill memory block
   Write...      write memory block to a file
   Read...       read memory block from a file
  
    

                                Fig. 9.1

    To copy memory block use the  Copy Block  dialog  window.  Specify
  source address (From), destination address (To) and amount of  bytes
  to copy (Count). Copying is produced by usual 16-bit instruction rep
  movsb, with all resulting consequences: you  can't  copy  more  than
  64KB of data, in  certain  cases  can  occur  cyclic  overflow  (for
  example, when offset + counter > 10000h).



  9.4. Filling memory block


    Filling the area of memory is produced similarly to copying, using
  dialog window Fill Block. Specify initial address (From), amount  of
  repetitions (Count) and value (9.1) which must be written to  memory
  (Fill with).  Can't be filled more than 64KB.  The bytes defined  by
  line Fill with, are written Count times.



  9.5. Writing memory block to a file


    It is possible to write memory block to a  file  on  disk.  Former
  restrictions are superimposed on size of the block. Specify filename
  (File name), the address of block (From) and size of block in  bytes
  (Count). If the file with such name  already  exists,  you  will  be
  asked to rewrite the existing file or to add the block to it.



  9.6. Reading memory block from a file


    Reading data from file to memory produced in  similar  way,  using
  dialog window Read Block.





  10. APPENDIX 1: MENU SYSTEM





  10.1. Main menu


  File
  ~~~~
    Load
        Load new program into non-resident debugger (F3, chapter 7.1)

    New
        Prepare debugger to debugging a new program (chapter 7.1)

    About
        Show information about debugger and it's authors

    Resident
        Exit from debugger leaving it in memory (chapter 3.2)

    Exit
        Exit from debugger if it is not a TSR (Alt+X)

  Edit
  ~~~~
    Assembler
        Switch to assembler mode (Shift+A, chapter 5.1.3)

    Dump
        Go to dump window (Shift+D, chapter 5.2)

    Registers
        Go to registers window (Shift+R, chapter 5.3)

    Flags
        Go to flags window (Shift+F, chapter 5.4)

  Run
  ~~~
    Run
        Run program (Ctrl+F9, chapter 7.2)

    Go to cursor
        Run program to current cursor position (F4, chapter 7.2)

    Trace into
        Execute single instruction (F7, chapter 7.2)

    Step over
        Execute single instruction, skip over calls (F8, chapter 7.2)

    Animate
        Not yet implemented

    Arguments
        Set command line arguments for debugged program (chapter 7.1)

    Program reset
        Terminate debugging and reload program (Ctrl+F2, chapter 7.1)

  Breakpoints
  ~~~~~~~~~~~
    Set/Clear
        Set / clear breakpoint (F2, chapter 7.3)

    Activity
        Enable / disable breakpoint (Alt+F2, chapter 7.3)

    Edit
        Not yet implemented

    Delete all
        Delete all breakpoints (chapter 7.3)

    Enable all
        Enable all breakpoints (chapter 7.3)

    Disable all
        Disable all breakpoints (chapter 7.3)

  Options
  ~~~~~~~
    CPU for disassembler
    ~~~~~~~~~~~~~~~~~~~~
      8086/8088
        8086/8088 mode (chapter 6.1)

      80286
        80286 mode (chapter 6.1)

      80386
        80386 mode (chapter 6.1)

      80486
        80486 mode (chapter 6.1)

      Auto detect
        Automatically detect disassembling mode (chapter 6.1)

    Screen swapping
    ~~~~~~~~~~~~~~~
      None
        Do not switch to program's screen while debugging (chapter 6.2)

      Smart
        Switch  to  program's  screen  only  on  certain  instructions
        (chapter 6.2)

      Always
        Switch to program's screen on any instruction (chapter 6.2)

    Configuration
        Not yet implemented

  Window
  ~~~~~~
    Refresh display
        Redraw debugger's screen (F5, chapter 6.2)

    User screen
        Show screen of the program being debugged (Alt+F5, chapter 6.2)




  10.2. Code window menu


    Assembler
        Switch to assembler mode (Shift+A, chapter 5.1.3)

    New CS:IP
        Set CS:IP to address  of  instruction  under  cursor  (Ctrl+N,
        chapter 7.2)

    16/32-bit regs
        Switch between 16-bit and 32-bit mode (Ctrl+R, chapter 5.3)

    Data watch
        Turn on/off data watch mode (Ctrl+W, chapter 8.2)

    Dump position
    ~~~~~~~~~~~~~
      Address
        Set initial address of dump window (Ctrl+D, chapter 8.1)

      Reference
        Use address, on which current instruction refers,  as  initial
        address of dump window (Alt+=, chapter 8.1)

      User screen
        Use address of buffer with content of the program's screen  as
        initial address of dump window (Alt+U, chapter 8.1)

      Dump DS:SI
        Use value of DS:SI as initial address of dump  window  (Alt+D,
        chapter 8.1)

      Dump ES:DI
        Use value of ES:DI as initial address of dump  window  (Alt+E,
        chapter 8.1)

      Dump SS:BP
        Use value of SS:BP as initial address of dump  window  (Alt+S,
        chapter 8.1)

      Dump CS:IP
        Use value of CS:IP as initial address of dump  window  (Alt+C,
        chapter 8.1)

      Dump ES:BX
        Use value of ES:BX as initial address of dump  window  (Alt+B,
        chapter 8.1)

      Dump ES:SI
        Use value of ES:SI as initial address of dump  window  (Alt+I,
        chapter 8.1)

      Dump DS:DX
        Use value of DS:DX as initial address of dump  window  (Alt+F,
        chapter 8.1)

      Dump DS:DI
        Use value of DS:DI as initial address of dump  window  (Alt+J,
        chapter 8.1)

      Dump DX:AX
        Use value of DX:AX as initial address of dump  window  (Alt+A,
        chapter 8.1)

      Dump code
        Use address of current instruction as initial address of  dump
        window (Alt+L, chapter 8.1)

    Code position
    ~~~~~~~~~~~~~
      Address
        Set initial address of code window (Ctrl+G, chapter 8.1)

      Origin
        Use value of CS:IP as initial address of code  window  (Ctrl+O
        or Ctrl+Enter, chapter 8.1)

      Follow
        Follow jump, call,  ret  or  int  instruction  to  destination
        (Ctrl+F or Enter, chapter 8.1)

      Previous
        Return to previous displayed instruction (after Follow command)
        (Ctrl+P or Backspace, chapter 8.1)

    Restore CS:IP
        Restore CS:IP (Ctrl+C, chapter 5.3)

    Restore regs
        Restore all registers except for CS:IP and flags (Ctrl+A,
        chapter 5.3)

    Restore flags
        Restore flags register (Ctrl+T, chapters 5.3 and 5.4)

    Search bytes
        Search for data and/or instructions (Ctrl+S, chapter 9.2)

    Search again
        Find next sequence of bytes (Ctrl+L, chapter 9.2)



  10.3. Dump window menu


    Dump position
    ~~~~~~~~~~~~~
      Address
        Set initial address of dump window (Ctrl+D, chapter 8.1)

      Reference
        Use address, on which current instruction refers,  as  initial
        address of dump window (Alt+=, chapter 8.1)

      User screen
        Use address of buffer with content of the program's screen  as
        initial address of dump window (Alt+U, chapter 8.1)

      Dump DS:SI
        Use value of DS:SI as initial address of dump  window  (Alt+D,
        chapter 8.1)

      Dump ES:DI
        Use value of ES:DI as initial address of dump  window  (Alt+E,
        chapter 8.1)

      Dump SS:BP
        Use value of SS:BP as initial address of dump  window  (Alt+S,
        chapter 8.1)

      Dump CS:IP
        Use value of CS:IP as initial address of dump  window  (Alt+C,
        chapter 8.1)

      Dump ES:BX
        Use value of ES:BX as initial address of dump  window  (Alt+B,
        chapter 8.1)

      Dump ES:SI
        Use value of ES:SI as initial address of dump  window  (Alt+I,
        chapter 8.1)

      Dump DS:DX
        Use value of DS:DX as initial address of dump  window  (Alt+F,
        chapter 8.1)

      Dump DS:DI
        Use value of DS:DI as initial address of dump  window  (Alt+J,
        chapter 8.1)

      Dump DX:AX
        Use value of DX:AX as initial address of dump  window  (Alt+A,
        chapter 8.1)

      Dump code
        Use address of current instruction as initial address of  dump
        window (Alt+L, chapter 8.1)

    Dump follow
    ~~~~~~~~~~~
      Near data
        Use word under  cursor  as  initial  address  of  dump  window
        (chapter 8.1)

      Far data
        Use doubleword under cursor as initial address of dump  window
        (chapter 8.1)

      Data segment
        Use word under cursor  as  initial  segment  address  of  dump
        window (offset is 0) (chapter 8.1)

      Near code
        Use word under  cursor  as  initial  address  of  code  window
        (chapter 8.1)

      Far code
        Use doubleword under cursor as initial address of code  window
        (chapter 8.1)

      Code segment
        Use word under cursor  as  initial  segment  address  of  code
        window (offset is 0) (chapter 8.1)

    Block
    ~~~~~
      Copy
        Copy a memory block to a new address (chapter 9.3)

      Fill
        Fill a memory block with pattern (chapter 9.4)

      Write
        Write from a memory block to a file (chapter 9.5)

      Read
        Read to a memory block from a file (chapter 9.6)

    Search bytes
        Search for data and/or instructions (Ctrl+S, chapter 9.2)

    Search again
        Find next sequence of bytes (Ctrl+L, chapter 9.2)



  10.4. Registers window menu


    Increment
        Increment register (Ctrl+I, chapter 5.3)

    Decrement
        Decrement register (Ctrl+D, chapter 5.3)

    Zero
        Clear register (Ctrl+Z, chapter 5.3)

    Restore
        Restore register (Ctrl+O, chapter 5.3)

    Restore all
        Restore all registers except  for  CS:IP  and  flags  (Ctrl+A,
        chapter 5.3)

    Restore CS:IP
        Restore CS:IP (Ctrl+C, chapter 5.3)

    Restore flags
        Restore flags register (Ctrl+T, chapters 5.3 and 5.4)

    32-bit regs
        Switch between 16-bit and 32-bit mode (Ctrl+R, chapter 5.3)



  10.5. Flags window menu


    Toggle
        Toggle the state of the flag (Space, chapter 5.4)

    Restore flags
        Restore flags register (Ctrl+T, chapters 5.3 and 5.4)





  11. APPENDIX 2: KEYBOARD SHORTCUTS





  11.1. Code window


  number (n)
        Go to mark n (chapter 8.3)

  F1
        Short help

  F2
        Set / clear breakpoint (Breakpoints|Set/Clear, chapter 7.3)

  F3
        Load  new  program  into  non-resident  debugger   (File|Load,
        chapter 7.1)

  F4
        Run program to current  cursor  position  (Run|Go  to  cursor,
        chapter 7.2)

  F5
        Redraw debugger's screen (Window|Refresh display, chapter 6.2)

  F7
        Execute single instruction (Run|Trace into, chapter 7.2)

  F8
        Execute single instruction, skip over  calls  (Run|Step  over,
        chapter 7.2)

  Enter
        Follow jump, call,  ret  or  int  instruction  to  destination
        (Code position|Follow, Ctrl+F, chapter 8.1)

  Backspace
        Return to previous displayed instruction (after Follow command)
        (Code position|Previous, Ctrl+P, chapter 8.1)

  Shift+number (n)
        Delete mark n (chapter 8.3)

  Shift+A
        Switch to assembler mode (Edit|Assembler, chapter 5.1.3)

  Shift+D
        Go to dump window (Edit|Dump, chapter 5.2)

  Shift+F
        Go to flags window (Edit|Flags, chapter 5.4)

  Shift+R
        Go to registers window (Edit|Registers, chapter 5.3)

  Ctrl+Enter
        Use value of CS:IP as initial address of code  window (Origin,
        Ctrl+O, chapter 8.1)

  Ctrl+A
        Restore all registers except for CS:IP and flags (Restore regs,
        chapter 5.3)

  Ctrl+B
        Block menu (chapter 9.3)

  Ctrl+C
        Restore CS:IP (Restore CS:IP, chapter 5.3)

  Ctrl+D
        Set initial address  of  dump  window  (Dump position|Address,
        chapter 8.1)

  Ctrl+F
        Follow jump, call,  ret  or  int  instruction  to  destination
        (Code position|Follow, Enter, chapter 8.1)

  Ctrl+G
        Set initial address  of  code  window  (Code position|Address,
        chapter 8.1)

  Ctrl+L
        Find next sequence of bytes (Search again, chapter 9.2)

  Ctrl+N
        Set CS:IP to address of instruction  under  cursor (New CS:IP,
        chapter 7.2)

  Ctrl+O
        Use value of CS:IP as initial address of code  window (Origin,
        Ctrl+Enter, chapter 8.1)

  Ctrl+P
        Return to previous displayed instruction (after Follow command)
        (Code position|Previous, Backspace, chapter 8.1)

  Ctrl+R
        Switch between 16-bit and 32-bit mode (16/32-bit mode, chapter
        5.3)

  Ctrl+S
        Search for data and/or instructions (Search bytes, chapter 9.2)

  Ctrl+T
        Restore flags register (Restore flags, chapters 5.3 and 5.4)

  Ctrl+W
        Turn on/off data watch mode (Data watch, chapter 8.2)

  Ctrl+F2
        Terminate debugging and  reload  program  (Run|Program  reset,
        chapter 7.1)

  Ctrl+F9
        Run program (Run|Run, chapter 7.2)

  Alt+number (n)
        Set mark n in code window (chapter 8.3)

  Alt+=
        Use address, on which current instruction refers,  as  initial
        address of dump window (Dump position|Reference, chapter 8.1)

  Alt+A
        Use value of DX:AX as initial address  of  dump  window  (Dump
        position|Dump DX:AX, chapter 8.1)

  Alt+B
        Use value of ES:BX as initial address  of  dump  window  (Dump
        position|Dump ES:BX, chapter 8.1)

  Alt+C
        Use value of CS:IP as initial address  of  dump  window  (Dump
        position|Dump CS:IP, chapter 8.1)

  Alt+D
        Use value of DS:SI as initial address  of  dump  window  (Dump
        position|Dump DS:SI, chapter 8.1)

  Alt+E
        Use value of ES:DI as initial address  of  dump  window  (Dump
        position|Dump ES:DI, chapter 8.1)

  Alt+F
        Use value of DS:DX as initial address  of  dump  window  (Dump
        position|Dump DS:DX, chapter 8.1)

  Alt+I
        Use value of ES:SI as initial address  of  dump  window  (Dump
        position|Dump ES:SI, chapter 8.1)

  Alt+J
        Use value of DS:DI as initial address  of  dump  window  (Dump
        position|Dump DS:DI, chapter 8.1)

  Alt+L
        Use address of current instruction as initial address of  dump
        window (Dump position|Dump code, chapter 8.1)

  Alt+S
        Use value of SS:BP as initial address  of  dump  window  (Dump
        position|Dump SS:BP, chapter 8.1)

  Alt+U
        Use address of buffer with content of the program's screen  as
        initial address  of  dump  window  (Dump position|User screen,
        chapter 8.1)

  Alt+X
        Exit if debugger is not a TSR

  Alt+F2
        Enable / disable breakpoint (Breakpoints|Activity, chapter 7.3)

  Alt+F5
        Show screen of the program being debugged (Window|User screen,
        chapter 6.2)

  Alt+Shift+number (n)
        Set mark n in dump window (chapter 8.3)



  11.2. Dump window


  Ctrl+B
        Block menu (chapter 9.3)

  Ctrl+D
        Set initial address  of  dump  window  (Dump position|Address,
        chapter 8.1)

  Ctrl+F
        Follow menu (chapter 8.1)

  Ctrl+L
        Find next sequence of bytes (Search again, chapter 9.2)

  Ctrl+S
        Search for data and/or instructions (Search bytes, chapter 9.2)

  Alt+=
        Use address, on which current instruction refers,  as  initial
        address of dump window (Dump position|Reference, chapter 8.1)

  Alt+A
        Use value of DX:AX as initial address  of  dump  window  (Dump
        position|Dump DX:AX, chapter 8.1)

  Alt+B
        Use value of ES:BX as initial address  of  dump  window  (Dump
        position|Dump ES:BX, chapter 8.1)

  Alt+C
        Use value of CS:IP as initial address  of  dump  window  (Dump
        position|Dump CS:IP, chapter 8.1)

  Alt+D
        Use value of DS:SI as initial address  of  dump  window  (Dump
        position|Dump DS:SI, chapter 8.1)

  Alt+E
        Use value of ES:DI as initial address  of  dump  window  (Dump
        position|Dump ES:DI, chapter 8.1)

  Alt+F
        Use value of DS:DX as initial address  of  dump  window  (Dump
        position|Dump DS:DX, chapter 8.1)

  Alt+I
        Use value of ES:SI as initial address  of  dump  window  (Dump
        position|Dump ES:SI, chapter 8.1)

  Alt+J
        Use value of DS:DI as initial address  of  dump  window  (Dump
        position|Dump DS:DI, chapter 8.1)

  Alt+L
        Use address of current instruction as initial address of  dump
        window (Dump position|Dump code, chapter 8.1)

  Alt+S
        Use value of SS:BP as initial address  of  dump  window  (Dump
        position|Dump SS:BP, chapter 8.1)



  11.3. Registers window


  Ctrl+A
        Restore all registers except for CS:IP and flags (Restore regs,
        chapter 5.3)

  Ctrl+C
        Restore CS:IP (Restore CS:IP, chapter 5.3)

  Ctrl+D
        Decrement register (Decrement, chapter 5.3)

  Ctrl+I
        Increment register (Increment, chapter 5.3)

  Ctrl+O
        Restore register (Restore, chapter 5.3)

  Ctrl+R
        Switch between 16-bit and 32-bit mode (16/32-bit mode, chapter
        5.3)

  Ctrl+T
        Restore flags register (Restore flags, chapters 5.3 and 5.4)

  Ctrl+Z
        Clear register (Zero, chapter 5.3)



  11.4. Flags window


  0 and 1
        Clear / set the flag (chapter 5.4)

  Space
        Toggle the state of the flag (Toggle, chapter 5.4)

  Ctrl+T
        Restore flags register (Restore flags, chapters 5.3 and 5.4)





  12. COMMENTS, SUGGESTIONS, BUG REPORTS




    If you have an offers on thing that it  is  necessary  to  add  in
  debugger, or that it is necessary remove from it, or you have  found
  the exasperating error in program or in Description, that  we  shall
  pleased hear your opinion (information about error). You  may  write
  to the following address:

    Oleg O. Chukaev

       Internet:    oleg.chukaev@mail.ru

  The addresses of the authors of the debugger:

    Victor Gamayunov

       Internet:    tolstolob@mospravda.ru

    Sergey Pimenov

       Internet:    sergey@mospravda.ru

       FIDO:        2:5020/1039.1245

    If you want to report bug, then in detail describe the  situation,
  in which it has occurred.






