IDADWARF README

IDADWARF is an IDA plugin that imports DWARF debugging symbols
into an IDA database.

The plugin is written in C++ with some GNU extensions.

IDADWARF is (c) 2009 Vincent Rasneur and is licensed under the GPLv3.

How to use it?
--------------

Just copy the 'idadwarf.plw' file to the IDA plugins directory.
This file has been compiled with the IDA 5.5 SDK.
When loading an ELF file, there should be a new "IDADWARF ELF vX.X" entry
in the "Edit/plugins" menu.

Warning: only use this plugin on an already analyzed database.

How to build it?
----------------

See the INSTALL file.

What information can be retrieved from the debugging symbols?
-------------------------------------------------------------

It depends on the compiler... If the compiler has successfully generated the debugging symbols
for all the code being compiled, that means the symbols contain:
* all the data types (not only the program types, but the libraries types too (glibc, ...))
* function prototypes and static/automatic variables information.
* global variables info
* assembler/line number mapping
* etc...

IDADWARF can retrieve a significant part of these informations:
* found data types are stored in the "Local Types" window.
* found functions are given their "normal" prototypes.
* stack frame information is readable now :)
  i.e. no arg_XX or var_XX, but the real names. The types are shown in a comment.
* nearly the same for global/static variables.
* label names (loc_XXXX) are replaced by their source code names.
* register names are replaced by their variable names.
* enumerations are applied in the assembly listing:
  'cmp eax, 2' is replaced by 'cmp eax, MY_ENUM_CONSTANT'
* structures members are applied too:
  'mov eax, [ebx+12]' is replaced by 'mov eax, [ebx+my_struc.my_member]'
* code cross-references for all the processed functions
  the plugin handles 2 types of argument passing: 'push arg' and 'mov [esp+offset], arg'
* preprocessor macro definitions are displayed

Some limitations of the plugin:
-------------------------------

* only DWARF 2 and 3 support (nobody uses DWARF 1 anyway...)
* C debugging symbols will give the best results.
  There is nearly no C++ support for now: no namespaces, objects, templates, references...
  No Pascal or FORTRAN or [your language here] either.
* only ELF binaries are supported.
* types retrieval works for all the architectures, other retrievals (functions, variables, ...)
  can only be performed when working on an IA32 (metapc) program.
* the heuristics used by the plugin can fail...
* if the debugging symbols are crappy, no data will be imported.
* the compilation procedure is funky ;-)

Why such a plugin exists?
-------------------------

If a program being disassembled contains debugging symbols, then why not use them?
A great number of programs in production systems are compiled with debugging symbols.

The plugin is also useful when we want to check the binary output of a compiler.
The "assembly with debugging information" listing generated by GCC is not
really usable. Now you can use this plugin to have your commented assembly listing :)

What can I find in the tarball?
-------------------------------

* README : is the current file
* INSTALL : informations to build the plugin from source
* CODING_STYLE : C++ coding style for the plugin
* TODO: things to be done later :)
* bin/ : contains the IDADWARF DLL, compiled for IDA Pro 5.5
* src/ : contains the source files
* tests/ : contains test files, type 'make' to build them
* tests/bin/ : contains test binaries
  (for now, the httpd daemon compiled with debug symbols)
* screens/ : contains some screenshots of the plugin

How can I contact the author?
-----------------------------

You can send an email to vrasneur@denyall.com or vrasneur@free.fr