From 6ae711b1d900bffbca407fe97d5e5ce97745dff1 Mon Sep 17 00:00:00 2001 From: Dominic Chen Date: Thu, 25 Jul 2013 10:45:32 +0100 Subject: move website to separate repo --- www/CoreutilsExperiments.html | 158 -------- www/Documentation.html | 57 --- www/GetInvolved.html | 53 --- www/GetStarted.html | 244 ----------- www/KQuery.html | 620 ---------------------------- www/OpenProjects.html | 91 ----- www/Publications.html | 402 ------------------- www/TestingCoreutils.html | 893 ----------------------------------------- www/Tutorial-1.html | 187 --------- www/Tutorial-2.html | 287 ------------- www/Tutorials.html | 38 -- www/bugs.html | 24 -- www/content.css | 75 ---- www/content/coreutils_kc_0.png | Bin 277141 -> 0 bytes www/content/coreutils_kc_1.png | Bin 232377 -> 0 bytes www/developers-guide.html | 114 ------ www/index.html | 36 -- www/klee-dev.html | 31 -- www/klee-files.html | 137 ------- www/klee-options.html | 99 ----- www/klee-tools.html | 84 ---- www/menu.css | 39 -- www/menu.html.incl | 31 -- www/resources/Regexp.c.html | 78 ---- www/resources/get_sign.c.html | 37 -- www/resources/islower.c.html | 33 -- 26 files changed, 3848 deletions(-) delete mode 100644 www/CoreutilsExperiments.html delete mode 100644 www/Documentation.html delete mode 100644 www/GetInvolved.html delete mode 100644 www/GetStarted.html delete mode 100644 www/KQuery.html delete mode 100644 www/OpenProjects.html delete mode 100644 www/Publications.html delete mode 100644 www/TestingCoreutils.html delete mode 100644 www/Tutorial-1.html delete mode 100644 www/Tutorial-2.html delete mode 100644 www/Tutorials.html delete mode 100644 www/bugs.html delete mode 100644 www/content.css delete mode 100644 www/content/coreutils_kc_0.png delete mode 100644 www/content/coreutils_kc_1.png delete mode 100644 www/developers-guide.html delete mode 100644 www/index.html delete mode 100644 www/klee-dev.html delete mode 100644 www/klee-files.html delete mode 100644 www/klee-options.html delete mode 100644 www/klee-tools.html delete mode 100644 www/menu.css delete mode 100644 www/menu.html.incl delete mode 100644 www/resources/Regexp.c.html delete mode 100644 www/resources/get_sign.c.html delete mode 100644 www/resources/islower.c.html diff --git a/www/CoreutilsExperiments.html b/www/CoreutilsExperiments.html deleted file mode 100644 index c0f0829c..00000000 --- a/www/CoreutilsExperiments.html +++ /dev/null @@ -1,158 +0,0 @@ - - - - - - KLEE - Coreutils Experiments - - - - - -
- -

Coreutils Experiments

- -

- This document is meant to give additional information regarding - the Coreutils experiments discussed in - our KLEE - OSDI'08 paper. However, please note that in the last several - years, KLEE and its dependencies (particularly LLVM and STP), have - undergone major changes, which have resulted in considerable - different behavior on several benchmarks, including Coreutils.

- -

- This document is structured as a series of FAQs: -

- -
    -
  1. How did you build Coreutils?
    - Please follow the instructions in the Coreutils Tutorial. -
    2. - -
  2. What version of LLVM was used in the OSDI paper?
    - We generally kept in sync with the LLVM top-of-tree, which at the time - was somewhere around LLVM 2.2 and 2.3.
    3. - - -
  3. What version of STP was used in the OSDI paper?
    - An old version of STP, which is still available as part of KLEE's - repository, in revisions up to r161056. -
    4. - -
  4. On what OS did you run your experiments?
    - We ran most experiments on a 32-bit Fedora machine with SELinux - support. The most important aspect is that this was a 32-bit - system: the constraints generated on a 64-bit system are typically - more complex and memory consumption might also increase. -
    5. - -
  5. What are the 89 Coreutils applications that you tested?
    -
    - [ base64 basename cat chcon chgrp chmod chown chroot cksum comm cp csplit cut date dd df dircolors dirname du echo env expand expr factor false fmt fold head hostid hostname id ginstall join kill link ln logname ls md5sum mkdir mkfifo mknod mktemp mv nice nl nohup od paste pathchk pinky pr printenv printf ptx pwd readlink rm rmdir runcon seq setuidgid shred shuf sleep sort split stat stty sum sync tac tail tee touch tr tsort tty uname unexpand uniq unlink uptime users wc whoami who yes -
    -
    6. - -
  6. What options did you run KLEE with?
    - We used the following options (the command below is for paste): -
    -$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    - --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    - --use-cex-cache --with-libc --with-file-model=release \
    - --allow-external-sym-calls --only-output-states-covering-new \
    - --exclude-libc-cov --exclude-cov-file=./../lib/functions.txt \
    - --environ=test.env --run-in=/tmp/sandbox --output-dir=paste-data-1h \
    - --max-sym-array-size=4096 --max-instruction-time=10. --max-time=3600. \
    - --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    - --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    - --randomize-fork --use-random-path --use-interleaved-covnew-NURS \
    - --use-batching-search --batch-instructions 10000 --init-env \
    - ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - - Some of these options have been renamed or removed in the current - version of KLEE. Most notably, the options "--exclude-libc-cov" - and "--exclude-cov-file" were implemented in a fragile way and we - decided to remove them from KLEE. The idea was to treat the - functions in libc or specified in a text file as "covered". (For - the Coreutils experiments, we were interested in covering the - code in the tools themselves, as opposed to library code, see the - paper for more details). If you plan to reimplement these - options in a clean way, please consider contributing your code to the mainline. -
    7. - -
  7. What are the options closest to the ones above that - work with the current version KLEE?
    - Try the following: - -
    -$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    - --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    - --use-cex-cache --libc=uclibc --posix-runtime \
    - --allow-external-sym-calls --only-output-states-covering-new \
    - --environ=test.env --run-in=/tmp/sandbox \
    - --max-sym-array-size=4096 --max-instruction-time=30. --max-time=3600. \
    - --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    - --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    - --randomize-fork --search=random-path --search=nurs:covnew \
    - --use-batching-search --batch-instructions=10000 \
    - ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - -
    8. - -
  8. How do I generate test.env and /tmp/sandbox?
    - We used a simple environment and a "sandbox" directory to make - our experiments more deterministic. To recreate them, follow - these steps: -
      -
    1. Download testing-env.sh by clicking here, and place it in the current directory.
      2. -
    2. Create test.env by running: -
      - $ env -i /bin/bash -c '(source testing-env.sh; env >test.env)' -
      -
      3. -
    3. Download sandbox.tgz by clicking here, place it in /tmp, and run: -
      - $ cd /tmp - $ tar xzfv sandbox.tgz -
      -
      4. -
    -
    9. -
  9. - What symbolic arguments did you use in your experiments?
    - We ran most utilities using the arguments below. Our choice was - based on a high-level understanding of the Coreutils - applications: most behavior can be triggered with no more than two - short options, one long option, and two small input streams (stdin and one file). -
    - --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - - - - For eight tools where the coverage results were unsatisfactory, -we consulted the man page and increased the number and size of -arguments and files as follows: -
    - dd: --sym-args 0 3 10 --sym-files 1 8 --sym-stdout
    - dircolors: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    - echo: --sym-args 0 4 300 --sym-files 2 30 --sym-stdout
    - expr: --sym-args 0 1 10 --sym-args 0 3 2 --sym-stdout
    - mknod: --sym-args 0 1 10 --sym-args 0 3 2 --sym-files 1 8 --sym-stdout
    - od: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    - pathchk: --sym-args 0 1 2 --sym-args 0 1 300 --sym-files 1 8 --sym-stdout
    - printf: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout -
    - -
    10. - -
- - -
- - diff --git a/www/Documentation.html b/www/Documentation.html deleted file mode 100644 index 538cada7..00000000 --- a/www/Documentation.html +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - KLEE - Documentation - - - - - -
- -

KLEE Documentation

- - -
    -
  1. - KLEE Tutorials: - Simple examples of how to use KLEE to test programs. -
    2. - -
  2. - KLEE Options: - Overview of KLEE's main command-line options. -
    3. - -
  3. - KLEE Generated Files: - Overview of the main files generated by KLEE. -
    4. - -
  4. - KLEE Tools: - Overview of the main auxiliary tools provided by KLEE. -
    5. - -
  5. - KQuery Language Reference Manual: - The reference manual for the KQuery language, used for interacting with - the KLEE solver (kleaver). -
    6. - -
  6. - OSDI'08 Coreutils Experiments: - Some information about the Coreutils experiments presented in our KLEE OSDI'08 paper. -
    7. - -
  7. - Developer's Guide: - A brief guide on working with the KLEE source code. -
    8. -
-
- - diff --git a/www/GetInvolved.html b/www/GetInvolved.html deleted file mode 100644 index 2ff2b5ee..00000000 --- a/www/GetInvolved.html +++ /dev/null @@ -1,53 +0,0 @@ - - - - - KLEE - Get Involved - - - - - - - -
- -

Getting Involved with the KLEE Project

- -

If you are interested in following development of KLEE, or would like to -contribute, here are some resources that may prove useful.

- -

Mailing Lists

- -

Currently the main list for KLEE discussion (both for users and developers) -is klee-dev.

- -

Commit messages to the KLEE repository go to -klee-commits. This -is also the place to send patches if you are interested in contributing to -KLEE.

- -

Bug Reports

- -

If you find a bug in KLEE, please report it on klee-dev -and also fill a bug report on Bugzilla under the klee product.

- - -

Working with the Code

- -

You should first check KLEE's developer's guide.

- -

Developer documentation is written in - doxygen. - -

- -

- -

Many parts of KLEE rely on the LLVM infrastructure, so you might also want to look at -LLVM's General Programming Documentation.

- -
- - diff --git a/www/GetStarted.html b/www/GetStarted.html deleted file mode 100644 index 7f6199dc..00000000 --- a/www/GetStarted.html +++ /dev/null @@ -1,244 +0,0 @@ - - - - - KLEE - Getting Started - - - - - - - -
- -

Getting Started: Building and Running KLEE

- - - -

-1. Trying out KLEE without installing any dependencies
-2. Building KLEE
-

- - -

Trying out KLEE without installing any dependencies

- -

-If you would like to try out KLEE without the hassle of compiling or installing dependencies, download the self-contained package (200MB), and follow the instructions in klee-cde-package/README to get up-and-running! -

- -

-This package contains a self-contained source+binary distribution of KLEE and all of its associated dependencies (e.g., llvm-2.7, llvm-gcc, uClibc, svn). Using this package, you can: -

- -
    -
  1. Compile target programs using llvm-gcc -
  2. Run KLEE on target programs compiled with llvm-gcc -
  3. Modify KLEE's source code, re-compile it to build a new KLEE binary, and then run the test suite using the new binary -
  4. Pull the latest KLEE source code updates from SVN -
  5. Run the entire Coreutils case study -
- -

-... all without compiling or installing anything else on your Linux machine! -

- -

-The only requirement is that you are running a reasonably-modern x86-Linux distro that can execute 32-bit ELF binaries. This package was created using the CDE auto-packaging tool. -

- -

-NOTE: The CDE package is mainly meant for trying out KLEE on -some simple examples and the Coreutils case study. It is likely that -you will run into errors when testing other applications, in which -case you will need to follow the full installation instructions below. -

- - -

Building KLEE

- - -

The current procedure for building is outlined below.

- -
    - -
  1. Install dependencies: - -KLEE requires all the dependencies of LLVM, which are discussed here. In particular, you should have the following packages (the list is likely not complete): g++, curl, dejagnu, subversion, bison, flex: -
    - $ sudo apt-get install g++ curl dejagnu subversion bison flex (Ubuntu)
    - $ sudo yum install g++ curl dejagnu subversion bison flex (Fedora) -
    -

    - -On some architectures, you might also need to set the following environment variables (best to put them in a config file like .bashrc): -
    - $ export C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
    - $ export CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu -
    - -
  2. Build LLVM 2.9: - -

    -KLEE is built on top of LLVM; the first -steps are to get a working LLVM installation. -See Getting Started -with the LLVM System for more information. -

    - -

    -NOTE: KLEE is currently tested only on Linux x86-32 and x86-64 -targets, using LLVM 2.9. KLEE will not work with older LLVM -versions (e.g., 2.5), and might not work with newer versions (e.g., -3.0). -

    - - -
      -
    1. Install llvm-gcc: -
        -
      • Download and install the LLVM 2.9 release of llvm-gcc - from here. - -
        Add llvm-gcc to your PATH. It - is important to do this first so that llvm-gcc is - found in subsequent configure - steps. llvm-gcc will be used later to compile - programs that KLEE can execute. -
        • - -
      • Forgetting to add llvm-gcc to your PATH at this point is - by far the most common source of build errors reported by new - users.
        • -
      -
      2. - -
    2. Download and build LLVM 2.9: -
      - $ curl -O http://llvm.org/releases/2.9/llvm-2.9.tgz
      - $ tar zxvf llvm-2.9.tgz
      - $ cd llvm-2.9
      - $ ./configure --enable-optimized --enable-assertions
      - $ make -
      - - (the --enable-optimized configure argument is not necessary, but - KLEE runs very slowly in Debug mode). -
      3. - -
    - - -
  3. Build STP: - -

    KLEE is based on -the STP -constraint solver. STP does not make frequent releases, and its -Subversion repository is under constant development and may be -unstable. The instructions below are for a particular revision which -we have used successfully, but you can try a more recent revision by -changing or removing the -r argument to the svn co -command. (Please let us know if you have successfully and extensively -used KLEE with a more recent version of STP.) -

    - -
    - $ svn co -r 940 https://stp-fast-prover.svn.sourceforge.net/svnroot/stp-fast-prover/trunk/stp stp
    - $ cd stp
    - $ ./scripts/configure --with-prefix=path/to/stp/install --with-cryptominisat2
    - $ make OPTIMIZE=-O2 CFLAGS_M32= install -
    -
    4. - -As documented on the STP website, it is essential to run the following -command before using STP (and thus KLEE): -
    - $ ulimit -s unlimited -
    - - -
  4. [Optional] Build uclibc and the POSIX environment model: - -

    -By default, KLEE works on closed programs (programs that don't use any -external code such as C library functions). However, if you want to -use KLEE to run real programs you will want to enable the KLEE POSIX -runtime, which is built on top of the uClibc C library. -

    - -
      -
    1. Download KLEE's uClibc. KLEE uses a version - of uClibc which has been - modified slightly for our purposes. -
        -
      • A version that works on 32-bit Linux can be found - here -
        • -
      • A version that works on 64-bit Linux can be found - here -
        • -
      -
      2. - -
    2. Build uClibc with llvm-gcc: -
      - $ tar zxvf klee-uclibc-0.02.tgz
      - $ ./configure --with-llvm=path/to/llvm
      - $ make
      -
      - -

      NOTE: If you are on a different target (i.e., not i386 - or x64), you will need to run make config and select the - correct target. The defaults for the other uClibc configuration - variables should be fine.

      -

      3. - -
    - - -
  5. Checkout KLEE (to any path you like): -
    - $ svn co http://llvm.org/svn/llvm-project/klee/trunk klee -
    - Alternatively, if you prefer to use git there is also a - read-only git mirror, which syncs automatically with each - Subversion commit. You can do a git clone of KLEE via: -
    - $ git clone http://llvm.org/git/klee.git -
    -
    6. - -
  6. Configure KLEE: -

    From the KLEE source directory, run:

    -
    - $ ./configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime -
    - -

    NOTE: If you skipped step 4, simply remove the --with-uclibc and --enable-posix-runtime options.

    -
    7. - -
  7. Build KLEE: -
    - $ make ENABLE_OPTIMIZED=1 -
    -
    8. - -
  8. Run the regression suite to verify your build: -
    - $ make check
    - $ make unittests
    -
    -
    9. - -
  9. You're ready to go! Go to the Tutorials page - to try KLEE.
    10. -
- -

NOTE: If you are installing the system of Ubuntu 12.04 (or similar), you might want to take a look at this message.

-
- -
- - diff --git a/www/KQuery.html b/www/KQuery.html deleted file mode 100644 index a40f4435..00000000 --- a/www/KQuery.html +++ /dev/null @@ -1,620 +0,0 @@ - - - - - KLEE - KQuery Language Reference Manul - - - - - - - -
- -

KQuery Language Reference Manual

- -

Table Of Contents

-
    -
  1. Introduction
    2. -
  2. Notation
    3. -
  3. Structure
    4. -
      -
    1. Expression and Version Labels -
    -
  4. Literals -
      -
    1. Identifiers
      2. -
    2. Numbers
      3. -
    3. Types
      4. -
    -
    5. -
  5. Declarations -
      -
    1. Arrays
      2. -
    2. Query Commands
      3. -
    -
    6. -
  6. Versions
    7. -
  7. Expressions -
      -
    1. Primitive Expressions -
        -
      1. Expression References
        2. -
      2. Constants
        3. -
      -
      2. -
    2. Arithmetic Operations -
        -
      1. Add
        2. -
      2. Sub
        3. -
      3. Mul
        4. -
      4. UDiv
        5. -
      5. URem
        6. -
      6. SDiv
        7. -
      7. SRem
        8. -
      -
      3. -
    3. Bitwise Operations -
        -
      1. Not
        2. -
      2. And
        3. -
      3. Or
        4. -
      4. Xor
        5. -
      5. Shl
        6. -
      6. LShr
        7. -
      7. AShr
        8. -
      -
      4. -
    4. Comparisons -
        -
      1. Eq
        2. -
      2. Ne
        3. -
      3. Ult
        4. -
      4. Ule
        5. -
      5. Ugt
        6. -
      6. Uge
        7. -
      7. Slt
        8. -
      8. Sle
        9. -
      9. Sgt
        10. -
      10. Sge
        11. -
      -
      5. -
    5. Bitvector Manipulation -
        -
      1. Concat
        2. -
      2. Extract
        3. -
      3. ZExt
        4. -
      4. SExt
        5. -
      -
      6. -
    6. Special Expressions -
        -
      1. Read
        2. -
      2. Select
        3. -
      -
      7. -
    7. Macro Expressions -
        -
      1. Neg
        2. -
      2. ReadLSB
        3. -
      3. ReadMSB
        4. -
      -
      8. -
    -
    8. -
- -

Introduction

- -

The KQuery language is the textual representation of constraint - expressions and queries which is used as input to the Kleaver - constraint solver.

- -

Currently the language is capable of representing quantifier free - formulas over bitvectors and arrays, with direct support for all - standard operations on bitvectors. The language has been designed to - be compact and easy to read and write.

- -

The KQuery language is closely related to the C++ API for Exprs, see - also the - doxygen Expr - documentation.

- -

Notation

- -

In this document, syntax is given in Extended Backus-Naur Form and appears as:

-
- "(" "Eq" [ type ] LHS RHS ")" -
-

Unless noted, the rules are described in terms of tokens not characters, - and tokens can be separate by white space and comments.

- -

In some case, a production like child-expression is used as an alias - for the expression production, when subsequent text needs to - differentiate the expression.

- -

Examples are shown using:

-
- (Eq w32 a b) -
- -

Structure

- -

A KQuery source file consists of a sequence of declarations.

- -

Syntax:

-
- kquery = { array-declaration | query-command } -
- -

Currently, the language supports two kinds of declarations:

- - -

Comments begin with "#" and continue until the end of line. For example:

-
- (Add w32 1 1) # Two, hopefully -
- -

Expression and Version Labels

- -

Expressions are frequently shared among constraints and query - expressions. In order to keep the output succinct and readable, expression - labels can be used to introduce a lexical binding which can be used in - subsequent expressions. Expression labels are globally scoped through the - entire source file, and a definition must preceed any use in the source - file.

- -

Syntax:

-
- expression = identifier ":" expression
-
- -

Likewise, versions are frequently shared among reads and can be labelled in - the same fashion.

- -

Examples:

-
- (Add w32 N0:(Add w32 1 1) N0) # Four

- array const_array[] : w32 -> w8 = [5,6]
- (Read w8 0 U0:[0=255] @ const_array) # U0 now refers to an array [255,6]
- (Read w8 1 U0) # Read from byte offset 1 of [255,6]
-
- -

Literals

- -

Identifiers

- -

Identifiers are used for specifying array names and - for expression labels.

- -

Syntax:

-
- identifier = "[a-zA-Z_][a-zA-Z0-9._]*"
-
- -

Examples:

-
- _foo
- arr10_20
-
- -

Note that in order to keep open the possibility to introduce explicit - integral and floating-point types, the following identifiers are treated - as reserved keywords:

-
- floating-point-type = "fp[0-9]+([.].*)?"
- integer-type = "i[0-9]+"
-
- -

Numbers

- -

Numeric constants can be specified as follows.

- -

Syntax:

-
- number = "true" | "false" | signed-constant
- signed-constant = [ "+" | "-" ] ( dec-constant | bin-constant | oct-constant | hex-constant )
- dec-constant = "[0-9_]+"
- bin-constant = "0b[01_]+"
- oct-constant = "0o[0-7_]+"
- hex-constant = "0x[0-9a-fA-F_]+"
-
- -

Examples:

-
- false
- -10
- 0b1000_0001 # 129
-
- -

Non-decimal constants can be signed. The '_' character is ignored when - evaluating constants, but is available for use as a separator.

- -

Types

- -

Types are explicit operands to most expressions, and indicate the - bit-width of the type.

- -

Syntax:

-
- type = "w[0-9]+"
-
- -

Example:

-
- w32
-
- -

The numeric portion of the token is taken to be a decimal integer - specifying the bit-width of the type.

- -

Declarations

- -

Arrays

- -

Arrays are the basic type for defining symbolic variables (the - language does not currently support simple variables).

- -

Syntax:

-
- array-declaration = "array" name "[" [ size ] "]" ":" domain "->" range "=" array-initializer
- array-initializer = "symbolic" | "[" number-list "]"
- number-list = number | number "," number-list
-
- -

Arrays can be initialized to be either symbolic, or to have a given list of - constant values. For constant arrays, the initializer list must exactly match - the size of the array (if the size was unspecified, it will be the number of - constant values).

- -

Examples:

-
- array foo[10] : w32 -> w8 = symbolic # A ten element symbolic array
- array foo[] : w8 -> w1 = [ true, false, false, true ] # A constant array of four booleans
-
- -

Query Commands

- -

Query declarations describe the queries that the constraint solver - should run, along with optional additional arguments to specify - expressions and arrays for which counterexamples should be provided.

- -

Syntax:

-
- query-command = "(" "query" constraint-list query-expression [ eval-expr-list [ eval-array-list ] ] ")"
- query-expression = expression
- constraint-list = "[" { expression } "]"
- eval-expr-list = "[" { expression } "]"
- eval-array-list = "[" { identifier } "]"
-
- -

Examples:

-
- (query [] false)
- (query [(Eq w8 (Read w8 0 mem) 10)] false [] [ mem ])
-
- -

A query command consists a query, consisting of a constraint list and - a query expression, and two optional lists for use when a counterexample is desired.

- -

The constraint-list is a list of expressions (with boolean - type) which are assumed to hold. Although not required in the language, - many solvers require that this set of constraints be - consistent. The query-expression is the expression to determine - the validity of.

- -

If a counterexample is desired for invalid - queries, eval-expr-list is a list of expressions for which a - possible value should be constructed, and eval-array-list is a - list of arrays for which values for the entire array should be - provided. All counterexamples results must be simultaneously - feasible.

- -

Versions

- -

Versions are used to refer to an array with an ordered sequence of writes to it.

- -

Syntax:

-
- version = identifier | "[" [ update-list ] "]" "@" version
- update-list = lhs-expression "=" rhs-expression [ "," update-list ]
-
- -

Examples:

-
- array small_array[2] : w32 -> w8 = symbolic # The array we will read from
-
- (Read w8 0 thing) # No Updates to small_array
- (Read w8 1 [1=0xff] @ small_array) # Read from small_array at byte offset 1 with update where byte 1 set to decimal 255
-
-

A version can be specified either by an identifier, which can refer to an - array or a labelled version, or by an explicit list - of writes which are to be concatenated to another version (the most recent - writes are first).

- -

Expressions

- -

Expressions are strongly typed, and have the following general - form:

-
- "(" EXPR_NAME EXPR_TYPE ... arguments ... ")" -
-

where EXPR_NAME is the expression name, EXPR_TYPE is the - expression type (which may be optional), followed by any additional - arguments.

- -

Primitive Expressions

- -

Expression References

- -

An expression reference can be used to refer to a - previously labelled expression.

- -

Syntax:

-
- expression = identifier
-
- -

Expression and version labels are in separate namespaces, it is the users - responsibility to use separate labels to preserve readability.

- -

Constants

- -

Constants are specified by a numeric token or a type and numeric - token.

- -

Syntax:

-
- expression = number | "(" type number ")"
-
- -

When a constant is specified without a type, the resulting expression - is only well-formed if its type can be inferred from the enclosing - context. The true and false constants always have - type w1. - -

Examples:

-
- true
- (w32 0)
- (Add w32 10 20) # The type for 10 and 20 is inferred to be w32.
-
- -

Arithmetic Operations

- -

Add, - Sub, - Mul, - UDiv, SDiv, URem, SRem

- -

Syntax:

-
- arithmetic-expr-kind = ( "Add" | "Sub" | "Mul" | "UDiv" | "URem" | "SDiv" | "SRem" )
- expression = "(" arithmetic-expr-kind type expression expression ")"
-
- -

Arithmetic operations are always binary and the types of the left- - and right-hand side expressions must match the expression type.

- -

UDiv

-

Truncated unsigned division. Undefined if divisor is 0.

- -

URem

-

Unsigned remainder. Undefined if divisor is 0.

- -

SDiv

-

Signed division. Undefined if divisor is 0.

- -

SRem

-

Signed remainder. Undefined if divisor is 0. Sign of the - remainder is the same as that of the dividend.

- - -

Bitwise Operations

- -

Not

- -

Syntax:

-
- expression = "(" "Not" [ type ] expression ")" -
- -

Bitwise negation. The result is the bitwise negation (one's complement) of - the input expression. If the type is specified, it must match the expression - type.

- -

And, - Or, - Xor, - Shl, - LShr, - AShr

- -

Syntax:

-
- bitwise-expr-kind = ( "And" | "Or" | "Xor" | "Shl" | "LShr" | "AShr" )
- expression = "(" bitwise-expr-kind type expression expression ")"
-
- -

These bitwise operations are always binary and the types of the left- and - right-hand side expressions must match the expression type.

- -

Shl

- -
- expression = "(" "Shl" type X Y ")" -
- -

Logical shift left. Moves each bit of X to the left - by Y positions. The Y right-most bits of X are - replaced with zero, and the left-most bits discarded.

- -

LShr

- -
- expression = "(" "LShr" type X Y ")" -
- -

Logical shift right. Moves each bit of X to the right - by Y positions. The Y left-most bits of X are - replaced with zero, and the right-most bits discarded.

- - -

AShr

- -
- expression = "(" "AShr" type X Y ")" -
- -

Arithmetic shift right. Behaves as LShr except that the - left-most bits of X copy the initial left-most bit (the sign - bit) of X. - -

Comparisons

- -

Eq, - Ne, - Ult, - Ule, - Ugt, - Uge, - Slt, - Sle, - Sgt, - Sge

- -

Syntax:

-
- comparison-expr-kind = ( "Eq" | "Ne" | "Ult" | "Ule" | "Ugt" | "Uge" | "Slt" | "Sle" | "Sgt" | "Sge" )
- expression = "(" comparison-expr-kind [ type ] expression expression ")"
-
- -

Comparison operations are always binary and the types of the left- - and right-hand side expression must match. If the type is specified, it - must be w1.

- -

Bitvector Manipulation

- -

Concat

- -

Syntax:

-
- expression = "(" "Concat" [type] msb-expression lsb-expression ")" -
- -

Concat evaluates to a type bits formed by - concatenating lsb-expression to msb-expression.

- -

Extract

- -

Syntax:

-
- expression = "(" "Extract" type offset-number child-expression ")" -
- -

Extract evaluates to type bits from child-expression - taken from offset-number, where offset-number is the index of - the least-significant bit in child-expression which should be - extracted. - -

ZExt

- -

Syntax:

-
- expression = "(" "ZExt" type child-expression ")" -
- -

ZExt evaluates to the lowest type bits - of child-expression, with undefined bits set to zero.

- -

SExt

- -

Syntax:

-
- expression = "(" "SExt" type input-expression ")" -
- -

SExt evaluates to the lowest type bits - of child-expression, with undefined bits set to the most-significant - bit of input-expression.

- -

Special Expressions

- -

Read

- -

Syntax:

-
- expression = "(" "Read" type index-expression version ")"
-
- -

The Read expression evaluates to the first write - in version for which index-expression is equivalent to - the index in the write. The type of the expression must match the range of the - root array in version, and the type - of index-expression must match the domain.

- -

Select

- -

Syntax:

-
- expression = "(" "Select" type cond-expression true-expression false-expression ")"
-
- -

The Select expression evalues to true-expression if the - condition evaluates to true, and to false-expression if the condition - evaluates to false. The cond-expression must have type w1.

- -

Both the true and false expressions must be well-formed, regardless of the - condition expression. In particular, it is not legal for one of the - expressions to cause a division-by-zero during evaluation, even if - the Select expression will never evaluate to that expression.

- -

Macro Expressions

- -

Several common expressions are not implemented directly in the Expr - library, but can be expressed in terms of other operations. A number of these - are implemented as "macros". The pretty printer recognizes and prints the - appropriate Expr forms as the macro, and the parser recognizes them and turns - them into the underlying representation.

- -

Neg

- -

Syntax:

-
- expression = "(" "Neg" [ type ] expression ")" -
- -

This macro form can be used to generate a Sub from zero.

- -

ReadLSB, - ReadMSB

- -

Syntax:

-
- expression = "(" "ReadLSB" type index-expression version ")"
- expression = "(" "ReadMSB" type index-expression version ")"
-
- -

ReadLSB and ReadMSB can be used to simplify contiguous array - accesses. The type of the expression must be a multiple N of the array - range type. The expression expands to a concatenation of N read - expressions, where each read is done at a subsequent offset from - the index-expression. For ReadLSB (ReadMSB), the - concatentation is done such that the read at index-expression forms the - least- (most-) significant bits.

-
- - - diff --git a/www/OpenProjects.html b/www/OpenProjects.html deleted file mode 100644 index d4a01964..00000000 --- a/www/OpenProjects.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - KLEE - Open Projects - - - - - -
- -

KLEE Open Projects

- - - This page lists a variety of open projects that are natural (and tractable) - extensions of KLEE and things that we would love to see people work on. If - you are interested in tackling any of the projects, please mail - klee-dev - with your ideas -- or even better, your patches!. - - -
- - diff --git a/www/Publications.html b/www/Publications.html deleted file mode 100644 index 2a2dd313..00000000 --- a/www/Publications.html +++ /dev/null @@ -1,402 +0,0 @@ - - - - - - KLEE - Publications - - - - - -
- -

KLEE-related Publications and Systems

- - -

Below you can find a list of papers that use or extend KLEE. - Papers are listed in chronological order.
If you have used and - extended KLEE, please share your experience by having your paper - listed here (email klee-dev-owner or c.cadar AT imperial.ac.uk).

- -
    -
  1. - - - KLEE: Unassisted and Automatic Generation of High-Coverage Tests for - Complex Systems Programs - - -
    - Cristian Cadar, Daniel Dunbar, Dawson Engler -
    - USENIX Symposium on Operating Systems Design and Implementation (OSDI 2008) -
    - December 8-10, 2008, San Diego, CA, USA -

    -
    2. - -
  2. - - - Server-side Verification of Client Behavior in Online Games - - -
    - Darrell Bethea, Robert Cochran, Michael Reiter -
    - Network and Distributed System Security Symposium (NDSS 2010) -
    - February 28 - March 3, San Diego, CA, USA -

    -
    3. - -
  3. - - - KleeNet: Discovering Insidious Interaction Bugs in Wireless Sensor Networks Before Deployment - - -
    - Raimondas Sasnauskas, Olaf Landsiedel, Muhammad Hamad Alizai, - Carsten Weise, Stefan Kowalewski, Klaus Wehrle -
    - ACM/IEEE International Conference on Information Processing in Sensor Networks (IPSN 2010) -
    - April 12-16, 2010, Stockholm, Sweden -
    - KleeNet is available here. -

    -
    4. - -
  4. - - - Execution Synthesis: A Technique for Automated Software Debugging - - -
    - Cristian Zamfir, George Candea -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) -
    - April 13-16, 2010, Paris, France -

    -
    5. - -
  5. - - - Reverse Engineering of Binary Device Drivers with RevNIC - - -
    - Vitaly Chipounov, George Candea -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) -
    - April 13-16, 2010, Paris, France -

    -
    6. - -
  6. - - - Testing Closed-Source Binary Device Drivers with DDT - - -
    - Volodymyr Kuznetsov, Vitaly Chipounov, George Candea -
    - USENIX Annual Technical Conference (USENIX ATC 2010) -
    - June 22-25, 2010, Boston, MA, USA -

    -
    7. - -
  7. - - - Stable Deterministic Multithreading through Schedule Memoization - - -
    - Heming Cui, Jingyue Wu, Chia-che Tsai, Junfeng Yang -
    - USENIX Symposium on Operating Systems Design and Implementation (OSDI 2010) -
    - October 4-6, 2010, Vancouver, BC, Canada -

    -
    8. - -
  8. - - - AEG: Automatic Exploit Generation - - -
    - Thanassis Avgerinos, Sang Kil Cha, Brent Lim Tze Hao, David Brumley -
    - Network and Distributed System Security Symposium (NDSS 2011) -
    - February 6-9, 2011, San Diego, CA, USA -

    -
    9. - -
  9. - - - Howard: A Dynamic Excavator for Reverse Engineering Data Structures - - -
    - Asia Slowinska, Traian Stancescu, Herbert Bos -
    - Network and Distributed System Security Symposium (NDSS 2011) -
    - February 6-9, 2011, San Diego, CA, USA -

    -
    10. - -
  10. - - - S2E: A Platform for In Vivo Multi-Path Analysis of Software Systems - - -
    - Vitaly Chipounov, Volodymyr Kuznetsov, George Candea -
    - International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS 2011) -
    - March 5-11, 2011, Newport Beach, CA -
    - S2E is available here. -

    -
    11. - -
  11. - - - Parallel Symbolic Execution for Automated Real-World Software Testing - - -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) -
    - Stefan Bucur, Vlad Ureche, Cristian Zamfir, George Candea -
    - April 10-13, 2011, Salzburg, Austria -
    - Cloud9 is available here. -

    -
    12. - -
  12. - - - Symbolic Crosschecking of Floating-Point and SIMD Code - - -
    - Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) -
    - April 10-13, 2011, Salzburg, Austria -

    -
    13. - -
  13. - - - Practical, Low-Effort Equivalence Verification of Real Code - - -
    - David Ramos, Dawson Engler -
    - Computer Aided Verification (CAV 2011) -
    - July 16-20, 2011, Snowbird, UT, USA -

    -
    14. - -
  14. - - - Scalable Symbolic Execution of Distributed Systems - - -
    - Raimondas Sasnauskas, Oscar Soria Dustmann, Benjamin Lucien Kaminski, - Carsten Weise, Stefan Kowalewski, Klaus Wehrle -
    - IEEE International Conference on Distributed Computing Systems (ICDCS 2011) -
    - June 20-24, 2011, Minneapolis, MN, USA -

    -
    15. - -
  15. - - - Efficient Deterministic Multithreading through Schedule Relaxation - - -
    - Heming Cui, Jingyue Wu, John Gallagher, Huayang Guo, Junfeng Yang -
    - ACM Symposium on Operating Systems Principles (SOSP 2011) -
    - October 23-26, 2011, Cascais, Portugal -

    -
    16. - -
  16. - - - KLOVER: A Symbolic Execution and Automatic Test Generation Tool for C++ Programs - - -
    - Guodong Li, Indradeep Ghosh and Sreeranga Rajan -
    - International Conference on Computer Aided Verification (CAV 2011) -
    - July 14-20, 2011, Cliff Lodge, Snowbird, UT, USA -

    -
    17. - -
  17. - - - Symbolic Testing of OpenCL Code - - -
    - Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly -
    - Haifa Verification Conference (HVC 2011) -
    - December 6-8, 2011, Haifa, Israel -

    -
    18. - -
  18. - - - GKLEE: Concolic Verification and Test Generation for GPUs - - -
    - Guodong Li, Peng Li, Geof Sawaya, Ganesh Gopalakrishnan, Indradeep Ghosh, and Sreeranga P. Rajan -
    - ACM Symposium on Principles and Practice of Parallel Programming (PPoPP 2012) -
    - February 25-29, 2012, New Orleans, LA, USA -
    - GKLEE is available here. -

    -
    19. - -
  19. - - - make test-zesti: A Symbolic Execution Solution for Improving Regression Testing - - -
    - Paul Dan Marinescu, Cristian Cadar -
    - International Conference on Software Engineering (ICSE 2012) -
    - June 2-9, 2012, Zurich, Switzerland -
    - ZESTI is available here. -

    -
    20. - -
  20. - - - BugRedux: Reproducing Field Failures for In-House Debugging - - -
    - Wei Jin, Alessandro Orso -
    - International Conference on Software Engineering (ICSE 2012) -
    - June 2-9, 2012, Zurich, Switzerland -
    - BugRedux is available here. -

    -
    21. - -
  21. - - - Efficient State Merging in Symbolic Execution - - -
    - Volodymyr Kuznetsov, Johannes Kinder, Stefan Bucur, George Candea -
    - Programming Language Design and Implementation (PLDI) -
    - June 11-16, 2012, Beijing, China -

    -
    22. - -
  22. - - - High-Coverage Symbolic Patch Testing - - -
    - Paul Dan Marinescu, Cristian Cadar -
    - SPIN Workshop on Model Checking of Software (SPIN 2012) -
    - July 23-24, 2012, Oxford, UK -

    -
    23. - -
  23. - - - Automatic Detection of Floating-Point Exceptions - - -
    - Peter C. Rigby, Earl T. Barr, Christian Bird, Premkumar Devanbu, Daniel M. German -
    - Principles of Programming Languages (POPL) -
    - January 23-25, 2013, Rome, Italy -

    -
    24. - -
  24. - - - Redundant State Detection for Dynamic Symbolic Execution - - -
    - Suhabe Bugrara, Dawson Engler -
    - USENIX Annual Technical Conference (USENIX ATC 2013) -
    - June 26-28, 2013, San Jose, California. -

    -
    25. - -
-
- - diff --git a/www/TestingCoreutils.html b/www/TestingCoreutils.html deleted file mode 100644 index 7ae49302..00000000 --- a/www/TestingCoreutils.html +++ /dev/null @@ -1,893 +0,0 @@ - - - - - - KLEE - Coreutils Case Study - - - - - -
- -

Coreutils Case Study

- -

- As a more detailed explanation of using KLEE, we will look at how we did our - testing of GNU - Coreutils using KLEE. -

- -

This tutorial assumes that you have configured and built KLEE - with uclibc and POSIX runtime support. -

- -

These tests were done on a 32-bit Linux machine. On a 64-bit - machine, we needed to also set the LD_LIBRARY_PATH environment - variable: - 

-    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64 (Fedora)
-    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/x86_64-linux-gnu (Ubuntu)
-
-

- - - -

Step 1: Build coreutils with gcov

- -

- First you will need to download and unpack the source - for coreutils. In this - example we use version 6.11 (one version later than what was used for our - OSDI paper). -

- -

- Before we build with LLVM, let's build a version of coreutils - with gcov support. We will use this later to get coverage - information on the test cases produced by KLEE. -

- -

- From inside the coreutils directory, we'll do the usual - configure/make steps inside a subdirectory (obj-gcov). Here are the - steps: -

- -
- 
-coreutils-6.11$ mkdir obj-gcov
-coreutils-6.11$ cd obj-gcov
-obj-gcov$ ../configure --disable-nls CFLAGS="-g -fprofile-arcs -ftest-coverage"
-... verify that configure worked ...
-obj-gcov$ make
-obj-gcov$ make -C src arch hostname
-... verify that make worked ...
-
- -

- We build with --disable-nls because this adds a lot of extra - initialization in the C library which we are not interested in testing. Even - though these aren't the executables that KLEE will be running on, we want to - use the same compiler flags so that the test cases KLEE generates are most - likely to work correctly when run on the uninstrumented binaries. -

- -

- You should now have a set of coreutils in - the objc-gcov/src directory. For example: -

- -
- 
-obj-gcov$ cd src
-src$ ls -l ls echo cat
--rwxr-xr-x 1 ddunbar ddunbar 164841 2009-07-25 20:58 cat
--rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
--rwxr-xr-x 1 ddunbar ddunbar 439712 2009-07-25 20:58 ls
-src$ ./cat --version
-cat (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by Torbjorn Granlund and Richard M. Stallman.
-
- -

- In addition, these executables should be built with gcov support, - so if you run one it will write a .gcda into the current - directory. That file contains information about exactly what code was - executed when the program ran. See - the Gcov - Documentation for more information. We can use the gcov tool - itself to produce a human readable form of the coverage information. For - example: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ ./echo
-
-src$ ls -l echo.gcda
--rw-r--r-- 1 ddunbar ddunbar 1832 2009-08-04 21:14 echo.gcda
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:0.00% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:18.81% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- By default gcov will show the number of lines executed in the - program (the .h files include code which was compiled - into echo.c). -

- - - -

Step 2: Build coreutils with LLVM

- -

- One of the difficult parts of testing real software using KLEE is that it - must be first compiled so that the final program is an LLVM bitcode file and - not a linked executable. The software's build system may be set up to use - tools such as 'ar', 'libtool', and 'ld', which do not in general understand - LLVM bitcode files. -

- -

- It depends on the actual project what the best way to do this is. For - coreutils, we use a helper script klee-gcc, which acts - like llvm-gcc but adds additional arguments to cause it to emit - LLVM bitcode files and to call llvm-ld to link executables. This - is not a general solution, and your mileage may vary. -

- - - -

- As before, we will build in a separate directory so we can easily access - both the native executables and the LLVM versions. Here are the steps: -

- -
- 
-coreutils-6.11$ mkdir obj-llvm
-coreutils-6.11$ cd obj-llvm
-obj-llvm$ ../configure --disable-nls CFLAGS="-g"
-... verify that configure worked ...
-obj-llvm$ make CC=/full/path/to/klee/scripts/klee-gcc
-obj-llvm$ make -C src arch hostname CC=/full/path/to/klee/scripts/klee-gcc
-... verify that make worked ...
-
- -

- Notice that we made two changes. First, we don't want to add gcov - instrumentation in the binary we are going to test using KLEE, so we left of - the -fprofile-arcs -ftest-coverage flags. Second, when running - make, we set the CC variable to point to our klee-gcc - wrapper script. -

- -

- If all went well, you should now have LLVM bitcode versions of coreutils! For - example: -

- -
- 
-obj-llvm$ cd src
-src$ ls -l ls echo cat
--rwxr-xr-x 1 ddunbar ddunbar 65 2009-07-25 23:40 cat
--rwxr-xr-x 1 ddunbar ddunbar 66 2009-07-25 23:43 echo
--rwxr-xr-x 1 ddunbar ddunbar 94 2009-07-25 23:38 ls
-src$ ./cat --version
-cat (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-LLVM ERROR: JIT does not support inline asm!
-
- -

- You may notice some funny things going on. To start with, the files are way - too small! Since we are actually producing LLVM bitcode files, the operating - system can't run them directly. What llvm-ld does to make it so we - can still run the resulting outputs is write a little shell script which - uses the LLVM interpreter to run the binaries; the actual LLVM bitcode - files have .bc appended. If we look a little closer: -

- -
- 
-src$ cat ls
-#!/bin/sh
-lli=${LLVMINTERP-lli}
-exec $lli \
-    -load=/usr/lib/librt.so \
-    ls.bc ${1+"$@"}
-src$ ls -l ls.bc
--rwxr-xr-x 1 ddunbar ddunbar 643640 2009-07-25 23:38 ls.bc
-
- -

- The other funny thing is that the version message doesn't all print out, the - LLVM interpreter emits a message about not supporting inline assembly. The - problem here is that glibc occasionally implements certain - operations using inline assembly, which the LLVM interpreter (lli) - doesn't understand. KLEE works around this problem by specially recognizing - certain common inline assembly sequences and turning them back into the - appropriate LLVM instructions before executing the binary. -

- - - -

Step 3: Using KLEE as an interpreter

- -

- At its core, KLEE is just an interpreter for LLVM bitcode. For example, here - is how to run the same cat command we did before, using KLEE. Note, - this step requires that you configured and built KLEE with uclibc - and POSIX runtime support (if you didn't, you'll need to go do that - now). -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./cat.bc --version
-KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
-KLEE: output directory = "klee-out-3"
-KLEE: WARNING: undefined reference to function: __signbitl
-KLEE: WARNING: executable has module level assembly (ignoring)
-KLEE: WARNING: calling external: syscall(54, 0, 21505, 177325672)
-KLEE: WARNING: calling __user_main with extra arguments.
-KLEE: WARNING: calling external: getpagesize()
-KLEE: WARNING: calling external: vprintf(177640072, 183340048)
-cat (GNU coreutils) 6.11
-
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by Torbjorn Granlund and Richard M. Stallman.
-KLEE: WARNING: calling close_stdout with extra arguments.
-Copyright (C) 2008 Free Software Foundation, Inc.
-KLEE: done: total instructions = 259357
-KLEE: done: completed paths = 1
-KLEE: done: generated tests = 1
-
- -

- We got a lot more output this time! Let's step through it, starting with the - KLEE command itself. The general form of a KLEE command line is first the - arguments for KLEE itself, then the LLVM bitcode file to execute - (cat.bc), and then any arguments to pass to the application - (--version in this case, as before). -

- -

- If we were running a normal native application, it would have been linked - with the C library, but in this case KLEE is running the LLVM bitcode file - directly. In order for KLEE to work effectively, it needs to have - definitions for all the external functions the program may call. We have - modified the uClibc C library - implementation for use with KLEE; the --libc=uclibc KLEE argument - tells KLEE to load that library and link it with the application before it - starts execution. -

- -

- Similarly, a native application would be running on top of an operating - system that provides lower level facilities like write(), which the - C library uses in its implementation. As before, KLEE needs definitions for - these functions in order to fully understand the program. We provide a POSIX - runtime which is designed to work with KLEE and the uClibc library to - provide the majority of operating system facilities used by command line - applications -- the --posix-runtime argument tells KLEE to link - this library in as well. -

- -

- As before, cat prints out its version information (note that this - time all the text is written out), but we now have a number of additional - information output by KLEE. In this case, most of these warnings are - innocuous, but for completeness here is what they mean: -

- - - -

- In general, KLEE will only emit a given warning once. The warnings are also - logged to warnings.txt in the KLEE output directory. -

- - - -

Step 4: Introducing symbolic data to an application

- -

- We've seen that KLEE can interpret a program normally, but the real purpose - of KLEE is to explore programs more exhaustively by making parts of their - input symbolic. For example, lets look at running KLEE on the echo - application. -

- -

- When using uClibc and the POSIX runtime, KLEE replaces the - program's main() function with a special function - (klee_init_env) provided inside the runtime library. This - function alters the normal command line processing of the - application, in particular to support construction of symbolic - arguments. For example, passing --help yields: -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./echo.bc --help
-...
-
-usage: (klee_init_env) [options] [program arguments]
-  -sym-arg               - Replace by a symbolic argument with length N
-  -sym-args    - Replace by at least MIN arguments and at most
-                              MAX arguments, each with maximum length N
-  -sym-files        - Make stdin and up to NUM symbolic files, each
-                              with maximum size N.
-  -sym-stdout               - Make stdout symbolic.
-  -max-fail              - Allow up to  injected failures
-  -fd-fail                  - Shortcut for '-max-fail 1'
-...
-
- -

- As an example, lets run echo with a symbolic argument of 3 - characters. -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
-KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
-KLEE: output directory = "klee-out-16"
-KLEE: WARNING: undefined reference to function: __signbitl
-KLEE: WARNING: executable has module level assembly (ignoring)
-KLEE: WARNING: calling external: syscall(54, 0, 21505, 189414856)
-KLEE: WARNING: calling __user_main with extra arguments.
-..
-KLEE: WARNING: calling close_stdout with extra arguments.
-...
-KLEE: WARNING: calling external: printf(183664896, 183580400)
-Usage: ./echo.bc [OPTION]... [STRING]...
-Echo the STRING(s) to standard output.
-
-  -n             do not output the trailing newline
-  -e             enable interpretation of backslash escapes
-  -E             disable interpretation of backslash escapes (default)
-      --help     display this help and exit
-      --version  output version information and exit
-
-If -e is in effect, the following sequences are recognized:
-
-  \0NNN   the character whose ASCII code is NNN (octal)
-  \\     backslash
-  \a     alert (BEL)
-  \b     backspace
-  \c     suppress trailing newline
-  \f     form feed
-  \n     new line
-  \r     carriage return
-  \t     horizontal tab
-  \v     vertical tab
-
-NOTE: your shell may have its own version of echo, which usually supersedes
-the version described here.  Please refer to your shell's documentation
-for details about the options it supports.
-
-Report bugs to .
-KLEE: WARNING: calling external: vprintf(183956664, 190534360)
-echo (GNU coreutils) 6.11
-
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by FIXME unknown.
-...
-...
-...
-
-
-
-
-..
-
-
-.
-
-.
-..
-...
-Copyright (C) 2008 Free Software Foundation, Inc.
-KLEE: done: total instructions = 300193
-KLEE: done: completed paths = 25
-KLEE: done: generated tests = 25
-
- -

- The results here are slightly more interesting, KLEE has explored 25 paths - through the program. The output from all the paths is intermingled, but you - can see that in addition to echoing various random characters, some blocks - of text also were output. You may be suprised to learn that - coreutils' echo takes some arguments, in this case the - options --v (short for --version) and --h (short - for --help) were explored. We can get a short summary of KLEE's - internal statistics by running klee-stats on the output directory - (remember, KLEE always makes a symlink called klee-last to the most - recent output directory). -

- -
- 
-src$ klee-stats klee-last
--------------------------------------------------------------------------
-| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
--------------------------------------------------------------------------
-| klee-last | 300673 |    1.47 |   28.18 |   17.37 |  28635 |      5.65 |
--------------------------------------------------------------------------
-
- -

- Here ICov is the percentage of LLVM instructions which were - covered, and BCov is the percentage of branches that were - covered. You may be wondering why the percentages are so low -- how much - more code can echo have! The main reason is that these numbers are computed - using all the instructions or branches in the bitcode files; that includes a - lot of library code which may not even be executable. We can help with that - problem (and others) by passing the --optimize option to KLEE. This - will cause KLEE to run the LLVM optimization passes on the bitcode module - before executing it; in particular they will remove any dead code. When - working with non-trivial applications, it is almost always a good idea to - use this flag. Here are the results from running again - with --optimze enabled: -

- -
- 
-src$ klee --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
-...
-KLEE: done: total instructions = 123251
-KLEE: done: completed paths = 25
-KLEE: done: generated tests = 25
-src$ klee-stats klee-last
--------------------------------------------------------------------------
-| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
--------------------------------------------------------------------------
-| klee-last | 123251 |    0.32 |   38.02 |   25.43 |   9531 |     29.66 |
--------------------------------------------------------------------------
-
- -

- This time the instruction coverage went up by about ten percent, and you can - see that KLEE also ran faster and executed less instructions. Most of the - remaining code is still in library functions, just in places that the - optimizers aren't smart enough to remove. We can verify this -- and look for - uncovered code inside echo -- by using KCachegrind to visualize the - results of a KLEE run. -

- - - -

Step 5: Visualizing KLEE's progress with kcachegrind

- -

- KCachegrind is an excellent - profiling visualization tool, originally written for use with the callgrind - plugin for valgrind. If you don't have it already, it is usually easily - available on a modern Linux distribution via your platforms' software - installation tool (e.g., apt-get or yum). -

- -

- KLEE by default writes out a run.istats file into the test output - directory which is actually a KCachegrind file. In this example, - the run.istats is from a run without --optimize, so the - results are easier to understand. Assuming you have KCachegrind installed, - just run: -

- -
- 
 src$ kcachegrind klee-last/run.istats
-
- -

- After KCachegrind opens, you should see a window that looks something like - the one below. You should make sure that the "Instructions" statistic is - selected by choosing "View" > "Primary Event Type" > "Instructions" - from the menu, and make sure the "Source Code" view is selected (the right - hand pane in the screenshot below). -

- - - - -

- KCachegrind is a complex application in itself, and interested users should - see the KCachegrind website for more information and documentation. However, - the basics are that the one pane shows the "Flat Profile"; this is a list of - which how many instructions were executed in each function. The "Self" - column is the number of instructions which were executed in the function - itself, and the "Incl" (inclusive) column is the number of instructions - which were executed in the function, or any of the functions it called (or - its callees called, and so on). -

- -

- KLEE includes quite a few statistics about execution. The one we are - interested in now is "Uncovered Instructions", which will show which - functions have instructions which were never executed. If you select that - statistic and resort the list of functions, you should see something like - this: -

- - - - -

- Notice that most of the uncovered instructions are in library code as we - would expect. However, if we select the __user_main function, we - can look for code inside echo itself that was uncovered. In this - case, most of the uncovered instructions are inside a large if - statement guarded by the variable do_v9. If you look a bit more, - you can see that this is a flag set to true when -e is passed. The - reason that KLEE never explored this code is because we only passed one - symbolic argument -- hitting this code requires a command line like $ - echo -e \a. -

- -

- One subtle thing to understand if you are trying to actually make sense of - the KCachegrind numbers is that they include events accumulated across all - states. For example, consider the following code: -

- -
- 
-Line 1:      a = 1;
-Line 2:      if (...)
-Line 3:        printf("hello\n");
-Line 4:      b = c;
-
- -

- In a normal application, if the statement on Line 1 was only executed once, - then the statement on Line 4 could be (at most) executed once. When KLEE is - running an application, however, it could fork and generate separate - processes at Line 2. In that case, Line 4 may be executed more times than - Line 1! -

- -

- Another useful tidbit: KLEE actually writes the run.istats file - periodically as the application is running. This provides one way to monitor - the status of long running applications (another way is to use the - klee-stats tool). -

- - - -

Step 6: Replaying KLEE generated test cases

- -

- Let's step away from KLEE for a bit and look at just the test cases KLEE - generated. If we look inside the klee-last we should see - 25 .ktest files. -

- -
- 
-src$ ls klee-last
-assembly.ll	  test000004.ktest  test000012.ktest  test000020.ktest
-info		  test000005.ktest  test000013.ktest  test000021.ktest
-messages.txt	  test000006.ktest  test000014.ktest  test000022.ktest
-run.istats	  test000007.ktest  test000015.ktest  test000023.ktest
-run.stats	  test000008.ktest  test000016.ktest  test000024.ktest
-test000001.ktest  test000009.ktest  test000017.ktest  test000025.ktest
-test000002.ktest  test000010.ktest  test000018.ktest  warnings.txt
-test000003.ktest  test000011.ktest  test000019.ktest
-
- -

- These files contain the actual values to use for the symbolic data in order - to reproduce the path that KLEE followed (either for obtaining code - coverage, or for reproducing a bug). They also contain additional metadata - generated by the POSIX runtime in order to track what the values correspond - to and the version of the runtime. We can look at the individual contents of - one file using ktest-tool: -

- -
- 
-$ ktest-tool klee-last/test000001.ktest
-ktest file : 'klee-last/test000001.ktest'
-args       : ['./echo.bc', '--sym-arg', '3']
-num objects: 2
-object    0: name: 'arg0'
-object    0: size: 4
-object    0: data: '@@@\x00'
-object    1: name: 'model_version'
-object    1: size: 4
-object    1: data: '\x01\x00\x00\x00'
-
- -

- In this case, the test case indicates that values "@@@\x00" should be passed - as the first argument. However, .ktest files generally aren't - really meant to be looked at directly. For the POSIX runtime, we provide a - tool klee-replay which can be used to read the .ktest file - and invoke the native application, automatically passing it the data - necessary to reproduce the path that KLEE followed. -

- -

- To see how it works, go back to the directory where we built the native - executables: -

- -
- 
-src$ cd ..
-obj-llvm$ cd ..
-coreutils-6.11$ cd obj-gcov
-obj-gcov$ cd src
-src$ ls -l echo
--rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
-
- -

- To use the klee-replay tool, we just tell it the executable to run - and the .ktest file to use. The program arguments, input files, - etc. will all be constructed from the data in the .ktest file. -

- -
- 
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/test000001.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" "@@@" 
-@@@
-klee-replay: EXIT STATUS: NORMAL (0 seconds)
-
- -

- The first two and last lines here come from the klee-replay tool - itself. The first two lines list the test case being run, and the concrete - values for arguments that are being passed to the application (notice this - matches what we saw in the .ktest file earlier). The last line is - the exit status of the program and the elapsed time to run. -

- -

- We can also use the klee-replay tool to run a set of test cases at - once, one after the other. Let's do this and compare the gcov - coverage to the numbers we got from klee-stats: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" "@@@" 
-@@@
-klee-replay: EXIT STATUS: NORMAL (0 seconds)
-...
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000022.ktest
-klee-replay: ARGS: "./echo" "--v" 
-echo (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-...
-
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:6.38% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:50.50% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- The number for echo.c here significantly higher than - the klee-stats number because gcov is only considering - lines in that one file, not the entire application. As with kcachegrind, we can inspect the coverage file output by gcov to see exactly what lines were covered and which weren't. Here is a fragment from the output: -

- -
- 
-        -:  193:      }
-        -:  194:
-       23:  195:just_echo:
-        -:  196:
-       23:  197:  if (do_v9)
-        -:  198:    {
-       10:  199:      while (argc > 0)
-        -:  200:	{
-    #####:  201:	  char const *s = argv[0];
-        -:  202:	  unsigned char c;
-        -:  203:
-    #####:  204:	  while ((c = *s++))
-        -:  205:	    {
-    #####:  206:	      if (c == '\\' && *s)
-        -:  207:		{
-    #####:  208:		  switch (c = *s++)
-        -:  209:		    {
-    #####:  210:		    case 'a': c = '\a'; break;
-    #####:  211:		    case 'b': c = '\b'; break;
-    #####:  212:		    case 'c': exit (EXIT_SUCCESS);
-    #####:  213:		    case 'f': c = '\f'; break;
-    #####:  214:		    case 'n': c = '\n'; break;
-
- -

- The far left hand column is the number of times each line was - executed; - means the line has no executable code, and ##### - means the line was never covered. As you can see, the uncovered lines here - correspond exactly to the uncovered lines as reported - in kcachegrind. -

- -

- Before moving on to testing more complex applications, lets make sure we can - get decent coverage of the simple echo.c. The problem before was - that we weren't making enough data symbolic, providing echo with two - symbolic arguments should be plenty to cover the entire program. We can use - the POSIX runtime --sym-args option to pass multiple options. Here - are the steps, after switching back to the obj-llvm/src directory: -

- -
- 
-src$ klee --only-output-states-covering-new --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-args 0 2 4
- ... 
-KLEE: done: total instructions = 7437521
-KLEE: done: completed paths = 9963
-KLEE: done: generated tests = 55
-
- -

- The format of the --sym-args option actually specifies a minimum - and a maximum number of arguments to pass and the length to use for each - argument. In this case --sym-args 0 2 4 says to pass between 0 and - 2 arguments (inclusive), each with a maximum length of four characters. -

- -

- We also added the --only-output-states-covering-new option to the - KLEE command line. By default KLEE will write out test cases for every path - it explores. This becomes less useful once the program becomes larger, because many test cases will end up - exercise the same paths, and computing (or even reexecuting) each one wastes - time. Using this option tells KLEE to only output test cases for paths which - covered some new instruction in the code (or hit an error). The final lines - of the output show that even though KLEE explored almost ten thousand paths - through the code, it only needed to write 55 test cases. -

- -

- If we go back to the obj-gcov/src directory and rerun the latest - set of test cases, we finally have reasonable coverage of echo.c: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" 
-
- ... 
-
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:6.38% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:97.03% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- The reasons for not getting perfect 100% line coverage are left as an - exercise to the reader. :) -

- - - -

Step 7: Using zcov to analyze coverage

- -

- For visualizing the coverage results, you might want to use the zcov tool. -

-
- -
- - diff --git a/www/Tutorial-1.html b/www/Tutorial-1.html deleted file mode 100644 index 38c3b101..00000000 --- a/www/Tutorial-1.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - - - KLEE - Tutorial One - - - - - -
- -

Tutorial One: Testing a Small Function

- - -

The demo code

- - This tutorial walks you through the main steps needed to test a - simple function with KLEE. Here is our simple function: - - 
-  int get_sign(int x) {
-    if (x == 0)
-       return 0;
-
-    if (x < 0)
-       return -1;
-    else 
-       return 1;
-  }
- - You can find the entire code for this example in the source tree - under examples/get_sign. A version of the source code can - also be accessed here. - -

Marking input as symbolic

- - In order to test this function with KLEE, we need to run it - on symbolic input. To mark a variable as symbolic, we use - the klee_make_symbolic() function, which takes three - arguments: the address of the variable (memory location) that we - want to treat as symbolic, its size, and a name (which can be - anything). Here is a simple main() function that marks a - variable a as symbolic and uses it to - call get_sign(): - - 
-  int main() {
-      int a;
-      klee_make_symbolic(&a, sizeof(a), "a");
-      return get_sign(a);
-  }
- - - -

Compiling to LLVM bitcode

- - KLEE operates on LLVM bitcode. To run a program with KLEE, you - first compile it to LLVM bitcode using llvm-gcc - --emit-llvm. Assuming our code is stored in get_sign.c, - we run: - -
- llvm-gcc --emit-llvm -c -g get_sign.c -
- - to generate the LLVM bitcode file get_sign.o. - - It is useful to (1) build with -g to add debug information - to the bitcode file, which we use to generate source line level - statistics information, and (2) not use any optimization flags. The - code can be optimized later, as KLEE provides the - --optimize command line option to run the optimizer - internally. - -

Running KLEE

- - To run KLEE on the bitcode file simply execute: - -
- klee get_sign.o -
- - You should see the following output (assumes LLVM 2.8): - 
-  KLEE: output directory = "klee-out-0"
-
-  KLEE: done: total instructions = 51
-  KLEE: done: completed paths = 3
-  KLEE: done: generated tests = 3
- - There are three paths through our simple function, one - where a is 0, one where it is less than 0 - and one where it is greater than 0. - - As expected, KLEE informs us that it explored three paths in the - program and generated one test case for each path explored. The - output of a KLEE execution is a directory (in our - case klee-out-0) containing the test cases generated by - KLEE. KLEE names the output directory klee-out-N where N - is the lowest available number (so if we run KLEE again it will - create a directory called klee-out-1), and also generates a - symbolic link called klee-last to this directory for - convenience: - - 
-  $ ls klee-last/
-  assembly.ll      run.istats       test000002.ktest
-  info             run.stats        test000003.ktest
-  messages.txt     test000001.ktest warnings.txt
- - Please click here if you would like an - overview of the files generated by KLEE. In this tutorial, we only - focus on the actual test files generated by KLEE. - -

KLEE-generated test cases

The test cases generated by KLEE - are written in files with extension .ktest. These are - binary files, which can be read with the ktest-tool - utility. So let's examine each file: - - 
-  $ ktest-tool --write-ints klee-last/test000001.ktest 
-  ktest file : 'klee-last/test000001.ktest'
-  args       : ['get_sign.o']
-  num objects: 1
-  object    0: name: 'a'
-  object    0: size: 4
-  object    0: data: 1
-  
-  $ ktest-tool --write-ints klee-last/test000002.ktest  
-  ...
-  object    0: data: -2147483648
-
-  $ ktest-tool --write-ints klee-last/test000003.ktest 
-  ...
-  object    0: data: 0
- - In each test file, KLEE reports the arguments with which the program - was invoked (in our case no arguments other than the program name - itself), the number of symbolic objects on that path (only one in - our case), the name of our symbolic object ('a') and its size (4). - The actual test itself is represented by the value of our - input: 1 for the first test, -2147483648 for the - second and 0 for the last one. As expected, KLEE generated - value 0, one negative value (-2147483648), and one - positive value (1). We can now run these values on a - native version of our program, to exercise all paths through the - code! - - -

Replaying a test case

- - While we can run the test cases generated by KLEE on our program by - hand, (or with the help of an existing test infrastructure), KLEE - provides a convenient replay library, which simply replaces - the call to klee_make_symbolic with a call to a function - that assigns to our input the value stored in the .ktest - file. - - To use it, simply link your program with the libkleeRuntest - library and set the KTEST_FILE environment variable to - point to the name of the desired test case: - - 
-  $ export LD_LIBRARY_PATH=path-to-klee-root/Release+Asserts/lib/:$LD_LIBRARY_PATH
-  $ gcc -L path-to-klee-root/Release+Asserts/lib/ get_sign.c -lkleeRuntest
-  $ KTEST_FILE=klee-last/test000001.ktest ./a.out 
-  $ echo $?
-  1
-  $ KTEST_FILE=klee-last/test000002.ktest ./a.out 
-  $ echo $?
-  255
-  $ KTEST_FILE=klee-last/test000003.ktest ./a.out
-  $ echo $?
-  0
- - As expected, our program returns 1 when running the first test case, - 255 (-1 converted to a valid exit code value in the 0-255 range) - when running the second one, and 0 when running the last one. - -

- -
- - diff --git a/www/Tutorial-2.html b/www/Tutorial-2.html deleted file mode 100644 index 47187a45..00000000 --- a/www/Tutorial-2.html +++ /dev/null @@ -1,287 +0,0 @@ - - - - - KLEE - Tutorial Two - - - - - - - -
- -

Tutorial Two: Testing a Simple Regular Expression Library

- -

This is an example of using KLEE to test a simple regular expression matching -function. You can find the basic example in the source tree -under examples/regexp.

- -

Regexp.c contains a simple regular expression matching function, and -the bare bones testing harness (in main) needed to explore this code -with klee. You can see a version of the source -code here.

- -

This example will show to build and run the example using KLEE, as well as -how to interpret the output, and some additional KLEE features that can be used -when writing a test driver by hand.

- -

We'll start by showing how to build and run the example, and then explain how -the test harness works in more detail.

- -

Building the example

- -

The first step is to compile the source code using a compiler which can -generate object files in LLVM bitcode format. Here we use llvm-gcc, -but Clang works just as well!

- -

From within the examples/regexp directory: -

- $ llvm-gcc -I ../../include -emit-llvm -c -g Regexp.c -
-which should create a Regexp.o file in LLVM bitcode -format. The -I argument is used so that the compiler can -find "klee/klee.h", -which contains definitions for the intrinsic functions used to interact with the -KLEE virtual machine. -c is used because we only want to compile the -code to an object file (not a native executable), and finally -g causes -additional debug information to be stored in the object file, which KLEE will -use to determine source line number information.

- -

If you have the LLVM tools installed in your path, you can verify that this step -worked by running llvm-nm on the generated file:

-
-
-  $ llvm-nm Regexp.o
-         t matchstar
-         t matchhere
-         T match
-         T main
-         U klee_make_symbolic_name
-         d LC
-         d LC1
-
-
- -

Normally before running this program we would need to link it to create a -native executable. However, KLEE runs directly on LLVM bitcode files -- since -this program only has a single file there is no need to link. For "real" -programs with multiple inputs, -the llvm-link -and llvm-ld tools can -be used in place of the regular link step to merge multiple LLVM bitcode files -into a single module which can be executed by KLEE.

- -

Executing the code with KLEE

- - -

The next step is to execute the code with KLEE:

-
-
-$ klee --only-output-states-covering-new Regexp.o
-KLEE: output directory = "klee-out-1"
-KLEE: ERROR: .../klee/examples/regexp/Regexp.c:23: memory error: out of bound pointer
-KLEE: NOTE: now ignoring this error at this location
-KLEE: ERROR: .../klee/examples/regexp/Regexp.c:25: memory error: out of bound pointer
-KLEE: NOTE: now ignoring this error at this location
-KLEE: done: total instructions = 6334861
-KLEE: done: completed paths = 7692
-KLEE: done: generated tests = 22
-
-
- -

On startup, KLEE prints the directory used to store output (in this -case klee-out-1). By default klee will use the first -free klee-out-N directory and also create a klee-last -symlink which will point to the most recent created directory. You can specify a -directory to use for outputs using the -output-dir=path -command line argument.

- -

While KLEE is running, it will print status messages for "important" events, -for example when it finds an error in the program. In this case, KLEE detected -to invalid memory accesses on lines 23 and 25 of our test program. We'll look -more at this in a moment.

- -

Finally, when KLEE finishes execution it prints out a few statistics about -the run. Here we see that KLEE executed a total of ~6 million instructions, -explored 7,692 paths, and generated 22 test cases.

- -

Note that many realistic programs have an infinite (or extremely large) -number of paths through them, and it is common that KLEE will not terminate. By -default KLEE will run until the user presses Control-C (i.e. klee gets -a SIGINT), but there are additional options to limit KLEE's runtime and memory -usage:

-

-

- -

KLEE error reports

- -

When KLEE detects an error in the program being executed it will generate a -test case which exhibits the error, and write some additional information about -the error into a file testN.TYPE.err, where N is -the test case number, and TYPE identifies the kind of error. Some -types of errors KLEE detects include:

- - - -

KLEE will print a message to the console when it detects an error, in the -test run above we can see that KLEE detected two memory errors. For all program -errors, KLEE will write a simple backtrace into the .err file. This is -what one of the errors above looks like:

-
-
-Error: memory error: out of bound pointer
-File: .../klee/examples/regexp/Regexp.c
-Line: 23
-Stack: 
-	#0 00000146 in matchhere (re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:23
-	#1 00000074 in matchstar (c, re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#2 00000172 in matchhere (re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#3 00000074 in matchstar (c, re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#4 00000172 in matchhere (re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#5 00000074 in matchstar (c, re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#6 00000172 in matchhere (re=14816465, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#7 00000231 in matchhere (re=14816464, text=14815300) at .../klee/examples/regexp/Regexp.c:30
-	#8 00000280 in match (re=14816464, text=14815296) at .../klee/examples/regexp/Regexp.c:38
-	#9 00000327 in main () at .../klee/examples/regexp/Regexp.c:59
-Info: 
-	address: 14816471
-	next: object at 14816624 of size 4
-	prev: object at 14816464 of size 7
-
-
- -

Each line of the backtrace lists the frame number, the instruction line (this -is the line number in the assembly.ll file found along with the run -output), the function and arguments (including values for the concrete -parameters), and the source information.

- -

Particular error reports may also include additional information. For memory -errors, KLEE will show the invalid address, and what objects are on the heap -both before and after that address. In this case, we can see that the address -happens to be exactly one byte past the end of the previous object.

- -

Changing the test harness

- -

The reason KLEE is finding memory errors in this program isn't because the -regular expression functions have a bug, rather it indicates a problem in our -test driver. The problem is that we are making the input regular expression -buffer completely symbolic, but the match function expects it to be a -null terminated string. Let's look at two ways we can fix this.

- -

The simplest way to fix this problem is to store '\0' at the end of -the buffer, after making it symbolic. This makes our driver look like this:

-
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic(re, sizeof re, "re");
-  re[SIZE - 1] = '\0';
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-

Making a buffer symbolic just initializes the contents to refer to symbolic -variables, we are still free to modify the memory as we wish. If you recompile -and run klee on this test program, the memory errors should now be -gone.

- -

Another way to accomplish the same effect is to use the klee_assume -intrinsic function. klee_assume takes a single argument (an unsigned -integer) which generally should some kind of conditional expression, and -"assumes" that expression to be true on the current path (if that can never -happen, i.e. the expression is provably false, KLEE will report an error). - -

We can use klee_assume to cause KLEE to only explore states where -the string is null terminated by writing the driver like this:

-
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic(re, sizeof re, "re");
-  klee_assume(re[SIZE - 1] == '\0');
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-

In this particular example, both solutions work fine, but in -general klee_assume is more flexible:

- - -

NOTE: One important caveat when using klee_assume with -multiple conditions; remember that boolean conditionals like '&&' and '||' may -be compiled into code which branches before computing the result of the -expression. In such situations KLEE will branch the process *before* it reaches -the call to klee_assume, which may result in exploring unnecessary -additional states. For this reason it is good to use as simple expressions as -possible to klee_assume (for example splitting a single call into -multiple ones), and to use the '&' and '|' operators instead of the -short-circuiting ones.

- - - -
- - diff --git a/www/Tutorials.html b/www/Tutorials.html deleted file mode 100644 index e063a9a8..00000000 --- a/www/Tutorials.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - KLEE - Tutorials - - - - - -
- -

KLEE Tutorials

- - -
    -
  1. Tutorial One: Testing a small function.
    2. - -
  2. Tutorial Two: Testing a simple regular - expression library.
    3. - -
  3. - Solving a maze with KLEE: A nice explanation of how symbolic - execution can be used to generate interesting program - inputs. The example shows how to use KLEE to find all the - solutions to a maze game. -
    4. - -
  4. Testing Coreutils: In-depth - description of how to use KLEE to test GNU Coreutils.
    5. -
- - -
- - diff --git a/www/bugs.html b/www/bugs.html deleted file mode 100644 index 1ac9421a..00000000 --- a/www/bugs.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Bug Reports

- - - Please report any bugs in KLEE to - the klee-dev mailing list. You need to - be subscribe to the list in order to send your report. - -
- - diff --git a/www/content.css b/www/content.css deleted file mode 100644 index 50835ec3..00000000 --- a/www/content.css +++ /dev/null @@ -1,75 +0,0 @@ -html, body { - padding:0px; - font-size:small; - font-family:"Lucida Grande", "Lucida Sans Unicode", Arial, Verdana, Helvetica, sans-serif; - background-color: #fff; color: #222; - line-height:1.5; -} - -h1, h2, h3, tt { color: #000 } - -h1 { color:#000000; padding-top: 0px; margin-top:0px;} -h2 { color:#333333; padding-top: 0.5em; } -h3 { color:#2d58b7; padding-top: 0.5em; margin-bottom: -0.25em; } -h4 { color:#2d58b7; } -li { padding-bottom: 0.5em; } -ul { padding-left:1.5em; } - -/* Slides */ -IMG.img_slide { - display: block; - margin-left: auto; - margin-right: auto -} - -.itemTitle { color:#2d58b7 } - -/* Tables */ -tr { vertical-align:top } - -/* Syntax */ -div.syntax { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: SeaShell; - padding: 7px; - margin: 7px; -} - -/* Examples */ -div.example { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Instructions */ -div.instr { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Output */ -pre.output { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Code */ -pre.code{ - display:table; - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - margin: 10px; - padding: 10px; -} - diff --git a/www/content/coreutils_kc_0.png b/www/content/coreutils_kc_0.png deleted file mode 100644 index 3f72dc49..00000000 Binary files a/www/content/coreutils_kc_0.png and /dev/null differ diff --git a/www/content/coreutils_kc_1.png b/www/content/coreutils_kc_1.png deleted file mode 100644 index d4372f26..00000000 Binary files a/www/content/coreutils_kc_1.png and /dev/null differ diff --git a/www/developers-guide.html b/www/developers-guide.html deleted file mode 100644 index 9c0ff719..00000000 --- a/www/developers-guide.html +++ /dev/null @@ -1,114 +0,0 @@ - - - - - KLEE - Getting Started - - - - - - - -
- -

KLEE Developer's Guide

- -

This guide covers several areas of KLEE that may not be imediately obvious to new developers.

- -

- 1. KLEE's Build System
- 2. KLEE's Test Framework
- 3. Miscellaneous
-

- -

KLEE's Build System

-

KLEE uses LLVM's ability to build third-party projects, which is described here. The build system uses GNU Autoconf and AutoHeader to configure the build, but does not use the rest of GNU Autotools (e.g. automake).

- -

LLVM's build system supports out-of-source builds and therefore so does KLEE. It is highly recommended you take advantage of this. For example, you could create three builds (Release, Release with debug symbols, Debug) - that all use the same source tree. This allows you keep your source tree clean and allows multiple configurations to be tested from a single source tree.

- -

Setting up a debug build of KLEE

-

Setting up a debug build of KLEE (we'll assume it is an out-of-source build) is very similar to the build process described in Getting Started, with the exception of steps 6 and 7.

- -
    -
  1. Now we will configure KLEE. Notice that we are forcing the compiler to produce unoptimised code, this isn't the default behaviour. -
    - $ mkdir path/to/build-dir
    - $ cd path/to/build-dir
    - $ CXXFLAGS="-g -O0" CFLAGS="-g -O0" path/to/source-dir/configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime --with-runtime=Debug+Asserts -
    - Note if you're using an out-of-source build of LLVM you will need to use --with-llvmsrc= and --with-llvmobj= configure options instead of --with-llvm= -
    2. -
  2. Now we can build KLEE. -
    - $ make -j -
    - Note that we are using the -j option of make to speed up the compilation process. -
    3. -
- -

Note that KLEE depends on LLVM and STP. If you need to debug KLEE's calls to that code, then you will need to build LLVM/STP with debug support too.

- -

Adding a class

-

Because KLEE uses LLVM's build system, adding a class to an existing library in KLEE is very simple. For example, to add a class to libkleaverExpr, the following steps would be followed: -

    -
  1. Create the header file (.h) for the class and place it somewhere inside include/ (the location isn't really important except that #include is relative to the include/ directory). -
    2. -
  2. Create the source file (.cpp) for the class place it in lib/Expr/. You can confirm that the library in which your new class will be included is kleaverExpr by looking at the Makefile in lib/Expr. -
    3. -
- That's it! Now LLVM's build system will detect the new .cpp file and add it to the library that is generated when you run make. -

- -

Building code documentation

-

KLEE uses Doxygen to generate code documentation. To generate it yourself you can run the following from KLEE's build directory root. -

- $ make doxygen -
- This will generate documentation in path/to/build-dir/docs/doxygen/ folder. You can also find KLEE's latest official code documentation here -

- - -

KLEE's Test Framework

-

KLEE uses LLVM's testing infrastructure for its tests, which itself uses DejaGnu. These are the tests that are executed by the make check command. Some documentation on LLVM's testing infrastructure can be found here. -

-

KLEE's tests are currently divided into categories, each of which is a subdirectory in test/ in the source tree (e.g. test/Feature) . The dg.exp file in each subdirectory instructs the LLVM testing infrastructure which files in the subdirectory are to be used as tests. For example, test/Expr/dg.exp contains: -

- load_lib llvm.exp

- - RunLLVMTests [lsort [glob -nocomplain $srcdir/$subdir/*.{pc}]] -
- This instructs the testing infrastructure that every .pc file in test/Expr should be used as a test. -

-

The actions performed in each test are specified by special comments in the file. For example, in test/Feature/ByteSwap.c the first two lines are -

- // RUN: %llvmgcc %s -emit-llvm -O0 -c -o %t1.bc
- // RUN: %klee --libc=klee --exit-on-error %t1.bc
-
- This first runs llvm-gcc on the source file (%s) and generates a temporary file (%t1.bc). Then KLEE is executed on this generated temporary file. If either program returns a non-zero exit code (or crashes) then - test is considered to have failed. More information on the available substitution variables (such as %s) can be found here. -

- -

It is useful to be able to execute just a single test rather than all of them. KLEE provides a makefile target for doing so which can used as shown below. Note that category/test-name should be the test that one would like to execute, e.g. Feature/ByteSwap.c. -

- $ cd path/to/build-dir/test
- $ make check-one TESTONE=path/to/source-dir/test/category/test-name -
-

- - -

Miscellaneous

-

Writing messages to standard error

-

The kleeCore library (lib/Core) provides several functions that can be used similarly to printf() in C. See lib/Core/Common.h for more information. -

- -

Adding a command line option to a tool

-

KLEE uses LLVM's CommandLine library for adding options to tools in KLEE, which is well documented here. See lib/core/Executor.cpp for examples.

- -
- -
- - diff --git a/www/index.html b/www/index.html deleted file mode 100644 index b76a42bc..00000000 --- a/www/index.html +++ /dev/null @@ -1,36 +0,0 @@ - - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

The KLEE Symbolic Virtual Machine

- - -

KLEE is a symbolic virtual machine built on top of - the LLVM compiler infrastructure, and available - under the UIUC open source license.

- -

For more information on what KLEE is and what it can do, see - the OSDI - 2008 paper.

- -

If you are interested in trying it yourself, please - see Getting Started.

- - - -
- - diff --git a/www/klee-dev.html b/www/klee-dev.html deleted file mode 100644 index 5434ce57..00000000 --- a/www/klee-dev.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - klee-dev mailing list - - - - - -
- -

klee-dev mailing list

- - -

If you have questions about KLEE that are not answered on this - website, please send a message to - the klee-dev - mailing list.

- - -

However, before doing so, please - check klee-dev's - searchable archive to see if your question has already been - answered.

- -
- - diff --git a/www/klee-files.html b/www/klee-files.html deleted file mode 100644 index 299f593b..00000000 --- a/www/klee-files.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

Files generated by KLEE

- - -

Standard Global Files

- - These are global files are always generated on a KLEE execution: -
    -
  1. info: This is a text file containing various information - related to a KLEE run. In particular, it records the exact - command-line with which KLEE was run, and the total time taken by - the execution. E.g.: - 
    -    $ cat info 
-    klee --write-pcs demo.o
-    PID: 12460
-    Started: 2009-05-20 22:31:41
-    BEGIN searcher description
-    DFSSearcher
-    END searcher description
-    Finished: 2009-05-20 22:31:41
-    Elapsed: 00:00:00
-    KLEE: done: explored paths = 3
-    KLEE: done: avg. constructs per query = 6
-    KLEE: done: total queries = 3
-    KLEE: done: valid queries = 0
-    KLEE: done: invalid queriers = 3
-    KLEE: done: query cex = 3
-    KLEE: done: total instructions = 67
-    KLEE: done: completed paths = 3
-    KLEE: done: generated tests = 3
    -
    2. - -
  2. warnings.txt: This is a text file containing all warnings emitted by KLEE. -
    3. - -
  3. messages.txt: This is a text file containing all other messages emitted by KLEE. -
    4. - -
  4. assembly.ll: This file contains a human readable version - of the LLVM bitcode executed by KLEE - -
  5. run.stats: This is a text file containing various - statistics emitted by KLEE. While this file can be inspected - manually, you should use the klee-stats - tool for that.
    6. - -
  6. run.istats: This is a binary file containing global - statistics emitted by KLEE for each line of code in the program. -
    7. - -
- - -

Other Global Files

- -
    -
  1. all-queries.pc: This file contains all the queries KLEE - made during execution in the KQuery - format. Note these are the queries before any optimisation - (e.g. caching, constraint independence) so it is possible that - some of the queries logged are never executed by KLEE's underlying - solver or are modified before being executed by KLEE's underlying - solver. The generation of this file can be enabled by specifying - the option --use-query-log=all:pc to KLEE.
    2. -
  2. all-queries.smt2: This file contains all the queries KLEE made during execution in the SMT-LIBv2 - .It contains the same information as all-queries.pc. - The generation of this file can be enabled by specifying the option --use-query-log=all:smt2 to KLEE.
    3. -
  3. solver-queries.pc: This file contains all the queries passed to KLEE's underlying solver during execution in the - KQuery format. Note these are the - queries after all optimisations (e.g. caching, constraint - independence) are performed. The generation of this file can be - enabled by specifying the - option --use-query-log=solver:pc to KLEE.
    4. -
  4. solver-queries.smt2: This file contains all the queries passed to KLEE's underlying solver during execution in the - SMT-LIBv2 - format. It contains the same information as solver-queries.pc. - The generation of this file can be enabled by specifying the option --use-query-log=solver:smt2 to KLEE.
    5. -
- - -

Per-path files

- -
    -
  1. - test<N>.ktest: Contains the test case generated by - KLEE on that path. Use ktest-tool - to read the contents. The generation of .ktest files - can be disabled using the --no-output option. -
    2. - -
  2. - test<N>.<error-type>.err: Generated for paths - where KLEE found an error. Contains information about the error - in textual form. -
    3. - -
  3. test<N>.pc: Contains the constraints associated with the given - path, in KQuery format. The generation - of these files can be enabled via the --write-cvcs flag. -
    4. - -
  4. - test<N>.cvc: Contains the constraints associated - with the given path, - in CVC - format. The generation of these files can be enabled via - the --write-pcs flag. (This is the same information as - in the corresponding .pc file.) -
    5. -
  5. - test<N>.smt2: Contains the constraints associated - with the given path, - in SMT-LIBv2 - format. The generation of these files can be enabled via - the --write-smt2s flag. (This is the same information as - in the corresponding .pc file.) -
    6. -
- - -
- - diff --git a/www/klee-options.html b/www/klee-options.html deleted file mode 100644 index be997ec4..00000000 --- a/www/klee-options.html +++ /dev/null @@ -1,99 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Options

- - -

- 1. Search Heuristics
- 2. Query Logging
-

- - - -

Main search heuristics

- -

- KLEE provides four main search heuristics: -

    -
  1. Depth-First Search (DFS): Traverses states in depth-first order.
    2. -
  2. Random State Search:Randomly selects a state to explore.
    3. -
  3. Random Path Selection: Described in our KLEE OSDI'08 paper.
    4. -
  4. Non Uniform Random Search (NURS): Selects a state randomly according to a given distribution. The distribution can be based on the minimum distance to an uncovered instruction (MD2U), the query cost, etc. -
- - To select a search heuristic, use the --search option provided by KLEE. For example: - 
-    $ klee --search=dfs demo.o
- - runs demo.o using DFS, while - 
-    $ klee --search=random-path demo.o
- runs it using the random path selection strategy. - - The full list of options is shown in KLEE's help message: - 
-    $ klee --help
-    -search                                 - Specify the search heuristic (default=random-path interleaved with nurs:covnew)
-      =dfs                                  -   use Depth First Search (DFS)
-      =random-state                         -   randomly select a state to explore
-      =random-path                          -   use Random Path Selection (see OSDI'08 paper)
-      =nurs:covnew                          -   use Non Uniform Random Search (NURS) with Coverage-New heuristic
-      =nurs:md2u                            -   use NURS with Min-Dist-to-Uncovered heuristic
-      =nurs:depth                           -   use NURS with 2^depth heuristic
-      =nurs:icnt                            -   use NURS with Instr-Count heuristic
-      =nurs:cpicnt                          -   use NURS with CallPath-Instr-Count heuristic
-      =nurs:qc                              -   use NURS with Query-Cost heuristic
- - -

Interleaving search heuristics

-

- Search heuristics in KLEE can be interleaved in a round-robin - fashion. To interleave several search heuristics to be interleaved, use the --search multiple times. For example: - 

-    $ klee --search=random-state --search=nurs:md2u demo.o
- interleaves the Random State and the NURS:MD2U heuristics in a round robin fashion. -
-

- - -

Default search heuristics

-

- The default heuristics used by KLEE are random-path interleaved with nurs:covnew. -

- -

Query Logging

- - To log the queries issued by KLEE during symbolic execution, you can use the following options: -
    -
  1. - --use-query-log=TYPE:FORMAT, where: -
      -
    • TYPE is either all to log all the queries KLEE made during execution before any optimisation (e.g. caching, constraint independence) is performed, or solver to log only the queries passed to KLEE's underlying solver. Note that it is possible that some of the unoptimized queries are never executed or are modified before being executed by KLEE's underlying solver.
      • -
    • FORMAT is the format in which queries are logged and can be either pc for the KQuery format, or smt2 for the SMT-LIBv2 format. -
    -
  2. - --min-query-time-to-log=TIME (in ms) is used to log only queries that exceed a certain time limit. TIME can be: -
      -
    • 0 (default): to log all queries
      • -
    • <0: a negative value specifies that only queries that timed out should be logged. The timeout value is specified via the --max-stp-time option.
      • -
    • >0: only queries that took more that TIME milliseconds should be logged. -
    -
    3. - -
- -
- - diff --git a/www/klee-tools.html b/www/klee-tools.html deleted file mode 100644 index 80ae5d35..00000000 --- a/www/klee-tools.html +++ /dev/null @@ -1,84 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Tools

- - -

- 1. ktest-tool
- 2. klee-stats
-

- -

ktest-tool

- -

klee-stats

- klee-stats is a Python script used to extract and present in a - tabular form runtime statistics for a KLEE execution. The runtime statistics include: - - - - klee-stats extracts statistics information from the run.stats file - present in the klee-out-* directory created during a KLEE execution. - The exact usage of klee-stats is as follows: - 
klee-stats [options] directories
- The directories parameter is a list of klee-out-* directories - created by KLEE. A common scenario is to simply run klee-stats on klee-last. - -

- In order to limit printed information only to the values of measured times, - the following options can be used: - -

- - The --precision option can be used to configure the number of fractional - digits displayed in floating point values. By default, 2 fractional digits - are displayed, but in some cases that might be not sufficient—if the value - is very small, e.g. 0.0001, with 2-digits precision it will be printed as 0.00. -

- -

Various other options can be used to specify what values are - displayed and how they are displayed. Options for comparison of - statistics are also provided. More information about available - options can be obtained using the command: - 

klee-stats --help
-

- -
- -
- - diff --git a/www/menu.css b/www/menu.css deleted file mode 100644 index 6e96a457..00000000 --- a/www/menu.css +++ /dev/null @@ -1,39 +0,0 @@ -/***************/ -/* page layout */ -/***************/ - -[id=menu] { - position:fixed; - width:25ex; -} -[id=content] { - /* ***** EDIT THIS VALUE IF CONTENT OVERLAPS MENU ***** */ - position:absolute; - left:29ex; - padding-right:4ex; -} - -/**************/ -/* menu style */ -/**************/ - -#menu .submenu { - padding-top:1em; - display:block; -} - -#menu label { - display:block; - font-weight: bold; - text-align: center; - background-color: rgb(192,192,192); -} -#menu a { - padding:0 .2em; - display:block; - text-align: center; - background-color: rgb(235,235,235); -} -#menu a:visited { - color:rgb(100,50,100); -} \ No newline at end of file diff --git a/www/menu.html.incl b/www/menu.html.incl deleted file mode 100644 index 7f2e4e33..00000000 --- a/www/menu.html.incl +++ /dev/null @@ -1,31 +0,0 @@ - diff --git a/www/resources/Regexp.c.html b/www/resources/Regexp.c.html deleted file mode 100644 index cb3e3d75..00000000 --- a/www/resources/Regexp.c.html +++ /dev/null @@ -1,78 +0,0 @@ - - - -Enscript Output - - - - -

Regexp.c

- -
-/* 
- * Simple regular expression matching.
- *
- * From:
- *   The Practice of Programming
- *   Brian W. Kernighan, Rob Pike
- *
- */ 
-
-#include <klee/klee.h>
-
-static int matchhere(char*,char*);
-
-static int matchstar(int c, char *re, char *text) {
-  do {
-    if (matchhere(re, text))
-      return 1;
-  } while (*text != '\0' && (*text++ == c || c== '.'));
-  return 0;
-}
-
-static int matchhere(char *re, char *text) {
-  if (re[0] == '\0')
-     return 0;
-  if (re[1] == '*')
-    return matchstar(re[0], re+2, text);
-  if (re[0] == '$' && re[1]=='\0')
-    return *text == '\0';
-  if (*text!='\0' && (re[0]=='.' || re[0]==*text))
-    return matchhere(re+1, text+1);
-  return 0;
-}
-
-int match(char *re, char *text) {
-  if (re[0] == '^')
-    return matchhere(re+1, text);
-  do {
-    if (matchhere(re, text))
-      return 1;
-  } while (*text++ != '\0');
-  return 0;
-}
-
-/*
- * Harness for testing with KLEE.
- */
-
-// The size of the buffer to test with.
-#define SIZE 7
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic_name(re, sizeof re, "re");
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-
Generated by GNU enscript 1.6.4.
- - diff --git a/www/resources/get_sign.c.html b/www/resources/get_sign.c.html deleted file mode 100644 index 58c28d01..00000000 --- a/www/resources/get_sign.c.html +++ /dev/null @@ -1,37 +0,0 @@ - - - -Enscript Output - - - - -

get_sign.c

- -
-/*
- * First KLEE tutorial: testing a small function
- */
-
-
-int get_sign(int x) {
-  if (x == 0)
-     return 0;
-  
-  if (x < 0)
-     return -1;
-  else 
-     return 1;
-} 
-
-int main() {
-  int a;
-  klee_make_symbolic(&a, sizeof(a), "a");
-  return get_sign(a);
-} 
-
-
-
Generated by GNU Enscript 1.6.5.2.
-enscript -Ec --color -w html get_sign.c -o get_sign.c.html - - diff --git a/www/resources/islower.c.html b/www/resources/islower.c.html deleted file mode 100644 index 524f2093..00000000 --- a/www/resources/islower.c.html +++ /dev/null @@ -1,33 +0,0 @@ - - - -Enscript Output - - - - -

islower.c

- -
-/*
- * First KLEE tutorial: testing a small function
- */
-
-#include <klee/klee.h>
-
-int my_islower(int x) {
-  if (x >= 'a' && x <= 'z')
-    return 1;
-  else return 0;
-}
-
-int main() {
-  char c;
-  klee_make_symbolic(&c, sizeof(c), "input");
-  return my_islower(c);
-}
-
-
-
Generated by GNU enscript 1.6.4.
- - -- cgit 1.4.1 From 4df4cee1ef65b197020871095cc16d377c9a1996 Mon Sep 17 00:00:00 2001 From: Dominic Chen Date: Thu, 25 Jul 2013 10:50:53 +0100 Subject: Revert "move website to separate repo" This reverts commit 6ae711b1d900bffbca407fe97d5e5ce97745dff1. --- www/CoreutilsExperiments.html | 158 ++++++++ www/Documentation.html | 57 +++ www/GetInvolved.html | 53 +++ www/GetStarted.html | 244 +++++++++++ www/KQuery.html | 620 ++++++++++++++++++++++++++++ www/OpenProjects.html | 91 +++++ www/Publications.html | 402 +++++++++++++++++++ www/TestingCoreutils.html | 893 +++++++++++++++++++++++++++++++++++++++++ www/Tutorial-1.html | 187 +++++++++ www/Tutorial-2.html | 287 +++++++++++++ www/Tutorials.html | 38 ++ www/bugs.html | 24 ++ www/content.css | 75 ++++ www/content/coreutils_kc_0.png | Bin 0 -> 277141 bytes www/content/coreutils_kc_1.png | Bin 0 -> 232377 bytes www/developers-guide.html | 114 ++++++ www/index.html | 36 ++ www/klee-dev.html | 31 ++ www/klee-files.html | 137 +++++++ www/klee-options.html | 99 +++++ www/klee-tools.html | 84 ++++ www/menu.css | 39 ++ www/menu.html.incl | 31 ++ www/resources/Regexp.c.html | 78 ++++ www/resources/get_sign.c.html | 37 ++ www/resources/islower.c.html | 33 ++ 26 files changed, 3848 insertions(+) create mode 100644 www/CoreutilsExperiments.html create mode 100644 www/Documentation.html create mode 100644 www/GetInvolved.html create mode 100644 www/GetStarted.html create mode 100644 www/KQuery.html create mode 100644 www/OpenProjects.html create mode 100644 www/Publications.html create mode 100644 www/TestingCoreutils.html create mode 100644 www/Tutorial-1.html create mode 100644 www/Tutorial-2.html create mode 100644 www/Tutorials.html create mode 100644 www/bugs.html create mode 100644 www/content.css create mode 100644 www/content/coreutils_kc_0.png create mode 100644 www/content/coreutils_kc_1.png create mode 100644 www/developers-guide.html create mode 100644 www/index.html create mode 100644 www/klee-dev.html create mode 100644 www/klee-files.html create mode 100644 www/klee-options.html create mode 100644 www/klee-tools.html create mode 100644 www/menu.css create mode 100644 www/menu.html.incl create mode 100644 www/resources/Regexp.c.html create mode 100644 www/resources/get_sign.c.html create mode 100644 www/resources/islower.c.html diff --git a/www/CoreutilsExperiments.html b/www/CoreutilsExperiments.html new file mode 100644 index 00000000..c0f0829c --- /dev/null +++ b/www/CoreutilsExperiments.html @@ -0,0 +1,158 @@ + + + + + + KLEE - Coreutils Experiments + + + + + +
+ +

Coreutils Experiments

+ +

+ This document is meant to give additional information regarding + the Coreutils experiments discussed in + our KLEE + OSDI'08 paper. However, please note that in the last several + years, KLEE and its dependencies (particularly LLVM and STP), have + undergone major changes, which have resulted in considerable + different behavior on several benchmarks, including Coreutils.

+ +

+ This document is structured as a series of FAQs: +

+ +
    +
  1. How did you build Coreutils?
    + Please follow the instructions in the Coreutils Tutorial. +
    2. + +
  2. What version of LLVM was used in the OSDI paper?
    + We generally kept in sync with the LLVM top-of-tree, which at the time + was somewhere around LLVM 2.2 and 2.3.
    3. + + +
  3. What version of STP was used in the OSDI paper?
    + An old version of STP, which is still available as part of KLEE's + repository, in revisions up to r161056. +
    4. + +
  4. On what OS did you run your experiments?
    + We ran most experiments on a 32-bit Fedora machine with SELinux + support. The most important aspect is that this was a 32-bit + system: the constraints generated on a 64-bit system are typically + more complex and memory consumption might also increase. +
    5. + +
  5. What are the 89 Coreutils applications that you tested?
    +
    + [ base64 basename cat chcon chgrp chmod chown chroot cksum comm cp csplit cut date dd df dircolors dirname du echo env expand expr factor false fmt fold head hostid hostname id ginstall join kill link ln logname ls md5sum mkdir mkfifo mknod mktemp mv nice nl nohup od paste pathchk pinky pr printenv printf ptx pwd readlink rm rmdir runcon seq setuidgid shred shuf sleep sort split stat stty sum sync tac tail tee touch tr tsort tty uname unexpand uniq unlink uptime users wc whoami who yes +
    +
    6. + +
  6. What options did you run KLEE with?
    + We used the following options (the command below is for paste): +
    +$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    + --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    + --use-cex-cache --with-libc --with-file-model=release \
    + --allow-external-sym-calls --only-output-states-covering-new \
    + --exclude-libc-cov --exclude-cov-file=./../lib/functions.txt \
    + --environ=test.env --run-in=/tmp/sandbox --output-dir=paste-data-1h \
    + --max-sym-array-size=4096 --max-instruction-time=10. --max-time=3600. \
    + --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    + --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    + --randomize-fork --use-random-path --use-interleaved-covnew-NURS \
    + --use-batching-search --batch-instructions 10000 --init-env \
    + ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout +
    + + Some of these options have been renamed or removed in the current + version of KLEE. Most notably, the options "--exclude-libc-cov" + and "--exclude-cov-file" were implemented in a fragile way and we + decided to remove them from KLEE. The idea was to treat the + functions in libc or specified in a text file as "covered". (For + the Coreutils experiments, we were interested in covering the + code in the tools themselves, as opposed to library code, see the + paper for more details). If you plan to reimplement these + options in a clean way, please consider contributing your code to the mainline. +
    7. + +
  7. What are the options closest to the ones above that + work with the current version KLEE?
    + Try the following: + +
    +$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    + --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    + --use-cex-cache --libc=uclibc --posix-runtime \
    + --allow-external-sym-calls --only-output-states-covering-new \
    + --environ=test.env --run-in=/tmp/sandbox \
    + --max-sym-array-size=4096 --max-instruction-time=30. --max-time=3600. \
    + --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    + --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    + --randomize-fork --search=random-path --search=nurs:covnew \
    + --use-batching-search --batch-instructions=10000 \
    + ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout +
    + +
    8. + +
  8. How do I generate test.env and /tmp/sandbox?
    + We used a simple environment and a "sandbox" directory to make + our experiments more deterministic. To recreate them, follow + these steps: +
      +
    1. Download testing-env.sh by clicking here, and place it in the current directory.
      2. +
    2. Create test.env by running: +
      + $ env -i /bin/bash -c '(source testing-env.sh; env >test.env)' +
      +
      3. +
    3. Download sandbox.tgz by clicking here, place it in /tmp, and run: +
      + $ cd /tmp + $ tar xzfv sandbox.tgz +
      +
      4. +
    +
    9. +
  9. + What symbolic arguments did you use in your experiments?
    + We ran most utilities using the arguments below. Our choice was + based on a high-level understanding of the Coreutils + applications: most behavior can be triggered with no more than two + short options, one long option, and two small input streams (stdin and one file). +
    + --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout +
    + + + + For eight tools where the coverage results were unsatisfactory, +we consulted the man page and increased the number and size of +arguments and files as follows: +
    + dd: --sym-args 0 3 10 --sym-files 1 8 --sym-stdout
    + dircolors: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    + echo: --sym-args 0 4 300 --sym-files 2 30 --sym-stdout
    + expr: --sym-args 0 1 10 --sym-args 0 3 2 --sym-stdout
    + mknod: --sym-args 0 1 10 --sym-args 0 3 2 --sym-files 1 8 --sym-stdout
    + od: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    + pathchk: --sym-args 0 1 2 --sym-args 0 1 300 --sym-files 1 8 --sym-stdout
    + printf: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout +
    + +
    10. + +
+ + +
+ + diff --git a/www/Documentation.html b/www/Documentation.html new file mode 100644 index 00000000..538cada7 --- /dev/null +++ b/www/Documentation.html @@ -0,0 +1,57 @@ + + + + + + KLEE - Documentation + + + + + +
+ +

KLEE Documentation

+ + +
    +
  1. + KLEE Tutorials: + Simple examples of how to use KLEE to test programs. +
    2. + +
  2. + KLEE Options: + Overview of KLEE's main command-line options. +
    3. + +
  3. + KLEE Generated Files: + Overview of the main files generated by KLEE. +
    4. + +
  4. + KLEE Tools: + Overview of the main auxiliary tools provided by KLEE. +
    5. + +
  5. + KQuery Language Reference Manual: + The reference manual for the KQuery language, used for interacting with + the KLEE solver (kleaver). +
    6. + +
  6. + OSDI'08 Coreutils Experiments: + Some information about the Coreutils experiments presented in our KLEE OSDI'08 paper. +
    7. + +
  7. + Developer's Guide: + A brief guide on working with the KLEE source code. +
    8. +
+
+ + diff --git a/www/GetInvolved.html b/www/GetInvolved.html new file mode 100644 index 00000000..2ff2b5ee --- /dev/null +++ b/www/GetInvolved.html @@ -0,0 +1,53 @@ + + + + + KLEE - Get Involved + + + + + + + +
+ +

Getting Involved with the KLEE Project

+ +

If you are interested in following development of KLEE, or would like to +contribute, here are some resources that may prove useful.

+ +

Mailing Lists

+ +

Currently the main list for KLEE discussion (both for users and developers) +is klee-dev.

+ +

Commit messages to the KLEE repository go to +klee-commits. This +is also the place to send patches if you are interested in contributing to +KLEE.

+ +

Bug Reports

+ +

If you find a bug in KLEE, please report it on klee-dev +and also fill a bug report on Bugzilla under the klee product.

+ + +

Working with the Code

+ +

You should first check KLEE's developer's guide.

+ +

Developer documentation is written in + doxygen. + +

+ +

+ +

Many parts of KLEE rely on the LLVM infrastructure, so you might also want to look at +LLVM's General Programming Documentation.

+ +
+ + diff --git a/www/GetStarted.html b/www/GetStarted.html new file mode 100644 index 00000000..7f6199dc --- /dev/null +++ b/www/GetStarted.html @@ -0,0 +1,244 @@ + + + + + KLEE - Getting Started + + + + + + + +
+ +

Getting Started: Building and Running KLEE

+ + + +

+1. Trying out KLEE without installing any dependencies
+2. Building KLEE
+

+ + +

Trying out KLEE without installing any dependencies

+ +

+If you would like to try out KLEE without the hassle of compiling or installing dependencies, download the self-contained package (200MB), and follow the instructions in klee-cde-package/README to get up-and-running! +

+ +

+This package contains a self-contained source+binary distribution of KLEE and all of its associated dependencies (e.g., llvm-2.7, llvm-gcc, uClibc, svn). Using this package, you can: +

+ +
    +
  1. Compile target programs using llvm-gcc +
  2. Run KLEE on target programs compiled with llvm-gcc +
  3. Modify KLEE's source code, re-compile it to build a new KLEE binary, and then run the test suite using the new binary +
  4. Pull the latest KLEE source code updates from SVN +
  5. Run the entire Coreutils case study +
+ +

+... all without compiling or installing anything else on your Linux machine! +

+ +

+The only requirement is that you are running a reasonably-modern x86-Linux distro that can execute 32-bit ELF binaries. This package was created using the CDE auto-packaging tool. +

+ +

+NOTE: The CDE package is mainly meant for trying out KLEE on +some simple examples and the Coreutils case study. It is likely that +you will run into errors when testing other applications, in which +case you will need to follow the full installation instructions below. +

+ + +

Building KLEE

+ + +

The current procedure for building is outlined below.

+ +
    + +
  1. Install dependencies: + +KLEE requires all the dependencies of LLVM, which are discussed here. In particular, you should have the following packages (the list is likely not complete): g++, curl, dejagnu, subversion, bison, flex: +
    + $ sudo apt-get install g++ curl dejagnu subversion bison flex (Ubuntu)
    + $ sudo yum install g++ curl dejagnu subversion bison flex (Fedora) +
    +

    + +On some architectures, you might also need to set the following environment variables (best to put them in a config file like .bashrc): +
    + $ export C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
    + $ export CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu +
    + +
  2. Build LLVM 2.9: + +

    +KLEE is built on top of LLVM; the first +steps are to get a working LLVM installation. +See Getting Started +with the LLVM System for more information. +

    + +

    +NOTE: KLEE is currently tested only on Linux x86-32 and x86-64 +targets, using LLVM 2.9. KLEE will not work with older LLVM +versions (e.g., 2.5), and might not work with newer versions (e.g., +3.0). +

    + + +
      +
    1. Install llvm-gcc: +
        +
      • Download and install the LLVM 2.9 release of llvm-gcc + from here. + +
        Add llvm-gcc to your PATH. It + is important to do this first so that llvm-gcc is + found in subsequent configure + steps. llvm-gcc will be used later to compile + programs that KLEE can execute. +
        • + +
      • Forgetting to add llvm-gcc to your PATH at this point is + by far the most common source of build errors reported by new + users.
        • +
      +
      2. + +
    2. Download and build LLVM 2.9: +
      + $ curl -O http://llvm.org/releases/2.9/llvm-2.9.tgz
      + $ tar zxvf llvm-2.9.tgz
      + $ cd llvm-2.9
      + $ ./configure --enable-optimized --enable-assertions
      + $ make +
      + + (the --enable-optimized configure argument is not necessary, but + KLEE runs very slowly in Debug mode). +
      3. + +
    + + +
  3. Build STP: + +

    KLEE is based on +the STP +constraint solver. STP does not make frequent releases, and its +Subversion repository is under constant development and may be +unstable. The instructions below are for a particular revision which +we have used successfully, but you can try a more recent revision by +changing or removing the -r argument to the svn co +command. (Please let us know if you have successfully and extensively +used KLEE with a more recent version of STP.) +

    + +
    + $ svn co -r 940 https://stp-fast-prover.svn.sourceforge.net/svnroot/stp-fast-prover/trunk/stp stp
    + $ cd stp
    + $ ./scripts/configure --with-prefix=path/to/stp/install --with-cryptominisat2
    + $ make OPTIMIZE=-O2 CFLAGS_M32= install +
    +
    4. + +As documented on the STP website, it is essential to run the following +command before using STP (and thus KLEE): +
    + $ ulimit -s unlimited +
    + + +
  4. [Optional] Build uclibc and the POSIX environment model: + +

    +By default, KLEE works on closed programs (programs that don't use any +external code such as C library functions). However, if you want to +use KLEE to run real programs you will want to enable the KLEE POSIX +runtime, which is built on top of the uClibc C library. +

    + +
      +
    1. Download KLEE's uClibc. KLEE uses a version + of uClibc which has been + modified slightly for our purposes. +
        +
      • A version that works on 32-bit Linux can be found + here +
        • +
      • A version that works on 64-bit Linux can be found + here +
        • +
      +
      2. + +
    2. Build uClibc with llvm-gcc: +
      + $ tar zxvf klee-uclibc-0.02.tgz
      + $ ./configure --with-llvm=path/to/llvm
      + $ make
      +
      + +

      NOTE: If you are on a different target (i.e., not i386 + or x64), you will need to run make config and select the + correct target. The defaults for the other uClibc configuration + variables should be fine.

      +

      3. + +
    + + +
  5. Checkout KLEE (to any path you like): +
    + $ svn co http://llvm.org/svn/llvm-project/klee/trunk klee +
    + Alternatively, if you prefer to use git there is also a + read-only git mirror, which syncs automatically with each + Subversion commit. You can do a git clone of KLEE via: +
    + $ git clone http://llvm.org/git/klee.git +
    +
    6. + +
  6. Configure KLEE: +

    From the KLEE source directory, run:

    +
    + $ ./configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime +
    + +

    NOTE: If you skipped step 4, simply remove the --with-uclibc and --enable-posix-runtime options.

    +
    7. + +
  7. Build KLEE: +
    + $ make ENABLE_OPTIMIZED=1 +
    +
    8. + +
  8. Run the regression suite to verify your build: +
    + $ make check
    + $ make unittests
    +
    +
    9. + +
  9. You're ready to go! Go to the Tutorials page + to try KLEE.
    10. +
+ +

NOTE: If you are installing the system of Ubuntu 12.04 (or similar), you might want to take a look at this message.

+
+ +
+ + diff --git a/www/KQuery.html b/www/KQuery.html new file mode 100644 index 00000000..a40f4435 --- /dev/null +++ b/www/KQuery.html @@ -0,0 +1,620 @@ + + + + + KLEE - KQuery Language Reference Manul + + + + + + + +
+ +

KQuery Language Reference Manual

+ +

Table Of Contents

+
    +
  1. Introduction
    2. +
  2. Notation
    3. +
  3. Structure
    4. +
      +
    1. Expression and Version Labels +
    +
  4. Literals +
      +
    1. Identifiers
      2. +
    2. Numbers
      3. +
    3. Types
      4. +
    +
    5. +
  5. Declarations +
      +
    1. Arrays
      2. +
    2. Query Commands
      3. +
    +
    6. +
  6. Versions
    7. +
  7. Expressions +
      +
    1. Primitive Expressions +
        +
      1. Expression References
        2. +
      2. Constants
        3. +
      +
      2. +
    2. Arithmetic Operations +
        +
      1. Add
        2. +
      2. Sub
        3. +
      3. Mul
        4. +
      4. UDiv
        5. +
      5. URem
        6. +
      6. SDiv
        7. +
      7. SRem
        8. +
      +
      3. +
    3. Bitwise Operations +
        +
      1. Not
        2. +
      2. And
        3. +
      3. Or
        4. +
      4. Xor
        5. +
      5. Shl
        6. +
      6. LShr
        7. +
      7. AShr
        8. +
      +
      4. +
    4. Comparisons +
        +
      1. Eq
        2. +
      2. Ne
        3. +
      3. Ult
        4. +
      4. Ule
        5. +
      5. Ugt
        6. +
      6. Uge
        7. +
      7. Slt
        8. +
      8. Sle
        9. +
      9. Sgt
        10. +
      10. Sge
        11. +
      +
      5. +
    5. Bitvector Manipulation +
        +
      1. Concat
        2. +
      2. Extract
        3. +
      3. ZExt
        4. +
      4. SExt
        5. +
      +
      6. +
    6. Special Expressions +
        +
      1. Read
        2. +
      2. Select
        3. +
      +
      7. +
    7. Macro Expressions +
        +
      1. Neg
        2. +
      2. ReadLSB
        3. +
      3. ReadMSB
        4. +
      +
      8. +
    +
    8. +
+ +

Introduction

+ +

The KQuery language is the textual representation of constraint + expressions and queries which is used as input to the Kleaver + constraint solver.

+ +

Currently the language is capable of representing quantifier free + formulas over bitvectors and arrays, with direct support for all + standard operations on bitvectors. The language has been designed to + be compact and easy to read and write.

+ +

The KQuery language is closely related to the C++ API for Exprs, see + also the + doxygen Expr + documentation.

+ +

Notation

+ +

In this document, syntax is given in Extended Backus-Naur Form and appears as:

+
+ "(" "Eq" [ type ] LHS RHS ")" +
+

Unless noted, the rules are described in terms of tokens not characters, + and tokens can be separate by white space and comments.

+ +

In some case, a production like child-expression is used as an alias + for the expression production, when subsequent text needs to + differentiate the expression.

+ +

Examples are shown using:

+
+ (Eq w32 a b) +
+ +

Structure

+ +

A KQuery source file consists of a sequence of declarations.

+ +

Syntax:

+
+ kquery = { array-declaration | query-command } +
+ +

Currently, the language supports two kinds of declarations:

+
    +
  • Array Declarations: Use to + declare an array of bitvectors for use in subsequent + expressions.
    • + +
  • Query Commands: Used to + define queries which should be executed by the constraint solver. A + query consists of a set of constraints (assumptions), a query + expression, and optionally expressions and arrays to compute values + for if the query expression is invalid.
    • +
+ +

Comments begin with "#" and continue until the end of line. For example:

+
+ (Add w32 1 1) # Two, hopefully +
+ +

Expression and Version Labels

+ +

Expressions are frequently shared among constraints and query + expressions. In order to keep the output succinct and readable, expression + labels can be used to introduce a lexical binding which can be used in + subsequent expressions. Expression labels are globally scoped through the + entire source file, and a definition must preceed any use in the source + file.

+ +

Syntax:

+
+ expression = identifier ":" expression
+
+ +

Likewise, versions are frequently shared among reads and can be labelled in + the same fashion.

+ +

Examples:

+
+ (Add w32 N0:(Add w32 1 1) N0) # Four

+ array const_array[] : w32 -> w8 = [5,6]
+ (Read w8 0 U0:[0=255] @ const_array) # U0 now refers to an array [255,6]
+ (Read w8 1 U0) # Read from byte offset 1 of [255,6]
+
+ +

Literals

+ +

Identifiers

+ +

Identifiers are used for specifying array names and + for expression labels.

+ +

Syntax:

+
+ identifier = "[a-zA-Z_][a-zA-Z0-9._]*"
+
+ +

Examples:

+
+ _foo
+ arr10_20
+
+ +

Note that in order to keep open the possibility to introduce explicit + integral and floating-point types, the following identifiers are treated + as reserved keywords:

+
+ floating-point-type = "fp[0-9]+([.].*)?"
+ integer-type = "i[0-9]+"
+
+ +

Numbers

+ +

Numeric constants can be specified as follows.

+ +

Syntax:

+
+ number = "true" | "false" | signed-constant
+ signed-constant = [ "+" | "-" ] ( dec-constant | bin-constant | oct-constant | hex-constant )
+ dec-constant = "[0-9_]+"
+ bin-constant = "0b[01_]+"
+ oct-constant = "0o[0-7_]+"
+ hex-constant = "0x[0-9a-fA-F_]+"
+
+ +

Examples:

+
+ false
+ -10
+ 0b1000_0001 # 129
+
+ +

Non-decimal constants can be signed. The '_' character is ignored when + evaluating constants, but is available for use as a separator.

+ +

Types

+ +

Types are explicit operands to most expressions, and indicate the + bit-width of the type.

+ +

Syntax:

+
+ type = "w[0-9]+"
+
+ +

Example:

+
+ w32
+
+ +

The numeric portion of the token is taken to be a decimal integer + specifying the bit-width of the type.

+ +

Declarations

+ +

Arrays

+ +

Arrays are the basic type for defining symbolic variables (the + language does not currently support simple variables).

+ +

Syntax:

+
+ array-declaration = "array" name "[" [ size ] "]" ":" domain "->" range "=" array-initializer
+ array-initializer = "symbolic" | "[" number-list "]"
+ number-list = number | number "," number-list
+
+ +

Arrays can be initialized to be either symbolic, or to have a given list of + constant values. For constant arrays, the initializer list must exactly match + the size of the array (if the size was unspecified, it will be the number of + constant values).

+ +

Examples:

+
+ array foo[10] : w32 -> w8 = symbolic # A ten element symbolic array
+ array foo[] : w8 -> w1 = [ true, false, false, true ] # A constant array of four booleans
+
+ +

Query Commands

+ +

Query declarations describe the queries that the constraint solver + should run, along with optional additional arguments to specify + expressions and arrays for which counterexamples should be provided.

+ +

Syntax:

+
+ query-command = "(" "query" constraint-list query-expression [ eval-expr-list [ eval-array-list ] ] ")"
+ query-expression = expression
+ constraint-list = "[" { expression } "]"
+ eval-expr-list = "[" { expression } "]"
+ eval-array-list = "[" { identifier } "]"
+
+ +

Examples:

+
+ (query [] false)
+ (query [(Eq w8 (Read w8 0 mem) 10)] false [] [ mem ])
+
+ +

A query command consists a query, consisting of a constraint list and + a query expression, and two optional lists for use when a counterexample is desired.

+ +

The constraint-list is a list of expressions (with boolean + type) which are assumed to hold. Although not required in the language, + many solvers require that this set of constraints be + consistent. The query-expression is the expression to determine + the validity of.

+ +

If a counterexample is desired for invalid + queries, eval-expr-list is a list of expressions for which a + possible value should be constructed, and eval-array-list is a + list of arrays for which values for the entire array should be + provided. All counterexamples results must be simultaneously + feasible.

+ +

Versions

+ +

Versions are used to refer to an array with an ordered sequence of writes to it.

+ +

Syntax:

+
+ version = identifier | "[" [ update-list ] "]" "@" version
+ update-list = lhs-expression "=" rhs-expression [ "," update-list ]
+
+ +

Examples:

+
+ array small_array[2] : w32 -> w8 = symbolic # The array we will read from
+
+ (Read w8 0 thing) # No Updates to small_array
+ (Read w8 1 [1=0xff] @ small_array) # Read from small_array at byte offset 1 with update where byte 1 set to decimal 255
+
+

A version can be specified either by an identifier, which can refer to an + array or a labelled version, or by an explicit list + of writes which are to be concatenated to another version (the most recent + writes are first).

+ +

Expressions

+ +

Expressions are strongly typed, and have the following general + form:

+
+ "(" EXPR_NAME EXPR_TYPE ... arguments ... ")" +
+

where EXPR_NAME is the expression name, EXPR_TYPE is the + expression type (which may be optional), followed by any additional + arguments.

+ +

Primitive Expressions

+ +

Expression References

+ +

An expression reference can be used to refer to a + previously labelled expression.

+ +

Syntax:

+
+ expression = identifier
+
+ +

Expression and version labels are in separate namespaces, it is the users + responsibility to use separate labels to preserve readability.

+ +

Constants

+ +

Constants are specified by a numeric token or a type and numeric + token.

+ +

Syntax:

+
+ expression = number | "(" type number ")"
+
+ +

When a constant is specified without a type, the resulting expression + is only well-formed if its type can be inferred from the enclosing + context. The true and false constants always have + type w1. + +

Examples:

+
+ true
+ (w32 0)
+ (Add w32 10 20) # The type for 10 and 20 is inferred to be w32.
+
+ +

Arithmetic Operations

+ +

Add, + Sub, + Mul, + UDiv, SDiv, URem, SRem

+ +

Syntax:

+
+ arithmetic-expr-kind = ( "Add" | "Sub" | "Mul" | "UDiv" | "URem" | "SDiv" | "SRem" )
+ expression = "(" arithmetic-expr-kind type expression expression ")"
+
+ +

Arithmetic operations are always binary and the types of the left- + and right-hand side expressions must match the expression type.

+ +

UDiv

+

Truncated unsigned division. Undefined if divisor is 0.

+ +

URem

+

Unsigned remainder. Undefined if divisor is 0.

+ +

SDiv

+

Signed division. Undefined if divisor is 0.

+ +

SRem

+

Signed remainder. Undefined if divisor is 0. Sign of the + remainder is the same as that of the dividend.

+ + +

Bitwise Operations

+ +

Not

+ +

Syntax:

+
+ expression = "(" "Not" [ type ] expression ")" +
+ +

Bitwise negation. The result is the bitwise negation (one's complement) of + the input expression. If the type is specified, it must match the expression + type.

+ +

And, + Or, + Xor, + Shl, + LShr, + AShr

+ +

Syntax:

+
+ bitwise-expr-kind = ( "And" | "Or" | "Xor" | "Shl" | "LShr" | "AShr" )
+ expression = "(" bitwise-expr-kind type expression expression ")"
+
+ +

These bitwise operations are always binary and the types of the left- and + right-hand side expressions must match the expression type.

+ +

Shl

+ +
+ expression = "(" "Shl" type X Y ")" +
+ +

Logical shift left. Moves each bit of X to the left + by Y positions. The Y right-most bits of X are + replaced with zero, and the left-most bits discarded.

+ +

LShr

+ +
+ expression = "(" "LShr" type X Y ")" +
+ +

Logical shift right. Moves each bit of X to the right + by Y positions. The Y left-most bits of X are + replaced with zero, and the right-most bits discarded.

+ + +

AShr

+ +
+ expression = "(" "AShr" type X Y ")" +
+ +

Arithmetic shift right. Behaves as LShr except that the + left-most bits of X copy the initial left-most bit (the sign + bit) of X. + +

Comparisons

+ +

Eq, + Ne, + Ult, + Ule, + Ugt, + Uge, + Slt, + Sle, + Sgt, + Sge

+ +

Syntax:

+
+ comparison-expr-kind = ( "Eq" | "Ne" | "Ult" | "Ule" | "Ugt" | "Uge" | "Slt" | "Sle" | "Sgt" | "Sge" )
+ expression = "(" comparison-expr-kind [ type ] expression expression ")"
+
+ +

Comparison operations are always binary and the types of the left- + and right-hand side expression must match. If the type is specified, it + must be w1.

+ +

Bitvector Manipulation

+ +

Concat

+ +

Syntax:

+
+ expression = "(" "Concat" [type] msb-expression lsb-expression ")" +
+ +

Concat evaluates to a type bits formed by + concatenating lsb-expression to msb-expression.

+ +

Extract

+ +

Syntax:

+
+ expression = "(" "Extract" type offset-number child-expression ")" +
+ +

Extract evaluates to type bits from child-expression + taken from offset-number, where offset-number is the index of + the least-significant bit in child-expression which should be + extracted. + +

ZExt

+ +

Syntax:

+
+ expression = "(" "ZExt" type child-expression ")" +
+ +

ZExt evaluates to the lowest type bits + of child-expression, with undefined bits set to zero.

+ +

SExt

+ +

Syntax:

+
+ expression = "(" "SExt" type input-expression ")" +
+ +

SExt evaluates to the lowest type bits + of child-expression, with undefined bits set to the most-significant + bit of input-expression.

+ +

Special Expressions

+ +

Read

+ +

Syntax:

+
+ expression = "(" "Read" type index-expression version ")"
+
+ +

The Read expression evaluates to the first write + in version for which index-expression is equivalent to + the index in the write. The type of the expression must match the range of the + root array in version, and the type + of index-expression must match the domain.

+ +

Select

+ +

Syntax:

+
+ expression = "(" "Select" type cond-expression true-expression false-expression ")"
+
+ +

The Select expression evalues to true-expression if the + condition evaluates to true, and to false-expression if the condition + evaluates to false. The cond-expression must have type w1.

+ +

Both the true and false expressions must be well-formed, regardless of the + condition expression. In particular, it is not legal for one of the + expressions to cause a division-by-zero during evaluation, even if + the Select expression will never evaluate to that expression.

+ +

Macro Expressions

+ +

Several common expressions are not implemented directly in the Expr + library, but can be expressed in terms of other operations. A number of these + are implemented as "macros". The pretty printer recognizes and prints the + appropriate Expr forms as the macro, and the parser recognizes them and turns + them into the underlying representation.

+ +

Neg

+ +

Syntax:

+
+ expression = "(" "Neg" [ type ] expression ")" +
+ +

This macro form can be used to generate a Sub from zero.

+ +

ReadLSB, + ReadMSB

+ +

Syntax:

+
+ expression = "(" "ReadLSB" type index-expression version ")"
+ expression = "(" "ReadMSB" type index-expression version ")"
+
+ +

ReadLSB and ReadMSB can be used to simplify contiguous array + accesses. The type of the expression must be a multiple N of the array + range type. The expression expands to a concatenation of N read + expressions, where each read is done at a subsequent offset from + the index-expression. For ReadLSB (ReadMSB), the + concatentation is done such that the read at index-expression forms the + least- (most-) significant bits.

+
+ + + diff --git a/www/OpenProjects.html b/www/OpenProjects.html new file mode 100644 index 00000000..d4a01964 --- /dev/null +++ b/www/OpenProjects.html @@ -0,0 +1,91 @@ + + + + + + KLEE - Open Projects + + + + + +
+ +

KLEE Open Projects

+ + + This page lists a variety of open projects that are natural (and tractable) + extensions of KLEE and things that we would love to see people work on. If + you are interested in tackling any of the projects, please mail + klee-dev + with your ideas -- or even better, your patches!. + +
    +
  • + Implement SMT support for Kleaver: + +

    We would like to make Kleaver (KLEE's constraint solver) a more viable + standalone product. One of the steps in this direction is to implement SMT + support. This would also allow us to enter Kleaver into + the SMT-COMP theorem prover + competition, which would be a good proving ground for our optimizations + and benchmarking our underlying constraint solver (STP, currently) against + other implementations.

    +
    • + +
  • + Distributed Constraint Solving: + +

    Much of the execution time of KLEE is spent inside the constraint + solver. A natural extension would be to implement support for a + distributed constraint solver, which would run KLEE on a single machine, + but would farm out the constraints to be solved on a network of + machines.

    +
    • + +
  • + Improve User Interface: + +

    This is not a very glamorous project, but it is still + important. Currently, KLEE has a myriad of command line options and flags, + most of which are left over from its research project roots. In order to + promote KLEE's use as a user tool, we would like to clean up most of the + UI so that the default behavior matches best practice, and so that more + arcane or research-only options are hidden by default.

    +
    • + +
  • + Experiment With Other Constraint Solvers: + +

    For the most part, KLEE has been written so that it is possible to swap + in other constraint solvers, but we have never tried anything other than + STP. We would love to see the results of using other contraint solvers + (like Yices or Z3) with KLEE.

    +
    • + +
  • + Implement Expression Level Constraint Optimization: + +

    KLEE does not currently do much optimization of constraint expressions + before sending them to the constraint solver. We would like to have an + internal framework for doing optimization of constraint expressions (e.g., + (A & ~A) => 0) so that these optimizations are only done once instead of + on every solver query.

    + +

    In general, because KLEE is dealing with expressions which result from + dynamic execution traces, many expressions end up having constant + components. This means we can frequently apply the same optimizations a + compiler would do, but to much greater effect because we are more likely + to see constant values. For reference, see the kinds of optimizations done + by LLVM's InstCombine + pass here.

    + +

    The bulk of this project involves defining a good framework for us to + apply optimizations to expressions, and for deciding when to attempt to + optimization expressions.

    +
    • +
+
+ + diff --git a/www/Publications.html b/www/Publications.html new file mode 100644 index 00000000..2a2dd313 --- /dev/null +++ b/www/Publications.html @@ -0,0 +1,402 @@ + + + + + + KLEE - Publications + + + + + +
+ +

KLEE-related Publications and Systems

+ + +

Below you can find a list of papers that use or extend KLEE. + Papers are listed in chronological order.
If you have used and + extended KLEE, please share your experience by having your paper + listed here (email klee-dev-owner or c.cadar AT imperial.ac.uk).

+ +
    +
  1. + + + KLEE: Unassisted and Automatic Generation of High-Coverage Tests for + Complex Systems Programs + + +
    + Cristian Cadar, Daniel Dunbar, Dawson Engler +
    + USENIX Symposium on Operating Systems Design and Implementation (OSDI 2008) +
    + December 8-10, 2008, San Diego, CA, USA +

    +
    2. + +
  2. + + + Server-side Verification of Client Behavior in Online Games + + +
    + Darrell Bethea, Robert Cochran, Michael Reiter +
    + Network and Distributed System Security Symposium (NDSS 2010) +
    + February 28 - March 3, San Diego, CA, USA +

    +
    3. + +
  3. + + + KleeNet: Discovering Insidious Interaction Bugs in Wireless Sensor Networks Before Deployment + + +
    + Raimondas Sasnauskas, Olaf Landsiedel, Muhammad Hamad Alizai, + Carsten Weise, Stefan Kowalewski, Klaus Wehrle +
    + ACM/IEEE International Conference on Information Processing in Sensor Networks (IPSN 2010) +
    + April 12-16, 2010, Stockholm, Sweden +
    + KleeNet is available here. +

    +
    4. + +
  4. + + + Execution Synthesis: A Technique for Automated Software Debugging + + +
    + Cristian Zamfir, George Candea +
    + ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) +
    + April 13-16, 2010, Paris, France +

    +
    5. + +
  5. + + + Reverse Engineering of Binary Device Drivers with RevNIC + + +
    + Vitaly Chipounov, George Candea +
    + ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) +
    + April 13-16, 2010, Paris, France +

    +
    6. + +
  6. + + + Testing Closed-Source Binary Device Drivers with DDT + + +
    + Volodymyr Kuznetsov, Vitaly Chipounov, George Candea +
    + USENIX Annual Technical Conference (USENIX ATC 2010) +
    + June 22-25, 2010, Boston, MA, USA +

    +
    7. + +
  7. + + + Stable Deterministic Multithreading through Schedule Memoization + + +
    + Heming Cui, Jingyue Wu, Chia-che Tsai, Junfeng Yang +
    + USENIX Symposium on Operating Systems Design and Implementation (OSDI 2010) +
    + October 4-6, 2010, Vancouver, BC, Canada +

    +
    8. + +
  8. + + + AEG: Automatic Exploit Generation + + +
    + Thanassis Avgerinos, Sang Kil Cha, Brent Lim Tze Hao, David Brumley +
    + Network and Distributed System Security Symposium (NDSS 2011) +
    + February 6-9, 2011, San Diego, CA, USA +

    +
    9. + +
  9. + + + Howard: A Dynamic Excavator for Reverse Engineering Data Structures + + +
    + Asia Slowinska, Traian Stancescu, Herbert Bos +
    + Network and Distributed System Security Symposium (NDSS 2011) +
    + February 6-9, 2011, San Diego, CA, USA +

    +
    10. + +
  10. + + + S2E: A Platform for In Vivo Multi-Path Analysis of Software Systems + + +
    + Vitaly Chipounov, Volodymyr Kuznetsov, George Candea +
    + International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS 2011) +
    + March 5-11, 2011, Newport Beach, CA +
    + S2E is available here. +

    +
    11. + +
  11. + + + Parallel Symbolic Execution for Automated Real-World Software Testing + + +
    + ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) +
    + Stefan Bucur, Vlad Ureche, Cristian Zamfir, George Candea +
    + April 10-13, 2011, Salzburg, Austria +
    + Cloud9 is available here. +

    +
    12. + +
  12. + + + Symbolic Crosschecking of Floating-Point and SIMD Code + + +
    + Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly +
    + ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) +
    + April 10-13, 2011, Salzburg, Austria +

    +
    13. + +
  13. + + + Practical, Low-Effort Equivalence Verification of Real Code + + +
    + David Ramos, Dawson Engler +
    + Computer Aided Verification (CAV 2011) +
    + July 16-20, 2011, Snowbird, UT, USA +

    +
    14. + +
  14. + + + Scalable Symbolic Execution of Distributed Systems + + +
    + Raimondas Sasnauskas, Oscar Soria Dustmann, Benjamin Lucien Kaminski, + Carsten Weise, Stefan Kowalewski, Klaus Wehrle +
    + IEEE International Conference on Distributed Computing Systems (ICDCS 2011) +
    + June 20-24, 2011, Minneapolis, MN, USA +

    +
    15. + +
  15. + + + Efficient Deterministic Multithreading through Schedule Relaxation + + +
    + Heming Cui, Jingyue Wu, John Gallagher, Huayang Guo, Junfeng Yang +
    + ACM Symposium on Operating Systems Principles (SOSP 2011) +
    + October 23-26, 2011, Cascais, Portugal +

    +
    16. + +
  16. + + + KLOVER: A Symbolic Execution and Automatic Test Generation Tool for C++ Programs + + +
    + Guodong Li, Indradeep Ghosh and Sreeranga Rajan +
    + International Conference on Computer Aided Verification (CAV 2011) +
    + July 14-20, 2011, Cliff Lodge, Snowbird, UT, USA +

    +
    17. + +
  17. + + + Symbolic Testing of OpenCL Code + + +
    + Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly +
    + Haifa Verification Conference (HVC 2011) +
    + December 6-8, 2011, Haifa, Israel +

    +
    18. + +
  18. + + + GKLEE: Concolic Verification and Test Generation for GPUs + + +
    + Guodong Li, Peng Li, Geof Sawaya, Ganesh Gopalakrishnan, Indradeep Ghosh, and Sreeranga P. Rajan +
    + ACM Symposium on Principles and Practice of Parallel Programming (PPoPP 2012) +
    + February 25-29, 2012, New Orleans, LA, USA +
    + GKLEE is available here. +

    +
    19. + +
  19. + + + make test-zesti: A Symbolic Execution Solution for Improving Regression Testing + + +
    + Paul Dan Marinescu, Cristian Cadar +
    + International Conference on Software Engineering (ICSE 2012) +
    + June 2-9, 2012, Zurich, Switzerland +
    + ZESTI is available here. +

    +
    20. + +
  20. + + + BugRedux: Reproducing Field Failures for In-House Debugging + + +
    + Wei Jin, Alessandro Orso +
    + International Conference on Software Engineering (ICSE 2012) +
    + June 2-9, 2012, Zurich, Switzerland +
    + BugRedux is available here. +

    +
    21. + +
  21. + + + Efficient State Merging in Symbolic Execution + + +
    + Volodymyr Kuznetsov, Johannes Kinder, Stefan Bucur, George Candea +
    + Programming Language Design and Implementation (PLDI) +
    + June 11-16, 2012, Beijing, China +

    +
    22. + +
  22. + + + High-Coverage Symbolic Patch Testing + + +
    + Paul Dan Marinescu, Cristian Cadar +
    + SPIN Workshop on Model Checking of Software (SPIN 2012) +
    + July 23-24, 2012, Oxford, UK +

    +
    23. + +
  23. + + + Automatic Detection of Floating-Point Exceptions + + +
    + Peter C. Rigby, Earl T. Barr, Christian Bird, Premkumar Devanbu, Daniel M. German +
    + Principles of Programming Languages (POPL) +
    + January 23-25, 2013, Rome, Italy +

    +
    24. + +
  24. + + + Redundant State Detection for Dynamic Symbolic Execution + + +
    + Suhabe Bugrara, Dawson Engler +
    + USENIX Annual Technical Conference (USENIX ATC 2013) +
    + June 26-28, 2013, San Jose, California. +

    +
    25. + +
+
+ + diff --git a/www/TestingCoreutils.html b/www/TestingCoreutils.html new file mode 100644 index 00000000..7ae49302 --- /dev/null +++ b/www/TestingCoreutils.html @@ -0,0 +1,893 @@ + + + + + + KLEE - Coreutils Case Study + + + + + +
+ +

Coreutils Case Study

+ +

+ As a more detailed explanation of using KLEE, we will look at how we did our + testing of GNU + Coreutils using KLEE. +

+ +

This tutorial assumes that you have configured and built KLEE + with uclibc and POSIX runtime support. +

+ +

These tests were done on a 32-bit Linux machine. On a 64-bit + machine, we needed to also set the LD_LIBRARY_PATH environment + variable: + 

+    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64 (Fedora)
+    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/x86_64-linux-gnu (Ubuntu)
+
+

+ + + +

Step 1: Build coreutils with gcov

+ +

+ First you will need to download and unpack the source + for coreutils. In this + example we use version 6.11 (one version later than what was used for our + OSDI paper). +

+ +

+ Before we build with LLVM, let's build a version of coreutils + with gcov support. We will use this later to get coverage + information on the test cases produced by KLEE. +

+ +

+ From inside the coreutils directory, we'll do the usual + configure/make steps inside a subdirectory (obj-gcov). Here are the + steps: +

+ +
+ 
+coreutils-6.11$ mkdir obj-gcov
+coreutils-6.11$ cd obj-gcov
+obj-gcov$ ../configure --disable-nls CFLAGS="-g -fprofile-arcs -ftest-coverage"
+... verify that configure worked ...
+obj-gcov$ make
+obj-gcov$ make -C src arch hostname
+... verify that make worked ...
+
+ +

+ We build with --disable-nls because this adds a lot of extra + initialization in the C library which we are not interested in testing. Even + though these aren't the executables that KLEE will be running on, we want to + use the same compiler flags so that the test cases KLEE generates are most + likely to work correctly when run on the uninstrumented binaries. +

+ +

+ You should now have a set of coreutils in + the objc-gcov/src directory. For example: +

+ +
+ 
+obj-gcov$ cd src
+src$ ls -l ls echo cat
+-rwxr-xr-x 1 ddunbar ddunbar 164841 2009-07-25 20:58 cat
+-rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
+-rwxr-xr-x 1 ddunbar ddunbar 439712 2009-07-25 20:58 ls
+src$ ./cat --version
+cat (GNU coreutils) 6.11
+Copyright (C) 2008 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later 
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by Torbjorn Granlund and Richard M. Stallman.
+
+ +

+ In addition, these executables should be built with gcov support, + so if you run one it will write a .gcda into the current + directory. That file contains information about exactly what code was + executed when the program ran. See + the Gcov + Documentation for more information. We can use the gcov tool + itself to produce a human readable form of the coverage information. For + example: +

+ +
+ 
+src$ rm -f *.gcda # Get rid of any stale gcov files
+src$ ./echo
+
+src$ ls -l echo.gcda
+-rw-r--r-- 1 ddunbar ddunbar 1832 2009-08-04 21:14 echo.gcda
+src$ gcov echo
+File '../../src/system.h'
+Lines executed:0.00% of 47
+../../src/system.h:creating 'system.h.gcov'
+
+File '../../lib/timespec.h'
+Lines executed:0.00% of 2
+../../lib/timespec.h:creating 'timespec.h.gcov'
+
+File '../../lib/gettext.h'
+Lines executed:0.00% of 32
+../../lib/gettext.h:creating 'gettext.h.gcov'
+
+File '../../lib/openat.h'
+Lines executed:0.00% of 8
+../../lib/openat.h:creating 'openat.h.gcov'
+
+File '../../src/echo.c'
+Lines executed:18.81% of 101
+../../src/echo.c:creating 'echo.c.gcov'
+
+ +

+ By default gcov will show the number of lines executed in the + program (the .h files include code which was compiled + into echo.c). +

+ + + +

Step 2: Build coreutils with LLVM

+ +

+ One of the difficult parts of testing real software using KLEE is that it + must be first compiled so that the final program is an LLVM bitcode file and + not a linked executable. The software's build system may be set up to use + tools such as 'ar', 'libtool', and 'ld', which do not in general understand + LLVM bitcode files. +

+ +

+ It depends on the actual project what the best way to do this is. For + coreutils, we use a helper script klee-gcc, which acts + like llvm-gcc but adds additional arguments to cause it to emit + LLVM bitcode files and to call llvm-ld to link executables. This + is not a general solution, and your mileage may vary. +

+ + + +

+ As before, we will build in a separate directory so we can easily access + both the native executables and the LLVM versions. Here are the steps: +

+ +
+ 
+coreutils-6.11$ mkdir obj-llvm
+coreutils-6.11$ cd obj-llvm
+obj-llvm$ ../configure --disable-nls CFLAGS="-g"
+... verify that configure worked ...
+obj-llvm$ make CC=/full/path/to/klee/scripts/klee-gcc
+obj-llvm$ make -C src arch hostname CC=/full/path/to/klee/scripts/klee-gcc
+... verify that make worked ...
+
+ +

+ Notice that we made two changes. First, we don't want to add gcov + instrumentation in the binary we are going to test using KLEE, so we left of + the -fprofile-arcs -ftest-coverage flags. Second, when running + make, we set the CC variable to point to our klee-gcc + wrapper script. +

+ +

+ If all went well, you should now have LLVM bitcode versions of coreutils! For + example: +

+ +
+ 
+obj-llvm$ cd src
+src$ ls -l ls echo cat
+-rwxr-xr-x 1 ddunbar ddunbar 65 2009-07-25 23:40 cat
+-rwxr-xr-x 1 ddunbar ddunbar 66 2009-07-25 23:43 echo
+-rwxr-xr-x 1 ddunbar ddunbar 94 2009-07-25 23:38 ls
+src$ ./cat --version
+cat (GNU coreutils) 6.11
+Copyright (C) 2008 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later 
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+LLVM ERROR: JIT does not support inline asm!
+
+ +

+ You may notice some funny things going on. To start with, the files are way + too small! Since we are actually producing LLVM bitcode files, the operating + system can't run them directly. What llvm-ld does to make it so we + can still run the resulting outputs is write a little shell script which + uses the LLVM interpreter to run the binaries; the actual LLVM bitcode + files have .bc appended. If we look a little closer: +

+ +
+ 
+src$ cat ls
+#!/bin/sh
+lli=${LLVMINTERP-lli}
+exec $lli \
+    -load=/usr/lib/librt.so \
+    ls.bc ${1+"$@"}
+src$ ls -l ls.bc
+-rwxr-xr-x 1 ddunbar ddunbar 643640 2009-07-25 23:38 ls.bc
+
+ +

+ The other funny thing is that the version message doesn't all print out, the + LLVM interpreter emits a message about not supporting inline assembly. The + problem here is that glibc occasionally implements certain + operations using inline assembly, which the LLVM interpreter (lli) + doesn't understand. KLEE works around this problem by specially recognizing + certain common inline assembly sequences and turning them back into the + appropriate LLVM instructions before executing the binary. +

+ + + +

Step 3: Using KLEE as an interpreter

+ +

+ At its core, KLEE is just an interpreter for LLVM bitcode. For example, here + is how to run the same cat command we did before, using KLEE. Note, + this step requires that you configured and built KLEE with uclibc + and POSIX runtime support (if you didn't, you'll need to go do that + now). +

+ +
+ 
+src$ klee --libc=uclibc --posix-runtime ./cat.bc --version
+KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
+KLEE: output directory = "klee-out-3"
+KLEE: WARNING: undefined reference to function: __signbitl
+KLEE: WARNING: executable has module level assembly (ignoring)
+KLEE: WARNING: calling external: syscall(54, 0, 21505, 177325672)
+KLEE: WARNING: calling __user_main with extra arguments.
+KLEE: WARNING: calling external: getpagesize()
+KLEE: WARNING: calling external: vprintf(177640072, 183340048)
+cat (GNU coreutils) 6.11
+
+License GPLv3+: GNU GPL version 3 or later 
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by Torbjorn Granlund and Richard M. Stallman.
+KLEE: WARNING: calling close_stdout with extra arguments.
+Copyright (C) 2008 Free Software Foundation, Inc.
+KLEE: done: total instructions = 259357
+KLEE: done: completed paths = 1
+KLEE: done: generated tests = 1
+
+ +

+ We got a lot more output this time! Let's step through it, starting with the + KLEE command itself. The general form of a KLEE command line is first the + arguments for KLEE itself, then the LLVM bitcode file to execute + (cat.bc), and then any arguments to pass to the application + (--version in this case, as before). +

+ +

+ If we were running a normal native application, it would have been linked + with the C library, but in this case KLEE is running the LLVM bitcode file + directly. In order for KLEE to work effectively, it needs to have + definitions for all the external functions the program may call. We have + modified the uClibc C library + implementation for use with KLEE; the --libc=uclibc KLEE argument + tells KLEE to load that library and link it with the application before it + starts execution. +

+ +

+ Similarly, a native application would be running on top of an operating + system that provides lower level facilities like write(), which the + C library uses in its implementation. As before, KLEE needs definitions for + these functions in order to fully understand the program. We provide a POSIX + runtime which is designed to work with KLEE and the uClibc library to + provide the majority of operating system facilities used by command line + applications -- the --posix-runtime argument tells KLEE to link + this library in as well. +

+ +

+ As before, cat prints out its version information (note that this + time all the text is written out), but we now have a number of additional + information output by KLEE. In this case, most of these warnings are + innocuous, but for completeness here is what they mean: +

+ +
    +
  • undefined reference to function: __signbitl: This warning means + that the program contains a call to the function __signbitl, + but that function isn't defined anywhere (we would have seen a lot more + of these if we had not linked with uClibc and the POSIX runtime). If the + program actually ends up making a call to this function while it is + executing, KLEE won't be able to interpret it and may terminate the + program.
    • + +
  • executable has module level assembly (ignoring): Some file + compiled in to the application had file level inline-assembly, which KLEE + can't understand. In this case this comes from uClibc and is unused, so + this is safe.
    • + +
  • calling __user_main with extra arguments: This indicates that + the function was called with more arguments than it expected, it is + almost always innocuous. In this case __user_main is actually + the main() function for cat, which KLEE has renamed it + when linking with uClibc. main() is being called with + additional arguments by uClibc itself during startup, for example the + environment pointer.
    • + +
  • calling external: getpagesize(): This is an example of KLEE + calling a function which is used in the program but is never + defined. What KLEE actually does in such cases is try to call the native + version of the function, if it exists. This is sometimes safe, as long + as that function does write to any of the programs memory or attempt to + manipulate symbolic values. getpagesize(), for example, just + returns a constant.
    • +
+ +

+ In general, KLEE will only emit a given warning once. The warnings are also + logged to warnings.txt in the KLEE output directory. +

+ + + +

Step 4: Introducing symbolic data to an application

+ +

+ We've seen that KLEE can interpret a program normally, but the real purpose + of KLEE is to explore programs more exhaustively by making parts of their + input symbolic. For example, lets look at running KLEE on the echo + application. +

+ +

+ When using uClibc and the POSIX runtime, KLEE replaces the + program's main() function with a special function + (klee_init_env) provided inside the runtime library. This + function alters the normal command line processing of the + application, in particular to support construction of symbolic + arguments. For example, passing --help yields: +

+ +
+ 
+src$ klee --libc=uclibc --posix-runtime ./echo.bc --help
+...
+
+usage: (klee_init_env) [options] [program arguments]
+  -sym-arg               - Replace by a symbolic argument with length N
+  -sym-args    - Replace by at least MIN arguments and at most
+                              MAX arguments, each with maximum length N
+  -sym-files        - Make stdin and up to NUM symbolic files, each
+                              with maximum size N.
+  -sym-stdout               - Make stdout symbolic.
+  -max-fail              - Allow up to  injected failures
+  -fd-fail                  - Shortcut for '-max-fail 1'
+...
+
+ +

+ As an example, lets run echo with a symbolic argument of 3 + characters. +

+ +
+ 
+src$ klee --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
+KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
+KLEE: output directory = "klee-out-16"
+KLEE: WARNING: undefined reference to function: __signbitl
+KLEE: WARNING: executable has module level assembly (ignoring)
+KLEE: WARNING: calling external: syscall(54, 0, 21505, 189414856)
+KLEE: WARNING: calling __user_main with extra arguments.
+..
+KLEE: WARNING: calling close_stdout with extra arguments.
+...
+KLEE: WARNING: calling external: printf(183664896, 183580400)
+Usage: ./echo.bc [OPTION]... [STRING]...
+Echo the STRING(s) to standard output.
+
+  -n             do not output the trailing newline
+  -e             enable interpretation of backslash escapes
+  -E             disable interpretation of backslash escapes (default)
+      --help     display this help and exit
+      --version  output version information and exit
+
+If -e is in effect, the following sequences are recognized:
+
+  \0NNN   the character whose ASCII code is NNN (octal)
+  \\     backslash
+  \a     alert (BEL)
+  \b     backspace
+  \c     suppress trailing newline
+  \f     form feed
+  \n     new line
+  \r     carriage return
+  \t     horizontal tab
+  \v     vertical tab
+
+NOTE: your shell may have its own version of echo, which usually supersedes
+the version described here.  Please refer to your shell's documentation
+for details about the options it supports.
+
+Report bugs to .
+KLEE: WARNING: calling external: vprintf(183956664, 190534360)
+echo (GNU coreutils) 6.11
+
+License GPLv3+: GNU GPL version 3 or later 
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by FIXME unknown.
+...
+...
+...
+
+
+
+
+..
+
+
+.
+
+.
+..
+...
+Copyright (C) 2008 Free Software Foundation, Inc.
+KLEE: done: total instructions = 300193
+KLEE: done: completed paths = 25
+KLEE: done: generated tests = 25
+
+ +

+ The results here are slightly more interesting, KLEE has explored 25 paths + through the program. The output from all the paths is intermingled, but you + can see that in addition to echoing various random characters, some blocks + of text also were output. You may be suprised to learn that + coreutils' echo takes some arguments, in this case the + options --v (short for --version) and --h (short + for --help) were explored. We can get a short summary of KLEE's + internal statistics by running klee-stats on the output directory + (remember, KLEE always makes a symlink called klee-last to the most + recent output directory). +

+ +
+ 
+src$ klee-stats klee-last
+-------------------------------------------------------------------------
+| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
+-------------------------------------------------------------------------
+| klee-last | 300673 |    1.47 |   28.18 |   17.37 |  28635 |      5.65 |
+-------------------------------------------------------------------------
+
+ +

+ Here ICov is the percentage of LLVM instructions which were + covered, and BCov is the percentage of branches that were + covered. You may be wondering why the percentages are so low -- how much + more code can echo have! The main reason is that these numbers are computed + using all the instructions or branches in the bitcode files; that includes a + lot of library code which may not even be executable. We can help with that + problem (and others) by passing the --optimize option to KLEE. This + will cause KLEE to run the LLVM optimization passes on the bitcode module + before executing it; in particular they will remove any dead code. When + working with non-trivial applications, it is almost always a good idea to + use this flag. Here are the results from running again + with --optimze enabled: +

+ +
+ 
+src$ klee --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
+...
+KLEE: done: total instructions = 123251
+KLEE: done: completed paths = 25
+KLEE: done: generated tests = 25
+src$ klee-stats klee-last
+-------------------------------------------------------------------------
+| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
+-------------------------------------------------------------------------
+| klee-last | 123251 |    0.32 |   38.02 |   25.43 |   9531 |     29.66 |
+-------------------------------------------------------------------------
+
+ +

+ This time the instruction coverage went up by about ten percent, and you can + see that KLEE also ran faster and executed less instructions. Most of the + remaining code is still in library functions, just in places that the + optimizers aren't smart enough to remove. We can verify this -- and look for + uncovered code inside echo -- by using KCachegrind to visualize the + results of a KLEE run. +

+ + + +

Step 5: Visualizing KLEE's progress with kcachegrind

+ +

+ KCachegrind is an excellent + profiling visualization tool, originally written for use with the callgrind + plugin for valgrind. If you don't have it already, it is usually easily + available on a modern Linux distribution via your platforms' software + installation tool (e.g., apt-get or yum). +

+ +

+ KLEE by default writes out a run.istats file into the test output + directory which is actually a KCachegrind file. In this example, + the run.istats is from a run without --optimize, so the + results are easier to understand. Assuming you have KCachegrind installed, + just run: +

+ +
+ 
 src$ kcachegrind klee-last/run.istats
+
+ +

+ After KCachegrind opens, you should see a window that looks something like + the one below. You should make sure that the "Instructions" statistic is + selected by choosing "View" > "Primary Event Type" > "Instructions" + from the menu, and make sure the "Source Code" view is selected (the right + hand pane in the screenshot below). +

+ + + + +

+ KCachegrind is a complex application in itself, and interested users should + see the KCachegrind website for more information and documentation. However, + the basics are that the one pane shows the "Flat Profile"; this is a list of + which how many instructions were executed in each function. The "Self" + column is the number of instructions which were executed in the function + itself, and the "Incl" (inclusive) column is the number of instructions + which were executed in the function, or any of the functions it called (or + its callees called, and so on). +

+ +

+ KLEE includes quite a few statistics about execution. The one we are + interested in now is "Uncovered Instructions", which will show which + functions have instructions which were never executed. If you select that + statistic and resort the list of functions, you should see something like + this: +

+ + + + +

+ Notice that most of the uncovered instructions are in library code as we + would expect. However, if we select the __user_main function, we + can look for code inside echo itself that was uncovered. In this + case, most of the uncovered instructions are inside a large if + statement guarded by the variable do_v9. If you look a bit more, + you can see that this is a flag set to true when -e is passed. The + reason that KLEE never explored this code is because we only passed one + symbolic argument -- hitting this code requires a command line like $ + echo -e \a. +

+ +

+ One subtle thing to understand if you are trying to actually make sense of + the KCachegrind numbers is that they include events accumulated across all + states. For example, consider the following code: +

+ +
+ 
+Line 1:      a = 1;
+Line 2:      if (...)
+Line 3:        printf("hello\n");
+Line 4:      b = c;
+
+ +

+ In a normal application, if the statement on Line 1 was only executed once, + then the statement on Line 4 could be (at most) executed once. When KLEE is + running an application, however, it could fork and generate separate + processes at Line 2. In that case, Line 4 may be executed more times than + Line 1! +

+ +

+ Another useful tidbit: KLEE actually writes the run.istats file + periodically as the application is running. This provides one way to monitor + the status of long running applications (another way is to use the + klee-stats tool). +

+ + + +

Step 6: Replaying KLEE generated test cases

+ +

+ Let's step away from KLEE for a bit and look at just the test cases KLEE + generated. If we look inside the klee-last we should see + 25 .ktest files. +

+ +
+ 
+src$ ls klee-last
+assembly.ll	  test000004.ktest  test000012.ktest  test000020.ktest
+info		  test000005.ktest  test000013.ktest  test000021.ktest
+messages.txt	  test000006.ktest  test000014.ktest  test000022.ktest
+run.istats	  test000007.ktest  test000015.ktest  test000023.ktest
+run.stats	  test000008.ktest  test000016.ktest  test000024.ktest
+test000001.ktest  test000009.ktest  test000017.ktest  test000025.ktest
+test000002.ktest  test000010.ktest  test000018.ktest  warnings.txt
+test000003.ktest  test000011.ktest  test000019.ktest
+
+ +

+ These files contain the actual values to use for the symbolic data in order + to reproduce the path that KLEE followed (either for obtaining code + coverage, or for reproducing a bug). They also contain additional metadata + generated by the POSIX runtime in order to track what the values correspond + to and the version of the runtime. We can look at the individual contents of + one file using ktest-tool: +

+ +
+ 
+$ ktest-tool klee-last/test000001.ktest
+ktest file : 'klee-last/test000001.ktest'
+args       : ['./echo.bc', '--sym-arg', '3']
+num objects: 2
+object    0: name: 'arg0'
+object    0: size: 4
+object    0: data: '@@@\x00'
+object    1: name: 'model_version'
+object    1: size: 4
+object    1: data: '\x01\x00\x00\x00'
+
+ +

+ In this case, the test case indicates that values "@@@\x00" should be passed + as the first argument. However, .ktest files generally aren't + really meant to be looked at directly. For the POSIX runtime, we provide a + tool klee-replay which can be used to read the .ktest file + and invoke the native application, automatically passing it the data + necessary to reproduce the path that KLEE followed. +

+ +

+ To see how it works, go back to the directory where we built the native + executables: +

+ +
+ 
+src$ cd ..
+obj-llvm$ cd ..
+coreutils-6.11$ cd obj-gcov
+obj-gcov$ cd src
+src$ ls -l echo
+-rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
+
+ +

+ To use the klee-replay tool, we just tell it the executable to run + and the .ktest file to use. The program arguments, input files, + etc. will all be constructed from the data in the .ktest file. +

+ +
+ 
+src$ klee-replay ./echo ../../obj-llvm/src/klee-last/test000001.ktest 
+klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
+klee-replay: ARGS: "./echo" "@@@" 
+@@@
+klee-replay: EXIT STATUS: NORMAL (0 seconds)
+
+ +

+ The first two and last lines here come from the klee-replay tool + itself. The first two lines list the test case being run, and the concrete + values for arguments that are being passed to the application (notice this + matches what we saw in the .ktest file earlier). The last line is + the exit status of the program and the elapsed time to run. +

+ +

+ We can also use the klee-replay tool to run a set of test cases at + once, one after the other. Let's do this and compare the gcov + coverage to the numbers we got from klee-stats: +

+ +
+ 
+src$ rm -f *.gcda # Get rid of any stale gcov files
+src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
+klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
+klee-replay: ARGS: "./echo" "@@@" 
+@@@
+klee-replay: EXIT STATUS: NORMAL (0 seconds)
+...
+klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000022.ktest
+klee-replay: ARGS: "./echo" "--v" 
+echo (GNU coreutils) 6.11
+Copyright (C) 2008 Free Software Foundation, Inc.
+...
+
+src$ gcov echo
+File '../../src/system.h'
+Lines executed:6.38% of 47
+../../src/system.h:creating 'system.h.gcov'
+
+File '../../lib/timespec.h'
+Lines executed:0.00% of 2
+../../lib/timespec.h:creating 'timespec.h.gcov'
+
+File '../../lib/gettext.h'
+Lines executed:0.00% of 32
+../../lib/gettext.h:creating 'gettext.h.gcov'
+
+File '../../lib/openat.h'
+Lines executed:0.00% of 8
+../../lib/openat.h:creating 'openat.h.gcov'
+
+File '../../src/echo.c'
+Lines executed:50.50% of 101
+../../src/echo.c:creating 'echo.c.gcov'
+
+ +

+ The number for echo.c here significantly higher than + the klee-stats number because gcov is only considering + lines in that one file, not the entire application. As with kcachegrind, we can inspect the coverage file output by gcov to see exactly what lines were covered and which weren't. Here is a fragment from the output: +

+ +
+ 
+        -:  193:      }
+        -:  194:
+       23:  195:just_echo:
+        -:  196:
+       23:  197:  if (do_v9)
+        -:  198:    {
+       10:  199:      while (argc > 0)
+        -:  200:	{
+    #####:  201:	  char const *s = argv[0];
+        -:  202:	  unsigned char c;
+        -:  203:
+    #####:  204:	  while ((c = *s++))
+        -:  205:	    {
+    #####:  206:	      if (c == '\\' && *s)
+        -:  207:		{
+    #####:  208:		  switch (c = *s++)
+        -:  209:		    {
+    #####:  210:		    case 'a': c = '\a'; break;
+    #####:  211:		    case 'b': c = '\b'; break;
+    #####:  212:		    case 'c': exit (EXIT_SUCCESS);
+    #####:  213:		    case 'f': c = '\f'; break;
+    #####:  214:		    case 'n': c = '\n'; break;
+
+ +

+ The far left hand column is the number of times each line was + executed; - means the line has no executable code, and ##### + means the line was never covered. As you can see, the uncovered lines here + correspond exactly to the uncovered lines as reported + in kcachegrind. +

+ +

+ Before moving on to testing more complex applications, lets make sure we can + get decent coverage of the simple echo.c. The problem before was + that we weren't making enough data symbolic, providing echo with two + symbolic arguments should be plenty to cover the entire program. We can use + the POSIX runtime --sym-args option to pass multiple options. Here + are the steps, after switching back to the obj-llvm/src directory: +

+ +
+ 
+src$ klee --only-output-states-covering-new --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-args 0 2 4
+ ... 
+KLEE: done: total instructions = 7437521
+KLEE: done: completed paths = 9963
+KLEE: done: generated tests = 55
+
+ +

+ The format of the --sym-args option actually specifies a minimum + and a maximum number of arguments to pass and the length to use for each + argument. In this case --sym-args 0 2 4 says to pass between 0 and + 2 arguments (inclusive), each with a maximum length of four characters. +

+ +

+ We also added the --only-output-states-covering-new option to the + KLEE command line. By default KLEE will write out test cases for every path + it explores. This becomes less useful once the program becomes larger, because many test cases will end up + exercise the same paths, and computing (or even reexecuting) each one wastes + time. Using this option tells KLEE to only output test cases for paths which + covered some new instruction in the code (or hit an error). The final lines + of the output show that even though KLEE explored almost ten thousand paths + through the code, it only needed to write 55 test cases. +

+ +

+ If we go back to the obj-gcov/src directory and rerun the latest + set of test cases, we finally have reasonable coverage of echo.c: +

+ +
+ 
+src$ rm -f *.gcda # Get rid of any stale gcov files
+src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
+klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
+klee-replay: ARGS: "./echo" 
+
+ ... 
+
+src$ gcov echo
+File '../../src/system.h'
+Lines executed:6.38% of 47
+../../src/system.h:creating 'system.h.gcov'
+
+File '../../lib/timespec.h'
+Lines executed:0.00% of 2
+../../lib/timespec.h:creating 'timespec.h.gcov'
+
+File '../../lib/gettext.h'
+Lines executed:0.00% of 32
+../../lib/gettext.h:creating 'gettext.h.gcov'
+
+File '../../lib/openat.h'
+Lines executed:0.00% of 8
+../../lib/openat.h:creating 'openat.h.gcov'
+
+File '../../src/echo.c'
+Lines executed:97.03% of 101
+../../src/echo.c:creating 'echo.c.gcov'
+
+ +

+ The reasons for not getting perfect 100% line coverage are left as an + exercise to the reader. :) +

+ + + +

Step 7: Using zcov to analyze coverage

+ +

+ For visualizing the coverage results, you might want to use the zcov tool. +

+
+ +
+ + diff --git a/www/Tutorial-1.html b/www/Tutorial-1.html new file mode 100644 index 00000000..38c3b101 --- /dev/null +++ b/www/Tutorial-1.html @@ -0,0 +1,187 @@ + + + + + + KLEE - Tutorial One + + + + + +
+ +

Tutorial One: Testing a Small Function

+ + +

The demo code

+ + This tutorial walks you through the main steps needed to test a + simple function with KLEE. Here is our simple function: + + 
+  int get_sign(int x) {
+    if (x == 0)
+       return 0;
+
+    if (x < 0)
+       return -1;
+    else 
+       return 1;
+  }
+ + You can find the entire code for this example in the source tree + under examples/get_sign. A version of the source code can + also be accessed here. + +

Marking input as symbolic

+ + In order to test this function with KLEE, we need to run it + on symbolic input. To mark a variable as symbolic, we use + the klee_make_symbolic() function, which takes three + arguments: the address of the variable (memory location) that we + want to treat as symbolic, its size, and a name (which can be + anything). Here is a simple main() function that marks a + variable a as symbolic and uses it to + call get_sign(): + + 
+  int main() {
+      int a;
+      klee_make_symbolic(&a, sizeof(a), "a");
+      return get_sign(a);
+  }
+ + + +

Compiling to LLVM bitcode

+ + KLEE operates on LLVM bitcode. To run a program with KLEE, you + first compile it to LLVM bitcode using llvm-gcc + --emit-llvm. Assuming our code is stored in get_sign.c, + we run: + +
+ llvm-gcc --emit-llvm -c -g get_sign.c +
+ + to generate the LLVM bitcode file get_sign.o. + + It is useful to (1) build with -g to add debug information + to the bitcode file, which we use to generate source line level + statistics information, and (2) not use any optimization flags. The + code can be optimized later, as KLEE provides the + --optimize command line option to run the optimizer + internally. + +

Running KLEE

+ + To run KLEE on the bitcode file simply execute: + +
+ klee get_sign.o +
+ + You should see the following output (assumes LLVM 2.8): + 
+  KLEE: output directory = "klee-out-0"
+
+  KLEE: done: total instructions = 51
+  KLEE: done: completed paths = 3
+  KLEE: done: generated tests = 3
+ + There are three paths through our simple function, one + where a is 0, one where it is less than 0 + and one where it is greater than 0. + + As expected, KLEE informs us that it explored three paths in the + program and generated one test case for each path explored. The + output of a KLEE execution is a directory (in our + case klee-out-0) containing the test cases generated by + KLEE. KLEE names the output directory klee-out-N where N + is the lowest available number (so if we run KLEE again it will + create a directory called klee-out-1), and also generates a + symbolic link called klee-last to this directory for + convenience: + + 
+  $ ls klee-last/
+  assembly.ll      run.istats       test000002.ktest
+  info             run.stats        test000003.ktest
+  messages.txt     test000001.ktest warnings.txt
+ + Please click here if you would like an + overview of the files generated by KLEE. In this tutorial, we only + focus on the actual test files generated by KLEE. + +

KLEE-generated test cases

The test cases generated by KLEE + are written in files with extension .ktest. These are + binary files, which can be read with the ktest-tool + utility. So let's examine each file: + + 
+  $ ktest-tool --write-ints klee-last/test000001.ktest 
+  ktest file : 'klee-last/test000001.ktest'
+  args       : ['get_sign.o']
+  num objects: 1
+  object    0: name: 'a'
+  object    0: size: 4
+  object    0: data: 1
+  
+  $ ktest-tool --write-ints klee-last/test000002.ktest  
+  ...
+  object    0: data: -2147483648
+
+  $ ktest-tool --write-ints klee-last/test000003.ktest 
+  ...
+  object    0: data: 0
+ + In each test file, KLEE reports the arguments with which the program + was invoked (in our case no arguments other than the program name + itself), the number of symbolic objects on that path (only one in + our case), the name of our symbolic object ('a') and its size (4). + The actual test itself is represented by the value of our + input: 1 for the first test, -2147483648 for the + second and 0 for the last one. As expected, KLEE generated + value 0, one negative value (-2147483648), and one + positive value (1). We can now run these values on a + native version of our program, to exercise all paths through the + code! + + +

Replaying a test case

+ + While we can run the test cases generated by KLEE on our program by + hand, (or with the help of an existing test infrastructure), KLEE + provides a convenient replay library, which simply replaces + the call to klee_make_symbolic with a call to a function + that assigns to our input the value stored in the .ktest + file. + + To use it, simply link your program with the libkleeRuntest + library and set the KTEST_FILE environment variable to + point to the name of the desired test case: + + 
+  $ export LD_LIBRARY_PATH=path-to-klee-root/Release+Asserts/lib/:$LD_LIBRARY_PATH
+  $ gcc -L path-to-klee-root/Release+Asserts/lib/ get_sign.c -lkleeRuntest
+  $ KTEST_FILE=klee-last/test000001.ktest ./a.out 
+  $ echo $?
+  1
+  $ KTEST_FILE=klee-last/test000002.ktest ./a.out 
+  $ echo $?
+  255
+  $ KTEST_FILE=klee-last/test000003.ktest ./a.out
+  $ echo $?
+  0
+ + As expected, our program returns 1 when running the first test case, + 255 (-1 converted to a valid exit code value in the 0-255 range) + when running the second one, and 0 when running the last one. + +

+ +
+ + diff --git a/www/Tutorial-2.html b/www/Tutorial-2.html new file mode 100644 index 00000000..47187a45 --- /dev/null +++ b/www/Tutorial-2.html @@ -0,0 +1,287 @@ + + + + + KLEE - Tutorial Two + + + + + + + +
+ +

Tutorial Two: Testing a Simple Regular Expression Library

+ +

This is an example of using KLEE to test a simple regular expression matching +function. You can find the basic example in the source tree +under examples/regexp.

+ +

Regexp.c contains a simple regular expression matching function, and +the bare bones testing harness (in main) needed to explore this code +with klee. You can see a version of the source +code here.

+ +

This example will show to build and run the example using KLEE, as well as +how to interpret the output, and some additional KLEE features that can be used +when writing a test driver by hand.

+ +

We'll start by showing how to build and run the example, and then explain how +the test harness works in more detail.

+ +

Building the example

+ +

The first step is to compile the source code using a compiler which can +generate object files in LLVM bitcode format. Here we use llvm-gcc, +but Clang works just as well!

+ +

From within the examples/regexp directory: +

+ $ llvm-gcc -I ../../include -emit-llvm -c -g Regexp.c +
+which should create a Regexp.o file in LLVM bitcode +format. The -I argument is used so that the compiler can +find "klee/klee.h", +which contains definitions for the intrinsic functions used to interact with the +KLEE virtual machine. -c is used because we only want to compile the +code to an object file (not a native executable), and finally -g causes +additional debug information to be stored in the object file, which KLEE will +use to determine source line number information.

+ +

If you have the LLVM tools installed in your path, you can verify that this step +worked by running llvm-nm on the generated file:

+
+
+  $ llvm-nm Regexp.o
+         t matchstar
+         t matchhere
+         T match
+         T main
+         U klee_make_symbolic_name
+         d LC
+         d LC1
+
+
+ +

Normally before running this program we would need to link it to create a +native executable. However, KLEE runs directly on LLVM bitcode files -- since +this program only has a single file there is no need to link. For "real" +programs with multiple inputs, +the llvm-link +and llvm-ld tools can +be used in place of the regular link step to merge multiple LLVM bitcode files +into a single module which can be executed by KLEE.

+ +

Executing the code with KLEE

+ + +

The next step is to execute the code with KLEE:

+
+
+$ klee --only-output-states-covering-new Regexp.o
+KLEE: output directory = "klee-out-1"
+KLEE: ERROR: .../klee/examples/regexp/Regexp.c:23: memory error: out of bound pointer
+KLEE: NOTE: now ignoring this error at this location
+KLEE: ERROR: .../klee/examples/regexp/Regexp.c:25: memory error: out of bound pointer
+KLEE: NOTE: now ignoring this error at this location
+KLEE: done: total instructions = 6334861
+KLEE: done: completed paths = 7692
+KLEE: done: generated tests = 22
+
+
+ +

On startup, KLEE prints the directory used to store output (in this +case klee-out-1). By default klee will use the first +free klee-out-N directory and also create a klee-last +symlink which will point to the most recent created directory. You can specify a +directory to use for outputs using the -output-dir=path +command line argument.

+ +

While KLEE is running, it will print status messages for "important" events, +for example when it finds an error in the program. In this case, KLEE detected +to invalid memory accesses on lines 23 and 25 of our test program. We'll look +more at this in a moment.

+ +

Finally, when KLEE finishes execution it prints out a few statistics about +the run. Here we see that KLEE executed a total of ~6 million instructions, +explored 7,692 paths, and generated 22 test cases.

+ +

Note that many realistic programs have an infinite (or extremely large) +number of paths through them, and it is common that KLEE will not terminate. By +default KLEE will run until the user presses Control-C (i.e. klee gets +a SIGINT), but there are additional options to limit KLEE's runtime and memory +usage:

+

    +
  • -max-time=seconds: Halt execution after the given number + of seconds.
    • +
  • -max-forks=N: Stop forking after N symbolic + branches, and run the remaining paths to termination.
    • +
  • -max-memory=N: Try to limit memory consumption + to N megabytes.
    • +
+

+ +

KLEE error reports

+ +

When KLEE detects an error in the program being executed it will generate a +test case which exhibits the error, and write some additional information about +the error into a file testN.TYPE.err, where N is +the test case number, and TYPE identifies the kind of error. Some +types of errors KLEE detects include:

+ +
    +
  • ptr: Stores or loads of invalid memory locations.
    • + +
  • free: Double or invalid free().
    • + +
  • abort: The program called abort().
    • + +
  • assert: An assertion failed.
    • + +
  • div: A division or modulus by zero was detected.
    • + +
  • user: There is a problem with the input (invalid klee + intrinsic calls) or the way KLEE is being used.
    • + +
  • exec: There was a problem which prevented KLEE from executing the + program; for example an unknown instruction, a call to an invalid function + pointer, or inline assembly.
    • + +
  • model: KLEE was unable to keep full precision and is only exploring + parts of the program state. For example, symbolic sizes to malloc are + not currently supported, in such cases KLEE will concretize the argument.
    • +
+ +

KLEE will print a message to the console when it detects an error, in the +test run above we can see that KLEE detected two memory errors. For all program +errors, KLEE will write a simple backtrace into the .err file. This is +what one of the errors above looks like:

+
+
+Error: memory error: out of bound pointer
+File: .../klee/examples/regexp/Regexp.c
+Line: 23
+Stack: 
+	#0 00000146 in matchhere (re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:23
+	#1 00000074 in matchstar (c, re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:16
+	#2 00000172 in matchhere (re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:26
+	#3 00000074 in matchstar (c, re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:16
+	#4 00000172 in matchhere (re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:26
+	#5 00000074 in matchstar (c, re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:16
+	#6 00000172 in matchhere (re=14816465, text=14815301) at .../klee/examples/regexp/Regexp.c:26
+	#7 00000231 in matchhere (re=14816464, text=14815300) at .../klee/examples/regexp/Regexp.c:30
+	#8 00000280 in match (re=14816464, text=14815296) at .../klee/examples/regexp/Regexp.c:38
+	#9 00000327 in main () at .../klee/examples/regexp/Regexp.c:59
+Info: 
+	address: 14816471
+	next: object at 14816624 of size 4
+	prev: object at 14816464 of size 7
+
+
+ +

Each line of the backtrace lists the frame number, the instruction line (this +is the line number in the assembly.ll file found along with the run +output), the function and arguments (including values for the concrete +parameters), and the source information.

+ +

Particular error reports may also include additional information. For memory +errors, KLEE will show the invalid address, and what objects are on the heap +both before and after that address. In this case, we can see that the address +happens to be exactly one byte past the end of the previous object.

+ +

Changing the test harness

+ +

The reason KLEE is finding memory errors in this program isn't because the +regular expression functions have a bug, rather it indicates a problem in our +test driver. The problem is that we are making the input regular expression +buffer completely symbolic, but the match function expects it to be a +null terminated string. Let's look at two ways we can fix this.

+ +

The simplest way to fix this problem is to store '\0' at the end of +the buffer, after making it symbolic. This makes our driver look like this:

+
+
+int main() {
+  // The input regular expression.
+  char re[SIZE];
+  
+  // Make the input symbolic. 
+  klee_make_symbolic(re, sizeof re, "re");
+  re[SIZE - 1] = '\0';
+
+  // Try to match against a constant string "hello".
+  match(re, "hello");
+
+  return 0;
+}
+
+
+

Making a buffer symbolic just initializes the contents to refer to symbolic +variables, we are still free to modify the memory as we wish. If you recompile +and run klee on this test program, the memory errors should now be +gone.

+ +

Another way to accomplish the same effect is to use the klee_assume +intrinsic function. klee_assume takes a single argument (an unsigned +integer) which generally should some kind of conditional expression, and +"assumes" that expression to be true on the current path (if that can never +happen, i.e. the expression is provably false, KLEE will report an error). + +

We can use klee_assume to cause KLEE to only explore states where +the string is null terminated by writing the driver like this:

+
+
+int main() {
+  // The input regular expression.
+  char re[SIZE];
+  
+  // Make the input symbolic. 
+  klee_make_symbolic(re, sizeof re, "re");
+  klee_assume(re[SIZE - 1] == '\0');
+
+  // Try to match against a constant string "hello".
+  match(re, "hello");
+
+  return 0;
+}
+
+
+

In this particular example, both solutions work fine, but in +general klee_assume is more flexible:

+
    +
  • By explicitly declaring the constraint, this will force test cases to have + the '\0' in them. In the first example where we write the terminating + null explicitly, it doesn't matter what the last byte of the symbolic input is + and KLEE is free to generate any value. In some cases where you want to + inspect the test cases by hand, it is more convenient for the test case to + show all the values that matter.
    • + +
  • klee_assume can be used to encode more complicated + constraints. For example, we could use klee_assume(re[0] != '^') to + cause KLEE to only explore states where the first byte is + not '^'.
    • +
+ +

NOTE: One important caveat when using klee_assume with +multiple conditions; remember that boolean conditionals like '&&' and '||' may +be compiled into code which branches before computing the result of the +expression. In such situations KLEE will branch the process *before* it reaches +the call to klee_assume, which may result in exploring unnecessary +additional states. For this reason it is good to use as simple expressions as +possible to klee_assume (for example splitting a single call into +multiple ones), and to use the '&' and '|' operators instead of the +short-circuiting ones.

+ + + +
+ + diff --git a/www/Tutorials.html b/www/Tutorials.html new file mode 100644 index 00000000..e063a9a8 --- /dev/null +++ b/www/Tutorials.html @@ -0,0 +1,38 @@ + + + + + + KLEE - Tutorials + + + + + +
+ +

KLEE Tutorials

+ + +
    +
  1. Tutorial One: Testing a small function.
    2. + +
  2. Tutorial Two: Testing a simple regular + expression library.
    3. + +
  3. + Solving a maze with KLEE: A nice explanation of how symbolic + execution can be used to generate interesting program + inputs. The example shows how to use KLEE to find all the + solutions to a maze game. +
    4. + +
  4. Testing Coreutils: In-depth + description of how to use KLEE to test GNU Coreutils.
    5. +
+ + +
+ + diff --git a/www/bugs.html b/www/bugs.html new file mode 100644 index 00000000..1ac9421a --- /dev/null +++ b/www/bugs.html @@ -0,0 +1,24 @@ + + + + + + The KLEE Symbolic Virtual Machine + + + + + +
+ +

KLEE Bug Reports

+ + + Please report any bugs in KLEE to + the klee-dev mailing list. You need to + be subscribe to the list in order to send your report. + +
+ + diff --git a/www/content.css b/www/content.css new file mode 100644 index 00000000..50835ec3 --- /dev/null +++ b/www/content.css @@ -0,0 +1,75 @@ +html, body { + padding:0px; + font-size:small; + font-family:"Lucida Grande", "Lucida Sans Unicode", Arial, Verdana, Helvetica, sans-serif; + background-color: #fff; color: #222; + line-height:1.5; +} + +h1, h2, h3, tt { color: #000 } + +h1 { color:#000000; padding-top: 0px; margin-top:0px;} +h2 { color:#333333; padding-top: 0.5em; } +h3 { color:#2d58b7; padding-top: 0.5em; margin-bottom: -0.25em; } +h4 { color:#2d58b7; } +li { padding-bottom: 0.5em; } +ul { padding-left:1.5em; } + +/* Slides */ +IMG.img_slide { + display: block; + margin-left: auto; + margin-right: auto +} + +.itemTitle { color:#2d58b7 } + +/* Tables */ +tr { vertical-align:top } + +/* Syntax */ +div.syntax { + border: 1px solid LightSteelBlue ; + font-family: Courier New; + background-color: SeaShell; + padding: 7px; + margin: 7px; +} + +/* Examples */ +div.example { + border: 1px solid LightSteelBlue ; + font-family: Courier New; + background-color: #E3E3E3; + padding: 7px; + margin: 7px; +} + +/* Instructions */ +div.instr { + border: 1px solid LightSteelBlue ; + font-family: Courier New; + background-color: #E3E3E3; + padding: 7px; + margin: 7px; +} + +/* Output */ +pre.output { + border: 1px solid LightSteelBlue ; + font-family: Courier New; + background-color: #E3E3E3; + padding: 7px; + margin: 7px; +} + +/* Code */ +pre.code{ + display:table; + border: 1px solid LightSteelBlue ; + font-family: Courier New; + background-color: #E3E3E3; + margin: 10px; + padding: 10px; +} + diff --git a/www/content/coreutils_kc_0.png b/www/content/coreutils_kc_0.png new file mode 100644 index 00000000..3f72dc49 Binary files /dev/null and b/www/content/coreutils_kc_0.png differ diff --git a/www/content/coreutils_kc_1.png b/www/content/coreutils_kc_1.png new file mode 100644 index 00000000..d4372f26 Binary files /dev/null and b/www/content/coreutils_kc_1.png differ diff --git a/www/developers-guide.html b/www/developers-guide.html new file mode 100644 index 00000000..9c0ff719 --- /dev/null +++ b/www/developers-guide.html @@ -0,0 +1,114 @@ + + + + + KLEE - Getting Started + + + + + + + +
+ +

KLEE Developer's Guide

+ +

This guide covers several areas of KLEE that may not be imediately obvious to new developers.

+ +

+ 1. KLEE's Build System
+ 2. KLEE's Test Framework
+ 3. Miscellaneous
+

+ +

KLEE's Build System

+

KLEE uses LLVM's ability to build third-party projects, which is described here. The build system uses GNU Autoconf and AutoHeader to configure the build, but does not use the rest of GNU Autotools (e.g. automake).

+ +

LLVM's build system supports out-of-source builds and therefore so does KLEE. It is highly recommended you take advantage of this. For example, you could create three builds (Release, Release with debug symbols, Debug) + that all use the same source tree. This allows you keep your source tree clean and allows multiple configurations to be tested from a single source tree.

+ +

Setting up a debug build of KLEE

+

Setting up a debug build of KLEE (we'll assume it is an out-of-source build) is very similar to the build process described in Getting Started, with the exception of steps 6 and 7.

+ +
    +
  1. Now we will configure KLEE. Notice that we are forcing the compiler to produce unoptimised code, this isn't the default behaviour. +
    + $ mkdir path/to/build-dir
    + $ cd path/to/build-dir
    + $ CXXFLAGS="-g -O0" CFLAGS="-g -O0" path/to/source-dir/configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime --with-runtime=Debug+Asserts +
    + Note if you're using an out-of-source build of LLVM you will need to use --with-llvmsrc= and --with-llvmobj= configure options instead of --with-llvm= +
    2. +
  2. Now we can build KLEE. +
    + $ make -j +
    + Note that we are using the -j option of make to speed up the compilation process. +
    3. +
+ +

Note that KLEE depends on LLVM and STP. If you need to debug KLEE's calls to that code, then you will need to build LLVM/STP with debug support too.

+ +

Adding a class

+

Because KLEE uses LLVM's build system, adding a class to an existing library in KLEE is very simple. For example, to add a class to libkleaverExpr, the following steps would be followed: +

    +
  1. Create the header file (.h) for the class and place it somewhere inside include/ (the location isn't really important except that #include is relative to the include/ directory). +
    2. +
  2. Create the source file (.cpp) for the class place it in lib/Expr/. You can confirm that the library in which your new class will be included is kleaverExpr by looking at the Makefile in lib/Expr. +
    3. +
+ That's it! Now LLVM's build system will detect the new .cpp file and add it to the library that is generated when you run make. +

+ +

Building code documentation

+

KLEE uses Doxygen to generate code documentation. To generate it yourself you can run the following from KLEE's build directory root. +

+ $ make doxygen +
+ This will generate documentation in path/to/build-dir/docs/doxygen/ folder. You can also find KLEE's latest official code documentation here +

+ + +

KLEE's Test Framework

+

KLEE uses LLVM's testing infrastructure for its tests, which itself uses DejaGnu. These are the tests that are executed by the make check command. Some documentation on LLVM's testing infrastructure can be found here. +

+

KLEE's tests are currently divided into categories, each of which is a subdirectory in test/ in the source tree (e.g. test/Feature) . The dg.exp file in each subdirectory instructs the LLVM testing infrastructure which files in the subdirectory are to be used as tests. For example, test/Expr/dg.exp contains: +

+ load_lib llvm.exp

+ + RunLLVMTests [lsort [glob -nocomplain $srcdir/$subdir/*.{pc}]] +
+ This instructs the testing infrastructure that every .pc file in test/Expr should be used as a test. +

+

The actions performed in each test are specified by special comments in the file. For example, in test/Feature/ByteSwap.c the first two lines are +

+ // RUN: %llvmgcc %s -emit-llvm -O0 -c -o %t1.bc
+ // RUN: %klee --libc=klee --exit-on-error %t1.bc
+
+ This first runs llvm-gcc on the source file (%s) and generates a temporary file (%t1.bc). Then KLEE is executed on this generated temporary file. If either program returns a non-zero exit code (or crashes) then + test is considered to have failed. More information on the available substitution variables (such as %s) can be found here. +

+ +

It is useful to be able to execute just a single test rather than all of them. KLEE provides a makefile target for doing so which can used as shown below. Note that category/test-name should be the test that one would like to execute, e.g. Feature/ByteSwap.c. +

+ $ cd path/to/build-dir/test
+ $ make check-one TESTONE=path/to/source-dir/test/category/test-name +
+

+ + +

Miscellaneous

+

Writing messages to standard error

+

The kleeCore library (lib/Core) provides several functions that can be used similarly to printf() in C. See lib/Core/Common.h for more information. +

+ +

Adding a command line option to a tool

+

KLEE uses LLVM's CommandLine library for adding options to tools in KLEE, which is well documented here. See lib/core/Executor.cpp for examples.

+ +
+ +
+ + diff --git a/www/index.html b/www/index.html new file mode 100644 index 00000000..b76a42bc --- /dev/null +++ b/www/index.html @@ -0,0 +1,36 @@ + + + + + + + The KLEE Symbolic Virtual Machine + + + + + +
+ +

The KLEE Symbolic Virtual Machine

+ + +

KLEE is a symbolic virtual machine built on top of + the LLVM compiler infrastructure, and available + under the UIUC open source license.

+ +

For more information on what KLEE is and what it can do, see + the OSDI + 2008 paper.

+ +

If you are interested in trying it yourself, please + see Getting Started.

+ + + +
+ + diff --git a/www/klee-dev.html b/www/klee-dev.html new file mode 100644 index 00000000..5434ce57 --- /dev/null +++ b/www/klee-dev.html @@ -0,0 +1,31 @@ + + + + + + klee-dev mailing list + + + + + +
+ +

klee-dev mailing list

+ + +

If you have questions about KLEE that are not answered on this + website, please send a message to + the klee-dev + mailing list.

+ + +

However, before doing so, please + check klee-dev's + searchable archive to see if your question has already been + answered.

+ +
+ + diff --git a/www/klee-files.html b/www/klee-files.html new file mode 100644 index 00000000..299f593b --- /dev/null +++ b/www/klee-files.html @@ -0,0 +1,137 @@ + + + + + + The KLEE Symbolic Virtual Machine + + + + + +
+ +

Files generated by KLEE

+ + +

Standard Global Files

+ + These are global files are always generated on a KLEE execution: +
    +
  1. info: This is a text file containing various information + related to a KLEE run. In particular, it records the exact + command-line with which KLEE was run, and the total time taken by + the execution. E.g.: + 
    +    $ cat info 
+    klee --write-pcs demo.o
+    PID: 12460
+    Started: 2009-05-20 22:31:41
+    BEGIN searcher description
+    DFSSearcher
+    END searcher description
+    Finished: 2009-05-20 22:31:41
+    Elapsed: 00:00:00
+    KLEE: done: explored paths = 3
+    KLEE: done: avg. constructs per query = 6
+    KLEE: done: total queries = 3
+    KLEE: done: valid queries = 0
+    KLEE: done: invalid queriers = 3
+    KLEE: done: query cex = 3
+    KLEE: done: total instructions = 67
+    KLEE: done: completed paths = 3
+    KLEE: done: generated tests = 3
    +
    2. + +
  2. warnings.txt: This is a text file containing all warnings emitted by KLEE. +
    3. + +
  3. messages.txt: This is a text file containing all other messages emitted by KLEE. +
    4. + +
  4. assembly.ll: This file contains a human readable version + of the LLVM bitcode executed by KLEE + +
  5. run.stats: This is a text file containing various + statistics emitted by KLEE. While this file can be inspected + manually, you should use the klee-stats + tool for that.
    6. + +
  6. run.istats: This is a binary file containing global + statistics emitted by KLEE for each line of code in the program. +
    7. + +
+ + +

Other Global Files

+ +
    +
  1. all-queries.pc: This file contains all the queries KLEE + made during execution in the KQuery + format. Note these are the queries before any optimisation + (e.g. caching, constraint independence) so it is possible that + some of the queries logged are never executed by KLEE's underlying + solver or are modified before being executed by KLEE's underlying + solver. The generation of this file can be enabled by specifying + the option --use-query-log=all:pc to KLEE.
    2. +
  2. all-queries.smt2: This file contains all the queries KLEE made during execution in the SMT-LIBv2 + .It contains the same information as all-queries.pc. + The generation of this file can be enabled by specifying the option --use-query-log=all:smt2 to KLEE.
    3. +
  3. solver-queries.pc: This file contains all the queries passed to KLEE's underlying solver during execution in the + KQuery format. Note these are the + queries after all optimisations (e.g. caching, constraint + independence) are performed. The generation of this file can be + enabled by specifying the + option --use-query-log=solver:pc to KLEE.
    4. +
  4. solver-queries.smt2: This file contains all the queries passed to KLEE's underlying solver during execution in the + SMT-LIBv2 + format. It contains the same information as solver-queries.pc. + The generation of this file can be enabled by specifying the option --use-query-log=solver:smt2 to KLEE.
    5. +
+ + +

Per-path files

+ +
    +
  1. + test<N>.ktest: Contains the test case generated by + KLEE on that path. Use ktest-tool + to read the contents. The generation of .ktest files + can be disabled using the --no-output option. +
    2. + +
  2. + test<N>.<error-type>.err: Generated for paths + where KLEE found an error. Contains information about the error + in textual form. +
    3. + +
  3. test<N>.pc: Contains the constraints associated with the given + path, in KQuery format. The generation + of these files can be enabled via the --write-cvcs flag. +
    4. + +
  4. + test<N>.cvc: Contains the constraints associated + with the given path, + in CVC + format. The generation of these files can be enabled via + the --write-pcs flag. (This is the same information as + in the corresponding .pc file.) +
    5. +
  5. + test<N>.smt2: Contains the constraints associated + with the given path, + in SMT-LIBv2 + format. The generation of these files can be enabled via + the --write-smt2s flag. (This is the same information as + in the corresponding .pc file.) +
    6. +
+ + +
+ + diff --git a/www/klee-options.html b/www/klee-options.html new file mode 100644 index 00000000..be997ec4 --- /dev/null +++ b/www/klee-options.html @@ -0,0 +1,99 @@ + + + + + + The KLEE Symbolic Virtual Machine + + + + + +
+ +

KLEE Options

+ + +

+ 1. Search Heuristics
+ 2. Query Logging
+

+ + + +

Main search heuristics

+ +

+ KLEE provides four main search heuristics: +

    +
  1. Depth-First Search (DFS): Traverses states in depth-first order.
    2. +
  2. Random State Search:Randomly selects a state to explore.
    3. +
  3. Random Path Selection: Described in our KLEE OSDI'08 paper.
    4. +
  4. Non Uniform Random Search (NURS): Selects a state randomly according to a given distribution. The distribution can be based on the minimum distance to an uncovered instruction (MD2U), the query cost, etc. +
+ + To select a search heuristic, use the --search option provided by KLEE. For example: + 
+    $ klee --search=dfs demo.o
+ + runs demo.o using DFS, while + 
+    $ klee --search=random-path demo.o
+ runs it using the random path selection strategy. + + The full list of options is shown in KLEE's help message: + 
+    $ klee --help
+    -search                                 - Specify the search heuristic (default=random-path interleaved with nurs:covnew)
+      =dfs                                  -   use Depth First Search (DFS)
+      =random-state                         -   randomly select a state to explore
+      =random-path                          -   use Random Path Selection (see OSDI'08 paper)
+      =nurs:covnew                          -   use Non Uniform Random Search (NURS) with Coverage-New heuristic
+      =nurs:md2u                            -   use NURS with Min-Dist-to-Uncovered heuristic
+      =nurs:depth                           -   use NURS with 2^depth heuristic
+      =nurs:icnt                            -   use NURS with Instr-Count heuristic
+      =nurs:cpicnt                          -   use NURS with CallPath-Instr-Count heuristic
+      =nurs:qc                              -   use NURS with Query-Cost heuristic
+ + +

Interleaving search heuristics

+

+ Search heuristics in KLEE can be interleaved in a round-robin + fashion. To interleave several search heuristics to be interleaved, use the --search multiple times. For example: + 

+    $ klee --search=random-state --search=nurs:md2u demo.o
+ interleaves the Random State and the NURS:MD2U heuristics in a round robin fashion. +
+

+ + +

Default search heuristics

+

+ The default heuristics used by KLEE are random-path interleaved with nurs:covnew. +

+ +

Query Logging

+ + To log the queries issued by KLEE during symbolic execution, you can use the following options: +
    +
  1. + --use-query-log=TYPE:FORMAT, where: +
      +
    • TYPE is either all to log all the queries KLEE made during execution before any optimisation (e.g. caching, constraint independence) is performed, or solver to log only the queries passed to KLEE's underlying solver. Note that it is possible that some of the unoptimized queries are never executed or are modified before being executed by KLEE's underlying solver.
      • +
    • FORMAT is the format in which queries are logged and can be either pc for the KQuery format, or smt2 for the SMT-LIBv2 format. +
    +
  2. + --min-query-time-to-log=TIME (in ms) is used to log only queries that exceed a certain time limit. TIME can be: +
      +
    • 0 (default): to log all queries
      • +
    • <0: a negative value specifies that only queries that timed out should be logged. The timeout value is specified via the --max-stp-time option.
      • +
    • >0: only queries that took more that TIME milliseconds should be logged. +
    +
    3. + +
+ +
+ + diff --git a/www/klee-tools.html b/www/klee-tools.html new file mode 100644 index 00000000..80ae5d35 --- /dev/null +++ b/www/klee-tools.html @@ -0,0 +1,84 @@ + + + + + + The KLEE Symbolic Virtual Machine + + + + + +
+ +

KLEE Tools

+ + +

+ 1. ktest-tool
+ 2. klee-stats
+

+ +

ktest-tool

+ +

klee-stats

+ klee-stats is a Python script used to extract and present in a + tabular form runtime statistics for a KLEE execution. The runtime statistics include: +
    +
  • The number of executed instructions
    • +
  • Instruction coverage in the LLVM bitcode (%)
    • +
  • Branch coverage in the LLVM bitcode (%)
    • +
  • Total static instructions in the LLVM bitcode
    • +
  • The number of currently active states
    • +
  • Megabytes of memory currently used
    • +
  • The number of queries issued to STP
    • +
  • The average number of query constructs per query
    • +
  • Various time statistics: +
      +
    • Total user time
      • +
    • Total wall time
      • +
    • Time spent in the constraint solver
      • +
    • Time spent in the counterexample caching code
      • +
    • Time spent forking
      • +
    • Time spent in object resolution
      • +
    • +
+ + + klee-stats extracts statistics information from the run.stats file + present in the klee-out-* directory created during a KLEE execution. + The exact usage of klee-stats is as follows: + 
klee-stats [options] directories
+ The directories parameter is a list of klee-out-* directories + created by KLEE. A common scenario is to simply run klee-stats on klee-last. + +

+ In order to limit printed information only to the values of measured times, + the following options can be used: + +

    +
  • --print-rel-times—display time values relative + to measured execution time
    • + +
  • --print-abs-times—display absolute time values
    • +
+ + The --precision option can be used to configure the number of fractional + digits displayed in floating point values. By default, 2 fractional digits + are displayed, but in some cases that might be not sufficient—if the value + is very small, e.g. 0.0001, with 2-digits precision it will be printed as 0.00. +

+ +

Various other options can be used to specify what values are + displayed and how they are displayed. Options for comparison of + statistics are also provided. More information about available + options can be obtained using the command: + 

klee-stats --help
+

+ +
+ +
+ + diff --git a/www/menu.css b/www/menu.css new file mode 100644 index 00000000..6e96a457 --- /dev/null +++ b/www/menu.css @@ -0,0 +1,39 @@ +/***************/ +/* page layout */ +/***************/ + +[id=menu] { + position:fixed; + width:25ex; +} +[id=content] { + /* ***** EDIT THIS VALUE IF CONTENT OVERLAPS MENU ***** */ + position:absolute; + left:29ex; + padding-right:4ex; +} + +/**************/ +/* menu style */ +/**************/ + +#menu .submenu { + padding-top:1em; + display:block; +} + +#menu label { + display:block; + font-weight: bold; + text-align: center; + background-color: rgb(192,192,192); +} +#menu a { + padding:0 .2em; + display:block; + text-align: center; + background-color: rgb(235,235,235); +} +#menu a:visited { + color:rgb(100,50,100); +} \ No newline at end of file diff --git a/www/menu.html.incl b/www/menu.html.incl new file mode 100644 index 00000000..7f2e4e33 --- /dev/null +++ b/www/menu.html.incl @@ -0,0 +1,31 @@ + diff --git a/www/resources/Regexp.c.html b/www/resources/Regexp.c.html new file mode 100644 index 00000000..cb3e3d75 --- /dev/null +++ b/www/resources/Regexp.c.html @@ -0,0 +1,78 @@ + + + +Enscript Output + + + + +

Regexp.c

+ +
+/* 
+ * Simple regular expression matching.
+ *
+ * From:
+ *   The Practice of Programming
+ *   Brian W. Kernighan, Rob Pike
+ *
+ */ 
+
+#include <klee/klee.h>
+
+static int matchhere(char*,char*);
+
+static int matchstar(int c, char *re, char *text) {
+  do {
+    if (matchhere(re, text))
+      return 1;
+  } while (*text != '\0' && (*text++ == c || c== '.'));
+  return 0;
+}
+
+static int matchhere(char *re, char *text) {
+  if (re[0] == '\0')
+     return 0;
+  if (re[1] == '*')
+    return matchstar(re[0], re+2, text);
+  if (re[0] == '$' && re[1]=='\0')
+    return *text == '\0';
+  if (*text!='\0' && (re[0]=='.' || re[0]==*text))
+    return matchhere(re+1, text+1);
+  return 0;
+}
+
+int match(char *re, char *text) {
+  if (re[0] == '^')
+    return matchhere(re+1, text);
+  do {
+    if (matchhere(re, text))
+      return 1;
+  } while (*text++ != '\0');
+  return 0;
+}
+
+/*
+ * Harness for testing with KLEE.
+ */
+
+// The size of the buffer to test with.
+#define SIZE 7
+
+int main() {
+  // The input regular expression.
+  char re[SIZE];
+  
+  // Make the input symbolic. 
+  klee_make_symbolic_name(re, sizeof re, "re");
+
+  // Try to match against a constant string "hello".
+  match(re, "hello");
+
+  return 0;
+}
+
+
+
Generated by GNU enscript 1.6.4.
+ + diff --git a/www/resources/get_sign.c.html b/www/resources/get_sign.c.html new file mode 100644 index 00000000..58c28d01 --- /dev/null +++ b/www/resources/get_sign.c.html @@ -0,0 +1,37 @@ + + + +Enscript Output + + + + +

get_sign.c

+ +
+/*
+ * First KLEE tutorial: testing a small function
+ */
+
+
+int get_sign(int x) {
+  if (x == 0)
+     return 0;
+  
+  if (x < 0)
+     return -1;
+  else 
+     return 1;
+} 
+
+int main() {
+  int a;
+  klee_make_symbolic(&a, sizeof(a), "a");
+  return get_sign(a);
+} 
+
+
+
Generated by GNU Enscript 1.6.5.2.
+enscript -Ec --color -w html get_sign.c -o get_sign.c.html + + diff --git a/www/resources/islower.c.html b/www/resources/islower.c.html new file mode 100644 index 00000000..524f2093 --- /dev/null +++ b/www/resources/islower.c.html @@ -0,0 +1,33 @@ + + + +Enscript Output + + + + +

islower.c

+ +
+/*
+ * First KLEE tutorial: testing a small function
+ */
+
+#include <klee/klee.h>
+
+int my_islower(int x) {
+  if (x >= 'a' && x <= 'z')
+    return 1;
+  else return 0;
+}
+
+int main() {
+  char c;
+  klee_make_symbolic(&c, sizeof(c), "input");
+  return my_islower(c);
+}
+
+
+
Generated by GNU enscript 1.6.4.
+ + -- cgit 1.4.1 From 032a2dedd1d3d033bcc410c3de07e6ed0f701ac0 Mon Sep 17 00:00:00 2001 From: Dominic Chen Date: Thu, 25 Jul 2013 10:58:00 +0100 Subject: remove www from master branch --- www/CoreutilsExperiments.html | 158 -------- www/Documentation.html | 57 --- www/GetInvolved.html | 53 --- www/GetStarted.html | 244 ----------- www/KQuery.html | 620 ---------------------------- www/OpenProjects.html | 91 ----- www/Publications.html | 402 ------------------- www/TestingCoreutils.html | 893 ----------------------------------------- www/Tutorial-1.html | 187 --------- www/Tutorial-2.html | 287 ------------- www/Tutorials.html | 38 -- www/bugs.html | 24 -- www/content.css | 75 ---- www/content/coreutils_kc_0.png | Bin 277141 -> 0 bytes www/content/coreutils_kc_1.png | Bin 232377 -> 0 bytes www/developers-guide.html | 114 ------ www/index.html | 36 -- www/klee-dev.html | 31 -- www/klee-files.html | 137 ------- www/klee-options.html | 99 ----- www/klee-tools.html | 84 ---- www/menu.css | 39 -- www/menu.html.incl | 31 -- www/resources/Regexp.c.html | 78 ---- www/resources/get_sign.c.html | 37 -- www/resources/islower.c.html | 33 -- 26 files changed, 3848 deletions(-) delete mode 100644 www/CoreutilsExperiments.html delete mode 100644 www/Documentation.html delete mode 100644 www/GetInvolved.html delete mode 100644 www/GetStarted.html delete mode 100644 www/KQuery.html delete mode 100644 www/OpenProjects.html delete mode 100644 www/Publications.html delete mode 100644 www/TestingCoreutils.html delete mode 100644 www/Tutorial-1.html delete mode 100644 www/Tutorial-2.html delete mode 100644 www/Tutorials.html delete mode 100644 www/bugs.html delete mode 100644 www/content.css delete mode 100644 www/content/coreutils_kc_0.png delete mode 100644 www/content/coreutils_kc_1.png delete mode 100644 www/developers-guide.html delete mode 100644 www/index.html delete mode 100644 www/klee-dev.html delete mode 100644 www/klee-files.html delete mode 100644 www/klee-options.html delete mode 100644 www/klee-tools.html delete mode 100644 www/menu.css delete mode 100644 www/menu.html.incl delete mode 100644 www/resources/Regexp.c.html delete mode 100644 www/resources/get_sign.c.html delete mode 100644 www/resources/islower.c.html diff --git a/www/CoreutilsExperiments.html b/www/CoreutilsExperiments.html deleted file mode 100644 index c0f0829c..00000000 --- a/www/CoreutilsExperiments.html +++ /dev/null @@ -1,158 +0,0 @@ - - - - - - KLEE - Coreutils Experiments - - - - - -
- -

Coreutils Experiments

- -

- This document is meant to give additional information regarding - the Coreutils experiments discussed in - our KLEE - OSDI'08 paper. However, please note that in the last several - years, KLEE and its dependencies (particularly LLVM and STP), have - undergone major changes, which have resulted in considerable - different behavior on several benchmarks, including Coreutils.

- -

- This document is structured as a series of FAQs: -

- -
    -
  1. How did you build Coreutils?
    - Please follow the instructions in the Coreutils Tutorial. -
    2. - -
  2. What version of LLVM was used in the OSDI paper?
    - We generally kept in sync with the LLVM top-of-tree, which at the time - was somewhere around LLVM 2.2 and 2.3.
    3. - - -
  3. What version of STP was used in the OSDI paper?
    - An old version of STP, which is still available as part of KLEE's - repository, in revisions up to r161056. -
    4. - -
  4. On what OS did you run your experiments?
    - We ran most experiments on a 32-bit Fedora machine with SELinux - support. The most important aspect is that this was a 32-bit - system: the constraints generated on a 64-bit system are typically - more complex and memory consumption might also increase. -
    5. - -
  5. What are the 89 Coreutils applications that you tested?
    -
    - [ base64 basename cat chcon chgrp chmod chown chroot cksum comm cp csplit cut date dd df dircolors dirname du echo env expand expr factor false fmt fold head hostid hostname id ginstall join kill link ln logname ls md5sum mkdir mkfifo mknod mktemp mv nice nl nohup od paste pathchk pinky pr printenv printf ptx pwd readlink rm rmdir runcon seq setuidgid shred shuf sleep sort split stat stty sum sync tac tail tee touch tr tsort tty uname unexpand uniq unlink uptime users wc whoami who yes -
    -
    6. - -
  6. What options did you run KLEE with?
    - We used the following options (the command below is for paste): -
    -$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    - --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    - --use-cex-cache --with-libc --with-file-model=release \
    - --allow-external-sym-calls --only-output-states-covering-new \
    - --exclude-libc-cov --exclude-cov-file=./../lib/functions.txt \
    - --environ=test.env --run-in=/tmp/sandbox --output-dir=paste-data-1h \
    - --max-sym-array-size=4096 --max-instruction-time=10. --max-time=3600. \
    - --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    - --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    - --randomize-fork --use-random-path --use-interleaved-covnew-NURS \
    - --use-batching-search --batch-instructions 10000 --init-env \
    - ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - - Some of these options have been renamed or removed in the current - version of KLEE. Most notably, the options "--exclude-libc-cov" - and "--exclude-cov-file" were implemented in a fragile way and we - decided to remove them from KLEE. The idea was to treat the - functions in libc or specified in a text file as "covered". (For - the Coreutils experiments, we were interested in covering the - code in the tools themselves, as opposed to library code, see the - paper for more details). If you plan to reimplement these - options in a clean way, please consider contributing your code to the mainline. -
    7. - -
  7. What are the options closest to the ones above that - work with the current version KLEE?
    - Try the following: - -
    -$ klee --simplify-sym-indices --write-cvcs --write-cov --output-module \
    - --max-memory=1000 --disable-inlining --optimize --use-forked-stp \
    - --use-cex-cache --libc=uclibc --posix-runtime \
    - --allow-external-sym-calls --only-output-states-covering-new \
    - --environ=test.env --run-in=/tmp/sandbox \
    - --max-sym-array-size=4096 --max-instruction-time=30. --max-time=3600. \
    - --watchdog --max-memory-inhibit=false --max-static-fork-pct=1 \
    - --max-static-solve-pct=1 --max-static-cpfork-pct=1 --switch-type=internal \
    - --randomize-fork --search=random-path --search=nurs:covnew \
    - --use-batching-search --batch-instructions=10000 \
    - ./paste.bc --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - -
    8. - -
  8. How do I generate test.env and /tmp/sandbox?
    - We used a simple environment and a "sandbox" directory to make - our experiments more deterministic. To recreate them, follow - these steps: -
      -
    1. Download testing-env.sh by clicking here, and place it in the current directory.
      2. -
    2. Create test.env by running: -
      - $ env -i /bin/bash -c '(source testing-env.sh; env >test.env)' -
      -
      3. -
    3. Download sandbox.tgz by clicking here, place it in /tmp, and run: -
      - $ cd /tmp - $ tar xzfv sandbox.tgz -
      -
      4. -
    -
    9. -
  9. - What symbolic arguments did you use in your experiments?
    - We ran most utilities using the arguments below. Our choice was - based on a high-level understanding of the Coreutils - applications: most behavior can be triggered with no more than two - short options, one long option, and two small input streams (stdin and one file). -
    - --sym-args 0 1 10 --sym-args 0 2 2 --sym-files 1 8 --sym-stdout -
    - - - - For eight tools where the coverage results were unsatisfactory, -we consulted the man page and increased the number and size of -arguments and files as follows: -
    - dd: --sym-args 0 3 10 --sym-files 1 8 --sym-stdout
    - dircolors: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    - echo: --sym-args 0 4 300 --sym-files 2 30 --sym-stdout
    - expr: --sym-args 0 1 10 --sym-args 0 3 2 --sym-stdout
    - mknod: --sym-args 0 1 10 --sym-args 0 3 2 --sym-files 1 8 --sym-stdout
    - od: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout
    - pathchk: --sym-args 0 1 2 --sym-args 0 1 300 --sym-files 1 8 --sym-stdout
    - printf: --sym-args 0 3 10 --sym-files 2 12 --sym-stdout -
    - -
    10. - -
- - -
- - diff --git a/www/Documentation.html b/www/Documentation.html deleted file mode 100644 index 538cada7..00000000 --- a/www/Documentation.html +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - KLEE - Documentation - - - - - -
- -

KLEE Documentation

- - -
    -
  1. - KLEE Tutorials: - Simple examples of how to use KLEE to test programs. -
    2. - -
  2. - KLEE Options: - Overview of KLEE's main command-line options. -
    3. - -
  3. - KLEE Generated Files: - Overview of the main files generated by KLEE. -
    4. - -
  4. - KLEE Tools: - Overview of the main auxiliary tools provided by KLEE. -
    5. - -
  5. - KQuery Language Reference Manual: - The reference manual for the KQuery language, used for interacting with - the KLEE solver (kleaver). -
    6. - -
  6. - OSDI'08 Coreutils Experiments: - Some information about the Coreutils experiments presented in our KLEE OSDI'08 paper. -
    7. - -
  7. - Developer's Guide: - A brief guide on working with the KLEE source code. -
    8. -
-
- - diff --git a/www/GetInvolved.html b/www/GetInvolved.html deleted file mode 100644 index 2ff2b5ee..00000000 --- a/www/GetInvolved.html +++ /dev/null @@ -1,53 +0,0 @@ - - - - - KLEE - Get Involved - - - - - - - -
- -

Getting Involved with the KLEE Project

- -

If you are interested in following development of KLEE, or would like to -contribute, here are some resources that may prove useful.

- -

Mailing Lists

- -

Currently the main list for KLEE discussion (both for users and developers) -is klee-dev.

- -

Commit messages to the KLEE repository go to -klee-commits. This -is also the place to send patches if you are interested in contributing to -KLEE.

- -

Bug Reports

- -

If you find a bug in KLEE, please report it on klee-dev -and also fill a bug report on Bugzilla under the klee product.

- - -

Working with the Code

- -

You should first check KLEE's developer's guide.

- -

Developer documentation is written in - doxygen. - -

- -

- -

Many parts of KLEE rely on the LLVM infrastructure, so you might also want to look at -LLVM's General Programming Documentation.

- -
- - diff --git a/www/GetStarted.html b/www/GetStarted.html deleted file mode 100644 index 7f6199dc..00000000 --- a/www/GetStarted.html +++ /dev/null @@ -1,244 +0,0 @@ - - - - - KLEE - Getting Started - - - - - - - -
- -

Getting Started: Building and Running KLEE

- - - -

-1. Trying out KLEE without installing any dependencies
-2. Building KLEE
-

- - -

Trying out KLEE without installing any dependencies

- -

-If you would like to try out KLEE without the hassle of compiling or installing dependencies, download the self-contained package (200MB), and follow the instructions in klee-cde-package/README to get up-and-running! -

- -

-This package contains a self-contained source+binary distribution of KLEE and all of its associated dependencies (e.g., llvm-2.7, llvm-gcc, uClibc, svn). Using this package, you can: -

- -
    -
  1. Compile target programs using llvm-gcc -
  2. Run KLEE on target programs compiled with llvm-gcc -
  3. Modify KLEE's source code, re-compile it to build a new KLEE binary, and then run the test suite using the new binary -
  4. Pull the latest KLEE source code updates from SVN -
  5. Run the entire Coreutils case study -
- -

-... all without compiling or installing anything else on your Linux machine! -

- -

-The only requirement is that you are running a reasonably-modern x86-Linux distro that can execute 32-bit ELF binaries. This package was created using the CDE auto-packaging tool. -

- -

-NOTE: The CDE package is mainly meant for trying out KLEE on -some simple examples and the Coreutils case study. It is likely that -you will run into errors when testing other applications, in which -case you will need to follow the full installation instructions below. -

- - -

Building KLEE

- - -

The current procedure for building is outlined below.

- -
    - -
  1. Install dependencies: - -KLEE requires all the dependencies of LLVM, which are discussed here. In particular, you should have the following packages (the list is likely not complete): g++, curl, dejagnu, subversion, bison, flex: -
    - $ sudo apt-get install g++ curl dejagnu subversion bison flex (Ubuntu)
    - $ sudo yum install g++ curl dejagnu subversion bison flex (Fedora) -
    -

    - -On some architectures, you might also need to set the following environment variables (best to put them in a config file like .bashrc): -
    - $ export C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
    - $ export CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu -
    - -
  2. Build LLVM 2.9: - -

    -KLEE is built on top of LLVM; the first -steps are to get a working LLVM installation. -See Getting Started -with the LLVM System for more information. -

    - -

    -NOTE: KLEE is currently tested only on Linux x86-32 and x86-64 -targets, using LLVM 2.9. KLEE will not work with older LLVM -versions (e.g., 2.5), and might not work with newer versions (e.g., -3.0). -

    - - -
      -
    1. Install llvm-gcc: -
        -
      • Download and install the LLVM 2.9 release of llvm-gcc - from here. - -
        Add llvm-gcc to your PATH. It - is important to do this first so that llvm-gcc is - found in subsequent configure - steps. llvm-gcc will be used later to compile - programs that KLEE can execute. -
        • - -
      • Forgetting to add llvm-gcc to your PATH at this point is - by far the most common source of build errors reported by new - users.
        • -
      -
      2. - -
    2. Download and build LLVM 2.9: -
      - $ curl -O http://llvm.org/releases/2.9/llvm-2.9.tgz
      - $ tar zxvf llvm-2.9.tgz
      - $ cd llvm-2.9
      - $ ./configure --enable-optimized --enable-assertions
      - $ make -
      - - (the --enable-optimized configure argument is not necessary, but - KLEE runs very slowly in Debug mode). -
      3. - -
    - - -
  3. Build STP: - -

    KLEE is based on -the STP -constraint solver. STP does not make frequent releases, and its -Subversion repository is under constant development and may be -unstable. The instructions below are for a particular revision which -we have used successfully, but you can try a more recent revision by -changing or removing the -r argument to the svn co -command. (Please let us know if you have successfully and extensively -used KLEE with a more recent version of STP.) -

    - -
    - $ svn co -r 940 https://stp-fast-prover.svn.sourceforge.net/svnroot/stp-fast-prover/trunk/stp stp
    - $ cd stp
    - $ ./scripts/configure --with-prefix=path/to/stp/install --with-cryptominisat2
    - $ make OPTIMIZE=-O2 CFLAGS_M32= install -
    -
    4. - -As documented on the STP website, it is essential to run the following -command before using STP (and thus KLEE): -
    - $ ulimit -s unlimited -
    - - -
  4. [Optional] Build uclibc and the POSIX environment model: - -

    -By default, KLEE works on closed programs (programs that don't use any -external code such as C library functions). However, if you want to -use KLEE to run real programs you will want to enable the KLEE POSIX -runtime, which is built on top of the uClibc C library. -

    - -
      -
    1. Download KLEE's uClibc. KLEE uses a version - of uClibc which has been - modified slightly for our purposes. -
        -
      • A version that works on 32-bit Linux can be found - here -
        • -
      • A version that works on 64-bit Linux can be found - here -
        • -
      -
      2. - -
    2. Build uClibc with llvm-gcc: -
      - $ tar zxvf klee-uclibc-0.02.tgz
      - $ ./configure --with-llvm=path/to/llvm
      - $ make
      -
      - -

      NOTE: If you are on a different target (i.e., not i386 - or x64), you will need to run make config and select the - correct target. The defaults for the other uClibc configuration - variables should be fine.

      -

      3. - -
    - - -
  5. Checkout KLEE (to any path you like): -
    - $ svn co http://llvm.org/svn/llvm-project/klee/trunk klee -
    - Alternatively, if you prefer to use git there is also a - read-only git mirror, which syncs automatically with each - Subversion commit. You can do a git clone of KLEE via: -
    - $ git clone http://llvm.org/git/klee.git -
    -
    6. - -
  6. Configure KLEE: -

    From the KLEE source directory, run:

    -
    - $ ./configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime -
    - -

    NOTE: If you skipped step 4, simply remove the --with-uclibc and --enable-posix-runtime options.

    -
    7. - -
  7. Build KLEE: -
    - $ make ENABLE_OPTIMIZED=1 -
    -
    8. - -
  8. Run the regression suite to verify your build: -
    - $ make check
    - $ make unittests
    -
    -
    9. - -
  9. You're ready to go! Go to the Tutorials page - to try KLEE.
    10. -
- -

NOTE: If you are installing the system of Ubuntu 12.04 (or similar), you might want to take a look at this message.

-
- -
- - diff --git a/www/KQuery.html b/www/KQuery.html deleted file mode 100644 index a40f4435..00000000 --- a/www/KQuery.html +++ /dev/null @@ -1,620 +0,0 @@ - - - - - KLEE - KQuery Language Reference Manul - - - - - - - -
- -

KQuery Language Reference Manual

- -

Table Of Contents

-
    -
  1. Introduction
    2. -
  2. Notation
    3. -
  3. Structure
    4. -
      -
    1. Expression and Version Labels -
    -
  4. Literals -
      -
    1. Identifiers
      2. -
    2. Numbers
      3. -
    3. Types
      4. -
    -
    5. -
  5. Declarations -
      -
    1. Arrays
      2. -
    2. Query Commands
      3. -
    -
    6. -
  6. Versions
    7. -
  7. Expressions -
      -
    1. Primitive Expressions -
        -
      1. Expression References
        2. -
      2. Constants
        3. -
      -
      2. -
    2. Arithmetic Operations -
        -
      1. Add
        2. -
      2. Sub
        3. -
      3. Mul
        4. -
      4. UDiv
        5. -
      5. URem
        6. -
      6. SDiv
        7. -
      7. SRem
        8. -
      -
      3. -
    3. Bitwise Operations -
        -
      1. Not
        2. -
      2. And
        3. -
      3. Or
        4. -
      4. Xor
        5. -
      5. Shl
        6. -
      6. LShr
        7. -
      7. AShr
        8. -
      -
      4. -
    4. Comparisons -
        -
      1. Eq
        2. -
      2. Ne
        3. -
      3. Ult
        4. -
      4. Ule
        5. -
      5. Ugt
        6. -
      6. Uge
        7. -
      7. Slt
        8. -
      8. Sle
        9. -
      9. Sgt
        10. -
      10. Sge
        11. -
      -
      5. -
    5. Bitvector Manipulation -
        -
      1. Concat
        2. -
      2. Extract
        3. -
      3. ZExt
        4. -
      4. SExt
        5. -
      -
      6. -
    6. Special Expressions -
        -
      1. Read
        2. -
      2. Select
        3. -
      -
      7. -
    7. Macro Expressions -
        -
      1. Neg
        2. -
      2. ReadLSB
        3. -
      3. ReadMSB
        4. -
      -
      8. -
    -
    8. -
- -

Introduction

- -

The KQuery language is the textual representation of constraint - expressions and queries which is used as input to the Kleaver - constraint solver.

- -

Currently the language is capable of representing quantifier free - formulas over bitvectors and arrays, with direct support for all - standard operations on bitvectors. The language has been designed to - be compact and easy to read and write.

- -

The KQuery language is closely related to the C++ API for Exprs, see - also the - doxygen Expr - documentation.

- -

Notation

- -

In this document, syntax is given in Extended Backus-Naur Form and appears as:

-
- "(" "Eq" [ type ] LHS RHS ")" -
-

Unless noted, the rules are described in terms of tokens not characters, - and tokens can be separate by white space and comments.

- -

In some case, a production like child-expression is used as an alias - for the expression production, when subsequent text needs to - differentiate the expression.

- -

Examples are shown using:

-
- (Eq w32 a b) -
- -

Structure

- -

A KQuery source file consists of a sequence of declarations.

- -

Syntax:

-
- kquery = { array-declaration | query-command } -
- -

Currently, the language supports two kinds of declarations:

-
    -
  • Array Declarations: Use to - declare an array of bitvectors for use in subsequent - expressions.
    • - -
  • Query Commands: Used to - define queries which should be executed by the constraint solver. A - query consists of a set of constraints (assumptions), a query - expression, and optionally expressions and arrays to compute values - for if the query expression is invalid.
    • -
- -

Comments begin with "#" and continue until the end of line. For example:

-
- (Add w32 1 1) # Two, hopefully -
- -

Expression and Version Labels

- -

Expressions are frequently shared among constraints and query - expressions. In order to keep the output succinct and readable, expression - labels can be used to introduce a lexical binding which can be used in - subsequent expressions. Expression labels are globally scoped through the - entire source file, and a definition must preceed any use in the source - file.

- -

Syntax:

-
- expression = identifier ":" expression
-
- -

Likewise, versions are frequently shared among reads and can be labelled in - the same fashion.

- -

Examples:

-
- (Add w32 N0:(Add w32 1 1) N0) # Four

- array const_array[] : w32 -> w8 = [5,6]
- (Read w8 0 U0:[0=255] @ const_array) # U0 now refers to an array [255,6]
- (Read w8 1 U0) # Read from byte offset 1 of [255,6]
-
- -

Literals

- -

Identifiers

- -

Identifiers are used for specifying array names and - for expression labels.

- -

Syntax:

-
- identifier = "[a-zA-Z_][a-zA-Z0-9._]*"
-
- -

Examples:

-
- _foo
- arr10_20
-
- -

Note that in order to keep open the possibility to introduce explicit - integral and floating-point types, the following identifiers are treated - as reserved keywords:

-
- floating-point-type = "fp[0-9]+([.].*)?"
- integer-type = "i[0-9]+"
-
- -

Numbers

- -

Numeric constants can be specified as follows.

- -

Syntax:

-
- number = "true" | "false" | signed-constant
- signed-constant = [ "+" | "-" ] ( dec-constant | bin-constant | oct-constant | hex-constant )
- dec-constant = "[0-9_]+"
- bin-constant = "0b[01_]+"
- oct-constant = "0o[0-7_]+"
- hex-constant = "0x[0-9a-fA-F_]+"
-
- -

Examples:

-
- false
- -10
- 0b1000_0001 # 129
-
- -

Non-decimal constants can be signed. The '_' character is ignored when - evaluating constants, but is available for use as a separator.

- -

Types

- -

Types are explicit operands to most expressions, and indicate the - bit-width of the type.

- -

Syntax:

-
- type = "w[0-9]+"
-
- -

Example:

-
- w32
-
- -

The numeric portion of the token is taken to be a decimal integer - specifying the bit-width of the type.

- -

Declarations

- -

Arrays

- -

Arrays are the basic type for defining symbolic variables (the - language does not currently support simple variables).

- -

Syntax:

-
- array-declaration = "array" name "[" [ size ] "]" ":" domain "->" range "=" array-initializer
- array-initializer = "symbolic" | "[" number-list "]"
- number-list = number | number "," number-list
-
- -

Arrays can be initialized to be either symbolic, or to have a given list of - constant values. For constant arrays, the initializer list must exactly match - the size of the array (if the size was unspecified, it will be the number of - constant values).

- -

Examples:

-
- array foo[10] : w32 -> w8 = symbolic # A ten element symbolic array
- array foo[] : w8 -> w1 = [ true, false, false, true ] # A constant array of four booleans
-
- -

Query Commands

- -

Query declarations describe the queries that the constraint solver - should run, along with optional additional arguments to specify - expressions and arrays for which counterexamples should be provided.

- -

Syntax:

-
- query-command = "(" "query" constraint-list query-expression [ eval-expr-list [ eval-array-list ] ] ")"
- query-expression = expression
- constraint-list = "[" { expression } "]"
- eval-expr-list = "[" { expression } "]"
- eval-array-list = "[" { identifier } "]"
-
- -

Examples:

-
- (query [] false)
- (query [(Eq w8 (Read w8 0 mem) 10)] false [] [ mem ])
-
- -

A query command consists a query, consisting of a constraint list and - a query expression, and two optional lists for use when a counterexample is desired.

- -

The constraint-list is a list of expressions (with boolean - type) which are assumed to hold. Although not required in the language, - many solvers require that this set of constraints be - consistent. The query-expression is the expression to determine - the validity of.

- -

If a counterexample is desired for invalid - queries, eval-expr-list is a list of expressions for which a - possible value should be constructed, and eval-array-list is a - list of arrays for which values for the entire array should be - provided. All counterexamples results must be simultaneously - feasible.

- -

Versions

- -

Versions are used to refer to an array with an ordered sequence of writes to it.

- -

Syntax:

-
- version = identifier | "[" [ update-list ] "]" "@" version
- update-list = lhs-expression "=" rhs-expression [ "," update-list ]
-
- -

Examples:

-
- array small_array[2] : w32 -> w8 = symbolic # The array we will read from
-
- (Read w8 0 thing) # No Updates to small_array
- (Read w8 1 [1=0xff] @ small_array) # Read from small_array at byte offset 1 with update where byte 1 set to decimal 255
-
-

A version can be specified either by an identifier, which can refer to an - array or a labelled version, or by an explicit list - of writes which are to be concatenated to another version (the most recent - writes are first).

- -

Expressions

- -

Expressions are strongly typed, and have the following general - form:

-
- "(" EXPR_NAME EXPR_TYPE ... arguments ... ")" -
-

where EXPR_NAME is the expression name, EXPR_TYPE is the - expression type (which may be optional), followed by any additional - arguments.

- -

Primitive Expressions

- -

Expression References

- -

An expression reference can be used to refer to a - previously labelled expression.

- -

Syntax:

-
- expression = identifier
-
- -

Expression and version labels are in separate namespaces, it is the users - responsibility to use separate labels to preserve readability.

- -

Constants

- -

Constants are specified by a numeric token or a type and numeric - token.

- -

Syntax:

-
- expression = number | "(" type number ")"
-
- -

When a constant is specified without a type, the resulting expression - is only well-formed if its type can be inferred from the enclosing - context. The true and false constants always have - type w1. - -

Examples:

-
- true
- (w32 0)
- (Add w32 10 20) # The type for 10 and 20 is inferred to be w32.
-
- -

Arithmetic Operations

- -

Add, - Sub, - Mul, - UDiv, SDiv, URem, SRem

- -

Syntax:

-
- arithmetic-expr-kind = ( "Add" | "Sub" | "Mul" | "UDiv" | "URem" | "SDiv" | "SRem" )
- expression = "(" arithmetic-expr-kind type expression expression ")"
-
- -

Arithmetic operations are always binary and the types of the left- - and right-hand side expressions must match the expression type.

- -

UDiv

-

Truncated unsigned division. Undefined if divisor is 0.

- -

URem

-

Unsigned remainder. Undefined if divisor is 0.

- -

SDiv

-

Signed division. Undefined if divisor is 0.

- -

SRem

-

Signed remainder. Undefined if divisor is 0. Sign of the - remainder is the same as that of the dividend.

- - -

Bitwise Operations

- -

Not

- -

Syntax:

-
- expression = "(" "Not" [ type ] expression ")" -
- -

Bitwise negation. The result is the bitwise negation (one's complement) of - the input expression. If the type is specified, it must match the expression - type.

- -

And, - Or, - Xor, - Shl, - LShr, - AShr

- -

Syntax:

-
- bitwise-expr-kind = ( "And" | "Or" | "Xor" | "Shl" | "LShr" | "AShr" )
- expression = "(" bitwise-expr-kind type expression expression ")"
-
- -

These bitwise operations are always binary and the types of the left- and - right-hand side expressions must match the expression type.

- -

Shl

- -
- expression = "(" "Shl" type X Y ")" -
- -

Logical shift left. Moves each bit of X to the left - by Y positions. The Y right-most bits of X are - replaced with zero, and the left-most bits discarded.

- -

LShr

- -
- expression = "(" "LShr" type X Y ")" -
- -

Logical shift right. Moves each bit of X to the right - by Y positions. The Y left-most bits of X are - replaced with zero, and the right-most bits discarded.

- - -

AShr

- -
- expression = "(" "AShr" type X Y ")" -
- -

Arithmetic shift right. Behaves as LShr except that the - left-most bits of X copy the initial left-most bit (the sign - bit) of X. - -

Comparisons

- -

Eq, - Ne, - Ult, - Ule, - Ugt, - Uge, - Slt, - Sle, - Sgt, - Sge

- -

Syntax:

-
- comparison-expr-kind = ( "Eq" | "Ne" | "Ult" | "Ule" | "Ugt" | "Uge" | "Slt" | "Sle" | "Sgt" | "Sge" )
- expression = "(" comparison-expr-kind [ type ] expression expression ")"
-
- -

Comparison operations are always binary and the types of the left- - and right-hand side expression must match. If the type is specified, it - must be w1.

- -

Bitvector Manipulation

- -

Concat

- -

Syntax:

-
- expression = "(" "Concat" [type] msb-expression lsb-expression ")" -
- -

Concat evaluates to a type bits formed by - concatenating lsb-expression to msb-expression.

- -

Extract

- -

Syntax:

-
- expression = "(" "Extract" type offset-number child-expression ")" -
- -

Extract evaluates to type bits from child-expression - taken from offset-number, where offset-number is the index of - the least-significant bit in child-expression which should be - extracted. - -

ZExt

- -

Syntax:

-
- expression = "(" "ZExt" type child-expression ")" -
- -

ZExt evaluates to the lowest type bits - of child-expression, with undefined bits set to zero.

- -

SExt

- -

Syntax:

-
- expression = "(" "SExt" type input-expression ")" -
- -

SExt evaluates to the lowest type bits - of child-expression, with undefined bits set to the most-significant - bit of input-expression.

- -

Special Expressions

- -

Read

- -

Syntax:

-
- expression = "(" "Read" type index-expression version ")"
-
- -

The Read expression evaluates to the first write - in version for which index-expression is equivalent to - the index in the write. The type of the expression must match the range of the - root array in version, and the type - of index-expression must match the domain.

- -

Select

- -

Syntax:

-
- expression = "(" "Select" type cond-expression true-expression false-expression ")"
-
- -

The Select expression evalues to true-expression if the - condition evaluates to true, and to false-expression if the condition - evaluates to false. The cond-expression must have type w1.

- -

Both the true and false expressions must be well-formed, regardless of the - condition expression. In particular, it is not legal for one of the - expressions to cause a division-by-zero during evaluation, even if - the Select expression will never evaluate to that expression.

- -

Macro Expressions

- -

Several common expressions are not implemented directly in the Expr - library, but can be expressed in terms of other operations. A number of these - are implemented as "macros". The pretty printer recognizes and prints the - appropriate Expr forms as the macro, and the parser recognizes them and turns - them into the underlying representation.

- -

Neg

- -

Syntax:

-
- expression = "(" "Neg" [ type ] expression ")" -
- -

This macro form can be used to generate a Sub from zero.

- -

ReadLSB, - ReadMSB

- -

Syntax:

-
- expression = "(" "ReadLSB" type index-expression version ")"
- expression = "(" "ReadMSB" type index-expression version ")"
-
- -

ReadLSB and ReadMSB can be used to simplify contiguous array - accesses. The type of the expression must be a multiple N of the array - range type. The expression expands to a concatenation of N read - expressions, where each read is done at a subsequent offset from - the index-expression. For ReadLSB (ReadMSB), the - concatentation is done such that the read at index-expression forms the - least- (most-) significant bits.

-
- - - diff --git a/www/OpenProjects.html b/www/OpenProjects.html deleted file mode 100644 index d4a01964..00000000 --- a/www/OpenProjects.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - - - KLEE - Open Projects - - - - - -
- -

KLEE Open Projects

- - - This page lists a variety of open projects that are natural (and tractable) - extensions of KLEE and things that we would love to see people work on. If - you are interested in tackling any of the projects, please mail - klee-dev - with your ideas -- or even better, your patches!. - -
    -
  • - Implement SMT support for Kleaver: - -

    We would like to make Kleaver (KLEE's constraint solver) a more viable - standalone product. One of the steps in this direction is to implement SMT - support. This would also allow us to enter Kleaver into - the SMT-COMP theorem prover - competition, which would be a good proving ground for our optimizations - and benchmarking our underlying constraint solver (STP, currently) against - other implementations.

    -
    • - -
  • - Distributed Constraint Solving: - -

    Much of the execution time of KLEE is spent inside the constraint - solver. A natural extension would be to implement support for a - distributed constraint solver, which would run KLEE on a single machine, - but would farm out the constraints to be solved on a network of - machines.

    -
    • - -
  • - Improve User Interface: - -

    This is not a very glamorous project, but it is still - important. Currently, KLEE has a myriad of command line options and flags, - most of which are left over from its research project roots. In order to - promote KLEE's use as a user tool, we would like to clean up most of the - UI so that the default behavior matches best practice, and so that more - arcane or research-only options are hidden by default.

    -
    • - -
  • - Experiment With Other Constraint Solvers: - -

    For the most part, KLEE has been written so that it is possible to swap - in other constraint solvers, but we have never tried anything other than - STP. We would love to see the results of using other contraint solvers - (like Yices or Z3) with KLEE.

    -
    • - -
  • - Implement Expression Level Constraint Optimization: - -

    KLEE does not currently do much optimization of constraint expressions - before sending them to the constraint solver. We would like to have an - internal framework for doing optimization of constraint expressions (e.g., - (A & ~A) => 0) so that these optimizations are only done once instead of - on every solver query.

    - -

    In general, because KLEE is dealing with expressions which result from - dynamic execution traces, many expressions end up having constant - components. This means we can frequently apply the same optimizations a - compiler would do, but to much greater effect because we are more likely - to see constant values. For reference, see the kinds of optimizations done - by LLVM's InstCombine - pass here.

    - -

    The bulk of this project involves defining a good framework for us to - apply optimizations to expressions, and for deciding when to attempt to - optimization expressions.

    -
    • -
-
- - diff --git a/www/Publications.html b/www/Publications.html deleted file mode 100644 index 2a2dd313..00000000 --- a/www/Publications.html +++ /dev/null @@ -1,402 +0,0 @@ - - - - - - KLEE - Publications - - - - - -
- -

KLEE-related Publications and Systems

- - -

Below you can find a list of papers that use or extend KLEE. - Papers are listed in chronological order.
If you have used and - extended KLEE, please share your experience by having your paper - listed here (email klee-dev-owner or c.cadar AT imperial.ac.uk).

- -
    -
  1. - - - KLEE: Unassisted and Automatic Generation of High-Coverage Tests for - Complex Systems Programs - - -
    - Cristian Cadar, Daniel Dunbar, Dawson Engler -
    - USENIX Symposium on Operating Systems Design and Implementation (OSDI 2008) -
    - December 8-10, 2008, San Diego, CA, USA -

    -
    2. - -
  2. - - - Server-side Verification of Client Behavior in Online Games - - -
    - Darrell Bethea, Robert Cochran, Michael Reiter -
    - Network and Distributed System Security Symposium (NDSS 2010) -
    - February 28 - March 3, San Diego, CA, USA -

    -
    3. - -
  3. - - - KleeNet: Discovering Insidious Interaction Bugs in Wireless Sensor Networks Before Deployment - - -
    - Raimondas Sasnauskas, Olaf Landsiedel, Muhammad Hamad Alizai, - Carsten Weise, Stefan Kowalewski, Klaus Wehrle -
    - ACM/IEEE International Conference on Information Processing in Sensor Networks (IPSN 2010) -
    - April 12-16, 2010, Stockholm, Sweden -
    - KleeNet is available here. -

    -
    4. - -
  4. - - - Execution Synthesis: A Technique for Automated Software Debugging - - -
    - Cristian Zamfir, George Candea -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) -
    - April 13-16, 2010, Paris, France -

    -
    5. - -
  5. - - - Reverse Engineering of Binary Device Drivers with RevNIC - - -
    - Vitaly Chipounov, George Candea -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2010) -
    - April 13-16, 2010, Paris, France -

    -
    6. - -
  6. - - - Testing Closed-Source Binary Device Drivers with DDT - - -
    - Volodymyr Kuznetsov, Vitaly Chipounov, George Candea -
    - USENIX Annual Technical Conference (USENIX ATC 2010) -
    - June 22-25, 2010, Boston, MA, USA -

    -
    7. - -
  7. - - - Stable Deterministic Multithreading through Schedule Memoization - - -
    - Heming Cui, Jingyue Wu, Chia-che Tsai, Junfeng Yang -
    - USENIX Symposium on Operating Systems Design and Implementation (OSDI 2010) -
    - October 4-6, 2010, Vancouver, BC, Canada -

    -
    8. - -
  8. - - - AEG: Automatic Exploit Generation - - -
    - Thanassis Avgerinos, Sang Kil Cha, Brent Lim Tze Hao, David Brumley -
    - Network and Distributed System Security Symposium (NDSS 2011) -
    - February 6-9, 2011, San Diego, CA, USA -

    -
    9. - -
  9. - - - Howard: A Dynamic Excavator for Reverse Engineering Data Structures - - -
    - Asia Slowinska, Traian Stancescu, Herbert Bos -
    - Network and Distributed System Security Symposium (NDSS 2011) -
    - February 6-9, 2011, San Diego, CA, USA -

    -
    10. - -
  10. - - - S2E: A Platform for In Vivo Multi-Path Analysis of Software Systems - - -
    - Vitaly Chipounov, Volodymyr Kuznetsov, George Candea -
    - International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS 2011) -
    - March 5-11, 2011, Newport Beach, CA -
    - S2E is available here. -

    -
    11. - -
  11. - - - Parallel Symbolic Execution for Automated Real-World Software Testing - - -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) -
    - Stefan Bucur, Vlad Ureche, Cristian Zamfir, George Candea -
    - April 10-13, 2011, Salzburg, Austria -
    - Cloud9 is available here. -

    -
    12. - -
  12. - - - Symbolic Crosschecking of Floating-Point and SIMD Code - - -
    - Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly -
    - ACM SIGOPS/EuroSys European Conference on Computer Systems (EuroSys 2011) -
    - April 10-13, 2011, Salzburg, Austria -

    -
    13. - -
  13. - - - Practical, Low-Effort Equivalence Verification of Real Code - - -
    - David Ramos, Dawson Engler -
    - Computer Aided Verification (CAV 2011) -
    - July 16-20, 2011, Snowbird, UT, USA -

    -
    14. - -
  14. - - - Scalable Symbolic Execution of Distributed Systems - - -
    - Raimondas Sasnauskas, Oscar Soria Dustmann, Benjamin Lucien Kaminski, - Carsten Weise, Stefan Kowalewski, Klaus Wehrle -
    - IEEE International Conference on Distributed Computing Systems (ICDCS 2011) -
    - June 20-24, 2011, Minneapolis, MN, USA -

    -
    15. - -
  15. - - - Efficient Deterministic Multithreading through Schedule Relaxation - - -
    - Heming Cui, Jingyue Wu, John Gallagher, Huayang Guo, Junfeng Yang -
    - ACM Symposium on Operating Systems Principles (SOSP 2011) -
    - October 23-26, 2011, Cascais, Portugal -

    -
    16. - -
  16. - - - KLOVER: A Symbolic Execution and Automatic Test Generation Tool for C++ Programs - - -
    - Guodong Li, Indradeep Ghosh and Sreeranga Rajan -
    - International Conference on Computer Aided Verification (CAV 2011) -
    - July 14-20, 2011, Cliff Lodge, Snowbird, UT, USA -

    -
    17. - -
  17. - - - Symbolic Testing of OpenCL Code - - -
    - Peter Collingbourne, Cristian Cadar, Paul H. J. Kelly -
    - Haifa Verification Conference (HVC 2011) -
    - December 6-8, 2011, Haifa, Israel -

    -
    18. - -
  18. - - - GKLEE: Concolic Verification and Test Generation for GPUs - - -
    - Guodong Li, Peng Li, Geof Sawaya, Ganesh Gopalakrishnan, Indradeep Ghosh, and Sreeranga P. Rajan -
    - ACM Symposium on Principles and Practice of Parallel Programming (PPoPP 2012) -
    - February 25-29, 2012, New Orleans, LA, USA -
    - GKLEE is available here. -

    -
    19. - -
  19. - - - make test-zesti: A Symbolic Execution Solution for Improving Regression Testing - - -
    - Paul Dan Marinescu, Cristian Cadar -
    - International Conference on Software Engineering (ICSE 2012) -
    - June 2-9, 2012, Zurich, Switzerland -
    - ZESTI is available here. -

    -
    20. - -
  20. - - - BugRedux: Reproducing Field Failures for In-House Debugging - - -
    - Wei Jin, Alessandro Orso -
    - International Conference on Software Engineering (ICSE 2012) -
    - June 2-9, 2012, Zurich, Switzerland -
    - BugRedux is available here. -

    -
    21. - -
  21. - - - Efficient State Merging in Symbolic Execution - - -
    - Volodymyr Kuznetsov, Johannes Kinder, Stefan Bucur, George Candea -
    - Programming Language Design and Implementation (PLDI) -
    - June 11-16, 2012, Beijing, China -

    -
    22. - -
  22. - - - High-Coverage Symbolic Patch Testing - - -
    - Paul Dan Marinescu, Cristian Cadar -
    - SPIN Workshop on Model Checking of Software (SPIN 2012) -
    - July 23-24, 2012, Oxford, UK -

    -
    23. - -
  23. - - - Automatic Detection of Floating-Point Exceptions - - -
    - Peter C. Rigby, Earl T. Barr, Christian Bird, Premkumar Devanbu, Daniel M. German -
    - Principles of Programming Languages (POPL) -
    - January 23-25, 2013, Rome, Italy -

    -
    24. - -
  24. - - - Redundant State Detection for Dynamic Symbolic Execution - - -
    - Suhabe Bugrara, Dawson Engler -
    - USENIX Annual Technical Conference (USENIX ATC 2013) -
    - June 26-28, 2013, San Jose, California. -

    -
    25. - -
-
- - diff --git a/www/TestingCoreutils.html b/www/TestingCoreutils.html deleted file mode 100644 index 7ae49302..00000000 --- a/www/TestingCoreutils.html +++ /dev/null @@ -1,893 +0,0 @@ - - - - - - KLEE - Coreutils Case Study - - - - - -
- -

Coreutils Case Study

- -

- As a more detailed explanation of using KLEE, we will look at how we did our - testing of GNU - Coreutils using KLEE. -

- -

This tutorial assumes that you have configured and built KLEE - with uclibc and POSIX runtime support. -

- -

These tests were done on a 32-bit Linux machine. On a 64-bit - machine, we needed to also set the LD_LIBRARY_PATH environment - variable: - 

-    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64 (Fedora)
-    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/x86_64-linux-gnu (Ubuntu)
-
-

- - - -

Step 1: Build coreutils with gcov

- -

- First you will need to download and unpack the source - for coreutils. In this - example we use version 6.11 (one version later than what was used for our - OSDI paper). -

- -

- Before we build with LLVM, let's build a version of coreutils - with gcov support. We will use this later to get coverage - information on the test cases produced by KLEE. -

- -

- From inside the coreutils directory, we'll do the usual - configure/make steps inside a subdirectory (obj-gcov). Here are the - steps: -

- -
- 
-coreutils-6.11$ mkdir obj-gcov
-coreutils-6.11$ cd obj-gcov
-obj-gcov$ ../configure --disable-nls CFLAGS="-g -fprofile-arcs -ftest-coverage"
-... verify that configure worked ...
-obj-gcov$ make
-obj-gcov$ make -C src arch hostname
-... verify that make worked ...
-
- -

- We build with --disable-nls because this adds a lot of extra - initialization in the C library which we are not interested in testing. Even - though these aren't the executables that KLEE will be running on, we want to - use the same compiler flags so that the test cases KLEE generates are most - likely to work correctly when run on the uninstrumented binaries. -

- -

- You should now have a set of coreutils in - the objc-gcov/src directory. For example: -

- -
- 
-obj-gcov$ cd src
-src$ ls -l ls echo cat
--rwxr-xr-x 1 ddunbar ddunbar 164841 2009-07-25 20:58 cat
--rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
--rwxr-xr-x 1 ddunbar ddunbar 439712 2009-07-25 20:58 ls
-src$ ./cat --version
-cat (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by Torbjorn Granlund and Richard M. Stallman.
-
- -

- In addition, these executables should be built with gcov support, - so if you run one it will write a .gcda into the current - directory. That file contains information about exactly what code was - executed when the program ran. See - the Gcov - Documentation for more information. We can use the gcov tool - itself to produce a human readable form of the coverage information. For - example: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ ./echo
-
-src$ ls -l echo.gcda
--rw-r--r-- 1 ddunbar ddunbar 1832 2009-08-04 21:14 echo.gcda
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:0.00% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:18.81% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- By default gcov will show the number of lines executed in the - program (the .h files include code which was compiled - into echo.c). -

- - - -

Step 2: Build coreutils with LLVM

- -

- One of the difficult parts of testing real software using KLEE is that it - must be first compiled so that the final program is an LLVM bitcode file and - not a linked executable. The software's build system may be set up to use - tools such as 'ar', 'libtool', and 'ld', which do not in general understand - LLVM bitcode files. -

- -

- It depends on the actual project what the best way to do this is. For - coreutils, we use a helper script klee-gcc, which acts - like llvm-gcc but adds additional arguments to cause it to emit - LLVM bitcode files and to call llvm-ld to link executables. This - is not a general solution, and your mileage may vary. -

- - - -

- As before, we will build in a separate directory so we can easily access - both the native executables and the LLVM versions. Here are the steps: -

- -
- 
-coreutils-6.11$ mkdir obj-llvm
-coreutils-6.11$ cd obj-llvm
-obj-llvm$ ../configure --disable-nls CFLAGS="-g"
-... verify that configure worked ...
-obj-llvm$ make CC=/full/path/to/klee/scripts/klee-gcc
-obj-llvm$ make -C src arch hostname CC=/full/path/to/klee/scripts/klee-gcc
-... verify that make worked ...
-
- -

- Notice that we made two changes. First, we don't want to add gcov - instrumentation in the binary we are going to test using KLEE, so we left of - the -fprofile-arcs -ftest-coverage flags. Second, when running - make, we set the CC variable to point to our klee-gcc - wrapper script. -

- -

- If all went well, you should now have LLVM bitcode versions of coreutils! For - example: -

- -
- 
-obj-llvm$ cd src
-src$ ls -l ls echo cat
--rwxr-xr-x 1 ddunbar ddunbar 65 2009-07-25 23:40 cat
--rwxr-xr-x 1 ddunbar ddunbar 66 2009-07-25 23:43 echo
--rwxr-xr-x 1 ddunbar ddunbar 94 2009-07-25 23:38 ls
-src$ ./cat --version
-cat (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-LLVM ERROR: JIT does not support inline asm!
-
- -

- You may notice some funny things going on. To start with, the files are way - too small! Since we are actually producing LLVM bitcode files, the operating - system can't run them directly. What llvm-ld does to make it so we - can still run the resulting outputs is write a little shell script which - uses the LLVM interpreter to run the binaries; the actual LLVM bitcode - files have .bc appended. If we look a little closer: -

- -
- 
-src$ cat ls
-#!/bin/sh
-lli=${LLVMINTERP-lli}
-exec $lli \
-    -load=/usr/lib/librt.so \
-    ls.bc ${1+"$@"}
-src$ ls -l ls.bc
--rwxr-xr-x 1 ddunbar ddunbar 643640 2009-07-25 23:38 ls.bc
-
- -

- The other funny thing is that the version message doesn't all print out, the - LLVM interpreter emits a message about not supporting inline assembly. The - problem here is that glibc occasionally implements certain - operations using inline assembly, which the LLVM interpreter (lli) - doesn't understand. KLEE works around this problem by specially recognizing - certain common inline assembly sequences and turning them back into the - appropriate LLVM instructions before executing the binary. -

- - - -

Step 3: Using KLEE as an interpreter

- -

- At its core, KLEE is just an interpreter for LLVM bitcode. For example, here - is how to run the same cat command we did before, using KLEE. Note, - this step requires that you configured and built KLEE with uclibc - and POSIX runtime support (if you didn't, you'll need to go do that - now). -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./cat.bc --version
-KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
-KLEE: output directory = "klee-out-3"
-KLEE: WARNING: undefined reference to function: __signbitl
-KLEE: WARNING: executable has module level assembly (ignoring)
-KLEE: WARNING: calling external: syscall(54, 0, 21505, 177325672)
-KLEE: WARNING: calling __user_main with extra arguments.
-KLEE: WARNING: calling external: getpagesize()
-KLEE: WARNING: calling external: vprintf(177640072, 183340048)
-cat (GNU coreutils) 6.11
-
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by Torbjorn Granlund and Richard M. Stallman.
-KLEE: WARNING: calling close_stdout with extra arguments.
-Copyright (C) 2008 Free Software Foundation, Inc.
-KLEE: done: total instructions = 259357
-KLEE: done: completed paths = 1
-KLEE: done: generated tests = 1
-
- -

- We got a lot more output this time! Let's step through it, starting with the - KLEE command itself. The general form of a KLEE command line is first the - arguments for KLEE itself, then the LLVM bitcode file to execute - (cat.bc), and then any arguments to pass to the application - (--version in this case, as before). -

- -

- If we were running a normal native application, it would have been linked - with the C library, but in this case KLEE is running the LLVM bitcode file - directly. In order for KLEE to work effectively, it needs to have - definitions for all the external functions the program may call. We have - modified the uClibc C library - implementation for use with KLEE; the --libc=uclibc KLEE argument - tells KLEE to load that library and link it with the application before it - starts execution. -

- -

- Similarly, a native application would be running on top of an operating - system that provides lower level facilities like write(), which the - C library uses in its implementation. As before, KLEE needs definitions for - these functions in order to fully understand the program. We provide a POSIX - runtime which is designed to work with KLEE and the uClibc library to - provide the majority of operating system facilities used by command line - applications -- the --posix-runtime argument tells KLEE to link - this library in as well. -

- -

- As before, cat prints out its version information (note that this - time all the text is written out), but we now have a number of additional - information output by KLEE. In this case, most of these warnings are - innocuous, but for completeness here is what they mean: -

- -
    -
  • undefined reference to function: __signbitl: This warning means - that the program contains a call to the function __signbitl, - but that function isn't defined anywhere (we would have seen a lot more - of these if we had not linked with uClibc and the POSIX runtime). If the - program actually ends up making a call to this function while it is - executing, KLEE won't be able to interpret it and may terminate the - program.
    • - -
  • executable has module level assembly (ignoring): Some file - compiled in to the application had file level inline-assembly, which KLEE - can't understand. In this case this comes from uClibc and is unused, so - this is safe.
    • - -
  • calling __user_main with extra arguments: This indicates that - the function was called with more arguments than it expected, it is - almost always innocuous. In this case __user_main is actually - the main() function for cat, which KLEE has renamed it - when linking with uClibc. main() is being called with - additional arguments by uClibc itself during startup, for example the - environment pointer.
    • - -
  • calling external: getpagesize(): This is an example of KLEE - calling a function which is used in the program but is never - defined. What KLEE actually does in such cases is try to call the native - version of the function, if it exists. This is sometimes safe, as long - as that function does write to any of the programs memory or attempt to - manipulate symbolic values. getpagesize(), for example, just - returns a constant.
    • -
- -

- In general, KLEE will only emit a given warning once. The warnings are also - logged to warnings.txt in the KLEE output directory. -

- - - -

Step 4: Introducing symbolic data to an application

- -

- We've seen that KLEE can interpret a program normally, but the real purpose - of KLEE is to explore programs more exhaustively by making parts of their - input symbolic. For example, lets look at running KLEE on the echo - application. -

- -

- When using uClibc and the POSIX runtime, KLEE replaces the - program's main() function with a special function - (klee_init_env) provided inside the runtime library. This - function alters the normal command line processing of the - application, in particular to support construction of symbolic - arguments. For example, passing --help yields: -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./echo.bc --help
-...
-
-usage: (klee_init_env) [options] [program arguments]
-  -sym-arg               - Replace by a symbolic argument with length N
-  -sym-args    - Replace by at least MIN arguments and at most
-                              MAX arguments, each with maximum length N
-  -sym-files        - Make stdin and up to NUM symbolic files, each
-                              with maximum size N.
-  -sym-stdout               - Make stdout symbolic.
-  -max-fail              - Allow up to  injected failures
-  -fd-fail                  - Shortcut for '-max-fail 1'
-...
-
- -

- As an example, lets run echo with a symbolic argument of 3 - characters. -

- -
- 
-src$ klee --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
-KLEE: NOTE: Using model: /home/ddunbar/public/klee/Release/lib/libkleeRuntimePOSIX.bca
-KLEE: output directory = "klee-out-16"
-KLEE: WARNING: undefined reference to function: __signbitl
-KLEE: WARNING: executable has module level assembly (ignoring)
-KLEE: WARNING: calling external: syscall(54, 0, 21505, 189414856)
-KLEE: WARNING: calling __user_main with extra arguments.
-..
-KLEE: WARNING: calling close_stdout with extra arguments.
-...
-KLEE: WARNING: calling external: printf(183664896, 183580400)
-Usage: ./echo.bc [OPTION]... [STRING]...
-Echo the STRING(s) to standard output.
-
-  -n             do not output the trailing newline
-  -e             enable interpretation of backslash escapes
-  -E             disable interpretation of backslash escapes (default)
-      --help     display this help and exit
-      --version  output version information and exit
-
-If -e is in effect, the following sequences are recognized:
-
-  \0NNN   the character whose ASCII code is NNN (octal)
-  \\     backslash
-  \a     alert (BEL)
-  \b     backspace
-  \c     suppress trailing newline
-  \f     form feed
-  \n     new line
-  \r     carriage return
-  \t     horizontal tab
-  \v     vertical tab
-
-NOTE: your shell may have its own version of echo, which usually supersedes
-the version described here.  Please refer to your shell's documentation
-for details about the options it supports.
-
-Report bugs to .
-KLEE: WARNING: calling external: vprintf(183956664, 190534360)
-echo (GNU coreutils) 6.11
-
-License GPLv3+: GNU GPL version 3 or later 
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Written by FIXME unknown.
-...
-...
-...
-
-
-
-
-..
-
-
-.
-
-.
-..
-...
-Copyright (C) 2008 Free Software Foundation, Inc.
-KLEE: done: total instructions = 300193
-KLEE: done: completed paths = 25
-KLEE: done: generated tests = 25
-
- -

- The results here are slightly more interesting, KLEE has explored 25 paths - through the program. The output from all the paths is intermingled, but you - can see that in addition to echoing various random characters, some blocks - of text also were output. You may be suprised to learn that - coreutils' echo takes some arguments, in this case the - options --v (short for --version) and --h (short - for --help) were explored. We can get a short summary of KLEE's - internal statistics by running klee-stats on the output directory - (remember, KLEE always makes a symlink called klee-last to the most - recent output directory). -

- -
- 
-src$ klee-stats klee-last
--------------------------------------------------------------------------
-| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
--------------------------------------------------------------------------
-| klee-last | 300673 |    1.47 |   28.18 |   17.37 |  28635 |      5.65 |
--------------------------------------------------------------------------
-
- -

- Here ICov is the percentage of LLVM instructions which were - covered, and BCov is the percentage of branches that were - covered. You may be wondering why the percentages are so low -- how much - more code can echo have! The main reason is that these numbers are computed - using all the instructions or branches in the bitcode files; that includes a - lot of library code which may not even be executable. We can help with that - problem (and others) by passing the --optimize option to KLEE. This - will cause KLEE to run the LLVM optimization passes on the bitcode module - before executing it; in particular they will remove any dead code. When - working with non-trivial applications, it is almost always a good idea to - use this flag. Here are the results from running again - with --optimze enabled: -

- -
- 
-src$ klee --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-arg 3
-...
-KLEE: done: total instructions = 123251
-KLEE: done: completed paths = 25
-KLEE: done: generated tests = 25
-src$ klee-stats klee-last
--------------------------------------------------------------------------
-| Path      | Instrs | Time(s) | ICov(%) | BCov(%) | ICount | Solver(%) |
--------------------------------------------------------------------------
-| klee-last | 123251 |    0.32 |   38.02 |   25.43 |   9531 |     29.66 |
--------------------------------------------------------------------------
-
- -

- This time the instruction coverage went up by about ten percent, and you can - see that KLEE also ran faster and executed less instructions. Most of the - remaining code is still in library functions, just in places that the - optimizers aren't smart enough to remove. We can verify this -- and look for - uncovered code inside echo -- by using KCachegrind to visualize the - results of a KLEE run. -

- - - -

Step 5: Visualizing KLEE's progress with kcachegrind

- -

- KCachegrind is an excellent - profiling visualization tool, originally written for use with the callgrind - plugin for valgrind. If you don't have it already, it is usually easily - available on a modern Linux distribution via your platforms' software - installation tool (e.g., apt-get or yum). -

- -

- KLEE by default writes out a run.istats file into the test output - directory which is actually a KCachegrind file. In this example, - the run.istats is from a run without --optimize, so the - results are easier to understand. Assuming you have KCachegrind installed, - just run: -

- -
- 
 src$ kcachegrind klee-last/run.istats
-
- -

- After KCachegrind opens, you should see a window that looks something like - the one below. You should make sure that the "Instructions" statistic is - selected by choosing "View" > "Primary Event Type" > "Instructions" - from the menu, and make sure the "Source Code" view is selected (the right - hand pane in the screenshot below). -

- - - - -

- KCachegrind is a complex application in itself, and interested users should - see the KCachegrind website for more information and documentation. However, - the basics are that the one pane shows the "Flat Profile"; this is a list of - which how many instructions were executed in each function. The "Self" - column is the number of instructions which were executed in the function - itself, and the "Incl" (inclusive) column is the number of instructions - which were executed in the function, or any of the functions it called (or - its callees called, and so on). -

- -

- KLEE includes quite a few statistics about execution. The one we are - interested in now is "Uncovered Instructions", which will show which - functions have instructions which were never executed. If you select that - statistic and resort the list of functions, you should see something like - this: -

- - - - -

- Notice that most of the uncovered instructions are in library code as we - would expect. However, if we select the __user_main function, we - can look for code inside echo itself that was uncovered. In this - case, most of the uncovered instructions are inside a large if - statement guarded by the variable do_v9. If you look a bit more, - you can see that this is a flag set to true when -e is passed. The - reason that KLEE never explored this code is because we only passed one - symbolic argument -- hitting this code requires a command line like $ - echo -e \a. -

- -

- One subtle thing to understand if you are trying to actually make sense of - the KCachegrind numbers is that they include events accumulated across all - states. For example, consider the following code: -

- -
- 
-Line 1:      a = 1;
-Line 2:      if (...)
-Line 3:        printf("hello\n");
-Line 4:      b = c;
-
- -

- In a normal application, if the statement on Line 1 was only executed once, - then the statement on Line 4 could be (at most) executed once. When KLEE is - running an application, however, it could fork and generate separate - processes at Line 2. In that case, Line 4 may be executed more times than - Line 1! -

- -

- Another useful tidbit: KLEE actually writes the run.istats file - periodically as the application is running. This provides one way to monitor - the status of long running applications (another way is to use the - klee-stats tool). -

- - - -

Step 6: Replaying KLEE generated test cases

- -

- Let's step away from KLEE for a bit and look at just the test cases KLEE - generated. If we look inside the klee-last we should see - 25 .ktest files. -

- -
- 
-src$ ls klee-last
-assembly.ll	  test000004.ktest  test000012.ktest  test000020.ktest
-info		  test000005.ktest  test000013.ktest  test000021.ktest
-messages.txt	  test000006.ktest  test000014.ktest  test000022.ktest
-run.istats	  test000007.ktest  test000015.ktest  test000023.ktest
-run.stats	  test000008.ktest  test000016.ktest  test000024.ktest
-test000001.ktest  test000009.ktest  test000017.ktest  test000025.ktest
-test000002.ktest  test000010.ktest  test000018.ktest  warnings.txt
-test000003.ktest  test000011.ktest  test000019.ktest
-
- -

- These files contain the actual values to use for the symbolic data in order - to reproduce the path that KLEE followed (either for obtaining code - coverage, or for reproducing a bug). They also contain additional metadata - generated by the POSIX runtime in order to track what the values correspond - to and the version of the runtime. We can look at the individual contents of - one file using ktest-tool: -

- -
- 
-$ ktest-tool klee-last/test000001.ktest
-ktest file : 'klee-last/test000001.ktest'
-args       : ['./echo.bc', '--sym-arg', '3']
-num objects: 2
-object    0: name: 'arg0'
-object    0: size: 4
-object    0: data: '@@@\x00'
-object    1: name: 'model_version'
-object    1: size: 4
-object    1: data: '\x01\x00\x00\x00'
-
- -

- In this case, the test case indicates that values "@@@\x00" should be passed - as the first argument. However, .ktest files generally aren't - really meant to be looked at directly. For the POSIX runtime, we provide a - tool klee-replay which can be used to read the .ktest file - and invoke the native application, automatically passing it the data - necessary to reproduce the path that KLEE followed. -

- -

- To see how it works, go back to the directory where we built the native - executables: -

- -
- 
-src$ cd ..
-obj-llvm$ cd ..
-coreutils-6.11$ cd obj-gcov
-obj-gcov$ cd src
-src$ ls -l echo
--rwxr-xr-x 1 ddunbar ddunbar 151051 2009-07-25 20:59 echo
-
- -

- To use the klee-replay tool, we just tell it the executable to run - and the .ktest file to use. The program arguments, input files, - etc. will all be constructed from the data in the .ktest file. -

- -
- 
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/test000001.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" "@@@" 
-@@@
-klee-replay: EXIT STATUS: NORMAL (0 seconds)
-
- -

- The first two and last lines here come from the klee-replay tool - itself. The first two lines list the test case being run, and the concrete - values for arguments that are being passed to the application (notice this - matches what we saw in the .ktest file earlier). The last line is - the exit status of the program and the elapsed time to run. -

- -

- We can also use the klee-replay tool to run a set of test cases at - once, one after the other. Let's do this and compare the gcov - coverage to the numbers we got from klee-stats: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" "@@@" 
-@@@
-klee-replay: EXIT STATUS: NORMAL (0 seconds)
-...
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000022.ktest
-klee-replay: ARGS: "./echo" "--v" 
-echo (GNU coreutils) 6.11
-Copyright (C) 2008 Free Software Foundation, Inc.
-...
-
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:6.38% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:50.50% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- The number for echo.c here significantly higher than - the klee-stats number because gcov is only considering - lines in that one file, not the entire application. As with kcachegrind, we can inspect the coverage file output by gcov to see exactly what lines were covered and which weren't. Here is a fragment from the output: -

- -
- 
-        -:  193:      }
-        -:  194:
-       23:  195:just_echo:
-        -:  196:
-       23:  197:  if (do_v9)
-        -:  198:    {
-       10:  199:      while (argc > 0)
-        -:  200:	{
-    #####:  201:	  char const *s = argv[0];
-        -:  202:	  unsigned char c;
-        -:  203:
-    #####:  204:	  while ((c = *s++))
-        -:  205:	    {
-    #####:  206:	      if (c == '\\' && *s)
-        -:  207:		{
-    #####:  208:		  switch (c = *s++)
-        -:  209:		    {
-    #####:  210:		    case 'a': c = '\a'; break;
-    #####:  211:		    case 'b': c = '\b'; break;
-    #####:  212:		    case 'c': exit (EXIT_SUCCESS);
-    #####:  213:		    case 'f': c = '\f'; break;
-    #####:  214:		    case 'n': c = '\n'; break;
-
- -

- The far left hand column is the number of times each line was - executed; - means the line has no executable code, and ##### - means the line was never covered. As you can see, the uncovered lines here - correspond exactly to the uncovered lines as reported - in kcachegrind. -

- -

- Before moving on to testing more complex applications, lets make sure we can - get decent coverage of the simple echo.c. The problem before was - that we weren't making enough data symbolic, providing echo with two - symbolic arguments should be plenty to cover the entire program. We can use - the POSIX runtime --sym-args option to pass multiple options. Here - are the steps, after switching back to the obj-llvm/src directory: -

- -
- 
-src$ klee --only-output-states-covering-new --optimize --libc=uclibc --posix-runtime ./echo.bc --sym-args 0 2 4
- ... 
-KLEE: done: total instructions = 7437521
-KLEE: done: completed paths = 9963
-KLEE: done: generated tests = 55
-
- -

- The format of the --sym-args option actually specifies a minimum - and a maximum number of arguments to pass and the length to use for each - argument. In this case --sym-args 0 2 4 says to pass between 0 and - 2 arguments (inclusive), each with a maximum length of four characters. -

- -

- We also added the --only-output-states-covering-new option to the - KLEE command line. By default KLEE will write out test cases for every path - it explores. This becomes less useful once the program becomes larger, because many test cases will end up - exercise the same paths, and computing (or even reexecuting) each one wastes - time. Using this option tells KLEE to only output test cases for paths which - covered some new instruction in the code (or hit an error). The final lines - of the output show that even though KLEE explored almost ten thousand paths - through the code, it only needed to write 55 test cases. -

- -

- If we go back to the obj-gcov/src directory and rerun the latest - set of test cases, we finally have reasonable coverage of echo.c: -

- -
- 
-src$ rm -f *.gcda # Get rid of any stale gcov files
-src$ klee-replay ./echo ../../obj-llvm/src/klee-last/*.ktest 
-klee-replay: TEST CASE: ../../obj-llvm/src/klee-last/test000001.ktest
-klee-replay: ARGS: "./echo" 
-
- ... 
-
-src$ gcov echo
-File '../../src/system.h'
-Lines executed:6.38% of 47
-../../src/system.h:creating 'system.h.gcov'
-
-File '../../lib/timespec.h'
-Lines executed:0.00% of 2
-../../lib/timespec.h:creating 'timespec.h.gcov'
-
-File '../../lib/gettext.h'
-Lines executed:0.00% of 32
-../../lib/gettext.h:creating 'gettext.h.gcov'
-
-File '../../lib/openat.h'
-Lines executed:0.00% of 8
-../../lib/openat.h:creating 'openat.h.gcov'
-
-File '../../src/echo.c'
-Lines executed:97.03% of 101
-../../src/echo.c:creating 'echo.c.gcov'
-
- -

- The reasons for not getting perfect 100% line coverage are left as an - exercise to the reader. :) -

- - - -

Step 7: Using zcov to analyze coverage

- -

- For visualizing the coverage results, you might want to use the zcov tool. -

-
- -
- - diff --git a/www/Tutorial-1.html b/www/Tutorial-1.html deleted file mode 100644 index 38c3b101..00000000 --- a/www/Tutorial-1.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - - - KLEE - Tutorial One - - - - - -
- -

Tutorial One: Testing a Small Function

- - -

The demo code

- - This tutorial walks you through the main steps needed to test a - simple function with KLEE. Here is our simple function: - - 
-  int get_sign(int x) {
-    if (x == 0)
-       return 0;
-
-    if (x < 0)
-       return -1;
-    else 
-       return 1;
-  }
- - You can find the entire code for this example in the source tree - under examples/get_sign. A version of the source code can - also be accessed here. - -

Marking input as symbolic

- - In order to test this function with KLEE, we need to run it - on symbolic input. To mark a variable as symbolic, we use - the klee_make_symbolic() function, which takes three - arguments: the address of the variable (memory location) that we - want to treat as symbolic, its size, and a name (which can be - anything). Here is a simple main() function that marks a - variable a as symbolic and uses it to - call get_sign(): - - 
-  int main() {
-      int a;
-      klee_make_symbolic(&a, sizeof(a), "a");
-      return get_sign(a);
-  }
- - - -

Compiling to LLVM bitcode

- - KLEE operates on LLVM bitcode. To run a program with KLEE, you - first compile it to LLVM bitcode using llvm-gcc - --emit-llvm. Assuming our code is stored in get_sign.c, - we run: - -
- llvm-gcc --emit-llvm -c -g get_sign.c -
- - to generate the LLVM bitcode file get_sign.o. - - It is useful to (1) build with -g to add debug information - to the bitcode file, which we use to generate source line level - statistics information, and (2) not use any optimization flags. The - code can be optimized later, as KLEE provides the - --optimize command line option to run the optimizer - internally. - -

Running KLEE

- - To run KLEE on the bitcode file simply execute: - -
- klee get_sign.o -
- - You should see the following output (assumes LLVM 2.8): - 
-  KLEE: output directory = "klee-out-0"
-
-  KLEE: done: total instructions = 51
-  KLEE: done: completed paths = 3
-  KLEE: done: generated tests = 3
- - There are three paths through our simple function, one - where a is 0, one where it is less than 0 - and one where it is greater than 0. - - As expected, KLEE informs us that it explored three paths in the - program and generated one test case for each path explored. The - output of a KLEE execution is a directory (in our - case klee-out-0) containing the test cases generated by - KLEE. KLEE names the output directory klee-out-N where N - is the lowest available number (so if we run KLEE again it will - create a directory called klee-out-1), and also generates a - symbolic link called klee-last to this directory for - convenience: - - 
-  $ ls klee-last/
-  assembly.ll      run.istats       test000002.ktest
-  info             run.stats        test000003.ktest
-  messages.txt     test000001.ktest warnings.txt
- - Please click here if you would like an - overview of the files generated by KLEE. In this tutorial, we only - focus on the actual test files generated by KLEE. - -

KLEE-generated test cases

The test cases generated by KLEE - are written in files with extension .ktest. These are - binary files, which can be read with the ktest-tool - utility. So let's examine each file: - - 
-  $ ktest-tool --write-ints klee-last/test000001.ktest 
-  ktest file : 'klee-last/test000001.ktest'
-  args       : ['get_sign.o']
-  num objects: 1
-  object    0: name: 'a'
-  object    0: size: 4
-  object    0: data: 1
-  
-  $ ktest-tool --write-ints klee-last/test000002.ktest  
-  ...
-  object    0: data: -2147483648
-
-  $ ktest-tool --write-ints klee-last/test000003.ktest 
-  ...
-  object    0: data: 0
- - In each test file, KLEE reports the arguments with which the program - was invoked (in our case no arguments other than the program name - itself), the number of symbolic objects on that path (only one in - our case), the name of our symbolic object ('a') and its size (4). - The actual test itself is represented by the value of our - input: 1 for the first test, -2147483648 for the - second and 0 for the last one. As expected, KLEE generated - value 0, one negative value (-2147483648), and one - positive value (1). We can now run these values on a - native version of our program, to exercise all paths through the - code! - - -

Replaying a test case

- - While we can run the test cases generated by KLEE on our program by - hand, (or with the help of an existing test infrastructure), KLEE - provides a convenient replay library, which simply replaces - the call to klee_make_symbolic with a call to a function - that assigns to our input the value stored in the .ktest - file. - - To use it, simply link your program with the libkleeRuntest - library and set the KTEST_FILE environment variable to - point to the name of the desired test case: - - 
-  $ export LD_LIBRARY_PATH=path-to-klee-root/Release+Asserts/lib/:$LD_LIBRARY_PATH
-  $ gcc -L path-to-klee-root/Release+Asserts/lib/ get_sign.c -lkleeRuntest
-  $ KTEST_FILE=klee-last/test000001.ktest ./a.out 
-  $ echo $?
-  1
-  $ KTEST_FILE=klee-last/test000002.ktest ./a.out 
-  $ echo $?
-  255
-  $ KTEST_FILE=klee-last/test000003.ktest ./a.out
-  $ echo $?
-  0
- - As expected, our program returns 1 when running the first test case, - 255 (-1 converted to a valid exit code value in the 0-255 range) - when running the second one, and 0 when running the last one. - -

- -
- - diff --git a/www/Tutorial-2.html b/www/Tutorial-2.html deleted file mode 100644 index 47187a45..00000000 --- a/www/Tutorial-2.html +++ /dev/null @@ -1,287 +0,0 @@ - - - - - KLEE - Tutorial Two - - - - - - - -
- -

Tutorial Two: Testing a Simple Regular Expression Library

- -

This is an example of using KLEE to test a simple regular expression matching -function. You can find the basic example in the source tree -under examples/regexp.

- -

Regexp.c contains a simple regular expression matching function, and -the bare bones testing harness (in main) needed to explore this code -with klee. You can see a version of the source -code here.

- -

This example will show to build and run the example using KLEE, as well as -how to interpret the output, and some additional KLEE features that can be used -when writing a test driver by hand.

- -

We'll start by showing how to build and run the example, and then explain how -the test harness works in more detail.

- -

Building the example

- -

The first step is to compile the source code using a compiler which can -generate object files in LLVM bitcode format. Here we use llvm-gcc, -but Clang works just as well!

- -

From within the examples/regexp directory: -

- $ llvm-gcc -I ../../include -emit-llvm -c -g Regexp.c -
-which should create a Regexp.o file in LLVM bitcode -format. The -I argument is used so that the compiler can -find "klee/klee.h", -which contains definitions for the intrinsic functions used to interact with the -KLEE virtual machine. -c is used because we only want to compile the -code to an object file (not a native executable), and finally -g causes -additional debug information to be stored in the object file, which KLEE will -use to determine source line number information.

- -

If you have the LLVM tools installed in your path, you can verify that this step -worked by running llvm-nm on the generated file:

-
-
-  $ llvm-nm Regexp.o
-         t matchstar
-         t matchhere
-         T match
-         T main
-         U klee_make_symbolic_name
-         d LC
-         d LC1
-
-
- -

Normally before running this program we would need to link it to create a -native executable. However, KLEE runs directly on LLVM bitcode files -- since -this program only has a single file there is no need to link. For "real" -programs with multiple inputs, -the llvm-link -and llvm-ld tools can -be used in place of the regular link step to merge multiple LLVM bitcode files -into a single module which can be executed by KLEE.

- -

Executing the code with KLEE

- - -

The next step is to execute the code with KLEE:

-
-
-$ klee --only-output-states-covering-new Regexp.o
-KLEE: output directory = "klee-out-1"
-KLEE: ERROR: .../klee/examples/regexp/Regexp.c:23: memory error: out of bound pointer
-KLEE: NOTE: now ignoring this error at this location
-KLEE: ERROR: .../klee/examples/regexp/Regexp.c:25: memory error: out of bound pointer
-KLEE: NOTE: now ignoring this error at this location
-KLEE: done: total instructions = 6334861
-KLEE: done: completed paths = 7692
-KLEE: done: generated tests = 22
-
-
- -

On startup, KLEE prints the directory used to store output (in this -case klee-out-1). By default klee will use the first -free klee-out-N directory and also create a klee-last -symlink which will point to the most recent created directory. You can specify a -directory to use for outputs using the -output-dir=path -command line argument.

- -

While KLEE is running, it will print status messages for "important" events, -for example when it finds an error in the program. In this case, KLEE detected -to invalid memory accesses on lines 23 and 25 of our test program. We'll look -more at this in a moment.

- -

Finally, when KLEE finishes execution it prints out a few statistics about -the run. Here we see that KLEE executed a total of ~6 million instructions, -explored 7,692 paths, and generated 22 test cases.

- -

Note that many realistic programs have an infinite (or extremely large) -number of paths through them, and it is common that KLEE will not terminate. By -default KLEE will run until the user presses Control-C (i.e. klee gets -a SIGINT), but there are additional options to limit KLEE's runtime and memory -usage:

-

    -
  • -max-time=seconds: Halt execution after the given number - of seconds.
    • -
  • -max-forks=N: Stop forking after N symbolic - branches, and run the remaining paths to termination.
    • -
  • -max-memory=N: Try to limit memory consumption - to N megabytes.
    • -
-

- -

KLEE error reports

- -

When KLEE detects an error in the program being executed it will generate a -test case which exhibits the error, and write some additional information about -the error into a file testN.TYPE.err, where N is -the test case number, and TYPE identifies the kind of error. Some -types of errors KLEE detects include:

- -
    -
  • ptr: Stores or loads of invalid memory locations.
    • - -
  • free: Double or invalid free().
    • - -
  • abort: The program called abort().
    • - -
  • assert: An assertion failed.
    • - -
  • div: A division or modulus by zero was detected.
    • - -
  • user: There is a problem with the input (invalid klee - intrinsic calls) or the way KLEE is being used.
    • - -
  • exec: There was a problem which prevented KLEE from executing the - program; for example an unknown instruction, a call to an invalid function - pointer, or inline assembly.
    • - -
  • model: KLEE was unable to keep full precision and is only exploring - parts of the program state. For example, symbolic sizes to malloc are - not currently supported, in such cases KLEE will concretize the argument.
    • -
- -

KLEE will print a message to the console when it detects an error, in the -test run above we can see that KLEE detected two memory errors. For all program -errors, KLEE will write a simple backtrace into the .err file. This is -what one of the errors above looks like:

-
-
-Error: memory error: out of bound pointer
-File: .../klee/examples/regexp/Regexp.c
-Line: 23
-Stack: 
-	#0 00000146 in matchhere (re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:23
-	#1 00000074 in matchstar (c, re=14816471, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#2 00000172 in matchhere (re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#3 00000074 in matchstar (c, re=14816469, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#4 00000172 in matchhere (re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#5 00000074 in matchstar (c, re=14816467, text=14815301) at .../klee/examples/regexp/Regexp.c:16
-	#6 00000172 in matchhere (re=14816465, text=14815301) at .../klee/examples/regexp/Regexp.c:26
-	#7 00000231 in matchhere (re=14816464, text=14815300) at .../klee/examples/regexp/Regexp.c:30
-	#8 00000280 in match (re=14816464, text=14815296) at .../klee/examples/regexp/Regexp.c:38
-	#9 00000327 in main () at .../klee/examples/regexp/Regexp.c:59
-Info: 
-	address: 14816471
-	next: object at 14816624 of size 4
-	prev: object at 14816464 of size 7
-
-
- -

Each line of the backtrace lists the frame number, the instruction line (this -is the line number in the assembly.ll file found along with the run -output), the function and arguments (including values for the concrete -parameters), and the source information.

- -

Particular error reports may also include additional information. For memory -errors, KLEE will show the invalid address, and what objects are on the heap -both before and after that address. In this case, we can see that the address -happens to be exactly one byte past the end of the previous object.

- -

Changing the test harness

- -

The reason KLEE is finding memory errors in this program isn't because the -regular expression functions have a bug, rather it indicates a problem in our -test driver. The problem is that we are making the input regular expression -buffer completely symbolic, but the match function expects it to be a -null terminated string. Let's look at two ways we can fix this.

- -

The simplest way to fix this problem is to store '\0' at the end of -the buffer, after making it symbolic. This makes our driver look like this:

-
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic(re, sizeof re, "re");
-  re[SIZE - 1] = '\0';
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-

Making a buffer symbolic just initializes the contents to refer to symbolic -variables, we are still free to modify the memory as we wish. If you recompile -and run klee on this test program, the memory errors should now be -gone.

- -

Another way to accomplish the same effect is to use the klee_assume -intrinsic function. klee_assume takes a single argument (an unsigned -integer) which generally should some kind of conditional expression, and -"assumes" that expression to be true on the current path (if that can never -happen, i.e. the expression is provably false, KLEE will report an error). - -

We can use klee_assume to cause KLEE to only explore states where -the string is null terminated by writing the driver like this:

-
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic(re, sizeof re, "re");
-  klee_assume(re[SIZE - 1] == '\0');
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-

In this particular example, both solutions work fine, but in -general klee_assume is more flexible:

-
    -
  • By explicitly declaring the constraint, this will force test cases to have - the '\0' in them. In the first example where we write the terminating - null explicitly, it doesn't matter what the last byte of the symbolic input is - and KLEE is free to generate any value. In some cases where you want to - inspect the test cases by hand, it is more convenient for the test case to - show all the values that matter.
    • - -
  • klee_assume can be used to encode more complicated - constraints. For example, we could use klee_assume(re[0] != '^') to - cause KLEE to only explore states where the first byte is - not '^'.
    • -
- -

NOTE: One important caveat when using klee_assume with -multiple conditions; remember that boolean conditionals like '&&' and '||' may -be compiled into code which branches before computing the result of the -expression. In such situations KLEE will branch the process *before* it reaches -the call to klee_assume, which may result in exploring unnecessary -additional states. For this reason it is good to use as simple expressions as -possible to klee_assume (for example splitting a single call into -multiple ones), and to use the '&' and '|' operators instead of the -short-circuiting ones.

- - - -
- - diff --git a/www/Tutorials.html b/www/Tutorials.html deleted file mode 100644 index e063a9a8..00000000 --- a/www/Tutorials.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - KLEE - Tutorials - - - - - -
- -

KLEE Tutorials

- - -
    -
  1. Tutorial One: Testing a small function.
    2. - -
  2. Tutorial Two: Testing a simple regular - expression library.
    3. - -
  3. - Solving a maze with KLEE: A nice explanation of how symbolic - execution can be used to generate interesting program - inputs. The example shows how to use KLEE to find all the - solutions to a maze game. -
    4. - -
  4. Testing Coreutils: In-depth - description of how to use KLEE to test GNU Coreutils.
    5. -
- - -
- - diff --git a/www/bugs.html b/www/bugs.html deleted file mode 100644 index 1ac9421a..00000000 --- a/www/bugs.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Bug Reports

- - - Please report any bugs in KLEE to - the klee-dev mailing list. You need to - be subscribe to the list in order to send your report. - -
- - diff --git a/www/content.css b/www/content.css deleted file mode 100644 index 50835ec3..00000000 --- a/www/content.css +++ /dev/null @@ -1,75 +0,0 @@ -html, body { - padding:0px; - font-size:small; - font-family:"Lucida Grande", "Lucida Sans Unicode", Arial, Verdana, Helvetica, sans-serif; - background-color: #fff; color: #222; - line-height:1.5; -} - -h1, h2, h3, tt { color: #000 } - -h1 { color:#000000; padding-top: 0px; margin-top:0px;} -h2 { color:#333333; padding-top: 0.5em; } -h3 { color:#2d58b7; padding-top: 0.5em; margin-bottom: -0.25em; } -h4 { color:#2d58b7; } -li { padding-bottom: 0.5em; } -ul { padding-left:1.5em; } - -/* Slides */ -IMG.img_slide { - display: block; - margin-left: auto; - margin-right: auto -} - -.itemTitle { color:#2d58b7 } - -/* Tables */ -tr { vertical-align:top } - -/* Syntax */ -div.syntax { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: SeaShell; - padding: 7px; - margin: 7px; -} - -/* Examples */ -div.example { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Instructions */ -div.instr { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Output */ -pre.output { - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - padding: 7px; - margin: 7px; -} - -/* Code */ -pre.code{ - display:table; - border: 1px solid LightSteelBlue ; - font-family: Courier New; - background-color: #E3E3E3; - margin: 10px; - padding: 10px; -} - diff --git a/www/content/coreutils_kc_0.png b/www/content/coreutils_kc_0.png deleted file mode 100644 index 3f72dc49..00000000 Binary files a/www/content/coreutils_kc_0.png and /dev/null differ diff --git a/www/content/coreutils_kc_1.png b/www/content/coreutils_kc_1.png deleted file mode 100644 index d4372f26..00000000 Binary files a/www/content/coreutils_kc_1.png and /dev/null differ diff --git a/www/developers-guide.html b/www/developers-guide.html deleted file mode 100644 index 9c0ff719..00000000 --- a/www/developers-guide.html +++ /dev/null @@ -1,114 +0,0 @@ - - - - - KLEE - Getting Started - - - - - - - -
- -

KLEE Developer's Guide

- -

This guide covers several areas of KLEE that may not be imediately obvious to new developers.

- -

- 1. KLEE's Build System
- 2. KLEE's Test Framework
- 3. Miscellaneous
-

- -

KLEE's Build System

-

KLEE uses LLVM's ability to build third-party projects, which is described here. The build system uses GNU Autoconf and AutoHeader to configure the build, but does not use the rest of GNU Autotools (e.g. automake).

- -

LLVM's build system supports out-of-source builds and therefore so does KLEE. It is highly recommended you take advantage of this. For example, you could create three builds (Release, Release with debug symbols, Debug) - that all use the same source tree. This allows you keep your source tree clean and allows multiple configurations to be tested from a single source tree.

- -

Setting up a debug build of KLEE

-

Setting up a debug build of KLEE (we'll assume it is an out-of-source build) is very similar to the build process described in Getting Started, with the exception of steps 6 and 7.

- -
    -
  1. Now we will configure KLEE. Notice that we are forcing the compiler to produce unoptimised code, this isn't the default behaviour. -
    - $ mkdir path/to/build-dir
    - $ cd path/to/build-dir
    - $ CXXFLAGS="-g -O0" CFLAGS="-g -O0" path/to/source-dir/configure --with-llvm=path/to/llvm --with-stp=path/to/stp/install --with-uclibc=path/to/klee-uclibc --enable-posix-runtime --with-runtime=Debug+Asserts -
    - Note if you're using an out-of-source build of LLVM you will need to use --with-llvmsrc= and --with-llvmobj= configure options instead of --with-llvm= -
    2. -
  2. Now we can build KLEE. -
    - $ make -j -
    - Note that we are using the -j option of make to speed up the compilation process. -
    3. -
- -

Note that KLEE depends on LLVM and STP. If you need to debug KLEE's calls to that code, then you will need to build LLVM/STP with debug support too.

- -

Adding a class

-

Because KLEE uses LLVM's build system, adding a class to an existing library in KLEE is very simple. For example, to add a class to libkleaverExpr, the following steps would be followed: -

    -
  1. Create the header file (.h) for the class and place it somewhere inside include/ (the location isn't really important except that #include is relative to the include/ directory). -
    2. -
  2. Create the source file (.cpp) for the class place it in lib/Expr/. You can confirm that the library in which your new class will be included is kleaverExpr by looking at the Makefile in lib/Expr. -
    3. -
- That's it! Now LLVM's build system will detect the new .cpp file and add it to the library that is generated when you run make. -

- -

Building code documentation

-

KLEE uses Doxygen to generate code documentation. To generate it yourself you can run the following from KLEE's build directory root. -

- $ make doxygen -
- This will generate documentation in path/to/build-dir/docs/doxygen/ folder. You can also find KLEE's latest official code documentation here -

- - -

KLEE's Test Framework

-

KLEE uses LLVM's testing infrastructure for its tests, which itself uses DejaGnu. These are the tests that are executed by the make check command. Some documentation on LLVM's testing infrastructure can be found here. -

-

KLEE's tests are currently divided into categories, each of which is a subdirectory in test/ in the source tree (e.g. test/Feature) . The dg.exp file in each subdirectory instructs the LLVM testing infrastructure which files in the subdirectory are to be used as tests. For example, test/Expr/dg.exp contains: -

- load_lib llvm.exp

- - RunLLVMTests [lsort [glob -nocomplain $srcdir/$subdir/*.{pc}]] -
- This instructs the testing infrastructure that every .pc file in test/Expr should be used as a test. -

-

The actions performed in each test are specified by special comments in the file. For example, in test/Feature/ByteSwap.c the first two lines are -

- // RUN: %llvmgcc %s -emit-llvm -O0 -c -o %t1.bc
- // RUN: %klee --libc=klee --exit-on-error %t1.bc
-
- This first runs llvm-gcc on the source file (%s) and generates a temporary file (%t1.bc). Then KLEE is executed on this generated temporary file. If either program returns a non-zero exit code (or crashes) then - test is considered to have failed. More information on the available substitution variables (such as %s) can be found here. -

- -

It is useful to be able to execute just a single test rather than all of them. KLEE provides a makefile target for doing so which can used as shown below. Note that category/test-name should be the test that one would like to execute, e.g. Feature/ByteSwap.c. -

- $ cd path/to/build-dir/test
- $ make check-one TESTONE=path/to/source-dir/test/category/test-name -
-

- - -

Miscellaneous

-

Writing messages to standard error

-

The kleeCore library (lib/Core) provides several functions that can be used similarly to printf() in C. See lib/Core/Common.h for more information. -

- -

Adding a command line option to a tool

-

KLEE uses LLVM's CommandLine library for adding options to tools in KLEE, which is well documented here. See lib/core/Executor.cpp for examples.

- -
- -
- - diff --git a/www/index.html b/www/index.html deleted file mode 100644 index b76a42bc..00000000 --- a/www/index.html +++ /dev/null @@ -1,36 +0,0 @@ - - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

The KLEE Symbolic Virtual Machine

- - -

KLEE is a symbolic virtual machine built on top of - the LLVM compiler infrastructure, and available - under the UIUC open source license.

- -

For more information on what KLEE is and what it can do, see - the OSDI - 2008 paper.

- -

If you are interested in trying it yourself, please - see Getting Started.

- - - -
- - diff --git a/www/klee-dev.html b/www/klee-dev.html deleted file mode 100644 index 5434ce57..00000000 --- a/www/klee-dev.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - klee-dev mailing list - - - - - -
- -

klee-dev mailing list

- - -

If you have questions about KLEE that are not answered on this - website, please send a message to - the klee-dev - mailing list.

- - -

However, before doing so, please - check klee-dev's - searchable archive to see if your question has already been - answered.

- -
- - diff --git a/www/klee-files.html b/www/klee-files.html deleted file mode 100644 index 299f593b..00000000 --- a/www/klee-files.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

Files generated by KLEE

- - -

Standard Global Files

- - These are global files are always generated on a KLEE execution: -
    -
  1. info: This is a text file containing various information - related to a KLEE run. In particular, it records the exact - command-line with which KLEE was run, and the total time taken by - the execution. E.g.: - 
    -    $ cat info 
-    klee --write-pcs demo.o
-    PID: 12460
-    Started: 2009-05-20 22:31:41
-    BEGIN searcher description
-    DFSSearcher
-    END searcher description
-    Finished: 2009-05-20 22:31:41
-    Elapsed: 00:00:00
-    KLEE: done: explored paths = 3
-    KLEE: done: avg. constructs per query = 6
-    KLEE: done: total queries = 3
-    KLEE: done: valid queries = 0
-    KLEE: done: invalid queriers = 3
-    KLEE: done: query cex = 3
-    KLEE: done: total instructions = 67
-    KLEE: done: completed paths = 3
-    KLEE: done: generated tests = 3
    -
    2. - -
  2. warnings.txt: This is a text file containing all warnings emitted by KLEE. -
    3. - -
  3. messages.txt: This is a text file containing all other messages emitted by KLEE. -
    4. - -
  4. assembly.ll: This file contains a human readable version - of the LLVM bitcode executed by KLEE - -
  5. run.stats: This is a text file containing various - statistics emitted by KLEE. While this file can be inspected - manually, you should use the klee-stats - tool for that.
    6. - -
  6. run.istats: This is a binary file containing global - statistics emitted by KLEE for each line of code in the program. -
    7. - -
- - -

Other Global Files

- -
    -
  1. all-queries.pc: This file contains all the queries KLEE - made during execution in the KQuery - format. Note these are the queries before any optimisation - (e.g. caching, constraint independence) so it is possible that - some of the queries logged are never executed by KLEE's underlying - solver or are modified before being executed by KLEE's underlying - solver. The generation of this file can be enabled by specifying - the option --use-query-log=all:pc to KLEE.
    2. -
  2. all-queries.smt2: This file contains all the queries KLEE made during execution in the SMT-LIBv2 - .It contains the same information as all-queries.pc. - The generation of this file can be enabled by specifying the option --use-query-log=all:smt2 to KLEE.
    3. -
  3. solver-queries.pc: This file contains all the queries passed to KLEE's underlying solver during execution in the - KQuery format. Note these are the - queries after all optimisations (e.g. caching, constraint - independence) are performed. The generation of this file can be - enabled by specifying the - option --use-query-log=solver:pc to KLEE.
    4. -
  4. solver-queries.smt2: This file contains all the queries passed to KLEE's underlying solver during execution in the - SMT-LIBv2 - format. It contains the same information as solver-queries.pc. - The generation of this file can be enabled by specifying the option --use-query-log=solver:smt2 to KLEE.
    5. -
- - -

Per-path files

- -
    -
  1. - test<N>.ktest: Contains the test case generated by - KLEE on that path. Use ktest-tool - to read the contents. The generation of .ktest files - can be disabled using the --no-output option. -
    2. - -
  2. - test<N>.<error-type>.err: Generated for paths - where KLEE found an error. Contains information about the error - in textual form. -
    3. - -
  3. test<N>.pc: Contains the constraints associated with the given - path, in KQuery format. The generation - of these files can be enabled via the --write-cvcs flag. -
    4. - -
  4. - test<N>.cvc: Contains the constraints associated - with the given path, - in CVC - format. The generation of these files can be enabled via - the --write-pcs flag. (This is the same information as - in the corresponding .pc file.) -
    5. -
  5. - test<N>.smt2: Contains the constraints associated - with the given path, - in SMT-LIBv2 - format. The generation of these files can be enabled via - the --write-smt2s flag. (This is the same information as - in the corresponding .pc file.) -
    6. -
- - -
- - diff --git a/www/klee-options.html b/www/klee-options.html deleted file mode 100644 index be997ec4..00000000 --- a/www/klee-options.html +++ /dev/null @@ -1,99 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Options

- - -

- 1. Search Heuristics
- 2. Query Logging
-

- - - -

Main search heuristics

- -

- KLEE provides four main search heuristics: -

    -
  1. Depth-First Search (DFS): Traverses states in depth-first order.
    2. -
  2. Random State Search:Randomly selects a state to explore.
    3. -
  3. Random Path Selection: Described in our KLEE OSDI'08 paper.
    4. -
  4. Non Uniform Random Search (NURS): Selects a state randomly according to a given distribution. The distribution can be based on the minimum distance to an uncovered instruction (MD2U), the query cost, etc. -
- - To select a search heuristic, use the --search option provided by KLEE. For example: - 
-    $ klee --search=dfs demo.o
- - runs demo.o using DFS, while - 
-    $ klee --search=random-path demo.o
- runs it using the random path selection strategy. - - The full list of options is shown in KLEE's help message: - 
-    $ klee --help
-    -search                                 - Specify the search heuristic (default=random-path interleaved with nurs:covnew)
-      =dfs                                  -   use Depth First Search (DFS)
-      =random-state                         -   randomly select a state to explore
-      =random-path                          -   use Random Path Selection (see OSDI'08 paper)
-      =nurs:covnew                          -   use Non Uniform Random Search (NURS) with Coverage-New heuristic
-      =nurs:md2u                            -   use NURS with Min-Dist-to-Uncovered heuristic
-      =nurs:depth                           -   use NURS with 2^depth heuristic
-      =nurs:icnt                            -   use NURS with Instr-Count heuristic
-      =nurs:cpicnt                          -   use NURS with CallPath-Instr-Count heuristic
-      =nurs:qc                              -   use NURS with Query-Cost heuristic
- - -

Interleaving search heuristics

-

- Search heuristics in KLEE can be interleaved in a round-robin - fashion. To interleave several search heuristics to be interleaved, use the --search multiple times. For example: - 

-    $ klee --search=random-state --search=nurs:md2u demo.o
- interleaves the Random State and the NURS:MD2U heuristics in a round robin fashion. -
-

- - -

Default search heuristics

-

- The default heuristics used by KLEE are random-path interleaved with nurs:covnew. -

- -

Query Logging

- - To log the queries issued by KLEE during symbolic execution, you can use the following options: -
    -
  1. - --use-query-log=TYPE:FORMAT, where: -
      -
    • TYPE is either all to log all the queries KLEE made during execution before any optimisation (e.g. caching, constraint independence) is performed, or solver to log only the queries passed to KLEE's underlying solver. Note that it is possible that some of the unoptimized queries are never executed or are modified before being executed by KLEE's underlying solver.
      • -
    • FORMAT is the format in which queries are logged and can be either pc for the KQuery format, or smt2 for the SMT-LIBv2 format. -
    -
  2. - --min-query-time-to-log=TIME (in ms) is used to log only queries that exceed a certain time limit. TIME can be: -
      -
    • 0 (default): to log all queries
      • -
    • <0: a negative value specifies that only queries that timed out should be logged. The timeout value is specified via the --max-stp-time option.
      • -
    • >0: only queries that took more that TIME milliseconds should be logged. -
    -
    3. - -
- -
- - diff --git a/www/klee-tools.html b/www/klee-tools.html deleted file mode 100644 index 80ae5d35..00000000 --- a/www/klee-tools.html +++ /dev/null @@ -1,84 +0,0 @@ - - - - - - The KLEE Symbolic Virtual Machine - - - - - -
- -

KLEE Tools

- - -

- 1. ktest-tool
- 2. klee-stats
-

- -

ktest-tool

- -

klee-stats

- klee-stats is a Python script used to extract and present in a - tabular form runtime statistics for a KLEE execution. The runtime statistics include: -
    -
  • The number of executed instructions
    • -
  • Instruction coverage in the LLVM bitcode (%)
    • -
  • Branch coverage in the LLVM bitcode (%)
    • -
  • Total static instructions in the LLVM bitcode
    • -
  • The number of currently active states
    • -
  • Megabytes of memory currently used
    • -
  • The number of queries issued to STP
    • -
  • The average number of query constructs per query
    • -
  • Various time statistics: -
      -
    • Total user time
      • -
    • Total wall time
      • -
    • Time spent in the constraint solver
      • -
    • Time spent in the counterexample caching code
      • -
    • Time spent forking
      • -
    • Time spent in object resolution
      • -
    • -
- - - klee-stats extracts statistics information from the run.stats file - present in the klee-out-* directory created during a KLEE execution. - The exact usage of klee-stats is as follows: - 
klee-stats [options] directories
- The directories parameter is a list of klee-out-* directories - created by KLEE. A common scenario is to simply run klee-stats on klee-last. - -

- In order to limit printed information only to the values of measured times, - the following options can be used: - -

    -
  • --print-rel-times—display time values relative - to measured execution time
    • - -
  • --print-abs-times—display absolute time values
    • -
- - The --precision option can be used to configure the number of fractional - digits displayed in floating point values. By default, 2 fractional digits - are displayed, but in some cases that might be not sufficient—if the value - is very small, e.g. 0.0001, with 2-digits precision it will be printed as 0.00. -

- -

Various other options can be used to specify what values are - displayed and how they are displayed. Options for comparison of - statistics are also provided. More information about available - options can be obtained using the command: - 

klee-stats --help
-

- -
- -
- - diff --git a/www/menu.css b/www/menu.css deleted file mode 100644 index 6e96a457..00000000 --- a/www/menu.css +++ /dev/null @@ -1,39 +0,0 @@ -/***************/ -/* page layout */ -/***************/ - -[id=menu] { - position:fixed; - width:25ex; -} -[id=content] { - /* ***** EDIT THIS VALUE IF CONTENT OVERLAPS MENU ***** */ - position:absolute; - left:29ex; - padding-right:4ex; -} - -/**************/ -/* menu style */ -/**************/ - -#menu .submenu { - padding-top:1em; - display:block; -} - -#menu label { - display:block; - font-weight: bold; - text-align: center; - background-color: rgb(192,192,192); -} -#menu a { - padding:0 .2em; - display:block; - text-align: center; - background-color: rgb(235,235,235); -} -#menu a:visited { - color:rgb(100,50,100); -} \ No newline at end of file diff --git a/www/menu.html.incl b/www/menu.html.incl deleted file mode 100644 index 7f2e4e33..00000000 --- a/www/menu.html.incl +++ /dev/null @@ -1,31 +0,0 @@ - diff --git a/www/resources/Regexp.c.html b/www/resources/Regexp.c.html deleted file mode 100644 index cb3e3d75..00000000 --- a/www/resources/Regexp.c.html +++ /dev/null @@ -1,78 +0,0 @@ - - - -Enscript Output - - - - -

Regexp.c

- -
-/* 
- * Simple regular expression matching.
- *
- * From:
- *   The Practice of Programming
- *   Brian W. Kernighan, Rob Pike
- *
- */ 
-
-#include <klee/klee.h>
-
-static int matchhere(char*,char*);
-
-static int matchstar(int c, char *re, char *text) {
-  do {
-    if (matchhere(re, text))
-      return 1;
-  } while (*text != '\0' && (*text++ == c || c== '.'));
-  return 0;
-}
-
-static int matchhere(char *re, char *text) {
-  if (re[0] == '\0')
-     return 0;
-  if (re[1] == '*')
-    return matchstar(re[0], re+2, text);
-  if (re[0] == '$' && re[1]=='\0')
-    return *text == '\0';
-  if (*text!='\0' && (re[0]=='.' || re[0]==*text))
-    return matchhere(re+1, text+1);
-  return 0;
-}
-
-int match(char *re, char *text) {
-  if (re[0] == '^')
-    return matchhere(re+1, text);
-  do {
-    if (matchhere(re, text))
-      return 1;
-  } while (*text++ != '\0');
-  return 0;
-}
-
-/*
- * Harness for testing with KLEE.
- */
-
-// The size of the buffer to test with.
-#define SIZE 7
-
-int main() {
-  // The input regular expression.
-  char re[SIZE];
-  
-  // Make the input symbolic. 
-  klee_make_symbolic_name(re, sizeof re, "re");
-
-  // Try to match against a constant string "hello".
-  match(re, "hello");
-
-  return 0;
-}
-
-
-
Generated by GNU enscript 1.6.4.
- - diff --git a/www/resources/get_sign.c.html b/www/resources/get_sign.c.html deleted file mode 100644 index 58c28d01..00000000 --- a/www/resources/get_sign.c.html +++ /dev/null @@ -1,37 +0,0 @@ - - - -Enscript Output - - - - -

get_sign.c

- -
-/*
- * First KLEE tutorial: testing a small function
- */
-
-
-int get_sign(int x) {
-  if (x == 0)
-     return 0;
-  
-  if (x < 0)
-     return -1;
-  else 
-     return 1;
-} 
-
-int main() {
-  int a;
-  klee_make_symbolic(&a, sizeof(a), "a");
-  return get_sign(a);
-} 
-
-
-
Generated by GNU Enscript 1.6.5.2.
-enscript -Ec --color -w html get_sign.c -o get_sign.c.html - - diff --git a/www/resources/islower.c.html b/www/resources/islower.c.html deleted file mode 100644 index 524f2093..00000000 --- a/www/resources/islower.c.html +++ /dev/null @@ -1,33 +0,0 @@ - - - -Enscript Output - - - - -

islower.c

- -
-/*
- * First KLEE tutorial: testing a small function
- */
-
-#include <klee/klee.h>
-
-int my_islower(int x) {
-  if (x >= 'a' && x <= 'z')
-    return 1;
-  else return 0;
-}
-
-int main() {
-  char c;
-  klee_make_symbolic(&c, sizeof(c), "input");
-  return my_islower(c);
-}
-
-
-
Generated by GNU enscript 1.6.4.
- - -- cgit 1.4.1