Nguyen Anh Quynh | ae3649f | 2014-01-02 13:15:07 +0800 | [diff] [blame] | 1 | #ifndef CAPSTONE_ENGINE_H |
| 2 | #define CAPSTONE_ENGINE_H |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 3 | |
Nguyen Anh Quynh | 7751fbe | 2014-04-28 11:23:14 +0800 | [diff] [blame] | 4 | /* Capstone Disassembly Engine */ |
| 5 | /* By Nguyen Anh Quynh <aquynh@gmail.com>, 2013-2014 */ |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 6 | |
| 7 | #ifdef __cplusplus |
| 8 | extern "C" { |
| 9 | #endif |
| 10 | |
| 11 | #include <stdint.h> |
Nguyen Anh Quynh | 64d4083 | 2014-01-17 20:55:21 +0800 | [diff] [blame] | 12 | #include <stdarg.h> |
reverser | bcf09f4 | 2015-04-09 18:28:19 +0100 | [diff] [blame] | 13 | #if defined(CAPSTONE_HAS_OSXKERNEL) |
| 14 | #include <libkern/libkern.h> |
| 15 | #else |
Nguyen Anh Quynh | f185180 | 2013-12-21 12:16:47 +0800 | [diff] [blame] | 16 | #include <stdlib.h> |
reverser | bcf09f4 | 2015-04-09 18:28:19 +0100 | [diff] [blame] | 17 | #include <stdio.h> |
| 18 | #endif |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 19 | |
Nguyen Anh Quynh | 171eb75 | 2014-05-15 21:01:08 +0800 | [diff] [blame] | 20 | #include "platform.h" |
| 21 | |
Alex Ionescu | 46018db | 2014-01-22 09:45:00 -0800 | [diff] [blame] | 22 | #ifdef _MSC_VER |
Nguyen Anh Quynh | a18abdd | 2014-10-29 21:32:06 +0800 | [diff] [blame] | 23 | #pragma warning(disable:4201) |
| 24 | #pragma warning(disable:4100) |
| 25 | #ifdef CAPSTONE_SHARED |
| 26 | #define CAPSTONE_EXPORT __declspec(dllexport) |
| 27 | #else // defined(CAPSTONE_STATIC) |
| 28 | #define CAPSTONE_EXPORT |
| 29 | #endif |
Ali Rizvi-Santiago | 10053ba | 2014-06-03 21:04:23 +0000 | [diff] [blame] | 30 | #else |
Hilko Bengen | d83bf84 | 2015-02-26 18:37:32 +0100 | [diff] [blame] | 31 | #ifdef __GNUC__ |
| 32 | #define CAPSTONE_EXPORT __attribute__((visibility("default"))) |
| 33 | #else |
Nguyen Anh Quynh | a18abdd | 2014-10-29 21:32:06 +0800 | [diff] [blame] | 34 | #define CAPSTONE_EXPORT |
Alex Ionescu | 46018db | 2014-01-22 09:45:00 -0800 | [diff] [blame] | 35 | #endif |
Hilko Bengen | d83bf84 | 2015-02-26 18:37:32 +0100 | [diff] [blame] | 36 | #endif |
Alex Ionescu | 46018db | 2014-01-22 09:45:00 -0800 | [diff] [blame] | 37 | |
Nguyen Anh Quynh | 0beb0d4 | 2014-08-27 22:55:29 +0800 | [diff] [blame] | 38 | #ifdef __GNUC__ |
| 39 | #define CAPSTONE_DEPRECATED __attribute__((deprecated)) |
| 40 | #elif defined(_MSC_VER) |
| 41 | #define CAPSTONE_DEPRECATED __declspec(deprecated) |
| 42 | #else |
| 43 | #pragma message("WARNING: You need to implement CAPSTONE_DEPRECATED for this compiler") |
| 44 | #define CAPSTONE_DEPRECATED |
| 45 | #endif |
| 46 | |
Nguyen Anh Quynh | bb64b0b | 2013-12-10 07:56:17 +0800 | [diff] [blame] | 47 | // Capstone API version |
Nguyen Anh Quynh | fd0f798 | 2014-08-13 14:15:27 +0800 | [diff] [blame] | 48 | #define CS_API_MAJOR 3 |
| 49 | #define CS_API_MINOR 0 |
Nguyen Anh Quynh | bb64b0b | 2013-12-10 07:56:17 +0800 | [diff] [blame] | 50 | |
Nguyen Anh Quynh | 2296d5e | 2013-12-22 21:01:17 +0800 | [diff] [blame] | 51 | // Macro to create combined version which can be compared to |
Nguyen Anh Quynh | b90cb99 | 2013-12-28 13:59:09 +0800 | [diff] [blame] | 52 | // result of cs_version() API. |
Nguyen Anh Quynh | 2296d5e | 2013-12-22 21:01:17 +0800 | [diff] [blame] | 53 | #define CS_MAKE_VERSION(major, minor) ((major << 8) + minor) |
| 54 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 55 | // Handle using with all API |
Nguyen Anh Quynh | b42a657 | 2013-11-29 17:40:07 +0800 | [diff] [blame] | 56 | typedef size_t csh; |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 57 | |
| 58 | // Architecture type |
| 59 | typedef enum cs_arch { |
| 60 | CS_ARCH_ARM = 0, // ARM architecture (including Thumb, Thumb-2) |
| 61 | CS_ARCH_ARM64, // ARM-64, also called AArch64 |
| 62 | CS_ARCH_MIPS, // Mips architecture |
| 63 | CS_ARCH_X86, // X86 architecture (including x86 & x86-64) |
Nguyen Anh Quynh | 42c6b1a | 2013-12-30 00:15:25 +0800 | [diff] [blame] | 64 | CS_ARCH_PPC, // PowerPC architecture |
Nguyen Anh Quynh | 05e2713 | 2014-03-10 11:58:57 +0800 | [diff] [blame] | 65 | CS_ARCH_SPARC, // Sparc architecture |
Nguyen Anh Quynh | 48a14ca | 2014-03-23 08:35:45 +0800 | [diff] [blame] | 66 | CS_ARCH_SYSZ, // SystemZ architecture |
Nguyen Anh Quynh | c80d840 | 2014-05-26 23:02:48 +0800 | [diff] [blame] | 67 | CS_ARCH_XCORE, // XCore architecture |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 68 | CS_ARCH_MAX, |
Nguyen Anh Quynh | 753f44a | 2014-11-12 11:05:42 +0800 | [diff] [blame] | 69 | CS_ARCH_ALL = 0xFFFF, // All architectures - for cs_support() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 70 | } cs_arch; |
| 71 | |
Nguyen Anh Quynh | 9518148 | 2014-03-25 23:20:41 +0800 | [diff] [blame] | 72 | // Support value to verify diet mode of the engine. |
| 73 | // If cs_support(CS_SUPPORT_DIET) return True, the engine was compiled |
| 74 | // in diet mode. |
Nguyen Anh Quynh | 492b8ed | 2014-02-25 08:14:15 +0800 | [diff] [blame] | 75 | #define CS_SUPPORT_DIET (CS_ARCH_ALL + 1) |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 76 | |
Nguyen Anh Quynh | 6d3c711 | 2014-03-27 15:38:23 +0800 | [diff] [blame] | 77 | // Support value to verify X86 reduce mode of the engine. |
Nguyen Anh Quynh | 59b5489 | 2014-03-27 10:54:44 +0800 | [diff] [blame] | 78 | // If cs_support(CS_SUPPORT_X86_REDUCE) return True, the engine was compiled |
Nguyen Anh Quynh | 6d3c711 | 2014-03-27 15:38:23 +0800 | [diff] [blame] | 79 | // in X86 reduce mode. |
Nguyen Anh Quynh | 59b5489 | 2014-03-27 10:54:44 +0800 | [diff] [blame] | 80 | #define CS_SUPPORT_X86_REDUCE (CS_ARCH_ALL + 2) |
Nguyen Anh Quynh | 9518148 | 2014-03-25 23:20:41 +0800 | [diff] [blame] | 81 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 82 | // Mode type |
| 83 | typedef enum cs_mode { |
Nguyen Anh Quynh | a7b06fd | 2014-11-13 12:00:48 +0800 | [diff] [blame] | 84 | CS_MODE_LITTLE_ENDIAN = 0, // little-endian mode (default mode) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 85 | CS_MODE_ARM = 0, // 32-bit ARM |
Nguyen Anh Quynh | a7b06fd | 2014-11-13 12:00:48 +0800 | [diff] [blame] | 86 | CS_MODE_16 = 1 << 1, // 16-bit mode (X86) |
| 87 | CS_MODE_32 = 1 << 2, // 32-bit mode (X86) |
| 88 | CS_MODE_64 = 1 << 3, // 64-bit mode (X86, PPC) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 89 | CS_MODE_THUMB = 1 << 4, // ARM's Thumb mode, including Thumb-2 |
Nguyen Anh Quynh | 7c089fd | 2014-08-13 23:08:40 +0800 | [diff] [blame] | 90 | CS_MODE_MCLASS = 1 << 5, // ARM's Cortex-M series |
Nguyen Anh Quynh | c942f22 | 2014-11-10 21:52:09 +0800 | [diff] [blame] | 91 | CS_MODE_V8 = 1 << 6, // ARMv8 A32 encodings for ARM |
Nguyen Anh Quynh | a7b06fd | 2014-11-13 12:00:48 +0800 | [diff] [blame] | 92 | CS_MODE_MICRO = 1 << 4, // MicroMips mode (MIPS) |
Jay Oster | 79e253c | 2014-10-12 16:03:12 -0700 | [diff] [blame] | 93 | CS_MODE_MIPS3 = 1 << 5, // Mips III ISA |
| 94 | CS_MODE_MIPS32R6 = 1 << 6, // Mips32r6 ISA |
Nguyen Anh Quynh | a7b06fd | 2014-11-13 12:00:48 +0800 | [diff] [blame] | 95 | CS_MODE_MIPSGP64 = 1 << 7, // General Purpose Registers are 64-bit wide (MIPS) |
| 96 | CS_MODE_V9 = 1 << 4, // SparcV9 mode (Sparc) |
| 97 | CS_MODE_BIG_ENDIAN = 1 << 31, // big-endian mode |
| 98 | CS_MODE_MIPS32 = CS_MODE_32, // Mips32 ISA (Mips) |
| 99 | CS_MODE_MIPS64 = CS_MODE_64, // Mips64 ISA (Mips) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 100 | } cs_mode; |
| 101 | |
Nguyen Anh Quynh | a8eb7a5 | 2014-01-11 12:55:31 +0800 | [diff] [blame] | 102 | typedef void* (*cs_malloc_t)(size_t size); |
| 103 | typedef void* (*cs_calloc_t)(size_t nmemb, size_t size); |
| 104 | typedef void* (*cs_realloc_t)(void *ptr, size_t size); |
| 105 | typedef void (*cs_free_t)(void *ptr); |
Nguyen Anh Quynh | bdd1e34 | 2014-01-16 12:34:06 +0800 | [diff] [blame] | 106 | typedef int (*cs_vsnprintf_t)(char *str, size_t size, const char *format, va_list ap); |
Nguyen Anh Quynh | edeeb04 | 2014-01-15 20:44:03 +0800 | [diff] [blame] | 107 | |
Nguyen Anh Quynh | 24bf0d9 | 2014-01-05 11:19:04 +0800 | [diff] [blame] | 108 | |
Nguyen Anh Quynh | 56aba59 | 2014-01-15 21:24:28 +0800 | [diff] [blame] | 109 | // User-defined dynamic memory related functions: malloc/calloc/realloc/free/vsnprintf() |
| 110 | // By default, Capstone uses system's malloc(), calloc(), realloc(), free() & vsnprintf(). |
Nguyen Anh Quynh | 24bf0d9 | 2014-01-05 11:19:04 +0800 | [diff] [blame] | 111 | typedef struct cs_opt_mem { |
Nguyen Anh Quynh | a8eb7a5 | 2014-01-11 12:55:31 +0800 | [diff] [blame] | 112 | cs_malloc_t malloc; |
| 113 | cs_calloc_t calloc; |
| 114 | cs_realloc_t realloc; |
| 115 | cs_free_t free; |
Nguyen Anh Quynh | edeeb04 | 2014-01-15 20:44:03 +0800 | [diff] [blame] | 116 | cs_vsnprintf_t vsnprintf; |
Nguyen Anh Quynh | 24bf0d9 | 2014-01-05 11:19:04 +0800 | [diff] [blame] | 117 | } cs_opt_mem; |
| 118 | |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 119 | // Runtime option for the disassembled engine |
Nguyen Anh Quynh | b8ce68e | 2013-12-03 23:45:08 +0800 | [diff] [blame] | 120 | typedef enum cs_opt_type { |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 121 | CS_OPT_SYNTAX = 1, // Assembly output syntax |
Nguyen Anh Quynh | a209e67 | 2013-12-14 00:23:41 +0800 | [diff] [blame] | 122 | CS_OPT_DETAIL, // Break down instruction structure into details |
Nguyen Anh Quynh | 1bdb23a | 2013-12-20 00:04:26 +0800 | [diff] [blame] | 123 | CS_OPT_MODE, // Change engine's mode at run-time |
Nguyen Anh Quynh | 56aba59 | 2014-01-15 21:24:28 +0800 | [diff] [blame] | 124 | CS_OPT_MEM, // User-defined dynamic memory related functions |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 125 | CS_OPT_SKIPDATA, // Skip data when disassembling. Then engine is in SKIPDATA mode. |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 126 | CS_OPT_SKIPDATA_SETUP, // Setup user-defined function for SKIPDATA option |
Nguyen Anh Quynh | b8ce68e | 2013-12-03 23:45:08 +0800 | [diff] [blame] | 127 | } cs_opt_type; |
| 128 | |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 129 | // Runtime option value (associated with option type above) |
Nguyen Anh Quynh | b8ce68e | 2013-12-03 23:45:08 +0800 | [diff] [blame] | 130 | typedef enum cs_opt_value { |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 131 | CS_OPT_OFF = 0, // Turn OFF an option - default option of CS_OPT_DETAIL, CS_OPT_SKIPDATA. |
| 132 | CS_OPT_ON = 3, // Turn ON an option (CS_OPT_DETAIL, CS_OPT_SKIPDATA). |
Nguyen Anh Quynh | 42c6b1a | 2013-12-30 00:15:25 +0800 | [diff] [blame] | 133 | CS_OPT_SYNTAX_DEFAULT = 0, // Default asm syntax (CS_OPT_SYNTAX). |
| 134 | CS_OPT_SYNTAX_INTEL, // X86 Intel asm syntax - default on X86 (CS_OPT_SYNTAX). |
Nguyen Anh Quynh | c263d35 | 2014-01-07 23:50:02 +0800 | [diff] [blame] | 135 | CS_OPT_SYNTAX_ATT, // X86 ATT asm syntax (CS_OPT_SYNTAX). |
Nguyen Anh Quynh | 2ff665a | 2014-03-11 00:18:50 +0800 | [diff] [blame] | 136 | CS_OPT_SYNTAX_NOREGNAME, // Prints register name with only number (CS_OPT_SYNTAX) |
Nguyen Anh Quynh | b8ce68e | 2013-12-03 23:45:08 +0800 | [diff] [blame] | 137 | } cs_opt_value; |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 138 | |
Nguyen Anh Quynh | 3ab5091 | 2014-10-31 14:40:45 +0800 | [diff] [blame] | 139 | //> Common instruction operand types - to be consistent across all architectures. |
Nguyen Anh Quynh | 21ac056 | 2014-10-31 13:08:28 +0800 | [diff] [blame] | 140 | typedef enum cs_op_type { |
| 141 | CS_OP_INVALID = 0, // uninitialized/invalid operand. |
| 142 | CS_OP_REG, // Register operand. |
| 143 | CS_OP_IMM, // Immediate operand. |
| 144 | CS_OP_MEM, // Memory operand. |
Nguyen Anh Quynh | 3ab5091 | 2014-10-31 14:40:45 +0800 | [diff] [blame] | 145 | CS_OP_FP, // Floating-Point operand. |
Nguyen Anh Quynh | 21ac056 | 2014-10-31 13:08:28 +0800 | [diff] [blame] | 146 | } cs_op_type; |
| 147 | |
Nguyen Anh Quynh | 3ab5091 | 2014-10-31 14:40:45 +0800 | [diff] [blame] | 148 | //> Common instruction groups - to be consistent across all architectures. |
| 149 | typedef enum cs_group_type { |
| 150 | CS_GRP_INVALID = 0, // uninitialized/invalid group. |
| 151 | CS_GRP_JUMP, // all jump instructions (conditional+direct+indirect jumps) |
| 152 | CS_GRP_CALL, // all call instructions |
| 153 | CS_GRP_RET, // all return instructions |
| 154 | CS_GRP_INT, // all interrupt instructions (int+syscall) |
| 155 | CS_GRP_IRET, // all interrupt return instructions |
| 156 | } cs_group_type; |
| 157 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 158 | /* |
Nguyen Anh Quynh | ff2939a | 2014-10-12 10:43:02 +0800 | [diff] [blame] | 159 | User-defined callback function for SKIPDATA option. |
| 160 | See tests/test_skipdata.c for sample code demonstrating this API. |
| 161 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 162 | @code: the input buffer containing code to be disassembled. |
| 163 | This is the same buffer passed to cs_disasm(). |
| 164 | @code_size: size (in bytes) of the above @code buffer. |
| 165 | @offset: the position of the currently-examining byte in the input |
| 166 | buffer @code mentioned above. |
| 167 | @user_data: user-data passed to cs_option() via @user_data field in |
| 168 | cs_opt_skipdata struct below. |
| 169 | |
| 170 | @return: return number of bytes to skip, or 0 to immediately stop disassembling. |
| 171 | */ |
Nguyen Anh Quynh | 43efc45 | 2014-10-11 00:38:30 +0800 | [diff] [blame] | 172 | typedef size_t (*cs_skipdata_cb_t)(const uint8_t *code, size_t code_size, size_t offset, void *user_data); |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 173 | |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 174 | // User-customized setup for SKIPDATA option |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 175 | typedef struct cs_opt_skipdata { |
| 176 | // Capstone considers data to skip as special "instructions". |
| 177 | // User can specify the string for this instruction's "mnemonic" here. |
Nguyen Anh Quynh | 2c425fc | 2014-09-07 09:46:54 +0800 | [diff] [blame] | 178 | // By default (if @mnemonic is NULL), Capstone use ".byte". |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 179 | const char *mnemonic; |
Nguyen Anh Quynh | a89383e | 2014-04-10 11:53:46 +0800 | [diff] [blame] | 180 | |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 181 | // User-defined callback function to be called when Capstone hits data. |
Nguyen Anh Quynh | a89383e | 2014-04-10 11:53:46 +0800 | [diff] [blame] | 182 | // If the returned value from this callback is positive (>0), Capstone |
| 183 | // will skip exactly that number of bytes & continue. Otherwise, if |
| 184 | // the callback returns 0, Capstone stops disassembling and returns |
Nguyen Anh Quynh | 0beb0d4 | 2014-08-27 22:55:29 +0800 | [diff] [blame] | 185 | // immediately from cs_disasm() |
Nguyen Anh Quynh | a89383e | 2014-04-10 11:53:46 +0800 | [diff] [blame] | 186 | // NOTE: if this callback pointer is NULL, Capstone would skip a number |
| 187 | // of bytes depending on architectures, as following: |
| 188 | // Arm: 2 bytes (Thumb mode) or 4 bytes. |
| 189 | // Arm64: 4 bytes. |
| 190 | // Mips: 4 bytes. |
Nguyen Anh Quynh | 3d5b6f3 | 2014-04-11 09:53:53 +0800 | [diff] [blame] | 191 | // PowerPC: 4 bytes. |
Nguyen Anh Quynh | a89383e | 2014-04-10 11:53:46 +0800 | [diff] [blame] | 192 | // Sparc: 4 bytes. |
| 193 | // SystemZ: 2 bytes. |
| 194 | // X86: 1 bytes. |
Nguyen Anh Quynh | c80d840 | 2014-05-26 23:02:48 +0800 | [diff] [blame] | 195 | // XCore: 2 bytes. |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 196 | cs_skipdata_cb_t callback; // default value is NULL |
Nguyen Anh Quynh | a89383e | 2014-04-10 11:53:46 +0800 | [diff] [blame] | 197 | |
Nguyen Anh Quynh | d3ffe37 | 2014-04-09 23:49:30 +0800 | [diff] [blame] | 198 | // User-defined data to be passed to @callback function pointer. |
| 199 | void *user_data; |
| 200 | } cs_opt_skipdata; |
| 201 | |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 202 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 203 | #include "arm.h" |
| 204 | #include "arm64.h" |
| 205 | #include "mips.h" |
Nguyen Anh Quynh | 42c6b1a | 2013-12-30 00:15:25 +0800 | [diff] [blame] | 206 | #include "ppc.h" |
Nguyen Anh Quynh | 05e2713 | 2014-03-10 11:58:57 +0800 | [diff] [blame] | 207 | #include "sparc.h" |
Nguyen Anh Quynh | 48a14ca | 2014-03-23 08:35:45 +0800 | [diff] [blame] | 208 | #include "systemz.h" |
| 209 | #include "x86.h" |
Nguyen Anh Quynh | c80d840 | 2014-05-26 23:02:48 +0800 | [diff] [blame] | 210 | #include "xcore.h" |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 211 | |
Nguyen Anh Quynh | 4fe224b | 2013-12-24 16:49:36 +0800 | [diff] [blame] | 212 | // NOTE: All information in cs_detail is only available when CS_OPT_DETAIL = CS_OPT_ON |
| 213 | typedef struct cs_detail { |
| 214 | uint8_t regs_read[12]; // list of implicit registers read by this insn |
| 215 | uint8_t regs_read_count; // number of implicit registers read by this insn |
| 216 | |
| 217 | uint8_t regs_write[20]; // list of implicit registers modified by this insn |
| 218 | uint8_t regs_write_count; // number of implicit registers modified by this insn |
| 219 | |
| 220 | uint8_t groups[8]; // list of group this instruction belong to |
| 221 | uint8_t groups_count; // number of groups this insn belongs to |
| 222 | |
| 223 | // Architecture-specific instruction info |
| 224 | union { |
| 225 | cs_x86 x86; // X86 architecture, including 16-bit, 32-bit & 64-bit mode |
| 226 | cs_arm64 arm64; // ARM64 architecture (aka AArch64) |
| 227 | cs_arm arm; // ARM architecture (including Thumb/Thumb2) |
| 228 | cs_mips mips; // MIPS architecture |
Nguyen Anh Quynh | 42c6b1a | 2013-12-30 00:15:25 +0800 | [diff] [blame] | 229 | cs_ppc ppc; // PowerPC architecture |
Nguyen Anh Quynh | 05e2713 | 2014-03-10 11:58:57 +0800 | [diff] [blame] | 230 | cs_sparc sparc; // Sparc architecture |
Nguyen Anh Quynh | 48a14ca | 2014-03-23 08:35:45 +0800 | [diff] [blame] | 231 | cs_sysz sysz; // SystemZ architecture |
Nguyen Anh Quynh | c80d840 | 2014-05-26 23:02:48 +0800 | [diff] [blame] | 232 | cs_xcore xcore; // XCore architecture |
Nguyen Anh Quynh | 4fe224b | 2013-12-24 16:49:36 +0800 | [diff] [blame] | 233 | }; |
| 234 | } cs_detail; |
| 235 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 236 | // Detail information of disassembled instruction |
| 237 | typedef struct cs_insn { |
mrexodia | ac9253c | 2015-04-24 22:56:55 +0200 | [diff] [blame] | 238 | // Instruction ID (basically a numeric ID for the instruction mnemonic) |
| 239 | // Find the instruction id in the '[ARCH]_insn' enum in the header file |
| 240 | // of corresponding architecture, such as 'arm_insn' in arm.h for ARM, |
| 241 | // 'x86_insn' in x86.h for X86, etc... |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 242 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
Nguyen Anh Quynh | fb429b1 | 2014-10-12 15:29:12 +0800 | [diff] [blame] | 243 | // NOTE: in Skipdata mode, "data" instruction has 0 for this id field. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 244 | unsigned int id; |
| 245 | |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 246 | // Address (EIP) of this instruction |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 247 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
Nguyen Anh Quynh | f2a649e | 2013-12-03 12:21:01 +0800 | [diff] [blame] | 248 | uint64_t address; |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 249 | |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 250 | // Size of this instruction |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 251 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
Nguyen Anh Quynh | 8f13f3c | 2013-12-04 22:57:04 +0800 | [diff] [blame] | 252 | uint16_t size; |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 253 | // Machine bytes of this instruction, with number of bytes indicated by @size above |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 254 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
pancake | f0e4eed | 2013-12-11 22:14:42 +0100 | [diff] [blame] | 255 | uint8_t bytes[16]; |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 256 | |
| 257 | // Ascii text of instruction mnemonic |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 258 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 259 | char mnemonic[32]; |
Nguyen Anh Quynh | cf89cf6 | 2014-01-06 09:08:35 +0800 | [diff] [blame] | 260 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 261 | // Ascii text of instruction operands |
Nguyen Anh Quynh | 46a5afd | 2013-12-14 11:52:06 +0800 | [diff] [blame] | 262 | // This information is available even when CS_OPT_DETAIL = CS_OPT_OFF |
Nguyen Anh Quynh | 0636f68 | 2014-01-15 17:51:08 +0800 | [diff] [blame] | 263 | char op_str[160]; |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 264 | |
Nguyen Anh Quynh | 4fe224b | 2013-12-24 16:49:36 +0800 | [diff] [blame] | 265 | // Pointer to cs_detail. |
Nguyen Anh Quynh | 801ce2b | 2014-10-12 10:36:57 +0800 | [diff] [blame] | 266 | // NOTE: detail pointer is only valid when both requirements below are met: |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 267 | // (1) CS_OP_DETAIL = CS_OPT_ON |
Nguyen Anh Quynh | 801ce2b | 2014-10-12 10:36:57 +0800 | [diff] [blame] | 268 | // (2) Engine is not in Skipdata mode (CS_OP_SKIPDATA option set to CS_OPT_ON) |
Nguyen Anh Quynh | 2c8b262 | 2014-10-12 20:23:08 +0800 | [diff] [blame] | 269 | // |
| 270 | // NOTE 2: when in Skipdata mode, or when detail mode is OFF, even if this pointer |
| 271 | // is not NULL, its content is still irrelevant. |
Nguyen Anh Quynh | 4fe224b | 2013-12-24 16:49:36 +0800 | [diff] [blame] | 272 | cs_detail *detail; |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 273 | } cs_insn; |
| 274 | |
Nguyen Anh Quynh | bb54603 | 2013-12-05 18:29:51 +0800 | [diff] [blame] | 275 | |
| 276 | // Calculate the offset of a disassembled instruction in its buffer, given its position |
| 277 | // in its array of disassembled insn |
Nguyen Anh Quynh | a236902 | 2013-12-05 20:21:09 +0800 | [diff] [blame] | 278 | // NOTE: this macro works with position (>=1), not index |
| 279 | #define CS_INSN_OFFSET(insns, post) (insns[post - 1].address - insns[0].address) |
Nguyen Anh Quynh | bb54603 | 2013-12-05 18:29:51 +0800 | [diff] [blame] | 280 | |
| 281 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 282 | // All type of errors encountered by Capstone API. |
| 283 | // These are values returned by cs_errno() |
| 284 | typedef enum cs_err { |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 285 | CS_ERR_OK = 0, // No error: everything was fine |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 286 | CS_ERR_MEM, // Out-Of-Memory error: cs_open(), cs_disasm(), cs_disasm_iter() |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 287 | CS_ERR_ARCH, // Unsupported architecture: cs_open() |
| 288 | CS_ERR_HANDLE, // Invalid handle: cs_op_count(), cs_op_index() |
| 289 | CS_ERR_CSH, // Invalid csh argument: cs_close(), cs_errno(), cs_option() |
| 290 | CS_ERR_MODE, // Invalid/unsupported mode: cs_open() |
| 291 | CS_ERR_OPTION, // Invalid/unsupported option: cs_option() |
| 292 | CS_ERR_DETAIL, // Information is unavailable because detail option is OFF |
Nguyen Anh Quynh | c52352d | 2014-01-06 09:06:30 +0800 | [diff] [blame] | 293 | CS_ERR_MEMSETUP, // Dynamic memory management uninitialized (see CS_OPT_MEM) |
Nguyen Anh Quynh | 11ec881 | 2014-04-10 17:20:01 +0800 | [diff] [blame] | 294 | CS_ERR_VERSION, // Unsupported version (bindings) |
| 295 | CS_ERR_DIET, // Access irrelevant data in "diet" engine |
| 296 | CS_ERR_SKIPDATA, // Access irrelevant data for "data" instruction in SKIPDATA mode |
Nguyen Anh Quynh | 6638294 | 2014-08-20 14:02:14 +0800 | [diff] [blame] | 297 | CS_ERR_X86_ATT, // X86 AT&T syntax is unsupported (opt-out at compile time) |
| 298 | CS_ERR_X86_INTEL, // X86 Intel syntax is unsupported (opt-out at compile time) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 299 | } cs_err; |
| 300 | |
Nguyen Anh Quynh | b880678 | 2013-12-22 15:20:07 +0800 | [diff] [blame] | 301 | /* |
Nguyen Anh Quynh | b880678 | 2013-12-22 15:20:07 +0800 | [diff] [blame] | 302 | Return combined API version & major and minor version numbers. |
Nguyen Anh Quynh | 36df4bb | 2013-12-10 13:31:20 +0800 | [diff] [blame] | 303 | |
Nguyen Anh Quynh | b880678 | 2013-12-22 15:20:07 +0800 | [diff] [blame] | 304 | @major: major number of API version |
| 305 | @minor: minor number of API version |
Nguyen Anh Quynh | 36df4bb | 2013-12-10 13:31:20 +0800 | [diff] [blame] | 306 | |
Nguyen Anh Quynh | b90cb99 | 2013-12-28 13:59:09 +0800 | [diff] [blame] | 307 | @return hexical number as (major << 8 | minor), which encodes both |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 308 | major & minor versions. |
| 309 | NOTE: This returned value can be compared with version number made |
Nguyen Anh Quynh | b90cb99 | 2013-12-28 13:59:09 +0800 | [diff] [blame] | 310 | with macro CS_MAKE_VERSION |
Nguyen Anh Quynh | 39a42ed | 2013-12-22 10:40:58 +0800 | [diff] [blame] | 311 | |
| 312 | For example, second API version would return 1 in @major, and 1 in @minor |
| 313 | The return value would be 0x0101 |
Nguyen Anh Quynh | 0877747 | 2013-12-22 14:16:28 +0800 | [diff] [blame] | 314 | |
| 315 | NOTE: if you only care about returned value, but not major and minor values, |
Nguyen Anh Quynh | b90cb99 | 2013-12-28 13:59:09 +0800 | [diff] [blame] | 316 | set both @major & @minor arguments to NULL. |
Nguyen Anh Quynh | 36df4bb | 2013-12-10 13:31:20 +0800 | [diff] [blame] | 317 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 318 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | b90cb99 | 2013-12-28 13:59:09 +0800 | [diff] [blame] | 319 | unsigned int cs_version(int *major, int *minor); |
Nguyen Anh Quynh | 39a42ed | 2013-12-22 10:40:58 +0800 | [diff] [blame] | 320 | |
| 321 | |
| 322 | /* |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 323 | This API can be used to either ask for archs supported by this library, |
Nguyen Anh Quynh | c70adc3 | 2014-02-23 00:03:46 +0800 | [diff] [blame] | 324 | or check to see if the library was compile with 'diet' option (or called |
| 325 | in 'diet' mode). |
Nguyen Anh Quynh | 39a42ed | 2013-12-22 10:40:58 +0800 | [diff] [blame] | 326 | |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 327 | To check if a particular arch is supported by this library, set @query to |
| 328 | arch mode (CS_ARCH_* value). |
| 329 | To verify if this library supports all the archs, use CS_ARCH_ALL. |
Nguyen Anh Quynh | 39a42ed | 2013-12-22 10:40:58 +0800 | [diff] [blame] | 330 | |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 331 | To check if this library is in 'diet' mode, set @query to CS_SUPPORT_DIET. |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 332 | |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 333 | @return True if this library supports the given arch, or in 'diet' mode. |
Nguyen Anh Quynh | 39a42ed | 2013-12-22 10:40:58 +0800 | [diff] [blame] | 334 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 335 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | b2870e4 | 2014-02-22 23:41:16 +0800 | [diff] [blame] | 336 | bool cs_support(int query); |
Nguyen Anh Quynh | 36df4bb | 2013-12-10 13:31:20 +0800 | [diff] [blame] | 337 | |
| 338 | /* |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 339 | Initialize CS handle: this must be done before any usage of CS. |
| 340 | |
| 341 | @arch: architecture type (CS_ARCH_*) |
| 342 | @mode: hardware mode. This is combined of CS_MODE_* |
| 343 | @handle: pointer to handle, which will be updated at return time |
| 344 | |
| 345 | @return CS_ERR_OK on success, or other value on failure (refer to cs_err enum |
| 346 | for detailed error). |
| 347 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 348 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 349 | cs_err cs_open(cs_arch arch, cs_mode mode, csh *handle); |
| 350 | |
| 351 | /* |
| 352 | Close CS handle: MUST do to release the handle when it is not used anymore. |
Nguyen Anh Quynh | b265406 | 2014-01-03 17:08:58 +0800 | [diff] [blame] | 353 | NOTE: this must be only called when there is no longer usage of Capstone, |
| 354 | not even access to cs_insn array. The reason is the this API releases some |
| 355 | cached memory, thus access to any Capstone API after cs_close() might crash |
| 356 | your application. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 357 | |
Nguyen Anh Quynh | c8e0785 | 2014-02-28 09:38:11 +0800 | [diff] [blame] | 358 | In fact,this API invalidate @handle by ZERO out its value (i.e *handle = 0). |
| 359 | |
Nguyen Anh Quynh | 226d7dc | 2014-02-27 22:20:39 +0800 | [diff] [blame] | 360 | @handle: pointer to a handle returned by cs_open() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 361 | |
| 362 | @return CS_ERR_OK on success, or other value on failure (refer to cs_err enum |
| 363 | for detailed error). |
| 364 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 365 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 226d7dc | 2014-02-27 22:20:39 +0800 | [diff] [blame] | 366 | cs_err cs_close(csh *handle); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 367 | |
| 368 | /* |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 369 | Set option for disassembling engine at runtime |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 370 | |
| 371 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | b8ce68e | 2013-12-03 23:45:08 +0800 | [diff] [blame] | 372 | @type: type of option to be set |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 373 | @value: option value corresponding with @type |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 374 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 375 | @return: CS_ERR_OK on success, or other value on failure. |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 376 | Refer to cs_err enum for detailed error. |
Nguyen Anh Quynh | a60ed8b | 2014-01-05 23:52:30 +0800 | [diff] [blame] | 377 | |
| 378 | NOTE: in the case of CS_OPT_MEM, handle's value can be anything, |
| 379 | so that cs_option(handle, CS_OPT_MEM, value) can (i.e must) be called |
| 380 | even before cs_open() |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 381 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 382 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | da8adad | 2013-12-04 09:44:07 +0800 | [diff] [blame] | 383 | cs_err cs_option(csh handle, cs_opt_type type, size_t value); |
Nguyen Anh Quynh | 01aba00 | 2013-12-03 21:00:09 +0800 | [diff] [blame] | 384 | |
| 385 | /* |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 386 | Report the last error number when some API function fail. |
| 387 | Like glibc's errno, cs_errno might not retain its old value once accessed. |
| 388 | |
| 389 | @handle: handle returned by cs_open() |
| 390 | |
| 391 | @return: error code of cs_err enum type (CS_ERR_*, see above) |
| 392 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 393 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 394 | cs_err cs_errno(csh handle); |
| 395 | |
Nguyen Anh Quynh | 34f9638 | 2014-01-03 22:49:07 +0800 | [diff] [blame] | 396 | |
| 397 | /* |
| 398 | Return a string describing given error code. |
| 399 | |
| 400 | @code: error code (see CS_ERR_* above) |
| 401 | |
| 402 | @return: returns a pointer to a string that describes the error code |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 403 | passed in the argument @code |
Nguyen Anh Quynh | 34f9638 | 2014-01-03 22:49:07 +0800 | [diff] [blame] | 404 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 405 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 34f9638 | 2014-01-03 22:49:07 +0800 | [diff] [blame] | 406 | const char *cs_strerror(cs_err code); |
| 407 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 408 | /* |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 409 | Disassemble binary code, given the code buffer, size, address and number |
| 410 | of instructions to be decoded. |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 411 | This API dynamically allocate memory to contain disassembled instruction. |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 412 | Resulted instructions will be put into @*insn |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 413 | |
| 414 | NOTE 1: this API will automatically determine memory needed to contain |
| 415 | output disassembled instructions in @insn. |
Nguyen Anh Quynh | 024e55e | 2014-10-20 23:32:06 +0800 | [diff] [blame] | 416 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 417 | NOTE 2: caller must free the allocated memory itself to avoid memory leaking. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 418 | |
Nguyen Anh Quynh | 024e55e | 2014-10-20 23:32:06 +0800 | [diff] [blame] | 419 | NOTE 3: for system with scarce memory to be dynamically allocated such as |
| 420 | OS kernel or firmware, the API cs_disasm_iter() might be a better choice than |
| 421 | cs_disasm(). The reason is that with cs_disasm(), based on limited available |
| 422 | memory, we have to calculate in advance how many instructions to be disassembled, |
| 423 | which complicates things. This is especially troublesome for the case @count=0, |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 424 | when cs_disasm() runs uncontrollably (until either end of input buffer, or |
Nguyen Anh Quynh | 024e55e | 2014-10-20 23:32:06 +0800 | [diff] [blame] | 425 | when it encounters an invalid instruction). |
| 426 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 427 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 428 | @code: buffer containing raw binary code to be disassembled. |
| 429 | @code_size: size of the above code buffer. |
| 430 | @address: address of the first instruction in given raw code buffer. |
| 431 | @insn: array of instructions filled in by this API. |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 432 | NOTE: @insn will be allocated by this function, and should be freed |
Nguyen Anh Quynh | 79976c1 | 2013-12-04 23:03:13 +0800 | [diff] [blame] | 433 | with cs_free() API. |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 434 | @count: number of instructions to be disassembled, or 0 to get all of them |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 435 | |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 436 | @return: the number of successfully disassembled instructions, |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 437 | or 0 if this function failed to disassemble the given code |
Nguyen Anh Quynh | 029df20 | 2013-12-03 11:36:54 +0800 | [diff] [blame] | 438 | |
| 439 | On failure, call cs_errno() for error code. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 440 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 441 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 0beb0d4 | 2014-08-27 22:55:29 +0800 | [diff] [blame] | 442 | size_t cs_disasm(csh handle, |
pancake | f0e4eed | 2013-12-11 22:14:42 +0100 | [diff] [blame] | 443 | const uint8_t *code, size_t code_size, |
Nguyen Anh Quynh | 612b5d2 | 2013-12-03 12:23:09 +0800 | [diff] [blame] | 444 | uint64_t address, |
Nguyen Anh Quynh | b42a657 | 2013-11-29 17:40:07 +0800 | [diff] [blame] | 445 | size_t count, |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 446 | cs_insn **insn); |
| 447 | |
Nguyen Anh Quynh | aa58f7f | 2014-09-25 16:56:31 +0800 | [diff] [blame] | 448 | /* |
| 449 | Deprecated function - to be retired in the next version! |
Nguyen Anh Quynh | 0beb0d4 | 2014-08-27 22:55:29 +0800 | [diff] [blame] | 450 | Use cs_disasm() instead of cs_disasm_ex() |
| 451 | */ |
| 452 | CAPSTONE_EXPORT |
| 453 | CAPSTONE_DEPRECATED |
| 454 | size_t cs_disasm_ex(csh handle, |
| 455 | const uint8_t *code, size_t code_size, |
| 456 | uint64_t address, |
| 457 | size_t count, |
| 458 | cs_insn **insn); |
Nguyen Anh Quynh | aa58f7f | 2014-09-25 16:56:31 +0800 | [diff] [blame] | 459 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 460 | /* |
Nguyen Anh Quynh | 542a540 | 2014-10-11 13:12:15 +0800 | [diff] [blame] | 461 | Free memory allocated by cs_malloc() or cs_disasm() (argument @insn) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 462 | |
Nguyen Anh Quynh | 542a540 | 2014-10-11 13:12:15 +0800 | [diff] [blame] | 463 | @insn: pointer returned by @insn argument in cs_disasm() or cs_malloc() |
| 464 | @count: number of cs_insn structures returned by cs_disasm(), or 1 |
| 465 | to free memory allocated by cs_malloc(). |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 466 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 467 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 4fe224b | 2013-12-24 16:49:36 +0800 | [diff] [blame] | 468 | void cs_free(cs_insn *insn, size_t count); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 469 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 470 | |
| 471 | /* |
| 472 | Allocate memory for 1 instruction to be used by cs_disasm_iter(). |
| 473 | |
| 474 | @handle: handle returned by cs_open() |
| 475 | |
Nguyen Anh Quynh | 5cb3d64 | 2014-10-11 01:32:39 +0800 | [diff] [blame] | 476 | NOTE: when no longer in use, you can reclaim the memory allocated for |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 477 | this instruction with cs_free(insn, 1) |
| 478 | */ |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 479 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 480 | cs_insn *cs_malloc(csh handle); |
| 481 | |
| 482 | /* |
Nguyen Anh Quynh | 5cb3d64 | 2014-10-11 01:32:39 +0800 | [diff] [blame] | 483 | Fast API to disassemble binary code, given the code buffer, size, address |
| 484 | and number of instructions to be decoded. |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 485 | This API put the resulted instruction into a given cache in @insn. |
Nguyen Anh Quynh | ff2939a | 2014-10-12 10:43:02 +0800 | [diff] [blame] | 486 | See tests/test_iter.c for sample code demonstrating this API. |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 487 | |
| 488 | NOTE 1: this API will update @code, @size & @address to point to the next |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 489 | instruction in the input buffer. Therefore, it is convenient to use |
Nguyen Anh Quynh | 5cb3d64 | 2014-10-11 01:32:39 +0800 | [diff] [blame] | 490 | cs_disasm_iter() inside a loop to quickly iterate all the instructions. |
| 491 | While decoding one instruction at a time can also be achieved with |
| 492 | cs_disasm(count=1), some benchmarks shown that cs_disasm_iter() can be 30% |
| 493 | faster on random input. |
| 494 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 495 | NOTE 2: the cache in @insn can be created with cs_malloc() API. |
| 496 | |
Nguyen Anh Quynh | 024e55e | 2014-10-20 23:32:06 +0800 | [diff] [blame] | 497 | NOTE 3: for system with scarce memory to be dynamically allocated such as |
| 498 | OS kernel or firmware, this API is recommended over cs_disasm(), which |
| 499 | allocates memory based on the number of instructions to be disassembled. |
| 500 | The reason is that with cs_disasm(), based on limited available memory, |
| 501 | we have to calculate in advance how many instructions to be disassembled, |
| 502 | which complicates things. This is especially troublesome for the case |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 503 | @count=0, when cs_disasm() runs uncontrollably (until either end of input |
Nguyen Anh Quynh | 024e55e | 2014-10-20 23:32:06 +0800 | [diff] [blame] | 504 | buffer, or when it encounters an invalid instruction). |
| 505 | |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 506 | @handle: handle returned by cs_open() |
| 507 | @code: buffer containing raw binary code to be disassembled |
| 508 | @code_size: size of above code |
| 509 | @address: address of the first insn in given raw code buffer |
| 510 | @insn: pointer to instruction to be filled in by this API. |
| 511 | |
| 512 | @return: true if this API successfully decode 1 instruction, |
| 513 | or false otherwise. |
| 514 | |
| 515 | On failure, call cs_errno() for error code. |
| 516 | */ |
| 517 | CAPSTONE_EXPORT |
| 518 | bool cs_disasm_iter(csh handle, |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 519 | const uint8_t **code, size_t *size, |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 520 | uint64_t *address, cs_insn *insn); |
hlide | 993f362 | 2014-10-05 18:14:40 +0200 | [diff] [blame] | 521 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 522 | /* |
Taras Tsugrii | 37590df | 2015-05-05 13:57:15 -0700 | [diff] [blame] | 523 | Return friendly name of register in a string. |
Nguyen Anh Quynh | c70adc3 | 2014-02-23 00:03:46 +0800 | [diff] [blame] | 524 | Find the instruction id from header file of corresponding architecture (arm.h for ARM, |
| 525 | x86.h for X86, ...) |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 526 | |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 527 | WARN: when in 'diet' mode, this API is irrelevant because engine does not |
Nguyen Anh Quynh | fc83a43 | 2014-02-22 23:26:27 +0800 | [diff] [blame] | 528 | store register name. |
| 529 | |
Nguyen Anh Quynh | 3640f3c | 2013-12-01 00:26:27 +0800 | [diff] [blame] | 530 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | 650f96c | 2014-07-08 08:59:27 +0800 | [diff] [blame] | 531 | @reg_id: register id |
Nguyen Anh Quynh | 0a2eca7 | 2014-10-11 00:36:16 +0800 | [diff] [blame] | 532 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 533 | @return: string name of the register, or NULL if @reg_id is invalid. |
| 534 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 535 | CAPSTONE_EXPORT |
pancake | f0e4eed | 2013-12-11 22:14:42 +0100 | [diff] [blame] | 536 | const char *cs_reg_name(csh handle, unsigned int reg_id); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 537 | |
| 538 | /* |
Nguyen Anh Quynh | 650f96c | 2014-07-08 08:59:27 +0800 | [diff] [blame] | 539 | Return friendly name of an instruction in a string. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 540 | Find the instruction id from header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 541 | |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 542 | WARN: when in 'diet' mode, this API is irrelevant because the engine does not |
Nguyen Anh Quynh | fc83a43 | 2014-02-22 23:26:27 +0800 | [diff] [blame] | 543 | store instruction name. |
| 544 | |
Nguyen Anh Quynh | 3640f3c | 2013-12-01 00:26:27 +0800 | [diff] [blame] | 545 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | 650f96c | 2014-07-08 08:59:27 +0800 | [diff] [blame] | 546 | @insn_id: instruction id |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 547 | |
| 548 | @return: string name of the instruction, or NULL if @insn_id is invalid. |
| 549 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 550 | CAPSTONE_EXPORT |
pancake | f0e4eed | 2013-12-11 22:14:42 +0100 | [diff] [blame] | 551 | const char *cs_insn_name(csh handle, unsigned int insn_id); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 552 | |
| 553 | /* |
Nguyen Anh Quynh | 650f96c | 2014-07-08 08:59:27 +0800 | [diff] [blame] | 554 | Return friendly name of a group id (that an instruction can belong to) |
| 555 | Find the group id from header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 556 | |
| 557 | WARN: when in 'diet' mode, this API is irrelevant because the engine does not |
| 558 | store group name. |
| 559 | |
| 560 | @handle: handle returned by cs_open() |
| 561 | @group_id: group id |
| 562 | |
| 563 | @return: string name of the group, or NULL if @group_id is invalid. |
| 564 | */ |
| 565 | CAPSTONE_EXPORT |
Nguyen Anh Quynh | aa58f7f | 2014-09-25 16:56:31 +0800 | [diff] [blame] | 566 | const char *cs_group_name(csh handle, unsigned int group_id); |
Nguyen Anh Quynh | 650f96c | 2014-07-08 08:59:27 +0800 | [diff] [blame] | 567 | |
| 568 | /* |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 569 | Check if a disassembled instruction belong to a particular group. |
| 570 | Find the group id from header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 571 | Internally, this simply verifies if @group_id matches any member of insn->groups array. |
| 572 | |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 573 | NOTE: this API is only valid when detail option is ON (which is OFF by default). |
| 574 | |
| 575 | WARN: when in 'diet' mode, this API is irrelevant because the engine does not |
Nguyen Anh Quynh | fc83a43 | 2014-02-22 23:26:27 +0800 | [diff] [blame] | 576 | update @groups array. |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 577 | |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 578 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 579 | @insn: disassembled instruction structure received from cs_disasm() or cs_disasm_iter() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 580 | @group_id: group that you want to check if this instruction belong to. |
| 581 | |
| 582 | @return: true if this instruction indeed belongs to aboved group, or false otherwise. |
| 583 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 584 | CAPSTONE_EXPORT |
obs | 876b6b6 | 2014-08-21 00:57:04 +0200 | [diff] [blame] | 585 | bool cs_insn_group(csh handle, const cs_insn *insn, unsigned int group_id); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 586 | |
| 587 | /* |
| 588 | Check if a disassembled instruction IMPLICITLY used a particular register. |
| 589 | Find the register id from header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 590 | Internally, this simply verifies if @reg_id matches any member of insn->regs_read array. |
| 591 | |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 592 | NOTE: this API is only valid when detail option is ON (which is OFF by default) |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 593 | |
| 594 | WARN: when in 'diet' mode, this API is irrelevant because the engine does not |
Nguyen Anh Quynh | fc83a43 | 2014-02-22 23:26:27 +0800 | [diff] [blame] | 595 | update @regs_read array. |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 596 | |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 597 | @insn: disassembled instruction structure received from cs_disasm() or cs_disasm_iter() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 598 | @reg_id: register that you want to check if this instruction used it. |
| 599 | |
| 600 | @return: true if this instruction indeed implicitly used aboved register, or false otherwise. |
| 601 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 602 | CAPSTONE_EXPORT |
obs | 876b6b6 | 2014-08-21 00:57:04 +0200 | [diff] [blame] | 603 | bool cs_reg_read(csh handle, const cs_insn *insn, unsigned int reg_id); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 604 | |
| 605 | /* |
| 606 | Check if a disassembled instruction IMPLICITLY modified a particular register. |
| 607 | Find the register id from header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 608 | Internally, this simply verifies if @reg_id matches any member of insn->regs_write array. |
| 609 | |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 610 | NOTE: this API is only valid when detail option is ON (which is OFF by default) |
Nguyen Anh Quynh | 544e0ff | 2014-02-23 20:24:47 +0800 | [diff] [blame] | 611 | |
| 612 | WARN: when in 'diet' mode, this API is irrelevant because the engine does not |
Nguyen Anh Quynh | fc83a43 | 2014-02-22 23:26:27 +0800 | [diff] [blame] | 613 | update @regs_write array. |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 614 | |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 615 | @insn: disassembled instruction structure received from cs_disasm() or cs_disasm_iter() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 616 | @reg_id: register that you want to check if this instruction modified it. |
| 617 | |
| 618 | @return: true if this instruction indeed implicitly modified aboved register, or false otherwise. |
| 619 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 620 | CAPSTONE_EXPORT |
obs | 876b6b6 | 2014-08-21 00:57:04 +0200 | [diff] [blame] | 621 | bool cs_reg_write(csh handle, const cs_insn *insn, unsigned int reg_id); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 622 | |
| 623 | /* |
| 624 | Count the number of operands of a given type. |
| 625 | Find the operand type in header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 626 | |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 627 | NOTE: this API is only valid when detail option is ON (which is OFF by default) |
| 628 | |
Nguyen Anh Quynh | 3640f3c | 2013-12-01 00:26:27 +0800 | [diff] [blame] | 629 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 630 | @insn: disassembled instruction structure received from cs_disasm() or cs_disasm_iter() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 631 | @op_type: Operand type to be found. |
| 632 | |
| 633 | @return: number of operands of given type @op_type in instruction @insn, |
| 634 | or -1 on failure. |
| 635 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 636 | CAPSTONE_EXPORT |
obs | 876b6b6 | 2014-08-21 00:57:04 +0200 | [diff] [blame] | 637 | int cs_op_count(csh handle, const cs_insn *insn, unsigned int op_type); |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 638 | |
| 639 | /* |
Nguyen Anh Quynh | 4c0ed0b | 2014-06-03 15:06:20 +0700 | [diff] [blame] | 640 | Retrieve the position of operand of given type in <arch>.operands[] array. |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 641 | Later, the operand can be accessed using the returned position. |
| 642 | Find the operand type in header file of corresponding architecture (arm.h for ARM, x86.h for X86, ...) |
| 643 | |
Nguyen Anh Quynh | 2f05ab2 | 2014-01-15 11:07:28 +0800 | [diff] [blame] | 644 | NOTE: this API is only valid when detail option is ON (which is OFF by default) |
| 645 | |
Nguyen Anh Quynh | 3640f3c | 2013-12-01 00:26:27 +0800 | [diff] [blame] | 646 | @handle: handle returned by cs_open() |
Nguyen Anh Quynh | c41da15 | 2014-10-15 16:31:35 +0800 | [diff] [blame] | 647 | @insn: disassembled instruction structure received from cs_disasm() or cs_disasm_iter() |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 648 | @op_type: Operand type to be found. |
| 649 | @position: position of the operand to be found. This must be in the range |
| 650 | [1, cs_op_count(handle, insn, op_type)] |
| 651 | |
Nguyen Anh Quynh | 4c0ed0b | 2014-06-03 15:06:20 +0700 | [diff] [blame] | 652 | @return: index of operand of given type @op_type in <arch>.operands[] array |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 653 | in instruction @insn, or -1 on failure. |
| 654 | */ |
Nguyen Anh Quynh | 07c3693 | 2014-06-03 18:33:15 +0800 | [diff] [blame] | 655 | CAPSTONE_EXPORT |
obs | 876b6b6 | 2014-08-21 00:57:04 +0200 | [diff] [blame] | 656 | int cs_op_index(csh handle, const cs_insn *insn, unsigned int op_type, |
Nguyen Anh Quynh | 26ee41a | 2013-11-27 12:11:31 +0800 | [diff] [blame] | 657 | unsigned int position); |
| 658 | |
| 659 | #ifdef __cplusplus |
| 660 | } |
| 661 | #endif |
| 662 | |
| 663 | #endif |