home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / progmisc / dmpprg20.zip / DUMPPROG.DOC < prev    next >
Text File  |  1992-11-25  |  12KB  |  276 lines
  1. DUMPPROG version 2.01 - Dump program file in mixed disassembly and source code.
  2.  
  3.   Copyright (c) D.J. Murdoch, 1991, 1992
  4.   Portions of disassembler copyright (c) 1992 Jeroen Pluimers, based on
  5.    public domain code by William Peavy
  6.  
  7. Syntax:  DUMPPROG [options] progname [selection]...
  8.  
  9.  reads map from progname.MAP and dumps executable progname.EXE
  10.  
  11.  Options (either '/' or '-' may be used):
  12.    /Exxx    Use source extension xxx if unspecified in MAP file.
  13.             Default is PAS.
  14.    /M       Dumpprog will write out .MAP information.
  15.    /O       Force DUMPPROG to dump using old .EXE format.
  16.    /A       Dump complete .EXE image.  (NB:  selections will override this.)
  17.    /Verbose Display verbose code.
  18.    /0 to /4 Choose instruction set: 8086 thru 80486.
  19.  
  20.    Selection - What to dump:
  21.      Name          - dumps public symbol or segment Name
  22.      [filename]#nn - dumps source line nn
  23.      ssss:oooo     - dumps specific hex address
  24.      Selection1-Selection2 - dumps from start of first selection
  25.                              to end of second one.
  26.      Generally any name used as a label in the dump may be used to
  27.      select a range to dump.
  28.  
  29. Examples:
  30.  
  31.   DUMPPROG myprog.exe
  32.     will use myprog.map for information, and assume .PAS extension.
  33.     Output will go to the screen.  Only code with source lines mentioned
  34.     in the .MAP file will be dumped.
  35.   DUMPPROG myprog.exe /A
  36.     will be as above, but the complete .EXE will be dumped.
  37.   DUMPPROG myprog /Epas >myprog.lst
  38.     will dump myprog.exe using myprog.map for information, and assume
  39.     that any source file with no extension should have .pas added,
  40.     putting the results into the file myprog.lst.
  41.   DUMPPROG myprog myproc
  42.     will dump myprog.exe, public symbol myproc.
  43.   DUMPPROG myprog myprog.pas#23-myproc
  44.     will dump myprog.exe, starting at source line 23 in myprog.pas,
  45.     and stopping at the end of myproc.
  46.   DUMPPROG myprog #34-#56
  47.     will dump myprog.exe source lines 34 to 56 (from every source file).
  48.   DUMPPROG kernel.exe entry.91
  49.     will dump the (Windows) kernel.exe routine INITTASK, which is entry
  50.     point 91.
  51.  
  52. Description:
  53.  
  54.   This program is designed to let you see disassembled output mixed with
  55.   source code, as some compilers will optionally output.  It can make
  56.   use of a detailed .MAP file from the compiler which includes source
  57.   files, public definitions and line number information.  If you don't
  58.   have one, it will try to construct a segment map; you must then
  59.   explicitly ask for particular parts of the file (using selection
  60.   parameters).
  61.  
  62.   I wrote it and tested it on the .EXE files and .MAP files produced by
  63.   various versions of Turbo Pascal and Borland Pascal; it should work
  64.   (but probably has bugs) on other programs.  To get a detailed map from
  65.   Turbo Pascal, use the $D+ (debugging info) and /GD options on the
  66.   command line, or set these options in the IDE.
  67.  
  68.   You can control which parts of a program are dumped by editing the
  69.   .MAP file, using selections, or using the /A option.
  70.  
  71.   If public symbols are defined in the map file, their locations will be
  72.   marked in the disassembly, and calls or jumps to them will be
  73.   identified.
  74.  
  75.   With new .EXE files (i.e. those for Windows, OS/2, or DOS extenders),
  76.   public symbols and entry points will be marked in the disassembly, and
  77.   can be used for selections.
  78.  
  79. Selections:
  80.  
  81.   The ideal selection logic would let you type what you mean, and
  82.   DUMPPROG would figure it out and dump it for you.  The actual logic
  83.   isn't quite that good, but it tries its best, building on some fairly
  84.   simple rules.
  85.  
  86.   If you give a single item, you get the dump from the start of it to
  87.   the end.  If you give a range using 'first-second', you get from the
  88.   start of first to the end of second.
  89.  
  90.   Individual items can be of several types:
  91.  
  92.      Any label taken from a dump can be used as an item, e.g.
  93.      "dumper.pas#236" or "dump_selection" taken from
  94.  
  95.         DUMP_SELECTION:
  96.         dumper.pas#236:  begin
  97.           008E:0A33 55              PUSH    BP
  98.           008E:0A34 89E5            MOV     BP,SP
  99.  
  100.      Source files can be specified in any way which would be equivalent
  101.      under DOS, with the /Exxx (default .PAS) extension added if no dot
  102.      is given.  If an exact line match isn't found in the .MAP, an
  103.      approximate one is used.  For example, "dumpprog#1" selects the
  104.      following fragment from the DUMPPROG source:
  105.  
  106.         SYNTAX_EXIT:
  107.         c:\stuff\dumpprog\dumpprog.pas#16:  begin
  108.           0000:0237 55              PUSH    BP
  109.           0000:0238 89E5            MOV     BP,SP
  110.           0000:023A 31C0            XOR     AX,AX
  111.           0000:023C 9ADF04CD0A      CALL    0ACD:04DF
  112.  
  113.      Addresses can be given in hex; a segment is required in the
  114.      first item, but not in the second, where the segment of the first
  115.      is assumed.  For example, "syntax_exit-23b" would select the first
  116.      three lines of disassembly above, as would "0:237-23b" or
  117.      "0:237-0:23b".
  118.  
  119.      By specifying segments explicitly, you can force DUMPPROG to ignore
  120.      the segmentation implied by the .MAP file in DOS programs.  It'll
  121.      complain; for example "23:7-23:b" gives the same range as above,
  122.      but the dump looks like this:
  123.  
  124.         Warning:  Segment incorrect!
  125.         SYNTAX_EXIT:
  126.         Warning:  Segment incorrect!
  127.         c:\stuff\dumpprog\dumpprog.pas#16:  begin
  128.           0023:0007 55              PUSH    BP
  129.           0023:0008 89E5            MOV     BP,SP
  130.           0023:000A 31C0            XOR     AX,AX
  131.  
  132.      Ambiguities (e.g. "0:0-abc", where it's not clear if "abc" is a hex
  133.      number or an identifier) are resolved in favour of the identifier.
  134.  
  135. DUMP2MSG:
  136.  
  137.   Turbo/Borland Pascal 7.0 and Borland C++ include an option in their
  138.   environments to install external tools.  I've written a "message
  139.   filter" called DUMP2MSG to let you install DUMPPROG as an external
  140.   tool; it allows you to point to the name of a routine, and obtain a
  141.   disassembly of it in a single keystroke.
  142.  
  143.   Here's how to install it in the BP IDE.  The same instructions work
  144.   for the TP 7.0 IDE; I'm not familiar with BC++ so I'm not sure of how
  145.   to install the filter there.
  146.  
  147.   1. Select the Options Tools menu, scroll to a blank position, and
  148.      type N to create a new entry.
  149.   2. Fill in the fields as follows:
  150.       Title:         D~u~mpprog
  151.       Program path:  DUMPPROG
  152.       Command line:  $SAVE PROMPT $NOSWAP $CAP MSG(DUMP2MSG) $EXENAME
  153.                      $EDNAME#$LINE $CURTOKEN
  154.  
  155.      (The command line should be typed all on one line.)  You may want to
  156.      insert "$PROMPT" before $EXENAME if you want to be able to edit the
  157.      arguments to DUMPPROG.
  158.   3. Assign a hot key to the disassembler by selecting one from the list
  159.      at the right of the dialog box.
  160.   4. Save the changes by hitting Enter, Alt-K for OK, and then Options Save.
  161.  
  162.   Once it's installed, you use the tool as follows.  Compile your
  163.   program with the detailed map file (Options Linker Detailed), point at
  164.   a symbol, and hit your chosen hot key.  A message window will pop up
  165.   showing a disassembly of the current line and of the current symbol.
  166.  
  167. Limitations:
  168.  
  169.   DUMPPROG can't tell code from data with standard .EXE files.  In Turbo
  170.   Pascal executables, constant data is kept at the beginning of code
  171.   segments.  DUMPPROG will try to disassemble this, producing lengthy
  172.   streams of nonsense.
  173.  
  174.   It doesn't know whether a source line is complete or not.  The map
  175.   file says where the source starts; it doesn't say where it ends.
  176.  
  177.   It also doesn't know where code ends, but does a bit better here.
  178.   Generally it assumes code stretches to the next line given in the MAP
  179.   file.  This can lead to very long stretches of assembler with no
  180.   source, and probably with incorrect segment/offset addresses, if
  181.   there's a gap in the .MAP. For the last line in the .MAP file, it
  182.   displays up to the the start of the next segment, or the end of the
  183.   executable, whichever comes first.
  184.  
  185.   Source code must be in the current directory, or on a path specified
  186.   with the filename in the .MAP file.  If DUMPPROG can't find the
  187.   source, it will print a warning and go ahead, leaving blanks where the
  188.   source code should go.
  189.  
  190. Credits
  191.  
  192.   The disassembler in DUMPPROG is an adaptation of a module from William
  193.   Peavy's excellent TWU program (used with permission).  Jeroen Pluimers
  194.   updated it to 486 opcodes, and added the hooks that let it work with
  195.   DUMPPROG.  Many thanks to several beta testers who found a number of
  196.   bugs.
  197.  
  198.   DUMPPROG is written in Turbo Pascal, and compiled in the Borland
  199.   Pascal 7.0 compiler.  It uses several units from the excellent Turbo
  200.   Professional library by TurboPower software.
  201.  
  202. Changing the default options:
  203.  
  204.   If you don't like the defaults I've chosen for any of the options,
  205.   you can change them---provided you're comfortable with patching the
  206.   .EXE file.  The changeable defaults are all in a group near the end of
  207.   the .EXE, with Turbo Pascal declarations:
  208.                                       { Option to change value }
  209.     SourceExtension : String[3] = 'pas';     { /E }
  210.     DoWriteMap      : Boolean   = False;     { /M }
  211.     Force_Old_Style : Boolean   = False;     { /O }
  212.     VerboseEmulation: Boolean   = False;     { /V }
  213.     Dump_it_all     : Boolean   = False;     { /A }
  214.     CPU_type        : Byte      = 4;         { /0, /1, /2, /3, /4 }
  215.     One_Line        : Boolean   = False;     { none! }
  216.     Case_Sensitive  : Boolean   = False;     { none! }
  217.  
  218.   The last two flags can't be set from the command line.  If "One_Line"
  219.   is true, then only one line of source code will be printed for each
  220.   code fragment.  If "Case_Sensitive" is true, then the symbol table
  221.   becomes case sensitive.  The only way to change these is to patch the
  222.   .EXE.
  223.  
  224.   To find this group of variables, just search for the string 'pas'.
  225.   Last I checked, this was the only occurrence in DUMPPROG.EXE.  Note
  226.   that TP stores "String[3]" as a length byte followed by 3 characters,
  227.   and Booleans as single bytes, 0=False, 1=True.
  228.  
  229. History
  230.  
  231.   1.0 - First version
  232.  
  233.   1.1 - Added code for Windows/3 executables as well as standard DOS
  234.         .EXE files; it may also handle OS/2 executables, but I don't
  235.         have any to try it on.
  236.  
  237.   1.2 - Added some 286 and 386 opcodes to disassembler
  238.  
  239.   1.21 - Fixed error in display of IMUL instruction
  240.  
  241.   2.00 - New disassembler, with full 486 opcodes displayed.
  242.          Added support for public symbols, and support for Win/3 loader
  243.          fixups.
  244.          Fixed buggy handling of .COM files.
  245.  
  246.   2.01 - Added selection capability, /M option, /A option, /0 to /4
  247.          options, fixed bugs.
  248.  
  249. License
  250.  
  251.   DUMPPROG is not a public domain program.  It contains code whose
  252.   copyright belongs to D.J. Murdoch and Jeroen Pluimers, as well as
  253.   library code from Borland International and TurboPower Software, and
  254.   public domain code written by William Peavy.
  255.  
  256.   You are free to use DUMPPROG without charge.  You may distribute it
  257.   unmodified, together with this documentation file, provided that you
  258.   charge no more than distribution costs, and on no account more than
  259.   $10 per copy.
  260.  
  261. Warranty
  262.  
  263.   There is no warranty of any kind with this program.  It is
  264.   experimental software, and likely contains bugs.  Use at your own
  265.   risk.
  266.  
  267. Note:  Expect bugs.  If you find any, please send bug reports to me (Duncan
  268. Murdoch) at one of the following addresses:
  269.  
  270.  DJ Murdoch at Fidonet node 1:249/99.5
  271.  dmurdoch@mast.queensu.ca on Internet
  272.  71631,122 on Compuserve
  273.  
  274.  337 Willingdon Ave
  275.  Kingston, Ontario, Canada K7L 4J3
  276.