API 7.0 Porting Guide

clear IDA 7.0 SDK: Porting from IDA 4.9-6.x API to IDA 7.0 API

Introduction

The SDK now only supports the new 7.0 API in x64 mode. The old SDK 6.95 can be used to develop plugins for IDA 7.0-x86 (which is ABI-compatible with IDA 6.95).

While the API has been revamped somewhat, most basic concepts still hold.

There are still two variants of IDA: one supporting 32-bit (ea_t is 32-bit) and the other 64-bit address space (ea_t is 64-bit). IDA database extensions remain correspondingly '.idb' and '.i64'.

Naming of IDA binaries has been unified across all OS variants:

  • The IDA GUI binary has been renamed from 'idaq[.exe]' to just 'ida[.exe]'.

  • The IDA text-mode UI has been renamed from 'idaw.exe' (on Windows) and 'idal' (on Linux/Mac OS X) to 'idat[.exe]' on all platforms.

  • Plugins, loaders, processor modules, and the kernel now use standard OS-specific suffixes ('.dll', '.so', or '.dylib') instead of custom extensions.

General approaches that were taken when cleaning up the APIs:

  • Try to use descriptive names and drop old, cryptic abbreviations.

  • Rename functions using camelCase to snake_case (e.g. 'isFlow' -> 'is_flow').

  • Move output parameters to the front of the argument list.

  • Change input parameters to const references whenever possible.

  • Remove obsolete and deprecated functions.

  • Rename functioname2/3 to just functioname (e.g. 'validate_name3' -> 'validate_name').

  • Rename functions with 64 suffix to the main name (e.g. 'qfseek64' -> 'qfseek').

  • File offsets are 64-bit in all functions working with files.

  • Get rid of global variables (not complete, but we made good progress).

  • Most functions accepting a buffer and size (or limited to MAXSTR) now use 'qstring' or 'bytevec_t' instead (depending on the nature of the data).

  • Assume UTF-8 in most functions dealing with text.

  • Try to get rid of forced struct packing and rearrange fields to avoid unnecessary gaps as needed.

Porting

Common porting steps for plugins/loaders/modules:

  • Add __X64__ to the list of preprocessor defines. You still need to compile with or without __EA64__ defined to select between 32- and 64-bit address space.

  • If using custom build system, change output extension to OS-specific suffixes ('.dll', '.so', or '.dylib').

  • IDA library link path should start with x64 instead of x86.

Renamed/removed header files

Some headers have been renamed and/or removed:

Commonly used renamed structs and fields

area-related methods have been renamed too (e.g. 'prev_area' -> 'prev_range').

Porting plugins.

The plugin entry prototype has been changed from:

  • void idaapi run(int);

to:

  • bool idaapi run(size_t);

The input parameter is now of type 'size_t', which allows passing a pointer as the argument of run() for extra possibilities.

The rest of the plugin interface is unchanged.

Porting loaders

The prototype for 'accept_file()' has been changed from:

  • int idaapi accept_file(linput_t *li, char fileformatname[MAX_FILE_FORMAT_NAME], int n);

to:

  • int idaapi accept_file(qstring *fileformatname, qstring *processor, linput_t *li, const char *filename);

The desired processor may be returned in the 'processor' output parameter.

The return value has been extended with flags 'ACCEPT_ARCHIVE' and 'ACCEPT_CONTINUE'.

Loaders can also process and extract archives now. If you detect an archive, the return value for 'accept_file' should be ORed with the 'ACCEPT_ARCHIVE' flag. After extraction, all loaders are queried again, which means IDA can now handle multiply nested archives.

Non-archive loaders should extend the return value with the 'ACCEPT_CONTINUE' flag.

Porting processor modules

WARNING: The global variables 'cmd' and 'uFlag' are gone.

Most APIs return or accept an 'insn_t' structure with instruction details.

The 'processor_t' structure has had many unused and obsolete fields removed, such as 'flag2', 'rFiles', 'rFnames', 'rFdescs', and 'CPUregs'.

Most callbacks are now handled centrally via the 'notify()' function:

ana.cpp

Change the prototype of 'ana' from:

  • int idaapi ana(void);

to:

  • int idaapi ana(insn_t *_insn);

You may then declare an 'insn_t' reference variable to simplify your code:

  • insn_t &insn = *_insn;

Then replace all uses of 'cmd' by 'insn'. You will likely need to pass 'insn' to other helper functions that used 'cmd'.

emu.cpp

Change the prototype of 'emu' from:

  • int idaapi emu(void);

to:

  • int idaapi emu(const insn_t &insn);

Then replace all uses of 'cmd' by 'insn'. You may need to adjust some code if it was relying on cmd being writeable.

out.cpp

The output functions now use a context structure ('outctx_t') instead of operating on a global buffer.

You must declare a class inheriting from 'outctx_t' and override its methods or add new ones for non-standard functions. For example:

class out_myproc_t : public outctx_t
{
  void outreg(int r) { out_register(ph.reg_names[r]); }
  void outmem(const op_t &x, ea_t ea);
  bool outbit(ea_t ea, int bit);

  bool out_operand(const op_t &x);
  void out_insn(void);
  void out_mnem(void);
}

Then use one of the two macros from idaidp.hpp:

  • DECLARE_OUT_FUNCS_WITHOUT_OUTMNEM(out_myproc_t)

or, if you implement 'out_mnem':

  • DECLARE_OUT_FUNCS(out_myproc_t)

Then prefix old function names with your class and rename them to match methods. For example, from:

  void idaapi out(void);
  void out_myproc_t::out(void);

to:

  bool idaapi outop(op_t &x);
  bool out_myproc_t::out_operand(const op_t &x);

Then remove calls to 'init_output_buffer()' and uses of the buffer variable.

Other changes that must be made are:

  • Replacing references to 'cmd' with 'insn';

  • Replacing term_output_buffer()/MakeLine() sequence with flush_outbuf().

Most of the other code can remain intact or can be replaced by the new helper functions.

For other output-related callbacks, convert them to take an 'outctx_t &ctx' parameter and use its methods. For example, from:

  • void idaapi header(void);

to:

  • void idaapi myproc_header(outctx_t &ctx)

See the changes to 'ua.hpp' below for more information on converting the functions.

Also, see the SDK samples for more ideas.

reg.cpp

Remove the old callbacks from the 'processor_t' structure and call them from the 'notify()' function instead. For example:

    case processor_t::ev_ana_insn:
      {
        insn_t *out = va_arg(va, insn_t *);
        return myproc_ana(out);
      }

For 'ev_out_insn', call 'out_insn()' generated by the macro in out.cpp:

    case processor_t::ev_out_insn:
      {
        outctx_t *ctx = va_arg(va, outctx_t *);
        out_insn(*ctx);
        return 1;
      }

Porting notifications

  • When hooking notifications, return 0 for "not handled" instead of 1 as before.

  • Many notifications had their arguments types and/or order changed. Double-check your handlers against the new headers.

  • Instead of calling ph.notify() or similar, prefer helper inline functions for additional type safety. For example, use 'ph.get_operand_string()' instead of 'ph.notify(processor_t::get_operand_string, ...)'.

  • Some IDP events have been moved to the IDB event group (see the table class="table table-sm" below), so they should be handled on the HT_IDB level. You will need to move the corresponding code from the IDP notification hooks to the IDB hooks.

UI: Porting choosers

  • Make a new class derived from 'chooser_t' or 'chooser_multi_t'. Its fields are similar to arguments of 'choose2()' from IDA 6.95.

  • You should implement at least 2 methods:

  • 'get_count()', and

  • 'get_row()'.

The 'get_row()' method combines 3 methods of 6.95's old 'chooser_info_t':

  • 'get_row()'

  • 'get_icon()', and

  • 'get_attrs()'

  • If you want to show actions Ins/Delete/Edit/Refresh in a popup-menu you should set new bits 'CH_CAN_...' in the 'flags' member.

  • The header line is stored in a new 'header' member.

  • All indexes are now 0-based. You can use new constant 'NO_SELECTION' for non-existing rows.

  • The default value is not stored in the 'chooser_t' structure now and it is passed directly to the 'choose()' function.

  • You can prepare a specialized version of the 'choose()' method that takes a special default value (e.g. an effective address). For this you should implement a new 'get_item_index()' method.

  • The 'update()' callback has been renamed to 'refresh()' and it returns the cursor position after refresh. If the data has not changed this callback should return a 'NOTHING_CHANGED' hint.

  • The returned value of the 'ins()', 'del()', 'edit()' and 'exit()' callbacks are the same as for 'refresh()' callback. E.g. the 'ins()' callback may return the cursor position of the newly inserted item. Or the 'del()' callback may return 'NOTHING_CHANGED' if it asked the user about the removal and he refused.

  • The 'initializer()' callback has been renamed to 'init()'. Its use allows you to prepare data when it is really needed (i.e., "lazy" populating).

  • The 'destroyer()' callback has been renamed to 'closed()' and it is called when the chooser window is about to close. To clean up the chooser data you should use the destructor.

  • The 'CH_MULTI' flag has been removed altogether. If you want to create a chooser with multiple selection, you should derive your class from 'chooser_multi_t'.

  • While callbacks for the 'chooser_t' class would receive and return a single value specifying the currently-selected row, callbacks of the 'chooser_multi_t' class will receive a vector of such values instead.

  • In a similar fashion, instead of using the 'NO_SELECTION' constant, 'chooser_multi_t' will use an empty vector.

  • In contrast to IDA 6.95, the selected items are now all processed at once, in one call to the 'ins()', 'del()', 'edit()' and 'exit()' callbacks (this greatly simplified implementing them.)

Changes per file in the SDK

This section describes in detail the changes to the APIs for each file in the SDK.

auto.hpp

NOTE: global variables 'auto_state', 'auto_display', and 'autoEnabled' have been removed.

  • [1] output argument moved to beginning of argument list

bitrange.hpp

bytes.hpp

NOTE: The misleading term "ASCII string" has been replaced by "string literal" (strlit).

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

compress.hpp

config.hpp (NEW file)

dbg.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

diskio.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] return type changed from '[u]int32' to '[u]int64'/'qoff64_t'

  • [4] input argument changed from '[u]int32' to '[u]int64'/'qoff64_t'

entry.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] added 'flags' argument

enum.hpp

NOTE: global variable 'enums' has been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

err.h

expr.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] input argument changed from pointer to reference

fixup.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] input argument changed from pointer to reference

fpro.h

  • [1] input argument changed from 'int32' to 'qoff64_t'

  • [2] return type changed from 'int32' to 'qoff64_t'

frame.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] input argument 'func_t *pfn' made const

funcs.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

gdl.hpp

graph.hpp

  • [1] input argument changed from 'TCustomControl *' to 'graph_viewer_t *'

help.h

ida.hpp

idd.hpp

  • [1] output argument moved to beginning of argument list

idp.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

ieee.h

  • [1] output argument moved to beginning of argument list

ints.hpp (REMOVED)

kernwin.hpp

NOTE: Please note that in IDA version 6.7 we introduced the Actions API, which deprecated many functions related to augmenting functionality in IDA.

Those previously deprecated functions have been removed. For more details about the Actions API, please visit our old blog post from 2014:

http://www.hexblog.com/?p=886

NOTE: 'TForm', 'TCustomControl', and 'TWinControl' have been replaced by 'TWidget'

NOTE: global variable 'dirty_infos' has been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] input argument changed from pointer to reference

  • [4] return type changed from 'TForm *' to 'TWidget *'

  • [5] input argument changed from 'TCustomControl *' to 'TWidget *'

lex.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

lines.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] return type changed from 'void' to 'bool'

llong.hpp

  • [1] output argument moved to beginning of argument list

  • [2] output argument changed from reference to pointer

loader.hpp

NOTE: global variables 'database_flags', 'command_line_file', 'idb_path', and 'id0_path' have been removed.

NOTE: class 'loader_jump' has been renamed to 'loader_failure_t'

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] input argument changed from 'int32' to 'qoff64_t'

  • [3] return type changed from 'int32' to 'qoff64_t'

moves.hpp

NOTE: 'curloc_t' and 'location_t' have been replaced by 'lochist_t'.

nalt.hpp

NOTE: global variable 'import_node' has been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

name.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] output argument changed from reference to pointer

netnode.hpp

offset.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] input argument 'refinfo_t &' made const

problems.h (RENAMED from queue.hpp)

NOTE: 'qtype_t' has been changed to 'problist_id_t'.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

prodir.h

pro.h

NOTE: global variables 'codepage' and 'oemcodepage' have been removed.

  • [1] output argument moved to beginning of argument list

pronet.h

range.h (RENAMED from area.hpp)

NOTE: some classes have been renamed: - 'area_t' has been renamed to 'range_t' - 'areavec_t' has been renamed to 'rangevec_t' - 'areaset_t' has been renamed to 'rangeset_t'

NOTE: the classes 'rangecb_t', 'ranges_cache_t', and 'lock_range' have been removed

registry.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

search.hpp

  • [1] output argument moved to beginning of argument list

segment.hpp

NOTE: global variables 'hidden_ranges', 'funcs', and 'segs' have been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] added 'flags' argument

segregs.hpp (RENAMED from srarea.hpp)

NOTE: type 'segreg_area_t' has been renamed to 'sreg_range_t'

sistack.h (REMOVED)

strlist.hpp

  • [1] output argument moved to beginning of argument list

struct.hpp

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

tryblks.hpp (NEW file)

typeinf.hpp

NOTE: global variable 'idati' has been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

ua.hpp

WARNING: The global variables 'cmd' and 'uFlag' are gone.

All functions previously operating on 'cmd' now accept an 'insn_t' pointer or reference. Use get_flags() (or, if you really need it, get_full_flags()) to read the current flags.

NOTE: The maximum number of instruction operands (UA_MAXOP) has increased to 8.

NOTE: class 'outctx_base_t' has been added to replace functions that generate the disassembly text

NOTE: global variable 'lookback' has been removed.

  • [1] output argument moved to beginning of argument list

    • q: argument is a qstring

  • [2] output buffer converted to qstring

  • [3] added input/output 'insn_t &insn' argument

  • [4] added input 'const insn_t &insn' argument

  • [5] added output 'insn_t *out' argument

xref.hpp

  • [1] output argument moved to beginning of argument list

  • [2] input argument changed from pointer to reference

Last updated