callingconvention module

Class

Description

binaryninja.callingconvention.CallLayout

binaryninja.callingconvention.CallingConvention

class CallingConvention describes how parameters, return values, and the stack are handled…

binaryninja.callingconvention.CoreCallingConvention

class CallingConvention describes how parameters, return values, and the stack are handled…

CallLayout

class CallLayout[source]

Bases: object

CallLayout(parameters: List[ForwardRef(‘types.ValueLocation’)], return_value: Optional[ForwardRef(‘types.ValueLocation’)], stack_adjustment: int, reg_stack_adjustments: Dict[ForwardRef(‘architecture.RegisterIndex’), int])

__init__(parameters: List[ValueLocation], return_value: ValueLocation | None, stack_adjustment: int, reg_stack_adjustments: Dict[RegisterIndex, int]) → None
Parameters:
Return type:

None

parameters: List[ValueLocation]
reg_stack_adjustments: Dict[RegisterIndex, int]
return_value: ValueLocation | None
stack_adjustment: int

CallingConvention

class CallingConvention[source]

Bases: object

class CallingConvention describes how parameters, return values, and the stack are handled when a function is called. Subclasses of CallingConvention define the behavior of a calling convention by setting the class attributes below and, where necessary, overriding the methods.

Variables:

  • name – The name of this calling convention.

  • caller_saved_regs – The list of registers that are not preserved across a call (caller-saved / volatile registers).

  • callee_saved_regs – The list of registers that a callee must preserve across a call (callee-saved / non-volatile registers).

  • int_arg_regs – The registers used to pass integer and pointer arguments, in the order they are used.

  • float_arg_regs – The registers used to pass floating point arguments, in the order they are used.

  • required_arg_regs – The set of registers that must be arguments for heuristic calling convention detection to consider this calling convention as a valid option.

  • required_clobbered_regs – The set of registers that must be clobbered for heuristic calling convention detection to consider this calling convention as a valid option.

  • arg_regs_share_index – Whether the integer and floating point argument registers share a single argument index. When True, the Nth argument consumes the Nth slot of both the integer and float register lists regardless of its type. When False, integer and float arguments are assigned from their respective register lists independently.

  • arg_regs_for_varargs – Whether argument registers are used to pass variadic arguments.

  • stack_reserved_for_arg_regs – Whether stack space is reserved by the caller for the register arguments (for example, the shadow/home space used by the Windows x64 calling convention).

  • stack_adjusted_on_return – Whether the callee adjusts the stack to remove the arguments before returning (as in stdcall), rather than leaving the caller to clean up the stack (as in cdecl).

  • eligible_for_heuristics – Whether this calling convention may be selected by heuristic calling convention detection.

  • int_return_reg – The register that holds the integer return value.

  • high_int_return_reg – The register that holds the high part of an integer return value that is too large to fit in a single register, or None if there is none.

  • float_return_reg – The register that holds the floating point return value, or None if there is none.

  • global_pointer_reg – Deprecated. Use global_pointer_regs instead. The register that holds the global pointer, if the calling convention defines one, or None if there is none.

  • global_pointer_regs – The registers that hold global pointers, if the calling convention defines any.

  • implicitly_defined_regs – The registers that are implicitly given a known value on function entry by this calling convention.

  • stack_args_naturally_aligned – Whether arguments passed on the stack are aligned to their natural alignment. If False, arguments are aligned to the address size.

  • stack_args_pushed_left_to_right – Whether arguments passed on the stack are pushed left-to-right, as opposed to the more common right-to-left order.

__init__(arch: Architecture | None = None, name: str | None = None, handle=None, confidence: int = 255)[source]
Parameters:
default_is_arg_type_reg_compatible(type: Type) → bool[source]

default_is_arg_type_reg_compatible is the default implementation of is_arg_type_reg_compatible. The default implementation allows register arguments for types that fit in a single register, or are a floating point type when float_arg_regs has valid registers.

Parameters:

type (Type) – argument type to check

Returns:

whether the argument type is register compatible

Return type:

bool

default_is_return_type_reg_compatible(type: Type) → bool[source]

default_is_return_type_reg_compatible is the default implementation of is_return_type_reg_compatible. The default implementation allows register returns for types that fit in a single register, have a size equal to two registers when high_int_return_reg is set, or are a floating point type when float_return_reg is set.

Parameters:

type (Type) – return type to check

Returns:

whether the return type is register compatible

Return type:

bool

get_call_layout(view: BinaryView | None, return_value: types.ReturnValueOrType | None, params: types.ParamsType, func: Function | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → CallLayout[source]

get_call_layout computes the complete call layout (parameter locations, return value location, and stack adjustments) for a call with the given return value and parameters. It is recommended to only override this method if the calling convention behavior cannot be modeled with get_return_value_location and/or get_parameter_locations.

The default implementation calls get_default_call_layout.

When calling this method to query the layout of a function, the return value and parameters should have their named type references dereferenced before passing them to this method. Calling the methods BinaryView.deref_return_value_named_type_references and BinaryView.deref_parameter_named_type_references will perform this dereferencing.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType | None) – return value of the call

  • params (types.ParamsType) – parameters of the call

  • func (Function) – function used to resolve the architecture of the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the computed call layout

Return type:

CallLayout

get_default_call_layout(view: BinaryView | None, return_value: types.ReturnValueOrType | None, params: types.ParamsType, func: Function | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → CallLayout[source]

get_default_call_layout is the default implementation of get_call_layout. The default implementation uses get_return_value_location, get_parameter_locations, get_stack_adjustment_for_locations, and get_register_stack_adjustments to compute the layout.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType | None) – return value of the call

  • params (types.ParamsType) – parameters of the call

  • func (Function) – function used to resolve the architecture of the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the computed call layout

Return type:

CallLayout

get_default_indirect_return_value_location() → CoreVariable[source]

get_default_indirect_return_value_location is the default implementation of get_indirect_return_value_location. The default location is the first integer argument register, or the first stack slot if there are no integer argument registers.

Returns:

the location of the indirect return value pointer

Return type:

CoreVariable

get_default_parameter_locations(view: BinaryView | None, return_value: ValueLocation | None, params: types.ParamsType, arch: Architecture | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → List[ValueLocation][source]

get_default_parameter_locations is the default implementation of get_parameter_locations. The default implementation uses int_arg_regs, float_arg_regs, arg_regs_share_index, stack_reserved_for_arg_regs, is_arg_type_reg_compatible, is_non_reg_arg_indirect, stack_args_naturally_aligned, and stack_args_pushed_left_to_right to compute the parameter layout.

This function is usually sufficient unless the calling convention has unusual parameter passing behavior. Most calling conventions can be defined per-argument using the attributes and methods listed above.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (ValueLocation | None) – optional location of the return value

  • params (types.ParamsType) – parameters of the call

  • arch (Architecture) – architecture used to resolve the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the locations of the parameters, in order

Return type:

List[ValueLocation]

get_default_parameter_ordering_for_variables(params: Dict[CoreVariable, Type]) → List[CoreVariable][source]

get_default_parameter_ordering_for_variables is the default implementation of get_parameter_ordering_for_variables. The default implementation first checks arg_regs_share_index to see if the parameter ordering is well defined. If the arguments do not share an index, it places all integer arguments before the floating point arguments. Arguments that are not passed in a normal location are placed last.

Parameters:

params (Dict[CoreVariable, Type]) – map of parameter variables to their types

Returns:

the parameter variables in the order they are passed

Return type:

List[CoreVariable]

get_default_register_stack_adjustments(return_value: ValueLocation | None, params: List[ValueLocation]) → Dict[RegisterIndex, int][source]

get_default_register_stack_adjustments is the default implementation of get_register_stack_adjustments. The default implementation compares the register stack slots used by the parameters and the return value to compute the adjustments.

Parameters:
Returns:

a map from register stack index to its adjustment

Return type:

Dict[RegisterIndex, int]

get_default_return_value_location(view: BinaryView | None, return_value: types.ReturnValueOrType) → ValueLocation | None[source]

get_default_return_value_location is the default implementation of get_return_value_location. The default implementation checks is_return_type_reg_compatible and places the return value in registers if it can, or uses an indirect return by pointer if not. If an indirect return is required, then get_indirect_return_value_location and get_returned_indirect_return_value_pointer are used to provide the location of the indirect return value.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType) – return value to compute the location for

Returns:

the location of the return value

Return type:

Optional[ValueLocation]

get_default_stack_adjustment_for_locations(return_value: ValueLocation | None, params: List[Tuple[ValueLocation, Type]])[source]

get_default_stack_adjustment_for_locations is the default implementation of get_stack_adjustment_for_locations. The default implementation first checks stack_adjusted_on_return, and returns zero if that is False. Otherwise, it checks the stack parameter locations and stack_args_naturally_aligned to compute the stack adjustment necessary to cover all parameters.

Parameters:
Returns:

the stack adjustment in bytes

Return type:

int

get_incoming_flag_value(reg: RegisterName, func: Function) → RegisterValue[source]

get_incoming_flag_value gets the known value of a flag on entry to a function.

Parameters:

  • reg (RegisterName) – flag to query

  • func (Function) – function being analyzed

Returns:

the incoming value of the flag

Return type:

RegisterValue

get_incoming_reg_value(reg: RegisterName, func: Function) → RegisterValue[source]

get_incoming_reg_value gets the known value of a register on entry to a function.

Parameters:

  • reg (RegisterName) – register to query

  • func (Function) – function being analyzed

Returns:

the incoming value of the register

Return type:

RegisterValue

get_incoming_var_for_parameter_var(in_var: CoreVariable, func: Function | None = None) → CoreVariable[source]

get_incoming_var_for_parameter_var gets the incoming variable that corresponds to the given parameter variable. This is the inverse of get_parameter_var_for_incoming_var.

Parameters:
Returns:

the incoming variable corresponding to the parameter variable

Return type:

CoreVariable

get_indirect_return_value_location() → CoreVariable[source]

get_indirect_return_value_location gets the location used to pass the hidden pointer argument for return values that are returned indirectly through memory.

Returns:

the location of the indirect return value pointer

Return type:

CoreVariable

get_parameter_locations(view: BinaryView | None, return_value: ValueLocation | None, params: types.ParamsType, arch: Architecture | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → List[ValueLocation][source]

get_parameter_locations computes the locations of the parameters for a call with the given return value and parameters.

The default implementation calls get_default_parameter_locations.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (ValueLocation | None) – optional location of the return value, which may affect parameter placement (for example, when an indirect return pointer consumes an argument register)

  • params (types.ParamsType) – parameters of the call

  • arch (Architecture) – architecture used to resolve the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the locations of the parameters, in order

Return type:

List[ValueLocation]

get_parameter_ordering_for_variables(view: BinaryView | None, params: Dict[CoreVariable, Type]) → List[CoreVariable][source]

get_parameter_ordering_for_variables computes the order in which the given parameter variables are passed. Used by the heuristic calling convention detection to create a function type from a list of parameter variables.

The default implementation calls get_default_parameter_ordering_for_variables.

Parameters:
Returns:

the parameter variables in the order they are passed

Return type:

List[CoreVariable]

get_parameter_var_for_incoming_var(in_var: CoreVariable, func: Function | None = None) → CoreVariable[source]

get_parameter_var_for_incoming_var gets the parameter variable that corresponds to the given incoming variable. This is the inverse of get_incoming_var_for_parameter_var.

Parameters:
Returns:

the parameter variable corresponding to the incoming variable

Return type:

CoreVariable

get_register_stack_adjustments(view: BinaryView | None, return_value: ValueLocation | None, params: List[ValueLocation]) → Dict[RegisterIndex, int][source]

get_register_stack_adjustments computes the per-register-stack adjustments (for architectures with register stacks, such as the x87 floating point stack) for a call with the given return value and parameter locations.

The default implementation calls get_default_register_stack_adjustments.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (ValueLocation | None) – optional location of the return value

  • params (List[ValueLocation]) – locations of the parameters

Returns:

a map from register stack index to its adjustment

Return type:

Dict[RegisterIndex, int]

get_return_value_location(view: BinaryView | None, return_value: types.ReturnValueOrType) → ValueLocation | None[source]

get_return_value_location computes the location of the return value for the given return value type and location structure.

The default implementation calls get_default_return_value_location.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType) – return value to compute the location for

Returns:

the location of the return value

Return type:

Optional[ValueLocation]

get_returned_indirect_return_value_pointer() → CoreVariable | None[source]

get_returned_indirect_return_value_pointer gets the location in which the hidden indirect return value pointer is returned to the caller, for calling conventions that return it.

Returns:

the location the indirect return value pointer is returned in, or None if it is not returned

Return type:

Optional[CoreVariable]

get_stack_adjustment_for_locations(view: BinaryView | None, return_value: ValueLocation | None, params: List[Tuple[ValueLocation, Type]])[source]

get_stack_adjustment_for_locations computes the stack adjustment applied on return for a call with the given return value and parameter locations.

The default implementation calls get_default_stack_adjustment_for_locations.

Parameters:
Returns:

the stack adjustment in bytes

Return type:

int

is_arg_type_reg_compatible(view: BinaryView | None, type: Type) → bool[source]

is_arg_type_reg_compatible determines whether a value of the given type can be passed as an argument in registers.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – argument type to check

Returns:

whether the argument type is register compatible

Return type:

bool

is_non_reg_arg_indirect(view: BinaryView | None, type: Type | None) → bool[source]

is_non_reg_arg_indirect determines whether an argument that cannot be passed in registers is passed indirectly by pointer as opposed to being passed directly on the stack.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – argument type to check

Returns:

whether the non-register argument is passed indirectly by pointer

Return type:

bool

is_return_type_reg_compatible(view: BinaryView | None, type: Type) → bool[source]

is_return_type_reg_compatible determines whether a value of the given type can be returned in registers, as opposed to being returned indirectly through memory.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – return type to check

Returns:

whether the return type is register compatible

Return type:

bool

perform_get_incoming_flag_value(flag: FlagName, func: Function) → RegisterValue[source]

Deprecated, override get_incoming_flag_value instead.

Parameters:
Return type:

RegisterValue

perform_get_incoming_reg_value(reg: RegisterName, func: Function) → RegisterValue[source]

Deprecated, override get_incoming_reg_value instead.

Parameters:
Return type:

RegisterValue

perform_get_incoming_var_for_parameter_var(in_var: CoreVariable, func: Function | None = None) → CoreVariable[source]

Deprecated, override get_incoming_var_for_parameter_var instead.

Parameters:
Return type:

CoreVariable

perform_get_parameter_var_for_incoming_var(in_var: CoreVariable, func: Function | None = None) → CoreVariable[source]

Deprecated, override get_parameter_var_for_incoming_var instead.

Parameters:
Return type:

CoreVariable

with_confidence(confidence: int) → CallingConvention[source]
Parameters:

confidence (int)

Return type:

CallingConvention

property arch: Architecture

The architecture this calling convention applies to.

Getter:

returns the architecture this calling convention applies to

Setter:

sets the architecture this calling convention applies to

Type:

Architecture

arg_regs_for_varargs = True
arg_regs_share_index = False
callee_saved_regs = []
caller_saved_regs = []
eligible_for_heuristics = True
float_arg_regs = []
float_return_reg = None
global_pointer_reg = None
global_pointer_regs = []
high_int_return_reg = None
implicitly_defined_regs = []
int_arg_regs = []
int_return_reg = None
name = None
required_arg_regs = []
required_clobbered_regs = []
stack_adjusted_on_return = False
stack_args_naturally_aligned = False
stack_args_pushed_left_to_right = False
stack_reserved_for_arg_regs = False

CoreCallingConvention

class CoreCallingConvention[source]

Bases: CallingConvention

__init__(handle, confidence: int = 255)[source]
Parameters:

confidence (int)

get_call_layout(view: BinaryView | None, return_value: types.ReturnValueOrType | None, params: types.ParamsType, func: Function | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → CallLayout[source]

get_call_layout computes the complete call layout (parameter locations, return value location, and stack adjustments) for a call with the given return value and parameters. It is recommended to only override this method if the calling convention behavior cannot be modeled with get_return_value_location and/or get_parameter_locations.

The default implementation calls get_default_call_layout.

When calling this method to query the layout of a function, the return value and parameters should have their named type references dereferenced before passing them to this method. Calling the methods BinaryView.deref_return_value_named_type_references and BinaryView.deref_parameter_named_type_references will perform this dereferencing.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType | None) – return value of the call

  • params (types.ParamsType) – parameters of the call

  • func (Function) – function used to resolve the architecture of the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the computed call layout

Return type:

CallLayout

get_incoming_flag_value(flag: architecture.FlagType, func: Function) → RegisterValue[source]

get_incoming_flag_value gets the known value of a flag on entry to a function.

Parameters:

  • reg – flag to query

  • func (Function) – function being analyzed

  • flag (architecture.FlagType)

Returns:

the incoming value of the flag

Return type:

RegisterValue

get_incoming_reg_value(reg: architecture.RegisterType, func: Function) → RegisterValue[source]

get_incoming_reg_value gets the known value of a register on entry to a function.

Parameters:

  • reg (RegisterName) – register to query

  • func (Function) – function being analyzed

Returns:

the incoming value of the register

Return type:

RegisterValue

get_incoming_var_for_parameter_var(in_var: CoreVariable, func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction = None) → Variable[source]

get_incoming_var_for_parameter_var gets the incoming variable that corresponds to the given parameter variable. This is the inverse of get_parameter_var_for_incoming_var.

Parameters:
Returns:

the incoming variable corresponding to the parameter variable

Return type:

CoreVariable

get_indirect_return_value_location() → CoreVariable[source]

get_indirect_return_value_location gets the location used to pass the hidden pointer argument for return values that are returned indirectly through memory.

Returns:

the location of the indirect return value pointer

Return type:

CoreVariable

get_parameter_locations(view: BinaryView | None, return_value: ValueLocation | None, params: types.ParamsType, arch: Architecture | None = None, permitted_regs: List[architecture.RegisterIndex] | None = None) → List[ValueLocation][source]

get_parameter_locations computes the locations of the parameters for a call with the given return value and parameters.

The default implementation calls get_default_parameter_locations.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (ValueLocation | None) – optional location of the return value, which may affect parameter placement (for example, when an indirect return pointer consumes an argument register)

  • params (types.ParamsType) – parameters of the call

  • arch (Architecture) – architecture used to resolve the resulting locations

  • permitted_regs (List[architecture.RegisterIndex] | None) – optional set of register indices that argument passing is restricted to; if not provided, the calling convention’s default registers are used

Returns:

the locations of the parameters, in order

Return type:

List[ValueLocation]

get_parameter_ordering_for_variables(view: BinaryView | None, params: Dict[CoreVariable, Type]) → List[CoreVariable][source]

get_parameter_ordering_for_variables computes the order in which the given parameter variables are passed. Used by the heuristic calling convention detection to create a function type from a list of parameter variables.

The default implementation calls get_default_parameter_ordering_for_variables.

Parameters:
Returns:

the parameter variables in the order they are passed

Return type:

List[CoreVariable]

get_parameter_var_for_incoming_var(in_var: CoreVariable, func: Function | LowLevelILFunction | MediumLevelILFunction | HighLevelILFunction = None) → Variable[source]

get_parameter_var_for_incoming_var gets the parameter variable that corresponds to the given incoming variable. This is the inverse of get_incoming_var_for_parameter_var.

Parameters:
Returns:

the parameter variable corresponding to the incoming variable

Return type:

CoreVariable

get_register_stack_adjustments(view: BinaryView | None, return_value: ValueLocation | None, params: List[ValueLocation]) → Dict[RegisterIndex, int][source]

get_register_stack_adjustments computes the per-register-stack adjustments (for architectures with register stacks, such as the x87 floating point stack) for a call with the given return value and parameter locations.

The default implementation calls get_default_register_stack_adjustments.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (ValueLocation | None) – optional location of the return value

  • params (List[ValueLocation]) – locations of the parameters

Returns:

a map from register stack index to its adjustment

Return type:

Dict[RegisterIndex, int]

get_return_value_location(view: BinaryView | None, return_value: types.ReturnValueOrType) → ValueLocation | None[source]

get_return_value_location computes the location of the return value for the given return value type and location structure.

The default implementation calls get_default_return_value_location.

Parameters:

  • view (BinaryView) – binary view providing type information

  • return_value (types.ReturnValueOrType) – return value to compute the location for

Returns:

the location of the return value

Return type:

Optional[ValueLocation]

get_returned_indirect_return_value_pointer() → CoreVariable | None[source]

get_returned_indirect_return_value_pointer gets the location in which the hidden indirect return value pointer is returned to the caller, for calling conventions that return it.

Returns:

the location the indirect return value pointer is returned in, or None if it is not returned

Return type:

Optional[CoreVariable]

get_stack_adjustment_for_locations(view: BinaryView | None, return_value: ValueLocation | None, params: List[Tuple[ValueLocation, Type]])[source]

get_stack_adjustment_for_locations computes the stack adjustment applied on return for a call with the given return value and parameter locations.

The default implementation calls get_default_stack_adjustment_for_locations.

Parameters:
Returns:

the stack adjustment in bytes

Return type:

int

is_arg_type_reg_compatible(view: BinaryView | None, type: Type) → bool[source]

is_arg_type_reg_compatible determines whether a value of the given type can be passed as an argument in registers.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – argument type to check

Returns:

whether the argument type is register compatible

Return type:

bool

is_non_reg_arg_indirect(view: BinaryView | None, type: Type | None) → bool[source]

is_non_reg_arg_indirect determines whether an argument that cannot be passed in registers is passed indirectly by pointer as opposed to being passed directly on the stack.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – argument type to check

Returns:

whether the non-register argument is passed indirectly by pointer

Return type:

bool

is_return_type_reg_compatible(view: BinaryView | None, type: Type) → bool[source]

is_return_type_reg_compatible determines whether a value of the given type can be returned in registers, as opposed to being returned indirectly through memory.

Parameters:

  • view (BinaryView) – binary view providing type information

  • type (Type) – return type to check

Returns:

whether the return type is register compatible

Return type:

bool