readme.txt

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

        This SDK should be used with IDA kernel version ##VERDOTTED##

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

        Please read through the entire file before continuing!

        Check also the IDA Pro book by Chris Eagle:

        http://www.idabook.com/

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


SUPPORTED COMPILERS
-------------------

  A compiler that fully supports C++11 is a requirement for this SDK.

  MS Windows:
    - Visual C++ 2017 (15.0) or later

  Linux:
    - GNU C++ compiler
    - LLVM/Clang C++ compiler

  Mac OS X (SDK 10.11 or later):
    - GNU C++ compiler
    - LLVM/Clang C++ compiler

  Other compilers might work but are not supported officially.


HEADERS
-------

        A quick tour on IDA's header files:

pro.h           This is the first header included in the IDA project.
                It defines the most common types, functions, and data.
                It also contains compiler- and platform-related definitions.

ida.hpp         In this file the 'inf' structure is defined: it keeps all
                parameters of the disassembled file.

idp.hpp         The 'main' header file for IDP modules.
                Contains definition of the interface to IDP modules.
                The interface consists of 2 structures:
                  processor_t - description of processor
                  asm_t       - description of assembler
                Each IDP has one processor_t and several asm_t structures.

loader.hpp      Definitions of IDP, LDR, and PLUGIN module interfaces.
                This file also contains:
                  - functions to load files into the database
                  - functions to generate output files
                  - high level functions to work with the database
                    (open, save, close)

ua.hpp          Functions that deal with the disassembling of program
                instructions.
                Disassembly of an instruction is made in three steps:
                  - analysis
                  - emulation
                  - conversion to text

kernwin.hpp     Defines the interface between the kernel and the UI.
                Some string processing functions are also kept in this header.

idd.hpp         Debugger plugin API for debugger module writers.
                Contains definition of the interface to IDD modules.

bytes.hpp       Functions and definitions used to describe and manipulate each
                byte of the disassembled program.
                Information about the byte includes associated features
                (comments, names, references, etc), data types (dword, qword,
                string literal, etc), instruction operands, status (mapped,
                loaded, patched, etc), among others.

netnode.hpp     Functions that provide the lowest level public interface to
                the database. Modules can use this to keep some private
                information in the database. A description of the concept is
                available in the header file itself.

allins.hpp      List of instructions available from all processor modules.

auto.hpp        Auto-analysis related functions.

compress.hpp    Data compression functions.

config.hpp      Functions that deal with configuration options and files.

dbg.hpp         Contains functions to control the debugging of a process.

diskio.hpp      File I/O functions for IDA.
                You should not use standard C file I/O functions in modules.
                Use functions from this header, pro.h, and fpro.h instead.

entry.hpp       Functions that deal with entry points to the program being
                disassembled.

enum.hpp        Enumeration type management (assembly level types).

err.h           Thread safe functions that deal with error codes.

expr.hpp        Functions that deal with C-like expressions, external
                languages, and the built-in IDC language.

fixup.hpp       Functions that deal with fixup (relocation) information.

fpro.h          System independent counterparts of 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.

                NOTE: You must use these functions instead of the C standard
                      I/O functions.

frame.hpp       Routines to manipulate function stack frames, stack variables,
                register variables and local labels.

funcs.hpp       Routines for working with functions within the disassembled
                program. This file also contains routines for working with
                library signatures (e.g. FLIRT).

gdl.hpp         Low level graph drawing operations.

graph.hpp       Graph view management.

help.h          Help subsystem. This subsystem is not used in IDP files.
                We put it just in case.

ieee.h          IEEE floating point functions.

intel.hpp       Header file from the IBM PC module. For information only.
                It will not compile because it contains references to
                internal files!

lex.hpp         Tools for parsing C-like input.

lines.hpp       High level functions that deal with the generation of the
                disassembled text lines.

nalt.hpp        Definitions of various information kept in netnodes.
                These functions should not be used directly since they are
                very low level.

moves.hpp       Functions and classes related to location history.

name.hpp        Functions that deal with names (setting, deleting, getting,
                validating, etc).

offset.hpp      Functions that deal with offsets.

problems.hpp    Functions that deal with the list of problems.

prodir.h        Low level functions to find files in the file system.
                It is better to use enumerate_files2() from diskio.hpp.

pronet.h        Network related functions.

range.hpp       Contains the definition of the 'range_t' class.
                This is a base class used by many parts of IDA, such as the
                'segment_t' and 'segreg_range_t' (segment register) classes.

registry.hpp    Registry related functions.
                IDA uses the registry to store global configuration options
                that must persist after IDA has been closed.

segment.hpp     Functions that deal with program segmentation.

segregs.hpp     Functions that deal with the segment registers.
                If your processor doesn't use segment registers, then you
                don't need this file.

strlist.hpp     Functions that deal with the strings list.

struct.hpp      Structure type management (assembly level types).

typeinf.hpp     Describes the type information records in IDA.

xref.hpp        Functions that deal with cross-references.


All functions usable in the modules are marked by the "ida_export" keyword.
There are some exported functions that should be not used except very cautiously.
For example, set_nalt_cmt() and many functions from nalt.hpp should be avoided.
In general, try to find a high-level counterpart of the function in these cases.

Naturally, all inline functions from the header files can be used too.


LIBRARIES
---------

  This SDK provides import and stub libraries to link against the IDA kernel.

  For MS Windows targets, import libraries are provided in:
    x64_win_vc_32/ida.lib               Visual C++ import libraries for IDA32
    x64_win_vc_64/ida.lib               Visual C++ import libraries for IDA64

  For Linux and Mac OS X targets, you may link directly to the shared library
  of the IDA kernel (libida[_64].so or libida[_64].dylib), but stub libraries
  are also provided to simplify building of the SDK.

  For Linux targets, stub libraries are provided in:
    x64_linux_gcc_32/libida.so          LLVM/GCC stub libraries for IDA32
    x64_linux_gcc_64/libida64.so        LLVM/GCC stub libraries for IDA64

  For Mac OS X targets, stub libraries are provided in:
    x64_mac_gcc_32/libida.dylib         LLVM/GCC stub libraries for IDA32
    x64_mac_gcc_64/libida64.dylib       LLVM/GCC stub libraries for IDA64

  To build the debugger servers, the 'dumb' object are needed. These files are
  provided for the following architectures:

    x86_win_vc_32     Visual C++ libraries for building 32-bit Windows debugger server
    x86_win_vc_64     Visual C++ libraries for building 64-bit Windows debugger server
    x86_linux_gcc_32  GCC libraries for building 32-bit Linux debugger server
    x86_linux_gcc_64  GCC libraries for building 64-bit Linux debugger server
    x86_mac_gcc_32    GCC libraries for building 32-bit Mac debugger server
    x86_mac_gcc_64    GCC libraries for building 64-bit Mac debugger server

  NOTE: To build the debug servers for MS Windows targets, Microsoft Windows
        SDK v7.1A must be used.

  If you want to compile the Qt plugin sample, you will also need the libQt*
  libraries. For MS Windows targets, the import libraries for Qt are available
  in the x64_win_qt directory. For Linux and Mac OS X targets, you should link
  against the Qt libraries from the IDA directory.


DESCRIPTION OF PROCESSOR MODULES
--------------------------------

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

    The analyser (ana.cpp) should be fast and simple: just decode an
    instruction into an 'insn' 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 performs the following tasks:
      - creates cross-references
      - plans to disassemble subsequent instructions
      - creates 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 parts of the line: line prefix, comments, and
    cross-references will be generated by the kernel itself.
    To generate lines, you should subclass the outctx_t structure from ua.hpp.

makefile        - makefile for a processor module
stub            - MSDOS stub for the module
ana.cpp         - analysis of an instruction: fills the insn 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.


SDK BUILD INSTRUCTIONS
----------------------

  To build the SDK using the command line on all systems (MS Windows, Linux,
  and Mac OS X), refer to:
    - install_make.txt

  For explanations on how to use the Visual C++ IDE with the SDK, refer to:
    - install_visual.txt


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

        And finally:

  We recommend to study the samples, compile and run them.
  The SDK comes with many samples and the source code for MS Windows,
  Mac OS X, and Linux debugger modules.

  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 a new processor module is written in the following way:

        - copy the sample module files to a new directory
        - 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 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
  BPT macro construct in the module initialization code.

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

        set IDALOG=ida.log

  We always have this variable set, it is very helpful.

  Support for the SDK is not included in the IDA Pro purchase but
  you can subscribe for the extended SDK support:

        http://www.hex-rays.com/products/ida/order.shtml