libdasm -- simple x86 disassembly library
=========================================
Copyright (c) 2004-2007  Jarkko Turkulainen <jt / nologin.org> <turkja / github.com>)
Copyright (c) 2005       Ero Carrera Ventura <ero / dkbza.org> (Python binding)
Copyright (c) 2006       Matt Miller skape <mmiller / hick.org> (Ruby binding)
Copyright (c) 2009-2010  Ange Albertini <angea / github.com>
Copyright (c) 2015-2018  Joshua Pereyda <jtpereyda / github.com>


1. Acknowledgments
===================

Thanks to skape, thief, spoonm, Silvio Cesare, Georg oxff Wicherski, BeatriX
and fine folks @nologin for bug reports, ideas and support.
Special thanks to ero for creating and contributing pydasm
and to skape for rbdasm.



2. What is libdasm?
===================

libdasm is a C-library that tries to provide simple and convenient
way to disassemble Intel x86 raw opcode bytes (machine code).
It can parse and print out opcodes in AT&T and Intel syntax.

The opcodes are based on IA-32 Intel Architecture Software Developer's
Manual Volume 2: Instruction Set Reference, order number 243667,
year 2004.  Non-Intel instructions are not supported atm (also,
non-Intel but Intel-compatible cpu extensions, like AMD 3DNow! are
not supported).

libdasm should compile with all decent C-compilers (only gcc and
MSVC tested).


3. How to use libdasm?
======================

Compiling your application with libdasm is very easy. As usual, there are
several ways to do it:

- Include "libdasm.c" and compile as usual. Remember to copy "libdasm.h"
  and "opcode_tables.h" in the same directory as they are included by the
  main c-file.
- Include "libdasm.h" and compile with "libdasm.c" (and remember to copy
  also "opcode_tables.h").
- Compile libdasm as library and link against it statically or dynamically,
  depending on the system and your needs. Win32 DLL and Unix static/dynamic
  libraries can be built with the supplied makefiles. See the file LIB.txt
  for more information.
- Compile pydasm and use libdasm as a python module (see directory "pydasm"
  for more information).
- Compile rbdasm and use libdasm as a ruby module (see directory "rbdasm"
  for more information).

For basic disassembling, there are are only one or two libdasm functions
you will need. First and the most important function is get_instruction.

3.1. get_instruction
====================

get_instruction analyzes data stream and fills in a structure presenting
the instruction. This structure, defined as struct INSTRUCTION, can be
later used for formatting the instruction to printable form or for
analyzing the instruction contents. It is defined as follows:

int get_instruction(
      INSTRUCTION *inst,      // pointer to INSTRUCTION structure
      BYTE *addr,             // data buffer
      enum Mode mode          // mode: MODE_32 or MODE_16
);

First argument is a reference to INSTRUCTION structure. There is no
need to initialize the structure prior to function call, get_instruction
will take care of filling it.

Second argument is an address of code buffer. get_instruction will
read data starting from that address and parse a single instruction.
INSTRUCTION structure is filled with the components of the returned
instruction. Normally you don't need to know about the contents of the
structure, but if you need to, read the next chapter.

Third argument, the mode is either 32-bit (MODE_32) or 16-bit (MODE_16).
This is the desired addressing mode. Note that the instruction might
override the mode.

get_instruction returns the instruction length. If the returned value
is zero, it indicates illegal instruction.

When get_instruction returns, you can print the instruction with
get_instruction_string or do analysis of the instruction members. When
ready, increment data buffer pointer to next instruction and call
get_instruction again. Here is pseudo-code presenting this procedure:

	INSTRUCTION inst;
	int len, buflen, c = 0;
	BYTE *buf;

	do {
		len = get_instruction(&inst, buf+c, MODE_32);

		// do something with the instruction

		c  += len;

	} while (c < buflen);



3.2. get_instruction_string
===========================

get_instruction_string parses the instruction structure and fills in
a string presenting the instruction in given format. Currently,
ATT and Intel formats are supported. The function is defined as:

int get_instruction_string(
        INSTRUCTION *instr,     // pointer to INSTRUCTION structure
        enum Format format,     // format: FORMAT_ATT or FORMAT_INTEL
        DWORD offset,           // instruction absolute address
        char *string,           // string buffer
        int length              // string length
);

The offset is needed only if you need to make relational offsets look
nice (jmp/call/loop etc.). If you are parsing instructions in known 
virtual address, use the virtual address. Otherwise, you can use zero.
DWORD is defined in libdasm.h as unsigned 32-bit number (libdasm only
supports IA-32 atm). string is the pointer to instruction buffer, length
is the size of the buffer. Note that the text is truncated if it doesn't
fit in buffer.

get_instruction_string will initialize the string and terminate it
correctly for convenience. It returns zero if the operation is not
successful.

That's it! Check out sample disassembler programs "simple.c" and "das.c"
for examples.


3.3 Other libdasm functions
===========================

libdasm uses internally lot of useful functions that might help in
instruction formatting etc. For example, get_instruction_string calls
get_mnemonic_string and get_operand_string for simple instruction
formatting. These functions are defined as:

int get_mnemonic_string(
	INSTRUCTION *inst,
	enum Format format,
	char *string,
	int length
);

int get_operand_string(
	INSTRUCTION *inst,
	OPERAND *op,
	enum Format format,
	DWORD offset,
	char *string,
	int length
);

Both functions initialize and terminate the string buffer and return
data formatted as defined in member "format". There are also many
useful helper functions defined in libdasm.h for analyzing instruction
contents.


4. INSTRUCTION structure
========================

If all you need is to fetch and print out instructions in the data buffer,
you can skip this chapter. But if you need to inspect the individual
components that make up an instruction, you will need this information.

All libdasm functions inspect and/or manipulate INSTRUCTION structure.
It is defined as follows:

typedef struct _INSTRUCTION {
        int length;             // Instruction length
        enum Instruction type;  // Instruction type
	enum Mode mode;         // Addressing mode
        BYTE opcode;            // Actual opcode
        BYTE modrm;             // MODRM byte
        BYTE sib;               // SIB byte
	int extindex;           // Extension table index
	int fpuindex;           // FPU table index
        int dispbytes;          // Displacement bytes (0 = no displacement)
        int immbytes;           // Immediate bytes (0 = no immediate)
        int sectionbytes;       // Section prefix bytes (0 = no section prefix)
        OPERAND op1;            // First operand (if any)
        OPERAND op2;            // Second operand (if any)
        OPERAND op3;            // Additional operand (if any)
        int flags;		// Instruction flags
} INSTRUCTION, *PINSTRUCTION;

Most important members are probably "length", "opcode", and the operands.
"length" is the instruction size, also returned by get_instruction.
If the instruction size is zero, the instruction is illegal. "opcode" is the
instruction opcode byte. Some of the most common instructions also have a
meaningful "type" member. This member can have one of the following values:

	INSTRUCTION_TYPE_MOV,
        INSTRUCTION_TYPE_ADD,
        INSTRUCTION_TYPE_SUB,
        INSTRUCTION_TYPE_INC,
        INSTRUCTION_TYPE_DEC,
        INSTRUCTION_TYPE_DIV,
        INSTRUCTION_TYPE_MUL,
        INSTRUCTION_TYPE_IMUL,
        INSTRUCTION_TYPE_XOR,
        INSTRUCTION_TYPE_LEA,
        INSTRUCTION_TYPE_XCHG,
        INSTRUCTION_TYPE_CMP,
        INSTRUCTION_TYPE_TEST,
        INSTRUCTION_TYPE_PUSH,	// includes enter, pusha and pushf
        INSTRUCTION_TYPE_AND,
        INSTRUCTION_TYPE_OR,
        INSTRUCTION_TYPE_POP,	// includes popa and popf
        INSTRUCTION_TYPE_JMP,	// includes jmpf
        INSTRUCTION_TYPE_JMPC,  // conditional jump
        INSTRUCTION_TYPE_LOOP,
        INSTRUCTION_TYPE_CALL,	// includes callf
        INSTRUCTION_TYPE_RET,	// includes leave, retn and retf
        INSTRUCTION_TYPE_INT,   // interrupt
        INSTRUCTION_TYPE_FPU,   // FPU-related instruction
        INSTRUCTION_TYPE_OTHER, // Other instructions :-)

The list above is not complete, check out libdasm.h for complete listing of
all possible instruction types.

Individual operands can be accessed by the OPERAND structures. All instructions
have 0-3 operands which are ordered in INTEL order (op1 is the first operand in
INTEL syntax). struct OPERAND is defined as:

typedef struct _OPERAND {
        enum Operand type;      // Operand type (register, memory, etc)
        int reg;                // Register (if any)
        int basereg;            // Base register (if any)
        int indexreg;           // Index register (if any)
        int scale;              // Scale (if any)
        int dispbytes;          // Displacement bytes (0 = no displacement)
        int dispoffset;         // Displacement offset (0 = no diplacement)
        int immbytes;           // Immediate bytes (0 = no immediate)
        int immoffset;          // Immediate offset (0 = no immediate)
        int sectionbytes;       // Section prefix bytes (0 = no section prefix)
        WORD section;           // Section prefix value
        DWORD displacement;     // Displacement value
        DWORD immediate;        // Immediate value
        int flags;		// Operand flags
} OPERAND, *POPERAND;

Operand type is always defined in member "type". This member can have one
of the following values:

        OPERAND_TYPE_NONE
        OPERAND_TYPE_MEMORY
        OPERAND_TYPE_REGISTER
        OPERAND_TYPE_IMMEDIATE

If the type is OPERAND_TYPE_NONE, operand is not present in the instruction.

If the type is OPERAND_TYPE_REGISTER, OPERAND member "reg" is present.

If the type is OPERAND_TYPE_MEMORY, some combination of the members
"basereg", "indexreg", "scale", "dispbytes" and "displacement" is present.
These members form the memory operand as follows:

	[ basereg + scale * indexreg + displacement ] (INTEL)
	displacement(basereg, indexreg, scale)        (ATT)

If the type is OPERAND_TYPE_IMMEDIATE, some combination of the members
"immbytes", "sectionbytes", "section" and "immediate" is present.
Section-specific members are used only in far type call/jmp. Member
"immediate" is filled with the actual immediate value.
Example: in "mov eax, 0x11" second operand "immediate" value is 0x11.

If present, register members "reg", "basereg" and "indexreg" can have one
of the following values:

	REGISTER_EAX
	REGISTER_ECX
	REGISTER_EDX
	REGISTER_EBX
	REGISTER_ESP
	REGISTER_EBP
	REGISTER_ESI
	REGISTER_EDI

If registers are not present, they are defined as REGISTER_NOP. Note that
the register is not necessarily general purpose register. Only way to
detect this is to inspect operand flags. You can also use helper function
get_register_type for determining the register type. Register type can
be one of the following:

	REGISTER_TYPE_GEN
	REGISTER_TYPE_SEGMENT 
	REGISTER_TYPE_DEBUG 
	REGISTER_TYPE_CONTROL 
	REGISTER_TYPE_TEST
	REGISTER_TYPE_XMM
	REGISTER_TYPE_MMX
	REGISTER_TYPE_FPU

get_register_type returns some of the values only if the operand type
is OPERAND_TYPE_REGISTER. If the operand is OPERAND_TYPE_MEMORY, the
registers are always general purpose and for immediate operands, there
are of course no registers involved.


5. Miscellaneous notes
======================

5.1. General output formatting

get_instruction_string tries to follow INTEL/ATT conventions but not
too strictly. There are some compromises that are made to keep the
implementation simple (or because the current implementation is already
too complex..).

5.2. Segment prefix formatting

Libdasm is modeled after the assumption that there is only one memory
operand at maximum in the instruction. If there is segment register override,
the segment register is placed in front of the memory operand, like this:

  mov eax, fs:[0x30]

If there are no memory operands, the segment prefix is placed in front of
the instruction:

  fs mov eax, 0x30

Some string instructions are also considered containing no memory operands,
like cmps. In reality, it contains two memory operands. So the following:

  fs cmpsd 

is equivalent to:

  cmpsd fs:[esi], es:[edi]

And BTW, if you are wondering what are those weird "(bt)" and "(bnt)"
prefixes in front of conditional jumps, they are branch hint prefixes 
("branch taken" and "branch not taken").


5.3. Instruction correctness

There is not too much sanity checking in current code. So if you feed libdasm
enough with random data or illegally constructed instructions it probably
gives wrong disassembly at some point. But libdasm should always disassemble
correctly "real" code.


5.4. Boundary checks

Libdasm will not check for read buffer boundaries. It means that if the
opcode requires additional data to be read and that data cannot be accessed,
libdasm might access violate, depending on the implementation. There is no
platform-independent way of checking this condition, so you better make
sure of it by yourself. If the data is real machine code, there is no
problem (unless of course there is a bug in libdasm) because libdasm needs
to read exactly what the instruction requires and of course the full
instruction is in buffer, right? But in some rare cases when disassembling
random data this could cause some troubles.

5.5. Endianness

Endianness might not be identified correctly on all platforms
(see libdasm.h for definition of __LITTLE_ENDIAN__). If you encounter
endianness related problems, please report the system and possible workaround
for the problem.


5.6. Inline functions

Some functions are defined as inline, this might not work for all compilers.
Only gcc and MSVC are tested by the author.


5.7. Other issues

There are probably MANY unknown bugs in code and in instruction tables.
Some known issues are listed in file TODO.txt.


6. Licensing
============

libdasm was originally released as public domain software. You can do whatever you like with it.
Due to some legal uncertainty of "public domain" in some countries it was re-licensed to
2-clause BSD type license to allow both commercial and non-commercial use.


7. How to contact the author
============================

If you have bug report or some improvement ideas or want to harass the author
for some other reason, please raise the issue on GitHub:
https://github.com/jtpereyda/libdasm/issues