        IDA SDK - Interactive Disassembler Module SDK
        =============================================

        This SDK should be used with IDA kernel version 4.3.0.735

        This package allows you to write:
                - processor modules
                - input file loader modules
                - plugin modules (including the
                   processor module extension plugins)

        Please read read through whole file before continuing!

-----------------------------------------------

        What you need:

To create 32bit MS DOS modules:         Watcom 10.6 and make.exe from Borland
To create 32bit OS/2 modules:           Watcom 10.6 and make.exe from Borland
To create 32bit Win32 modules:             Borland C++ Builder v4.0
                                        or free BCC v5.5
                                        or Visual C++ v6.0

The Visual C++ users should refer to install_visual.txt for the explanations
how to install.

The CBuilder visual environment users should refer to install_cb.txt for the
explanations how to install (only for the development of plugins using the
visual components).

All others should refer to install_make.txt.

-----------------------------------------------

        A quick tour on header files:

IDA      HPP            the 'main' header file of IDA project.
                        This file should be included in all source files.
                        In this file the 'inf' structure is
                        defined: it keeps all parameters of the disassembled
                        file.
NETNODE  HPP            the lowest level of access to the database. Modules
                        can use this level to keep some private inforation
                        in the database. Here is a short description of
                        the concept:
                          the database consists of 'netnodes'.
                          The netnodes are numbered by 32-bit integers
                          and may have:
                            - a name (max length is MAXNAMESIZE-1)
                            - a value (a string)
                            - sparse arrays of values:
                              Each sparse array has a 8-bit tag. Therefore,
                              we can have 256 sparse arrays in one netnode.
                              Only non-zero elements of the arrays are stored in
                              the database. Arrays are indexed by 32-bit or 8-bit
                              indexes. You can keep any type of information in
                              an array element. The size of an element is limited
                              by MAXSPECSIZE. For example, you could have an
                              array of addresses that have been patched by the user:

                              <address> : <old_value_of_byte>

                              The array is empty at the start and will
                              grow as the user patches the input file.

                              There are 2 predefined arrays:

                                - strings       (supval)
                                - longs         (altval)

                              The arrays don't need to be declared or created
                              specially. They implicitly exist at each node.
                              To save something into an array simply write
                              to the array element (altset or supset functions)
                        There are no limitations on the size or number of
                        netnode arrays.
NALT     HPP            some predefined netnode array indexes used by the
                        kernel. these functions should not be used directly
                        since they are very low level.
NAME     HPP            names: rename, unname bytes etc.
FUNCS    HPP            Functions in the disassembled program
FRAME    HPP            Local variables, stack trace
IEEE     H              IEEE floating point functions
TYPEINF  HPP            Type information in the program
STRUCT   HPP            Structure types in the disassembled program
ENUM     HPP            Enumeration types in the disassembled program
OFFSET   HPP            functions that work with offsets.
SEGMENT  HPP            program segmentation
SRAREA   HPP            segment registers. If your processor doesn't have
                        segment registers, you don't need this file.
AREA     HPP            class 'area'. This class is a base class for
                        'segment_t' and 'srarea_t' (segment register) classes.
                        This class keeps information about various areas
                        of the disassembled file.
KERNWIN  HPP            various functions to interact with the user.
                        Also, some functions to process strings are kept in
                        this header.
AUTO     HPP            auto-analysis related functions
BYTES    HPP            Functions and definitions which describe each byte
                        of the disassembled program: is it an instruction,
                        data, operand types etc.
DISKIO   HPP            file i/o functions
                        See file pro.h and fpro.h for additional system functions
ENTRY    HPP            List of entry points to the program being
                        disassembled.
FIXUP    HPP            information about relocation table of the program.
PRO      H              compiler related stuff and some system-independent functions
FPRO     H              Alternative set of system-indenendent file i/o
                        functions. These functions do check errors but never
                        exit even if an error occurs. They return extended
                        error code in qerrno variable.
                        You must use these functions, not functions from
                        stdio.h
HELP     H              Help subsystem. This subsystem is not used in
                        IDP files. I put it just in case.
IDP      HPP            the 'main' header file of IDP modules.
                        2 structures are described here:
                          processor_t - description of processor
                          asm_t       - description of assembler
                        Each IDP has one processor_t and several asm_t structures
INTS     HPP            predefined comments
LINES    HPP            generation of source (assembler) lines and long
                        comment lines. variables controlling the exact time
                        and place to generate xrefs, indented comments etc.
                        shouldn't be used in simple IDP modules.
                        You must use these function instead of functions
                        from stdlib.h
QUEUE    HPP            queue of problems.
EXPR     HPP            IDC language functions.
UA       HPP            This header file describes insn_t structure called
                        cmd: this structure keeps a disassembled instruction
                        in the internal form. Also, you will find here
                        helper functions to create output lines etc.
VA       HPP            Virtual array. Used by other parts of IDA.
                        IDP module don't use it directly.
VM       HPP            Virtual memory. Used by other parts of IDA.
                        IDP module don't use it directly.
XREF     HPP            cross-references.


All functions usable in the modules are marked by the "ida_export" keyword.

-----------------------------------------------

        Libraries

IDA      LIB    - import library with all functions exported from the kernel

        There are 4 different versions of this file, one for each platform.

-----------------------------------------------

        Description of the processor module example

     The module disassembles an instruction in several steps:
        - analysis (decoding)           file ana.cpp
        - emulation                     file amu.cpp
        - output                        file out.cpp

     The analyser (ana.cpp) should be fast and simple: just decode an
     instruction and fill the 'cmd' structure. The analyser will always be called
     before calling emulator and output functions. If the current address
     can't contain an instruction, it should return 0. Otherwise, it returns
     the length of the instruction in bytes.

     The emulator and outputter should use the contents of the 'cmd' array.
     The emulator performs the following tasks:
        - creates cross-references
        - plans to disassemble subsequent instructions
        - create stack variables (optional)
        - tries to keep track of register contents (optional)
        - provides better analysis method for the kernel (optional)
        - etc

     The outputter produces a line (or lines) that will be displayed on
     the screen.
     It generates only essential part of the line: line prefix, comments,
     cross-references will be generated by the kernel itself.
     To generate a line, MakeLine() or printf_line() should be used.

MAKEFILE        - makefile for a processor module
                  The DESCRIPTION line
                  should contain names of processors handled by this IDP
                  module, separated by colons. The first name is description
                  of whole module (not a processor name).
STUB            - MSDOS stub for the module
ANA      CPP    - analysis of an instruction: fills the cmd structure.
EMU      CPP    - emulation: creates xrefs, plans to analyse subsequent
                  instructions
INS      CPP    - table of instructions.
OUT      CPP    - generate source lines.
REG      CPP    - description of processor, assemblers, and notify() function.
                  This function is called when certain events occur. You
                  may want to have some additional processing of those events.
IDP      DEF    - the module description for the linker.
I51      HPP    - local header file. you may have another header file for
                  you module.
INS      HPP    - list of instructions.

-----------------------------------------------

        And finally:

  I'm sure you'll have questions - don't hesitate to contact me,
  I'll be happy to answer.

  I recommend to study the samples, compile and run them.

  Limitations on the modules:
        - for the dynamic memory allocation: please use qalloc/qfree()
          while you are free to use any other means, these functions
          are provided by the kernel and everything allocated by the
          kernel should be deleted using qfree()
        - for the file i/o: never use functions from stdio.h.
          Use functions from fpro.h instead.
          If you still want to use the standard functions, never pass
          FILE* pointer obtained from the standard functions to the kernel
          and vice versa.
        - the exported descriptor names are fixed:
                processor module        LPH
                loader module           LDSC
                plugin module           PLUGIN

  Usually I write a new processor module in the following way:
        - copy the sample module files to a new directory
        - first I edit INS.CPP and INS.HPP files
        - write the analyser ana.cpp
        - then outputter
        - and emulator (you can start with an almost empty emulator)
        - and describe the processor & assembler, write the notify() function

  Naturally, it is easier to copy and to modify example files than to write
  your own files from the scratch.

  Debugging:
  You can use the following debug print functions:
        deb() - display a line in the messages window if -z command
                line switch is specified. You may use debug one of:
                IDA_DEBUG_IDP, IDA_DEBUG_LDR, IDA_DEBUG_PLUGIN
        msg() - display a line in the messages window
        warning() - display a dialog box with the message

  To stop in the debugger when the module is loaded, you may use the
  __emit__(0xCC) construct in the module initialization code.
  (__asm _emit 0xCC; for Visual C++)

  BTW, you can save all lines appearing in the messages window to a file.
  Just set an enviroment variable:

        set IDALOG=ida.log

  I always have this variable set, it is great help in the development.

-----------------------------------------------------
