Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +You may be interested in applying Kani if you're in this situation:
+++If you haven't already, we also recommend techniques like property testing and fuzzing (e.g. with
+bolero). +These yield good results, are very cheap to apply, and are often easy to adopt and debug.
In this section, we explain how Kani compares with other tools +and suggest where to start applying Kani in real code.
+ +benchcomp command linebenchcomp is a single command that runs benchmarks, parses their results, combines these results, and emits visualizations.
+benchcomp also provides subcommands to run these steps individually.
+Most users will want to invoke benchcomp in one of two ways:
benchcomp without any subcommands, which runs the entire performance comparison process as depicted belowbenchcomp visualize, which runs the visualization step on the results of a previous benchmark run without actually re-running the benchmarks.
+This is useful when tweaking the parameters of a visualization, for example changing the threshold of what is considered to be a regression.The subcommands run and collate are also available.
+The diagram below depicts benchcomp's order of operation.
Running benchcomp invokes run, collate, and visualize behind the scenes.
+If you have previously run benchcomp, then running benchcomp visualize will emit the visualizations in the config file using the previous result.yaml.
In the diagram above, two different suites (1 and 2) are both run using two variants---combinations of command, working directory, and environment variables.
+Benchmark suite 2 requires a totally different command line to suite 1---for example, suite_1 might contain Kani harnesses invoked through cargo kani, while suite_2 might contain CBMC harnesses invoked through run_cbmc_proofs.py.
+Users would therefore define different variants (c and d) for invoking suite_2, and also specify a different parser to parse the results.
+No matter how different the benchmark suites are, the collate stage combines their results so that they can later be compared.
Users must specify the actual suites to run, the parsers used to collect their results, and the visualizations to emit in a file called benchcomp.yaml or a file passed to the -c/--config flag.
+The next section describes the schema for this configuration file.
+A run similar to the diagram above might be achieved using the following configuration file:
# Compare a range of Kani and CBMC benchmarks when
+# using Cadical versus the default SAT solver
+
+variants:
+ variant_a:
+ config:
+ directory: kani_benchmarks
+ command_line: scripts/kani-perf.sh
+ env: {}
+
+ variant_b:
+ config:
+ directory: kani_benchmarks
+ command_line: scripts/kani-perf.sh
+ # This variant uses a hypothetical environment variable that
+ # forces Kani to use the cadical SAT solver
+ env:
+ KANI_SOLVER: cadical
+
+ variant_c:
+ config:
+ directory: cbmc_benchmarks
+ command_line: run_cbmc_proofs.py
+ env: {}
+
+ variant_d:
+ config:
+ directory: cbmc_benchmarks
+ command_line: run_cbmc_proofs.py
+ env:
+ EXTERNAL_SAT_SOLVER: cadical
+
+run:
+ suites:
+ suite_1:
+ parser:
+ module: kani_perf
+ variants: [variant_a, variant_b]
+
+ suite_2:
+ parser:
+ module: cbmc_litani_parser
+ variants: [variant_c, variant_d]
+
+visualize:
+ - type: dump_graph
+ out_file: graph.svg
+
+ - type: dump_markdown_results_table
+ out_file: summary.md
+ extra_columns: []
+
+ - type: error_on_regression
+ variant_pairs:
+ - [variant_a, variant_b]
+ - [variant_c, variant_d]
+benchcomp configuration filebenchcomp's operation is controlled through a YAML file---benchcomp.yaml by default or a file passed to the -c/--config option.
+This page lists the different visualizations that are available.
A variant is a single invocation of a benchmark suite. Benchcomp runs several
+variants, so that their performance can be compared later. A variant consists of
+a command-line argument, working directory, and environment. Benchcomp invokes
+the command using the operating system environment, updated with the keys and
+values in env. If any values in env contain strings of the form ${var},
+Benchcomp expands them to the value of the environment variable $var.
variants:
+ variant_1:
+ config:
+ command_line: echo "Hello, world"
+ directory: /tmp
+ env:
+ PATH: /my/local/directory:${PATH}
+After benchcomp has finished parsing the results, it writes the results to results.yaml by default.
+Before visualizing the results (see below), benchcomp can filter the results by piping them into an external program.
To filter results before visualizing them, add filters to the configuration file.
filters:
+ - command_line: ./scripts/remove-redundant-results.py
+ - command_line: cat
+The value of filters is a list of dicts.
+Currently the only legal key for each of the dicts is command_line.
+Benchcomp invokes each command_line in order, passing the results as a JSON file on stdin, and interprets the stdout as a YAML-formatted modified set of results.
+Filter scripts can emit either YAML (which might be more readable while developing the script), or JSON (which benchcomp will parse as a subset of YAML).
The following visualizations are available; these can be added to the visualize list of benchcomp.yaml.
Detailed documentation for these visualizations follows.
+Scatterplot configuration options
+Print Markdown-formatted tables displaying benchmark results
+For each metric, this visualization prints out a table of benchmarks, +showing the value of the metric for each variant, combined with an optional +scatterplot.
+The 'out_file' key is mandatory; specify '-' to print to stdout.
+'extra_colums' can be an empty dict. The sample configuration below assumes +that each benchmark result has a 'success' and 'runtime' metric for both +variants, 'variant_1' and 'variant_2'. It adds a 'ratio' column to the table +for the 'runtime' metric, and a 'change' column to the table for the +'success' metric. The 'text' lambda is called once for each benchmark. The +'text' lambda accepts a single argument---a dict---that maps variant +names to the value of that variant for a particular metric. The lambda +returns a string that is rendered in the benchmark's row in the new column. +This allows you to emit arbitrary text or markdown formatting in response to +particular combinations of values for different variants, such as +regressions or performance improvements.
+'scatterplot' takes the values 'off' (default), 'linear' (linearly scaled +axes), or 'log' (logarithmically scaled axes).
+Sample configuration:
+visualize:
+- type: dump_markdown_results_table
+ out_file: "-"
+ scatterplot: linear
+ extra_columns:
+ runtime:
+ - column_name: ratio
+ text: >
+ lambda b: str(b["variant_2"]/b["variant_1"])
+ if b["variant_2"] < (1.5 * b["variant_1"])
+ else "**" + str(b["variant_2"]/b["variant_1"]) + "**"
+ success:
+ - column_name: change
+ text: >
+ lambda b: "" if b["variant_2"] == b["variant_1"]
+ else "newly passing" if b["variant_2"]
+ else "regressed"
+Example output:
+## runtime
+
+| Benchmark | variant_1 | variant_2 | ratio |
+| --- | --- | --- | --- |
+| bench_1 | 5 | 10 | **2.0** |
+| bench_2 | 10 | 5 | 0.5 |
+
+## success
+
+| Benchmark | variant_1 | variant_2 | change |
+| --- | --- | --- | --- |
+| bench_1 | True | True | |
+| bench_2 | True | False | regressed |
+| bench_3 | False | True | newly passing |
+Print the YAML-formatted results to a file.
+The 'out_file' key is mandatory; specify '-' to print to stdout.
+Sample configuration:
+visualize:
+- type: dump_yaml
+ out_file: '-'
+Terminate benchcomp with a return code of 1 if any benchmark regressed.
+This visualization checks whether any benchmark regressed from one variant +to another. Sample configuration:
+visualize:
+- type: error_on_regression
+ variant_pairs:
+ - [variant_1, variant_2]
+ - [variant_1, variant_3]
+ checks:
+ - metric: runtime
+ test: "lambda old, new: new / old > 1.1"
+ - metric: passed
+ test: "lambda old, new: False if not old else not new"
+This says to check whether any benchmark regressed when run under variant_2 +compared to variant_1. A benchmark is considered to have regressed if the +value of the 'runtime' metric under variant_2 is 10% higher than the value +under variant_1. Furthermore, the benchmark is also considered to have +regressed if it was previously passing, but is now failing. These same +checks are performed on all benchmarks run under variant_3 compared to +variant_1. If any of those lambda functions returns True, then benchcomp +will terminate with a return code of 1.
+Run an executable command, passing the performance metrics as JSON on stdin.
+This allows you to write your own visualization, which reads a result file +on stdin and does something with it, e.g. writing out a graph or other +output file.
+Sample configuration:
+visualize:
+- type: run_command
+ command: ./my_visualization.py
+Benchcomp ships with built-in parsers that retrieve the results of a benchmark suite after the run has completed. +You can also create your own parser, either to run locally or to check into the Kani codebase.
+You specify which parser should run for each benchmark suite in benchcomp.yaml.
+For example, if you're running the kani performance suite, you would use the built-in kani_perf parser to parse the results:
suites:
+ my_benchmark_suite:
+ variants: [variant_1, variant_2]
+ parser:
+ module: kani_perf
+A parser is a program that benchcomp runs inside the root directory of a benchmark suite, after the suite run has completed.
+The parser should retrieve the results of the run (by parsing output files etc.) and print the results out as a YAML document.
+You can use your executable parser by specifying the command key rather than the module key in your benchconf.yaml file:
suites:
+ my_benchmark_suite:
+ variants: [variant_1, variant_2]
+ parser:
+ command: ./my-cool-parser.sh
+The kani_perf parser mentioned above, in tools/benchcomp/benchcomp/parsers/kani_perf.py, is a good starting point for writing a custom parser, as it also works as a standalone executable.
+Here is an example output from an executable parser:
metrics:
+ runtime: {}
+ success: {}
+ errors: {}
+benchmarks:
+ bench_1:
+ metrics:
+ runtime: 32
+ success: true
+ errors: []
+ bench_2:
+ metrics:
+ runtime: 0
+ success: false
+ errors: ["compilation failed"]
+The above format is different from the final result.yaml file that benchcomp writes, because the above file represents the output of running a single benchmark suite using a single variant.
+Your parser will run once for each variant, and benchcomp combines the dictionaries into the final result.yaml file.
To turn your executable parser into one that benchcomp can invoke as a module, ensure that it has a main(working_directory) method that returns a dict (the same dict that it would print out as a YAML file to stdout).
+Save the file in tools/benchcomp/benchcomp/parsers using python module naming conventions (filename should be an identifier and end in .py).
++If you were able to install Kani normally, you do not need to build Kani from source. +You probably want to proceed to the Kani tutorial.
+
In general, the following dependencies are required to build Kani from source.
+++NOTE: These dependencies may be installed by running the scripts shown +below and don't need to be manually installed.
+
Kani has been tested in Ubuntu and macOS platforms.
+Support is available for Ubuntu 18.04, 20.04 and 22.04. +The simplest way to install dependencies (especially if you're using a fresh VM) +is following our CI scripts:
+# git clone git@github.com:model-checking/kani.git
+git clone https://github.com/model-checking/kani.git
+cd kani
+git submodule update --init
+./scripts/setup/ubuntu/install_deps.sh
+# If you haven't already (or from https://rustup.rs/):
+./scripts/setup/install_rustup.sh
+source $HOME/.cargo/env
+Support is available for macOS 11. You need to have Homebrew installed already.
+# git clone git@github.com:model-checking/kani.git
+git clone https://github.com/model-checking/kani.git
+cd kani
+git submodule update --init
+./scripts/setup/macos/install_deps.sh
+# If you haven't already (or from https://rustup.rs/):
+./scripts/setup/install_rustup.sh
+source $HOME/.cargo/env
+Build the Kani package:
+cargo build-dev
+Then, optionally, run the regression tests:
+./scripts/kani-regression.sh
+This script has a lot of noisy output, but on a successful run you'll see at the end of the execution:
+All Kani regression tests completed successfully.
+To use a locally-built Kani from anywhere, add the Kani scripts to your path:
+export PATH=$(pwd)/scripts:$PATH
+If you're learning Kani for the first time, you may be interested in our tutorial.
+ +This section describes how to access more advanced CBMC options from Kani.
+Kani is able to handle common CBMC arguments as if they were its own (e.g.,
+--default-unwind <n>), but sometimes it may be necessary to use CBMC arguments which
+are not handled by Kani.
To pass additional arguments for CBMC, you pass --cbmc-args to Kani. Note that
+this "switches modes" from Kani arguments to CBMC arguments: Any arguments that
+appear after --cbmc-args are considered to be CBMC arguments, so all Kani
+arguments must be placed before it.
Thus, the command line format to invoke cargo kani with CBMC arguments is:
cargo kani [<kani-args>]* --cbmc-args [<cbmc-args>]*
+++NOTE: In cases where CBMC is not expected to emit a verification output, +you have to use Kani's argument
+--output-format oldto turn off the +post-processing of output from CBMC.
Setting --default-unwind <n> affects every loop in a harness.
+Once you know a particular loop is causing trouble, sometimes it can be helpful to provide a specific bound for it.
In the general case, specifying just the highest bound globally for all loops +shouldn't cause any problems, except that the solver may take more time because +all loops will be unwound to the specified bound.
+In situations where you need to optimize for the solver, individual bounds for
+each loop can be provided on the command line. To do so, we first need to know
+the labels assigned to each loop with the CBMC argument --show-loops:
# kani src/lib.rs --output-format old --cbmc-args --show-loops
+[...]
+Loop _RNvCs6JP7pnlEvdt_3lib17initialize_prefix.0:
+ file ./src/lib.rs line 11 column 5 function initialize_prefix
+
+Loop _RNvMs8_NtNtCswN0xKFrR8r_4core3ops5rangeINtB5_14RangeInclusivejE8is_emptyCs6JP7pnlEvdt_3lib.0:
+ file $RUST/library/core/src/ops/range.rs line 540 column 9 function std::ops::RangeInclusive::<Idx>::is_empty
+
+Loop gen-repeat<[u8; 10]::16806744624734428132>.0:
+This command shows us the labels of the loops involved. Note that, as mentioned
+in CBMC arguments, we need to use --output-format old to
+avoid post-processing the output from CBMC.
++NOTE: At the moment, these labels are constructed using the mangled name +of the function and an index. Mangled names are likely to change across +different versions, so this method is highly unstable.
+
Then, we can use the CBMC argument --unwindset label_1:bound_1,label_2:bound_2,... to specify an individual bound for each
+loop as follows:
kani src/lib.rs --cbmc-args --unwindset _RNvCs6JP7pnlEvdt_3lib17initialize_prefix.0:12
+Development work in the Kani project depends on multiple tools. Regardless of +your familiarity with the project, the commands below may be useful for +development purposes.
+# Error "'rustc' panicked at 'failed to lookup `SourceFile` in new context'"
+# or similar error? Cleaning artifacts might help.
+# Otherwise, comment the line below.
+cargo clean
+cargo build-dev
+# Full regression suite
+./scripts/kani-regression.sh
+# Delete regression test caches (Linux)
+rm -r build/x86_64-unknown-linux-gnu/tests/
+# Delete regression test caches (macOS)
+rm -r build/x86_64-apple-darwin/tests/
+# Test suite run (we can only run one at a time)
+# cargo run -p compiletest -- --suite ${suite} --mode ${mode}
+cargo run -p compiletest -- --suite kani --mode kani
+# Build documentation
+cd docs
+./build-docs.sh
+These can help understand what Kani is generating or encountering on an example or test file:
+# Enable `debug!` macro logging output when running Kani:
+kani --debug file.rs
+# Use KANI_LOG for a finer grain control of the source and verbosity of logs.
+# E.g.: The command below will print all logs from the kani_middle module.
+KANI_LOG="kani_compiler::kani_middle=trace" kani file.rs
+# Keep CBMC Symbol Table and Goto-C output (.json and .goto)
+kani --keep-temps file.rs
+# Generate "C code" from CBMC IR (.c)
+kani --gen-c file.rs
+# Generate a ${INPUT}.kani.mir file with a human friendly MIR dump
+# for all items that are compiled to the respective goto-program.
+RUSTFLAGS="--emit mir" kani ${INPUT}.rs
+The KANI_REACH_DEBUG environment variable can be used to debug Kani's reachability analysis.
+If defined, Kani will generate a DOT graph ${INPUT}.dot with the graph traversed during reachability analysis.
+If defined and not empty, the graph will be filtered to end at functions that contains the substring
+from KANI_REACH_DEBUG.
Note that this will only work on debug builds.
+# Generate a DOT graph ${INPUT}.dot with the graph traversed during reachability analysis
+KANI_REACH_DEBUG= kani ${INPUT}.rs
+
+# Generate a DOT graph ${INPUT}.dot with the sub-graph traversed during the reachability analysis
+# that connect to the given target.
+KANI_REACH_DEBUG="${TARGET_ITEM}" kani ${INPUT}.rs
+# See CBMC IR from a C file:
+goto-cc file.c -o file.out
+goto-instrument --print-internal-representation file.out
+# or (for json symbol table)
+cbmc --show-symbol-table --json-ui file.out
+# or (an alternative concise format)
+cbmc --show-goto-functions file.out
+# Recover C from goto-c binary
+goto-instrument --dump-c file.out > file.gen.c
+The Kani project follows the squash and merge option for pull request merges. +As a result:
+But the main commit message body is editable at merge time, so you don't have to worry about "typo fix" messages because these can be removed before merging.
+# Set up your git fork
+git remote add fork git@github.com:${USER}/kani.git
+# Reset everything. Don't have any uncommitted changes!
+git clean -xffd
+git submodule foreach --recursive git clean -xffd
+git submodule update --init
+# Need to update local branch (e.g. for an open pull request?)
+git fetch origin
+git merge origin/main
+# Or rebase, but that requires a force push,
+# and because we squash and merge, an extra merge commit in a PR doesn't hurt.
+# Checkout a pull request locally without the github cli
+git fetch origin pull/$ID/head:pr/$ID
+git switch pr/$ID
+# Push to someone else's pull request
+git origin add $USER $GIR_URL_FOR_THAT_USER
+git push $USER $LOCAL_BRANCH:$THEIR_PR_BRANCH_NAME
+# Search only git-tracked files
+git grep codegen_panic
+# Accidentally commit to main?
+# "Move" commit to a branch:
+git checkout -b my_branch
+# Fix main:
+git branch --force main origin/main
+We automate most of our formatting preferences. Our CI will run format checkers for PRs and pushes. +These checks are required for merging any PR.
+For Rust, we use rustfmt
+which is configured via the rustfmt.toml file.
+We are also in the process of enabling clippy.
+Because of that, we still have a couple of lints disabled (see .cargo/config for the updated list).
We also have a bit of C and Python code in our repository.
+For C we use clang-format and for Python scripts we use autopep8.
+See .clang-format
+and pyproject.toml
+for their configuration.
We recognize that in some cases, the formatting and lints automation may not be applicable to a specific code.
+In those cases, we usually prefer explicitly allowing exceptions by locally disabling the check.
+E.g., use #[allow] annotation instead of disabling a link on a crate or project level.
All source code files begin with a copyright and license notice. If this is a new file, please add the following notice:
+// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+When modifying a file from another project, please keep their headers as is and append the following notice after them:
+// ... existing licensing headers ...
+
+// Modifications Copyright Kani Contributors
+// See GitHub history for details.
+Note: The comment escape characters will depend on the type of file you are working with. E.g.: For rust start the
+header with //, but for python start with #.
We also have automated checks for the copyright notice. +There are a few file types where this rule doesn't apply. +You can see that list in the copyright-exclude file.
+We are developing Kani to provide assurance that critical Rust components are verifiably free of certain classes of +security and correctness issues. +Thus, it is critical that we provide a verification tool that is sound. +For the class of errors that Kani can verify, we should not produce a "No Error" result if there was in fact an +error in the code being verified, i.e., it has no +"False Negatives".
+Because of that, we bias on the side of correctness. +Any incorrect modeling +that may trigger an unsound analysis that cannot be fixed in the short term should be mitigated. +Here are a few ways how we do that.
+Make sure to add user-friendly errors for constructs that we can't handle. +For example, Kani cannot handle the panic unwind strategy, and it will fail compilation if the crate uses this +configuration.
+In general, it's preferred that error messages follow these guidelines used for rustc development.
+If the errors are being emitted from kani-compiler, you should use the compiler error message utilities (e.g., the Session::span_err method). However, if the
+errors are being emitted from kani-driver, you should use the functions provided in the util module in kani-driver.
Even though this doesn't provide users the best experience, you are encouraged to add checks in the compiler for any
+assumptions you make during development.
+Those checks can be on the form of assert!() or unreachable!()
+statement.
+Please provide a meaningful message to help user understand why something failed, and try to explain, at least with
+a comment, why this is the case.
We don't formally use any specific formal representation of function contract, +but whenever possible we do instrument the code with assertions that may represent the function pre- and +post-conditions to ensure we are modeling the user code correctly.
+In cases where Kani fails to model a certain instruction or local construct that doesn't have a global effect,
+we encode this failure as a verification error.
+I.e., we generate an assertion failure instead of the construct we are modeling using
+codegen_unimplemented(),
+which blocks the execution whenever this construct is reached.
This will allow users to verify their crate successfully as long as
+that construct is not reachable in any harness. If a harness has at least one possible execution path that reaches
+such construct, Kani will fail the verification, and it will mark all checks, other than failed checks, with
+UNDETERMINED status.
It is OK to add "TODO" comments as long as they don't compromise user experience or the tool correctness. +When doing so, please create an issue that captures the task. +Add details about the task at hand including any impact to the user. +Finally, add the link to the issue that captures the "TODO" task as part of your comment.
+E.g.:
+// TODO: This function assumes type cannot be ZST. Check if that's always the case.
+// https://github.com/model-checking/kani/issues/XXXX
+assert!(!typ.is_zst(), "Unexpected ZST type");
+We aim at writing code that is performant but also readable and easy to maintain. +Avoid compromising the code quality if the performance gain is not significant.
+Here are few tips that can help the readability of your code:
+pub trait Arbitrarywhere
+ Self: Sized,{
+ // Required method
+ fn any() -> Self;
+
+ // Provided method
+ fn any_array<const MAX_ARRAY_LENGTH: usize>() -> [Self; MAX_ARRAY_LENGTH]
+ where [(); { _ }]: { ... }
+}This trait should be used to generate symbolic variables that represent any valid value of +its type.
+Validate that a char is not outside the ranges [0x0, 0xD7FF] and [0xE000, 0x10FFFF] +Ref: https://doc.rust-lang.org/stable/nomicon/what-unsafe-does.html
+#[ensures]Add a postcondition to this function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a condition over the input values to the
+annotated function and its return value, accessible as a variable called
+result. All Rust syntax is supported, even calling other functions, but
+the computations must be side effect free, e.g. it cannot perform I/O or use
+mutable memory.
Kani requires each function that uses a contract (this attribute or
+requires) to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[modifies]Declaration of an explicit write-set for the annotated function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a series of comma-separated expressions referencing the
+arguments of the function. Each expression is expected to return a pointer type, i.e. *const T,
+*mut T, &T or &mut T. The pointed-to type must implement
+Arbitrary.
All Rust syntax is supported, even calling other functions, but the computations must be side +effect free, e.g. it cannot perform I/O or use mutable memory.
+Kani requires each function that uses a contract to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[proof]Marks a Kani proof harness
+For async harnesses, this will call block_on to drive the future to completion (see its documentation for more information).
If you want to spawn tasks in an async harness, you have to pass a schedule to the #[kani::proof] attribute,
+e.g. #[kani::proof(schedule = kani::RoundRobin::default())].
This will wrap the async function in a call to block_on_with_spawn (see its documentation for more information).
#[proof_for_contract]Designates this function as a harness to check a function contract.
+The argument to this macro is the relative path (e.g. foo or
+super::some_mod::foo or crate::SomeStruct::foo) to the function, the
+contract of which should be checked.
This is part of the function contract API, for more general information see +the module-level documentation.
+#[recursion]Specifies that a function contains recursion for contract instrumentation.**
+This attribute is only used for function-contract instrumentation. Kani uses
+this annotation to identify recursive functions and properly instantiate
+kani::any_modifies to check such functions using induction.
#[requires]Add a precondition to this function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a condition over the input values to the +annotated function. All Rust syntax is supported, even calling other +functions, but the computations must be side effect free, e.g. it cannot +perform I/O or use mutable memory.
+Kani requires each function that uses a contract (this attribute or
+ensures) to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[should_panic]Specifies that a proof harness is expected to panic.**
+This attribute allows users to exercise negative verification.
+It’s analogous to how
+#[should_panic]
+allows users to exercise negative testing
+for Rust unit tests.
The #[kani::should_panic] attribute verifies that there are one or more failed checks related to panics.
+At the moment, it’s not possible to pin it down to specific panics.
#[stub]Specify a function/method stub pair to use for proof harness
+The attribute #[kani::stub(original, replacement)] can only be used alongside #[kani::proof].
original - The function or method to replace, specified as a path.replacement - The function or method to use as a replacement, specified as a path.#[stub_verified]stub_verified(TARGET) is a harness attribute (to be used on
+proof or proof_for_contract
+function) that replaces all occurrences of TARGET reachable from this
+harness with a stub generated from the contract on TARGET.
The target of stub_verified must have a contract. More information about
+how to specify a contract for your function can be found
+here.
You may use multiple stub_verified attributes on a single harness.
This is part of the function contract API, for more general information see +the module-level documentation.
+#[ensures]Add a postcondition to this function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a condition over the input values to the
+annotated function and its return value, accessible as a variable called
+result. All Rust syntax is supported, even calling other functions, but
+the computations must be side effect free, e.g. it cannot perform I/O or use
+mutable memory.
Kani requires each function that uses a contract (this attribute or
+requires) to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[modifies]Declaration of an explicit write-set for the annotated function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a series of comma-separated expressions referencing the
+arguments of the function. Each expression is expected to return a pointer type, i.e. *const T,
+*mut T, &T or &mut T. The pointed-to type must implement
+Arbitrary.
All Rust syntax is supported, even calling other functions, but the computations must be side +effect free, e.g. it cannot perform I/O or use mutable memory.
+Kani requires each function that uses a contract to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[proof_for_contract]Designates this function as a harness to check a function contract.
+The argument to this macro is the relative path (e.g. foo or
+super::some_mod::foo or crate::SomeStruct::foo) to the function, the
+contract of which should be checked.
This is part of the function contract API, for more general information see +the module-level documentation.
+#[requires]Add a precondition to this function.
+This is part of the function contract API, for more general information see +the module-level documentation.
+The contents of the attribute is a condition over the input values to the +annotated function. All Rust syntax is supported, even calling other +functions, but the computations must be side effect free, e.g. it cannot +perform I/O or use mutable memory.
+Kani requires each function that uses a contract (this attribute or
+ensures) to have at least one designated
+proof_for_contract harness for checking the
+contract.
#[stub_verified]stub_verified(TARGET) is a harness attribute (to be used on
+proof or proof_for_contract
+function) that replaces all occurrences of TARGET reachable from this
+harness with a stub generated from the contract on TARGET.
The target of stub_verified must have a contract. More information about
+how to specify a contract for your function can be found
+here.
You may use multiple stub_verified attributes on a single harness.
This is part of the function contract API, for more general information see +the module-level documentation.
+Kani implementation of function contracts.
+Function contracts are still under development. Using the APIs therefore
+requires the unstable -Zfunction-contracts flag to be passed. You can join
+the discussion on contract design by reading our
+RFC
+and commenting on the tracking
+issue.
The function contract API is expressed as proc-macro attributes, and there +are two parts to it.
+requires and ensures.proof_for_contract and
+stub_verified.Let us explore using a workflow involving contracts on the example of a
+simple division function my_div:
fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}With the contract specification attributes we can specify the behavior of
+this function declaratively. The requires attribute
+allows us to declare constraints on what constitutes valid inputs to our
+function. In this case we would want to disallow a divisor that is 0.
#[requires(divisor != 0)]This is called a precondition, because it is enforced before (pre-) the
+function call. As you can see attribute has access to the functions
+arguments. The condition itself is just regular Rust code. You can use any
+Rust code, including calling functions and methods. However you may not
+perform I/O (like println!) or mutate memory (like Vec::push).
The ensures attribute on the other hand lets us describe
+the output value in terms of the inputs. You may be as (im)precise as you
+like in the ensures clause, depending on your needs. One
+approximation of the result of division for instance could be this:
#[ensures(result <= dividend)]This is called a postcondition and it also has access to the arguments and
+is expressed in regular Rust code. The same restrictions apply as did for
+requires. In addition to the arguments the postcondition
+also has access to the value returned from the function in a variable called
+result.
You may combine as many requires and
+ensures attributes on a single function as you please.
+They all get enforced (as if their conditions were &&ed together) and the
+order does not matter. In our example putting them together looks like this:
#[kani::requires(divisor != 0)]
+#[kani::ensures(result <= dividend)]
+fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}Once we are finished specifying our contract we can ask Kani to check it’s
+validity. For this we need to provide a proof harness that exercises the
+function. The harness is created like any other, e.g. as a test-like
+function with inputs and using kani::any to create arbitrary values.
+However we do not need to add any assertions or assumptions about the
+inputs, Kani will use the pre- and postconditions we have specified for that
+and we use the proof_for_contract attribute
+instead of proof and provide it with the path to the
+function we want to check.
#[kani::proof_for_contract(my_div)]
+fn my_div_harness() {
+ my_div(kani::any(), kani::any()) }The harness is checked like any other by running cargo kani and can be
+specifically selected with --harness my_div_harness.
Once we have verified that our contract holds, we can use perhaps it’s +coolest feature: verified stubbing. This allows us to use the conditions of +the contract instead of it’s implementation. This can be very powerful for +expensive implementations (involving loops for instance).
+Verified stubbing is available to any harness via the
+stub_verified harness attribute. We must provide
+the attribute with the path to the function to stub, but unlike with
+stub we do not need to provide a function to replace with,
+the contract will be used automatically.
#[kani::proof]
+#[kani::stub_verified(my_div)]
+fn use_div() {
+ let v = vec![...];
+ let some_idx = my_div(v.len() - 1, 3);
+ v[some_idx];
+}In this example the contract is sufficient to prove that the element access +in the last line cannot be out-of-bounds.
+The basic two specification attributes available for describing
+function behavior are requires for preconditions and
+ensures for postconditions. Both admit arbitrary Rust
+expressions as their bodies which may also reference the function arguments
+but must not mutate memory or perform I/O. The postcondition may
+additionally reference the return value of the function as the variable
+result.
In addition Kani provides the modifies attribute. This
+works a bit different in that it does not contain conditions but a comma
+separated sequence of expressions that evaluate to pointers. This attribute
+constrains to which memory locations the function is allowed to write. Each
+expression can contain arbitrary Rust syntax, though it may not perform side
+effects and it is also currently unsound if the expression can panic. For more
+information see the write sets section.
During verified stubbing the return value of a function with a contract is
+replaced by a call to kani::any. As such the return value must implement
+the kani::Arbitrary trait.
In Kani, function contracts are optional. As such a function with at least
+one specification attribute is considered to “have a contract” and any
+absent specification type defaults to its most general interpretation
+(true). All functions with not a single specification attribute are
+considered “not to have a contract” and are ineligible for use as the target
+of a proof_for_contract of
+stub_verified attribute.
Contract are used both to verify function behavior and to leverage the +verification result as a sound abstraction.
+Verifying function behavior currently requires the designation of at least
+one checking harness with the
+proof_for_contract attribute. A harness may
+only have one proof_for_contract attribute and it may not also have a
+proof attribute.
The checking harness is expected to set up the arguments that foo should
+be called with and initialized any static mut globals that are reachable.
+All of these should be initialized to as general value as possible, usually
+achieved using kani::any. The harness must call e.g. foo at least once
+and if foo has type parameters, only one instantiation of those parameters
+is admissible. Violating either results in a compile error.
If any inputs have special invariants you can use kani::assume to
+enforce them but this may introduce unsoundness. In general all restrictions
+on input parameters should be part of the requires
+clause of the function contract.
Once the contract has been verified it may be used as a verified stub. For
+this the stub_verified attribute is used.
+stub_verified is a harness attribute, like
+unwind, meaning it is used on functions that are
+annotated with proof. It may also be used on a
+proof_for_contract proof.
Unlike proof_for_contract multiple stub_verified attributes are allowed
+on the same proof harness though they must target different functions.
Function contracts by default use inductive verification to efficiently +verify recursive functions. In inductive verification a recursive function +is executed once and every recursive call instead uses the contract +replacement. In this way many recursive calls can be checked with a +single verification pass.
+The downside of inductive verification is that the return value of a
+contracted function must implement kani::Arbitrary. Due to restrictions to
+code generation in proc macros, the contract macros cannot determine reliably
+in all cases whether a given function with a contract is recursive. As a
+result it conservatively sets up inductive verification for every function
+and requires the kani::Arbitrary constraint for contract checks.
If you feel strongly about this issue you can join the discussion on issue +#2823 to enable +opt-out of inductive verification.
+The modifies attribute is used to describe which
+locations in memory a function may assign to. The attribute contains a comma
+separated series of expressions that reference the function arguments.
+Syntactically any expression is permissible, though it may not perform side
+effects (I/O, mutation) or panic. As an example consider this super simple
+function:
#[kani::modifies(ptr, my_box.as_ref())]
+fn a_function(ptr: &mut u32, my_box: &mut Box<u32>) {
+ *ptr = 80;
+ *my_box.as_mut() = 90;
+}Because the function performs an observable side-effect (setting both the
+value behind the pointer and the value pointed-to by the box) we need to
+provide a modifies attribute. Otherwise Kani will reject a contract on
+this function.
An expression used in a modifies clause must return a pointer to the
+location that you would like to allow to be modified. This can be any basic
+Rust pointer type (&T, &mut T, *const T or *mut T). In addition T
+must implement Arbitrary. This is used to assign
+kani::any() to the location when the function is used in a stub_verified.
stub_verified(TARGET) is a harness attribute (to be used on
+proof or proof_for_contract
+function) that replaces all occurrences of TARGET reachable from this
+harness with a stub generated from the contract on TARGET.pub fn any<T: Arbitrary>() -> TThis creates an symbolic valid value of type T. You can assign the return value of this
+function to a variable that you want to make symbolic.
In the snippet below, we are verifying the behavior of the function fn_under_verification
+under all possible NonZeroU8 input values, i.e., all possible u8 values except zero.
let inputA = kani::any::<std::num::NonZeroU8>();
+fn_under_verification(inputA);Note: This is a safe construct and can only be used with types that implement the Arbitrary
+trait. The Arbitrary trait is used to build a symbolic value that represents all possible
+valid values for type T.
pub fn any_where<T: Arbitrary, F: FnOnce(&T) -> bool>(f: F) -> TThis creates a symbolic valid value of type T.
+The value is constrained to be a value accepted by the predicate passed to the filter.
+You can assign the return value of this function to a variable that you want to make symbolic.
In the snippet below, we are verifying the behavior of the function fn_under_verification
+under all possible u8 input values between 0 and 12.
let inputA: u8 = kani::any_where(|x| *x < 12);
+fn_under_verification(inputA);Note: This is a safe construct and can only be used with types that implement the Arbitrary
+trait. The Arbitrary trait is used to build a symbolic value that represents all possible
+valid values for type T.
pub fn assume(cond: bool)Creates an assumption that will be valid after this statement run. Note that the assumption +will only be applied for paths that follow the assumption. If the assumption doesn’t hold, the +program will exit successfully.
+The code snippet below should never panic.
+ +let i : i32 = kani::any();
+kani::assume(i > 10);
+if i < 0 {
+ panic!("This will never panic");
+}The following code may panic though:
+ +let i : i32 = kani::any();
+assert!(i < 0, "This may panic and verification should fail.");
+kani::assume(i > 10);pub const fn cover(_cond: bool, _msg: &'static str)Creates a cover property with the specified condition and message.
+kani::cover(slice.len() == 0, "The slice may have a length of 0");A cover property checks if there is at least one execution that satisfies +the specified condition at the location in which the function is called.
+Cover properties are reported as:
+This function is called by the cover! macro. The macro is more
+convenient to use.
pub enum SchedulingAssumption {
+ CanAssumeRunning,
+ CannotAssumeRunning,
+}Indicates to the scheduler whether it can kani::assume that the returned task is running.
This is useful if the task was picked nondeterministically using kani::any().
+For more information, see SchedulingStrategy.
pub fn block_on<T>(fut: impl Future<Output = T>) -> TA very simple executor: it polls the future in a busy loop until completion
+This is intended as a drop-in replacement for futures::block_on, which Kani cannot handle.
+Whereas a clever executor like block_on in futures or tokio would interact with the OS scheduler
+to be woken up when a resource becomes available, this is not supported by Kani.
+As a consequence, this function completely ignores the waker infrastructure and just polls the given future in a busy loop.
Note that spawn is not supported with this function. Use block_on_with_spawn if you need it.
pub fn block_on_with_spawn<F: Future<Output = ()> + Sync + 'static>(
+ fut: F,
+ scheduling_plan: impl SchedulingStrategy
+)Polls the given future and the tasks it may spawn until all of them complete
+Contrary to block_on, this allows spawning other futures
pub fn spawn<F: Future<Output = ()> + Sync + 'static>(fut: F) -> JoinHandle ⓘSpawns a task on the current global executor (which is set by block_on_with_spawn)
This function can only be called inside a future passed to block_on_with_spawn.
This module contains functions to work with futures (and async/.await) in Kani.
+kani::assume that the returned task is running.block_on_with_spawn)pub struct JoinHandle { /* private fields */ }Result of spawning a task.
+If you .await a JoinHandle, this will wait for the spawned task to complete.
pub struct RoundRobin { /* private fields */ }Keeps cycling through the tasks in a deterministic order
+pub trait SchedulingStrategy {
+ // Required method
+ fn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption);
+}Trait that determines the possible sequence of tasks scheduling for a harness.
+If your harness spawns several tasks, Kani’s scheduler has to decide in what order to poll them. +This order may depend on the needs of your verification goal. +For example, you sometimes may wish to verify all possible schedulings, i.e. a nondeterministic scheduling strategy.
+Nondeterministic scheduling strategies can be very slow to verify because they require Kani to check a large number of permutations of tasks.
+So if you want to verify a harness that uses spawn, but don’t care about concurrency issues, you can simply use a deterministic scheduling strategy,
+such as RoundRobin, which polls each task in turn.
Finally, you have the option of providing your own scheduling strategy by implementing this trait. +This can be useful, for example, if you want to verify that things work correctly for a very specific task ordering.
+Picks the next task to be scheduled whenever the scheduler needs to pick a task to run next, and whether it can be assumed that the picked task is still running
+Tasks are numbered 0..num_tasks.
+For example, if pick_task(4) returns (2, CanAssumeRunning) than it picked the task with index 2 and allows Kani to assume that this task is still running.
+This is useful if the task is chosen nondeterministicall (kani::any()) and allows the verifier to discard useless execution branches (such as polling a completed task again).
As a rule of thumb:
+if the scheduling strategy picks the next task nondeterministically (using kani::any()), return CanAssumeRunning, otherwise CannotAssumeRunning.
+When returning CanAssumeRunning, the scheduler will then assume that the picked task is still running, which cuts off “useless” paths where a completed task is polled again.
+It is even necessary to make things terminate if nondeterminism is involved:
+if we pick the task nondeterministically, and don’t have the restriction to still running tasks, we could poll the same task over and over again.
However, for most deterministic scheduling strategies, e.g. the round robin scheduling strategy, assuming that the picked task is still running is generally not possible
+because if that task has ended, we are saying assume(false) and the verification effectively stops (which is undesirable, of course).
+In such cases, return CannotAssumeRunning instead.
pub use arbitrary::Arbitrary;pub use futures::block_on;pub use futures::block_on_with_spawn;pub use futures::spawn;pub use futures::yield_now;pub use futures::RoundRobin;kani::Arbitrary. Tuples of size up to 12 are supported in this
+file.implies!(premise => conclusion) means that if the premise is true, so
+must be the conclusion.T. You can assign the return value of this
+function to a variable that you want to make symbolic.T.
+The value is constrained to be a value accepted by the predicate passed to the filter.
+You can assign the return value of this function to a variable that you want to make symbolic.concrete_playback for type checking during verification mode.stub_verified(TARGET) is a harness attribute (to be used on
+proof or proof_for_contract
+function) that replaces all occurrences of TARGET reachable from this
+harness with a stub generated from the contract on TARGET.#[kani::unwind(arg)] can only be called alongside #[kani::proof].
+arg - Takes in a integer value (u32) that represents the unwind value for the harness.#[derive(Arbitrary)] macro.Redirecting to macro.cover.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.cover.html b/crates/doc/kani/macro.cover.html new file mode 100644 index 000000000000..c92e39249f1a --- /dev/null +++ b/crates/doc/kani/macro.cover.html @@ -0,0 +1,28 @@ +macro_rules! cover { + () => { ... }; + ($cond:expr $(,)?) => { ... }; + ($cond:expr, $msg:literal) => { ... }; +}
A macro to check if a condition is satisfiable at a specific location in the +code.
+let mut set: BTreeSet<i32> = BTreeSet::new();
+set.insert(kani::any());
+set.insert(kani::any());
+// check if the set can end up with a single element (if both elements
+// inserted were the same)
+kani::cover!(set.len() == 1);The macro can also be called without any arguments to check if a location is +reachable.
+match e {
+ MyEnum::A => { /* .. */ }
+ MyEnum::B => {
+ // make sure the `MyEnum::B` variant is possible
+ kani::cover!();
+ // ..
+ }
+}A custom message can also be passed to the macro.
+kani::cover!(x > y, "x can be greater than y")Redirecting to macro.implies.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.implies.html b/crates/doc/kani/macro.implies.html new file mode 100644 index 000000000000..807a26bffaf5 --- /dev/null +++ b/crates/doc/kani/macro.implies.html @@ -0,0 +1,7 @@ +macro_rules! implies { + ($premise:expr => $conclusion:expr) => { ... }; +}
implies!(premise => conclusion) means that if the premise is true, so
+must be the conclusion.
This simply expands to !premise || conclusion and is intended to make checks more readable,
+as the concept of an implication is more natural to think about than its expansion.
pub fn assert_valid_ptr<T>(ptr: *const T) -> boolAssert that the pointer is valid for access according to crate::mem conditions 1, 2 and 3.
+Note that an unaligned pointer is still considered valid.
+TODO: Kani should automatically add those checks when a de-reference happens. +https://github.com/model-checking/kani/issues/2975
+This function will either panic or return true. This is to make it easier to use it in
+contracts.
This module contains functions useful for checking unsafe memory access.
+Given the following validity rules provided in the Rust documentation: +https://doc.rust-lang.org/std/ptr/index.html (accessed Feb 6th, 2024)
+NonNull::dangling.read_volatile and write_volatile:
+Volatile accesses cannot be used for inter-thread synchronization.Kani is able to verify #1 and #2 today.
+For #3, we are overly cautious, and Kani will only consider zero-sized pointer access safe if
+the address matches NonNull::<()>::dangling().
+The way Kani tracks provenance is not enough to check if the address was the result of a cast
+from a non-zero integer literal.
pub fn any_slice_of_array<T, const LENGTH: usize>(arr: &[T; LENGTH]) -> &[T]Given an array arr of length LENGTH, this function returns a valid
+slice of arr with non-deterministic start and end points. This is useful
+in situations where one wants to verify that all possible slices of a given
+array satisfy some property.
let arr = [1, 2, 3];
+let slice = kani::slice::any_slice_of_array(&arr);
+foo(slice); // where foo is a function that takes a slice and verifies a property about itpub fn any_slice_of_array_mut<T, const LENGTH: usize>(
+ arr: &mut [T; LENGTH]
+) -> &mut [T]A mutable version of the previous function
+arr of length LENGTH, this function returns a valid
+slice of arr with non-deterministic start and end points. This is useful
+in situations where one wants to verify that all possible slices of a given
+array satisfy some property.T. You can …\nThis creates a symbolic valid value of type T. The value …\nThis module introduces the Arbitrary trait as well as …\nCreates an assertion of the specified condition and …\nCreates an assumption that will be valid after this …\nNOP concrete_playback for type checking during …\nKani implementation of function contracts.\nCreates a cover property with the specified condition and …\nA macro to check if a condition is satisfiable at a …\nAdd a postcondition to this function.\nThis module contains functions to work with futures (and …\nimplies!(premise => conclusion) means that if the premise …\nThis module contains functions useful for checking unsafe …\nDeclaration of an explicit write-set for the annotated …\nMarks a Kani proof harness\nDesignates this function as a harness to check a function …\nSpecifies that a function contains recursion for contract …\nAdd a precondition to this function.\nSpecifies that a proof harness is expected to panic.**\nSelect the SAT solver to use with CBMC for this harness\nSpecify a function/method stub pair to use for proof …\nstub_verified(TARGET) is a harness attribute (to be used on\nSupport for arbitrary tuples where each element implements …\nSet Loop unwind limit for proof harnesses The attribute …\nThis trait should be used to generate symbolic variables …\nAdd a postcondition to this function.\nDeclaration of an explicit write-set for the annotated …\nDesignates this function as a harness to check a function …\nAdd a precondition to this function.\nstub_verified(TARGET) is a harness attribute (to be used on\nResult of spawning a task.\nKeeps cycling through the tasks in a deterministic order\nIndicates to the scheduler whether it can kani::assume …\nTrait that determines the possible sequence of tasks …\nA very simple executor: it polls the future in a busy loop …\nPolls the given future and the tasks it may spawn until …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPicks the next task to be scheduled whenever the scheduler …\nSpawns a task on the current global executor (which is set …\nSuspends execution of the current future, to allow the …\nAssert that the pointer is valid for access according to …\nGiven an array arr of length LENGTH, this function returns …\nA mutable version of the previous function\nGenerates an arbitrary vector whose length is at most …\nGenerates an arbitrary vector that is exactly EXACT_LENGTH …")
\ No newline at end of file
diff --git a/crates/doc/settings.html b/crates/doc/settings.html
new file mode 100644
index 000000000000..1677495c7783
--- /dev/null
+++ b/crates/doc/settings.html
@@ -0,0 +1 @@
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! This module introduces the Arbitrary trait as well as implementation for primitive types and
+//! other std containers.
+
+use std::{
+ marker::{PhantomData, PhantomPinned},
+ num::*,
+};
+
+/// This trait should be used to generate symbolic variables that represent any valid value of
+/// its type.
+pub trait Arbitrary
+where
+ Self: Sized,
+{
+ fn any() -> Self;
+ fn any_array<const MAX_ARRAY_LENGTH: usize>() -> [Self; MAX_ARRAY_LENGTH]
+ // the requirement defined in the where clause must appear on the `impl`'s method `any_array`
+ // but also on the corresponding trait's method
+ where
+ [(); std::mem::size_of::<[Self; MAX_ARRAY_LENGTH]>()]:,
+ {
+ [(); MAX_ARRAY_LENGTH].map(|_| Self::any())
+ }
+}
+
+/// The given type can be represented by an unconstrained symbolic value of size_of::<T>.
+macro_rules! trivial_arbitrary {
+ ( $type: ty ) => {
+ impl Arbitrary for $type {
+ #[inline(always)]
+ fn any() -> Self {
+ // This size_of call does not use generic_const_exprs feature. It's inside a macro, and Self isn't generic.
+ unsafe { crate::any_raw_internal::<Self, { std::mem::size_of::<Self>() }>() }
+ }
+ fn any_array<const MAX_ARRAY_LENGTH: usize>() -> [Self; MAX_ARRAY_LENGTH]
+ where
+ // `generic_const_exprs` requires all potential errors to be reflected in the signature/header.
+ // We must repeat the expression in the header, to make sure that if the body can fail the header will also fail.
+ [(); { std::mem::size_of::<[$type; MAX_ARRAY_LENGTH]>() }]:,
+ {
+ unsafe {
+ crate::any_raw_internal::<
+ [Self; MAX_ARRAY_LENGTH],
+ { std::mem::size_of::<[Self; MAX_ARRAY_LENGTH]>() },
+ >()
+ }
+ }
+ }
+ };
+}
+
+trivial_arbitrary!(u8);
+trivial_arbitrary!(u16);
+trivial_arbitrary!(u32);
+trivial_arbitrary!(u64);
+trivial_arbitrary!(u128);
+trivial_arbitrary!(usize);
+
+trivial_arbitrary!(i8);
+trivial_arbitrary!(i16);
+trivial_arbitrary!(i32);
+trivial_arbitrary!(i64);
+trivial_arbitrary!(i128);
+trivial_arbitrary!(isize);
+
+// We do not constraint floating points values per type spec. Users must add assumptions to their
+// verification code if they want to eliminate NaN, infinite, or subnormal.
+trivial_arbitrary!(f32);
+trivial_arbitrary!(f64);
+
+trivial_arbitrary!(());
+
+impl Arbitrary for bool {
+ #[inline(always)]
+ fn any() -> Self {
+ let byte = u8::any();
+ crate::assume(byte < 2);
+ byte == 1
+ }
+}
+
+/// Validate that a char is not outside the ranges [0x0, 0xD7FF] and [0xE000, 0x10FFFF]
+/// Ref: <https://doc.rust-lang.org/stable/nomicon/what-unsafe-does.html>
+impl Arbitrary for char {
+ #[inline(always)]
+ fn any() -> Self {
+ // Generate an arbitrary u32 and constrain it to make it a valid representation of char.
+ let val = u32::any();
+ crate::assume(val <= 0xD7FF || (0xE000..=0x10FFFF).contains(&val));
+ unsafe { char::from_u32_unchecked(val) }
+ }
+}
+
+macro_rules! nonzero_arbitrary {
+ ( $type: ty, $base: ty ) => {
+ impl Arbitrary for $type {
+ #[inline(always)]
+ fn any() -> Self {
+ let val = <$base>::any();
+ crate::assume(val != 0);
+ unsafe { <$type>::new_unchecked(val) }
+ }
+ }
+ };
+}
+
+nonzero_arbitrary!(NonZeroU8, u8);
+nonzero_arbitrary!(NonZeroU16, u16);
+nonzero_arbitrary!(NonZeroU32, u32);
+nonzero_arbitrary!(NonZeroU64, u64);
+nonzero_arbitrary!(NonZeroU128, u128);
+nonzero_arbitrary!(NonZeroUsize, usize);
+
+nonzero_arbitrary!(NonZeroI8, i8);
+nonzero_arbitrary!(NonZeroI16, i16);
+nonzero_arbitrary!(NonZeroI32, i32);
+nonzero_arbitrary!(NonZeroI64, i64);
+nonzero_arbitrary!(NonZeroI128, i128);
+nonzero_arbitrary!(NonZeroIsize, isize);
+
+impl<T, const N: usize> Arbitrary for [T; N]
+where
+ T: Arbitrary,
+ [(); std::mem::size_of::<[T; N]>()]:,
+{
+ fn any() -> Self {
+ T::any_array()
+ }
+}
+
+impl<T> Arbitrary for Option<T>
+where
+ T: Arbitrary,
+{
+ fn any() -> Self {
+ if bool::any() { Some(T::any()) } else { None }
+ }
+}
+
+impl<T, E> Arbitrary for Result<T, E>
+where
+ T: Arbitrary,
+ E: Arbitrary,
+{
+ fn any() -> Self {
+ if bool::any() { Ok(T::any()) } else { Err(E::any()) }
+ }
+}
+
+impl<T: ?Sized> Arbitrary for std::marker::PhantomData<T> {
+ fn any() -> Self {
+ PhantomData
+ }
+}
+
+impl Arbitrary for std::marker::PhantomPinned {
+ fn any() -> Self {
+ PhantomPinned
+ }
+}
+
+impl<T> Arbitrary for std::boxed::Box<T>
+where
+ T: Arbitrary,
+{
+ fn any() -> Self {
+ Box::new(T::any())
+ }
+}
+
+impl Arbitrary for std::time::Duration {
+ fn any() -> Self {
+ const NANOS_PER_SEC: u32 = 1_000_000_000;
+ let nanos = u32::any();
+ crate::assume(nanos < NANOS_PER_SEC);
+ std::time::Duration::new(u64::any(), nanos)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! Kani implementation of function contracts.
+//!
+//! Function contracts are still under development. Using the APIs therefore
+//! requires the unstable `-Zfunction-contracts` flag to be passed. You can join
+//! the discussion on contract design by reading our
+//! [RFC](https://model-checking.github.io/kani/rfc/rfcs/0009-function-contracts.html)
+//! and [commenting on the tracking
+//! issue](https://github.com/model-checking/kani/issues/2652).
+//!
+//! The function contract API is expressed as proc-macro attributes, and there
+//! are two parts to it.
+//!
+//! 1. [Contract specification attributes](#specification-attributes-overview):
+//! [`requires`][macro@requires] and [`ensures`][macro@ensures].
+//! 2. [Contract use attributes](#contract-use-attributes-overview):
+//! [`proof_for_contract`][macro@proof_for_contract] and
+//! [`stub_verified`][macro@stub_verified].
+//!
+//! ## Step-by-step Guide
+//!
+//! Let us explore using a workflow involving contracts on the example of a
+//! simple division function `my_div`:
+//!
+//! ```
+//! fn my_div(dividend: u32, divisor: u32) -> u32 {
+//! dividend / divisor
+//! }
+//! ```
+//!
+//! With the contract specification attributes we can specify the behavior of
+//! this function declaratively. The [`requires`][macro@requires] attribute
+//! allows us to declare constraints on what constitutes valid inputs to our
+//! function. In this case we would want to disallow a divisor that is `0`.
+//!
+//! ```ignore
+//! #[requires(divisor != 0)]
+//! ```
+//!
+//! This is called a precondition, because it is enforced before (pre-) the
+//! function call. As you can see attribute has access to the functions
+//! arguments. The condition itself is just regular Rust code. You can use any
+//! Rust code, including calling functions and methods. However you may not
+//! perform I/O (like [`println!`]) or mutate memory (like [`Vec::push`]).
+//!
+//! The [`ensures`][macro@ensures] attribute on the other hand lets us describe
+//! the output value in terms of the inputs. You may be as (im)precise as you
+//! like in the [`ensures`][macro@ensures] clause, depending on your needs. One
+//! approximation of the result of division for instance could be this:
+//!
+//! ```
+//! #[ensures(result <= dividend)]
+//! ```
+//!
+//! This is called a postcondition and it also has access to the arguments and
+//! is expressed in regular Rust code. The same restrictions apply as did for
+//! [`requires`][macro@requires]. In addition to the arguments the postcondition
+//! also has access to the value returned from the function in a variable called
+//! `result`.
+//!
+//! You may combine as many [`requires`][macro@requires] and
+//! [`ensures`][macro@ensures] attributes on a single function as you please.
+//! They all get enforced (as if their conditions were `&&`ed together) and the
+//! order does not matter. In our example putting them together looks like this:
+//!
+//! ```
+//! #[kani::requires(divisor != 0)]
+//! #[kani::ensures(result <= dividend)]
+//! fn my_div(dividend: u32, divisor: u32) -> u32 {
+//! dividend / divisor
+//! }
+//! ```
+//!
+//! Once we are finished specifying our contract we can ask Kani to check it's
+//! validity. For this we need to provide a proof harness that exercises the
+//! function. The harness is created like any other, e.g. as a test-like
+//! function with inputs and using `kani::any` to create arbitrary values.
+//! However we do not need to add any assertions or assumptions about the
+//! inputs, Kani will use the pre- and postconditions we have specified for that
+//! and we use the [`proof_for_contract`][macro@proof_for_contract] attribute
+//! instead of [`proof`](crate::proof) and provide it with the path to the
+//! function we want to check.
+//!
+//! ```
+//! #[kani::proof_for_contract(my_div)]
+//! fn my_div_harness() {
+//! my_div(kani::any(), kani::any()) }
+//! ```
+//!
+//! The harness is checked like any other by running `cargo kani` and can be
+//! specifically selected with `--harness my_div_harness`.
+//!
+//! Once we have verified that our contract holds, we can use perhaps it's
+//! coolest feature: verified stubbing. This allows us to use the conditions of
+//! the contract *instead* of it's implementation. This can be very powerful for
+//! expensive implementations (involving loops for instance).
+//!
+//! Verified stubbing is available to any harness via the
+//! [`stub_verified`][macro@stub_verified] harness attribute. We must provide
+//! the attribute with the path to the function to stub, but unlike with
+//! [`stub`](crate::stub) we do not need to provide a function to replace with,
+//! the contract will be used automatically.
+//!
+//! ```
+//! #[kani::proof]
+//! #[kani::stub_verified(my_div)]
+//! fn use_div() {
+//! let v = vec![...];
+//! let some_idx = my_div(v.len() - 1, 3);
+//! v[some_idx];
+//! }
+//! ```
+//!
+//! In this example the contract is sufficient to prove that the element access
+//! in the last line cannot be out-of-bounds.
+//!
+//! ## Specification Attributes Overview
+//!
+//! The basic two specification attributes available for describing
+//! function behavior are [`requires`][macro@requires] for preconditions and
+//! [`ensures`][macro@ensures] for postconditions. Both admit arbitrary Rust
+//! expressions as their bodies which may also reference the function arguments
+//! but must not mutate memory or perform I/O. The postcondition may
+//! additionally reference the return value of the function as the variable
+//! `result`.
+//!
+//! In addition Kani provides the [`modifies`](macro@modifies) attribute. This
+//! works a bit different in that it does not contain conditions but a comma
+//! separated sequence of expressions that evaluate to pointers. This attribute
+//! constrains to which memory locations the function is allowed to write. Each
+//! expression can contain arbitrary Rust syntax, though it may not perform side
+//! effects and it is also currently unsound if the expression can panic. For more
+//! information see the [write sets](#write-sets) section.
+//!
+//! During verified stubbing the return value of a function with a contract is
+//! replaced by a call to `kani::any`. As such the return value must implement
+//! the `kani::Arbitrary` trait.
+//!
+//! In Kani, function contracts are optional. As such a function with at least
+//! one specification attribute is considered to "have a contract" and any
+//! absent specification type defaults to its most general interpretation
+//! (`true`). All functions with not a single specification attribute are
+//! considered "not to have a contract" and are ineligible for use as the target
+//! of a [`proof_for_contract`][macro@proof_for_contract] of
+//! [`stub_verified`][macro@stub_verified] attribute.
+//!
+//! ## Contract Use Attributes Overview
+//!
+//! Contract are used both to verify function behavior and to leverage the
+//! verification result as a sound abstraction.
+//!
+//! Verifying function behavior currently requires the designation of at least
+//! one checking harness with the
+//! [`proof_for_contract`](macro@proof_for_contract) attribute. A harness may
+//! only have one `proof_for_contract` attribute and it may not also have a
+//! `proof` attribute.
+//!
+//! The checking harness is expected to set up the arguments that `foo` should
+//! be called with and initialized any `static mut` globals that are reachable.
+//! All of these should be initialized to as general value as possible, usually
+//! achieved using `kani::any`. The harness must call e.g. `foo` at least once
+//! and if `foo` has type parameters, only one instantiation of those parameters
+//! is admissible. Violating either results in a compile error.
+//!
+//! If any inputs have special invariants you *can* use `kani::assume` to
+//! enforce them but this may introduce unsoundness. In general all restrictions
+//! on input parameters should be part of the [`requires`](macro@requires)
+//! clause of the function contract.
+//!
+//! Once the contract has been verified it may be used as a verified stub. For
+//! this the [`stub_verified`](macro@stub_verified) attribute is used.
+//! `stub_verified` is a harness attribute, like
+//! [`unwind`](macro@crate::unwind), meaning it is used on functions that are
+//! annotated with [`proof`](macro@crate::proof). It may also be used on a
+//! `proof_for_contract` proof.
+//!
+//! Unlike `proof_for_contract` multiple `stub_verified` attributes are allowed
+//! on the same proof harness though they must target different functions.
+//!
+//! ## Inductive Verification
+//!
+//! Function contracts by default use inductive verification to efficiently
+//! verify recursive functions. In inductive verification a recursive function
+//! is executed once and every recursive call instead uses the contract
+//! replacement. In this way many recursive calls can be checked with a
+//! single verification pass.
+//!
+//! The downside of inductive verification is that the return value of a
+//! contracted function must implement `kani::Arbitrary`. Due to restrictions to
+//! code generation in proc macros, the contract macros cannot determine reliably
+//! in all cases whether a given function with a contract is recursive. As a
+//! result it conservatively sets up inductive verification for every function
+//! and requires the `kani::Arbitrary` constraint for contract checks.
+//!
+//! If you feel strongly about this issue you can join the discussion on issue
+//! [#2823](https://github.com/model-checking/kani/issues/2823) to enable
+//! opt-out of inductive verification.
+//!
+//! ## Write Sets
+//!
+//! The [`modifies`](macro@modifies) attribute is used to describe which
+//! locations in memory a function may assign to. The attribute contains a comma
+//! separated series of expressions that reference the function arguments.
+//! Syntactically any expression is permissible, though it may not perform side
+//! effects (I/O, mutation) or panic. As an example consider this super simple
+//! function:
+//!
+//! ```
+//! #[kani::modifies(ptr, my_box.as_ref())]
+//! fn a_function(ptr: &mut u32, my_box: &mut Box<u32>) {
+//! *ptr = 80;
+//! *my_box.as_mut() = 90;
+//! }
+//! ```
+//!
+//! Because the function performs an observable side-effect (setting both the
+//! value behind the pointer and the value pointed-to by the box) we need to
+//! provide a `modifies` attribute. Otherwise Kani will reject a contract on
+//! this function.
+//!
+//! An expression used in a `modifies` clause must return a pointer to the
+//! location that you would like to allow to be modified. This can be any basic
+//! Rust pointer type (`&T`, `&mut T`, `*const T` or `*mut T`). In addition `T`
+//! must implement [`Arbitrary`](super::Arbitrary). This is used to assign
+//! `kani::any()` to the location when the function is used in a `stub_verified`.
+pub use super::{ensures, modifies, proof_for_contract, requires, stub_verified};
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! This module contains functions to work with futures (and async/.await) in Kani.
+
+use std::{
+ future::Future,
+ pin::Pin,
+ task::{Context, RawWaker, RawWakerVTable, Waker},
+};
+
+/// A very simple executor: it polls the future in a busy loop until completion
+///
+/// This is intended as a drop-in replacement for `futures::block_on`, which Kani cannot handle.
+/// Whereas a clever executor like `block_on` in `futures` or `tokio` would interact with the OS scheduler
+/// to be woken up when a resource becomes available, this is not supported by Kani.
+/// As a consequence, this function completely ignores the waker infrastructure and just polls the given future in a busy loop.
+///
+/// Note that [`spawn`] is not supported with this function. Use [`block_on_with_spawn`] if you need it.
+#[crate::unstable(feature = "async-lib", issue = 2559, reason = "experimental async support")]
+pub fn block_on<T>(mut fut: impl Future<Output = T>) -> T {
+ let waker = unsafe { Waker::from_raw(NOOP_RAW_WAKER) };
+ let cx = &mut Context::from_waker(&waker);
+ // SAFETY: we shadow the original binding, so it cannot be accessed again for the rest of the scope.
+ // This is the same as what the pin_mut! macro in the futures crate does.
+ let mut fut = unsafe { Pin::new_unchecked(&mut fut) };
+ loop {
+ match fut.as_mut().poll(cx) {
+ std::task::Poll::Ready(res) => return res,
+ std::task::Poll::Pending => continue,
+ }
+ }
+}
+
+/// A dummy waker, which is needed to call [`Future::poll`]
+const NOOP_RAW_WAKER: RawWaker = {
+ #[inline]
+ unsafe fn clone_waker(_: *const ()) -> RawWaker {
+ NOOP_RAW_WAKER
+ }
+
+ #[inline]
+ unsafe fn noop(_: *const ()) {}
+
+ RawWaker::new(std::ptr::null(), &RawWakerVTable::new(clone_waker, noop, noop, noop))
+};
+
+/// The global executor used by [`spawn`] and [`block_on_with_spawn`] to run tasks.
+static mut GLOBAL_EXECUTOR: Option<Scheduler> = None;
+
+type BoxFuture = Pin<Box<dyn Future<Output = ()> + Sync + 'static>>;
+
+/// Indicates to the scheduler whether it can `kani::assume` that the returned task is running.
+///
+/// This is useful if the task was picked nondeterministically using `kani::any()`.
+/// For more information, see [`SchedulingStrategy`].
+pub enum SchedulingAssumption {
+ CanAssumeRunning,
+ CannotAssumeRunning,
+}
+
+/// Trait that determines the possible sequence of tasks scheduling for a harness.
+///
+/// If your harness spawns several tasks, Kani's scheduler has to decide in what order to poll them.
+/// This order may depend on the needs of your verification goal.
+/// For example, you sometimes may wish to verify all possible schedulings, i.e. a nondeterministic scheduling strategy.
+///
+/// Nondeterministic scheduling strategies can be very slow to verify because they require Kani to check a large number of permutations of tasks.
+/// So if you want to verify a harness that uses `spawn`, but don't care about concurrency issues, you can simply use a deterministic scheduling strategy,
+/// such as [`RoundRobin`], which polls each task in turn.
+///
+/// Finally, you have the option of providing your own scheduling strategy by implementing this trait.
+/// This can be useful, for example, if you want to verify that things work correctly for a very specific task ordering.
+pub trait SchedulingStrategy {
+ /// Picks the next task to be scheduled whenever the scheduler needs to pick a task to run next, and whether it can be assumed that the picked task is still running
+ ///
+ /// Tasks are numbered `0..num_tasks`.
+ /// For example, if pick_task(4) returns (2, CanAssumeRunning) than it picked the task with index 2 and allows Kani to `assume` that this task is still running.
+ /// This is useful if the task is chosen nondeterministicall (`kani::any()`) and allows the verifier to discard useless execution branches (such as polling a completed task again).
+ ///
+ /// As a rule of thumb:
+ /// if the scheduling strategy picks the next task nondeterministically (using `kani::any()`), return CanAssumeRunning, otherwise CannotAssumeRunning.
+ /// When returning `CanAssumeRunning`, the scheduler will then assume that the picked task is still running, which cuts off "useless" paths where a completed task is polled again.
+ /// It is even necessary to make things terminate if nondeterminism is involved:
+ /// if we pick the task nondeterministically, and don't have the restriction to still running tasks, we could poll the same task over and over again.
+ ///
+ /// However, for most deterministic scheduling strategies, e.g. the round robin scheduling strategy, assuming that the picked task is still running is generally not possible
+ /// because if that task has ended, we are saying assume(false) and the verification effectively stops (which is undesirable, of course).
+ /// In such cases, return `CannotAssumeRunning` instead.
+ fn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption);
+}
+
+/// Keeps cycling through the tasks in a deterministic order
+#[derive(Default)]
+pub struct RoundRobin {
+ index: usize,
+}
+
+impl SchedulingStrategy for RoundRobin {
+ #[inline]
+ fn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption) {
+ self.index = (self.index + 1) % num_tasks;
+ (self.index, SchedulingAssumption::CannotAssumeRunning)
+ }
+}
+
+pub(crate) struct Scheduler {
+ tasks: Vec<Option<BoxFuture>>,
+ num_running: usize,
+}
+
+impl Scheduler {
+ /// Creates a scheduler with an empty task list
+ #[inline]
+ pub(crate) const fn new() -> Scheduler {
+ Scheduler { tasks: Vec::new(), num_running: 0 }
+ }
+
+ /// Adds a future to the scheduler's task list, returning a JoinHandle
+ pub(crate) fn spawn<F: Future<Output = ()> + Sync + 'static>(&mut self, fut: F) -> JoinHandle {
+ let index = self.tasks.len();
+ self.tasks.push(Some(Box::pin(fut)));
+ self.num_running += 1;
+ JoinHandle { index }
+ }
+
+ /// Runs the scheduler with the given scheduling plan until all tasks have completed
+ fn run(&mut self, mut scheduling_plan: impl SchedulingStrategy) {
+ let waker = unsafe { Waker::from_raw(NOOP_RAW_WAKER) };
+ let cx = &mut Context::from_waker(&waker);
+ while self.num_running > 0 {
+ let (index, assumption) = scheduling_plan.pick_task(self.tasks.len());
+ let task = &mut self.tasks[index];
+ if let Some(fut) = task.as_mut() {
+ match fut.as_mut().poll(cx) {
+ std::task::Poll::Ready(()) => {
+ self.num_running -= 1;
+ let _prev = task.take();
+ }
+ std::task::Poll::Pending => (),
+ }
+ } else if let SchedulingAssumption::CanAssumeRunning = assumption {
+ crate::assume(false); // useful so that we can assume that a nondeterministically picked task is still running
+ }
+ }
+ }
+
+ /// Polls the given future and the tasks it may spawn until all of them complete
+ fn block_on<F: Future<Output = ()> + Sync + 'static>(
+ &mut self,
+ fut: F,
+ scheduling_plan: impl SchedulingStrategy,
+ ) {
+ self.spawn(fut);
+ self.run(scheduling_plan);
+ }
+}
+
+/// Result of spawning a task.
+///
+/// If you `.await` a JoinHandle, this will wait for the spawned task to complete.
+pub struct JoinHandle {
+ index: usize,
+}
+
+impl Future for JoinHandle {
+ type Output = ();
+
+ fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll<Self::Output> {
+ if unsafe { GLOBAL_EXECUTOR.as_mut().unwrap().tasks[self.index].is_some() } {
+ std::task::Poll::Pending
+ } else {
+ cx.waker().wake_by_ref(); // For completeness. But Kani currently ignores wakers.
+ std::task::Poll::Ready(())
+ }
+ }
+}
+
+/// Spawns a task on the current global executor (which is set by [`block_on_with_spawn`])
+///
+/// This function can only be called inside a future passed to [`block_on_with_spawn`].
+#[crate::unstable(feature = "async-lib", issue = 2559, reason = "experimental async support")]
+pub fn spawn<F: Future<Output = ()> + Sync + 'static>(fut: F) -> JoinHandle {
+ unsafe {
+ if let Some(executor) = GLOBAL_EXECUTOR.as_mut() {
+ executor.spawn(fut)
+ } else {
+ // An explicit panic instead of `.expect(...)` has better location information in Kani's output
+ panic!("`spawn` should only be called within `block_on_with_spawn`")
+ }
+ }
+}
+
+/// Polls the given future and the tasks it may spawn until all of them complete
+///
+/// Contrary to [`block_on`], this allows `spawn`ing other futures
+#[crate::unstable(feature = "async-lib", issue = 2559, reason = "experimental async support")]
+pub fn block_on_with_spawn<F: Future<Output = ()> + Sync + 'static>(
+ fut: F,
+ scheduling_plan: impl SchedulingStrategy,
+) {
+ unsafe {
+ assert!(GLOBAL_EXECUTOR.is_none(), "`block_on_with_spawn` should not be nested");
+ GLOBAL_EXECUTOR = Some(Scheduler::new());
+ GLOBAL_EXECUTOR.as_mut().unwrap().block_on(fut, scheduling_plan);
+ GLOBAL_EXECUTOR = None;
+ }
+}
+
+/// Suspends execution of the current future, to allow the scheduler to poll another future
+///
+/// Specifically, it returns a future that isn't ready until the second time it is polled.
+#[crate::unstable(feature = "async-lib", issue = 2559, reason = "experimental async support")]
+pub fn yield_now() -> impl Future<Output = ()> {
+ struct YieldNow {
+ yielded: bool,
+ }
+
+ impl Future for YieldNow {
+ type Output = ();
+
+ fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll<Self::Output> {
+ if self.yielded {
+ cx.waker().wake_by_ref(); // For completeness. But Kani currently ignores wakers.
+ std::task::Poll::Ready(())
+ } else {
+ self.yielded = true;
+ std::task::Poll::Pending
+ }
+ }
+ }
+
+ YieldNow { yielded: false }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+/// Helper trait for code generation for `modifies` contracts.
+///
+/// We allow the user to provide us with a pointer-like object that we convert as needed.
+#[doc(hidden)]
+pub trait Pointer<'a> {
+ /// Type of the pointed-to data
+ type Inner;
+
+ /// Used for checking assigns contracts where we pass immutable references to the function.
+ ///
+ /// We're using a reference to self here, because the user can use just a plain function
+ /// argument, for instance one of type `&mut _`, in the `modifies` clause which would move it.
+ unsafe fn decouple_lifetime(&self) -> &'a Self::Inner;
+
+ /// used for havocking on replecement of a `modifies` clause.
+ unsafe fn assignable(self) -> &'a mut Self::Inner;
+}
+
+impl<'a, 'b, T> Pointer<'a> for &'b T {
+ type Inner = T;
+ unsafe fn decouple_lifetime(&self) -> &'a Self::Inner {
+ std::mem::transmute(*self)
+ }
+
+ #[allow(clippy::transmute_ptr_to_ref)]
+ unsafe fn assignable(self) -> &'a mut Self::Inner {
+ std::mem::transmute(self as *const T)
+ }
+}
+
+impl<'a, 'b, T> Pointer<'a> for &'b mut T {
+ type Inner = T;
+
+ #[allow(clippy::transmute_ptr_to_ref)]
+ unsafe fn decouple_lifetime(&self) -> &'a Self::Inner {
+ std::mem::transmute::<_, &&'a T>(self)
+ }
+
+ unsafe fn assignable(self) -> &'a mut Self::Inner {
+ std::mem::transmute(self)
+ }
+}
+
+impl<'a, T> Pointer<'a> for *const T {
+ type Inner = T;
+ unsafe fn decouple_lifetime(&self) -> &'a Self::Inner {
+ &**self as &'a T
+ }
+
+ #[allow(clippy::transmute_ptr_to_ref)]
+ unsafe fn assignable(self) -> &'a mut Self::Inner {
+ std::mem::transmute(self)
+ }
+}
+
+impl<'a, T> Pointer<'a> for *mut T {
+ type Inner = T;
+ unsafe fn decouple_lifetime(&self) -> &'a Self::Inner {
+ &**self as &'a T
+ }
+
+ #[allow(clippy::transmute_ptr_to_ref)]
+ unsafe fn assignable(self) -> &'a mut Self::Inner {
+ std::mem::transmute(self)
+ }
+}
+
+/// A way to break the ownerhip rules. Only used by contracts where we can
+/// guarantee it is done safely.
+#[inline(never)]
+#[doc(hidden)]
+#[rustc_diagnostic_item = "KaniUntrackedDeref"]
+pub fn untracked_deref<T>(_: &T) -> T {
+ todo!()
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+// Required so we can use kani_macros attributes.
+#![feature(register_tool)]
+#![register_tool(kanitool)]
+// Used for rustc_diagnostic_item.
+// Note: We could use a kanitool attribute instead.
+#![feature(rustc_attrs)]
+// This is required for the optimized version of `any_array()`
+#![feature(generic_const_exprs)]
+#![allow(incomplete_features)]
+// Used to model simd.
+#![feature(repr_simd)]
+// Features used for tests only.
+#![cfg_attr(test, feature(core_intrinsics, portable_simd))]
+// Required for `rustc_diagnostic_item` and `core_intrinsics`
+#![allow(internal_features)]
+// Required for implementing memory predicates.
+#![feature(ptr_metadata)]
+
+pub mod arbitrary;
+#[cfg(feature = "concrete_playback")]
+mod concrete_playback;
+pub mod futures;
+pub mod mem;
+pub mod slice;
+pub mod tuple;
+pub mod vec;
+
+#[doc(hidden)]
+pub mod internal;
+
+mod models;
+
+pub use arbitrary::Arbitrary;
+#[cfg(feature = "concrete_playback")]
+pub use concrete_playback::concrete_playback_run;
+
+#[cfg(not(feature = "concrete_playback"))]
+/// NOP `concrete_playback` for type checking during verification mode.
+pub fn concrete_playback_run<F: Fn()>(_: Vec<Vec<u8>>, _: F) {
+ unreachable!("Concrete playback does not work during verification")
+}
+pub use futures::{block_on, block_on_with_spawn, spawn, yield_now, RoundRobin};
+
+/// Creates an assumption that will be valid after this statement run. Note that the assumption
+/// will only be applied for paths that follow the assumption. If the assumption doesn't hold, the
+/// program will exit successfully.
+///
+/// # Example:
+///
+/// The code snippet below should never panic.
+///
+/// ```rust
+/// let i : i32 = kani::any();
+/// kani::assume(i > 10);
+/// if i < 0 {
+/// panic!("This will never panic");
+/// }
+/// ```
+///
+/// The following code may panic though:
+///
+/// ```rust
+/// let i : i32 = kani::any();
+/// assert!(i < 0, "This may panic and verification should fail.");
+/// kani::assume(i > 10);
+/// ```
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniAssume"]
+#[cfg(not(feature = "concrete_playback"))]
+pub fn assume(cond: bool) {
+ let _ = cond;
+}
+
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniAssume"]
+#[cfg(feature = "concrete_playback")]
+pub fn assume(cond: bool) {
+ assert!(cond, "`kani::assume` should always hold");
+}
+
+/// `implies!(premise => conclusion)` means that if the `premise` is true, so
+/// must be the `conclusion`.
+///
+/// This simply expands to `!premise || conclusion` and is intended to make checks more readable,
+/// as the concept of an implication is more natural to think about than its expansion.
+#[macro_export]
+macro_rules! implies {
+ ($premise:expr => $conclusion:expr) => {
+ !($premise) || ($conclusion)
+ };
+}
+
+/// Creates an assertion of the specified condition and message.
+///
+/// # Example:
+///
+/// ```rust
+/// let x: bool = kani::any();
+/// let y = !x;
+/// kani::assert(x || y, "ORing a boolean variable with its negation must be true")
+/// ```
+#[cfg(not(feature = "concrete_playback"))]
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniAssert"]
+pub const fn assert(cond: bool, msg: &'static str) {
+ let _ = cond;
+ let _ = msg;
+}
+
+#[cfg(feature = "concrete_playback")]
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniAssert"]
+pub const fn assert(cond: bool, msg: &'static str) {
+ assert!(cond, "{}", msg);
+}
+
+/// Creates a cover property with the specified condition and message.
+///
+/// # Example:
+///
+/// ```rust
+/// kani::cover(slice.len() == 0, "The slice may have a length of 0");
+/// ```
+///
+/// A cover property checks if there is at least one execution that satisfies
+/// the specified condition at the location in which the function is called.
+///
+/// Cover properties are reported as:
+/// - SATISFIED: if Kani found an execution that satisfies the condition
+/// - UNSATISFIABLE: if Kani proved that the condition cannot be satisfied
+/// - UNREACHABLE: if Kani proved that the cover property itself is unreachable (i.e. it is vacuously UNSATISFIABLE)
+///
+/// This function is called by the [`cover!`] macro. The macro is more
+/// convenient to use.
+///
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniCover"]
+pub const fn cover(_cond: bool, _msg: &'static str) {}
+
+/// This creates an symbolic *valid* value of type `T`. You can assign the return value of this
+/// function to a variable that you want to make symbolic.
+///
+/// # Example:
+///
+/// In the snippet below, we are verifying the behavior of the function `fn_under_verification`
+/// under all possible `NonZeroU8` input values, i.e., all possible `u8` values except zero.
+///
+/// ```rust
+/// let inputA = kani::any::<std::num::NonZeroU8>();
+/// fn_under_verification(inputA);
+/// ```
+///
+/// Note: This is a safe construct and can only be used with types that implement the `Arbitrary`
+/// trait. The Arbitrary trait is used to build a symbolic value that represents all possible
+/// valid values for type `T`.
+#[rustc_diagnostic_item = "KaniAny"]
+#[inline(always)]
+pub fn any<T: Arbitrary>() -> T {
+ T::any()
+}
+
+/// This function is only used for function contract instrumentation.
+/// It behaves exaclty like `kani::any<T>()`, except it will check for the trait bounds
+/// at compilation time. It allows us to avoid type checking errors while using function
+/// contracts only for verification.
+#[rustc_diagnostic_item = "KaniAnyModifies"]
+#[inline(never)]
+#[doc(hidden)]
+pub fn any_modifies<T>() -> T {
+ // This function should not be reacheable.
+ // Users must include `#[kani::recursion]` in any function contracts for recursive functions;
+ // otherwise, this might not be properly instantiate. We mark this as unreachable to make
+ // sure Kani doesn't report any false positives.
+ unreachable!()
+}
+
+/// This creates a symbolic *valid* value of type `T`.
+/// The value is constrained to be a value accepted by the predicate passed to the filter.
+/// You can assign the return value of this function to a variable that you want to make symbolic.
+///
+/// # Example:
+///
+/// In the snippet below, we are verifying the behavior of the function `fn_under_verification`
+/// under all possible `u8` input values between 0 and 12.
+///
+/// ```rust
+/// let inputA: u8 = kani::any_where(|x| *x < 12);
+/// fn_under_verification(inputA);
+/// ```
+///
+/// Note: This is a safe construct and can only be used with types that implement the `Arbitrary`
+/// trait. The Arbitrary trait is used to build a symbolic value that represents all possible
+/// valid values for type `T`.
+#[inline(always)]
+pub fn any_where<T: Arbitrary, F: FnOnce(&T) -> bool>(f: F) -> T {
+ let result = T::any();
+ assume(f(&result));
+ result
+}
+
+/// This function creates a symbolic value of type `T`. This may result in an invalid value.
+///
+/// # Safety
+///
+/// This function is unsafe and it may represent invalid `T` values which can lead to many
+/// undesirable undefined behaviors. Because of that, this function can only be used
+/// internally when we can guarantee that the type T has no restriction regarding its bit level
+/// representation.
+///
+/// This function is also used to find concrete values in the CBMC output trace
+/// and return those concrete values in concrete playback mode.
+///
+/// Note that SIZE_T must be equal the size of type T in bytes.
+#[inline(never)]
+#[cfg(not(feature = "concrete_playback"))]
+pub(crate) unsafe fn any_raw_internal<T, const SIZE_T: usize>() -> T {
+ any_raw_inner::<T>()
+}
+
+#[inline(never)]
+#[cfg(feature = "concrete_playback")]
+pub(crate) unsafe fn any_raw_internal<T, const SIZE_T: usize>() -> T {
+ concrete_playback::any_raw_internal::<T, SIZE_T>()
+}
+
+/// This low-level function returns nondet bytes of size T.
+#[rustc_diagnostic_item = "KaniAnyRaw"]
+#[inline(never)]
+#[allow(dead_code)]
+fn any_raw_inner<T>() -> T {
+ kani_intrinsic()
+}
+
+/// Function used to generate panic with a static message as this is the only one currently
+/// supported by Kani display.
+///
+/// During verification this will get replaced by `assert(false)`. For concrete executions, we just
+/// invoke the regular `std::panic!()` function. This function is used by our standard library
+/// overrides, but not the other way around.
+#[inline(never)]
+#[rustc_diagnostic_item = "KaniPanic"]
+#[doc(hidden)]
+pub const fn panic(message: &'static str) -> ! {
+ panic!("{}", message)
+}
+
+/// An empty body that can be used to define Kani intrinsic functions.
+///
+/// A Kani intrinsic is a function that is interpreted by Kani compiler.
+/// While we could use `unreachable!()` or `panic!()` as the body of a kani intrinsic
+/// function, both cause Kani to produce a warning since we don't support caller location.
+/// (see https://github.com/model-checking/kani/issues/2010).
+///
+/// This function is dead, since its caller is always handled via a hook anyway,
+/// so we just need to put a body that rustc does not complain about.
+/// An infinite loop works out nicely.
+fn kani_intrinsic<T>() -> T {
+ #[allow(clippy::empty_loop)]
+ loop {}
+}
+/// A macro to check if a condition is satisfiable at a specific location in the
+/// code.
+///
+/// # Example 1:
+///
+/// ```rust
+/// let mut set: BTreeSet<i32> = BTreeSet::new();
+/// set.insert(kani::any());
+/// set.insert(kani::any());
+/// // check if the set can end up with a single element (if both elements
+/// // inserted were the same)
+/// kani::cover!(set.len() == 1);
+/// ```
+/// The macro can also be called without any arguments to check if a location is
+/// reachable.
+///
+/// # Example 2:
+///
+/// ```rust
+/// match e {
+/// MyEnum::A => { /* .. */ }
+/// MyEnum::B => {
+/// // make sure the `MyEnum::B` variant is possible
+/// kani::cover!();
+/// // ..
+/// }
+/// }
+/// ```
+///
+/// A custom message can also be passed to the macro.
+///
+/// # Example 3:
+///
+/// ```rust
+/// kani::cover!(x > y, "x can be greater than y")
+/// ```
+#[macro_export]
+macro_rules! cover {
+ () => {
+ kani::cover(true, "cover location");
+ };
+ ($cond:expr $(,)?) => {
+ kani::cover($cond, concat!("cover condition: ", stringify!($cond)));
+ };
+ ($cond:expr, $msg:literal) => {
+ kani::cover($cond, $msg);
+ };
+}
+
+// Used to bind `core::assert` to a different name to avoid possible name conflicts if a
+// crate uses `extern crate std as core`. See
+// https://github.com/model-checking/kani/issues/1949 and https://github.com/model-checking/kani/issues/2187
+#[doc(hidden)]
+#[cfg(not(feature = "concrete_playback"))]
+pub use core::assert as __kani__workaround_core_assert;
+
+// Kani proc macros must be in a separate crate
+pub use kani_macros::*;
+
+pub mod contracts;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+//! This module contains functions useful for checking unsafe memory access.
+//!
+//! Given the following validity rules provided in the Rust documentation:
+//! <https://doc.rust-lang.org/std/ptr/index.html> (accessed Feb 6th, 2024)
+//!
+//! 1. A null pointer is never valid, not even for accesses of size zero.
+//! 2. For a pointer to be valid, it is necessary, but not always sufficient, that the pointer
+//! be dereferenceable: the memory range of the given size starting at the pointer must all be
+//! within the bounds of a single allocated object. Note that in Rust, every (stack-allocated)
+//! variable is considered a separate allocated object.
+//! Even for operations of size zero, the pointer must not be pointing to deallocated memory,
+//! i.e., deallocation makes pointers invalid even for zero-sized operations.
+//! 3. However, casting any non-zero integer literal to a pointer is valid for zero-sized
+//! accesses, even if some memory happens to exist at that address and gets deallocated.
+//! This corresponds to writing your own allocator: allocating zero-sized objects is not very
+//! hard. The canonical way to obtain a pointer that is valid for zero-sized accesses is
+//! `NonNull::dangling`.
+//! 4. All accesses performed by functions in this module are non-atomic in the sense of atomic
+//! operations used to synchronize between threads.
+//! This means it is undefined behavior to perform two concurrent accesses to the same location
+//! from different threads unless both accesses only read from memory.
+//! Notice that this explicitly includes `read_volatile` and `write_volatile`:
+//! Volatile accesses cannot be used for inter-thread synchronization.
+//! 5. The result of casting a reference to a pointer is valid for as long as the underlying
+//! object is live and no reference (just raw pointers) is used to access the same memory.
+//! That is, reference and pointer accesses cannot be interleaved.
+//!
+//! Kani is able to verify #1 and #2 today.
+//!
+//! For #3, we are overly cautious, and Kani will only consider zero-sized pointer access safe if
+//! the address matches `NonNull::<()>::dangling()`.
+//! The way Kani tracks provenance is not enough to check if the address was the result of a cast
+//! from a non-zero integer literal.
+
+use crate::kani_intrinsic;
+use crate::mem::private::Internal;
+use std::mem::{align_of, size_of};
+use std::ptr::{DynMetadata, NonNull, Pointee};
+
+/// Assert that the pointer is valid for access according to [crate::mem] conditions 1, 2 and 3.
+///
+/// Note that an unaligned pointer is still considered valid.
+///
+/// TODO: Kani should automatically add those checks when a de-reference happens.
+/// <https://github.com/model-checking/kani/issues/2975>
+///
+/// This function will either panic or return `true`. This is to make it easier to use it in
+/// contracts.
+#[crate::unstable(
+ feature = "mem-predicates",
+ issue = 2690,
+ reason = "experimental memory predicate API"
+)]
+pub fn assert_valid_ptr<T>(ptr: *const T) -> bool
+where
+ T: ?Sized,
+ <T as Pointee>::Metadata: PtrProperties<T>,
+{
+ crate::assert(!ptr.is_null(), "Expected valid pointer, but found `null`");
+
+ let (thin_ptr, metadata) = ptr.to_raw_parts();
+ let sz = metadata.pointee_size(Internal);
+ if sz == 0 {
+ true // ZST pointers are always valid
+ } else {
+ // Note that this branch can't be tested in concrete execution as `is_read_ok` needs to be
+ // stubbed.
+ crate::assert(
+ is_read_ok(thin_ptr, sz),
+ "Expected valid pointer, but found dangling pointer",
+ );
+ true
+ }
+}
+
+mod private {
+ /// Define like this to restrict usage of PtrProperties functions outside Kani.
+ #[derive(Copy, Clone)]
+ pub struct Internal;
+}
+
+/// Trait that allow us to extract information from pointers without de-referencing them.
+#[doc(hidden)]
+pub trait PtrProperties<T: ?Sized> {
+ fn pointee_size(&self, _: Internal) -> usize;
+
+ fn min_alignment(&self, _: Internal) -> usize;
+
+ fn dangling(&self, _: Internal) -> *const ();
+}
+
+/// Get the information for sized types (they don't have metadata).
+impl<T> PtrProperties<T> for () {
+ fn pointee_size(&self, _: Internal) -> usize {
+ size_of::<T>()
+ }
+
+ fn min_alignment(&self, _: Internal) -> usize {
+ align_of::<T>()
+ }
+
+ fn dangling(&self, _: Internal) -> *const () {
+ NonNull::<T>::dangling().as_ptr() as *const _
+ }
+}
+
+/// Get the information from the str metadata.
+impl PtrProperties<str> for usize {
+ #[inline(always)]
+ fn pointee_size(&self, _: Internal) -> usize {
+ *self
+ }
+
+ /// String slices are a UTF-8 representation of characters that have the same layout as slices
+ /// of type [u8].
+ /// <https://doc.rust-lang.org/reference/type-layout.html#str-layout>
+ fn min_alignment(&self, _: Internal) -> usize {
+ align_of::<u8>()
+ }
+
+ fn dangling(&self, _: Internal) -> *const () {
+ NonNull::<u8>::dangling().as_ptr() as _
+ }
+}
+
+/// Get the information from the slice metadata.
+impl<T> PtrProperties<[T]> for usize {
+ fn pointee_size(&self, _: Internal) -> usize {
+ *self * size_of::<T>()
+ }
+
+ fn min_alignment(&self, _: Internal) -> usize {
+ align_of::<T>()
+ }
+
+ fn dangling(&self, _: Internal) -> *const () {
+ NonNull::<T>::dangling().as_ptr() as _
+ }
+}
+
+/// Get the information from the vtable.
+impl<T> PtrProperties<T> for DynMetadata<T>
+where
+ T: ?Sized,
+{
+ fn pointee_size(&self, _: Internal) -> usize {
+ self.size_of()
+ }
+
+ fn min_alignment(&self, _: Internal) -> usize {
+ self.align_of()
+ }
+
+ fn dangling(&self, _: Internal) -> *const () {
+ NonNull::<&T>::dangling().as_ptr() as _
+ }
+}
+
+/// Check if the pointer `_ptr` contains an allocated address of size equal or greater than `_size`.
+///
+/// This function should only be called to ensure a pointer is valid. The opposite isn't true.
+/// I.e.: This function always returns `true` if the pointer is valid.
+/// Otherwise, it returns non-det boolean.
+#[rustc_diagnostic_item = "KaniIsReadOk"]
+#[inline(never)]
+fn is_read_ok(_ptr: *const (), _size: usize) -> bool {
+ kani_intrinsic()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{assert_valid_ptr, PtrProperties};
+ use crate::mem::private::Internal;
+ use std::fmt::Debug;
+ use std::intrinsics::size_of;
+ use std::mem::{align_of, align_of_val, size_of_val};
+ use std::ptr;
+ use std::ptr::{NonNull, Pointee};
+
+ fn size_of_t<T>(ptr: *const T) -> usize
+ where
+ T: ?Sized,
+ <T as Pointee>::Metadata: PtrProperties<T>,
+ {
+ let (_, metadata) = ptr.to_raw_parts();
+ metadata.pointee_size(Internal)
+ }
+
+ fn align_of_t<T>(ptr: *const T) -> usize
+ where
+ T: ?Sized,
+ <T as Pointee>::Metadata: PtrProperties<T>,
+ {
+ let (_, metadata) = ptr.to_raw_parts();
+ metadata.min_alignment(Internal)
+ }
+
+ #[test]
+ fn test_size_of() {
+ assert_eq!(size_of_t("hi"), size_of_val("hi"));
+ assert_eq!(size_of_t(&0u8), size_of_val(&0u8));
+ assert_eq!(size_of_t(&0u8 as *const dyn std::fmt::Display), size_of_val(&0u8));
+ assert_eq!(size_of_t(&[0u8, 1u8] as &[u8]), size_of_val(&[0u8, 1u8]));
+ assert_eq!(size_of_t(&[] as &[u8]), size_of_val::<[u8; 0]>(&[]));
+ assert_eq!(
+ size_of_t(NonNull::<u32>::dangling().as_ptr() as *const dyn std::fmt::Display),
+ size_of::<u32>()
+ );
+ }
+
+ #[test]
+ fn test_alignment() {
+ assert_eq!(align_of_t("hi"), align_of_val("hi"));
+ assert_eq!(align_of_t(&0u8), align_of_val(&0u8));
+ assert_eq!(align_of_t(&0u32 as *const dyn std::fmt::Display), align_of_val(&0u32));
+ assert_eq!(align_of_t(&[0isize, 1isize] as &[isize]), align_of_val(&[0isize, 1isize]));
+ assert_eq!(align_of_t(&[] as &[u8]), align_of_val::<[u8; 0]>(&[]));
+ assert_eq!(
+ align_of_t(NonNull::<u32>::dangling().as_ptr() as *const dyn std::fmt::Display),
+ align_of::<u32>()
+ );
+ }
+
+ #[test]
+ pub fn test_empty_slice() {
+ let slice_ptr = Vec::<char>::new().as_slice() as *const [char];
+ assert_valid_ptr(slice_ptr);
+ }
+
+ #[test]
+ pub fn test_empty_str() {
+ let slice_ptr = String::new().as_str() as *const str;
+ assert_valid_ptr(slice_ptr);
+ }
+
+ #[test]
+ fn test_dangling_zst() {
+ test_dangling_of_t::<()>();
+ test_dangling_of_t::<[(); 10]>();
+ }
+
+ fn test_dangling_of_t<T>() {
+ let dangling: *const T = NonNull::<T>::dangling().as_ptr();
+ assert_valid_ptr(dangling);
+
+ let vec_ptr = Vec::<T>::new().as_ptr();
+ assert_valid_ptr(vec_ptr);
+ }
+
+ #[test]
+ #[should_panic(expected = "Expected valid pointer, but found `null`")]
+ fn test_null_fat_ptr() {
+ assert_valid_ptr(ptr::null::<char>() as *const dyn Debug);
+ }
+
+ #[test]
+ #[should_panic(expected = "Expected valid pointer, but found `null`")]
+ fn test_null_char() {
+ assert_valid_ptr(ptr::null::<char>());
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+//! Contains definitions that Kani compiler may use to model functions that are not suitable for
+//! verification or functions without a body, such as intrinsics.
+//!
+//! Note that these are models that Kani uses by default; thus, we keep them separate from stubs.
+
+// Definitions in this module are not meant to be visible to the end user, only the compiler.
+#[allow(dead_code)]
+mod intrinsics {
+ use std::fmt::Debug;
+ use std::mem::size_of;
+
+ /// Similar definition to portable SIMD.
+ /// We cannot reuse theirs since TRUE and FALSE defs are private.
+ /// We leave this private today, since this is not necessarily a final solution, so we don't
+ /// want users relying on this.
+ /// Our definitions are also a bit more permissive to comply with the platform intrinsics.
+ pub(super) trait MaskElement: PartialEq + Debug {
+ const TRUE: Self;
+ const FALSE: Self;
+ }
+
+ macro_rules! impl_element {
+ { $ty:ty } => {
+ impl MaskElement for $ty {
+ const TRUE: Self = -1;
+ const FALSE: Self = 0;
+ }
+ }
+ }
+
+ macro_rules! impl_unsigned_element {
+ { $ty:ty } => {
+ impl MaskElement for $ty {
+ // Note that in the declaration of the intrinsic it is documented that the lane
+ // values should be -1 or 0:
+ // <https://github.com/rust-lang/rust/blob/338cfd3/library/portable-simd/crates/core_simd/src/intrinsics.rs#L134-L144>
+ //
+ // However, MIRI and the Rust compiler seems to accept unsigned values and they
+ // use their binary representation. Thus, that's what we use for now.
+ /// All bits are 1 which represents TRUE.
+ const TRUE: Self = <$ty>::MAX;
+ /// All bits are 0 which represents FALSE.
+ const FALSE: Self = 0;
+ }
+ }
+ }
+
+ impl_element! { i8 }
+ impl_element! { i16 }
+ impl_element! { i32 }
+ impl_element! { i64 }
+ impl_element! { i128 }
+ impl_element! { isize }
+
+ impl_unsigned_element! { u8 }
+ impl_unsigned_element! { u16 }
+ impl_unsigned_element! { u32 }
+ impl_unsigned_element! { u64 }
+ impl_unsigned_element! { u128 }
+ impl_unsigned_element! { usize }
+
+ /// Calculate the minimum number of lanes to represent a mask
+ /// Logic similar to `bitmask_len` from `portable_simd`.
+ /// <https://github.com/rust-lang/portable-simd/blob/490b5cf/crates/core_simd/src/masks/to_bitmask.rs#L75-L79>
+ pub(super) const fn mask_len(len: usize) -> usize {
+ (len + 7) / 8
+ }
+
+ #[cfg(target_endian = "little")]
+ unsafe fn simd_bitmask_impl<T, const LANES: usize>(input: &[T; LANES]) -> [u8; mask_len(LANES)]
+ where
+ T: MaskElement,
+ {
+ let mut mask_array = [0; mask_len(LANES)];
+ for lane in (0..input.len()).rev() {
+ let byte = lane / 8;
+ let mask = &mut mask_array[byte];
+ let shift_mask = *mask << 1;
+ *mask = if input[lane] == T::TRUE {
+ shift_mask | 0x1
+ } else {
+ assert_eq!(input[lane], T::FALSE, "Masks values should either be 0 or -1");
+ shift_mask
+ };
+ }
+ mask_array
+ }
+
+ /// Stub for simd_bitmask.
+ ///
+ /// It will reduce a simd vector (TxN), into an integer of size S (in bits), where S >= N.
+ /// Each bit of the output will represent a lane from the input. A lane value of all 0's will be
+ /// translated to 1b0, while all 1's will be translated to 1b1.
+ ///
+ /// In order to be able to do this pragmatically, we take additional parameters that are filled
+ /// by the compiler.
+ #[rustc_diagnostic_item = "KaniModelSimdBitmask"]
+ pub(super) unsafe fn simd_bitmask<T, U, E, const LANES: usize>(input: T) -> U
+ where
+ [u8; mask_len(LANES)]: Sized,
+ E: MaskElement,
+ {
+ // These checks are compiler sanity checks to ensure we are not doing anything invalid.
+ assert_eq!(
+ size_of::<U>(),
+ size_of::<[u8; mask_len(LANES)]>(),
+ "Expected size of return type and mask lanes to match",
+ );
+ assert_eq!(
+ size_of::<T>(),
+ size_of::<Simd::<E, LANES>>(),
+ "Expected size of input and lanes to match",
+ );
+
+ let data = &*(&input as *const T as *const [E; LANES]);
+ let mask = simd_bitmask_impl(data);
+ (&mask as *const [u8; mask_len(LANES)] as *const U).read()
+ }
+
+ /// Structure used for sanity check our parameters.
+ #[repr(simd)]
+ struct Simd<T, const LANES: usize>([T; LANES]);
+}
+
+#[cfg(test)]
+mod test {
+ use super::intrinsics as kani_intrinsic;
+ use std::intrinsics::simd::*;
+ use std::{fmt::Debug, simd::*};
+
+ /// Test that the `simd_bitmask` model is equivalent to the intrinsic for all true and all false
+ /// masks with lanes represented using i16.
+ #[test]
+ fn test_bitmask_i16() {
+ check_portable_bitmask::<_, i16, 16, u16>(mask16x16::splat(false));
+ check_portable_bitmask::<_, i16, 16, u16>(mask16x16::splat(true));
+ }
+
+ /// Tests that the model correctly fails if an invalid value is given.
+ #[test]
+ #[should_panic(expected = "Masks values should either be 0 or -1")]
+ fn test_invalid_bitmask() {
+ let invalid_mask = unsafe { mask32x16::from_int_unchecked(i32x16::splat(10)) };
+ assert_eq!(
+ unsafe { kani_intrinsic::simd_bitmask::<_, u16, i32, 16>(invalid_mask) },
+ u16::MAX
+ );
+ }
+
+ /// Tests that the model correctly fails if the size parameter of the mask doesn't match the
+ /// expected number of bytes in the representation.
+ #[test]
+ #[should_panic(expected = "Expected size of return type and mask lanes to match")]
+ fn test_invalid_generics() {
+ let mask = mask32x16::splat(false);
+ assert_eq!(unsafe { kani_intrinsic::simd_bitmask::<_, u16, i32, 2>(mask) }, u16::MAX);
+ }
+
+ /// Test that the `simd_bitmask` model is equivalent to the intrinsic for a few random values.
+ /// These values shouldn't be symmetric and ensure that we also handle endianness correctly.
+ #[test]
+ fn test_bitmask_i32() {
+ check_portable_bitmask::<_, i32, 8, u8>(mask32x8::from([
+ true, true, false, true, false, false, false, true,
+ ]));
+
+ check_portable_bitmask::<_, i32, 4, u8>(mask32x4::from([true, false, false, true]));
+ }
+
+ #[repr(simd)]
+ #[derive(Clone, Debug)]
+ struct CustomMask<T, const LANES: usize>([T; LANES]);
+
+ /// Check that the bitmask model can handle odd size SIMD arrays.
+ /// Since the portable_simd restricts the number of lanes, we have to use our own custom SIMD.
+ #[test]
+ fn test_bitmask_odd_lanes() {
+ check_bitmask::<_, [u8; 3], i128, 23>(CustomMask([0i128; 23]));
+ check_bitmask::<_, [u8; 9], i128, 70>(CustomMask([-1i128; 70]));
+ }
+
+ /// Compare the value returned by our model and the portable simd representation.
+ fn check_portable_bitmask<T, E, const LANES: usize, M>(mask: Mask<T, LANES>)
+ where
+ T: std::simd::MaskElement,
+ LaneCount<LANES>: SupportedLaneCount,
+ E: kani_intrinsic::MaskElement,
+ [u8; kani_intrinsic::mask_len(LANES)]: Sized,
+ u64: From<M>,
+ {
+ assert_eq!(
+ unsafe { u64::from(kani_intrinsic::simd_bitmask::<_, M, E, LANES>(mask.clone())) },
+ mask.to_bitmask()
+ );
+ }
+
+ /// Compare the value returned by our model and the simd_bitmask intrinsic.
+ fn check_bitmask<T, U, E, const LANES: usize>(mask: T)
+ where
+ T: Clone,
+ U: PartialEq + Debug,
+ E: kani_intrinsic::MaskElement,
+ [u8; kani_intrinsic::mask_len(LANES)]: Sized,
+ {
+ assert_eq!(
+ unsafe { kani_intrinsic::simd_bitmask::<_, U, E, LANES>(mask.clone()) },
+ unsafe { simd_bitmask::<T, U>(mask) }
+ );
+ }
+
+ /// Similar to portable simd_harness.
+ #[test]
+ fn check_mask_harness() {
+ // From array doesn't work either. Manually build [false, true, false, true]
+ let mut mask = mask32x4::splat(false);
+ mask.set(1, true);
+ mask.set(3, true);
+ let bitmask = mask.to_bitmask();
+ assert_eq!(bitmask, 0b1010);
+
+ let kani_mask =
+ unsafe { u64::from(kani_intrinsic::simd_bitmask::<_, u8, u32, 4>(mask.clone())) };
+ assert_eq!(kani_mask, bitmask);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+use crate::{any, assume};
+
+/// Given an array `arr` of length `LENGTH`, this function returns a **valid**
+/// slice of `arr` with non-deterministic start and end points. This is useful
+/// in situations where one wants to verify that all possible slices of a given
+/// array satisfy some property.
+///
+/// # Example:
+///
+/// ```rust
+/// let arr = [1, 2, 3];
+/// let slice = kani::slice::any_slice_of_array(&arr);
+/// foo(slice); // where foo is a function that takes a slice and verifies a property about it
+/// ```
+pub fn any_slice_of_array<T, const LENGTH: usize>(arr: &[T; LENGTH]) -> &[T] {
+ let (from, to) = any_range::<LENGTH>();
+ &arr[from..to]
+}
+
+/// A mutable version of the previous function
+pub fn any_slice_of_array_mut<T, const LENGTH: usize>(arr: &mut [T; LENGTH]) -> &mut [T] {
+ let (from, to) = any_range::<LENGTH>();
+ &mut arr[from..to]
+}
+
+fn any_range<const LENGTH: usize>() -> (usize, usize) {
+ let from: usize = any();
+ let to: usize = any();
+ assume(to <= LENGTH);
+ assume(from <= to);
+ (from, to)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! Support for arbitrary tuples where each element implements
+//! `kani::Arbitrary`. Tuples of size up to 12 are supported in this
+//! file.
+
+use crate::Arbitrary;
+
+/// This macro implements `kani::Arbitrary` on a tuple whose elements
+/// already implement `kani::Arbitrary` by running `kani::any()` on
+/// each index of the tuple.
+macro_rules! tuple {
+ ($($typ:ident),*) => {
+ impl<$($typ : Arbitrary),*> Arbitrary for ($($typ,)*) {
+ #[inline(always)]
+ fn any() -> Self {
+ ($(crate::any::<$typ>(),)*)
+ }
+ }
+ }
+}
+
+tuple!(A);
+tuple!(A, B);
+tuple!(A, B, C);
+tuple!(A, B, C, D);
+tuple!(A, B, C, D, E);
+tuple!(A, B, C, D, E, F);
+tuple!(A, B, C, D, E, F, G);
+tuple!(A, B, C, D, E, F, G, H);
+tuple!(A, B, C, D, E, F, G, H, I);
+tuple!(A, B, C, D, E, F, G, H, I, J);
+tuple!(A, B, C, D, E, F, G, H, I, J, K);
+tuple!(A, B, C, D, E, F, G, H, I, J, K, L);
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+use crate::{any, any_where, Arbitrary};
+
+/// Generates an arbitrary vector whose length is at most MAX_LENGTH.
+pub fn any_vec<T, const MAX_LENGTH: usize>() -> Vec<T>
+where
+ T: Arbitrary,
+ [(); std::mem::size_of::<[T; MAX_LENGTH]>()]:,
+{
+ let real_length: usize = any_where(|sz| *sz <= MAX_LENGTH);
+ match real_length {
+ 0 => vec![],
+ exact if exact == MAX_LENGTH => exact_vec::<T, MAX_LENGTH>(),
+ _ => {
+ let mut any_vec = exact_vec::<T, MAX_LENGTH>();
+ any_vec.truncate(real_length);
+ any_vec.shrink_to_fit();
+ assert!(any_vec.capacity() == any_vec.len());
+ any_vec
+ }
+ }
+}
+
+/// Generates an arbitrary vector that is exactly EXACT_LENGTH long.
+pub fn exact_vec<T, const EXACT_LENGTH: usize>() -> Vec<T>
+where
+ T: Arbitrary,
+ [(); std::mem::size_of::<[T; EXACT_LENGTH]>()]:,
+{
+ let boxed_array: Box<[T; EXACT_LENGTH]> = Box::new(any());
+ <[T]>::into_vec(boxed_array)
+}
+fn:) to \
+ restrict the search to a given item kind.","Accepted kinds are: fn, mod, struct, \
+ enum, trait, type, macro, \
+ and const.","Search functions by type signature (e.g., vec -> usize or \
+ -> vec or String, enum:Cow -> bool)","You can look for items with an exact name by putting double quotes around \
+ your request: \"string\"","Look for functions that accept or return \
+ slices and \
+ arrays by writing \
+ square brackets (e.g., -> [u8] or [] -> Option)","Look for items inside another one by searching for a path: vec::Vec",].map(x=>""+x+"
").join("");const div_infos=document.createElement("div");addClass(div_infos,"infos");div_infos.innerHTML="${value.replaceAll(" ", " ")}`}else{error[index]=value}});output+=`Kani currently ships with a kani crate that provide APIs to allow users to
+write and configure their harnesses.
+These APIs are tightly coupled with each Kani version, so they are not
+published yet at https://crates.io.
You can find their latest documentation here:
+When the result of a certain check comes back as a FAILURE,
+Kani offers different options to help debug:
--concrete-playback. This experimental feature generates a Rust unit test case that plays back a failing
+proof harness using a concrete counterexample.--visualize. This feature generates an HTML text-based trace that
+enumerates the execution steps leading to the check failure.When concrete playback is enabled, Kani will generate unit tests for assertions that failed during verification, +as well as cover statements that are reachable.
+These tests can then be executed using Kani's playback subcommand.
+In order to enable this feature, run Kani with the -Z concrete-playback --concrete-playback=[print|inplace] flag.
+After getting a verification failure, Kani will generate a Rust unit test case that plays back a failing
+proof harness with a concrete counterexample.
+The concrete playback modes mean the following:
print: Kani will just print the unit test to stdout.
+You will then need to copy this unit test into the same module as your proof harness.
+This is also helpful if you just want to quickly find out which values were assigned by kani::any() calls.inplace: Kani will automatically copy the unit test into your source code.
+Before running this mode, you might find it helpful to have your existing code committed to git.
+That way, you can easily remove the unit test with git revert.
+Note that Kani will not copy the unit test into your source code if it detects
+that the exact same test already exists.After the unit test is in your source code, you can run it with the playback subcommand.
+To debug it, there are a couple of options:
To manually compile and run the test, you can use Kani's playback subcommand:
cargo kani playback -Z concrete-playback -- ${unit_test_func_name}
+The output from this command is similar to cargo test.
+The output will have a line in the beginning like
+Running unittests {files} ({binary}).
You can further debug the binary with tools like rust-gdb or lldb.
Running kani -Z concrete-playback --concrete-playback=print on the following source file:
#[kani::proof]
+fn proof_harness() {
+ let a: u8 = kani::any();
+ let b: u16 = kani::any();
+ assert!(a / 2 * 2 == a &&
+ b / 2 * 2 == b);
+}
+yields a concrete playback Rust unit test similar to the one below:
+#[test]
+fn kani_concrete_playback_proof_harness_16220658101615121791() {
+ let concrete_vals: Vec<Vec<u8>> = vec![
+ // 133
+ vec![133],
+ // 35207
+ vec![135, 137],
+ ];
+ kani::concrete_playback_run(concrete_vals, proof_harness);
+}
+Here, 133 and 35207 are the concrete values that, when substituted for a and b,
+cause an assertion failure.
+vec![135, 137] is the byte array representation of 35207.
This feature is experimental and is therefore subject to change. +If you have ideas for improving the user experience of this feature, +please add them to this GitHub issue. +We are tracking the existing feature requests in +this GitHub milestone.
+cargo kani assessAssess is an experimental new feature to gather data about Rust crates, to aid the start of proof writing.
+In the short-term, assess collects and dumps tables of data that may help Kani developers understand what's needed to begin writing proofs for another project. +For instance, assess may help answer questions like:
+In the long-term, assess will become a user-facing feature, and help Kani users get started writing proofs. +We expect that users will have the same questions as above, but in the long term, hopefully the answers to those trend towards an uninteresting "yes." +So the new questions might be:
+These long-term goals are only "hinted at" with the present experimental version of assess. +Currently, we only get as far as finding out which tests successfully verify (concretely) with Kani. +This might indicate tests that could be generalized and converted into proofs, but we currently don't do anything to group, rank, or otherwise heuristically prioritize what might be most "interesting." +(For instance, we'd like to eventually compute coverage information and use that to help rank the results.) +As a consequence, the output of the tool is very hard to interpret, and likely not (yet!) helpful to new or potential Kani users.
+To assess a package, run:
+cargo kani --enable-unstable assess
+As a temporary hack (arguments shouldn't work like this), to assess a single cargo workspace, run:
+cargo kani --enable-unstable --workspace assess
+To scan a collection of workspaces or packages that are not part of a shared workspace, run:
+cargo kani --enable-unstable assess scan
+The only difference between 'scan' and 'regular' assess is how the packages built are located.
+All versions of assess produce the same output and metrics.
+Assess will normally build just like cargo kani or cargo build, whereas scan will find all cargo packages beneath the current directory, even in unrelated workspaces.
+Thus, 'scan' may be helpful in the case where the user has a choice of packages and is looking for the easiest to get started with (in addition to the Kani developer use-case, of aggregating statistics across many packages).
(Tip: Assess may need to run for awhile, so try using screen, tmux or nohup to avoid terminating the process if, for example, an ssh connection breaks.
+Some tests can also consume huge amounts of ram when run through Kani, so you may wish to use ulimit -v 6000000 to prevent any processes from using more than 6GB.
+You can also limit the number of concurrent tests that will be run by providing e.g. -j 4, currently as a prepended argument, like --enable-unstable or --workspace in the examples above.)
Assess builds all the packages requested in "test mode" (i.e. --tests), and runs all the same tests that cargo test would, except through Kani.
+This gives end-to-end assurance we're able to actually build and run code from these packages, skipping nothing of what the verification process would need, except that the harnesses don't have any nondeterminism (kani::any()) and consequently don't "prove" much.
+The interesting signal comes from what tests cannot be analyzed by Kani due to unsupported features, performance problems, crash bugs, or other issues that get in the way.
Currently, assess forces termination by using unwind(1) on all tests, so many tests will fail with unwinding assertions.
Assess produces a few tables of output (both visually in the terminal, and in a more detailed json format) so far:
+======================================================
+ Unsupported feature | Crates | Instances
+ | impacted | of use
+-------------------------------+----------+-----------
+ caller_location | 71 | 239
+ simd_bitmask | 39 | 160
+...
+The unsupported features table aggregates information about features that Kani does not yet support.
+These correspond to uses of codegen_unimplemented in the kani-compiler, and appear as warnings during compilation.
Unimplemented features are not necessarily actually hit by (dynamically) reachable code, so an immediate future improvement on this table would be to count the features actually hit by failing test cases, instead of just those features reported as existing in code by the compiler. +In other words, the current unsupported features table is not what we want to see, in order to perfectly prioritize implementing these features, because we may be counting features that no proof would ever hit. +A perfect signal here isn't possible: there may be code that looks statically reachable, but is never dynamically reachable, and we can't tell. +But we can use test coverage as an approximation: well-tested code will hopefully cover most of the dynamically reachable code. +The operating hypothesis of assess is that code covered by tests is code that could be covered by proof, and so measuring unsupported features by those actually hit by a test should provide a better "signal" about priorities. +Implicitly deprioritizing unsupported features because they aren't covered by tests may not be a bug, but a feature: we may simply not want to prove anything about that code, if it hasn't been tested first, and so adding support for that feature may not be important.
+A few notes on terminology:
+1 in this column, regardless of the number of dependencies.================================================
+ Reason for failure | Number of tests
+------------------------------+-----------------
+ unwind | 61
+ none (success) | 6
+ assertion + overflow | 2
+...
+The test failure reasons table indicates why, when assess ran a test through Kani, it failed to verify. +Notably:
+unwind(1), we expect unwind to rank highly.assertion means an ordinary assert!() was hit (or something else with this property class).+, such as assertion + overflow.should_fail tests, so assertion may actually be "success": the test should hit an assertion and did.=============================================================================
+ Candidate for proof harness | Location
+-------------------------------------------------------+---------------------
+ float::tests::f64_edge_cases | src/float.rs:226
+ float::tests::f32_edge_cases | src/float.rs:184
+ integer::tests::test_integers | src/integer.rs:171
+This table is the most rudimentary so far, but is the core of what long-term assess will help accomplish. +Currently, this table just presents (with paths displayed in a clickable manner) the tests that successfully "verify" with Kani. +These might be good candidates for turning into proof harnesses. +This list is presently unordered; the next step for improving it would be to find even a rudimentary way of ranking these test cases (e.g. perhaps by code coverage).
+kani-compiler emits *.kani-metadata.json for each target it builds.
+This format can be found in the kani_metadata crate, shared by kani-compiler and kani-driver.
+This is the starting point for assess.
Assess obtains this metadata by essentially running a cargo kani:
--all-features turned onunwind always set to 1--testsAssess starts by getting all the information from these metadata files. +This is enough by itself to construct a rudimentary "unsupported features" table. +But assess also uses it to discover all the test cases, and (instead of running proof harnesses) it then runs all these test harnesses under Kani.
+Assess produces a second metadata format, called (unsurprisingly) "assess metadata".
+(Found in kani-driver under src/assess/metadata.rs.)
+This format records the results of what assess does.
This metadata can be written to a json file by providing --emit-metadata <file> to assess.
+Likewise, scan can be told to write out this data with the same option.
Assess metadata is an aggregatable format.
+It does not apply to just one package, as assess can work on a workspace of packages.
+Likewise, scan uses and produces the exact same format, across multiple workspaces.
So far all assess metadata comes in the form of "tables" which are built with TableBuilder<T: TableRow>.
+This is documented further in src/assess/table_builder.rs.
There is a script in the Kani repo for this purpose.
+This will clone the top-100 crates to /tmp/top-100-experiment and run assess scan on them:
./scripts/exps/assess-scan-on-repos.sh
+If you'd like to preseve the results, you can direct scan to use a different directory with an environment variable:
+ASSESS_SCAN="~/top-100-experiment" ./scripts/exps/assess-scan-on-repos.sh
+To re-run the experiment, it suffices to be in the experiment directory:
+cd ~/top-100-experiment && ~/kani/scripts/exps/assess-scan-on-repos.sh
+Kani is an open source project open to external contributions.
+The easiest way to contribute is to report any +issue you encounter +while using the tool. If you want to contribute to its development, +we recommend looking into these issues.
+In this chapter, we provide documentation that might be helpful for Kani +developers (including external contributors):
+cbmc.rustc.++ +NOTE: The developer documentation is intended for Kani developers and not +users. At present, the project is under heavy development and some items +discussed in this documentation may stop working without notice (e.g., commands +or configurations). Therefore, we recommend users to not rely on them.
+
This section collects frequently asked questions about Kani. +Please consider opening an issue if you have a question that would like to see here.
+kani::assume(false). Why?kani::assume(false) (or kani::assume(cond) where cond is a condition that results in false in the context of the program), won't cause errors in Kani.
+Instead, such an assumption has the effect of blocking all the symbolic execution paths from the assumption.
+Therefore, all checks after the assumption should appear as UNREACHABLE.
+That's the expected behavior for kani::assume(false) in Kani.
If you didn't expect certain checks in a harness to be UNREACHABLE, we recommend using the kani::cover macro to determine what conditions are possible in case you've over-constrained the harness.
kani::Arbitrary trait for a type that's not from my crate, and got the error
+only traits defined in the current crate can be implemented for types defined outside of the crate.
+What does this mean? What can I do?This error is due to a violation of Rust's orphan rules for trait implementations, which are explained here. +In that case, you'll need to write a function that builds an object from non-deterministic variables. +Inside this function you would simply return an arbitrary value by generating arbitrary values for its components.
+For example, let's assume the type you're working with is this enum:
+#[derive(Copy, Clone)]
+pub enum Rating {
+ One,
+ Two,
+ Three,
+}
+Then, you can match on a non-deterministic integer (supplied by kani::any) to return non-deterministic Rating variants:
pub fn any_rating() -> Rating {
+ match kani::any() {
+ 0 => Rating::One,
+ 1 => Rating::Two,
+ _ => Rating::Three,
+ }
+ }
+More details about this option, which also useful in other cases, can be found here.
+If the type comes from std (Rust's standard library), you can open a request for adding Arbitrary implementations to the Kani library.
+Otherwise, there are more involved options to consider:
Arbitrary there.Arbitrary implementation to the external crate that defines the type.Kani is an open-source verification tool that uses model checking to analyze Rust programs. +Kani is particularly useful for verifying unsafe code blocks in Rust, where the "unsafe superpowers" are unchecked by the compiler. +Some example properties you can prove with Kani include memory safety properties (e.g., null pointer dereferences, use-after-free, etc.), the absence of certain runtime errors (i.e., index out of bounds, panics), and the absence of some types of unexpected behavior (e.g., arithmetic overflows). +Kani can also prove custom properties provided in the form of user-specified assertions. +As Kani uses model checking, Kani will either prove the property, disprove the +property (with a counterexample), or may run out of resources.
+Kani uses proof harnesses to analyze programs. +Proof harnesses are similar to test harnesses, especially property-based test harnesses.
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book.
+There is support for a fair amount of Rust language features, but not all (e.g., concurrency). +Please see Limitations for a detailed list of supported features.
+Kani releases every two weeks. +As part of every release, Kani will synchronize with a recent nightly release of Rust, and so is generally up-to-date with the latest Rust language features.
+If you encounter issues when using Kani, we encourage you to report them to us.
+ +Kani is an open-source verification tool that uses model checking to analyze Rust programs. +Kani is particularly useful for verifying unsafe code blocks in Rust, where the "unsafe superpowers" are unchecked by the compiler. +Some example properties you can prove with Kani include memory safety properties (e.g., null pointer dereferences, use-after-free, etc.), the absence of certain runtime errors (i.e., index out of bounds, panics), and the absence of some types of unexpected behavior (e.g., arithmetic overflows). +Kani can also prove custom properties provided in the form of user-specified assertions. +As Kani uses model checking, Kani will either prove the property, disprove the +property (with a counterexample), or may run out of resources.
+Kani uses proof harnesses to analyze programs. +Proof harnesses are similar to test harnesses, especially property-based test harnesses.
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book.
+There is support for a fair amount of Rust language features, but not all (e.g., concurrency). +Please see Limitations for a detailed list of supported features.
+Kani releases every two weeks. +As part of every release, Kani will synchronize with a recent nightly release of Rust, and so is generally up-to-date with the latest Rust language features.
+If you encounter issues when using Kani, we encourage you to report them to us.
+ +Kani offers a GitHub Action for running Kani in CI.
+As of now, only Ubuntu 20.04 with x86_64-unknown-linux-gnu is supported for Kani in CI.
Our GitHub Action is available in the GitHub Marketplace.
+The following workflow snippet will checkout your repository and run cargo kani on it whenever a push or pull request occurs.
+Replace <MAJOR>.<MINOR> with the version of Kani you want to run with.
name: Kani CI
+on:
+ pull_request:
+ push:
+jobs:
+ run-kani:
+ runs-on: ubuntu-20.04
+ steps:
+ - name: 'Checkout your code.'
+ uses: actions/checkout@v3
+
+ - name: 'Run Kani on your code.'
+ uses: model-checking/kani-github-action@v<MAJOR>.<MINOR>
+This will run cargo kani on the code you checked out.
The action takes the following optional parameters:
+command: The command to run.
+Defaults to cargo kani.
+Most often, you will not need to change this.working-directory: The directory to execute the command in.
+Defaults to ..
+Useful if your repository has multiple crates, and you only want to run on one of them.args: The arguments to pass to the given ${command}.
+See cargo kani --help for a full list of options.
+Useful options include:
+--output-format=terse to generate terse output.--tests to run on proofs inside the test module (needed for running Bolero).--workspace to run on all crates within your repository.Kani offers an easy installation option on three platforms:
+x86_64-unknown-linux-gnu (Most Linux distributions)x86_64-apple-darwin (Intel Mac OS)aarch64-apple-darwin (Apple Silicon Mac OS)Other platforms are either not yet supported or require instead that +you build from source. To use Kani in your +GitHub CI workflows, see GitHub CI Action.
+The following must already be installed:
+pip.rustup.ctags is required for Kani's --visualize option to work correctly. Universal ctags is recommended.To install the latest version of Kani, run:
+cargo install --locked kani-verifier
+cargo kani setup
+This will build and place in ~/.cargo/bin (in a typical environment) the kani and cargo-kani binaries.
+The second step (cargo kani setup) will download the Kani compiler and other necessary dependencies, and place them under ~/.kani/ by default.
+A custom path can be specified using the KANI_HOME environment variable.
cargo install --locked kani-verifier --version <VERSION>
+cargo kani setup
+After you've installed Kani, +you can try running it by creating a test file:
+// File: test.rs
+#[kani::proof]
+fn main() {
+ assert!(1 == 2);
+}
+Run Kani on the single file:
+kani test.rs
+You should get a result like this one:
+[...]
+RESULTS:
+Check 1: main.assertion.1
+ - Status: FAILURE
+ - Description: "assertion failed: 1 == 2"
+[...]
+VERIFICATION:- FAILED
+Fix the test and you should see a result like this one:
+[...]
+VERIFICATION:- SUCCESSFUL
+If you're learning Kani for the first time, you may be interested in our tutorial.
+ +++NOTE: This tutorial expects you to have followed the Kani installation instructions first.
+
This tutorial will step you through a progression from simple to moderately complex tasks with Kani. +It's meant to ensure you can get started, and see at least some simple examples of how typical proofs are structured. +It will also teach you the basics of "debugging" proof harnesses, which mainly consists of diagnosing and resolving non-termination issues with the solver.
+You may also want to read the Application section to better +understand what Kani is and how it can be applied on real code.
+ +Like other tools, Kani comes with some limitations. In some cases, these +limitations are inherent because of the techniques it's based on, or the +undecidability of the properties that Kani seeks to prove. In other +cases, it's just a matter of time and effort to remove these limitations (e.g., +specific unsupported Rust language features).
+In this chapter, we do the following to document these limitations:
+As explained in Comparison with other +tools, Kani is based on a +technique called model checking, which verifies a program without actually +executing it. It does so through encoding the program and analyzing the encoded +version. The encoding process often requires "modeling" some of the library +functions to make them suitable for analysis. Typical examples of functionality +that requires modeling are system calls and I/O operations. In some cases, Kani +performs such encoding through overriding some of the definitions in the Rust +standard library.
+The following table lists some of the symbols that Kani
+overrides and a description of their behavior compared to the std versions:
| Name | Description |
|---|---|
assert, assert_eq, and assert_ne macros | Skips string formatting code, generates a more informative message and performs some instrumentation |
debug_assert, debug_assert_eq, and debug_assert_ne macros | Rewrites as equivalent assert* macro |
print, eprint, println, and eprintln macros | Skips string formatting and I/O operations |
unreachable macro | Skips string formatting and invokes panic!() |
std::process::{abort, exit} functions | Invokes panic!() to abort the execution |
benchcompWhile Kani includes a performance regression suite, you may wish to test Kani's performance using your own benchmarks or with particular versions of Kani.
+You can use the benchcomp tool in the Kani repository to run several 'variants' of a command on one or more benchmark suites; automatically parse the results of each of those suites; and take actions or emit visualizations based on those results.
Benchcomp provides the following features to support your performance-comparison workflow:
+Here's how to run Kani's performance suite twice, comparing the last released version of Kani with the current HEAD.
+cd $KANI_SRC_DIR
+git worktree add new HEAD
+git worktree add old $(git describe --tags --abbrev=0)
+
+tools/benchcomp/bin/benchcomp --config tools/benchcomp/configs/perf-regression.yaml
+This uses the perf-regression.yaml configuration file that we use in continuous integration.
+After running the suite twice, the configuration file terminates benchcomp with a return code of 1 if any of the benchmarks regressed on metrics such as success (a boolean), solver_runtime, and number_vccs (numerical).
+Additionally, the config file directs benchcomp to print out a Markdown table that GitHub's CI summary page renders in to a table.
The rest of this documentation describes how to modify benchcomp for your own use cases, including writing a configuration file; writing a custom parser for your benchmark suite; and writing a custom visualization to examine the results of a performance comparison.
Kani is an open-source verification tool that uses model checking to analyze Rust programs. +Kani is particularly useful for verifying unsafe code blocks in Rust, where the "unsafe superpowers" are unchecked by the compiler. +Some example properties you can prove with Kani include memory safety properties (e.g., null pointer dereferences, use-after-free, etc.), the absence of certain runtime errors (i.e., index out of bounds, panics), and the absence of some types of unexpected behavior (e.g., arithmetic overflows). +Kani can also prove custom properties provided in the form of user-specified assertions. +As Kani uses model checking, Kani will either prove the property, disprove the +property (with a counterexample), or may run out of resources.
+Kani uses proof harnesses to analyze programs. +Proof harnesses are similar to test harnesses, especially property-based test harnesses.
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book.
+There is support for a fair amount of Rust language features, but not all (e.g., concurrency). +Please see Limitations for a detailed list of supported features.
+Kani releases every two weeks. +As part of every release, Kani will synchronize with a recent nightly release of Rust, and so is generally up-to-date with the latest Rust language features.
+If you encounter issues when using Kani, we encourage you to report them to us.
+Kani offers an easy installation option on three platforms:
+x86_64-unknown-linux-gnu (Most Linux distributions)x86_64-apple-darwin (Intel Mac OS)aarch64-apple-darwin (Apple Silicon Mac OS)Other platforms are either not yet supported or require instead that +you build from source. To use Kani in your +GitHub CI workflows, see GitHub CI Action.
+The following must already be installed:
+pip.rustup.ctags is required for Kani's --visualize option to work correctly. Universal ctags is recommended.To install the latest version of Kani, run:
+cargo install --locked kani-verifier
+cargo kani setup
+This will build and place in ~/.cargo/bin (in a typical environment) the kani and cargo-kani binaries.
+The second step (cargo kani setup) will download the Kani compiler and other necessary dependencies, and place them under ~/.kani/ by default.
+A custom path can be specified using the KANI_HOME environment variable.
cargo install --locked kani-verifier --version <VERSION>
+cargo kani setup
+After you've installed Kani, +you can try running it by creating a test file:
+// File: test.rs
+#[kani::proof]
+fn main() {
+ assert!(1 == 2);
+}
+Run Kani on the single file:
+kani test.rs
+You should get a result like this one:
+[...]
+RESULTS:
+Check 1: main.assertion.1
+ - Status: FAILURE
+ - Description: "assertion failed: 1 == 2"
+[...]
+VERIFICATION:- FAILED
+Fix the test and you should see a result like this one:
+[...]
+VERIFICATION:- SUCCESSFUL
+If you're learning Kani for the first time, you may be interested in our tutorial.
+++If you were able to install Kani normally, you do not need to build Kani from source. +You probably want to proceed to the Kani tutorial.
+
In general, the following dependencies are required to build Kani from source.
+++NOTE: These dependencies may be installed by running the scripts shown +below and don't need to be manually installed.
+
Kani has been tested in Ubuntu and macOS platforms.
+Support is available for Ubuntu 18.04, 20.04 and 22.04. +The simplest way to install dependencies (especially if you're using a fresh VM) +is following our CI scripts:
+# git clone git@github.com:model-checking/kani.git
+git clone https://github.com/model-checking/kani.git
+cd kani
+git submodule update --init
+./scripts/setup/ubuntu/install_deps.sh
+# If you haven't already (or from https://rustup.rs/):
+./scripts/setup/install_rustup.sh
+source $HOME/.cargo/env
+Support is available for macOS 11. You need to have Homebrew installed already.
+# git clone git@github.com:model-checking/kani.git
+git clone https://github.com/model-checking/kani.git
+cd kani
+git submodule update --init
+./scripts/setup/macos/install_deps.sh
+# If you haven't already (or from https://rustup.rs/):
+./scripts/setup/install_rustup.sh
+source $HOME/.cargo/env
+Build the Kani package:
+cargo build-dev
+Then, optionally, run the regression tests:
+./scripts/kani-regression.sh
+This script has a lot of noisy output, but on a successful run you'll see at the end of the execution:
+All Kani regression tests completed successfully.
+To use a locally-built Kani from anywhere, add the Kani scripts to your path:
+export PATH=$(pwd)/scripts:$PATH
+If you're learning Kani for the first time, you may be interested in our tutorial.
+Kani offers a GitHub Action for running Kani in CI.
+As of now, only Ubuntu 20.04 with x86_64-unknown-linux-gnu is supported for Kani in CI.
Our GitHub Action is available in the GitHub Marketplace.
+The following workflow snippet will checkout your repository and run cargo kani on it whenever a push or pull request occurs.
+Replace <MAJOR>.<MINOR> with the version of Kani you want to run with.
name: Kani CI
+on:
+ pull_request:
+ push:
+jobs:
+ run-kani:
+ runs-on: ubuntu-20.04
+ steps:
+ - name: 'Checkout your code.'
+ uses: actions/checkout@v3
+
+ - name: 'Run Kani on your code.'
+ uses: model-checking/kani-github-action@v<MAJOR>.<MINOR>
+This will run cargo kani on the code you checked out.
The action takes the following optional parameters:
+command: The command to run.
+Defaults to cargo kani.
+Most often, you will not need to change this.working-directory: The directory to execute the command in.
+Defaults to ..
+Useful if your repository has multiple crates, and you only want to run on one of them.args: The arguments to pass to the given ${command}.
+See cargo kani --help for a full list of options.
+Useful options include:
+--output-format=terse to generate terse output.--tests to run on proofs inside the test module (needed for running Bolero).--workspace to run on all crates within your repository.At present, Kani can used in two ways:
+kani command.cargo kani command.If you plan to integrate Kani in your projects, the recommended approach is to use cargo kani.
+If you're already using cargo, this will handle dependencies automatically, and it can be configured (if needed) in Cargo.toml.
+But kani is useful for small examples/tests.
Kani is integrated with cargo and can be invoked from a package as follows:
cargo kani [OPTIONS]
+This works like cargo test except that it will analyze all proof harnesses instead of running all test harnesses.
Common to both kani and cargo kani are many command-line flags:
--concrete-playback=[print|inplace]: Experimental, --enable-unstable feature that generates a Rust unit test case
+that plays back a failing proof harness using a concrete counterexample.
+If used with print, Kani will only print the unit test to stdout.
+If used with inplace, Kani will automatically add the unit test to the user's source code, next to the proof harness. For more detailed instructions, see the debugging verification failures section.
--visualize: Experimental, --enable-unstable feature that generates an HTML report providing traces (i.e., counterexamples) for each failure found by Kani.
--tests: Build in "test mode", i.e. with cfg(test) set and dev-dependencies available (when using cargo kani).
--harness <name>: By default, Kani checks all proof harnesses it finds.
+You can switch to checking a single harness using this flag.
--default-unwind <n>: Set a default global upper loop unwinding bound for proof harnesses.
+This can force termination when CBMC tries to unwind loops indefinitely.
Run cargo kani --help to see a complete list of arguments.
For small examples or initial learning, it's very common to run Kani on just one source file. +The command line format for invoking Kani directly is the following:
+kani filename.rs [OPTIONS]
+This will build filename.rs and run all proof harnesses found within.
Cargo.tomlUsers can add a default configuration to the Cargo.toml file for running harnesses in a package.
+Kani will extract any arguments from these sections:
[workspace.metadata.kani.flags][package.metadata.kani.flags]For example, if you want to set a default loop unwinding bound (when it's not otherwise specified), you can achieve this by adding the following lines to the package's Cargo.toml:
[package.metadata.kani.flags]
+default-unwind = 1
+The options here are the same as on the command line (cargo kani --help), and flags (that is, command line arguments that don't take a value) are enabled by setting them to true.
Starting with Rust 1.80 (or nightly-2024-05-05), every reachable #[cfg] will be automatically checked that they match the expected config names and values.
+To avoid warnings on cfg(kani), we recommend adding the check-cfg lint config in your crate's Cargo.toml as follows:
[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(kani)'] }
+For more information please consult this blog post.
+When Kani builds your code, it does two important things:
+cfg(kani).kani crate.A proof harness (which you can learn more about in the tutorial), is a function annotated with #[kani::proof] much like a test is annotated with #[test].
+But you may experience a similar problem using Kani as you would with dev-dependencies: if you try writing #[kani::proof] directly in your code, cargo build will fail because it doesn't know what the kani crate is.
This is why we recommend the same conventions as are used when writing tests in Rust: wrap your proof harnesses in cfg(kani) conditional compilation:
#[cfg(kani)]
+mod verification {
+ use super::*;
+
+ #[kani::proof]
+ pub fn check_something() {
+ // ....
+ }
+}
+This will ensure that a normal build of your code will be completely unaffected by anything Kani-related.
+This conditional compilation with cfg(kani) (as seen above) is still required for Kani proofs placed under tests/.
+When this code is built by cargo test, the kani crate is not available, and so it would otherwise cause build failures.
+(Whereas the use of dev-dependencies under tests/ does not need to be gated with cfg(test) since that code is already only built when testing.)
Running Kani on a harness produces an output that includes a set of checks as +follows:
+RESULTS:
+Check 1: example.assertion.1
+ - Status: <status>
+ - Description: <description>
+ - Location: <location>
+[...]
+Kani determines the verification result for the harness based on the
+result (i.e., <status>) of each individual check (also known as "properties"). If all
+checks are successful then the overall verification result of the harness is successful. Otherwise the
+verification fails, which indicates issues with the code under verification.
The result (or Status) of a check in Kani can be one of the following:
SUCCESS: This indicates that the check passed (i.e., the property holds).
+Note that in some cases, the property may hold vacuously. This can occur
+because the property is unreachable, or because the harness is
+over-constrained.Example:
+fn success_example() {
+ let mut sum = 0;
+ for i in 1..4 {
+ sum += i;
+ }
+ assert_eq!(sum, 6);
+}
+The output from Kani indicates that the assertion holds:
+Check 4: success_example.assertion.4
+ - Status: SUCCESS
+ - Description: "assertion failed: sum == 6"
+FAILURE: This indicates that the check failed (i.e., the property doesn't
+hold). In this case, please see the debugging verification failures
+section for more help.Example:
+fn failure_example() {
+ let arr = [1, 2, 3];
+ assert_ne!(arr.len(), 3);
+}
+The assertion doesn't hold as Kani's output indicates:
+Check 2: failure_example.assertion.2
+ - Status: FAILURE
+ - Description: "assertion failed: arr.len() != 3"
+UNREACHABLE: This indicates that the check is unreachable (i.e., the
+property holds vacuously). This occurs when there is no possible execution
+trace that can reach the check's line of code.
+This may be because the function that contains the check is unused, or because
+the harness does not trigger the condition under which the check is invoked.
+Kani currently checks reachability for the following assertion types:
+assert, assert_eq, etc.)Example:
+fn unreachable_example() {
+ let x = 5;
+ let y = x + 2;
+ if x > y {
+ assert!(x < 8);
+ }
+}
+The output from Kani indicates that the assertion is unreachable:
+Check 2: unreachable_example.assertion.2
+ - Status: UNREACHABLE
+ - Description: "assertion failed: x < 8"
+UNDETERMINED: This indicates that Kani was not able to conclude whether the
+property holds or not. This can occur when the Rust program contains a construct
+that is not currently supported by Kani. See
+Rust feature support for Kani's current support of the
+Rust language features.Example:
+fn undetermined_example() {
+ let mut x = 0;
+ unsupp(&mut x);
+ assert!(x == 0);
+}
+
+#[feature(asm)]
+fn unsupp(x: &mut u8) {
+ unsafe {
+ std::arch::asm!("nop");
+ }
+}
+
+The output from Kani indicates that the assertion is undetermined due to the +missing support for inline assembly in Kani:
+Check 2: undetermined_example.assertion.2
+ - Status: UNDETERMINED
+ - Description: "assertion failed: x == 0"
+Kani provides a kani::cover macro that can be used for checking whether a condition may occur at a certain point in the code.
The result of a cover property can be one of the following:
+SATISFIED: This indicates that Kani found an execution that triggers the specified condition.The following example uses kani::cover to check if it's possible for x and y to hold the values 24 and 72, respectively, after 3 iterations of the while loop, which turns out to be the case.
#[kani::unwind(256)]
+fn cover_satisfied_example() {
+ let mut x: u8 = kani::any();
+ let mut y: u8 = kani::any();
+ y /= 2;
+ let mut i = 0;
+ while x != 0 && y != 0 {
+ kani::cover!(i > 2 && x == 24 && y == 72);
+ if x >= y { x -= y; }
+ else { y -= x; }
+ i += 1;
+ }
+}
+Results:
+Check 1: cover_satisfied_example.cover.1
+ - Status: SATISFIED
+ - Description: "cover condition: i > 2 && x == 24 && y == 72"
+ - Location: src/main.rs:60:9 in function cover_satisfied_example
+UNSATISFIABLE: This indicates that Kani proved that the specified condition is impossible.The following example uses kani::cover to check if it's possible to have a UTF-8 encoded string consisting of 5 bytes that correspond to a string with a single character.
#[kani::unwind(6)]
+fn cover_unsatisfiable_example() {
+ let bytes: [u8; 5] = kani::any();
+ let s = std::str::from_utf8(&bytes);
+ if let Ok(s) = s {
+ kani::cover!(s.chars().count() <= 1);
+ }
+}
+which is not possible as such string will contain at least two characters.
+Check 46: cover_unsatisfiable_example.cover.1
+ - Status: UNSATISFIABLE
+ - Description: "cover condition: s.chars().count() <= 1"
+ - Location: src/main.rs:75:9 in function cover_unsatisfiable_example
+UNREACHABLE: This indicates that the cover property itself is unreachable (i.e. it is vacuously unsatisfiable).In contrast to an UNREACHABLE result for assertions, an unreachable (or an unsatisfiable) cover property may indicate an incomplete proof.
Example:
+In this example, a kani::cover call is unreachable because if the outer if condition holds, then the non-empty range r2 is strictly larger than the non-empty range r1, in which case, the condition in the inner if condition is impossible.
#[kani::unwind(6)]
+fn cover_unreachable_example() {
+ let r1: std::ops::Range<i32> = kani::any()..kani::any();
+ let r2: std::ops::Range<i32> = kani::any()..kani::any();
+ kani::assume(!r1.is_empty());
+ kani::assume(!r2.is_empty());
+ if r2.start > r1.end {
+ if r2.end < r1.end {
+ kani::cover!(r2.contains(&0));
+ }
+ }
+}
+Check 3: cover_unreachable_example.cover.1
+ - Status: UNREACHABLE
+ - Description: "cover condition: r2.contains(&0)"
+ - Location: src/main.rs:90:13 in function cover_unreachable_example
+UNDETERMINED: This is the same as the UNDETERMINED result for normal checks (see [check_results]).Kani reports a summary at the end of the verification report, which includes the overall results of all checks, the overall results of cover properties (if the package includes cover properties), and the overall verification result, e.g.:
+SUMMARY:
+ ** 0 of 786 failed (41 unreachable)
+
+ ** 0 of 1 cover properties satisfied
+
+
+VERIFICATION:- SUCCESSFUL
+++NOTE: This tutorial expects you to have followed the Kani installation instructions first.
+
This tutorial will step you through a progression from simple to moderately complex tasks with Kani. +It's meant to ensure you can get started, and see at least some simple examples of how typical proofs are structured. +It will also teach you the basics of "debugging" proof harnesses, which mainly consists of diagnosing and resolving non-termination issues with the solver.
+You may also want to read the Application section to better +understand what Kani is and how it can be applied on real code.
+Kani is unlike the testing tools you may already be familiar with. +Much of testing is concerned with thinking of new corner cases that need to be covered. +With Kani, all the corner cases are covered from the start, and the new concern is narrowing down the scope to something manageable for the verifier.
+Consider this first program (which can be found under first-steps-v1):
fn estimate_size(x: u32) -> u32 {
+ if x < 256 {
+ if x < 128 {
+ return 1;
+ } else {
+ return 3;
+ }
+ } else if x < 1024 {
+ if x > 1022 {
+ panic!("Oh no, a failing corner case!");
+ } else {
+ return 5;
+ }
+ } else {
+ if x < 2048 {
+ return 7;
+ } else {
+ return 9;
+ }
+ }
+}
+Think about the test harness you would need to write to test this function. +You would need figure out a whole set of arguments to call the function with that would exercise each branch. +You would also need to keep that test harness up-to-date with the code, in case some of the branches change. +And if this function was more complicated—for example, if some of the branches depended on global state—the test harness would be even more onerous to write.
+We can try to property test a function like this, but if we're naive about it (and consider all possible u32 inputs), then it's unlikely we'll ever find the bug.
proptest! {
+ #![proptest_config(ProptestConfig::with_cases(10000))]
+ #[test]
+ fn doesnt_crash(x: u32) {
+ estimate_size(x);
+ }
+ }
+# cargo test
+[...]
+test tests::doesnt_crash ... ok
+There's only 1 in 4 billion inputs that fail, so it's vanishingly unlikely the property test will find it, even with a million samples.
+Let's write a Kani proof harness for estimate_size.
+This is a lot like a test harness, but now we can use kani::any() to represent all possible u32 values:
#[cfg(kani)]
+#[kani::proof]
+fn check_estimate_size() {
+ let x: u32 = kani::any();
+ estimate_size(x);
+}
+# cargo kani
+[...]
+Runtime decision procedure: 0.00116886s
+
+RESULTS:
+Check 3: estimate_size.assertion.1
+ - Status: FAILURE
+ - Description: "Oh no, a failing corner case!"
+[...]
+VERIFICATION:- FAILED
+Kani has immediately found a failure.
+Notably, we haven't had to write explicit assertions in our proof harness: by default, Kani will find a host of erroneous conditions which include a reachable call to panic or a failing assert.
+If Kani had run successfully on this harness, this amounts to a mathematical proof that there is no input that could cause a panic in estimate_size.
By default, Kani only reports failures, not how the failure happened.
+In this running example, it seems obvious what we're interested in (the value of x that caused the failure) because we just have one unknown input at the start (similar to the property test), but that's kind of a special case.
+In general, understanding how a failure happened requires exploring a full (potentially large) execution trace.
An execution trace is a record of exactly how a failure can occur.
+Nondeterminism (like a call to kani::any(), which could return any value) can appear in the middle of its execution.
+A trace is a record of exactly how execution proceeded, including concrete choices (like 1023) for all of these nondeterministic values.
To get a trace for a failing check in Kani, run:
+cargo kani --visualize --enable-unstable
+This command runs Kani and generates an HTML report that includes a trace. +Open the report with your preferred browser. +Under the "Errors" heading, click on the "trace" link to find the trace for this failure.
+From this trace report, we can filter through it to find relevant lines.
+A good rule of thumb is to search for either kani::any() or assignments to variables you're interested in.
+At present time, an unfortunate amount of generated code is present in the trace.
+This code isn't a part of the Rust code you wrote, but is an internal implementation detail of how Kani runs proof harnesses.
+Still, searching for kani::any() quickly finds us these lines:
let x: u32 = kani::any();
+x = 1023u
+Here we're seeing the line of code and the value assigned in this particular trace. +Like property testing, this is just one example of a failure. +To proceed, we recommend fixing the code to avoid this particular issue and then re-running Kani to see if you find more issues.
+We put an explicit panic in this function, but it's not the only kind of failure Kani will find. +Try a few other types of errors.
+For example, instead of panicking we could try explicitly dereferencing a null pointer:
+unsafe { return *(0 as *const u32) };
+Notably, however, the Rust compiler emits a warning here:
+warning: dereferencing a null pointer
+ --> src/lib.rs:10:29
+ |
+10 | unsafe { return *(0 as *const u32) };
+ | ^^^^^^^^^^^^^^^^^^ this code causes undefined behavior when executed
+ |
+ = note: `#[warn(deref_nullptr)]` on by default
+Still, it's just a warning, and we can run the code without test failures just as before. +But Kani still catches the issue:
+[...]
+RESULTS:
+[...]
+Check 2: estimate_size.pointer_dereference.1
+ - Status: FAILURE
+ - Description: "dereference failure: pointer NULL"
+[...]
+VERIFICATION:- FAILED
+Exercise: Can you find an example where the Rust compiler will not complain, and Kani will?
+return 1 << x;
+Overflow (in addition, multiplication or, in this case, bit-shifting by too much) is also caught by Kani:
+RESULTS:
+[...]
+Check 1: estimate_size.assertion.1
+ - Status: FAILURE
+ - Description: "attempt to shift left with overflow"
+
+Check 3: estimate_size.undefined-shift.1
+ - Status: FAILURE
+ - Description: "shift distance too large"
+[...]
+VERIFICATION:- FAILED
+It seems a bit odd that our example function is tested against billions of possible inputs, when it really only seems to be designed to handle a few thousand.
+Let's encode this fact about our function by asserting some reasonable upper bound on our input, after we've fixed our bug.
+(New code available under first-steps-v2):
fn estimate_size(x: u32) -> u32 {
+ assert!(x < 4096);
+
+ if x < 256 {
+ if x < 128 {
+ return 1;
+ } else {
+ return 3;
+ }
+ } else if x < 1024 {
+ if x > 1022 {
+ return 4;
+ } else {
+ return 5;
+ }
+ } else {
+ if x < 2048 {
+ return 7;
+ } else {
+ return 9;
+ }
+ }
+}
+Now we've explicitly stated our previously implicit expectation: this function should never be called with inputs that are too big. +But if we attempt to verify this modified function, we run into a problem:
+[...]
+RESULTS:
+[...]
+Check 3: estimate_size.assertion.1
+ - Status: FAILURE
+ - Description: "assertion failed: x < 4096"
+[...]
+VERIFICATION:- FAILED
+What we want is a precondition for estimate_size.
+That is, something that should always be true every time we call the function.
+By putting the assertion at the beginning, we ensure the function immediately fails if that expectation is not met.
But our proof harness will still call this function with any integer, even ones that just don't meet the function's preconditions. +That's... not a useful or interesting result. +We know that won't work already. +How do we go back to successfully verifying this function?
+This is the purpose of writing a proof harness. +Much like property testing (which would also fail in this assertion), we need to set up our preconditions, call the function in question, then assert our postconditions. +Here's a revised example of the proof harness, one that now succeeds:
+#[cfg(kani)]
+#[kani::proof]
+fn verify_success() {
+ let x: u32 = kani::any();
+ kani::assume(x < 4096);
+ let y = estimate_size(x);
+ assert!(y < 10);
+}
+But now we must wonder if we've really fully tested our function. +What if we revise the function, but forget to update the assumption in our proof harness to cover the new range of inputs?
+Fortunately, Kani is able to report a coverage metric for each proof harness. +Try running:
+cargo kani --visualize --harness verify_success
+The beginning of the report includes coverage information. +Clicking through to the file will show fully-covered lines in green. +Lines not covered by our proof harness will show in red.
+Try changing the assumption in the proof harness to x < 2048.
+Now the harness won't be testing all possible cases.
+Rerun cargo kani --visualize.
+Look at the report: you'll see we no longer have 100% coverage of the function.
In this section:
+kani::any().kani --visualizekani::assume().In the last section, we saw Kani spot two major kinds of failures: assertions and panics. +If the proof harness allows some program execution that results in a panic, then Kani will report that as a failure. +In addition, we saw (very briefly) a couple of other kinds of failures: null pointer dereferences and overflows. +In this section, we're going to expand on these additional checks, to give you an idea of what other problems Kani will find.
+Rust is safe by default, and so includes dynamic (run-time) bounds checking where needed. +Consider this Rust code (available here):
+/// Wrap "too-large" indexes back into a valid range for the array
+fn get_wrapped(i: usize, a: &[u32]) -> u32 {
+ if a.len() == 0 {
+ return 0;
+ }
+ return a[i % a.len() + 1];
+}
+We can again write a simple property test against this code:
+ proptest! {
+ #[test]
+ fn doesnt_crash(i: usize, a: Vec<u32>) {
+ get_wrapped(i, &a);
+ }
+ }
+This property test will immediately find a failing case, thanks to Rust's built-in bounds checking.
+But what if we change this function to use unsafe Rust?
+return unsafe { *a.get_unchecked(i % a.len() + 1) };
+Now the error becomes invisible to this test:
+# cargo test
+[...]
+test bounds_check::tests::doesnt_crash ... ok
+The property test still causes an out-of-bounds access, but this undefined behavior does not necessarily cause an immediate crash. +(This is part of why undefined behavior is so difficult to debug.) +Through the use of unsafe code, we removed the runtime check for an out of bounds access. +It just turned out that none of the randomly generated tests triggered behavior that actually crashed. +But if we write a Kani proof harness:
+#[cfg(kani)]
+#[kani::proof]
+fn bound_check() {
+ let size: usize = kani::any();
+ kani::assume(size < 4096);
+ let index: usize = kani::any();
+ let array: Vec<u32> = vec![0; size];
+ get_wrapped(index, &array);
+}
+And run this proof with:
+cargo kani --harness bound_check
+We still see a failure from Kani, even without Rust's runtime bounds checking.
+++Also, notice there were many checks in the verification output. +(At time of writing, 351.) +This is a result of using the standard library
+Vecimplementation, which means our harness actually used quite a bit of code, short as it looks. +Kani is inserting a lot more checks than appear as asserts in our code, so the output can be large.
We get the following summary at the end:
+SUMMARY:
+ ** 1 of 351 failed
+Failed Checks: dereference failure: pointer outside object bounds
+ File: "./src/bounds_check.rs", line 11, in bounds_check::get_wrapped
+
+VERIFICATION:- FAILED
+Notice that, for Kani, this has gone from a simple bounds-checking problem to a pointer-checking problem. +Kani will check operations on pointers to ensure they're not potentially invalid memory accesses. +Any unsafe code that manipulates pointers will, as we see here, raise failures if its behavior is actually a problem.
+Consider trying a few more small exercises with this example:
+Having switched back to the safe indexing operation, Kani reports two failures:
+SUMMARY:
+ ** 2 of 350 failed
+Failed Checks: index out of bounds: the length is less than or equal to the given index
+ File: "./src/bounds_check.rs", line 11, in bounds_check::get_wrapped
+Failed Checks: dereference failure: pointer outside object bounds
+ File: "./src/bounds_check.rs", line 11, in bounds_check::get_wrapped
+
+VERIFICATION:- FAILED
+The first is Rust's runtime bounds checking for the safe indexing operation. +The second is Kani's check to ensure the pointer operation is actually safe. +This pattern (two checks for similar issues in safe Rust code) is common to see, and we'll see it again in the next section.
+++NOTE: While Kani will always be checking for both properties, in the future the output here may change. +You might have noticed that the bad pointer dereference can't happen, since the bounds check would panic first. +In the future, Kani's output may report only the bounds checking failure in this example.
+
Having run cargo kani --harness bound_check --visualize and clicked on one of the failures to see a trace, there are three things to immediately notice:
Vec is involved, there's a lot going on.To navigate this trace to find the information you need, we again recommend searching for things you expect to be somewhere in the trace:
+kani::any or <variable_of_interest> = such as size = or let size.
+We can use this to find out what example values lead to a problem.
+In this case, where we just have a couple of kani::any values in our proof harness, we can learn a lot just by seeing what these are.
+In this trace we find (and the values you get may be different):Step 36: Function bound_check, File src/bounds_check.rs, Line 37
+let size: usize = kani::any();
+size = 2464ul
+
+Step 39: Function bound_check, File src/bounds_check.rs, Line 39
+let index: usize = kani::any();
+index = 2463ul
+You may see different values here, as it depends on the solver's behavior.
+failure:. This will be near the end of the page.
+You can now search upwards from a failure to see what values certain variables had.
+Sometimes it can be helpful to change the source code to add intermediate variables, so their value is visible in the trace.
+For instance, you might want to compute the index before indexing into the array.
+That way you'd see in the trace exactly what value is being used.These two techniques should help you find both the nondeterministic inputs, and the values that were involved in the failing assertion.
+Consider a different variant on the function above:
+fn get_wrapped(i: usize, a: &[u32]) -> u32 {
+ return a[i % a.len()];
+}
+We've corrected the out-of-bounds access, but now we've omitted the "base case": what to return on an empty list.
+Kani will spot this not as a bound error, but as a mathematical error: on an empty list the modulus operator (%) will cause a division by zero.
get_wrapped, to see what this kind of failure looks like.Rust can also perform runtime safety checks for integer overflows, much like it does for bounds checks.
+(Though Rust disables this by default in --release mode, it can be re-enabled.)
+Consider this code (available here):
fn simple_addition(a: u32, b: u32) -> u32 {
+ return a + b;
+}
+A trivial function, but if we write a property test for it, we immediately find inputs where it fails, thanks to Rust's dynamic checks. +Kani will find these failures as well. +Here's the output from Kani:
+# cargo kani --harness add_overflow
+[...]
+SUMMARY:
+ ** 1 of 2 failed
+Failed Checks: attempt to add with overflow
+ File: "./src/overflow.rs", line 7, in overflow::simple_addition
+
+VERIFICATION:- FAILED
+This issue can be fixed using Rust's alternative mathematical functions with explicit overflow behavior.
+For instance, if the wrapping behavior is intended, you can write a.wrapping_add(b) instead of a + b.
+Kani will then report no issues.
A classic example of a subtle bug that persisted in many implementations for a very long time is "finding the midpoint" in quick sort. +This often naively looks like this (code available here):
+fn find_midpoint(low: u32, high: u32) -> u32 {
+ return (low + high) / 2;
+}
+cargo kani --harness midpoint_overflow
+Kani immediately spots the bug in the above code.
+high > low to your proof harness.
+Don't add that right away, see what happens if you don't. Just keep it in mind.)A very common approach for resolving the overflow issue looks like this:
+return low + (high - low) / 2;
+But if you naively try this (try it!), you'll find a new underflow error: high - low might result in a negative number, but has type u32.
+Hence, the need to add the assumption we suggested above, to make that impossible.
+(Adding an assumption, though, means there's a new way to "use it wrong." Perhaps we'd like to avoid that! Can you avoid the assumption?)
After that, you might wonder how to "prove your new implementation correct." +After all, what does "correct" even mean? +Often we're using a good approximation of correct, such as the equivalence of two implementations (often one much "simpler" than the other somehow). +Here's one possible assertion we could write in the proof harness:
+assert!(result as u64 == (a as u64 + b as u64) / 2);
+You might have even come up with this approach to avoiding the overflow issue in the first place! +Having two different implementations, using different approaches, but proven to yield the same results, gives us greater confidence that we compute the correct result.
+Check out Limitations for information on the checks that Kani does not perform. +Notably, Kani is not prioritizing all Rust-specific notions of undefined behavior.
+In this section:
+Consider code like this (available here):
+fn initialize_prefix(length: usize, buffer: &mut [u8]) {
+ // Let's just ignore invalid calls
+ if length > buffer.len() {
+ return;
+ }
+
+ for i in 0..=length {
+ buffer[i] = 0;
+ }
+}
+This code has an off-by-one error that only occurs on the last iteration of the loop (when called with an input that will trigger it). +We can try to find this bug with a proof harness like this:
+#[cfg(kani)]
+#[kani::proof]
+#[kani::unwind(1)] // deliberately too low
+fn check_initialize_prefix() {
+ const LIMIT: usize = 10;
+ let mut buffer: [u8; LIMIT] = [1; LIMIT];
+
+ let length = kani::any();
+ kani::assume(length <= LIMIT);
+
+ initialize_prefix(length, &mut buffer);
+}
+But we've just used a new attribute (#[kani::unwind(1)]) that requires some explanation.
+When we run cargo kani on this code as we have written it, we see an odd verification failure:
SUMMARY:
+ ** 1 of 67 failed (66 undetermined)
+Failed Checks: unwinding assertion loop 0
+
+VERIFICATION:- FAILED
+If we try removing this "unwind" annotation and re-running Kani, the result is worse: non-termination. +Kani simply doesn't produce a result.
+The problem we're struggling with is the technique Kani uses to verify code. +We're not able to handle code with "unbounded" loops, and what "bounded" means can be quite subtle. +It has to have a constant number of iterations that's "obviously constant" enough for the verifier to actually figure this out. +In practice, very few loops are like this.
+To verify programs like this with Kani as it exists today, we need to do two things:
+LIMIT of 10.kani::unwind annotation.Bounding proofs like this means we may no longer be proving as much as we originally hoped. +Who's to say, if we prove everything works up to size 10, that there isn't a novel bug lurking, reachable only with problems of size 11+? +Perhaps! +But, let's get back to the issue at hand.
+By putting #[kani::unwind(1)] on the proof harness, we've placed an upper bound of 1 loop iteration.
+The "unwinding assertion" failure that Kani reports is because this bound is not high enough.
+The code tries to execute more than 1 loop iteration.
+(And, because the unwinding isn't high enough, many of the other properties Kani is verifying become "undetermined": we don't really know if they're true or false, because we can't get far enough.)
Exercise: Try increasing the bound. Where might you start? How high do you need to go to get rid of the "unwinding assertion" failure?
+Since the proof harness is trying to limit the array to size 10, an initial unwind value of 10 seems like the obvious place to start. +But that's not large enough for Kani, and we still see the "unwinding assertion" failure.
+At size 11, the "unwinding assertion" goes away, and now we can see the actual failure we're trying to find too. +We'll explain why we see this behavior in a moment.
+Once we have increased the unwinding limit high enough, we're left with these failures:
+SUMMARY:
+ ** 1 of 68 failed
+Failed Checks: index out of bounds: the length is less than or equal to the given index
+ File: "./src/lib.rs", line 12, in initialize_prefix
+
+VERIFICATION:- FAILED
+Exercise: Fix the off-by-one error, and get the (bounded) proof to go through.
+We now return to the question: why is 11 the unwinding bound?
+Kani needs the unwinding bound to be "one more than" the number of loop iterations. +We previously had an off-by-one error that tried to do 11 iterations on an array of size 10. +So... the unwinding bound needed to be 11, then.
+++NOTE: Presently, there are some situations where "number of iterations of a loop" can be less obvious than it seems. +This can be easily triggered with use of
+breakorcontinuewithin loops. +Often this manifests itself as needing "two more" or "three more" iterations in the unwind bound than seems like it would actually run. +In those situations, we might still need a bound likekani::unwind(13), despite looking like a loop bounded to 10 iterations.
The approach we've taken here is a general method for getting a bounded proof to go through:
+LIMIT in our proof harness.
+We don't create a slice any bigger than that, and that's what we loop over.kani::unwind bound, and increase until the unwinding assertion failure goes away.The best approach to supplying Kani with unwind bounds is using the annotation kani::unwind, as we show above.
You might want to supply one via command line when experimenting, however.
+In that case you can either use --default-unwind x to set an unwind bound for every proof harness that does not have an explicit bound.
Or you can override a harness's bound, but only when running a specific harness:
+cargo kani --harness check_initialize_prefix --unwind 11
+Finally, you might be interested in defaulting the unwind bound to 1, to force termination (and force supplying a bound) on all your proof harnesses.
+You can do this by putting this into your Cargo.toml file:
[workspace.metadata.kani.flags]
+default-unwind = 1
+Before we finish, it's worth revisiting the implications of what we've done here. +Kani frequently needs to do "bounded proof", which contrasts with unbounded or full verification.
+We've written a proof harness that shows initialize_prefix has no errors on input slices of size 10, but no higher.
+The particular size we choose is usually determined by balancing the level of assurance we want, versus runtime of Kani.
+It's often not worth running proofs for large numbers of iterations, unless either very high assurance is necessary, or there's reason to suspect larger problems will contain novel failure modes.
Exercise: Try increasing the problem size (both the unwind and the LIMIT constant). When does it start to take more than a few seconds?
On your friendly neighborhood author's machine, a LIMIT of 100 takes about 3.8 seconds end-to-end.
+This is a relatively simple bit of code, though, and it's not uncommon for some proofs to scale poorly even to 5 iterations.
One consequence of this, however, is that Kani often scales poorly to "big string problems" like parsing. +Often a parser will need to consume inputs larger than 10-20 characters to exhibit strange behaviors.
+In this section:
+#[kani::unwind(1)] can help force Kani to terminate (with a verification failure).Kani is able to reason about programs and their execution paths by allowing users to create nondeterministic (also called symbolic) values using kani::any().
+Kani is a "bit-precise" model checker, which means that Kani considers all the possible bit-value combinations that would be valid if assigned to a variable's memory contents.
+In other words, kani::any() should not produce values that are invalid for the type (which would lead to Rust undefined behavior).
Out of the box, Kani includes kani::any() implementations for most primitive and some std types.
+In this tutorial, we will show how to use kani::any() to create symbolic values for other types.
Let's say you're developing an inventory management tool, and you would like to start verifying properties about your API. +Here is a simple example (available here):
+use std::num::NonZeroU32;
+use vector_map::VecMap;
+
+pub type ProductId = u32;
+
+pub struct Inventory {
+ /// Every product in inventory must have a non-zero quantity
+ pub inner: VecMap<ProductId, NonZeroU32>,
+}
+
+impl Inventory {
+ pub fn update(&mut self, id: ProductId, new_quantity: NonZeroU32) {
+ self.inner.insert(id, new_quantity);
+ }
+
+ pub fn get(&self, id: &ProductId) -> Option<NonZeroU32> {
+ self.inner.get(id).cloned()
+ }
+}
+Let's write a fairly simple proof harness, one that just ensures we successfully get the value we inserted with update:
#[kani::proof]
+ #[kani::unwind(3)]
+ pub fn safe_update() {
+ // Empty to start
+ let mut inventory = Inventory { inner: VecMap::new() };
+
+ // Create non-deterministic variables for id and quantity.
+ let id: ProductId = kani::any();
+ let quantity: NonZeroU32 = kani::any();
+ assert!(quantity.get() != 0, "NonZeroU32 is internally a u32 but it should never be 0.");
+
+ // Update the inventory and check the result.
+ inventory.update(id, quantity);
+ assert!(inventory.get(&id).unwrap() == quantity);
+ }
+We use kani::any() twice here:
id has type ProductId which was actually just a u32, and so any value is fine.quantity, however, has type NonZeroU32.
+In Rust, it would be undefined behavior to have a value of 0 for this type.We included an extra assertion that the value returned by kani::any() here was actually non-zero.
+If we run this, you'll notice that verification succeeds.
cargo kani --harness safe_update
+kani::any() is safe Rust, and so Kani only implements it for types where type invariants are enforced.
+For NonZeroU32, this means we never return a 0 value.
+The assertion we wrote in this harness was just an extra check we added to demonstrate this fact, not an essential part of the proof.
While kani::any() is the only method Kani provides to inject non-determinism into a proof harness, Kani only ships with implementations for a few std types where we can guarantee safety.
+When you need nondeterministic variables of types that don't have a kani::any() implementation available, you have the following options:
kani::Arbitrary trait for your type, so you and downstream crates can use kani::any() with your type.bolero_generator::TypeGenerator trait.
+This will enable you and downstream crates to use Kani via Bolero.We recommend the first approach for most cases.
+The first approach is simple and conventional. This option will also enable you to use it with parameterized types, such as Option<MyType> and arrays.
+Kani includes a derive macro that allows you to automatically derive kani::Arbitrary for structures and enumerations as long as all its fields also implement the kani::Arbitrary trait.
+One downside of this approach today is that the kani crate ships with Kani, but it's not yet available on crates.io.
+So you need to annotate the Arbitrary implementation with a #[cfg(kani)] attribute.
+For the derive macro, use #[cfg_attr(kani, derive(kani::Arbitrary))].
The second approach is recommended for cases where you would also like to be able to apply fuzzing or property testing.
+The benefits of doing so were described in this blog post.
+Like kani::Arbitrary, this trait can also be used with a derive macro.
+One thing to be aware of is that this type allow users to generate arbitrary values that include pointers.
+In those cases, only the values pointed to are arbitrary, not the pointers themselves.
Finally, the last approach is recommended when you need to pass in parameters, like bounds on the size of the data structure. +(Which we'll discuss more in the next section.) +This approach is also necessary when you need to generate a nondeterministic variable of a type that you're importing from another crate, since Rust doesn't allow you to implement a trait defined in an external crate for a type that you don't own.
+Either way, inside this function you would simply return an arbitrary value by generating arbitrary values for its components. +To generate a nondeterministic struct, you would just generate nondeterministic values for each of its fields. +For complex data structures like vectors or other containers, you can start with an empty one and add a (bounded) nondeterministic number of entries.
+For example, for a simple enum you can just annotate it with the Arbitrary derive attribute:
+#[derive(Copy, Clone)]
+#[cfg_attr(kani, derive(kani::Arbitrary))]
+pub enum Rating {
+ One,
+ Two,
+ Three,
+}
+But if the same enum is defined in an external crate, you can use a simple trick:
+ pub fn any_rating() -> Rating {
+ match kani::any() {
+ 0 => Rating::One,
+ 1 => Rating::Two,
+ _ => Rating::Three,
+ }
+ }
+All we're doing here is making use of a nondeterministic integer to decide which variant of Rating to return.
++NOTE: If we thought of this code as generating a random value, this function looks heavily biased. +We'd overwhelmingly generate a
+Threebecause it's matching "all other integers besides 1 and 2." +But Kani just see 3 meaningful possibilities, each of which is not treated any differently from each other. +The "proportion" of integers does not matter.
You can use kani::any() for [T; N] (if implemented for T) because this array type has an exact and constant size.
+But if you wanted a slice ([T]) up to size N, you can no longer use kani::any() for that.
+Likewise, there is no implementation of kani::any() for more complex data structures like Vec.
The trouble with a nondeterministic vector is that you usually need to bound the size of the vector, for the reasons we investigated in the last chapter.
+The kani::any() function does not have any arguments, and so cannot be given an upper bound.
This does not mean you cannot have a nondeterministic vector.
+It just means you have to construct one.
+Our example proof harness above constructs a nondeterministic Inventory of size 1, simply by starting with the empty Inventory and inserting a nondeterministic entry.
Try writing a function to generate a (bounded) nondeterministic inventory (from the first example:)
+fn any_inventory(bound: u32) -> Inventory {
+ // fill in here
+}
+One thing you'll quickly find is that the bounds must be very small.
+Kani does not (yet!) scale well to nondeterministic-size data structures involving heap allocations.
+A proof harness like safe_update above, but starting with any_inventory(2) will probably take a couple of minutes to prove.
A hint for this exercise: you might choose two different behaviors, "size of exactly bound" or "size up to bound".
+Try both!
A solution can be found in exercise_solution.rs.
In this section:
+kani::any() will return "safe" values for each of the types Kani implements it for.kani::Arbitrary or just write a function to create nondeterministic values for other types.kani::any() as they need a bound on their size.Inventory.When the result of a certain check comes back as a FAILURE,
+Kani offers different options to help debug:
--concrete-playback. This experimental feature generates a Rust unit test case that plays back a failing
+proof harness using a concrete counterexample.--visualize. This feature generates an HTML text-based trace that
+enumerates the execution steps leading to the check failure.When concrete playback is enabled, Kani will generate unit tests for assertions that failed during verification, +as well as cover statements that are reachable.
+These tests can then be executed using Kani's playback subcommand.
+In order to enable this feature, run Kani with the -Z concrete-playback --concrete-playback=[print|inplace] flag.
+After getting a verification failure, Kani will generate a Rust unit test case that plays back a failing
+proof harness with a concrete counterexample.
+The concrete playback modes mean the following:
print: Kani will just print the unit test to stdout.
+You will then need to copy this unit test into the same module as your proof harness.
+This is also helpful if you just want to quickly find out which values were assigned by kani::any() calls.inplace: Kani will automatically copy the unit test into your source code.
+Before running this mode, you might find it helpful to have your existing code committed to git.
+That way, you can easily remove the unit test with git revert.
+Note that Kani will not copy the unit test into your source code if it detects
+that the exact same test already exists.After the unit test is in your source code, you can run it with the playback subcommand.
+To debug it, there are a couple of options:
To manually compile and run the test, you can use Kani's playback subcommand:
cargo kani playback -Z concrete-playback -- ${unit_test_func_name}
+The output from this command is similar to cargo test.
+The output will have a line in the beginning like
+Running unittests {files} ({binary}).
You can further debug the binary with tools like rust-gdb or lldb.
Running kani -Z concrete-playback --concrete-playback=print on the following source file:
#[kani::proof]
+fn proof_harness() {
+ let a: u8 = kani::any();
+ let b: u16 = kani::any();
+ assert!(a / 2 * 2 == a &&
+ b / 2 * 2 == b);
+}
+yields a concrete playback Rust unit test similar to the one below:
+#[test]
+fn kani_concrete_playback_proof_harness_16220658101615121791() {
+ let concrete_vals: Vec<Vec<u8>> = vec![
+ // 133
+ vec![133],
+ // 35207
+ vec![135, 137],
+ ];
+ kani::concrete_playback_run(concrete_vals, proof_harness);
+}
+Here, 133 and 35207 are the concrete values that, when substituted for a and b,
+cause an assertion failure.
+vec![135, 137] is the byte array representation of 35207.
This feature is experimental and is therefore subject to change. +If you have ideas for improving the user experience of this feature, +please add them to this GitHub issue. +We are tracking the existing feature requests in +this GitHub milestone.
+This section is the main reference for Kani. +It contains sections that informally describe its main features.
+In Kani, attributes are used to mark functions as harnesses and control their execution. +This section explains the attributes available in Kani and how they affect the verification process.
+At present, the available Kani attributes are the following:
+#[kani::proof]#[kani::should_panic]#[kani::unwind(<number>)]#[kani::solver(<solver>)]#[kani::stub(<original>, <replacement>)]#[kani::proof]The #[kani::proof] attribute specifies that a function is a proof harness.
Proof harnesses are similar to test harnesses, especially property-based test harnesses,
+and they may use functions from the Kani API (e.g., kani::any()).
+A proof harness is the smallest verification unit in Kani.
When Kani is run, either through kani or cargo kani, it'll first collect all proof harnesses
+(i.e., functions with the attribute #[kani::proof]) and then attempt to verify them.
If we run Kani on this example:
+#[kani::proof]
+fn my_harness() {
+ assert!(1 + 1 == 2);
+}
+We should see a line in the output that says Checking harness my_harness... (assuming my_harness is the only harness in our code).
+This will be followed by multiple messages that come from CBMC (the verification engine used by Kani) and the verification results.
Using any other Kani attribute without #[kani::proof] will result in compilation errors.
The #[kani::proof] attribute can only be added to functions without parameters.
#[kani::should_panic]The #[kani::should_panic] attribute specifies that a proof harness is expected to panic.
This attribute allows users to exercise negative verification.
+It's analogous to how #[should_panic] allows users to exercise negative testing for Rust unit tests.
This attribute only affects the overall verification result.
+In particular, using the #[kani::should_panic] attribute will return one of the following results:
VERIFICATION:- FAILED (encountered no panics, but at least one was expected) if there were no failed checks.VERIFICATION:- FAILED (encountered failures other than panics, which were unexpected) if there were failed checks but not all them were related to panics.VERIFICATION:- SUCCESSFUL (encountered one or more panics as expected) otherwise.At the moment, to determine if a check is related to a panic, we check if its class is assertion.
+The class is the second member in the property name, the triple that's printed after Check X: : <function>.<class>.<number>.
+For example, the class in Check 1: my_harness.assertion.1 is assertion, so this check is considered to be related to a panic.
++NOTE: The
+#[kani::should_panic]is only recommended for writing +harnesses which complement existing harnesses that don't use the same +attribute. In order words, it's only recommended to write negative harnesses +after having written positive harnesses that successfully verify interesting +properties about the function under verification.
The #[kani::should_panic] attribute verifies that there are one or more failed checks related to panics.
+At the moment, it's not possible to pin it down to specific panics.
+Therefore, it's possible that the panics detected with #[kani::should_panic] aren't the ones that were originally expected after a change in the code under verification.
Let's assume we're using the Device from this example:
struct Device {
+ is_init: bool,
+}
+
+impl Device {
+ fn new() -> Self {
+ Device { is_init: false }
+ }
+
+ fn init(&mut self) {
+ assert!(!self.is_init);
+ self.is_init = true;
+ }
+}
+We may want to verify that calling device.init() more than once should result in a panic.
+We can do so with the following harness:
#[kani::proof]
+#[kani::should_panic]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+Running Kani on it will produce the result VERIFICATION:- SUCCESSFUL (encountered one or more panics as expected)
#[kani::unwind(<number>)]The #[kani::unwind(<number>)] attribute specifies that all loops must be unwound up to <number> times.
By default, Kani attempts to unwind all loops automatically.
+However, this unwinding process doesn't always terminate.
+The #[kani::unwind(<number>)] attribute will:
<number> times.After the unwinding stage, Kani will attempt to verify the harness.
+If the #[kani::unwind(<number>)] attribute was specified, there's a chance that one or more loops weren't unwound enough times.
+In that case, there will be at least one failed unwinding assertion (there's one unwinding assertion for each loop), causing verification to fail.
Check the Loops, unwinding and bounds section for more information about unwinding.
+Let's assume we've written this code which contains a loop:
+fn my_sum(vec: &Vec<u32>) -> u32 {
+ let mut sum = 0;
+ for elem in vec {
+ sum += elem;
+ }
+ sum
+}
+
+#[kani::proof]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+Running this example on Kani will produce a successful verification result.
+In this case, Kani automatically finds the required unwinding value (i.e., the number of times it needs to unwind all loops).
+This means that the #[kani::unwind(<number>)] attribute isn't needed, as we'll see soon.
+In general, the required unwinding value is equal to the maximum number of iterations for all loops, plus one.
+The required unwinding value in this example is 4: the 3 iterations in the for elem in vec loop, plus 1.
Let's see what happens if we force a lower unwinding value with #[kani::unwind(3)]:
#[kani::proof]
+#[kani::unwind(3)]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+As we mentioned, trying to verify this harness causes an unwinding failure:
+SUMMARY:
+ ** 1 of 187 failed (186 undetermined)
+Failed Checks: unwinding assertion loop 0
+ File: "/home/ubuntu/devices/src/main.rs", line 32, in my_sum
+
+VERIFICATION:- FAILED
+[Kani] info: Verification output shows one or more unwinding failures.
+[Kani] tip: Consider increasing the unwinding value or disabling `--unwinding-assertions`.
+Kani cannot verify the harness because there is at least one unwinding assertion failure.
+But, if we use #[kani::unwind(4)], which is the right unwinding value we computed earlier:
#[kani::proof]
+#[kani::unwind(4)]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+We'll get a successful result again:
+SUMMARY:
+ ** 0 of 186 failed
+
+VERIFICATION:- SUCCESSFUL
+#[kani::solver(<solver>)]Changes the solver to be used by Kani's verification engine (CBMC).
+This may change the verification time required to verify a harness.
+At present, <solver> can be one of:
minisat: MiniSat.cadical (default): CaDiCaL.kissat: kissat.bin="<SAT_SOLVER_BINARY>": A custom solver binary, "<SAT_SOLVER_BINARY>", that must be in path.Kani will use the CaDiCaL solver in the following example:
+#[kani::proof]
+#[kani::solver(cadical)]
+fn check() {
+ let mut a = [2, 3, 1];
+ a.sort();
+ assert_eq!(a[0], 1);
+ assert_eq!(a[1], 2);
+ assert_eq!(a[2], 3);
+}
+Changing the solver may result in different verification times depending on the harness.
+Note that the default solver may vary depending on Kani's version. +We highly recommend users to annotate their harnesses if the choice of solver +has a major impact on performance, even if the solver used is the current +default one.
+#[kani::stub(<original>, <replacement>)]Replaces the function/method with name
Check the Stubbing section for more information about stubbing.
+Stubbing (or mocking) is an unstable feature which allows users to specify that certain items should be replaced with stubs (mocks) of those items during verification. +At present, the only items where stubbing can be applied are functions and methods (see limitations for more details).
+In general, we have identified three reasons where users may consider stubbing:
+In most cases, stubbing enables users to verify code that otherwise would be impractical to verify. +Although definitions for mocking (normally used in testing) and stubbing may slightly differ depending on who you ask, we often use both terms interchangeably.
+The stubbing feature can be enabled by using the --enable-stubbing option when calling Kani.
+Since it's an unstable feature, it requires passing the --enable-unstable option in addition to --enable-stubbing.
At present, the only component of the stubbing feature is the #[kani::stub(<original>, <replacement>)] attribute,
+which allows you to specify the pair of functions/methods that must be stubbed in a harness.
#[kani::stub(...)] attributeThe stub attribute #[kani::stub(<original>, <replacement>)] is the main tool of the stubbing feature.
It indicates to Kani that the function/method with name <original> should be replaced with the function/method with name <replacement> during the compilation step.
+The names of these functions/methods are resolved using Rust's standard name resolution rules.
+This includes support for imports like use foo::bar as baz, as well as imports of multiple versions of the same crate.
This attribute must be specified on a per-harness basis. This provides a high degree of flexibility for users, since they are given the option to stub the same item with different replacements (or not use stubbing at all) depending on the proof harness. In addition, the attribute can be specified multiple times per harness, so that multiple (non-conflicting) stub pairings are supported.
+randomLet's see a simple example where we use the rand::random function
+to generate an encryption key.
#[cfg(kani)]
+#[kani::proof]
+fn encrypt_then_decrypt_is_identity() {
+ let data: u32 = kani::any();
+ let encryption_key: u32 = rand::random();
+ let encrypted_data = data ^ encryption_key;
+ let decrypted_data = encrypted_data ^ encryption_key;
+ assert_eq!(data, decrypted_data);
+}
+
+At present, Kani fails to verify this example due to issue #1781.
+However, we can work around this limitation thanks to the stubbing feature:
+#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(rand::random, mock_random)]
+fn encrypt_then_decrypt_is_identity() {
+ let data: u32 = kani::any();
+ let encryption_key: u32 = rand::random();
+ let encrypted_data = data ^ encryption_key;
+ let decrypted_data = encrypted_data ^ encryption_key;
+ assert_eq!(data, decrypted_data);
+}
+Here, the #[kani::stub(rand::random, mock_random)] attribute indicates to Kani that it should replace rand::random with the stub mock_random.
+Note that this is a fair assumption to do: rand::random is expected to return any u32 value, just like kani::any.
Now, let's run it through Kani:
+cargo kani --enable-unstable --enable-stubbing --harness encrypt_then_decrypt_is_identity
+The verification result is composed of a single check: the assertion corresponding to assert_eq!(data, decrypted_data).
RESULTS:
+Check 1: encrypt_then_decrypt_is_identity.assertion.1
+ - Status: SUCCESS
+ - Description: "assertion failed: data == decrypted_data"
+ - Location: src/main.rs:18:5 in function encrypt_then_decrypt_is_identity
+
+
+SUMMARY:
+ ** 0 of 1 failed
+
+VERIFICATION:- SUCCESSFUL
+Kani shows that the assertion is successful, avoiding any issues that appear if we attempt to verify the code without stubbing.
+In the following, we describe all the limitations of the stubbing feature.
+The usage of stubbing is limited to the verification of a single harness.
+Therefore, users are required to pass the --harness option when using the stubbing feature.
In addition, this feature isn't compatible with concrete playback.
+Support for stubbing is currently limited to functions and methods. All other items aren't supported.
+The following are examples of items that could be good candidates for stubbing, but aren't supported:
+We acknowledge that support for method stubbing isn't as ergonomic as it could be.
+A common problem when attempting to define method stubs is that we don't have access to the private fields of an object (i.e., the fields in self).
+One workaround is to use the unsafe function std::mem::transmute, as in this example:
struct Foo {
+ x: u32,
+}
+
+impl Foo {
+ pub fn m(&self) -> u32 {
+ 0
+ }
+}
+
+struct MockFoo {
+ pub x: u32,
+}
+
+fn mock_m(foo: &Foo) -> u32 {
+ let mock: &MockFoo = unsafe { std::mem::transmute(foo) };
+ return mock.x;
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(Foo::m, mock_m)]
+fn my_harness() { ... }
+However, this isn't recommended since it's unsafe and error-prone. +In general, we don't recommend stubbing for private functions/methods. +Doing so can lead to brittle proofs: private functions/methods are subject to change or removal even in version minor upgrades (they aren't part of the APIs). +Therefore, proofs that rely on stubbing for private functions/methods might incur a high maintenance burden.
+Given a set of original-replacement pairs, Kani will exit with an error if:
original function does not exist;replacement stub does not exist;original function is mapped to multiple replacement functions); orreplacement stub is not compatible with the signature of the original function/method (see next section).We consider a stub and a function/method to be compatible if all the following conditions are met:
+bar<A, B>(x: A, y: B) -> B is considered to have a type compatible with the function foo<S, T>(x: S, y: T) -> T.The final point is the most subtle. +We don't require that a type parameter in the signature of the stub implements the same traits as the corresponding type parameter in the signature of the original function/method. +However, Kani will reject a stub if a trait mismatch leads to a situation where a statically dispatched call to a trait method cannot be resolved during monomorphization. +For example, this restriction rules out the following harness:
+fn foo<T>(_x: T) -> bool {
+ false
+}
+
+trait DoIt {
+ fn do_it(&self) -> bool;
+}
+
+fn bar<T: DoIt>(x: T) -> bool {
+ x.do_it()
+}
+
+#[kani::proof]
+#[kani::stub(foo, bar)]
+fn harness() {
+ assert!(foo("hello"));
+}
+The call to the trait method DoIt::do_it is unresolvable in the stub bar when the type parameter T is instantiated with the type &str.
+On the other hand, this approach provides some flexibility, such as allowing our earlier example of mocking rand::random:
+both rand::random and my_random have type () -> T, but in the first case T is restricted such that the type Standard implements Distribution<T>,
+whereas in the latter case T has to implement kani::Arbitrary.
+This trait mismatch is allowed because at this call site T is instantiated with u32, which implements kani::Arbitrary.
You may be interested in applying Kani if you're in this situation:
+++If you haven't already, we also recommend techniques like property testing and fuzzing (e.g. with
+bolero). +These yield good results, are very cheap to apply, and are often easy to adopt and debug.
In this section, we explain how Kani compares with other tools +and suggest where to start applying Kani in real code.
+Fuzzing (for example, with cargo-fuzz) is a unguided approach to random testing.
+A fuzzer generally provides an input of random bytes, and then examines fairly generic properties (such as "doesn't crash" or "commit undefined behavior") about the resulting program.
Fuzzers generally get their power through a kind of evolutionary algorithm that rewards new mutant inputs that "discover" new branches of the program under test. +Fuzzers are excellent for testing security boundaries, precisely because they make no validity assumptions (hence, they are "unguided") when generating the input.
+Property testing (for example, with Proptest) is a guided approach to random testing. +"Guided" in the sense that the test generally provides a strategy for generating random values that constrains their range. +The purpose of this strategy is to either focus on interesting values, or avoid failing assertions that only hold for a constrained set of inputs. +Tests in this style do actually state properties: For all inputs (of some constrained kind), this condition should hold.
+Property testing is often quite effective, but the engine can't fully prove the property: It can only sample randomly a few of those values to test (though property testing libraries frequently give interesting "edge cases" a higher probability, making them more effective at bug-finding).
+Model checking is similar to these techniques in how you use them, but it's non-random and exhaustive (though often only up to some bound on input or problem size). +Thus, properties checked with a model checker are effectively proofs. +Instead of naively trying all possible concrete inputs (which could be infeasible and blow up exponentially), model checkers like Kani will cleverly encode program traces as symbolic "SAT/SMT" problems, and hand them off to SAT/SMT solvers. +SAT/SMT solving is an NP-complete problem, but many practical programs can be model-checked within milliseconds to seconds (with notable exceptions: you can easily try to reverse a cryptographic hash with a model checker, but good luck getting it to terminate!)
+Model checking allows you to prove non-trivial properties about programs, and check those proofs in roughly the same amount of time as a traditional test suite would take to run. +The downside is many types of properties can quickly become "too large" to practically model-check, and so writing "proof harnesses" (very similar to property tests and fuzzer harnesses) requires some skill to understand why the solver is not terminating and fix the structure of the problem you're giving it so that it does. +This process basically boils down to "debugging" the proof.
+At present, Kani does not support verifying concurrent code. +Two tools of immediate interest are Loom and Shuttle. +Loom attempts to check all possible interleavings, while Shuttle chooses interleavings randomly. +The former is sound (like Kani), but the latter is more scalable to large problem spaces (like property testing).
+The Rust Formal Methods Interest Group maintains a list of interesting Rust verification tools.
+It can be daunting to find the right place to start writing proofs for a real-world project. +This section will try to help you get over that hurdle.
+In general, you're trying to do three things:
+By far, the best strategy is to follow your testing. +Places where proof will be valuable are often places where you've written a lot of tests, because they're valuable there for the same reasons. +Likewise, code structure changes to make functions more unit-testable will also make functions more amenable to proof. +Often, by examining existing unit tests (and especially property tests), you can easily find a relatively self-contained function that's a good place to start.
+Where complicated things happen with untrusted user input. +These are often the critical "entry points" into the code. +These are also places where you probably want to try other techniques (e.g., fuzz testing).
+Where unsafe is used extensively.
+These are often places where you'll already have concentrated a lot of tests.
Where you have a complicated implementation that accomplishes a much simpler abstract problem. +Ideal places for property testing, if you haven't tried that already. +But the usual style of property tests you often write here (generate large random lists of operations, then compare between concrete and abstract model) won't be practical to directly port to model checking.
+Where normal testing "smells" intractable.
+Find crates or files with smaller lists of dependencies. +Dependencies can sometimes blow up the tractability of proofs. +This can usually be handled, but requires a lot more investment to make it happen, and so isn't a good place to start.
+Don't forget to consider starting with your dependencies. +Sometimes the best place to start won't be your code, but the code that you depend on. +If it's used by more projects that just yours, it will be valuable to more people, too!
+Find well-tested code. +When you make changes to improve the unit-testability of code, that also makes it more amenable to proof, too.
+Here are some things to avoid, when starting out:
+Lots of loops, or at least nested loops. +As we saw in the tutorial, right now we often need to put upper bounds on loops to make more limited claims.
+Inductive data structures. +These are data structures with unbounded size (e.g., linked lists or trees.) +These can be hard to model since you need to set bounds on their size, similar to what happens with loops.
+Input/Output code. +Kani doesn't model I/O, so if your code depends on behavior like reading/writing to a file, you won't be able to prove anything. +This is one obvious area where testability helps provability: often we separate I/O and "pure" computation into different functions, so we can unit-test the latter.
+Deeper call graphs. +Functions that call a lot of other functions can require more investment to make tractable. +They may not be a good starting point.
+Significant global state. +Rust tends to discourage this, but it still exists in some forms.
+A first proof will likely start in the following form:
+Running Kani on this simple starting point will help figure out:
+kani::assume) to avoid "expected" failures.--visualize. Ideally you'd see 100% coverage, and if not, it's usually because you've assumed too much (thus over-constraining the inputs).#[kani::unwind(1)] to force early termination and work up from there.)Once you've got something working, the next step is to prove more interesting properties than just what Kani covers by default. +You accomplish this by adding new assertions (not just in your harness, but also to the code being run). +Even if a proof harness has no post-conditions being asserted directly, the assertions encountered along the way can be meaningful proof results by themselves.
+On the Kani blog, we've documented worked examples of applying Kani:
+Rectangle example of the Rust BookKani is an open source project open to external contributions.
+The easiest way to contribute is to report any +issue you encounter +while using the tool. If you want to contribute to its development, +we recommend looking into these issues.
+In this chapter, we provide documentation that might be helpful for Kani +developers (including external contributors):
+cbmc.rustc.++NOTE: The developer documentation is intended for Kani developers and not +users. At present, the project is under heavy development and some items +discussed in this documentation may stop working without notice (e.g., commands +or configurations). Therefore, we recommend users to not rely on them.
+
We automate most of our formatting preferences. Our CI will run format checkers for PRs and pushes. +These checks are required for merging any PR.
+For Rust, we use rustfmt
+which is configured via the rustfmt.toml file.
+We are also in the process of enabling clippy.
+Because of that, we still have a couple of lints disabled (see .cargo/config for the updated list).
We also have a bit of C and Python code in our repository.
+For C we use clang-format and for Python scripts we use autopep8.
+See .clang-format
+and pyproject.toml
+for their configuration.
We recognize that in some cases, the formatting and lints automation may not be applicable to a specific code.
+In those cases, we usually prefer explicitly allowing exceptions by locally disabling the check.
+E.g., use #[allow] annotation instead of disabling a link on a crate or project level.
All source code files begin with a copyright and license notice. If this is a new file, please add the following notice:
+// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+When modifying a file from another project, please keep their headers as is and append the following notice after them:
+// ... existing licensing headers ...
+
+// Modifications Copyright Kani Contributors
+// See GitHub history for details.
+Note: The comment escape characters will depend on the type of file you are working with. E.g.: For rust start the
+header with //, but for python start with #.
We also have automated checks for the copyright notice. +There are a few file types where this rule doesn't apply. +You can see that list in the copyright-exclude file.
+We are developing Kani to provide assurance that critical Rust components are verifiably free of certain classes of +security and correctness issues. +Thus, it is critical that we provide a verification tool that is sound. +For the class of errors that Kani can verify, we should not produce a "No Error" result if there was in fact an +error in the code being verified, i.e., it has no +"False Negatives".
+Because of that, we bias on the side of correctness. +Any incorrect modeling +that may trigger an unsound analysis that cannot be fixed in the short term should be mitigated. +Here are a few ways how we do that.
+Make sure to add user-friendly errors for constructs that we can't handle. +For example, Kani cannot handle the panic unwind strategy, and it will fail compilation if the crate uses this +configuration.
+In general, it's preferred that error messages follow these guidelines used for rustc development.
+If the errors are being emitted from kani-compiler, you should use the compiler error message utilities (e.g., the Session::span_err method). However, if the
+errors are being emitted from kani-driver, you should use the functions provided in the util module in kani-driver.
Even though this doesn't provide users the best experience, you are encouraged to add checks in the compiler for any
+assumptions you make during development.
+Those checks can be on the form of assert!() or unreachable!()
+statement.
+Please provide a meaningful message to help user understand why something failed, and try to explain, at least with
+a comment, why this is the case.
We don't formally use any specific formal representation of function contract, +but whenever possible we do instrument the code with assertions that may represent the function pre- and +post-conditions to ensure we are modeling the user code correctly.
+In cases where Kani fails to model a certain instruction or local construct that doesn't have a global effect,
+we encode this failure as a verification error.
+I.e., we generate an assertion failure instead of the construct we are modeling using
+codegen_unimplemented(),
+which blocks the execution whenever this construct is reached.
This will allow users to verify their crate successfully as long as
+that construct is not reachable in any harness. If a harness has at least one possible execution path that reaches
+such construct, Kani will fail the verification, and it will mark all checks, other than failed checks, with
+UNDETERMINED status.
It is OK to add "TODO" comments as long as they don't compromise user experience or the tool correctness. +When doing so, please create an issue that captures the task. +Add details about the task at hand including any impact to the user. +Finally, add the link to the issue that captures the "TODO" task as part of your comment.
+E.g.:
+// TODO: This function assumes type cannot be ZST. Check if that's always the case.
+// https://github.com/model-checking/kani/issues/XXXX
+assert!(!typ.is_zst(), "Unexpected ZST type");
+We aim at writing code that is performant but also readable and easy to maintain. +Avoid compromising the code quality if the performance gain is not significant.
+Here are few tips that can help the readability of your code:
+This section describes how to access more advanced CBMC options from Kani.
+Kani is able to handle common CBMC arguments as if they were its own (e.g.,
+--default-unwind <n>), but sometimes it may be necessary to use CBMC arguments which
+are not handled by Kani.
To pass additional arguments for CBMC, you pass --cbmc-args to Kani. Note that
+this "switches modes" from Kani arguments to CBMC arguments: Any arguments that
+appear after --cbmc-args are considered to be CBMC arguments, so all Kani
+arguments must be placed before it.
Thus, the command line format to invoke cargo kani with CBMC arguments is:
cargo kani [<kani-args>]* --cbmc-args [<cbmc-args>]*
+++NOTE: In cases where CBMC is not expected to emit a verification output, +you have to use Kani's argument
+--output-format oldto turn off the +post-processing of output from CBMC.
Setting --default-unwind <n> affects every loop in a harness.
+Once you know a particular loop is causing trouble, sometimes it can be helpful to provide a specific bound for it.
In the general case, specifying just the highest bound globally for all loops +shouldn't cause any problems, except that the solver may take more time because +all loops will be unwound to the specified bound.
+In situations where you need to optimize for the solver, individual bounds for
+each loop can be provided on the command line. To do so, we first need to know
+the labels assigned to each loop with the CBMC argument --show-loops:
# kani src/lib.rs --output-format old --cbmc-args --show-loops
+[...]
+Loop _RNvCs6JP7pnlEvdt_3lib17initialize_prefix.0:
+ file ./src/lib.rs line 11 column 5 function initialize_prefix
+
+Loop _RNvMs8_NtNtCswN0xKFrR8r_4core3ops5rangeINtB5_14RangeInclusivejE8is_emptyCs6JP7pnlEvdt_3lib.0:
+ file $RUST/library/core/src/ops/range.rs line 540 column 9 function std::ops::RangeInclusive::<Idx>::is_empty
+
+Loop gen-repeat<[u8; 10]::16806744624734428132>.0:
+This command shows us the labels of the loops involved. Note that, as mentioned
+in CBMC arguments, we need to use --output-format old to
+avoid post-processing the output from CBMC.
++NOTE: At the moment, these labels are constructed using the mangled name +of the function and an index. Mangled names are likely to change across +different versions, so this method is highly unstable.
+
Then, we can use the CBMC argument --unwindset label_1:bound_1,label_2:bound_2,... to specify an individual bound for each
+loop as follows:
kani src/lib.rs --cbmc-args --unwindset _RNvCs6JP7pnlEvdt_3lib17initialize_prefix.0:12
+rustcKani is developed on the top of the Rust compiler, which is not distributed on crates.io and depends on
+bootstrapping mechanisms to properly build its components.
+Thus, our dependency on rustc crates are not declared in our Cargo.toml.
Below are a few hacks that will make it easier to develop on the top of rustc.
rustc definitionsIDEs rely on cargo to find dependencies and sources to provide proper code analysis and code completion.
+In order to get these features working for rustc crates, you can do the following:
Add the following to the rust-analyzer extension settings in settings.json:
"rust-analyzer.rustc.source": "discover",
+ "rust-analyzer.workspace.symbol.search.scope": "workspace_and_dependencies",
+Ensure that any packages that use rustc data structures have the following line set in their Cargo.toml
[package.metadata.rust-analyzer]
+# This package uses rustc crates.
+rustc_private=true
+You may also need to install the rustc-dev package using rustup
rustup toolchain install nightly --component rustc-dev
+To debug Kani in VS code, first install the CodeLLDB extension.
+Then add the following lines at the start of the main function (see the CodeLLDB manual for details):
{
+ let url = format!(
+ "vscode://vadimcn.vscode-lldb/launch/config?{{'request':'attach','sourceLanguages':['rust'],'waitFor':true,'pid':{}}}",
+ std::process::id()
+ );
+ std::process::Command::new("code").arg("--open-url").arg(url).output().unwrap();
+}
+Note that pretty printing for the Rust nightly toolchain (which Kani uses) is not very good as of June 2022.
+For example, a vector may be displayed as vec![{...}, {...}] on nightly Rust, when it would be displayed as vec![Some(0), None] on stable Rust.
+Hopefully, this will be fixed soon.
This is not a great solution, but it works for now (see https://github.com/intellij-rust/intellij-rust/issues/1618
+for more details).
+Edit the Cargo.toml of the package that you're working on and add artificial dependencies on the rustc packages that you would like to explore.
# This configuration doesn't exist so it shouldn't affect your build.
+[target.'cfg(KANI_DEV)'.dependencies]
+# Adjust the path here to point to a local copy of the rust compiler.
+# The best way is to use the rustup path. Replace <toolchain> with the
+# proper name to your toolchain.
+rustc_driver = { path = "~/.rustup/toolchains/<toolchain>/lib/rustlib/rustc-src/rust/compiler/rustc_driver" }
+rustc_interface = { path = "~/.rustup/toolchains/<toolchain>/lib/rustlib/rustc-src/rust/compiler/rustc_interface" }
+Don't forget to rollback the changes before you create your PR.
+use-package)First, Cargo.toml and rustup toolchain steps are identical to VS
+Code. Install Rust-analyzer binary under ~/.cargo/bin/.
On EMACS, add the following to your EMACS lisp files. They will
+install the necessary packages using the use-package manager.
;; Install LSP
+(use-package lsp-mode
+ :commands lsp)
+(use-package lsp-ui)
+
+;; Install Rust mode
+(use-package toml-mode)
+(use-package rust-mode)
+
+(setq lsp-rust-server 'rust-analyzer)
+(setenv "PATH" (concat (getenv "PATH") ":/home/USER/.cargo/bin/"))
+If EMACS complains that it cannot find certain packages, try running
+M-x package-refresh-contents.
For LSP to be able to find rustc_private files used by Kani, you
+will need to modify variable lsp-rust-analyzer-rustc-source. Run
+M-x customize-variable, type in lsp-rust-analyzer-rustc-source,
+click Value Menu and change it to Path. Paste in the path to
+Cargo.toml of rustc's source code. You can find the source code
+under .rustup, and the path should end with
+compiler/rustc/Cargo.toml. Important: make sure that this
+rustc is the same version and architecture as what Kani uses. If
+not, LSP features like definition lookup may be break.
This ends the basic install for EMACS. You can test your configuration +with the following steps.
+rustc_private import.M-x lsp.Cargo.toml with
+rustc_private=true added.rustc_private imports, do the following. If both
+work, then you are set up.
+rustc_private import. If LSP is working,
+you should get information about the imported item.rustc_private import, run M-x lsp-find-definition. This should jump to the definition within
+rustc's source code.LSP mode can integrate with flycheck for instant error checking and
+company for auto-complete. Consider adding the following to the
+configuration.
(use-package flycheck
+ :hook (prog-mode . flycheck-mode))
+
+(use-package company
+ :hook (prog-mode . company-mode)
+ :config
+ (global-company-mode))
+clippy linter can be added by changing the LSP install to:
(use-package lsp-mode
+ :commands lsp
+ :custom
+ (lsp-rust-analyzer-cargo-watch-command "clippy"))
+Finally lsp-mode can run rust-analyzer via TRAMP for remote +development. We found this way of using rust-analyzer to be unstable +as of 2022-06. If you want to give it a try you will need to add a +new LSP client for that remote with the following code.
+(lsp-register-client
+ (make-lsp-client
+ :new-connection (lsp-tramp-connection "/full/path/to/remote/machines/rust-analyzer")
+ :major-modes '(rust-mode)
+ :remote? t
+ :server-id 'rust-analyzer-remote))
+For further details, please see https://emacs-lsp.github.io/lsp-mode/page/remote/.
+rustcThere are a few reasons why you may want to use your own copy of rustc. E.g.:
rustc code.rustc.We will assume that you already have a Kani setup and that the variable KANI_WORKSPACE contains the path to your Kani workspace.
It's highly recommended that you start from the commit that corresponds to the current rustc version from your workspace.
+To get that information, run the following command:
cd ${KANI_WORKSPACE} # Go to your Kani workspace.
+rustc --version # This will print the commit id. Something like:
+# rustc 1.60.0-nightly (0c292c966 2022-02-08)
+# ^^^^^^^^^ this is used as the ${COMMIT_ID} below
+# E.g.:
+COMMIT_ID=0c292c966
+First you need to clone and build stage 2 of the compiler. +You should tweak the configuration to satisfy your use case. +For more details, see https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html and https://rustc-dev-guide.rust-lang.org/building/suggested.html.
+git clone https://github.com/rust-lang/rust.git
+cd rust
+git checkout ${COMMIT_ID:?"Missing rustc commit id"}
+./configure --enable-extended --tools=src,rustfmt,cargo --enable-debug --set=llvm.download-ci-llvm=true
+./x.py build -i --stage 2
+Now create a custom toolchain (here we name it custom-toolchain):
# Use x86_64-apple-darwin for MacOs
+rustup toolchain link custom-toolchain build/x86_64-unknown-linux-gnu/stage2
+cp build/x86_64-unknown-linux-gnu/stage2-tools-bin/* build/x86_64-unknown-linux-gnu/stage2/bin/
+Finally, override the current toolchain in your kani workspace and rebuild kani:
+cd ${KANI_WORKSPACE}
+rustup override set custom-toolchain
+cargo clean
+cargo build-dev
+kani-compilerrustc logsIn order to enable logs, you can just define the RUSTC_LOG variable, as documented here: https://rustc-dev-guide.rust-lang.org/tracing.html.
Note that, depending on the level of logs you would like to get (debug and trace are not enabled by default), you'll need to build your own version of rustc as described above.
+For logs that are related to kani-compiler code, use the KANI_LOG variable.
In order to print the type layout computed by the Rust compiler, you can pass the following flag to rustc: -Zprint-type-sizes.
+This flag can be passed to kani or cargo kani by setting the RUSTFLAG environment variable.
RUSTFLAGS=-Zprint-type-sizes kani test.rs
+When enabled, the compiler will print messages that look like:
+print-type-size type: `std::option::Option<bool>`: 1 bytes, alignment: 1 bytes
+print-type-size variant `Some`: 1 bytes
+print-type-size field `.0`: 1 bytes
+print-type-size variant `None`: 0 bytes
+You can easily visualize the MIR that is used as an input to code generation by setting the Rust flag --emit mir. I.e.:
RUSTFLAGS=--emit=mir kani test.rs
+The compiler will generate a few files, but we recommend looking at the files that have the following suffix: kani.mir.
+Those files will include the entire MIR collected by our reachability analysis.
+It will include functions from all dependencies, including the std library.
+One limitation is that we dump one copy of each specialization of the MIR function, even though the MIR body itself doesn't change.
We have partnered with the Rust compiler team in the initiative to introduce stable +APIs to the compiler that can be used by third-party tools, which is known as the +Stable MIR Project, or just StableMIR. +This means that we are starting to use the new APIs introduced by this project as is, +despite them not being stable yet.
+For now, the StableMIR APIs are exposed as a crate in the compiler named stable_mir.
+This crate includes the definition of structures and methods to be stabilized,
+which are expected to become the stable APIs in the compiler.
+To reduce the migration burden, these APIs are somewhat close to the original compiler interfaces.
+However, some changes have been made to make these APIs cleaner and easier to use.
For example:
+TyCtxt) is transparent to the user.
+The StableMIR implementation caches this context in a thread local variable,
+and retrieves it whenever necessary.
+run call.DefId has been specialized into multiple types,
+making its usage less error prone. E.g.:
+FnDef represents the definition of a function,
+while StaticDef is the definition of a static variable.
+DefId may be mapped to different definitions according to its context.
+For example, an InstanceDef and a FnDef may represent the same function definition.TyCtxt are now part of a type.
+Example, the function TyCtxt.instance_mir is now Instance::body.Instance::body.
+This method already instantiates all types and resolves all constants before converting
+it to stable APIs.Since the new APIs require converting internal data to a stable representation, +the APIs were also designed to avoid needless conversions, +and to allow extra information to be retrieved on demand.
+For example, Ty is just an identifier, while TyKind is a structure that can be retrieved via Ty::kind method.
+The TyKind is a more structured object, thus,
+it is only generated when the kind method is invoked.
+Since this translation is not cached,
+many of the functions that the rust compiler used to expose in Ty,
+is now only part of TyKind.
+The reason being that there is no cache for the TyKind,
+and users should do the caching themselves to avoid needless translations.
From our initial experiments with the transition of the reachability algorithm to use StableMIR, +there is a small penalty of using StableMIR over internal rust compiler APIs. +However, they are still fairly efficient and it did not impact the overall compilation time.
+To reduce the burden of migrating to StableMIR, +and to allow StableMIR to be used together with internal APIs, +there are two helpful methods to convert StableMIR constructs to internal rustc and back:
+rustc_internal::internal(): Convert a Stable item into an internal one.rustc_internal::stable(): Convert an internal item into a Stable one.Both of these methods are inside rustc_smir crate in the rustc_internal
+module inside the compiler.
+Note that there is no plan to stabilize any of these methods,
+and there's also no guarantee on its support and coverage.
The conversion is not implemented for all items, and some conversions may be incomplete. +Please proceed with caution when using these methods.
+Besides that, do not invoke any other rustc_smir methods, except for run.
+This crate's methods are not meant to be invoked externally.
+Note that, the method run will also eventually be replaced by a Stable driver.
For now, StableMIR should only be used to get information from the compiler. +Do not try to create or modify items directly, as it may not work. +This may result in incorrect behavior or an internal compiler error (ICE).
+As we adopt StableMIR, we would like to introduce a few conventions to make it easier to maintain the code.
+Whenever there is a name conflict, for example, Ty or codegen_ty,
+use a suffix to indicate which API you are using.
+Stable for StableMIR and Internal for rustc internal APIs.
A module should either default its naming to Stable APIs or Internal APIs.
+I.e.: Modules that have been migrated to StableMIR don't need to add the Stable suffix to stable items.
+While those that haven't been migrated, should add Stable, but no Internal is needed.
For example, the codegen::typ module will likely include methods:
codegen_ty(&mut self, Ty) and codegen_ty_stable(&mut, TyStable) to handle
+internal and stable APIs.
Development work in the Kani project depends on multiple tools. Regardless of +your familiarity with the project, the commands below may be useful for +development purposes.
+# Error "'rustc' panicked at 'failed to lookup `SourceFile` in new context'"
+# or similar error? Cleaning artifacts might help.
+# Otherwise, comment the line below.
+cargo clean
+cargo build-dev
+# Full regression suite
+./scripts/kani-regression.sh
+# Delete regression test caches (Linux)
+rm -r build/x86_64-unknown-linux-gnu/tests/
+# Delete regression test caches (macOS)
+rm -r build/x86_64-apple-darwin/tests/
+# Test suite run (we can only run one at a time)
+# cargo run -p compiletest -- --suite ${suite} --mode ${mode}
+cargo run -p compiletest -- --suite kani --mode kani
+# Build documentation
+cd docs
+./build-docs.sh
+These can help understand what Kani is generating or encountering on an example or test file:
+# Enable `debug!` macro logging output when running Kani:
+kani --debug file.rs
+# Use KANI_LOG for a finer grain control of the source and verbosity of logs.
+# E.g.: The command below will print all logs from the kani_middle module.
+KANI_LOG="kani_compiler::kani_middle=trace" kani file.rs
+# Keep CBMC Symbol Table and Goto-C output (.json and .goto)
+kani --keep-temps file.rs
+# Generate "C code" from CBMC IR (.c)
+kani --gen-c file.rs
+# Generate a ${INPUT}.kani.mir file with a human friendly MIR dump
+# for all items that are compiled to the respective goto-program.
+RUSTFLAGS="--emit mir" kani ${INPUT}.rs
+The KANI_REACH_DEBUG environment variable can be used to debug Kani's reachability analysis.
+If defined, Kani will generate a DOT graph ${INPUT}.dot with the graph traversed during reachability analysis.
+If defined and not empty, the graph will be filtered to end at functions that contains the substring
+from KANI_REACH_DEBUG.
Note that this will only work on debug builds.
+# Generate a DOT graph ${INPUT}.dot with the graph traversed during reachability analysis
+KANI_REACH_DEBUG= kani ${INPUT}.rs
+
+# Generate a DOT graph ${INPUT}.dot with the sub-graph traversed during the reachability analysis
+# that connect to the given target.
+KANI_REACH_DEBUG="${TARGET_ITEM}" kani ${INPUT}.rs
+# See CBMC IR from a C file:
+goto-cc file.c -o file.out
+goto-instrument --print-internal-representation file.out
+# or (for json symbol table)
+cbmc --show-symbol-table --json-ui file.out
+# or (an alternative concise format)
+cbmc --show-goto-functions file.out
+# Recover C from goto-c binary
+goto-instrument --dump-c file.out > file.gen.c
+The Kani project follows the squash and merge option for pull request merges. +As a result:
+But the main commit message body is editable at merge time, so you don't have to worry about "typo fix" messages because these can be removed before merging.
+# Set up your git fork
+git remote add fork git@github.com:${USER}/kani.git
+# Reset everything. Don't have any uncommitted changes!
+git clean -xffd
+git submodule foreach --recursive git clean -xffd
+git submodule update --init
+# Need to update local branch (e.g. for an open pull request?)
+git fetch origin
+git merge origin/main
+# Or rebase, but that requires a force push,
+# and because we squash and merge, an extra merge commit in a PR doesn't hurt.
+# Checkout a pull request locally without the github cli
+git fetch origin pull/$ID/head:pr/$ID
+git switch pr/$ID
+# Push to someone else's pull request
+git origin add $USER $GIR_URL_FOR_THAT_USER
+git push $USER $LOCAL_BRANCH:$THEIR_PR_BRANCH_NAME
+# Search only git-tracked files
+git grep codegen_panic
+# Accidentally commit to main?
+# "Move" commit to a branch:
+git checkout -b my_branch
+# Fix main:
+git branch --force main origin/main
+cargo kani assessAssess is an experimental new feature to gather data about Rust crates, to aid the start of proof writing.
+In the short-term, assess collects and dumps tables of data that may help Kani developers understand what's needed to begin writing proofs for another project. +For instance, assess may help answer questions like:
+In the long-term, assess will become a user-facing feature, and help Kani users get started writing proofs. +We expect that users will have the same questions as above, but in the long term, hopefully the answers to those trend towards an uninteresting "yes." +So the new questions might be:
+These long-term goals are only "hinted at" with the present experimental version of assess. +Currently, we only get as far as finding out which tests successfully verify (concretely) with Kani. +This might indicate tests that could be generalized and converted into proofs, but we currently don't do anything to group, rank, or otherwise heuristically prioritize what might be most "interesting." +(For instance, we'd like to eventually compute coverage information and use that to help rank the results.) +As a consequence, the output of the tool is very hard to interpret, and likely not (yet!) helpful to new or potential Kani users.
+To assess a package, run:
+cargo kani --enable-unstable assess
+As a temporary hack (arguments shouldn't work like this), to assess a single cargo workspace, run:
+cargo kani --enable-unstable --workspace assess
+To scan a collection of workspaces or packages that are not part of a shared workspace, run:
+cargo kani --enable-unstable assess scan
+The only difference between 'scan' and 'regular' assess is how the packages built are located.
+All versions of assess produce the same output and metrics.
+Assess will normally build just like cargo kani or cargo build, whereas scan will find all cargo packages beneath the current directory, even in unrelated workspaces.
+Thus, 'scan' may be helpful in the case where the user has a choice of packages and is looking for the easiest to get started with (in addition to the Kani developer use-case, of aggregating statistics across many packages).
(Tip: Assess may need to run for awhile, so try using screen, tmux or nohup to avoid terminating the process if, for example, an ssh connection breaks.
+Some tests can also consume huge amounts of ram when run through Kani, so you may wish to use ulimit -v 6000000 to prevent any processes from using more than 6GB.
+You can also limit the number of concurrent tests that will be run by providing e.g. -j 4, currently as a prepended argument, like --enable-unstable or --workspace in the examples above.)
Assess builds all the packages requested in "test mode" (i.e. --tests), and runs all the same tests that cargo test would, except through Kani.
+This gives end-to-end assurance we're able to actually build and run code from these packages, skipping nothing of what the verification process would need, except that the harnesses don't have any nondeterminism (kani::any()) and consequently don't "prove" much.
+The interesting signal comes from what tests cannot be analyzed by Kani due to unsupported features, performance problems, crash bugs, or other issues that get in the way.
Currently, assess forces termination by using unwind(1) on all tests, so many tests will fail with unwinding assertions.
Assess produces a few tables of output (both visually in the terminal, and in a more detailed json format) so far:
+======================================================
+ Unsupported feature | Crates | Instances
+ | impacted | of use
+-------------------------------+----------+-----------
+ caller_location | 71 | 239
+ simd_bitmask | 39 | 160
+...
+The unsupported features table aggregates information about features that Kani does not yet support.
+These correspond to uses of codegen_unimplemented in the kani-compiler, and appear as warnings during compilation.
Unimplemented features are not necessarily actually hit by (dynamically) reachable code, so an immediate future improvement on this table would be to count the features actually hit by failing test cases, instead of just those features reported as existing in code by the compiler. +In other words, the current unsupported features table is not what we want to see, in order to perfectly prioritize implementing these features, because we may be counting features that no proof would ever hit. +A perfect signal here isn't possible: there may be code that looks statically reachable, but is never dynamically reachable, and we can't tell. +But we can use test coverage as an approximation: well-tested code will hopefully cover most of the dynamically reachable code. +The operating hypothesis of assess is that code covered by tests is code that could be covered by proof, and so measuring unsupported features by those actually hit by a test should provide a better "signal" about priorities. +Implicitly deprioritizing unsupported features because they aren't covered by tests may not be a bug, but a feature: we may simply not want to prove anything about that code, if it hasn't been tested first, and so adding support for that feature may not be important.
+A few notes on terminology:
+1 in this column, regardless of the number of dependencies.================================================
+ Reason for failure | Number of tests
+------------------------------+-----------------
+ unwind | 61
+ none (success) | 6
+ assertion + overflow | 2
+...
+The test failure reasons table indicates why, when assess ran a test through Kani, it failed to verify. +Notably:
+unwind(1), we expect unwind to rank highly.assertion means an ordinary assert!() was hit (or something else with this property class).+, such as assertion + overflow.should_fail tests, so assertion may actually be "success": the test should hit an assertion and did.=============================================================================
+ Candidate for proof harness | Location
+-------------------------------------------------------+---------------------
+ float::tests::f64_edge_cases | src/float.rs:226
+ float::tests::f32_edge_cases | src/float.rs:184
+ integer::tests::test_integers | src/integer.rs:171
+This table is the most rudimentary so far, but is the core of what long-term assess will help accomplish. +Currently, this table just presents (with paths displayed in a clickable manner) the tests that successfully "verify" with Kani. +These might be good candidates for turning into proof harnesses. +This list is presently unordered; the next step for improving it would be to find even a rudimentary way of ranking these test cases (e.g. perhaps by code coverage).
+kani-compiler emits *.kani-metadata.json for each target it builds.
+This format can be found in the kani_metadata crate, shared by kani-compiler and kani-driver.
+This is the starting point for assess.
Assess obtains this metadata by essentially running a cargo kani:
--all-features turned onunwind always set to 1--testsAssess starts by getting all the information from these metadata files. +This is enough by itself to construct a rudimentary "unsupported features" table. +But assess also uses it to discover all the test cases, and (instead of running proof harnesses) it then runs all these test harnesses under Kani.
+Assess produces a second metadata format, called (unsurprisingly) "assess metadata".
+(Found in kani-driver under src/assess/metadata.rs.)
+This format records the results of what assess does.
This metadata can be written to a json file by providing --emit-metadata <file> to assess.
+Likewise, scan can be told to write out this data with the same option.
Assess metadata is an aggregatable format.
+It does not apply to just one package, as assess can work on a workspace of packages.
+Likewise, scan uses and produces the exact same format, across multiple workspaces.
So far all assess metadata comes in the form of "tables" which are built with TableBuilder<T: TableRow>.
+This is documented further in src/assess/table_builder.rs.
There is a script in the Kani repo for this purpose.
+This will clone the top-100 crates to /tmp/top-100-experiment and run assess scan on them:
./scripts/exps/assess-scan-on-repos.sh
+If you'd like to preseve the results, you can direct scan to use a different directory with an environment variable:
+ASSESS_SCAN="~/top-100-experiment" ./scripts/exps/assess-scan-on-repos.sh
+To re-run the experiment, it suffices to be in the experiment directory:
+cd ~/top-100-experiment && ~/kani/scripts/exps/assess-scan-on-repos.sh
+Testing in Kani is carried out in multiple ways. There are at least +two very good reasons to do it:
+Software regression: A regression is a type of bug +that appears after a change is introduced where a feature that +was previously working has unexpectedly stopped working.
+Regression testing allows one to prevent a software regression +from happening by running a comprehensive set of working tests +before any change is committed to the project.
+Software metrics: A metric is a measure of software +characteristics which are quantitative and countable. Metrics are +particularly valuable for project management purposes.
+We recommend reading our section on Regression +Testing if you're interested in Kani +development. To run kani on a large number of remotely +hosted crates, please see Repository Crawl.
+Kani relies on a quite extensive range of tests to perform regression testing. +Regression testing can be executed by running the command:
+./scripts/kani-regression.sh
+The kani-regression.sh script executes different testing commands, which we classify into:
See below for a description of each one.
+Note that regression testing is run whenever a Pull Request is opened, updated or merged +into the main branch. Therefore, it's a good idea to run regression testing locally before +submitting a Pull Request for Kani.
+The Kani testing suites are the main testing resource for Kani. In most cases, the +tests contained in the Kani testing suites are single Rust files that are run +using the following command:
+kani file.rs <options>
+Command-line options can be passed to the test by adding a special +comment to the file. See testing options for more details.
+In particular, the Kani testing suites are composed of:
+kani: The main testing suite for Kani. The test is a single Rust file that's
+run through Kani. In general, the test passes if verification with Kani
+is successful, otherwise it fails.firecracker: Works like kani but contains tests inspired by
+Firecracker code.prusti: Works like kani but contains tests from the
+Prusti tool.smack: Works like kani but contains tests from the
+SMACK tool.kani-fixme: Similar to kani, but runs ignored tests from the kani testing
+suite (i.e., tests with fixme or ignore in their name).
+Allows us to detect when a previously not supported test becomes
+supported. More details in "Fixme" tests.expected: Similar to kani but with an additional check which ensures that
+lines appearing in *.expected files appear in the output
+generated by kani.ui: Works like expected, but focuses on the user interface (e.g.,
+warnings) instead of the verification output.cargo-kani: This suite is designed to test the cargo-kani command. As such,
+this suite works with packages instead of single Rust files.
+Arguments can be specified in the Cargo.toml configuration file.
+Similar to the expected suite, we look for *.expected files
+for each harness in the package.cargo-ui: Similar to cargo-kani, but focuses on the user interface like the ui test suite.script-based-pre: This suite is useful to execute script-based tests, and
+also allows checking expected output and exit codes after
+running them. The suite uses the exec mode, described in
+more detail here.We've extended
+compiletest (the
+Rust compiler testing framework) to work with these suites. That way, we take
+advantage of all compiletest features (e.g., parallel execution).
The process of running single-file tests is split into three stages:
+check: This stage uses the Rust front-end to detect if the example is valid
+Rust code.codegen: This stage uses the Kani back-end to determine if we can generate
+GotoC code.verify: This stage uses CBMC to obtain a verification result.If a test fails, the error message will include the stage where it failed:
+error: test failed: expected check success, got failure
+When working on a test that's expected to fail, there are two options to +indicate an expected failure. The first one is to add a comment
+// kani-<stage>-fail
+at the top of the test file, where <stage> is the stage where the test is
+expected to fail.
The other option is to use the predicate kani::expect_fail(cond, message)
+included in the Kani library. The cond in kani::expect_fail is a condition
+that you expect not to hold during verification. The testing framework expects
+one EXPECTED FAIL message in the verification output for each use of the
+predicate.
++NOTE:
+kani::expect_failis only useful to indicate failure in the +verifystage, errors in other stages will be considered testing failures.
Many tests will require passing command-line options to Kani. These options can +be specified in single Rust files by adding a comment at the top of the file:
+// kani-flags: <options>
+For example, to use an unwinding value of 4 in a test, we can write:
+// kani-flags: --default-unwind 4
+For cargo-kani tests, the preferred way to pass command-line options is adding
+them to Cargo.toml. See Usage on a package for more details.
Any test containing fixme or ignore in its name is considered a test not
+supported for some reason (i.e., they return an unexpected verification result).
However, "fixme" tests included in the kani folder are run via the kani-fixme
+testing suite. kani-fixme works on test files from kani but:
fixme or ignore (ignoring the rest).We welcome contributions with "fixme" tests which demonstrate a bug or +unsupported feature in Kani. Ideally, the test should include some comments +regarding:
+To include a new "fixme" test in kani you only need to ensure its name contains
+fixme or ignore. If your changes to Kani cause a "fixme" test to become
+supported, you only need to rename it so the name does not contain fixme nor
+ignore.
These tests follow the +Rust unit testing +style.
+At present, Kani runs unit tests from the following packages:
+cprover_bindingskani-compilercargo-kaniWe use the Python unit testing framework to +test the CBMC JSON parser.
+These are tests which are run using scripts. Scripting gives us the ability to +perform ad-hoc checks that cannot be done otherwise. They are currently used +for:
+In fact, most of them are equivalent to running cargo kani and performing
+checks on the output. The downside to scripting is that these tests will always
+be run, even if there have not been any changes since the last time the
+regression was run.
++NOTE: With the addition of the
+execmode forcompiletest(described +below), we'll be migrating these script-based tests to other suites using the +execmode. Theexecmode allows us to take advantage ofcompiletest+features while executing script-based tests (e.g., parallel execution).
exec modeThe exec mode in compiletest allows us to execute script-based tests, in
+addition to checking expected output and exit codes after running them.
In particular, tests are expected to be placed directly under the test directory
+(e.g., script-based-pre) in a directory with a config.yml file, which
+should contain:
script: The path to the script to be executed.expected (optional): The path to the .expected file to
+use for output comparison.exit_code (optional): The exit code to be returned by executing
+the script (a zero exit code is expected if not specified).For example, let's say want to test the script exit-one.sh:
echo "Exiting with code 1!"
+exit 1
+In this case, we'll create a folder that contains the config.yml file:
script: exit-one.sh
+expected: exit-one.expected
+exit_code: 1
+where exit-one.expected is simply a text file such as:
Exiting with code 1!
+If expected isn't specified, the output won't be checked. If exit_code isn't
+specified, the exec mode will check the exit code was zero.
Note that all paths specified in the config.yml file are local to the test
+directory, which is the working directory assumed when executing the test. This
+is meant to avoid problems when executing the test manually.
This section explains how to run Kani on a large number of crates +downloaded from git forges. You may want to do this if you are going +to test Kani's ability to handle Rust features found in projects out +in the wild.
+For the first half, we will explain how to use data from crates.io to +pick targets. Second half will explain how to use a script to run on a +list of selected repositories.
+In picking repositories, you may want to select by metrics like +popularity or by the presence of certain features. In this section, we +will explain how to select top ripostes by download count.
+We will use the db-dump method of getting data from crates.io as it
+is zero cost to their website and gives us SQL access. To start, have
+the following programs set up on your computer.
docker-compose.yaml. version: '3.3' may need to change.version: '3.3'
+services:
+ db:
+ image: postgres:latest
+ restart: always
+ environment:
+ - POSTGRES_USER=postgres
+ - POSTGRES_PASSWORD=postgres
+ volumes:
+ - crates-data:/var/lib/postgresql/data
+ logging:
+ driver: "json-file"
+ options:
+ max-size: "50m"
+volumes:
+ crates-data:
+ driver: local
+Then, run the following to start the setup.
+docker-compose up -d
+Once set up, run docker ls to figure out the container's name. We
+will refer to the name as $CONTAINER_NAME from now on.
Download actual data from crates.io. First, run the following
+command to get a shell in the container: docker exec -it --user postgres $CONTAINER_NAME bash. Now, run the following to grab and
+install the data into the repository. Please note that this may
+take a while.
wget https://static.crates.io/db-dump.tar.gz
+tar -xf db-dump.tar.gz
+psql postgres -f */schema.sql
+psql postgres -f */import.sql
+Extract the data. In the same docker shell, run the following to +extract the top 1k repositories. Other SQL queries may be used if +you want another criteria
+\copy
+(SELECT name, repository, downloads FROM crates
+WHERE repository LIKE 'http%' ORDER BY DOWNLOADS DESC LIMIT 1000)
+to 'top-1k.csv' csv header;
+Clean the data. The above query will capture duplicates paths that +are deeper than the repository. You can clean these out.
+cat top-1k.csv | awk -F ',' '{ print $2 }' | grep -v 'http.*'sed 's/tree\/master.*$//g'sort | uniq --uniqueIn this step we will download the list of repositories using a script +assess-scan-on-repos.sh
+Make sure to have Kani ready to run. For that, see the build instructions.
+From the repository root, you can run the script with
+./scripts/exps/assess-scan-on-repos.sh $URL_LIST_FILE where
+$URL_LIST_FILE points to a line-delimited list of URLs you want to
+run Kani on. Repositories that give warnings or errors can be grepping
+for with "STDERR Warnings" and "Error exit in" respectively.
benchcompWhile Kani includes a performance regression suite, you may wish to test Kani's performance using your own benchmarks or with particular versions of Kani.
+You can use the benchcomp tool in the Kani repository to run several 'variants' of a command on one or more benchmark suites; automatically parse the results of each of those suites; and take actions or emit visualizations based on those results.
Benchcomp provides the following features to support your performance-comparison workflow:
+Here's how to run Kani's performance suite twice, comparing the last released version of Kani with the current HEAD.
+cd $KANI_SRC_DIR
+git worktree add new HEAD
+git worktree add old $(git describe --tags --abbrev=0)
+
+tools/benchcomp/bin/benchcomp --config tools/benchcomp/configs/perf-regression.yaml
+This uses the perf-regression.yaml configuration file that we use in continuous integration.
+After running the suite twice, the configuration file terminates benchcomp with a return code of 1 if any of the benchmarks regressed on metrics such as success (a boolean), solver_runtime, and number_vccs (numerical).
+Additionally, the config file directs benchcomp to print out a Markdown table that GitHub's CI summary page renders in to a table.
The rest of this documentation describes how to modify benchcomp for your own use cases, including writing a configuration file; writing a custom parser for your benchmark suite; and writing a custom visualization to examine the results of a performance comparison.
benchcomp command linebenchcomp is a single command that runs benchmarks, parses their results, combines these results, and emits visualizations.
+benchcomp also provides subcommands to run these steps individually.
+Most users will want to invoke benchcomp in one of two ways:
benchcomp without any subcommands, which runs the entire performance comparison process as depicted belowbenchcomp visualize, which runs the visualization step on the results of a previous benchmark run without actually re-running the benchmarks.
+This is useful when tweaking the parameters of a visualization, for example changing the threshold of what is considered to be a regression.The subcommands run and collate are also available.
+The diagram below depicts benchcomp's order of operation.
Running benchcomp invokes run, collate, and visualize behind the scenes.
+If you have previously run benchcomp, then running benchcomp visualize will emit the visualizations in the config file using the previous result.yaml.
In the diagram above, two different suites (1 and 2) are both run using two variants---combinations of command, working directory, and environment variables.
+Benchmark suite 2 requires a totally different command line to suite 1---for example, suite_1 might contain Kani harnesses invoked through cargo kani, while suite_2 might contain CBMC harnesses invoked through run_cbmc_proofs.py.
+Users would therefore define different variants (c and d) for invoking suite_2, and also specify a different parser to parse the results.
+No matter how different the benchmark suites are, the collate stage combines their results so that they can later be compared.
Users must specify the actual suites to run, the parsers used to collect their results, and the visualizations to emit in a file called benchcomp.yaml or a file passed to the -c/--config flag.
+The next section describes the schema for this configuration file.
+A run similar to the diagram above might be achieved using the following configuration file:
# Compare a range of Kani and CBMC benchmarks when
+# using Cadical versus the default SAT solver
+
+variants:
+ variant_a:
+ config:
+ directory: kani_benchmarks
+ command_line: scripts/kani-perf.sh
+ env: {}
+
+ variant_b:
+ config:
+ directory: kani_benchmarks
+ command_line: scripts/kani-perf.sh
+ # This variant uses a hypothetical environment variable that
+ # forces Kani to use the cadical SAT solver
+ env:
+ KANI_SOLVER: cadical
+
+ variant_c:
+ config:
+ directory: cbmc_benchmarks
+ command_line: run_cbmc_proofs.py
+ env: {}
+
+ variant_d:
+ config:
+ directory: cbmc_benchmarks
+ command_line: run_cbmc_proofs.py
+ env:
+ EXTERNAL_SAT_SOLVER: cadical
+
+run:
+ suites:
+ suite_1:
+ parser:
+ module: kani_perf
+ variants: [variant_a, variant_b]
+
+ suite_2:
+ parser:
+ module: cbmc_litani_parser
+ variants: [variant_c, variant_d]
+
+visualize:
+ - type: dump_graph
+ out_file: graph.svg
+
+ - type: dump_markdown_results_table
+ out_file: summary.md
+ extra_columns: []
+
+ - type: error_on_regression
+ variant_pairs:
+ - [variant_a, variant_b]
+ - [variant_c, variant_d]
+benchcomp configuration filebenchcomp's operation is controlled through a YAML file---benchcomp.yaml by default or a file passed to the -c/--config option.
+This page lists the different visualizations that are available.
A variant is a single invocation of a benchmark suite. Benchcomp runs several
+variants, so that their performance can be compared later. A variant consists of
+a command-line argument, working directory, and environment. Benchcomp invokes
+the command using the operating system environment, updated with the keys and
+values in env. If any values in env contain strings of the form ${var},
+Benchcomp expands them to the value of the environment variable $var.
variants:
+ variant_1:
+ config:
+ command_line: echo "Hello, world"
+ directory: /tmp
+ env:
+ PATH: /my/local/directory:${PATH}
+After benchcomp has finished parsing the results, it writes the results to results.yaml by default.
+Before visualizing the results (see below), benchcomp can filter the results by piping them into an external program.
To filter results before visualizing them, add filters to the configuration file.
filters:
+ - command_line: ./scripts/remove-redundant-results.py
+ - command_line: cat
+The value of filters is a list of dicts.
+Currently the only legal key for each of the dicts is command_line.
+Benchcomp invokes each command_line in order, passing the results as a JSON file on stdin, and interprets the stdout as a YAML-formatted modified set of results.
+Filter scripts can emit either YAML (which might be more readable while developing the script), or JSON (which benchcomp will parse as a subset of YAML).
The following visualizations are available; these can be added to the visualize list of benchcomp.yaml.
Detailed documentation for these visualizations follows.
+Scatterplot configuration options
+Print Markdown-formatted tables displaying benchmark results
+For each metric, this visualization prints out a table of benchmarks, +showing the value of the metric for each variant, combined with an optional +scatterplot.
+The 'out_file' key is mandatory; specify '-' to print to stdout.
+'extra_colums' can be an empty dict. The sample configuration below assumes +that each benchmark result has a 'success' and 'runtime' metric for both +variants, 'variant_1' and 'variant_2'. It adds a 'ratio' column to the table +for the 'runtime' metric, and a 'change' column to the table for the +'success' metric. The 'text' lambda is called once for each benchmark. The +'text' lambda accepts a single argument---a dict---that maps variant +names to the value of that variant for a particular metric. The lambda +returns a string that is rendered in the benchmark's row in the new column. +This allows you to emit arbitrary text or markdown formatting in response to +particular combinations of values for different variants, such as +regressions or performance improvements.
+'scatterplot' takes the values 'off' (default), 'linear' (linearly scaled +axes), or 'log' (logarithmically scaled axes).
+Sample configuration:
+visualize:
+- type: dump_markdown_results_table
+ out_file: "-"
+ scatterplot: linear
+ extra_columns:
+ runtime:
+ - column_name: ratio
+ text: >
+ lambda b: str(b["variant_2"]/b["variant_1"])
+ if b["variant_2"] < (1.5 * b["variant_1"])
+ else "**" + str(b["variant_2"]/b["variant_1"]) + "**"
+ success:
+ - column_name: change
+ text: >
+ lambda b: "" if b["variant_2"] == b["variant_1"]
+ else "newly passing" if b["variant_2"]
+ else "regressed"
+Example output:
+## runtime
+
+| Benchmark | variant_1 | variant_2 | ratio |
+| --- | --- | --- | --- |
+| bench_1 | 5 | 10 | **2.0** |
+| bench_2 | 10 | 5 | 0.5 |
+
+## success
+
+| Benchmark | variant_1 | variant_2 | change |
+| --- | --- | --- | --- |
+| bench_1 | True | True | |
+| bench_2 | True | False | regressed |
+| bench_3 | False | True | newly passing |
+Print the YAML-formatted results to a file.
+The 'out_file' key is mandatory; specify '-' to print to stdout.
+Sample configuration:
+visualize:
+- type: dump_yaml
+ out_file: '-'
+Terminate benchcomp with a return code of 1 if any benchmark regressed.
+This visualization checks whether any benchmark regressed from one variant +to another. Sample configuration:
+visualize:
+- type: error_on_regression
+ variant_pairs:
+ - [variant_1, variant_2]
+ - [variant_1, variant_3]
+ checks:
+ - metric: runtime
+ test: "lambda old, new: new / old > 1.1"
+ - metric: passed
+ test: "lambda old, new: False if not old else not new"
+This says to check whether any benchmark regressed when run under variant_2 +compared to variant_1. A benchmark is considered to have regressed if the +value of the 'runtime' metric under variant_2 is 10% higher than the value +under variant_1. Furthermore, the benchmark is also considered to have +regressed if it was previously passing, but is now failing. These same +checks are performed on all benchmarks run under variant_3 compared to +variant_1. If any of those lambda functions returns True, then benchcomp +will terminate with a return code of 1.
+Run an executable command, passing the performance metrics as JSON on stdin.
+This allows you to write your own visualization, which reads a result file +on stdin and does something with it, e.g. writing out a graph or other +output file.
+Sample configuration:
+visualize:
+- type: run_command
+ command: ./my_visualization.py
+Benchcomp ships with built-in parsers that retrieve the results of a benchmark suite after the run has completed. +You can also create your own parser, either to run locally or to check into the Kani codebase.
+You specify which parser should run for each benchmark suite in benchcomp.yaml.
+For example, if you're running the kani performance suite, you would use the built-in kani_perf parser to parse the results:
suites:
+ my_benchmark_suite:
+ variants: [variant_1, variant_2]
+ parser:
+ module: kani_perf
+A parser is a program that benchcomp runs inside the root directory of a benchmark suite, after the suite run has completed.
+The parser should retrieve the results of the run (by parsing output files etc.) and print the results out as a YAML document.
+You can use your executable parser by specifying the command key rather than the module key in your benchconf.yaml file:
suites:
+ my_benchmark_suite:
+ variants: [variant_1, variant_2]
+ parser:
+ command: ./my-cool-parser.sh
+The kani_perf parser mentioned above, in tools/benchcomp/benchcomp/parsers/kani_perf.py, is a good starting point for writing a custom parser, as it also works as a standalone executable.
+Here is an example output from an executable parser:
metrics:
+ runtime: {}
+ success: {}
+ errors: {}
+benchmarks:
+ bench_1:
+ metrics:
+ runtime: 32
+ success: true
+ errors: []
+ bench_2:
+ metrics:
+ runtime: 0
+ success: false
+ errors: ["compilation failed"]
+The above format is different from the final result.yaml file that benchcomp writes, because the above file represents the output of running a single benchmark suite using a single variant.
+Your parser will run once for each variant, and benchcomp combines the dictionaries into the final result.yaml file.
To turn your executable parser into one that benchcomp can invoke as a module, ensure that it has a main(working_directory) method that returns a dict (the same dict that it would print out as a YAML file to stdout).
+Save the file in tools/benchcomp/benchcomp/parsers using python module naming conventions (filename should be an identifier and end in .py).
Like other tools, Kani comes with some limitations. In some cases, these +limitations are inherent because of the techniques it's based on, or the +undecidability of the properties that Kani seeks to prove. In other +cases, it's just a matter of time and effort to remove these limitations (e.g., +specific unsupported Rust language features).
+In this chapter, we do the following to document these limitations:
+Rust has a broad definition of undefined behaviour (UB). +The Rust documentation warns that UB can have unexpected, non-local effects:
+++Note: Undefined behavior affects the entire program. For example, calling a function in C that exhibits undefined behavior of C means your entire program contains undefined behaviour that can also affect the Rust code. And vice versa, undefined behavior in Rust can cause adverse affects on code executed by any FFI calls to other languages.
+
If a program has UB, the semantics of the rest of the program are undefined. +As a result, if the program under verification contains UB then, in principle, the program (including its representation in MIR analyzed by Kani) has no semantics and hence could do anything, including violating the guarantees checked by Kani. +This means that verification results are subject to the proviso that the program under verification does not contain UB.
+Rust’s definition of UB is so broad that Rust has the following warning:
+++Warning +The following list is not exhaustive. There is no formal model of Rust's semantics for what is and is not allowed in unsafe code, so there may be more behavior considered unsafe. The following list is just what we know for sure is undefined behavior. Please read the Rustonomicon (https://doc.rust-lang.org/nomicon/index.html) before writing unsafe code.
+
Given the lack of a formal semantics for UB, and given Kani's focus on memory safety, there are classes of UB which Kani does not detect. +A non-exhaustive list of these, based on the non-exhaustive list from the Rust documentation, is:
+rustc to check for this case.rustc to check for this case.kani::any() but it also won't complain if you transmute an invalid value to a Rust type (for example, a 0 to NonZeroU32).Kani makes a best-effort attempt to detect some cases of UB:
+*expr) on a raw pointer that is dangling or unaligned.
+The table below tries to summarize the current support in Kani for +the Rust language features according to the Rust Reference. +We use the following values to indicate the level of support:
+As with all software, bugs may be found anywhere regardless of the level of support. In such cases, we +would greatly appreciate that you filed a bug report.
+| Reference | Feature | Support | Notes |
|---|---|---|---|
| 3.1 | Macros By Example | Yes | |
| 3.2 | Procedural Macros | Yes | |
| 4 | Crates and source files | Yes | |
| 5 | Conditional compilation | Yes | |
| 6.1 | Modules | Yes | |
| 6.2 | Extern crates | Yes | |
| 6.3 | Use declarations | Yes | |
| 6.4 | Functions | Yes | |
| 6.5 | Type aliases | Yes | |
| 6.6 | Structs | Yes | |
| 6.7 | Enumerations | Yes | |
| 6.8 | Unions | Yes | |
| 6.9 | Constant items | Yes | |
| 6.10 | Static items | Yes | |
| 6.11 | Traits | Yes | |
| 6.12 | Implementations | Yes | |
| 6.13 | External blocks | Yes | |
| 6.14 | Generic parameters | Yes | |
| 6.15 | Associated Items | Yes | |
| 7 | Attributes | Yes | |
| 8.1 | Statements | Yes | |
| 8.2.1 | Literal expressions | Yes | |
| 8.2.2 | Path expressions | Yes | |
| 8.2.3 | Block expressions | Yes | |
| 8.2.4 | Operator expressions | Yes | |
| 8.2.5 | Grouped expressions | Yes | |
| 8.2.6 | Array and index expressions | Yes | |
| 8.2.7 | Tuple and index expressions | Yes | |
| 8.2.8 | Struct expressions | Yes | |
| 8.2.9 | Call expressions | Yes | |
| 8.2.10 | Method call expressions | Yes | |
| 8.2.11 | Field access expressions | Yes | |
| 8.2.12 | Closure expressions | Yes | |
| 8.2.13 | Loop expressions | Yes | |
| 8.2.14 | Range expressions | Yes | |
| 8.2.15 | If and if let expressions | Yes | |
| 8.2.16 | Match expressions | Yes | |
| 8.2.17 | Return expressions | Yes | |
| 8.2.18 | Await expressions | No | See Notes - Concurrency |
| 9 | Patterns | Partial | #707 |
| 10.1.1 | Boolean type | Yes | |
| 10.1.2 | Numeric types | Yes | |
| 10.1.3 | Textual types | Yes | |
| 10.1.4 | Never type | Yes | |
| 10.1.5 | Tuple types | Yes | |
| 10.1.6 | Array types | Yes | |
| 10.1.7 | Slice types | Yes | |
| 10.1.8 | Struct types | Yes | |
| 10.1.9 | Enumerated types | Yes | |
| 10.1.10 | Union types | Yes | |
| 10.1.11 | Function item types | Yes | |
| 10.1.12 | Closure types | Partial | See Notes - Advanced features |
| 10.1.13 | Pointer types | Partial | See Notes - Advanced features |
| 10.1.14 | Function pointer types | Partial | See Notes - Advanced features |
| 10.1.15 | Trait object types | Partial | See Notes - Advanced features |
| 10.1.16 | Impl trait type | Partial | See Notes - Advanced features |
| 10.1.17 | Type parameters | Partial | See Notes - Advanced features |
| 10.1.18 | Inferred type | Partial | See Notes - Advanced features |
| 10.2 | Dynamically Sized Types | Partial | See Notes - Advanced features |
| 10.3 | Type layout | Yes | |
| 10.4 | Interior mutability | Yes | |
| 10.5 | Subtyping and Variance | Yes | |
| 10.6 | Trait and lifetime bounds | Yes | |
| 10.7 | Type coercions | Partial | See Notes - Advanced features |
| 10.8 | Destructors | Partial | |
| 10.9 | Lifetime elision | Yes | |
| 11 | Special types and traits | Partial | |
Box<T> | Yes | ||
Rc<T> | Yes | ||
Arc<T> | Yes | ||
Pin<T> | Yes | ||
UnsafeCell<T> | Partial | ||
PhantomData<T> | Partial | ||
| Operator Traits | Partial | ||
Deref and DerefMut | Yes | ||
Drop | Partial | ||
Copy | Yes | ||
Clone | Yes | ||
| 14 | Linkage | Yes | |
| 15.1 | Unsafe functions | Yes | |
| 15.2 | Unsafe blocks | Yes | |
| 15.3 | Behavior considered undefined | Partial | |
| Data races | No | See Notes - Concurrency | |
| Dereferencing dangling raw pointers | Yes | ||
| Dereferencing unaligned raw pointers | No | ||
| Breaking pointer aliasing rules | No | ||
| Mutating immutable data | No | ||
| Invoking undefined behavior via compiler intrinsics | Partial | See Notes - Intrinsics | |
| Executing code compiled with platform features that the current platform does not support | No | ||
| Producing an invalid value, even in private fields and locals | No |
Kani aims to be an industrial verification tool. Most industrial crates may +include unsupported features in parts of their code that do not need to be +verified. In general, this should not prevent users using Kani to verify their code.
+Because of that, the general rule is that Kani generates an assert(false)
+statement followed by an assume(false) statement when compiling any
+unsupported feature. assert(false) will cause verification to fail if the
+statement is reachable during the verification stage, while assume(false) will
+block any further exploration of the path. However, the analysis will not be
+affected if the statement is not reachable from the code under verification, so
+users can still verify components of their code that do not use unsupported
+features.
In a few cases, Kani aborts execution if the analysis could be affected in +some way because of an unsupported feature (e.g., global ASM).
+Kani does not support assembly code for now. We may add it in the future but at +present there are no plans to do so.
+Check out the tracking issues for inline assembly (asm!
+macro) and global assembly
+(asm_global! macro) to know
+more about the current status.
Concurrent features are currently out of scope for Kani. In general, the +verification of concurrent programs continues to be an open research problem +where most tools that analyze concurrent code lack support for other features. +Because of this, Kani emits a warning whenever it encounters concurrent code and +compiles as if it was sequential code.
+Kani overrides a few common functions +(e.g., print macros) to provide a more verification friendly implementation.
+The semantics around some advanced features (traits, types, etc.) from Rust are +not formally defined which makes it harder to ensure that we can properly model +all their use cases.
+In particular, there are some outstanding issues to note here:
+Variant type in projections
+#448.We are particularly interested in bug reports concerning +these features, so please file a bug +report +if you're aware of one.
+Rust has two different strategies when a panic occurs:
+Currently, Kani does not support stack unwinding. This has some implications +regarding memory safety since programs sometimes rely on the unwinding logic to +ensure there is no resource leak or persistent data inconsistency. Check out +this issue for updates on +stack unwinding support.
+Reading uninitialized memory is +considered undefined behavior in Rust. +At the moment, Kani cannot detect if memory is uninitialized, but in practice +this is mitigated by the fact that all memory is initialized with +nondeterministic values. +Therefore, any code that depends on uninitialized data will exhibit nondeterministic behavior. +See this issue for more details.
+At present, we are aware of some issues with destructors, in particular those +related to advanced features.
+Please refer to Intrinsics for information +on the current support in Kani for Rust compiler intrinsics.
+Kani supports floating point numbers, but some supported operations on floats are "over-approximated."
+These are the trigonometric functions like sin and cos and the sqrt function as well.
+This means the verifier can raise errors that cannot actually happen when the code is run normally.
+For instance, (#1342) the sin/cos functions basically return a nondeterministic value between -1 and 1.
+In other words, they largely ignore their input and give very conservative answers.
+This range certainly includes the "real" value, so proof soundness is still preserved, but it means Kani could raise spurious errors that cannot actually happen.
+This makes Kani unsuitable for verifying some kinds of properties (e.g. precision) about numerical algorithms.
+Proofs that fail because of this problem can sometimes be repaired by introducing "stubs" for these functions that return a more acceptable approximation.
+However, note that the actual behavior of these functions can vary by platform/os/architecture/compiler, so introducing an "overly precise" approximation may introduce unsoundness: actual system behavior may produce different values from the stub's approximation.
The tables below try to summarize the current support in Kani for Rust intrinsics. +We define the level of support similar to how we indicate Rust feature support:
+In general, code generation for unsupported intrinsics follows the rule +described in Rust feature support - Code generation for unsupported +features.
+Any intrinsic not appearing in the tables below is considered not supported. +Please open a feature request +if your code depends on an unsupported intrinsic.
+| Name | Support | Notes |
|---|---|---|
| abort | Yes | |
| add_with_overflow | Yes | |
| arith_offset | Yes | |
| assert_inhabited | Yes | |
| assert_uninit_valid | Yes | |
| assert_zero_valid | Yes | |
| assume | Yes | |
| atomic_and_seqcst | Partial | See Atomics |
| atomic_and_acquire | Partial | See Atomics |
| atomic_and_acqrel | Partial | See Atomics |
| atomic_and_release | Partial | See Atomics |
| atomic_and_relaxed | Partial | See Atomics |
| atomic_cxchg_acqrel_acquire | Partial | See Atomics |
| atomic_cxchg_acqrel_relaxed | Partial | See Atomics |
| atomic_cxchg_acqrel_seqcst | Partial | See Atomics |
| atomic_cxchg_acquire_acquire | Partial | See Atomics |
| atomic_cxchg_acquire_relaxed | Partial | See Atomics |
| atomic_cxchg_acquire_seqcst | Partial | See Atomics |
| atomic_cxchg_relaxed_acquire | Partial | See Atomics |
| atomic_cxchg_relaxed_relaxed | Partial | See Atomics |
| atomic_cxchg_relaxed_seqcst | Partial | See Atomics |
| atomic_cxchg_release_acquire | Partial | See Atomics |
| atomic_cxchg_release_relaxed | Partial | See Atomics |
| atomic_cxchg_release_seqcst | Partial | See Atomics |
| atomic_cxchg_seqcst_acquire | Partial | See Atomics |
| atomic_cxchg_seqcst_relaxed | Partial | See Atomics |
| atomic_cxchg_seqcst_seqcst | Partial | See Atomics |
| atomic_cxchgweak_acqrel_acquire | Partial | See Atomics |
| atomic_cxchgweak_acqrel_relaxed | Partial | See Atomics |
| atomic_cxchgweak_acqrel_seqcst | Partial | See Atomics |
| atomic_cxchgweak_acquire_acquire | Partial | See Atomics |
| atomic_cxchgweak_acquire_relaxed | Partial | See Atomics |
| atomic_cxchgweak_acquire_seqcst | Partial | See Atomics |
| atomic_cxchgweak_relaxed_acquire | Partial | See Atomics |
| atomic_cxchgweak_relaxed_relaxed | Partial | See Atomics |
| atomic_cxchgweak_relaxed_seqcst | Partial | See Atomics |
| atomic_cxchgweak_release_acquire | Partial | See Atomics |
| atomic_cxchgweak_release_relaxed | Partial | See Atomics |
| atomic_cxchgweak_release_seqcst | Partial | See Atomics |
| atomic_cxchgweak_seqcst_acquire | Partial | See Atomics |
| atomic_cxchgweak_seqcst_relaxed | Partial | See Atomics |
| atomic_cxchgweak_seqcst_seqcst | Partial | See Atomics |
| atomic_fence_seqcst | Partial | See Atomics |
| atomic_fence_acquire | Partial | See Atomics |
| atomic_fence_acqrel | Partial | See Atomics |
| atomic_fence_release | Partial | See Atomics |
| atomic_load_seqcst | Partial | See Atomics |
| atomic_load_acquire | Partial | See Atomics |
| atomic_load_relaxed | Partial | See Atomics |
| atomic_load_unordered | Partial | See Atomics |
| atomic_max_seqcst | Partial | See Atomics |
| atomic_max_acquire | Partial | See Atomics |
| atomic_max_acqrel | Partial | See Atomics |
| atomic_max_release | Partial | See Atomics |
| atomic_max_relaxed | Partial | See Atomics |
| atomic_min_seqcst | Partial | See Atomics |
| atomic_min_acquire | Partial | See Atomics |
| atomic_min_acqrel | Partial | See Atomics |
| atomic_min_release | Partial | See Atomics |
| atomic_min_relaxed | Partial | See Atomics |
| atomic_nand_seqcst | Partial | See Atomics |
| atomic_nand_acquire | Partial | See Atomics |
| atomic_nand_acqrel | Partial | See Atomics |
| atomic_nand_release | Partial | See Atomics |
| atomic_nand_relaxed | Partial | See Atomics |
| atomic_or_seqcst | Partial | See Atomics |
| atomic_or_acquire | Partial | See Atomics |
| atomic_or_acqrel | Partial | See Atomics |
| atomic_or_release | Partial | See Atomics |
| atomic_or_relaxed | Partial | See Atomics |
| atomic_singlethreadfence_seqcst | Partial | See Atomics |
| atomic_singlethreadfence_acquire | Partial | See Atomics |
| atomic_singlethreadfence_acqrel | Partial | See Atomics |
| atomic_singlethreadfence_release | Partial | See Atomics |
| atomic_store_seqcst | Partial | See Atomics |
| atomic_store_release | Partial | See Atomics |
| atomic_store_relaxed | Partial | See Atomics |
| atomic_store_unordered | Partial | See Atomics |
| atomic_umax_seqcst | Partial | See Atomics |
| atomic_umax_acquire | Partial | See Atomics |
| atomic_umax_acqrel | Partial | See Atomics |
| atomic_umax_release | Partial | See Atomics |
| atomic_umax_relaxed | Partial | See Atomics |
| atomic_umin_seqcst | Partial | See Atomics |
| atomic_umin_acquire | Partial | See Atomics |
| atomic_umin_acqrel | Partial | See Atomics |
| atomic_umin_release | Partial | See Atomics |
| atomic_umin_relaxed | Partial | See Atomics |
| atomic_xadd_seqcst | Partial | See Atomics |
| atomic_xadd_acquire | Partial | See Atomics |
| atomic_xadd_acqrel | Partial | See Atomics |
| atomic_xadd_release | Partial | See Atomics |
| atomic_xadd_relaxed | Partial | See Atomics |
| atomic_xchg_seqcst | Partial | See Atomics |
| atomic_xchg_acquire | Partial | See Atomics |
| atomic_xchg_acqrel | Partial | See Atomics |
| atomic_xchg_release | Partial | See Atomics |
| atomic_xchg_relaxed | Partial | See Atomics |
| atomic_xor_seqcst | Partial | See Atomics |
| atomic_xor_acquire | Partial | See Atomics |
| atomic_xor_acqrel | Partial | See Atomics |
| atomic_xor_release | Partial | See Atomics |
| atomic_xor_relaxed | Partial | See Atomics |
| atomic_xsub_seqcst | Partial | See Atomics |
| atomic_xsub_acquire | Partial | See Atomics |
| atomic_xsub_acqrel | Partial | See Atomics |
| atomic_xsub_release | Partial | See Atomics |
| atomic_xsub_relaxed | Partial | See Atomics |
| blackbox | Yes | |
| bitreverse | Yes | |
| breakpoint | Yes | |
| bswap | Yes | |
| caller_location | No | |
| ceilf32 | Yes | |
| ceilf64 | Yes | |
| copy | Yes | |
| copy_nonoverlapping | Yes | |
| copysignf32 | Yes | |
| copysignf64 | Yes | |
| cosf32 | Partial | Results are overapproximated; this test explains how |
| cosf64 | Partial | Results are overapproximated; this test explains how |
| ctlz | Yes | |
| ctlz_nonzero | Yes | |
| ctpop | Yes | |
| cttz | Yes | |
| cttz_nonzero | Yes | |
| discriminant_value | Yes | |
| drop_in_place | No | |
| exact_div | Yes | |
| exp2f32 | Partial | Results are overapproximated |
| exp2f64 | Partial | Results are overapproximated |
| expf32 | Partial | Results are overapproximated |
| expf64 | Partial | Results are overapproximated |
| fabsf32 | Yes | |
| fabsf64 | Yes | |
| fadd_fast | Yes | |
| fdiv_fast | Partial | #809 |
| float_to_int_unchecked | No | |
| floorf32 | Yes | |
| floorf64 | Yes | |
| fmaf32 | No | |
| fmaf64 | No | |
| fmul_fast | Partial | #809 |
| forget | Yes | |
| frem_fast | No | |
| fsub_fast | Yes | |
| likely | Yes | |
| log10f32 | No | |
| log10f64 | No | |
| log2f32 | No | |
| log2f64 | No | |
| logf32 | Partial | Results are overapproximated |
| logf64 | Partial | Results are overapproximated |
| maxnumf32 | Yes | |
| maxnumf64 | Yes | |
| min_align_of | Yes | |
| min_align_of_val | Yes | |
| minnumf32 | Yes | |
| minnumf64 | Yes | |
| move_val_init | No | |
| mul_with_overflow | Yes | |
| nearbyintf32 | Yes | |
| nearbyintf64 | Yes | |
| needs_drop | Yes | |
| nontemporal_store | No | |
| offset | Partial | Doesn't check all UB conditions |
| powf32 | Partial | Results are overapproximated |
| powf64 | Partial | Results are overapproximated |
| powif32 | No | |
| powif64 | No | |
| pref_align_of | Yes | |
| prefetch_read_data | No | |
| prefetch_read_instruction | No | |
| prefetch_write_data | No | |
| prefetch_write_instruction | No | |
| ptr_guaranteed_eq | Yes | |
| ptr_guaranteed_ne | Yes | |
| ptr_offset_from | Partial | Doesn't check all UB conditions |
| raw_eq | Partial | Cannot detect uninitialized memory |
| rintf32 | Yes | |
| rintf64 | Yes | |
| rotate_left | Yes | |
| rotate_right | Yes | |
| roundf32 | Yes | |
| roundf64 | Yes | |
| rustc_peek | No | |
| saturating_add | Yes | |
| saturating_sub | Yes | |
| sinf32 | Partial | Results are overapproximated; this test explains how |
| sinf64 | Partial | Results are overapproximated; this test explains how |
| size_of | Yes | |
| size_of_val | Yes | |
| sqrtf32 | No | |
| sqrtf64 | No | |
| sub_with_overflow | Yes | |
| transmute | Partial | Doesn't check all UB conditions |
| truncf32 | Yes | |
| truncf64 | Yes | |
| try | No | #267 |
| type_id | Yes | |
| type_name | Yes | |
| typed_swap | Yes | |
| unaligned_volatile_load | No | See Notes - Concurrency |
| unaligned_volatile_store | No | See Notes - Concurrency |
| unchecked_add | Yes | |
| unchecked_div | Yes | |
| unchecked_mul | Yes | |
| unchecked_rem | Yes | |
| unchecked_shl | Yes | |
| unchecked_shr | Yes | |
| unchecked_sub | Yes | |
| unlikely | Yes | |
| unreachable | Yes | |
| variant_count | No | |
| volatile_copy_memory | No | See Notes - Concurrency |
| volatile_copy_nonoverlapping_memory | No | See Notes - Concurrency |
| volatile_load | Partial | See Notes - Concurrency |
| volatile_set_memory | No | See Notes - Concurrency |
| volatile_store | Partial | See Notes - Concurrency |
| wrapping_add | Yes | |
| wrapping_mul | Yes | |
| wrapping_sub | Yes | |
| write_bytes | Yes |
All atomic intrinsics are compiled as an atomic block where the operation is +performed. But as noted in Notes - Concurrency, Kani support for +concurrent verification is limited and not used by default. Verification on code +containing atomic intrinsics should not be trusted given that Kani assumes the +code to be sequential.
+Intrinsics from the platform_intrinsics feature.
| Name | Support | Notes |
|---|---|---|
simd_add | Yes | |
simd_and | Yes | |
simd_div | Yes | |
simd_eq | Yes | |
simd_extract | Yes | |
simd_ge | Yes | |
simd_gt | Yes | |
simd_insert | Yes | |
simd_le | Yes | |
simd_lt | Yes | |
simd_mul | Yes | |
simd_ne | Yes | |
simd_or | Yes | |
simd_rem | Yes | Doesn't check for floating point overflow #2669 |
simd_shl | Yes | |
simd_shr | Yes | |
simd_shuffle* | Yes | |
simd_sub | Yes | |
simd_xor | Yes |
In general, unstable Rust features are out of scope and any support +for them available in Kani should be considered unstable as well.
+The following are examples of unstable features that are not supported +in Kani:
+As explained in Comparison with other +tools, Kani is based on a +technique called model checking, which verifies a program without actually +executing it. It does so through encoding the program and analyzing the encoded +version. The encoding process often requires "modeling" some of the library +functions to make them suitable for analysis. Typical examples of functionality +that requires modeling are system calls and I/O operations. In some cases, Kani +performs such encoding through overriding some of the definitions in the Rust +standard library.
+The following table lists some of the symbols that Kani
+overrides and a description of their behavior compared to the std versions:
| Name | Description |
|---|---|
assert, assert_eq, and assert_ne macros | Skips string formatting code, generates a more informative message and performs some instrumentation |
debug_assert, debug_assert_eq, and debug_assert_ne macros | Rewrites as equivalent assert* macro |
print, eprint, println, and eprintln macros | Skips string formatting and I/O operations |
unreachable macro | Skips string formatting and invokes panic!() |
std::process::{abort, exit} functions | Invokes panic!() to abort the execution |
Kani currently ships with a kani crate that provide APIs to allow users to
+write and configure their harnesses.
+These APIs are tightly coupled with each Kani version, so they are not
+published yet at https://crates.io.
You can find their latest documentation here:
+This section collects frequently asked questions about Kani. +Please consider opening an issue if you have a question that would like to see here.
+kani::assume(false). Why?kani::assume(false) (or kani::assume(cond) where cond is a condition that results in false in the context of the program), won't cause errors in Kani.
+Instead, such an assumption has the effect of blocking all the symbolic execution paths from the assumption.
+Therefore, all checks after the assumption should appear as UNREACHABLE.
+That's the expected behavior for kani::assume(false) in Kani.
If you didn't expect certain checks in a harness to be UNREACHABLE, we recommend using the kani::cover macro to determine what conditions are possible in case you've over-constrained the harness.
kani::Arbitrary trait for a type that's not from my crate, and got the error
+only traits defined in the current crate can be implemented for types defined outside of the crate.
+What does this mean? What can I do?This error is due to a violation of Rust's orphan rules for trait implementations, which are explained here. +In that case, you'll need to write a function that builds an object from non-deterministic variables. +Inside this function you would simply return an arbitrary value by generating arbitrary values for its components.
+For example, let's assume the type you're working with is this enum:
+#[derive(Copy, Clone)]
+pub enum Rating {
+ One,
+ Two,
+ Three,
+}
+Then, you can match on a non-deterministic integer (supplied by kani::any) to return non-deterministic Rating variants:
pub fn any_rating() -> Rating {
+ match kani::any() {
+ 0 => Rating::One,
+ 1 => Rating::Two,
+ _ => Rating::Three,
+ }
+ }
+More details about this option, which also useful in other cases, can be found here.
+If the type comes from std (Rust's standard library), you can open a request for adding Arbitrary implementations to the Kani library.
+Otherwise, there are more involved options to consider:
Arbitrary there.Arbitrary implementation to the external crate that defines the type.This section is the main reference for Kani. +It contains sections that informally describe its main features.
+ +In Kani, attributes are used to mark functions as harnesses and control their execution. +This section explains the attributes available in Kani and how they affect the verification process.
+At present, the available Kani attributes are the following:
+#[kani::proof]#[kani::should_panic]#[kani::unwind(<number>)]#[kani::solver(<solver>)]#[kani::stub(<original>, <replacement>)]#[kani::proof]The #[kani::proof] attribute specifies that a function is a proof harness.
Proof harnesses are similar to test harnesses, especially property-based test harnesses,
+and they may use functions from the Kani API (e.g., kani::any()).
+A proof harness is the smallest verification unit in Kani.
When Kani is run, either through kani or cargo kani, it'll first collect all proof harnesses
+(i.e., functions with the attribute #[kani::proof]) and then attempt to verify them.
If we run Kani on this example:
+#[kani::proof]
+fn my_harness() {
+ assert!(1 + 1 == 2);
+}
+We should see a line in the output that says Checking harness my_harness... (assuming my_harness is the only harness in our code).
+This will be followed by multiple messages that come from CBMC (the verification engine used by Kani) and the verification results.
Using any other Kani attribute without #[kani::proof] will result in compilation errors.
The #[kani::proof] attribute can only be added to functions without parameters.
#[kani::should_panic]The #[kani::should_panic] attribute specifies that a proof harness is expected to panic.
This attribute allows users to exercise negative verification.
+It's analogous to how #[should_panic] allows users to exercise negative testing for Rust unit tests.
This attribute only affects the overall verification result.
+In particular, using the #[kani::should_panic] attribute will return one of the following results:
VERIFICATION:- FAILED (encountered no panics, but at least one was expected) if there were no failed checks.VERIFICATION:- FAILED (encountered failures other than panics, which were unexpected) if there were failed checks but not all them were related to panics.VERIFICATION:- SUCCESSFUL (encountered one or more panics as expected) otherwise.At the moment, to determine if a check is related to a panic, we check if its class is assertion.
+The class is the second member in the property name, the triple that's printed after Check X: : <function>.<class>.<number>.
+For example, the class in Check 1: my_harness.assertion.1 is assertion, so this check is considered to be related to a panic.
++NOTE: The
+#[kani::should_panic]is only recommended for writing +harnesses which complement existing harnesses that don't use the same +attribute. In order words, it's only recommended to write negative harnesses +after having written positive harnesses that successfully verify interesting +properties about the function under verification.
The #[kani::should_panic] attribute verifies that there are one or more failed checks related to panics.
+At the moment, it's not possible to pin it down to specific panics.
+Therefore, it's possible that the panics detected with #[kani::should_panic] aren't the ones that were originally expected after a change in the code under verification.
Let's assume we're using the Device from this example:
struct Device {
+ is_init: bool,
+}
+
+impl Device {
+ fn new() -> Self {
+ Device { is_init: false }
+ }
+
+ fn init(&mut self) {
+ assert!(!self.is_init);
+ self.is_init = true;
+ }
+}
+We may want to verify that calling device.init() more than once should result in a panic.
+We can do so with the following harness:
#[kani::proof]
+#[kani::should_panic]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+Running Kani on it will produce the result VERIFICATION:- SUCCESSFUL (encountered one or more panics as expected)
#[kani::unwind(<number>)]The #[kani::unwind(<number>)] attribute specifies that all loops must be unwound up to <number> times.
By default, Kani attempts to unwind all loops automatically.
+However, this unwinding process doesn't always terminate.
+The #[kani::unwind(<number>)] attribute will:
<number> times.After the unwinding stage, Kani will attempt to verify the harness.
+If the #[kani::unwind(<number>)] attribute was specified, there's a chance that one or more loops weren't unwound enough times.
+In that case, there will be at least one failed unwinding assertion (there's one unwinding assertion for each loop), causing verification to fail.
Check the Loops, unwinding and bounds section for more information about unwinding.
+Let's assume we've written this code which contains a loop:
+fn my_sum(vec: &Vec<u32>) -> u32 {
+ let mut sum = 0;
+ for elem in vec {
+ sum += elem;
+ }
+ sum
+}
+
+#[kani::proof]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+Running this example on Kani will produce a successful verification result.
+In this case, Kani automatically finds the required unwinding value (i.e., the number of times it needs to unwind all loops).
+This means that the #[kani::unwind(<number>)] attribute isn't needed, as we'll see soon.
+In general, the required unwinding value is equal to the maximum number of iterations for all loops, plus one.
+The required unwinding value in this example is 4: the 3 iterations in the for elem in vec loop, plus 1.
Let's see what happens if we force a lower unwinding value with #[kani::unwind(3)]:
#[kani::proof]
+#[kani::unwind(3)]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+As we mentioned, trying to verify this harness causes an unwinding failure:
+SUMMARY:
+ ** 1 of 187 failed (186 undetermined)
+Failed Checks: unwinding assertion loop 0
+ File: "/home/ubuntu/devices/src/main.rs", line 32, in my_sum
+
+VERIFICATION:- FAILED
+[Kani] info: Verification output shows one or more unwinding failures.
+[Kani] tip: Consider increasing the unwinding value or disabling `--unwinding-assertions`.
+Kani cannot verify the harness because there is at least one unwinding assertion failure.
+But, if we use #[kani::unwind(4)], which is the right unwinding value we computed earlier:
#[kani::proof]
+#[kani::unwind(4)]
+fn my_harness() {
+ let vec = vec![1, 2, 3];
+ let sum = my_sum(&vec);
+ assert!(sum == 6);
+}
+We'll get a successful result again:
+SUMMARY:
+ ** 0 of 186 failed
+
+VERIFICATION:- SUCCESSFUL
+#[kani::solver(<solver>)]Changes the solver to be used by Kani's verification engine (CBMC).
+This may change the verification time required to verify a harness.
+At present, <solver> can be one of:
minisat: MiniSat.cadical (default): CaDiCaL.kissat: kissat.bin="<SAT_SOLVER_BINARY>": A custom solver binary, "<SAT_SOLVER_BINARY>", that must be in path.Kani will use the CaDiCaL solver in the following example:
+#[kani::proof]
+#[kani::solver(cadical)]
+fn check() {
+ let mut a = [2, 3, 1];
+ a.sort();
+ assert_eq!(a[0], 1);
+ assert_eq!(a[1], 2);
+ assert_eq!(a[2], 3);
+}
+Changing the solver may result in different verification times depending on the harness.
+Note that the default solver may vary depending on Kani's version. +We highly recommend users to annotate their harnesses if the choice of solver +has a major impact on performance, even if the solver used is the current +default one.
+#[kani::stub(<original>, <replacement>)]Replaces the function/method with name
Check the Stubbing section for more information about stubbing.
+ +Stubbing (or mocking) is an unstable feature which allows users to specify that certain items should be replaced with stubs (mocks) of those items during verification. +At present, the only items where stubbing can be applied are functions and methods (see limitations for more details).
+In general, we have identified three reasons where users may consider stubbing:
+In most cases, stubbing enables users to verify code that otherwise would be impractical to verify. +Although definitions for mocking (normally used in testing) and stubbing may slightly differ depending on who you ask, we often use both terms interchangeably.
+The stubbing feature can be enabled by using the --enable-stubbing option when calling Kani.
+Since it's an unstable feature, it requires passing the --enable-unstable option in addition to --enable-stubbing.
At present, the only component of the stubbing feature is the #[kani::stub(<original>, <replacement>)] attribute,
+which allows you to specify the pair of functions/methods that must be stubbed in a harness.
#[kani::stub(...)] attributeThe stub attribute #[kani::stub(<original>, <replacement>)] is the main tool of the stubbing feature.
It indicates to Kani that the function/method with name <original> should be replaced with the function/method with name <replacement> during the compilation step.
+The names of these functions/methods are resolved using Rust's standard name resolution rules.
+This includes support for imports like use foo::bar as baz, as well as imports of multiple versions of the same crate.
This attribute must be specified on a per-harness basis. This provides a high degree of flexibility for users, since they are given the option to stub the same item with different replacements (or not use stubbing at all) depending on the proof harness. In addition, the attribute can be specified multiple times per harness, so that multiple (non-conflicting) stub pairings are supported.
+randomLet's see a simple example where we use the rand::random function
+to generate an encryption key.
#[cfg(kani)]
+#[kani::proof]
+fn encrypt_then_decrypt_is_identity() {
+ let data: u32 = kani::any();
+ let encryption_key: u32 = rand::random();
+ let encrypted_data = data ^ encryption_key;
+ let decrypted_data = encrypted_data ^ encryption_key;
+ assert_eq!(data, decrypted_data);
+}
+
+At present, Kani fails to verify this example due to issue #1781.
+However, we can work around this limitation thanks to the stubbing feature:
+#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(rand::random, mock_random)]
+fn encrypt_then_decrypt_is_identity() {
+ let data: u32 = kani::any();
+ let encryption_key: u32 = rand::random();
+ let encrypted_data = data ^ encryption_key;
+ let decrypted_data = encrypted_data ^ encryption_key;
+ assert_eq!(data, decrypted_data);
+}
+Here, the #[kani::stub(rand::random, mock_random)] attribute indicates to Kani that it should replace rand::random with the stub mock_random.
+Note that this is a fair assumption to do: rand::random is expected to return any u32 value, just like kani::any.
Now, let's run it through Kani:
+cargo kani --enable-unstable --enable-stubbing --harness encrypt_then_decrypt_is_identity
+The verification result is composed of a single check: the assertion corresponding to assert_eq!(data, decrypted_data).
RESULTS:
+Check 1: encrypt_then_decrypt_is_identity.assertion.1
+ - Status: SUCCESS
+ - Description: "assertion failed: data == decrypted_data"
+ - Location: src/main.rs:18:5 in function encrypt_then_decrypt_is_identity
+
+
+SUMMARY:
+ ** 0 of 1 failed
+
+VERIFICATION:- SUCCESSFUL
+Kani shows that the assertion is successful, avoiding any issues that appear if we attempt to verify the code without stubbing.
+In the following, we describe all the limitations of the stubbing feature.
+The usage of stubbing is limited to the verification of a single harness.
+Therefore, users are required to pass the --harness option when using the stubbing feature.
In addition, this feature isn't compatible with concrete playback.
+Support for stubbing is currently limited to functions and methods. All other items aren't supported.
+The following are examples of items that could be good candidates for stubbing, but aren't supported:
+We acknowledge that support for method stubbing isn't as ergonomic as it could be.
+A common problem when attempting to define method stubs is that we don't have access to the private fields of an object (i.e., the fields in self).
+One workaround is to use the unsafe function std::mem::transmute, as in this example:
struct Foo {
+ x: u32,
+}
+
+impl Foo {
+ pub fn m(&self) -> u32 {
+ 0
+ }
+}
+
+struct MockFoo {
+ pub x: u32,
+}
+
+fn mock_m(foo: &Foo) -> u32 {
+ let mock: &MockFoo = unsafe { std::mem::transmute(foo) };
+ return mock.x;
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(Foo::m, mock_m)]
+fn my_harness() { ... }
+However, this isn't recommended since it's unsafe and error-prone. +In general, we don't recommend stubbing for private functions/methods. +Doing so can lead to brittle proofs: private functions/methods are subject to change or removal even in version minor upgrades (they aren't part of the APIs). +Therefore, proofs that rely on stubbing for private functions/methods might incur a high maintenance burden.
+Given a set of original-replacement pairs, Kani will exit with an error if:
original function does not exist;replacement stub does not exist;original function is mapped to multiple replacement functions); orreplacement stub is not compatible with the signature of the original function/method (see next section).We consider a stub and a function/method to be compatible if all the following conditions are met:
+bar<A, B>(x: A, y: B) -> B is considered to have a type compatible with the function foo<S, T>(x: S, y: T) -> T.The final point is the most subtle. +We don't require that a type parameter in the signature of the stub implements the same traits as the corresponding type parameter in the signature of the original function/method. +However, Kani will reject a stub if a trait mismatch leads to a situation where a statically dispatched call to a trait method cannot be resolved during monomorphization. +For example, this restriction rules out the following harness:
+fn foo<T>(_x: T) -> bool {
+ false
+}
+
+trait DoIt {
+ fn do_it(&self) -> bool;
+}
+
+fn bar<T: DoIt>(x: T) -> bool {
+ x.do_it()
+}
+
+#[kani::proof]
+#[kani::stub(foo, bar)]
+fn harness() {
+ assert!(foo("hello"));
+}
+The call to the trait method DoIt::do_it is unresolvable in the stub bar when the type parameter T is instantiated with the type &str.
+On the other hand, this approach provides some flexibility, such as allowing our earlier example of mocking rand::random:
+both rand::random and my_random have type () -> T, but in the first case T is restricted such that the type Standard implements Distribution<T>,
+whereas in the latter case T has to implement kani::Arbitrary.
+This trait mismatch is allowed because at this call site T is instantiated with u32, which implements kani::Arbitrary.
Kani relies on a quite extensive range of tests to perform regression testing. +Regression testing can be executed by running the command:
+./scripts/kani-regression.sh
+The kani-regression.sh script executes different testing commands, which we classify into:
See below for a description of each one.
+Note that regression testing is run whenever a Pull Request is opened, updated or merged +into the main branch. Therefore, it's a good idea to run regression testing locally before +submitting a Pull Request for Kani.
+The Kani testing suites are the main testing resource for Kani. In most cases, the +tests contained in the Kani testing suites are single Rust files that are run +using the following command:
+kani file.rs <options>
+Command-line options can be passed to the test by adding a special +comment to the file. See testing options for more details.
+In particular, the Kani testing suites are composed of:
+kani: The main testing suite for Kani. The test is a single Rust file that's
+run through Kani. In general, the test passes if verification with Kani
+is successful, otherwise it fails.firecracker: Works like kani but contains tests inspired by
+Firecracker code.prusti: Works like kani but contains tests from the
+Prusti tool.smack: Works like kani but contains tests from the
+SMACK tool.kani-fixme: Similar to kani, but runs ignored tests from the kani testing
+suite (i.e., tests with fixme or ignore in their name).
+Allows us to detect when a previously not supported test becomes
+supported. More details in "Fixme" tests.expected: Similar to kani but with an additional check which ensures that
+lines appearing in *.expected files appear in the output
+generated by kani.ui: Works like expected, but focuses on the user interface (e.g.,
+warnings) instead of the verification output.cargo-kani: This suite is designed to test the cargo-kani command. As such,
+this suite works with packages instead of single Rust files.
+Arguments can be specified in the Cargo.toml configuration file.
+Similar to the expected suite, we look for *.expected files
+for each harness in the package.cargo-ui: Similar to cargo-kani, but focuses on the user interface like the ui test suite.script-based-pre: This suite is useful to execute script-based tests, and
+also allows checking expected output and exit codes after
+running them. The suite uses the exec mode, described in
+more detail here.We've extended
+compiletest (the
+Rust compiler testing framework) to work with these suites. That way, we take
+advantage of all compiletest features (e.g., parallel execution).
The process of running single-file tests is split into three stages:
+check: This stage uses the Rust front-end to detect if the example is valid
+Rust code.codegen: This stage uses the Kani back-end to determine if we can generate
+GotoC code.verify: This stage uses CBMC to obtain a verification result.If a test fails, the error message will include the stage where it failed:
+error: test failed: expected check success, got failure
+When working on a test that's expected to fail, there are two options to +indicate an expected failure. The first one is to add a comment
+// kani-<stage>-fail
+at the top of the test file, where <stage> is the stage where the test is
+expected to fail.
The other option is to use the predicate kani::expect_fail(cond, message)
+included in the Kani library. The cond in kani::expect_fail is a condition
+that you expect not to hold during verification. The testing framework expects
+one EXPECTED FAIL message in the verification output for each use of the
+predicate.
++NOTE:
+kani::expect_failis only useful to indicate failure in the +verifystage, errors in other stages will be considered testing failures.
Many tests will require passing command-line options to Kani. These options can +be specified in single Rust files by adding a comment at the top of the file:
+// kani-flags: <options>
+For example, to use an unwinding value of 4 in a test, we can write:
+// kani-flags: --default-unwind 4
+For cargo-kani tests, the preferred way to pass command-line options is adding
+them to Cargo.toml. See Usage on a package for more details.
Any test containing fixme or ignore in its name is considered a test not
+supported for some reason (i.e., they return an unexpected verification result).
However, "fixme" tests included in the kani folder are run via the kani-fixme
+testing suite. kani-fixme works on test files from kani but:
fixme or ignore (ignoring the rest).We welcome contributions with "fixme" tests which demonstrate a bug or +unsupported feature in Kani. Ideally, the test should include some comments +regarding:
+To include a new "fixme" test in kani you only need to ensure its name contains
+fixme or ignore. If your changes to Kani cause a "fixme" test to become
+supported, you only need to rename it so the name does not contain fixme nor
+ignore.
These tests follow the +Rust unit testing +style.
+At present, Kani runs unit tests from the following packages:
+cprover_bindingskani-compilercargo-kaniWe use the Python unit testing framework to +test the CBMC JSON parser.
+These are tests which are run using scripts. Scripting gives us the ability to +perform ad-hoc checks that cannot be done otherwise. They are currently used +for:
+In fact, most of them are equivalent to running cargo kani and performing
+checks on the output. The downside to scripting is that these tests will always
+be run, even if there have not been any changes since the last time the
+regression was run.
++NOTE: With the addition of the
+execmode forcompiletest(described +below), we'll be migrating these script-based tests to other suites using the +execmode. Theexecmode allows us to take advantage ofcompiletest+features while executing script-based tests (e.g., parallel execution).
exec modeThe exec mode in compiletest allows us to execute script-based tests, in
+addition to checking expected output and exit codes after running them.
In particular, tests are expected to be placed directly under the test directory
+(e.g., script-based-pre) in a directory with a config.yml file, which
+should contain:
script: The path to the script to be executed.expected (optional): The path to the .expected file to
+use for output comparison.exit_code (optional): The exit code to be returned by executing
+the script (a zero exit code is expected if not specified).For example, let's say want to test the script exit-one.sh:
echo "Exiting with code 1!"
+exit 1
+In this case, we'll create a folder that contains the config.yml file:
script: exit-one.sh
+expected: exit-one.expected
+exit_code: 1
+where exit-one.expected is simply a text file such as:
Exiting with code 1!
+If expected isn't specified, the output won't be checked. If exit_code isn't
+specified, the exec mode will check the exit code was zero.
Note that all paths specified in the config.yml file are local to the test
+directory, which is the working directory assumed when executing the test. This
+is meant to avoid problems when executing the test manually.
This section explains how to run Kani on a large number of crates +downloaded from git forges. You may want to do this if you are going +to test Kani's ability to handle Rust features found in projects out +in the wild.
+For the first half, we will explain how to use data from crates.io to +pick targets. Second half will explain how to use a script to run on a +list of selected repositories.
+In picking repositories, you may want to select by metrics like +popularity or by the presence of certain features. In this section, we +will explain how to select top ripostes by download count.
+We will use the db-dump method of getting data from crates.io as it
+is zero cost to their website and gives us SQL access. To start, have
+the following programs set up on your computer.
docker-compose.yaml. version: '3.3' may need to change.version: '3.3'
+services:
+ db:
+ image: postgres:latest
+ restart: always
+ environment:
+ - POSTGRES_USER=postgres
+ - POSTGRES_PASSWORD=postgres
+ volumes:
+ - crates-data:/var/lib/postgresql/data
+ logging:
+ driver: "json-file"
+ options:
+ max-size: "50m"
+volumes:
+ crates-data:
+ driver: local
+Then, run the following to start the setup.
+docker-compose up -d
+Once set up, run docker ls to figure out the container's name. We
+will refer to the name as $CONTAINER_NAME from now on.
Download actual data from crates.io. First, run the following
+command to get a shell in the container: docker exec -it --user postgres $CONTAINER_NAME bash. Now, run the following to grab and
+install the data into the repository. Please note that this may
+take a while.
wget https://static.crates.io/db-dump.tar.gz
+tar -xf db-dump.tar.gz
+psql postgres -f */schema.sql
+psql postgres -f */import.sql
+Extract the data. In the same docker shell, run the following to +extract the top 1k repositories. Other SQL queries may be used if +you want another criteria
+\copy
+(SELECT name, repository, downloads FROM crates
+WHERE repository LIKE 'http%' ORDER BY DOWNLOADS DESC LIMIT 1000)
+to 'top-1k.csv' csv header;
+Clean the data. The above query will capture duplicates paths that +are deeper than the repository. You can clean these out.
+cat top-1k.csv | awk -F ',' '{ print $2 }' | grep -v 'http.*'sed 's/tree\/master.*$//g'sort | uniq --uniqueIn this step we will download the list of repositories using a script +assess-scan-on-repos.sh
+Make sure to have Kani ready to run. For that, see the build instructions.
+From the repository root, you can run the script with
+./scripts/exps/assess-scan-on-repos.sh $URL_LIST_FILE where
+$URL_LIST_FILE points to a line-delimited list of URLs you want to
+run Kani on. Repositories that give warnings or errors can be grepping
+for with "STDERR Warnings" and "Error exit in" respectively.
This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Kani is an open-source verification tool that uses automated reasoning to analyze Rust programs. In order to +integrate feedback from developers and users on future changes to Kani, we decided to follow a light-weight +"RFC" (request for comments) process.
+You should create an RFC in one of two cases:
+Bugs and improvements to existing features do not require an RFC. +If you are in doubt, feel free to create a feature request and discuss the next steps in the new issue. +Your PR reviewer may also request an RFC if your change appears to fall into category 1 or 2.
+You do not necessarily need to create an RFC immediately. It is our experience that it is often best to write some "proof of concept" code to test out possible ideas before writing the formal RFC.
+This is the overall workflow for the RFC process:
+ Create RFC ──> Receive Feedback ──> Accepted?
+ │ ∧ │ Y
+ ∨ │ ├───> Implement ───> Test + Feedback ───> Stabilize?
+ Revise │ N │ Y
+ └───> Close PR ├───> RFC Stable
+ │ N
+ └───> Remove feature
+rfc/src/template.md) to rfc/src/rfcs/<ID_NUMBER><my-feature>.md.rfc/src/SUMMARY.md-Z <FEATURE_ID> as an argument to Kani.-Z <FEATURE_ID> guard and that marks the RFC status as "STABLE".
+Kani is an open-source verification tool that uses automated reasoning to analyze Rust programs. In order to +integrate feedback from developers and users on future changes to Kani, we decided to follow a light-weight +"RFC" (request for comments) process.
+You should create an RFC in one of two cases:
+Bugs and improvements to existing features do not require an RFC. +If you are in doubt, feel free to create a feature request and discuss the next steps in the new issue. +Your PR reviewer may also request an RFC if your change appears to fall into category 1 or 2.
+You do not necessarily need to create an RFC immediately. It is our experience that it is often best to write some "proof of concept" code to test out possible ideas before writing the formal RFC.
+This is the overall workflow for the RFC process:
+ Create RFC ──> Receive Feedback ──> Accepted?
+ │ ∧ │ Y
+ ∨ │ ├───> Implement ───> Test + Feedback ───> Stabilize?
+ Revise │ N │ Y
+ └───> Close PR ├───> RFC Stable
+ │ N
+ └───> Remove feature
+rfc/src/template.md) to rfc/src/rfcs/<ID_NUMBER><my-feature>.md.rfc/src/SUMMARY.md-Z <FEATURE_ID> as an argument to Kani.-Z <FEATURE_ID> guard and that marks the RFC status as "STABLE".
+Kani is an open-source verification tool that uses automated reasoning to analyze Rust programs. In order to +integrate feedback from developers and users on future changes to Kani, we decided to follow a light-weight +"RFC" (request for comments) process.
+You should create an RFC in one of two cases:
+Bugs and improvements to existing features do not require an RFC. +If you are in doubt, feel free to create a feature request and discuss the next steps in the new issue. +Your PR reviewer may also request an RFC if your change appears to fall into category 1 or 2.
+You do not necessarily need to create an RFC immediately. It is our experience that it is often best to write some "proof of concept" code to test out possible ideas before writing the formal RFC.
+This is the overall workflow for the RFC process:
+ Create RFC ──> Receive Feedback ──> Accepted?
+ │ ∧ │ Y
+ ∨ │ ├───> Implement ───> Test + Feedback ───> Stabilize?
+ Revise │ N │ Y
+ └───> Close PR ├───> RFC Stable
+ │ N
+ └───> Remove feature
+rfc/src/template.md) to rfc/src/rfcs/<ID_NUMBER><my-feature>.md.rfc/src/SUMMARY.md-Z <FEATURE_ID> as an argument to Kani.-Z <FEATURE_ID> guard and that marks the RFC status as "STABLE".
+new_feature)Short (1-2 sentences) description of the feature. What is this feature about?
+Imagine this as your elevator pitch directed to users as well as Kani developers.
+If this RFC is related to change in the architecture without major user impact, +think about the long term impact for user. +I.e.: what future work will this enable.
+This should be a description on how users will interact with the feature. +Users should be able to read this section and understand how to use the feature. +Do not include implementation details in this section, neither discuss the rationale behind the chosen UX.
+Please include:
+If the RFC is related to architectural changes and there are no visible changes to UX, please state so. +No further explanation is needed.
+This is the beginning of the technical portion of the RFC. +From now on, your main audience is Kani developers, so it's OK to assume readers know Kani architecture.
+Please provide a high level description your design.
+kani-compiler, kani-driver, metadata, proc-macros, installation...)We recommend you to leave this empty for the first version of your RFC.
+This is the section where you discuss the decisions you made.
+List of open questions + an optional link to an issue that captures the work required to address the open question. +Capture the details of each open question in their respective issue, not here.
+Example:
+Make sure all open questions are addressed before stabilization.
+Optional Section: List of extensions and possible improvements that you predict for this feature that is out of +the scope of this RFC.
+Feel free to add as many items as you want, but please refrain from adding too much detail. +If you want to capture your thoughts or start a discussion, please create a feature request. +You are welcome to add a link to the new issue here.
+This unique ident should be used to enable features proposed in the RFC using -Z <ident> until the feature has been stabilized.
mir_linker)Fix linking issues with the rust standard library in a scalable manner by only generating goto-program for +code that is reachable from the user harnesses.
+The main goal of this RFC is to enable Kani users to link against all supported constructs from the std library.
+Currently, Kani will only link to items that are either generic or have an inline annotation.
The approach introduced in this RFC will have the following secondary benefits.
+One downside is that we will include a pre-compiled version of the std, our release bundle will double in size
+(See Rational and Alternatives
+for more information on the size overhead).
+This will negatively impact the time taken to set up Kani
+(triggered by either the first time a user invokes kani | cargo-kani , or explicit invoke the subcommand setup).
Once this RFC has been stabilized users shall use Kani in the same manner as they have been today.
+Until then, we wil add an unstable option --mir-linker to enable the cross-crate reachability analysis
+and the generation of the goto-program only when compiling the target crate.
Kani setup will likely take longer and more disk space as mentioned in the section above.
+This change will not be guarded by --mir-linker option above.
In a nutshell, we will no longer generate a goto-program for every crate we compile. +Instead, we will generate the MIR for every crate, and we will generate only one goto-program. +This model will only include items reachable from the target crate's harnesses.
+The current system flow for a crate verification is the following (Kani here represents either kani | cargo-kani
+executable):
kani-compiler will generate a goto-program.
+This model includes everything reachable from the crate's public functions.goto-cc.
+This step will also link against Kani's C library.goto-instrument to prune the linked model to only include items reachable from the given harness.goto-instrument and cbmc calls.After this RFC, the system flow would be slightly different:
+kani-compiler will generate an artifact that includes the MIR representation
+of all items in the crate.goto-cc will still be invoked to link the generated model against Kani's C library.This feature will require three main changes to Kani which are detailed in the sub-sections below.
+Kani currently uses rustup sysroot to gather information from the standard library constructs.
+The artifacts from this sysroot include the MIR for generic items as well as for items that may be included in
+a crate compilation (e.g.: functions marked with #[inline] annotation).
+The artifacts do not include the MIR for items that have already been compiled to the std shared library.
+This leaves a gap that cannot be filled by the kani-compiler;
+thus, we are unable to translate these items into goto-program.
In order to fulfill this gap, we must compile the standard library from scratch.
+This RFC proposes a similar method to what MIRI implements.
+We will generate our own sysroot using the -Z always-encode-mir compilation flag.
+This sysroot will be pre-compiled and included in our release bundle.
We will compile kani's libraries (kani and std) also with -Z always-encode-mir
+and with the new sysroot.
kani-compiler will include a new reachability module to traverse over the local and external MIR items.
+This module will monomorphize all generic code as it's performing the traversal.
The traversal logic will be customizable allowing different starting points to be used.
+The two options to be included in this RFC is starting from all local harnesses
+(tagged with #[kani::proof]) and all public functions in the local crate.
The kani-compiler behavior will be customizable via a new flag:
--reachability=[ harnesses | pub_fns | none | legacy | tests ]
+where:
+harnesses: Use the local harnesses as the starting points for the reachability analysis.pub_fns: Use the public local functions as the starting points for the reachability analysis.none: This will be the default value if --reachability flag is not provided. It will skip
+reachability analysis. No goto-program will be generated.
+This will be used to compile dependencies up to the MIR level.
+kani-compiler will still generate artifacts with the crate's MIR.tests: Use the functions marked as tests with #[tests] as the starting points for the analysis.legacy: Mimics rustc behavior by invoking
+rustc_monomorphizer::collect_and_partition_mono_items() to collect the items to be generated.
+This will not include many items that go beyond the crate boundary.
+This option was only kept for now for internal usage in some of our compiler tests.
+It cannot be used as part of the end to end verification flow, and it will be removed in the future.These flags will not be exposed to the final user.
+They will only be used for the communication between kani-driver and kani-compiler.
The flags described in the section above will be used by kani-driver to implement the new system flow.
+For that, we propose the following mechanism:
For standalone kani, we will pass the option --reachability=harnesses to kani-compiler.
For cargo-kani, we will replace
cargo build <FLAGS>
+with:
+cargo rustc <FLAGS> -- --reachability=harnesses
+to build everything.
+This command will compile all dependencies without the --reachability argument, and it will only pass harnesses
+value to the compiler when compiling the target crate.
Not doing anything is not an alternative, since this fixes a major gap in Kani's usability.
+kani-compiler.#[no_mangle] annotation
+(Issue-661).Failures in the linking stage would not impact the tool soundness. I anticipate the following failure scenarios:
+The new reachability code would be highly dependent on the rustc unstable APIs, which could increase
+the cost of the upstream synchronization.
+That said, the APIs that would be required are already used today.
Finally, this implementation relies on a few unstable options from cargo and rustc.
+These APIs are used by other tools such as MIRI, so we don't see a high risk that they would be removed.
The other options explored were:
+*symtab.json files.symtab2gb) and link them into one single goto-program.
+Ship the generated model.Both would still require shipping the compiler metadata (via rlib or rmeta) for the kani library, its
+dependencies, and kani_macro.so.
Both alternatives are very similar. They only differ on the artifact that would be shipped.
+They require generating and shipping a custom sysroot;
+however, there is no need to implement the reachability algorithm.
We implemented a prototype for the MIR linker and one for the alternatives.
+Both prototypes generate the sysroot as part of the cargo kani flow.
We performed a small experiment (on a c5.4xlarge ec2 instance running Ubuntu 20.04) to assess the options.
For this experiment, we used the following harness:
+#[kani::proof]
+#[kani::unwind(4)]
+pub fn check_format() {
+ assert!("2".parse::<u32>().unwrap() == 2);
+}
+The experiment showed that the MIR linker approach is much more efficient.
+See the table bellow for the breakdown of time (in seconds) taken for each major step of +the harness verification:
+| Stage | MIR Linker | Alternative 1 |
|---|---|---|
| compilation | 22.2s | 64.7s |
| goto-program generation | 2.4s | 90.7s |
| goto-program linking | 0.8s | 33.2s |
| code instrumentation | 0.8s | 33.1 |
| verification | 0.5s | 8.5s |
It is possible that goto-cc time can be improved, but this would also require further experimentation and
+expertise that we don't have today.
Every option would require a custom sysroot to either be built or shipped with Kani.
+The table below shows the size of the sysroot files for the alternative #2
+(goto-program files) vs compiler artifacts (*.rmeta files)
+files with -Z always-encode-mir for x86_64-unknown-linux-gnu (on Ubuntu 18.04).
| File Type | Raw size | Compressed size |
|---|---|---|
symtab.json | 950M | 26M |
symtab.out | 84M | 24M |
*.rmeta | 92M | 25M |
These results were obtained by looking at the artifacts generated during the same experiment.
+kani setup?std library.workspace?cargo rustc per package.cargo kani --tests?cargo rustc --profile test -- --reachability=harnessesC to rust.function-stubbing)Allow users to specify that certain functions and methods should be replaced with mock functions (stubs) during verification.
+In scope:
+Out of scope:
+We anticipate that function/method stubbing will have a substantial positive impact on the usability of Kani:
+f, and then in other proofs---that call f indirectly---use a stub of f that mocks that behavior but is less complex.In all cases, stubbing would enable users to verify code that cannot currently be verified by Kani (or at least not within a reasonable resource bound).
+Even without stubbing types, the ability to stub functions/methods can help provide verification-friendly abstractions for standard data structures.
+For example, Issue 1673 suggests that some Kani proofs run more quickly if Vec::new is replaced with Vec::with_capacity; function stubbing would allow us to make this substitution everywhere in a codebase (and not just in the proof harness).
In what follows, we give an example of stubbing external code, using the annotations we propose in this RFC. +We are able to run this example on a modified version of Kani using a proof-of-concept MIR-to-MIR transformation implementing stubbing (the prototype does not support stub-related annotations; instead, it reads the stub mapping from a file). +This example stubs out a function that returns a random number. +This is the type of function that is commonly stubbed in other verification and program analysis projects, along with system calls, timer functions, logging calls, and deserialization methods---all of which we should be able to handle. +See the appendix at the end of this RFC for an extended example involving stubbing out a deserialization method.
+The crate rand is widely used (150M downloads).
+However, Kani cannot currently handle code that uses it (Kani users have run into this; see Issue 1727.
+Consider this example:
#[cfg(kani)]
+#[kani::proof]
+fn random_cannot_be_zero() {
+ assert_ne!(rand::random::<u32>(), 0);
+}
+For unwind values less than 2, Kani encounters an unwinding assertion error (there is a loop used to seed the random number generator); if we set an unwind value of 2, Kani fails to terminate within 5 minutes.
+Using stubbing, we can specify that the function rand::random should be replaced with a mocked version:
#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(rand::random, mock_random)]
+fn random_cannot_be_zero() {
+ assert_ne!(rand::random::<u32>(), 0);
+}
+Under this substitution, Kani has a single check, which proves that the assertion can fail. Verification time is 0.02 seconds.
+This feature is currently limited to stubbing functions and methods. +We anticipate that the annotations we propose here could also be used for stubbing types, although the underlying technical approach might have to change.
+Stubs will be specified per harness; that is, different harnesses can use different stubs. +This is one of the main design points. +Users might want to mock the behavior of a function within one proof harness, and then mock it a different way for another harness, or even use the original function definition. +It would be overly restrictive to impose the same stub definitions across all proof harnesses. +A good example of this is compositional reasoning: in some harnesses, we want to prove properties of a particular function (and so want to use its actual implementation), and in other harnesses we want to assume that that function has those properties.
+Users will specify stubs by attaching the #[kani::stub(<original>, <replacement>)] attribute to each harness function.
+The arguments original and replacement give the names of functions/methods.
+They will be resolved using Rust's standard name resolution rules; this includes supporting imports like use foo::bar as baz, as well as imports of multiple versions of the same crate (in which case a name would resolve to a function/method in a particular version).
+The attribute may be specified multiple times per harness, so that multiple (non-conflicting) stub pairings are supported.
For example, this code specifies that the function mock_random should be used in place of the function rand::random and the function my_mod::bar should be used in place of the function my_mod::foo for the harness my_mod::my_harness:
#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+mod my_mod {
+
+ fn foo(x: u32) -> u32 { ... }
+
+ fn bar(x: u32) -> u32 { ... }
+
+ #[cfg(kani)]
+ #[kani::proof]
+ #[kani::stub(rand::random, super::mock_random)]
+ #[kani::stub(foo, bar)]
+ fn my_harness() { ... }
+
+}
+We will support the stubbing of private functions and methods. +While this provides flexibility that we believe will be necessary in practice, it can also lead to brittle proofs: private functions/methods can change or disappear in even minor version upgrades (thanks to refactoring), and so proofs that depend on them might have a high maintenance burden. +In the documentation, we will discourage stubbing private functions/methods except if absolutely necessary.
+As a convenience, we will provide a macro kani::stub_set that allows users to specify sets of stubs that can be applied to multiple harnesses:
kani::stub_set!(my_io_stubs(
+ stub(std::fs::read, my_read),
+ stub(std::fs::write, my_write),
+));
+When declaring a harness, users can use the #[kani::use_stub_set(<stub_set_name>)] attribute to apply the stub set:
#[cfg(kani)]
+#[kani::proof]
+#[kani::use_stub_set(my_io_stubs)]
+fn my_harness() { ... }
+The name of the stub set will be resolved through the module path (i.e., they are not global symbols), using Rust's standard name resolution rules.
+A similar mechanism can be used to aggregate stub sets:
+kani::stub_set!(all_my_stubs(
+ use_stub_set(my_io_stubs),
+ use_stub_set(my_other_stubs),
+));
+Given a set of original-replacement pairs, Kani will exit with an error if
original function/method does not exist;replacement stub does not exist;original function is mapped to multiple replacement functions); orreplacement stub is not compatible with the signature of the original function/method (see next section).When considering whether a function/method can be replaced with some given stub, we want to allow some measure of flexibility, while also ensuring that we can provide the user with useful feedback if stubbing results in misformed code. +We consider a stub and a function/method to be compatible if all the following conditions are met:
+bar<A, B>(x: A, y: B) -> B is considered to have a type compatible with the function foo<S, T>(x: S, y: T) -> T.The final point is the most subtle. +We do not require that a type parameter in the signature of the stub implements the same traits as the corresponding type parameter in the signature of the original function/method. +However, Kani will reject a stub if a trait mismatch leads to a situation where a statically dispatched call to a trait method cannot be resolved during monomorphization. +For example, this restriction rules out the following harness:
+fn foo<T>(_x: T) -> bool {
+ false
+}
+
+trait DoIt {
+ fn do_it(&self) -> bool;
+}
+
+fn bar<T: DoIt>(x: T) -> bool {
+ x.do_it()
+}
+
+#[kani::proof]
+#[kani::stub(foo, bar)]
+fn harness() {
+ assert!(foo("hello"));
+}
+The call to the trait method DoIt::do_it is unresolvable in the stub bar when the type parameter T is instantiated with the type &str.
+On the other hand, our approach provides some flexibility, such as allowing our earlier example of mocking randomization: both rand::random and my_random have the type () -> T, but in the first case T is restricted such that the type Standard implements Distribution<T>, whereas in the latter case T has to implement kani::Arbitrary.
+This trait mismatch is allowed because at this call site T is instantiated with u32, which implements kani::Arbitrary.
To teach this feature, we will update the documentation with a section on function and method stubbing, including simple examples showing how stubbing can help Kani handle code that currently cannot be verified, as well as a guide to best practices for stubbing.
+We expect that this feature will require changes primarily to kani-compiler, with some less invasive changes to kani-driver.
+We will modify kani-compiler to collects stub mapping information (from the harness attributes) before code generation.
+Since stubs are specified on a per-harness basis, we need to generate multiple versions of code if all harnesses do not agree on their stub mappings; accordingly, we will update kani-compiler to generate multiple versions of code as appropriate.
+To do the stubbing, we will plug in a new MIR-to-MIR transformation that replaces the bodies of specified functions with their replacements.
+This can be achieved via rustc's query mechanism: if the user wants to replace foo with bar, then when the compiler requests the MIR for foo, we instead return the MIR for bar.
+kani-compiler will also be responsible for checking for the error conditions previously enumerated.
We will also need to update the metadata that kani-compiler generates, so that it maps each harness to the generated code that has the right stub mapping for that harness (since there will be multiple versions of generated code).
+The metadata will also list the stubs applied in each harness.
+kani-driver will need to be updated to process this new type of metadata and invoke the correct generated code for each harness.
+We can also update the results report to include the stubs that were used.
We anticipate that this design will evolve and be iterated upon.
+Stubbing is a de facto necessity for verification tools, and the lack of stubbing has a negative impact on the usability of Kani.
+In this alternative, users add an attribute #[kani::stub_by(<replacement>)] to the function that should be replaced.
+This approach is similar to annotating a function with a contract specifying its behavior (the stub acts like a programmatic contract).
+The major downside with this approach is that it would not be possible to stub external code. We see this as a likely use case that needs to be supported: users will want to replace std library functions or functions from arbitrary external crates.
In this alternative, users add an attribute #[kani::stub_of(<original>)] to the stub function itself, saying which function it replaces:
#[cfg(kani)]
+#[kani::stub_of(rand::random)]
+fn mock_random<T: kani::Arbitrary>() -> T { ... }
+The downside is that this stub must be uniformly applied across all harnesses and the stub specifications might be spread out across multiple files. +It would also require an extra layer of indirection to use a function as a stub if the user does not have source code access to it.
+This alternative combines the proposed solution and Alternative #2.
+Users annotate the stub (as in Alternative #2) and specify for each harness which stubs to use using an annotation #[kani::use_stubs(<stub>+)] placed above the harness.
This could be combined with modules, so that a module can be used to group stubs together, and then harnesses could pull in all the stubs in the module:
+#[cfg(kani)]
+mod my_stubs {
+
+ #[kani::stub_of(foo)]
+ fn stub1() { ... }
+
+ #[kani::stub_of(bar)]
+ fn stub2() { ... }
+
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::use_stubs(my_stubs)]
+fn my_harness() { ... }
+The benefit is that stubs are specified per harness, and (using modules) it might be possible to group stubs together. +The downside is that multiple annotations are required and the stub mappings themselves are remote from the harness (at the harness you would know what stub is being used, but not what it is replacing). +There are also several issues that would need to be resolved:
+stub1 to mock foo, and harness B wants to use stub1 to mock bar.)One alternative would be to specify stubs in a file that is passed to kani-driver via a command line option.
+Users would specify per-harness stub pairings in the file; JSON would be a possible format.
+Using a file would eliminate the need for kani-compiler to do an extra pass to extract harness information from the Rust source code before doing code generation; the rest of the implementation would stay the same.
+It would also allow the same harness to be run with different stub selections (by supplying a different file).
+The disadvantage is that the stub selection is remote from the harness itself.
Our approach is based on a MIR-to-MIR transformation.
+Some advantages are that it operates over a relatively simple intermediate representation and rustc has good support for plugging in MIR-to-MIR transformations, so it would not require any changes to rustc itself.
+At this stage of the compiler, names have been fully resolved, and there is no problem with swapping in the body of a function defined in one crate for a function defined in another.
+Another benefit is that it should be possible to extend the compiler to integrate --concrete-playback with the abstractions (although doing so is out of scope for the current proposal).
The major downside with the MIR-to-MIR transformation is that it does not appear to be possible to stub types at that stage (there is no way to change the definition of a type through the MIR). +Thus, our proposed approach will not be a fully general stubbing solution. +However, it is technically feasible and relatively clean, and provides benefits over having no stubbing at all (as can be seen in the examples in the first part of this document).
+Furthermore, it could be used as part of a portfolio of stubbing approaches, where users stub local types using conditional compilation (see Alternative #1), and Kani provides a modified version of the standard library with verification-friendly versions of types like std::vec::Vec.
In this baseline alternative, we do not provide any stubbing mechanism at all.
+Instead, users can effectively stub local code (functions, methods, and types) using conditional compilation.
+For example, they could specify using #[cfg(kani)] to turn off the original definition and turn on the replacement definition when Kani is running, similarly to the ghost state approach taken in the Tokio Bytes proof.
The disadvantage with this approach is that it does not provide any way to stub external code, which is one of the main motivations of our proposed approach.
+In this alternative, we rewrite the source code before it even gets to the compiler. +The advantage with this approach is that it is very flexible, allowing us to stub functions, methods, and types, either by directly replacing them, or appending their replacements and injecting appropriate conditional compilation guards.
+This approach entails less user effort than Alternative #1, but it has the same downside that it requires all source code to be available. +It also might be difficult to inject code in a way that names are correctly resolved (e.g., if the replacement code comes from a different crate). +Also, source code is difficult to work with (e.g., unexpanded macros).
+On the last two points, we might be able to take advantage of an existing source analysis platform like rust-analyzer (which has facilities like structural search replace), but this would add more (potentially fragile) dependencies to Kani.
In this alternative, we implement stubbing by rewriting the AST or High-Level IR (HIR) of the program.
+The HIR is a more compiler-friendly version of the AST; it is what is used for type checking.
+To swap out a function, method, or type at this level, it looks like it would be necessary to add another pass to rustc that takes the initial AST/HIR and produces a new AST/HIR with the appropriate replacements.
The advantage with this approach is, like source transformations, it would be very flexible.
+The downside is that it would require modifying rustc (as far as we know, there is not an API for plugging in a new AST/HIR pass), and would also require performing the transformations at a very syntactic level: although the AST/HIR would likely be easier to work with than source code directly, it is still very close to the source code and not very abstract.
+Furthermore, provided we supported stubbing across crate boundaries, it seems like we would run into a sequencing issue: if we were trying to stub a function in a dependency, we might not know until after we have compiled that dependency that we need to modify its AST/HIR; furthermore, even if we were aware of this, the replacement AST/HIR code would not be available at that time (the AST/HIR is usually just constructed for the crate currently being compiled).
--concrete-playback (for now).It would increase the utility of stubbing if we supported stubs for types. +The source code annotations could likely stay the same, although the underlying technical approach performing these substitutions might be significantly more complex.
+It would probably make sense to provide a library of common stubs for users, since many applications might want to stub the same functions and mock the same behaviors (e.g., rand::random can be replaced with a function returning kani::any).
We could provide special classes of stubs that are likely to come up in practice:
+unreachable: assert the function is unreachable.havoc_locals: return nondeterministic values and assign nondeterministic values to all mutable arguments.havoc: similar to havoc_locals but also assign nondeterministic values to all mutable global variables.uninterpret: treat function as an uninterpreted function.How can we provide a good user experience for accessing private fields of self in methods?
+It is possible to do so using std::mem::transmute (see below); this is clunky and error-prone, and it would be good to provide better support for users.
struct Foo {
+ x: u32,
+}
+
+impl Foo {
+ pub fn m(&self) -> u32 {
+ 0
+ }
+}
+
+struct MockFoo {
+ pub x: u32,
+}
+
+fn mock_m(foo: &Foo) {
+ let mock: &MockFoo = unsafe { std::mem::transmute(foo) };
+ return mock.x;
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(Foo::m, mock_m)]
+fn my_harness() { ... }
+In this example, we mock a serde_json (96M downloads) deserialization method so that we can prove a property about the following Firecracker function that parses a configuration from some raw data:
+fn parse_put_vsock(body: &Body) -> Result<ParsedRequest, Error> {
+ METRICS.put_api_requests.vsock_count.inc();
+ let vsock_cfg = serde_json::from_slice::<VsockDeviceConfig>(body.raw()).map_err(|err| {
+ METRICS.put_api_requests.vsock_fails.inc();
+ err
+ })?;
+
+ // Check for the presence of deprecated `vsock_id` field.
+ let mut deprecation_message = None;
+ if vsock_cfg.vsock_id.is_some() {
+ // vsock_id field in request is deprecated.
+ METRICS.deprecated_api.deprecated_http_api_calls.inc();
+ deprecation_message = Some("PUT /vsock: vsock_id field is deprecated.");
+ }
+
+ // Construct the `ParsedRequest` object.
+ let mut parsed_req = ParsedRequest::new_sync(VmmAction::SetVsockDevice(vsock_cfg));
+ // If `vsock_id` was present, set the deprecation message in `parsing_info`.
+ if let Some(msg) = deprecation_message {
+ parsed_req.parsing_info().append_deprecation_message(msg);
+ }
+
+ Ok(parsed_req)
+}
+We manually mocked some of the Firecracker types with simpler versions to reduce the number of dependencies we had to pull in (e.g., we removed some enum variants, unused struct fields). +With these changes, we were able to prove that the configuration data has a vsock ID if and only if the parsing metadata includes a deprecation message:
+#[cfg(kani)]
+fn get_vsock_device_config(action: RequestAction) -> Option<VsockDeviceConfig> {
+ match action {
+ RequestAction::Sync(vmm_action) => match *vmm_action {
+ VmmAction::SetVsockDevice(dev) => Some(dev),
+ _ => None,
+ },
+ _ => None,
+ }
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::unwind(2)]
+#[kani::stub(serde_json::deserialize_slice, mock_deserialize)]
+fn test_deprecation_vsock_id_consistent() {
+ // We are going to mock the parsing of this body, so might as well use an empty one.
+ let body: Vec<u8> = Vec::new();
+ if let Ok(res) = parse_put_vsock(&Body::new(body)) {
+ let (action, mut parsing_info) = res.into_parts();
+ let config = get_vsock_device_config(action).unwrap();
+ assert_eq!(
+ config.vsock_id.is_some(),
+ parsing_info.take_deprecation_message().is_some()
+ );
+ }
+}
+Crucially, we did this by stubbing out serde_json::from_slice and replacing it with our mock version below, which ignores its input and creates a "symbolic" configuration struct:
#[cfg(kani)]
+fn symbolic_string(len: usize) -> String {
+ let mut v: Vec<u8> = Vec::with_capacity(len);
+ for _ in 0..len {
+ v.push(kani::any());
+ }
+ unsafe { String::from_utf8_unchecked(v) }
+}
+
+#[cfg(kani)]
+fn mock_deserialize(_data: &[u8]) -> serde_json::Result<VsockDeviceConfig> {
+ const STR_LEN: usize = 1;
+ let vsock_id = if kani::any() {
+ None
+ } else {
+ Some(symbolic_string(STR_LEN))
+ };
+ let guest_cid = kani::any();
+ let uds_path = symbolic_string(STR_LEN);
+ let config = VsockDeviceConfig {
+ vsock_id,
+ guest_cid,
+ uds_path,
+ };
+ Ok(config)
+}
+The proof takes 170 seconds to complete (using Kissat as the backend SAT solver for CBMC).
+cover-statement)A new Kani API that allows users to check that a certain condition can occur at a specific location in the code.
+Users typically want to gain confidence that a proof checks what it is supposed to check, i.e. that properties are not passing vacuously due to an over-constrained environment.
+A new Kani macro, cover will be created that can be used for checking that a certain condition can occur at a specific location in the code.
+The purpose of the macro is to verify, for example, that assumptions are not ruling out those conditions, e.g.:
let mut v: Vec<i32> = Vec::new();
+let len: usize = kani::any();
+kani::assume(len < 5);
+for _i in 0..len {
+ v.push(kani::any());
+}
+// make sure we can get a vector of length 5
+kani::cover!(v.len() == 5);
+This is typically used to ensure that verified checks are not passing vacuously, e.g. due to overconstrained pre-conditions.
+The special case of verifying that a certain line of code is reachable can be achieved using kani::cover!() (which is equivalent to cover!(true)), e.g.
match x {
+ val_1 => ...,
+ val_2 => ...,
+ ...
+ val_i => kani::cover!(), // verify that `x` can take the value `val_i`
+}
+Similar to Rust's assert macro, a custom message can be specified, e.g.
kani::cover!(x > y, "x can be greater than y");
+The cover macro instructs Kani to find at least one possible execution that satisfies the specified condition at that line of code. If no such execution is possible, the check is reported as unsatisfiable.
Each cover statement will be reported as a check whose description is cover condition: cond and whose status is:
SATISFIED (green): if Kani found an execution that satisfies the condition.UNSATISFIABLE (yellow): if Kani proved that the condition cannot be satisfied.UNREACHABLE (yellow): if Kani proved that the cover statement itself cannot be reached.For example, for the following cover statement:
kani::cover!(a == 0);
+An example result is:
+Check 2: main.cover.2
+ - Status: SATISFIED
+ - Description: "cover condition: a == 0"
+ - Location: foo.rs:9:5 in function main
+By default, unsatisfiable and unreachable cover checks will not impact verification success or failure.
+This is to avoid getting verification failure for harnesses for which a cover check is not relevant.
+For example, on the following program, verification should not fail for another_harness_that_doesnt_call_foo because the cover statement in foo is unreachable from it.
[kani::proof]
+fn a_harness_that_calls_foo() {
+ foo();
+}
+
+#[kani::proof]
+fn another_harness_that_doesnt_call_foo() {
+ // ...
+}
+
+fn foo() {
+ kani::cover!( /* some condition */);
+}
+The --fail-uncoverable option will allow users to fail the verification if a cover property is unsatisfiable or unreachable.
+This option will be integrated within the framework of Global Conditions, which is used to define properties that depend on other properties.
Using the --fail-uncoverable option will enable the global condition with name fail_uncoverable.
+Following the format for global conditions, the outcome will be one of the following:
- fail_uncoverable: FAILURE (expected all cover statements to be satisfied, but at least one was not) - fail_uncoverable: SUCCESS (all cover statements were satisfied as expected)Note that the criteria to achieve a SUCCESS status depends on all properties of the "cover" class having a SATISFIED status.
+Otherwise, we return a FAILURE status.
Cover checks will be reported separately in the verification summary, e.g.
+SUMMARY:
+ ** 1 of 206 failed (2 unreachable)
+ Failed Checks: assertion failed: x[0] == x[1]
+
+ ** 30 of 35 cover statements satisfied (1 unreachable) <--- NEW
+In this example, 5 of the 35 cover statements were found to be unsatisfiable, and one of those 5 is additionally unreachable.
+If one or more unwinding assertions fail or an unsupported construct is found to be reachable (which indicate an incomplete path exploration), and Kani found the condition to be unsatisfiable or unreachable, the result will be reported as UNDETERMINED.
The implementation will touch the following components:
+cover macro will be added there along with a cover function with a rustc_diagnostic_itemkani-compiler: The cover function will be handled via a hook and codegen as two assertions (cover(cond) will be codegen as __CPROVER_assert(false); __CPROVER_assert(!cond)).
+The purpose of the __CPROVER_assert(false) is to determine whether the cover statement is reachable.
+If it is, the second __CPROVER_assert(!cond) indicates whether the condition is satisfiable or not.kani-driver: The CBMC output parser will extract cover properties through their property class, and their result will be set based on the result of the two assertions:
+FAILURE (UNREACHABLE)FAILURE to indicate that the condition is unsatisfiableSUCCESS to indicate that the condition is satisfiableWhat are the pros and cons of this design?
+CBMC has its own cover API (__CPROVER_cover), for which SUCCESS is reported if an execution is found, and FAILURE is reported otherwise.
+However, using this API currently requires running CBMC in a separate "cover" mode.
+Having to run CBMC in that mode would complicate the Kani driver as it will have to perform two CBMC runs, and then combine their results into a single report.
+Thus, the advantage of the proposed design is that it keeps the Kani driver simple.
+In addition, the proposed solution does not depend on a feature in the backend, and thus will continue to work if we were to integrate a different backend.
What is the impact of not doing this?
+The current workaround to accomplish the same effect of verifying that a condition can be covered is to use assert!(!cond).
+However, if the condition can indeed be covered, verification would fail due to the failure of the assertion.
kani::cover!(x > y, "{} can be greater than {}", x, y)?
+Users may expect this to be supported since the macro looks similar to the assert macro, but Kani doesn't include the formatted string in the message description, since it's not available at compile time.~
+We need to make sure the concrete playback feature can be used with cover statements that were found to be coverable.
The new cover API subsumes the current kani::expect_fail function.
+Once it's implemented, we should be able to get rid of expect_fail, and all the related code in compiletest that handles the EXPECTED FAILURE message in a special manner.
loop-contract-synthesis)A new option that allows users to verify programs without unwinding loops by synthesizing loop contracts for those loops.
+Currently Kani does not support verification on programs with unbounded control flow (e.g. loops with dynamic bounds). +Kani unrolls all unbounded loops until a global threshold (unwinding number) specified by the user and then verifies this unrolled program, which limits the set of programs it can verify.
+A new Kani flag --synthesize-loop-contracts will be created that can be used to enable the goto-level loop-contract synthesizer goto-synthesizer.
+The idea of loop contracts is, instead of unwinding loops, we abstract those loops as non-loop structures that can cover arbitrary iterations of the loops.
+The loop contract synthesizer, when enabled, will attempt to synthesize loop contracts for all loops.
+CBMC can then apply the synthesized loop contracts and verify the program without unwinding any loop.
+So, the synthesizer will help to verify the programs that require Kani to unwind loops for a very large number of times to cover all iterations.
For example, the number of executed iterations of the loop in the following harness is dynamically bounded by an unbounded variable y 1.
+Only an unwinding value of i32::MAX can guarantee to cover all iterations of the loop, and hence satisfy the unwinding assertions.
+Unwinding the loop an i32::MAX number of times will result in a too large goto program to be verified by CBMC.
#[kani::proof]
+fn main() {
+ let mut y: i32 = kani::any_where(|i| *i > 0);
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+With the loop-contract synthesizer, Kani can synthesize the loop invariant y >= 0, with which it can prove the post-condition y == 0 without unwinding the loop.
Also, loop contracts could improve Kani’s verification time since all loops will be abstracted to a single iteration, as opposed to being unwound a large number of iterations.
+For example, we can easily find out that the following loop is bounded by an unwinding value of 5000.
+Kani can verify the program in a few minutes by unwinding the loop 5000 times.
+With loop contracts, we only need to verify the single abstract iteration of the loop, which leads to a smaller query.
+As a result, Kani with the synthesizer can verify the program in a few seconds.
#[kani::proof]
+#[kani::unwind(5000)]
+fn main() {
+ let mut y: i32 = 5000;
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+The goto-synthesizer is an enumeration-based synthesizer.
+It enumerates candidate invariants from a pre-designed search space described by a given regular tree grammar and verifies if the candidate is an inductive invariant.
+Therefore it has the following limitations:
a[i] == 0 contains an array access and cannot be captured by the current search space.
+However, we can easily extend the search space to include more complex expressions with the cost of an exponential increase of the running time of the synthesizer.Users will be able to use the new command-line flag --synthesize-loop-contracts to run the synthesizer, which will attempt to synthesize loop contracts, and verify programs with the synthesized loop contracts.
Without a resource limit, an enumerative synthesizer may run forever to exhaust a search space consisting of an infinite number of candidates, especially when there is no solution in the search space.
+So, for the guarantee of termination, we provide users options: --limit-synthesis-time T to limit the running time of the synthesizer to be less than T seconds.
When the flag --synthesize-loop-contracts is provided, Kani will report different result for different cases
UNDETERMINED instead of FAILED.A question about how do we print the synthesized loop contracts when users request is discussed in Open question.
+The synthesizer goto-synthesizer is implemented in the repository of CBMC, takes as input a goto binary, and outputs a new goto binary with the synthesized loop contracts applied.
+Currently, Kani invokes goto-instrument to instrument the goto binary main.goto into a new goto binary main_instrumented.goto, and then invokes cbmc on main_instrumented.goto to get the verification result.
+The synthesis will happen between calling goto-instrument and calling cbmc.
+That is, we invoke goto-synthesizer on main_instrumented.goto to produce a new goto binary main_synthesized.goto, and then call cbmc on main_synthesized.goto instead.
When invoking goto-synthesizer, we pass the following parameters to it with the flags built in goto-synthesizer:
The enumerator used in the synthesizer enumerates candidates from the language of the following grammar template.
+NT_Bool -> NT_Bool && NT_Bool | NT_int == NT_int
+ | NT_int <= NT_int | NT_int < NT_int
+ | SAME_OBJECT(terminals_ptr, terminals_ptr)
+
+NT_int -> NT_int + NT_int | terminals_int | LOOP_ENTRY(terminals_int)
+ | POINTER_OFFSET(terminals_ptr) | OBJECT_SIZE(terminals_ptr)
+ | POINTER_OFFSET(LOOP_ENTRY(terminals_ptr)) | 1
+where terminals_ptr are all pointer variables in the scope, and terminal_int are all integer variables in the scope.
+For every candidate invariant, goto-synthesizer applies it to the GOTO program and runs CBMC to verify the program.
goto-synthesizer returns it as a solution.goto-synthesizer returns the conjunction of all inductive clauses as the best-effort-synthesized loop contracts.We use the following example to illustrate how the synthesizer works.
+#[kani::proof]
+fn main() {
+ let mut y: i32 = kani::any_where(|i| *i > 0);
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+As there is only one variable y in the scope, the grammar template above will be instantiated to the following grammar
NT_Bool -> NT_Bool && NT_Bool | NT_int == NT_int
+ | NT_int <= NT_int | NT_int < NT_int
+NT_int -> NT_int + NT_int | y | LOOP_ENTRY(y) | 1
+The synthesizer will enumerate candidates derived from NT_Bool in the following order.
y == y
+y == LOOP_ENTRY(y)
+y == 1
+...
+1 <= y + 1
+...
+The synthesizer then verifies with CBMC if the candidate is an inductive invariant that can be used to prove the post-condition y == 0.
+For example, the candidate y == y is verified to be an inductive invariant, but cannot be used to prove the post-condition y == 0.
+The candidate y == 1 is not inductive.
+The synthesizer rejects all candidates until it finds the candidate 1 <= y + 1, which can be simplified to y >= 0.
+y >= 0 is an inductive invariant that can be used to prove the post-condition.
+So the synthesizer will return y >= 0 and apply it to the goto model to get main_synthesized.goto.
For assign clauses, the synthesizer will first use alias analysis to determine an initial set of assign targets. +During the following iteration, if any assignable-check is violated, the synthesizer will extract the assign target from the violated check.
+Then Kani will call cbmc on main_synthesized.goto to verify the program with the synthesized loop contracts.
goto-instrument, but probably not enough for other user-written checks.
+We may want to include array-indexing, pointer-dereference, or other arithmetic operators in the candidate grammar for synthesizing a larger set of loop invariants.
+However, there is a trade-off between the size of candidate we enumerate and the running time of the enumeration.
+We will collect more data to decide what operators we should include in the candidate grammar.
+Once we decide more kinds of candidate grammars, we will provide users options to choose which candidate grammar they want to use.How does the synthesizer work with unwinding numbers? +There may exist some loops for which the synthesizer cannot find loop contracts, but some small unwinding numbers are enough to cover all executions of the loops. +In this case, we may want to unwind some loops in the program while synthesizing loop contracts for other loops. +It requires us to have a way to identify and specify which loops we want to unwind.
+In C programs, we identify loops by the loop ID, which is a pair (function name, loop number).
+However, in Rust programs, loops are usually in library functions such as Iterator::for_each.
+And a library function may be called from different places in the program.
+We may want to unwind the loop in some calls but not in other calls.
How do we output the synthesized loop contracts?
+To better earn users' trust, we want to be able to report what loop contracts we synthesized and used to verify the given programs.
+Now goto-synthesizer can dump the synthesized loop contracts into a JSON file.
+Here is an example of the dumped loop contracts.
+It contains the location of source files of the loops, the synthesized invariant clauses and assign clauses for loops identified by loop numbers.
{
+ "sources": [ "/Users/qinhh/Repos/playground/kani/synthesis/base_2/test.rs" ],
+ "functions": [
+ {
+ "main": [ "loop 1 invariant y >= 0",
+ "loop 1 assigns var_9,var_10,var_11,x,y,var_12" ]
+ }
+ ],
+ "output": "stdout"
+}
+There are two challenges here if we want to also dump synthesized loop contracts in Kani.
+rust instead of c.var_9, var_10, var_11, and var_12 in the above JSON file.
+We need to translate them back to the original variables they represent.User-provided loop contracts. +If we have a good answer for how to identify loops and dump synthesized loop contracts, we could probably also allow users to provide the loop contracts they wrote to Kani, and verify programs with user-provided loop contracts.
+When users want to unwind some loops, we can also introduce macros to enable/disable unwinding for certain block of code.
+#[kani::proof]
+#[kani::unwind(10)]
+fn check() {
+ // unwinding starts as enabled, so all loops in this code block will be unwound to 10
+ #[kani::disable_unwinding]
+ // unwinding is disabled for all loops in this block of code
+ #[kani::enable_unwinding]
+ // it is enabled in this block of code until the end of the program
+}
+Invariant caching. +The loop invariant could be broken when users modify their code. +However, we could probably cache previously working loop invariants and attempt to reuse them when users modify their code. +Even if the cached loop invariants are not enough to prove the post-condition, they could still be used as a starting point for the synthesizer to find new loop invariants.
+We say an integer variable is unbounded if there is no other bound on its value besides the width of its bit-vector representation.
+kani::should_panic attribute (should-panic-attr)Users may want to express that a verification harness should panic.
+This RFC proposes a new harness attribute #[kani::should_panic] that informs Kani about this expectation.
Users may want to express that a verification harness should panic. +In general, a user adding such a harness wants to demonstrate that the verification fails because a panic is reachable from the harness.
+Let's refer to this concept as negative verification,
+so the relation with negative testing becomes clearer.
+Negative testing can be exercised in Rust unit tests using the #[should_panic] attribute.
+If the #[should_panic] attribute is added to a test, cargo test will check that the execution of the test results in a panic.
+This capability doesn't exist in Kani at the moment, but it would be useful for the same reasons
+(e.g., to show that invalid inputs result in verification failures, or increase the overall verification coverage).
We propose an attribute that allows users to exercise negative verification in Kani.
+We also acknowledge that, in other cases, users may want to express more granular expectations for their harnesses. +For example, a user may want to specify that a given check is unreachable from the harness. +An ergonomic mechanism for informing Kani about such expectations is likely to require other improvements in Kani (a comprehensive classification for checks reported by Kani, a language to describe expectations for checks and cover statements, and general output improvements). +Moving forward, we consider that such a mechanism and this proposal solve different problems, so they don't need to be discussed together. +This is further discussed in the rationale and alternatives and future possibilities sections.
+The scope of this functionality is limited to the overall verification result. +The rationale section discusses the granularity of failures, and how this attribute could be extended.
+Let's look at this code:
+struct Device {
+ is_init: bool,
+}
+
+impl Device {
+ fn new() -> Self {
+ Device { is_init: false }
+ }
+
+ fn init(&mut self) {
+ assert!(!self.is_init);
+ self.is_init = true;
+ }
+}
+
+#[kani::proof]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+This is what a negative harness may look like.
+The user wants to verify that calling device.init() more than once should result in a panic.
++NOTE: We could convert this into a Rust unit test and add the
+#[should_panic]attribute to it. +However, there are a few good reasons to have a verification-specific attribute that does the same:+
+- To ensure that other unexpected behaviors don't occur (e.g., overflows).
+- Because
+#[should_panic]cannot be used if the test harness contains calls to Kani's API.- To ensure that a panic still occurs after stubbing out code which is expected to panic.
+
Currently, this example produces a VERIFICATION:- FAILED result.
+In addition, it will return a non-successful code.
#[kani::proof]
+#[kani::should_panic]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+Since we added #[kani::should_panic], running this example would produce a successful code.
Now, we've considered two ways to represent this result in the verification output. +Note that it's important that we provide the user with this feedback:
+Therefore, the representation must make clear both the expectation and the outcome. +Below, we show how we'll represent this result.
+The #[kani::should_panic] attribute essentially behaves as a property that depends on other properties.
+This makes it well-suited for integration within the framework of Global Conditions.
Using the #[kani::should_panic] attribute will enable the global condition with name should_panic.
+Following the format for global conditions, the outcome will be one of the following:
- `should_panic`: FAILURE (encountered no panics, but at least one was expected) if there were no failures. - `should_panic`: FAILURE (encountered failures other than panics, which were unexpected) if there were failures but not all them had prop.property_class() == "assertion". - `should_panic`: SUCCESS (encountered one or more panics as expected) otherwise.Note that the criteria to achieve a SUCCESS status depends on all failed properties having the property class "assertion".
+If they don't, then the failed properties may contain UB, so we return a FAILURE status instead.
When there are multiple harnesses, we'll implement the single-harness changes in addition to the following ones. +Currently, a "Summary" section appears1 after reporting the results for each harness:
+Verification failed for - harness3
+Verification failed for - harness2
+Verification failed for - harness1
+Complete - 0 successfully verified harnesses, 3 failures, 3 total.
+Harnesses marked with #[kani::should_panic] won't show unless the expected result was different from the actual result.
+The summary will consider harnesses that match their expectation as "successfully verified harnesses".
Therefore, if we added #[kani::should_panic] to all harnesses in the previous example, we'd see this output:
Complete - 3 successfully verified harnesses, 0 failures, 3 total.
+In a verification context, an execution can branch into multiple executions that depend on a condition. +This may result in a situation where different panics are reachable, as in this example:
+#[kani::proof]
+#[kani::should_panic]
+fn branch_panics() {
+ let b: bool = kani::any();
+
+ do_something();
+
+ if b {
+ call_panic_1(); // leads to a panic-related failure
+ } else {
+ call_panic_2(); // leads to a different panic-related failure
+ }
+}
+Note that we could safeguard against these situations by checking that only one panic-related failure is reachable.
+However, users have expressed that a coarse version (i.e., checking that at least one panic can be reached) is preferred.
+Users also anticipate that #[kani::should_panic] will be used to exercise smoke testing in many cases.
+Additionally, restricting #[kani::should_panic] to the verification of single panic-related failures could be confusing for users and reduce its overall usefulness.
This feature will only be available as an attribute.
+That means this feature won't be available as a CLI option (i.e., --should-panic).
+There are good reasons to avoid the CLI option:
--harness to filter negative harnesses.The #[kani::should_panic] attribute will become one of the most basic attributes in Kani.
+As such, it'll be mentioned in the tutorial and added to the dedicated section planned in #2208.
In general, we'll also advise against negative verification when a harness can be written both as a regular (positive) harness and a negative one. +The feature, as it's presented in this proposal, won't allow checking that the panic failure is due to the panic we expected. +So there could be cases where the panic changes, but it goes unnoticed while running Kani. +Because of that, it'll preferred that users write positive harnesses instead.
+At a high level, we expect modifications in the following components:
+kani-compiler: Changes required to (1) process the new attribute, and (2) extend HarnessMetadata with a should_panic: bool field.kani-driver: Changes required to (1) edit information about harnesses printed by kani-driver, (2) edit verification output when post-processing CBMC verification results, and (3) return the appropriate exit status after post-processing CBMC verification results.We don't expect these changes to require new dependencies. +Besides, we don't expect these changes to be updated unless we decide to extend the attribute with further fields (see Future possibilities for more details).
+This proposal would enable users to exercise negative verification with a relatively simple mechanism. +Not adding such a mechanism could impact Kani's usability by limiting the harnesses that users can write.
+This proposal doesn't consider generic failures but only panics. +In principle, it's not clear that a mechanism for generic failures would be useful. +Such a mechanism would allow users to expect UB in their harness, but there isn't a clear motivation for doing that.
+We have considered two alternatives for the "expectation" part of the attribute's name: should and expect.
+We avoid expect altogether for two reasons:
expected argument to #[kani::should_panic].#[kani::expect].expected mode, which works with *.expected files. Other modes also use such files.expected argumentWe could consider an expected argument, similar to the #[should_panic] attribute.
+To be clear, the #[should_panic] attribute may receive an argument expected which allows users to specify the expected panic string:
#[test]
+ #[should_panic(expected = "Divide result is zero")]
+ fn test_specific_panic() {
+ divide_non_zero_result(1, 10);
+ }
+In principle, we anticipate that we'll extend this proposal to include the expected argument at some point.
+The implementation could compare the expected string against the panic string.
At present, the only technical limitation is that panic strings printed in Kani aren't formatted.
+One option is to use substrings to compare.
+However, the long-term solution is to use concrete playback to replay the panic and match against the expected panic string.
+By doing this, we would achieve feature parity with Rust's #[should_panic].
As mentioned earlier, users may want to express more granular expectations for their harnesses.
+There could be problems with this proposal if we attempt to do both:
+We don't have sufficient data about the use-case considered in this alternative. +This proposal can also contribute to collect this data: once users can expect panics, they may want to expect other things.
+This functionality could be part of the Kani API instead of being an attribute. +For example, some contributors proposed a function that takes a predicate closure to filter executions and check that they result in a panic.
+However, such a function couldn't be used in external code, limiting its usability to the user's code.
+Once the feature is available, it'd be good to gather user feedback to answer these questions:
+#[kani::should_panic] with an expected field? Yes, but not in this version.#[kani::should_panic]? Yes (this is now discussed in User Experience).kani::proof (#[kani::proof(should_panic)] reads very well).expected argument to #[kani::should_panic], and replay the harness with concrete playback to get the actual panic string.Double negation may not be the best representation, but it's at least accurate with respect to the original result.
+This summary is printed in both the default and terse outputs.
+unstable-api)Provide a standard option for users to enable experimental APIs and features in Kani, +and ensure that those APIs are off by default.
+Add an opt-in model for users to try experimental APIs. +The goal is to enable users to try features that aren't stable yet, +which allow us to get valuable feedback during the development of new features and APIs.
+The opt-in model empowers the users to control when some instability is acceptable, +which makes Kani UX more consistent and safe.
+Currently, each new unstable feature will introduce a new switch, some of them will look like --enable-<feature>,
+while others will be a plain switch which allows further feature configuration --<feature-config>=[value].
+For example, we today have the following unstable switches --enable-stubbing, --concrete-playback, --gen-c.
+In all cases, users are still required to provide the additional --enable-unstable option.
+Some unstable features are included in the --help section, and only a few mention the requirement
+to include --enable-unstable. There is no way to list all unstable features.
+The transition to stable switches is also ad-hoc.
In order to reduce friction, we will also standardize how users opt-in to any Kani unstable feature.
+We will use similar syntax to the one used by the Rust compiler and Cargo.
+As part of this work, we will also deprecate and remove --enable-unstable option.
Note that although Kani is still on v0, which means that everything is somewhat unstable, +this allow us to set different bars when it comes to what kind of changes is expected, +as well as what kind of support we will provide for a feature.
+Users will have to invoke Kani with:
+-Z <feature_identifier>
+in order to enable any unstable feature in Kani, including unstable APIs in the Kani library.
+For unstable command line options, we will add -Z unstable-options, similar to the Rust compiler.
+E.g.:
-Z unstable-options --concrete-playback=print
+Users will also be able to enable unstable features in their Cargo.toml in the unstable table
+under kani table. E.g:
[package.metadata.kani.unstable]
+unstable-options = true
+
+[workspace.metadata.kani]
+flags = { concrete-playback = true }
+unstable = { unstable-options = true }
+In order to mark an API as unstable, we will add the following attribute to the APIs marked as unstable:
+#[kani::unstable(feature="<IDENTIFIER>", issue="<TRACKING_ISSUE_NUMBER>", reason="<DESCRIPTION>")]
+pub fn unstable_api() {}
+This is similar to the interface used by the standard library.
+If the user tries to use an unstable feature in Kani without explicitly enabling it, +Kani will trigger an error. For unstable APIs, the error will be triggered during the crate +compilation.
+We will add the -Z option to both kani-driver and kani-compiler.
+Kani driver will pass the information to the compiler.
For unstable APIs, the compiler will check if any reachable function uses an unstable feature that was not enabled. +If that is the case, the compiler will trigger a compilation error.
+We will also change the compiler to only generate code for harnesses that match the harness filter. +The filter is already passed to the compiler, but it is currently only used for stubbing.
+Once an API has been stabilized, we will remove the unstable attributes from the given API.
+If the user tries to enable a feature that was already stabilized,
+Kani will print a warning stating that the feature has been stabilized.
If we decide to remove an API that is marked as unstable, we should follow a regular deprecation
+path (using #[deprecated] attribute), and keep the unstable flag + attributes, until we are
+ready to remove the feature completely.
For this RFC, the suggestion is to only enable experimental features globally for simplicity of use and implementation.
+For now, we will trigger a compilation error if an unstable API is reachable from a user crate +unless if the user opts in for the unstable feature.
+We could allow users to specify experimental features on a per-harness basis, +but it could be tricky to make it clear to the user which harness may be affected by which feature. +The extra granularity would also be painful when we decide a feature is no longer experimental, +whether it is stabilized or removed. +In those cases, users would have to edit each harness that enables the affected feature.
+stable attribute that documents when an API was stabilized?global-conditions)A new section in Kani's output to summarize the status of properties that depend on other properties. We use the term global conditions to refer to such properties.
+The addition of new options that affect the overall verification result depending on certain property attributes demands some consideration.
+In particular, the addition of a new option to fail verification if there are uncoverable (i.e., unsatisfiable or unreachable) cover properties (requested in #2299) is posing new challenges to our current architecture and UI.
This concept isn't made explicit in Kani, but exists in some ways.
+For example, the kani::should_panic attribute is a global condition because it can be described in terms of other properties (checks).
+The request in #2299 is essentially another global conditions, and we may expect more to be requested in the future.
In this RFC, we propose a new section in Kani's output focused on reporting global conditions. +The goal is for users to receive useful information about hyperproperties without it becoming overwhelming. +This will help users to understand better options that are enabled through global conditions and ease the addition of such options to Kani.
+The output will refer to properties that depend on other properties as "global conditions", which is a simpler term. +The options to enable different global conditions will depend on a case-by-case basis1.
+The main UI change in this proposal is a new GLOBAL CONDITIONS section that won't be printed if no global conditions have been enabled.
+This section will only appear in Kani's default output after the RESULTS section (used for individual checks) and have the format:
GLOBAL CONDITIONS:
+ - `<name>`: <status> (<reason>)
+ - `<name>`: <status> (<reason>)
+ [...]
+where:
+<name> is the name given to the global condition.<status> is the status determined for the global condition.<reason> is an explanation that depends on the status of the global condition.For example, let's assume we implement the option requested in #2299. +A concrete example of this output would be:
+GLOBAL CONDITIONS:
+ - `fail_uncoverable`: SUCCESS (all cover statements were satisfied as expected)
+A FAILED status in any enabled global condition will cause verification to fail.
+In that case, the overall verification result will point out that one or more global conditions failed, as in:
VERIFICATION:- FAILURE (one or more global conditions failed)
+This last UI change will also be implemented for the terse output. +Finally, checks that cause an enabled global condition to fail will be reported using the same interface we use for failed checks2.
+Global conditions which aren't enabled won't appear in the GLOBAL CONDITIONS section.
+Their status will be computed regardless3, and we may consider showing this status when the --verbose option is passed.
The documentation of global conditions will depend on how they're enabled, which depends on a case-by-case basis.
+However, we may consider adding a new subsection Global conditions to the Reference section that collects all of them so it's easier for users to consult all of them in one place.
The only component to be modified is kani-driver since that's where verification results are built and determined.
+But we should consider moving this logic into another crate.
We don't need new dependencies. +The corner cases will depend on the specific global conditions to be implemented.
+As mentioned earlier, we're proposing this change to help users understand global conditions and how they're determined.
+In many cases, global conditions empower users to write harnesses which weren't possible to write before.
+As an example, the #[kani::should_panic] attribute allowed users to write harnesses expecting panic-related failures.
Also, we don't really know if more global conditions will be requested in the future. +We may consider discarding this proposal and waiting for the next feature that can be implemented as a global condition to be requested.
+One option we've considered in the past is to enable global conditions as a regular checks. +While it's technically doable, it doesn't feel appropriate for global conditions to reported through regular checks since generally a higher degree of visibility may be appreciated.
+No open questions.
+A redesign of Kani's output is likely to change the style/architecture to report global conditions.
+The results for global conditions would be computed during postprocessing based on the results of other checks. +Global conditions' checks aren't part of the SAT, therefore this computation won't impact verification time.
+We do not discuss the specific interface to report the failed checks because it needs improvements (for both global conditions and standard verification).
+In particular, the description field is the only information printed for properties (such as cover statements) without trace locations.
+There are additional improvements we should consider: printing the actual status (for global conditions, this won't always be FAILED), avoid the repetition of Failed Checks: , etc.
+This comment discusses problems with the current interface on some examples.
In other words, global conditions won't force a specific mechanism to be enabled.
+For example, if the #[kani::should_panic] attribute is converted into a global condition, it will continue to be enabled through the attribute itself.
+Other global conditions may be enabled through CLI flags only (e.g., --fail-uncoverable), or a combination of options in general.
line-coverage)Add verification-based line coverage reports to Kani.
+Nowadays, users can't easily obtain verification-based coverage reports in Kani. +Generally speaking, coverage reports show which parts of the code under verification are covered and which are not. +Because of that, coverage is often seen as a great metric to determine the quality of a verification effort.
+Moreover, some users prefer using coverage information for harness development and debugging. +That's because coverage information provides users with more familiar way to interpret verification results.
+This RFC proposes adding a new option for verification-based line coverage reports to Kani. +As mentioned earlier, we expect users to employ this coverage-related option on several stages of a verification effort:
+Moreover, adding this option directly to Kani, instead of relying on another tools, is likely to:
+Which translates into faster and more reliable coverage options for users.
+The goal is for Kani to generate code coverage report per harness in a well established format, such as LCOV, and possibly a summary in the output. +For now, we will focus on an interim solution that will enable us to assess the results of our instrumentation and enable integration with the Kani VS Code extension.
+For the first version, this experimental feature will report verification results along coverage reports.
+Because of that, we'll add a new section Coverage results that shows coverage results for each individual harness.
In the following, we describe an experimental output format. +Note that the final output format and overall UX is to be determined.
+The Coverage results section for each harness will produce coverage information in a CSV format as follows:
<file>, <line>, <status>
+where <status> is either FULL, PARTIAL or NONE.
As mentioned, this format is designed for evaluating the native instrumentation-based design and is likely to be substituted with another well-established format as soon as possible.
+Users are not expected to consume this output directly. +Instead, coverage data is to be consumed by the Kani VS Code extension and displayed as in the VS Code Extension prototype.
+How to activate and display coverage information in the extension is out of scope for this RFC. +That said, a proof-of-concept implementation is available here.
+We will add a new unstable --coverage verification option to Kani which will require -Z line-coverage until this feature is stabilized.
+We will also add a new --coverage-checks option to kani-compiler, which will result in the injection of coverage checks before each Rust statement and terminator1.
+This option will be supplied by kani-driver when the --coverage option is selected.
+These options will cause Kani to inject coverage checks during compilation and postprocess them to produce the coverage results sections described earlier.
Coverage checks are a new class of checks similar to cover checks.
+The main difference is that users cannot directly interact with coverage checks (i.e., they cannot add or remove them manually).
+Coverage checks are encoded as an assert(false) statement (to test reachability) with a fixed description.
+In addition, coverage checks are:
In the following, we describe the injection and postprocessing procedures to generate coverage results.
+The injection of coverage checks will be done while generating code for basic blocks. +This allows us to add one coverage check before each statement and terminator, which provides the most accurate results1. +It's not completely clear how this compares to the coverage instrumentation done in the Rust compiler, but an exploration to use the compiler APIs revealed that they're quite similar2.
+The injection of coverage checks often results in one or more checks per line (assuming a well-formatted program). +We'll postprocess these checks so for each line
+SATISFIED: return FULLUNSATISFIED: return NONEPARTIALWe won't report coverage status for lines which don't include a coverage check.
+Kani has relied on cbmc-viewer to report coverage information since the beginning.
+In essence, cbmc-viewer consumes data from coverage-focused invocations of CBMC and produces an HTML report containing (1) coverage information and (2) counterexample traces.
+Recently, there have been some issues with the coverage information reported by cbmc-viewer (e.g., #2048 or #1707), forcing us to mark the --visualize option as unstable and disable coverage results in the reports (in #2206).
However, it's possible for Kani to report coverage information without cbmc-viewer, as explained before.
+This would give Kani control on both ends:
cbmc-viewer's output, development is likely to be faster this way.cbmc-viewerAs an alternative, we could fix and use cbmc-viewer to report line coverage.
Most of the issues with cbmc-viewer are generally due to:
--cover <option>) in CBMC.cbmc-viewer.Note that (1) is not exclusive to coverage results from cbmc-viewer.
+Finding checks with missing locations and propagating them if possible (as suggested in this comment) should be done regardless of the approach used for line coverage reports.
In contrast, (2) and (3) can be considered the main problems for Kani contributors to develop coverage options on top of cbmc-viewer and CBMC.
+It's not clear how much effort this would involve, but (3) is likely to require substantial documentation contributions.
+But (4) shouldn't be an issue if we decided to invest in cbmc-viewer.
Finally, the following downside must be considered:
+cbmc-viewer can report line coverage but the path to report region-based coverage may involve a complete rewrite.
One of the long-term goals for this feature is to provide a UX that is familiar for users. +This is particularly relevant when talking about output formats. +Some services and frameworks working with certain coverage output formats have become quite popular.
+However, this version doesn't consider common output formats (i.e., GCOV or LCOV) since coverage results will only be consumed by the Kani VS Code Extension at first. +But other output formats will be considered in the future.
+Open questions:
+COVERED/UNCOVERED or FULL/PARTIAL/NONE?Feedback to gather before stabilization:
+We expect many incremental improvements in the coverage area:
+We have experimented with different options for injecting coverage checks. +For example, we have tried injecting one before each basic block, or one before each statement, etc. +The proposed option (one before each statement AND each terminator) gives us the most accurate results.
+In particular, comments in CoverageSpan and generate_coverage_spans hint that the initial set of spans come from Statements and Terminators. This comment goes in detail about the attempt to use the compiler APIs.
-Zfunction-contracts, enforced by compile time error1Function contracts are a means to specify and check function behavior. On top of +that the specification can then be used as a sound2 +abstraction to replace the concrete implementation, similar to stubbing.
+This allows for a modular verification.
+ +Function contracts provide an interface for a verified, +sound2 function abstraction. This is similar to stubbing +but with verification of the abstraction instead of blind trust. This allows for +modular verification, which paves the way for the following two ambitious goals.
+Function contracts are completely optional with no user impact if unused. This +RFC proposes the addition of new attributes, and functions, that shouldn't +interfere with existing functionalities.
+A function contract specifies the behavior of a function as a predicate that +can be checked against the function implementation and also used as an +abstraction of the implementation at the call sites.
+The lifecycle of a contract is split into three phases: specification, +verification and call abstraction, which we will explore on this example:
+fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}
+In the first phase we specify the contract. Kani provides two new
+annotations: requires (preconditions) to describe the expectations this
+function has as to the calling context and ensures (postconditions) which
+approximates function outputs in terms of function inputs.
#[kani::requires(divisor != 0)]
+#[kani::ensures(result <= dividend)]
+fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}
+requires here indicates this function expects its divisor input to never
+be 0, or it will not execute correctly (for instance panic or cause undefined
+behavior).
ensures puts a bound on the output, relative to the dividend input.
Conditions in contracts are Rust expressions which reference the
+function arguments and, in case of ensures, the return value of the
+function. The return value is a special variable called result (see open
+questions on a discussion about (re)naming). Syntactically
+Kani supports any Rust expression, including function calls, defining types
+etc. However they must be side-effect free (see also side effects
+here) or Kani will throw a compile error.
Multiple requires and ensures clauses are allowed on the same function,
+they are implicitly logically conjoined.
Next, Kani ensures that the function implementation respects all the conditions specified in its contract.
+To perform this check Kani needs a suitable harness to verify the function
+in. The harness is mainly responsible for providing the function arguments
+but also set up a valid heap that pointers may refer to and properly
+initialize static variables.
Kani demands of us, as the user, to provide this harness; a limitation of +this proposal. See also future possibilities for a +discussion about the arising soundness issues and their remedies.
+Harnesses for checking contract are defined with the
+proof_for_contract(TARGET) attribute which references TARGET, the
+function for which the contract is supposed to be checked.
#[kani::proof_for_contract(my_div)]
+fn my_div_harness() {
+ my_div(kani::any(), kani::any())
+}
+Similar to a verification harness for any other function, we are supposed to
+create all possible input combinations the function can encounter, then call
+the function at least once with those abstract inputs. If we forget to call
+my_div Kani reports an error. Unlike other harnesses we only need to create
+suitable data structures but we don't need to add any checks as Kani will
+use the conditions we specified in the contract.
Kani inserts preconditions (requires) as kani::assume before the call
+to my_div, limiting inputs to those the function is actually defined for.
+It inserts postconditions (ensures) as kani::assert checks after the
+call to my_div, enforcing the contract.
The expanded version of our harness that Kani generates looks roughly like +this:
+#[kani::proof]
+fn my_div_harness() {
+ let dividend = kani::any();
+ let divisor = kani::any();
+ kani::assume(divisor != 0); // requires
+ let result = my_div(dividend, divisor);
+ kani::assert(result <= dividend); // ensures
+}
+Kani verifies the expanded harness like any other harness, giving the +green light for the next step: call abstraction.
+In the last phase the verified contract is ready for us to use to +abstract the function at its call sites.
+Kani requires that there has to be at least one associated
+proof_for_contract harness for each abstracted function, otherwise an error is
+thrown. In addition, by default, it requires all proof_for_contract
+harnesses to pass verification before attempting verification of any
+harnesses that use the contract as a stub.
A possible harness that uses our my_div contract could be the following:
#[kani::proof]
+#[kani::stub_verified(my_div)]
+fn use_div() {
+ let v = vec![...];
+ let some_idx = my_div(v.len() - 1, 3);
+ v[some_idx];
+}
+At a call site where the contract is used as an abstraction Kani
+kani::asserts the preconditions (requires) and produces a
+nondeterministic value (kani::any) which satisfies the postconditions.
Mutable memory is similarly made non-deterministic, discussed later in +havocking.
+An expanded stubbing of my_div looks like this:
fn my_div_stub(dividend: u32, divisor: u32) -> u32 {
+ kani::assert(divisor != 0); // pre-condition
+ kani::any_where(|result| { /* post-condition */ result <= dividend })
+}
+Notice that this performs no actual computation for my_div (other than the
+conditions) which allows us to avoid something potentially costly.
Also notice that Kani was able to express both contract checking and abstracting +with existing capabilities; the important feature is the enforcement. The +checking is, by construction, performed against the same condition that is +later used as the abstraction, which ensures soundness (see discussion on +lingering threats to soundness in the future section) +and guarding against abstractions diverging from their checks.
+Functions can have side effects on data reachable through mutable references or +pointers. To overapproximate all such modifications a function could apply to +pointed-to data, the verifier "havocs" those regions, essentially replacing +their content with non-deterministic values.
+Let us consider a simple example of a pop method.
impl<T> Vec<T> {
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+This function can, in theory, modify any memory behind &mut self, so this is
+what Kani will assume it does by default. It infers the "write set", that is the
+set of memory locations a function may modify, from the type of the function
+arguments. As a result, any data pointed to by a mutable reference or pointer is
+considered part of the write set3. In addition, a static
+analysis of the source code discovers any static mut variables the function or
+it's dependencies reference and adds all pointed-to data to the write set also.
During havocking the verifier replaces all locations in the write set with
+non-deterministic values. Kani emits a set of automatically generated
+postconditions which encode the expectations from the Rust type system and
+assumes them for the havocked locations to ensure they are valid. This
+encompasses both limits as to what values are acceptable for a given type, such
+as char or the possible values of an enum discriminator, as well as lifetime
+constraints.
While the inferred write set is sound and enough for successful contract
+checking4 in many cases this inference is too coarse
+grained. In the case of pop every value in this vector will be made
+non-deterministic.
To address this the proposal also adds a modifies and frees clause which
+limits the scope of havocking. Both clauses represent an assertion that the
+function will modify only the specified memory regions. Similar to
+requires/ensures the verifier enforces the assertion in the checking stage to
+ensure soundness. When the contract is used as an abstraction, the modifies
+clause is used as the write set to havoc.
In our pop example the only modified memory location is the last element and
+only if the vector was not already empty, which would be specified thusly.
impl<T> Vec<T> {
+ #[modifies(if !self.is_empty() => (*self).buf.ptr.pointer.pointer[self.len])]
+ #[modifies(if self.is_empty())]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+The #[modifies(when = CONDITION, targets = { MODIFIES_RANGE, ... })] consists
+of a CONDITION and zero or more, comma separated MODIFIES_RANGEs which are
+essentially a place expression.
Place expressions describe a position in the abstract program memory. You may
+think of it as what goes to the left of an assignment. They compose of the name
+of one function argument (or static variable) and zero or more projections
+(dereference *, field access .x and slice indexing [1]5).
If no when is provided the condition defaults to true, meaning the modifies
+ranges apply to all invocations of the function. If targets is omitted it
+defaults to {}, e.g. an empty set of targets meaning under this condition the
+function modifies no mutable memory.
Because place expressions are restricted to using projections only, Kani must
+break Rusts pub/no-pub encapsulation here6.
+If need be we can reference fields that are usually hidden, without an error
+from the compiler.
In addition to a place expression, a MODIFIES_RANGE can also be terminated
+with more complex slice expressions as the last projection. This only applies
+to *mut pointers to arrays. For instance this is needed for Vec::truncate
+where all of the latter section of the allocation is assigned (dropped).
impl<T> Vec<T> {
+ #[modifies(self.buf.ptr.pointer.pointer[len..])]
+ fn truncate(&mut self, len: usize) {
+ ...
+ }
+}
+[..] denotes the entirety of an allocation, [i..], [..j] and [i..j] are
+ranges of pointer offsets5. The slice indices are offsets with sizing T, e.g.
+in Rust p[i..j] would be equivalent to
+std::slice::from_raw_parts(p.offset(i), i - j). i must be smaller or equal
+than j.
A #[frees(when = CONDITION, targets = { PLACE, ... })] clause works similarly
+to modifies but denotes memory that is deallocated. Like modifies it applies
+only to pointers but unlike modifies it does not admit slice syntax, only
+place expressions, because the whole allocation has to be freed.
Kani's contract language contains additional support to reason about changes of
+mutable memory. One case where this is necessary is whenever ensures needs to
+refer to state before the function call. By default variables in the ensures
+clause are interpreted in the post-call state whereas history expressions are
+interpreted in the pre-call state.
Returning to our pop function from before we may wish to describe in which
+case the result is Some. However that depends on whether self is empty
+before pop is called. To do this Kani provides the old(EXPR) pseudo
+function (see this section about a discussion on naming),
+which evaluates EXPR before the call (e.g. to pop) and makes the result
+available to ensures. It is used like so:
impl<T> Vec<T> {
+ #[kani::ensures(old(self.is_empty()) || result.is_some())]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+old allows evaluating any Rust expression in the pre-call context, so long as
+it is free of side-effects. See also this
+explanation. The borrow checker enforces that the
+mutations performed by e.g. pop cannot be observed by the history expression, as
+that would defeat the purpose. If you wish to return borrowed content from
+old, make a copy instead (using e.g. clone()).
Note also that old is syntax, not a function and implemented as an extraction
+and lifting during code generation. It can reference e.g. pop's arguments but
+not local variables. Compare the following
Invalid ❌: #[kani::ensures({ let x = self.is_empty(); old(x) } || result.is_some())]
+Valid ✅: #[kani::ensures(old({ let x = self.is_empty(); x }) || result.is_some())]
And it will only be recognized as old(...), not as let old1 = old; old1(...) etc.
kani or cargo kani first verifies all contract harnesses
+(proof_for_contract) reachable from the file or in the local workspace
+respectively.stub_verified is required to have at least one associated contract harness.
+Kani reports any missing contract harnesses as errors.stub_verified contracts
+passed step 1 and 2.When specific harnesses are selected (with --harness) contracts are not
+verified.
Kani reports a compile time error if any of the following constraints are violated:
+A function may have any number of requires, ensures, modifies and frees
+attributes. Any function with at least one such annotation is considered as
+"having a contract".
Harnesses (general or for contract checking) may not have any such annotation.
+A harness may have up to one proof_for_contract(TARGET) annotation where TARGET must
+"have a contract". One or more proof_for_contract harnesses may have the
+same TARGET.
A proof_for_contract harness may use any harness attributes, including
+stub and stub_verified, though the TARGET may not appear in either.
Kani checks that TARGET is reachable from the proof_for_contract harness,
+but it does not warn if abstracted functions use TARGET8.
A proof_for_contract function may not have the kani::proof attribute (it
+is already implied by proof_for_contract).
A harness may have multiple stub_verified(TARGET) attributes. Each TARGET
+must "have a contract". No TARGET may appear twice. Each local TARGET is
+expected to have at least one associated proof_for_contract harness which
+passes verification, see also the discussion on when to check contracts in
+open questions.
Harnesses may combine stub(S_TARGET, ..) and stub_verified(V_TARGET)
+annotations, though no target may occur in S_TARGETs and V_TARGETs
+simultaneously.
For mutually recursive functions using stub_verified, Kani will check their
+contracts in non-deterministic order and assume each time the respective other
+check succeeded.
Kani implements the functionality of function contracts in three places.
+requires and ensures macros (kani_macros).kani-compiler for modifies clauses.kani-driver to enforce
+contract checking before replacement. Also plumbing between compiler and
+driver for enforcement of assigns clauses.kani_macrosThe requires and ensures macros perform code generation in the macro,
+creating a check and a replace function which use assert and assume as
+described in the user experience section. Both are attached
+to the function they are checking/replacing by kanitool::checked_with and
+kanitool::replaced_with attributes respectively. See also the
+discussion about why we decided to generate check
+and replace functions like this.
The code generation in the macros is straightforward, save two aspects: old
+and the borrow checker.
The special old builtin function is implemented as an AST rewrite. Consider
+the below example:
impl<T> Vec<T> {
+ #[kani::ensures(self.is_empty() || self.len() == old(self.len()) - 1)]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+The ensures macro performs an AST rewrite consisting of an extraction of the
+expressions in old and a replacement with a fresh local variable, creating the
+following:
impl<T> Vec<T> {
+ fn check_pop(&mut self) -> Option<T> {
+ let old_1 = self.len();
+ let result = Self::pop(self);
+ kani::assert(self.is_empty() || self.len() == old_1 - 1)
+ }
+}
+Nested invocations of old are prohibited (Kani throws an error) and the
+expression inside may only refer to the function arguments and not other local
+variables in the contract (Rust will report those variables as not being in
+scope).
The borrow checker also ensures for us that none of the temporary variables
+borrow in a way that would be able to observe the modification in pop which
+would occur for instance if the user wrote old(self). Instead of borrowing
+copies should be created (e.g. old(self.clone())). This is only enforced for
+safe Rust though.
The second part relevant for the implementation is how we deal with the borrow
+checker for postconditions. They reference the arguments of the function after
+the call which is problematic if part of an input is borrowed mutably in the
+return value. For instance the Vec::split_at_mut function does this and a
+sensible contract for it might look as follows:
impl<T> Vec<T> {
+ #[ensures(self.len() == result.0.len() + result.1.len())]
+ fn split_at_mut(&mut self, i: usize) -> (&mut [T], &mut [T]) {
+ ...
+ }
+}
+This contract refers simultaneously to self and the result. Since the method
+however borrows self mutably, it would no longer be accessible in the
+postcondition. To work around this we strategically break the borrowing rules
+using a new hidden builtin kani::unchecked_deref with the type signature for <T> fn (&T) -> T which is essentially a C-style dereference operation. Breaking
+the borrow checker like this is safe for 2 reasons:
bool, meaning they cannot leak references to
+the arguments and cause the race conditions the Rust type system tries to
+prevent.The "copies" of arguments created by unsafe_deref are stored as fresh local
+variables and their occurrence in the postcondition is renamed. In addition a
+mem::forget is emitted for each copy to avoid a double free.
Kani verifies contracts for recursive functions inductively. Reentry of the +function is detected with a function-specific static variable. Upon detecting +reentry we use the replacement of the contract instead of the function body.
+Kani generates an additional wrapper around the function to add the detection.
+The additional wrapper is there so we can place the modifies contract on
+check_pop and replace_pop instead of recursion_wrapper which prevents CBMC
+from triggering its recursion induction as this would skip our replacement checks.
#[checked_with = "recursion_wrapper"]
+#[replaced_with = "replace_pop"]
+fn pop(&mut self) { ... }
+
+fn check_pop(&mut self) { ... }
+
+fn replace_pop(&mut self) { ... }
+
+fn recursion_wrapper(&mut self) {
+ static mut IS_ENTERED: bool = false;
+
+ if unsafe { IS_ENTERED } {
+ replace_pop(self)
+ } else {
+ unsafe { IS_ENTERED = true; }
+ let result = check_pop(self);
+ unsafe { IS_ENTERED = false; }
+ result
+ };
+}
+Note that this is insufficient to verify all types of recursive functions, as +the contract specification language has no support for inductive lemmas (for +instance in ACSL section 2.6.3 +"inductive predicates"). Inductive lemmas are usually needed for recursive +data structures.
+Contract enforcement and replacement (kani::proof_for_contract(f),
+kani::stub_verified(f)) both dispatch to the stubbing logic, stubbing f
+with the generated check and replace function respectively. If f has no
+contract, Kani throws an error.
For write sets Kani relies on CBMC. modifies clauses (whether derived from
+types or from explicit clauses) are emitted from the compiler as GOTO contracts
+in the artifact. Then the driver invokes goto-instrument with the name of the
+GOTO-level function names to enforce or replace the memory contracts. The
+compiler communicates the names of the function via harness metadata.
Code used in contracts is required to be side effect free which means it
+must not perform I/O, mutate memory (&mut vars and such) or (de)allocate heap
+memory. This is enforced in two layers. First with an MIR traversal over all
+code reachable from a contract expression. An error is thrown if known
+side-effecting actions are performed such as ptr::write, malloc, free or
+functions which we cannot check, such as e.g. extern "C", with the exception
+of known side effect free functions in e.g. the standard library.
Instead of generating check and replace functions in Kani, we could use the contract instrumentation provided by CBMC.
+We tried this earlier but came up short, because it is difficult to implement, +while supporting arbitrary Rust syntax. We exported the conditions into +functions so that Rust would do the parsing/type checking/lowering for us and +then call the lowered function in the CBMC contract.
+The trouble is that CBMC's old is only supported directly in the contract, not
+in functions called from the contract. This means we either need to inline the
+contract function body, which is brittle in the presence of control flow, or we
+must extract the old expressions, evaluate them in the contract directly and
+pass the results to the check function. However this means we must restrict the
+expressions in old, because we now need to lower those by hand and even if we
+could let rustc do it, CBMC's old has no support for function calls in its
+argument expression.
Instead of expanding contract macros one-at-a-time and layering the checks we +could expand all subsequent one's with the outermost one in one go.
+This is however brittle with respect to renaming. If a user does use kani::requires as my_requires and then does multiple
+#[my_requires(condition)] macro would not collect them properly since it can
+only match syntactically and it does not know about the use and neither can we
+restrict this kind of use or warn the user. By contrast, the collection with
+kanitool::checked_with is safe, because that attribute is generated by our
+macro itself, so we can rely on the fact that it uses the canonical
+representation.
Instead of generating the check and replace functions as siblings to the
+contracted function we could nest them like so
fn my_div(dividend: u32, divisor: u32) -> u32 {
+ fn my_div_check_5e3713(dividend: u32, divisor: u32) -> u32 {
+ ...
+ }
+ ...
+}
+This could be beneficial if we want to be able to allow contracts on trait impl +items, in which case generating sibling functions is not allowed. On the other +hand this makes it harder to implement contracts on trait definitions, +because there is no body available which we could nest the function into. +Ultimately we may require both so that we can support both.
+What is required to make this work is an additional pass over the condition that
+replaces every self with a fresh identifier that now becomes the first
+argument of the function. In addition there are open questions as to how to
+resolve the nested name inside the compiler.
Instead of
+adding a new special proof_for_contact attributes we could have instead done:
kani invocation with something like a
+--check-contract flag that directs the system to instrument the function.
+This is a very flexible design, but also easily used incorrectly.
+Specifically nothing in the source indicates which harnesses are supposed
+to be used for which contract, users must remember to invoke the check and
+are also responsible for ensuring they really do verify all contacts they
+will later be replacing and lastly.#[kani::proof] harness. This would have used
+e.g. a #[kani::for_contract] attributes on a #[kani::proof]. Since
+#[kani::for_contract] is only valid on a proof, we decided to just
+imply it and save the user some headache. Contract checking harnesses are
+not meant to be reused for other purposes anyway and if the user really
+wants to the can just factor out the actual contents of the harness to
+reuse it.A current limitation with how contracts are enforced means that if the target of
+a proof_for_contract is polymorphic, only one monomorphization is permitted to
+occur in the harness. This does not limit the target to a single occurrence,
+but to a single instantiation of its generic parameters.
This is because we rely on CBMC for enforcing the modifies contract. At the
+GOTO level all monomorphized instances are distinct functions and CBMC only
+allows checking one function contract at a time, hence this restriction.
We make the user supply the harnesses for checking contracts. This is our major +source of unsoundness, if corner cases are not adequately covered. Having Kani +generate the harnesses automatically is a non-trivial task (because heaps are +hard) and will be the subject of future improvements.
+In limited cases we could generate harnesses, for instance if only bounded types
+(integers, booleans, enums, tuples, structs, references and their combinations)
+were used. We could restrict the use of contracts to cases where only such types
+are involved in the function inputs and outputs, however this would drastically
+limit the applicability, as even simple heap data structures such as Vec,
+String and even &[T] and &str (slices) would be out of scope. These data
+structures however are ubiquitous and users can avoid the unsoundness with
+relative confidence by overprovisioning (generating inputs that are several
+times larger than what they expect the function will touch).
Returning kani::any() in a replacement isn't great, because it wouldn't work
+for references as they can't have an Arbitrary implementation. Plus the
+soundness then relies on a correct implementation of Arbitrary. Instead it
+may be better to allow for the user to specify type invariants which can the
+be used to generate correct values in replacement but also be checked as part
+of the contract checking.
Making result special. Should we use special syntax here like @result or
+kani::result(), though with the latter I worry that people may get confused
+because it is syntactic and not subject to usual use renaming and import
+semantics. Alternatively we can let the user pick the name with an additional
+argument to ensures, e.g. ensures(my_result_var, CONDITION)
Similar concerns apply to old, which may be more appropriate to be special
+syntax, e.g. @old.
See #2597
+How to check the right contracts at the right time. By default kani and
+cargo kani check all contracts in a crate/workspace. This represents the
+safest option for the user but may be too costly in some cases.
The user should be provided with options to disable contract checking for the +sake of efficiency. Such options may look like this:
+kani/cargo kani) all local contracts are checked,
+harnesses are only checked if the contracts they depend on succeeded their check.--harness) only those contracts which the
+selected harnesses depend on are checked.--paranoid flag also checks contracts for
+dependencies (other crates) when they are used in abstractions.#[stub_verified(TARGET, trusted)] or
+#[stub_unverified(TARGET)]. This also plays nicely with cfg_attr.--trusted TARGET to skip checking those
+contracts.--all-trusted.--litigate flag checks only contract harnesses.Aside: I'm obviously having some fun here with the names, happy to change, +it's really just about the semantics.
+Can old accidentally break scope? The old function cannot reference local
+variables. For instance #[ensures({let x = ...; old(x)})] cannot work as an
+AST rewrite because the expression in old is lifted out of it's context into
+one where the only bound variables are the function arguments (see also
+history expressions). In most cases this will be a
+compiler error complaining that x is unbound, however it is possible that
+if there is also a function argument x, then it may silently succeed the
+code generation but confusingly fail verification. For instance #[ensures({ let x = 1; old(x) == x })] on a function that has an argument named x would
+not hold.
To handle this correctly we would need an extra check that detects if old
+references local variables. That would also enable us to provide a better
+error message than the default "cannot find value x in this scope".
Can panicking be expected behavior? Usually preconditions are used to rule +out panics but it is conceivable that a user would want to specify that a +function panics under certain conditions. Specifying this would require an +extension to the current interface.
+UB checking. With unsafe rust it is possible to break the type system +guarantees in Rust without causing immediate errors. Contracts must be +cognizant of this and enforce the guarantees as part of the contract or +require users to explicitly defer such checks to use sites. The latter case +requires dedicated support because the potential UB must be reflected in the +havoc.
+modifies clauses over patterns. Modifies clauses mention values bound in
+the function header and as a user I would expect that if I use a pattern in
+the function header then I can use the names bound in that pattern as base
+variables in the modifies clause. However modifies clauses are implemented
+as assigns clauses in CBMC which does not have a notion of function header
+patterns. Thus it is necessary to project any modifies ranges deeper by the
+fields used in the matched pattern.
Quantifiers: Quantifiers are like logic-level loops and a powerful
+reasoning helper. CBMC has support for both exists and forall, but the
+code generation is difficult. The most ergonomic and easy way to implement
+quantifiers on the Rust side is as higher-order functions taking Fn(T) -> bool, where T is some arbitrary type that can be quantified over. This
+interface is familiar to developers, but the code generation is tricky, as
+CBMC level quantifiers only allow certain kinds of expressions. This
+necessitates a rewrite of the Fn closure to a compliant expression.
Letting the user supply the harnesses for checking contracts is a source of +unsoundness, if corner cases are not adequately covered. Ideally Kani would +generate the check harness automatically, but this is difficult both because +heap data structures are potentially infinite, and also because it must observe +user-level type invariants.
+A complete solution for this is not known to us but there are ongoing +investigations into harness generation mechanisms in CBMC.
+Function inputs that are non-inductive could be created from the type as the +safe Rust type constraints describe a finite space.
+For dealing with pointers one applicable mechanism could be memory +predicates to declaratively describe the state of the heap both before and +after the function call.
+In CBMC's implementation memory predicates are part of the pre/postconditions.
+This does not easily translate to Kani, since we handle pre/postconditions
+manually and mainly in proc-macros. There are multiple ways to bridge this
+gap, perhaps the easiest being to add memory predicates separately to Kani
+instead of as part of pre/postconditions, so they can be handled by forwarding
+them to CBMC. However this is also tricky, because memory predicates are used
+to describe pointers and pointers only. Meaning that if they are encapsulated
+in a structure (such as Vec or RefCell) there is no way of specifying the
+target of the predicate without breaking encapsulation (similar to
+modifies). In addition there are limitations also on the pointer predicates
+in CBMC itself. For instance they cannot be combined with quantifiers.
A better solution would be for the data structure to declare its own +invariants at definition site which are automatically swapped in on every +contract that uses this type.
+What about mutable trait inputs (wrt memory access patters), e.g. a mut impl AccessMe
Trait contracts: Our proposal could be extended easily to handle simple
+trait contracts. The macros would generate new trait methods with default
+implementations, similar to the functions it generates today. Using sealed
+types we can prevent the user from overwriting the generated contract methods.
+Contracts for the trait and contracts on it's impls are combined by abstracting
+the original method depending on context. The occurrence inside the contract
+generated from the trait method is replaced by the impl contract. Any other
+occurrence is replaced by the just altered trait method contract.
Cross Session Verification Caching: This proposal focuses on scalability +benefits within a single verification session, but those verification results +could be cached across sessions and speed up verification for large projects +using contacts in the future.
+Inductive Reasoning: Describing recursive functions can require that the +contract also recurse, describing a fixpoint logic. This is needed for +instance for linked data structures like linked lists or trees. Consider for +instance a reachability predicate for a linked list:
+struct LL<T> { head: T, next: *const LL<T> }
+
+fn reachable(list: &LL<T>, t: &T) -> bool {
+ list.head == t
+ || unsafe { next.as_ref() }.map_or(false, |p| reachable(p, t))
+}
+
+Compositional Contracts: The proposal in this document lacks a +comprehensive handling of type parameters. Contract checking harnesses require +monomorphization. However this means the contract is only checked against a +finite number of instantiations of any type parameter (at most as many as +contract checking harnesses were defined). There is nothing preventing the +user from using different instantiations of the function's type parameters.
+A function (f()) can only interact with its type parameters P through the
+traits (T) they are constrained over. We can require T to carry contracts
+on each method T::m(). During checking we can use a synthetic type that
+abstracts T::m() with its contract. This way we check f() against Ts
+contract. Then we later abstract f() we can ensure any instantiations of P
+have passed verification of the contract of T::m(). This makes the
+substitution safe even if the particular type has not been used in a checking
+harness.
For higher order functions this gets a bit more tricky, as closures are ad-hoc
+defined types. Here the contract for the closure could be attached to f()
+and then checked for each closure that may be provided. However this does not
+work so long as the user has to provide the harnesses, as they cannot recreate
+the closure type.
Enforced gates means all uses of constructs (functions, annotations, +macros) in this RFC are an error.
+The main remaining threat to soundness in the use of +contracts, as defined in this proposal, is the reliance on user-supplied +harnesses for contract checking (explained in item 2 of user +experience). A more thorough discussion on the dangers +and potential remedies can be found in the future +section.
+For inductively defined types the write set inference
+will only add the first "layer" to the write set. If you wish to modify
+deeper layers of a recursive type an explicit modifies clause is required.
While inferred memory footprints are sound for both safe
+and unsafe Rust certain features in unsafe rust (e.g. RefCell) get
+inferred incorrectly and will lead to a failing contract check.
Slice indices can be place expressions referencing function
+arguments, constants and integer arithmetic expressions. Take for example
+this Vec method (places simplified vs. actual implementation in std):
+fn truncate(&mut self, len: usize). A relatively precise contract for this
+method can be achieved with slice indices like so:
+#[modifies(self.buf[len..self.len], self.len)]
Breaking the pub encapsulation has
+unfortunate side effects because it means the contract depends on non-public
+elements which are not expected to be stable and can drastically change even
+in minor versions. For instance if your project depends on crate a which
+in turn depends on crate b, and a::foo has a contract that takes as
+input a pointer data structure b::Bar then a::foos assigns contract
+must reference internal fields of b::Bar. Say your project depends on the
+replacement of a::foo, if b changes the internal representation of
+Bar in a minor version update cargo could bump your version of b,
+breaking the contract of a::foo (it now crashes because it e.g. references
+non-existent fields).
+You cannot easily update the contract for a::foo, since it is a
+third-party crate; in fact even the author of a could not properly update
+to the new contract since their old version specification would still admit
+the new, broken version of b. They would have to yank the old version and
+explicitly nail down the exact minor version of b which defeats the whole
+purpose of semantic versioning.
Contracts for functions from
+external crates (crates from outside the workspace, which is not quite the
+definition of extern crate in Rust) are not checked by default. The
+expectation is that the library author providing the contract has performed
+this check. See also open question for a discussion on
+defaults and checking external contracts.
Kani cannot report the occurrence of a contract function to check +in abstracted functions as errors, because the mechanism is needed to verify +mutually recursive functions.
+mir_linker)Fix linking issues with the rust standard library in a scalable manner by only generating goto-program for +code that is reachable from the user harnesses.
+The main goal of this RFC is to enable Kani users to link against all supported constructs from the std library.
+Currently, Kani will only link to items that are either generic or have an inline annotation.
The approach introduced in this RFC will have the following secondary benefits.
+One downside is that we will include a pre-compiled version of the std, our release bundle will double in size
+(See Rational and Alternatives
+for more information on the size overhead).
+This will negatively impact the time taken to set up Kani
+(triggered by either the first time a user invokes kani | cargo-kani , or explicit invoke the subcommand setup).
Once this RFC has been stabilized users shall use Kani in the same manner as they have been today.
+Until then, we wil add an unstable option --mir-linker to enable the cross-crate reachability analysis
+and the generation of the goto-program only when compiling the target crate.
Kani setup will likely take longer and more disk space as mentioned in the section above.
+This change will not be guarded by --mir-linker option above.
In a nutshell, we will no longer generate a goto-program for every crate we compile. +Instead, we will generate the MIR for every crate, and we will generate only one goto-program. +This model will only include items reachable from the target crate's harnesses.
+The current system flow for a crate verification is the following (Kani here represents either kani | cargo-kani
+executable):
kani-compiler will generate a goto-program.
+This model includes everything reachable from the crate's public functions.goto-cc.
+This step will also link against Kani's C library.goto-instrument to prune the linked model to only include items reachable from the given harness.goto-instrument and cbmc calls.After this RFC, the system flow would be slightly different:
+kani-compiler will generate an artifact that includes the MIR representation
+of all items in the crate.goto-cc will still be invoked to link the generated model against Kani's C library.This feature will require three main changes to Kani which are detailed in the sub-sections below.
+Kani currently uses rustup sysroot to gather information from the standard library constructs.
+The artifacts from this sysroot include the MIR for generic items as well as for items that may be included in
+a crate compilation (e.g.: functions marked with #[inline] annotation).
+The artifacts do not include the MIR for items that have already been compiled to the std shared library.
+This leaves a gap that cannot be filled by the kani-compiler;
+thus, we are unable to translate these items into goto-program.
In order to fulfill this gap, we must compile the standard library from scratch.
+This RFC proposes a similar method to what MIRI implements.
+We will generate our own sysroot using the -Z always-encode-mir compilation flag.
+This sysroot will be pre-compiled and included in our release bundle.
We will compile kani's libraries (kani and std) also with -Z always-encode-mir
+and with the new sysroot.
kani-compiler will include a new reachability module to traverse over the local and external MIR items.
+This module will monomorphize all generic code as it's performing the traversal.
The traversal logic will be customizable allowing different starting points to be used.
+The two options to be included in this RFC is starting from all local harnesses
+(tagged with #[kani::proof]) and all public functions in the local crate.
The kani-compiler behavior will be customizable via a new flag:
--reachability=[ harnesses | pub_fns | none | legacy | tests ]
+where:
+harnesses: Use the local harnesses as the starting points for the reachability analysis.pub_fns: Use the public local functions as the starting points for the reachability analysis.none: This will be the default value if --reachability flag is not provided. It will skip
+reachability analysis. No goto-program will be generated.
+This will be used to compile dependencies up to the MIR level.
+kani-compiler will still generate artifacts with the crate's MIR.tests: Use the functions marked as tests with #[tests] as the starting points for the analysis.legacy: Mimics rustc behavior by invoking
+rustc_monomorphizer::collect_and_partition_mono_items() to collect the items to be generated.
+This will not include many items that go beyond the crate boundary.
+This option was only kept for now for internal usage in some of our compiler tests.
+It cannot be used as part of the end to end verification flow, and it will be removed in the future.These flags will not be exposed to the final user.
+They will only be used for the communication between kani-driver and kani-compiler.
The flags described in the section above will be used by kani-driver to implement the new system flow.
+For that, we propose the following mechanism:
For standalone kani, we will pass the option --reachability=harnesses to kani-compiler.
For cargo-kani, we will replace
cargo build <FLAGS>
+with:
+cargo rustc <FLAGS> -- --reachability=harnesses
+to build everything.
+This command will compile all dependencies without the --reachability argument, and it will only pass harnesses
+value to the compiler when compiling the target crate.
Not doing anything is not an alternative, since this fixes a major gap in Kani's usability.
+kani-compiler.#[no_mangle] annotation
+(Issue-661).Failures in the linking stage would not impact the tool soundness. I anticipate the following failure scenarios:
+The new reachability code would be highly dependent on the rustc unstable APIs, which could increase
+the cost of the upstream synchronization.
+That said, the APIs that would be required are already used today.
Finally, this implementation relies on a few unstable options from cargo and rustc.
+These APIs are used by other tools such as MIRI, so we don't see a high risk that they would be removed.
The other options explored were:
+*symtab.json files.symtab2gb) and link them into one single goto-program.
+Ship the generated model.Both would still require shipping the compiler metadata (via rlib or rmeta) for the kani library, its
+dependencies, and kani_macro.so.
Both alternatives are very similar. They only differ on the artifact that would be shipped.
+They require generating and shipping a custom sysroot;
+however, there is no need to implement the reachability algorithm.
We implemented a prototype for the MIR linker and one for the alternatives.
+Both prototypes generate the sysroot as part of the cargo kani flow.
We performed a small experiment (on a c5.4xlarge ec2 instance running Ubuntu 20.04) to assess the options.
For this experiment, we used the following harness:
+#[kani::proof]
+#[kani::unwind(4)]
+pub fn check_format() {
+ assert!("2".parse::<u32>().unwrap() == 2);
+}
+The experiment showed that the MIR linker approach is much more efficient.
+See the table bellow for the breakdown of time (in seconds) taken for each major step of +the harness verification:
+| Stage | MIR Linker | Alternative 1 |
|---|---|---|
| compilation | 22.2s | 64.7s |
| goto-program generation | 2.4s | 90.7s |
| goto-program linking | 0.8s | 33.2s |
| code instrumentation | 0.8s | 33.1 |
| verification | 0.5s | 8.5s |
It is possible that goto-cc time can be improved, but this would also require further experimentation and
+expertise that we don't have today.
Every option would require a custom sysroot to either be built or shipped with Kani.
+The table below shows the size of the sysroot files for the alternative #2
+(goto-program files) vs compiler artifacts (*.rmeta files)
+files with -Z always-encode-mir for x86_64-unknown-linux-gnu (on Ubuntu 18.04).
| File Type | Raw size | Compressed size |
|---|---|---|
symtab.json | 950M | 26M |
symtab.out | 84M | 24M |
*.rmeta | 92M | 25M |
These results were obtained by looking at the artifacts generated during the same experiment.
+kani setup?std library.workspace?cargo rustc per package.cargo kani --tests?cargo rustc --profile test -- --reachability=harnessesC to rust.function-stubbing)Allow users to specify that certain functions and methods should be replaced with mock functions (stubs) during verification.
+In scope:
+Out of scope:
+We anticipate that function/method stubbing will have a substantial positive impact on the usability of Kani:
+f, and then in other proofs---that call f indirectly---use a stub of f that mocks that behavior but is less complex.In all cases, stubbing would enable users to verify code that cannot currently be verified by Kani (or at least not within a reasonable resource bound).
+Even without stubbing types, the ability to stub functions/methods can help provide verification-friendly abstractions for standard data structures.
+For example, Issue 1673 suggests that some Kani proofs run more quickly if Vec::new is replaced with Vec::with_capacity; function stubbing would allow us to make this substitution everywhere in a codebase (and not just in the proof harness).
In what follows, we give an example of stubbing external code, using the annotations we propose in this RFC. +We are able to run this example on a modified version of Kani using a proof-of-concept MIR-to-MIR transformation implementing stubbing (the prototype does not support stub-related annotations; instead, it reads the stub mapping from a file). +This example stubs out a function that returns a random number. +This is the type of function that is commonly stubbed in other verification and program analysis projects, along with system calls, timer functions, logging calls, and deserialization methods---all of which we should be able to handle. +See the appendix at the end of this RFC for an extended example involving stubbing out a deserialization method.
+The crate rand is widely used (150M downloads).
+However, Kani cannot currently handle code that uses it (Kani users have run into this; see Issue 1727.
+Consider this example:
#[cfg(kani)]
+#[kani::proof]
+fn random_cannot_be_zero() {
+ assert_ne!(rand::random::<u32>(), 0);
+}
+For unwind values less than 2, Kani encounters an unwinding assertion error (there is a loop used to seed the random number generator); if we set an unwind value of 2, Kani fails to terminate within 5 minutes.
+Using stubbing, we can specify that the function rand::random should be replaced with a mocked version:
#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(rand::random, mock_random)]
+fn random_cannot_be_zero() {
+ assert_ne!(rand::random::<u32>(), 0);
+}
+Under this substitution, Kani has a single check, which proves that the assertion can fail. Verification time is 0.02 seconds.
+This feature is currently limited to stubbing functions and methods. +We anticipate that the annotations we propose here could also be used for stubbing types, although the underlying technical approach might have to change.
+Stubs will be specified per harness; that is, different harnesses can use different stubs. +This is one of the main design points. +Users might want to mock the behavior of a function within one proof harness, and then mock it a different way for another harness, or even use the original function definition. +It would be overly restrictive to impose the same stub definitions across all proof harnesses. +A good example of this is compositional reasoning: in some harnesses, we want to prove properties of a particular function (and so want to use its actual implementation), and in other harnesses we want to assume that that function has those properties.
+Users will specify stubs by attaching the #[kani::stub(<original>, <replacement>)] attribute to each harness function.
+The arguments original and replacement give the names of functions/methods.
+They will be resolved using Rust's standard name resolution rules; this includes supporting imports like use foo::bar as baz, as well as imports of multiple versions of the same crate (in which case a name would resolve to a function/method in a particular version).
+The attribute may be specified multiple times per harness, so that multiple (non-conflicting) stub pairings are supported.
For example, this code specifies that the function mock_random should be used in place of the function rand::random and the function my_mod::bar should be used in place of the function my_mod::foo for the harness my_mod::my_harness:
#[cfg(kani)]
+fn mock_random<T: kani::Arbitrary>() -> T {
+ kani::any()
+}
+
+mod my_mod {
+
+ fn foo(x: u32) -> u32 { ... }
+
+ fn bar(x: u32) -> u32 { ... }
+
+ #[cfg(kani)]
+ #[kani::proof]
+ #[kani::stub(rand::random, super::mock_random)]
+ #[kani::stub(foo, bar)]
+ fn my_harness() { ... }
+
+}
+We will support the stubbing of private functions and methods. +While this provides flexibility that we believe will be necessary in practice, it can also lead to brittle proofs: private functions/methods can change or disappear in even minor version upgrades (thanks to refactoring), and so proofs that depend on them might have a high maintenance burden. +In the documentation, we will discourage stubbing private functions/methods except if absolutely necessary.
+As a convenience, we will provide a macro kani::stub_set that allows users to specify sets of stubs that can be applied to multiple harnesses:
kani::stub_set!(my_io_stubs(
+ stub(std::fs::read, my_read),
+ stub(std::fs::write, my_write),
+));
+When declaring a harness, users can use the #[kani::use_stub_set(<stub_set_name>)] attribute to apply the stub set:
#[cfg(kani)]
+#[kani::proof]
+#[kani::use_stub_set(my_io_stubs)]
+fn my_harness() { ... }
+The name of the stub set will be resolved through the module path (i.e., they are not global symbols), using Rust's standard name resolution rules.
+A similar mechanism can be used to aggregate stub sets:
+kani::stub_set!(all_my_stubs(
+ use_stub_set(my_io_stubs),
+ use_stub_set(my_other_stubs),
+));
+Given a set of original-replacement pairs, Kani will exit with an error if
original function/method does not exist;replacement stub does not exist;original function is mapped to multiple replacement functions); orreplacement stub is not compatible with the signature of the original function/method (see next section).When considering whether a function/method can be replaced with some given stub, we want to allow some measure of flexibility, while also ensuring that we can provide the user with useful feedback if stubbing results in misformed code. +We consider a stub and a function/method to be compatible if all the following conditions are met:
+bar<A, B>(x: A, y: B) -> B is considered to have a type compatible with the function foo<S, T>(x: S, y: T) -> T.The final point is the most subtle. +We do not require that a type parameter in the signature of the stub implements the same traits as the corresponding type parameter in the signature of the original function/method. +However, Kani will reject a stub if a trait mismatch leads to a situation where a statically dispatched call to a trait method cannot be resolved during monomorphization. +For example, this restriction rules out the following harness:
+fn foo<T>(_x: T) -> bool {
+ false
+}
+
+trait DoIt {
+ fn do_it(&self) -> bool;
+}
+
+fn bar<T: DoIt>(x: T) -> bool {
+ x.do_it()
+}
+
+#[kani::proof]
+#[kani::stub(foo, bar)]
+fn harness() {
+ assert!(foo("hello"));
+}
+The call to the trait method DoIt::do_it is unresolvable in the stub bar when the type parameter T is instantiated with the type &str.
+On the other hand, our approach provides some flexibility, such as allowing our earlier example of mocking randomization: both rand::random and my_random have the type () -> T, but in the first case T is restricted such that the type Standard implements Distribution<T>, whereas in the latter case T has to implement kani::Arbitrary.
+This trait mismatch is allowed because at this call site T is instantiated with u32, which implements kani::Arbitrary.
To teach this feature, we will update the documentation with a section on function and method stubbing, including simple examples showing how stubbing can help Kani handle code that currently cannot be verified, as well as a guide to best practices for stubbing.
+We expect that this feature will require changes primarily to kani-compiler, with some less invasive changes to kani-driver.
+We will modify kani-compiler to collects stub mapping information (from the harness attributes) before code generation.
+Since stubs are specified on a per-harness basis, we need to generate multiple versions of code if all harnesses do not agree on their stub mappings; accordingly, we will update kani-compiler to generate multiple versions of code as appropriate.
+To do the stubbing, we will plug in a new MIR-to-MIR transformation that replaces the bodies of specified functions with their replacements.
+This can be achieved via rustc's query mechanism: if the user wants to replace foo with bar, then when the compiler requests the MIR for foo, we instead return the MIR for bar.
+kani-compiler will also be responsible for checking for the error conditions previously enumerated.
We will also need to update the metadata that kani-compiler generates, so that it maps each harness to the generated code that has the right stub mapping for that harness (since there will be multiple versions of generated code).
+The metadata will also list the stubs applied in each harness.
+kani-driver will need to be updated to process this new type of metadata and invoke the correct generated code for each harness.
+We can also update the results report to include the stubs that were used.
We anticipate that this design will evolve and be iterated upon.
+Stubbing is a de facto necessity for verification tools, and the lack of stubbing has a negative impact on the usability of Kani.
+In this alternative, users add an attribute #[kani::stub_by(<replacement>)] to the function that should be replaced.
+This approach is similar to annotating a function with a contract specifying its behavior (the stub acts like a programmatic contract).
+The major downside with this approach is that it would not be possible to stub external code. We see this as a likely use case that needs to be supported: users will want to replace std library functions or functions from arbitrary external crates.
In this alternative, users add an attribute #[kani::stub_of(<original>)] to the stub function itself, saying which function it replaces:
#[cfg(kani)]
+#[kani::stub_of(rand::random)]
+fn mock_random<T: kani::Arbitrary>() -> T { ... }
+The downside is that this stub must be uniformly applied across all harnesses and the stub specifications might be spread out across multiple files. +It would also require an extra layer of indirection to use a function as a stub if the user does not have source code access to it.
+This alternative combines the proposed solution and Alternative #2.
+Users annotate the stub (as in Alternative #2) and specify for each harness which stubs to use using an annotation #[kani::use_stubs(<stub>+)] placed above the harness.
This could be combined with modules, so that a module can be used to group stubs together, and then harnesses could pull in all the stubs in the module:
+#[cfg(kani)]
+mod my_stubs {
+
+ #[kani::stub_of(foo)]
+ fn stub1() { ... }
+
+ #[kani::stub_of(bar)]
+ fn stub2() { ... }
+
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::use_stubs(my_stubs)]
+fn my_harness() { ... }
+The benefit is that stubs are specified per harness, and (using modules) it might be possible to group stubs together. +The downside is that multiple annotations are required and the stub mappings themselves are remote from the harness (at the harness you would know what stub is being used, but not what it is replacing). +There are also several issues that would need to be resolved:
+stub1 to mock foo, and harness B wants to use stub1 to mock bar.)One alternative would be to specify stubs in a file that is passed to kani-driver via a command line option.
+Users would specify per-harness stub pairings in the file; JSON would be a possible format.
+Using a file would eliminate the need for kani-compiler to do an extra pass to extract harness information from the Rust source code before doing code generation; the rest of the implementation would stay the same.
+It would also allow the same harness to be run with different stub selections (by supplying a different file).
+The disadvantage is that the stub selection is remote from the harness itself.
Our approach is based on a MIR-to-MIR transformation.
+Some advantages are that it operates over a relatively simple intermediate representation and rustc has good support for plugging in MIR-to-MIR transformations, so it would not require any changes to rustc itself.
+At this stage of the compiler, names have been fully resolved, and there is no problem with swapping in the body of a function defined in one crate for a function defined in another.
+Another benefit is that it should be possible to extend the compiler to integrate --concrete-playback with the abstractions (although doing so is out of scope for the current proposal).
The major downside with the MIR-to-MIR transformation is that it does not appear to be possible to stub types at that stage (there is no way to change the definition of a type through the MIR). +Thus, our proposed approach will not be a fully general stubbing solution. +However, it is technically feasible and relatively clean, and provides benefits over having no stubbing at all (as can be seen in the examples in the first part of this document).
+Furthermore, it could be used as part of a portfolio of stubbing approaches, where users stub local types using conditional compilation (see Alternative #1), and Kani provides a modified version of the standard library with verification-friendly versions of types like std::vec::Vec.
In this baseline alternative, we do not provide any stubbing mechanism at all.
+Instead, users can effectively stub local code (functions, methods, and types) using conditional compilation.
+For example, they could specify using #[cfg(kani)] to turn off the original definition and turn on the replacement definition when Kani is running, similarly to the ghost state approach taken in the Tokio Bytes proof.
The disadvantage with this approach is that it does not provide any way to stub external code, which is one of the main motivations of our proposed approach.
+In this alternative, we rewrite the source code before it even gets to the compiler. +The advantage with this approach is that it is very flexible, allowing us to stub functions, methods, and types, either by directly replacing them, or appending their replacements and injecting appropriate conditional compilation guards.
+This approach entails less user effort than Alternative #1, but it has the same downside that it requires all source code to be available. +It also might be difficult to inject code in a way that names are correctly resolved (e.g., if the replacement code comes from a different crate). +Also, source code is difficult to work with (e.g., unexpanded macros).
+On the last two points, we might be able to take advantage of an existing source analysis platform like rust-analyzer (which has facilities like structural search replace), but this would add more (potentially fragile) dependencies to Kani.
In this alternative, we implement stubbing by rewriting the AST or High-Level IR (HIR) of the program.
+The HIR is a more compiler-friendly version of the AST; it is what is used for type checking.
+To swap out a function, method, or type at this level, it looks like it would be necessary to add another pass to rustc that takes the initial AST/HIR and produces a new AST/HIR with the appropriate replacements.
The advantage with this approach is, like source transformations, it would be very flexible.
+The downside is that it would require modifying rustc (as far as we know, there is not an API for plugging in a new AST/HIR pass), and would also require performing the transformations at a very syntactic level: although the AST/HIR would likely be easier to work with than source code directly, it is still very close to the source code and not very abstract.
+Furthermore, provided we supported stubbing across crate boundaries, it seems like we would run into a sequencing issue: if we were trying to stub a function in a dependency, we might not know until after we have compiled that dependency that we need to modify its AST/HIR; furthermore, even if we were aware of this, the replacement AST/HIR code would not be available at that time (the AST/HIR is usually just constructed for the crate currently being compiled).
--concrete-playback (for now).It would increase the utility of stubbing if we supported stubs for types. +The source code annotations could likely stay the same, although the underlying technical approach performing these substitutions might be significantly more complex.
+It would probably make sense to provide a library of common stubs for users, since many applications might want to stub the same functions and mock the same behaviors (e.g., rand::random can be replaced with a function returning kani::any).
We could provide special classes of stubs that are likely to come up in practice:
+unreachable: assert the function is unreachable.havoc_locals: return nondeterministic values and assign nondeterministic values to all mutable arguments.havoc: similar to havoc_locals but also assign nondeterministic values to all mutable global variables.uninterpret: treat function as an uninterpreted function.How can we provide a good user experience for accessing private fields of self in methods?
+It is possible to do so using std::mem::transmute (see below); this is clunky and error-prone, and it would be good to provide better support for users.
struct Foo {
+ x: u32,
+}
+
+impl Foo {
+ pub fn m(&self) -> u32 {
+ 0
+ }
+}
+
+struct MockFoo {
+ pub x: u32,
+}
+
+fn mock_m(foo: &Foo) {
+ let mock: &MockFoo = unsafe { std::mem::transmute(foo) };
+ return mock.x;
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::stub(Foo::m, mock_m)]
+fn my_harness() { ... }
+In this example, we mock a serde_json (96M downloads) deserialization method so that we can prove a property about the following Firecracker function that parses a configuration from some raw data:
+fn parse_put_vsock(body: &Body) -> Result<ParsedRequest, Error> {
+ METRICS.put_api_requests.vsock_count.inc();
+ let vsock_cfg = serde_json::from_slice::<VsockDeviceConfig>(body.raw()).map_err(|err| {
+ METRICS.put_api_requests.vsock_fails.inc();
+ err
+ })?;
+
+ // Check for the presence of deprecated `vsock_id` field.
+ let mut deprecation_message = None;
+ if vsock_cfg.vsock_id.is_some() {
+ // vsock_id field in request is deprecated.
+ METRICS.deprecated_api.deprecated_http_api_calls.inc();
+ deprecation_message = Some("PUT /vsock: vsock_id field is deprecated.");
+ }
+
+ // Construct the `ParsedRequest` object.
+ let mut parsed_req = ParsedRequest::new_sync(VmmAction::SetVsockDevice(vsock_cfg));
+ // If `vsock_id` was present, set the deprecation message in `parsing_info`.
+ if let Some(msg) = deprecation_message {
+ parsed_req.parsing_info().append_deprecation_message(msg);
+ }
+
+ Ok(parsed_req)
+}
+We manually mocked some of the Firecracker types with simpler versions to reduce the number of dependencies we had to pull in (e.g., we removed some enum variants, unused struct fields). +With these changes, we were able to prove that the configuration data has a vsock ID if and only if the parsing metadata includes a deprecation message:
+#[cfg(kani)]
+fn get_vsock_device_config(action: RequestAction) -> Option<VsockDeviceConfig> {
+ match action {
+ RequestAction::Sync(vmm_action) => match *vmm_action {
+ VmmAction::SetVsockDevice(dev) => Some(dev),
+ _ => None,
+ },
+ _ => None,
+ }
+}
+
+#[cfg(kani)]
+#[kani::proof]
+#[kani::unwind(2)]
+#[kani::stub(serde_json::deserialize_slice, mock_deserialize)]
+fn test_deprecation_vsock_id_consistent() {
+ // We are going to mock the parsing of this body, so might as well use an empty one.
+ let body: Vec<u8> = Vec::new();
+ if let Ok(res) = parse_put_vsock(&Body::new(body)) {
+ let (action, mut parsing_info) = res.into_parts();
+ let config = get_vsock_device_config(action).unwrap();
+ assert_eq!(
+ config.vsock_id.is_some(),
+ parsing_info.take_deprecation_message().is_some()
+ );
+ }
+}
+Crucially, we did this by stubbing out serde_json::from_slice and replacing it with our mock version below, which ignores its input and creates a "symbolic" configuration struct:
#[cfg(kani)]
+fn symbolic_string(len: usize) -> String {
+ let mut v: Vec<u8> = Vec::with_capacity(len);
+ for _ in 0..len {
+ v.push(kani::any());
+ }
+ unsafe { String::from_utf8_unchecked(v) }
+}
+
+#[cfg(kani)]
+fn mock_deserialize(_data: &[u8]) -> serde_json::Result<VsockDeviceConfig> {
+ const STR_LEN: usize = 1;
+ let vsock_id = if kani::any() {
+ None
+ } else {
+ Some(symbolic_string(STR_LEN))
+ };
+ let guest_cid = kani::any();
+ let uds_path = symbolic_string(STR_LEN);
+ let config = VsockDeviceConfig {
+ vsock_id,
+ guest_cid,
+ uds_path,
+ };
+ Ok(config)
+}
+The proof takes 170 seconds to complete (using Kissat as the backend SAT solver for CBMC).
+ +cover-statement)A new Kani API that allows users to check that a certain condition can occur at a specific location in the code.
+Users typically want to gain confidence that a proof checks what it is supposed to check, i.e. that properties are not passing vacuously due to an over-constrained environment.
+A new Kani macro, cover will be created that can be used for checking that a certain condition can occur at a specific location in the code.
+The purpose of the macro is to verify, for example, that assumptions are not ruling out those conditions, e.g.:
let mut v: Vec<i32> = Vec::new();
+let len: usize = kani::any();
+kani::assume(len < 5);
+for _i in 0..len {
+ v.push(kani::any());
+}
+// make sure we can get a vector of length 5
+kani::cover!(v.len() == 5);
+This is typically used to ensure that verified checks are not passing vacuously, e.g. due to overconstrained pre-conditions.
+The special case of verifying that a certain line of code is reachable can be achieved using kani::cover!() (which is equivalent to cover!(true)), e.g.
match x {
+ val_1 => ...,
+ val_2 => ...,
+ ...
+ val_i => kani::cover!(), // verify that `x` can take the value `val_i`
+}
+Similar to Rust's assert macro, a custom message can be specified, e.g.
kani::cover!(x > y, "x can be greater than y");
+The cover macro instructs Kani to find at least one possible execution that satisfies the specified condition at that line of code. If no such execution is possible, the check is reported as unsatisfiable.
Each cover statement will be reported as a check whose description is cover condition: cond and whose status is:
SATISFIED (green): if Kani found an execution that satisfies the condition.UNSATISFIABLE (yellow): if Kani proved that the condition cannot be satisfied.UNREACHABLE (yellow): if Kani proved that the cover statement itself cannot be reached.For example, for the following cover statement:
kani::cover!(a == 0);
+An example result is:
+Check 2: main.cover.2
+ - Status: SATISFIED
+ - Description: "cover condition: a == 0"
+ - Location: foo.rs:9:5 in function main
+By default, unsatisfiable and unreachable cover checks will not impact verification success or failure.
+This is to avoid getting verification failure for harnesses for which a cover check is not relevant.
+For example, on the following program, verification should not fail for another_harness_that_doesnt_call_foo because the cover statement in foo is unreachable from it.
[kani::proof]
+fn a_harness_that_calls_foo() {
+ foo();
+}
+
+#[kani::proof]
+fn another_harness_that_doesnt_call_foo() {
+ // ...
+}
+
+fn foo() {
+ kani::cover!( /* some condition */);
+}
+The --fail-uncoverable option will allow users to fail the verification if a cover property is unsatisfiable or unreachable.
+This option will be integrated within the framework of Global Conditions, which is used to define properties that depend on other properties.
Using the --fail-uncoverable option will enable the global condition with name fail_uncoverable.
+Following the format for global conditions, the outcome will be one of the following:
- fail_uncoverable: FAILURE (expected all cover statements to be satisfied, but at least one was not) - fail_uncoverable: SUCCESS (all cover statements were satisfied as expected)Note that the criteria to achieve a SUCCESS status depends on all properties of the "cover" class having a SATISFIED status.
+Otherwise, we return a FAILURE status.
Cover checks will be reported separately in the verification summary, e.g.
+SUMMARY:
+ ** 1 of 206 failed (2 unreachable)
+ Failed Checks: assertion failed: x[0] == x[1]
+
+ ** 30 of 35 cover statements satisfied (1 unreachable) <--- NEW
+In this example, 5 of the 35 cover statements were found to be unsatisfiable, and one of those 5 is additionally unreachable.
+If one or more unwinding assertions fail or an unsupported construct is found to be reachable (which indicate an incomplete path exploration), and Kani found the condition to be unsatisfiable or unreachable, the result will be reported as UNDETERMINED.
The implementation will touch the following components:
+cover macro will be added there along with a cover function with a rustc_diagnostic_itemkani-compiler: The cover function will be handled via a hook and codegen as two assertions (cover(cond) will be codegen as __CPROVER_assert(false); __CPROVER_assert(!cond)).
+The purpose of the __CPROVER_assert(false) is to determine whether the cover statement is reachable.
+If it is, the second __CPROVER_assert(!cond) indicates whether the condition is satisfiable or not.kani-driver: The CBMC output parser will extract cover properties through their property class, and their result will be set based on the result of the two assertions:
+FAILURE (UNREACHABLE)FAILURE to indicate that the condition is unsatisfiableSUCCESS to indicate that the condition is satisfiableWhat are the pros and cons of this design?
+CBMC has its own cover API (__CPROVER_cover), for which SUCCESS is reported if an execution is found, and FAILURE is reported otherwise.
+However, using this API currently requires running CBMC in a separate "cover" mode.
+Having to run CBMC in that mode would complicate the Kani driver as it will have to perform two CBMC runs, and then combine their results into a single report.
+Thus, the advantage of the proposed design is that it keeps the Kani driver simple.
+In addition, the proposed solution does not depend on a feature in the backend, and thus will continue to work if we were to integrate a different backend.
What is the impact of not doing this?
+The current workaround to accomplish the same effect of verifying that a condition can be covered is to use assert!(!cond).
+However, if the condition can indeed be covered, verification would fail due to the failure of the assertion.
kani::cover!(x > y, "{} can be greater than {}", x, y)?
+Users may expect this to be supported since the macro looks similar to the assert macro, but Kani doesn't include the formatted string in the message description, since it's not available at compile time.~
+We need to make sure the concrete playback feature can be used with cover statements that were found to be coverable.
The new cover API subsumes the current kani::expect_fail function.
+Once it's implemented, we should be able to get rid of expect_fail, and all the related code in compiletest that handles the EXPECTED FAILURE message in a special manner.
loop-contract-synthesis)A new option that allows users to verify programs without unwinding loops by synthesizing loop contracts for those loops.
+Currently Kani does not support verification on programs with unbounded control flow (e.g. loops with dynamic bounds). +Kani unrolls all unbounded loops until a global threshold (unwinding number) specified by the user and then verifies this unrolled program, which limits the set of programs it can verify.
+A new Kani flag --synthesize-loop-contracts will be created that can be used to enable the goto-level loop-contract synthesizer goto-synthesizer.
+The idea of loop contracts is, instead of unwinding loops, we abstract those loops as non-loop structures that can cover arbitrary iterations of the loops.
+The loop contract synthesizer, when enabled, will attempt to synthesize loop contracts for all loops.
+CBMC can then apply the synthesized loop contracts and verify the program without unwinding any loop.
+So, the synthesizer will help to verify the programs that require Kani to unwind loops for a very large number of times to cover all iterations.
For example, the number of executed iterations of the loop in the following harness is dynamically bounded by an unbounded variable y 1.
+Only an unwinding value of i32::MAX can guarantee to cover all iterations of the loop, and hence satisfy the unwinding assertions.
+Unwinding the loop an i32::MAX number of times will result in a too large goto program to be verified by CBMC.
#[kani::proof]
+fn main() {
+ let mut y: i32 = kani::any_where(|i| *i > 0);
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+With the loop-contract synthesizer, Kani can synthesize the loop invariant y >= 0, with which it can prove the post-condition y == 0 without unwinding the loop.
Also, loop contracts could improve Kani’s verification time since all loops will be abstracted to a single iteration, as opposed to being unwound a large number of iterations.
+For example, we can easily find out that the following loop is bounded by an unwinding value of 5000.
+Kani can verify the program in a few minutes by unwinding the loop 5000 times.
+With loop contracts, we only need to verify the single abstract iteration of the loop, which leads to a smaller query.
+As a result, Kani with the synthesizer can verify the program in a few seconds.
#[kani::proof]
+#[kani::unwind(5000)]
+fn main() {
+ let mut y: i32 = 5000;
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+The goto-synthesizer is an enumeration-based synthesizer.
+It enumerates candidate invariants from a pre-designed search space described by a given regular tree grammar and verifies if the candidate is an inductive invariant.
+Therefore it has the following limitations:
a[i] == 0 contains an array access and cannot be captured by the current search space.
+However, we can easily extend the search space to include more complex expressions with the cost of an exponential increase of the running time of the synthesizer.Users will be able to use the new command-line flag --synthesize-loop-contracts to run the synthesizer, which will attempt to synthesize loop contracts, and verify programs with the synthesized loop contracts.
Without a resource limit, an enumerative synthesizer may run forever to exhaust a search space consisting of an infinite number of candidates, especially when there is no solution in the search space.
+So, for the guarantee of termination, we provide users options: --limit-synthesis-time T to limit the running time of the synthesizer to be less than T seconds.
When the flag --synthesize-loop-contracts is provided, Kani will report different result for different cases
UNDETERMINED instead of FAILED.A question about how do we print the synthesized loop contracts when users request is discussed in Open question.
+The synthesizer goto-synthesizer is implemented in the repository of CBMC, takes as input a goto binary, and outputs a new goto binary with the synthesized loop contracts applied.
+Currently, Kani invokes goto-instrument to instrument the goto binary main.goto into a new goto binary main_instrumented.goto, and then invokes cbmc on main_instrumented.goto to get the verification result.
+The synthesis will happen between calling goto-instrument and calling cbmc.
+That is, we invoke goto-synthesizer on main_instrumented.goto to produce a new goto binary main_synthesized.goto, and then call cbmc on main_synthesized.goto instead.
When invoking goto-synthesizer, we pass the following parameters to it with the flags built in goto-synthesizer:
The enumerator used in the synthesizer enumerates candidates from the language of the following grammar template.
+NT_Bool -> NT_Bool && NT_Bool | NT_int == NT_int
+ | NT_int <= NT_int | NT_int < NT_int
+ | SAME_OBJECT(terminals_ptr, terminals_ptr)
+
+NT_int -> NT_int + NT_int | terminals_int | LOOP_ENTRY(terminals_int)
+ | POINTER_OFFSET(terminals_ptr) | OBJECT_SIZE(terminals_ptr)
+ | POINTER_OFFSET(LOOP_ENTRY(terminals_ptr)) | 1
+where terminals_ptr are all pointer variables in the scope, and terminal_int are all integer variables in the scope.
+For every candidate invariant, goto-synthesizer applies it to the GOTO program and runs CBMC to verify the program.
goto-synthesizer returns it as a solution.goto-synthesizer returns the conjunction of all inductive clauses as the best-effort-synthesized loop contracts.We use the following example to illustrate how the synthesizer works.
+#[kani::proof]
+fn main() {
+ let mut y: i32 = kani::any_where(|i| *i > 0);
+
+ while y > 0 {
+ y = y - 1;
+ }
+ assert!(y == 0);
+}
+As there is only one variable y in the scope, the grammar template above will be instantiated to the following grammar
NT_Bool -> NT_Bool && NT_Bool | NT_int == NT_int
+ | NT_int <= NT_int | NT_int < NT_int
+NT_int -> NT_int + NT_int | y | LOOP_ENTRY(y) | 1
+The synthesizer will enumerate candidates derived from NT_Bool in the following order.
y == y
+y == LOOP_ENTRY(y)
+y == 1
+...
+1 <= y + 1
+...
+The synthesizer then verifies with CBMC if the candidate is an inductive invariant that can be used to prove the post-condition y == 0.
+For example, the candidate y == y is verified to be an inductive invariant, but cannot be used to prove the post-condition y == 0.
+The candidate y == 1 is not inductive.
+The synthesizer rejects all candidates until it finds the candidate 1 <= y + 1, which can be simplified to y >= 0.
+y >= 0 is an inductive invariant that can be used to prove the post-condition.
+So the synthesizer will return y >= 0 and apply it to the goto model to get main_synthesized.goto.
For assign clauses, the synthesizer will first use alias analysis to determine an initial set of assign targets. +During the following iteration, if any assignable-check is violated, the synthesizer will extract the assign target from the violated check.
+Then Kani will call cbmc on main_synthesized.goto to verify the program with the synthesized loop contracts.
goto-instrument, but probably not enough for other user-written checks.
+We may want to include array-indexing, pointer-dereference, or other arithmetic operators in the candidate grammar for synthesizing a larger set of loop invariants.
+However, there is a trade-off between the size of candidate we enumerate and the running time of the enumeration.
+We will collect more data to decide what operators we should include in the candidate grammar.
+Once we decide more kinds of candidate grammars, we will provide users options to choose which candidate grammar they want to use.How does the synthesizer work with unwinding numbers? +There may exist some loops for which the synthesizer cannot find loop contracts, but some small unwinding numbers are enough to cover all executions of the loops. +In this case, we may want to unwind some loops in the program while synthesizing loop contracts for other loops. +It requires us to have a way to identify and specify which loops we want to unwind.
+In C programs, we identify loops by the loop ID, which is a pair (function name, loop number).
+However, in Rust programs, loops are usually in library functions such as Iterator::for_each.
+And a library function may be called from different places in the program.
+We may want to unwind the loop in some calls but not in other calls.
How do we output the synthesized loop contracts?
+To better earn users' trust, we want to be able to report what loop contracts we synthesized and used to verify the given programs.
+Now goto-synthesizer can dump the synthesized loop contracts into a JSON file.
+Here is an example of the dumped loop contracts.
+It contains the location of source files of the loops, the synthesized invariant clauses and assign clauses for loops identified by loop numbers.
{
+ "sources": [ "/Users/qinhh/Repos/playground/kani/synthesis/base_2/test.rs" ],
+ "functions": [
+ {
+ "main": [ "loop 1 invariant y >= 0",
+ "loop 1 assigns var_9,var_10,var_11,x,y,var_12" ]
+ }
+ ],
+ "output": "stdout"
+}
+There are two challenges here if we want to also dump synthesized loop contracts in Kani.
+rust instead of c.var_9, var_10, var_11, and var_12 in the above JSON file.
+We need to translate them back to the original variables they represent.User-provided loop contracts. +If we have a good answer for how to identify loops and dump synthesized loop contracts, we could probably also allow users to provide the loop contracts they wrote to Kani, and verify programs with user-provided loop contracts.
+When users want to unwind some loops, we can also introduce macros to enable/disable unwinding for certain block of code.
+#[kani::proof]
+#[kani::unwind(10)]
+fn check() {
+ // unwinding starts as enabled, so all loops in this code block will be unwound to 10
+ #[kani::disable_unwinding]
+ // unwinding is disabled for all loops in this block of code
+ #[kani::enable_unwinding]
+ // it is enabled in this block of code until the end of the program
+}
+Invariant caching. +The loop invariant could be broken when users modify their code. +However, we could probably cache previously working loop invariants and attempt to reuse them when users modify their code. +Even if the cached loop invariants are not enough to prove the post-condition, they could still be used as a starting point for the synthesizer to find new loop invariants.
+We say an integer variable is unbounded if there is no other bound on its value besides the width of its bit-vector representation.
+kani::should_panic attribute (should-panic-attr)Users may want to express that a verification harness should panic.
+This RFC proposes a new harness attribute #[kani::should_panic] that informs Kani about this expectation.
Users may want to express that a verification harness should panic. +In general, a user adding such a harness wants to demonstrate that the verification fails because a panic is reachable from the harness.
+Let's refer to this concept as negative verification,
+so the relation with negative testing becomes clearer.
+Negative testing can be exercised in Rust unit tests using the #[should_panic] attribute.
+If the #[should_panic] attribute is added to a test, cargo test will check that the execution of the test results in a panic.
+This capability doesn't exist in Kani at the moment, but it would be useful for the same reasons
+(e.g., to show that invalid inputs result in verification failures, or increase the overall verification coverage).
We propose an attribute that allows users to exercise negative verification in Kani.
+We also acknowledge that, in other cases, users may want to express more granular expectations for their harnesses. +For example, a user may want to specify that a given check is unreachable from the harness. +An ergonomic mechanism for informing Kani about such expectations is likely to require other improvements in Kani (a comprehensive classification for checks reported by Kani, a language to describe expectations for checks and cover statements, and general output improvements). +Moving forward, we consider that such a mechanism and this proposal solve different problems, so they don't need to be discussed together. +This is further discussed in the rationale and alternatives and future possibilities sections.
+The scope of this functionality is limited to the overall verification result. +The rationale section discusses the granularity of failures, and how this attribute could be extended.
+Let's look at this code:
+struct Device {
+ is_init: bool,
+}
+
+impl Device {
+ fn new() -> Self {
+ Device { is_init: false }
+ }
+
+ fn init(&mut self) {
+ assert!(!self.is_init);
+ self.is_init = true;
+ }
+}
+
+#[kani::proof]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+This is what a negative harness may look like.
+The user wants to verify that calling device.init() more than once should result in a panic.
++NOTE: We could convert this into a Rust unit test and add the
+#[should_panic]attribute to it. +However, there are a few good reasons to have a verification-specific attribute that does the same:+
+- To ensure that other unexpected behaviors don't occur (e.g., overflows).
+- Because
+#[should_panic]cannot be used if the test harness contains calls to Kani's API.- To ensure that a panic still occurs after stubbing out code which is expected to panic.
+
Currently, this example produces a VERIFICATION:- FAILED result.
+In addition, it will return a non-successful code.
#[kani::proof]
+#[kani::should_panic]
+fn cannot_init_device_twice() {
+ let mut device = Device::new();
+ device.init();
+ device.init();
+}
+Since we added #[kani::should_panic], running this example would produce a successful code.
Now, we've considered two ways to represent this result in the verification output. +Note that it's important that we provide the user with this feedback:
+Therefore, the representation must make clear both the expectation and the outcome. +Below, we show how we'll represent this result.
+The #[kani::should_panic] attribute essentially behaves as a property that depends on other properties.
+This makes it well-suited for integration within the framework of Global Conditions.
Using the #[kani::should_panic] attribute will enable the global condition with name should_panic.
+Following the format for global conditions, the outcome will be one of the following:
- `should_panic`: FAILURE (encountered no panics, but at least one was expected) if there were no failures. - `should_panic`: FAILURE (encountered failures other than panics, which were unexpected) if there were failures but not all them had prop.property_class() == "assertion". - `should_panic`: SUCCESS (encountered one or more panics as expected) otherwise.Note that the criteria to achieve a SUCCESS status depends on all failed properties having the property class "assertion".
+If they don't, then the failed properties may contain UB, so we return a FAILURE status instead.
When there are multiple harnesses, we'll implement the single-harness changes in addition to the following ones. +Currently, a "Summary" section appears1 after reporting the results for each harness:
+Verification failed for - harness3
+Verification failed for - harness2
+Verification failed for - harness1
+Complete - 0 successfully verified harnesses, 3 failures, 3 total.
+Harnesses marked with #[kani::should_panic] won't show unless the expected result was different from the actual result.
+The summary will consider harnesses that match their expectation as "successfully verified harnesses".
Therefore, if we added #[kani::should_panic] to all harnesses in the previous example, we'd see this output:
Complete - 3 successfully verified harnesses, 0 failures, 3 total.
+In a verification context, an execution can branch into multiple executions that depend on a condition. +This may result in a situation where different panics are reachable, as in this example:
+#[kani::proof]
+#[kani::should_panic]
+fn branch_panics() {
+ let b: bool = kani::any();
+
+ do_something();
+
+ if b {
+ call_panic_1(); // leads to a panic-related failure
+ } else {
+ call_panic_2(); // leads to a different panic-related failure
+ }
+}
+Note that we could safeguard against these situations by checking that only one panic-related failure is reachable.
+However, users have expressed that a coarse version (i.e., checking that at least one panic can be reached) is preferred.
+Users also anticipate that #[kani::should_panic] will be used to exercise smoke testing in many cases.
+Additionally, restricting #[kani::should_panic] to the verification of single panic-related failures could be confusing for users and reduce its overall usefulness.
This feature will only be available as an attribute.
+That means this feature won't be available as a CLI option (i.e., --should-panic).
+There are good reasons to avoid the CLI option:
--harness to filter negative harnesses.The #[kani::should_panic] attribute will become one of the most basic attributes in Kani.
+As such, it'll be mentioned in the tutorial and added to the dedicated section planned in #2208.
In general, we'll also advise against negative verification when a harness can be written both as a regular (positive) harness and a negative one. +The feature, as it's presented in this proposal, won't allow checking that the panic failure is due to the panic we expected. +So there could be cases where the panic changes, but it goes unnoticed while running Kani. +Because of that, it'll preferred that users write positive harnesses instead.
+At a high level, we expect modifications in the following components:
+kani-compiler: Changes required to (1) process the new attribute, and (2) extend HarnessMetadata with a should_panic: bool field.kani-driver: Changes required to (1) edit information about harnesses printed by kani-driver, (2) edit verification output when post-processing CBMC verification results, and (3) return the appropriate exit status after post-processing CBMC verification results.We don't expect these changes to require new dependencies. +Besides, we don't expect these changes to be updated unless we decide to extend the attribute with further fields (see Future possibilities for more details).
+This proposal would enable users to exercise negative verification with a relatively simple mechanism. +Not adding such a mechanism could impact Kani's usability by limiting the harnesses that users can write.
+This proposal doesn't consider generic failures but only panics. +In principle, it's not clear that a mechanism for generic failures would be useful. +Such a mechanism would allow users to expect UB in their harness, but there isn't a clear motivation for doing that.
+We have considered two alternatives for the "expectation" part of the attribute's name: should and expect.
+We avoid expect altogether for two reasons:
expected argument to #[kani::should_panic].#[kani::expect].expected mode, which works with *.expected files. Other modes also use such files.expected argumentWe could consider an expected argument, similar to the #[should_panic] attribute.
+To be clear, the #[should_panic] attribute may receive an argument expected which allows users to specify the expected panic string:
#[test]
+ #[should_panic(expected = "Divide result is zero")]
+ fn test_specific_panic() {
+ divide_non_zero_result(1, 10);
+ }
+In principle, we anticipate that we'll extend this proposal to include the expected argument at some point.
+The implementation could compare the expected string against the panic string.
At present, the only technical limitation is that panic strings printed in Kani aren't formatted.
+One option is to use substrings to compare.
+However, the long-term solution is to use concrete playback to replay the panic and match against the expected panic string.
+By doing this, we would achieve feature parity with Rust's #[should_panic].
As mentioned earlier, users may want to express more granular expectations for their harnesses.
+There could be problems with this proposal if we attempt to do both:
+We don't have sufficient data about the use-case considered in this alternative. +This proposal can also contribute to collect this data: once users can expect panics, they may want to expect other things.
+This functionality could be part of the Kani API instead of being an attribute. +For example, some contributors proposed a function that takes a predicate closure to filter executions and check that they result in a panic.
+However, such a function couldn't be used in external code, limiting its usability to the user's code.
+Once the feature is available, it'd be good to gather user feedback to answer these questions:
+#[kani::should_panic] with an expected field? Yes, but not in this version.#[kani::should_panic]? Yes (this is now discussed in User Experience).kani::proof (#[kani::proof(should_panic)] reads very well).expected argument to #[kani::should_panic], and replay the harness with concrete playback to get the actual panic string.Double negation may not be the best representation, but it's at least accurate with respect to the original result.
+This summary is printed in both the default and terse outputs.
+unstable-api)Provide a standard option for users to enable experimental APIs and features in Kani, +and ensure that those APIs are off by default.
+Add an opt-in model for users to try experimental APIs. +The goal is to enable users to try features that aren't stable yet, +which allow us to get valuable feedback during the development of new features and APIs.
+The opt-in model empowers the users to control when some instability is acceptable, +which makes Kani UX more consistent and safe.
+Currently, each new unstable feature will introduce a new switch, some of them will look like --enable-<feature>,
+while others will be a plain switch which allows further feature configuration --<feature-config>=[value].
+For example, we today have the following unstable switches --enable-stubbing, --concrete-playback, --gen-c.
+In all cases, users are still required to provide the additional --enable-unstable option.
+Some unstable features are included in the --help section, and only a few mention the requirement
+to include --enable-unstable. There is no way to list all unstable features.
+The transition to stable switches is also ad-hoc.
In order to reduce friction, we will also standardize how users opt-in to any Kani unstable feature.
+We will use similar syntax to the one used by the Rust compiler and Cargo.
+As part of this work, we will also deprecate and remove --enable-unstable option.
Note that although Kani is still on v0, which means that everything is somewhat unstable, +this allow us to set different bars when it comes to what kind of changes is expected, +as well as what kind of support we will provide for a feature.
+Users will have to invoke Kani with:
+-Z <feature_identifier>
+in order to enable any unstable feature in Kani, including unstable APIs in the Kani library.
+For unstable command line options, we will add -Z unstable-options, similar to the Rust compiler.
+E.g.:
-Z unstable-options --concrete-playback=print
+Users will also be able to enable unstable features in their Cargo.toml in the unstable table
+under kani table. E.g:
[package.metadata.kani.unstable]
+unstable-options = true
+
+[workspace.metadata.kani]
+flags = { concrete-playback = true }
+unstable = { unstable-options = true }
+In order to mark an API as unstable, we will add the following attribute to the APIs marked as unstable:
+#[kani::unstable(feature="<IDENTIFIER>", issue="<TRACKING_ISSUE_NUMBER>", reason="<DESCRIPTION>")]
+pub fn unstable_api() {}
+This is similar to the interface used by the standard library.
+If the user tries to use an unstable feature in Kani without explicitly enabling it, +Kani will trigger an error. For unstable APIs, the error will be triggered during the crate +compilation.
+We will add the -Z option to both kani-driver and kani-compiler.
+Kani driver will pass the information to the compiler.
For unstable APIs, the compiler will check if any reachable function uses an unstable feature that was not enabled. +If that is the case, the compiler will trigger a compilation error.
+We will also change the compiler to only generate code for harnesses that match the harness filter. +The filter is already passed to the compiler, but it is currently only used for stubbing.
+Once an API has been stabilized, we will remove the unstable attributes from the given API.
+If the user tries to enable a feature that was already stabilized,
+Kani will print a warning stating that the feature has been stabilized.
If we decide to remove an API that is marked as unstable, we should follow a regular deprecation
+path (using #[deprecated] attribute), and keep the unstable flag + attributes, until we are
+ready to remove the feature completely.
For this RFC, the suggestion is to only enable experimental features globally for simplicity of use and implementation.
+For now, we will trigger a compilation error if an unstable API is reachable from a user crate +unless if the user opts in for the unstable feature.
+We could allow users to specify experimental features on a per-harness basis, +but it could be tricky to make it clear to the user which harness may be affected by which feature. +The extra granularity would also be painful when we decide a feature is no longer experimental, +whether it is stabilized or removed. +In those cases, users would have to edit each harness that enables the affected feature.
+stable attribute that documents when an API was stabilized?global-conditions)A new section in Kani's output to summarize the status of properties that depend on other properties. We use the term global conditions to refer to such properties.
+The addition of new options that affect the overall verification result depending on certain property attributes demands some consideration.
+In particular, the addition of a new option to fail verification if there are uncoverable (i.e., unsatisfiable or unreachable) cover properties (requested in #2299) is posing new challenges to our current architecture and UI.
This concept isn't made explicit in Kani, but exists in some ways.
+For example, the kani::should_panic attribute is a global condition because it can be described in terms of other properties (checks).
+The request in #2299 is essentially another global conditions, and we may expect more to be requested in the future.
In this RFC, we propose a new section in Kani's output focused on reporting global conditions. +The goal is for users to receive useful information about hyperproperties without it becoming overwhelming. +This will help users to understand better options that are enabled through global conditions and ease the addition of such options to Kani.
+The output will refer to properties that depend on other properties as "global conditions", which is a simpler term. +The options to enable different global conditions will depend on a case-by-case basis1.
+The main UI change in this proposal is a new GLOBAL CONDITIONS section that won't be printed if no global conditions have been enabled.
+This section will only appear in Kani's default output after the RESULTS section (used for individual checks) and have the format:
GLOBAL CONDITIONS:
+ - `<name>`: <status> (<reason>)
+ - `<name>`: <status> (<reason>)
+ [...]
+where:
+<name> is the name given to the global condition.<status> is the status determined for the global condition.<reason> is an explanation that depends on the status of the global condition.For example, let's assume we implement the option requested in #2299. +A concrete example of this output would be:
+GLOBAL CONDITIONS:
+ - `fail_uncoverable`: SUCCESS (all cover statements were satisfied as expected)
+A FAILED status in any enabled global condition will cause verification to fail.
+In that case, the overall verification result will point out that one or more global conditions failed, as in:
VERIFICATION:- FAILURE (one or more global conditions failed)
+This last UI change will also be implemented for the terse output. +Finally, checks that cause an enabled global condition to fail will be reported using the same interface we use for failed checks2.
+Global conditions which aren't enabled won't appear in the GLOBAL CONDITIONS section.
+Their status will be computed regardless3, and we may consider showing this status when the --verbose option is passed.
The documentation of global conditions will depend on how they're enabled, which depends on a case-by-case basis.
+However, we may consider adding a new subsection Global conditions to the Reference section that collects all of them so it's easier for users to consult all of them in one place.
The only component to be modified is kani-driver since that's where verification results are built and determined.
+But we should consider moving this logic into another crate.
We don't need new dependencies. +The corner cases will depend on the specific global conditions to be implemented.
+As mentioned earlier, we're proposing this change to help users understand global conditions and how they're determined.
+In many cases, global conditions empower users to write harnesses which weren't possible to write before.
+As an example, the #[kani::should_panic] attribute allowed users to write harnesses expecting panic-related failures.
Also, we don't really know if more global conditions will be requested in the future. +We may consider discarding this proposal and waiting for the next feature that can be implemented as a global condition to be requested.
+One option we've considered in the past is to enable global conditions as a regular checks. +While it's technically doable, it doesn't feel appropriate for global conditions to reported through regular checks since generally a higher degree of visibility may be appreciated.
+No open questions.
+A redesign of Kani's output is likely to change the style/architecture to report global conditions.
+The results for global conditions would be computed during postprocessing based on the results of other checks. +Global conditions' checks aren't part of the SAT, therefore this computation won't impact verification time.
+We do not discuss the specific interface to report the failed checks because it needs improvements (for both global conditions and standard verification).
+In particular, the description field is the only information printed for properties (such as cover statements) without trace locations.
+There are additional improvements we should consider: printing the actual status (for global conditions, this won't always be FAILED), avoid the repetition of Failed Checks: , etc.
+This comment discusses problems with the current interface on some examples.
In other words, global conditions won't force a specific mechanism to be enabled.
+For example, if the #[kani::should_panic] attribute is converted into a global condition, it will continue to be enabled through the attribute itself.
+Other global conditions may be enabled through CLI flags only (e.g., --fail-uncoverable), or a combination of options in general.
line-coverage)Add verification-based line coverage reports to Kani.
+Nowadays, users can't easily obtain verification-based coverage reports in Kani. +Generally speaking, coverage reports show which parts of the code under verification are covered and which are not. +Because of that, coverage is often seen as a great metric to determine the quality of a verification effort.
+Moreover, some users prefer using coverage information for harness development and debugging. +That's because coverage information provides users with more familiar way to interpret verification results.
+This RFC proposes adding a new option for verification-based line coverage reports to Kani. +As mentioned earlier, we expect users to employ this coverage-related option on several stages of a verification effort:
+Moreover, adding this option directly to Kani, instead of relying on another tools, is likely to:
+Which translates into faster and more reliable coverage options for users.
+The goal is for Kani to generate code coverage report per harness in a well established format, such as LCOV, and possibly a summary in the output. +For now, we will focus on an interim solution that will enable us to assess the results of our instrumentation and enable integration with the Kani VS Code extension.
+For the first version, this experimental feature will report verification results along coverage reports.
+Because of that, we'll add a new section Coverage results that shows coverage results for each individual harness.
In the following, we describe an experimental output format. +Note that the final output format and overall UX is to be determined.
+The Coverage results section for each harness will produce coverage information in a CSV format as follows:
<file>, <line>, <status>
+where <status> is either FULL, PARTIAL or NONE.
As mentioned, this format is designed for evaluating the native instrumentation-based design and is likely to be substituted with another well-established format as soon as possible.
+Users are not expected to consume this output directly. +Instead, coverage data is to be consumed by the Kani VS Code extension and displayed as in the VS Code Extension prototype.
+How to activate and display coverage information in the extension is out of scope for this RFC. +That said, a proof-of-concept implementation is available here.
+We will add a new unstable --coverage verification option to Kani which will require -Z line-coverage until this feature is stabilized.
+We will also add a new --coverage-checks option to kani-compiler, which will result in the injection of coverage checks before each Rust statement and terminator1.
+This option will be supplied by kani-driver when the --coverage option is selected.
+These options will cause Kani to inject coverage checks during compilation and postprocess them to produce the coverage results sections described earlier.
Coverage checks are a new class of checks similar to cover checks.
+The main difference is that users cannot directly interact with coverage checks (i.e., they cannot add or remove them manually).
+Coverage checks are encoded as an assert(false) statement (to test reachability) with a fixed description.
+In addition, coverage checks are:
In the following, we describe the injection and postprocessing procedures to generate coverage results.
+The injection of coverage checks will be done while generating code for basic blocks. +This allows us to add one coverage check before each statement and terminator, which provides the most accurate results1. +It's not completely clear how this compares to the coverage instrumentation done in the Rust compiler, but an exploration to use the compiler APIs revealed that they're quite similar2.
+The injection of coverage checks often results in one or more checks per line (assuming a well-formatted program). +We'll postprocess these checks so for each line
+SATISFIED: return FULLUNSATISFIED: return NONEPARTIALWe won't report coverage status for lines which don't include a coverage check.
+Kani has relied on cbmc-viewer to report coverage information since the beginning.
+In essence, cbmc-viewer consumes data from coverage-focused invocations of CBMC and produces an HTML report containing (1) coverage information and (2) counterexample traces.
+Recently, there have been some issues with the coverage information reported by cbmc-viewer (e.g., #2048 or #1707), forcing us to mark the --visualize option as unstable and disable coverage results in the reports (in #2206).
However, it's possible for Kani to report coverage information without cbmc-viewer, as explained before.
+This would give Kani control on both ends:
cbmc-viewer's output, development is likely to be faster this way.cbmc-viewerAs an alternative, we could fix and use cbmc-viewer to report line coverage.
Most of the issues with cbmc-viewer are generally due to:
--cover <option>) in CBMC.cbmc-viewer.Note that (1) is not exclusive to coverage results from cbmc-viewer.
+Finding checks with missing locations and propagating them if possible (as suggested in this comment) should be done regardless of the approach used for line coverage reports.
In contrast, (2) and (3) can be considered the main problems for Kani contributors to develop coverage options on top of cbmc-viewer and CBMC.
+It's not clear how much effort this would involve, but (3) is likely to require substantial documentation contributions.
+But (4) shouldn't be an issue if we decided to invest in cbmc-viewer.
Finally, the following downside must be considered:
+cbmc-viewer can report line coverage but the path to report region-based coverage may involve a complete rewrite.
One of the long-term goals for this feature is to provide a UX that is familiar for users. +This is particularly relevant when talking about output formats. +Some services and frameworks working with certain coverage output formats have become quite popular.
+However, this version doesn't consider common output formats (i.e., GCOV or LCOV) since coverage results will only be consumed by the Kani VS Code Extension at first. +But other output formats will be considered in the future.
+Open questions:
+COVERED/UNCOVERED or FULL/PARTIAL/NONE?Feedback to gather before stabilization:
+We expect many incremental improvements in the coverage area:
+We have experimented with different options for injecting coverage checks. +For example, we have tried injecting one before each basic block, or one before each statement, etc. +The proposed option (one before each statement AND each terminator) gives us the most accurate results.
+In particular, comments in CoverageSpan and generate_coverage_spans hint that the initial set of spans come from Statements and Terminators. This comment goes in detail about the attempt to use the compiler APIs.
-Zfunction-contracts, enforced by compile time error1Function contracts are a means to specify and check function behavior. On top of +that the specification can then be used as a sound2 +abstraction to replace the concrete implementation, similar to stubbing.
+This allows for a modular verification.
+ +Function contracts provide an interface for a verified, +sound2 function abstraction. This is similar to stubbing +but with verification of the abstraction instead of blind trust. This allows for +modular verification, which paves the way for the following two ambitious goals.
+Function contracts are completely optional with no user impact if unused. This +RFC proposes the addition of new attributes, and functions, that shouldn't +interfere with existing functionalities.
+A function contract specifies the behavior of a function as a predicate that +can be checked against the function implementation and also used as an +abstraction of the implementation at the call sites.
+The lifecycle of a contract is split into three phases: specification, +verification and call abstraction, which we will explore on this example:
+fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}
+In the first phase we specify the contract. Kani provides two new
+annotations: requires (preconditions) to describe the expectations this
+function has as to the calling context and ensures (postconditions) which
+approximates function outputs in terms of function inputs.
#[kani::requires(divisor != 0)]
+#[kani::ensures(result <= dividend)]
+fn my_div(dividend: u32, divisor: u32) -> u32 {
+ dividend / divisor
+}
+requires here indicates this function expects its divisor input to never
+be 0, or it will not execute correctly (for instance panic or cause undefined
+behavior).
ensures puts a bound on the output, relative to the dividend input.
Conditions in contracts are Rust expressions which reference the
+function arguments and, in case of ensures, the return value of the
+function. The return value is a special variable called result (see open
+questions on a discussion about (re)naming). Syntactically
+Kani supports any Rust expression, including function calls, defining types
+etc. However they must be side-effect free (see also side effects
+here) or Kani will throw a compile error.
Multiple requires and ensures clauses are allowed on the same function,
+they are implicitly logically conjoined.
Next, Kani ensures that the function implementation respects all the conditions specified in its contract.
+To perform this check Kani needs a suitable harness to verify the function
+in. The harness is mainly responsible for providing the function arguments
+but also set up a valid heap that pointers may refer to and properly
+initialize static variables.
Kani demands of us, as the user, to provide this harness; a limitation of +this proposal. See also future possibilities for a +discussion about the arising soundness issues and their remedies.
+Harnesses for checking contract are defined with the
+proof_for_contract(TARGET) attribute which references TARGET, the
+function for which the contract is supposed to be checked.
#[kani::proof_for_contract(my_div)]
+fn my_div_harness() {
+ my_div(kani::any(), kani::any())
+}
+Similar to a verification harness for any other function, we are supposed to
+create all possible input combinations the function can encounter, then call
+the function at least once with those abstract inputs. If we forget to call
+my_div Kani reports an error. Unlike other harnesses we only need to create
+suitable data structures but we don't need to add any checks as Kani will
+use the conditions we specified in the contract.
Kani inserts preconditions (requires) as kani::assume before the call
+to my_div, limiting inputs to those the function is actually defined for.
+It inserts postconditions (ensures) as kani::assert checks after the
+call to my_div, enforcing the contract.
The expanded version of our harness that Kani generates looks roughly like +this:
+#[kani::proof]
+fn my_div_harness() {
+ let dividend = kani::any();
+ let divisor = kani::any();
+ kani::assume(divisor != 0); // requires
+ let result = my_div(dividend, divisor);
+ kani::assert(result <= dividend); // ensures
+}
+Kani verifies the expanded harness like any other harness, giving the +green light for the next step: call abstraction.
+In the last phase the verified contract is ready for us to use to +abstract the function at its call sites.
+Kani requires that there has to be at least one associated
+proof_for_contract harness for each abstracted function, otherwise an error is
+thrown. In addition, by default, it requires all proof_for_contract
+harnesses to pass verification before attempting verification of any
+harnesses that use the contract as a stub.
A possible harness that uses our my_div contract could be the following:
#[kani::proof]
+#[kani::stub_verified(my_div)]
+fn use_div() {
+ let v = vec![...];
+ let some_idx = my_div(v.len() - 1, 3);
+ v[some_idx];
+}
+At a call site where the contract is used as an abstraction Kani
+kani::asserts the preconditions (requires) and produces a
+nondeterministic value (kani::any) which satisfies the postconditions.
Mutable memory is similarly made non-deterministic, discussed later in +havocking.
+An expanded stubbing of my_div looks like this:
fn my_div_stub(dividend: u32, divisor: u32) -> u32 {
+ kani::assert(divisor != 0); // pre-condition
+ kani::any_where(|result| { /* post-condition */ result <= dividend })
+}
+Notice that this performs no actual computation for my_div (other than the
+conditions) which allows us to avoid something potentially costly.
Also notice that Kani was able to express both contract checking and abstracting +with existing capabilities; the important feature is the enforcement. The +checking is, by construction, performed against the same condition that is +later used as the abstraction, which ensures soundness (see discussion on +lingering threats to soundness in the future section) +and guarding against abstractions diverging from their checks.
+Functions can have side effects on data reachable through mutable references or +pointers. To overapproximate all such modifications a function could apply to +pointed-to data, the verifier "havocs" those regions, essentially replacing +their content with non-deterministic values.
+Let us consider a simple example of a pop method.
impl<T> Vec<T> {
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+This function can, in theory, modify any memory behind &mut self, so this is
+what Kani will assume it does by default. It infers the "write set", that is the
+set of memory locations a function may modify, from the type of the function
+arguments. As a result, any data pointed to by a mutable reference or pointer is
+considered part of the write set3. In addition, a static
+analysis of the source code discovers any static mut variables the function or
+it's dependencies reference and adds all pointed-to data to the write set also.
During havocking the verifier replaces all locations in the write set with
+non-deterministic values. Kani emits a set of automatically generated
+postconditions which encode the expectations from the Rust type system and
+assumes them for the havocked locations to ensure they are valid. This
+encompasses both limits as to what values are acceptable for a given type, such
+as char or the possible values of an enum discriminator, as well as lifetime
+constraints.
While the inferred write set is sound and enough for successful contract
+checking4 in many cases this inference is too coarse
+grained. In the case of pop every value in this vector will be made
+non-deterministic.
To address this the proposal also adds a modifies and frees clause which
+limits the scope of havocking. Both clauses represent an assertion that the
+function will modify only the specified memory regions. Similar to
+requires/ensures the verifier enforces the assertion in the checking stage to
+ensure soundness. When the contract is used as an abstraction, the modifies
+clause is used as the write set to havoc.
In our pop example the only modified memory location is the last element and
+only if the vector was not already empty, which would be specified thusly.
impl<T> Vec<T> {
+ #[modifies(if !self.is_empty() => (*self).buf.ptr.pointer.pointer[self.len])]
+ #[modifies(if self.is_empty())]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+The #[modifies(when = CONDITION, targets = { MODIFIES_RANGE, ... })] consists
+of a CONDITION and zero or more, comma separated MODIFIES_RANGEs which are
+essentially a place expression.
Place expressions describe a position in the abstract program memory. You may
+think of it as what goes to the left of an assignment. They compose of the name
+of one function argument (or static variable) and zero or more projections
+(dereference *, field access .x and slice indexing [1]5).
If no when is provided the condition defaults to true, meaning the modifies
+ranges apply to all invocations of the function. If targets is omitted it
+defaults to {}, e.g. an empty set of targets meaning under this condition the
+function modifies no mutable memory.
Because place expressions are restricted to using projections only, Kani must
+break Rusts pub/no-pub encapsulation here6.
+If need be we can reference fields that are usually hidden, without an error
+from the compiler.
In addition to a place expression, a MODIFIES_RANGE can also be terminated
+with more complex slice expressions as the last projection. This only applies
+to *mut pointers to arrays. For instance this is needed for Vec::truncate
+where all of the latter section of the allocation is assigned (dropped).
impl<T> Vec<T> {
+ #[modifies(self.buf.ptr.pointer.pointer[len..])]
+ fn truncate(&mut self, len: usize) {
+ ...
+ }
+}
+[..] denotes the entirety of an allocation, [i..], [..j] and [i..j] are
+ranges of pointer offsets5. The slice indices are offsets with sizing T, e.g.
+in Rust p[i..j] would be equivalent to
+std::slice::from_raw_parts(p.offset(i), i - j). i must be smaller or equal
+than j.
A #[frees(when = CONDITION, targets = { PLACE, ... })] clause works similarly
+to modifies but denotes memory that is deallocated. Like modifies it applies
+only to pointers but unlike modifies it does not admit slice syntax, only
+place expressions, because the whole allocation has to be freed.
Kani's contract language contains additional support to reason about changes of
+mutable memory. One case where this is necessary is whenever ensures needs to
+refer to state before the function call. By default variables in the ensures
+clause are interpreted in the post-call state whereas history expressions are
+interpreted in the pre-call state.
Returning to our pop function from before we may wish to describe in which
+case the result is Some. However that depends on whether self is empty
+before pop is called. To do this Kani provides the old(EXPR) pseudo
+function (see this section about a discussion on naming),
+which evaluates EXPR before the call (e.g. to pop) and makes the result
+available to ensures. It is used like so:
impl<T> Vec<T> {
+ #[kani::ensures(old(self.is_empty()) || result.is_some())]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+old allows evaluating any Rust expression in the pre-call context, so long as
+it is free of side-effects. See also this
+explanation. The borrow checker enforces that the
+mutations performed by e.g. pop cannot be observed by the history expression, as
+that would defeat the purpose. If you wish to return borrowed content from
+old, make a copy instead (using e.g. clone()).
Note also that old is syntax, not a function and implemented as an extraction
+and lifting during code generation. It can reference e.g. pop's arguments but
+not local variables. Compare the following
Invalid ❌: #[kani::ensures({ let x = self.is_empty(); old(x) } || result.is_some())]
+Valid ✅: #[kani::ensures(old({ let x = self.is_empty(); x }) || result.is_some())]
And it will only be recognized as old(...), not as let old1 = old; old1(...) etc.
kani or cargo kani first verifies all contract harnesses
+(proof_for_contract) reachable from the file or in the local workspace
+respectively.stub_verified is required to have at least one associated contract harness.
+Kani reports any missing contract harnesses as errors.stub_verified contracts
+passed step 1 and 2.When specific harnesses are selected (with --harness) contracts are not
+verified.
Kani reports a compile time error if any of the following constraints are violated:
+A function may have any number of requires, ensures, modifies and frees
+attributes. Any function with at least one such annotation is considered as
+"having a contract".
Harnesses (general or for contract checking) may not have any such annotation.
+A harness may have up to one proof_for_contract(TARGET) annotation where TARGET must
+"have a contract". One or more proof_for_contract harnesses may have the
+same TARGET.
A proof_for_contract harness may use any harness attributes, including
+stub and stub_verified, though the TARGET may not appear in either.
Kani checks that TARGET is reachable from the proof_for_contract harness,
+but it does not warn if abstracted functions use TARGET8.
A proof_for_contract function may not have the kani::proof attribute (it
+is already implied by proof_for_contract).
A harness may have multiple stub_verified(TARGET) attributes. Each TARGET
+must "have a contract". No TARGET may appear twice. Each local TARGET is
+expected to have at least one associated proof_for_contract harness which
+passes verification, see also the discussion on when to check contracts in
+open questions.
Harnesses may combine stub(S_TARGET, ..) and stub_verified(V_TARGET)
+annotations, though no target may occur in S_TARGETs and V_TARGETs
+simultaneously.
For mutually recursive functions using stub_verified, Kani will check their
+contracts in non-deterministic order and assume each time the respective other
+check succeeded.
Kani implements the functionality of function contracts in three places.
+requires and ensures macros (kani_macros).kani-compiler for modifies clauses.kani-driver to enforce
+contract checking before replacement. Also plumbing between compiler and
+driver for enforcement of assigns clauses.kani_macrosThe requires and ensures macros perform code generation in the macro,
+creating a check and a replace function which use assert and assume as
+described in the user experience section. Both are attached
+to the function they are checking/replacing by kanitool::checked_with and
+kanitool::replaced_with attributes respectively. See also the
+discussion about why we decided to generate check
+and replace functions like this.
The code generation in the macros is straightforward, save two aspects: old
+and the borrow checker.
The special old builtin function is implemented as an AST rewrite. Consider
+the below example:
impl<T> Vec<T> {
+ #[kani::ensures(self.is_empty() || self.len() == old(self.len()) - 1)]
+ fn pop(&mut self) -> Option<T> {
+ ...
+ }
+}
+The ensures macro performs an AST rewrite consisting of an extraction of the
+expressions in old and a replacement with a fresh local variable, creating the
+following:
impl<T> Vec<T> {
+ fn check_pop(&mut self) -> Option<T> {
+ let old_1 = self.len();
+ let result = Self::pop(self);
+ kani::assert(self.is_empty() || self.len() == old_1 - 1)
+ }
+}
+Nested invocations of old are prohibited (Kani throws an error) and the
+expression inside may only refer to the function arguments and not other local
+variables in the contract (Rust will report those variables as not being in
+scope).
The borrow checker also ensures for us that none of the temporary variables
+borrow in a way that would be able to observe the modification in pop which
+would occur for instance if the user wrote old(self). Instead of borrowing
+copies should be created (e.g. old(self.clone())). This is only enforced for
+safe Rust though.
The second part relevant for the implementation is how we deal with the borrow
+checker for postconditions. They reference the arguments of the function after
+the call which is problematic if part of an input is borrowed mutably in the
+return value. For instance the Vec::split_at_mut function does this and a
+sensible contract for it might look as follows:
impl<T> Vec<T> {
+ #[ensures(self.len() == result.0.len() + result.1.len())]
+ fn split_at_mut(&mut self, i: usize) -> (&mut [T], &mut [T]) {
+ ...
+ }
+}
+This contract refers simultaneously to self and the result. Since the method
+however borrows self mutably, it would no longer be accessible in the
+postcondition. To work around this we strategically break the borrowing rules
+using a new hidden builtin kani::unchecked_deref with the type signature for <T> fn (&T) -> T which is essentially a C-style dereference operation. Breaking
+the borrow checker like this is safe for 2 reasons:
bool, meaning they cannot leak references to
+the arguments and cause the race conditions the Rust type system tries to
+prevent.The "copies" of arguments created by unsafe_deref are stored as fresh local
+variables and their occurrence in the postcondition is renamed. In addition a
+mem::forget is emitted for each copy to avoid a double free.
Kani verifies contracts for recursive functions inductively. Reentry of the +function is detected with a function-specific static variable. Upon detecting +reentry we use the replacement of the contract instead of the function body.
+Kani generates an additional wrapper around the function to add the detection.
+The additional wrapper is there so we can place the modifies contract on
+check_pop and replace_pop instead of recursion_wrapper which prevents CBMC
+from triggering its recursion induction as this would skip our replacement checks.
#[checked_with = "recursion_wrapper"]
+#[replaced_with = "replace_pop"]
+fn pop(&mut self) { ... }
+
+fn check_pop(&mut self) { ... }
+
+fn replace_pop(&mut self) { ... }
+
+fn recursion_wrapper(&mut self) {
+ static mut IS_ENTERED: bool = false;
+
+ if unsafe { IS_ENTERED } {
+ replace_pop(self)
+ } else {
+ unsafe { IS_ENTERED = true; }
+ let result = check_pop(self);
+ unsafe { IS_ENTERED = false; }
+ result
+ };
+}
+Note that this is insufficient to verify all types of recursive functions, as +the contract specification language has no support for inductive lemmas (for +instance in ACSL section 2.6.3 +"inductive predicates"). Inductive lemmas are usually needed for recursive +data structures.
+Contract enforcement and replacement (kani::proof_for_contract(f),
+kani::stub_verified(f)) both dispatch to the stubbing logic, stubbing f
+with the generated check and replace function respectively. If f has no
+contract, Kani throws an error.
For write sets Kani relies on CBMC. modifies clauses (whether derived from
+types or from explicit clauses) are emitted from the compiler as GOTO contracts
+in the artifact. Then the driver invokes goto-instrument with the name of the
+GOTO-level function names to enforce or replace the memory contracts. The
+compiler communicates the names of the function via harness metadata.
Code used in contracts is required to be side effect free which means it
+must not perform I/O, mutate memory (&mut vars and such) or (de)allocate heap
+memory. This is enforced in two layers. First with an MIR traversal over all
+code reachable from a contract expression. An error is thrown if known
+side-effecting actions are performed such as ptr::write, malloc, free or
+functions which we cannot check, such as e.g. extern "C", with the exception
+of known side effect free functions in e.g. the standard library.
Instead of generating check and replace functions in Kani, we could use the contract instrumentation provided by CBMC.
+We tried this earlier but came up short, because it is difficult to implement, +while supporting arbitrary Rust syntax. We exported the conditions into +functions so that Rust would do the parsing/type checking/lowering for us and +then call the lowered function in the CBMC contract.
+The trouble is that CBMC's old is only supported directly in the contract, not
+in functions called from the contract. This means we either need to inline the
+contract function body, which is brittle in the presence of control flow, or we
+must extract the old expressions, evaluate them in the contract directly and
+pass the results to the check function. However this means we must restrict the
+expressions in old, because we now need to lower those by hand and even if we
+could let rustc do it, CBMC's old has no support for function calls in its
+argument expression.
Instead of expanding contract macros one-at-a-time and layering the checks we +could expand all subsequent one's with the outermost one in one go.
+This is however brittle with respect to renaming. If a user does use kani::requires as my_requires and then does multiple
+#[my_requires(condition)] macro would not collect them properly since it can
+only match syntactically and it does not know about the use and neither can we
+restrict this kind of use or warn the user. By contrast, the collection with
+kanitool::checked_with is safe, because that attribute is generated by our
+macro itself, so we can rely on the fact that it uses the canonical
+representation.
Instead of generating the check and replace functions as siblings to the
+contracted function we could nest them like so
fn my_div(dividend: u32, divisor: u32) -> u32 {
+ fn my_div_check_5e3713(dividend: u32, divisor: u32) -> u32 {
+ ...
+ }
+ ...
+}
+This could be beneficial if we want to be able to allow contracts on trait impl +items, in which case generating sibling functions is not allowed. On the other +hand this makes it harder to implement contracts on trait definitions, +because there is no body available which we could nest the function into. +Ultimately we may require both so that we can support both.
+What is required to make this work is an additional pass over the condition that
+replaces every self with a fresh identifier that now becomes the first
+argument of the function. In addition there are open questions as to how to
+resolve the nested name inside the compiler.
Instead of
+adding a new special proof_for_contact attributes we could have instead done:
kani invocation with something like a
+--check-contract flag that directs the system to instrument the function.
+This is a very flexible design, but also easily used incorrectly.
+Specifically nothing in the source indicates which harnesses are supposed
+to be used for which contract, users must remember to invoke the check and
+are also responsible for ensuring they really do verify all contacts they
+will later be replacing and lastly.#[kani::proof] harness. This would have used
+e.g. a #[kani::for_contract] attributes on a #[kani::proof]. Since
+#[kani::for_contract] is only valid on a proof, we decided to just
+imply it and save the user some headache. Contract checking harnesses are
+not meant to be reused for other purposes anyway and if the user really
+wants to the can just factor out the actual contents of the harness to
+reuse it.A current limitation with how contracts are enforced means that if the target of
+a proof_for_contract is polymorphic, only one monomorphization is permitted to
+occur in the harness. This does not limit the target to a single occurrence,
+but to a single instantiation of its generic parameters.
This is because we rely on CBMC for enforcing the modifies contract. At the
+GOTO level all monomorphized instances are distinct functions and CBMC only
+allows checking one function contract at a time, hence this restriction.
We make the user supply the harnesses for checking contracts. This is our major +source of unsoundness, if corner cases are not adequately covered. Having Kani +generate the harnesses automatically is a non-trivial task (because heaps are +hard) and will be the subject of future improvements.
+In limited cases we could generate harnesses, for instance if only bounded types
+(integers, booleans, enums, tuples, structs, references and their combinations)
+were used. We could restrict the use of contracts to cases where only such types
+are involved in the function inputs and outputs, however this would drastically
+limit the applicability, as even simple heap data structures such as Vec,
+String and even &[T] and &str (slices) would be out of scope. These data
+structures however are ubiquitous and users can avoid the unsoundness with
+relative confidence by overprovisioning (generating inputs that are several
+times larger than what they expect the function will touch).
Returning kani::any() in a replacement isn't great, because it wouldn't work
+for references as they can't have an Arbitrary implementation. Plus the
+soundness then relies on a correct implementation of Arbitrary. Instead it
+may be better to allow for the user to specify type invariants which can the
+be used to generate correct values in replacement but also be checked as part
+of the contract checking.
Making result special. Should we use special syntax here like @result or
+kani::result(), though with the latter I worry that people may get confused
+because it is syntactic and not subject to usual use renaming and import
+semantics. Alternatively we can let the user pick the name with an additional
+argument to ensures, e.g. ensures(my_result_var, CONDITION)
Similar concerns apply to old, which may be more appropriate to be special
+syntax, e.g. @old.
See #2597
+How to check the right contracts at the right time. By default kani and
+cargo kani check all contracts in a crate/workspace. This represents the
+safest option for the user but may be too costly in some cases.
The user should be provided with options to disable contract checking for the +sake of efficiency. Such options may look like this:
+kani/cargo kani) all local contracts are checked,
+harnesses are only checked if the contracts they depend on succeeded their check.--harness) only those contracts which the
+selected harnesses depend on are checked.--paranoid flag also checks contracts for
+dependencies (other crates) when they are used in abstractions.#[stub_verified(TARGET, trusted)] or
+#[stub_unverified(TARGET)]. This also plays nicely with cfg_attr.--trusted TARGET to skip checking those
+contracts.--all-trusted.--litigate flag checks only contract harnesses.Aside: I'm obviously having some fun here with the names, happy to change, +it's really just about the semantics.
+Can old accidentally break scope? The old function cannot reference local
+variables. For instance #[ensures({let x = ...; old(x)})] cannot work as an
+AST rewrite because the expression in old is lifted out of it's context into
+one where the only bound variables are the function arguments (see also
+history expressions). In most cases this will be a
+compiler error complaining that x is unbound, however it is possible that
+if there is also a function argument x, then it may silently succeed the
+code generation but confusingly fail verification. For instance #[ensures({ let x = 1; old(x) == x })] on a function that has an argument named x would
+not hold.
To handle this correctly we would need an extra check that detects if old
+references local variables. That would also enable us to provide a better
+error message than the default "cannot find value x in this scope".
Can panicking be expected behavior? Usually preconditions are used to rule +out panics but it is conceivable that a user would want to specify that a +function panics under certain conditions. Specifying this would require an +extension to the current interface.
+UB checking. With unsafe rust it is possible to break the type system +guarantees in Rust without causing immediate errors. Contracts must be +cognizant of this and enforce the guarantees as part of the contract or +require users to explicitly defer such checks to use sites. The latter case +requires dedicated support because the potential UB must be reflected in the +havoc.
+modifies clauses over patterns. Modifies clauses mention values bound in
+the function header and as a user I would expect that if I use a pattern in
+the function header then I can use the names bound in that pattern as base
+variables in the modifies clause. However modifies clauses are implemented
+as assigns clauses in CBMC which does not have a notion of function header
+patterns. Thus it is necessary to project any modifies ranges deeper by the
+fields used in the matched pattern.
Quantifiers: Quantifiers are like logic-level loops and a powerful
+reasoning helper. CBMC has support for both exists and forall, but the
+code generation is difficult. The most ergonomic and easy way to implement
+quantifiers on the Rust side is as higher-order functions taking Fn(T) -> bool, where T is some arbitrary type that can be quantified over. This
+interface is familiar to developers, but the code generation is tricky, as
+CBMC level quantifiers only allow certain kinds of expressions. This
+necessitates a rewrite of the Fn closure to a compliant expression.
Letting the user supply the harnesses for checking contracts is a source of +unsoundness, if corner cases are not adequately covered. Ideally Kani would +generate the check harness automatically, but this is difficult both because +heap data structures are potentially infinite, and also because it must observe +user-level type invariants.
+A complete solution for this is not known to us but there are ongoing +investigations into harness generation mechanisms in CBMC.
+Function inputs that are non-inductive could be created from the type as the +safe Rust type constraints describe a finite space.
+For dealing with pointers one applicable mechanism could be memory +predicates to declaratively describe the state of the heap both before and +after the function call.
+In CBMC's implementation memory predicates are part of the pre/postconditions.
+This does not easily translate to Kani, since we handle pre/postconditions
+manually and mainly in proc-macros. There are multiple ways to bridge this
+gap, perhaps the easiest being to add memory predicates separately to Kani
+instead of as part of pre/postconditions, so they can be handled by forwarding
+them to CBMC. However this is also tricky, because memory predicates are used
+to describe pointers and pointers only. Meaning that if they are encapsulated
+in a structure (such as Vec or RefCell) there is no way of specifying the
+target of the predicate without breaking encapsulation (similar to
+modifies). In addition there are limitations also on the pointer predicates
+in CBMC itself. For instance they cannot be combined with quantifiers.
A better solution would be for the data structure to declare its own +invariants at definition site which are automatically swapped in on every +contract that uses this type.
+What about mutable trait inputs (wrt memory access patters), e.g. a mut impl AccessMe
Trait contracts: Our proposal could be extended easily to handle simple
+trait contracts. The macros would generate new trait methods with default
+implementations, similar to the functions it generates today. Using sealed
+types we can prevent the user from overwriting the generated contract methods.
+Contracts for the trait and contracts on it's impls are combined by abstracting
+the original method depending on context. The occurrence inside the contract
+generated from the trait method is replaced by the impl contract. Any other
+occurrence is replaced by the just altered trait method contract.
Cross Session Verification Caching: This proposal focuses on scalability +benefits within a single verification session, but those verification results +could be cached across sessions and speed up verification for large projects +using contacts in the future.
+Inductive Reasoning: Describing recursive functions can require that the +contract also recurse, describing a fixpoint logic. This is needed for +instance for linked data structures like linked lists or trees. Consider for +instance a reachability predicate for a linked list:
+struct LL<T> { head: T, next: *const LL<T> }
+
+fn reachable(list: &LL<T>, t: &T) -> bool {
+ list.head == t
+ || unsafe { next.as_ref() }.map_or(false, |p| reachable(p, t))
+}
+
+Compositional Contracts: The proposal in this document lacks a +comprehensive handling of type parameters. Contract checking harnesses require +monomorphization. However this means the contract is only checked against a +finite number of instantiations of any type parameter (at most as many as +contract checking harnesses were defined). There is nothing preventing the +user from using different instantiations of the function's type parameters.
+A function (f()) can only interact with its type parameters P through the
+traits (T) they are constrained over. We can require T to carry contracts
+on each method T::m(). During checking we can use a synthetic type that
+abstracts T::m() with its contract. This way we check f() against Ts
+contract. Then we later abstract f() we can ensure any instantiations of P
+have passed verification of the contract of T::m(). This makes the
+substitution safe even if the particular type has not been used in a checking
+harness.
For higher order functions this gets a bit more tricky, as closures are ad-hoc
+defined types. Here the contract for the closure could be attached to f()
+and then checked for each closure that may be provided. However this does not
+work so long as the user has to provide the harnesses, as they cannot recreate
+the closure type.
Enforced gates means all uses of constructs (functions, annotations, +macros) in this RFC are an error.
+The main remaining threat to soundness in the use of +contracts, as defined in this proposal, is the reliance on user-supplied +harnesses for contract checking (explained in item 2 of user +experience). A more thorough discussion on the dangers +and potential remedies can be found in the future +section.
+For inductively defined types the write set inference
+will only add the first "layer" to the write set. If you wish to modify
+deeper layers of a recursive type an explicit modifies clause is required.
While inferred memory footprints are sound for both safe
+and unsafe Rust certain features in unsafe rust (e.g. RefCell) get
+inferred incorrectly and will lead to a failing contract check.
Slice indices can be place expressions referencing function
+arguments, constants and integer arithmetic expressions. Take for example
+this Vec method (places simplified vs. actual implementation in std):
+fn truncate(&mut self, len: usize). A relatively precise contract for this
+method can be achieved with slice indices like so:
+#[modifies(self.buf[len..self.len], self.len)]
Breaking the pub encapsulation has
+unfortunate side effects because it means the contract depends on non-public
+elements which are not expected to be stable and can drastically change even
+in minor versions. For instance if your project depends on crate a which
+in turn depends on crate b, and a::foo has a contract that takes as
+input a pointer data structure b::Bar then a::foos assigns contract
+must reference internal fields of b::Bar. Say your project depends on the
+replacement of a::foo, if b changes the internal representation of
+Bar in a minor version update cargo could bump your version of b,
+breaking the contract of a::foo (it now crashes because it e.g. references
+non-existent fields).
+You cannot easily update the contract for a::foo, since it is a
+third-party crate; in fact even the author of a could not properly update
+to the new contract since their old version specification would still admit
+the new, broken version of b. They would have to yank the old version and
+explicitly nail down the exact minor version of b which defeats the whole
+purpose of semantic versioning.
Contracts for functions from
+external crates (crates from outside the workspace, which is not quite the
+definition of extern crate in Rust) are not checked by default. The
+expectation is that the library author providing the contract has performed
+this check. See also open question for a discussion on
+defaults and checking external contracts.
Kani cannot report the occurrence of a contract function to check +in abstracted functions as errors, because the mechanism is needed to verify +mutually recursive functions.
+