Customize instruction mnemonic

Customize instruction mnemonic at run-time

1. Setup Capstone to customize mnemonic

In some architectures, an instruction might have alternative mnemonic. Example is the JNE instruction on X86: this is also called JNZ by some disassemblers. The problem is that all the mnemonics are fixed in the engine and cannot be customized. For this reason, some disassembly tools built on top of Capstone have to use some tricks to modify mnemonics at the output for what they desire.

This has been changed with a new option CS_OPT_MNEMONIC (available in the Github branch next now, and will be ready when version 4.0 is out). Use this option with cs_option() to customize instruction mnemonics, as in the sample C code below.

1
2
3
4
5
6
7
8
9
10
csh handle;

// Customize mnemonic JNE to "jnz"
cs_opt_mnem my_mnem = { X86_INS_JNE, "jnz" };

if (cs_open(CS_ARCH_X86, CS_MODE_32, &handle) == CS_ERR_OK) {
    cs_option(handle, CS_OPT_MNEMONIC, (size_t)&my_mnem);
    // from here onwards, disassembling will give JNE a mnemonic "jnz"
    // ...
}

Below is the explanation for important lines of the above C sample.

Line 4: Declare variables my_mnem of data type cs_opt_mnem to customize JNE instruction (indicated by X86_INS_JNE) to have mnemonic “jnz”.
Line 6: Initialize X86 engine of 32-bit mode.
Line 7: Call cs_option with option CS_OPT_MNEMONIC, and pass the address of my_mnem in the third parameter. After this, we can start disassembling and instruction JNE will have “jnz” mnemonic, rather than the default value “jne”.

The below Python code does the same thing as the above C sample. The only important difference is that we use method mnemonic_setup() to customize the menemonic of JNE instruction in line 5.

1
2
3
4
5
from capstone import *
from capstone.x86 import *

md = Cs(CS_ARCH_X86, CS_MODE_32)
md.mnemonic_setup(X86_INS_JNE, "jnz")

Finally, note that while the above samples are for X86, the same technique can be applied for all other architectures supported by Capstone. Because we can run cs_option(CS_OPT_MNEMONIC) as many times as we want, there is no limitation on the number of instructions we can customize.

2. Reset Capstone to the default mnemonic

After customizing instruction mnemonic as in section 1 above, we can always reset Capstone to the default mnemonic, as in the sample C code below.

1
2
3
4
5
// Reset instruction JNE to use its default mnemonic
cs_opt_mnem default_mnem = { X86_INS_JNE, NULL };

cs_option(handle, CS_OPT_MNEMONIC, (size_t)&default_mnem);
// from here onwards, our engine will switch back to the default mnemonic "jne" for JNE.

Basically, rather than using a string for the mnemonic, we pass the value NULL in line 2 when declaring the cs_opt_mnem structure.

The below Python sample does the same thing to reset the engine, which is self explanatory.

1
md.mnemonic_setup(X86_INS_JNE, None)

3. More examples

Find the full samples on how to use CS_OPT_MNEMONIC in the source of test_x86.c or test_x86.py.

When running these samples, the output is as follows.

Disassemble X86 code with default instruction mnemonic
75 01		jne	0x1003

Now customize engine to change mnemonic from 'JNE' to 'JNZ'
75 01		jnz	0x1003

Reset engine to use the default mnemonic
75 01		jne	0x1003