module Flx_cil_cil: sig
.. end
CIL API Documentation. An html version of this document can be found at
* http://manju.cs.berkeley.edu/cil.
val initCIL : unit -> unit
Call this function to perform some initialization. Call if after you have
* set
Flx_cil_cil.msvcMode
.
val cilVersion : string
This are the CIL version numbers. A CIL version is a number of the form
* M.m.r (major, minor and release)
val cilVersionMajor : int
val cilVersionMinor : int
val cilVersionRevision : int
This module defines the abstract syntax of CIL. It also provides utility
* functions for traversing the CIL data structures, and pretty-printing
* them. The parser for both the GCC and MSVC front-ends can be invoked as
* Flx_cil_frontc.parse: string -> unit ->
Flx_cil_cil.file
. This function must be given
* the name of a preprocessed C file and will return the top-level data
* structure that describes a whole source file. By default the parsing and
* elaboration into CIL is done as for GCC source. If you want to use MSVC
* source you must set the Flx_cil_cil.msvcMode
to true
and must also invoke the
* function Flx_cil_frontc.setMSVCMode: unit -> unit
.
The Abstract Syntax of CIL
The top-level representation of a CIL source file (and the result of the
* parsing and elaboration). Its main contents is the list of global
* declarations and definitions. You can iterate over the globals in a
* Flx_cil_cil.file
using the following iterators: Flx_cil_cil.mapGlobals
,
* Flx_cil_cil.iterGlobals
and Flx_cil_cil.foldGlobals
. You can also use the
* Flx_cil_cil.dummyFile
when you need a Flx_cil_cil.file
as a placeholder. For each
* global item CIL stores the source location where it appears (using the
* type Flx_cil_cil.location
)
type
file = {
|
mutable fileName : string ; |
|
mutable globals : global list ; |
|
mutable globinit : fundec option ; |
|
mutable globinitcalled : bool ; |
}
Top-level representation of a C source file
Globals. The main type for representing global declarations and
* definitions. A list of these form a CIL file. The order of globals in the
* file is generally important.
type
global =
A global declaration or definition
Types. A C type is represented in CIL using the type Flx_cil_cil.typ
.
* Among types we differentiate the integral types (with different kinds
* denoting the sign and precision), floating point types, enumeration types,
* array and pointer types, and function types. Every type is associated with
* a list of attributes, which are always kept in sorted order. Use
* Flx_cil_cil.addAttribute
and Flx_cil_cil.addAttributes
to construct list of
* attributes. If you want to inspect a type, you should use
* Flx_cil_cil.unrollType
or Flx_cil_cil.unrollTypeDeep
to see through the uses of
* named types.
CIL is configured at build-time with the sizes and alignments of the
* underlying compiler (GCC or MSVC). CIL contains functions that can compute
* the size of a type (in bits) Flx_cil_cil.bitsSizeOf
, the alignment of a type
* (in bytes) Flx_cil_cil.alignOf_int
, and can convert an offset into a start and
* width (both in bits) using the function Flx_cil_cil.bitsOffset
. At the moment
* these functions do not take into account the packed
attributes and
* pragmas.
type
typ =
There are a number of functions for querying the kind of a type. These are
Flx_cil_cil.isIntegralType
,
Flx_cil_cil.isArithmeticType
,
Flx_cil_cil.isPointerType
,
Flx_cil_cil.isFunctionType
,
Flx_cil_cil.isArrayType
.
There are two easy ways to scan a type. First, you can use the
Flx_cil_cil.existsType
to return a boolean answer about a type. This function
is controlled by a user-provided function that is queried for each type that is
used to construct the current type. The function can specify whether to
terminate the scan with a boolean result or to continue the scan for the
nested types.
The other method for scanning types is provided by the visitor interface (see
Flx_cil_cil.cilVisitor
).
If you want to compare types (or to use them as hash-values) then you should
use instead type signatures (represented as Flx_cil_cil.typsig
). These
contain the same information as types but canonicalized such that simple Ocaml
structural equality will tell whether two types are equal. Use
Flx_cil_cil.typeSig
to compute the signature of a type. If you want to ignore
certain type attributes then use Flx_cil_cil.typeSigWithAttrs
.
type
ikind =
| |
IBool |
| |
IChar |
| |
ISChar |
| |
IUChar |
| |
IInt |
| |
IUInt |
| |
IShort |
| |
IUShort |
| |
ILong |
| |
IULong |
| |
ILongLong |
| |
IULongLong |
Various kinds of integers
type
fkind =
| |
FFloat |
| |
FDouble |
| |
FLongDouble |
| |
CFloat |
| |
CDouble |
| |
CLongDouble |
| |
IFloat |
| |
IDouble |
| |
ILongDouble |
Various kinds of floating-point numbers
Attributes.
type
attribute =
type
attributes = attribute list
type
attrparam =
The type of parameters of attributes
Structures. The Flx_cil_cil.compinfo
describes the definition of a
* structure or union type. Each such Flx_cil_cil.compinfo
must be defined at the
* top-level using the GCompTag
constructor and must be shared by all
* references to this type (using either the TComp
type constructor or from
* the definition of the fields.
If all you need is to scan the definition of each
* composite type once, you can do that by scanning all top-level GCompTag
.
* Constructing a Flx_cil_cil.compinfo
can be tricky since it must contain fields
* that might refer to the host Flx_cil_cil.compinfo
and furthermore the type of
* the field might need to refer to the Flx_cil_cil.compinfo
for recursive types.
* Use the Flx_cil_cil.mkCompInfo
function to create a Flx_cil_cil.compinfo
. You can
* easily fetch the Flx_cil_cil.fieldinfo
for a given field in a structure with
* Flx_cil_cil.getCompField
.
type
compinfo = {
|
mutable cstruct : bool ; |
|
mutable cname : string ; |
|
mutable ckey : int ; |
|
mutable cfields : fieldinfo list ; |
|
mutable cattr : attributes ; |
|
mutable cdefined : bool ; |
|
mutable creferenced : bool ; |
}
The definition of a structure or union type. Use
Flx_cil_cil.mkCompInfo
to
* make one and use
Flx_cil_cil.copyCompInfo
to copy one (this ensures that a new
* key is assigned and that the fields have the right pointers to parents.).
Structure fields. The Flx_cil_cil.fieldinfo
structure is used to describe
* a structure or union field. Fields, just like variables, can have
* attributes associated with the field itself or associated with the type of
* the field (stored along with the type of the field).
type
fieldinfo = {
|
mutable fcomp : compinfo ; |
|
mutable fname : string ; |
|
mutable ftype : typ ; |
|
mutable fbitfield : int option ; |
|
mutable fattr : attributes ; |
|
mutable floc : location ; |
|
mutable fstorage : storage ; |
}
Information about a struct/union field
Enumerations. Information about an enumeration. This is shared by all
* references to an enumeration. Make sure you have a GEnumTag
for each of
* of these.
type
enuminfo = {
|
mutable ename : string ; |
|
mutable eitems : (string * exp * location) list ; |
|
mutable eattr : attributes ; |
|
mutable ereferenced : bool ; |
}
Information about an enumeration
Enumerations. Information about an enumeration. This is shared by all
* references to an enumeration. Make sure you have a GEnumTag
for each of
* of these.
type
typeinfo = {
|
mutable tname : string ; |
|
mutable ttype : typ ; |
|
mutable treferenced : bool ; |
}
Information about a defined type
Variables.
Each local or global variable is represented by a unique Flx_cil_cil.varinfo
structure. A global Flx_cil_cil.varinfo
can be introduced with the GVarDecl
or
GVar
or GFun
globals. A local varinfo can be introduced as part of a
function definition Flx_cil_cil.fundec
.
All references to a given global or local variable must refer to the same
copy of the varinfo
. Each varinfo
has a globally unique identifier that
can be used to index maps and hashtables (the name can also be used for this
purpose, except for locals from different functions). This identifier is
constructor using a global counter.
It is very important that you construct varinfo
structures using only one
of the following functions:
A varinfo
is also used in a function type to denote the list of formals.
type
varinfo = {
|
mutable vname : string ; |
|
mutable vtype : typ ; |
|
mutable vattr : attributes ; |
|
mutable vstorage : storage ; |
|
mutable vglob : bool ; |
|
mutable vinline : bool ; |
|
mutable vdecl : location ; |
|
mutable vid : int ; |
|
mutable vaddrof : bool ; |
|
mutable vreferenced : bool ; |
}
Information about a variable.
type
storage =
| |
NoStorage |
| |
Static |
| |
Register |
| |
Extern |
Storage-class information
Expressions. The CIL expression language contains only the side-effect free expressions of
C. They are represented as the type Flx_cil_cil.exp
. There are several
interesting aspects of CIL expressions:
Integer and floating point constants can carry their textual representation.
This way the integer 15 can be printed as 0xF if that is how it occurred in the
source.
CIL uses 64 bits to represent the integer constants and also stores the width
of the integer type. Care must be taken to ensure that the constant is
representable with the given width. Use the functions Flx_cil_cil.kinteger
,
Flx_cil_cil.kinteger64
and Flx_cil_cil.integer
to construct constant
expressions. CIL predefines the constants Flx_cil_cil.zero
,
Flx_cil_cil.one
and Flx_cil_cil.mone
(for -1).
Use the functions Flx_cil_cil.isConstant
and Flx_cil_cil.isInteger
to test if
an expression is a constant and a constant integer respectively.
CIL keeps the type of all unary and binary expressions. You can think of that
type qualifying the operator. Furthermore there are different operators for
arithmetic and comparisons on arithmetic types and on pointers.
Another unusual aspect of CIL is that the implicit conversion between an
expression of array type and one of pointer type is made explicit, using the
StartOf
expression constructor (which is not printed). If you apply the
AddrOf}
constructor to an lvalue of type T
then you will be getting an
expression of type TPtr(T)
.
You can find the type of an expression with Flx_cil_cil.typeOf
.
You can perform constant folding on expressions using the function
Flx_cil_cil.constFold
.
type
exp =
Expressions (Side-effect free)
Constants.
type
constant =
| |
CInt64 of int64 * ikind * string option |
| |
CStr of string |
| |
CWStr of int64 list |
| |
CChr of char |
| |
CReal of float * fkind * string option |
Literal constants
type
unop =
Unary operators
type
binop =
| |
PlusA |
| |
PlusPI |
| |
IndexPI |
| |
MinusA |
| |
MinusPI |
| |
MinusPP |
| |
Mult |
| |
Div |
| |
Mod |
| |
Shiftlt |
| |
Shiftrt |
| |
Lt |
| |
Gt |
| |
Le |
| |
Ge |
| |
Eq |
| |
Ne |
| |
BAnd |
| |
BXor |
| |
BOr |
| |
LAnd |
| |
LOr |
Binary operations
Lvalues. Lvalues are the sublanguage of expressions that can appear at the left of an assignment or as operand to the address-of operator.
In C the syntax for lvalues is not always a good indication of the meaning
of the lvalue. For example the C value
a[0][1][2]
might involve 1, 2 or 3 memory reads when used in an expression context,
depending on the declared type of the variable a
. If a
has type int
[4][4][4]
then we have one memory read from somewhere inside the area
that stores the array a
. On the other hand if a
has type int ***
then
the expression really means * ( * ( * (a + 0) + 1) + 2)
, in which case it is
clear that it involves three separate memory operations.
An lvalue denotes the contents of a range of memory addresses. This range
is denoted as a host object along with an offset within the object. The
host object can be of two kinds: a local or global variable, or an object
whose address is in a pointer expression. We distinguish the two cases so
that we can tell quickly whether we are accessing some component of a
variable directly or we are accessing a memory location through a pointer.
To make it easy to
tell what an lvalue means CIL represents lvalues as a host object and an
offset (see Flx_cil_cil.lval
). The host object (represented as
Flx_cil_cil.lhost
) can be a local or global variable or can be the object
pointed-to by a pointer expression. The offset (represented as
Flx_cil_cil.offset
) is a sequence of field or array index designators.
Both the typing rules and the meaning of an lvalue is very precisely
specified in CIL.
The following are a few useful function for operating on lvalues:
The following equivalences hold Mem(AddrOf(Mem a, aoff)), off = Mem a, aoff + off
Mem(AddrOf(Var v, aoff)), off = Var v, aoff + off
AddrOf (Mem a, NoOffset) = a
type
lval = lhost * offset
An lvalue
type
lhost =
type
offset =
The offset part of an
Flx_cil_cil.lval
. Each offset can be applied to certain
* kinds of lvalues and its effect is that it advances the starting address
* of the lvalue and changes the denoted type, essentially focusing to some
* smaller lvalue that is contained in the original one.
Initializers.
A special kind of expressions are those that can appear as initializers for
global variables (initialization of local variables is turned into
assignments). The initializers are represented as type Flx_cil_cil.init
. You
can create initializers with Flx_cil_cil.makeZeroInit
and you can conveniently
scan compound initializers them with Flx_cil_cil.foldLeftCompound
or with Flx_cil_cil.foldLeftCompoundAll
.
type
init =
Initializers for global variables.
type
initinfo = {
|
mutable init : init option ; |
}
We want to be able to update an initializer in a global variable, so we
* define it as a mutable field
Function definitions.
A function definition is always introduced with a GFun
constructor at the
top level. All the information about the function is stored into a
Flx_cil_cil.fundec
. Some of the information (e.g. its name, type,
storage, attributes) is stored as a Flx_cil_cil.varinfo
that is a field of the
fundec
. To refer to the function from the expression language you must use
the varinfo
.
The function definition contains, in addition to the body, a list of all the
local variables and separately a list of the formals. Both kind of variables
can be referred to in the body of the function. The formals must also be shared
with the formals that appear in the function type. For that reason, to
manipulate formals you should use the provided functions
Flx_cil_cil.makeFormalVar
and Flx_cil_cil.setFormals
.
type
fundec = {
|
mutable svar : varinfo ; |
|
mutable sformals : varinfo list ; |
|
mutable slocals : varinfo list ; |
|
mutable smaxid : int ; |
|
mutable sbody : block ; |
|
mutable smaxstmtid : int option ; |
}
Function definitions.
type
block = {
}
A block is a sequence of statements with the control falling through from
one element to the next
Statements.
CIL statements are the structural elements that make the CFG. They are
represented using the type Flx_cil_cil.stmt
. Every
statement has a (possibly empty) list of labels. The
Flx_cil_cil.stmtkind
field of a statement indicates what kind of statement it
is.
Use Flx_cil_cil.mkStmt
to make a statement and the fill-in the fields.
CIL also comes with support for control-flow graphs. The sid
field in
stmt
can be used to give unique numbers to statements, and the succs
and preds
fields can be used to maintain a list of successors and
predecessors for every statement. The CFG information is not computed by
default. Instead you must explicitly use the functions
Flx_cil_cil.prepareCFG
and Flx_cil_cil.computeCFGInfo
to do it.
type
stmt = {
|
mutable labels : label list ; |
|
mutable skind : stmtkind ; |
|
mutable sid : int ; |
|
mutable succs : stmt list ; |
|
mutable preds : stmt list ; |
}
Statements.
type
label =
Labels
type
stmtkind =
The various kinds of control-flow statements statements
Instructions.
An instruction Flx_cil_cil.instr
is a statement that has no local
(intraprocedural) control flow. It can be either an assignment,
function call, or an inline assembly instruction.
type
instr =
Instructions.
type
location = {
|
line : int ; |
|
file : string ; |
|
byte : int ; |
}
Describes a location in a source file
type
featureDescr = {
|
fd_enabled : bool Pervasives.ref ; |
|
fd_name : string ; |
|
fd_description : string ; |
|
fd_extraopt : (string * Arg.spec * string) list ; |
|
fd_doit : file -> unit ; |
|
fd_post_check : bool ; |
}
To be able to add/remove features easily, each feature should be package
* as an interface with the following interface. These features should be
val compareLoc : location -> location -> int
Comparison function for locations.
** Compares first by filename, then line, then byte
Values for manipulating globals
val emptyFunction : string -> fundec
Make an empty function
val setFormals : fundec -> varinfo list -> unit
Update the formals of a fundec
and make sure that the function type
has the same information. Will copy the name as well into the type.
val setFunctionType : fundec -> typ -> unit
Set the types of arguments and results as given by the function type
* passed as the second argument. Will not copy the names from the function
* type to the formals
val setMaxId : fundec -> unit
val dummyFunDec : fundec
A dummy function declaration handy when you need one as a placeholder. It
* contains inside a dummy varinfo.
val dummyFile : file
A dummy file
val saveBinaryFile : file -> string -> unit
Write a
Flx_cil_cil.file
in binary form to the filesystem. The file can be
* read back in later using
Flx_cil_cil.loadBinaryFile
, possibly saving parsing
* time. The second argument is the name of the file that should be
* created.
val saveBinaryFileChannel : file -> Pervasives.out_channel -> unit
val loadBinaryFile : string -> file
val getGlobInit : ?main_name:string -> file -> fundec
Get the global initializer and create one if it does not already exist.
* When it creates a global initializer it attempts to place a call to it in
* the main function named by the optional argument (default "main")
val iterGlobals : file -> (global -> unit) -> unit
Iterate over all globals, including the global initializer
val foldGlobals : file -> ('a -> global -> 'a) -> 'a -> 'a
Fold over all globals, including the global initializer
val mapGlobals : file -> (global -> global) -> unit
Map over all globals, including the global initializer and change things
in place
val prepareCFG : fundec -> unit
Prepare a function for CFG information computation by
*
Flx_cil_cil.computeCFGInfo
. This function converts all
Break
,
Switch
,
*
Default
and
Continue
Flx_cil_cil.stmtkind
s and
Flx_cil_cil.label
s into
If
s
* and
Goto
s, giving the function body a very CFG-like character. This
* function modifies its argument in place.
val computeCFGInfo : fundec -> bool -> stmt list
Compute the CFG information for all statements in a fundec and return a
* list of the statements. The input fundec cannot have
Break
,
Switch
,
*
Default
, or
Continue
Flx_cil_cil.stmtkind
s or
Flx_cil_cil.label
s. Use
*
Flx_cil_cil.prepareCFG
to transform them away. The second argument should
* be
true
if you wish a global statement number,
false
if you wish a
* local (per-function) statement numbering.
val copyFunction : fundec -> string -> fundec
Create a deep copy of a function. There should be no sharing between the
* copy and the original function
val pushGlobal : global ->
types:global list Pervasives.ref ->
variables:global list Pervasives.ref -> unit
CIL keeps the types at the beginning of the file and the variables at the
* end of the file. This function will take a global and add it to the
* corresponding stack. Its operation is actually more complicated because if
* the global declares a type that contains references to variables (e.g. in
* sizeof in an array length) then it will also add declarations for the
* variables to the types stack
val gccBuiltins : (string, typ * typ list * bool) Hashtbl.t
A list of the GCC built-in functions. Maps the name to the result and
* argument types, and whether it is vararg
val msvcBuiltins : (string, typ * typ list * bool) Hashtbl.t
A list of the MSVC built-in functions. Maps the name to the result and
* argument types, and whether it is vararg
Values for manipulating initializers
val makeZeroInit : typ -> init
Make a initializer for zero-ing a data type
val foldLeftCompound : doinit:(offset -> init -> typ -> 'a -> 'a) ->
ct:typ ->
initl:(offset * init) list -> acc:'a -> 'a
Fold over the list of initializers in a Compound. doinit
is called on
* every present initializer, even if it is of compound type. In the case of
* arrays there might be missing zero-initializers at the end of the list.
* These are not scanned. This is much like List.fold_left
except we also
* pass the type of the initializer
val foldLeftCompoundAll : doinit:(offset -> init -> typ -> 'a -> 'a) ->
ct:typ ->
initl:(offset * init) list -> acc:'a -> 'a
Fold over the list of initializers in a Compound, like
*
Flx_cil_cil.foldLeftCompound
but in the case of an array it scans even missing
* zero initializers at the end of the array
Values for manipulating types
val voidType : typ
void
val isVoidType : typ -> bool
val isVoidPtrType : typ -> bool
val intType : typ
int
val uintType : typ
unsigned int
val longType : typ
long
val ulongType : typ
unsigned long
val charType : typ
char
val charPtrType : typ
char *
val wcharKind : ikind Pervasives.ref
val wcharType : typ Pervasives.ref
val charConstPtrType : typ
char const *
val voidPtrType : typ
void *
val intPtrType : typ
int *
val uintPtrType : typ
unsigned int *
val doubleType : typ
double
val upointType : typ Pervasives.ref
val typeOfSizeOf : typ Pervasives.ref
val isSigned : ikind -> bool
Returns true if and only if the given integer type is signed.
val mkCompInfo : bool ->
string ->
(compinfo ->
(string * typ * int option * attributes *
location * storage)
list) ->
attributes -> compinfo
Creates a a (potentially recursive) composite type. The arguments are:
* (1) a boolean indicating whether it is a struct or a union, (2) the name
* (always non-empty), (3) a function that when given a representation of the
* structure type constructs the type of the fields recursive type (the first
* argument is only useful when some fields need to refer to the type of the
* structure itself), and (4) a list of attributes to be associated with the
* composite type. The resulting compinfo has the field "cdefined" only if
* the list of fields is non-empty.
val copyCompInfo : compinfo -> string -> compinfo
val missingFieldName : string
This is a constant used as the name of an unnamed bitfield. These fields
do not participate in initialization and their name is not printed.
val compFullName : compinfo -> string
Get the full name of a comp
val isCompleteType : typ -> bool
Returns true if this is a complete type.
This means that sizeof(t) makes sense.
Incomplete types are not yet defined
structures and empty arrays.
val unrollType : typ -> typ
Unroll a type until it exposes a non
* TNamed
. Will drop the top-level attributes appearing in TNamed
!!!
val unrollTypeDeep : typ -> typ
Unroll all the TNamed in a type (even under type constructors such as
* TPtr
, TFun
or TArray
. Does not unroll the types of fields in TComp
* types.
val isIntegralType : typ -> bool
True if the argument is an integral type (i.e. integer or enum)
val isArithmeticType : typ -> bool
True if the argument is an arithmetic type (i.e. integer, enum or
floating point
val isPointerType : typ -> bool
True if the argument is a pointer type
val isFunctionType : typ -> bool
True if the argument is a function type
val argsToList : (string * typ * attributes) list option ->
(string * typ * attributes) list
Obtain the argument list ([] if None)
val isArrayType : typ -> bool
True if the argument is an array type
exception LenOfArray
Raised when
Flx_cil_cil.lenOfArray
fails either because the length is
None
* or because it is a non-constant expression
val lenOfArray : exp option -> int
Call to compute the array length as present in the array type, to an
* integer. Raises
Flx_cil_cil.LenOfArray
if not able to compute the length, such
* as when there is no length or the length is not a constant.
val getCompField : compinfo -> string -> fieldinfo
Return a named fieldinfo in compinfo, or raise Not_found
type
existsAction =
| |
ExistsTrue |
| |
ExistsFalse |
| |
ExistsMaybe |
A datatype to be used in conjunction with existsType
val existsType : (typ -> existsAction) -> typ -> bool
Scans a type by applying the function on all elements.
When the function returns ExistsTrue, the scan stops with
true. When the function returns ExistsFalse then the current branch is not
scanned anymore. Care is taken to
apply the function only once on each composite type, thus avoiding
circularity. When the function returns ExistsMaybe then the types that
construct the current type are scanned (e.g. the base type for TPtr and
TArray, the type of fields for a TComp, etc).
val splitFunctionType : typ ->
typ *
(string * typ * attributes) list option * bool *
attributes
Given a function type split it into return type,
* arguments, is_vararg and attributes. An error is raised if the type is not
* a function type
Same as Flx_cil_cil.splitFunctionType
but takes a varinfo. Prints a nicer
* error message if the varinfo is not for a function
val splitFunctionTypeVI : varinfo ->
typ *
(string * typ * attributes) list option * bool *
attributes
Type signatures
type
typsig =
Type signatures. Two types are identical iff they have identical
* signatures. These contain the same information as types but canonicalized.
* For example, two function types that are identical except for the name of
* the formal arguments are given the same signature. Also, TNamed
* constructors are unrolled.
val d_typsig : unit -> typsig -> Flx_cil_pretty.doc
Print a type signature
val typeSig : typ -> typsig
Compute a type signature
val typeSigWithAttrs : (attributes -> attributes) ->
typ -> typsig
val setTypeSigAttrs : attributes -> typsig -> typsig
Replace the attributes of a signature (only at top level)
val typeSigAttrs : typsig -> attributes
Get the top-level attributes of a signature
LVALUES
val makeVarinfo : bool -> string -> typ -> varinfo
val makeFormalVar : fundec ->
?where:string -> string -> typ -> varinfo
Make a formal variable for a function. Insert it in both the sformals
and the type of the function. You can optionally specify where to insert
this one. If where = "^" then it is inserted first. If where = "$" then
it is inserted last. Otherwise where must be the name of a formal after
which to insert this. By default it is inserted at the end.
val makeLocalVar : fundec ->
?insert:bool -> string -> typ -> varinfo
Make a local variable and add it to a function's slocals (only if insert =
true, which is the default). Make sure you know what you are doing if you
set insert=false.
val makeTempVar : fundec -> ?name:string -> typ -> varinfo
Make a temporary variable and add it to a function's slocals. The name of
the temporary variable will be generated based on the given name hint so
that to avoid conflicts with other locals.
val makeGlobalVar : string -> typ -> varinfo
Make a global variable. Your responsibility to make sure that the name
is unique
val copyVarinfo : varinfo -> string -> varinfo
Make a shallow copy of a varinfo
and assign a new identifier
val addOffsetLval : offset -> lval -> lval
Add an offset at the end of an lvalue. Make sure the type of the lvalue
* and the offset are compatible.
val addOffset : offset -> offset -> offset
addOffset o1 o2
adds o1
to the end of o2
.
val removeOffsetLval : lval -> lval * offset
Remove ONE offset from the end of an lvalue. Returns the lvalue with the
* trimmed offset and the final offset. If the final offset is NoOffset
* then the original lval
did not have an offset.
val removeOffset : offset -> offset * offset
Remove ONE offset from the end of an offset sequence. Returns the
* trimmed offset and the final offset. If the final offset is NoOffset
* then the original lval
did not have an offset.
val typeOfLval : lval -> typ
Compute the type of an lvalue
val typeOffset : typ -> offset -> typ
Compute the type of an offset from a base type
Values for manipulating expressions
val zero : exp
0
val one : exp
1
val mone : exp
-1
val kinteger64 : ikind -> int64 -> exp
Construct an integer of a given kind, using OCaml's int64 type. If needed
* it will truncate the integer to be within the representable range for the
* given kind.
val kinteger : ikind -> int -> exp
Construct an integer of a given kind. Converts the integer to int64 and
* then uses kinteger64. This might truncate the value if you use a kind
* that cannot represent the given integer. This can only happen for one of
* the Char or Short kinds
val integer : int -> exp
Construct an integer of kind IInt. You can use this always since the
OCaml integers are 31 bits and are guaranteed to fit in an IInt
val isInteger : exp -> int64 option
True if the given expression is a (possibly cast'ed)
character or an integer constant
val isConstant : exp -> bool
True if the expression is a compile-time constant
val isZero : exp -> bool
True if the given expression is a (possibly cast'ed) integer or character
constant with value zero
val constFold : bool -> exp -> exp
Do constant folding on an expression. If the first argument is true then
will also compute compiler-dependent expressions such as sizeof
val constFoldBinOp : bool ->
binop ->
exp -> exp -> typ -> exp
Do constant folding on a binary operation. The bulk of the work done by
constFold
is done here. If the first argument is true then
will also compute compiler-dependent expressions such as sizeof
val increm : exp -> int -> exp
Increment an expression. Can be arithmetic or pointer type
val var : varinfo -> lval
Makes an lvalue out of a given variable
val mkAddrOf : lval -> exp
Make an AddrOf. Given an lvalue of type T will give back an expression of
type ptr(T). It optimizes somewhat expressions like "& v" and "& v0
"
val mkAddrOrStartOf : lval -> exp
Like mkAddrOf except if the type of lval is an array then it uses
StartOf. This is the right operation for getting a pointer to the start
of the storage denoted by lval.
val mkMem : addr:exp -> off:offset -> lval
Make a Mem, while optimizing AddrOf. The type of the addr must be
TPtr(t) and the type of the resulting lval is t. Note that in CIL the
implicit conversion between an array and the pointer to the first
element does not apply. You must do the conversion yourself using
StartOf
val mkString : string -> exp
Make an expression that is a string constant (of pointer type)
val mkCastT : e:exp ->
oldt:typ -> newt:typ -> exp
Construct a cast when having the old type of the expression. If the new
* type is the same as the old type, then no cast is added.
val mkCast : e:exp -> newt:typ -> exp
val typeOf : exp -> typ
Compute the type of an expression
val parseInt : string -> exp
Convert a string representing a C integer literal to an expression.
* Handles the prefixes 0x and 0 and the suffixes L, U, UL, LL, ULL
Values for manipulating statements
val mkStmt : stmtkind -> stmt
Construct a statement, given its kind. Initialize the sid
field to -1,
and labels
, succs
and preds
to the empty list
val mkBlock : stmt list -> block
Construct a block with no attributes, given a list of statements
val mkStmtOneInstr : instr -> stmt
Construct a statement consisting of just one instruction
val compactStmts : stmt list -> stmt list
Try to compress statements so as to get maximal basic blocks
val mkEmptyStmt : unit -> stmt
Returns an empty statement (of kind Instr
)
val dummyInstr : instr
A instr to serve as a placeholder
val dummyStmt : stmt
A statement consisting of just dummyInstr
val mkWhile : guard:exp -> body:stmt list -> stmt list
Make a while loop. Can contain Break or Continue
val mkForIncr : iter:varinfo ->
first:exp ->
stopat:exp ->
incr:exp -> body:stmt list -> stmt list
Make a for loop for(i=start; i<past; i += incr) { ... }. The body
can contain Break but not Continue. Can be used with i a pointer
or an integer. Start and done must have the same type but incr
must be an integer
val mkFor : start:stmt list ->
guard:exp ->
next:stmt list ->
body:stmt list -> stmt list
Make a for loop for(start; guard; next) { ... }. The body can
contain Break but not Continue !!!
Values for manipulating attributes
type
attributeClass =
| |
AttrName of bool |
| |
AttrFunType of bool |
| |
AttrType |
Various classes of attributes
val attributeHash : (string, attributeClass) Hashtbl.t
This table contains the mapping of predefined attributes to classes.
Extend this table with more attributes as you need. This table is used to
determine how to associate attributes with names or types
val partitionAttributes : default:attributeClass ->
attributes ->
attribute list * attribute list *
attribute list
Partition the attributes into classes:name attributes, function type,
and type attributes
val addAttribute : attribute -> attributes -> attributes
Add an attribute. Maintains the attributes in sorted order of the second
argument
val addAttributes : attribute list ->
attributes -> attributes
Add a list of attributes. Maintains the attributes in sorted order. The
second argument must be sorted, but not necessarily the first
val dropAttribute : string -> attributes -> attributes
Remove all attributes with the given name. Maintains the attributes in
sorted order.
val filterAttributes : string -> attributes -> attributes
Retains attributes with the given name
val hasAttribute : string -> attributes -> bool
True if the named attribute appears in the attribute list. The list of
attributes must be sorted.
val typeAttrs : typ -> attribute list
Returns all the attributes contained in a type. This requires a traversal
of the type structure, in case of composite, enumeration and named types
val setTypeAttrs : typ -> attributes -> typ
val typeAddAttributes : attribute list -> typ -> typ
Add some attributes to a type
val typeRemoveAttributes : string list -> typ -> typ
Remove all attributes with the given names from a type. Note that this
does not remove attributes from typedef and tag definitions, just from
their uses
The visitor
type 'a
visitAction =
| |
SkipChildren |
| |
DoChildren |
| |
ChangeTo of 'a |
| |
ChangeDoChildrenPost of 'a * ('a -> 'a) |
Different visiting actions. 'a will be instantiated with exp
, instr
,
etc.
class type cilVisitor = object
.. end
A visitor interface for traversing CIL trees.
class nopCilVisitor :
cilVisitor
Default Visitor.
val visitCilFile : cilVisitor -> file -> unit
Visit a file. This will will re-cons all globals TWICE (so that it is
* tail-recursive). Use
Flx_cil_cil.visitCilFileSameGlobals
if your visitor will
* not change the list of globals.
val visitCilFileSameGlobals : cilVisitor -> file -> unit
A visitor for the whole file that does not change the globals (but maybe
* changes things inside the globals). Use this function instead of
*
Flx_cil_cil.visitCilFile
whenever appropriate because it is more efficient for
* long files.
val visitCilGlobal : cilVisitor -> global -> global list
Visit a global
val visitCilFunction : cilVisitor -> fundec -> fundec
Visit a function definition
val visitCilExpr : cilVisitor -> exp -> exp
val visitCilLval : cilVisitor -> lval -> lval
Visit an lvalue
val visitCilOffset : cilVisitor -> offset -> offset
Visit an lvalue or recursive offset
val visitCilInitOffset : cilVisitor -> offset -> offset
Visit an initializer offset
val visitCilInstr : cilVisitor -> instr -> instr list
Visit an instruction
val visitCilStmt : cilVisitor -> stmt -> stmt
Visit a statement
val visitCilBlock : cilVisitor -> block -> block
Visit a block
val visitCilType : cilVisitor -> typ -> typ
Visit a type
val visitCilVarDecl : cilVisitor -> varinfo -> varinfo
Visit a variable declaration
val visitCilInit : cilVisitor -> init -> init
Visit an initializer
val visitCilAttributes : cilVisitor ->
attribute list -> attribute list
Visit a list of attributes
Flx_cil_utility functions
val msvcMode : bool Pervasives.ref
Whether the pretty printer should print output for the MS VC compiler.
Default is GCC. After you set this function you should call
Flx_cil_cil.initCIL
.
val useLogicalOperators : bool Pervasives.ref
Whether to use the logical operands LAnd and LOr. By default, do not use
* them because they are unlike other expressions and do not evaluate both of
* their operands
type
lineDirectiveStyle =
| |
LineComment |
| |
LinePreprocessorInput |
| |
LinePreprocessorOutput |
Styles of printing line directives
val lineDirectiveStyle : lineDirectiveStyle option Pervasives.ref
How to print line directives
val print_CIL_Input : bool Pervasives.ref
Whether we print something that will only be used as input to our own
* parser. In that case we are a bit more liberal in what we print
val printCilAsIs : bool Pervasives.ref
Whether to print the CIL as they are, without trying to be smart and
* print nicer code. Normally this is false, in which case the pretty
* printer will turn the while(1) loops of CIL into nicer loops, will not
* print empty "else" blocks, etc. These is one case howewer in which if you
* turn this on you will get code that does not compile: if you use varargs
* the __builtin_va_arg function will be printed in its internal form.
Debugging support
val currentLoc : location Pervasives.ref
A reference to the current location. If you are careful to set this to
* the current location then you can use some built-in logging functions that
* will print the location.
CIL has a fairly easy to use mechanism for printing error messages. This
* mechanism is built on top of the pretty-printer mechanism (see
* Flx_cil_pretty.doc
) and the error-message modules (see Flx_cil_errormsg.error
).
Here is a typical example for printing a log message:
ignore (Flx_cil_errormsg.log "Expression %a is not positive (at %s:%i)\n"
d_exp e loc.file loc.line)
and here is an example of how you print a fatal error message that stop the
* execution:
Flx_cil_errormsg.s (Flx_cil_errormsg.bug "Why am I here?")
Notice that you can use C format strings with some extension. The most
useful extension is "%a" that means to consumer the next two argument from
the argument list and to apply the first to unit
and then to the second
and to print the resulting Flx_cil_pretty.doc
. For each major type in CIL there is
a corresponding function that pretty-prints an element of that type:
val d_loc : unit -> location -> Flx_cil_pretty.doc
Flx_cil_pretty-print a location
val d_thisloc : unit -> Flx_cil_pretty.doc
val d_ikind : unit -> ikind -> Flx_cil_pretty.doc
Flx_cil_pretty-print an integer of a given kind
val d_fkind : unit -> fkind -> Flx_cil_pretty.doc
Flx_cil_pretty-print a floating-point kind
val d_storage : unit -> storage -> Flx_cil_pretty.doc
Flx_cil_pretty-print storage-class information
val d_const : unit -> constant -> Flx_cil_pretty.doc
Flx_cil_pretty-print a constant
class type cilPrinter = object
.. end
A printer interface for CIL trees.
class defaultCilPrinterClass :
cilPrinter
val defaultCilPrinter : cilPrinter
val printType : cilPrinter -> unit -> typ -> Flx_cil_pretty.doc
Print a type given a pretty printer
val printExp : cilPrinter -> unit -> exp -> Flx_cil_pretty.doc
Print an expression given a pretty printer
val printLval : cilPrinter -> unit -> lval -> Flx_cil_pretty.doc
Print an lvalue given a pretty printer
val printGlobal : cilPrinter -> unit -> global -> Flx_cil_pretty.doc
Print a global given a pretty printer
val printAttr : cilPrinter -> unit -> attribute -> Flx_cil_pretty.doc
Print an attribute given a pretty printer
val printAttrs : cilPrinter ->
unit -> attributes -> Flx_cil_pretty.doc
Print a set of attributes given a pretty printer
val printInstr : cilPrinter -> unit -> instr -> Flx_cil_pretty.doc
Print an instruction given a pretty printer
val printStmt : cilPrinter -> unit -> stmt -> Flx_cil_pretty.doc
Print a statement given a pretty printer. This can take very long
* (or even overflow the stack) for huge statements. Use
Flx_cil_cil.dumpStmt
* instead.
val printBlock : cilPrinter -> unit -> block -> Flx_cil_pretty.doc
Print a block given a pretty printer. This can take very long
* (or even overflow the stack) for huge block. Use
Flx_cil_cil.dumpBlock
* instead.
val dumpStmt : cilPrinter ->
Pervasives.out_channel -> int -> stmt -> unit
Dump a statement to a file using a given indentation. Use this instead of
*
Flx_cil_cil.printStmt
whenever possible.
val dumpBlock : cilPrinter ->
Pervasives.out_channel -> int -> block -> unit
Dump a block to a file using a given indentation. Use this instead of
*
Flx_cil_cil.printBlock
whenever possible.
val printInit : cilPrinter -> unit -> init -> Flx_cil_pretty.doc
Print an initializer given a pretty printer. This can take very long
* (or even overflow the stack) for huge initializers. Use
Flx_cil_cil.dumpInit
* instead.
val dumpInit : cilPrinter ->
Pervasives.out_channel -> int -> init -> unit
Dump an initializer to a file using a given indentation. Use this instead of
*
Flx_cil_cil.printInit
whenever possible.
val d_type : unit -> typ -> Flx_cil_pretty.doc
val d_exp : unit -> exp -> Flx_cil_pretty.doc
val d_lval : unit -> lval -> Flx_cil_pretty.doc
val d_offset : Flx_cil_pretty.doc -> unit -> offset -> Flx_cil_pretty.doc
val d_init : unit -> init -> Flx_cil_pretty.doc
val d_binop : unit -> binop -> Flx_cil_pretty.doc
Flx_cil_pretty-print a binary operator
val d_attr : unit -> attribute -> Flx_cil_pretty.doc
val d_attrparam : unit -> attrparam -> Flx_cil_pretty.doc
val d_attrlist : unit -> attributes -> Flx_cil_pretty.doc
val d_instr : unit -> instr -> Flx_cil_pretty.doc
val d_label : unit -> label -> Flx_cil_pretty.doc
val d_stmt : unit -> stmt -> Flx_cil_pretty.doc
val d_block : unit -> block -> Flx_cil_pretty.doc
val d_global : unit -> global -> Flx_cil_pretty.doc
Flx_cil_pretty-print the internal representation of a global using
*
Flx_cil_cil.defaultCilPrinter
. This can be extremely slow (or even overflow the
* stack) for huge globals (such as arrays with lots of initializers). Use
*
Flx_cil_cil.dumpGlobal
instead.
val dn_exp : unit -> exp -> Flx_cil_pretty.doc
Versions of the above pretty printers, that don't print #line directives
val dn_lval : unit -> lval -> Flx_cil_pretty.doc
val dn_init : unit -> init -> Flx_cil_pretty.doc
val dn_type : unit -> typ -> Flx_cil_pretty.doc
val dn_global : unit -> global -> Flx_cil_pretty.doc
val dn_attrlist : unit -> attributes -> Flx_cil_pretty.doc
val dn_attr : unit -> attribute -> Flx_cil_pretty.doc
val dn_attrparam : unit -> attrparam -> Flx_cil_pretty.doc
val dn_stmt : unit -> stmt -> Flx_cil_pretty.doc
val dn_instr : unit -> instr -> Flx_cil_pretty.doc
val d_shortglobal : unit -> global -> Flx_cil_pretty.doc
Flx_cil_pretty-print a short description of the global. This is useful for error
* messages
val dumpGlobal : cilPrinter ->
Pervasives.out_channel -> global -> unit
Flx_cil_pretty-print a global. Here you give the channel where the printout
* should be sent.
val dumpFile : cilPrinter -> Pervasives.out_channel -> file -> unit
Flx_cil_pretty-print an entire file. Here you give the channel where the printout
* should be sent.
val bug : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val unimp : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val error : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val errorLoc : location ->
('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val warn : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val warnOpt : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val warnContext : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val warnContextOpt : ('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
val warnLoc : location ->
('a, unit, Flx_cil_pretty.doc) Pervasives.format -> 'a
Sometimes you do not want to see the syntactic sugar that the above
* pretty-printing functions add. In that case you can use the following
* pretty-printing functions. But note that the output of these functions is
* not valid C
val d_plainexp : unit -> exp -> Flx_cil_pretty.doc
Flx_cil_pretty-print the internal representation of an expression
val d_plaininit : unit -> init -> Flx_cil_pretty.doc
Flx_cil_pretty-print the internal representation of an integer
val d_plainlval : unit -> lval -> Flx_cil_pretty.doc
Flx_cil_pretty-print the internal representation of an lvalue
Flx_cil_pretty-print the internal representation of an lvalue offset
val d_plainoffset: unit -> offset -> Flx_cil_pretty.doc
val d_plaintype : unit -> typ -> Flx_cil_pretty.doc
Flx_cil_pretty-print the internal representation of a type
ALPHA conversion
type
undoAlphaElement
This is the type of the elements that are recorded by the alpha
* conversion functions in order to be able to undo changes to the tables
* they modify. Useful for implementing
* scoping
type
alphaTableData
This is the type of the elements of the alpha renaming table.
val newAlphaName : alphaTable:(string, alphaTableData Pervasives.ref) Hashtbl.t ->
undolist:undoAlphaElement list Pervasives.ref option ->
lookupname:string -> string * location
Create a new name based on a given name. The new name is formed from a
* prefix (obtained from the given name by stripping a suffix consisting of _
* followed by only digits), followed by a special separator and then by a
* positive integer suffix. The first argument is a table mapping name
* prefixes to some data that specifies what suffixes have been used and how
* to create the new one. This function updates the table with the new
* largest suffix generated. The "undolist" argument, when present, will be
* used by the function to record information that can be used by
*
Flx_cil_cil.undoAlphaChanges
to undo those changes. Note that the undo
* information will be in reverse order in which the action occurred. Returns
* the new name and, if different from the lookupname, the location of the
* previous occurrence. This function knows about the location implicitly
* from the
Flx_cil_cil.currentLoc
.
val registerAlphaName : alphaTable:(string, alphaTableData Pervasives.ref) Hashtbl.t ->
undolist:undoAlphaElement list Pervasives.ref option ->
lookupname:string -> unit
Register a name with an alpha conversion table to ensure that when later
* we call newAlphaName we do not end up generating this one
val docAlphaTable : unit ->
(string, alphaTableData Pervasives.ref) Hashtbl.t ->
Flx_cil_pretty.doc
Split the name in preparation for newAlphaName. The prefix returned is
used to index into the hashtable. The next result value is a separator
(either empty or the separator chosen to separate the original name from
the index)
val getAlphaPrefix : lookupname:string -> string
val undoAlphaChanges : alphaTable:(string, alphaTableData Pervasives.ref) Hashtbl.t ->
undolist:undoAlphaElement list -> unit
Undo the changes to a table
val uniqueVarNames : file -> unit
Assign unique names to local variables. This might be necessary after you
* transformed the code and added or renamed some new variables. Names are
* not used by CIL internally, but once you print the file out the compiler
* downstream might be confused. You might
* have added a new global that happens to have the same name as a local in
* some function. Rename the local to ensure that there would never be
* confusioin. Or, viceversa, you might have added a local with a name that
* conflicts with a global
Optimization Passes
val peepHole2 : (instr * instr -> instr list option) ->
stmt list -> unit
A peephole optimizer that processes two adjacent statements and possibly
replaces them both. If some replacement happens, then the new statements
are themselves subject to optimization
val peepHole1 : (instr -> instr list option) ->
stmt list -> unit
Similar to peepHole2
except that the optimization window consists of
one statement, not two
Machine dependency
exception SizeOfError of typ
Raised when one of the bitsSizeOf functions cannot compute the size of a
type. This can happen because the type contains array-length expressions
that we don't know how to compute or because it is a type whose size is
not defined (e.g. TFun or an undefined compinfo)
val bitsSizeOf : typ -> int
The size of a type, in bits. Trailing padding is added for structs and
* arrays. Raises
Flx_cil_cil.SizeOfError
when it cannot compute the size. This
* function is architecture dependent, so you should only call this after you
* call
Flx_cil_cil.initCIL
. Remember that on GCC sizeof(void) is 1!
val sizeOf : typ -> exp
val alignOf_int : typ -> int
The minimum alignment (in bytes) for a type. This function is
* architecture dependent, so you should only call this after you call
*
Flx_cil_cil.initCIL
.
val bitsOffset : typ -> offset -> int * int
Give a type of a base and an offset, returns the number of bits from the
* base address and the width (also expressed in bits) for the subobject
* denoted by the offset. Raises
Flx_cil_cil.SizeOfError
when it cannot compute
* the size. This function is architecture dependent, so you should only call
* this after you call
Flx_cil_cil.initCIL
.
val char_is_unsigned : bool Pervasives.ref
val little_endian : bool Pervasives.ref
val locUnknown : location
Represents a location that cannot be determined
val get_instrLoc : instr -> location
Return the location of an instruction
val get_globalLoc : global -> location
Return the location of a global, or locUnknown
val get_stmtLoc : stmtkind -> location
Return the location of a statement, or locUnknown
val dExp : Flx_cil_pretty.doc -> exp
val dInstr : Flx_cil_pretty.doc -> location -> instr
val dGlobal : Flx_cil_pretty.doc -> location -> global
val mapNoCopy : ('a -> 'a) -> 'a list -> 'a list
Like map but try not to make a copy of the list
val mapNoCopyList : ('a -> 'a list) -> 'a list -> 'a list
Like map but each call can return a list. Try not to make a copy of the
list
val startsWith : string -> string -> bool
sm: return true if the first is a prefix of the second string
An Interpreter for constructing CIL constructs
type
formatArg =
The type of argument for the interpreter
val d_formatarg : unit -> formatArg -> Flx_cil_pretty.doc
Flx_cil_pretty-prints a format arg