Update copyright to LGPL on all files
[dyninst.git] / instructionAPI / src / MainDocPage.C
1 /*
2  * Copyright (c) 1996-2009 Barton P. Miller
3  * 
4  * We provide the Paradyn Parallel Performance Tools (below
5  * described as "Paradyn") on an AS IS basis, and do not warrant its
6  * validity or performance.  We reserve the right to update, modify,
7  * or discontinue this software at any time.  We shall have no
8  * obligation to supply such updates or modifications or any other
9  * form of support to you.
10  * 
11  * By your use of Paradyn, you understand and agree that we (or any
12  * other person or entity with proprietary rights in Paradyn) are
13  * under no obligation to provide either maintenance services,
14  * update services, notices of latent defects, or correction of
15  * defects for Paradyn.
16  * 
17  * This library is free software; you can redistribute it and/or
18  * modify it under the terms of the GNU Lesser General Public
19  * License as published by the Free Software Foundation; either
20  * version 2.1 of the License, or (at your option) any later version.
21  * 
22  * This library is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
25  * Lesser General Public License for more details.
26  * 
27  * You should have received a copy of the GNU Lesser General Public
28  * License along with this library; if not, write to the Free Software
29  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
30  */
31
32 namespace Dyninst
33 {
34   namespace InstructionAPI
35   {
36     
37     /*! \mainpage
38      * 
39      * When analyzing and modifying binary code, it is necessary to translate
40      * between raw binary instructions and an abstract form that describes the semantics
41      * of the instructions.
42      * As a part of the %Dyninst project, we have developed the
43      * %Instruction API, an API and library for decoding and representing
44      * machine instructions in a platform-independent manner. The
45      * %Instruction API includes methods for decoding machine language,
46      * convenient abstractions for its analysis, and methods to produce disassembly from those
47      * abstractions. The current implementation supports the IA32, IA-64,
48      * AMD-64, SPARC, POWER, and PowerPC instruction sets.  The %Instruction API
49      * has the following basic capabilities:
50      * - Decoding: interpreting a sequence of bytes as a machine instruction in a given machine language.
51      * - Abstract representation: representing the behavior of that instruction as an abstract syntax tree.
52      * - Disassembly: translating an abstract representation of a machine instruction into a string 
53      * representation of the corresponding assembly language instruction.
54      *
55      * Our goal in designing the %Instruction API is to provide a representation of machine
56      * instructions that can be manipulated by higher-level algorithms with minimal knowledge
57      * of platform-specific details.  In addition, users who need platform-specific information
58      * should be able to access it.  To do so, we provide an interface that disassembles a machine
59      * instruction, extracts an operation and its operands, converts the operands to abstract syntax trees,
60      * and presents this to the user.  A user of the %Instruction API can work at a level of abstraction slightly
61      * higher than assembly language,
62      * rather than working directly with machine language.  Additionally, by converting the operands to abstract
63      * syntax trees, we make it possible to analyze the operands in a uniform manner, regardless of the
64      * complexity involved in the operand's actual computation.
65      * \htmlonly
66 <h2><a class="anchor" name="abstractions">
67 Abstractions</a></h2>
68 <ul>
69 <li><a class="el" href="group__instruction.html">Instruction</a></li>
70 <li><a class="el" href="group__instructiondecoder.html">Instruction Decoder</a></li>
71 <li><a class="el" href="group__instructionASTModule.html">Instruction AST hierarchy</a> </li>
72 </ul>
73 <h2><a class="anchor" name="Examples">
74 Examples</a></h2>
75 <ul>
76 <li><a class="el" href="BasicCfgExample.html">Basic Control Flow Graph Construction</a> </li>
77 </ul>
78 The PDF version of this manual may be found here: <a class="el" href="../latex/refman.pdf">PDF Manual</a>
79 \endhtmlonly
80      */
81   };
82 };
83
84
85
86