# Copyright (c) 2018-2026 Vector 35 Inc

#

# Permission is hereby granted, free of charge, to any person obtaining a copy

# of this software and associated documentation files (the "Software"), to

# deal in the Software without restriction, including without limitation the

# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

# sell copies of the Software, and to permit persons to whom the Software is

# furnished to do so, subject to the following conditions:

#

# The above copyright notice and this permission notice shall be included in

# all copies or substantial portions of the Software.

#

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS

# IN THE SOFTWARE.

import ctypes

import struct

from typing import (Optional, List, Union, Mapping, MutableMapping,

Generator, NewType, Tuple, ClassVar, Dict, Set, Callable, Any, Iterator, overload)

from dataclasses import dataclass

from . import deprecation

# Binary Ninja components

from . import _binaryninjacore as core

from .enums import MediumLevelILOperation, ILBranchDependence, DataFlowQueryOption, FunctionGraphType, DeadStoreElimination, ILInstructionAttribute, StringType

from . import basicblock

from . import function

from . import types

from . import lowlevelil

from . import highlevelil

from . import flowgraph

from . import variable

from . import architecture

from . import binaryview

from . import types as _types

from .interaction import show_graph_report

from .commonil import (

BaseILInstruction, Constant, BinaryOperation, UnaryOperation, Comparison, SSA, Phi, FloatingPoint, ControlFlow,

Terminal, Call, Localcall, Syscall, Tailcall, Return, Signed, Arithmetic, Carry, DoublePrecision, Memory, Load,

Store, RegisterStack, SetVar, Intrinsic, VariableInstruction, SSAVariableInstruction, AliasedVariableInstruction,

ILSourceLocation, invalid_il_index

)

TokenList = List['function.InstructionTextToken']

ExpressionIndex = NewType('ExpressionIndex', int)

InstructionIndex = NewType('InstructionIndex', int)

Index = Union[ExpressionIndex, InstructionIndex]

InstructionOrExpression = Union['MediumLevelILInstruction', Index]

MLILInstructionsType = Generator['MediumLevelILInstruction', None, None]

MLILBasicBlocksType = Generator['MediumLevelILBasicBlock', None, None]

OperandsType = Tuple[ExpressionIndex, ExpressionIndex, ExpressionIndex, ExpressionIndex, ExpressionIndex]

MediumLevelILOperandType = Union[int, float, 'MediumLevelILOperationAndSize', 'MediumLevelILInstruction',

'lowlevelil.ILIntrinsic', 'variable.Variable', 'SSAVariable', List[int],

List['variable.Variable'], List['SSAVariable'], List['MediumLevelILInstruction'],

Dict[int, int], 'variable.ConstantData']

MediumLevelILVisitorCallback = Callable[[str, MediumLevelILOperandType, str, Optional['MediumLevelILInstruction']], bool]

StringOrType = Union[str, '_types.Type', '_types.TypeBuilder']

ILInstructionAttributeSet = Union[Set[ILInstructionAttribute], List[ILInstructionAttribute]]

LLILSSAToMLILInstructionMapping = MutableMapping['lowlevelil.InstructionIndex', InstructionIndex]

CallOutputList = Union[List[ExpressionIndex], List['variable.CoreVariable']]

@dataclass(frozen=True)

class LLILSSAToMLILExpressionMap:

lower_index: 'lowlevelil.ExpressionIndex'

higher_index: ExpressionIndex

map_lower_to_higher: bool

map_higher_to_lower: bool

lower_to_higher_direct: bool

higher_to_lower_direct: bool

def _to_core_struct(self):

result = core.BNExprMapInfo()

result.lowerIndex = self.lower_index

result.higherIndex = self.higher_index

result.mapLowerToHigher = self.map_lower_to_higher

result.mapHigherToLower = self.map_higher_to_lower

result.lowerToHigherDirect = self.lower_to_higher_direct

result.higherToLowerDirect = self.higher_to_lower_direct

return result

LLILSSAToMLILExpressionMapping = List['LLILSSAToMLILExpressionMap']

@dataclass(frozen=True, repr=False, order=True)

class SSAVariable:

var: 'variable.Variable'

version: int

def __repr__(self):

return f"<SSAVariable: {self.var} version {self.version}>"

@property

def name(self) -> str:

return self.var.name

@property

def type(self) -> 'types.Type':

return self.var.type

@property

def function(self) -> 'function.Function':

"""returns the source Function object which this variable belongs to"""

return self.var.function

@property

def il_function(self) -> 'function.ILFunctionType':

"""returns the il Function object which this variable belongs to"""

return self.var._il_function

@property

def dead_store_elimination(self) -> DeadStoreElimination:

"""returns the dead store elimination setting for this variable (read-only)"""

return self.var.dead_store_elimination

@property

def def_site(self) -> Optional[Union['MediumLevelILInstruction', 'highlevelil.HighLevelILInstruction']]:

"""

Gets the IL instructions where this SSAVariable is defined.

"""

return self.il_function.get_ssa_var_definition(self)

@property

def use_sites(self) -> List[Union['MediumLevelILInstruction', 'highlevelil.HighLevelILInstruction']]:

"""

Gets the list of IL instructions where this SSAVariable is used inside of this function.

"""

return self.il_function.get_ssa_var_uses(self)

class MediumLevelILLabel:

def __init__(self, handle: Optional[core.BNMediumLevelILLabel] = None):

if handle is None:

self.handle = (core.BNMediumLevelILLabel * 1)()

core.BNMediumLevelILInitLabel(self.handle)

else:

self.handle = handle

@property

def ref(self) -> bool:

return self.handle[0].ref

@ref.setter

def ref(self, value):

self.handle[0].ref = value

@property

def resolved(self) -> bool:

return self.handle[0].resolved

@property

def operand(self) -> InstructionIndex:

return InstructionIndex(self.handle[0].operand)

@operand.setter

def operand(self, value: InstructionIndex):

self.handle[0].operand = int(value)

@dataclass(frozen=True, repr=False)

class MediumLevelILOperationAndSize:

operation: MediumLevelILOperation

size: int

def __repr__(self):

if self.size == 0:

return f"<MediumLevelILOperationAndSize: {self.operation.name}>"

return f"<MediumLevelILOperationAndSize: {self.operation.name} {self.size}>"

@dataclass(frozen=True)

class CoreMediumLevelILInstruction:

operation: MediumLevelILOperation

attributes: int

source_operand: int

size: int

operands: OperandsType

address: int

@classmethod

def from_BNMediumLevelILInstruction(cls, instr: core.BNMediumLevelILInstruction) -> 'CoreMediumLevelILInstruction':

operands: OperandsType = tuple([ExpressionIndex(instr.operands[i]) for i in range(5)]) # type: ignore

return cls(MediumLevelILOperation(instr.operation), instr.attributes, instr.sourceOperand, instr.size, operands, instr.address)

@dataclass(frozen=True)

class MediumLevelILInstruction(BaseILInstruction):

"""

``class MediumLevelILInstruction`` Medium Level Intermediate Language Instructions are infinite length tree-based

instructions. Tree-based instructions use infix notation with the left hand operand being the destination operand.

Infix notation is thus more natural to read than other notations (e.g. x86 ``mov eax, 0`` vs. MLIL ``eax = 0``).

"""

function: 'MediumLevelILFunction'

expr_index: ExpressionIndex

instr: CoreMediumLevelILInstruction

instr_index: InstructionIndex

# ILOperations is deprecated and will be removed in a future version once BNIL Graph no longer uses it

# Use the visit methods visit, visit_all, and visit_operands

ILOperations: ClassVar[Mapping[MediumLevelILOperation, List[Tuple[str, str]]]] = {

MediumLevelILOperation.MLIL_NOP: [], MediumLevelILOperation.MLIL_SET_VAR: [("dest", "var"), ("src", "expr")],

MediumLevelILOperation.MLIL_SET_VAR_FIELD: [("dest", "var"), ("offset", "int"),

("src", "expr")], MediumLevelILOperation.MLIL_SET_VAR_SPLIT: [

("high", "var"), ("low", "var"), ("src", "expr")

], MediumLevelILOperation.MLIL_LOAD: [("src", "expr")],

MediumLevelILOperation.MLIL_LOAD_STRUCT: [("src", "expr"),

("offset", "int")], MediumLevelILOperation.MLIL_STORE: [

("dest", "expr"), ("src", "expr")

], MediumLevelILOperation.MLIL_STORE_STRUCT: [("dest", "expr"),

("offset", "int"),

("src", "expr")],

MediumLevelILOperation.MLIL_VAR: [("src", "var")], MediumLevelILOperation.MLIL_VAR_FIELD: [

("src", "var"), ("offset", "int")

], MediumLevelILOperation.MLIL_VAR_SPLIT: [("high", "var"), ("low", "var")],

MediumLevelILOperation.MLIL_ADDRESS_OF: [("src", "var")], MediumLevelILOperation.MLIL_PASS_BY_REF: [

("src", "expr")

], MediumLevelILOperation.MLIL_RETURN_BY_REF: [

("src", "expr")

], MediumLevelILOperation.MLIL_ADDRESS_OF_FIELD: [

("src", "var"), ("offset", "int")

], MediumLevelILOperation.MLIL_CONST: [("constant", "int")], MediumLevelILOperation.MLIL_CONST_PTR: [

("constant", "int")

], MediumLevelILOperation.MLIL_EXTERN_PTR: [

("constant", "int"), ("offset", "int")

], MediumLevelILOperation.MLIL_FLOAT_CONST: [("constant", "float")], MediumLevelILOperation.MLIL_IMPORT: [

("constant", "int")

], MediumLevelILOperation.MLIL_CONST_DATA: [("constant", "ConstantData")], MediumLevelILOperation.MLIL_CONST_DATA: [

("constant", "ConstantData")

], MediumLevelILOperation.MLIL_ADD: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_ADC: [

("left", "expr"), ("right", "expr"), ("carry", "expr")

], MediumLevelILOperation.MLIL_SUB: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_SBB: [

("left", "expr"), ("right", "expr"), ("carry", "expr")

], MediumLevelILOperation.MLIL_AND: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_OR: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_XOR: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_LSL: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_LSR: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_ASR: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_ROL: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_RLC: [

("left", "expr"), ("right", "expr"), ("carry", "expr")

], MediumLevelILOperation.MLIL_ROR: [("left", "expr"),

("right", "expr")], MediumLevelILOperation.MLIL_RRC: [("left", "expr"),

("right", "expr"),

("carry", "expr")],

MediumLevelILOperation.MLIL_MUL: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_MULU_DP: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_MULS_DP: [("left", "expr"),

("right", "expr")], MediumLevelILOperation.MLIL_DIVU: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_DIVU_DP: [("left", "expr"),

("right", "expr")],

MediumLevelILOperation.MLIL_DIVS: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_DIVS_DP: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_MODU: [("left", "expr"),

("right", "expr")], MediumLevelILOperation.MLIL_MODU_DP: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_MODS: [("left", "expr"),

("right", "expr")],

MediumLevelILOperation.MLIL_MODS_DP: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_NEG: [

("src", "expr")

], MediumLevelILOperation.MLIL_NOT: [("src", "expr")], MediumLevelILOperation.MLIL_SX: [

("src", "expr")

], MediumLevelILOperation.MLIL_ZX: [("src", "expr")], MediumLevelILOperation.MLIL_LOW_PART: [

("src", "expr")

], MediumLevelILOperation.MLIL_JUMP: [("dest", "expr")], MediumLevelILOperation.MLIL_JUMP_TO: [

("dest", "expr"), ("targets", "target_map")

], MediumLevelILOperation.MLIL_RET_HINT: [("dest", "expr")], MediumLevelILOperation.MLIL_CALL: [

("output", "expr_list"), ("dest", "expr"), ("params", "expr_list")

], MediumLevelILOperation.MLIL_CALL_UNTYPED: [

("output", "expr_list"), ("dest", "expr"), ("params", "expr"), ("stack", "expr")

], MediumLevelILOperation.MLIL_CALL_PARAM: [

("src", "expr_list")

], MediumLevelILOperation.MLIL_SEPARATE_PARAM_LIST: [

("params", "expr_list")

], MediumLevelILOperation.MLIL_SHARED_PARAM_SLOT: [

("params", "expr_list")

], MediumLevelILOperation.MLIL_VAR_OUTPUT: [

("dest", "var")

], MediumLevelILOperation.MLIL_VAR_OUTPUT_FIELD: [

("dest", "var"), ("offset", "int")

], MediumLevelILOperation.MLIL_STORE_OUTPUT: [

("dest", "expr")

], MediumLevelILOperation.MLIL_RET: [

("src", "expr_list")

], MediumLevelILOperation.MLIL_BLOCK_TO_EXPAND: [

("src", "expr_list")

], MediumLevelILOperation.MLIL_NORET: [], MediumLevelILOperation.MLIL_IF: [

("condition", "expr"), ("true", "int"), ("false", "int")

], MediumLevelILOperation.MLIL_GOTO: [("dest", "int")], MediumLevelILOperation.MLIL_CMP_E: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_NE: [("left", "expr"),

("right", "expr")], MediumLevelILOperation.MLIL_CMP_SLT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_ULT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_SLE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_ULE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_SGE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_UGE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_SGT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_CMP_UGT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_TEST_BIT: [("left", "expr"),

("right", "expr")],

MediumLevelILOperation.MLIL_BOOL_TO_INT: [("src", "expr")], MediumLevelILOperation.MLIL_ADD_OVERFLOW: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_SYSCALL: [

("output", "expr_list"), ("params", "expr_list")

], MediumLevelILOperation.MLIL_SYSCALL_UNTYPED: [

("output", "expr_list"), ("params", "expr"), ("stack", "expr")

], MediumLevelILOperation.MLIL_TAILCALL: [

("output", "expr_list"), ("dest", "expr"), ("params", "expr_list")

], MediumLevelILOperation.MLIL_TAILCALL_UNTYPED: [("output", "expr_list"), ("dest", "expr"), ("params", "expr"),

("stack", "expr")], MediumLevelILOperation.MLIL_BP: [],

MediumLevelILOperation.MLIL_TRAP: [("vector", "int")], MediumLevelILOperation.MLIL_INTRINSIC: [

("output", "var_list"), ("intrinsic", "intrinsic"), ("params", "expr_list")

], MediumLevelILOperation.MLIL_INTRINSIC_SSA: [

("output", "var_ssa_list"), ("intrinsic", "intrinsic"), ("params", "expr_list")

], MediumLevelILOperation.MLIL_MEMORY_INTRINSIC_OUTPUT_SSA: [

("dest_memory", "int"), ("output", "var_ssa_list")

], MediumLevelILOperation.MLIL_MEMORY_INTRINSIC_SSA: [

("output", "expr"), ("intrinsic", "intrinsic"), ("params", "expr_list"), ("src_memory", "int")

], MediumLevelILOperation.MLIL_FREE_VAR_SLOT: [

("dest", "var")

], MediumLevelILOperation.MLIL_FREE_VAR_SLOT_SSA: [

("prev", "var_ssa_dest_and_src")

], MediumLevelILOperation.MLIL_UNDEF: [], MediumLevelILOperation.MLIL_UNIMPL: [],

MediumLevelILOperation.MLIL_UNIMPL_MEM: [("src", "expr")], MediumLevelILOperation.MLIL_FADD: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FSUB: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_FMUL: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FDIV: [("left", "expr"), ("right", "expr")], MediumLevelILOperation.MLIL_FSQRT: [

("src", "expr")

], MediumLevelILOperation.MLIL_FNEG: [("src", "expr")], MediumLevelILOperation.MLIL_FABS: [

("src", "expr")

], MediumLevelILOperation.MLIL_FLOAT_TO_INT: [("src", "expr")], MediumLevelILOperation.MLIL_INT_TO_FLOAT: [

("src", "expr")

], MediumLevelILOperation.MLIL_FLOAT_CONV: [("src", "expr")], MediumLevelILOperation.MLIL_ROUND_TO_INT: [

("src", "expr")

], MediumLevelILOperation.MLIL_FLOOR: [("src", "expr")], MediumLevelILOperation.MLIL_CEIL: [

("src", "expr")

], MediumLevelILOperation.MLIL_FTRUNC: [("src", "expr")], MediumLevelILOperation.MLIL_FCMP_E: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_NE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_LT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_LE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_GE: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_GT: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_O: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_FCMP_UO: [

("left", "expr"), ("right", "expr")

], MediumLevelILOperation.MLIL_SET_VAR_SSA: [

("dest", "var_ssa"), ("src", "expr")

], MediumLevelILOperation.MLIL_SET_VAR_SSA_FIELD: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src"), ("offset", "int"), ("src", "expr")

], MediumLevelILOperation.MLIL_SET_VAR_SPLIT_SSA: [

("high", "var_ssa"), ("low", "var_ssa"), ("src", "expr")

], MediumLevelILOperation.MLIL_SET_VAR_ALIASED: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src"), ("src", "expr")

], MediumLevelILOperation.MLIL_SET_VAR_ALIASED_FIELD: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src"), ("offset", "int"), ("src", "expr")

], MediumLevelILOperation.MLIL_VAR_SSA: [("src", "var_ssa")], MediumLevelILOperation.MLIL_VAR_SSA_FIELD: [

("src", "var_ssa"), ("offset", "int")

], MediumLevelILOperation.MLIL_VAR_ALIASED: [

("src", "var_ssa")

], MediumLevelILOperation.MLIL_VAR_ALIASED_FIELD: [

("src", "var_ssa"), ("offset", "int")

], MediumLevelILOperation.MLIL_VAR_SPLIT_SSA: [

("high", "var_ssa"), ("low", "var_ssa")

], MediumLevelILOperation.MLIL_VAR_OUTPUT_SSA: [

("dest", "var_ssa")

], MediumLevelILOperation.MLIL_VAR_OUTPUT_SSA_FIELD: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src"), ("offset", "int")

], MediumLevelILOperation.MLIL_VAR_OUTPUT_ALIASED: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src")

], MediumLevelILOperation.MLIL_VAR_OUTPUT_ALIASED_FIELD: [

("dest", "var_ssa_dest_and_src"), ("prev", "var_ssa_dest_and_src"), ("offset", "int")

], MediumLevelILOperation.MLIL_CALL_SSA: [

("output", "expr"), ("output_dest_memory", "int"), ("dest", "expr"),

("params", "expr_list"), ("src_memory", "int")

], MediumLevelILOperation.MLIL_CALL_UNTYPED_SSA: [

("output", "expr"), ("dest", "expr"), ("params", "expr"), ("stack", "expr")

], MediumLevelILOperation.MLIL_SYSCALL_SSA: [

("output", "expr"), ("params", "expr_list"),

("src_memory", "int")

], MediumLevelILOperation.MLIL_SYSCALL_UNTYPED_SSA: [

("output", "expr"), ("params", "expr"), ("stack", "expr")

], MediumLevelILOperation.MLIL_TAILCALL_SSA: [

("output", "expr"), ("output_dest_memory", "int"),

("dest", "expr"), ("params", "expr_list"), ("src_memory", "int")

], MediumLevelILOperation.MLIL_TAILCALL_UNTYPED_SSA: [

("output", "expr"), ("dest", "expr"), ("params", "expr"), ("stack", "expr")

], MediumLevelILOperation.MLIL_CALL_OUTPUT_SSA: [

("dest_memory", "int"), ("dest", "var_ssa_list")

], MediumLevelILOperation.MLIL_CALL_PARAM_SSA: [

("src_memory", "int"), ("src", "expr_list")

], MediumLevelILOperation.MLIL_LOAD_SSA: [

("src", "expr"), ("src_memory", "int")

], MediumLevelILOperation.MLIL_LOAD_STRUCT_SSA: [

("src", "expr"), ("offset", "int"), ("src_memory", "int")

], MediumLevelILOperation.MLIL_STORE_SSA: [("dest", "expr"), ("dest_memory", "int"), ("src_memory", "int"),

("src", "expr")], MediumLevelILOperation.MLIL_STORE_STRUCT_SSA: [

("dest", "expr"), ("offset", "int"), ("dest_memory", "int"),

("src_memory", "int"), ("src", "expr")

], MediumLevelILOperation.MLIL_VAR_PHI: [

("dest", "var_ssa"), ("src", "var_ssa_list")

], MediumLevelILOperation.MLIL_MEM_PHI: [("dest_memory", "int"),

("src_memory", "int_list")]

}

@staticmethod

def show_mlil_hierarchy():

"""

Opens a new tab showing the MLIL hierarchy which includes classes which can

easily be used with isinstance to match multiple types of IL instructions.

"""

graph = flowgraph.FlowGraph()

nodes = {}

for instruction in ILInstruction.values():

instruction.add_subgraph(graph, nodes)

show_graph_report("MLIL Class Hierarchy Graph", graph)

@classmethod

def create(

cls, func: 'MediumLevelILFunction', expr_index: ExpressionIndex, instr_index: Optional[InstructionIndex] = None

) -> 'MediumLevelILInstruction':

assert func.arch is not None, "Attempted to create IL instruction with function missing an Architecture"

inst = core.BNGetMediumLevelILByIndex(func.handle, expr_index)

assert inst is not None, "core.BNGetMediumLevelILByIndex returned None"

if instr_index is None:

instr_index = core.BNGetMediumLevelILInstructionForExpr(func.handle, expr_index)

assert instr_index is not None, "core.BNGetMediumLevelILInstructionForExpr returned None"

instr = CoreMediumLevelILInstruction.from_BNMediumLevelILInstruction(inst)

return ILInstruction[instr.operation](func, expr_index, instr, instr_index) # type: ignore

def copy_to(

self, dest: 'MediumLevelILFunction',

sub_expr_handler: Optional[Callable[['MediumLevelILInstruction'], ExpressionIndex]] = None

) -> ExpressionIndex:

"""

``copy_to`` deep copies an expression into a new IL function.

If provided, the function ``sub_expr_handler`` will be called on every copied sub-expression

.. warning:: This function should ONLY be called as a part of a lifter or workflow. It will otherwise not do anything useful as analysis will not be running.

:param MediumLevelILFunction dest: Function to copy the expression to

:param sub_expr_handler: Optional function to call on every copied sub-expression

:return: Index of the copied expression in the target function

"""

return self.function.copy_expr_to(self, dest, sub_expr_handler)

def __str__(self):

tokens = self.tokens

if tokens is None:

return "invalid"

result = ""

for token in tokens:

result += token.text

return result

def __repr__(self):

return f"<{self.__class__.__name__}: {self}>"

def __eq__(self, other: 'MediumLevelILInstruction') -> bool:

if not isinstance(other, MediumLevelILInstruction):

return NotImplemented

return self.function == other.function and self.expr_index == other.expr_index

def __lt__(self, other: 'MediumLevelILInstruction') -> bool:

if not isinstance(other, MediumLevelILInstruction):

return NotImplemented

return self.function == other.function and self.expr_index < other.expr_index

def __le__(self, other: 'MediumLevelILInstruction') -> bool:

if not isinstance(other, MediumLevelILInstruction):

return NotImplemented

return self.function == other.function and self.expr_index <= other.expr_index

def __gt__(self, other: 'MediumLevelILInstruction') -> bool:

if not isinstance(other, MediumLevelILInstruction):

return NotImplemented

return self.function == other.function and self.expr_index > other.expr_index

def __ge__(self, other: 'MediumLevelILInstruction') -> bool:

if not isinstance(other, MediumLevelILInstruction):

return NotImplemented

return self.function == other.function and self.expr_index >= other.expr_index

def __hash__(self):

return hash((self.function, self.expr_index))

@property

def operands(self) -> List[MediumLevelILOperandType]:

"""

Operands for the instruction

Consider using more specific APIs for ``src``, ``dest``, ``params``, etc where appropriate.

"""

return list(map(lambda x: x[1], self.detailed_operands))

@property

def raw_operands(self) -> OperandsType:

"""Raw operand expression indices as specified by the core structure (read-only)"""

return self.instr.operands

@property

def detailed_operands(self) -> List[Tuple[str, MediumLevelILOperandType, str]]:

"""

Returns a list of tuples containing the name of the operand, the operand, and the type of the operand.

Useful for iterating over all operands of an instruction and sub-instructions.

"""

return []

def traverse(self, cb: Callable[['MediumLevelILInstruction', Any], Any], *args: Any, **kwargs: Any) -> Iterator[Any]:

"""

``traverse`` is a generator that allows you to traverse the MediumLevelILInstruction in a depth-first manner. It will yield the

result of the callback function for each node in the tree. Arguments can be passed to the callback function using

``args`` and ``kwargs``. See the `Developer Docs <https://docs.binary.ninja/dev/concepts.html#walking-ils>`_ for more examples.

:param Callable[[MediumLevelILInstruction, Any], Any] cb: The callback function to call for each node in the MediumLevelILInstruction

:param Any args: Custom user-defined arguments

:param Any kwargs: Custom user-defined keyword arguments

:return: An iterator of the results of the callback function

:rtype: Iterator[Any]

:Example:

>>> def get_constant_less_than_value(inst: MediumLevelILInstruction, value: int) -> int:

>>> if isinstance(inst, Constant) and inst.constant < value:

>>> return inst.constant

>>>

>>> list(inst.traverse(get_constant_less_than_value, 10))

"""

if (result := cb(self, *args, **kwargs)) is not None:

yield result

for _, op, _ in self.detailed_operands:

if isinstance(op, MediumLevelILInstruction):

yield from op.traverse(cb, *args, **kwargs)

elif isinstance(op, list) and all(isinstance(i, MediumLevelILInstruction) for i in op):

for i in op:

yield from i.traverse(cb, *args, **kwargs) # type: ignore

@deprecation.deprecated(deprecated_in="4.0.4907", details="Use :py:func:`MediumLevelILInstruction.traverse` instead.")

def visit_all(self, cb: MediumLevelILVisitorCallback,

name: str = "root", parent: Optional['MediumLevelILInstruction'] = None) -> bool:

"""

Visits all operands of this instruction and all operands of any sub-instructions.

Using pre-order traversal.

:param MediumLevelILVisitorCallback cb: Callback function that takes the name of the operand, the operand, operand type, and parent instruction

:return: True if all instructions were visited, False if the callback returned False

"""

if cb(name, self, "MediumLevelILInstruction", parent) == False:

return False

for name, op, opType in self.detailed_operands:

if isinstance(op, MediumLevelILInstruction):

if not op.visit_all(cb, name, self):

return False

elif isinstance(op, list) and all(isinstance(i, MediumLevelILInstruction) for i in op):

for i in op:

if not i.visit_all(cb, name, self): # type: ignore

return False

elif cb(name, op, opType, self) == False:

return False

return True

@deprecation.deprecated(deprecated_in="4.0.4907", details="Use :py:func:`MediumLevelILInstruction.traverse` instead.")

def visit_operands(self, cb: MediumLevelILVisitorCallback,

name: str = "root", parent: Optional['MediumLevelILInstruction'] = None) -> bool:

"""

Visits all leaf operands of this instruction and any sub-instructions.

:param MediumLevelILVisitorCallback cb: Callback function that takes the name of the operand, the operand, operand type, and parent instruction

:return: True if all instructions were visited, False if the callback returned False

"""

for name, op, opType in self.detailed_operands:

if isinstance(op, MediumLevelILInstruction):

if not op.visit_operands(cb, name, self):

return False

elif isinstance(op, list) and all(isinstance(i, MediumLevelILInstruction) for i in op):

for i in op:

if not i.visit_operands(cb, name, self): # type: ignore

return False

elif cb(name, op, opType, self) == False:

return False

return True

@deprecation.deprecated(deprecated_in="4.0.4907", details="Use :py:func:`MediumLevelILInstruction.traverse` instead.")

def visit(self, cb: MediumLevelILVisitorCallback,

name: str = "root", parent: Optional['MediumLevelILInstruction'] = None) -> bool:

"""

Visits all MediumLevelILInstructions in the operands of this instruction and any sub-instructions.

In the callback you provide, you likely only need to interact with the second argument (see the example below).

:param MediumLevelILVisitorCallback cb: Callback function that takes the name of the operand, the operand, operand type, and parent instruction

:return: True if all instructions were visited, False if the callback returned False

:Example:

>>> def visitor(_a, inst, _c, _d) -> bool:

>>> if isinstance(inst, Constant):

>>> print(f"Found constant: {inst.constant}")

>>> return False # Stop recursion (once we find a constant, don't recurse in to any sub-instructions (which there won't actually be any...))

>>> # Otherwise, keep recursing the subexpressions of this instruction; if no return value is provided, it'll keep descending

>>>

>>> # Finds all constants used in the program

>>> for inst in current_mlil.instructions:

>>> inst.visit(visitor)

"""

if cb(name, self, "MediumLevelILInstruction", parent) == False:

return False

for name, op, _ in self.detailed_operands:

if isinstance(op, MediumLevelILInstruction):

if not op.visit(cb, name, self):

return False

elif isinstance(op, list) and all(isinstance(i, MediumLevelILInstruction) for i in op):

for i in op:

if not i.visit(cb, name, self): # type: ignore

return False

return True

@property

def tokens(self) -> TokenList:

"""MLIL tokens (read-only)"""

# Special case for the helper instructions which don't have tokens

if isinstance(self, (MediumLevelILCallParam, MediumLevelILCallParamSsa)):

return []

count = ctypes.c_ulonglong()

tokens = ctypes.POINTER(core.BNInstructionTextToken)()

assert self.function.arch is not None, f"type(self.function): {type(self.function)} "

result = core.BNGetMediumLevelILExprText(

self.function.handle, self.function.arch.handle, self.expr_index, tokens, count, None

)

assert result, "core.BNGetMediumLevelILExprText returned False"

try:

return function.InstructionTextToken._from_core_struct(tokens, count.value)

finally:

core.BNFreeInstructionText(tokens, count.value)

@property

def il_basic_block(self) -> 'MediumLevelILBasicBlock':

"""IL basic block object containing this expression (read-only) (only available on finalized functions)"""

core_block = core.BNGetMediumLevelILBasicBlockForInstruction(self.function.handle, self.instr_index)

assert core_block is not None

assert self.function.source_function is not None

return MediumLevelILBasicBlock(core_block, self.function, self.function.source_function.view)

@property

def ssa_form(self) -> 'MediumLevelILInstruction':

"""SSA form of expression (read-only)"""

ssa_func = self.function.ssa_form

assert ssa_func is not None

return MediumLevelILInstruction.create(

ssa_func, ExpressionIndex(core.BNGetMediumLevelILSSAExprIndex(self.function.handle, self.expr_index))

)

@property

def non_ssa_form(self) -> 'MediumLevelILInstruction':

"""Non-SSA form of expression (read-only)"""

non_ssa_func = self.function.non_ssa_form

assert non_ssa_func is not None

return MediumLevelILInstruction.create(

non_ssa_func,

ExpressionIndex(core.BNGetMediumLevelILNonSSAExprIndex(self.function.handle, self.expr_index))

)

@property

def value(self) -> variable.RegisterValue:

"""Value of expression if constant or a known value (read-only)"""

value = core.BNGetMediumLevelILExprValue(self.function.handle, self.expr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

@property

def possible_values(self) -> variable.PossibleValueSet:

"""Possible values of expression using path-sensitive static data flow analysis (read-only)"""

value = core.BNGetMediumLevelILPossibleExprValues(self.function.handle, self.expr_index, None, 0)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

@property

def branch_dependence(self) -> Mapping[int, ILBranchDependence]:

"""Set of branching instructions that must take the true or false path to reach this instruction"""

count = ctypes.c_ulonglong()

deps = core.BNGetAllMediumLevelILBranchDependence(self.function.handle, self.instr_index, count)

assert deps is not None, "core.BNGetAllMediumLevelILBranchDependence returned None"

result = {}

for i in range(0, count.value):

result[deps[i].branch] = ILBranchDependence(deps[i].dependence)

core.BNFreeILBranchDependenceList(deps)

return result

@property

def low_level_il(self) -> Optional['lowlevelil.LowLevelILInstruction']:

"""Low level IL form of this expression"""

expr = self.function.get_low_level_il_expr_index(self.expr_index)

if expr is None or self.function.low_level_il is None:

return None

return lowlevelil.LowLevelILInstruction.create(self.function.low_level_il.ssa_form, expr, None)

@property

def llil(self) -> Optional['lowlevelil.LowLevelILInstruction']:

"""Alias for low_level_il"""

return self.low_level_il

@property

def llils(self) -> List['lowlevelil.LowLevelILInstruction']:

exprs = self.function.get_low_level_il_expr_indexes(self.expr_index)

if self.function.low_level_il is None:

return []

result = []

for expr in exprs:

result.append(lowlevelil.LowLevelILInstruction.create(self.function.low_level_il.ssa_form, expr, None))

return result

@property

def high_level_il(self) -> Optional[highlevelil.HighLevelILInstruction]:

"""High level IL form of this expression"""

expr = self.function.get_high_level_il_expr_index(self.expr_index)

if expr is None or self.function.high_level_il is None:

return None

return highlevelil.HighLevelILInstruction.create(self.function.high_level_il, expr, False)

@property

def hlil(self) -> Optional[highlevelil.HighLevelILInstruction]:

"""Alias for high_level_il"""

return self.high_level_il

@property

def hlils(self) -> List[highlevelil.HighLevelILInstruction]:

exprs = self.function.get_high_level_il_expr_indexes(self.expr_index)

result = []

if self.function.high_level_il is None:

return result

for expr in exprs:

result.append(highlevelil.HighLevelILInstruction.create(self.function.high_level_il, expr, False))

return result

@property

def ssa_memory_version(self) -> int:

"""Version of active memory contents in SSA form for this instruction"""

return core.BNGetMediumLevelILSSAMemoryVersionAtILInstruction(self.function.handle, self.instr_index)

@property

def ssa_memory_version_after(self) -> int:

"""Version of active memory contents in SSA form after this instruction"""

return core.BNGetMediumLevelILSSAMemoryVersionAfterILInstruction(self.function.handle, self.instr_index)

@property

def prefix_operands(self) -> List[MediumLevelILOperandType]:

"""All operands in the expression tree in prefix order"""

result: List[MediumLevelILOperandType] = [MediumLevelILOperationAndSize(self.operation, self.size)]

for operand in self.operands:

if isinstance(operand, MediumLevelILInstruction):

result.extend(operand.prefix_operands)

else:

result.append(operand)

return result

@property

def postfix_operands(self) -> List[MediumLevelILOperandType]:

"""All operands in the expression tree in postfix order"""

result: List[MediumLevelILOperandType] = []

for operand in self.operands:

if isinstance(operand, MediumLevelILInstruction):

result.extend(operand.postfix_operands)

else:

result.append(operand)

result.append(MediumLevelILOperationAndSize(self.operation, self.size))

return result

@property

def instruction_operands(self) -> List['MediumLevelILInstruction']:

return [i for i in self.operands if isinstance(i, MediumLevelILInstruction)]

@property

def vars_written(self) -> List[Union[variable.Variable, SSAVariable]]:

"""List of variables written by instruction"""

return []

@property

def vars_read(self) -> List[Union[variable.Variable, SSAVariable]]:

"""List of variables read by instruction"""

result = []

for operand in self.operands:

if isinstance(operand, (variable.Variable, SSAVariable)):

result.append(operand)

elif isinstance(operand, MediumLevelILInstruction):

result += operand.vars_read

return result

@property

def vars_address_taken(self) -> List[Union[variable.Variable, SSAVariable]]:

"""Non-unique list of variables whose address is taken by instruction"""

result = []

for operand in self.instruction_operands:

result.extend(operand.vars_address_taken)

return result

@property

def expr_type(self) -> Optional['types.Type']:

"""Type of expression"""

result = core.BNGetMediumLevelILExprType(self.function.handle, self.expr_index)

if result.type:

platform = None

if self.function.source_function:

platform = self.function.source_function.platform

return types.Type.create(

result.type, platform=platform, confidence=result.confidence

)

return None

@property

def attributes(self) -> Set[ILInstructionAttribute]:

"""The set of optional attributes placed on the instruction"""

result: Set[ILInstructionAttribute] = set()

for flag in ILInstructionAttribute:

if self.instr.attributes & flag.value != 0:

result.add(flag)

return result

@staticmethod

def _make_options_array(options: Optional[List[DataFlowQueryOption]]):

if options is None:

options = []

idx = 0

option_array = (core.DataFlowQueryOptionEnum * len(options))()

for option in options:

option_array[idx] = option

idx += 1

return option_array, len(options)

def get_possible_values(self, options: Optional[List[DataFlowQueryOption]] = None) -> variable.PossibleValueSet:

option_array, size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleExprValues(self.function.handle, self.expr_index, option_array, size)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_ssa_var_possible_values(self, ssa_var: SSAVariable, options: List[DataFlowQueryOption] = []):

var_data = ssa_var.var.to_BNVariable()

option_array, size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleSSAVarValues(

self.function.handle, var_data, ssa_var.version, self.instr_index, option_array, size

)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_ssa_var_version(self, var: variable.CoreVariable) -> int:

var_data = var.to_BNVariable()

return core.BNGetMediumLevelILSSAVarVersionAtILInstruction(self.function.handle, var_data, self.instr_index)

def get_ssa_var_version_after(self, var: variable.CoreVariable) -> int:

var_data = var.to_BNVariable()

return core.BNGetMediumLevelILSSAVarVersionAfterILInstruction(self.function.handle, var_data, self.instr_index)

def get_var_for_reg(self, reg: 'architecture.RegisterType') -> variable.Variable:

reg = self.function.arch.get_reg_index(reg)

result = core.BNGetMediumLevelILVariableForRegisterAtInstruction(self.function.handle, reg, self.instr_index)

return variable.Variable.from_BNVariable(self.function, result)

def get_var_for_reg_after(self, reg: 'architecture.RegisterType') -> variable.Variable:

reg = self.function.arch.get_reg_index(reg)

result = core.BNGetMediumLevelILVariableForRegisterAfterInstruction(self.function.handle, reg, self.instr_index)

return variable.Variable.from_BNVariable(self.function, result)

def get_var_for_flag(self, flag: 'architecture.FlagType') -> variable.Variable:

flag = self.function.arch.get_flag_index(flag)

result = core.BNGetMediumLevelILVariableForFlagAtInstruction(self.function.handle, flag, self.instr_index)

return variable.Variable.from_BNVariable(self.function, result)

def get_var_for_flag_after(self, flag: 'architecture.FlagType') -> variable.Variable:

flag = self.function.arch.get_flag_index(flag)

result = core.BNGetMediumLevelILVariableForFlagAfterInstruction(self.function.handle, flag, self.instr_index)

return variable.Variable.from_BNVariable(self.function, result)

def get_var_for_stack_location(self, offset: int) -> variable.Variable:

result = core.BNGetMediumLevelILVariableForStackLocationAtInstruction(

self.function.handle, offset, self.instr_index

)

return variable.Variable.from_BNVariable(self.function, result)

def get_var_for_stack_location_after(self, offset: int) -> variable.Variable:

result = core.BNGetMediumLevelILVariableForStackLocationAfterInstruction(

self.function.handle, offset, self.instr_index

)

return variable.Variable.from_BNVariable(self.function, result)

def get_reg_value(self, reg: 'architecture.RegisterType') -> 'variable.RegisterValue':

reg = self.function.arch.get_reg_index(reg)

value = core.BNGetMediumLevelILRegisterValueAtInstruction(self.function.handle, reg, self.instr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_reg_value_after(self, reg: 'architecture.RegisterType') -> 'variable.RegisterValue':

reg = self.function.arch.get_reg_index(reg)

value = core.BNGetMediumLevelILRegisterValueAfterInstruction(self.function.handle, reg, self.instr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_possible_reg_values(

self, reg: 'architecture.RegisterType', options: Optional[List[DataFlowQueryOption]] = None

) -> 'variable.PossibleValueSet':

option_array, size = MediumLevelILInstruction._make_options_array(options)

reg = self.function.arch.get_reg_index(reg)

value = core.BNGetMediumLevelILPossibleRegisterValuesAtInstruction(

self.function.handle, reg, self.instr_index, option_array, size

)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_possible_reg_values_after(

self, reg: 'architecture.RegisterType', options: Optional[List[DataFlowQueryOption]] = None

) -> 'variable.PossibleValueSet':

reg = self.function.arch.get_reg_index(reg)

option_array, size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleRegisterValuesAfterInstruction(

self.function.handle, reg, self.instr_index, option_array, size

)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_flag_value(self, flag: 'architecture.FlagType') -> 'variable.RegisterValue':

flag = self.function.arch.get_flag_index(flag)

value = core.BNGetMediumLevelILFlagValueAtInstruction(self.function.handle, flag, self.instr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_flag_value_after(self, flag: 'architecture.FlagType') -> 'variable.RegisterValue':

flag = self.function.arch.get_flag_index(flag)

value = core.BNGetMediumLevelILFlagValueAfterInstruction(self.function.handle, flag, self.instr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_possible_flag_values(

self, flag: 'architecture.FlagType', options: Optional[List[DataFlowQueryOption]] = None

) -> 'variable.PossibleValueSet':

flag = self.function.arch.get_flag_index(flag)

option_array, size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleFlagValuesAtInstruction(

self.function.handle, flag, self.instr_index, option_array, size

)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_possible_flag_values_after(

self, flag: 'architecture.FlagType', options: Optional[List[DataFlowQueryOption]] = None

) -> 'variable.PossibleValueSet':

flag = self.function.arch.get_flag_index(flag)

option_array, size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleFlagValuesAfterInstruction(

self.function.handle, flag, self.instr_index, option_array, size

)

result = variable.PossibleValueSet(self.function.arch, value)

core.BNFreePossibleValueSet(value)

return result

def get_stack_contents(self, offset: int, size: int) -> 'variable.RegisterValue':

value = core.BNGetMediumLevelILStackContentsAtInstruction(self.function.handle, offset, size, self.instr_index)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_stack_contents_after(self, offset: int, size: int) -> 'variable.RegisterValue':

value = core.BNGetMediumLevelILStackContentsAfterInstruction(

self.function.handle, offset, size, self.instr_index

)

result = variable.RegisterValue.from_BNRegisterValue(value, self.function.arch)

return result

def get_possible_stack_contents(

self, offset: int, size: int, options: Optional[List[DataFlowQueryOption]] = None

) -> 'variable.PossibleValueSet':

option_array, option_size = MediumLevelILInstruction._make_options_array(options)

value = core.BNGetMediumLevelILPossibleStackContentsAtInstruction(

self.function.handle, offset, size, self.instr_index, option_array, option_size

)

result = variable.PossibleValueSet(self.function.arch, value)