diff options
Diffstat (limited to 'docs/Capstone-Engine-Documentation/Capstone-Engine Documentation.md')
-rw-r--r-- | docs/Capstone-Engine-Documentation/Capstone-Engine Documentation.md | 3406 |
1 files changed, 3406 insertions, 0 deletions
diff --git a/docs/Capstone-Engine-Documentation/Capstone-Engine Documentation.md b/docs/Capstone-Engine-Documentation/Capstone-Engine Documentation.md new file mode 100644 index 00000000..b1b1b80a --- /dev/null +++ b/docs/Capstone-Engine-Documentation/Capstone-Engine Documentation.md @@ -0,0 +1,3406 @@ +# Capstone-Engine API Documentation + +| Version | 4.0.2 | +| ------- | ----- | + +**Official API document by [kabeor](https://github.com/kabeor)** + +[Capstone Engine](https://github.com/capstone-engine/capstone)是一个支持多种硬件架构的二进制反汇编引擎。 + + +## 0x0 开发准备 + + Capstone官网: http://www.capstone-engine.org + +### 自行编译lib和dll方法 + + 源码: https://github.com/capstone-engine/capstone.git + + git clone下来 + 文件结构如下: + +``` + . <- 主要引擎core engine + README + 编译文档COMPILE.TXT 等 +├── arch <- 各语言反编译支持的代码实现 +│ ├── AArch64 <- ARM64 (aka ARMv8) 引擎 +│ ├── ARM <- ARM 引擎 +│ ├── EVM <- Ethereum 引擎 +│ ├── M680X <- M680X 引擎 +│ ├── M68K <- M68K 引擎 +| ├── MOS65XX <- MOS65XX 引擎 +│ ├── Mips <- Mips 引擎 +│ ├── PowerPC <- PowerPC 引擎 +│ ├── Sparc <- Sparc 引擎 +│ ├── SystemZ <- SystemZ 引擎 +│ ├── TMS320C64x <- TMS320C64x 引擎 +│ ├── X86 <- X86 引擎 +│ └── XCore <- XCore 引擎 +├── bindings <- 绑定 +│ ├── java <- Java 绑定 + 测试代码 +│ ├── ocaml <- Ocaml 绑定 + 测试代码 +│ ├── powershell <- powershell 绑定 + 测试代码 +│ ├── python <- python 绑定 + 测试代码 +│ └── vb6 <- vb6 绑定 + 测试代码 +├── contrib <- 社区代码 +├── cstool <- Cstool 检测工具源码 +├── docs <- 文档,主要是capstone的实现思路 +├── include <- C头文件 +├── msvc <- Microsoft Visual Studio 支持(Windows) +├── packages <- Linux/OSX/BSD包 +├── suite <- 项目开发所需工具 +├── tests <- C语言测试用例 +├── windows <- Windows 支持(Windows内核驱动编译) +├── windowsce <- Windows CE 支持 +└── xcode <- Xcode 支持 (MacOSX 编译) +``` + +下面演示Windows10使用Visual Studio2019编译 + +复制msvc文件夹到一个比较清爽的位置,内部结构如下: + +![](API_Doc_Pic/1.jpg) + +VS打开capstone.sln项目文件,解决方案自动载入这些 + +![](API_Doc_Pic/2.jpg) + +可以看到支持的所有语言都在这里了,如果都需要的话,直接编译就好了,只需要其中几种,则右键解决方案->属性->配置属性 如下 + +![](API_Doc_Pic/3.jpg) + +生成选项中勾选你需要的支持项即可 +编译后会在当前文件夹Debug目录下生成capstone.lib静态编译库和capstone.dll动态库这样就可以开始使用Capstone进行开发了 + +如果不想自己编译,官方也提供了官方编译版本 + +Win32: https://github.com/capstone-engine/capstone/releases/download/4.0.2/capstone-4.0.2-win32.zip + +Win64: https://github.com/capstone-engine/capstone/releases/download/4.0.2/capstone-4.0.2-win64.zip + +选x32或x64将影响后面开发的位数 + + + +### 引擎调用测试 + +新建一个VS项目,将capstone\include\capstone中的头文件以及编译好的lib和dll文件全部拷贝到新建项目的主目录下 + +![](API_Doc_Pic/4.jpg) + +在VS解决方案中,头文件添加现有项capstone.h,资源文件中添加capstone.lib,重新生成解决方案 + +![](API_Doc_Pic/5.jpg) + +那么现在来测试一下我们自己的capstone引擎吧 + +主文件写入如下代码 + +<details><summary> Code </summary> + +```c++ +#include <iostream> +#include <stdio.h> +#include <cinttypes> +#include "capstone.h" +using namespace std; + +#define CODE "\x55\x48\x8b\x05\xb8\x13\x00\x00" + +int main(void) +{ + csh handle; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + + count = cs_disasm(handle, (unsigned char*)CODE, sizeof(CODE) - 1, 0x1000, 0, &insn); + if (count) { + size_t j; + + for (j = 0; j < count; j++) { + printf("0x%""Ix"":\t%s\t\t%s\n", insn[j].address, insn[j].mnemonic, insn[j].op_str); + } + + cs_free(insn, count); + } + else + printf("ERROR: Failed to disassemble given code!\n"); + + cs_close(&handle); + + return 0; +} +``` + +</details> + +运行结果 +![](API_Doc_Pic/6.jpg) + + + +## 0x1 数据类型 + +### csh + +用于生成调用capstone API的句柄 + +```cpp +size_t csh +``` + +> 用法: `csh handle;` + + +### cs_arch + +架构选择 + +<details><summary> Code </summary> + +```cpp + enum cs_arch { + CS_ARCH_ARM = 0, ///< ARM 架构 (包括 Thumb, Thumb-2) + CS_ARCH_ARM64, ///< ARM-64, 也叫 AArch64 + CS_ARCH_MIPS, ///< Mips 架构 + CS_ARCH_X86, ///< X86 架构 (包括 x86 & x86-64) + CS_ARCH_PPC, ///< PowerPC 架构 + CS_ARCH_SPARC, ///< Sparc 架构 + CS_ARCH_SYSZ, ///< SystemZ 架构 + CS_ARCH_XCORE, ///< XCore 架构 + CS_ARCH_M68K, ///< 68K 架构 + CS_ARCH_TMS320C64X, ///< TMS320C64x 架构 + CS_ARCH_M680X, ///< 680X 架构 + CS_ARCH_EVM, ///< Ethereum 架构 + CS_ARCH_MAX, + CS_ARCH_ALL = 0xFFFF, // All 架构 - for cs_support() +} cs_arch; +``` + +</details> + +> 用法:API中cs_arch参数填入枚举内容,如API中cs_open(cs_arch arch, cs_mode mode, csh *handle);第一个参数填CS_ARCH_X86则支持X86 架构 + + +### cs_mode + +模式选择 + +<details><summary> Code </summary> + +```cpp +enum cs_mode { + CS_MODE_LITTLE_ENDIAN = 0, ///< little-endian 模式 (default 模式) + CS_MODE_ARM = 0, ///< 32-bit ARM + CS_MODE_16 = 1 << 1, ///< 16-bit 模式 (X86) + CS_MODE_32 = 1 << 2, ///< 32-bit 模式 (X86) + CS_MODE_64 = 1 << 3, ///< 64-bit 模式 (X86, PPC) + CS_MODE_THUMB = 1 << 4, ///< ARM's Thumb 模式, 包括 Thumb-2 + CS_MODE_MCLASS = 1 << 5, ///< ARM's Cortex-M 系列 + CS_MODE_V8 = 1 << 6, ///< ARMv8 A32解码方式 + CS_MODE_MICRO = 1 << 4, ///< MicroMips 模式 (MIPS) + CS_MODE_MIPS3 = 1 << 5, ///< Mips III ISA + CS_MODE_MIPS32R6 = 1 << 6, ///< Mips32r6 ISA + CS_MODE_MIPS2 = 1 << 7, ///< Mips II ISA + CS_MODE_V9 = 1 << 4, ///< SparcV9 模式 (Sparc) + CS_MODE_QPX = 1 << 4, ///< Quad Processing eXtensions 模式 (PPC) + CS_MODE_SPE = 1 << 5, ///< Signal Processing Engine 模式 (PPC) + CS_MODE_BOOKE = 1 << 6, ///< Book-E 模式 (PPC) + CS_MODE_M68K_000 = 1 << 1, ///< M68K 68000 模式 + CS_MODE_M68K_010 = 1 << 2, ///< M68K 68010 模式 + CS_MODE_M68K_020 = 1 << 3, ///< M68K 68020 模式 + CS_MODE_M68K_030 = 1 << 4, ///< M68K 68030 模式 + CS_MODE_M68K_040 = 1 << 5, ///< M68K 68040 模式 + CS_MODE_M68K_060 = 1 << 6, ///< M68K 68060 模式 + CS_MODE_BIG_ENDIAN = 1 << 31, ///< big-endian 模式 + CS_MODE_MIPS32 = CS_MODE_32, ///< Mips32 ISA (Mips) + CS_MODE_MIPS64 = CS_MODE_64, ///< Mips64 ISA (Mips) + CS_MODE_M680X_6301 = 1 << 1, ///< M680X Hitachi 6301,6303 模式 + CS_MODE_M680X_6309 = 1 << 2, ///< M680X Hitachi 6309 模式 + CS_MODE_M680X_6800 = 1 << 3, ///< M680X Motorola 6800,6802 模式 + CS_MODE_M680X_6801 = 1 << 4, ///< M680X Motorola 6801,6803 模式 + CS_MODE_M680X_6805 = 1 << 5, ///< M680X Motorola/Freescale 6805 模式 + CS_MODE_M680X_6808 = 1 << 6, ///< M680X Motorola/Freescale/NXP 68HC08 模式 + CS_MODE_M680X_6809 = 1 << 7, ///< M680X Motorola 6809 模式 + CS_MODE_M680X_6811 = 1 << 8, ///< M680X Motorola/Freescale/NXP 68HC11 模式 + CS_MODE_M680X_CPU12 = 1 << 9, ///< M680X Motorola/Freescale/NXP CPU12 + ///< 用于 M68HC12/HCS12 + CS_MODE_M680X_HCS08 = 1 << 10, ///< M680X Freescale/NXP HCS08 模式 + CS_MODE_BPF_CLASSIC = 0, ///< Classic BPF 模式 (默认) + CS_MODE_BPF_EXTENDED = 1 << 0, ///< Extended BPF 模式 + CS_MODE_RISCV32 = 1 << 0, ///< RISCV RV32G + CS_MODE_RISCV64 = 1 << 1, ///< RISCV RV64G + CS_MODE_RISCVC = 1 << 2, ///< RISCV 压缩指令模式 + CS_MODE_MOS65XX_6502 = 1 << 1, ///< MOS65XXX MOS 6502 + CS_MODE_MOS65XX_65C02 = 1 << 2, ///< MOS65XXX WDC 65c02 + CS_MODE_MOS65XX_W65C02 = 1 << 3, ///< MOS65XXX WDC W65c02 + CS_MODE_MOS65XX_65816 = 1 << 4, ///< MOS65XXX WDC 65816, 8-bit m/x + CS_MODE_MOS65XX_65816_LONG_M = (1 << 5), ///< MOS65XXX WDC 65816, 16-bit m, 8-bit x + CS_MODE_MOS65XX_65816_LONG_X = (1 << 6), ///< MOS65XXX WDC 65816, 8-bit m, 16-bit x + CS_MODE_MOS65XX_65816_LONG_MX = CS_MODE_MOS65XX_65816_LONG_M | CS_MODE_MOS65XX_65816_LONG_X, +} cs_mode; +``` + +</details> + +> 用法:API中cs_mode参数填入枚举内容,如API中cs_open(cs_arch arch, cs_mode mode, csh *handle);第二个参数填CS_MODE_64则支持X64模式 + + +### cs_opt_mem + +内存操作 + +<details><summary> Code </summary> + +```cpp +struct cs_opt_mem { + cs_malloc_t malloc; + cs_calloc_t calloc; + cs_realloc_t realloc; + cs_free_t free; + cs_vsnprintf_t vsnprintf; +} cs_opt_mem; +``` + +</details> + +> 用法:可使用用户自定义的malloc/calloc/realloc/free/vsnprintf()函数,默认使用系统自带malloc(), calloc(), realloc(), free() & vsnprintf() + + +### cs_opt_mnem + +自定义助记符 + +<details><summary> Code </summary> + +```cpp +struct cs_opt_mnem { + /// 需要自定义的指令ID + unsigned int id; + /// 自定义的助记符 + const char *mnemonic; +} cs_opt_mnem; +``` + +</details> + + +### cs_opt_type + +反编译的运行时选项 + +<details><summary> Code </summary> + +```cpp +enum cs_opt_type { + CS_OPT_INVALID = 0, ///< 无特殊要求 + CS_OPT_SYNTAX, ///< 汇编输出语法 + CS_OPT_DETAIL, ///< 将指令结构分解为多个细节 + CS_OPT_MODE, ///< 运行时改变引擎模式 + CS_OPT_MEM, ///< 用户定义的动态内存相关函数 + CS_OPT_SKIPDATA, ///< 在反汇编时跳过数据。然后引擎将处于SKIPDATA模式 + CS_OPT_SKIPDATA_SETUP, ///< 为SKIPDATA选项设置用户定义函数 + CS_OPT_MNEMONIC, ///<自定义指令助记符 + CS_OPT_UNSIGNED, ///< 以无符号形式打印立即操作数 +} cs_opt_type; +``` + +</details> + +> 用法:API cs_option(csh handle, cs_opt_type type, size_t value);中第二个参数 + + +### cs_opt_value + +运行时选项值(与cs_opt_type关联) + +<details><summary> Code </summary> + +```cpp +enum cs_opt_value { + CS_OPT_OFF = 0, ///< 关闭一个选项 - 默认为CS_OPT_DETAIL, CS_OPT_SKIPDATA, CS_OPT_UNSIGNED. + CS_OPT_ON = 3, ///< 打开一个选项 (CS_OPT_DETAIL, CS_OPT_SKIPDATA). + CS_OPT_SYNTAX_DEFAULT = 0, ///< 默认asm语法 (CS_OPT_SYNTAX). + CS_OPT_SYNTAX_INTEL, ///< X86 Intel asm语法 - 默认开启 X86 (CS_OPT_SYNTAX). + CS_OPT_SYNTAX_ATT, ///< X86 ATT 汇编语法 (CS_OPT_SYNTAX). + CS_OPT_SYNTAX_NOREGNAME, ///< 只打印寄存器名和编号 (CS_OPT_SYNTAX) + CS_OPT_SYNTAX_MASM, ///< X86 Intel Masm 语法 (CS_OPT_SYNTAX). + CS_OPT_SYNTAX_MOTOROLA, ///< MOS65XX 用 $ 作为hex头 +} cs_opt_value; +``` + +</details> + +> 用法:API cs_option(csh handle, cs_opt_type type, size_t value);中第三个参数 + + +### cs_op_type + +通用指令操作数类型,在所有架构中保持一致 + +<details><summary> Code </summary> + +```cpp +enum cs_op_type { + CS_OP_INVALID = 0, ///< 未初始化/无效的操作数 + CS_OP_REG, ///< 寄存器操作数 + CS_OP_IMM, ///< 立即操作数 + CS_OP_MEM, ///< 内存操作数 + CS_OP_FP, ///< 浮点数 +} cs_op_type; +``` + +</details> + +> 目前开放的API中未调用 + + +### cs_ac_type + +通用指令操作数访问类型,在所有架构中保持一致 +可以组合访问类型,例如:CS_AC_READ | CS_AC_WRITE + +<details><summary> Code </summary> + +```cpp +enum cs_ac_type { + CS_AC_INVALID = 0, ///< 未初始化/无效的访问类型 + CS_AC_READ = 1 << 0, ///< 操作数从内存或寄存器中读取 + CS_AC_WRITE = 1 << 1, ///< 操作数从内存或寄存器中写入 +} cs_ac_type; +``` + +</details> + +> 目前开放的API中未调用 + + +### cs_group_type + +公共指令组,在所有架构中保持一致 + +<details><summary> Code </summary> + +```cpp +cs_group_type { + CS_GRP_INVALID = 0, ///< 未初始化/无效指令组 + CS_GRP_JUMP, ///< 所有跳转指令(条件跳转+直接跳转+间接跳转) + CS_GRP_CALL, ///< 所有调用指令 + CS_GRP_RET, ///< 所有返回指令 + CS_GRP_INT, ///< 所有中断指令(int+syscall) + CS_GRP_IRET, ///< 所有中断返回指令 + CS_GRP_PRIVILEGE, ///< 所有特权指令 + CS_GRP_BRANCH_RELATIVE, ///< 所有相关分支指令 +} cs_group_type; +``` + +</details> + +> 目前开放的API中未调用 + + +### cs_opt_skipdata + +用户自定义设置SKIPDATA选项 + +<details><summary> Code </summary> + +```cpp +struct cs_opt_skipdata { + /// Capstone认为要跳过的数据是特殊的“指令” + /// 用户可以在这里指定该指令的“助记符”字符串 + /// 默认情况下(@mnemonic为NULL), Capstone使用“.byte” + const char *mnemonic; + + /// 用户定义的回调函数,当Capstone命中数据时调用 + /// 如果这个回调返回的值是正数(>0),Capstone将跳过这个字节数并继续。如果回调返回0,Capstone将停止反汇编并立即从cs_disasm()返回 + /// 注意:如果这个回调指针为空,Capstone会根据架构跳过一些字节,如下所示: + /// Arm: 2 bytes (Thumb mode) or 4 bytes. + /// Arm64: 4 bytes. + /// Mips: 4 bytes. + /// M680x: 1 byte. + /// PowerPC: 4 bytes. + /// Sparc: 4 bytes. + /// SystemZ: 2 bytes. + /// X86: 1 bytes. + /// XCore: 2 bytes. + /// EVM: 1 bytes. + /// RISCV: 4 bytes. + /// WASM: 1 bytes. + /// MOS65XX: 1 bytes. + /// BPF: 8 bytes. + cs_skipdata_cb_t callback; // 默认值为 NULL + + /// 用户自定义数据将被传递给@callback函数指针 + void *user_data; +} cs_opt_skipdata; +``` + +</details> + +> 目前开放的API中未调用 + + +### cs_detail + +注意:只有当CS_OPT_DETAIL = CS_OPT_ON时,cs_detail中的所有信息才可用 + +在arch/ARCH/ARCHDisassembler.c的ARCH_getInstruction中初始化为memset(., 0, offsetof(cs_detail, ARCH)+sizeof(cs_ARCH)) + +如果cs_detail发生了变化,特别是在union之后添加了字段,那么相应地更新arch/ arch/ archdisassembly.c + +<details><summary> Code </summary> + +```cpp +struct cs_detail { + uint16_t regs_read[16]; ///< 这个参数读取隐式寄存器列表 + uint8_t regs_read_count; ///< 这个参数读取隐式寄存器计数 + + uint16_t regs_write[20]; ///< 这个参数修改隐式寄存器列表 + uint8_t regs_write_count; ///< 这个参数修改隐式寄存器计数 + + uint8_t groups[8]; ///< 此指令所属的指令组的列表 + uint8_t groups_count; ///< 此指令所属的组的数 + + /// 特定于体系结构的信息 + union { + cs_x86 x86; ///< X86 架构, 包括 16-bit, 32-bit & 64-bit 模式 + cs_arm64 arm64; ///< ARM64 架构 (aka AArch64) + cs_arm arm; ///< ARM 架构 (包括 Thumb/Thumb2) + cs_m68k m68k; ///< M68K 架构 + cs_mips mips; ///< MIPS 架构 + cs_ppc ppc; ///< PowerPC 架构 + cs_sparc sparc; ///< Sparc 架构 + cs_sysz sysz; ///< SystemZ 架构 + cs_xcore xcore; ///< XCore 架构 + cs_tms320c64x tms320c64x; ///< TMS320C64x 架构 + cs_m680x m680x; ///< M680X 架构 + cs_evm evm; ///< Ethereum 架构 + cs_mos65xx mos65xx; ///< MOS65XX 架构 (包含 MOS6502) + cs_wasm wasm; ///< Web Assembly 架构 + cs_bpf bpf; ///< Berkeley Packet Filter 架构 (包含 eBPF) + cs_riscv riscv; ///< RISCV 架构 + }; +} cs_detail; +``` + +</details> + + +### cs_insn + +指令的详细信息 + +<details><summary> Code </summary> + +```cpp +struct cs_insn { + /// 指令ID(基本上是一个用于指令助记符的数字ID) + /// 应在相应架构的头文件中查找'[ARCH]_insn' enum中的指令id,如ARM.h中的'arm_insn'代表ARM, X86.h中的'x86_insn'代表X86等… + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + /// 注意:在Skipdata模式下,这个id字段的“data”指令为0 + unsigned int id; + + /// 指令地址 (EIP) + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + uint64_t address; + + /// 指令长度 + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + uint16_t size; + + /// 此指令的机器码,其字节数由上面的@size表示 + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + uint8_t bytes[24]; + + /// 指令的Ascii文本助记符 + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + char mnemonic[CS_MNEMONIC_SIZE]; + + /// 指令操作数的Ascii文本 + /// 即使在CS_OPT_DETAIL = CS_OPT_OFF时也可以使用此信息 + char op_str[160]; + + /// cs_detail指针 + /// 注意:只有同时满足以下两个要求时,detail指针才有效: + /// (1) CS_OP_DETAIL = CS_OPT_ON + /// (2) 引擎未处于Skipdata模式(CS_OP_SKIPDATA选项设置为CS_OPT_ON) + /// + /// 注意2:当处于Skipdata模式或detail模式关闭时,即使这个指针不是NULL,它的内容仍然是不相关的。 + cs_detail *detail; +} cs_insn; +``` + +</details> + + +### cs_err + +Capstone API遇到的各类型的错误时cs_errno()的返回值 + +<details><summary> Code </summary> + +```cpp +typedef enum cs_err { + CS_ERR_OK = 0, ///< 无错误 + CS_ERR_MEM, ///< 内存不足: cs_open(), cs_disasm(), cs_disasm_iter() + CS_ERR_ARCH, ///< 不支持的架构: cs_open() + CS_ERR_HANDLE, ///<句柄不可用: cs_op_count(), cs_op_index() + CS_ERR_CSH, ///< csh参数不可用: cs_close(), cs_errno(), cs_option() + CS_ERR_MODE, ///< 无效的或不支持的模式: cs_open() + CS_ERR_OPTION, ///< 无效的或不支持的选项: cs_option() + CS_ERR_DETAIL, ///< 信息不可用,因为detail选项是关闭的 + CS_ERR_MEMSETUP, ///< 动态内存管理未初始化(见 CS_OPT_MEM) + CS_ERR_VERSION, ///< 不支持版本 (bindings) + CS_ERR_DIET, ///< 在“diet”引擎中访问不相关的数据 + CS_ERR_SKIPDATA, ///< 在SKIPDATA模式下访问与“数据”指令无关的数据 + CS_ERR_X86_ATT, ///< X86 AT&T 语法不支持(在编译时退出) + CS_ERR_X86_INTEL, ///< X86 Intel 语法不支持(在编译时退出) + CS_ERR_X86_MASM, ///< X86 Intel 语法不支持(在编译时退出) +} cs_err; +``` + +</details> + + +## 0x2 API + +### cs_version + +`unsigned int CAPSTONE_API cs_version(int *major, int *minor);` + +用来输出capstone版本号 + +``` +major: API主版本 +minor: API次版本 +return: 返回主次版本的16进制,如4.0版本返回 0x0400 +``` + +该版本定义于cs.c中,编译后不可更改,不接受自定义版本 + +![](API_Doc_Pic/7.jpg) + +![](API_Doc_Pic/8.jpg) + + +<details><summary> 示例1 </summary> + +```c +#include <stdio.h> +#include <stdlib.h> + +#include "platform.h" +#include "capstone.h" + +static int test() +{ + return cs_version(NULL, NULL); +} + +int main() +{ + int version = test(); + printf("%X", version); + return 0; +} +``` + +</details> + +![](API_Doc_Pic/9.jpg) + + +<details><summary> 示例2,强行修改版本 </summary> + +```cpp +#include <stdio.h> +#include <stdlib.h> + +#include "platform.h" +#include "capstone.h" + +static int test() +{ + int ma[] = { 5 }; + int mi[] = { 6 }; + + return cs_version(ma, mi); +} + +int main() +{ + int version = test(); + printf("%X", version); + return 0; +} +``` + +</details> + +![](API_Doc_Pic/10.jpg) + +可见并不能改变 + +### cs_support + +`bool CAPSTONE_API cs_support(int query);` + +用来检查capstone库是否支持参数输入的架构或处于某编译选项 + +<details><summary> 源码实现 </summary> + + +```cpp +bool CAPSTONE_API cs_support(int query) +{ + if (query == CS_ARCH_ALL) + return all_arch == ((1 << CS_ARCH_ARM) | (1 << CS_ARCH_ARM64) | + (1 << CS_ARCH_MIPS) | (1 << CS_ARCH_X86) | + (1 << CS_ARCH_PPC) | (1 << CS_ARCH_SPARC) | + (1 << CS_ARCH_SYSZ) | (1 << CS_ARCH_XCORE) | + (1 << CS_ARCH_M68K) | (1 << CS_ARCH_TMS320C64X) | + (1 << CS_ARCH_M680X) | (1 << CS_ARCH_EVM)); + + if ((unsigned int)query < CS_ARCH_MAX) + return all_arch & (1 << query); + + if (query == CS_SUPPORT_DIET) { +#ifdef CAPSTONE_DIET + return true; +#else + return false; +#endif + } + + if (query == CS_SUPPORT_X86_REDUCE) { +#if defined(CAPSTONE_HAS_X86) && defined(CAPSTONE_X86_REDUCE) + return true; +#else + return false; +#endif + } + + // unsupported query + return false; +} +``` + +</details> + +示例1(CS_ARCH_ALL,检查是否支持所有架构) + +![](API_Doc_Pic/12.jpg) + +示例2(CS_ARCH_*,检查是否支持指定架构) + +![](API_Doc_Pic/13.jpg) + +示例3(检查是否处于DIET编译模式): + +![](API_Doc_Pic/14.jpg) + +示例4(检查是否处于X86_REDUCE编译模式) + +![](API_Doc_Pic/15.jpg) + + +### cs_malloc_t + +`void* (CAPSTONE_API *cs_malloc_t)(size_t size);` + +cs的动态内存分配,用于 + +```cpp +struct cs_opt_mem { + cs_malloc_t malloc; + cs_calloc_t calloc; + cs_realloc_t realloc; + cs_free_t free; + cs_vsnprintf_t vsnprintf; +} cs_opt_mem; +``` + +在用户模式下,cs_mem_malloc默认使用系统malloc + +Windows driver模式下,`cs_malloc_t cs_mem_malloc = cs_winkernel_malloc;` + +cs_winkernel_malloc定义于\capstone-4.0.1\windows\winkernel_mm.c, + +<details><summary> 源码实现 </summary> + +```cpp +void * CAPSTONE_API cs_winkernel_malloc(size_t size) +{ + // 长度不能分配为0 + NT_ASSERT(size); + + // FP; NonPagedPool用于支持 Windows 7 +#pragma prefast(suppress : 30030) // 分配可执行的POOL_TYPE内存 + size_t number_of_bytes = 0; + CS_WINKERNEL_MEMBLOCK *block = NULL; + // 特定的值能造成溢出 + // 如果value中的和超出或低于类型容量,函数将返回NULL。 + if (!NT_SUCCESS(RtlSizeTAdd(size, sizeof(CS_WINKERNEL_MEMBLOCK), &number_of_bytes))) { + return NULL; + } + block = (CS_WINKERNEL_MEMBLOCK *)ExAllocatePoolWithTag( + NonPagedPool, number_of_bytes, CS_WINKERNEL_POOL_TAG); + if (!block) { + return NULL; + } + block->size = size; + + return block->data; +} +``` + +</details> + +> OSX kernel模式下,`cs_malloc_t cs_mem_malloc = kern_os_malloc;`,这里暂且不探讨。 + + +### cs_calloc_t + +`void* (CAPSTONE_API *cs_calloc_t)(size_t nmemb, size_t size);` + +cs申请内存并初始化 + +用于`struct cs_opt_mem`,定义于cs.c + +用户模式: `cs_calloc_t cs_mem_calloc = calloc;`,使用系统calloc + +Windows driver模式: `cs_calloc_t cs_mem_calloc = cs_winkernel_calloc;` + +<details><summary> 源码实现 </summary> + +```cpp +void * CAPSTONE_API cs_winkernel_calloc(size_t n, size_t size) +{ + size_t total = n * size; + + void *new_ptr = cs_winkernel_malloc(total); + if (!new_ptr) { + return NULL; + } + + return RtlFillMemory(new_ptr, total, 0); +} +``` + +</details> + +> OSX kernel模式: `cs_calloc_t cs_mem_calloc = cs_kern_os_calloc;` 直接调用kern_os_malloc + + +### cs_realloc_t + +`void* (CAPSTONE_API *cs_realloc_t)(void *ptr, size_t size);` + +cs重新分配内存 + +用于`struct cs_opt_mem`,定义于cs.c + +用户模式: `cs_realloc_t cs_mem_realloc = realloc;`,调用系统realloc + +Windows driver模式: `cs_realloc_t cs_mem_realloc = cs_winkernel_realloc;` + +<details><summary> 源码实现 </summary> + +```cpp +void * CAPSTONE_API cs_winkernel_realloc(void *ptr, size_t size) +{ + void *new_ptr = NULL; + size_t current_size = 0; + size_t smaller_size = 0; + + if (!ptr) { + return cs_winkernel_malloc(size); + } + + new_ptr = cs_winkernel_malloc(size); + if (!new_ptr) { + return NULL; + } + + current_size = CONTAINING_RECORD(ptr, CS_WINKERNEL_MEMBLOCK, data)->size; + smaller_size = (current_size < size) ? current_size : size; + RtlCopyMemory(new_ptr, ptr, smaller_size); + cs_winkernel_free(ptr); + + return new_ptr; +} +``` + +</details> + +> OSX kernel模式: `cs_realloc_t cs_mem_realloc = kern_os_realloc;` + + +### cs_free_t + +`typedef void (CAPSTONE_API *cs_free_t)(void *ptr);` + +cs释放内存 + +用于`struct cs_opt_mem`,定义于cs.c + +用户模式: `cs_free_t cs_mem_free = free;`,调用系统free + +Windows driver模式: `cs_free_t cs_mem_free = cs_winkernel_free;` + +<details><summary> 源码实现 </summary> + +```cpp +void CAPSTONE_API cs_winkernel_free(void *ptr) +{ + if (ptr) { + ExFreePoolWithTag(CONTAINING_RECORD(ptr, CS_WINKERNEL_MEMBLOCK, data), CS_WINKERNEL_POOL_TAG); + } +} +``` + +</details> + +> OSX kernel模式: `cs_free_t cs_mem_free = kern_os_free;` + + + +### cs_vsnprintf_t + +`int (CAPSTONE_API *cs_vsnprintf_t)(char *str, size_t size, const char *format, va_list ap);` + +按size大小输出到字符串str中 + +如果系统为wince,将使用_vsnprintf函数 + +vsnprintf ()和_vsnprintf()对于驱动程序都是可用的,但是它们有一些不同 + +在需要返回值和设置空终止符时应使用vsnprintf() + +Windows driver模式: `cs_vsnprintf_t cs_vsnprintf = cs_winkernel_vsnprintf;` + +<details><summary> 源码实现 </summary> + +```cpp +int CAPSTONE_API cs_winkernel_vsnprintf(char *buffer, size_t count, const char *format, va_list argptr) +{ + int result = _vsnprintf(buffer, count, format, argptr); + + // _vsnprintf()在字符串被截断时返回-1,在整个字符串被存储但“buffer”末尾没有“\0”时返回“count”。在这两种情况下,都需要手动添加空终止符。 + if (result == -1 || (size_t)result == count) { + buffer[count - 1] = '\0'; + } + + if (result == -1) { + // 在返回-1时,函数必须获取并返回一些本来要写入的字符。因此,通过重试使用temp buffer进行相同的转换,这个缓冲区就可能足够大来完成格式化,并且获得很多本应写入的字符。 + char* tmp = cs_winkernel_malloc(0x1000); + if (!tmp) { + return result; + } + + result = _vsnprintf(tmp, 0x1000, format, argptr); + NT_ASSERT(result != -1); + cs_winkernel_free(tmp); + } + + return result; +} +``` + +</details> + +> OSX kernel模式: `cs_vsnprintf_t cs_vsnprintf = vsnprintf;`,使用默认vsnprintf + + + +### cs_skipdata_cb_t + +`size_t (CAPSTONE_API *cs_skipdata_cb_t)(const uint8_t *code, size_t code_size, size_t offset, void *user_data);` + +SKIPDATA选项的用户自定义回调函数。 + +``` +code:包含要分解的代码的输入缓冲区。和传递给cs_disasm()的缓冲区相同。 +code_size:上面的code缓冲区的大小(以字节为单位)。 +offset:上面提到的输入缓冲区code中当前检查字节的位置。 +user_data:用户数据通过cs_opt_skipdata结构中的@user_data字段传递给cs_option()。 +return:返回要跳过的字节数,或者0表示立即停止反汇编。 +``` + +cs_skipdata_cb_t在`struct cs_opt_skipdata`中调用 + +<details><summary> 示例 </summary> + +```cpp +#include <stdio.h> +#include <stdlib.h> + +#include "platform.h" +#include "capstone.h" + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; + cs_opt_type opt_skipdata; + size_t skipdata; +}; + +static void print_string_hex(unsigned char* str, size_t len) //输出机器码 +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ + +#define X86_CODE32 "\x8d\x4c\x32\x08\x01\xd8\x81\xc6\x34\x12\x00\x00\x00\x91\x92" //测试用机器码 + +#define RANDOM_CODE "\xed\x00\x00\x00\x00\x1a\x5a\x0f\x1f\xff\xc2\x09\x80\x00\x00\x00\x07\xf7\xeb\x2a\xff\xff\x7f\x57\xe3\x01\xff\xff\x7f\x57\xeb\x00\xf0\x00\x00\x24\xb2\x4f\x00\x78" + + cs_opt_skipdata skipdata = { + // 把默认 "data" 描述符从 ".byte" 重命名为 "db" + "db", + }; + + struct platform platforms[2] = { //以默认描述符和自定义描述符两种方式建立一个数组 + { + CS_ARCH_X86, + CS_MODE_32, + (unsigned char*)X86_CODE32, + sizeof(X86_CODE32) - 1, + "X86 32 (Intel syntax) - Skip data", + }, + { + CS_ARCH_X86, + CS_MODE_32, + (unsigned char*)X86_CODE32, + sizeof(X86_CODE32) - 1, + "X86 32 (Intel syntax) - Skip data with custom mnemonic", + CS_OPT_INVALID, + CS_OPT_OFF, + CS_OPT_SKIPDATA_SETUP, + (size_t)& skipdata, + }, + + }; + + csh handle; //建立capstone句柄 + uint64_t address = 0x1000; //设置起始地址 + cs_insn* insn; //具体信息结构体 + cs_err err; //错误枚举 + int i; + size_t count; //成功反汇编行数 + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); //错误检查 + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + // 打开SKIPDATA 模式 + cs_option(handle, CS_OPT_SKIPDATA, CS_OPT_ON); + cs_option(handle, platforms[i].opt_skipdata, platforms[i].skipdata); + + count = cs_disasm(handle, platforms[i].code, platforms[i].size, address, 0, &insn); + if (count) { + size_t j; + + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + for (j = 0; j < count; j++) { //输出汇编 + printf("0x%" PRIx64 ":\t%s\t\t%s\n", + insn[j].address, insn[j].mnemonic, insn[j].op_str); + } + + // 最后一行代码后打印偏移 + printf("0x%" PRIx64 ":\n", insn[j - 1].address + insn[j - 1].size); + + // 释放cs_disasm()申请的内存 + cs_free(insn, count); + } + else { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + print_string_hex(platforms[i].code, platforms[i].size); + printf("ERROR: Failed to disasm given code!\n"); + abort(); + } + + printf("\n"); + + cs_close(&handle); + } +} + +int main() +{ + test(); + + return 0; +} +``` + +</details> + +运行结果如下,默认的.byte数据类型被改为db描述符 + +![](API_Doc_Pic/11.jpg) + + + + +### cs_open + +`cs_err CAPSTONE_API cs_open(cs_arch arch, cs_mode mode, csh *handle);` + +初始化cs句柄 + +``` +arch: 架构类型 (CS_ARCH_*) +mode: 硬件模式. CS_MODE_*在cs_mode数据类型中可查 +handle: 指向句柄, 返回时更新 +return: 创建成功返回CS_ERR_OK,否则返回cs_err枚举中对应的错误信息 +``` + +<details><summary> 源码实现 </summary> + +```cpp +cs_err CAPSTONE_API cs_open(cs_arch arch, cs_mode mode, csh *handle) +{ + cs_err err; + struct cs_struct *ud; + if (!cs_mem_malloc || !cs_mem_calloc || !cs_mem_realloc || !cs_mem_free || !cs_vsnprintf) + // Error: 使用cs_open()前, 必须使用cs_option(CS_OPT_MEM)进行动态内存管理的初始化 + return CS_ERR_MEMSETUP; + + if (arch < CS_ARCH_MAX && cs_arch_init[arch]) { + // 验证架构是否使用,方式:架构在枚举中且可初始化 + if (mode & cs_arch_disallowed_mode_mask[arch]) { + *handle = 0; + return CS_ERR_MODE; + } + + ud = cs_mem_calloc(1, sizeof(*ud)); + if (!ud) { + // 内存不足 + return CS_ERR_MEM; + } + + ud->errnum = CS_ERR_OK; + ud->arch = arch; + ud->mode = mode; + // 默认情况指令不打开detail模式 + ud->detail = CS_OPT_OFF; + + // 默认skipdata设置 + ud->skipdata_setup.mnemonic = SKIPDATA_MNEM; + + err = cs_arch_init[ud->arch](ud); + if (err) { + cs_mem_free(ud); + *handle = 0; + return err; + } + + *handle = (uintptr_t)ud; + + return CS_ERR_OK; + } else { + *handle = 0; + return CS_ERR_ARCH; + } +} +``` + +其中,cs_struct结构体包含更多细节设定,如下 + +```cpp +struct cs_struct { + cs_arch arch; + cs_mode mode; + Printer_t printer; // 打印asm + void *printer_info; // 打印信息 + Disasm_t disasm; // 反编译 + void *getinsn_info; // 打印辅助信息 + GetName_t reg_name; + GetName_t insn_name; + GetName_t group_name; + GetID_t insn_id; + PostPrinter_t post_printer; + cs_err errnum; + ARM_ITStatus ITBlock; // ARM特殊选项 + cs_opt_value detail, imm_unsigned; + int syntax; //ARM, Mips & PPC等架构的基本asm语法打印 + bool doing_mem; // 在InstPrinter代码中处理内存操作数 + unsigned short *insn_cache; //为mapping.c建立缓存索引 + GetRegisterName_t get_regname; + bool skipdata; // 如果反编译时要跳过数据,该项设置为True + uint8_t skipdata_size; //要跳过bytes的数量 + cs_opt_skipdata skipdata_setup; // 自定义skipdata设置 + const uint8_t *regsize_map; //映射register大小 (目前仅支持x86) + GetRegisterAccess_t reg_access; + struct insn_mnem *mnem_list; // 自定义指令助记符的链接list +}; +``` + +</details> + +示例(创建一个x86_64类型的cs句柄) + +`cs_open(CS_ARCH_X86, CS_MODE_64, &handle)` + + +### cs_close + +`cs_err CAPSTONE_API cs_close(csh *handle);` + +释放句柄 + +``` +handle: 指向一个cs_open()打开的句柄 +return: 释放成功返回CS_ERR_OK,否则返回cs_err枚举的错误信息 +``` + +释放句柄实质为将句柄值设置为0 + +<details><summary> 源码实现 </summary> + +```cpp +cs_err CAPSTONE_API cs_close(csh *handle) +{ + struct cs_struct *ud; + struct insn_mnem *next, *tmp; + + if (*handle == 0) + // 句柄不可用 + return CS_ERR_CSH; + + ud = (struct cs_struct *)(*handle); + + if (ud->printer_info) + cs_mem_free(ud->printer_info); + + // 释放自定义助记符的链接list + tmp = ud->mnem_list; + while(tmp) { + next = tmp->next; + cs_mem_free(tmp); + tmp = next; + } + + cs_mem_free(ud->insn_cache); + + memset(ud, 0, sizeof(*ud)); + cs_mem_free(ud); + + // handle值设置为0,保证这个句柄在cs_close()释放后不可使用 + *handle = 0; + + return CS_ERR_OK; +} +``` + +</details> + +示例 + +`cs_close(&handle);` + + +### cs_option + +`cs_err CAPSTONE_API cs_option(csh handle, cs_opt_type type, size_t value);` + +反编译引擎的运行时选项 + +``` +handle: cs_open()打开的句柄 +type: 设置选项的类型 +value: 与type对应的选项值 +return: 设置成功返回CS_ERR_OK,否则返回cs_err枚举的错误信息 +``` + +注意: 在CS_OPT_MEM的情况下,handle可以是任何值,因此cs_option(handle, CS_OPT_MEM, value)必须在cs_open()之前被调用 + +<details><summary> 源码实现 </summary> + +```cpp +cs_err CAPSTONE_API cs_option(csh ud, cs_opt_type type, size_t value) +{ + struct cs_struct *handle; + cs_opt_mnem *opt; + + // 支持在所有API前支持 (even cs_open()) + if (type == CS_OPT_MEM) { + cs_opt_mem *mem = (cs_opt_mem *)value; + + cs_mem_malloc = mem->malloc; + cs_mem_calloc = mem->calloc; + cs_mem_realloc = mem->realloc; + cs_mem_free = mem->free; + cs_vsnprintf = mem->vsnprintf; + + return CS_ERR_OK; + } + + handle = (struct cs_struct *)(uintptr_t)ud; + if (!handle) + return CS_ERR_CSH; + + switch(type) { + default: + break; + + case CS_OPT_UNSIGNED: + handle->imm_unsigned = (cs_opt_value)value; + return CS_ERR_OK; + + case CS_OPT_DETAIL: + handle->detail = (cs_opt_value)value; + return CS_ERR_OK; + + case CS_OPT_SKIPDATA: + handle->skipdata = (value == CS_OPT_ON); + if (handle->skipdata) { + if (handle->skipdata_size == 0) { + handle->skipdata_size = skipdata_size(handle); + } + } + return CS_ERR_OK; + + case CS_OPT_SKIPDATA_SETUP: + if (value) + handle->skipdata_setup = *((cs_opt_skipdata *)value); + return CS_ERR_OK; + + case CS_OPT_MNEMONIC: + opt = (cs_opt_mnem *)value; + if (opt->id) { + if (opt->mnemonic) { + struct insn_mnem *tmp; + + // 添加新指令或替换现有指令 + // 查看当前insn释放在list中 + tmp = handle->mnem_list; + while(tmp) { + if (tmp->insn.id == opt->id) { + // f找到指令,替换助记符 + (void)strncpy(tmp->insn.mnemonic, opt->mnemonic, sizeof(tmp->insn.mnemonic) - 1); + tmp->insn.mnemonic[sizeof(tmp->insn.mnemonic) - 1] = '\0'; + break; + } + tmp = tmp->next; + } + + // 2. 如果没有就添加这条指令 + if (!tmp) { + tmp = cs_mem_malloc(sizeof(*tmp)); + tmp->insn.id = opt->id; + (void)strncpy(tmp->insn.mnemonic, opt->mnemonic, sizeof(tmp->insn.mnemonic) - 1); + tmp->insn.mnemonic[sizeof(tmp->insn.mnemonic) - 1] = '\0'; + // 新指令放在list最前面 + tmp->next = handle->mnem_list; + handle->mnem_list = tmp; + } + return CS_ERR_OK; + } else { + struct insn_mnem *prev, *tmp; + + tmp = handle->mnem_list; + prev = tmp; + while(tmp) { + if (tmp->insn.id == opt->id) { + // 删除指令 + if (tmp == prev) { + handle->mnem_list = tmp->next; + } else { + prev->next = tmp->next; + } + cs_mem_free(tmp); + break; + } + prev = tmp; + tmp = tmp->next; + } + } + } + return CS_ERR_OK; + + case CS_OPT_MODE: + // 验证所请求的模式是否有效 + if (value & cs_arch_disallowed_mode_mask[handle->arch]) { + return CS_ERR_OPTION; + } + break; + } + + return cs_arch_option[handle->arch](handle, type, value); +} +``` +</details> + + +<details><summary> 示例,更改反汇编后显示的语法 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +#define CODE "\x55\x48\x8b\x05\xb8\x13\x00\x00" + +int main(void) +{ + csh handle; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + cs_option(handle, CS_OPT_SYNTAX, CS_OPT_SYNTAX_ATT); // 以AT&T语法显示 + count = cs_disasm(handle, (unsigned char*)CODE, sizeof(CODE) - 1, 0x1000, 0, &insn); + if (count) { + size_t j; + + for (j = 0; j < count; j++) { + printf("0x%""Ix"":\t%s\t\t%s\n", insn[j].address, insn[j].mnemonic, insn[j].op_str); + } + + cs_free(insn, count); + } + else + printf("ERROR: Failed to disassemble given code!\n"); + + cs_close(&handle); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/16.jpg) + + +### cs_errno + +`cs_err CAPSTONE_API cs_errno(csh handle);` + +API出错时返回错误消息 + +``` +handle: cs_open()打开的句柄 +return: 无错误返回CS_ERR_OK,否则返回cs_err枚举的错误信息 +``` + +判断到句柄不存在直接返回CS_ERR_CSH + +<details><summary> 示例 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +#define CODE "\x55\x48\x8b\x05\xb8\x13\x00\x00" + +int main(void) +{ + csh handle = 0; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + + cs_close(&handle); + std::cout << cs_errno(handle); //关闭句柄后检查将报错 + return 0; +} +``` + +</details> + +输出,错误码4即CS_ERR_CSH + +![](API_Doc_Pic/17.jpg) + + +### cs_strerror + +`const char * CAPSTONE_API cs_strerror(cs_err code);` + +将上个API输出的错误码转换为详细错误信息 + +<details><summary> 源码实现 </summary> + +```cpp +const char * CAPSTONE_API cs_strerror(cs_err code) +{ + switch(code) { + default: + return "Unknown error code"; + case CS_ERR_OK: + return "OK (CS_ERR_OK)"; + case CS_ERR_MEM: + return "Out of memory (CS_ERR_MEM)"; + case CS_ERR_ARCH: + return "Invalid/unsupported architecture(CS_ERR_ARCH)"; + case CS_ERR_HANDLE: + return "Invalid handle (CS_ERR_HANDLE)"; + case CS_ERR_CSH: + return "Invalid csh (CS_ERR_CSH)"; + case CS_ERR_MODE: + return "Invalid mode (CS_ERR_MODE)"; + case CS_ERR_OPTION: + return "Invalid option (CS_ERR_OPTION)"; + case CS_ERR_DETAIL: + return "Details are unavailable (CS_ERR_DETAIL)"; + case CS_ERR_MEMSETUP: + return "Dynamic memory management uninitialized (CS_ERR_MEMSETUP)"; + case CS_ERR_VERSION: + return "Different API version between core & binding (CS_ERR_VERSION)"; + case CS_ERR_DIET: + return "Information irrelevant in diet engine (CS_ERR_DIET)"; + case CS_ERR_SKIPDATA: + return "Information irrelevant for 'data' instruction in SKIPDATA mode (CS_ERR_SKIPDATA)"; + case CS_ERR_X86_ATT: + return "AT&T syntax is unavailable (CS_ERR_X86_ATT)"; + case CS_ERR_X86_INTEL: + return "INTEL syntax is unavailable (CS_ERR_X86_INTEL)"; + case CS_ERR_X86_MASM: + return "MASM syntax is unavailable (CS_ERR_X86_MASM)"; + } +} +``` +</details> + + +<details><summary> 示例,结合cs_errno使用 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +#define CODE "\x55\x48\x8b\x05\xb8\x13\x00\x00" + +int main(void) +{ + csh handle = 0; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + + cs_close(&handle); + std::cout << cs_strerror(cs_errno(handle)); //直接输出报错信息 + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/18.jpg) + + +### cs_disasm + +```cpp +size_t CAPSTONE_API cs_disasm(csh handle, + const uint8_t *code, size_t code_size, + uint64_t address, + size_t count, + cs_insn **insn); +``` + +给定缓冲区、大小、地址和编号,反编译机器码 + +API动态地分配内存来包含分解的指令,生成的指令将放在*insn中 + +注意: 必须释放分配的内存,以避免内存泄漏。对于需要动态分配稀缺内存的系统(如OS内核或固件),API cs_disasm_iter()可能是比cs_disasm()更好的选择。原因是,使用cs_disasm()时,基于有限的可用内存,必须预先计算要分解多少条指令。 + +``` +handle: cs_open()返回的句柄 +code: 包含要反汇编的机器码的缓冲区。 +code_size:上面代码缓冲区的大小。 +address:给定原始代码缓冲区中的第一条指令的地址。 +insn: 由这个API填写的指令数组。注意: insn将由这个函数分配,应该用cs_free () API释放 +count: 需要分解的指令数量,或输入0分解所有指令 +return:成功反汇编指令的数量,如果该函数未能反汇编给定的代码,则为0,失败时,调用cs_errno()获取错误代码。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +size_t CAPSTONE_API cs_disasm(csh ud, const uint8_t *buffer, size_t size, uint64_t offset, size_t count, cs_insn **insn) +{ + struct cs_struct *handle; + MCInst mci; + uint16_t insn_size; + size_t c = 0, i; + unsigned int f = 0; // 缓存中下一条指令的索引 + cs_insn *insn_cache; // 缓存反汇编后的指令 + void *total = NULL; + size_t total_size = 0; //所有insn的输出缓冲区的总大小 + bool r; + void *tmp; + size_t skipdata_bytes; + uint64_t offset_org; // 保存缓冲区的所有原始信息 + size_t size_org; + const uint8_t *buffer_org; + unsigned int cache_size = INSN_CACHE_SIZE; + size_t next_offset; + + handle = (struct cs_struct *)(uintptr_t)ud; + if (!handle) { + // 修复方式: + // handle->errnum = CS_ERR_HANDLE; + return 0; + } + + handle->errnum = CS_ERR_OK; + + // 重设ARM架构的IT block + if (handle->arch == CS_ARCH_ARM) + handle->ITBlock.size = 0; + +#ifdef CAPSTONE_USE_SYS_DYN_MEM + if (count > 0 && count <= INSN_CACHE_SIZE) + cache_size = (unsigned int) count; +#endif + + // 保存SKIPDATA原始偏移量 + buffer_org = buffer; + offset_org = offset; + size_org = size; + + total_size = sizeof(cs_insn) * cache_size; + total = cs_mem_malloc(total_size); + if (total == NULL) { + // 内存不足 + handle->errnum = CS_ERR_MEM; + return 0; + } + + insn_cache = total; + + while (size > 0) { + MCInst_Init(&mci); + mci.csh = handle; + + mci.address = offset; + + if (handle->detail) { + //给detail指针分配内存 + insn_cache->detail = cs_mem_malloc(sizeof(cs_detail)); + } else { + insn_cache->detail = NULL; + } + + // 为non-detailed模式保存所有信息 + mci.flat_insn = insn_cache; + mci.flat_insn->address = offset; +#ifdef CAPSTONE_DIET + //mnemonic & op_str0填充 + mci.flat_insn->mnemonic[0] = '\0'; + mci.flat_insn->op_str[0] = '\0'; +#endif + + r = handle->disasm(ud, buffer, size, &mci, &insn_size, offset, handle->getinsn_info); + if (r) { + SStream ss; + SStream_Init(&ss); + + mci.flat_insn->size = insn_size; + + //将内部指令操作码映射到公共insn ID + handle->insn_id(handle, insn_cache, mci.Opcode); + + handle->printer(&mci, &ss, handle->printer_info); + fill_insn(handle, insn_cache, ss.buffer, &mci, handle->post_printer, buffer); + + // 调整opcode (X86) + if (handle->arch == CS_ARCH_X86) + insn_cache->id += mci.popcode_adjust; + + next_offset = insn_size; + } else { + // 遇到中断指令 + + // 为detail指针释放内存 + if (handle->detail) { + cs_mem_free(insn_cache->detail); + } + + if (!handle->skipdata || handle->skipdata_size > size) + break; + + if (handle->skipdata_setup.callback) { + skipdata_bytes = handle->skipdata_setup.callback(buffer_org, size_org, + (size_t)(offset - offset_org), handle->skipdata_setup.user_data); + if (skipdata_bytes > size) + break; + + if (!skipdata_bytes) + break; + } else + skipdata_bytes = handle->skipdata_size; + + insn_cache->id = 0; + insn_cache->address = offset; + insn_cache->size = (uint16_t)skipdata_bytes; + memcpy(insn_cache->bytes, buffer, skipdata_bytes); +#ifdef CAPSTONE_DIET + insn_cache->mnemonic[0] = '\0'; + insn_cache->op_str[0] = '\0'; +#else + strncpy(insn_cache->mnemonic, handle->skipdata_setup.mnemonic, + sizeof(insn_cache->mnemonic) - 1); + skipdata_opstr(insn_cache->op_str, buffer, skipdata_bytes); +#endif + insn_cache->detail = NULL; + + next_offset = skipdata_bytes; + } + + // 一条新指令进入缓存 + f++; + + // 反汇编了一条指令 + c++; + if (count > 0 && c == count) + break; + + if (f == cache_size) { + cache_size = cache_size * 8 / 5; + total_size += (sizeof(cs_insn) * cache_size); + tmp = cs_mem_realloc(total, total_size); + if (tmp == NULL) { //内存不足 + if (handle->detail) { + insn_cache = (cs_insn *)total; + for (i = 0; i < c; i++, insn_cache++) + cs_mem_free(insn_cache->detail); + } + + cs_mem_free(total); + *insn = NULL; + handle->errnum = CS_ERR_MEM; + return 0; + } + + total = tmp; + //在最后一条指令之后继续填充缓存 + insn_cache = (cs_insn *)((char *)total + sizeof(cs_insn) * c); + + // 将f重置为0,从一开始就填入缓存 + f = 0; + } else + insn_cache++; + + buffer += next_offset; + size -= next_offset; + offset += next_offset; + } + + if (!c) { + //未反汇编任何指令 + cs_mem_free(total); + total = NULL; + } else if (f != cache_size) { + // 没有完全使用最后一个缓存,缩小大小 + tmp = cs_mem_realloc(total, total_size - (cache_size - f) * sizeof(*insn_cache)); + if (tmp == NULL) { // 内存不足 + // 释放所有detail指针 + if (handle->detail) { + insn_cache = (cs_insn *)total; + for (i = 0; i < c; i++, insn_cache++) + cs_mem_free(insn_cache->detail); + } + + cs_mem_free(total); + *insn = NULL; + + handle->errnum = CS_ERR_MEM; + return 0; + } + + total = tmp; + } + + *insn = total; + + return c; +} +``` + +</details> + + +<details><summary> 示例,x86_64 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +#define CODE "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + +int main(void) +{ + csh handle = 0; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + + count = cs_disasm(handle, (unsigned char*)CODE, sizeof(CODE) - 1, 0x1000, 0, &insn); //所有指令,基址0x1000,放入insn + if (count) { + size_t j; + + for (j = 0; j < count; j++) { + printf("0x%""Ix"":\t%s\t\t%s\n", insn[j].address, insn[j].mnemonic, insn[j].op_str); + } + + cs_free(insn, count); + } + else + printf("ERROR: Failed to disassemble given code!\n"); + + cs_close(&handle); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/19.jpg) + + +### cs_free + +`void CAPSTONE_API cs_free(cs_insn *insn, size_t count);` + +释放被 cs_malloc() 或 cs_disasm() 分配的内存(insn参数) + +``` +insn: 由cs_disasm()或cs_malloc()中的@insn参数返回的指针 +count: 赋值由cs_disasm()返回的cs_insn结构的数量,或赋值为1表示由cs_malloc()分配给空闲内存的数量 +``` + +<details><summary> 源码实现 </summary> + +```cpp +void CAPSTONE_API cs_free(cs_insn *insn, size_t count) +{ + size_t i; + + // free 所有 detail 指针 + for (i = 0; i < count; i++) + cs_mem_free(insn[i].detail); + + cs_mem_free(insn); +} +``` + +直接调用cs_mem_free,也就是默认的free + +</details> + + +<details><summary> 示例(释放cs_disasm申请的内存) </summary> + +```cpp + count = cs_disasm(handle, (unsigned char*)CODE, sizeof(CODE) - 1, 0x1000, 0, &insn); //计数由cs_disasm申请的内存 + if (count) { + size_t j; + + for (j = 0; j < count; j++) { + printf("0x%""Ix"":\t%s\t\t%s\n", insn[j].address, insn[j].mnemonic, insn[j].op_str); + } + + cs_free(insn, count); //循环依次释放每条insn的内存 + } +``` + +</details> + + +### cs_malloc + +`cs_insn * CAPSTONE_API cs_malloc(csh handle);` + +被用于在API cs_disasm_iter()中为一条指令分配内存 + +``` +handle: cs_open()返回的句柄 +``` + +<details><summary> 源码实现 </summary> + +```cpp +cs_insn * CAPSTONE_API cs_malloc(csh ud) +{ + cs_insn *insn; + struct cs_struct *handle = (struct cs_struct *)(uintptr_t)ud; + + insn = cs_mem_malloc(sizeof(cs_insn)); + if (!insn) { + // insufficient memory + handle->errnum = CS_ERR_MEM; + return NULL; + } else { + if (handle->detail) { + // allocate memory for @detail pointer + insn->detail = cs_mem_malloc(sizeof(cs_detail)); + if (insn->detail == NULL) { // insufficient memory + cs_mem_free(insn); + handle->errnum = CS_ERR_MEM; + return NULL; + } + } else + insn->detail = NULL; + } + + return insn; +} +``` + +</details> + +当这条指令所占的内存不再使用时,使用cs_free(insn, 1)释放,示例在下面cs_disasm_iter处 + + +### cs_disasm_iter + +```cpp +bool CAPSTONE_API cs_disasm_iter(csh handle, + const uint8_t **code, size_t *size, + uint64_t *address, cs_insn *insn); +``` + +给定buff、大小、地址和要解码的指令数,更快速的反汇编机器码, +这个API将生成的指令放入insn中的给定的缓存中。 + +注意1: 此API将更新code、size和address以指向输入缓冲区中的下一条指令。所以,虽然每次反汇编一条指令可以使用cs_disasm(count=1)来实现,但一些基准测试显示,在循环中使用cs_disasm_iter()可以方便地快速迭代所有指令,在随机输入时可以快30%。 + +注意2:可以使用cs_malloc()创建insn中的缓存。 + +注意3:对于动态分配内存可能产生内存不足的系统(比如OS内核或固件),建议使用cs_disasm()这个API, 因为cs_disasm()是根据要分解的指令的数量来分配内存。 + +``` +handle: cs_open()返回的句柄 +code: 要反汇编的机器码所在的缓冲区 +size: 机器码缓冲区的大小 +address: 所给机器码缓冲区中第一个insn的地址 +insn: 指向这个API要填充的指令的指针。 +return:如果这个API成功反汇编了一条指令返回true,否则将返回false。 +``` + +失败时,调用cs_errno()获取错误代码。 + +<details><summary> 代码实现,在cs_disasm基础上使用动态内存分配 </summary> + +```cpp +bool CAPSTONE_API cs_disasm_iter(csh ud, const uint8_t **code, size_t *size, + uint64_t *address, cs_insn *insn) +{ + struct cs_struct *handle; + uint16_t insn_size; + MCInst mci; + bool r; + + handle = (struct cs_struct *)(uintptr_t)ud; + if (!handle) { + return false; + } + + handle->errnum = CS_ERR_OK; + + MCInst_Init(&mci); + mci.csh = handle; + + mci.address = *address; + + // 为无detail模式保存相关信息 + mci.flat_insn = insn; + mci.flat_insn->address = *address; +#ifdef CAPSTONE_DIET + mci.flat_insn->mnemonic[0] = '\0'; + mci.flat_insn->op_str[0] = '\0'; +#endif + + r = handle->disasm(ud, *code, *size, &mci, &insn_size, *address, handle->getinsn_info); + if (r) { + SStream ss; + SStream_Init(&ss); + + mci.flat_insn->size = insn_size; + + // 将内部指令操作码映射到公共insn ID + handle->insn_id(handle, insn, mci.Opcode); + + handle->printer(&mci, &ss, handle->printer_info); + + fill_insn(handle, insn, ss.buffer, &mci, handle->post_printer, *code); + + // 调整伪操作码(X86) + if (handle->arch == CS_ARCH_X86) + insn->id += mci.popcode_adjust; + + *code += insn_size; + *size -= insn_size; + *address += insn_size; + } else { // 遇到中断指令 + size_t skipdata_bytes; + + // 如果没有跳过数据的请求,或者剩余数据太小,则退出 + if (!handle->skipdata || handle->skipdata_size > *size) + return false; + + if (handle->skipdata_setup.callback) { + skipdata_bytes = handle->skipdata_setup.callback(*code, *size, + 0, handle->skipdata_setup.user_data); + if (skipdata_bytes > *size) + // 剩余数据太小 + return false; + + if (!skipdata_bytes) + return false; + } else + skipdata_bytes = handle->skipdata_size; + + // 基于架构和模式跳过一些数据 + insn->id = 0; // 此“数据”指令的ID无效 + insn->address = *address; + insn->size = (uint16_t)skipdata_bytes; +#ifdef CAPSTONE_DIET + insn->mnemonic[0] = '\0'; + insn->op_str[0] = '\0'; +#else + memcpy(insn->bytes, *code, skipdata_bytes); + strncpy(insn->mnemonic, handle->skipdata_setup.mnemonic, + sizeof(insn->mnemonic) - 1); + skipdata_opstr(insn->op_str, *code, skipdata_bytes); +#endif + + *code += skipdata_bytes; + *size -= skipdata_bytes; + *address += skipdata_bytes; + } + + return true; +} +``` + +</details> + + +<details><summary> 示例 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ +#define X86_CODE16 "\x8d\x4c\x32\x08\x01\xd8\x81\xc6\x34\x12\x00\x00" +#define X86_CODE32 "\x8d\x4c\x32\x08\x01\xd8\x81\xc6\x34\x12\x00\x00" +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00" + + struct platform platforms[4] = { //架构及模式 + { + CS_ARCH_X86, + CS_MODE_16, + (unsigned char*)X86_CODE16, + sizeof(X86_CODE32) - 1, + "X86 16bit (Intel syntax)" + }, + { + CS_ARCH_X86, + CS_MODE_32, + (unsigned char*)X86_CODE32, + sizeof(X86_CODE32) - 1, + "X86 32bit (ATT syntax)", + CS_OPT_SYNTAX, + CS_OPT_SYNTAX_ATT, + }, + { + CS_ARCH_X86, + CS_MODE_32, + (unsigned char*)X86_CODE32, + sizeof(X86_CODE32) - 1, + "X86 32 (Intel syntax)" + }, + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + // 为cs_disasm_iter()分配内存 + insn = cs_malloc(handle); + + print_string_hex(platforms[i].code, platforms[i].size); //原机器码 + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { //cs_disasm_iter反汇编 + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s // insn-ID: %u, insn-mnem: %s\n", + insn->address, insn->mnemonic, insn->op_str, + insn->id, cs_insn_name(handle, insn->id)); + + // 打印此指令使用的隐式寄存器 + detail = insn->detail; + + if (detail->regs_read_count > 0) { + printf("\tImplicit registers read: "); + for (n = 0; n < detail->regs_read_count; n++) { + printf("%s ", cs_reg_name(handle, detail->regs_read[n])); + } + printf("\n"); + } + + // 打印此指令修改的隐式寄存器 + if (detail->regs_write_count > 0) { + printf("\tImplicit registers modified: "); + for (n = 0; n < detail->regs_write_count; n++) { + printf("%s ", cs_reg_name(handle, detail->regs_write[n])); + } + printf("\n"); + } + + // 打印此指令所属指令集 + if (detail->groups_count > 0) { + printf("\tThis instruction belongs to groups: "); + for (n = 0; n < detail->groups_count; n++) { + printf("%s ", cs_group_name(handle, detail->groups[n])); + } + printf("\n"); + } + } + + printf("\n"); + + // 释放cs_malloc()分配的内存 + cs_free(insn, 1); + + cs_close(&handle); + } +} + +int main() +{ + test(); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/20.jpg) + + +### cs_reg_name + +`const char * CAPSTONE_API cs_reg_name(csh handle, unsigned int reg_id);` + +获取寄存器的名字(string类型) +寄存器id可在相关架构的头文件(建立项目时复制到项目文件夹的那些头文件)内找到 + +注意: 当处于diet模式时此API不可用,因为引擎不会存储寄存器名 + +``` +handle: cs_open()返回的句柄 +reg_id: 寄存器id +return: 寄存器的字符名, 如果reg_id不可用返回NULL +``` + +<details><summary> 源码实现 </summary> + +```cpp +const char * CAPSTONE_API cs_reg_name(csh ud, unsigned int reg) +{ + struct cs_struct *handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle || handle->reg_name == NULL) { + return NULL; + } + + return handle->reg_name(ud, reg); +} +``` + +</details> + + +<details><summary> 示例(打印RAX) </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +int main(void) +{ + csh handle = 0; + cs_insn* insn; + size_t count; + + if (cs_open(CS_ARCH_X86, CS_MODE_64, &handle)) { + printf("ERROR: Failed to initialize engine!\n"); + return -1; + } + + printf("%s", cs_reg_name(handle, X86_REG_RAX)); + cs_close(&handle); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/21.jpg) + + +### cs_insn_name + +`const char * CAPSTONE_API cs_insn_name(csh handle, unsigned int insn_id);` + +获取指令的名字(string类型) + +指令id可在相关架构的头文件(建立项目时复制到项目文件夹的那些头文件)内找到 + +注意: 当处于diet模式时此API不可用,因为引擎不会存储寄存器名 + +``` +handle: cs_open()返回的句柄 +insn_id: 指令id +return: 指令的字符名, 如果insn_id不可用返回NULL +``` + +<details><summary> 源码实现 </summary> + +```cpp +const char * CAPSTONE_API cs_insn_name(csh ud, unsigned int insn) +{ + struct cs_struct *handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle || handle->insn_name == NULL) { + return NULL; + } + + return handle->insn_name(ud, insn); +} +``` + +</details> + + +<details><summary> 示例 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ + +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + + struct platform platforms[] = { + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + }; + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + insn = cs_malloc(handle); + + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s", + insn->address, insn->mnemonic, insn->op_str); + printf(" instruction: %s", cs_insn_name(handle, insn->id)); //输出该行的操作指令 + cout << endl; + + printf("\n"); + cs_free(insn, 1); + cs_close(&handle); + } +} + +int main() +{ + test(); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/22.jpg) + + +### cs_group_name + +`const char * CAPSTONE_API cs_group_name(csh handle, unsigned int group_id);` + +输出指令类型名字 + +指令id可在相关架构的头文件(建立项目时复制到项目文件夹的那些头文件)内找到 + +注意: 当处于diet模式时此API不可用,因为引擎不会存储寄存器名 + +``` +handle: cs_open()返回的句柄 +insn_id: 指令类型id +return: 指令类型的字符名, 如果insn_id不可用返回NULL +``` + +示例都与上面类似,略。 + + +### cs_insn_group + +`bool CAPSTONE_API cs_insn_group(csh handle, const cs_insn *insn, unsigned int group_id);` + +检查反汇编后的指令是否属于某个特定指令类型 + +注意:只有当detail选项为ON时这个API可用 (默认OFF). + +在“diet”模式下,此API没有用,因为引擎不更新insn->groups数组 + +``` +handle: cs_open()返回的句柄 +insn: 从cs_disasm()或cs_disasm_iter()接收的反汇编指令结构 +group_id: 要检查此指令是否属于的指令类型。 +return: 如果该指令确实属于给定的指令类型,则为true,否则为false。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +bool CAPSTONE_API cs_insn_group(csh ud, const cs_insn *insn, unsigned int group_id) +{ + struct cs_struct *handle; + if (!ud) + return false; + + handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return false; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + return arr_exist8(insn->detail->groups, insn->detail->groups_count, group_id); +} +``` + +</details> + + +<details><summary> 示例(判断是否属于跳转指令) </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ + +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + + struct platform platforms[] = { + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + }; + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + insn = cs_malloc(handle); + + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s ", + insn->address, insn->mnemonic, insn->op_str); + cout << "is JUMP: " <<cs_insn_group(handle, insn, CS_GRP_JUMP) << endl; //判断是否为跳转指令 + cout << endl; + + printf("\n"); + cs_free(insn, 1); + cs_close(&handle); + } +} + +int main() +{ + test(); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/23.jpg) + + +### cs_reg_read + +`bool CAPSTONE_API cs_reg_read(csh handle, const cs_insn *insn, unsigned int reg_id);` + +检查反汇编指令是否隐式使用特定寄存器。 + +注意:此API仅在启用detail选项时有效(默认为关闭) + +在“diet”模式下,此API没有用,因为引擎不更新insn->regs_read数组 + +``` +insn: 从cs_disasm()或cs_disasm_iter()接收的反汇编指令结构 +reg_id: 标注想要检查的这个指令是否使用了它。 +return: 如果该指令确实隐式使用了给定寄存器,则为true,否则为false。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +bool CAPSTONE_API cs_reg_read(csh ud, const cs_insn *insn, unsigned int reg_id) +{ + struct cs_struct *handle; + if (!ud) + return false; + + handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return false; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + return arr_exist(insn->detail->regs_read, insn->detail->regs_read_count, reg_id); +} +``` +</details> + +示例同API cs_disasm_iter + + +### cs_reg_write + +`bool CAPSTONE_API cs_reg_write(csh handle, const cs_insn *insn, unsigned int reg_id);` + +检查反汇编指令是否隐式修改了特定寄存器。 + +注意:此API仅在启用detail选项时有效(默认为关闭) + +在“diet”模式下,此API没有用,因为引擎不更新insn->regs_read数组 + +``` +insn: 从cs_disasm()或cs_disasm_iter()接收的反汇编指令结构 +reg_id: 标注想要检查的这个指令是否修改了它。 +return: 如果该指令确实隐式修改了给定寄存器,则为true,否则为false。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +bool CAPSTONE_API cs_reg_write(csh ud, const cs_insn *insn, unsigned int reg_id) +{ + struct cs_struct *handle; + if (!ud) + return false; + + handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return false; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return false; + } + + return arr_exist(insn->detail->regs_write, insn->detail->regs_write_count, reg_id); +} +``` +</details> + +示例同API cs_disasm_iter + + +### cs_op_count + +`int CAPSTONE_API cs_op_count(csh handle, const cs_insn *insn, unsigned int op_type);` + +计算给定类型的操作数的数量 + +注意:只有当detail选项为ON时这个API可用 (默认OFF). + +``` +handle: cs_open()返回的句柄 +insn: 从cs_disasm()或cs_disasm_iter()接收的反汇编指令结构 +op_type: 要找到的操作数类型。 +return: 指令insn中给定类型op_type的操作数的数量,返回-1表示查找失败。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +int CAPSTONE_API cs_op_count(csh ud, const cs_insn *insn, unsigned int op_type) +{ + struct cs_struct *handle; + unsigned int count = 0, i; + if (!ud) + return -1; + + handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return -1; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return -1; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return -1; + } + + handle->errnum = CS_ERR_OK; + + switch (handle->arch) { + default: + handle->errnum = CS_ERR_HANDLE; + return -1; + case CS_ARCH_ARM: + for (i = 0; i < insn->detail->arm.op_count; i++) + if (insn->detail->arm.operands[i].type == (arm_op_type)op_type) + count++; + break; + case CS_ARCH_ARM64: + for (i = 0; i < insn->detail->arm64.op_count; i++) + if (insn->detail->arm64.operands[i].type == (arm64_op_type)op_type) + count++; + break; + case CS_ARCH_X86: + for (i = 0; i < insn->detail->x86.op_count; i++) + if (insn->detail->x86.operands[i].type == (x86_op_type)op_type) + count++; + break; + case CS_ARCH_MIPS: + for (i = 0; i < insn->detail->mips.op_count; i++) + if (insn->detail->mips.operands[i].type == (mips_op_type)op_type) + count++; + break; + case CS_ARCH_PPC: + for (i = 0; i < insn->detail->ppc.op_count; i++) + if (insn->detail->ppc.operands[i].type == (ppc_op_type)op_type) + count++; + break; + case CS_ARCH_SPARC: + for (i = 0; i < insn->detail->sparc.op_count; i++) + if (insn->detail->sparc.operands[i].type == (sparc_op_type)op_type) + count++; + break; + case CS_ARCH_SYSZ: + for (i = 0; i < insn->detail->sysz.op_count; i++) + if (insn->detail->sysz.operands[i].type == (sysz_op_type)op_type) + count++; + break; + case CS_ARCH_XCORE: + for (i = 0; i < insn->detail->xcore.op_count; i++) + if (insn->detail->xcore.operands[i].type == (xcore_op_type)op_type) + count++; + break; + case CS_ARCH_M68K: + for (i = 0; i < insn->detail->m68k.op_count; i++) + if (insn->detail->m68k.operands[i].type == (m68k_op_type)op_type) + count++; + break; + case CS_ARCH_TMS320C64X: + for (i = 0; i < insn->detail->tms320c64x.op_count; i++) + if (insn->detail->tms320c64x.operands[i].type == (tms320c64x_op_type)op_type) + count++; + break; + case CS_ARCH_M680X: + for (i = 0; i < insn->detail->m680x.op_count; i++) + if (insn->detail->m680x.operands[i].type == (m680x_op_type)op_type) + count++; + break; + case CS_ARCH_EVM: +#if 0 + for (i = 0; i < insn->detail->evm.op_count; i++) + if (insn->detail->evm.operands[i].type == (evm_op_type)op_type) + count++; +#endif + break; + } + + return count; +} +``` + +</details> + + +<details><summary> x86指令操作码类型示例(判断寄存操作码) </summary> + +```cpp +typedef enum x86_op_type { + X86_OP_INVALID = 0, ///< = CS_OP_INVALID (未初始化). + X86_OP_REG, ///< = CS_OP_REG (寄存操作码). + X86_OP_IMM, ///< = CS_OP_IMM (立即操作码). + X86_OP_MEM, ///< = CS_OP_MEM (内存操作码). +} x86_op_type; +``` + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ + +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + + struct platform platforms[] = { + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + }; + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + insn = cs_malloc(handle); + + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s ", + insn->address, insn->mnemonic, insn->op_str); + cout << "is REG: " << cs_op_count(handle, insn, X86_OP_REG) << endl; //判断是否为寄存操作码 + cout << endl; + + printf("\n"); + cs_free(insn, 1); + cs_close(&handle); + } +} + +int main() +{ + test(); + + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/24.jpg) + + +### cs_op_index + +`int CAPSTONE_API cs_op_index(csh handle, const cs_insn *insn, unsigned int op_type, unsigned int position);` + +检索给定类型的操作数在`<arch>.operands[]`数组中的位置, 使用返回的位置访问操作数 + +注意:只有当detail选项为ON时这个API可用 (默认OFF). + +``` +handle: cs_open()返回的句柄 +insn: 从cs_disasm()或cs_disasm_iter()接收的反汇编指令结构 +op_type: 要找到的操作数类型。 +position: 要查找的操作数的位置。范围一定在`[1, cs_op_count(handle, insn, op_type)]`内 +return: 指令insn的`<arch>.operands[]`数组中给定类型op_type的操作数的索引,失败时返回-1。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +int CAPSTONE_API cs_op_index(csh ud, const cs_insn *insn, unsigned int op_type, + unsigned int post) +{ + struct cs_struct *handle; + unsigned int count = 0, i; + if (!ud) + return -1; + + handle = (struct cs_struct *)(uintptr_t)ud; + + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return -1; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return -1; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return -1; + } + + handle->errnum = CS_ERR_OK; + + switch (handle->arch) { + default: + handle->errnum = CS_ERR_HANDLE; + return -1; + case CS_ARCH_ARM: + for (i = 0; i < insn->detail->arm.op_count; i++) { + if (insn->detail->arm.operands[i].type == (arm_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_ARM64: + for (i = 0; i < insn->detail->arm64.op_count; i++) { + if (insn->detail->arm64.operands[i].type == (arm64_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_X86: + for (i = 0; i < insn->detail->x86.op_count; i++) { + if (insn->detail->x86.operands[i].type == (x86_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_MIPS: + for (i = 0; i < insn->detail->mips.op_count; i++) { + if (insn->detail->mips.operands[i].type == (mips_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_PPC: + for (i = 0; i < insn->detail->ppc.op_count; i++) { + if (insn->detail->ppc.operands[i].type == (ppc_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_SPARC: + for (i = 0; i < insn->detail->sparc.op_count; i++) { + if (insn->detail->sparc.operands[i].type == (sparc_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_SYSZ: + for (i = 0; i < insn->detail->sysz.op_count; i++) { + if (insn->detail->sysz.operands[i].type == (sysz_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_XCORE: + for (i = 0; i < insn->detail->xcore.op_count; i++) { + if (insn->detail->xcore.operands[i].type == (xcore_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_M68K: + for (i = 0; i < insn->detail->m68k.op_count; i++) { + if (insn->detail->m68k.operands[i].type == (m68k_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_TMS320C64X: + for (i = 0; i < insn->detail->tms320c64x.op_count; i++) { + if (insn->detail->tms320c64x.operands[i].type == (tms320c64x_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + case CS_ARCH_M680X: + for (i = 0; i < insn->detail->m680x.op_count; i++) { + if (insn->detail->m680x.operands[i].type == (m680x_op_type)op_type) + count++; + if (count == post) + return i; + } + break; + } + + return -1; +} +``` +</details> + + +<details><summary> 示例 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + struct platform platforms[] = { + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + }; + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + cs_x86* x86; + + int count; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + insn = cs_malloc(handle); + x86 = &(insn->detail->x86); + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s ", + insn->address, insn->mnemonic, insn->op_str); + cout << endl; + + count = cs_op_count(handle, insn, X86_OP_IMM); //查找立即数 + if (count) { + printf("\timm_count: %u\n", count); + for (i = 1; i < count + 1; i++) { + int index = cs_op_index(handle, insn, X86_OP_IMM, i); + printf("\timms[%u]: 0x%" PRIx64 "\n", i, x86->operands[index].imm); + if (x86->encoding.imm_offset != 0) { + printf("\timm_offset: 0x%x\n", x86->encoding.imm_offset); + } + if (x86->encoding.imm_size != 0) { + printf("\timm_size: 0x%x\n", x86->encoding.imm_size); + } + } + } + } + + printf("\n"); + cs_free(insn, 1); + cs_close(&handle); + } +} + +int main() +{ + test(); + return 0; +} +``` + +</details> + +输出 +![](API_Doc_Pic/25.jpg) + + +### cs_regs_access + +```cpp +cs_err CAPSTONE_API cs_regs_access(csh handle, const cs_insn *insn, + cs_regs regs_read, uint8_t *regs_read_count, + cs_regs regs_write, uint8_t *regs_write_count); +``` + +检索由一条指令显式或隐式访问的所有寄存器 + +注意: 在“diet”模式下,此API不可用,因为引擎不存储寄存器 + +``` +handle: cs_open()返回的句柄 +insn: 从cs_disasm()或cs_disasm_iter()返回的反汇编指令结构 +regs_read:返回时,这个数组包含所有按指令读取的寄存器。 +regs_read_count:保存在regs_read数组中的寄存器数。 +regs_write:返回时,这个数组包含所有由指令修改的寄存器。 +regs_write_count:保存在regs_write数组中的寄存器数。 +成功时返回CS_ERR_OK,失败时返回其他值(详细错误请参阅cs_err enum)。 +``` + +<details><summary> 源码实现 </summary> + +```cpp +cs_err CAPSTONE_API cs_regs_access(csh ud, const cs_insn *insn, + cs_regs regs_read, uint8_t *regs_read_count, + cs_regs regs_write, uint8_t *regs_write_count) +{ + struct cs_struct *handle; + + if (!ud) + return -1; + + handle = (struct cs_struct *)(uintptr_t)ud; + +#ifdef CAPSTONE_DIET + // This API does not work in DIET mode + handle->errnum = CS_ERR_DIET; + return CS_ERR_DIET; +#else + if (!handle->detail) { + handle->errnum = CS_ERR_DETAIL; + return CS_ERR_DETAIL; + } + + if (!insn->id) { + handle->errnum = CS_ERR_SKIPDATA; + return CS_ERR_SKIPDATA; + } + + if (!insn->detail) { + handle->errnum = CS_ERR_DETAIL; + return CS_ERR_DETAIL; + } + + if (handle->reg_access) { + handle->reg_access(insn, regs_read, regs_read_count, regs_write, regs_write_count); + } else { + // this arch is unsupported yet + handle->errnum = CS_ERR_ARCH; + return CS_ERR_ARCH; + } + + return CS_ERR_OK; +#endif +} +``` + +</details> + + +<details><summary> 示例 </summary> + +```cpp +#include <iostream> +#include <stdio.h> + +#include "capstone.h" +#include "platform.h" + +using namespace std; + +struct platform { + cs_arch arch; + cs_mode mode; + unsigned char* code; + size_t size; + const char* comment; + cs_opt_type opt_type; + cs_opt_value opt_value; +}; + +static void print_string_hex(unsigned char* str, size_t len) +{ + unsigned char* c; + + printf("Code: "); + for (c = str; c < str + len; c++) { + printf("0x%02x ", *c & 0xff); + } + printf("\n"); +} + +static void test() +{ +#define X86_CODE64 "\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\xea\xbe\xad\xde\xff\x25\x23\x01\x00\x00\xe8\xdf\xbe\xad\xde\x74\xff" + struct platform platforms[] = { + { + CS_ARCH_X86, + CS_MODE_64, + (unsigned char*)X86_CODE64, + sizeof(X86_CODE64) - 1, + "X86 64 (Intel syntax)" + }, + }; + + csh handle; + uint64_t address; + cs_insn* insn; + cs_detail* detail; + int i; + cs_err err; + const uint8_t* code; + size_t size; + + cs_x86* x86; + cs_regs regs_read, regs_write; + uint8_t regs_read_count, regs_write_count; + + int count; + + for (i = 0; i < sizeof(platforms) / sizeof(platforms[0]); i++) { + printf("****************\n"); + printf("Platform: %s\n", platforms[i].comment); + err = cs_open(platforms[i].arch, platforms[i].mode, &handle); + if (err) { + printf("Failed on cs_open() with error returned: %u\n", err); + abort(); + } + + if (platforms[i].opt_type) + cs_option(handle, platforms[i].opt_type, platforms[i].opt_value); + + cs_option(handle, CS_OPT_DETAIL, CS_OPT_ON); + + insn = cs_malloc(handle); + x86 = &(insn->detail->x86); + print_string_hex(platforms[i].code, platforms[i].size); + printf("Disasm:\n"); + + address = 0x1000; + code = platforms[i].code; + size = platforms[i].size; + while (cs_disasm_iter(handle, &code, &size, &address, insn)) { + int n; + + printf("0x%" PRIx64 ":\t%s\t\t%s ", + insn->address, insn->mnemonic, insn->op_str); + cout << endl; + + if (!cs_regs_access(handle, insn, //每条指令所有读取和修改的寄存器 + regs_read, ®s_read_count, + regs_write, ®s_write_count)) { + if (regs_read_count) { + printf("\tRegisters read:"); + for (i = 0; i < regs_read_count; i++) { + printf(" %s", cs_reg_name(handle, regs_read[i])); + } + printf("\n"); + } + + if (regs_write_count) { + printf("\tRegisters modified:"); + for (i = 0; i < regs_write_count; i++) { + printf(" %s", cs_reg_name(handle, regs_write[i])); + } + printf("\n"); + } + } + } + + printf("\n"); + cs_free(insn, 1); + cs_close(&handle); + } +} + +int main() +{ + test(); + return 0; +} +``` + +</details> + +输出 + +![](API_Doc_Pic/26.jpg) |