Virtualization
/
capstone
mirror of https://gitlab.com/qemu-project/capstone.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

capstone.h: add notes on cs_disasm() vs cs_disasm_iter()

This commit is contained in:
Nguyen Anh Quynh 2014-10-20 23:32:06 +08:00
parent 257ea59241
commit 024e55ebeb
1 changed files with 18 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
include/capstone.h
View File

@ -382,8 +382,17 @@ const char *cs_strerror(cs_err code);
NOTE 1: this API will automatically determine memory needed to contain NOTE 1: this API will automatically determine memory needed to contain
output disassembled instructions in @insn. output disassembled instructions in @insn.
NOTE 2: caller must free the allocated memory itself to avoid memory leaking. NOTE 2: caller must free the allocated memory itself to avoid memory leaking.
NOTE 3: for system with scarce memory to be dynamically allocated such as
OS kernel or firmware, the API cs_disasm_iter() might be a better choice than
cs_disasm(). The reason is that with cs_disasm(), based on limited available
memory, we have to calculate in advance how many instructions to be disassembled,
which complicates things. This is especially troublesome for the case @count=0,
when cs_disasm() runs uncontrolly (until either end of input buffer, or
when it encounters an invalid instruction).
@handle: handle returned by cs_open() @handle: handle returned by cs_open()
@code: buffer containing raw binary code to be disassembled. @code: buffer containing raw binary code to be disassembled.
@code_size: size of the above code buffer. @code_size: size of the above code buffer.
@ -454,6 +463,15 @@ cs_insn *cs_malloc(csh handle);
NOTE 2: the cache in @insn can be created with cs_malloc() API. NOTE 2: the cache in @insn can be created with cs_malloc() API.
NOTE 3: for system with scarce memory to be dynamically allocated such as
OS kernel or firmware, this API is recommended over cs_disasm(), which
allocates memory based on the number of instructions to be disassembled.
The reason is that with cs_disasm(), based on limited available memory,
we have to calculate in advance how many instructions to be disassembled,
which complicates things. This is especially troublesome for the case
@count=0, when cs_disasm() runs uncontrolly (until either end of input
buffer, or when it encounters an invalid instruction).
@handle: handle returned by cs_open() @handle: handle returned by cs_open()
@code: buffer containing raw binary code to be disassembled @code: buffer containing raw binary code to be disassembled
@code_size: size of above code @code_size: size of above code