Move LLIL instruction retrieval into the LLIL function where it belongs

The python API was kept the same seeing as we are close to the release, will likely start deprecating some of those API's soon.

Author: emesare

binaryninjaapi.h

@@ -11345,16 +11345,6 @@ namespace BinaryNinja {
 		*/
 		Ref<LowLevelILFunction> GetLowLevelILIfAvailable() const;
 
-		/*! Get the Low Level IL Instruction start for an instruction at an address
-
-			\param arch Architecture for the instruction
-			\param addr Address of the instruction
-			\return Start address of the instruction
-		*/
-		size_t GetLowLevelILForInstruction(Architecture* arch, uint64_t addr);
-		std::set<size_t> GetLowLevelILInstructionsForAddress(Architecture* arch, uint64_t addr);
-		std::vector<size_t> GetLowLevelILExitsForInstruction(Architecture* arch, uint64_t addr);
-
 		std::pair<DataBuffer, BNBuiltinType> GetConstantData(
 			BNRegisterValueType state, uint64_t value, size_t size = 0);
 
@@ -12289,6 +12279,9 @@ namespace BinaryNinja {
 		uint64_t GetCurrentAddress() const;
 		void SetCurrentAddress(Architecture* arch, uint64_t addr);
 		size_t GetInstructionStart(Architecture* arch, uint64_t addr);
+		std::set<size_t> GetInstructionsAt(Architecture* arch, uint64_t addr);
+
+		std::vector<size_t> GetExitsForInstruction(size_t i);
 
 		void ClearIndirectBranches();
 		void SetIndirectBranches(const std::vector<ArchAndAddr>& branches);

binaryninjacore.h

@@ -37,14 +37,14 @@
 // Current ABI version for linking to the core. This is incremented any time
 // there are changes to the API that affect linking, including new functions,
 // new types, or modifications to existing functions or types.
-#define BN_CURRENT_CORE_ABI_VERSION 123
+#define BN_CURRENT_CORE_ABI_VERSION 124
 
 // Minimum ABI version that is supported for loading of plugins. Plugins that
 // are linked to an ABI version less than this will not be able to load and
 // will require rebuilding. The minimum version is increased when there are
 // incompatible changes that break binary compatibility, such as changes to
 // existing types or functions.
-#define BN_MINIMUM_CORE_ABI_VERSION 121
+#define BN_MINIMUM_CORE_ABI_VERSION 124
 
 #ifdef __GNUC__
 	#ifdef BINARYNINJACORE_LIBRARY
@@ -4787,11 +4787,6 @@ extern "C"
 
 	BINARYNINJACOREAPI BNLowLevelILFunction* BNGetFunctionLowLevelIL(BNFunction* func);
 	BINARYNINJACOREAPI BNLowLevelILFunction* BNGetFunctionLowLevelILIfAvailable(BNFunction* func);
-	BINARYNINJACOREAPI size_t BNGetLowLevelILForInstruction(BNFunction* func, BNArchitecture* arch, uint64_t addr);
-	BINARYNINJACOREAPI size_t* BNGetLowLevelILInstructionsForAddress(
-	    BNFunction* func, BNArchitecture* arch, uint64_t addr, size_t* count);
-	BINARYNINJACOREAPI size_t* BNGetLowLevelILExitsForInstruction(
-	    BNFunction* func, BNArchitecture* arch, uint64_t addr, size_t* count);
 	BINARYNINJACOREAPI void BNFreeILInstructionList(size_t* list);
 	BINARYNINJACOREAPI BNMediumLevelILFunction* BNGetFunctionMediumLevelIL(BNFunction* func);
 	BINARYNINJACOREAPI BNMediumLevelILFunction* BNGetFunctionMediumLevelILIfAvailable(BNFunction* func);
@@ -4837,9 +4832,6 @@ extern "C"
 
 	BINARYNINJACOREAPI BNLowLevelILFunction* BNGetFunctionLiftedIL(BNFunction* func);
 	BINARYNINJACOREAPI BNLowLevelILFunction* BNGetFunctionLiftedILIfAvailable(BNFunction* func);
-	BINARYNINJACOREAPI size_t BNGetLiftedILForInstruction(BNFunction* func, BNArchitecture* arch, uint64_t addr);
-	BINARYNINJACOREAPI size_t* BNGetLiftedILInstructionsForAddress(
-	    BNFunction* func, BNArchitecture* arch, uint64_t addr, size_t* count);
 	BINARYNINJACOREAPI size_t* BNGetLiftedILFlagUsesForDefinition(
 	    BNFunction* func, size_t i, uint32_t flag, size_t* count);
 	BINARYNINJACOREAPI size_t* BNGetLiftedILFlagDefinitionsForUse(
@@ -5967,6 +5959,10 @@ extern "C"
 	BINARYNINJACOREAPI void BNLowLevelILSetCurrentSourceBlock(BNLowLevelILFunction* func, BNBasicBlock* source);
 	BINARYNINJACOREAPI size_t BNLowLevelILGetInstructionStart(
 	    BNLowLevelILFunction* func, BNArchitecture* arch, uint64_t addr);
+	BINARYNINJACOREAPI size_t* BNLowLevelILGetInstructionsAt(
+		BNLowLevelILFunction* func, BNArchitecture* arch, uint64_t addr, size_t* count);
+	BINARYNINJACOREAPI size_t* BNLowLevelILGetExitsForInstruction(
+		BNLowLevelILFunction* func, size_t instr, size_t* count);
 	BINARYNINJACOREAPI void BNLowLevelILClearIndirectBranches(BNLowLevelILFunction* func);
 	BINARYNINJACOREAPI void BNLowLevelILSetIndirectBranches(
 	    BNLowLevelILFunction* func, BNArchitectureAndAddress* branches, size_t count);

function.cpp

@@ -460,39 +460,6 @@ Ref<LowLevelILFunction> Function::GetLowLevelILIfAvailable() const
 }
 
 
-size_t Function::GetLowLevelILForInstruction(Architecture* arch, uint64_t addr)
-{
-	return BNGetLowLevelILForInstruction(m_object, arch->GetObject(), addr);
-}
-
-
-set<size_t> Function::GetLowLevelILInstructionsForAddress(Architecture* arch, uint64_t addr)
-{
-	size_t count;
-	size_t* instrs = BNGetLowLevelILInstructionsForAddress(m_object, arch->GetObject(), addr, &count);
-
-	set<size_t> result;
-	for (size_t i = 0; i < count; i++)
-		result.insert(instrs[i]);
-
-	BNFreeILInstructionList(instrs);
-	return result;
-}
-
-
-vector<size_t> Function::GetLowLevelILExitsForInstruction(Architecture* arch, uint64_t addr)
-{
-	size_t count;
-	size_t* exits = BNGetLowLevelILExitsForInstruction(m_object, arch->GetObject(), addr, &count);
-
-	vector<size_t> result;
-	result.insert(result.end(), exits, &exits[count]);
-
-	BNFreeILInstructionList(exits);
-	return result;
-}
-
-
 RegisterValue RegisterValue::FromAPIObject(const BNRegisterValue& value)
 {
 	RegisterValue result;
@@ -795,26 +762,6 @@ Ref<LowLevelILFunction> Function::GetLiftedILIfAvailable() const
 }
 
 
-size_t Function::GetLiftedILForInstruction(Architecture* arch, uint64_t addr)
-{
-	return BNGetLiftedILForInstruction(m_object, arch->GetObject(), addr);
-}
-
-
-set<size_t> Function::GetLiftedILInstructionsForAddress(Architecture* arch, uint64_t addr)
-{
-	size_t count;
-	size_t* instrs = BNGetLiftedILInstructionsForAddress(m_object, arch->GetObject(), addr, &count);
-
-	set<size_t> result;
-	for (size_t i = 0; i < count; i++)
-		result.insert(instrs[i]);
-
-	BNFreeILInstructionList(instrs);
-	return result;
-}
-
-
 set<size_t> Function::GetLiftedILFlagUsesForDefinition(size_t i, uint32_t flag)
 {
 	size_t count;

lowlevelil.cpp

@@ -96,6 +96,29 @@ size_t LowLevelILFunction::GetInstructionStart(Architecture* arch, uint64_t addr
 	return BNLowLevelILGetInstructionStart(m_object, arch ? arch->GetObject() : nullptr, addr);
 }
 
+std::set<size_t> LowLevelILFunction::GetInstructionsAt(Architecture *arch, uint64_t addr)
+{
+	size_t count;
+	size_t* instructions = BNLowLevelILGetInstructionsAt(m_object, arch ? arch->GetObject() : nullptr, addr, &count);
+	std::set<size_t> result;
+	for (size_t i = 0; i < count; i++)
+		result.insert(instructions[i]);
+	BNFreeILInstructionList(instructions);
+	return result;
+}
+
+std::vector<size_t> LowLevelILFunction::GetExitsForInstruction(size_t i)
+{
+	size_t count;
+	size_t* instructions = BNLowLevelILGetExitsForInstruction(m_object, i, &count);
+	std::vector<size_t> result;
+	result.reserve(count);
+	for (size_t j = 0; j < count; j++)
+		result.push_back(instructions[j]);
+	BNFreeILInstructionList(instructions);
+	return result;
+}
+
 
 void LowLevelILFunction::ClearIndirectBranches()
 {

plugins/efi_resolver/src/Resolver.cpp

@@ -308,7 +308,7 @@ vector<HighLevelILInstruction> Resolver::HighLevelILExprsAt(Ref<Function> func,
 	auto mlil = func->GetMediumLevelIL();
 	auto hlil = func->GetHighLevelIL();
 
-	size_t llilIdx = func->GetLowLevelILForInstruction(arch, addr);
+	size_t llilIdx = llil->GetInstructionStart(arch, addr);
 	size_t llilExprIdx = llil->GetIndexForInstruction(llilIdx);
 	auto mlilIdxes = llil->GetMediumLevelILExprIndexes(llilExprIdx);
 

python/function.py

@@ -1852,15 +1852,12 @@ def get_low_level_il_at(
 			>>> func.get_low_level_il_at(func.start)
 			<il: push(rbp)>
 		"""
-		if arch is None:
-			arch = self.arch
-
-		idx = core.BNGetLowLevelILForInstruction(self.handle, arch.handle, addr)
-
 		llil = self.llil
-		if llil is None or idx == len(llil):
+		if llil is None:
+			return None
+		idx = llil.get_instruction_start(addr, arch)
+		if idx is None:
 			return None
-
 		return llil[idx]
 
 	def get_low_level_ils_at(self, addr: int,
@@ -1881,19 +1878,7 @@ def get_low_level_ils_at(self, addr: int,
 		llil = self.llil
 		if llil is None:
 			return []
-
-		if arch is None:
-			arch = self.arch
-		count = ctypes.c_ulonglong()
-		instrs = core.BNGetLowLevelILInstructionsForAddress(self.handle, arch.handle, addr, count)
-		assert instrs is not None, "core.BNGetLowLevelILInstructionsForAddress returned None"
-		try:
-			result = []
-			for i in range(0, count.value):
-				result.append(llil[instrs[i]])
-			return result
-		finally:
-			core.BNFreeILInstructionList(instrs)
+		return [llil[i] for i in llil.get_instructions_at(addr, arch)]
 
 	def get_llil_at(self, addr: int,
 	                arch: Optional['architecture.Architecture'] = None) -> Optional['lowlevelil.LowLevelILInstruction']:
@@ -1929,33 +1914,16 @@ def get_llils_at(self, addr: int,
 		llil = self.llil
 		if llil is None:
 			return []
-
-		if arch is None:
-			arch = self.arch
-		count = ctypes.c_ulonglong()
-		instrs = core.BNGetLowLevelILInstructionsForAddress(self.handle, arch.handle, addr, count)
-		assert instrs is not None, "core.BNGetLowLevelILInstructionsForAddress returned None"
-		try:
-			result = []
-			for i in range(0, count.value):
-				result.append(llil[instrs[i]])
-			return result
-		finally:
-			core.BNFreeILInstructionList(instrs)
+		return [llil[i] for i in llil.get_instructions_at(addr, arch)]
 
 	def get_low_level_il_exits_at(self, addr: int, arch: Optional['architecture.Architecture'] = None) -> List[int]:
-		if arch is None:
-			arch = self.arch
-		count = ctypes.c_ulonglong()
-		exits = core.BNGetLowLevelILExitsForInstruction(self.handle, arch.handle, addr, count)
-		assert exits is not None, "core.BNGetLowLevelILExitsForInstruction returned None"
-		try:
-			result = []
-			for i in range(0, count.value):
-				result.append(exits[i])
-			return result
-		finally:
-			core.BNFreeILInstructionList(exits)
+		llil = self.llil
+		if llil is None:
+			return []
+		idx = llil.get_instruction_start(addr, arch)
+		if idx is None:
+			return []
+		return llil.get_exits_for_instr(idx)
 
 	def get_constant_data(self, state: RegisterValueType, value: int, size: int = 0) -> databuffer.DataBuffer:
 		return databuffer.DataBuffer(handle=core.BNGetConstantData(self.handle, state, value, size, None))
@@ -2144,15 +2112,13 @@ def get_stack_vars_referenced_by_address_if_available(
 	def get_lifted_il_at(
 	    self, addr: int, arch: Optional['architecture.Architecture'] = None
 	) -> Optional['lowlevelil.LowLevelILInstruction']:
-		if arch is None:
-			arch = self.arch
-
-		idx = core.BNGetLiftedILForInstruction(self.handle, arch.handle, addr)
-
-		if idx == len(self.lifted_il):
+		lifted_il = self.lifted_il
+		if lifted_il is None:
 			return None
-
-		return self.lifted_il[idx]
+		idx = lifted_il.get_instruction_start(addr, arch)
+		if idx is None:
+			return None
+		return lifted_il[idx]
 
 	def get_lifted_ils_at(
 	    self, addr: int, arch: Optional['architecture.Architecture'] = None
@@ -2168,16 +2134,10 @@ def get_lifted_ils_at(
 			>>> func.get_lifted_ils_at(func.start)
 			[<il: push(rbp)>]
 		"""
-		if arch is None:
-			arch = self.arch
-		count = ctypes.c_ulonglong()
-		instrs = core.BNGetLiftedILInstructionsForAddress(self.handle, arch.handle, addr, count)
-		assert instrs is not None, "core.BNGetLiftedILInstructionsForAddress returned None"
-		result = []
-		for i in range(0, count.value):
-			result.append(self.lifted_il[instrs[i]])
-		core.BNFreeILInstructionList(instrs)
-		return result
+		lifted_il = self.lifted_il
+		if lifted_il is None:
+			return []
+		return [lifted_il[i] for i in lifted_il.get_instructions_at(addr, arch)]
 
 	def get_constants_referenced_by(self, addr: int,
 	                                arch: Optional['architecture.Architecture'] = None) -> List[variable.ConstantReference]:

python/lowlevelil.py

@@ -3799,6 +3799,45 @@ def get_instruction_start(self, addr: int, arch: Optional['architecture.Architec
 			return None
 		return InstructionIndex(result)
 
+	def get_instructions_at(self, addr: int, arch: Optional['architecture.Architecture'] = None) -> List[InstructionIndex]:
+		"""
+		``get_instructions_at`` gets the InstructionIndex(s) corresponding to the given virtual address
+		See the `docs for mappings between ils <https://dev-docs.binary.ninja/dev/concepts.html#mapping-between-ils>`_ for more information.
+
+		:param int addr: virtual address of the instruction to be queried
+		:param Architecture arch: (optional) Architecture for the given function
+		:rtype: list(InstructionIndex)
+		:Example:
+
+			>>> func = next(bv.functions)
+			>>> func.llil.get_instructions_at(func.start)
+			[0]
+		"""
+		if arch is None:
+			arch = self.arch
+		count = ctypes.c_ulonglong()
+		instrs = core.BNLowLevelILGetInstructionsAt(self.handle, arch.handle, addr, count)
+		assert instrs is not None, "core.BNLowLevelILGetInstructionsAt returned None"
+		try:
+			result = []
+			for i in range(0, count.value):
+				result.append(instrs[i])
+			return result
+		finally:
+			core.BNFreeILInstructionList(instrs)
+
+	def get_exits_for_instr(self, idx: InstructionIndex) -> List[InstructionIndex]:
+		count = ctypes.c_ulonglong()
+		exits = core.BNLowLevelILGetExitsForInstruction(self.handle, idx, count)
+		assert exits is not None, "core.BNLowLevelILGetExitsForInstruction returned None"
+		try:
+			result = []
+			for i in range(0, count.value):
+				result.append(exits[i])
+			return result
+		finally:
+			core.BNFreeILInstructionList(exits)
+
 	def clear_indirect_branches(self) -> None:
 		core.BNLowLevelILClearIndirectBranches(self.handle)