capstone

mirror of https://github.com/capstone-engine/capstone.git synced 2024-11-23 05:29:53 +00:00

This page details all the changes in 2.0 version, which was release Jan 22nd, 2014

NOTE: changes are listed in order: newer changes are at the top, older changes are at the bottom.

Capstone now can compile/install on all *nix, including Linux, OSX, *BSD & Solaris 11.

The API version was bumped from 1.0 to 2.0 due to lots of changes in this version.

Python binding now supports Cython compiler, which significantly improves the performance. Some benchmarks report that this is 30% faster than pure Python binding. The exact number depends on cases and running platforms, however.

To install this Cython binding, Cython must be installed, recommended via pip or easy_install for newer version.

$ sudo pip install cython    # or  sudo easy_install cython
$ cd bindings/python
$ sudo make install_cython

The benchmark tool can be found in suite/benchmark.py

- **Big-endian** support for *Arm* & *Arm64* has been added.
- The **detail** option is **OFF** by default now. So you need to explicitly turn it *ON* if you need detail information.

See http://capstone-engine.org/documentation.html, or sample code in main repo (test*.c for C code, test*.py for Python, Test*.java for Java) for how to do that.

- New option **CS_OPT_MEM** let you specify your own functions for dynamically memory management used internally by Capstone. By default, we just use system's functions: *malloc()*, *calloc()*, *realloc()*, *free()* & *vsnprintf()* (vsnprintf() is involved because it might call malloc() internally)
- **PowerPC** architecture is supported. So Capstone can disassemble 5 archs now: Arm, Arm64, Mips, PPC & X86.
- New API **cs_strerror(errno)** returns a string describing error code given in its only argument. This API should get the error code from the output of *cs_errno()*, and behaves similarly to the POSIX's *strerror()*.
- Fixed some installation issues for Gentoo.

Python binding: cs_disasm_quick() & Cs.disasm() now use generator (rather than a list) to return the disassembled instructions. This is to improve the performance, and reduce memory usage for Python code.

For information of structure cs_insn, all the fields that are only available when CS_OPT_DETAIL is set to CS_OPT_ON now must be accessed through a newly added detail pointer. The list of these fields are regs_read, regs_read_count, regs_write, regs_write_count, groups, groups_count and also union fields arm, arm64, mips & x86.

For example, if before your code access to regs_read_count like:

        if (insn.regs_read_count > 0)

Then now your code must be rewritten as below to access the same field through the detail pointer:

        if (insn.detail->regs_read_count > 0)

**NOTE**: You only need to care about this change if you write *C program*, but all of these changes are *hidden away* in all the bindings (Python, Ruby, Java, etc), so your code written with these bindings need absolutely *no change*.

New API added: cs_support() can be used to check if this lib supports a particular arch, like below:

        if (cs_support(CS_ARCH_ARM64)) {
             // so this library supports ARM64
        }

In case you want to check if this lib supports all archs, use the newly added CS_ARCH_ALL instead:

        if (cs_support(CS_ARCH_ALL)) {
             // cool, this library supports everything: ARM+ARM64+MIPS+X86
        }

Change API: cs_version() now returns combined version which encodes both major & minor versions. Thanks to this, now we can check if current API version is at least from 1.1 or newer, like below (C code):

        // check if this version is not older than 1.1
        if (cs_version(&major, &minor) >= 0x0101) {
            // do something
        }

In case all you need is the returned combined version, set both arguments of cs_version() to NULL:

        // check if this version is not older than 1.1
        if (cs_version(NULL, NULL) >= 0x0101) {
            // do something
        }

User now can choose which archs to be supported by modifying config.mk file before compiling/installing. This is handy when you want to make the library smaller, so you can embed libcapstone into your projects.

By default, we still compile all archs like before.

See file COMPILE for updated information on how to compile with config.mk

Some small changes was made in internal structures but managed to make library size significantly smaller: around 40%.

Before this, libcapstone.so was about 5.6MB. Now it is only 3.2MB

- Dynamically change engine's mode at run-time

In 1.0 version we specify the engine's mode with cs_open() and from then on we cannot change the mode. I have added a new CS_OPT_MODE option, so that now we can change engine's mode at run-time.

This is useful for example with Arm, where we want to switch between Arm & Thumb mode without having to create a new engine. This also happens with X86, where we might want to switch back and forth between protected-mode code & real-mode code.

Below sample code (in Python) proves how this new CS_OPT_MODE works (you dont see CS_OPT_MODE here since it is hidden behind Python setter):

        md = Cs(CS_ARCH_ARM, CS_MODE_ARM)
        # from now on disasm Arm code ....
        md.mode = CS_MODE_THUMB
        # from now on disasm Thumb code ....
        md.mode = CS_MODE_ARM
        # switch back to Arm code again

Sample C code will be like this:

        cs_open(CS_ARCH_ARM, CS_MODE_ARM, &handle);
        // from now on disasm Arm code ....
        cs_option(handle, CS_OPT_MODE, CS_MODE_THUMB)
        // from now on disasm Thumb code ....
        cs_option(handle, CS_OPT_MODE, CS_MODE_ARM)
        // switch back to Arm code again

- Mips: support friendly register names

Thanks to this, instead of output as srl $2, $1, 0x1f, now we have srl $v0, $at, 0x1f

- ARM: support friendly alias register names

Thanks to this, instead of output as sub r12, r11, 0x14, now we have sub ip, fp, 0x14