Getting Started

This page describes how to install, use, and extend Chisel.

Outline

Workflow

The high-level workflow of Chisel is illustrated below:

Installing Chisel

Use one of the following two options to install Chisel:

  1. Downloading Docker image
  2. Building from source code
The following sections describe each of these options.
Option 1: Downloading Docker Image

This is the easiest way to get started with Chisel since you will not need to install anything (except Docker) on your system. You can install Docker on macOS, Windows 10, or Linux.

After installing the Docker engine, simply copy the Dockerfile from here, and run the following commands in the directory in which the Dockerfile is located.

$ docker build -t chisel .
$ docker run --privileged -it chisel
Option 2: Building from Source Code

You can obtain Chisel's source code by cloning this repository. Next, refer to the step-by-step guide to install the dependencies. Finally, refer to the installation guide to build Chisel.

Using Chisel

Preparing a Test Script

The test script is a core part of the debloating. It is where you specify multiple instances of the desired, and undesired features. Desired features, as the name implies, are those that you want to keep, and undesired features are those you want to remove.

Let's see how you can write test scripts for your project:

  1. We recommend that you start by looking at some test script examples in ChiselBench before writing your own test script.
  2. When you are ready to start writing the test script, make a copy of the test template, and fill it with your program features.
  3. Most importantly, the test script must terminate with status code 0 when successful and a non-zero value otherwise.
Tips and Tricks for Writing a Good Script:

  • Avoid redundant test cases.
  • If you are aware of corner cases, include them in the script.
  • Try to come up with test cases that give a high run-time coverage of the parts of code you want to keep.
  • If a test case is more likely to fail, put it earlier in the script.

Running Chisel

Once your test scripts are ready, you can run Chisel. Your program must be compilable using one of the following compilers or compile systems:

  • make
  • clang
  • clang++
  • gcc
  • g++

Chisel can be run in one of two different ways depending on how your program is compiled.

On Individual Files

If your program is compiled directly, run Chisel as follows:

  $ chisel --build ./test.sh -- CC -c X.c Y.c Z.c
where X.c, Y.c, and Z.c are source files of the program, and CC is one of gcc, g++, clang, or clang++.
On a Project

If the input program is compiled via make, run Chisel as follows:

  $ chisel --build ./test.sh -- make
Visualizing the Result

Once you have the reduced program, you can use Chisel to visualize the results in HTML format. The visualization contains the following features:

  • Lines that have been removed from the original program (Green lines exist in both programs, and red lines are the removed ones.)
  • Lines that are covered by the test script (Yellow box next to each program line indicates coverage.)
  • Browsable source code for easier navigation in the program

In order to visualize the results, the following steps should be taken:

  1. Make sure both the original program (e.g., file.c) and the reduced program (e.g., file.c.chisel.c) exist.
  2. Make sure the following tools are installed on your system:
    • clang-format (for reformatting the programs to generate pretty output)
    • llvm-profdata and llvm-cov (for computing the covered lines -- optional)
    • The modified version of woboq codebrowser that can be accessed and installed through its github repository. Follow the installation guide, and make sure to add it to PATH environment variable.
  3. Modify the test script with coverage information. As an example, take a look at mkdir test script. Alternatively, provide a line-separated file with covered line numbers. Note that, if the input name is file.c, this file should be named file.c.coverage.

  4. Finally, run the following command to generate the HTML visualization:

          $ chisel --xref ./test.sh file.c

    By default, you can find the output in xref-output under the same directory.

Command-line Options

Synopsis
  $ chisel [OPTIONS]... TestScript Program
Description of OPTIONS
-h, --help
Shows the help message
-t, --output_dir OUTDIR
Sets the output directory to OUTDIR. (default: chisel-out)
-b, --build
Integrates Chisel with the build system. The following systems are supported: clang, clang++, gcc, g++, and make. For example usages, please refer to this section.
-s, --save_temp
Saves intermediate results in OUTDIR.
-D, --skip_learning
Disables decision tree learning.
-d, --skip_delay_learning
Learns a new model for every iteration. If this flag is not set, the model will not be re-trained in every iteration. Delay learning is useful for decreasing the learning overhead in large input programs.
-g, --skip_global
Skips global-level reduction. Elements that are currently supported in global-level reduction:
  • global variables
  • function declarations
-l, --skip_local
Skips function-level reduction. Statements that are currently supported in function-level reduction:
  • Conditionals (if and switch statements)
  • Loops (while and do-while)
  • Compound statements (aka blocks) ({ body; })
  • Labels (label_test: statement;)
  • Assignments
  • Function calls
-c, --no_cache
Disables caching the intermediate results.
-L, --skip_local_dep
Disables local dependency checking. Local dependency rules improve the performace of Chisel by making the search space smaller. Local dependency rules that are currently implemented:
  1. Preventing dangling labels
  2. Keeping at least one return statement in non-void functions
  3. Def-use dependency should not be broken (flow-insensitive)
-G, --skip_global_dep
Disables global dependency checking. Global dependency rules improve the performace of Chisel by making the search space smaller. Global dependency rules that are currently implemented:
  1. main function should be kept.
  2. If a function is called in the program, its declaration should not be removed.
-C, --skip_dce
Disables static unreachability analysis. This analysis, if enabled, is used to remove the following:
  1. Unused variables
  2. Unused labels
  3. Empty or redundant blocks
-p, --no_profile
Skips printing the profiling report. An example of profiling report is illustrated below: 
    ====================================================
                           Report
    ====================================================
                 Total Time :                996.1s
                Oracle Time :                988.4s
              Learning Time :                  2.3s
       Global Success Ratio :   83% (   51 /    61)
        Local Success Ratio :   14% (  171 /  1148)
      #Functions (Original) :                    43
     #Statements (Original) :                  1804
       #Functions (Reduced) :                    13
      #Statements (Reduced) :                   160
-v, --debug
Prints debugging information.
-S, --stat
Counts the number of statements in the input program.
-X, --xref
Only visualize the results with cross-referencing

Extending Chisel

If you wish to extend Chisel, refer to the developer's documentation.