Skip to content

capstone

Capstone integration

capstone_decode_block(block)

Decode a basic block with capstone

Decode an block and retry for ARM to check if the Thumb mode was activated The decoding logic is done by the inner method _decode.

Parameters:

Name Type Description Default
inst

Block to translate

 required

Returns:

Type Description
list[CsInsn]

A list of capstone instructions if they have been decoded
Source code in bindings/python/quokka/backends/capstone.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def capstone_decode_block(
    block: quokka.Block,
) -> list[capstone.CsInsn]:
    """Decode a basic block with capstone

    Decode an block and retry for ARM to check if the Thumb mode was activated
    The decoding logic is done by the inner method `_decode`.

    Arguments:
        inst: Block to translate

    Returns:
        A list of capstone instructions if they have been decoded
    """

    context: capstone.Cs = _update_capstone_context(block.program, block.is_thumb)
    capstone_inst = _decode(context, block.bytes, block.address, count=0)

    if not capstone_inst and context.arch == capstone.CS_ARCH_ARM:
        if context.mode == capstone.CS_MODE_THUMB:
            new_context = get_capstone_context(quokka.analysis.ArchARM)
        else:
            new_context = get_capstone_context(quokka.analysis.ArchARMThumb)

        capstone_inst = _decode(new_context, block.bytes, block.address, count=0)
    return capstone_inst

capstone_decode_instruction(inst)

Decode an instruction with capstone

Decode an instruction and retry for ARM to check if the Thumb mode was activated The decoding logic is done by the inner method _decode.

Parameters:

Name Type Description Default
inst Instruction

Instruction to translate

 required

Returns:

Type Description
CsInsn | None

A capstone instruction if it has been decoded
Source code in bindings/python/quokka/backends/capstone.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def capstone_decode_instruction(inst: quokka.Instruction) -> capstone.CsInsn|None:
    """Decode an instruction with capstone

    Decode an instruction and retry for ARM to check if the Thumb mode was activated
    The decoding logic is done by the inner method `_decode`.

    Arguments:
        inst: Instruction to translate

    Returns:
        A capstone instruction if it has been decoded
    """

    context: capstone.Cs = _update_capstone_context(inst.program, inst.is_thumb)
    capstone_inst = _decode(context, inst.bytes, inst.address, count=1)

    if not capstone_inst and context.arch == capstone.CS_ARCH_ARM:
        if context.mode == capstone.CS_MODE_THUMB:
            new_context = get_capstone_context(quokka.analysis.ArchARM)
        else:
            new_context = get_capstone_context(quokka.analysis.ArchARMThumb)

        capstone_inst = _decode(new_context, inst.bytes, inst.address, count=1)

    return capstone_inst[0] if capstone_inst else None

get_capstone_context(arch, endian=Endianness.LITTLE_ENDIAN)

Compute the capstone context for the program

The Capstone context is used to decode instructions afterwards. Since we are interested in most of the details, we already set the details to True.

Parameters:

Name Type Description Default
arch Type[QuokkaArch]

Quokka program architecture

 required

Returns:

Type Description
Cs

A capstone Cs instance
Source code in bindings/python/quokka/backends/capstone.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def get_capstone_context(
        arch: Type[quokka.analysis.QuokkaArch],
        endian: Type[Endianness] = Endianness.LITTLE_ENDIAN) -> capstone.Cs:
    """Compute the capstone context for the program

    The Capstone context is used to decode instructions afterwards. Since we are
    interested in most of the details, we already set the details to True.

    Arguments:
        arch: Quokka program architecture

    Returns:
        A capstone Cs instance
    """
    endian_mapping = {
        Endianness.BIG_ENDIAN: capstone.CS_MODE_BIG_ENDIAN,
        Endianness.LITTLE_ENDIAN: capstone.CS_MODE_LITTLE_ENDIAN,
    }
    capstone_endian = endian_mapping[endian]

    mapping = {
        quokka.analysis.ArchARM: (capstone.CS_ARCH_ARM, capstone.CS_MODE_ARM),
        quokka.analysis.ArchARM64: (capstone.CS_ARCH_ARM64, capstone.CS_MODE_ARM),
        quokka.analysis.ArchX86: (capstone.CS_ARCH_X86, capstone.CS_MODE_32),
        quokka.analysis.ArchX64: (capstone.CS_ARCH_X86, capstone.CS_MODE_64),
        quokka.analysis.ArchARMThumb: (
            capstone.CS_ARCH_ARM,
            capstone.CS_MODE_THUMB,
        ),
        quokka.analysis.ArchMIPS: (
            capstone.CS_ARCH_MIPS,
            capstone.CS_MODE_32 + capstone_endian),
        quokka.analysis.ArchMIPS64: (
            capstone.CS_ARCH_MIPS,
            capstone.CS_MODE_64 + capstone_endian),
        quokka.analysis.ArchPPC: (
            capstone.CS_ARCH_PPC,
            capstone.CS_MODE_32 + capstone_endian),
        quokka.analysis.ArchPPC64: (
            capstone.CS_ARCH_PPC,
            capstone.CS_MODE_64 + capstone_endian),
    }

    try:
        capstone_arch, capstone_mode = mapping.get(arch)
    except TypeError as exc:
        raise quokka.CapstoneError("Unable to find the Architecture") from exc

    context = capstone.Cs(capstone_arch, capstone_mode)
    context.detail = True

    return context