Update manual version numbers and minor fixes
[dyninst.git] / symtabAPI / doc / 1-Intro.tex
1 \section{Introduction}
2 \label{sec:intro}
3
4 SymtabAPI is a multi-platform library for parsing symbol tables,
5 object file headers and debug information. SymtabAPI currently
6 supports the ELF (IA-32, AMD-64, ARMv8-64, and POWER) and PE
7 (Windows) object file formats. In addition, it also supports the DWARF
8 and stabs debugging formats.
9
10 The main goal of this API is to provide an abstract view of binaries and
11 libraries across multiple platforms. An abstract interface provides two
12 benefits: it simplifies the development of a tool since the complexity of a
13 particular file format is hidden, and it allows tools to be easily ported
14 between platforms. Each binary object file is represented in a canonical
15 platform independent manner by the API. The canonical format consists of four
16 components: a header block that contains general information about the object
17 (e.g., its name and location), a set of symbol lists that index symbols within
18 the object for fast lookup, debug information (type, line number and local
19 variable information) present in the object file and a set of additional data
20 that represents information that may be present in the object (e.g., relocation
21 or exception information). Adding a new format requires no changes to the
22 interface and hence will not affect any of the tools that use the SymtabAPI. 
23
24 Our other design goal with SymtabAPI is to allow users and tool developers to
25 easily extend or add symbol or debug information to the library through a
26 platform-independent interface. Often times it is impossible to satify all the
27 requirements of a tool that uses SymtabAPI, as those requirements can vary from
28 tool to tool. So by providing extensible structures, SymtabAPI allows tools to
29 modify any structure to fit their own requirements. Also, tools frequently use
30 more sophisticated analyses to augment the information available from the binary
31 directly; it should be possible to make this extra information available to the
32 SymtabAPI library. An example of this is a tool operating on a stripped binary.
33 Although the symbols for the majority of functions in the binary may be missing,
34 many can be determined via more sophisticated analysis. In our model, the tool
35 would then inform the SymtabAPI library of the presence of these functions; this
36 information would be incorporated and available for subsequent analysis. Other
37 examples of such extensions might involve creating and adding new types or
38 adding new local variables to certain functions.