# Copyright (c) 2019-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, Generator, List, Union, NewType, Tuple, ClassVar, Mapping, Set, Callable, Any, Iterator, overload

from dataclasses import dataclass

from enum import Enum

# Binary Ninja components

from . import _binaryninjacore as core

from .enums import (

HighLevelILOperation, DataFlowQueryOption, FunctionGraphType, ILInstructionAttribute, StringType,

DisassemblyOption

)

from . import function

from . import binaryview

from . import architecture

from . import lowlevelil

from . import mediumlevelil

from . import basicblock

from . import types

from . import highlight

from . import flowgraph

from . import variable

from . import databuffer

from . import stringrecognizer

from . import types as _types

from .interaction import show_graph_report

from .commonil import (

BaseILInstruction, Tailcall, Syscall, Localcall, Comparison, Signed, UnaryOperation, BinaryOperation, SSA, Phi,

Loop, ControlFlow, Memory, Constant, Arithmetic, DoublePrecision, Terminal, FloatingPoint, Intrinsic, Return,

VariableInstruction, SSAVariableInstruction, SetVar, ILSourceLocation

)

from . import deprecation

TokenList = List['function.InstructionTextToken']

LinesType = Generator['function.DisassemblyTextLine', None, None]

ExpressionIndex = NewType('ExpressionIndex', int)

InstructionIndex = NewType('InstructionIndex', int)

Index = Union[ExpressionIndex, InstructionIndex]

InstructionOrExpression = Union['HighLevelILInstruction', Index]

HLILInstructionsType = Generator['HighLevelILInstruction', None, None]

HLILBasicBlocksType = Generator['HighLevelILBasicBlock', None, None]

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

HighLevelILOperandType = Union['HighLevelILInstruction', 'lowlevelil.ILIntrinsic', 'variable.Variable',

'mediumlevelil.SSAVariable', List[int], List['variable.Variable'],

List['mediumlevelil.SSAVariable'], List['HighLevelILInstruction'], Optional[int], float,

'GotoLabel', variable.ConstantData, databuffer.DataBuffer]

VariablesList = List[Union['mediumlevelil.SSAVariable', 'variable.Variable']]

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

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

HighLevelILVisitorCallback = Callable[[str, HighLevelILOperandType, str, Optional['HighLevelILInstruction']], bool]

class VariableReferenceType(Enum):

Read = 0

Written = 1

AddressTaken = 2

@dataclass(frozen=True)

class HighLevelILOperationAndSize:

operation: HighLevelILOperation

size: int

def __repr__(self):

if self.size == 0:

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

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

@dataclass

class GotoLabel:

function: 'HighLevelILFunction'

id: int

def __repr__(self):

return f"<GotoLabel: {self.name}>"

def __str__(self):

return self.name

@property

def label_id(self) -> int:

return self.id

@property

def name(self) -> str:

assert self.function.source_function is not None, "Cant get name of function without source_function"

return core.BNGetGotoLabelName(self.function.source_function.handle, self.id)

@name.setter

def name(self, value: str) -> None:

assert self.function.source_function is not None, "Cant set name of function without source_function"

core.BNSetUserGotoLabelName(self.function.source_function.handle, self.id, value)

@property

def definition(self) -> Optional['HighLevelILInstruction']:

return self.function.get_label(self.id)

@property

def uses(self) -> List['HighLevelILInstruction']:

return self.function.get_label_uses(self.id)

@dataclass(frozen=True, order=True)

class CoreHighLevelILInstruction:

operation: HighLevelILOperation

attributes: int

source_operand: int

size: int

operands: OperandsType

address: int

parent: ExpressionIndex

@classmethod

def from_BNHighLevelILInstruction(cls, instr: core.BNHighLevelILInstruction) -> 'CoreHighLevelILInstruction':

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

return cls(

HighLevelILOperation(instr.operation), instr.attributes, instr.sourceOperand, instr.size, operands, instr.address,

instr.parent

)

@dataclass(frozen=True)

class HighLevelILInstruction(BaseILInstruction):

"""

``class HighLevelILInstruction`` High Level Intermediate Language Instructions form an abstract syntax tree of

the code. Control flow structures are present as high level constructs in the HLIL tree.

"""

function: 'HighLevelILFunction'

expr_index: ExpressionIndex

core_instr: CoreHighLevelILInstruction

as_ast: bool

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[HighLevelILOperation, List[Tuple[str, str]]]] = {

HighLevelILOperation.HLIL_NOP: [], HighLevelILOperation.HLIL_BLOCK: [("body", "expr_list")],

HighLevelILOperation.HLIL_IF: [("condition", "expr"), ("true", "expr"),

("false", "expr")], HighLevelILOperation.HLIL_WHILE: [("condition", "expr"),

("body", "expr")],

HighLevelILOperation.HLIL_WHILE_SSA: [("condition_phi", "expr"), ("condition", "expr"),

("body", "expr")], HighLevelILOperation.HLIL_DO_WHILE: [

("body", "expr"), ("condition", "expr")

], HighLevelILOperation.HLIL_DO_WHILE_SSA: [("body", "expr"),

("condition_phi", "expr"),

("condition", "expr")],

HighLevelILOperation.HLIL_FOR: [("init", "expr"), ("condition", "expr"), ("update", "expr"),

("body", "expr")], HighLevelILOperation.HLIL_FOR_SSA: [

("init", "expr"), ("condition_phi", "expr"), ("condition", "expr"),

("update", "expr"), ("body", "expr")

], HighLevelILOperation.HLIL_SWITCH: [

("condition", "expr"), ("default", "expr"), ("cases", "expr_list")

], HighLevelILOperation.HLIL_CASE: [("values", "expr_list"), ("body", "expr")],

HighLevelILOperation.HLIL_BREAK: [], HighLevelILOperation.HLIL_CONTINUE: [], HighLevelILOperation.HLIL_JUMP: [

("dest", "expr")

], HighLevelILOperation.HLIL_RET: [("src", "expr_list")], HighLevelILOperation.HLIL_NORET: [],

HighLevelILOperation.HLIL_UNREACHABLE: [],

HighLevelILOperation.HLIL_GOTO: [("target", "label")], HighLevelILOperation.HLIL_LABEL: [

("target", "label")

], HighLevelILOperation.HLIL_VAR_DECLARE: [("var", "var")], HighLevelILOperation.HLIL_VAR_INIT: [

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

], HighLevelILOperation.HLIL_VAR_INIT_SSA: [

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

], HighLevelILOperation.HLIL_ASSIGN: [("dest", "expr"),

("src", "expr")], HighLevelILOperation.HLIL_ASSIGN_UNPACK: [

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

], HighLevelILOperation.HLIL_ASSIGN_MEM_SSA: [("dest", "expr"),

("dest_memory", "int"),

("src", "expr"),

("src_memory", "int")],

HighLevelILOperation.HLIL_ASSIGN_UNPACK_MEM_SSA: [

("dest", "expr_list"), ("dest_memory", "int"), ("src", "expr"), ("src_memory", "int")

], HighLevelILOperation.HLIL_VAR: [("var", "var")], HighLevelILOperation.HLIL_VAR_SSA: [

("var", "var_ssa")

], HighLevelILOperation.HLIL_VAR_PHI: [("dest", "var_ssa"),

("src", "var_ssa_list")], HighLevelILOperation.HLIL_MEM_PHI: [

("dest", "int"), ("src", "int_list")

], HighLevelILOperation.HLIL_STRUCT_FIELD: [

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

], HighLevelILOperation.HLIL_ARRAY_INDEX: [

("src", "expr"), ("index", "expr")

], HighLevelILOperation.HLIL_ARRAY_INDEX_SSA: [("src", "expr"),

("src_memory", "int"),

("index", "expr")],

HighLevelILOperation.HLIL_SPLIT: [("high", "expr"), ("low", "expr")], HighLevelILOperation.HLIL_DEREF: [

("src", "expr")

], HighLevelILOperation.HLIL_DEREF_FIELD: [

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

], HighLevelILOperation.HLIL_DEREF_SSA: [

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

], HighLevelILOperation.HLIL_DEREF_FIELD_SSA: [

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

("member_index", "member_index")

], HighLevelILOperation.HLIL_ADDRESS_OF: [("src", "expr")], HighLevelILOperation.HLIL_PASS_BY_REF: [

("src", "expr")

], HighLevelILOperation.HLIL_RETURN_BY_REF: [

("src", "expr")

], HighLevelILOperation.HLIL_CONST: [

("constant", "int")

], HighLevelILOperation.HLIL_CONST_PTR: [("constant", "int")], HighLevelILOperation.HLIL_EXTERN_PTR: [

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

], HighLevelILOperation.HLIL_FLOAT_CONST: [("constant", "float")], HighLevelILOperation.HLIL_IMPORT: [

("constant", "int")

], HighLevelILOperation.HLIL_CONST_DATA: [("constant", "ConstantData")], HighLevelILOperation.HLIL_CONST_DATA: [

("constant", "ConstantData")

], HighLevelILOperation.HLIL_ADD: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_ADC: [

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

], HighLevelILOperation.HLIL_SUB: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_SBB: [

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

], HighLevelILOperation.HLIL_AND: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_OR: [

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

], HighLevelILOperation.HLIL_XOR: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_LSL: [

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

], HighLevelILOperation.HLIL_LSR: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_ASR: [

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

], HighLevelILOperation.HLIL_ROL: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_RLC: [

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

], HighLevelILOperation.HLIL_ROR: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_RRC: [

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

], HighLevelILOperation.HLIL_MUL: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_MULU_DP: [

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

], HighLevelILOperation.HLIL_MULS_DP: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_DIVU: [

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

], HighLevelILOperation.HLIL_DIVU_DP: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_DIVS: [

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

], HighLevelILOperation.HLIL_DIVS_DP: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_MODU: [

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

], HighLevelILOperation.HLIL_MODU_DP: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_MODS: [

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

], HighLevelILOperation.HLIL_MODS_DP: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_NEG: [

("src", "expr")

], HighLevelILOperation.HLIL_NOT: [("src", "expr")], HighLevelILOperation.HLIL_SX: [

("src", "expr")

], HighLevelILOperation.HLIL_ZX: [("src", "expr")], HighLevelILOperation.HLIL_LOW_PART: [

("src", "expr")

], HighLevelILOperation.HLIL_CALL: [

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

], HighLevelILOperation.HLIL_CALL_SSA: [

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

], HighLevelILOperation.HLIL_CMP_E: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_CMP_NE: [

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

], HighLevelILOperation.HLIL_CMP_SLT: [("left", "expr"), ("right", "expr")],

HighLevelILOperation.HLIL_CMP_ULT: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_CMP_SLE: [

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

], HighLevelILOperation.HLIL_CMP_ULE: [("left", "expr"),

("right", "expr")], HighLevelILOperation.HLIL_CMP_SGE: [

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

], HighLevelILOperation.HLIL_CMP_UGE: [("left", "expr"),

("right", "expr")],

HighLevelILOperation.HLIL_CMP_SGT: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_CMP_UGT: [

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

], HighLevelILOperation.HLIL_TEST_BIT: [

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

], HighLevelILOperation.HLIL_BOOL_TO_INT: [("src", "expr")], HighLevelILOperation.HLIL_ADD_OVERFLOW: [

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

], HighLevelILOperation.HLIL_SYSCALL: [("params", "expr_list")], HighLevelILOperation.HLIL_SYSCALL_SSA: [

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

], HighLevelILOperation.HLIL_TAILCALL: [

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

], HighLevelILOperation.HLIL_BP: [], HighLevelILOperation.HLIL_TRAP: [

("vector", "int")

], HighLevelILOperation.HLIL_INTRINSIC: [("intrinsic", "intrinsic"),

("params", "expr_list")], HighLevelILOperation.HLIL_INTRINSIC_SSA: [

("intrinsic", "intrinsic"), ("params", "expr_list"),

("dest_memory", "int"), ("src_memory", "int")

], HighLevelILOperation.HLIL_UNDEF: [],

HighLevelILOperation.HLIL_UNIMPL: [], HighLevelILOperation.HLIL_UNIMPL_MEM: [

("src", "expr")

], HighLevelILOperation.HLIL_FADD: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_FSUB: [

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

], HighLevelILOperation.HLIL_FMUL: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_FDIV: [

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

], HighLevelILOperation.HLIL_FSQRT: [("src", "expr")], HighLevelILOperation.HLIL_FNEG: [

("src", "expr")

], HighLevelILOperation.HLIL_FABS: [("src", "expr")], HighLevelILOperation.HLIL_FLOAT_TO_INT: [

("src", "expr")

], HighLevelILOperation.HLIL_INT_TO_FLOAT: [("src", "expr")], HighLevelILOperation.HLIL_FLOAT_CONV: [

("src", "expr")

], HighLevelILOperation.HLIL_ROUND_TO_INT: [("src", "expr")], HighLevelILOperation.HLIL_FLOOR: [

("src", "expr")

], HighLevelILOperation.HLIL_CEIL: [("src", "expr")], HighLevelILOperation.HLIL_FTRUNC: [

("src", "expr")

], HighLevelILOperation.HLIL_FCMP_E: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_FCMP_NE: [

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

], HighLevelILOperation.HLIL_FCMP_LT: [

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

], HighLevelILOperation.HLIL_FCMP_LE: [

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

], HighLevelILOperation.HLIL_FCMP_GE: [

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

], HighLevelILOperation.HLIL_FCMP_GT: [("left", "expr"), ("right", "expr")], HighLevelILOperation.HLIL_FCMP_O: [

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

], HighLevelILOperation.HLIL_FCMP_UO: [("left", "expr"), ("right", "expr")]

}

@staticmethod

def show_hlil_hierarchy():

"""

Opens a new tab showing the HLIL 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("HLIL Class Hierarchy Graph", graph)

@classmethod

def create(

cls, func: 'HighLevelILFunction', expr_index: ExpressionIndex, as_ast: bool = True,

instr_index: Optional[InstructionIndex] = None

) -> 'HighLevelILInstruction':

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

instr = core.BNGetHighLevelILByIndex(func.handle, expr_index, as_ast)

assert instr is not None, "core.BNGetHighLevelILByIndex returned None"

core_instr = CoreHighLevelILInstruction.from_BNHighLevelILInstruction(instr)

if instr_index is None:

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

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

return ILInstruction[instr.operation](func, expr_index, core_instr, as_ast, instr_index)

def __str__(self):

settings = function.DisassemblySettings.default_settings()

settings.set_option(DisassemblyOption.DisableLineFormatting)

lines = self.get_lines(settings)

if lines is None:

return "invalid"

result = []

for line in lines:

cur = ""

for token in line.tokens:

cur += token.text

result.append(cur)

return '\n'.join(result)

def __repr__(self):

settings = function.DisassemblySettings.default_settings()

settings.set_option(DisassemblyOption.DisableLineFormatting)

lines = self.get_lines(settings)

continuation = ""

if lines is None:

first_line = "<invalid>"

else:

first_line = ""

for token in next(lines).tokens:

first_line += token.text

if len(list(lines)) > 1:

continuation = "..."

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

def __eq__(self, other: 'HighLevelILInstruction'):

if not isinstance(other, HighLevelILInstruction):

return NotImplemented

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

def __lt__(self, other: 'HighLevelILInstruction'):

if not isinstance(other, HighLevelILInstruction):

return NotImplemented

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

def __le__(self, other: 'HighLevelILInstruction'):

if not isinstance(other, HighLevelILInstruction):

return NotImplemented

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

def __gt__(self, other: 'HighLevelILInstruction'):

if not isinstance(other, HighLevelILInstruction):

return NotImplemented

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

def __ge__(self, other: 'HighLevelILInstruction'):

if not isinstance(other, HighLevelILInstruction):

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 tokens(self) -> TokenList:

"""HLIL tokens taken from the HLIL text lines (read-only) -- does not include newlines or indentation, use lines for that information"""

settings = function.DisassemblySettings.default_settings()

settings.set_option(DisassemblyOption.DisableLineFormatting)

return [token for line in self.get_lines(settings) for token in line.tokens]

@property

def lines(self) -> LinesType:

"""HLIL text lines (read-only)"""

return self.get_lines()

@property

def prefix_operands(self) -> List[Union[HighLevelILOperandType, HighLevelILOperationAndSize]]:

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

result: List[Union[HighLevelILOperandType,

HighLevelILOperationAndSize]] = [HighLevelILOperationAndSize(self.operation, self.size)]

for operand in self.operands:

if isinstance(operand, HighLevelILInstruction):

result.extend(operand.prefix_operands)

else:

result.append(operand)

return result

@property

def postfix_operands(self) -> List[Union[HighLevelILOperandType, HighLevelILOperationAndSize]]:

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

result: List[Union[HighLevelILOperandType, HighLevelILOperationAndSize]] = []

for operand in self.operands:

if isinstance(operand, HighLevelILInstruction):

result.extend(operand.postfix_operands)

else:

result.append(operand)

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

return result

@property

def instr(self) -> 'HighLevelILInstruction':

"""The statement that this expression belongs to (read-only)"""

return self.function[self.instr_index]

@property

def ast(self) -> 'HighLevelILInstruction':

"""This expression with full AST printing (read-only)"""

if self.as_ast:

return self

return HighLevelILInstruction.create(self.function, self.expr_index, True)

@property

def non_ast(self) -> 'HighLevelILInstruction':

"""This expression without full AST printing (read-only)"""

if not self.as_ast:

return self

return HighLevelILInstruction.create(self.function, self.expr_index, False)

@property

def operation(self) -> HighLevelILOperation:

return self.core_instr.operation

@property

def size(self) -> int:

return self.core_instr.size

@property

def address(self) -> int:

return self.core_instr.address

@property

def source_operand(self) -> ExpressionIndex:

return ExpressionIndex(self.core_instr.source_operand)

@property

def source_location(self) -> ILSourceLocation:

return ILSourceLocation.from_instruction(self)

@property

def core_operands(self) -> OperandsType:

return self.core_instr.operands

@property

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

result = []

for i in self.operands:

if isinstance(i, list):

result.extend([j for j in i if isinstance(j, HighLevelILInstruction)])

elif isinstance(i, HighLevelILInstruction):

result.append(i)

return result

@property

def vars_written(self) -> VariablesList:

"""List of variables value is written by this instruction"""

result = []

for i in self.operands:

if isinstance(i, HighLevelILInstruction):

result.extend(i.vars_written)

return result

@property

def vars_read(self) -> VariablesList:

"""Non-unique list of variables whose value is read by this instruction"""

non_read = [*self.vars_written, *self.vars_address_taken]

result = []

for v in self.vars:

if v in non_read:

non_read.remove(v)

continue

result.append(v)

return result

@property

def vars_address_taken(self) -> VariablesList:

"""

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

.. note:: This property has some nuance to it, so use carefully. This property will return only those variable which \

directly have their address taken such as `&var_4` or `&var_8.d` but not those which are involved in an address \

calculation such as `&(var_4 + 0)` or `&var_4[0]` even though they may be functionally equivalent.

"""

result = []

for operand in self.instruction_operands:

result.extend(operand.vars_address_taken)

return result

@property

def vars(self) -> VariablesList:

"""Non-unique list of variables read by instruction"""

result = []

for operand in self.operands:

if isinstance(operand, HighLevelILInstruction):

result.extend(operand.vars)

elif isinstance(operand, (variable.Variable, mediumlevelil.SSAVariable)):

result.append(operand)

elif isinstance(operand, list):

for sub_operand in operand:

if isinstance(sub_operand, (variable.Variable, mediumlevelil.SSAVariable)):

result.append(sub_operand)

elif isinstance(sub_operand, HighLevelILInstruction):

result.extend(sub_operand.vars)

return result

@property

def parent(self) -> Optional['HighLevelILInstruction']:

if self.core_instr.parent >= core.BNGetHighLevelILExprCount(self.function.handle):

return None

return HighLevelILInstruction.create(self.function, self.core_instr.parent, self.as_ast)

@property

def ssa_form(self) -> 'HighLevelILInstruction':

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

assert self.function.ssa_form is not None

return HighLevelILInstruction.create(

self.function.ssa_form,

ExpressionIndex(core.BNGetHighLevelILSSAExprIndex(self.function.handle, self.expr_index)), self.as_ast

)

@property

def non_ssa_form(self) -> Optional['HighLevelILInstruction']:

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

if self.function.non_ssa_form is None:

return None

return HighLevelILInstruction.create(

self.function.non_ssa_form,

ExpressionIndex(core.BNGetHighLevelILNonSSAExprIndex(self.function.handle, self.expr_index)), self.as_ast

)

@property

def medium_level_il(self) -> Optional['mediumlevelil.MediumLevelILInstruction']:

"""Medium level IL form of this expression"""

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

if expr is None:

return None

mlil = self.function.medium_level_il

if mlil is None:

return None

ssa_func = mlil.ssa_form

assert ssa_func is not None, "medium_level_il.ssa_form is None"

return mediumlevelil.MediumLevelILInstruction.create(ssa_func, expr)

@property

def mlil(self) -> Optional['mediumlevelil.MediumLevelILInstruction']:

"""Alias for medium_level_il"""

return self.medium_level_il

@property

def mlils(self) -> Optional[List['mediumlevelil.MediumLevelILInstruction']]:

result = []

for expr in self.function.get_medium_level_il_expr_indexes(self.expr_index):

mlil = self.function.medium_level_il

if mlil is None:

return

ssa_func = mlil.ssa_form

assert ssa_func is not None, "medium_level_il.ssa_form is None"

result.append(mediumlevelil.MediumLevelILInstruction.create(ssa_func, expr))

return result

@property

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

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

if self.mlil is None:

return None

return self.mlil.llil

@property

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

"""Alias for low_level_il"""

return self.low_level_il

@property

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

result = set()

mlils = self.mlils

if mlils is None:

return []

for mlil_expr in mlils:

for llil_expr in mlil_expr.llils:

result.add(llil_expr)

return list(result)

@property

def il_basic_block(self) -> Optional['HighLevelILBasicBlock']:

"""

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

Returns None for HLIL_BLOCK expressions as these can contain multiple basic blocks.

"""

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

assert core_block is not None, "core.BNGetHighLevelILBasicBlockForInstruction returned None"

if self.function.source_function is None:

return None

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

@property

def value(self) -> 'variable.RegisterValue':

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

mlil = self.mlil

if mlil is None:

return variable.Undetermined()

return mlil.value

@property

def possible_values(self) -> 'variable.PossibleValueSet':

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

mlil = self.mlil

if mlil is None:

return variable.PossibleValueSet()

return mlil.possible_values

@property

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

"""Type of expression"""

result = core.BNGetHighLevelILExprType(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.core_instr.attributes & flag.value != 0:

result.add(flag)

return result

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

mlil = self.mlil

if mlil is None:

return variable.PossibleValueSet()

if options is None:

options = []

return mlil.get_possible_values(options)

@property

def ssa_memory_version(self) -> int:

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

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

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

var_data = var.to_BNVariable()

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

def _get_int(self, operand_index: int) -> int:

value = self.core_instr.operands[operand_index]

return (value & ((1 << 63) - 1)) - (value & (1 << 63))

def _get_float(self, operand_index: int) -> float:

value = self.core_instr.operands[operand_index]

if self.core_instr.size == 4:

return struct.unpack("f", struct.pack("I", value & 0xffffffff))[0]

elif self.core_instr.size == 8:

return struct.unpack("d", struct.pack("Q", value))[0]

else:

return float(value)

def _get_constant_data(self, operand_index1: int, operand_index2: int) -> variable.ConstantData:

state = variable.RegisterValueType(self.core_instr.operands[operand_index1])

value = self.core_instr.operands[operand_index2]

return variable.ConstantData(value, 0, state, core.max_confidence, self.core_instr.size, self.function.source_function)

def _get_expr(self, operand_index: int) -> 'HighLevelILInstruction':

return HighLevelILInstruction.create(

self.function, ExpressionIndex(self.core_instr.operands[operand_index]),

self.as_ast

)

def _get_intrinsic(self, operand_index: int) -> 'lowlevelil.ILIntrinsic':

if self.function.arch is None:

raise ValueError("Attempting to create ILIntrinsic from function with no Architecture")

return lowlevelil.ILIntrinsic(

self.function.arch, architecture.IntrinsicIndex(self.core_instr.operands[operand_index])

)

def _get_var(self, operand_index: int) -> 'variable.Variable':

value = self.core_instr.operands[operand_index]

return variable.Variable.from_identifier(self.function, value)

def _get_var_ssa(self, operand_index1: int, operand_index2: int) -> 'mediumlevelil.SSAVariable':

var = variable.Variable.from_identifier(self.function, self.core_instr.operands[operand_index1])

version = self.core_instr.operands[operand_index2]

return mediumlevelil.SSAVariable(var, version)

def _get_var_ssa_dest_and_src(self, operand_index1: int, operand_index2: int) -> 'mediumlevelil.SSAVariable':

var = variable.Variable.from_identifier(self.function, self.core_instr.operands[operand_index1])

dest_version = self.core_instr.operands[operand_index2]

return mediumlevelil.SSAVariable(var, dest_version)

def _get_int_list(self, operand_index: int) -> List[int]:

count = ctypes.c_ulonglong()

operand_list = core.BNHighLevelILGetOperandList(self.function.handle, self.expr_index, operand_index, count)

assert operand_list is not None, "core.BNHighLevelILGetOperandList returned None"

value: List[int] = []

try:

for j in range(count.value):

value.append(operand_list[j])

return value

finally:

core.BNHighLevelILFreeOperandList(operand_list)

def _get_expr_list(self, operand_index1: int, _: int) -> List['HighLevelILInstruction']:

count = ctypes.c_ulonglong()

operand_list = core.BNHighLevelILGetOperandList(self.function.handle, self.expr_index, operand_index1, count)

assert operand_list is not None, "core.BNHighLevelILGetOperandList returned None"

value: List[HighLevelILInstruction] = []

try:

for j in range(count.value):

value.append(HighLevelILInstruction.create(self.function, operand_list[j], self.as_ast))

return value

finally:

core.BNHighLevelILFreeOperandList(operand_list)

def _get_var_ssa_list(self, operand_index1: int, _: int) -> List['mediumlevelil.SSAVariable']:

count = ctypes.c_ulonglong()

operand_list = core.BNHighLevelILGetOperandList(self.function.handle, self.expr_index, operand_index1, count)

assert operand_list is not None, "core.BNHighLevelILGetOperandList returned None"

value = []

try:

for j in range(count.value // 2):

var_id = operand_list[j * 2]

var_version = operand_list[(j*2) + 1]

value.append(

mediumlevelil.SSAVariable(variable.Variable.from_identifier(self.function, var_id), var_version)

)

return value

finally:

core.BNMediumLevelILFreeOperandList(operand_list)

def _get_member_index(self, operand_index: int) -> Optional[int]:

value = self.core_instr.operands[operand_index]

if (value & (1 << 63)) != 0:

value = None

return value

def _get_label(self, operand_index: int) -> GotoLabel:

return GotoLabel(self.function, self.core_instr.operands[operand_index])

def _get_constraint(self, operand_index: int) -> variable.PossibleValueSet:

value = core.BNGetCachedHighLevelILPossibleValueSet(self.function.handle, self.core_instr.operands[operand_index])

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

core.BNFreePossibleValueSet(value)

return result

@property

def raw_operands(self) -> OperandsType:

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

return self.instr.operands

@property

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

"""

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 detailed_operands(self) -> List[Tuple[str, HighLevelILOperandType, 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[['HighLevelILInstruction', Any], Any], *args: Any, shallow: bool = True, **kwargs: Any) -> Iterator[Any]:

"""

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

result of the callback function for each node in the AST. 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[[HighLevelILInstruction, Any], Any] cb: The callback function to call for each node in the HighLevelILInstruction

:param Any args: Custom user-defined arguments

:param bool shallow: Whether traversal occurs on block instructions

: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: HighLevelILInstruction, value: int) -> int:

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

... return inst.constant

>>>

>>> for result in inst.traverse(get_constant_less_than_value, 10):

... print(f"Found a constant {result} < 10 in {repr(inst)}")

:Example:

>>> def get_import_data_var_with_name(inst: HighLevelILInstruction, name: str) -> Optional['DataVariable']:

... if isinstance(inst, HighLevelILImport):

... if bv.get_symbol_at(inst.constant).name == name:

... return bv.get_data_var_at(inst.constant)

>>>

>>> for result in inst.traverse(get_import_data_var_with_name, "__cxa_finalize", shallow=False):

... print(f"Found import at {result} in {repr(inst)}")

"""

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

yield result

blacklisted_op_names = {'true', 'false', 'body', 'cases', 'default'}

for op_name, op, _ in self.detailed_operands:

if shallow and op_name in blacklisted_op_names:

continue

if isinstance(op, HighLevelILInstruction):

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

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

for i in op:

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

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

def visit_all(self, cb: HighLevelILVisitorCallback,

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

"""

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

Using pre-order traversal.

:param HighLevelILVisitorCallback 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, "HighLevelILInstruction", parent) == False:

return False

for name, op, opType in self.detailed_operands:

if isinstance(op, HighLevelILInstruction):

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

return False

elif isinstance(op, list) and all(isinstance(i, HighLevelILInstruction) 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:`HighLevelILInstruction.traverse` instead.")

def visit_operands(self, cb: HighLevelILVisitorCallback,

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

"""

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

:param HighLevelILVisitorCallback 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, HighLevelILInstruction):

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

return False

elif isinstance(op, list) and all(isinstance(i, HighLevelILInstruction) 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:`HighLevelILInstruction.traverse` instead.")

def visit(self, cb: HighLevelILVisitorCallback,

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

"""

Visits all HighLevelILInstructions 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 HighLevelILVisitorCallback 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 bv.hlil_instructions:

>>> inst.visit(visitor)

"""

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

return False

for name, op, _ in self.detailed_operands:

if isinstance(op, HighLevelILInstruction):

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

return False

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

for i in op:

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

return False

return True

@property

def has_side_effects(self) -> bool:

return core.BNHighLevelILHasSideEffects(self.function.handle, self.expr_index)

def get_lines(self, settings: Optional['function.DisassemblySettings'] = None) -> LinesType:

"""Gets HLIL text lines with optional settings"""

if settings is not None:

settings = settings.handle

count = ctypes.c_ulonglong()

lines = core.BNGetHighLevelILExprText(self.function.handle, self.expr_index, self.as_ast, count, settings)

assert lines is not None, "core.BNGetHighLevelILExprText returned None"

try:

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

addr = lines[i].addr

if lines[i].instrIndex != 0xffffffffffffffff:

il_instr = self.function[lines[i].instrIndex]

else:

il_instr = None

color = highlight.HighlightColor._from_core_struct(lines[i].highlight)

tokens = function.InstructionTextToken._from_core_struct(lines[i].tokens, lines[i].count)

yield function.DisassemblyTextLine(tokens, addr, il_instr, color)

finally:

core.BNFreeDisassemblyTextLines(lines, count.value)

@property

def can_collapse(self) -> bool:

"""If this instruction can be collapsed in rendered lines"""

return self.operation in [

HighLevelILOperation.HLIL_IF,

HighLevelILOperation.HLIL_WHILE,

HighLevelILOperation.HLIL_WHILE_SSA,

HighLevelILOperation.HLIL_DO_WHILE,

HighLevelILOperation.HLIL_DO_WHILE_SSA,

HighLevelILOperation.HLIL_FOR,

HighLevelILOperation.HLIL_FOR_SSA,

HighLevelILOperation.HLIL_SWITCH,

HighLevelILOperation.HLIL_CASE

]

def get_instruction_hash(self, discriminator: int) -> int:

"""

Hash of instruction matching the C++ HighLevelILInstruction::GetInstructionHash,

used for collapsed region matching.

:param discriminator: Extra value to include in the hash to differentiate regions

"""

def rotl(value, shift):

return ((value << shift) & 0xffffffffffffffff) | (value >> (64 - shift))

hash = self.operation.value

hash ^= rotl(self.address, 23)

hash ^= rotl(discriminator, 47)

return hash

@property

def derived_string_reference(self) -> Optional['binaryview.DerivedString']:

str = core.BNDerivedString()

if not core.BNGetHighLevelILDerivedStringReferenceForExpr(self.function.handle, self.expr_index, str):

return None

return binaryview.DerivedString._from_core_struct(str, True)

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

class HighLevelILUnaryBase(HighLevelILInstruction, UnaryOperation):

@property

def src(self) -> HighLevelILInstruction:

return self._get_expr(0)

@property

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

return [

("src", self.src, "HighLevelILInstruction"),

]