CVC4 - User contributions [en]

~/.m2/settings.xml

2012-12-20T04:06:32Z

Wwang:

<settings>
<profiles>
<profile>
<id>tools-builds-cvc4</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<cvc4.version>4.0.0</cvc4.version>
<cvc4.basedir>/Users/Wei/Workspace/target/cvc4/</cvc4.basedir>
<cvc4.libdir>/Users/Wei/Workspace/target/cvc4/lib/</cvc4.libdir>
<cvc4.jni.libdir>/Users/Wei/Workspace/target/cvc4/lib/jni</cvc4.jni.libdir>
<cvc4.jar>/Users/Wei/Workspace/target/cvc4/share/java/CVC4.jar</cvc4.jar>
</properties>
</profile>
</profiles>
</settings>

~/.m2/settings.xml

2012-12-20T04:06:17Z

Wwang:

{{{
<settings>
<profiles>
<profile>
<id>tools-builds-cvc4</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<cvc4.version>4.0.0</cvc4.version>
<cvc4.basedir>/Users/Wei/Workspace/target/cvc4/</cvc4.basedir>
<cvc4.libdir>/Users/Wei/Workspace/target/cvc4/lib/</cvc4.libdir>
<cvc4.jni.libdir>/Users/Wei/Workspace/target/cvc4/lib/jni</cvc4.jni.libdir>
<cvc4.jar>/Users/Wei/Workspace/target/cvc4/share/java/CVC4.jar</cvc4.jar>
</properties>
</profile>
</profiles>
</settings>
}}}

Cascade User Manual

2012-12-20T01:17:30Z

Wwang: /* Command line */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/branches/wwang1109/cvc4_branch svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and here we only introduces those often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used to assume the function parameter list with root as start node is created with length 2 and field ''next''.
__create_acyclic_list(next, root, 2)

Cascade User Manual

2012-12-19T20:49:57Z

Wwang: /* Build and Install Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/branches/wwang1109/cvc4_branch svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and here we only introduces those often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used to assume the function parameter list with root as start node is created with length 2 and field ''next''.
__create_acyclic_list(next, root, 2)

About Cascade

2012-12-19T19:52:50Z

Wwang: /* People */

Cascade is a tool to check assertions in C programs as part of multi-stage verification strategy. There are a number of static analysis tools which can analyse large programs and find potential bugs. To scale, these tools must abstract the programs with the result that some of the errors reported are often false. Having to check these false alarms is often a time consuming task.

In two stage verification, a light-weight analysis capable of scaling to large codes is first run to detect potential bugs. Then a more detailed analysis is used to rule out false errors. Cascade provides a generic back-end for two stage verification of C programs which can be easily integrated with any initial stage. Cascade can handle most C constructs like loops, functions (including recursive functions), structs, pointers, and dynamic memory allocation.

Cascade uses a control file to interface with the first stage tool. The control file specifies the assertion(s) to be checked. In addition, the control file can be used to constrain the search for a violating trace by restricting the program paths to be explored or giving constraints on program variables.

== People ==
* [http://www.cs.nyu.edu/~barrett/ Clark Barrett]
* [http://www.cs.nyu.edu/~cconway/ Chris Conway]
* [http://www.cs.nyu.edu/~dejan/ Dejan Jovanović]
* [http://www.cs.wustl.edu/~mdeters/ Morgan Deters]
* [http://www.cs.nyu.edu/pnueli Amir Pnueli]
* [http://www.cs.nyu.edu/~nsethi Nikhil Sethi]
* [http://www.cs.nyu.edu/~wwang1109/ Wei Wang]

== Publications ==
* Christopher L. Conway and Clark Barrett. [http://www.cs.nyu.edu/~cconway/papers/conway-2010-datatypes.pdf Verifying Low-Level Implementations of High-Level Datatypes]. In Tayssir Touili, Byron Cook, and Paul Jackson, editors, Proceedings of the Twenty-Second International Conference on Computer Aided Verification (CAV '10), volume 6174 of Lecture Notes in Computer Science, pages 306-320. Springer, July 2010. Edinburgh, Scotland.

* Nikhil Sethi and Clark Barrett. [http://cs.nyu.edu/~barrett/pubs/SB06.ps CASCADE: C Assertion Checker and Deductive Engine.] In Thomas Ball and Robert B. Jones, editors, Proceedings of the 18th International Conference on Computer Aided Verification (CAV '06), volume 4144 of Lecture Notes in Computer Science, pages 166-169. Springer-Verlag, August 2006. Seattle, Washington.

== Support ==
Cascade development is supported by the National Science Foundation, grant number 0644299.

About Cascade

2012-12-19T19:51:11Z

Wwang: /* Publications */

Cascade is a tool to check assertions in C programs as part of multi-stage verification strategy. There are a number of static analysis tools which can analyse large programs and find potential bugs. To scale, these tools must abstract the programs with the result that some of the errors reported are often false. Having to check these false alarms is often a time consuming task.

In two stage verification, a light-weight analysis capable of scaling to large codes is first run to detect potential bugs. Then a more detailed analysis is used to rule out false errors. Cascade provides a generic back-end for two stage verification of C programs which can be easily integrated with any initial stage. Cascade can handle most C constructs like loops, functions (including recursive functions), structs, pointers, and dynamic memory allocation.

Cascade uses a control file to interface with the first stage tool. The control file specifies the assertion(s) to be checked. In addition, the control file can be used to constrain the search for a violating trace by restricting the program paths to be explored or giving constraints on program variables.

== People ==
* [http://www.cs.nyu.edu/~barrett/ Clark Barrett]
* [http://www.cs.nyu.edu/~cconway/ Chris Conway]
* [http://www.cs.nyu.edu/~dejan/ Dejan Jovanović]
* [http://www.cs.nyu.edu/~wwang1109/ Wei Wang]

== Publications ==
* Christopher L. Conway and Clark Barrett. [http://www.cs.nyu.edu/~cconway/papers/conway-2010-datatypes.pdf Verifying Low-Level Implementations of High-Level Datatypes]. In Tayssir Touili, Byron Cook, and Paul Jackson, editors, Proceedings of the Twenty-Second International Conference on Computer Aided Verification (CAV '10), volume 6174 of Lecture Notes in Computer Science, pages 306-320. Springer, July 2010. Edinburgh, Scotland.

* Nikhil Sethi and Clark Barrett. [http://cs.nyu.edu/~barrett/pubs/SB06.ps CASCADE: C Assertion Checker and Deductive Engine.] In Thomas Ball and Robert B. Jones, editors, Proceedings of the 18th International Conference on Computer Aided Verification (CAV '06), volume 4144 of Lecture Notes in Computer Science, pages 166-169. Springer-Verlag, August 2006. Seattle, Washington.

== Support ==
Cascade development is supported by the National Science Foundation, grant number 0644299.

About Cascade

2012-12-19T19:50:46Z

Wwang: /* Publications */

Cascade is a tool to check assertions in C programs as part of multi-stage verification strategy. There are a number of static analysis tools which can analyse large programs and find potential bugs. To scale, these tools must abstract the programs with the result that some of the errors reported are often false. Having to check these false alarms is often a time consuming task.

In two stage verification, a light-weight analysis capable of scaling to large codes is first run to detect potential bugs. Then a more detailed analysis is used to rule out false errors. Cascade provides a generic back-end for two stage verification of C programs which can be easily integrated with any initial stage. Cascade can handle most C constructs like loops, functions (including recursive functions), structs, pointers, and dynamic memory allocation.

Cascade uses a control file to interface with the first stage tool. The control file specifies the assertion(s) to be checked. In addition, the control file can be used to constrain the search for a violating trace by restricting the program paths to be explored or giving constraints on program variables.

== People ==
* [http://www.cs.nyu.edu/~barrett/ Clark Barrett]
* [http://www.cs.nyu.edu/~cconway/ Chris Conway]
* [http://www.cs.nyu.edu/~dejan/ Dejan Jovanović]
* [http://www.cs.nyu.edu/~wwang1109/ Wei Wang]

== Publications ==
* Christopher L. Conway and Clark Barrett. [https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CDcQFjAA&url=http%3A%2F%2Fwww.cs.nyu.edu%2F~cconway%2Fpapers%2Fconway-2010-datatypes.pdf&ei=ihrSULiSJa-70QHKo4GgCw&usg=AFQjCNGMR4KKLfP4NPx0liddH4ChtZXkbQ&sig2=D37AJMBY2rPGU-LrcDcrug&bvm=bv.1355534169,d.dmQ Verifying Low-Level Implementations of High-Level Datatypes]. In Tayssir Touili, Byron Cook, and Paul Jackson, editors, Proceedings of the Twenty-Second International Conference on Computer Aided Verification (CAV '10), volume 6174 of Lecture Notes in Computer Science, pages 306-320. Springer, July 2010. Edinburgh, Scotland.

* Nikhil Sethi and Clark Barrett. [http://cs.nyu.edu/~barrett/pubs/SB06.ps CASCADE: C Assertion Checker and Deductive Engine.] In Thomas Ball and Robert B. Jones, editors, Proceedings of the 18th International Conference on Computer Aided Verification (CAV '06), volume 4144 of Lecture Notes in Computer Science, pages 166-169. Springer-Verlag, August 2006. Seattle, Washington.

== Support ==
Cascade development is supported by the National Science Foundation, grant number 0644299.

About Cascade

2012-12-19T19:49:32Z

Wwang: /* Publications */

Cascade is a tool to check assertions in C programs as part of multi-stage verification strategy. There are a number of static analysis tools which can analyse large programs and find potential bugs. To scale, these tools must abstract the programs with the result that some of the errors reported are often false. Having to check these false alarms is often a time consuming task.

In two stage verification, a light-weight analysis capable of scaling to large codes is first run to detect potential bugs. Then a more detailed analysis is used to rule out false errors. Cascade provides a generic back-end for two stage verification of C programs which can be easily integrated with any initial stage. Cascade can handle most C constructs like loops, functions (including recursive functions), structs, pointers, and dynamic memory allocation.

Cascade uses a control file to interface with the first stage tool. The control file specifies the assertion(s) to be checked. In addition, the control file can be used to constrain the search for a violating trace by restricting the program paths to be explored or giving constraints on program variables.

== People ==
* [http://www.cs.nyu.edu/~barrett/ Clark Barrett]
* [http://www.cs.nyu.edu/~cconway/ Chris Conway]
* [http://www.cs.nyu.edu/~dejan/ Dejan Jovanović]
* [http://www.cs.nyu.edu/~wwang1109/ Wei Wang]

== Publications ==
Nikhil Sethi and Clark Barrett. [http://cs.nyu.edu/~barrett/pubs/SB06.ps CASCADE: C Assertion Checker and Deductive Engine.] In Thomas Ball and Robert B. Jones, editors, Proceedings of the 18th International Conference on Computer Aided Verification (CAV '06), volume 4144 of Lecture Notes in Computer Science, pages 166-169. Springer-Verlag, August 2006. Seattle, Washington.

== Support ==
Cascade development is supported by the National Science Foundation, grant number 0644299.

About Cascade

2012-12-19T19:48:39Z

Wwang: /* Support */

Cascade is a tool to check assertions in C programs as part of multi-stage verification strategy. There are a number of static analysis tools which can analyse large programs and find potential bugs. To scale, these tools must abstract the programs with the result that some of the errors reported are often false. Having to check these false alarms is often a time consuming task.

In two stage verification, a light-weight analysis capable of scaling to large codes is first run to detect potential bugs. Then a more detailed analysis is used to rule out false errors. Cascade provides a generic back-end for two stage verification of C programs which can be easily integrated with any initial stage. Cascade can handle most C constructs like loops, functions (including recursive functions), structs, pointers, and dynamic memory allocation.

Cascade uses a control file to interface with the first stage tool. The control file specifies the assertion(s) to be checked. In addition, the control file can be used to constrain the search for a violating trace by restricting the program paths to be explored or giving constraints on program variables.

== People ==
* [http://www.cs.nyu.edu/~barrett/ Clark Barrett]
* [http://www.cs.nyu.edu/~cconway/ Chris Conway]
* [http://www.cs.nyu.edu/~dejan/ Dejan Jovanović]
* [http://www.cs.nyu.edu/~wwang1109/ Wei Wang]

== Publications ==
Nikhil Sethi and Clark Barrett. CASCADE: C Assertion Checker and Deductive Engine. In Thomas Ball and Robert B. Jones, editors, Proceedings of the 18th International Conference on Computer Aided Verification (CAV '06), volume 4144 of Lecture Notes in Computer Science, pages 166-169. Springer-Verlag, August 2006. Seattle, Washington.

== Support ==
Cascade development is supported by the National Science Foundation, grant number 0644299.

About Cascade

2012-12-19T19:46:44Z

Wwang: /* People */

Cascade User Manual

2012-12-18T03:28:15Z

Wwang: /* Options */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and here we only introduces those often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used to assume the function parameter list with root as start node is created with length 2 and field ''next''.
__create_acyclic_list(next, root, 2)

Cascade User Manual

2012-12-18T03:26:55Z

Wwang: /* Reachability */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used to assume the function parameter list with root as start node is created with length 2 and field ''next''.
__create_acyclic_list(next, root, 2)

Cascade User Manual

2012-12-17T23:36:31Z

Wwang: /* Reachability */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used to assume a list linked by field ''next'', with length 2 and starts with node root.
__allocated_list(next, root, 2)

Cascade User Manual

2012-12-17T23:35:19Z

Wwang: /* Reachability */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Another sample control file [[list_contains.ctrl]] is for the function contains(). Note that, the predicate '''_create_acyclic_list(f, root, length)''' is used here.
__allocated_list(next, root, 2)
It means a list with length 2 and starts with root has been created.

Cascade User Manual

2012-12-17T22:51:21Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It is used to assume that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:50:45Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly linked acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It means that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly linked cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:50:02Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It means that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly cyclic list creation predicate: '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:49:47Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* Singly acyclic list creation predicate: '''_create_acyclic_list(f, root, length)'''. It means that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters.
_create_acyclic_list(f, l1, 3)
* Singly cyclic list creation predicate '''_create_cyclic_list(f, root, length)'''.
_create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:43:51Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* List allocation predicate: '''_create_acyclic_list(f, root, length)'''. It means that a singly acyclic list with particular length and root has been created. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters. For cyclic list creation, we have '''_create_cyclic_list(f, root, length)'''.
_create_acyclic_list(f, l1, 3) && _create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:43:28Z

Wwang: /* Logic Operators and Predicates */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))
* List allocation predicate: '''_create_acyclic_list(f, root, length)'''. It means that a singly acyclic list with particular length and root has been allocated. This predicate is very helpful for modular verification of linked data structure manipulation functions, which takes linked lists as parameters. For cyclic list creation, we have '''_create_cyclic_list(f, root, length)'''.
_create_acyclic_list(f, l1, 3) && _create_cyclic_list(f, l2, 4)

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T22:34:36Z

Wwang: /* Cascade Command */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

== Logic Operators and Predicates ==

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

About Cascade

2012-12-17T05:42:18Z

Wwang: /* People */

About Cascade

2012-12-17T05:41:41Z

Wwang: /* People */

About Cascade

2012-12-17T05:38:10Z

Wwang:

Cascade User Manual

2012-12-17T05:35:26Z

Wwang: /* Build and Install Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse or svn to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:34:48Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jdk]
** [http://www.oracle.com/technetwork/java/javase/downloads/index.html sun-java6-jre]
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:32:56Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** [http://maven.apache.org/download.html maven]
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:32:43Z

Wwang: /* Configure mvn */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure maven ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:31:47Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** [http://eclipse.org/m2e/download/ eclipse maven plugin]
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse plugin]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:30:38Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** eclipse maven plugin
** [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA subclipse]
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:29:37Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** [http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]
** eclipse maven plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:29:25Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** [[http://www.eclipse.org/downloads/packages/release/indigo/sr2 eclipse]]
** eclipse maven plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T05:27:18Z

Wwang: /* Miscellaneous setup */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse maven plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:51:05Z

Wwang: /* Build and Install Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc4-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc4-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc4-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:50:46Z

Wwang: /* Command line */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc3-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc3-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:48:46Z

Wwang: /* Build and Install Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd /Users/Wei/Workspace/cascade-cvc4/core
mvn package
mvn install

* Build "cvc3-plugin"
cd /Users/Wei/Workspace/cascade-cvc4/cvc3-plugin
mvn package
mvn install

*Build "c"
cd /Users/Wei/Workspace/cascade-cvc4/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:46:55Z

Wwang: /* Eclipse */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/Users/Wei/Workspace/target/cvc4/lib/jni"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/Users/Wei/Workspace/cascade-cvc4/c/src/test/resources/c/test/minicase_bug/funcCall_test.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:45:26Z

Wwang: /* Eclipse */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" (DYLD_LIBRARY_PATH for Mac) and Value: "/home/taking/phony_install_targets/cvc3/lib"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:44:43Z

Wwang: /* Command line */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc4jni library and the cvc4 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282-jar-with-dependencies.jar: \
/Users/Wei/Workspace/cascade-cvc4/c/target/cascade-c-0.0.2-SNAPSHOT-r1282.jar edu.nyu.cascade.c.Main /Users/Wei/Workspace/cascade-\
cvc4/c/src/test/resources/c/test/minicase_bug/minus_test.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc4-plugin/target
Can't read plugins directory: /Users/Wei/Workspace/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" and Value: "/home/taking/phony_install_targets/cvc3/lib"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:34:32Z

Wwang: /* Build and Install CVC4 */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc3jni library and the cvc3 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /home/taking/ws/eclipse/c/target/cascade-c-0.0.2-SNAPSHOT-r594-jar-with-dependencies.jar:/home/taking/phony_install_targets/cvc3/java/libcvc3-3.0.0.jar edu.nyu.cascade.c.Main /home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc3-plugin/target
Can't read plugins directory: /home/taking/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" and Value: "/home/taking/phony_install_targets/cvc3/lib"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:31:24Z

Wwang: /* Using Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* For Mac, add library to the DYLD_LIBRARY_PATH in ~/.bashrc (or profile).
export DYLD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$DYLD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

These instructions assume you have followed the installation instructions.

== Command line ==

* Make sure LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac) includes the directory the cvc3jni library and the cvc3 library are installed
export LD_LIBRARY_PATH=/home/taking/phony_install_targets/cvc3/lib:$LD_LIBRARY_PATH
* If you are For the cascade
* The cascade tool can be run using "c/target/cascade.sh". Use "--help" to determine options. This file is generated during the mvn package/install process.
* The cascade.sh tool does the following:
** Defines variables for library locations using the settings from ~/.m2/settings.xml (at the time of mvn install).
** Attempts to set the LD_LIBRARY_PATH variable. Note: I need to set LD_LIBRARY_PATH before cascade.sh. The part of the shell that is intended to set this does not seem to accomplish its task.
** Passes the appropriate arguments to java for the correct classpath and runs the "edu.nyu.cascade.c.Main" class.
* As an alternative to cascade.sh, you can run java directly. An example is below.
java -ea -cp /home/taking/ws/eclipse/c/target/cascade-c-0.0.2-SNAPSHOT-r594-jar-with-dependencies.jar:/home/taking/phony_install_targets/cvc3/java/libcvc3-3.0.0.jar edu.nyu.cascade.c.Main /home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl
* If you are not in the c/ directory when you run this, you may see the warning messages:
Can't read plugins directory: ../cvc3-plugin/target
Can't read plugins directory: /home/taking/.cascade/plugins

== Eclipse ==

* In the Package Explorer, Select c > src/main/java > edu.nyu.cascade.c > Main.java .
* Right-click Main.java. Select Run As > Run Configurations...
* Select the Environment tab
* Click New
* Enter Name: "LD_LIBRARY_PATH" and Value: "/home/taking/phony_install_targets/cvc3/lib"
* Select the Arguments tab
* Add "-ea" to the VM arguments
* Set the Program arguments tab as you would the arguments to cascade.sh. For example: "--help" or "/home/taking/ws/eclipse/c/target/test-classes/META-INF/syntax/swap.ctrl"

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:28:27Z

Wwang: /* Build and Install Cascade */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* For Mac, add library to the DYLD_LIBRARY_PATH in ~/.bashrc (or profile).
export DYLD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$DYLD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

* Use eclipse to check out each of these as top level projects from the [https://subversive.cims.nyu.edu/cascade/trunk/ svn repository].
** c
** core
** cvc3-plugin

* Build "core"
cd ~/ws/eclipse/core
mvn package
mvn install

* Build "cvc3-plugin"
cd ~/ws/eclipse/cvc3-plugin
mvn package
mvn install

*Build "c"
cd ~/ws/eclipse/c
mvn package
mvn install

= Using Cascade =

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

~/.m2/settings.xml

2012-12-17T03:26:22Z

Wwang: Created page with " <settings> <profiles> <profile> <id>tools-builds-cvc4</id> <activation> <activeByDefault>true</activeByDefault> </activation> …"

Cascade User Manual

2012-12-17T03:25:40Z

Wwang: /* Configure mvn */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* For Mac, add library to the DYLD_LIBRARY_PATH in ~/.bashrc (or profile).
export DYLD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$DYLD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my [[~/.m2/settings.xml]].

== Build and Install Cascade ==

= Using Cascade =

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.

Cascade User Manual

2012-12-17T03:24:56Z

Wwang: /* Build and Install CVC4 */

= Getting Cascade =

== Miscellaneous setup ==

* Packages that may need to be installed:
** sun-java6-jdk
** sun-java6-jre
** maven2
** eclipse 3.6.2
** eclipse mvn plugin
** subclipse plugin
* Until the bug is fixed!
** You may need to disable gnome_keyring in ~/.subversion/config.
** To do this set "password-stores = " .

== Build and Install CVC4 ==

* Please check the instructions on visit the [http://cvc4.cs.nyu.edu/wiki/User_Manual#Getting_CVC4 Getting CVC4]. Note that, the directory I used to install CVC4 is "/Users/Wei/Workspace/target/cvc4".
* For Linux, add library to the LD_LIBRARY_PATH in ~/.bashrc (or profile).
export LD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$LD_LIBRARY_PATH
* For Mac, add library to the DYLD_LIBRARY_PATH in ~/.bashrc (or profile).
export DYLD_LIBRARY_PATH=/Users/Wei/Workspace/target/cvc4/lib:$DYLD_LIBRARY_PATH

== Configure mvn ==

Here is a copy of my ~/.m2/settings.xml. Note that /

== Build and Install Cascade ==

= Using Cascade =

== Options ==

Cascade provides a number of options, and we introduce the ones often be used. The complete list of them are attached in [[cascade_options]].
* ''' -D, --debug''': run in debug mode.
* '''--counter-example''': enable counter example generation when Cascade failed to prove.
* '''--feasibility''': check path feasibility for runs.
* '''--order-alloc''': use an ordered allocation model (unsound). It assumes that there's no aliasing, overlapping between regions in the memory in an unsound way that keeps an arbitrary order of memory cells. It is enabled in the running of all the following examples.
* '''--sound-alloc''': use a sound allocation model (may be slow). It assumes that there's no aliasing, overlapping between regions in the memory in a sound way. However, it generates a very large formula involves many case-splitting, and thus the verification in the theorem prover maybe slow.
* '''--resource-limit <N>''': set resource limit for the theorem prover to N level.
* '''--time-limit <N>''': set time limit for the theorem prover to N sec.
* '''--cvc4-stats''': show statistics of the theorem prover.
* '''--iter-times <N>''': default iteration times of loop unrolling.

= Control Flow Annotation =

Instead of inserting annotations in the source code, Cascade keeps them in a control file in order to leaves the source code clean. The control file is in the simple XML format, which serves as the guidance of verification. In this section, we will introduce the elements included control files by showing how to verify some sample codes in Cascade.

== Basic Structure ==

Every control file starts with ''sourceFile'' sections that specify the files to be analyzed. Each source file has two attributes: ''name'' contains the path to the file, and ''fileId'' attaches a unique id to it. After ''sourceFile'', one or more ''run'' sections are specified, which describe the runs to be checked. Each run starts with a single ''startPosition'' and ''endPosition'' to give the start point and the end point respectively, and in between, one or more ''wayPoint''s may be inserted optionally to indicate the positions should be passed through.

Let's discuss it more with a simple example [[abs.c]]. This program returns the absolute value of parameter x.

[[abs1.ctrl]] is the control file for it, in which the ''sourceFile'' indicates the path to abs.c and assigns an id 1 for it. For the execution path to check, we simply use the start and end line number of [[abs.c]] as ''startPosition'' and ''endPosition''. Since there's a conditional statement if-else, we use a ''wayPoint'' to select one to check. Normally, a ''wayPoint'' is often the first line of the chosen code. Note that the ''fileId'' is all assigned to 1 in the ''startPosition'', ''endPosition'' and ''wayPoint'', which means these positions are all in [[abs.c]] (whose id is 1).

As mentioned above, multiple paths can be specified in one control file. In [[abs2.ctrl]], two possible alternative runs of [[abs.c]] are considered together.

== Function Call ==

Cascade supports functions by inlining. The locality of the parameters and the non-static local variables are preserved by attaching them with their scopes. Cascade can perform inlining and and thus parameters passing automatically. We'll see it in the example [[pow2.c]] and [[pow2.ctrl]].

If the function contains branches and loops and we need to check a specific execution path in it, the annotation ''function'' will be helpful, as shown in example [[absext.c]] and [[absext.ctrl]]. The ''function'' section is nested under the ''wayPoint'' where it is called. It has an attribute ''funcName'', whose value is name of the function, and the ''wayPoint''s of the path in that function is nested under it.

If multiple functions are called at the same line of code, we could nested multiple ''function''s under the ''wayPoint'', and differentiate them with the attribute ''funcId'' if the ''funcName'' are same, as in [[absext2.c]] and [[absext2.ctrl]].

== Loop ==

Cascade supports loop unwinding, which is unrolling the loops by finite number of times. It means the user must specify a bound by the attribute ''iterTimes'' in the anotation ''loop''. Cascade will then unwind the loops up to that bound, and we can check if the number is correct or not by using option --feasibility (which is used to check the specific path is feasible or not). As an example, consider [[log2.c]] and [[log2.ctrl]] (note that the ''loop'' is nested in the ''function'').

If there's a conditional statement inside the ''loop'', we also can specify ''wayPoint''s in it. In addition, if different rounds of iteration have different execution paths, which means we need to specify them separately, we would nested multiple ''loop''s under one ''wayPoint''. We will be clear about it with an example [[gcd.c]] and [[gcd.ctrl]].

= Cascade Command =

In addition to execution path, we could specify some commands in control files, which involves adding assertions, assumptions and memory allocations. These commands are in the following format:
<command>
<cascadeFunction> cascade_cmd </cascadeFunction>
<argument> arg_expr1 </argument>
<argument><![CDATA[
arg_expr2
]]>
</argument>
</command>

Before we go further into specific commands, let's talk a little about the argument expressions. They are valid C expressions, and a CDATA section can be used to allow regular C syntax within the XML format document. All variables referenced in the argument expression should be in scope at this position. Besides, Cascade provides a number of C extension that can be used within argument expressions to enable more expressive reasoning.
* Logic implication: '''_implies(P, Q)'''. It formally means ((!P) || Q).
* Universal quantification: '''_forall(v, u, E)'''. It means for every value v and u, E is true. For example, the assertion
x > 1 && _forall(i, _implies(1 < i && i < x, x % i != 0))
* Existential quantification: '''_exists(v, u, E)'''. It means for some value v and u, E is true. For example, the assertion
_exists(i, _implies(1 < i && i < N, b[i] == 0))
* Valid address predicate: '''_valid(p)'''. It means that p is a valid address in the memory, which has been allocated and not been freed yet.
_forall(i, _implies(0 <= i && i < N, _valid(&b[i])))
* Reachability predicate: '''_reach(f, a, b)'''. It means that ''a'' can reach ''b'' via ''f''-path. This predicate captures the unbounded number of dynamically allocated cells present in a linked list. For a given cell ''a'', it characterizes the set of cells {''a'', ''a.f'', ''a.f.f'', ...} reachable from ''u'' via ''f''-path using the transitive closure (will be discussed later in details).
_implies(_reach(f, a, b) && _reach(f, b, c), _reach(f, a, c))
* Heap allocation predicate: '''_allocated(p, size)'''. It is used to assume that a region with size 4 has been allocated at p. This predicate is very helpful for modular verification, particularly of a function with pointers, arrays or structures as input arguments. As an example, consider [[strlen.c]] and [[strlen.ctrl]].
_allocated(str, 4*sizeof(char))

Now, let's go through those Cascade commands. They could be added at each position in the specific run, such as start point, end point and way point. The effect of them would be same as modifying the C source file to insert the statement at the exact position.

== Cascade_check ==

The effect of this command is the same as the assert statement. Cascade would check if the argument expression is true at the particular position. Let's go back to the example of [[abs.c]] to see how to use it. Clearly, one desired property expected to hold at the end point of this program is
result >= 0
In [[abs3.ctrl]], such expression is an argument of command ''cascade_check''. Run Cascade, it is proved to be "valid" in both runs, which means it is guaranteed to hold in both branches.

== Cascade_assume ==

Sometimes, we want Cascade to ignore certain cases that would otherwise lead to invalid proof, in order to narrow down the check to more specific senario. We can do it by inserting assume statement at specific points of the run in the control file, as shown in the example [[div.c]]. This program computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type "div_t". In the corresponding control file [[div.ctrl]], an assumption
denom != 0
is inserted at the start point, which excludes the possiblity of division by zero. Without this assumption, Cascade would fail to prove the asserted formula. The reason behind this is that division by zero is undefined in mathematics, and thus "result.quote" is an arbitrary value.
num == div_result.quot * denom + div_result.rem
In fact, every statement along the execution path of the program is also an assumption, and the backend theorem prover is to prove if all assumptions hold, all assertions will also hold.

= Reachability =

In this section, we will discuss how to use Cascade to reason about reachability of linked data structure in details. Currently, we only support reason about linked list with single field. As discussed above, the predicate '''_reach(f, a, b)''' is used to indicate that b is reachable from a by repeatedly visiting the field f, and it is the key of our reasoning. [[list.c]] contains a number of functions of singly linked list, and we give a sample control file [[list_create.ctrl]] for the first function create(). A new section ''theory'' is created after ''sourceFile'', and it defines the theory used in the reasoning. The attribute ''qname'' gives the name of the theory. In the assertion
_reach(next, root, 0)
indicates that root can reach NULL (which defines as 0 in [[list.c]]) finally, which means that the created list is an acyclic list.