SAFECode Users Guide

Written by the LLVM Research Group

Overview

This manual provides information on using the tools that come with the SAFECode compiler. There are two primary tools provided in the SAFECode distribution: the first is the SAFECode compiler itself, also known as the sc tool or sc. The second tool is a fault injection tool named injectf.

All of these tools operate on LLVM bitcode, meaning that you must first compile your program to an LLVM bitcode file, feed that bitcode file through the sc or injectf tools, and then generate native code from the output of the sc/inject tool. Furthermore, the sc tool utilizes whole-program analysis: this means that you must compile your program into separate LLVM bitcode files, link these files together into a single bitcode file, process the complete bitcode file with sc, and then generate native code. You cannot run individiual bitcode object files through sc and then link them together.

The sc Tool

The sc tool is the SAFECode compiler. It takes a whole program in LLVM bitcode form, transforms it to be memory safe, and outputs instrumented LLVM bitcode. The output of the sc tool can be converted to native code via the LLVM llc tool and linked with the SAFECode run-time library.

The sc tool utilizes whole-program analysis: this means that you must compile your program into separate LLVM bitcode files, link these files together into a single bitcode file, process the complete bitcode file with sc, and then generate native code. You cannot run individiual bitcode object files through sc and then link them together.

The steps for compiling a program with SAFECode are as follows:

  1. Compile the program into a single LLVM bitcode file:
    1. Compile the program's source file into LLVM bitcode.
    2. Link the LLVM bitcode files together into a single bitcode file.
  2. Process the single bitcode file with the sc tool.
  3. Generate native code for the program.
  4. Link the native code with the SAFECode run-time library.
Compiling a Program Into a Single Bitcode File

Compiling a program into a single bitcode file requires that one first compile each source file into an LLVM bitcode file and then link these bitcode files together into a single bitcode file. To compile source files into an LLVM bitcode file instead of into a native object file, using the -emit-llvm option to llvm-gcc:

Once all of the the source files have been compiled, they can be linked together into a single bitcode file. The llvm-ld tool can be used to do this.

To link files together using llvm-ld, do the following:

Using the sc Tool

The sc tool takes as input a bitcode file representing a whole program and outputs an instrumented bitcode file. Invoke the sc tool as follows:

Options to the sc tool include:
Creating an Executable

Creating an executable from the output of the sc tool requires that one generate the native code for the output bitcode and link in the run-time libraries implementing the memory allocator and the SAFECode run-time checks. Generating native code can be done using the LLVM llc tool:

Creating the final executable can be done using GCC. At a minimum, you need to link in the two SAFECode run-time libraries and the C++ standard library. You will also need to link in any additional native code libraries that were not linked in as LLVM bitcode libraries. Below is an example of creating the final executable. In the example, Configuration is either Release, Debug, or Profile depending upon whether you built a Release, Debug, or Profile version of SAFECode: