Trait CallingConvention 

pub trait CallingConvention:
    'static
    + Sync
    + Sized
    + AsRef<CoreCallingConvention> {
    // Required methods
    fn caller_saved_registers(&self) -> Vec<RegisterId>;
    fn callee_saved_registers(&self) -> Vec<RegisterId>;
    fn int_arg_registers(&self) -> Vec<RegisterId>;
    fn float_arg_registers(&self) -> Vec<RegisterId>;
    fn arg_registers_shared_index(&self) -> bool;
    fn reserved_stack_space_for_arg_registers(&self) -> bool;
    fn stack_adjusted_on_return(&self) -> bool;
    fn is_eligible_for_heuristics(&self) -> bool;
    fn return_int_reg(&self) -> Option<RegisterId>;
    fn return_hi_int_reg(&self) -> Option<RegisterId>;
    fn return_float_reg(&self) -> Option<RegisterId>;
    fn global_pointer_reg(&self) -> Option<RegisterId>;
    fn implicitly_defined_registers(&self) -> Vec<RegisterId>;
    fn are_argument_registers_used_for_var_args(&self) -> bool;

    // Provided methods
    fn required_argument_registers(&self) -> Vec<RegisterId> { ... }
    fn required_clobbered_registers(&self) -> Vec<RegisterId> { ... }
    fn global_pointer_regs(&self) -> Vec<RegisterId> { ... }
    fn incoming_register_value(
        &self,
        reg: RegisterId,
        _func: Option<&Function>,
    ) -> RegisterValue { ... }
    fn incoming_flag_value(
        &self,
        _flag: FlagId,
        _func: Option<&Function>,
    ) -> RegisterValue { ... }
    fn incoming_variable_for_parameter_variable(
        &self,
        var: &Variable,
        _func: Option<&Function>,
    ) -> Variable { ... }
    fn parameter_variable_for_incoming_variable(
        &self,
        var: &Variable,
        _func: Option<&Function>,
    ) -> Variable { ... }
    fn is_return_type_register_compatible(
        &self,
        _view: Option<&BinaryView>,
        ty: &Type,
    ) -> bool { ... }
    fn indirect_return_value_location(&self) -> Variable { ... }
    fn returned_indirect_return_value_pointer(&self) -> Option<Variable> { ... }
    fn is_argument_type_register_compatible(
        &self,
        _view: Option<&BinaryView>,
        ty: &Type,
    ) -> bool { ... }
    fn is_non_register_argument_indirect(
        &self,
        _view: Option<&BinaryView>,
        _ty: &Type,
    ) -> bool { ... }
    fn are_stack_arguments_naturally_aligned(&self) -> bool { ... }
    fn are_stack_arguments_pushed_left_to_right(&self) -> bool { ... }
    fn call_layout(
        &self,
        view: Option<&BinaryView>,
        return_value: &ReturnValue,
        params: &[FunctionParameter],
        permitted_registers: Option<&[RegisterId]>,
    ) -> CallLayout { ... }
    fn return_value_location(
        &self,
        view: Option<&BinaryView>,
        return_value: &ReturnValue,
    ) -> ValueLocation { ... }
    fn parameter_locations(
        &self,
        view: Option<&BinaryView>,
        return_value: Option<&ValueLocation>,
        params: &[FunctionParameter],
        permitted_registers: Option<&[RegisterId]>,
    ) -> Vec<ValueLocation> { ... }
    fn parameter_ordering_for_variables(
        &self,
        _view: Option<&BinaryView>,
        params: &[(Variable, Ref<Type>)],
    ) -> Vec<Variable> { ... }
    fn stack_adjustment_for_locations(
        &self,
        _view: Option<&BinaryView>,
        return_value: Option<&ValueLocation>,
        params: &[(ValueLocation, Ref<Type>)],
    ) -> i64 { ... }
    fn register_stack_adjustments(
        &self,
        _view: Option<&BinaryView>,
        return_value: Option<&ValueLocation>,
        params: &[ValueLocation],
    ) -> BTreeMap<RegisterId, i32> { ... }
}

Describes how parameters, return values, and the stack are handled when a function is called.

Implementors only need to provide the methods that describe their convention; every method that computes a layout (parameter locations, return value location, and stack adjustments) has a default implementation that delegates to the core’s default behavior via the implementor’s associated CoreCallingConvention. A CallingConvention implementation must expose its core handle through AsRef<CoreCallingConvention>; see register_calling_convention for how the handle is provided to implementors.

Required Methods

fn caller_saved_registers(&self) -> Vec<RegisterId>

Gets the list of registers that are not preserved across a call (caller-saved / volatile registers).

fn callee_saved_registers(&self) -> Vec<RegisterId>

Gets the list of registers that a callee must preserve across a call (callee-saved / non-volatile registers).

fn int_arg_registers(&self) -> Vec<RegisterId>

Gets the registers used to pass integer and pointer arguments, in the order they are used.

fn float_arg_registers(&self) -> Vec<RegisterId>

Gets the registers used to pass floating point arguments, in the order they are used.

fn arg_registers_shared_index(&self) -> bool

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.

fn reserved_stack_space_for_arg_registers(&self) -> bool

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).

fn stack_adjusted_on_return(&self) -> bool

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).

fn is_eligible_for_heuristics(&self) -> bool

Whether this calling convention may be selected by heuristic calling convention detection.

fn return_int_reg(&self) -> Option<RegisterId>

Gets the register that holds the integer return value.

fn return_hi_int_reg(&self) -> Option<RegisterId>

Gets the register that holds the high part of an integer return value that is too large to fit in a single register.

fn return_float_reg(&self) -> Option<RegisterId>

Gets the register that holds the floating point return value.

fn global_pointer_reg(&self) -> Option<RegisterId>

Deprecated. Use CallingConvention::global_pointer_regs instead.

Gets the register that holds the global pointer, if the calling convention defines one.

fn implicitly_defined_registers(&self) -> Vec<RegisterId>

Gets the registers that are implicitly given a known value on function entry by this calling convention.

fn are_argument_registers_used_for_var_args(&self) -> bool

Whether argument registers are used to pass variadic arguments.

Provided Methods

fn required_argument_registers(&self) -> Vec<RegisterId>

Gets the set of registers that must be arguments for heuristic calling convention detection to consider this calling convention as a valid option.

fn required_clobbered_registers(&self) -> Vec<RegisterId>

Gets the set of registers that must be clobbered for heuristic calling convention detection to consider this calling convention as a valid option.

fn global_pointer_regs(&self) -> Vec<RegisterId>

fn incoming_register_value( &self, reg: RegisterId, _func: Option<&Function>, ) -> RegisterValue

The known value of a register on entry to a function. The default implementation models the top of a register stack (such as the x87 floating point stack) as the constant zero and leaves all other registers undetermined.

fn incoming_flag_value( &self, _flag: FlagId, _func: Option<&Function>, ) -> RegisterValue

The known value of a flag on entry to a function. The default implementation leaves all flags undetermined.

fn incoming_variable_for_parameter_variable( &self, var: &Variable, _func: Option<&Function>, ) -> Variable

The incoming variable used to pass the given parameter variable.

fn parameter_variable_for_incoming_variable( &self, var: &Variable, _func: Option<&Function>, ) -> Variable

The parameter variable corresponding to the given incoming variable.

fn is_return_type_register_compatible( &self, _view: Option<&BinaryView>, ty: &Type, ) -> bool

Whether a value of the given type can be returned in registers, as opposed to being returned indirectly through memory. The default implementation allows register returns for types that fit in a single register, have a size equal to two registers when CallingConvention::return_hi_int_reg is a valid register, or are a floating point type when CallingConvention::return_float_reg is a valid register.

fn indirect_return_value_location(&self) -> Variable

The location used to pass the hidden pointer argument for return values that are returned indirectly through memory. The default location is the first integer argument register, or the first stack slot if there are no integer argument registers.

fn returned_indirect_return_value_pointer(&self) -> Option<Variable>

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

fn is_argument_type_register_compatible( &self, _view: Option<&BinaryView>, ty: &Type, ) -> bool

Whether a value of the given type can be passed as an argument in registers. The default implementation allows register arguments for types that fit in a single register, or are a floating point type when CallingConvention::float_arg_registers has valid registers.

fn is_non_register_argument_indirect( &self, _view: Option<&BinaryView>, _ty: &Type, ) -> bool

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

fn are_stack_arguments_naturally_aligned(&self) -> bool

Whether arguments passed on the stack are aligned to their natural alignment. If false, arguments are aligned to the address size.

fn are_stack_arguments_pushed_left_to_right(&self) -> bool

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

fn call_layout( &self, view: Option<&BinaryView>, return_value: &ReturnValue, params: &[FunctionParameter], permitted_registers: Option<&[RegisterId]>, ) -> CallLayout

Computes the complete call layout (parameter locations, return value location, and stack adjustments) for a call with the given return value and parameters. The default implementation uses CallingConvention::return_value_location, CallingConvention::parameter_locations, CallingConvention::stack_adjustment_for_locations, and CallingConvention::stack_adjustment_for_locations to compute the layout.

It is recommended to only override this method if the calling convention behavior cannot be modeled with CallingConvention::return_value_location and/or CallingConvention::parameter_locations.

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

fn return_value_location( &self, view: Option<&BinaryView>, return_value: &ReturnValue, ) -> ValueLocation

Computes the location of the return value for the given return value type. The default implementation checks CallingConvention::is_return_type_register_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 CallingConvention::indirect_return_value_location and CallingConvention::returned_indirect_return_value_pointer are used to provide the location of the indirect return value.

fn parameter_locations( &self, view: Option<&BinaryView>, return_value: Option<&ValueLocation>, params: &[FunctionParameter], permitted_registers: Option<&[RegisterId]>, ) -> Vec<ValueLocation>

Computes the locations of the parameters for a call with the given return value and parameters. The default implementation uses CallingConvention::int_arg_registers, CallingConvention::float_arg_registers, CallingConvention::arg_registers_shared_index, CallingConvention::reserved_stack_space_for_arg_registers, CallingConvention::is_argument_type_register_compatible, CallingConvention::is_non_register_argument_indirect, CallingConvention::are_stack_arguments_naturally_aligned, and CallingConvention::are_stack_arguments_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 methods listed above.

fn parameter_ordering_for_variables( &self, _view: Option<&BinaryView>, params: &[(Variable, Ref<Type>)], ) -> Vec<Variable>

Computes the order in which the given parameter variables are passed. The default implementation first checks CallingConvention::arg_registers_shared_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.

fn stack_adjustment_for_locations( &self, _view: Option<&BinaryView>, return_value: Option<&ValueLocation>, params: &[(ValueLocation, Ref<Type>)], ) -> i64

Computes the stack adjustment applied on return for a call with the given return value and parameter locations. The default implementation first checks CallingConvention::stack_adjusted_on_return, and returns zero if that returns false. Otherwise, it checks the stack parameter locations and CallingConvention::are_stack_arguments_naturally_aligned to compute the stack adjustment necessary to cover all parameters.

fn register_stack_adjustments( &self, _view: Option<&BinaryView>, return_value: Option<&ValueLocation>, params: &[ValueLocation], ) -> BTreeMap<RegisterId, i32>

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 compares the register stack slots used by the parameters and the return value to compute the adjustments.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl CallingConvention for CoreCallingConvention