Ionic Wind Disassembly library Version 1.0
-----------------------------------------
Installing DISASSEM.DLL
====================
  Copy DISASSEM.DLL to the SYSTEM or the SYSTEM32 directory.

  Include the dll with your programs, the DLL needs to be in either the 
  system directory or in your executables path.


Using DISASSEM.DLL with Aurora
=========================================
   1. Install the supplied header file "disassem.inc"
      into your include directory. For a default install this would be
      c:\program files\Aurora\include

   2. Install the supplied library file "disassem.lib"
      into your libs directory. For a default install this would be
      c:\program files\Aurora\libs

   3. Add #include "disassem.inc" to any source file using the disassembler


Using DISASSEM.DLL with MSVC++
=========================================
   The header file and import library for MSVC++ are located in the MSVC directory.

   1. Install the supplied header files "disassem.h" 
      into a directory found in the INCLUDE path list.

   2. Install the supplied library files "disassem.exp" and "disassem.lib"
      into a directory found in the LIB path list.

   3. Add #include "disassem.h" to any source file using the disassembler

   Notes:
     - The include file uses a #pragma comment(lib,"disassem.lib") to add the linker library to the build,
       if you wish you can comment out this statement and add either the .lib or .exp to the project directly.
     - The DLL has been tested with VC++ versions 5.0 and 6.0


API reference
=========================================
Aurora: disassemble(unsigned byte *code,unsigned byte *base,int nCount,
				string *buffer,int cbBuffer,x86inst *x86),unsigned byte *;
C: unsigned char * DISASSEMAPI disassemble(unsigned char *code,unsigned char *base,int nCount,
				char *buffer,int cbBuffer,x86inst *x86);

Parameters:
  code - The starting address of the instructions to be disassembled.
  base - The load address.
  nCount - Number of instructions to be disassembled.
  buffer - Text buffer to store the disassembly listing.
  cbBuffer - Size of the buffer.
  x86 - Pointer to a x86inst struct.

Return value:
  The return value is the address of the next instruction ot be disassembled.

Description:
  The disassemble function is the main entry point into the disassembly library. The load address is used to correctly calculate offsets relative to EIP if you are disassembling code from another process or loaded into a different area of memory other than an executables load address, it can be NULL if you are disassembling code from within your own process.

  The x86inst structure will contain information for the last instuction decoded and can be NULL if not used. To size the buffer use the formula nCount * 27 as that is the largest string that the dissasembler will generate per instruction. If you are only using the x86 parameter then buffer can be NULL as well.

========
Aurora: disassemble_range(unsigned byte *code,unsigned byte *end,unsigned byte *base,string *buffer,int cbBuffer);
C: void DISASSEMAPI disassemble_range(unsigned char *code,unsigned char *end,unsigned char *base,char *buffer,int cbBuffer);

Parameters:
  code - The starting address of the instructions to be disassembled.
  end - The ending address of the instuctions to be disassembled.
  base - The load address.
  buffer - Text buffer to store disassembly listing.
  cbBuffer - Size of the buffer.

Return value:
  None.

Description:
  The disassemble_range function takes a start and end address and generates the assembly listing of all instruction contained between the two addresses. The load address is used to correctly calculate offsets relative to EIP if you are disassembling code from another process or loaded into a different area of memory other than an executables load address, it can be NULL if you are disassembling code from within your own process. The buffer usage is the same as the disassemble function. 

  If the end address falls int the middle of an instruction stream the disassembler will continue decoding the instruction until the entire sequence has been disassembled. 

========
Aurora: get_func_count(unsigned byte *code),int;
C: int DISASSEMAPI get_func_count(unsigned char *code);

Parameters:
  code - The starting address of a function.

Return value:
  The total number of instructions (not bytes) that the function contains.

Description:
  get_func_count decodes all opcodes contained between the starting address and the first encountered RET opcode. It returns the number of instructions found, including the RET.

========
Aurora: get_func_size(unsigned byte *code),int;
C: int DISASSEMAPI get_func_size(unsigned char *code);

Parameters:
  code - The starting address of a function.

Return value:
  The total number of bytes that the function contains.

Description:
  get_func_size decodes all opcodes contained between the starting address and the first encountered RET opcode. It returns the then number of bytes the code contains.

========
Aurora: get_inst_size(unsigned byte *code),int;
C: int DISASSEMAPI get_inst_size(unsigned char *code);

Parameters:
  code - The starting address of an instruction.

Return value:
  The size of the instuction in bytes.

Description:
  get_inst_size decodes a single instruction and returns the size in bytes.


x86inst structure
=========================================
The structure is used to return the last decoded instruction when used with the disassemble function. The structure is defined in Aurora as:

struct x86inst
{
	unsigned word opcode;	//opcode
	unsigned byte modRM;	//modRM byte
	unsigned byte SIB;	//SIB byte
	int displacement;		//integer displacement
	int immediate; 		//immediate operand
	int address_size;		//Size of the address (word or dword)
	int operand_size;		//Size of the operand (word or dword)
}

The structure elements are named the same in the C version.


Current bugs and limitations
=========================================
As of version 1.0 the disassembler does not handle MMX or SSE instructions. It will decode them properly but will not produce a text disassembly of those instruction. Which means the size and count functions will still work as expected. MMX and SSE support will be available in a later version.

The disassembler was designed specifically for 32 bit code. The decoder should work fine with 16 bit code but has not been fully tested for that purpose.

