Instr

Instr

Instr class is the representation of a CPU instruction.

Table of Contents

• Constructors
  • FromAddr
  • FromParts
• Properties
• Testers
  • needModRM
  • isReversed
  • hasAddrOvrd
  • hasOperOvrd
• Calculators
  • calcImmSize
  • calcTgtAddr
  • getNext
• Modifiers
  • moveToNext
  • addPrefix
  • addOpCode
• Overrides
  • toString

Constructors

While you can use the new keyword to create instances of this class. It is not advisable since it is a little tedious. Instead the following 2 functions have been provided to work as 'constructors'.

FromAddr

This is the more commonly used function in scripts. It extracts the instruction at the specified address in the Exe.

Syntax:

Instr.FromAddr(addr, [reflect])
Instr.FromAddr(addr, addrType, [reflect])
Instr.FromAddr(addr, result, [reflect])
Instr.FromAddr(addr, addrType, result, [reflect])

Argument	Description
addr	The address to extract from
addrType	Optional AddrType of the address specified. If omitted, it is considered to be the PHYSICAL address.
result	Optional holder for the resulting Instr object. This is useful if you wish to alter an existing object instead of creating a new one.
reflect	Optional boolean indicating whether changes from patches need to be 'reflected'. If omitted, reflection is not done.

FromParts

This is mostly used internally by the [Instruction generators]. It constructs the object using specific data as described below.

Syntax:

Instr.FromParts(data, code, oper)

Argument	Description
data	An OpData object describing the various arguments & prefixes used in the instruction.
code	The opcode or list of opcodes (for multi-byte opcode instruction).
oper	The operation number (only needed for certain instructions.

Properties

Property name	Description
Addr	The Exe address from where this instruction was extracted. Set to -1 if created FromParts.
Prefixes	List of prefix bytes.
Codes	List of opcode bytes.
MRM	The extracted/calculated ModRM object.
SIB	The extracted/calculated SIBase object.
Disp	The displacement value used for any memory pointers. It can be undefined.
BC_Disp	The byte count of the displacement. The default is 0 for no displacement.
Immd	The immediate value used. It can be undefined.
BC_Immd	The byte count of the immediate value. The default is 0 for no immediates.
SegNum	Segment number for FAR type instructions. It can be undefined.
NestLvl	Nesting level used for ENTER instruction. It can be undefined.
Size	The total size of the instruction in bytes.
NextAddr	The address for the next instruction. Only becomes valid if Addr is valid.

Testers

These functions check for some aspects of the object.

needModRM

Checks if the instruction requires a ModRM object.

Syntax:

<obj>.needModRM()

Result: true or false

isReversed

Checks if the instruction has to reverse its argument order.

Syntax:

<obj>.isReversed()

Result: true or false

hasAddrOvrd

Checks if the instruction has an address override prefix (AD16)

Syntax:

<obj>.hasAddrOvrd()

Result: true or false

hasOperOvrd

Checks if the instruction has an operand override prefix (OPCH).

Syntax:

<obj>.hasOperOvrd()

Result: true or false

Calculators

calcImmSize

Calculates the size of immediate value expected. BC_Immd property is set to the calculated value.

Syntax:

<obj>.calcImmSize()

Result: the calculated size

calcTgtAddr

Calculates the target VIRTUAL address (assuming the instruction is a direct CALL or one of the Jumps).

Syntax:

<obj>.calcTgtAddr()

Result: the calculated address

getNext

Extracts the instruction from an address relative to the NextAddr and returns it's Instr object.

Syntax:

<obj>.getNext([offset])

Argument	Description
offset	The offset relative to the NextAddr from where we need to extract. If omitted, offset is considered 0 i.e. the very next instruction is extracted.

Returns: the extracted Instr object

Modifiers

These functions modify the members of the Instr object being used.

moveToNext

It works identical to getNext, but the current Instr object is updated instead.

Syntax:

<obj>.moveToNext([offset])

Argument	Description
offset	The offset relative to the NextAddr from where we need to extract. If omitted, offset is considered 0 i.e. the very next instruction is extracted.

Returns: the updated Instr object itself

addPrefix

Adds an instruction prefix to the Instr object. If an array of values are specified, then the entire prefix set is replaced.

Syntax:

<obj>.addPrefix(p)

Argument	Description
p	Either the IPrefix object, it's underlying value or an array of prefixes.

Returns: the updated Instr object itself

addOpCode

Adds the opcode byte(s) to the Instr object. If an array of opcodes are specified, then the entire opcode set is replaced.

Syntax:

<obj>.addOpCode(o)

Argument	Description
o	The opcode byte or an array of opcodes.

Returns: the updated Instr object itself

Overrides

toString

Override of the toString function to construct the hex equivalent of the Instr object.

Usage of the object in a string context will automatically invoke this function. (For e.g. while constructing new code to be inserted.)

Syntax:

<obj>.toString()

Returns: the hex equivalent

Return to top

Further reading

• Inbuilt API
• Scripted API
• Writing scripts