instruction ¤

The underlying Capstone instruction object. Only the enhancement code should access the 'cs_insn' property

Length of the instruction

Ex: 'MOV'

Ex: 'RAX, RDX'

Capstone instruction groups that we belong to. Groups that apply to all architectures: CS_GRP_INVALID | CS_GRP_JUMP | CS_GRP_CALL | CS_GRP_RET | CS_GRP_INT | CS_GRP_IRET | CS_GRP_PRIVILEGE | CS_GRP_BRANCH_RELATIVE

The underlying Capstone ID for the instruction If it's an alias, use the id of the alias

Examples: X86_INS_JMP, X86_INS_CALL, RISCV_INS_C_JAL

The full string representing the instruction - mov rdi, rsp with appropriate padding.

This is syntax highlighted during enhancement.

This is additionally modified during enhancement for the purposes of replacing immediate values with their corresponding symbols

This is the address that the instruction pointer will be set to after using the "nexti" GDB command. This means it is the address of the next instruction to be executed in all cases except "call" instructions.

Typically, it is self.address + self.size (the next instruction in memory)

If it is a jump and we know it is taken, then it is the value of the jump target.

Not set to "call" instruction targets, to indicate we will eventually (probably) return to this address

This is target of instructions that change the PC, regardless of if it's conditional or not, and whether or not we take the jump. This includes "call" and all other instructions that set the PC

If the instruction is not one that changes the PC, target is set to "next"

String representation of the target address.

Colorized symbol if a symbol exists at address, else colorized address

Whether the target is a constant expression

Does the condition that the instruction checks for pass?

For example, "JNE" jumps if Zero Flag is 0, else it does nothing. "CMOVA" conditionally performs a move depending on a flag. See 'condition' function in pwndbg.aglib.disasm.x86 for example on setting this.

UNDETERMINED if we cannot reason about the condition, or if the instruction always executes unconditionally (most instructions).

TRUE if the instruction has a conditional action, and we determine it is taken.

FALSE if the instruction has a conditional action, and we know it is not taken.

This field is used to declare if the instruction is a conditional instruction. In most cases, we can determine this purely based on the instruction ID, and this field is irrelevent. However, in some arches, like Arm, the same instruction can be made conditional by certain instruction attributes. Ex: Arm, bls instruction. This is encoded as a b under the code, with an additional condition code field. In this case, sometimes a b instruction is unconditional (always branches), in other cases it is conditional. We use this field to disambiguate these cases.

True if we manually determine this instruction is a conditional instruction False if it's not a conditional instruction None if we don't have a determination (most cases)

This field is used to declare that this instruction is an unconditional jump. Most of the time, we depend on Capstone groups to check for jump instructions. However, some instructions become branches depending on the operands, such as Arm add, sub, ldr, pop, where PC is the destination register

In these cases, we want to forcefully state that this instruction mutates the PC, so we set this attribute to True.

This helps in two cases: 1. Disassembly splits 2. Instructions like stepuntilasm work better, as they detect these as branches to stop at.

This asserts that the .target attribute is the real target of the instruction. This is only relevent in the edge case that the target is the next instruction in memory (address + size). The normal check for "target" checks that the target is NOT the next address in memory, and here we can assert that even if that is the case, we know that the jump really does just go to where self.target is.

The string is set in the "DisassemblyAssistant.enhance" function. It is used in the disasm print view to add context to the instruction, mostly operand value. This string is not used for all cases - if the instruction is a call or a jump, the 'target'. variables is used instead. See 'pwndbg.color.disasm.instruction()' for specific usage.

The left adjustment padding that was used to previously print this. We retain it so the output is consistent between prints

The syscall number for this instruction, if it is a syscall. Otherwise None.

The syscall name as a string

Ex: "openat", "read"

Whether or not this instruction has a single branch delay slot

The type of split in the disasm display this instruction causes:

NO_SPLIT            - no extra spacing between this and the next instruction
BRANCH_TAKEN        - a newline with an arrow pointing down
BRANCH_NOT_TAKEN    - an empty newline

If the enhancement successfully used emulation for this instruction

True if this is a call-like instruction, meaning either it's a CALL or a branch and link.

Checking for the CS_GRP_CALL is insufficient, as there are many "branch and link" instructions that are not labeled as a call

True if this instruction is "jump-like", such as a JUMP, CALL, or RET. Basically, the PC is set to some target by means of this instruction.

It may still be a conditional jump - this property does not indicate whether the jump is taken or not.

True if we have determined that this instruction can explicitly change the program counter, and we have determined the jump target.

Edge case - the jump target MAY be the next address in memory - so we check force_unconditional_jump_target

True if this instruction can change the program counter conditionally.

This is used, in part, to determine if the instruction deserves a "checkmark" in the disasm view.

This does not imply that we have resolved the .target

True if we know the instruction can change the program counter, and does so unconditionally.

This includes things like RET, CALL, and JMP (in x86).

This property is used in enhancement to determine certain codepaths when resolving .next for this instruction.

This does not imply that we have resolved the .target

True if this is a conditional jump, and we predicted that we will take the jump

Raw machine instruction bytes

Underlying Capstone operand. Takes on a different value depending on the architecture.

x86 = capstone.x86.X86Op, arm = capstone.arm.ArmOp, mips = capstone.mips.MipsOp

The value of the operand before the instruction executes. This is set only if the operand value can be reasoned about.

The value of the operand after the instruction executes. Only set when using emulation.

The 'resolved' value of the operand that is actually used in the instruction logic, before the instruction executes. This is the same as before_value if it's not a memory operand, in which cases it's the dereferenced value.

Helpful for cases like cmp byte ptr [rip + 0x166669], 0, where first operand could be a register or a memory value to dereference, and we want the actual value used.

This is a special field used in some architectures that allow operand modifiers, such as shifts and extends in Arm. Capstone bundles the modifier with the operand, and when we are resolving concrete operand values, we apply the modifier. However, in some annotations we need to un-modified raw register value, which is what this field is for.

The 'resolved' value of the operand after the instruction executes.

String representing the operand

Ex: "RAX", or "[0x7fffffffd9e8]". None if value cannot be determined.

Colorized symbol name for this operand, if .before_value is set and symbol exists, else None.

CS_OP_REG | CS_OP_MEM | CS_OP_IMM | CS_OP_INVALID | CS_OP_FP

The underlying Capstone ID for the register

The immediate value of the operand (if applicable)

Return the underlying Capstone mem object (if applicable)