new docbook/xml documentation, updated webpage

[udis86.git] / docs / manual / manual.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
          "file:///opt/local/share/xml/docbook/4.5/docbookx.dtd">
<article>
<articleinfo>
  <title>Udis86 Manual</title>
  <author><firstname>Vivek</firstname><surname>Thampi</surname></author>
  <authorinitials>vmt</authorinitials>
  <pubdate>2009</pubdate>
  <titleabbrev>Udis86 Manual</titleabbrev>
  <revhistory>
     <revision>
        <revnumber>1.0</revnumber>
        <date>02 May 2009</date>
     </revision>
  </revhistory>
</articleinfo>


<section><title>Introduction</title>
Udis86 is a disassembler engine that interprets and decodes a 
stream of binary machine code bytes as opcodes defined in the 
x86 and x86-64 class of Instruction Set Archictures. The core 
component of this project is libudis86 which provides a clean 
and simple interface to disassemble binary code, and to inspect 
the disassembly to various degrees of details. The library is 
designed to aid software projects that entail analysis and 
manipulation of all flavors of x86 binary code.
</section>

<section><title>Getting Started</title>

<section><title>Building and Installing udis86</title>
udis86 is developed for unix-like environments, and like most
software, the basic steps towards building and installing 
it are as follows.
<screen>
<prompt>$</prompt> <userinput>./configure</userinput>
<prompt>$</prompt> <userinput>make</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
</screen>
Depending on your choice of install location, you may need to 
have root privileges to do a make install. The install scripts 
copy the necessary header and library files to appropriate 
locations on the system.
</section>

<section><title>Interfacing with libudis86: A Quick Example</title>
 The following code is an example of a program that interfaces 
 with libudis86 and uses the API to generate assembly language 
 output for 64-bit code, input from STDIN.
 <example><title>libudis86 Usage Example</title> 
<programlisting>#include &lt;stdio.h&gt;
#include &lt;udis86.h&gt;

int main()
{
    ud_t ud_obj;

    ud_init(&amp;ud_obj);
    ud_set_input_file(&amp;ud_obj, stdin);
    ud_set_mode(&amp;ud_obj, 64);
    ud_set_syntax(&amp;ud_obj, UD_SYN_INTEL);

    while (ud_disassemble(&amp;ud_obj)) {
        printf("\t%s\n", ud_insn_asm(&amp;ud_obj));
    }

    return 0;
} </programlisting></example>
 To compile the program (using gcc):
 <screen> <prompt>$</prompt> <userinput>gcc -ludis86 example.c -o example</userinput> </screen>
 This example should give you an idea of how this library can be used. The following 
 sections describe, in detail, the complete API of libudis86.
</section>
</section>

<section><title>libudis86 Programming Interface</title>
 <section><title>ud_t: udis86 object</title>
 libudis86 is reentrant, and to maintain that property it does not use static data. 
 All data related to the disassembly are stored in a single object, called the udis86 
 object <literal>ud_t</literal> (<literal>struct ud</literal>). So, to use libudis86 
 you must create an instance of this object,
 <programlisting> ud_t ud_obj; </programlisting>
 and initialize it,
 <programlisting> ud_init(&amp;ud_obj); </programlisting>
 You can create multiple such objects and use with the library, each one maintaining
 it's own disassembly state.
 </section>

  <section><title>Examining Instructions</title>
  
  <para>libudis86 exposes decoded instructions in an intermediate form meant 
  to be useful for programs that want to examine them. This intermediate form
  is available as values of certain fields of the <literal>ud_t</literal>
  udis86 object used to disassemble the instruction, as described below.</para>

  <section><title>Instruction Pointer</title>
   <para>The program counter (eip/rip) value at which the instruction was
   decoded, is available in <literal>ud_obj.pc</literal></para>
  </section>

  <section><title>Instruction Prefixes</title>
   <para>Prefix bytes that affect the disassembly of the instruction
   are availabe in the following fields, each of which corressponding
   to particular type or class of prefixes.
    <itemizedlist id="hhllo">
     <listitem><literal>ud_obj.pfx_rex</literal>     - 64-bit mode REX prefix</listitem>
     <listitem><literal>ud_obj.pfx_seg</literal>     - Segment register prefix</listitem>
     <listitem><literal>ud_obj.pfx_opr</literal>     - Operand-size prefix (66h)</listitem>
     <listitem><literal>ud_obj.pfx_adr</literal>     - Address-size prefix (67h)</listitem>
     <listitem><literal>ud_obj.pfx_lock</literal>    - Lock prefix</listitem>
     <listitem><literal>ud_obj.pfx_rep</literal>     - Rep prefix</listitem>
     <listitem><literal>ud_obj.pfx_repe</literal>    - Repe prefix</listitem>
     <listitem><literal>ud_obj.pfx_repne</literal>   - Repne prefix</listitem>
    </itemizedlist>
   These fields default to <literal>UD_NONE</literal> if the respective 
   prefixes were not found.
   </para>
  </section>

  <section><title>Instruction Mnemonic</title>
   <para>The instruction mnemonic in the form of an enumerated constant
   (<literal>enum ud_mnemonic_code</literal>) is available in
   <literal>ud_obj.mnemonic</literal>. As a convention all mnemonic 
   constants are composed by prefixing standard instruction mnemonics
   with <literal>UD_I</literal>. For example, 
        <literal>UD_Imov</literal>,
        <literal>UD_Ixor</literal>,
        <literal>UD_Ijmp</literal>, etc.
   </para>
  </section>

  <section><title>Instruction Operands</title>
  <para>
  The intermediate form for instruction operands are availabe as
  an array of objects of type <literal>struct ud_operand</literal>.
  Given a udis86 object <literal>ud_obj</literal>, the 
  <literal>n</literal>th operand is availabe in 
  <literal>ud_obj.operand[n]</literal>. 
  </para>
  <para>
  <literal>struct ud_operand</literal> has the following fields,
    <itemizedlist>
      <listitem><literal>type</literal></listitem>
      <listitem><literal>size</literal></listitem>
      <listitem><literal>base</literal></listitem>
      <listitem><literal>index</literal></listitem>
      <listitem><literal>scale</literal></listitem>
      <listitem><literal>offset</literal></listitem>
      <listitem><literal>lval</literal></listitem>
    </itemizedlist>
  </para>

  <para>
  The <literal>type</literal> and <literal>size</literal> fields
  determine the type and size of the operand, respectively. The
  possible types of operands are,
  </para>

  <itemizedlist>

    <listitem><literal>UD_NONE</literal>
      <para>
      No operand.
      </para>
    </listitem>

    <listitem><literal>UD_OP_MEM</literal>
      <para>
      Memory operand. The intermediate form normalizes all memory 
      address equations to the scale-index-base form. The address 
      equation is availabe in 
        <literal>base</literal>, 
        <literal>index</literal>, and
        <literal>scale</literal>.
      If the <literal>offset</literal> field has a non-zero value 
      (one of 8, 16, 32, and 64), <literal>lval</literal> will
      contain the memory offset. Note that <literal>base</literal> 
      and <literal>index</literal> fields contain the base and 
      index register of the address equation, in the form of an 
      enumerated constant <literal>enum ud_type</literal>.
      <literal>scale</literal> contains an integer value that
      the index register must be scaled by.
      </para>
    </listitem>

    <listitem><literal>UD_OP_PTR</literal>
     <para>A Segmet:Offset pointer operand.
     <literal>size</literal> can have two values 32 (for 16:16 seg:off) 
     and 48 (for 16:32 seg:off). The value is available in
     <literal>lval</literal> (<literal>lval.ptr.seg</literal> and <literal>lval.ptr.off</literal>.)
     </para>
    </listitem>

    <listitem><literal>UD_OP_IMM</literal>
      <para>
      Immediate operand. Value available in <literal>lval</literal>.
      </para>
    </listitem>

    <listitem><literal>UD_OP_JIMM</literal>
      <para>
      Immediate operand to branch instruction (relative offsets). 
      Value available in <literal>lval</literal>.
      </para>
    </listitem>
    
    <listitem><literal>UD_OP_CONST</literal>
      <para>
      Implicit constant operand.
      Value available in <literal>lval</literal>.
      </para>
    </listitem>

    <listitem>
     <literal>UD_OP_REG</literal>
     <para>
     Operand is a register. The specific register is contained in 
     <literal>base</literal> in the form of an enumerated constant, 
     <literal>enum ud_type</literal>.
     </para>
    </listitem>
  </itemizedlist>

  <para>The <literal>lval</literal> is a union data structure that
  aggregates integer fields of different sizes, that store values 
  depending on the type of operand.
  <itemizedlist>
    <listitem><literal>lval.sbyte</literal>   - Signed Byte</listitem>
    <listitem><literal>lval.ubyte</literal>   - Unsigned Byte</listitem>
    <listitem><literal>lval.sword</literal>   - Signed Word</listitem>
    <listitem><literal>lval.uword</literal>   - Unsigned Word</listitem>
    <listitem><literal>lval.sdword</literal>  - Signed Double Word</listitem>
    <listitem><literal>lval.udword</literal>  - Unsigned Double Word</listitem>
    <listitem><literal>lval.sqword</literal>  - Signed Quad Word</listitem>
    <listitem><literal>lval.uqword</literal>  - Unsigned Quad Word</listitem>
    <listitem><literal>lval.ptr.seg</literal> - Pointer Segment in Segment:Offset</listitem>
    <listitem><literal>lval.ptr.off</literal> - Pointer Offset in Segment:Offset  </listitem>
  </itemizedlist>
  </para>

  <para>The following enumerated constants (<literal>enum ud_type</literal>)
  are possible values for <literal>base</literal> and <literal>index</literal>.
  Note that a value of <literal>UD_NONE</literal> simply means that the
  field is not valid for the current instruction.
  </para>

  <programlisting>
    UD_NONE,

    /* 8 bit GPRs */
    UD_R_AL,    UD_R_CL,    UD_R_DL,    UD_R_BL,
    UD_R_AH,    UD_R_CH,    UD_R_DH,    UD_R_BH,
    UD_R_SPL,   UD_R_BPL,   UD_R_SIL,   UD_R_DIL,
    UD_R_R8B,   UD_R_R9B,   UD_R_R10B,  UD_R_R11B,
    UD_R_R12B,  UD_R_R13B,  UD_R_R14B,  UD_R_R15B,

    /* 16 bit GPRs */
    UD_R_AX,    UD_R_CX,    UD_R_DX,    UD_R_BX,
    UD_R_SP,    UD_R_BP,    UD_R_SI,    UD_R_DI,
    UD_R_R8W,   UD_R_R9W,   UD_R_R10W,  UD_R_R11W,
    UD_R_R12W,  UD_R_R13W,  UD_R_R14W,  UD_R_R15W,
            
    /* 32 bit GPRs */
    UD_R_EAX,   UD_R_ECX,   UD_R_EDX,   UD_R_EBX,
    UD_R_ESP,   UD_R_EBP,   UD_R_ESI,   UD_R_EDI,
    UD_R_R8D,   UD_R_R9D,   UD_R_R10D,  UD_R_R11D,
    UD_R_R12D,  UD_R_R13D,  UD_R_R14D,  UD_R_R15D,
            
    /* 64 bit GPRs */
    UD_R_RAX,   UD_R_RCX,   UD_R_RDX,   UD_R_RBX,
     UD_R_RSP,  UD_R_RBP,   UD_R_RSI,   UD_R_RDI,
    UD_R_R8,    UD_R_R9,    UD_R_R10,   UD_R_R11,
    UD_R_R12,   UD_R_R13,   UD_R_R14,   UD_R_R15,

    /* segment registers */
    UD_R_ES,    UD_R_CS,    UD_R_SS,    UD_R_DS,
    UD_R_FS,    UD_R_GS,    

    /* control registers*/
    UD_R_CR0,   UD_R_CR1,   UD_R_CR2,   UD_R_CR3,
    UD_R_CR4,   UD_R_CR5,   UD_R_CR6,   UD_R_CR7,
    UD_R_CR8,   UD_R_CR9,   UD_R_CR10,  UD_R_CR11,
    UD_R_CR12,  UD_R_CR13,  UD_R_CR14,  UD_R_CR15,
            
    /* debug registers */
    UD_R_DR0,   UD_R_DR1,   UD_R_DR2,   UD_R_DR3,
    UD_R_DR4,   UD_R_DR5,   UD_R_DR6,   UD_R_DR7,
    UD_R_DR8,   UD_R_DR9,   UD_R_DR10,  UD_R_DR11,
    UD_R_DR12,  UD_R_DR13,  UD_R_DR14,  UD_R_DR15,

    /* mmx registers */
    UD_R_MM0,   UD_R_MM1,   UD_R_MM2,   UD_R_MM3,
    UD_R_MM4,   UD_R_MM5,   UD_R_MM6,   UD_R_MM7,

    /* x87 registers */
    UD_R_ST0,   UD_R_ST1,   UD_R_ST2,   UD_R_ST3,
    UD_R_ST4,   UD_R_ST5,   UD_R_ST6,   UD_R_ST7, 

    /* extended multimedia registers */
    UD_R_XMM0,  UD_R_XMM1,  UD_R_XMM2,  UD_R_XMM3,
    UD_R_XMM4,  UD_R_XMM5,  UD_R_XMM6,  UD_R_XMM7,
    UD_R_XMM8,  UD_R_XMM9,  UD_R_XMM10, UD_R_XMM11,
    UD_R_XMM12, UD_R_XMM13, UD_R_XMM14, UD_R_XMM15,

    /* eip/rip */
    UD_R_RIP </programlisting>

  </section>
 </section>

 <section><title>Function Reference</title>
  <itemizedlist>

   <listitem>
    <literal>void ud_init (ud_t* ud_obj)</literal>
    <para>
    <literal>ud_t</literal> object initializer. This function must be called on a 
    udis86 object before it can used anywhere else.
    </para>
   </listitem>
    
   <listitem>
    <literal>void ud_set_input_hook(ud_t* ud_obj, int (*hook)())</literal>
    <para> This function sets the input source for the library. To retrieve each byte in 
    the stream, libudis86 calls back the function pointed to by <literal>hook</literal>. 
    The hook function, defined by the user code, must return a single byte of code 
    each time it is called. To signal end-of-input, it must return the constant, 
    <literal>UD_EOI</literal>.</para>
   </listitem>

   <listitem>
    <literal>void ud_set_user_opaque_data(ud_t* ud_obj, void* opaque);</literal>
    <para>Associates a pointer with the udis86 object to be retrieved and used in user 
    functions, such as the input hook callback function.</para>
   </listitem>

   <listitem>
    <literal>void* ud_get_user_opaque_data(ud_t* ud_obj);</literal>
    <para>This function returns any pointer associated with the udis86 object, using 
    the <literal>ud_set_opaque_data</literal> function.</para>
   </listitem>

    <listitem>
     <literal>void ud_set_input_buffer(ud_t* ud_obj, unsigned char* buffer, size_t size);</literal>
     <para>Sets the input source for the library to a buffer of fixed size.</para>
    </listitem>

    <listitem>
     <literal>void ud_set_input_file(ud_t* ud_obj, FILE* filep);</literal>
     <para>This function sets the input source for the library to a file pointed to by the 
     passed FILE pointer. Note that the library does not perform any checks, assuming 
     the file pointer to be properly initialized.</para>
    </listitem> 
 
    <listitem> 
     <literal>void ud_set_mode(ud_t* ud_obj, uint8_t mode_bits);</literal>
     <para>Sets the mode of disassembly. Possible values are 16, 32, and 64. By default, the 
     library works in 32bit mode.</para>
    </listitem>

    <listitem>
     <literal>void ud_set_pc(ud_t*, uint64_t pc);</literal>
     <para>Sets the program counter (EIP/RIP). This changes the offset of the assembly output 
     generated, with direct effect on branch instructions.</para>
    </listitem>

    <listitem>
     <literal>void ud_set_syntax(ud_t*, void (*translator)(ud_t*));</literal>
     <para>libudis86 disassembles one instruction at a time into an intermediate form that 
     lets you inspect the instruction and its various aspects individually. But to generate the 
     assembly language output, this intermediate form must be translated. This function sets 
     the translator. There are two inbuilt translators,</para>

     <itemizedlist>
      <listitem><literal>UD_SYN_INTEL</literal> - for INTEL (NASM-like) syntax.</listitem>
      <listitem><literal>UD_SYN_ATT</literal> - for AT&amp;T (GAS-like) syntax.</listitem>
     </itemizedlist>

     <para>If you do not want libudis86 to translate, you can pass 
     <literal>NULL</literal> to the function, with no more translations 
     thereafter. This is particularly useful for cases when you only 
     want to identify chunks of code and then create the assembly output 
     if needed.</para>
     <para>If you want to create your own translator, you must pass a pointer to function 
     that accepts a pointer to ud_t. This function will be called by libudis86 after each 
     instruction is decoded.</para>
    </listitem>

    <listitem>
     <literal>void ud_set_vendor(ud_t*, unsigned vendor);</literal>
     <para>Sets the vendor of whose instruction to choose from. This is only useful for 
     selecting the VMX or SVM instruction sets at which point INTEL and AMD have diverged 
     significantly. At a later stage, support for a more granular selection of instruction 
     sets maybe added.

     <itemizedlist>
      <listitem><literal>UD_VENDOR_INTEL</literal> - for INTEL instruction set.</listitem>
      <listitem><literal>UD_VEDNOR_ATT</literal> - for AMD instruction set.</listitem>
     </itemizedlist>
     </para>

    </listitem>

    <listitem>
     <literal>unsigned int ud_disassemble(ud_t*);</literal>
     <para>Disassembles the next instruction in the input stream. Returns the number of 
     bytes disassembled. A 0 indicates end of input. Note, to restart disassembly, after 
     the end of input, you must call one of the input setting functions with the new 
     input source.</para>
    </listitem>

    <listitem>
     <literal>unsigned int ud_insn_len(ud_t* u);</literal>
     <para>Returns the number of bytes disassembled.</para>
    </listitem>

    <listitem>
     <literal>uint64_t ud_insn_off(ud_t*);</literal>
     <para>Returns the starting offset of the disassembled instruction relative to the 
     program counter value specified initially.</para>
    </listitem>

    <listitem>
     <literal>char* ud_insn_hex(ud_t*);</literal>
     <para>Returns pointer to character string holding the hexadecimal 
     representation of the disassembled bytes.</para>
    </listitem>

    <listitem>
     <literal>uint8_t* ud_insn_ptr(ud_t* u);</literal>
     <para>Returns pointer to the buffer holding the instruction bytes. 
     Use <literal>ud_insn_len()</literal>, to determine the length of this 
     buffer.</para>
    </listitem>

    <listitem>
     <literal>char* ud_insn_asm(ud_t* u);</literal>
     <para>If the syntax is specified, returns pointer to the character 
     string holding assembly language representation of the disassembled 
     instruction.</para>
    </listitem>

    <listitem>
     <literal>void ud_input_skip(ud_t*, size_t n);</literal>
     <para>Skips n number of bytes in the input stream</para>
    </listitem>

  </itemizedlist>
 </section>


</section>

</article>