Module Bap_c_abi

C language ABI.

This module provides a common interface for building ABI support modules for C language.

type param = Bap_c_data.t * Bap.Std.exp

Function formal parameter is represented as a pair of an abstraction of data, that is passed via the parameter, and a BIL expression, that denotes the parameter.

type args = {
  1. return : param option;
  2. hidden : (Bap_c_type.t * param) list;
  3. params : param list;
}

subroutine argument list is split into three parts: return is the return arguments, that is optional; params are regular positional parameters, the length of the params list must equal to the amount of the formals in the function prototype; hidden are hidden parameters, that are inserted by abi to pass special arguments, like this pointer or a pointer to a structural value, for example.

The api processor, created by this module, will insert arg terms into sub in the following way:

  • nth positional argument corresponds to nth arg term (counting from 0).
  • the last arg term corresponds to the return argument, if any;
  • all hidden arguments are put between the last positional and the return argument.
type t = {
  1. insert_args : Bap.Std.sub Bap.Std.term -> Bap_c_type.attr list -> Bap_c_type.proto -> args option;
  2. apply_attrs : Bap_c_type.attr list -> Bap.Std.sub Bap.Std.term -> Bap.Std.sub Bap.Std.term;
}

an abi processor. Each architecture registers its own abi processor, that is responsible for dispatching the processed subroutine between architecture specific abi processors.

val create_api_processor : Bap_c_size.base -> t -> Bap_api.t

create_api_processor size t packs an api processor. The processor will insert arg terms into each recognized subroutine, propagate some known C attributes into corresponding BIR attributes, annotate each inserted arg term with its corresponding C type and datum model, and annotate each regognized subroutine with its C prototype.

The api processor relies on an availability of a front end parser for C language.

data size t creates an abstraction of data that is represented by type t. The size parameter defines a data model, e.g., sizes of primitive types, padding and alignment restrictions, etc.

The abstraction includes inner and trailing paddings, when necessary.

layout size t computes the c data type layout.

  • since 2.5.0

model target returns the data model for the given target.

  • since 2.5.0

apply processor attrs proto sub applies the abi processor to the subroutine sub.

The function inserts arguments and attaches appropriate arguments to the function and its subterms, such as strores the type of each argument, the provided C attributes, stores the prototype, computes and attaches data layouts, etc.

  • since 2.5.0
val arg_intent : Bap_c_type.t -> Bap.Std.intent

arg_intent t infers argument intention based on its C type. If an argument is passed by value, i.e., it is a c basic type, then it is an input argument. If an argument is a reference, but not a function, then it is input/output if any value, referenced by the argument is non-const. A reference to function always has the input intent. If an argyment is a structure or union, then it is input/output if any of its fields is input/output.

val register : string -> t -> unit

register name t registers an abi processor t named name that may be used by subroutines in this project.

@after 2.5.0 fails if there is already a processor for the given name. @after 2.5.0 the abi name should be a valid target name.

  • deprecated [since 2022-07] use the Arg module
val get_processor : string -> t option

get_processor name is used to access an abi processor with its name.

  • deprecated [since 2022-07] use [lookup]
val lookup : Bap_core_theory.Theory.Target.t -> t option

lookup t the abi processor associated with the target t.

  • since 2.5.0
module Stack : sig ... end

An abstraction of a stack, commonly used in C compilers.

module Arg : sig ... end

A monadic eDSL for argument passing semantics specification.

define target pass the high-level ABI specification function.

The function creates an abi processor and registers it using the name obtained from the target. The pass function is used to define the insert_args method (with the sub argument ignored).

The function also registers an ABI pass that checks the project target and if it matches with the passed target the function creates and registers the C API processor.