Previous Contents Next

7   CIL API Documentation

The CIL API is documented in the file src/cil.mli. We also have an online documentation extracted from cil.mli. We index below the main types that are used to represent C programs in CIL:

7.1   Using the visitor

One of the most useful tools exported by the CIL API is an implementation of the visitor pattern for CIL programs. The visiting engine scans depth-first the structure of a CIL program and at each node is queries a user-provided visitor structure whether it should do one of the following operations: By writing visitors you can customize the program traversal and transformation. One major limitation of the visiting engine is that it does not propagate information from one node to another. Each visitor must use its own private data to achieve this effect if necessary.

Each visitor is an object that is an instance of a class of type Cil.cilVisitor.. The most convenient way to obtain such classes is to specialize the Cil.nopCilVisitor.class (which just traverses the tree doing nothing). Any given specialization typically overrides only a few of the methods. Take a look for example at the visitor defined in the module logwrites.ml. Another, more elaborate example of a visitor is the [copyFunctionVisitor] defined in cil.ml.

Once you have defined a visitor you can invoke it with one of the functions: Some transformations may want to use visitors to insert additional instructions before statements and instructions. To do so, pass a list of instructions to the Cil.queueInstr method of the specialized object. The instructions will automatically be inserted before that instruction in the transformed code. The Cil.unqueueInstr method should not normally be called by the user.

7.2   Interpreted Constructors and Deconstructors

Interpreted constructors and deconstructors are a facility for constructing and deconstructing CIL constructs using a pattern with holes that can be filled with a variety of kinds of elements. The pattern is a string that uses the C syntax to represent C language elements. For example, the following code: 

Formatcil.cType "void * const (*)(int x)"
is an alternative way to construct the internal representation of the type of pointer to function with an integer argument and a void * const as result: 

TPtr(TFun(TVoid [Attr("const", [])],
          [ ("x", TInt(IInt, []), []) ], false, []), [])
The advantage of the interpreted constructors is that you can use familiar C syntax to construct CIL abstract-syntax trees.

You can construct this way types, lvalues, expressions, instructions and statements. The pattern string can also contain a number of placeholders that are replaced during construction with CIL items passed as additional argument to the construction function. For example, the %e:id placeholder means that the argument labeled ``id'' (expected to be of form Fe exp) will supply the expression to replace the placeholder. For example, the following code constructs an increment instruction at location loc: 

Formatcil.cInstr "%v:x = %v:x + %e:something"
        loc
        [ ("something", Fe some_exp);
          ("x", Fv some_varinfo) ]
An alternative way to construct the same CIL instruction is: 

Set((Var some_varinfo, NoOffset),
    BinOp(PlusA, Lval (Var some_varinfo, NoOffset),
          some_exp, intType), 
    loc)
See Cil.formatArg for a definition of the placeholders that are understood.

A dual feature is the interpreted deconstructors. This can be used to test whether a CIL construct has a certain form: 

Formatcil.dType "void * const (*)(int x)" t
will test whether the actual argument t is indeed a function pointer of the required type. If it is then the result is Some [] otherwise it is None. Furthermore, for the purpose of the interpreted deconstructors placeholders in patterns match anything of the right type. For example, 

Formatcil.dType "void * (*)(%F:t)" t
will match any function pointer type, independent of the type and number of the formals. If the match succeeds the result is Some [ FF forms ] where forms is a list of names and types of the formals. Note that each member in the resulting list corresponds positionally to a placeholder in the pattern.

The interpreted constructors and deconstructors do not support the complete C syntax, but only a substantial fragment chosen to simplify the parsing. The following is the syntax that is supported: 
Expressions:
  E ::= %e:ID | %d:ID | %g:ID | n | L | ( E ) | Unop E | E Binop E 
        | sizeof E | sizeof ( T ) | alignof E  | alignof ( T ) 
        | & L | ( T ) E 

Unary operators:
  Unop ::= + | - | ~ | %u:ID

Binary operators:
  Binop ::= + | - | * | / | << | >> | & | ``|'' | ^ 
          | == | != | < | > | <= | >= | %b:ID

Lvalues:
  L ::= %l:ID | %v:ID Offset | * E | (* E) Offset | E -> ident Offset 

Offsets:
  Offset ::= empty | %o:ID | . ident Offset | [ E ] Offset

Types:
  T ::= Type_spec Attrs Decl

Type specifiers:
  Type_spec ::= void | char | unsigned char | short | unsigned short
            | int | unsigned int | long | unsigned long | %k:ID | float 
            | double | struct %c:ID | union %c:ID 


Declarators:
  Decl ::= * Attrs Decl | Direct_decl


Direct declarators:
  Direct_decl ::= empty | ident | ( Attrs Decl ) 
                 | Direct_decl [ Exp_opt ]
                 | ( Attrs Decl )( Parameters )

Optional expressions
  Exp_opt ::= empty | E | %eo:ID

Formal parameters
  Parameters ::= empty | ... | %va:ID | %f:ID | T | T , Parameters

List of attributes
  Attrs ::= empty | %A:ID | Attrib Attrs

Attributes
  Attrib ::= const | restrict | volatile | __attribute__ ( ( GAttr ) )

GCC Attributes
  GAttr ::= ident | ident ( AttrArg_List )

Lists of GCC Attribute arguments:
  AttrArg_List ::= AttrArg | %P:ID | AttrArg , AttrArg_List

GCC Attribute arguments  
  AttrArg ::= %p:ID | ident | ident ( AttrArg_List )

Instructions
  Instr ::= %i:ID ; | L = E ; | L Binop= E | Callres L ( Args )

Actual arguments
   Args ::= empty | %E:ID | E | E , Args

Call destination
   Callres ::= empty | L = | %lo:ID

Statements
  Stmt ::= %s:ID | if ( E ) then Stmt ; | if ( E ) then Stmt else Stmt ;
       | return Exp_opt | break ; | continue ; | { Stmt_list } 
       | while (E ) Stmt | Instr_list 

Lists of statements
   Stmt_list ::= empty | %S:ID | Stmt Stmt_list  
                | Type_spec Attrs Decl ; Stmt_list
                | Type_spec Attrs Decl = E ; Stmt_list
                | Type_spec Attrs Decl = L (Args) ; Stmt_list

List of instructions
   Instr_list ::= Instr | %I:ID | Instr Instr_list
Notes regarding the syntax: The following function are defined in the Formatcil module for constructing and deconstructing: Below is an example using interpreted constructors. This example generates the CIL representation of code that scans an array backwards and initializes every even-index element with an expression: 

Formatcil.cStmts
  loc
  "int idx = sizeof(array) / sizeof(array[0]) - 1;
   while(idx >= 0) {
     // Some statements to be run for all the elements of the array
     %S:init
     if(! (idx & 1)) 
       array[idx] = %e:init_even;
     /* Do not forget to decrement the index variable */
     idx = idx - 1;
   }"
  (fun n t -> makeTempVar myfunc ~name:n t)
  [ ("array", Fv myarray); 
    ("init", FS [stmt1; stmt2; stmt3]);
    ("init_even", Fe init_expr_for_even_elements) ]
To write the same CIL statement directly in CIL would take much more effort. Note that the pattern is parsed only once and the result (a function that takes the arguments and constructs the statement) is memoized.

7.2.1   Performance considerations for interpreted constructors

Parsing the patterns is done with a LALR parser and it takes some time. To improve performance the constructors and deconstructors memoize the parsed patterns and will only compile a pattern once. Also all construction and deconstruction functions can be applied partially to the pattern string to produce a function that can be later used directly to construct or deconstruct. This function appears to be about two times slower than if the construction is done using the CIL constructors (without memoization the process would be one order of magnitude slower.) However, the convenience of interpreted constructor might make them a viable choice in many situations when performance is not paramount (e.g. prototyping).

7.3   Printing and Debugging support

The Modules Pretty and Errormsg contain respectively utilities for pretty printing and reporting errors and provide a convenient printf-like interface.

Additionally, CIL defines for each major type a pretty-printing function that you can use in conjunction with the Pretty interface. The following are some of the pretty-printing functions: You can even customize the pretty-printer by creating instances of Cil.cilPrinter.. Typically such an instance extends Cil.defaultCilPrinter. Once you have a customized pretty-printer you can use the following printing functions: CIL has certain internal consistency invariants. For example, all references to a global variable must point to the same varinfo structure. This ensures that one can rename the variable by changing the name in the varinfo. These constraints are mentioned in the API documentation. There is also a consistency checker in file src/check.ml. If you suspect that your transformation is breaking these constraints then you can pass the --check option to cilly and this will ensure that the consistency checker is run after each transformation.

7.4   Attributes



In CIL you can attach attributes to types and to names (variables, functions and fields). Attributes are represented using the type Cil.attribute. An attribute consists of a name and a number of arguments (represented using the type Cil.attrparam). Almost any expression can be used as an attribute argument. Attributes are stored in lists sorted by the name of the attribute. To maintain list ordering, use the functions Cil.typeAttrs to retrieve the attributes of a type and the functions Cil.addAttribute and Cil.addAttributes to add attributes. Alternatively you can use Cil.typeAddAttributes to add an attribute to a type (and return the new type).

GCC already has extensive support for attributes, and CIL extends this support to user-defined attributes. A GCC attribute has the syntax:

 gccattribute ::= __attribute__((attribute))    (Note the double parentheses)
Since GCC and MSVC both support various flavors of each attribute (with or without leading or trailing _) we first strip ALL leading and trailing _ from the attribute name (but not the identified in [ACons] parameters in Cil.attrparam). When we print attributes, for GCC we add two leading and two trailing _; for MSVC we add just two leading _.

There is support in CIL so that you can control the printing of attributes (see Cil.setCustomPrintAttribute and Cil.setCustomPrintAttributeScope). This custom-printing support is now used to print the "const" qualifier as "const" and not as "__attribute__((const))".

The attributes are specified in declarations. This is unfortunate since the C syntax for declarations is already quite complicated and after writing the parser and elaborator for declarations I am convinced that few C programmers understand it completely. Anyway, this seems to be the easiest way to support attributes.

Name attributes must be specified at the very end of the declaration, just before the = for the initializer or before the , the separates a declaration in a group of declarations or just before the ; that terminates the declaration. A name attribute for a function being defined can be specified just before the brace that starts the function body.

For example (in the following examples A1,...,An are type attributes and N is a name attribute (each of these uses the __attribute__ syntax):


 int x N;
 int x N, * y N = 0, z[] N;
 extern void exit() N;
 int fact(int x) N { ... }
Type attributes can be specified along with the type using the following rules:
  1. The type attributes for a base type (int, float, named type, reference to struct or union or enum) must be specified immediately following the type (actually it is Ok to mix attributes with the specification of the type, in between unsigned and int for example).

    For example: 
    
  int A1 x N;  /* A1 applies to the type int. An example is an attribute
                   "even" restricting the type int to even values. */
  struct foo A1 A2 x; // Both A1 and A2 apply to the struct foo type
  2. The type attributes for a pointer type must be specified immediately after the * symbol. 
    
 /* A pointer (A1) to an int (A2) */
 int A2 * A1 x;
 /* A pointer (A1) to a pointer (A2) to a float (A3) */
 float A3 * A2 * A1 x;
    Note: The attributes for base types and for pointer types are a strict extension of the ANSI C type qualifiers (const, volatile and restrict). In fact CIL treats these qualifiers as attributes.

  3. The attributes for a function type or for an array type can be specified using parenthesized declarators.

    For example: 
    
   /* A function (A1) from int (A2) to float (A3) */
   float A3 (A1 f)(int A2);

   /* A pointer (A1) to a function (A2) that returns an int (A3) */
   int A3 (A2 * A1 pfun)(void);

   /* An array (A1) of int (A2) */
   int A2 (A1 x0)[]

   /* Array (A1) of pointers (A2) to functions (A3) that take an int (A4) and 
    * return a pointer (A5) to int (A6)  */
   int A6 * A5 (A3 * A2 (A1 x1)[5])(int A4);


   /* A function (A4) that takes a float (A5) and returns a pointer (A6) to an 
    * int (A7) */
   extern int A7 * A6 (A4 x2)(float A5 x);

   /* A function (A1) that takes a int (A2) and that returns a pointer (A3) to 
    * a function (A4) that takes a float (A5) and returns a pointer (A6) to an 
    * int (A7) */
   int A7 * A6 (A4 * A3 (A1 x3)(int A2 x))(float A5) {
      return & x2;
   }
Note: ANSI C does not allow the specification of type qualifiers for function and array types, although it allows for the parenthesized declarator. With just a bit of thought (looking at the first few examples above) I hope that the placement of attributes for function and array types will seem intuitive.

This extension is not without problems however. If you want to refer just to a type (in a cast for example) then you leave the name out. But this leads to strange conflicts due to the parentheses that we introduce to scope the attributes. Take for example the type of x0 from above. It should be written as: 


        int A2 (A1 )[]
But this will lead most C parsers into deep confusion because the parentheses around A1 will be confused for parentheses of a function designator. To push this problem around (I don't know a solution) whenever we are about to print a parenthesized declarator with no name but with attributes, we comment out the attributes so you can see them (for whatever is worth) without confusing the compiler. For example, here is how we would print the above type:


        int A2 /*(A1 )*/[]
Handling of predefined GCC attributes
GCC already supports attributes in a lot of places in declarations. The only place where we support attributes and GCC does not is right before the { that starts a function body.

GCC classifies its attributes in attributes for functions, for variables and for types, although the latter category is only usable in definition of struct or union types and is not nearly as powerful as the CIL type attributes. We have made an effort to reclassify GCC attributes as name and type attributes (they only apply for function types). Here is what we came up with:

Handling of predefined MSVC attributes
MSVC has two kinds of attributes, declaration modifiers to be printed before the storage specifier using the notation "__declspec(...)" and a few function type attributes, printed almost as our CIL function type attributes.

The following are the name attributes that are printed using __declspec right before the storage designator of the declaration: thread, naked, dllimport, dllexport, noreturn

The following are the function type attributes supported by MSVC: fastcall, cdecl, stdcall

It is not worth going into the obscure details of where MSVC accepts these type attributes. The parser thinks it knows these details and it pulls these attributes from wherever they might be placed. The important thing is that MSVC will accept if we print them according to the rules of the CIL attributes !

Previous Contents Next