keystone/package.d

   1 // Keystone Assembler Engine (www.keystone-engine.org)
   2 // By Nguyen Anh Quynh <aquynh@gmail.com>, 2016
   3 // k8: see licenses in original capstone package, i'm too lazy to copy 'em.
   4 module iv.keystone /*is aliced*/;
   5 pragma(lib, "keystone");
   6 import iv.alice;
   7 extern(C) nothrow:
   8
   9 struct ks_engine {}
  10
  11 // Keystone API version
  12 enum KS_API_MAJOR = 0;
  13 enum KS_API_MINOR = 9;
  14
  15 /*
  16   Macro to create combined version which can be compared to
  17   result of ks_version() API.
  18 */
  19 uint KS_MAKE_VERSION (ubyte major, ubyte minor) { return ((major<<8)+minor); }
  20
  21 // Architecture type
  22 alias ks_arch = uint;
  23 enum /*ks_arch*/ : uint {
  24   KS_ARCH_ARM = 1, // ARM architecture (including Thumb, Thumb-2)
  25   KS_ARCH_ARM64,   // ARM-64, also called AArch64
  26   KS_ARCH_MIPS,    // Mips architecture
  27   KS_ARCH_X86,     // X86 architecture (including x86 & x86-64)
  28   KS_ARCH_PPC,     // PowerPC architecture (currently unsupported)
  29   KS_ARCH_SPARC,   // Sparc architecture
  30   KS_ARCH_SYSTEMZ, // SystemZ architecture (S390X)
  31   KS_ARCH_HEXAGON, // Hexagon architecture
  32   KS_ARCH_MAX,
  33 }
  34
  35 // Mode type
  36 alias ks_mode = uint;
  37 enum /*ks_mode*/ : uint {
  38   KS_MODE_LITTLE_ENDIAN = 0,    // little-endian mode (default mode)
  39   KS_MODE_BIG_ENDIAN = 1 << 30, // big-endian mode
  40   // arm / arm64
  41   KS_MODE_ARM = 1 << 0,         // ARM mode
  42   KS_MODE_THUMB = 1 << 4,       // THUMB mode (including Thumb-2)
  43   KS_MODE_V8 = 1 << 6,          // ARMv8 A32 encodings for ARM
  44   // mips
  45   KS_MODE_MICRO = 1 << 4,       // MicroMips mode
  46   KS_MODE_MIPS3 = 1 << 5,       // Mips III ISA
  47   KS_MODE_MIPS32R6 = 1 << 6,    // Mips32r6 ISA
  48   KS_MODE_MIPS32 = 1 << 2,      // Mips32 ISA
  49   KS_MODE_MIPS64 = 1 << 3,      // Mips64 ISA
  50   // x86 / x64
  51   KS_MODE_16 = 1 << 1,          // 16-bit mode
  52   KS_MODE_32 = 1 << 2,          // 32-bit mode
  53   KS_MODE_64 = 1 << 3,          // 64-bit mode
  54   // ppc
  55   KS_MODE_PPC32 = 1 << 2,       // 32-bit mode
  56   KS_MODE_PPC64 = 1 << 3,       // 64-bit mode
  57   KS_MODE_QPX = 1 << 4,         // Quad Processing eXtensions mode
  58   // sparc
  59   KS_MODE_SPARC32 = 1 << 2,     // 32-bit mode
  60   KS_MODE_SPARC64 = 1 << 3,     // 64-bit mode
  61   KS_MODE_V9 = 1 << 4,          // SparcV9 mode
  62 }
  63
  64 // All generic errors related to input assembly >= KS_ERR_ASM
  65 enum KS_ERR_ASM = 128;
  66
  67 // All architecture-specific errors related to input assembly >= KS_ERR_ASM_ARCH
  68 enum KS_ERR_ASM_ARCH = 512;
  69
  70 // All type of errors encountered by Keystone API.
  71 alias ks_err = uint;
  72 enum /*ks_err*/ : uint {
  73   KS_ERR_OK = 0,   // No error: everything was fine
  74   KS_ERR_NOMEM,      // Out-Of-Memory error: ks_open(), ks_emulate()
  75   KS_ERR_ARCH,     // Unsupported architecture: ks_open()
  76   KS_ERR_HANDLE,   // Invalid handle
  77   KS_ERR_MODE,     // Invalid/unsupported mode: ks_open()
  78   KS_ERR_VERSION,  // Unsupported version (bindings)
  79   KS_ERR_OPT_INVALID,  // Unsupported option
  80
  81   // generic input assembly errors - parser specific
  82   KS_ERR_ASM_EXPR_TOKEN = KS_ERR_ASM,    // unknown token in expression
  83   KS_ERR_ASM_DIRECTIVE_VALUE_RANGE,   // literal value out of range for directive
  84   KS_ERR_ASM_DIRECTIVE_ID,    // expected identifier in directive
  85   KS_ERR_ASM_DIRECTIVE_TOKEN, // unexpected token in directive
  86   KS_ERR_ASM_DIRECTIVE_STR,   // expected string in directive
  87   KS_ERR_ASM_DIRECTIVE_COMMA, // expected comma in directive
  88   KS_ERR_ASM_DIRECTIVE_RELOC_NAME, // expected relocation name in directive
  89   KS_ERR_ASM_DIRECTIVE_RELOC_TOKEN, // unexpected token in .reloc directive
  90   KS_ERR_ASM_DIRECTIVE_FPOINT,    // invalid floating point in directive
  91   KS_ERR_ASM_DIRECTIVE_UNKNOWN,    // unknown directive
  92   KS_ERR_ASM_DIRECTIVE_EQU,   // invalid equal directive
  93   KS_ERR_ASM_DIRECTIVE_INVALID,   // (generic) invalid directive
  94   KS_ERR_ASM_VARIANT_INVALID, // invalid variant
  95   KS_ERR_ASM_EXPR_BRACKET,    // brackets expression not supported on this target
  96   KS_ERR_ASM_SYMBOL_MODIFIER, // unexpected symbol modifier following '@'
  97   KS_ERR_ASM_SYMBOL_REDEFINED, // invalid symbol redefinition
  98   KS_ERR_ASM_SYMBOL_MISSING,  // cannot find a symbol
  99   KS_ERR_ASM_RPAREN,          // expected ')' in parentheses expression
 100   KS_ERR_ASM_STAT_TOKEN,      // unexpected token at start of statement
 101   KS_ERR_ASM_UNSUPPORTED,     // unsupported token yet
 102   KS_ERR_ASM_MACRO_TOKEN,     // unexpected token in macro instantiation
 103   KS_ERR_ASM_MACRO_PAREN,     // unbalanced parentheses in macro argument
 104   KS_ERR_ASM_MACRO_EQU,       // expected '=' after formal parameter identifier
 105   KS_ERR_ASM_MACRO_ARGS,      // too many positional arguments
 106   KS_ERR_ASM_MACRO_LEVELS_EXCEED, // macros cannot be nested more than 20 levels deep
 107   KS_ERR_ASM_MACRO_STR,    // invalid macro string
 108   KS_ERR_ASM_MACRO_INVALID,    // invalid macro (generic error)
 109   KS_ERR_ASM_ESC_BACKSLASH,   // unexpected backslash at end of escaped string
 110   KS_ERR_ASM_ESC_OCTAL,       // invalid octal escape sequence  (out of range)
 111   KS_ERR_ASM_ESC_SEQUENCE,         // invalid escape sequence (unrecognized character)
 112   KS_ERR_ASM_ESC_STR,         // broken escape string
 113   KS_ERR_ASM_TOKEN_INVALID,   // invalid token
 114   KS_ERR_ASM_INSN_UNSUPPORTED,   // this instruction is unsupported in this mode
 115   KS_ERR_ASM_FIXUP_INVALID,   // invalid fixup
 116   KS_ERR_ASM_LABEL_INVALID,   // invalid label
 117   KS_ERR_ASM_FRAGMENT_INVALID,   // invalid fragment
 118
 119   // generic input assembly errors - architecture specific
 120   KS_ERR_ASM_INVALIDOPERAND = KS_ERR_ASM_ARCH,
 121   KS_ERR_ASM_MISSINGFEATURE,
 122   KS_ERR_ASM_MNEMONICFAIL,
 123 }
 124
 125
 126 // Runtime option for the Keystone engine
 127 alias ks_opt_type = uint;
 128 enum /*ks_opt_type*/ : uint {
 129   KS_OPT_SYNTAX = 1,  // Choose syntax for input assembly
 130 }
 131
 132
 133 // Runtime option value (associated with ks_opt_type above)
 134 alias ks_opt_value = uint;
 135 enum /*ks_opt_value*/ : uint {
 136   KS_OPT_SYNTAX_INTEL = 1 << 0, // X86 Intel syntax - default on X86 (KS_OPT_SYNTAX).
 137   KS_OPT_SYNTAX_ATT   = 1 << 1, // X86 ATT asm syntax (KS_OPT_SYNTAX).
 138   KS_OPT_SYNTAX_NASM  = 1 << 2, // X86 Nasm syntax (KS_OPT_SYNTAX).
 139   KS_OPT_SYNTAX_MASM  = 1 << 3, // X86 Masm syntax (KS_OPT_SYNTAX) - unsupported yet.
 140   KS_OPT_SYNTAX_GAS   = 1 << 4, // X86 GNU GAS syntax (KS_OPT_SYNTAX).
 141 }
 142
 143 // x86
 144 alias ks_err_asm_x86 = uint;
 145 enum /*ks_err_asm_x86*/ {
 146   KS_ERR_ASM_X86_INVALIDOPERAND = KS_ERR_ASM_ARCH,
 147   KS_ERR_ASM_X86_MISSINGFEATURE,
 148   KS_ERR_ASM_X86_MNEMONICFAIL,
 149 }
 150
 151 /*
 152  Return combined API version & major and minor version numbers.
 153
 154  @major: major number of API version
 155  @minor: minor number of API version
 156
 157  @return hexical number as (major << 8 | minor), which encodes both
 158      major & minor versions.
 159      NOTE: This returned value can be compared with version number made
 160      with macro KS_MAKE_VERSION
 161
 162  For example, second API version would return 1 in @major, and 1 in @minor
 163  The return value would be 0x0101
 164
 165  NOTE: if you only care about returned value, but not major and minor values,
 166  set both @major & @minor arguments to NULL.
 167 */
 168 public uint ks_version (uint* major, uint* minor);
 169
 170
 171 /*
 172  Determine if the given architecture is supported by this library.
 173
 174  @arch: architecture type (KS_ARCH_*)
 175
 176  @return True if this library supports the given arch.
 177 */
 178 public bool ks_arch_supported (ks_arch arch);
 179
 180
 181 /*
 182  Create new instance of Keystone engine.
 183
 184  @arch: architecture type (KS_ARCH_*)
 185  @mode: hardware mode. This is combined of KS_MODE_*
 186  @ks: pointer to ks_engine, which will be updated at return time
 187
 188  @return KS_ERR_OK on success, or other value on failure (refer to ks_err enum
 189    for detailed error).
 190 */
 191 public ks_err ks_open (ks_arch arch, int mode, ks_engine** ks);
 192
 193
 194 /*
 195  Close KS instance: MUST do to release the handle when it is not used anymore.
 196  NOTE: this must be called only when there is no longer usage of Keystone.
 197  The reason is the this API releases some cached memory, thus access to any
 198  Keystone API after ks_close() might crash your application.
 199  After this, @ks is invalid, and nolonger usable.
 200
 201  @ks: pointer to a handle returned by ks_open()
 202
 203  @return KS_ERR_OK on success, or other value on failure (refer to ks_err enum
 204    for detailed error).
 205 */
 206 public ks_err ks_close (ks_engine* ks);
 207
 208
 209 /*
 210  Report the last error number when some API function fail.
 211  Like glibc's errno, ks_errno might not retain its old error once accessed.
 212
 213  @ks: handle returned by ks_open()
 214
 215  @return: error code of ks_err enum type (KS_ERR_*, see above)
 216 */
 217 public ks_err ks_errno (ks_engine* ks);
 218
 219
 220 /*
 221  Return a string describing given error code.
 222
 223  @code: error code (see KS_ERR_* above)
 224
 225  @return: returns a pointer to a string that describes the error code
 226    passed in the argument @code
 227  */
 228 public const(char)* ks_strerror (ks_err code);
 229
 230
 231 /*
 232  Set option for Keystone engine at runtime
 233
 234  @ks: handle returned by ks_open()
 235  @type: type of option to be set
 236  @value: option value corresponding with @type
 237
 238  @return: KS_ERR_OK on success, or other value on failure.
 239  Refer to ks_err enum for detailed error.
 240 */
 241 public ks_err ks_option (ks_engine* ks, ks_opt_type type, usize value);
 242
 243
 244 /*
 245  Assemble a string given its the buffer, size, start address and number
 246  of instructions to be decoded.
 247  This API dynamically allocate memory to contain assembled instruction.
 248  Resulted array of bytes containing the machine code  is put into @*encoding
 249
 250  NOTE 1: this API will automatically determine memory needed to contain
 251  output bytes in *encoding.
 252
 253  NOTE 2: caller must free the allocated memory itself to avoid memory leaking.
 254
 255  @ks: handle returned by ks_open()
 256  @str: NULL-terminated assembly string. Use ; or \n to separate statements.
 257  @address: address of the first assembly instruction, or 0 to ignore.
 258  @encoding: array of bytes containing encoding of input assembly string.
 259      NOTE: *encoding will be allocated by this function, and should be freed
 260      with ks_free() function.
 261  @encoding_size: size of *encoding
 262  @stat_count: number of statements successfully processed
 263
 264  @return: 0 on success, or -1 on failure.
 265
 266  On failure, call ks_errno() for error code.
 267 */
 268 public int ks_asm (ks_engine* ks, const(char)* string, ulong address, ubyte** encoding, usize* encoding_size, usize* stat_count);
 269
 270
 271 /*
 272  Free memory allocated by ks_asm()
 273
 274  @p: memory allocated in @encoding argument of ks_asm()
 275 */
 276 public void ks_free (void* p);