
LDasm 0.04.53 and PTrace 0.02

LDasm is copyright (C) 2000/1 Ravemax <ravemax@dextrose.com> and is
published under the GPL2 (see COPYING for details).

2002/12/18


0. Important note:
------------------
  This is the last version of LDasm because I switched to MacOSX.


1. Description
--------------

  LDasm (Linux Disassembler) is a Perl/Tk-based GUI for objdump/binutils that
  tries to imitate the look'n'feel of W32Dasm. It searchs for cross-
  references (e.g. strings), converts the code from GAS to a MASM-like style,
  traces programs and much more.
  Comes along with PTrace a process-flow-logger.  


2. System requirements (tested with)
------------------------------------

  o Perl 5.005+ (5.6.0)
  o Perl/Tk (800.022)
  o Any X-window system (XFree86 4.02)

  For the tracer:

  o Linux (Slackware w/ 2.4.0)
  o For the breakpoint version a x86 based architecture
  o GNU Binutils


3. LDasm
--------

  Start 'ldasm' and have a look at the online-help (press F1).


4. PTrace - the tracer
----------------------

  Note:  PTrace is based on "ExecTrace" by Trent Waddington. There is no
         contact address or homepage afaik, so give searchengines a try.

  Note2: The fast breakpoint mode was added by Waba <wabasoft@yahoo.fr>,
         so he owns a lot of credits.

  4.a The original PTrace
  -----------------------
    The tracer is implemented as a standalone program and can be used
    independently from LDasm, but it makes more sense to use it in conjunction
    with it. Its slow, since it single-steps the the whole section/program.
    A better solution would be to break at a specific address - maybe with
    the help of the GDB or the debug-registers.

    Usage-sequence:
      a.) Call 'ptrace' (by default installed in /usr/local/bin). As Example:
            "ptrace -o test /bin/chown --version"
          Btw. '--help' is interesting commandline-option.
      b.) Disassemble or open an existing project in LDasm.
      c.) LDasm menu 'Apply Trace file' and select the from PTrace created
          logfile.

  4.b The breakpoints version:
  ----------------------------
    When you use the -b (or --breakpoints) option with a file generated by 
	objdump (using objdump -d program > program.dump) or LDasm 
    (Disassembler->Save Disassembly Text File...), ptrace will read the lines
    numbers of the instructions and set breakpoints on them (using 0xf1, an 
    illegal instruction, see BP_set() for details).
	
    Then, each breakpoint triggered by the program is removed and the 
	instruction address (eip) saved like in the original version.
    Since most programs are mainly made of loops and functions, this is 
	extremly faster than the classic singlestep (see benchmarks below).
	
    Only inconvenient: this method doesn't record how much time a given 
	instruction has been executed. It isn't displayed in LDasm anyway.

  4.c Methods benchmarks:
  -----------------------
    (Made on a AMD 1200Mhz / 512MB RAM, using 
    the "convert" utility from ImageMagick on a big png to a jpg.
    Average on three samples, after caching of the image.
    Measured with "time").
    
    The format is: "U: User time / S: System time / R: Real (total) time".
    
    No tracing     ->  U: 2.9 secs  |  S: 0.1 secs  |  R: 3.0 secs
    Breakpoints    ->  U: 3.0 secs  |  S: 0.1 secs  |  R: 3.1 secs
    Classic ptrace ->  U: ~ 2h 20m  |  S: ~ 40m     |  R: ~ 3h

	As you can see, it is nearly no slow down when using the breakpoints.
	The 0.1 sec delta is likely to be due mostly to the parsing of the 
	objdump / LDasm file.
	
    
5. Help
-------

  o Where can I get Perl ?

    Should be already installed on your system. If not than point with your
    browser to:
      http://www.perl.com/pub/language/info/software.html

  o Perl/Tk ?

    The offical FAQ (with a download link) is at:
      http://w4.lns.cornell.edu/~pvhp/ptk/ptkTOC.html

  o File::Basename not found ?

    Get a newer Perl-distribution.

  o Problems with the Tk-filedialogs ?

    * To OPEN files select them always with a double-click (this works!).
    * Set the focus to the filename before pressing OK when SAVING.

  o The main-window disappears shortly after closing a file-dialog ?

    I know it looks ugly, but it seems to be the only solution for a window-
    manager-related problem (see "BUGS" in Tk::Wm.pod). You may try to
    disable the fix by removing "WMFix" from the configuration-file.
    Any Help here would be appreciated.

  o Tracer doesn't work ?

    It works only with Linux, but correct me if Iam wrong. Call make with
    "install_ldasm".
	The breakpoints version only works on the i386 architecture. Gimme 
	access to other hardware and I'll port it :)

  o I got an empty trace-file or "file not found" ?

    Pass the program always with the absolut path, "./" for files in the
    current directory. Also you may not have the required access-rights to
    write into the files-dir - try "-o".

  o Functions like "Copy Selected Line" doesn't work ?

    This one and other function prints the text to stdout. Execute LDasm
    from within a xterm.

  o The last character of most of the mnemonics is missing ?
    Add a "OBJDumpSize = no" to "~/.ldasmrc" - create file if necessary.
    This should be been done by the setup already.


6. Greets
---------

  o Andrzej Radecki
  o Francisco JM Coll
  o Jarek
  o Mosher
  o Nagra
  o Tuomas Jormola
  o Volker Fischer
  o Waba
  o John Mitchell
  o Tipu
  ...and all users.


7. Contact
----------

  If there are still questions left, ideas how to improve it or whatever,
  than feel free to drop me a mail:
    ravemax@dextrose.com
  or visit:
    http://ravemax.cjb.net

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

mQGiBDu0ygkRBACRFDxski/lDEJ3q/ZgXQTFNGpv05PxefuYfJFxip2+oahlxPSi
Lcvih00GEVCQJtKCnqMqII0NhhwQLlspqGzbArq+fqQh5yHKw7/CbSfYmTYltMdU
CiR6HcerDC60BzhFKaCUpE3Xsp02JrottVZuAE8T8xIcVFUt6DpL5YqVmwCgnEei
0/PVLiQRjDXRUBBovNqfAmkD/jejL9m3/wv2Boasb9JFQ0VmIh4pKp9CY3J8r48d
SS5ykbSA7pqb/QPltOya9uHcQLEkuu74XEIZWgyg9Q/psvZzpj6LGn/ou1uwT9lq
SdrhxJSAbEzGmjMsvEWhcMpMFuEDjWaJQgRh4EEmLlgYl01DxSicP5yH9+HrJijv
oyXAA/wPHv+cQgkI4mUe+ZPs9dAhbKBQQfASTqaIQ6VsQvD8hlD85eLDeKAJTOpS
IuEBxR1CzxjhfFyZq8n8CwoBgwR+rq5//LsS8ncHAuiVyGpE5d+StJ5nl35XgEzN
BZJW7YPpcODCIkzfNe0QGWTaqHpBc0E5YQjVZ5Sbb39uMU3vD7QpUGF0cmljayBH
bGVpY2htYW5uIDxyYXZlbWF4QGRleHRyb3NlLmNvbT6IVwQTEQIAFwUCO7TKCQUL
BwoDBAMVAwIDFgIBAheAAAoJEHwuK5x0rq+cDCwAn06kP+gEaATj5Vj1hpHrN1NY
xXqjAJ0Xx5P71RPbSW+sDEng6eZ/7MKgHrkBDQQ7tMocEAQAkNSnh+VkvQMPJhDj
rzwqk0e1GD9UonyPLN8uVt5FgVMlxs0BNpxskbw6et9VXZn3PaeiSC5owEC5dhBz
Fz7Q0tkUtGSz3DjPU6cL2XRbCuKaqxgMrMIt/gWGjZTpcwxsVTMY5B70CjcdPuau
tuQIMaxSy0hPrrNGHPojtgoDBuMAAwYEAIopYJWmpUqI1C1W2pEjqRtuUiMMc9wI
1/khp+Z84Y9mMU+32zs/JN5lpVZ7a+ieva6lpbFJfKcF6wK7q6wY59sHGbzHAWX2
GJodmhgORaNZ6ri5PrnW94TlT71O1Czlxno0lQZvN8cuExLNGsbHw4tH7Yde6QOE
o1js9/R+aO18iEYEGBECAAYFAju0yhwACgkQfC4rnHSur5z9TQCdHjdtjNpPrEDW
yxHZ/1YKxsn5mHsAn3j6Jcle3Bio1tJUq8Zp0XewBOA3
=yUzk
-----END PGP PUBLIC KEY BLOCK-----
