Instructions & Operands

Instructions are represented by BipInstr objects. They inherit from BipElt and as such have access to xrefs and common methods for objects with an address. They are also link to their function (func()) and basic block (block()) if any. Finally an instruction can have BipOperand which can be access using the ops() property.

The BipOperand class represent all types of operand. As this is not the common design for Bip this will probably be changed soon. For getting the type of an operand the type() property can be used and compare with the value of BipOpType. The value() allow to recuperate the value of an operand, the meaning of this value is depending of its type() and can be architectures dependant. This is not implemented yet and so is still link to information provided by IDA.

BipInstr API

class bip.base.BipInstr(ea=None)

Class for representing and manipulating a assembleur instruction in IDA.

UA_MAXOP = 8

Maximum number of operands for one instruction

__init__(ea=None)

Constructor for an instruction in IDA.

Parameters:ea (int) – The address of the instruction in IDA. If None the screen address is taken.

str

Property returning a string representing the complete instruction.

Returns:A representation of the complete instruction. Return type:str

mnem

Property which allow to get the mnemonic of the instruction.

Returns:The mnemonic of the instruction Return type:str

_insn

Property which return an insn_t representing the instruction as provided by IDA.

There is no reason to use this except for interfacing directly with IDA functions.

This is use internally by other functions.

__str__() <==> str(x)

countOperand

Property which return the number of operand for the instruction.

op(num)

Method for recuperating an BipOperand object.

Parameters:num (int) – The position of the operand. Raises:ValueError – If the position is not valid.

ops

Property returning a list of the operands of the instruction.

Returns:A list of BipOperand .

has_prev_instr

Property indicating if this instruction follow an other normal instruction (part of its flow). Wrapper on idc.is_flow .

is_call

Property indicating if this instruction is a call.

Return bool:True if this instruction is a call, False otherwise.

is_ret

Property indicating if this instruction is a ret.

Return bool:True if this instruction is a ret, False otherwise.

is_indirect_jmp

Property indicating if this instruction is an indirect jump (such as on a register or from the value of memory).

Return bool:True if this instruction is a indirect jmp, False otherwise.

is_end_block

Property indicating if this instruction is the end of a basic block. This property will return False if the instruction is a call which does not end a block such as display by IDA, see is_end_block_call() for returning True on call.

Return bool:True if this instruction is the last one for a block.

is_end_block_call

Property indicating if this instruction is the end of a basic block. This property will return True if the instruction is a call, see is_end_block() for returning False on call which are not at the end of a block.

Return bool:True if this instruction is the last one for a block, including the case when it is a call.

is_in_func

Property which return True if this instruction is inside a function.

prev

Property returning the instruction which preceed in the normal flow of execution the current instruction (no handle of jmp, call, …). It is possible for an instruction to not have a previous instruction typically at the start of a function but in other cases too. This can be tested with has_prev_instr() .

Returns:The previous instruction if any. Return type:BipInstr or None

next

The instruction following the current one. It is important to notice it will not always be the next instruction in the control flow.

If the next element is not an instruction (for example at the end of a function followed by data) None will be returned.

Returns:The next BipInstr or None in case of error.

classmethod _is_this_elt(ea)

Class method which allow the function GetElt() to know if this the correct type for an address. Only subclasses of an element which return True will be tested by GetElt(), BipBaseElt return always True except if idelt is not of the correct type.

Parameters:idelt (int) – An id representing the element, typically an address. Returns:True if this is a valid class for constructing this element.

block

Return the BipBlock in which this instruction is included.

This instruction will raise an exception if the instruction is not included an IDA basic block. See BipBlock for more information.

Returns:An BipBlock object containing this instruction.

func

Return the BipFunction in which this instruction is included.

This will raise a ValueError if the instruction is not in a defined function.

Returns:An BipFunction object containing this instruction.

xOrdinaryCfNext

Property returning the next instruction in the control flow. This may return None in several case such as ret or a non-conditional jmp .

Note

This can be simply handle because of things like a switch/jmp table.

Returns:BipInstr for the next instruction in the control flow or None .

xCfNext

Property allowing access to instructions which can follow in the control flow. This will take call, jmp and ordinary flow into account.

Returns:A list of BipInstr for the next possible intructions.

xCfPrev

Property allowing access to instructions which can lead to the current instructions. This will take call, jmp and ordinary flow into account.

classmethod make(ea=None)

Class method for defining an instruction. If auto-analysis is enable in IDA this may define also the following instructions. If the instruction is already define, this instruction just returns it.

Parameters:ea – The address at which to define the instruction, if None the current screen address is used. Returns:The BipInstr for this address. Raises:RuntimeError – If it was not possible to define the address as code.

BipOperand API

Warning

This API will probably change in the near future.

class bip.base.BipOperand(ins, num)

Class representing an operand of an instruction. This class should be used through BipInstr .

Todo

make test property depending of type

Todo

make subclass by type of operand ?

Todo

support .reg and other stuff like that

Todo

hex((i.Op2.specval >> 0x10) & 0xFF) give the segment

Todo

make pretty printing function if possible

instr = None

Instruction containing the operand

opnum = None

The position of the operand in the instruction

ea

Property allowing to get the address of the instruction containing this operand.

Returns:The address of the instruction. Return type:int or long

str

Property allowing to get the representation of the operand as a string. Wrapper on idc.GetOpnd (old) or idc.print_operand (new) .

Returns:The representation of the operand. Return type:str

type

Property allowing to get the type of the operand. This type correspond to the BipOpType value . Wrapper on idc.GetOpType (old) or idc.get_operand_type (new).

Returns:The type of the operand as defined in BipOpType . Return type:int

dtype

Property which allow to get the type of the operand value. Those can be access through the BipDestOpType enum. This is is equivalent to accessing the op_t.dtype from IDA.

Return int:The type of the destination of the operand as defined in BipDestOpType.

type_info

Property which allow to get the information on the type of the operand if defined. This will return an object which inherit from BipType if defined or None if not.

Note

By default this does not seems to be defined by IDA.

Returns:A BipType object defined for this operand or None if it was not defined.

value

Property allowing to get the value of an operand. Depending of the type of the operand this value can means different things. For an immediate the value return as a mask apply for getting only the number of bytes of the asm value and not the signed extended returned by IDA.

Todo

Look at idc.get_operand_value, somethings may need change here.

Todo

Support the dtype for other things than immediate (such as float).

Todo

Support all of the dtype for immediate

Returns:The value of the operand. Return type:int

is_void

Test if this object represent the fact that there is no operand. (BipOpType.VOID)

is_reg

Test if the operand represent a register. (BipOpType.REG)

is_memref

Test if the operand is a memory reference (one of MEM, PHRASE or DISPL in BipOpType)

is_imm

Test if the operand is an immediate value which is not an address (BipOpType.IMM).

is_addr

Test if the operand represent an address, far or near. (one of FAR or NEAR in BipOpType).

is_proc_specific

Test if this operand is processor specific.

set_offset(base=0)

Set this operand as being an offset.

Todo

this should be a setter on a property ?

Todo

doc base arg

class bip.base.BipOpType

Static class allowing to get the type of the operands as define in the ua.hpp file from hexrays. This is equivalent to the idc.o_* values.

VOID = 0

No Operand.

REG = 1

General Register (al,ax,es,ds…).

MEM = 2

Direct Memory Reference (DATA).

PHRASE = 3

Memory Ref [Base Reg + Index Reg].

DISPL = 4

Memory Reg [Base Reg + Index Reg + Displacement].

IMM = 5

Immediate Value.

FAR = 6

Immediate Far Address (CODE).

NEAR = 7

Immediate Near Address (CODE).

IDPSPEC0 = 8

processor specific type.

IDPSPEC1 = 9

processor specific type.

IDPSPEC2 = 10

processor specific type.

IDPSPEC3 = 11

processor specific type.

IDPSPEC4 = 12

processor specific type.

IDPSPEC5 = 13

processor specific type.

class bip.base.BipDestOpType

Static class representing an enum of the dt_* macro from IDA indicating the type of the operand value.

Defined in ua.hpp in IDA.

DT_BYTE = 0

8 bit

DT_WORD = 1

16 bit

DT_DWORD = 2

32 bit

DT_FLOAT = 3

4 byte

DT_DOUBLE = 4

8 byte

DT_TBYTE = 5

variable size

DT_PACKREAL = 6

packed real format for mc68040

DT_QWORD = 7

64 bit

DT_BYTE16 = 8

128 bit

DT_CODE = 9

ptr to code (not used?)

DT_VOID = 10

none

DT_FWORD = 11

48 bit

DT_BITFILD = 12

bit field (mc680x0)

DT_STRING = 13

pointer to asciiz string

DT_UNICODE = 14

pointer to unicode string

DT_LDBL = 15

long double (which may be different from tbyte)

DT_BYTE32 = 16

256 bit

DT_BYTE64 = 17

512 bit