## 6 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:

- An index of all types
- An index of all values
- Cil.file is the representation of a file.
- Cil.global is the representation of a global declaration or definitions. Values for operating on globals.
- Cil.typ is the representation of a type. Values for operating on types.
- Cil.compinfo is the representation of a structure or a union type
- Cil.fieldinfo is the representation of a field in a structure or a union
- Cil.enuminfo is the representation of an enumeration type.
- Cil.varinfo is the representation of a variable
- Cil.fundec is the representation of a function
- Cil.lval is the representation of an lvalue. Values for operating on lvalues.
- Cil.exp is the representation of an expression without side-effects. Values for operating on expressions.
- Cil.instr is the representation of an instruction (with side-effects but without control-flow)
- Cil.stmt is the representation of a control-flow statements. Values for operating on statements.
- Cil.attribute is the representation of attributes. Values for operating on attributes.

### 6.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:

- Ignore this node and all its descendants
- Descend into all of the children and when done rebuild the node if any of the children have changed.
- Replace the subtree rooted at the node with another tree.
- Replace the subtree with another tree, then descend into the children and rebuild the node if necessary and then invoke a user-specified function.
- In addition to all of the above actions then visitor can specify that some instructions should be queued to be inserted before the current instruction or statement being visited.

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:

- Cil.visitCilFile or Cil.visitCilFileSameGlobals - visit a file
- Cil.visitCilGlobal - visit a global
- Cil.visitCilFunction - visit a function definition
- Cil.visitCilExp - visit an expression
- Cil.visitCilLval - visit an lvalue
- Cil.visitCilInstr - visit an instruction
- Cil.visitCilStmt - visit a statement
- Cil.visitCilType - visit a type. Note that this does not visit the files of a composite type. use visitGlobal to visit the [GCompTag] that defines the fields.

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.

### 6.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:

- In the grammar description above non-terminals are written with uppercase initial
- All of the patterns consist of the `%` character followed by one or two letters, followed by “:” and an indentifier. For each such pattern there is a corresponding constructor of the Cil.formatArg type, whose name is the letter 'F' followed by the same one or two letters as in the pattern. That constructor is used by the user code to pass a Cil.formatArg actual argument to the interpreted constructor and by the interpreted deconstructor to return what was matched for a pattern.
- If the pattern name is uppercase, it designates a list of the elements designated by the corresponding lowercase pattern. E.g. %E designated lists of expressions (as in the actual arguments of a call).
- The two-letter patterns whose second letter is “o” designate an optional element. E.g. %eo designates an optional expression (as in the length of an array).
- Unlike in calls to `printf`, the pattern %g is used for strings.
- The usual precedence and associativity rules as in C apply
- The pattern string can contain newlines and comments, using both the `/* ... */` style as well as the `//` one.
- When matching a “cast” pattern of the form `( T ) E`, the deconstructor will match even expressions that do not have the actual cast but in that case the type is matched against the type of the expression. E.g. the patters `"(int)%e"` will match any expression of type `int` whether it has an explicit cast or not.
- The %k pattern is used to construct and deconstruct an integer type of any kind.
- Notice that the syntax of types and declaration are the same (in order to simplify the parser). This means that technically you can write a whole declaration instead of a type in the cast. In this case the name that you declare is ignored.
- In lists of formal parameters and lists of attributes, an empty list in the pattern matches any formal parameters or attributes.
- When matching types, uses of named types are unrolled to expose a real type before matching.
- The order of the attributes is ignored during matching. The the pattern for a list of attributes contains %A then the resulting `formatArg` will be bound to all attributes in the list. For example, the pattern `"const %A"` matches any list of attributes that contains `const` and binds the corresponding placeholder to the entire list of attributes, including `const`.
- All instruction-patterns must be terminated by semicolon
- The autoincrement and autodecrement instructions are not supported. Also not supported are complex expressions, the `&&` and `||` shortcut operators, and a number of other more complex instructions or statements. In general, the patterns support only constructs that can be represented directly in CIL.
- The pattern argument identifiers are not used during deconstruction. Instead, the result contains a sequence of values in the same order as the appearance of pattern arguments in the pattern.
- You can mix statements with declarations. For each declaration a new temporary will be constructed (using a function you provive). You can then refer to that temporary by name in the rest of the pattern.
- The `%v:` pattern specifier is optional.

The following function are defined in the `Formatcil` module for constructing and deconstructing:

- Formatcil.cExp constructs Cil.exp.
- Formatcil.cType constructs Cil.typ.
- Formatcil.cLval constructs Cil.lval.
- Formatcil.cInstr constructs Cil.instr.
- Formatcil.cStmt and Formatcil.cStmts construct Cil.stmt.
- Formatcil.dExp deconstructs Cil.exp.
- Formatcil.dType deconstructs Cil.typ.
- Formatcil.dLval deconstructs Cil.lval.
- Formatcil.dInstr deconstructs Cil.lval.

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.

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

### 6.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:

- Cil.d_exp - print an expression
- Cil.d_type - print a type
- Cil.d_lval - print an lvalue
- Cil.d_global - print a global
- Cil.d_stmt - print a statment
- Cil.d_instr - print an instruction
- Cil.d_init - print an initializer
- Cil.d_attr - print an attribute
- Cil.d_attrlist - print a set of attributes
- Cil.d_loc - print a location
- Cil.d_ikind - print an integer kind
- Cil.d_fkind - print a floating point kind
- Cil.d_const - print a constant
- Cil.d_storage - print a storage specifier

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.printExp - print an expression
- Cil.printType - print a type
- Cil.printLval - print an lvalue
- Cil.printGlobal - print a global
- Cil.printStmt - print a statment
- Cil.printInstr - print an instruction
- Cil.printInit - print an initializer
- Cil.printAttr - print an attribute
- Cil.printAttrs - print a set of attributes

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.

### 6.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:

- GCC name attributes:

  section, constructor, destructor, unused, weak, no_instrument_function, noreturn, alias, no_check_memory_usage, dllinport, dllexport, exception, model

  Note: the "noreturn" attribute would be more appropriately qualified as a function type attribute. But we classify it as a name attribute to make it easier to support a similarly named MSVC attribute.

- GCC function type attributes:

  fconst (printed as "const"), format, regparm, stdcall, cdecl, longcall

  I was not able to completely decipher the position in which these attributes must go. So, the CIL elaborator knows these names and applies the following rules:

  - All of the name attributes that appear in the specifier part (i.e. at the beginning) of a declaration are associated with all declared names.
  - All of the name attributes that appear at the end of a declarator are associated with the particular name being declared.
  - More complicated is the handling of the function type attributes, since there can be more than one function in a single declaration (a function returning a pointer to a function). Lacking any real understanding of how GCC handles this, I attach the function type attribute to the "nearest" function. This means that if a pointer to a function is "nearby" the attribute will be correctly associated with the function. In truth I pray that nobody uses declarations as that of x3 above.

##### 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 !