Add a reason field to MLIL_FORCE_VER for use in automated variable splitting

Author: D0ntPanic

binaryninjaapi.h

@@ -15912,8 +15912,10 @@ namespace BinaryNinja {
 		ExprId SetVarAliasedField(size_t size, const Variable& dest, size_t newMemVersion, size_t prevMemVersion,
 		    uint64_t offset, ExprId src, const ILSourceLocation& loc = ILSourceLocation());
 
-		ExprId ForceVer(size_t size, const Variable& dest, const Variable& src, const ILSourceLocation& loc = ILSourceLocation());
-		ExprId ForceVerSSA(size_t size, const SSAVariable& dest, const SSAVariable& src, const ILSourceLocation& loc = ILSourceLocation());
+		ExprId ForceVer(size_t size, const Variable& dest, const Variable& src, BNForceVersionReason reason,
+			const ILSourceLocation& loc = ILSourceLocation());
+		ExprId ForceVerSSA(size_t size, const SSAVariable& dest, const SSAVariable& src, BNForceVersionReason raeson,
+			const ILSourceLocation& loc = ILSourceLocation());
 
 		ExprId Assert(size_t size, const Variable& src, const PossibleValueSet& pvs, const ILSourceLocation& loc = ILSourceLocation());
 		ExprId AssertSSA(size_t size, const SSAVariable& src, const PossibleValueSet& pvs, const ILSourceLocation& loc = ILSourceLocation());

binaryninjacore.h

@@ -1590,6 +1590,12 @@ extern "C"
 		size_t operand;
 	} BNMediumLevelILLabel;
 
+	BN_ENUM(uint8_t, BNForceVersionReason)
+	{
+		UserForceVersionReason,
+		PartialAccessAnalysisForceVersionReason
+	};
+
 	BN_ENUM(uint8_t, BNVariableSourceType)
 	{
 		StackVariableSourceType,

mediumlevelilinstruction.cpp

@@ -96,6 +96,7 @@ static constexpr std::array s_operandTypeForUsage = {
 	OperandUsageType{ParameterSSAMemoryVersionMediumLevelOperandUsage, IndexMediumLevelOperand},
 	OperandUsageType{SourceSSAVariablesMediumLevelOperandUsages, SSAVariableListMediumLevelOperand},
 	OperandUsageType{ConstraintMediumLevelOperandUsage, ConstraintMediumLevelOperand},
+	OperandUsageType{ForceVersionReasonMediumLevelOperandUsage, ForceVersionReasonMediumLevelOperand},
 };
 
 static_assert(std::is_sorted(s_operandTypeForUsage.begin(), s_operandTypeForUsage.end()),
@@ -160,7 +161,7 @@ static constexpr std::array s_instructionOperandUsage = {
 	OperandUsage{MLIL_SET_VAR_FIELD, {DestVariableMediumLevelOperandUsage, OffsetMediumLevelOperandUsage, SourceExprMediumLevelOperandUsage}},
 	OperandUsage{MLIL_SET_VAR_SPLIT, {HighVariableMediumLevelOperandUsage, LowVariableMediumLevelOperandUsage, SourceExprMediumLevelOperandUsage}},
 	OperandUsage{MLIL_ASSERT, {SourceVariableMediumLevelOperandUsage, ConstraintMediumLevelOperandUsage}},
-	OperandUsage{MLIL_FORCE_VER, {DestVariableMediumLevelOperandUsage, SourceVariableMediumLevelOperandUsage}},
+	OperandUsage{MLIL_FORCE_VER, {DestVariableMediumLevelOperandUsage, SourceVariableMediumLevelOperandUsage, ForceVersionReasonMediumLevelOperandUsage}},
 	OperandUsage{MLIL_LOAD, {SourceExprMediumLevelOperandUsage}},
 	OperandUsage{MLIL_LOAD_STRUCT, {SourceExprMediumLevelOperandUsage, OffsetMediumLevelOperandUsage}},
 	OperandUsage{MLIL_STORE, {DestExprMediumLevelOperandUsage, SourceExprMediumLevelOperandUsage}},
@@ -280,7 +281,7 @@ static constexpr std::array s_instructionOperandUsage = {
 	OperandUsage{MLIL_VAR_ALIASED_FIELD, {SourceSSAVariableMediumLevelOperandUsage, OffsetMediumLevelOperandUsage}},
 	OperandUsage{MLIL_VAR_SPLIT_SSA, {HighSSAVariableMediumLevelOperandUsage, LowSSAVariableMediumLevelOperandUsage}},
 	OperandUsage{MLIL_ASSERT_SSA, {SourceSSAVariableMediumLevelOperandUsage, ConstraintMediumLevelOperandUsage}},
-	OperandUsage{MLIL_FORCE_VER_SSA, {DestSSAVariableMediumLevelOperandUsage, SourceSSAVariableMediumLevelOperandUsage}},
+	OperandUsage{MLIL_FORCE_VER_SSA, {DestSSAVariableMediumLevelOperandUsage, SourceSSAVariableMediumLevelOperandUsage, ForceVersionReasonMediumLevelOperandUsage}},
 	OperandUsage{MLIL_CALL_SSA, {OutputExprsSubExprMediumLevelOperandUsage, OutputSSAMemoryVersionMediumLevelOperandUsage, DestExprMediumLevelOperandUsage, ParameterExprsMediumLevelOperandUsage, SourceMemoryVersionMediumLevelOperandUsage}},
 	OperandUsage{MLIL_CALL_UNTYPED_SSA, {OutputExprsSubExprMediumLevelOperandUsage, OutputSSAMemoryVersionMediumLevelOperandUsage, DestExprMediumLevelOperandUsage, UntypedParameterSSAExprsMediumLevelOperandUsage, ParameterSSAMemoryVersionMediumLevelOperandUsage, StackExprMediumLevelOperandUsage}},
 	OperandUsage{MLIL_SYSCALL_SSA, {OutputExprsSubExprMediumLevelOperandUsage, OutputSSAMemoryVersionMediumLevelOperandUsage, ParameterExprsMediumLevelOperandUsage, SourceMemoryVersionMediumLevelOperandUsage}},
@@ -1724,9 +1725,11 @@ ExprId MediumLevelILInstruction::CopyTo(MediumLevelILFunction* dest,
 			GetSourceSSAVariable<MLIL_VAR_OUTPUT_ALIASED_FIELD>().version,
 			GetOffset<MLIL_VAR_OUTPUT_ALIASED_FIELD>(), loc);
 	case MLIL_FORCE_VER:
-		return dest->ForceVer(size, GetDestVariable<MLIL_FORCE_VER>(), GetSourceVariable<MLIL_FORCE_VER>(), loc);
+		return dest->ForceVer(size, GetDestVariable<MLIL_FORCE_VER>(), GetSourceVariable<MLIL_FORCE_VER>(),
+			GetForceVersionReason<MLIL_FORCE_VER>(), loc);
 	case MLIL_FORCE_VER_SSA:
-		return dest->ForceVerSSA(size, GetDestSSAVariable<MLIL_FORCE_VER_SSA>(), GetSourceSSAVariable<MLIL_FORCE_VER_SSA>(), loc);
+		return dest->ForceVerSSA(size, GetDestSSAVariable<MLIL_FORCE_VER_SSA>(), GetSourceSSAVariable<MLIL_FORCE_VER_SSA>(),
+			GetForceVersionReason<MLIL_FORCE_VER_SSA>(), loc);
 	case MLIL_ASSERT:
 		return dest->Assert(size, GetSourceVariable<MLIL_ASSERT>(), GetConstraint<MLIL_ASSERT>(), loc);
 	case MLIL_ASSERT_SSA:
@@ -2375,6 +2378,15 @@ MediumLevelILSSAVariableList MediumLevelILInstruction::GetSourceSSAVariables() c
 }
 
 
+BNForceVersionReason MediumLevelILInstruction::GetForceVersionReason() const
+{
+	size_t operandIndex;
+	if (GetOperandIndexForUsage(ForceVersionReasonMediumLevelOperandUsage, operandIndex))
+		return (BNForceVersionReason)GetRawOperandAsInteger(operandIndex);
+	throw MediumLevelILInstructionAccessException();
+}
+
+
 vector<Variable> MediumLevelILCallInstruction::GetOutputVariables() const
 {
 	vector<Variable> result;
@@ -2486,15 +2498,18 @@ ExprId MediumLevelILFunction::SetVarAliasedField(size_t size, const Variable& de
 }
 
 
-ExprId MediumLevelILFunction::ForceVer(size_t size, const Variable& dest, const Variable& src, const ILSourceLocation& loc)
+ExprId MediumLevelILFunction::ForceVer(size_t size, const Variable& dest, const Variable& src,
+	BNForceVersionReason reason, const ILSourceLocation& loc)
 {
-	return AddExprWithLocation(MLIL_FORCE_VER, loc, size, dest.ToIdentifier(), src.ToIdentifier());
+	return AddExprWithLocation(MLIL_FORCE_VER, loc, size, dest.ToIdentifier(), src.ToIdentifier(), reason);
 }
 
 
-ExprId MediumLevelILFunction::ForceVerSSA(size_t size, const SSAVariable& dest, const SSAVariable& src, const ILSourceLocation& loc)
+ExprId MediumLevelILFunction::ForceVerSSA(size_t size, const SSAVariable& dest, const SSAVariable& src,
+	BNForceVersionReason reason, const ILSourceLocation& loc)
 {
-	return AddExprWithLocation(MLIL_FORCE_VER_SSA, loc, size, dest.var.ToIdentifier(), dest.version, src.var.ToIdentifier(), src.version);
+	return AddExprWithLocation(MLIL_FORCE_VER_SSA, loc, size, dest.var.ToIdentifier(), dest.version,
+		src.var.ToIdentifier(), src.version, reason);
 }
 
 

mediumlevelilinstruction.h

@@ -105,7 +105,8 @@ namespace BinaryNinja
 		VariableListMediumLevelOperand,
 		SSAVariableListMediumLevelOperand,
 		ExprListMediumLevelOperand,
-		ConstraintMediumLevelOperand
+		ConstraintMediumLevelOperand,
+		ForceVersionReasonMediumLevelOperand
 	};
 
 	/*!
@@ -154,7 +155,8 @@ namespace BinaryNinja
 		UntypedParameterSSAExprsMediumLevelOperandUsage,
 		ParameterSSAMemoryVersionMediumLevelOperandUsage,
 		SourceSSAVariablesMediumLevelOperandUsages,
-		ConstraintMediumLevelOperandUsage
+		ConstraintMediumLevelOperandUsage,
+		ForceVersionReasonMediumLevelOperandUsage
 	};
 }  // namespace BinaryNinjaCore
 
@@ -800,6 +802,11 @@ namespace BinaryNinja
 		{
 			return As<N>().GetConstraint();
 		}
+		template <BNMediumLevelILOperation N>
+		BNForceVersionReason GetForceVersionReason() const
+		{
+			return As<N>().GetForceVersionReason();
+		}
 
 		template <BNMediumLevelILOperation N>
 		void SetDestSSAVersion(size_t version)
@@ -899,6 +906,7 @@ namespace BinaryNinja
 		MediumLevelILInstructionList GetParameterExprs() const;
 		MediumLevelILInstructionList GetSourceExprs() const;
 		MediumLevelILSSAVariableList GetSourceSSAVariables() const;
+		BNForceVersionReason GetForceVersionReason() const;
 	};
 
 	/*!
@@ -1122,6 +1130,7 @@ namespace BinaryNinja
 	{
 		Variable GetDestVariable() const { return GetRawOperandAsVariable(0); }
 		Variable GetSourceVariable() const { return GetRawOperandAsVariable(1); }
+		BNForceVersionReason GetForceVersionReason() const { return (BNForceVersionReason)GetRawOperandAsInteger(2); }
 	};
 	template <>
 	struct MediumLevelILInstructionAccessor<MLIL_FORCE_VER_SSA> : public MediumLevelILInstructionBase
@@ -1130,6 +1139,7 @@ namespace BinaryNinja
 		void SetDestSSAVersion(size_t version) { UpdateRawOperand(1, version); }
 		SSAVariable GetSourceSSAVariable() const { return GetRawOperandAsSSAVariable(2); }
 		void SetSourceSSAVersion(size_t version) { UpdateRawOperand(3, version); }
+		BNForceVersionReason GetForceVersionReason() const { return (BNForceVersionReason)GetRawOperandAsInteger(4); }
 	};
 	template <>
 	struct MediumLevelILInstructionAccessor<MLIL_ASSERT> : public MediumLevelILInstructionBase

python/mediumlevelil.py

@@ -27,7 +27,7 @@
 
 # Binary Ninja components
 from . import _binaryninjacore as core
-from .enums import MediumLevelILOperation, ILBranchDependence, DataFlowQueryOption, FunctionGraphType, DeadStoreElimination, ILInstructionAttribute, StringType
+from .enums import MediumLevelILOperation, ILBranchDependence, DataFlowQueryOption, FunctionGraphType, DeadStoreElimination, ILInstructionAttribute, StringType, ForceVersionReason
 from . import basicblock
 from . import function
 from . import types
@@ -3444,6 +3444,10 @@ def dest(self) -> variable.Variable:
 	def src(self) -> variable.Variable:
 		return self._get_var(1)
 
+	@property
+	def reason(self) -> ForceVersionReason:
+		return ForceVersionReason(self._get_int(2))
+
 @dataclass(frozen=True, repr=False, eq=False)
 class MediumLevelILForceVerSsa(MediumLevelILInstruction, SSA):
 	@property
@@ -3454,6 +3458,10 @@ def dest(self) -> SSAVariable:
 	def src(self) -> SSAVariable:
 		return self._get_var_ssa(2, 3)
 
+	@property
+	def reason(self) -> ForceVersionReason:
+		return ForceVersionReason(self._get_int(4))
+
 @dataclass(frozen=True, repr=False, eq=False)
 class MediumLevelILBlockToExpand(MediumLevelILInstruction):
 	@property
@@ -4117,7 +4125,7 @@ def do_copy(
 				return dest.var_output_field(expr.size, expr.dest, expr.offset, loc)
 			if expr.operation == MediumLevelILOperation.MLIL_FORCE_VER:
 				expr: MediumLevelILForceVer
-				return dest.force_ver(expr.size, expr.dest, expr.src, loc)
+				return dest.force_ver(expr.size, expr.dest, expr.src, expr.reason, loc)
 			if expr.operation == MediumLevelILOperation.MLIL_ASSERT:
 				expr: MediumLevelILAssert
 				return dest.assert_expr(expr.size, expr.src, expr.constraint, loc)
@@ -4796,6 +4804,7 @@ def force_ver(
 		size: int,
 		dest: 'variable.CoreVariable',
 		src: 'variable.CoreVariable',
+		reason: ForceVersionReason = ForceVersionReason.UserForceVersionReason,
 		loc: Optional['ILSourceLocation'] = None
 	) -> ExpressionIndex:
 		"""
@@ -4806,11 +4815,12 @@ def force_ver(
 		:param int size: size of the variable
 		:param Variable dest: the variable to force a new version of
 		:param Variable src: the variable created with the new version
+		:param ForceVersionReason reason: reason for forcing the version
 		:param ILSourceLocation loc: location of returned expression
 		:return: The expression ``FORCE_VER(reg)``
 		:rtype: ExpressionIndex
 		"""
-		return self.expr(MediumLevelILOperation.MLIL_FORCE_VER, dest.identifier, src.identifier, size=size, source_location=loc)
+		return self.expr(MediumLevelILOperation.MLIL_FORCE_VER, dest.identifier, src.identifier, int(reason), size=size, source_location=loc)
 
 	def address_of(self, var: 'variable.CoreVariable', loc: Optional['ILSourceLocation'] = None) -> ExpressionIndex:
 		"""