Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/crates/.rustc_info.json b/crates/.rustc_info.json
new file mode 100644
index 000000000000..22f974d85aa8
--- /dev/null
+++ b/crates/.rustc_info.json
@@ -0,0 +1 @@
+{"rustc_fingerprint":7283643872730095230,"outputs":{"14388650423374889093":{"success":true,"status":"","code":0,"stdout":"rustc 1.86.0-nightly (124cc9219 2025-02-09)\nbinary: rustc\ncommit-hash: 124cc92199ffa924f6b4c7cc819a85b65e0c3984\ncommit-date: 2025-02-09\nhost: x86_64-unknown-linux-gnu\nrelease: 1.86.0-nightly\nLLVM version: 19.1.7\n","stderr":""},"15992429099602374558":{"success":true,"status":"","code":0,"stdout":"___\nlib___.rlib\nlib___.so\nlib___.so\nlib___.a\nlib___.so\n/home/runner/.rustup/toolchains/nightly-2025-02-10-x86_64-unknown-linux-gnu\noff\npacked\nunpacked\n___\ndebug_assertions\nfmt_debug=\"full\"\nkani\noverflow_checks\npanic=\"unwind\"\nproc_macro\nrelocation_model=\"pic\"\ntarget_abi=\"\"\ntarget_arch=\"x86_64\"\ntarget_endian=\"little\"\ntarget_env=\"gnu\"\ntarget_family=\"unix\"\ntarget_feature=\"fxsr\"\ntarget_feature=\"sse\"\ntarget_feature=\"sse2\"\ntarget_feature=\"x87\"\ntarget_has_atomic\ntarget_has_atomic=\"16\"\ntarget_has_atomic=\"32\"\ntarget_has_atomic=\"64\"\ntarget_has_atomic=\"8\"\ntarget_has_atomic=\"ptr\"\ntarget_has_atomic_equal_alignment=\"16\"\ntarget_has_atomic_equal_alignment=\"32\"\ntarget_has_atomic_equal_alignment=\"64\"\ntarget_has_atomic_equal_alignment=\"8\"\ntarget_has_atomic_equal_alignment=\"ptr\"\ntarget_has_atomic_load_store\ntarget_has_atomic_load_store=\"16\"\ntarget_has_atomic_load_store=\"32\"\ntarget_has_atomic_load_store=\"64\"\ntarget_has_atomic_load_store=\"8\"\ntarget_has_atomic_load_store=\"ptr\"\ntarget_os=\"linux\"\ntarget_pointer_width=\"64\"\ntarget_thread_local\ntarget_vendor=\"unknown\"\nub_checks\nunix\n","stderr":""}},"successes":{}}
\ No newline at end of file
diff --git a/crates/.rustdoc_fingerprint.json b/crates/.rustdoc_fingerprint.json
new file mode 100644
index 000000000000..02a31108b995
--- /dev/null
+++ b/crates/.rustdoc_fingerprint.json
@@ -0,0 +1 @@
+{"rustc_vv":"rustc 1.86.0-nightly (124cc9219 2025-02-09)\nbinary: rustc\ncommit-hash: 124cc92199ffa924f6b4c7cc819a85b65e0c3984\ncommit-date: 2025-02-09\nhost: x86_64-unknown-linux-gnu\nrelease: 1.86.0-nightly\nLLVM version: 19.1.7\n"}
\ No newline at end of file
diff --git a/crates/doc/.lock b/crates/doc/.lock
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/crates/doc/crates.js b/crates/doc/crates.js
new file mode 100644
index 000000000000..c780c05bf815
--- /dev/null
+++ b/crates/doc/crates.js
@@ -0,0 +1,2 @@
+window.ALL_CRATES = ["kani"];
+//{"start":21,"fragment_lengths":[6]}
\ No newline at end of file
diff --git a/crates/doc/help.html b/crates/doc/help.html
new file mode 100644
index 000000000000..a5dc8de3f86a
--- /dev/null
+++ b/crates/doc/help.html
@@ -0,0 +1 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Coding conventions
+Formatting
+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.
Exceptions
+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.
Copyright notice
+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.
+Code for soundness
+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.
+Compilation errors
+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.
Internal compiler errors
+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.
+Verification errors
+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.
Create detailed issues for "TODO" tasks
+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");
+Performant but readable
+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:
+-
+
- Sort match arms, enum variants, and struct fields alphabetically. +
- Prefer concise but meaningful names. +
- Prefer exhaustive matches. +
- Prefer declarative over imperative programming. +
Rustdoc help
BackList of all items
Structs
Enums
Traits
Macros
- arbitrary_tuple
- cover
- generate_arbitrary
- generate_float
- generate_models
- implies
- kani_intrinsics
- kani_lib
- kani_mem
- kani_mem_init
- ptr_generator
- ptr_generator_fn
- slice_generator
Attribute Macros
- contracts::ensures
- contracts::modifies
- contracts::proof_for_contract
- contracts::requires
- contracts::stub_verified
- ensures
- loop_invariant
- modifies
- proof
- proof_for_contract
- recursion
- requires
- should_panic
- solver
- stub
- stub_verified
- unwind
Derive Macros
Functions
- any
- any_where
- assert
- assume
- concrete_playback_run
- cover
- float::float_to_int_in_range
- futures::block_on
- futures::block_on_with_spawn
- futures::spawn
- futures::yield_now
- mem::can_dereference
- mem::can_read_unaligned
- mem::can_write
- mem::can_write_unaligned
- mem::checked_align_of_raw
- mem::checked_size_of_raw
- mem::same_allocation
- pointer_generator
- slice::any_slice_of_array
- slice::any_slice_of_array_mut
- vec::any_vec
- vec::exact_vec
Expand description
This module introduces the Arbitrary trait as well as implementation for
+primitive types and other std containers.
Redirecting to ../../kani/enum.AllocationStatus.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/arbitrary_ptr/fn.pointer_generator.html b/crates/doc/kani/arbitrary_ptr/fn.pointer_generator.html new file mode 100644 index 000000000000..ab6a6cf0c987 --- /dev/null +++ b/crates/doc/kani/arbitrary_ptr/fn.pointer_generator.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../kani/fn.pointer_generator.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/arbitrary_ptr/struct.ArbitraryPointer.html b/crates/doc/kani/arbitrary_ptr/struct.ArbitraryPointer.html new file mode 100644 index 000000000000..656534c5c522 --- /dev/null +++ b/crates/doc/kani/arbitrary_ptr/struct.ArbitraryPointer.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../kani/struct.ArbitraryPointer.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/arbitrary_ptr/struct.PointerGenerator.html b/crates/doc/kani/arbitrary_ptr/struct.PointerGenerator.html new file mode 100644 index 000000000000..edddd32c905f --- /dev/null +++ b/crates/doc/kani/arbitrary_ptr/struct.PointerGenerator.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../kani/struct.PointerGenerator.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/attr.ensures.html b/crates/doc/kani/attr.ensures.html new file mode 100644 index 000000000000..8ae1bb99f607 --- /dev/null +++ b/crates/doc/kani/attr.ensures.html @@ -0,0 +1,13 @@ +Attribute Macro ensures
#[ensures]Expand description
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 closure that captures the input values to +the annotated function and the input to the function is the return value of +the function passed by reference. 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.
Attribute Macro loop_invariant
#[loop_invariant]Expand description
Add a loop invariant to this loop.
+The contents of the attribute is a condition that should be satisfied at the +beginning of every iteration of the loop. +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.
+Attribute Macro modifies
#[modifies]Expand description
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.
Attribute Macro proof
#[proof]Expand description
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).
Attribute Macro proof_for_contract
#[proof_for_contract]Expand description
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.
+Attribute Macro recursion
#[recursion]Expand description
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.
Attribute Macro requires
#[requires]Expand description
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.
Attribute Macro should_panic
#[should_panic]Expand description
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.
§Limitations
+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.
Attribute Macro solver
#[solver]Expand description
Select the SAT solver to use with CBMC for this harness
+The attribute #[kani::solver(arg)] can only be used alongside #[kani::proof].
arg - name of solver, e.g. kissat
+Attribute Macro stub
#[stub]Expand description
Specify a function/method stub pair to use for proof harness
+The attribute #[kani::stub(original, replacement)] can only be used alongside #[kani::proof].
§Arguments
+-
+
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.
+
Attribute Macro stub_verified
#[stub_verified]Expand description
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.
+Attribute Macro unwind
#[unwind]Expand description
Set Loop unwind limit for proof harnesses
+The attribute #[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.
Attribute Macro ensures
#[ensures]Expand description
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 closure that captures the input values to +the annotated function and the input to the function is the return value of +the function passed by reference. 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.
Attribute Macro modifies
#[modifies]Expand description
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.
Attribute Macro proof_for_contract
#[proof_for_contract]Expand description
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.
+Attribute Macro requires
#[requires]Expand description
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.
Attribute Macro stub_verified
#[stub_verified]Expand description
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.
+Expand description
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.
+-
+
- Contract specification attributes:
+
requiresandensures.
+ - Contract use attributes:
+
proof_for_contractand +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: usize, divisor: usize) -> usize {
+ 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 : &usize| *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 postcondition is expressed
+as a closure where the value returned from the function is passed to this
+closure by reference.
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:
use kani::{requires, ensures};
+
+#[requires(divisor != 0)]
+#[ensures(|result : &usize| *result <= dividend)]
+fn my_div(dividend: usize, divisor: usize) -> usize {
+ 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 = kani::vec::any_vec::<char, 5>();
+ 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 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 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 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.
§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 to enable +opt-out of inductive verification.
+§Write Sets
+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.
§History Expressions
+Additionally, an ensures clause is allowed to refer to the state of the function arguments before function execution and perform simple computations on them
+via an old monad. Any instance of old(computation) will evaluate the
+computation before the function is called. It is required that this computation
+is effect free and closed with respect to the function arguments.
For example, the following code passes kani tests:
+ +#[kani::modifies(a)]
+#[kani::ensures(|result| old(*a).wrapping_add(1) == *a)]
+#[kani::ensures(|result : &u32| old(*a).wrapping_add(1) == *result)]
+fn add1(a : &mut u32) -> u32 {
+ *a=a.wrapping_add(1);
+ *a
+}Here, the value stored in a is precomputed and remembered after the function
+is called, even though the contents of a changed during the function execution.
Attribute Macros§
- ensures
- Add a postcondition to this function.
- modifies
- Declaration of an explicit write-set for the annotated function.
- proof_
for_ contract - Designates this function as a harness to check a function contract.
- requires
- Add a precondition to this function.
- stub_
verified stub_verified(TARGET)is a harness attribute (to be used on +prooforproof_for_contract+function) that replaces all occurrences ofTARGETreachable from this +harness with a stub generated from the contract onTARGET.
Derive Macro Arbitrary
#[derive(Arbitrary)]
+{
+ // Attributes available to this derive:
+ #[safety_constraint]
+}
+Expand description
Allow users to auto generate Arbitrary implementations by using
+#[derive(Arbitrary)] macro.
§Type safety specification with the #[safety_constraint(...)] attribute
+When using #[derive(Arbitrary)] on a struct, the
+#[safety_constraint(<cond>)] attribute can be added to either the struct
+or its fields (but not both) to indicate a type safety invariant condition
+<cond>. Since kani::any() is always expected to produce type-safe
+values, adding #[safety_constraint(...)] to the struct or any of its
+fields will further constrain the objects generated with kani::any().
For example, the check_positive harness in this code is expected to
+pass:
#[derive(kani::Arbitrary)]
+struct AlwaysPositive {
+ #[safety_constraint(*inner >= 0)]
+ inner: i32,
+}
+
+#[kani::proof]
+fn check_positive() {
+ let val: AlwaysPositive = kani::any();
+ assert!(val.inner >= 0);
+}But using the #[safety_constraint(...)] attribute can lead to vacuous
+results when the values are over-constrained. For example, in this code
+the check_positive harness will pass too:
#[derive(kani::Arbitrary)]
+struct AlwaysPositive {
+ #[safety_constraint(*inner >= 0 && *inner < i32::MIN)]
+ inner: i32,
+}
+
+#[kani::proof]
+fn check_positive() {
+ let val: AlwaysPositive = kani::any();
+ assert!(val.inner >= 0);
+}Unfortunately, we made a mistake when specifying the condition because
+*inner >= 0 && *inner < i32::MIN is equivalent to false. This results
+in the relevant assertion being unreachable:
Check 1: check_positive.assertion.1
+ - Status: UNREACHABLE
+ - Description: "assertion failed: val.inner >= 0"
+ - Location: src/main.rs:22:5 in function check_positiveAs usual, we recommend users to defend against these behaviors by using
+kani::cover!(...) checks and watching out for unreachable assertions in
+their project’s code.
§Adding #[safety_constraint(...)] to the struct as opposed to its fields
+As mentioned earlier, the #[safety_constraint(...)] attribute can be added
+to either the struct or its fields, but not to both. Adding the
+#[safety_constraint(...)] attribute to both the struct and its fields will
+result in an error.
In practice, only one type of specification is need. If the condition for
+the type safety invariant involves a relation between two or more struct
+fields, the struct-level attribute should be used. Otherwise, using the
+#[safety_constraint(...)] on field(s) is recommended since it helps with readability.
For example, if we were defining a custom vector MyVector and wanted to
+specify that the inner vector’s length is always less than or equal to its
+capacity, we should do it as follows:
#[derive(Arbitrary)]
+#[safety_constraint(vector.len() <= *capacity)]
+struct MyVector<T> {
+ vector: Vec<T>,
+ capacity: usize,
+}However, if we were defining a struct whose fields are not related in any
+way, we would prefer using the #[safety_constraint(...)] attribute on its
+fields:
#[derive(Arbitrary)]
+struct PositivePoint {
+ #[safety_constraint(*x >= 0)]
+ x: i32,
+ #[safety_constraint(*y >= 0)]
+ y: i32,
+}Derive Macro Invariant
#[derive(Invariant)]
+{
+ // Attributes available to this derive:
+ #[safety_constraint]
+}
+Expand description
Allow users to auto generate Invariant implementations by using
+#[derive(Invariant)] macro.
§Type safety specification with the #[safety_constraint(...)] attribute
+When using #[derive(Invariant)] on a struct, the
+#[safety_constraint(<cond>)] attribute can be added to either the struct
+or its fields (but not both) to indicate a type safety invariant condition
+<cond>. This will ensure that the type-safety condition gets additionally
+checked when using the is_safe() method automatically generated by the
+#[derive(Invariant)] macro.
For example, the check_positive harness in this code is expected to
+fail:
#[derive(kani::Invariant)]
+struct AlwaysPositive {
+ #[safety_constraint(*inner >= 0)]
+ inner: i32,
+}
+
+#[kani::proof]
+fn check_positive() {
+ let val = AlwaysPositive { inner: -1 };
+ assert!(val.is_safe());
+}This is not too surprising since the type safety invariant that we indicated
+is not being taken into account when we create the AlwaysPositive object.
As mentioned, the is_safe() methods generated by the
+#[derive(Invariant)] macro check the corresponding is_safe() method for
+each field in addition to any type safety invariants specified through the
+#[safety_constraint(...)] attribute.
For example, for the AlwaysPositive struct from above, we will generate
+the following implementation:
impl kani::Invariant for AlwaysPositive {
+ fn is_safe(&self) -> bool {
+ let obj = self;
+ let inner = &obj.inner;
+ true && *inner >= 0 && inner.is_safe()
+ }
+}Note: the assignments to obj and inner are made so that we can treat the
+fields as if they were references.
§Adding #[safety_constraint(...)] to the struct as opposed to its fields
+As mentioned earlier, the #[safety_constraint(...)] attribute can be added
+to either the struct or its fields, but not to both. Adding the
+#[safety_constraint(...)] attribute to both the struct and its fields will
+result in an error.
In practice, only one type of specification is need. If the condition for
+the type safety invariant involves a relation between two or more struct
+fields, the struct-level attribute should be used. Otherwise, using the
+#[safety_constraint(...)] is recommended since it helps with readability.
For example, if we were defining a custom vector MyVector and wanted to
+specify that the inner vector’s length is always less than or equal to its
+capacity, we should do it as follows:
#[derive(Invariant)]
+#[safety_constraint(vector.len() <= *capacity)]
+struct MyVector<T> {
+ vector: Vec<T>,
+ capacity: usize,
+}However, if we were defining a struct whose fields are not related in any
+way, we would prefer using the #[safety_constraint(...)] attribute on its
+fields:
#[derive(Invariant)]
+struct PositivePoint {
+ #[safety_constraint(*x >= 0)]
+ x: i32,
+ #[safety_constraint(*y >= 0)]
+ y: i32,
+}pub enum AllocationStatus {
+ Dangling,
+ DeadObject,
+ Null,
+ InBounds,
+ OutOfBounds,
+}Expand description
Enumeration with the cases currently covered by the pointer generator.
+Variants§
Dangling
Dangling pointers
+DeadObject
Pointer to dead object
+Null
Null pointers
+InBounds
In bounds pointer (it may be unaligned)
+OutOfBounds
The pointer cannot be read / written to for the given type since one or more bytes +would be out of bounds of the current allocation.
+Trait Implementations§
Source§impl Arbitrary for AllocationStatus
impl Arbitrary for AllocationStatus
Source§impl Clone for AllocationStatus
impl Clone for AllocationStatus
Source§fn clone(&self) -> AllocationStatus
fn clone(&self) -> AllocationStatus
Returns a copy of the value. Read more
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from
source. Read moreSource§impl Debug for AllocationStatus
impl Debug for AllocationStatus
Source§impl PartialEq for AllocationStatus
impl PartialEq for AllocationStatus
impl Copy for AllocationStatus
impl Eq for AllocationStatus
impl StructuralPartialEq for AllocationStatus
Auto Trait Implementations§
impl Freeze for AllocationStatus
impl RefUnwindSafe for AllocationStatus
impl Send for AllocationStatus
impl Sync for AllocationStatus
impl Unpin for AllocationStatus
impl UnwindSafe for AllocationStatus
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Source§impl<T> CloneToUninit for Twhere
+ T: Clone,
impl<T> CloneToUninit for Twhere
+ T: Clone,
pub fn float_to_int_in_range<Float, Int>(value: Float) -> boolwhere
+ Float: FloatToInt<Int>,Expand description
Returns whether the given float value satisfies the range
+condition of the to_int_unchecked methods, namely that the value
+after truncation is in range of the target Int
§Example:
+let f: f32 = 145.7;
+let fits_in_i8 = kani::float::float_to_int_in_range::<f32, i8>(f);
+// doesn't fit in `i8` because the value after truncation (`145.0`) is larger than `i8::MAX`
+assert!(!fits_in_i8);
+
+let f: f64 = 1e6;
+let fits_in_u32 = kani::float::float_to_int_in_range::<f64, u32>(f);
+// fits in `u32` because the value after truncation (`1e6`) is smaller than `u32::MAX`
+assert!(fits_in_u32);Expand description
This module contains functions useful for float-related checks
+Functions§
- float_
to_ int_ in_ range - Returns whether the given float
valuesatisfies the range +condition of theto_int_uncheckedmethods, namely that thevalue+after truncation is in range of the targetInt
pub fn any<T: Arbitrary>() -> TExpand description
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.
let inputA = kani::any::<core::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) -> TExpand description
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.
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)Expand description
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.
+ +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)Expand description
Creates a cover property with the specified condition and message.
+§Example:
+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.
pub fn pointer_generator<T, const NUM_ELTS: usize>() -> PointerGenerator<{ _ }>Expand description
Create a pointer generator that fits at least N elements of type T.
pub enum SchedulingAssumption {
+ CanAssumeRunning,
+ CannotAssumeRunning,
+}Expand description
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.
Variants§
Auto Trait Implementations§
impl Freeze for SchedulingAssumption
impl RefUnwindSafe for SchedulingAssumption
impl Send for SchedulingAssumption
impl Sync for SchedulingAssumption
impl Unpin for SchedulingAssumption
impl UnwindSafe for SchedulingAssumption
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub fn block_on<T>(fut: impl Future<Output = T>) -> TExpand description
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.
pub fn block_on_with_spawn<F: Future<Output = ()> + Sync + 'static>(
+ fut: F,
+ scheduling_plan: impl SchedulingStrategy,
+)Expand description
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 ⓘExpand description
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.
Expand description
This module contains functions to work with futures (and async/.await) in Kani.
+Structs§
- Join
Handle - Result of spawning a task.
- Round
Robin - Keeps cycling through the tasks in a deterministic order
Enums§
- Scheduling
Assumption - Indicates to the scheduler whether it can
kani::assumethat the returned task is running.
Traits§
- Scheduling
Strategy - Trait that determines the possible sequence of tasks scheduling for a harness.
Functions§
- block_
on - A very simple executor: it polls the future in a busy loop until completion
- block_
on_ with_ spawn - Polls the given future and the tasks it may spawn until all of them complete
- spawn
- Spawns a task on the current global executor (which is set by
block_on_with_spawn) - yield_
now - Suspends execution of the current future, to allow the scheduler to poll another future
pub struct JoinHandle { /* private fields */ }Expand description
Result of spawning a task.
+If you .await a JoinHandle, this will wait for the spawned task to complete.
Trait Implementations§
Source§impl Future for JoinHandle
impl Future for JoinHandle
Auto Trait Implementations§
impl Freeze for JoinHandle
impl RefUnwindSafe for JoinHandle
impl Send for JoinHandle
impl Sync for JoinHandle
impl Unpin for JoinHandle
impl UnwindSafe for JoinHandle
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Source§impl<F> IntoFuture for Fwhere
+ F: Future,
impl<F> IntoFuture for Fwhere
+ F: Future,
Source§type IntoFuture = F
type IntoFuture = F
Which kind of future are we turning this into?
Source§fn into_future(self) -> <F as IntoFuture>::IntoFuture
fn into_future(self) -> <F as IntoFuture>::IntoFuture
Creates a future from a value. Read more
pub struct RoundRobin { /* private fields */ }Expand description
Keeps cycling through the tasks in a deterministic order
+Trait Implementations§
Source§impl Default for RoundRobin
impl Default for RoundRobin
Source§fn default() -> RoundRobin
fn default() -> RoundRobin
Returns the “default value” for a type. Read more
Source§impl SchedulingStrategy for RoundRobin
impl SchedulingStrategy for RoundRobin
Auto Trait Implementations§
impl Freeze for RoundRobin
impl RefUnwindSafe for RoundRobin
impl Send for RoundRobin
impl Sync for RoundRobin
impl Unpin for RoundRobin
impl UnwindSafe for RoundRobin
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub trait SchedulingStrategy {
+ // Required method
+ fn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption);
+}Expand description
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.
+Required Methods§
Sourcefn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption)
fn pick_task(&mut self, num_tasks: usize) -> (usize, SchedulingAssumption)
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.
Implementors§
impl SchedulingStrategy for RoundRobin
Re-exports§
pub use invariant::Invariant;pub use futures::RoundRobin;pub use futures::block_on;pub use futures::block_on_with_spawn;pub use futures::spawn;pub use futures::yield_now;
Modules§
- arbitrary
- This module introduces the
Arbitrarytrait as well as implementation for +primitive types and other std containers. - contracts
- Kani implementation of function contracts.
- float
- This module contains functions useful for float-related checks
- futures
- This module contains functions to work with futures (and async/.await) in Kani.
- invariant
- This module introduces the
Invarianttrait as well as its implementation +for primitive types. - mem
- This module contains functions useful for checking unsafe memory access.
- shadow
- This module contains an API for shadow memory. +Shadow memory is a mechanism by which we can store metadata on memory +locations, e.g. whether a memory location is initialized.
- slice
- vec
Macros§
- arbitrary_
tuple - This macro implements
kani::Arbitraryon a tuple whose elements +already implementkani::Arbitraryby runningkani::any()on +each index of the tuple. - cover
- generate_
arbitrary - generate_
float - generate_
models - implies
implies!(premise => conclusion)means that if thepremiseis true, so +must be theconclusion.- kani_
intrinsics - Kani intrinsics contains the public APIs used by users to verify their harnesses. +This macro is a part of kani_core as that allows us to verify even libraries that are no_core +such as core in rust’s std library itself.
- kani_
lib - Users should only need to invoke this.
- kani_
mem - kani_
mem_ init - ptr_
generator - ptr_
generator_ fn - slice_
generator
Structs§
- Arbitrary
Pointer - Holds information about a pointer that is generated non-deterministically.
- Pointer
Generator - Pointer generator that can be used to generate arbitrary pointers.
Enums§
- Allocation
Status - Enumeration with the cases currently covered by the pointer generator.
Traits§
Functions§
- any
- 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. - any_
where - 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. - assert
- Creates an assertion of the specified condition and message.
- assume
- 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.
- concrete_
playback_ run - NOP
concrete_playbackfor type checking during verification mode. - cover
- Creates a cover property with the specified condition and message.
- pointer_
generator - Create a pointer generator that fits at least
Nelements of typeT.
Attribute Macros§
- ensures
- Add a postcondition to this function.
- loop_
invariant - Add a loop invariant to this loop.
- modifies
- Declaration of an explicit write-set for the annotated function.
- proof
- Marks a Kani proof harness
- proof_
for_ contract - Designates this function as a harness to check a function contract.
- recursion
- Specifies that a function contains recursion for contract instrumentation.**
- requires
- Add a precondition to this function.
- should_
panic - Specifies that a proof harness is expected to panic.**
- solver
- Select the SAT solver to use with CBMC for this harness
- stub
- Specify a function/method stub pair to use for proof harness
- stub_
verified stub_verified(TARGET)is a harness attribute (to be used on +prooforproof_for_contract+function) that replaces all occurrences ofTARGETreachable from this +harness with a stub generated from the contract onTARGET.- unwind
- Set Loop unwind limit for proof harnesses
+The attribute
#[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 Macros§
Expand description
This module introduces the Invariant trait as well as its implementation
+for primitive types.
Traits§
- Invariant
- This trait should be used to specify and check type safety invariants for a +type. For type invariants, we refer to the definitions in the Rust’s Unsafe +Code Guidelines Reference: +https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant
pub trait Invariantwhere
+ Self: Sized,{
+ // Required method
+ fn is_safe(&self) -> bool;
+}Expand description
This trait should be used to specify and check type safety invariants for a +type. For type invariants, we refer to the definitions in the Rust’s Unsafe +Code Guidelines Reference: +https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant
+In summary, the reference distinguishes two kinds of type invariants:
+-
+
- Validity invariant: An invariant that all data must uphold any time +it’s accessed or copied in a typed manner. This invariant is exploited by +the compiler to perform optimizations. +
- Safety invariant: An invariant that safe code may assume all data to +uphold. This invariant can be temporarily violated by unsafe code, but +must always be upheld when interfacing with unknown safe code. +
Therefore, validity invariants must be upheld at all times, while safety +invariants only need to be upheld at the boundaries to safe code.
+Safety invariants are particularly interesting for user-defined types, and
+the Invariant trait allows you to check them with Kani.
It can also be used in tests. It’s a programmatic way to specify (in Rust) +properties over your data types. Since it’s written in Rust, it can be used +for static and dynamic checking.
+For example, let’s say you’re creating a type that represents a date:
+ +#[derive(kani::Arbitrary)]
+pub struct MyDate {
+ day: u8,
+ month: u8,
+ year: i64,
+}You can specify its safety invariant as:
+ +
+impl kani::Invariant for MyDate {
+ fn is_safe(&self) -> bool {
+ self.month > 0
+ && self.month <= 12
+ && self.day > 0
+ && self.day <= days_in_month(self.year, self.month)
+ }
+}And use it to check that your APIs are safe:
+ +#[kani::proof]
+fn check_increase_date() {
+ let mut date: MyDate = kani::any();
+ // Increase date by one day
+ increase_date(&mut date, 1);
+ assert!(date.is_safe());
+}Required Methods§
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.
Implementations on Foreign Types§
Implementors§
Redirecting to macro.arbitrary_tuple.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.arbitrary_tuple.html b/crates/doc/kani/macro.arbitrary_tuple.html new file mode 100644 index 000000000000..03fc08793c29 --- /dev/null +++ b/crates/doc/kani/macro.arbitrary_tuple.html @@ -0,0 +1,6 @@ +Macro arbitrary_tuple
macro_rules! arbitrary_tuple {
+ ($($type:ident),*) => { ... };
+}Expand description
This macro implements kani::Arbitrary on a tuple whose elements
+already implement kani::Arbitrary by running kani::any() on
+each index of the tuple.
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..b5214bb326d4 --- /dev/null +++ b/crates/doc/kani/macro.cover.html @@ -0,0 +1,5 @@ +macro_rules! cover {
+ () => { ... };
+ ($cond:expr $(,)?) => { ... };
+ ($cond:expr, $msg:literal) => { ... };
+}Redirecting to macro.generate_arbitrary.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.generate_arbitrary.html b/crates/doc/kani/macro.generate_arbitrary.html new file mode 100644 index 000000000000..d92cf9b355af --- /dev/null +++ b/crates/doc/kani/macro.generate_arbitrary.html @@ -0,0 +1,3 @@ +Macro generate_arbitrary
macro_rules! generate_arbitrary {
+ ($core:path) => { ... };
+}Redirecting to macro.generate_float.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.generate_float.html b/crates/doc/kani/macro.generate_float.html new file mode 100644 index 000000000000..af361d5dc643 --- /dev/null +++ b/crates/doc/kani/macro.generate_float.html @@ -0,0 +1,3 @@ +Macro generate_float
macro_rules! generate_float {
+ ($core:path) => { ... };
+}Redirecting to macro.generate_models.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.generate_models.html b/crates/doc/kani/macro.generate_models.html new file mode 100644 index 000000000000..8014a317946c --- /dev/null +++ b/crates/doc/kani/macro.generate_models.html @@ -0,0 +1,3 @@ +Macro generate_models
macro_rules! generate_models {
+ () => { ... };
+}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..aef26f57a275 --- /dev/null +++ b/crates/doc/kani/macro.implies.html @@ -0,0 +1,7 @@ +macro_rules! implies {
+ ($premise:expr => $conclusion:expr) => { ... };
+}Expand description
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.
Redirecting to macro.kani_intrinsics.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.kani_intrinsics.html b/crates/doc/kani/macro.kani_intrinsics.html new file mode 100644 index 000000000000..1596a0bd9a94 --- /dev/null +++ b/crates/doc/kani/macro.kani_intrinsics.html @@ -0,0 +1,7 @@ +Macro kani_intrinsics
macro_rules! kani_intrinsics {
+ ($core:tt) => { ... };
+}Expand description
Kani intrinsics contains the public APIs used by users to verify their harnesses. +This macro is a part of kani_core as that allows us to verify even libraries that are no_core +such as core in rust’s std library itself.
+TODO: Use this inside kani library so that we dont have to maintain two copies of the same intrinsics.
+Redirecting to macro.kani_lib.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.kani_lib.html b/crates/doc/kani/macro.kani_lib.html new file mode 100644 index 000000000000..3503db606486 --- /dev/null +++ b/crates/doc/kani/macro.kani_lib.html @@ -0,0 +1,11 @@ +Macro kani_lib
macro_rules! kani_lib {
+ (core) => { ... };
+ (kani) => { ... };
+}Expand description
Users should only need to invoke this.
+Options are:
+-
+
kani: Add definitions needed for Kani library.
+core: Define akanimodule insidecorecrate.
+std: TODO: Define akanimodule insidestdcrate. Users must define kani inside core.
+
Redirecting to macro.kani_mem.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.kani_mem.html b/crates/doc/kani/macro.kani_mem.html new file mode 100644 index 000000000000..b53027256a63 --- /dev/null +++ b/crates/doc/kani/macro.kani_mem.html @@ -0,0 +1,3 @@ +Macro kani_mem
macro_rules! kani_mem {
+ ($core:tt) => { ... };
+}Redirecting to macro.kani_mem_init.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.kani_mem_init.html b/crates/doc/kani/macro.kani_mem_init.html new file mode 100644 index 000000000000..dca5c196ba13 --- /dev/null +++ b/crates/doc/kani/macro.kani_mem_init.html @@ -0,0 +1,3 @@ +Macro kani_mem_init
macro_rules! kani_mem_init {
+ ($core:path) => { ... };
+}Redirecting to macro.ptr_generator.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.ptr_generator.html b/crates/doc/kani/macro.ptr_generator.html new file mode 100644 index 000000000000..44b79927a9e2 --- /dev/null +++ b/crates/doc/kani/macro.ptr_generator.html @@ -0,0 +1,3 @@ +Macro ptr_generator
macro_rules! ptr_generator {
+ () => { ... };
+}Redirecting to macro.ptr_generator_fn.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.ptr_generator_fn.html b/crates/doc/kani/macro.ptr_generator_fn.html new file mode 100644 index 000000000000..783616112076 --- /dev/null +++ b/crates/doc/kani/macro.ptr_generator_fn.html @@ -0,0 +1,3 @@ +Macro ptr_generator_fn
macro_rules! ptr_generator_fn {
+ () => { ... };
+}Redirecting to macro.slice_generator.html...
+ + + \ No newline at end of file diff --git a/crates/doc/kani/macro.slice_generator.html b/crates/doc/kani/macro.slice_generator.html new file mode 100644 index 000000000000..5503043d9ac6 --- /dev/null +++ b/crates/doc/kani/macro.slice_generator.html @@ -0,0 +1,3 @@ +Macro slice_generator
macro_rules! slice_generator {
+ () => { ... };
+}pub fn can_dereference<T: ?Sized>(ptr: *const T) -> boolExpand description
Checks that pointer ptr point to a valid value of type T.
For that, the pointer has to be a valid pointer according to crate::mem conditions 1, 2
+and 3,
+and the value stored must respect the validity invariants for type T.
TODO: Kani should automatically add those checks when a de-reference happens. +https://github.com/model-checking/kani/issues/2975
+This function will panic today if the pointer is not null, and it points to an unallocated or +deallocated memory location. This is an existing Kani limitation. +See https://github.com/model-checking/kani/issues/2690 for more details.
+pub fn can_read_unaligned<T: ?Sized>(ptr: *const T) -> boolExpand description
Checks that pointer ptr point to a valid value of type T.
For that, the pointer has to be a valid pointer according to crate::mem conditions 1, 2
+and 3,
+and the value stored must respect the validity invariants for type T.
Note this function succeeds for unaligned pointers. See self::can_dereference if you also +want to check pointer alignment.
+This function will panic today if the pointer is not null, and it points to an unallocated or +deallocated memory location. This is an existing Kani limitation. +See https://github.com/model-checking/kani/issues/2690 for more details.
+pub fn can_write<T: ?Sized>(ptr: *mut T) -> boolExpand description
Check if the pointer is valid for write access according to crate::mem conditions 1, 2 +and 3.
+Note this function also checks for pointer alignment. Use self::can_write_unaligned +if you don’t want to fail for unaligned pointers.
+This function does not check if the value stored is valid for the given type. Use +self::can_dereference for that.
+This function will panic today if the pointer is not null, and it points to an unallocated or +deallocated memory location. This is an existing Kani limitation. +See https://github.com/model-checking/kani/issues/2690 for more details.
+pub fn can_write_unaligned<T: ?Sized>(ptr: *const T) -> boolExpand description
Check if the pointer is valid for unaligned write access according to crate::mem conditions +1, 2 and 3.
+Note this function succeeds for unaligned pointers. See self::can_write if you also +want to check pointer alignment.
+This function will panic today if the pointer is not null, and it points to an unallocated or +deallocated memory location. This is an existing Kani limitation. +See https://github.com/model-checking/kani/issues/2690 for more details.
+Expand description
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)
+-
+
- A null pointer is never valid, not even for accesses of size zero. +
- 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.+ZST access is not OK for any pointer. +See: https://github.com/rust-lang/unsafe-code-guidelines/issues/472
+ - 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.
+ - 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_volatileandwrite_volatile: +Volatile accesses cannot be used for inter-thread synchronization.
+ - 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.
Functions§
- can_
dereference - Checks that pointer
ptrpoint to a valid value of typeT. - can_
read_ unaligned - Checks that pointer
ptrpoint to a valid value of typeT. - can_
write - Check if the pointer is valid for write access according to crate::mem conditions 1, 2 +and 3.
- can_
write_ unaligned - Check if the pointer is valid for unaligned write access according to crate::mem conditions +1, 2 and 3.
- checked_
align_ of_ raw - Compute the size of the val pointed to if safe.
- checked_
size_ of_ raw - Compute the size of the val pointed to if it is safe to do so.
- same_
allocation - Check if two pointers points to the same allocated object, and that both pointers +are in bounds of that object.
Expand description
This module contains an API for shadow memory. +Shadow memory is a mechanism by which we can store metadata on memory +locations, e.g. whether a memory location is initialized.
+The main data structure provided by this module is the ShadowMem struct,
+which allows us to store metadata on a given memory location.
§Example
+use kani::shadow::ShadowMem;
+use std::alloc::{alloc, Layout};
+
+let mut sm = ShadowMem::new(false);
+
+unsafe {
+ let ptr = alloc(Layout::new::<u8>());
+ // assert the memory location is not initialized
+ assert!(!sm.get(ptr));
+ // write to the memory location
+ *ptr = 42;
+ // update the shadow memory to indicate that this location is now initialized
+ sm.set(ptr, true);
+}Structs§
- Shadow
Mem - A shadow memory data structure that contains a two-dimensional array of a
+generic type
T. +Each element of the outer array represents an object, and each element of +the inner array represents a byte in the object.
pub struct ShadowMem<T: Copy> { /* private fields */ }Expand description
A shadow memory data structure that contains a two-dimensional array of a
+generic type T.
+Each element of the outer array represents an object, and each element of
+the inner array represents a byte in the object.
Implementations§
Auto Trait Implementations§
impl<T> Freeze for ShadowMem<T>where
+ T: Freeze,
impl<T> RefUnwindSafe for ShadowMem<T>where
+ T: RefUnwindSafe,
impl<T> Send for ShadowMem<T>where
+ T: Send,
impl<T> Sync for ShadowMem<T>where
+ T: Sync,
impl<T> Unpin for ShadowMem<T>where
+ T: Unpin,
impl<T> UnwindSafe for ShadowMem<T>where
+ T: UnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub fn any_slice_of_array<T, const LENGTH: usize>(arr: &[T; LENGTH]) -> &[T]Expand description
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:
+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]Expand description
A mutable version of the previous function
+Functions§
- any_
slice_ of_ array - Given an array
arrof lengthLENGTH, this function returns a valid +slice ofarrwith 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. - any_
slice_ of_ array_ mut - A mutable version of the previous function
pub struct ArbitraryPointer<'a, T> {
+ pub ptr: *mut T,
+ pub status: AllocationStatus,
+ pub is_initialized: bool,
+ /* private fields */
+}Expand description
Holds information about a pointer that is generated non-deterministically.
+Fields§
§ptr: *mut TThe pointer that was generated.
+status: AllocationStatusThe expected allocation status.
+is_initialized: boolWhether the pointer was generated with an initialized value or not.
+Trait Implementations§
Auto Trait Implementations§
impl<'a, T> Freeze for ArbitraryPointer<'a, T>
impl<'a, T> RefUnwindSafe for ArbitraryPointer<'a, T>where
+ T: RefUnwindSafe,
impl<'a, T> !Send for ArbitraryPointer<'a, T>
impl<'a, T> !Sync for ArbitraryPointer<'a, T>
impl<'a, T> Unpin for ArbitraryPointer<'a, T>
impl<'a, T> UnwindSafe for ArbitraryPointer<'a, T>where
+ T: RefUnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub struct PointerGenerator<const BYTES: usize> { /* private fields */ }Expand description
Pointer generator that can be used to generate arbitrary pointers.
+This generator allows users to build pointers with different safety properties. +This is different than creating a pointer that can have any address, since it will never +point to a previously allocated object. +See this section +for more details.
+The generator contains an internal buffer of a constant generic size, BYTES, that it
+uses to generate InBounds and OutOfBounds pointers.
+In those cases, the generated pointers will have the same provenance as the generator,
+and the same lifetime.
+The address of an InBounds pointer will represent all possible addresses in the range
+of the generator’s buffer address.
For other allocation statuses, the generator will create a pointer that satisfies the +given condition. +The pointer address will not represent all possible addresses that satisfies the +given allocation status.
+For example:
+ + let mut generator = PointerGenerator::<10>::new();
+ let arbitrary = generator.any_alloc_status::<char>();
+ kani::assume(arbitrary.status == AllocationStatus::InBounds);
+ // Pointer may be unaligned, but it should be in-bounds, so it is safe to write to
+ unsafe { arbitrary.ptr.write_unaligned(kani::any()) }The generator is parameterized by the number of bytes of its internal buffer. +See pointer_generator function if you would like to create a generator that fits +a minimum number of objects of a given type. Example:
+ + // These generators have the same capacity of 6 bytes.
+ let generator1 = PointerGenerator::<6>::new();
+ let generator2 = pointer_generator::<i16, 3>();§Buffer size
+The internal buffer is used to generate pointers, and its size determines the maximum +number of pointers it can generate without overlapping. +Larger values will impact the maximum distance between generated pointers.
+We recommend that you pick a size that is at least big enough to
+cover the cases where all pointers produced are non-overlapping.
+The buffer size in bytes must be big enough to fit distinct objects for each call
+of generate pointer.
+For example, generating two *mut u8 and one *mut u32 requires a buffer
+of at least 6 bytes.
This guarantees that your harness covers cases where all generated pointers +point to allocated positions that do not overlap. For example:
+ + let mut generator = PointerGenerator::<6>::new();
+ let ptr1: *mut u8 = generator.any_in_bounds().ptr;
+ let ptr2: *mut u8 = generator.any_in_bounds().ptr;
+ let ptr3: *mut u32 = generator.any_in_bounds().ptr;
+ // This cover is satisfied.
+ cover!((ptr1 as usize) >= (ptr2 as usize) + size_of::<u8>()
+ && (ptr2 as usize) >= (ptr3 as usize) + size_of::<u32>());
+ // As well as having overlapping pointers.
+ cover!((ptr1 as usize) == (ptr3 as usize));The first cover will be satisfied, since there exists at least one path where +the generator produces inbounds pointers that do not overlap. Such as this scenario:
++--------+--------+--------+--------+--------+--------+
+| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 |
++--------+--------+--------+--------+--------+--------+
+<--------------- ptr3 --------------><--ptr2-><--ptr1->I.e., the generator buffer is large enough to fit all 3 objects without overlapping.
+In contrast, if we had used a size of 1 element, all calls to any_in_bounds() would
+return elements that overlap, and the first cover would no longer be satisfied.
Note that the generator requires a minimum number of 1 byte, otherwise the
+InBounds case would never be covered.
+Compilation will fail if you try to create a generator of size 0.
Additionally, the verification will fail if you try to generate a pointer for a type +with size greater than the buffer size.
+Use larger buffer size if you want to cover scenarios where the distance +between the generated pointers matters.
+The only caveats of using very large numbers are:
+-
+
- The value cannot exceed the solver maximum object size (currently 2^48 by default), neither Rust’s
+maximum object size (
isize::MAX).
+ - Larger sizes could impact performance as they can lead to an exponential increase in the number of possibilities of pointer placement within the buffer. +
§Pointer provenance
+The pointer returned in the InBounds and OutOfBounds case will have the same
+provenance as the generator.
Use the same generator if you want to handle cases where 2 or more pointers may overlap. E.g.:
+ + let mut generator = pointer_generator::<char, 5>();
+ let ptr1 = generator.any_in_bounds::<char>().ptr;
+ let ptr2 = generator.any_in_bounds::<char>().ptr;
+ // This cover is satisfied.
+ cover!(ptr1 == ptr2)If you want to cover cases where two or more pointers may not have the same +provenance, you will need to instantiate multiple generators. +You can also apply non-determinism to cover cases where the pointers may or may not +have the same provenance. E.g.:
+ + let mut generator1 = pointer_generator::<char, 5>();
+ let mut generator2 = pointer_generator::<char, 5>();
+ let ptr1: *const char = generator1.any_in_bounds().ptr;
+ let ptr2: *const char = if kani::any() {
+ // Pointers will have same provenance and may overlap.
+ generator1.any_in_bounds().ptr
+ } else {
+ // Pointers will have different provenance and will not overlap.
+ generator2.any_in_bounds().ptr
+ };
+ // Invoke the function under verification
+ unsafe { my_target(ptr1, ptr2) };§Pointer Generator vs Pointer with any address
+Creating a pointer using the generator is different than generating a pointer +with any address.
+I.e.:
+ + // This pointer represents any address, and it may point to anything in memory,
+ // allocated or not.
+ let ptr1 = kani::any::<usize>() as *const u8;
+
+ // This pointer address will either point to unallocated memory, to a dead object
+ // or to allocated memory within the generator address space.
+ let mut generator = PointerGenerator::<5>::new();
+ let ptr2: *const u8 = generator.any_alloc_status().ptr;Kani cannot reason about a pointer allocation status (except for asserting its validity). +Thus, the generator was introduced to help writing harnesses that need to impose +constraints to the arbitrary pointer allocation status. +It also allow us to restrict the pointer provenance, excluding for example the address of +variables that are not available in the current context. +As a limitation, it will not cover the entire address space that a pointer can take.
+If your harness does not need to reason about pointer allocation, for example, verifying +pointer wrapping arithmetic, using a pointer with any address will allow you to cover +all possible scenarios.
+Implementations§
Source§impl<const BYTES: usize> PointerGenerator<BYTES>
impl<const BYTES: usize> PointerGenerator<BYTES>
Sourcepub fn any_alloc_status<'a, T>(&'a mut self) -> ArbitraryPointer<'a, T>where
+ T: Arbitrary,
pub fn any_alloc_status<'a, T>(&'a mut self) -> ArbitraryPointer<'a, T>where
+ T: Arbitrary,
Creates a raw pointer with non-deterministic properties.
+The pointer returned is either dangling or has the same provenance of the generator.
+Sourcepub fn any_in_bounds<'a, T>(&'a mut self) -> ArbitraryPointer<'a, T>where
+ T: Arbitrary,
pub fn any_in_bounds<'a, T>(&'a mut self) -> ArbitraryPointer<'a, T>where
+ T: Arbitrary,
Creates a in-bounds raw pointer with non-deterministic properties.
+The pointer points to an allocated location with the same provenance of the generator. +The pointer may be unaligned, and the pointee may be uninitialized.
+ + let mut generator = PointerGenerator::<6>::new();
+ let ptr1: *mut u8 = generator.any_in_bounds().ptr;
+ let ptr2: *mut u8 = generator.any_in_bounds().ptr;
+ // SAFETY: Both pointers have the same provenance.
+ let distance = unsafe { ptr1.offset_from(ptr2) };
+ assert!(distance > -5 && distance < 5)Trait Implementations§
Auto Trait Implementations§
impl<const BYTES: usize> Freeze for PointerGenerator<BYTES>
impl<const BYTES: usize> RefUnwindSafe for PointerGenerator<BYTES>
impl<const BYTES: usize> Send for PointerGenerator<BYTES>
impl<const BYTES: usize> Sync for PointerGenerator<BYTES>
impl<const BYTES: usize> Unpin for PointerGenerator<BYTES>
impl<const BYTES: usize> UnwindSafe for PointerGenerator<BYTES>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub trait Arbitrarywhere
+ Self: Sized,{
+ // Required method
+ fn any() -> Self;
+
+ // Provided method
+ fn any_array<const MAX_ARRAY_LENGTH: usize>() -> [Self; MAX_ARRAY_LENGTH] { ... }
+}Required Methods§
Provided Methods§
fn any_array<const MAX_ARRAY_LENGTH: usize>() -> [Self; MAX_ARRAY_LENGTH]
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.
Implementations on Foreign Types§
Source§impl Arbitrary for char
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
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
+Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary> Arbitrary for (A, B, C, D, E)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary> Arbitrary for (A, B, C, D, E)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary> Arbitrary for (A, B, C, D, E, F)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary> Arbitrary for (A, B, C, D, E, F)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary> Arbitrary for (A, B, C, D, E, F, G)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary> Arbitrary for (A, B, C, D, E, F, G)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary, K: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J, K)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary, K: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J, K)
Source§impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary, K: Arbitrary, L: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J, K, L)
impl<A: Arbitrary, B: Arbitrary, C: Arbitrary, D: Arbitrary, E: Arbitrary, F: Arbitrary, G: Arbitrary, H: Arbitrary, I: Arbitrary, J: Arbitrary, K: Arbitrary, L: Arbitrary> Arbitrary for (A, B, C, D, E, F, G, H, I, J, K, L)
Implementors§
impl Arbitrary for AllocationStatus
Arbitrary implementations by …\nHolds information about a pointer that is generated …\nDangling pointers\nPointer to dead object\nIn bounds pointer (it may be unaligned)\nAllow users to auto generate Invariant implementations by …\nNull pointers\nThe pointer cannot be read / written to for the given type …\nPointer generator that can be used to generate arbitrary …\nThis creates an symbolic valid value of type T. You can …\nCreates a raw pointer with non-deterministic properties.\nCreates a in-bounds raw pointer with non-deterministic …\nThis creates a symbolic valid value of type T. The value …\nThis module introduces the Arbitrary trait as well as …\nThis macro implements kani::Arbitrary on a tuple whose …\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 …\nAdd a postcondition to this function.\nThis module contains functions useful for float-related …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nThis module contains functions to work with futures (and …\nimplies!(premise => conclusion) means that if the premise …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nThis module introduces the Invariant trait as well as its …\nWhether the pointer was generated with an initialized …\nKani intrinsics contains the public APIs used by users to …\nUsers should only need to invoke this.\nAdd a loop invariant to this loop.\nThis module contains functions useful for checking unsafe …\nDeclaration of an explicit write-set for the annotated …\nCreate a new PointerGenerator.\nCreate a pointer generator that fits at least N elements …\nMarks a Kani proof harness\nDesignates this function as a harness to check a function …\nThe pointer that was generated.\nSpecifies that a function contains recursion for contract …\nAdd a precondition to this function.\nThis module contains an API for shadow memory. Shadow …\nSpecifies that a proof harness is expected to panic.**\nSelect the SAT solver to use with CBMC for this harness\nThe expected allocation status.\nSpecify a function/method stub pair to use for proof …\nstub_verified(TARGET) is a harness attribute (to be used on\nSet Loop unwind limit for proof harnesses The attribute …\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\nReturns whether the given float value satisfies the range …\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 …\nThis trait should be used to specify and check type safety …\nChecks that pointer ptr point to a valid value of type T.\nChecks that pointer ptr point to a valid value of type T.\nCheck if the pointer is valid for write access according …\nCheck if the pointer is valid for unaligned write access …\nCompute the size of the val pointed to if safe.\nCompute the size of the val pointed to if it is safe to do …\nCheck if two pointers points to the same allocated object, …\nA shadow memory data structure that contains a …\nReturns the argument unchanged.\nGet the shadow memory value of the given pointer\nCalls U::from(self).\nCreate a new shadow memory instance initialized with the …\nSet the shadow memory value of the given pointer\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..ada0eb811a30
--- /dev/null
+++ b/crates/doc/settings.html
@@ -0,0 +1 @@
+Rustdoc settings
Backkani/arbitrary.rs
// 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 crate::Arbitrary;
+
+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)
+ }
+}
+kani/contracts.rs
+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
// 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: usize, divisor: usize) -> usize {
+//! 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`.
+//!
+//! ```
+//! # use kani::requires;
+//! #[requires(divisor != 0)]
+//! # fn my_div(dividend: usize, divisor: usize) -> usize {
+//! # dividend / divisor
+//! # }
+//! ```
+//!
+//! 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:
+//!
+//! ```
+//! # use kani::ensures;
+//! #[ensures(|result : &usize| *result <= dividend)]
+//! # fn my_div(dividend: usize, divisor: usize) -> usize {
+//! # dividend / divisor
+//! # }
+//! ```
+//!
+//! 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 postcondition is expressed
+//! as a closure where the value returned from the function is passed to this
+//! closure by reference.
+//!
+//! 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:
+//!
+//! ```
+//! use kani::{requires, ensures};
+//!
+//! #[requires(divisor != 0)]
+//! #[ensures(|result : &usize| *result <= dividend)]
+//! fn my_div(dividend: usize, divisor: usize) -> usize {
+//! 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.
+//!
+//! ```
+//! # use kani::{requires, ensures};
+//! #
+//! # #[requires(divisor != 0)]
+//! # #[ensures(|result : &usize| *result <= dividend)]
+//! # fn my_div(dividend: usize, divisor: usize) -> usize {
+//! # dividend / divisor
+//! # }
+//! #
+//! #[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.
+//!
+//! ```
+//! # use kani::{requires, ensures};
+//! #
+//! # #[requires(divisor != 0)]
+//! # #[ensures(|result : &usize| *result <= dividend)]
+//! # fn my_div(dividend: usize, divisor: usize) -> usize {
+//! # dividend / divisor
+//! # }
+//! #
+//! #[kani::proof]
+//! #[kani::stub_verified(my_div)]
+//! fn use_div() {
+//! let v = kani::vec::any_vec::<char, 5>();
+//! 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`.
+//!
+//! ## History Expressions
+//!
+//! Additionally, an ensures clause is allowed to refer to the state of the function arguments before function execution and perform simple computations on them
+//! via an `old` monad. Any instance of `old(computation)` will evaluate the
+//! computation before the function is called. It is required that this computation
+//! is effect free and closed with respect to the function arguments.
+//!
+//! For example, the following code passes kani tests:
+//!
+//! ```
+//! #[kani::modifies(a)]
+//! #[kani::ensures(|result| old(*a).wrapping_add(1) == *a)]
+//! #[kani::ensures(|result : &u32| old(*a).wrapping_add(1) == *result)]
+//! fn add1(a : &mut u32) -> u32 {
+//! *a=a.wrapping_add(1);
+//! *a
+//! }
+//! ```
+//!
+//! Here, the value stored in `a` is precomputed and remembered after the function
+//! is called, even though the contents of `a` changed during the function execution.
+//!
+pub use super::{ensures, modifies, proof_for_contract, requires, stub_verified};
+kani/futures.rs
+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
// 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,
+}
+
+#[allow(static_mut_refs)]
+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")]
+#[allow(static_mut_refs)]
+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")]
+#[allow(static_mut_refs)]
+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 }
+}
+kani/invariant.rs
+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
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! This module introduces the `Invariant` trait as well as its implementation
+//! for primitive types.
+
+/// This trait should be used to specify and check type safety invariants for a
+/// type. For type invariants, we refer to the definitions in the Rust's Unsafe
+/// Code Guidelines Reference:
+/// <https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant>
+///
+/// In summary, the reference distinguishes two kinds of type invariants:
+/// - *Validity invariant*: An invariant that all data must uphold any time
+/// it's accessed or copied in a typed manner. This invariant is exploited by
+/// the compiler to perform optimizations.
+/// - *Safety invariant*: An invariant that safe code may assume all data to
+/// uphold. This invariant can be temporarily violated by unsafe code, but
+/// must always be upheld when interfacing with unknown safe code.
+///
+/// Therefore, validity invariants must be upheld at all times, while safety
+/// invariants only need to be upheld at the boundaries to safe code.
+///
+/// Safety invariants are particularly interesting for user-defined types, and
+/// the `Invariant` trait allows you to check them with Kani.
+///
+/// It can also be used in tests. It's a programmatic way to specify (in Rust)
+/// properties over your data types. Since it's written in Rust, it can be used
+/// for static and dynamic checking.
+///
+/// For example, let's say you're creating a type that represents a date:
+///
+/// ```rust
+/// #[derive(kani::Arbitrary)]
+/// pub struct MyDate {
+/// day: u8,
+/// month: u8,
+/// year: i64,
+/// }
+/// ```
+/// You can specify its safety invariant as:
+/// ```rust
+/// # #[derive(kani::Arbitrary)]
+/// # pub struct MyDate {
+/// # day: u8,
+/// # month: u8,
+/// # year: i64,
+/// # }
+/// # fn days_in_month(_: i64, _: u8) -> u8 { 31 }
+///
+/// impl kani::Invariant for MyDate {
+/// fn is_safe(&self) -> bool {
+/// self.month > 0
+/// && self.month <= 12
+/// && self.day > 0
+/// && self.day <= days_in_month(self.year, self.month)
+/// }
+/// }
+/// ```
+/// And use it to check that your APIs are safe:
+/// ```no_run
+/// # use kani::Invariant;
+/// #
+/// # #[derive(kani::Arbitrary)]
+/// # pub struct MyDate {
+/// # day: u8,
+/// # month: u8,
+/// # year: i64,
+/// # }
+/// #
+/// # fn days_in_month(_: i64, _: u8) -> u8 { todo!() }
+/// # fn increase_date(_: &mut MyDate, _: u8) { todo!() }
+/// #
+/// # impl Invariant for MyDate {
+/// # fn is_safe(&self) -> bool {
+/// # self.month > 0
+/// # && self.month <= 12
+/// # && self.day > 0
+/// # && self.day <= days_in_month(self.year, self.month)
+/// # }
+/// # }
+/// #
+/// #[kani::proof]
+/// fn check_increase_date() {
+/// let mut date: MyDate = kani::any();
+/// // Increase date by one day
+/// increase_date(&mut date, 1);
+/// assert!(date.is_safe());
+/// }
+/// ```
+pub trait Invariant
+where
+ Self: Sized,
+{
+ fn is_safe(&self) -> bool;
+}
+
+/// Any value is considered safe for the type
+macro_rules! trivial_invariant {
+ ( $type: ty ) => {
+ impl Invariant for $type {
+ #[inline(always)]
+ fn is_safe(&self) -> bool {
+ true
+ }
+ }
+ };
+}
+
+trivial_invariant!(u8);
+trivial_invariant!(u16);
+trivial_invariant!(u32);
+trivial_invariant!(u64);
+trivial_invariant!(u128);
+trivial_invariant!(usize);
+
+trivial_invariant!(i8);
+trivial_invariant!(i16);
+trivial_invariant!(i32);
+trivial_invariant!(i64);
+trivial_invariant!(i128);
+trivial_invariant!(isize);
+
+// We do not constrain the safety invariant for floating points types.
+// Users can create a new type wrapping the floating point type and define an
+// invariant that checks for NaN, infinite, or subnormal values.
+trivial_invariant!(f32);
+trivial_invariant!(f64);
+trivial_invariant!(f16);
+trivial_invariant!(f128);
+
+trivial_invariant!(());
+trivial_invariant!(bool);
+trivial_invariant!(char);
+kani/lib.rs
+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
// 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)]
+// Used to model simd.
+#![feature(repr_simd)]
+#![feature(generic_const_exprs)]
+#![allow(incomplete_features)]
+// 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(layout_for_ptr)]
+#![feature(ptr_metadata)]
+#![feature(f16)]
+#![feature(f128)]
+#![feature(convert_float_to_int)]
+
+// Allow us to use `kani::` to access crate features.
+extern crate self as kani;
+
+pub mod arbitrary;
+#[cfg(feature = "concrete_playback")]
+mod concrete_playback;
+pub mod futures;
+pub mod invariant;
+pub mod shadow;
+pub mod vec;
+
+mod models;
+
+#[cfg(feature = "concrete_playback")]
+pub use concrete_playback::concrete_playback_run;
+pub use invariant::Invariant;
+
+#[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::{RoundRobin, block_on, block_on_with_spawn, spawn, yield_now};
+
+// Kani proc macros must be in a separate crate
+pub use kani_macros::*;
+
+// Declare common Kani API such as assume, assert
+kani_core::kani_lib!(kani);
+
+// 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;
+
+#[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);
+ };
+}
+
+/// `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)
+ };
+}
+
+pub(crate) use kani_macros::unstable_feature as unstable;
+
+pub mod contracts;
+kani/models/mod.rs
+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
// 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.div_ceil(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)) },
+ 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)) };
+ assert_eq!(kani_mask, bitmask);
+ }
+}
+kani/shadow.rs
+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
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+//! This module contains an API for shadow memory.
+//! Shadow memory is a mechanism by which we can store metadata on memory
+//! locations, e.g. whether a memory location is initialized.
+//!
+//! The main data structure provided by this module is the `ShadowMem` struct,
+//! which allows us to store metadata on a given memory location.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use kani::shadow::ShadowMem;
+//! use std::alloc::{alloc, Layout};
+//!
+//! let mut sm = ShadowMem::new(false);
+//!
+//! unsafe {
+//! let ptr = alloc(Layout::new::<u8>());
+//! // assert the memory location is not initialized
+//! assert!(!sm.get(ptr));
+//! // write to the memory location
+//! *ptr = 42;
+//! // update the shadow memory to indicate that this location is now initialized
+//! sm.set(ptr, true);
+//! }
+//! ```
+
+const MAX_NUM_OBJECTS: usize = 1024;
+const MAX_OBJECT_SIZE: usize = 64;
+
+const MAX_NUM_OBJECTS_ASSERT_MSG: &str = "The number of objects exceeds the maximum number supported by Kani's shadow memory model (1024)";
+const MAX_OBJECT_SIZE_ASSERT_MSG: &str =
+ "The object size exceeds the maximum size supported by Kani's shadow memory model (64)";
+
+/// A shadow memory data structure that contains a two-dimensional array of a
+/// generic type `T`.
+/// Each element of the outer array represents an object, and each element of
+/// the inner array represents a byte in the object.
+pub struct ShadowMem<T: Copy> {
+ mem: [[T; MAX_OBJECT_SIZE]; MAX_NUM_OBJECTS],
+}
+
+impl<T: Copy> ShadowMem<T> {
+ /// Create a new shadow memory instance initialized with the given value
+ #[crate::unstable(
+ feature = "ghost-state",
+ issue = 3184,
+ reason = "experimental ghost state/shadow memory API"
+ )]
+ pub const fn new(val: T) -> Self {
+ Self { mem: [[val; MAX_OBJECT_SIZE]; MAX_NUM_OBJECTS] }
+ }
+
+ /// Get the shadow memory value of the given pointer
+ #[crate::unstable(
+ feature = "ghost-state",
+ issue = 3184,
+ reason = "experimental ghost state/shadow memory API"
+ )]
+ pub fn get<U>(&self, ptr: *const U) -> T {
+ let obj = crate::mem::pointer_object(ptr);
+ let offset = crate::mem::pointer_offset(ptr);
+ crate::assert(obj < MAX_NUM_OBJECTS, MAX_NUM_OBJECTS_ASSERT_MSG);
+ crate::assert(offset < MAX_OBJECT_SIZE, MAX_OBJECT_SIZE_ASSERT_MSG);
+ self.mem[obj][offset]
+ }
+
+ /// Set the shadow memory value of the given pointer
+ #[crate::unstable(
+ feature = "ghost-state",
+ issue = 3184,
+ reason = "experimental ghost state/shadow memory API"
+ )]
+ pub fn set<U>(&mut self, ptr: *const U, val: T) {
+ let obj = crate::mem::pointer_object(ptr);
+ let offset = crate::mem::pointer_offset(ptr);
+ crate::assert(obj < MAX_NUM_OBJECTS, MAX_NUM_OBJECTS_ASSERT_MSG);
+ crate::assert(offset < MAX_OBJECT_SIZE, MAX_OBJECT_SIZE_ASSERT_MSG);
+ self.mem[obj][offset] = val;
+ }
+}
+kani/vec.rs
+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
// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+use crate::{Arbitrary, any, any_where};
+
+/// 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,
+{
+ 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,
+{
+ let boxed_array: Box<[T; EXACT_LENGTH]> = Box::new(any());
+ <[T]>::into_vec(boxed_array)
+}
+"+window.searchState.loadingText+"
";window.searchState.showResults(search)},descShards:new Map(),loadDesc:async function({descShard,descIndex}){if(descShard.promise===null){descShard.promise=new Promise((resolve,reject)=>{descShard.resolve=resolve;const ds=descShard;const fname=`${ds.crate}-desc-${ds.shard}-`;const url=resourcePath(`search.desc/${descShard.crate}/${fname}`,".js",);loadScript(url,reject)})}const list=await descShard.promise;return list[descIndex]},loadedDescShard:function(crate,shard,data){this.descShards.get(crate)[shard].resolve(data.split("\n"))},};const toggleAllDocsId="toggle-all-docs";let savedHash="";function handleHashes(ev){if(ev!==null&&window.searchState.isDisplayed()&&ev.newURL){switchDisplayedElement(null);const hash=ev.newURL.slice(ev.newURL.indexOf("#")+1);if(browserSupportsHistoryApi()){history.replaceState(null,"",getNakedUrl()+window.location.search+"#"+hash)}const elem=document.getElementById(hash);if(elem){elem.scrollIntoView()}}const pageId=window.location.hash.replace(/^#/,"");if(savedHash!==pageId){savedHash=pageId;if(pageId!==""){expandSection(pageId)}}if(savedHash.startsWith("impl-")){const splitAt=savedHash.indexOf("/");if(splitAt!==-1){const implId=savedHash.slice(0,splitAt);const assocId=savedHash.slice(splitAt+1);const implElems=document.querySelectorAll(`details > summary > section[id^="${implId}"]`,);onEachLazy(implElems,implElem=>{const numbered=/^(.+?)-([0-9]+)$/.exec(implElem.id);if(implElem.id!==implId&&(!numbered||numbered[1]!==implId)){return false}return onEachLazy(implElem.parentElement.parentElement.querySelectorAll(`[id^="${assocId}"]`),item=>{const numbered=/^(.+?)-([0-9]+)$/.exec(item.id);if(item.id===assocId||(numbered&&numbered[1]===assocId)){openParentDetails(item);item.scrollIntoView();setTimeout(()=>{window.location.replace("#"+item.id)},0);return true}},)})}}}function onHashChange(ev){hideSidebar();handleHashes(ev)}function openParentDetails(elem){while(elem){if(elem.tagName==="DETAILS"){elem.open=true}elem=elem.parentNode}}function expandSection(id){openParentDetails(document.getElementById(id))}function handleEscape(ev){searchState.clearInputTimeout();searchState.hideResults();ev.preventDefault();searchState.defocus();window.hideAllModals(true)}function handleShortcut(ev){const disableShortcuts=getSettingValue("disable-shortcuts")==="true";if(ev.ctrlKey||ev.altKey||ev.metaKey||disableShortcuts){return}if(document.activeElement.tagName==="INPUT"&&document.activeElement.type!=="checkbox"&&document.activeElement.type!=="radio"){switch(getVirtualKey(ev)){case"Escape":handleEscape(ev);break}}else{switch(getVirtualKey(ev)){case"Escape":handleEscape(ev);break;case"s":case"S":case"/":ev.preventDefault();searchState.focus();break;case"+":ev.preventDefault();expandAllDocs();break;case"-":ev.preventDefault();collapseAllDocs();break;case"?":showHelp();break;default:break}}}document.addEventListener("keypress",handleShortcut);document.addEventListener("keydown",handleShortcut);function addSidebarItems(){if(!window.SIDEBAR_ITEMS){return}const sidebar=document.getElementById("rustdoc-modnav");function block(shortty,id,longty){const filtered=window.SIDEBAR_ITEMS[shortty];if(!filtered){return}const modpath=hasClass(document.querySelector(".rustdoc"),"mod")?"../":"";const h3=document.createElement("h3");h3.innerHTML=`${longty}`;const ul=document.createElement("ul");ul.className="block "+shortty;for(const name of filtered){let path;if(shortty==="mod"){path=`${modpath}${name}/index.html`}else{path=`${modpath}${shortty}.${name}.html`}let current_page=document.location.href.toString();if(current_page.endsWith("/")){current_page+="index.html"}const link=document.createElement("a");link.href=path;link.textContent=name;const li=document.createElement("li");if(link.href===current_page){li.classList.add("current")}li.appendChild(link);ul.appendChild(li)}sidebar.appendChild(h3);sidebar.appendChild(ul)}if(sidebar){block("primitive","primitives","Primitive Types");block("mod","modules","Modules");block("macro","macros","Macros");block("struct","structs","Structs");block("enum","enums","Enums");block("constant","constants","Constants");block("static","static","Statics");block("trait","traits","Traits");block("fn","functions","Functions");block("type","types","Type Aliases");block("union","unions","Unions");block("foreigntype","foreign-types","Foreign Types");block("keyword","keywords","Keywords");block("attr","attributes","Attribute Macros");block("derive","derives","Derive Macros");block("traitalias","trait-aliases","Trait Aliases")}}window.register_implementors=imp=>{const implementors=document.getElementById("implementors-list");const synthetic_implementors=document.getElementById("synthetic-implementors-list");const inlined_types=new Set();const TEXT_IDX=0;const SYNTHETIC_IDX=1;const TYPES_IDX=2;if(synthetic_implementors){onEachLazy(synthetic_implementors.getElementsByClassName("impl"),el=>{const aliases=el.getAttribute("data-aliases");if(!aliases){return}aliases.split(",").forEach(alias=>{inlined_types.add(alias)})})}let currentNbImpls=implementors.getElementsByClassName("impl").length;const traitName=document.querySelector(".main-heading h1 > .trait").textContent;const baseIdName="impl-"+traitName+"-";const libs=Object.getOwnPropertyNames(imp);const script=document.querySelector("script[data-ignore-extern-crates]");const ignoreExternCrates=new Set((script?script.getAttribute("data-ignore-extern-crates"):"").split(","),);for(const lib of libs){if(lib===window.currentCrate||ignoreExternCrates.has(lib)){continue}const structs=imp[lib];struct_loop:for(const struct of structs){const list=struct[SYNTHETIC_IDX]?synthetic_implementors:implementors;if(struct[SYNTHETIC_IDX]){for(const struct_type of struct[TYPES_IDX]){if(inlined_types.has(struct_type)){continue struct_loop}inlined_types.add(struct_type)}}const code=document.createElement("h3");code.innerHTML=struct[TEXT_IDX];addClass(code,"code-header");onEachLazy(code.getElementsByTagName("a"),elem=>{const href=elem.getAttribute("href");if(href&&!href.startsWith("#")&&!/^(?:[a-z+]+:)?\/\//.test(href)){elem.setAttribute("href",window.rootPath+href)}});const currentId=baseIdName+currentNbImpls;const anchor=document.createElement("a");anchor.href="#"+currentId;addClass(anchor,"anchor");const display=document.createElement("div");display.id=currentId;addClass(display,"impl");display.appendChild(anchor);display.appendChild(code);list.appendChild(display);currentNbImpls+=1}}};if(window.pending_implementors){window.register_implementors(window.pending_implementors)}window.register_type_impls=imp=>{if(!imp||!imp[window.currentCrate]){return}window.pending_type_impls=null;const idMap=new Map();let implementations=document.getElementById("implementations-list");let trait_implementations=document.getElementById("trait-implementations-list");let trait_implementations_header=document.getElementById("trait-implementations");const script=document.querySelector("script[data-self-path]");const selfPath=script?script.getAttribute("data-self-path"):null;const mainContent=document.querySelector("#main-content");const sidebarSection=document.querySelector(".sidebar section");let methods=document.querySelector(".sidebar .block.method");let associatedTypes=document.querySelector(".sidebar .block.associatedtype");let associatedConstants=document.querySelector(".sidebar .block.associatedconstant");let sidebarTraitList=document.querySelector(".sidebar .block.trait-implementation");for(const impList of imp[window.currentCrate]){const types=impList.slice(2);const text=impList[0];const isTrait=impList[1]!==0;const traitName=impList[1];if(types.indexOf(selfPath)===-1){continue}let outputList=isTrait?trait_implementations:implementations;if(outputList===null){const outputListName=isTrait?"Trait Implementations":"Implementations";const outputListId=isTrait?"trait-implementations-list":"implementations-list";const outputListHeaderId=isTrait?"trait-implementations":"implementations";const outputListHeader=document.createElement("h2");outputListHeader.id=outputListHeaderId;outputListHeader.innerText=outputListName;outputList=document.createElement("div");outputList.id=outputListId;if(isTrait){const link=document.createElement("a");link.href=`#${outputListHeaderId}`;link.innerText="Trait Implementations";const h=document.createElement("h3");h.appendChild(link);trait_implementations=outputList;trait_implementations_header=outputListHeader;sidebarSection.appendChild(h);sidebarTraitList=document.createElement("ul");sidebarTraitList.className="block trait-implementation";sidebarSection.appendChild(sidebarTraitList);mainContent.appendChild(outputListHeader);mainContent.appendChild(outputList)}else{implementations=outputList;if(trait_implementations){mainContent.insertBefore(outputListHeader,trait_implementations_header);mainContent.insertBefore(outputList,trait_implementations_header)}else{const mainContent=document.querySelector("#main-content");mainContent.appendChild(outputListHeader);mainContent.appendChild(outputList)}}}const template=document.createElement("template");template.innerHTML=text;onEachLazy(template.content.querySelectorAll("a"),elem=>{const href=elem.getAttribute("href");if(href&&!href.startsWith("#")&&!/^(?:[a-z+]+:)?\/\//.test(href)){elem.setAttribute("href",window.rootPath+href)}});onEachLazy(template.content.querySelectorAll("[id]"),el=>{let i=0;if(idMap.has(el.id)){i=idMap.get(el.id)}else if(document.getElementById(el.id)){i=1;while(document.getElementById(`${el.id}-${2 * i}`)){i=2*i}while(document.getElementById(`${el.id}-${i}`)){i+=1}}if(i!==0){const oldHref=`#${el.id}`;const newHref=`#${el.id}-${i}`;el.id=`${el.id}-${i}`;onEachLazy(template.content.querySelectorAll("a[href]"),link=>{if(link.getAttribute("href")===oldHref){link.href=newHref}})}idMap.set(el.id,i+1)});const templateAssocItems=template.content.querySelectorAll("section.tymethod, "+"section.method, section.associatedtype, section.associatedconstant");if(isTrait){const li=document.createElement("li");const a=document.createElement("a");a.href=`#${template.content.querySelector(".impl").id}`;a.textContent=traitName;li.appendChild(a);sidebarTraitList.append(li)}else{onEachLazy(templateAssocItems,item=>{let block=hasClass(item,"associatedtype")?associatedTypes:(hasClass(item,"associatedconstant")?associatedConstants:(methods));if(!block){const blockTitle=hasClass(item,"associatedtype")?"Associated Types":(hasClass(item,"associatedconstant")?"Associated Constants":("Methods"));const blockClass=hasClass(item,"associatedtype")?"associatedtype":(hasClass(item,"associatedconstant")?"associatedconstant":("method"));const blockHeader=document.createElement("h3");const blockLink=document.createElement("a");blockLink.href="#implementations";blockLink.innerText=blockTitle;blockHeader.appendChild(blockLink);block=document.createElement("ul");block.className=`block ${blockClass}`;const insertionReference=methods||sidebarTraitList;if(insertionReference){const insertionReferenceH=insertionReference.previousElementSibling;sidebarSection.insertBefore(blockHeader,insertionReferenceH);sidebarSection.insertBefore(block,insertionReferenceH)}else{sidebarSection.appendChild(blockHeader);sidebarSection.appendChild(block)}if(hasClass(item,"associatedtype")){associatedTypes=block}else if(hasClass(item,"associatedconstant")){associatedConstants=block}else{methods=block}}const li=document.createElement("li");const a=document.createElement("a");a.innerText=item.id.split("-")[0].split(".")[1];a.href=`#${item.id}`;li.appendChild(a);block.appendChild(li)})}outputList.appendChild(template.content)}for(const list of[methods,associatedTypes,associatedConstants,sidebarTraitList]){if(!list){continue}const newChildren=Array.prototype.slice.call(list.children);newChildren.sort((a,b)=>{const aI=a.innerText;const bI=b.innerText;return aI"+window.NOTABLE_TRAITS[notable_ty]+"
"}else{const ttl=e.getAttribute("title");if(ttl!==null){e.setAttribute("data-title",ttl);e.removeAttribute("title")}const dttl=e.getAttribute("data-title");if(dttl!==null){const titleContent=document.createElement("div");titleContent.className="content";titleContent.appendChild(document.createTextNode(dttl));wrapper.appendChild(titleContent)}}wrapper.className="tooltip popover";const focusCatcher=document.createElement("div");focusCatcher.setAttribute("tabindex","0");focusCatcher.onfocus=hideTooltip;wrapper.appendChild(focusCatcher);const pos=e.getBoundingClientRect();wrapper.style.top=(pos.top+window.scrollY+pos.height)+"px";wrapper.style.left=0;wrapper.style.right="auto";wrapper.style.visibility="hidden";document.body.appendChild(wrapper);const wrapperPos=wrapper.getBoundingClientRect();const finalPos=pos.left+window.scrollX-wrapperPos.width+24;if(finalPos>0){wrapper.style.left=finalPos+"px"}else{wrapper.style.setProperty("--popover-arrow-offset",(wrapperPos.right-pos.right+4)+"px",)}wrapper.style.visibility="";window.CURRENT_TOOLTIP_ELEMENT=wrapper;window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE=e;clearTooltipHoverTimeout(window.CURRENT_TOOLTIP_ELEMENT);wrapper.onpointerenter=ev=>{if(ev.pointerType!=="mouse"){return}clearTooltipHoverTimeout(e)};wrapper.onpointerleave=ev=>{if(ev.pointerType!=="mouse"||!(ev.relatedTarget instanceof HTMLElement)){return}if(!e.TOOLTIP_FORCE_VISIBLE&&!e.contains(ev.relatedTarget)){setTooltipHoverTimeout(e,false);addClass(wrapper,"fade-out")}}}function setTooltipHoverTimeout(element,show){clearTooltipHoverTimeout(element);if(!show&&!window.CURRENT_TOOLTIP_ELEMENT){return}if(show&&window.CURRENT_TOOLTIP_ELEMENT){return}if(window.CURRENT_TOOLTIP_ELEMENT&&window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE!==element){return}element.TOOLTIP_HOVER_TIMEOUT=setTimeout(()=>{if(show){showTooltip(element)}else if(!element.TOOLTIP_FORCE_VISIBLE){hideTooltip(false)}},show?window.RUSTDOC_TOOLTIP_HOVER_MS:window.RUSTDOC_TOOLTIP_HOVER_EXIT_MS)}function clearTooltipHoverTimeout(element){if(element.TOOLTIP_HOVER_TIMEOUT!==undefined){removeClass(window.CURRENT_TOOLTIP_ELEMENT,"fade-out");clearTimeout(element.TOOLTIP_HOVER_TIMEOUT);delete element.TOOLTIP_HOVER_TIMEOUT}}function tooltipBlurHandler(event){if(window.CURRENT_TOOLTIP_ELEMENT&&!window.CURRENT_TOOLTIP_ELEMENT.contains(document.activeElement)&&!window.CURRENT_TOOLTIP_ELEMENT.contains(event.relatedTarget)&&!window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.contains(document.activeElement)&&!window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.contains(event.relatedTarget)){setTimeout(()=>hideTooltip(false),0)}}function hideTooltip(focus){if(window.CURRENT_TOOLTIP_ELEMENT){if(window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.TOOLTIP_FORCE_VISIBLE){if(focus){window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.focus()}window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.TOOLTIP_FORCE_VISIBLE=false}document.body.removeChild(window.CURRENT_TOOLTIP_ELEMENT);clearTooltipHoverTimeout(window.CURRENT_TOOLTIP_ELEMENT);window.CURRENT_TOOLTIP_ELEMENT=null}}onEachLazy(document.getElementsByClassName("tooltip"),e=>{e.onclick=()=>{e.TOOLTIP_FORCE_VISIBLE=e.TOOLTIP_FORCE_VISIBLE?false:true;if(window.CURRENT_TOOLTIP_ELEMENT&&!e.TOOLTIP_FORCE_VISIBLE){hideTooltip(true)}else{showTooltip(e);window.CURRENT_TOOLTIP_ELEMENT.setAttribute("tabindex","0");window.CURRENT_TOOLTIP_ELEMENT.focus();window.CURRENT_TOOLTIP_ELEMENT.onblur=tooltipBlurHandler}return false};e.onpointerenter=ev=>{if(ev.pointerType!=="mouse"){return}setTooltipHoverTimeout(e,true)};e.onpointermove=ev=>{if(ev.pointerType!=="mouse"){return}setTooltipHoverTimeout(e,true)};e.onpointerleave=ev=>{if(ev.pointerType!=="mouse"){return}if(!e.TOOLTIP_FORCE_VISIBLE&&window.CURRENT_TOOLTIP_ELEMENT&&!window.CURRENT_TOOLTIP_ELEMENT.contains(ev.relatedTarget)){setTooltipHoverTimeout(e,false);addClass(window.CURRENT_TOOLTIP_ELEMENT,"fade-out")}}});const sidebar_menu_toggle=document.getElementsByClassName("sidebar-menu-toggle")[0];if(sidebar_menu_toggle){sidebar_menu_toggle.addEventListener("click",()=>{const sidebar=document.getElementsByClassName("sidebar")[0];if(!hasClass(sidebar,"shown")){showSidebar()}else{hideSidebar()}})}function helpBlurHandler(event){if(!getHelpButton().contains(document.activeElement)&&!getHelpButton().contains(event.relatedTarget)&&!getSettingsButton().contains(document.activeElement)&&!getSettingsButton().contains(event.relatedTarget)){window.hidePopoverMenus()}}function buildHelpMenu(){const book_info=document.createElement("span");const drloChannel=`https://doc.rust-lang.org/${getVar("channel")}`;book_info.className="top";book_info.innerHTML=`You can find more information in \
+the rustdoc book.`;const shortcuts=[["?","Show this help dialog"],["S / /","Focus the search field"],["↑","Move up in search results"],["↓","Move down in search results"],["← / →","Switch result tab (when results focused)"],["⏎","Go to active search result"],["+","Expand all sections"],["-","Collapse all sections"],].map(x=>"Keyboard Shortcuts
- "+shortcuts+"
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="Search Tricks
"+infos;const rustdoc_version=document.createElement("span");rustdoc_version.className="bottom";const rustdoc_version_code=document.createElement("code");rustdoc_version_code.innerText="rustdoc "+getVar("rustdoc-version");rustdoc_version.appendChild(rustdoc_version_code);const container=document.createElement("div");if(!isHelpPage){container.className="popover"}container.id="help";container.style.display="none";const side_by_side=document.createElement("div");side_by_side.className="side-by-side";side_by_side.appendChild(div_shortcuts);side_by_side.appendChild(div_infos);container.appendChild(book_info);container.appendChild(side_by_side);container.appendChild(rustdoc_version);if(isHelpPage){const help_section=document.createElement("section");help_section.appendChild(container);document.getElementById("main-content").appendChild(help_section);container.style.display="block"}else{const help_button=getHelpButton();help_button.appendChild(container);container.onblur=helpBlurHandler;help_button.onblur=helpBlurHandler;help_button.children[0].onblur=helpBlurHandler}return container}window.hideAllModals=switchFocus=>{hideSidebar();window.hidePopoverMenus();hideTooltip(switchFocus)};window.hidePopoverMenus=()=>{onEachLazy(document.querySelectorAll("rustdoc-toolbar .popover"),elem=>{elem.style.display="none"});const button=getHelpButton();if(button){removeClass(button,"help-open")}};function getHelpMenu(buildNeeded){let menu=getHelpButton().querySelector(".popover");if(!menu&&buildNeeded){menu=buildHelpMenu()}return menu}function showHelp(){const button=getHelpButton();addClass(button,"help-open");button.querySelector("a").focus();const menu=getHelpMenu(true);if(menu.style.display==="none"){window.hideAllModals();menu.style.display=""}}const helpLink=document.querySelector(`#${HELP_BUTTON_ID} > a`);if(isHelpPage){buildHelpMenu()}else if(helpLink){helpLink.addEventListener("click",event=>{if(!helpLink.contains(helpLink)||event.ctrlKey||event.altKey||event.metaKey){return}event.preventDefault();const menu=getHelpMenu(true);const shouldShowHelp=menu.style.display==="none";if(shouldShowHelp){showHelp()}else{window.hidePopoverMenus()}})}setMobileTopbar();addSidebarItems();addSidebarCrates();onHashChange(null);window.addEventListener("hashchange",onHashChange);searchState.setup()}());(function(){const SIDEBAR_MIN=100;const SIDEBAR_MAX=500;const RUSTDOC_MOBILE_BREAKPOINT=700;const BODY_MIN=400;const SIDEBAR_VANISH_THRESHOLD=SIDEBAR_MIN/2;const sidebarButton=document.getElementById("sidebar-button");if(sidebarButton){sidebarButton.addEventListener("click",e=>{removeClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","false");if(document.querySelector(".rustdoc.src")){window.rustdocToggleSrcSidebar()}e.preventDefault()})}let currentPointerId=null;let desiredSidebarSize=null;let pendingSidebarResizingFrame=false;const resizer=document.querySelector(".sidebar-resizer");const sidebar=document.querySelector(".sidebar");if(!resizer||!sidebar){return}const isSrcPage=hasClass(document.body,"src");const hideSidebar=function(){if(isSrcPage){window.rustdocCloseSourceSidebar();updateLocalStorage("src-sidebar-width",null);document.documentElement.style.removeProperty("--src-sidebar-width");sidebar.style.removeProperty("--src-sidebar-width");resizer.style.removeProperty("--src-sidebar-width")}else{addClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","true");updateLocalStorage("desktop-sidebar-width",null);document.documentElement.style.removeProperty("--desktop-sidebar-width");sidebar.style.removeProperty("--desktop-sidebar-width");resizer.style.removeProperty("--desktop-sidebar-width")}};const showSidebar=function(){if(isSrcPage){window.rustdocShowSourceSidebar()}else{removeClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","false")}};const changeSidebarSize=function(size){if(isSrcPage){updateLocalStorage("src-sidebar-width",size.toString());sidebar.style.setProperty("--src-sidebar-width",size+"px");resizer.style.setProperty("--src-sidebar-width",size+"px")}else{updateLocalStorage("desktop-sidebar-width",size.toString());sidebar.style.setProperty("--desktop-sidebar-width",size+"px");resizer.style.setProperty("--desktop-sidebar-width",size+"px")}};const isSidebarHidden=function(){return isSrcPage?!hasClass(document.documentElement,"src-sidebar-expanded"):hasClass(document.documentElement,"hide-sidebar")};const resize=function(e){if(currentPointerId===null||currentPointerId!==e.pointerId){return}e.preventDefault();const pos=e.clientX-3;if(pos\
+${item.alias} - see \
+
`}resultName.insertAdjacentHTML("beforeend",`${alias}\
+${item.displayPath}${name}\
+
`);const description=document.createElement("div");description.className="desc";description.insertAdjacentHTML("beforeend",item.desc);if(item.displayTypeSignature){const{type,mappedNames,whereClause}=await item.displayTypeSignature;const displayType=document.createElement("div");type.forEach((value,index)=>{if(index%2!==0){const highlight=document.createElement("strong");highlight.appendChild(document.createTextNode(value));displayType.appendChild(highlight)}else{displayType.appendChild(document.createTextNode(value))}});if(mappedNames.size>0||whereClause.size>0){let addWhereLineFn=()=>{const line=document.createElement("div");line.className="where";line.appendChild(document.createTextNode("where"));displayType.appendChild(line);addWhereLineFn=()=>{}};for(const[qname,name]of mappedNames){if(name===qname){continue}addWhereLineFn();const line=document.createElement("div");line.className="where";line.appendChild(document.createTextNode(` ${qname} matches `));const lineStrong=document.createElement("strong");lineStrong.appendChild(document.createTextNode(name));line.appendChild(lineStrong);displayType.appendChild(line)}for(const[name,innerType]of whereClause){if(innerType.length<=1){continue}addWhereLineFn();const line=document.createElement("div");line.className="where";line.appendChild(document.createTextNode(` ${name}: `));innerType.forEach((value,index)=>{if(index%2!==0){const highlight=document.createElement("strong");highlight.appendChild(document.createTextNode(value));line.appendChild(highlight)}else{line.appendChild(document.createTextNode(value))}});displayType.appendChild(line)}}displayType.className="type-signature";link.appendChild(displayType)}link.appendChild(description);return link}));lis.then(lis=>{for(const li of lis){output.appendChild(li)}})}else if(query.error===null){const dlroChannel=`https://doc.rust-lang.org/${getVar("channel")}`;output.className="search-failed"+extraClass;output.innerHTML="No results :("+"Try on DuckDuckGo?
"+"Or try looking in one of these:
- The Rust Reference `+" for technical details about the language.
- Rust By `+"Example for expository code examples.
- The Rust Book for `+"introductions to language features and the language itself.
- Docs.rs for documentation of crates released on"+" crates.io.
in
"}let output=`"+"
\
+
`;if(results.query.error!==null){const error=results.query.error;error.forEach((value,index)=>{value=value.split("<").join("<").split(">").join(">");if(index%2!==0){error[index]=`Results
${crates}${value.replaceAll(" ", " ")}`}else{error[index]=value}});output+=`Query parser error: "${error.join("")}".
`;output+=""+makeTabHeader(0,"In Names",results.others.length)+"
";currentTab=0}else if(results.query.foundElems<=1&&results.query.returned.length===0){output+=""+makeTabHeader(0,"In Names",results.others.length)+makeTabHeader(1,"In Parameters",results.in_args.length)+makeTabHeader(2,"In Return Types",results.returned.length)+"
"}else{const signatureTabTitle=results.query.elems.length===0?"In Function Return Types":results.query.returned.length===0?"In Function Parameters":"In Function Signatures";output+=""+makeTabHeader(0,signatureTabTitle,results.others.length)+"
";currentTab=0}if(results.query.correction!==null){const orig=results.query.returned.length>0?results.query.returned[0].name:results.query.elems[0].name;output+=""+`Type "${orig}" not found. `+"Showing results for closest type name "+`"${results.query.correction}" instead.
`}if(results.query.proposeCorrectionFrom!==null){const orig=results.query.proposeCorrectionFrom;const targ=results.query.proposeCorrectionTo;output+=""+`Type "${orig}" not found and used as generic parameter. `+`Consider searching for "${targ}" instead.
`}const[ret_others,ret_in_args,ret_returned]=await Promise.all([addTab(results.others,results.query,currentTab===0),addTab(results.in_args,results.query,currentTab===1),addTab(results.returned,results.query,currentTab===2),]);const resultsElem=document.createElement("div");resultsElem.id="results";resultsElem.appendChild(ret_others);resultsElem.appendChild(ret_in_args);resultsElem.appendChild(ret_returned);search.innerHTML=output;if(searchState.rustdocToolbar){search.querySelector(".main-heading").appendChild(searchState.rustdocToolbar)}const crateSearch=document.getElementById("crate-search");if(crateSearch){crateSearch.addEventListener("input",updateCrate)}search.appendChild(resultsElem);searchState.showResults(search);const elems=document.getElementById("search-tabs").childNodes;searchState.focusedByTab=[];let i=0;for(const elem of elems){const j=i;elem.onclick=()=>printTab(j);searchState.focusedByTab.push(null);i+=1}printTab(currentTab)}function updateSearchHistory(url){if(!browserSupportsHistoryApi()){return}const params=searchState.getQueryStringParams();if(!history.state&&!params.search){history.pushState(null,"",url)}else{history.replaceState(null,"",url)}}async function search(forced){const query=DocSearch.parseQuery(searchState.input.value.trim());let filterCrates=getFilterCrates();if(!forced&&query.userQuery===currentResults){if(query.userQuery.length>0){putBackSearch()}return}searchState.setLoadingSearch();const params=searchState.getQueryStringParams();if(filterCrates===null&¶ms["filter-crate"]!==undefined){filterCrates=params["filter-crate"]}searchState.title="\""+query.userQuery+"\" Search - Rust";updateSearchHistory(buildUrl(query.userQuery,filterCrates));await showResults(await docSearch.execQuery(query,filterCrates,window.currentCrate),params.go_to_first,filterCrates)}function onSearchSubmit(e){e.preventDefault();searchState.clearInputTimeout();search()}function putBackSearch(){const search_input=searchState.input;if(!searchState.input){return}if(search_input.value!==""&&!searchState.isDisplayed()){searchState.showResults();if(browserSupportsHistoryApi()){history.replaceState(null,"",buildUrl(search_input.value,getFilterCrates()))}document.title=searchState.title}}function registerSearchEvents(){const params=searchState.getQueryStringParams();if(searchState.input.value===""){searchState.input.value=params.search||""}const searchAfter500ms=()=>{searchState.clearInputTimeout();if(searchState.input.value.length===0){searchState.hideResults()}else{searchState.timeout=setTimeout(search,500)}};searchState.input.onkeyup=searchAfter500ms;searchState.input.oninput=searchAfter500ms;document.getElementsByClassName("search-form")[0].onsubmit=onSearchSubmit;searchState.input.onchange=e=>{if(e.target!==document.activeElement){return}searchState.clearInputTimeout();setTimeout(search,0)};searchState.input.onpaste=searchState.input.onchange;searchState.outputElement().addEventListener("keydown",e=>{if(e.altKey||e.ctrlKey||e.shiftKey||e.metaKey){return}if(e.which===38){const previous=document.activeElement.previousElementSibling;if(previous){previous.focus()}else{searchState.focus()}e.preventDefault()}else if(e.which===40){const next=document.activeElement.nextElementSibling;if(next){next.focus()}const rect=document.activeElement.getBoundingClientRect();if(window.innerHeight-rect.bottom";continue}const js_data_name=setting["js_name"];const setting_name=setting["name"];if(setting["options"]!==undefined){output+=`\ +
+
`}else{const checked=setting["default"]===true?" checked":"";output+=`\
+${setting_name}
+ `;onEach(setting["options"],option=>{const checked=option===setting["default"]?" checked":"";const full=`${js_data_name}-${option.replace(/ /g,"-")}`;output+=`\
+ `});output+=`\
+
+\
+ \
+
`}}return output}function buildSettingsPage(){const theme_names=getVar("themes").split(",").filter(t=>t);theme_names.push("light","dark","ayu");const settings=[{"name":"Theme","js_name":"theme","default":"system preference","options":theme_names.concat("system preference"),},{"name":"Preferred light theme","js_name":"preferred-light-theme","default":"light","options":theme_names,},{"name":"Preferred dark theme","js_name":"preferred-dark-theme","default":"dark","options":theme_names,},{"name":"Auto-hide item contents for large items","js_name":"auto-hide-large-items","default":true,},{"name":"Auto-hide item methods' documentation","js_name":"auto-hide-method-docs","default":false,},{"name":"Auto-hide trait implementation documentation","js_name":"auto-hide-trait-implementations","default":false,},{"name":"Directly go to item in search if there is only one result","js_name":"go-to-only-result","default":false,},{"name":"Show line numbers on code examples","js_name":"line-numbers","default":false,},{"name":"Hide persistent navigation bar","js_name":"hide-sidebar","default":false,},{"name":"Hide table of contents","js_name":"hide-toc","default":false,},{"name":"Hide module navigation","js_name":"hide-modnav","default":false,},{"name":"Disable keyboard shortcuts","js_name":"disable-shortcuts","default":false,},{"name":"Use sans serif fonts","js_name":"sans-serif-fonts","default":false,},];const elementKind=isSettingsPage?"section":"div";const innerHTML=`${buildSettingsPageSections(settings)}
`;const el=document.createElement(elementKind);el.id="settings";if(!isSettingsPage){el.className="popover"}el.innerHTML=innerHTML;if(isSettingsPage){document.getElementById(MAIN_ID).appendChild(el)}else{el.setAttribute("tabindex","-1");getSettingsButton().appendChild(el)}return el}const settingsMenu=buildSettingsPage();function displaySettings(){settingsMenu.style.display="";onEachLazy(settingsMenu.querySelectorAll("input[type='checkbox']"),el=>{const val=getSettingValue(el.id);const checked=val==="true";if(checked!==el.checked&&val!==null){el.checked=checked}})}function settingsBlurHandler(event){if(!getHelpButton().contains(document.activeElement)&&!getHelpButton().contains(event.relatedTarget)&&!getSettingsButton().contains(document.activeElement)&&!getSettingsButton().contains(event.relatedTarget)){window.hidePopoverMenus()}}if(!isSettingsPage){const settingsButton=getSettingsButton();const settingsMenu=document.getElementById("settings");settingsButton.onclick=event=>{if(settingsMenu.contains(event.target)){return}event.preventDefault();const shouldDisplaySettings=settingsMenu.style.display==="none";window.hideAllModals();if(shouldDisplaySettings){displaySettings()}};settingsButton.onblur=settingsBlurHandler;settingsButton.querySelector("a").onblur=settingsBlurHandler;onEachLazy(settingsMenu.querySelectorAll("input"),el=>{el.onblur=settingsBlurHandler});settingsMenu.onblur=settingsBlurHandler}setTimeout(()=>{setEvents(settingsMenu);if(!isSettingsPage){displaySettings()}removeClass(getSettingsButton(),"rotate")},0)})()
\ No newline at end of file
diff --git a/crates/doc/static.files/src-script-8fee9dc5.js b/crates/doc/static.files/src-script-8fee9dc5.js
new file mode 100644
index 000000000000..d0aebb85103b
--- /dev/null
+++ b/crates/doc/static.files/src-script-8fee9dc5.js
@@ -0,0 +1 @@
+"use strict";(function(){const rootPath=getVar("root-path");const NAME_OFFSET=0;const DIRS_OFFSET=1;const FILES_OFFSET=2;const RUSTDOC_MOBILE_BREAKPOINT=700;function closeSidebarIfMobile(){if(window.innerWidthwhere\n T: Freeze,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> Freeze for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[2585]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/marker/trait.Send.js b/crates/doc/trait.impl/core/marker/trait.Send.js
new file mode 100644
index 000000000000..b4d28b361cb7
--- /dev/null
+++ b/crates/doc/trait.impl/core/marker/trait.Send.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl Send for AllocationStatus",1,["kani::arbitrary_ptr::AllocationStatus"]],["impl Send for SchedulingAssumption",1,["kani::futures::SchedulingAssumption"]],["impl Send for JoinHandle",1,["kani::futures::JoinHandle"]],["impl Send for RoundRobin",1,["kani::futures::RoundRobin"]],["impl<'a, T> !Send for ArbitraryPointer<'a, T>",1,["kani::arbitrary_ptr::ArbitraryPointer"]],["impl<T> Send for ShadowMem<T>where\n T: Send,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> Send for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[2538]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/marker/trait.StructuralPartialEq.js b/crates/doc/trait.impl/core/marker/trait.StructuralPartialEq.js
new file mode 100644
index 000000000000..38e560f44448
--- /dev/null
+++ b/crates/doc/trait.impl/core/marker/trait.StructuralPartialEq.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl StructuralPartialEq for AllocationStatus"]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[320]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/marker/trait.Sync.js b/crates/doc/trait.impl/core/marker/trait.Sync.js
new file mode 100644
index 000000000000..1932c9b3ad72
--- /dev/null
+++ b/crates/doc/trait.impl/core/marker/trait.Sync.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl Sync for AllocationStatus",1,["kani::arbitrary_ptr::AllocationStatus"]],["impl Sync for SchedulingAssumption",1,["kani::futures::SchedulingAssumption"]],["impl Sync for JoinHandle",1,["kani::futures::JoinHandle"]],["impl Sync for RoundRobin",1,["kani::futures::RoundRobin"]],["impl<'a, T> !Sync for ArbitraryPointer<'a, T>",1,["kani::arbitrary_ptr::ArbitraryPointer"]],["impl<T> Sync for ShadowMem<T>where\n T: Sync,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> Sync for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[2538]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/marker/trait.Unpin.js b/crates/doc/trait.impl/core/marker/trait.Unpin.js
new file mode 100644
index 000000000000..101c4bcae76e
--- /dev/null
+++ b/crates/doc/trait.impl/core/marker/trait.Unpin.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl Unpin for AllocationStatus",1,["kani::arbitrary_ptr::AllocationStatus"]],["impl Unpin for SchedulingAssumption",1,["kani::futures::SchedulingAssumption"]],["impl Unpin for JoinHandle",1,["kani::futures::JoinHandle"]],["impl Unpin for RoundRobin",1,["kani::futures::RoundRobin"]],["impl<'a, T> Unpin for ArbitraryPointer<'a, T>",1,["kani::arbitrary_ptr::ArbitraryPointer"]],["impl<T> Unpin for ShadowMem<T>where\n T: Unpin,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> Unpin for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[2561]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js b/crates/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js
new file mode 100644
index 000000000000..fb339510a6e2
--- /dev/null
+++ b/crates/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl RefUnwindSafe for AllocationStatus",1,["kani::arbitrary_ptr::AllocationStatus"]],["impl RefUnwindSafe for SchedulingAssumption",1,["kani::futures::SchedulingAssumption"]],["impl RefUnwindSafe for JoinHandle",1,["kani::futures::JoinHandle"]],["impl RefUnwindSafe for RoundRobin",1,["kani::futures::RoundRobin"]],["impl<'a, T> RefUnwindSafe for ArbitraryPointer<'a, T>where\n T: RefUnwindSafe,
",1,["kani::arbitrary_ptr::ArbitraryPointer"]],["impl<T> RefUnwindSafe for ShadowMem<T>where\n T: RefUnwindSafe,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> RefUnwindSafe for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[3162]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js b/crates/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js
new file mode 100644
index 000000000000..296bd8466eff
--- /dev/null
+++ b/crates/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[["impl UnwindSafe for AllocationStatus",1,["kani::arbitrary_ptr::AllocationStatus"]],["impl UnwindSafe for SchedulingAssumption",1,["kani::futures::SchedulingAssumption"]],["impl UnwindSafe for JoinHandle",1,["kani::futures::JoinHandle"]],["impl UnwindSafe for RoundRobin",1,["kani::futures::RoundRobin"]],["impl<'a, T> UnwindSafe for ArbitraryPointer<'a, T>where\n T: RefUnwindSafe,
",1,["kani::arbitrary_ptr::ArbitraryPointer"]],["impl<T> UnwindSafe for ShadowMem<T>where\n T: UnwindSafe,
",1,["kani::shadow::ShadowMem"]],["impl<const BYTES: usize> UnwindSafe for PointerGenerator<BYTES>",1,["kani::arbitrary_ptr::PointerGenerator"]]]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[3090]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/kani/futures/trait.SchedulingStrategy.js b/crates/doc/trait.impl/kani/futures/trait.SchedulingStrategy.js
new file mode 100644
index 000000000000..d9cb395c1279
--- /dev/null
+++ b/crates/doc/trait.impl/kani/futures/trait.SchedulingStrategy.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[11]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/kani/invariant/trait.Invariant.js b/crates/doc/trait.impl/kani/invariant/trait.Invariant.js
new file mode 100644
index 000000000000..d9cb395c1279
--- /dev/null
+++ b/crates/doc/trait.impl/kani/invariant/trait.Invariant.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[11]}
\ No newline at end of file
diff --git a/crates/doc/trait.impl/kani/trait.Arbitrary.js b/crates/doc/trait.impl/kani/trait.Arbitrary.js
new file mode 100644
index 000000000000..d9cb395c1279
--- /dev/null
+++ b/crates/doc/trait.impl/kani/trait.Arbitrary.js
@@ -0,0 +1,9 @@
+(function() {
+ var implementors = Object.fromEntries([["kani",[]]]);
+ if (window.register_implementors) {
+ window.register_implementors(implementors);
+ } else {
+ window.pending_implementors = implementors;
+ }
+})()
+//{"start":57,"fragment_lengths":[11]}
\ No newline at end of file
diff --git a/crates/index.html b/crates/index.html
new file mode 100644
index 000000000000..3a397e6adec0
--- /dev/null
+++ b/crates/index.html
@@ -0,0 +1,192 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/css/chrome.css b/css/chrome.css
new file mode 100644
index 000000000000..21c08b930f04
--- /dev/null
+++ b/css/chrome.css
@@ -0,0 +1,495 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+::-webkit-scrollbar {
+ background: var(--bg);
+}
+::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+html {
+ scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+ color: var(--links);
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+ z-index: 101;
+ margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+ position: relative;
+ display: flex;
+ flex-wrap: wrap;
+ background-color: var(--bg);
+ border-bottom-color: var(--bg);
+ border-bottom-width: 1px;
+ border-bottom-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+ position: -webkit-sticky;
+ position: sticky;
+ top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+ position: sticky;
+ position: -webkit-sticky;
+ top: 0;
+ height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+ border-bottom-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+ position: relative;
+ padding: 0 8px;
+ z-index: 10;
+ line-height: var(--menu-bar-height);
+ cursor: pointer;
+ transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+ #menu-bar i, #menu-bar .icon-button {
+ padding: 0 5px;
+ }
+}
+
+.icon-button {
+ border: none;
+ background: none;
+ padding: 0;
+ color: inherit;
+}
+.icon-button i {
+ margin: 0;
+}
+
+.right-buttons {
+ margin: 0 15px;
+}
+.right-buttons a {
+ text-decoration: none;
+}
+
+.left-buttons {
+ display: flex;
+ margin: 0 5px;
+}
+.no-js .left-buttons {
+ display: none;
+}
+
+.menu-title {
+ display: inline-block;
+ font-weight: 200;
+ font-size: 2.4rem;
+ line-height: var(--menu-bar-height);
+ text-align: center;
+ margin: 0;
+ flex: 1;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.js .menu-title {
+ cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+ color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+ color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+
+ position: fixed;
+ top: 0;
+ bottom: 0;
+ margin: 0;
+ max-width: 150px;
+ min-width: 90px;
+
+ display: flex;
+ justify-content: center;
+ align-content: center;
+ flex-direction: column;
+
+ transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+ text-decoration: none;
+ background-color: var(--theme-hover);
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+ margin-top: 50px;
+ display: none;
+}
+
+.mobile-nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+ width: 90px;
+ border-radius: 5px;
+ background-color: var(--sidebar-bg);
+}
+
+.previous {
+ float: left;
+}
+
+.next {
+ float: right;
+ right: var(--page-padding);
+}
+
+@media only screen and (max-width: 1080px) {
+ .nav-wide-wrapper { display: none; }
+ .nav-wrapper { display: block; }
+}
+
+@media only screen and (max-width: 1380px) {
+ .sidebar-visible .nav-wide-wrapper { display: none; }
+ .sidebar-visible .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+ display: inline;
+ padding: 0.1em 0.3em;
+ border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+ color: var(--inline-code-color);
+ overflow-x: initial;
+}
+
+a:hover > .hljs {
+ text-decoration: underline;
+}
+
+pre {
+ position: relative;
+}
+pre > .buttons {
+ position: absolute;
+ z-index: 100;
+ right: 5px;
+ top: 5px;
+
+ color: var(--sidebar-fg);
+ cursor: pointer;
+}
+pre > .buttons :hover {
+ color: var(--sidebar-active);
+}
+pre > .buttons i {
+ margin-left: 8px;
+}
+pre > .buttons button {
+ color: inherit;
+ background: transparent;
+ border: none;
+ cursor: inherit;
+}
+pre > .result {
+ margin-top: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+ text-decoration: none;
+}
+
+mark {
+ border-radius: 2px;
+ padding: 0 3px 1px 3px;
+ margin: 0 -3px -1px -3px;
+ background-color: var(--search-mark-bg);
+ transition: background-color 300ms linear;
+ cursor: pointer;
+}
+
+mark.fade-out {
+ background-color: rgba(0,0,0,0) !important;
+ cursor: auto;
+}
+
+.searchbar-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+
+#searchbar {
+ width: 100%;
+ margin: 5px auto 0px auto;
+ padding: 10px 16px;
+ transition: box-shadow 300ms ease-in-out;
+ border: 1px solid var(--searchbar-border-color);
+ border-radius: 3px;
+ background-color: var(--searchbar-bg);
+ color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+ box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+ font-weight: bold;
+ font-size: 1em;
+ padding: 18px 0 0 5px;
+ color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+ border-bottom: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+ list-style: none;
+ padding-left: 20px;
+}
+ul#searchresults li {
+ margin: 10px 0px;
+ padding: 2px;
+ border-radius: 2px;
+}
+ul#searchresults li.focus {
+ background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+ display: block;
+ clear: both;
+ margin: 5px 0 0 20px;
+ font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+ font-weight: bold;
+ font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+ position: fixed;
+ left: 0;
+ top: 0;
+ bottom: 0;
+ width: var(--sidebar-width);
+ font-size: 0.875em;
+ box-sizing: border-box;
+ -webkit-overflow-scrolling: touch;
+ overscroll-behavior-y: contain;
+ background-color: var(--sidebar-bg);
+ color: var(--sidebar-fg);
+}
+.sidebar-resizing {
+ -moz-user-select: none;
+ -webkit-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.js:not(.sidebar-resizing) .sidebar {
+ transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+ line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+ overflow-y: auto;
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ left: 0;
+ right: 0;
+ padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+ position: absolute;
+ cursor: col-resize;
+ width: 0;
+ right: 0;
+ top: 0;
+ bottom: 0;
+}
+.js .sidebar .sidebar-resize-handle {
+ cursor: col-resize;
+ width: 5px;
+}
+.sidebar-hidden .sidebar {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+}
+.sidebar::-webkit-scrollbar {
+ background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+
+.sidebar-visible .page-wrapper {
+ transform: translateX(var(--sidebar-width));
+}
+@media only screen and (min-width: 620px) {
+ .sidebar-visible .page-wrapper {
+ transform: none;
+ margin-left: var(--sidebar-width);
+ }
+}
+
+.chapter {
+ list-style: none outside none;
+ padding-left: 0;
+ line-height: 2.2em;
+}
+
+.chapter ol {
+ width: 100%;
+}
+
+.chapter li {
+ display: flex;
+ color: var(--sidebar-non-existant);
+}
+.chapter li a {
+ display: block;
+ padding: 0;
+ text-decoration: none;
+ color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+ color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+ color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+ cursor: pointer;
+ display: block;
+ margin-left: auto;
+ padding: 0 10px;
+ user-select: none;
+ opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+ transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+ display: none;
+}
+
+.chapter li.chapter-item {
+ line-height: 1.5em;
+ margin-top: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+ transform: rotate(90deg);
+}
+
+.spacer {
+ width: 100%;
+ height: 3px;
+ margin: 5px 0px;
+}
+.chapter .spacer {
+ background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+ .chapter li a { padding: 5px 0; }
+ .spacer { margin: 10px 0; }
+}
+
+.section {
+ list-style: none outside none;
+ padding-left: 20px;
+ line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+ position: absolute;
+ left: 10px;
+ top: var(--menu-bar-height);
+ z-index: 1000;
+ border-radius: 4px;
+ font-size: 0.7em;
+ color: var(--fg);
+ background: var(--theme-popup-bg);
+ border: 1px solid var(--theme-popup-border);
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: none;
+}
+.theme-popup .default {
+ color: var(--icons);
+}
+.theme-popup .theme {
+ width: 100%;
+ border: 0;
+ margin: 0;
+ padding: 2px 10px;
+ line-height: 25px;
+ white-space: nowrap;
+ text-align: left;
+ cursor: pointer;
+ color: inherit;
+ background: inherit;
+ font-size: inherit;
+}
+.theme-popup .theme:hover {
+ background-color: var(--theme-hover);
+}
+.theme-popup .theme:hover:first-child,
+.theme-popup .theme:hover:last-child {
+ border-top-left-radius: inherit;
+ border-top-right-radius: inherit;
+}
diff --git a/css/general.css b/css/general.css
new file mode 100644
index 000000000000..ef2ba5048917
--- /dev/null
+++ b/css/general.css
@@ -0,0 +1,182 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+ /* Browser default font-size is 16px, this way 1 rem = 10px */
+ font-size: 62.5%;
+}
+
+html {
+ font-family: "Open Sans", sans-serif;
+ color: var(--fg);
+ background-color: var(--bg);
+ text-size-adjust: none;
+ -webkit-text-size-adjust: none;
+}
+
+body {
+ margin: 0;
+ font-size: 1.6rem;
+ overflow-x: hidden;
+}
+
+code {
+ font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important;
+ font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-top: 2.5em; }
+h4, h5 { margin-top: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+ margin-top: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+ display: inline-block;
+ content: "»";
+ margin-left: -30px;
+ width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+ in Safari Technology Preview 117 which I think will be Safari 14.2.
+ https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+ scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+ outline: 0;
+ padding: 0 var(--page-padding);
+ margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+ box-sizing: border-box;
+}
+.js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+ overflow-y: auto;
+ padding: 0 15px;
+ padding-bottom: 50px;
+}
+.content main {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+ color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+ text-decoration: none;
+}
+
+table {
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+table td {
+ padding: 3px 20px;
+ border: 1px var(--table-border-color) solid;
+}
+table thead {
+ background: var(--table-header-bg);
+}
+table thead td {
+ font-weight: 700;
+ border: none;
+}
+table thead th {
+ padding: 3px 20px;
+}
+table thead tr {
+ border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+ background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+ margin: 20px 0;
+ padding: 0 20px;
+ color: var(--fg);
+ background-color: var(--quote-bg);
+ border-top: .1em solid var(--quote-border);
+ border-bottom: .1em solid var(--quote-border);
+}
+
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+ margin-top: 2em;
+}
+.footnote-definition {
+ font-size: 0.9em;
+ margin: 0.5em 0;
+}
+.footnote-definition p {
+ display: inline;
+}
+
+.tooltiptext {
+ position: absolute;
+ visibility: hidden;
+ color: #fff;
+ background-color: #333;
+ transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+ left: -8px; /* Half of the width of the icon */
+ top: -35px;
+ font-size: 0.8em;
+ text-align: center;
+ border-radius: 6px;
+ padding: 5px 8px;
+ margin: 5px;
+ z-index: 1000;
+}
+.tooltipped .tooltiptext {
+ visibility: visible;
+}
+
+.chapter li.part-title {
+ color: var(--sidebar-fg);
+ margin: 5px 0px;
+ font-weight: bold;
+}
+
+.result-no-output {
+ font-style: italic;
+}
diff --git a/css/print.css b/css/print.css
new file mode 100644
index 000000000000..5e690f755994
--- /dev/null
+++ b/css/print.css
@@ -0,0 +1,54 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+ display: none;
+}
+
+#page-wrapper.page-wrapper {
+ transform: none;
+ margin-left: 0px;
+ overflow-y: initial;
+}
+
+#content {
+ max-width: none;
+ margin: 0;
+ padding: 0;
+}
+
+.page {
+ overflow-y: initial;
+}
+
+code {
+ background-color: #666666;
+ border-radius: 5px;
+
+ /* Force background to be printed in Chrome */
+ -webkit-print-color-adjust: exact;
+}
+
+pre > .buttons {
+ z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+ color: #4183c4;
+ text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ page-break-inside: avoid;
+ page-break-after: avoid;
+}
+
+pre, code {
+ page-break-inside: avoid;
+ white-space: pre-wrap;
+}
+
+.fa {
+ display: none !important;
+}
diff --git a/css/variables.css b/css/variables.css
new file mode 100644
index 000000000000..56b634bc3766
--- /dev/null
+++ b/css/variables.css
@@ -0,0 +1,253 @@
+
+/* Globals */
+
+:root {
+ --sidebar-width: 300px;
+ --page-padding: 15px;
+ --content-max-width: 750px;
+ --menu-bar-height: 50px;
+}
+
+/* Themes */
+
+.ayu {
+ --bg: hsl(210, 25%, 8%);
+ --fg: #c5c5c5;
+
+ --sidebar-bg: #14191f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #5c6773;
+ --sidebar-active: #ffb454;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #0096cf;
+
+ --inline-code-color: #ffb454;
+
+ --theme-popup-bg: #14191f;
+ --theme-popup-border: #5c6773;
+ --theme-hover: #191f26;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(210, 25%, 13%);
+ --table-header-bg: hsl(210, 25%, 28%);
+ --table-alternate-bg: hsl(210, 25%, 11%);
+
+ --searchbar-border-color: #848484;
+ --searchbar-bg: #424242;
+ --searchbar-fg: #fff;
+ --searchbar-shadow-color: #d4c89f;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #252932;
+ --search-mark-bg: #e3b171;
+}
+
+.coal {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+}
+
+.light {
+ --bg: hsl(0, 0%, 100%);
+ --fg: hsl(0, 0%, 0%);
+
+ --sidebar-bg: #fafafa;
+ --sidebar-fg: hsl(0, 0%, 0%);
+ --sidebar-non-existant: #aaaaaa;
+ --sidebar-active: #1f1fff;
+ --sidebar-spacer: #f4f4f4;
+
+ --scrollbar: #8F8F8F;
+
+ --icons: #747474;
+ --icons-hover: #000000;
+
+ --links: #20609f;
+
+ --inline-code-color: #301900;
+
+ --theme-popup-bg: #fafafa;
+ --theme-popup-border: #cccccc;
+ --theme-hover: #e6e6e6;
+
+ --quote-bg: hsl(197, 37%, 96%);
+ --quote-border: hsl(197, 37%, 91%);
+
+ --table-border-color: hsl(0, 0%, 95%);
+ --table-header-bg: hsl(0, 0%, 80%);
+ --table-alternate-bg: hsl(0, 0%, 97%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #e4f2fe;
+ --search-mark-bg: #a2cff5;
+}
+
+.navy {
+ --bg: hsl(226, 23%, 11%);
+ --fg: #bcbdd0;
+
+ --sidebar-bg: #282d3f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505274;
+ --sidebar-active: #2b79a2;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #161923;
+ --theme-popup-border: #737480;
+ --theme-hover: #282e40;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(226, 23%, 16%);
+ --table-header-bg: hsl(226, 23%, 31%);
+ --table-alternate-bg: hsl(226, 23%, 14%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #aeaec6;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #5f5f71;
+ --searchresults-border-color: #5c5c68;
+ --searchresults-li-bg: #242430;
+ --search-mark-bg: #a2cff5;
+}
+
+.rust {
+ --bg: hsl(60, 9%, 87%);
+ --fg: #262625;
+
+ --sidebar-bg: #3b2e2a;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #e69f67;
+ --sidebar-spacer: #45373a;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #262625;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #6e6b5e;
+
+ --theme-popup-bg: #e1e1db;
+ --theme-popup-border: #b38f6b;
+ --theme-hover: #99908a;
+
+ --quote-bg: hsl(60, 5%, 75%);
+ --quote-border: hsl(60, 5%, 70%);
+
+ --table-border-color: hsl(60, 9%, 82%);
+ --table-header-bg: #b3a497;
+ --table-alternate-bg: hsl(60, 9%, 84%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #dec2a2;
+ --search-mark-bg: #e69f67;
+}
+
+@media (prefers-color-scheme: dark) {
+ .light.no-js {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+ }
+}
diff --git a/dev-assess.html b/dev-assess.html
new file mode 100644
index 000000000000..46da07cef3c8
--- /dev/null
+++ b/dev-assess.html
@@ -0,0 +1,318 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Crates documentation
+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:
+-
+
- kani: This crate +provide APIs to write Kani harnesses. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/dev-documentation.html b/dev-documentation.html
new file mode 100644
index 000000000000..a3d80c5e21f4
--- /dev/null
+++ b/dev-documentation.html
@@ -0,0 +1,204 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ cargo kani assess
+Assess 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:
+-
+
- Does Kani successfully build all of the crates involved in this project? If not, why not? +
- Does Kani support all the Rust language features necessary to do verification with this project? If not, which are most important? +
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:
+-
+
- Is this project ready for verification? Projects need to be reasonably well-tested first. +Our operating hypothesis is that code currently covered by unit tests is the code that could become covered by proofs. +
- How much of given project (consisting of multiple packages or workspaces) or which of the user's projects might be verifiable? +If a user wants to start trying Kani, but they have the choice of several different packages where they might try, we can help find the package with the lowest hanging fruit. +
- Given a package, where in that package's code should the user look, in order to write the first (or next) proof? +
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.
+Using Assess
+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.)
What assess does
+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.
Current Assess Results
+Assess produces a few tables of output (both visually in the terminal, and in a more detailed json format) so far:
+Unsupported features
+======================================================
+ 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:
+-
+
- "Crates impacted" here means "packages in the current workspace (or scan) where the building of that package (and all of its dependencies) ultimately resulted in this warning."
+For example, if only assessing a single package (not a workspace) this could only be
1in this column, regardless of the number of dependencies.
+ - "Instances of use" likewise means "total instances found while compiling this package's tests and all the (reachable) code in its dependencies." +
- These counts are influenced by (static) reachability: if code is not potentially reachable from a test somehow, it will not be built and will not be counted. +
Test failure reasons
+================================================
+ 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:
+-
+
- Because we force termination with
unwind(1), we expectunwindto rank highly.
+ - We do report number of tests succeeding on this table, to aid understanding how well things went overall. +
- The reported reason is the "property class" of the CBMC property that failed. So
assertionmeans an ordinaryassert!()was hit (or something else with this property class).
+ - When multiple properties fail, they are aggregated with
+, such asassertion + overflow.
+ - Currently this table does not properly account for
should_failtests, soassertionmay actually be "success": the test should hit an assertion and did.
+
Promising test cases
+=============================================================================
+ 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).
+How Assess Works
+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:
-
+
- With
--all-featuresturned on
+ - With
unwindalways set to1
+ - In test mode, i.e.
--tests
+ - With test-case reachability mode. Normally Kani looks for proof harnesses and builds only those. Here we switch to building only the test harnesses instead. +
Assess 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.
Using Assess on the top-100 crates
+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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/elasticlunr.min.js b/elasticlunr.min.js
new file mode 100644
index 000000000000..94b20dd2ef46
--- /dev/null
+++ b/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Developer documentation
+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):
+-
+
- Coding conventions. +
- Useful command-line instructions for Kani/CBMC/Git. +
- Development setup recommendations for working with
cbmc.
+ - Development setup recommendations for working with
rustc.
+ - Guide for testing in Kani. +
- Transition to StableMIR. +
++ +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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/favicon.png b/favicon.png
new file mode 100644
index 000000000000..a5b1aa16c4dc
Binary files /dev/null and b/favicon.png differ
diff --git a/favicon.svg b/favicon.svg
new file mode 100644
index 000000000000..90e0ea58bdb1
--- /dev/null
+++ b/favicon.svg
@@ -0,0 +1,22 @@
+
+
diff --git a/fonts/OPEN-SANS-LICENSE.txt b/fonts/OPEN-SANS-LICENSE.txt
new file mode 100644
index 000000000000..d64569567334
--- /dev/null
+++ b/fonts/OPEN-SANS-LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/fonts/SOURCE-CODE-PRO-LICENSE.txt b/fonts/SOURCE-CODE-PRO-LICENSE.txt
new file mode 100644
index 000000000000..366206f54950
--- /dev/null
+++ b/fonts/SOURCE-CODE-PRO-LICENSE.txt
@@ -0,0 +1,93 @@
+Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/fonts/fonts.css b/fonts/fonts.css
new file mode 100644
index 000000000000..858efa59800b
--- /dev/null
+++ b/fonts/fonts.css
@@ -0,0 +1,100 @@
+/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
+/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
+
+/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 300;
+ src: local('Open Sans Light'), local('OpenSans-Light'),
+ url('open-sans-v17-all-charsets-300.woff2') format('woff2');
+}
+
+/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 300;
+ src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
+ url('open-sans-v17-all-charsets-300italic.woff2') format('woff2');
+}
+
+/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 400;
+ src: local('Open Sans Regular'), local('OpenSans-Regular'),
+ url('open-sans-v17-all-charsets-regular.woff2') format('woff2');
+}
+
+/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 400;
+ src: local('Open Sans Italic'), local('OpenSans-Italic'),
+ url('open-sans-v17-all-charsets-italic.woff2') format('woff2');
+}
+
+/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 600;
+ src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
+ url('open-sans-v17-all-charsets-600.woff2') format('woff2');
+}
+
+/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 600;
+ src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
+ url('open-sans-v17-all-charsets-600italic.woff2') format('woff2');
+}
+
+/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 700;
+ src: local('Open Sans Bold'), local('OpenSans-Bold'),
+ url('open-sans-v17-all-charsets-700.woff2') format('woff2');
+}
+
+/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 700;
+ src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
+ url('open-sans-v17-all-charsets-700italic.woff2') format('woff2');
+}
+
+/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
+ url('open-sans-v17-all-charsets-800.woff2') format('woff2');
+}
+
+/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
+ url('open-sans-v17-all-charsets-800italic.woff2') format('woff2');
+}
+
+/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Source Code Pro';
+ font-style: normal;
+ font-weight: 500;
+ src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2');
+}
diff --git a/fonts/open-sans-v17-all-charsets-300.woff2 b/fonts/open-sans-v17-all-charsets-300.woff2
new file mode 100644
index 000000000000..9f51be370fa9
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-300.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-300italic.woff2 b/fonts/open-sans-v17-all-charsets-300italic.woff2
new file mode 100644
index 000000000000..2f545448418c
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-300italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-600.woff2 b/fonts/open-sans-v17-all-charsets-600.woff2
new file mode 100644
index 000000000000..f503d558d58d
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-600.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-600italic.woff2 b/fonts/open-sans-v17-all-charsets-600italic.woff2
new file mode 100644
index 000000000000..c99aabe80340
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-600italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-700.woff2 b/fonts/open-sans-v17-all-charsets-700.woff2
new file mode 100644
index 000000000000..421a1ab25fa8
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-700.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-700italic.woff2 b/fonts/open-sans-v17-all-charsets-700italic.woff2
new file mode 100644
index 000000000000..12ce3d20d1ce
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-700italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-800.woff2 b/fonts/open-sans-v17-all-charsets-800.woff2
new file mode 100644
index 000000000000..c94a223b0332
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-800.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-800italic.woff2 b/fonts/open-sans-v17-all-charsets-800italic.woff2
new file mode 100644
index 000000000000..eed7d3c63d1f
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-800italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-italic.woff2 b/fonts/open-sans-v17-all-charsets-italic.woff2
new file mode 100644
index 000000000000..398b68a0853f
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-regular.woff2 b/fonts/open-sans-v17-all-charsets-regular.woff2
new file mode 100644
index 000000000000..8383e94c6547
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-regular.woff2 differ
diff --git a/fonts/source-code-pro-v11-all-charsets-500.woff2 b/fonts/source-code-pro-v11-all-charsets-500.woff2
new file mode 100644
index 000000000000..722245682f59
Binary files /dev/null and b/fonts/source-code-pro-v11-all-charsets-500.woff2 differ
diff --git a/getting-started.html b/getting-started.html
new file mode 100644
index 000000000000..d30f3bceafec
--- /dev/null
+++ b/getting-started.html
@@ -0,0 +1,195 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ FAQs
+This section collects frequently asked questions about Kani. +Please consider opening an issue if you have a question that would like to see here.
+Questions
+
+Kani doesn't fail after
+
+
+Kani doesn't fail after 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.
+I implemented the
+
+
+
+ I implemented the 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:
-
+
- Importing a copy of the external crate that defines the type, then implement
Arbitrarythere.
+ - Contributing the
Arbitraryimplementation to the external crate that defines the type.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/getting-started/verification-results/Cargo.toml b/getting-started/verification-results/Cargo.toml
new file mode 100644
index 000000000000..896ce98400a0
--- /dev/null
+++ b/getting-started/verification-results/Cargo.toml
@@ -0,0 +1,14 @@
+# Copyright Kani Contributors
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+[package]
+name = "result-types"
+version = "0.1.0"
+edition = "2018"
+
+[dependencies]
+
+[workspace]
+
+[package.metadata.kani]
+flags = {output-format = "regular"}
diff --git a/getting-started/verification-results/failure_example.expected b/getting-started/verification-results/failure_example.expected
new file mode 100644
index 000000000000..7df34043cdf7
--- /dev/null
+++ b/getting-started/verification-results/failure_example.expected
@@ -0,0 +1,2 @@
+FAILURE\
+Description: "assertion failed: arr.len() != 3"
diff --git a/getting-started/verification-results/src/main.rs b/getting-started/verification-results/src/main.rs
new file mode 100644
index 000000000000..7a03b34f0f9e
--- /dev/null
+++ b/getting-started/verification-results/src/main.rs
@@ -0,0 +1,96 @@
+// Copyright Kani Contributors
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#[kani::proof]
+// ANCHOR: success_example
+fn success_example() {
+ let mut sum = 0;
+ for i in 1..4 {
+ sum += i;
+ }
+ assert_eq!(sum, 6);
+}
+// ANCHOR_END: success_example
+
+#[kani::proof]
+// ANCHOR: failure_example
+fn failure_example() {
+ let arr = [1, 2, 3];
+ assert_ne!(arr.len(), 3);
+}
+// ANCHOR_END: failure_example
+
+#[kani::proof]
+// ANCHOR: unreachable_example
+fn unreachable_example() {
+ let x = 5;
+ let y = x + 2;
+ if x > y {
+ assert!(x < 8);
+ }
+}
+// ANCHOR_END: unreachable_example
+
+#[kani::proof]
+// ANCHOR: undetermined_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");
+ }
+}
+
+// ANCHOR_END: undetermined_example
+
+#[kani::proof]
+// ANCHOR: cover_satisfied_example
+#[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;
+ }
+}
+// ANCHOR_END: cover_satisfied_example
+
+#[kani::proof]
+// ANCHOR: cover_unsatisfiable_example
+#[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);
+ }
+}
+// ANCHOR_END: cover_unsatisfiable_example
+
+#[kani::proof]
+// ANCHOR: cover_unreachable_example
+#[kani::unwind(6)]
+fn cover_unreachable_example() {
+ let r1: std::ops::Range
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting started
+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.
+Project Status
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book. +We also publish updates on Kani use cases and features on our blog.
+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.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/install-github-ci.html b/install-github-ci.html
new file mode 100644
index 000000000000..0444afd07eb7
--- /dev/null
+++ b/install-github-ci.html
@@ -0,0 +1,237 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting started
+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.
+Project Status
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book. +We also publish updates on Kani use cases and features on our blog.
+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.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/install-guide.html b/install-guide.html
new file mode 100644
index 000000000000..e0b877c29cf3
--- /dev/null
+++ b/install-guide.html
@@ -0,0 +1,237 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ GitHub Action
+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.
Using Kani in your GitHub workflow
+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.
Options
+The action takes the following optional parameters:
+-
+
command: The command to run. +Defaults tocargo 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}. +Seecargo kani --helpfor a full list of options. +Useful options include: +-
+
--output-format=terseto generate terse output.
+--teststo run on proofs inside thetestmodule (needed for running Bolero).
+--workspaceto run on all crates within your repository.
+
+
FAQ
+-
+
- Kani takes too long for my CI: Try running Kani on a +schedule +with desired frequency. +
- Kani Silently Crashes with no logs: Few possible reasons:
+
-
+
- Kani ran out of RAM. GitHub offers up to 7GB of RAM, but Kani may +use more. Run locally to confirm. +
- GitHub terminates jobs longer than 6 hours. +
- Otherwise, consider filing an issue here. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/kani-tutorial.html b/kani-tutorial.html
new file mode 100644
index 000000000000..ce3c04cbc4e4
--- /dev/null
+++ b/kani-tutorial.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Installation
+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.
+Dependencies
+The following must already be installed:
+-
+
- Python version 3.7 or newer and the package installer
pip.
+ - Rust 1.58 or newer installed via
rustup.
+
Installing the latest version
+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.
Installing an older version
+cargo install --locked kani-verifier --version <VERSION>
+cargo kani setup
+Checking your installation
+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
+Next steps
+If you're learning Kani for the first time, you may be interested in our tutorial.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/limitations.html b/limitations.html
new file mode 100644
index 000000000000..f58d3cba4767
--- /dev/null
+++ b/limitations.html
@@ -0,0 +1,195 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mark.min.js b/mark.min.js
new file mode 100644
index 000000000000..163623188347
--- /dev/null
+++ b/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Limitations
+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:
+-
+
- Discuss the effect of Rust undefined behaviour. +
- Summarize the current support for Rust features. +
- Explain the need for overrides and list all overriden +symbols. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/performance-comparisons.html b/performance-comparisons.html
new file mode 100644
index 000000000000..30f39b367571
--- /dev/null
+++ b/performance-comparisons.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Overrides
+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 |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/print.html b/print.html
new file mode 100644
index 000000000000..7c75b7f87de7
--- /dev/null
+++ b/print.html
@@ -0,0 +1,4050 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Performance comparisons with
+
+
+
+
+ Performance comparisons with benchcomp
+While 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.
Example use-cases
+-
+
- Run one or more benchmark suites with the current and previous versions of Kani. +Exit with a return code of 1 or print a custom summary to the terminal if any benchmark regressed by more than a user-configured amount. +
- Run benchmark suites using several historical versions of Kani and emit a graph of performance over time. +
- Run benchmark suites using different SAT solvers, command-line flags, or environment variables. +
Features
+Benchcomp provides the following features to support your performance-comparison workflow:
+-
+
- Automatically copies benchmark suites into a fresh directories before running with each variant, to ensure that built artifacts do not affect subsequent runtimes +
- Parses the results of different 'kinds' of benchmark suite and combines those results into a single unified format. +This allows you to run benchmarks from external repositories, suites of pre-compiled GOTO-binaries, and other kinds of benchmark all together and view their results in a single dashboard. +
- Driven by a single configuration file that can be sent to colleagues or checked into a repository to be used in continuous integration. +
- Extensible, allowing you to write your own parsers and visualizations. +
- Caches all previous runs and allows you to re-create visualizations for the latest run without actually re-running the suites. +
Quick start
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference.html b/reference.html
new file mode 100644
index 000000000000..e028bd02f093
--- /dev/null
+++ b/reference.html
@@ -0,0 +1,185 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration in
+
+
+
+
+
+The
+An example: stubbing
+Loop contracts for
+Working with
+Code analysis for
+EMACS (with
+Custom
+Rust compiler utilities to debug
+Enable
+
+The
+Performance comparisons with
+
+
+
+
+
+
+
+
+
+
+ Getting started
+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.
+Project Status
+Kani is currently under active development. +Releases are published here. +Major changes to Kani are documented in the RFC Book. +We also publish updates on Kani use cases and features on our blog.
+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.
+Installation
+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.
+Dependencies
+The following must already be installed:
+-
+
- Python version 3.7 or newer and the package installer
pip.
+ - Rust 1.58 or newer installed via
rustup.
+
Installing the latest version
+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.
Installing an older version
+cargo install --locked kani-verifier --version <VERSION>
+cargo kani setup
+Checking your installation
+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
+Next steps
+If you're learning Kani for the first time, you may be interested in our tutorial.
+Installing from source code
+++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.
+
Dependencies
+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.
+Install dependencies on Ubuntu
+Support is available for Ubuntu 20.04, 22.04, and 24.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
+Install dependencies on macOS
+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 and test Kani
+Build the Kani package using:
+cargo build-dev -- --release
+to compile with optimizations turned on or using:
+cargo build-dev
+to compile in debug/development mode.
+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.
+Adding Kani to your path
+To use a locally-built Kani from anywhere, add the Kani scripts to your path:
+export PATH=$(pwd)/scripts:$PATH
+Next steps
+If you're learning Kani for the first time, you may be interested in our tutorial.
+GitHub Action
+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.
Using Kani in your GitHub workflow
+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.
Options
+The action takes the following optional parameters:
+-
+
command: The command to run. +Defaults tocargo 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}. +Seecargo kani --helpfor a full list of options. +Useful options include: +-
+
--output-format=terseto generate terse output.
+--teststo run on proofs inside thetestmodule (needed for running Bolero).
+--workspaceto run on all crates within your repository.
+
+
FAQ
+-
+
- Kani takes too long for my CI: Try running Kani on a +schedule +with desired frequency. +
- Kani Silently Crashes with no logs: Few possible reasons:
+
-
+
- Kani ran out of RAM. GitHub offers up to 7GB of RAM, but Kani may +use more. Run locally to confirm. +
- GitHub terminates jobs longer than 6 hours. +
- Otherwise, consider filing an issue here. +
+
Using Kani
+At present, Kani can used in two ways:
+-
+
- On a single crate with the
kanicommand.
+ - On a Cargo package with the
cargo kanicommand.
+
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.
Usage on a package
+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 command line flags
+Common to both kani and cargo kani are many command-line flags:
-
+
-
+
+--concrete-playback=[print|inplace]: Experimental,--enable-unstablefeature that generates a Rust unit test case +that plays back a failing proof harness using a concrete counterexample. +If used withprint, Kani will only print the unit test to stdout. +If used withinplace, Kani will automatically add the unit test to the user's source code, next to the proof harness. For more detailed instructions, see the concrete playback section.
+ -
+
+--tests: Build in "test mode", i.e. withcfg(test)set anddev-dependenciesavailable (when usingcargo 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.
Usage on a single crate
+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.
Configuration in Cargo.toml
+Users 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.
+The build process
+When Kani builds your code, it does three important things:
+-
+
- It sets
cfg(kani)for target crate compilation (including dependencies).
+ - It injects the
kanicrate.
+ - It sets
cfg(kani_host)for host build targets such as any build script and procedural macro crates.
+
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.)
Verification results
+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.
Check results
+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 concrete playback +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 macros (e.g.
assert,assert_eq, etc.)
+ - Arithmetic overflow checks +
- Negation overflow checks +
- Index out-of-bounds checks +
- Divide/remainder-by-zero checks +
+- Assert macros (e.g.
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"
+Cover property results
+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 thecoverproperty 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 theUNDETERMINEDresult for normal checks (see [check_results]).
+
Verification summary
+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
+Crates documentation
+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:
+-
+
- kani: This crate +provide APIs to write Kani harnesses. +
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.
+First steps
+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 example, it would be nice to get a concrete example of a value of
+xthat triggers the failure. +Kani offers an (experimental) concrete playback feature that serves this purpose. +As an exercise, try applying concrete playback to this example and see what Kani outputs.
Exercise: Try other failures
+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?
+
+
+Click to show one possible answer
+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
+Assertions, Assumptions, and Harnesses
+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);
+}
+Summary
+In this section:
+-
+
- We saw Kani find panics, assertion failures, and even some other failures like unsafe dereferencing of null pointers. +
- We saw Kani find failures that testing could not easily find. +
- We saw how to write a proof harness and use
kani::any().
+ - We saw how proof harnesses are used to set up preconditions with
kani::assume().
+
Failures that Kani can spot
+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.
+Bounds checking and pointers
+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.as_ptr().add(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, 345.) +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 345 failed (8 unreachable)
+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:
+-
+
- Exercise: Switch back to the normal/safe indexing operation and re-try Kani. +How does Kani's output change, compared to the unsafe operation? +(Try predicting the answer, then seeing if you got it right.) +
- Exercise: Try Kani's experimental concrete playback feature on this example. +
- Exercise: Fix the error, run Kani, and see a successful verification. +
- Exercise: Try switching back to the unsafe code (now with the error fixed) and re-run Kani. Does it still verify successfully? +
+
+Click to see explanation for exercise 1
+Having switched back to the safe indexing operation, Kani reports a bounds check failure:
+SUMMARY:
+ ** 1 of 343 failed (8 unreachable)
+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
+
+VERIFICATION:- FAILED
+
+
+Click to see explanation for exercise 2
+cargo kani -Z concrete-playback --concrete-playback=inplace --harness bound_check produces the following test:
rust
+#[test]
+fn kani_concrete_playback_bound_check_4752536404478138800() {
+ let concrete_vals: Vec<Vec<u8>> = vec![
+ // 1ul
+ vec![1, 0, 0, 0, 0, 0, 0, 0],
+ // 18446744073709551615ul
+ vec![255, 255, 255, 255, 255, 255, 255, 255],
+ ];
+ kani::concrete_playback_run(concrete_vals, bound_check);
+}
+which indicates that substituting the concrete values size = 1 and index = 2^64 in our proof harness will produce the out of bounds access.
Overflow and math errors
+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.
-
+
- Exercise: Try to run Kani on this version of
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.
Exercise: Classic overflow failure
+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.
+-
+
- Exercise: Fix this function so it no longer overflows.
+(Hint: depending on which approach you take, you may need to add the assumption that
high > lowto your proof harness. +Don't add that right away, see what happens if you don't. Just keep it in mind.)
+ - Exercise: Prove your new implementation actually finds the midpoint correctly by adding an assertion to the test harness. +
+
+Click to see solutions for these exercises
+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.
+Failures that Kani cannot spot
+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.
+Summary
+In this section:
+-
+
- We saw Kani spot out-of-bounds accesses. +
- We saw Kani spot actually-unsafe dereferencing of a raw pointer to invalid memory. +
- We saw Kani spot a division by zero error and an overflowing addition. +
- As an exercise, we tried proving an assertion (finding the midpoint) that was not completely trivial. +
Loops, unwinding, and bounds
+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:
+-
+
- Set an upper bound on the size of the problem.
+We've actually already done part of this: our proof harness above seems to be trying to set an upper
LIMITof 10.
+ - Tell Kani about this limit if (or when) it's not able to figure it out on its own.
+This is the purpose of the
kani::unwindannotation.
+
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?
+
+
+Click to see explanation for the exercise
+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:
+-
+
- Put an actual upper bound on the problem itself.
+Here that's accomplished via
LIMITin our proof harness. +We don't create a slice any bigger than that, and that's what we loop over.
+ - Start at a reasonable guess for a
kani::unwindbound, and increase until the unwinding assertion failure goes away.
+ - Or, if that starts to take too long to verify, decrease your problem's bound, to accommodate the verifier's performance. +
Unwinding value specification
+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
+Bounded proof
+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?
+
+Click to see explanation for the exercise
+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.
+Summary
+In this section:
+-
+
- We saw Kani fail to terminate. +
- We saw how
#[kani::unwind(1)]can help force Kani to terminate (with a verification failure).
+ - We saw "unwinding assertions" verify that we've set the unwinding limit high enough. +
- We saw how to put a practical bound on problem size in our proof harness. +
- We saw how to pick an unwinding size large enough to successfully verify that bounded proof. +
Nondeterministic variables
+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.
Safe nondeterministic variables
+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:
-
+
idhas typeProductIdwhich was actually just au32, and so any value is fine.
+quantity, however, has typeNonZeroU32. +In Rust, it would be undefined behavior to have a value of0for 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.
Custom nondeterministic types
+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:
-
+
- Implement the
kani::Arbitrarytrait for your type, so you and downstream crates can usekani::any()with your type.
+ - Implement the
bolero_generator::TypeGeneratortrait. +This will enable you and downstream crates to use Kani via Bolero.
+ - Write a function that builds an object from non-deterministic variables. +
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.
Bounding nondeterministic variables
+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.
Exercise
+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.
Summary
+In this section:
+-
+
- We saw how
kani::any()will return "safe" values for each of the types Kani implements it for.
+ - We saw how to implement
kani::Arbitraryor just write a function to create nondeterministic values for other types.
+ - We noted that some types cannot implement
kani::any()as they need a bound on their size.
+ - We did an exercise to generate nondeterministic values of bounded size for
Inventory.
+
Reference
+This section is the main reference for Kani. +It contains sections that informally describe its main features.
+Attributes
+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.
Example
+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.
Limitations
+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 other words, it's only recommended to write negative harnesses +after having written positive harnesses that successfully verify interesting +properties about the function under verification.
Limitations
+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.
Example
+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:
-
+
- Disable automatic unwinding. +
- Unwind all loops up to
<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.
+Example
+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.
+
Example
+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.
+Experimental Features
+We elaborate on some of the more commonly used experimental features in Kani.
+This is not an exhaustive list; to see all of Kani's experimental features, run cargo kani --help.
+To use an experimental feature, invoke Kani with the --unstable or -Z flag followed by the name of the feature.
Automatic Harness Generation
+Recall the harness for estimate_size that we wrote in First Steps:
#[cfg(kani)]
+#[kani::proof]
+fn check_estimate_size() {
+ let x: u32 = kani::any();
+ estimate_size(x);
+}
+This harness first declares a local variable x using kani::any(), then calls estimate_size with argument x.
+Many proof harnesses follow this predictable format—to verify a function foo, we create arbitrary values for each of foo's arguments, then call foo on those arguments.
The autoharness subcommand leverages this observation to automatically generate and run harnesses.
+Kani scans the crate for functions whose arguments all implement the kani::Arbitrary trait, generates harnesses for them, then runs them.
+These harnesses are internal to Kani--i.e., Kani does not make any changes to your source code.
Usage
+Run either:
+# cargo kani autoharness -Z unstable-options
+or
+# kani autoharness -Z unstable-options <FILE>
+If Kani detects that all of a function foo's arguments implement kani::Arbitrary, it will generate and run a #[kani::proof] harness, which prints:
Autoharness: Checking function foo against all possible inputs...
+<VERIFICATION RESULTS>
+However, if Kani detects that foo has a contract, it will instead generate a #[kani::proof_for_contract] harness and verify the contract:
Autoharness: Checking function foo's contract against all possible inputs...
+<VERIFICATION RESULTS>
+Kani generates and runs these harnesses internally—the user only sees the verification results.
+The autoharness subcommand has options --include-function and --exclude-function to include and exclude particular functions.
+These flags look for partial matches against the fully qualified name of a function.
For example, if a module my_module has many functions, but we are only interested in my_module::foo and my_module::bar, we can run:
cargo run autoharness -Z unstable-options --include-function foo include-function bar
+To exclude my_module entirely, run:
cargo run autoharness -Z unstable-options --exclude-function my_module
+Example
+Using the estimate_size example from First Steps again:
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;
+ }
+ }
+}
+We get:
+# cargo kani autoharness -Z unstable-options
+Autoharness: Checking function estimate_size against all possible inputs...
+RESULTS:
+Check 3: estimate_size.assertion.1
+ - Status: FAILURE
+ - Description: "Oh no, a failing corner case!"
+[...]
+
+Verification failed for - estimate_size
+Complete - 0 successfully verified functions, 1 failures, 1 total.
+Request for comments
+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.
+Limitations
+Kani will only generate an automatic harness for a function if it can determine that all of the function's arguments implement Arbitrary. +It does not attempt to derive/implement Arbitrary for any types, even if those types could implement Arbitrary.
+If a function contains a loop with a loop contract, Kani will detect the presence of a loop contract and verify that contract.
+If, however, the loop does not have a contract, then there is currently no way to specify an unwinding bound for the function, meaning that Kani may hang as it tries to unwind the loop.
+We recommend using the --exclude-function option to exclude any functions that have this issue (or --harness-timeout to bail after attempting verification for some amount of time).
Coverage
+Recall our estimate_size example from First steps,
+where we wrote a proof harness constraining the range of inputs to integers less than 4096:
#[cfg(kani)]
+#[kani::proof]
+fn verify_success() {
+ let x: u32 = kani::any();
+ kani::assume(x < 4096);
+ let y = estimate_size(x);
+ assert!(y < 10);
+}
+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.
+In the first-steps-v2 directory, try running:
cargo kani --coverage -Z source-coverage --harness verify_success
+which verifies the harness, then prints coverage information for each line.
+In this case, we see that each line of estimate_size is followed by FULL, indicating that our proof harness provides full coverage.
Try changing the assumption in the proof harness to x < 2048.
+Now the harness won't be testing all possible cases.
+Rerun the command.
+You'll see this line:
src/lib.rs, 24, NONE
+which indicates that the proof no longer covers line 24, which addresses the case where x >= 2048.
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).
+When to consider stubbing
+In general, we have identified three reasons where users may consider stubbing:
+-
+
- Unsupported features: The code under verification contains features that Kani does not support, such as inline assembly. +
- Bad performance: The code under verification contains features that Kani supports, but it leads to bad verification performance (for example, deserialization code). +
- Compositional reasoning: The code under verification contains code that has been verified separately. +Stubbing the code that has already been verified with a less complex version that mimics its behavior can result in reduced verification workloads. +
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.
+Components
+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.
The #[kani::stub(...)] attribute
+The 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.
+An example: stubbing random
+Let'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.
+Limitations
+In the following, we describe all the limitations of the stubbing feature.
+Usage restrictions
+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
+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:
+-
+
- Types +
- Macros +
- Traits +
- Intrinsics +
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.
+Error conditions
+Given a set of original-replacement pairs, Kani will exit with an error if:
-
+
- a specified
originalfunction does not exist;
+ - a specified
replacementstub does not exist;
+ - the user specifies conflicting stubs for the same harness (e.g., if the same
originalfunction is mapped to multiplereplacementfunctions); or
+ - the signature of the
replacementstub is not compatible with the signature of theoriginalfunction/method (see next section).
+
Stub compatibility and validation
+We consider a stub and a function/method to be compatible if all the following conditions are met:
+-
+
- They have the same number of parameters. +
- They have the same return type. +
- Each parameter in the stub has the same type as the corresponding parameter in the original function/method. +
- The stub must have the same number of generic parameters as the original function/method.
+However, a generic parameter in the stub is allowed to have a different name than the corresponding parameter in the original function/method.
+For example, the stub
bar<A, B>(x: A, y: B) -> Bis considered to have a type compatible with the functionfoo<S, T>(x: S, y: T) -> T.
+ - The bounds for each type parameter don't need to match; however, all calls to the original function must also satisfy the bounds of the stub. +
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.
Contracts
+Consider the following example:
+fn gcd(mut max: u8, mut min: u8) -> u8 {
+ if min > max {
+ std::mem::swap(&mut max, &mut min);
+ }
+
+ let rest = max % min;
+ if rest == 0 { min } else { gcd(min, rest) }
+}
+Let's assume we want to verify some code that calls gcd.
+In the worst case, the number of steps (recursions) in gcd approaches 1.5 times the number of bits needed to represent the input numbers.
+So, for two large 64-bit numbers, a single call to gcd can take almost 96 iterations.
+It would be very expensive for Kani to unroll each of these iterations and then perform symbolic execution.
Instead, we can write contracts with guarantees about gcd's behavior.
+Once Kani verifies that gcd's contracts are correct, it can replace each invocation of gcd with its contracts, which reduces verification time for gcd's callers.
+For example, perhaps we want to ensure that the returned result does indeed divide both max and min.
+In that case, we could write contracts like these:
#[kani::requires(min != 0 && max != 0)]
+#[kani::ensures(|result| *result != 0 && max % *result == 0 && min % *result == 0)]
+#[kani::recursion]
+fn gcd(mut max: u8, mut min: u8) -> u8 { ... }
+Since gcd performs max % min (and perhaps swaps those values), passing zero as an argument could cause a division by zero.
+The requires contract tells Kani to restrict the range of nondeterministic inputs to nonzero ones so that we don't run into this error.
+The ensures contract is what actually checks that the result is a correct divisor for the inputs.
+(The recursion attribute is required when using contracts on recursive functions).
Then, we would write a harness to verify those contracts, like so:
+#[kani::proof_for_contract(gcd)]
+fn check_gcd() {
+ let max: u8 = kani::any();
+ let min: u8 = kani::any();
+ gcd(max, min);
+}
+and verify it by running kani -Z function-contracts.
Once Kani verifies the contracts, we can use Kani's stubbing feature to replace all invocations to gcd with its contracts, for instance:
// Assume foo() invokes gcd().
+// By using stub_verified, we tell Kani to replace
+// invocations of gcd() with its verified contracts.
+#[kani::proof]
+#[kani::stub_verified(gcd)]
+fn check_foo() {
+ let x: u8 = kani::any();
+ foo(x);
+}
+By leveraging the stubbing feature, we can replace the (expensive) gcd call with a verified abstraction of its behavior, greatly reducing verification time for foo.
There is far more to learn about contracts.
+We highly recommend reading our blog post about contracts (from which this gcd example is taken). We also recommend looking at the contracts module in our documentation.
Loop Contracts
+Loop contract are used to specify invariants for loops for the sake of extending Kani's bounded proofs to unbounded proofs. +A loop invariant is an expression that holds upon entering a loop and after every execution of the loop body. +It captures something that does not change about every step of the loop.
+It is worth revisiting the discussion about bounded proof and +loop unwinding. In short, bounds on the number of times Kani unwinds loops also bound the size of inputs, +and hence result in a bounded proof. +Loop contracts are used to abstract out loops as non-loop blocks to avoid loop unwinding, and hence remove the bounds on the inputs.
+Consider the following example:
+fn simple_loop() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ while x > 1 {
+ x = x - 1;
+ }
+
+ assert!(x == 1);
+}
+In this program, the loop repeatedly decrements x until it equals 1. Because we haven't specified an upper bound for x, to verify this function,
+Kani needs to unwind the loop for u64::MAX iterations, which is computationally expensive. Loop contracts allow us to abstract the loop behavior, significantly reducing the verification cost.
With loop contracts, we can specify the loop’s behavior using invariants. For example:
+#![feature(stmt_expr_attributes)]
+#![feature(proc_macro_hygiene)]
+
+fn simple_loop_with_loop_contracts() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while x > 1 {
+ x = x - 1;
+ }
+
+ assert!(x == 1);
+}
+Here, the loop invariant #[kani::loop_invariant(x >= 1)] specifies that the condition x >= 1 must hold true at the start of each iteration before the loop guard is
+checked. Once Kani verifies that the loop invariant is inductive, it will use the invariant to abstract the loop and avoid unwinding.
Now let's run the proof with loop contracts through kani:
+kani simple_loop_with_loop_contracts.rs -Z loop-contracts
+The output reported by Kani on the example will be
+...
+
+
+Check 10: simple_loop_with_loop_contracts.loop_invariant_base.1
+ - Status: SUCCESS
+ - Description: "Check invariant before entry for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 11: simple_loop_with_loop_contracts.loop_assigns.1
+ - Status: SUCCESS
+ - Description: "Check assigns clause inclusion for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 13: simple_loop_with_loop_contracts.assigns.1
+ - Status: SUCCESS
+ - Description: "Check that x is assignable"
+ - Location: simple_while_loop.rs:17:9 in function simple_loop_with_loop_contracts
+
+Check 14: simple_loop_with_loop_contracts.loop_invariant_step.1
+ - Status: SUCCESS
+ - Description: "Check invariant after step for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 15: simple_loop_with_loop_contracts.loop_invariant_step.2
+ - Status: SUCCESS
+ - Description: "Check invariant after step for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+...
+
+SUMMARY:
+ ** 0 of 99 failed
+
+VERIFICATION:- SUCCESSFUL
+Verification Time: 0.3897019s
+
+Complete - 1 successfully verified harnesses, 0 failures, 1 total.
+Loop contracts for while loops
+Syntax
+++#[kani::loop_invariant( Expression )]
++
whileExpressionexcept struct expression BlockExpression
An invariant contract #[kani::loop_invariant(cond)] accepts a valid Boolean expression cond over the variables visible at the same scope as the loop.
Semantics
+A loop invariant contract expands to several assumptions and assertions:
+-
+
- The invariant is asserted just before the first iteration. +
- The invariant is assumed on a non-deterministic state to model a non-deterministic iteration. +
- The invariant is finally asserted again to establish its inductiveness. +
Mathematical induction is the working principle here. (1) establishes the base case for induction, and (2) & (3) establish the inductive case. +Therefore, the invariant must hold after the loop execution for any number of iterations. The invariant, together with the negation of the loop guard, +must be sufficient to establish subsequent assertions. If it is not, the abstraction is too imprecise and the user must supply a stronger invariant.
+To illustrate the key idea, we show how Kani abstracts the loop in simple_loop_with_loop_contracts as a non-loop block:
assert!(x >= 1) // check loop invariant for the base case.
+x = kani::any();
+kani::assume(x >= 1);
+if x > 1 {
+ // proof path 1:
+ // both loop guard and loop invariant are satisfied.
+ x = x - 1;
+ assert!(x >= 1); // check that loop invariant is inductive.
+ kani::assume(false) // block this proof path.
+}
+// proof path 2:
+// loop invariant is satisfied and loop guard is violated.
+assert!(x == 1);
+That is, we assume that we are in an arbitrary iteration after checking that the loop invariant holds for the base case. With the inductive hypothesis (kani::assume(x >= 1);),
+we will either enter the loop (proof path 1) or leave the loop (proof path 2). We prove the two paths separately by killing path 1 with kani::assume(false);.
+Note that all assertions after kani::assume(false) will be ignored as false => p can be deduced as true for any p.
In proof path 1, we prove properties inside the loop and at last check that the loop invariant is inductive.
+In proof path 2, we prove properties after leaving the loop. As we leave the loop only when the loop guard is violated, the post condition of the loop can be expressed as
+!guard && inv, which is x <= 1 && x >= 1 in the example. The postcondition implies x == 1—the property we want to prove at the end of simple_loop_with_loop_contracts.
Limitations
+Loop contracts comes with the following limitations.
+-
+
- Only
whileloops are supported. The other three kinds of loops are not supported:looploops +,while letloops, andforloops.
+ - Kani infers loop modifies with alias analysis. Loop modifies are those variables we assume to be arbitrary in the inductive hypothesis, and should cover all memory locations that are written to during +the execution of the loops. A proof will fail if the inferred loop modifies misses some targets written in the loops. +We observed this happens when some fields of structs are modified by some other functions called in the loops. +
- Kani doesn't check if a loop will always terminate in proofs with loop contracts. So it could be that some properties are proved successfully with Kani but actually are unreachable due to the +non-termination of some loops. +
- We don't check if loop invariants are side-effect free. A loop invariant with a side effect could lead to an unsound proof result. Make sure that the specified loop contracts are side-effect free. +
Concrete Playback
+When the result of a certain check comes back as a FAILURE, Kani offers the concrete-playback option to help debug. This feature generates a Rust unit test case that plays back a failing proof harness using a concrete counterexample.
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.
+Usage
+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 bykani::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 togit. +That way, you can easily remove the unit test withgit 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:
-
+
- You can try Kani's experimental extension +provided for VSCode. +
- Otherwise, you can debug the unit test on the command line. +
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.
Example
+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.
Request for comments
+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.
+Limitations
+-
+
- This feature does not generate unit tests for failing non-panic checks (e.g., UB checks). +This is because checks would not trigger runtime errors during concrete playback. +Kani generates warning messages for this. +
- This feature does not support generating unit tests for multiple assertion failures within the same harness. +This limitation might be removed in the future. +Kani generates warning messages for this. +
- This feature requires that you use the same Kani version to generate the test and to playback. +Any extra compilation option used during verification must be used during playback. +
Application
+You may be interested in applying Kani if you're in this situation:
+-
+
- You're working on a moderately important project in Rust. +
- You've already invested heavily in testing to ensure correctness. +
- You want to invest further, to gain a much higher degree of assurance. +
++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.
+Comparison with other tools
+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.
+Looking for concurrency?
+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).
+Other tools
+The Rust Formal Methods Interest Group maintains a list of interesting Rust verification tools.
+Where to start on real code
+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:
+-
+
- Find a place where it'd be valuable to have a proof. +
- Find a place where it won't be too difficult to prove something, just to start. +
- Figure out what a feasible longer-term goal might be. +
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 is proof valuable?
+-
+
-
+
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
+unsafeis 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.
+
+
Where is it easier to start?
+-
+
-
+
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.
+
+
Your first proof
+A first proof will likely start in the following form:
+-
+
- Nondeterministically initialize variables that will correspond to function inputs, with as few constraints as possible. +
- Call the function in question with these inputs. +
- Don't (yet) assert any post-conditions. +
Running Kani on this simple starting point will help figure out:
+-
+
- What unexpected constraints might be needed on your inputs (using
kani::assume) to avoid "expected" failures.
+ - Whether you're over-constrained. Check the coverage report using
--coverage -Z source-coverage. Ideally you'd see 100% coverage, and if not, it's usually because you've assumed too much (thus over-constraining the inputs).
+ - Whether Kani will support all the Rust features involved. +
- Whether you've started with a tractable problem.
+(Remember to try setting
#[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.
+Examples of the use of Kani
+On the Kani blog, we've documented worked examples of applying Kani:
+-
+
- The
Rectangleexample of the Rust Book
+ - A Rust standard library CVE +
- Verifying a part of Firecracker +
Developer documentation
+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):
+-
+
- Coding conventions. +
- Useful command-line instructions for Kani/CBMC/Git. +
- Development setup recommendations for working with
cbmc.
+ - Development setup recommendations for working with
rustc.
+ - Guide for testing in Kani. +
- Transition to StableMIR. +
++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.
+
Coding conventions
+Formatting
+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.
Exceptions
+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.
Copyright notice
+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.
+Code for soundness
+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.
+Compilation errors
+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.
Internal compiler errors
+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.
+Verification errors
+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.
Create detailed issues for "TODO" tasks
+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");
+Performant but readable
+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:
+-
+
- Sort match arms, enum variants, and struct fields alphabetically. +
- Prefer concise but meaningful names. +
- Prefer exhaustive matches. +
- Prefer declarative over imperative programming. +
Working with CBMC
+This section describes how to access more advanced CBMC options from Kani.
+CBMC arguments
+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.
Individual loop bounds
+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
+Working with rustc
+Kani 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.
Code analysis for rustc definitions
+IDEs 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:
VSCode
+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
+Debugging in VS code
+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.
RustRover / CLion
+This is not a great solution, but it works for now (see https://github.com/intellij-rust/intellij-rust/issues/1618 +for more details).
+Open the Cargo.toml of your crate (e.g.: kani-compiler), and do the following:
-
+
- Add optional dependencies on the
rustccrates you are using.
+ - Add a feature that enable those dependencies. +
- Toggle that feature using the IDE GUI. +
Here is an example:
+# ** At the bottom of the dependencies section: **
+# Adjust the path here to point to a local copy of the rust compiler.
+# E.g.: ~/.rustup/toolchains/<toolchain>/lib/rustlib/rustc-src/rust/compiler
+rustc_smir = { path = "<path_to_rustc>/rustc_smir", optional = true }
+stable_mir = { path = "<path_to_rustc>/stable_mir", optional = true }
+
+[features]
+clion = ['rustc_smir', 'stable_mir']
+Don't forget to rollback the changes before you create your PR.
+EMACS (with 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.
+-
+
- Opening up a rust file with at least one
rustc_privateimport.
+ - Activate LSP mode with
M-x lsp.
+ - When asked about the root of the project, pick one of them. Make
+sure that whichever root you pick has a
Cargo.tomlwith +rustc_private=trueadded.
+ - If LSP asks if you want to watch all files, select yes. For less +powerful machines, you may want to adjust that later. +
- On the file with
rustc_privateimports, do the following. If both +work, then you are set up. +-
+
- Hover mouse over the
rustc_privateimport. If LSP is working, +you should get information about the imported item.
+ - With text cursor over the same
rustc_privateimport, runM-x lsp-find-definition. This should jump to the definition within +rustc's source code.
+
+ - Hover mouse over the
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/.
+Custom rustc
+There are a few reasons why you may want to use your own copy of rustc. E.g.:
-
+
- Enable more verbose logs. +
- Use a debug build to allow you to step through
rustccode.
+ - Test changes to
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
+Rust compiler utilities to debug kani-compiler
+Enable rustc logs
+In 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.
Debugging type layout
+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
+Inspecting the MIR
+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.
Transition to StableMIR
+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.
+StableMIR APIs
+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:
+-
+
- The usage of the compiler context (aka
TyCtxt) is transparent to the user. +The StableMIR implementation caches this context in a thread local variable, +and retrieves it whenever necessary. +-
+
- Because of that, code that uses the StableMIR has to be invoked inside a
runcall.
+
+ - Because of that, code that uses the StableMIR has to be invoked inside a
- The
DefIdhas been specialized into multiple types, +making its usage less error prone. E.g.: +FnDefrepresents the definition of a function, +whileStaticDefis the definition of a static variable. +-
+
- Note that the same
DefIdmay be mapped to different definitions according to its context. +For example, anInstanceDefand aFnDefmay represent the same function definition.
+
+ - Note that the same
- Methods that used to be exposed as part of
TyCtxtare now part of a type. +Example, the functionTyCtxt.instance_miris nowInstance::body.
+ - There is no need for explicit instantiation (monomorphization) of items from an
Instance::body. +This method already instantiates all types and resolves all constants before converting +it to stable APIs.
+
Performance
+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.
+Interface with internal APIs
+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.
Creating and modifying StableMIR items
+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).
+Naming conventions in Kani
+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.
Command cheat sheets
+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.
+Kani
+Build
+# 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
+Test
+# 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
+Debug
+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
+CBMC
+# 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
+Git
+The Kani project follows the squash and merge option for pull request merges. +As a result:
+-
+
- The title of your pull request will become the main commit message. +
- The messages from commits in your pull request will appear by default as a bulleted list in the main commit message body. +
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 assess
+Assess 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:
+-
+
- Does Kani successfully build all of the crates involved in this project? If not, why not? +
- Does Kani support all the Rust language features necessary to do verification with this project? If not, which are most important? +
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:
+-
+
- Is this project ready for verification? Projects need to be reasonably well-tested first. +Our operating hypothesis is that code currently covered by unit tests is the code that could become covered by proofs. +
- How much of given project (consisting of multiple packages or workspaces) or which of the user's projects might be verifiable? +If a user wants to start trying Kani, but they have the choice of several different packages where they might try, we can help find the package with the lowest hanging fruit. +
- Given a package, where in that package's code should the user look, in order to write the first (or next) proof? +
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.
+Using Assess
+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.)
What assess does
+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.
Current Assess Results
+Assess produces a few tables of output (both visually in the terminal, and in a more detailed json format) so far:
+Unsupported features
+======================================================
+ 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:
+-
+
- "Crates impacted" here means "packages in the current workspace (or scan) where the building of that package (and all of its dependencies) ultimately resulted in this warning."
+For example, if only assessing a single package (not a workspace) this could only be
1in this column, regardless of the number of dependencies.
+ - "Instances of use" likewise means "total instances found while compiling this package's tests and all the (reachable) code in its dependencies." +
- These counts are influenced by (static) reachability: if code is not potentially reachable from a test somehow, it will not be built and will not be counted. +
Test failure reasons
+================================================
+ 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:
+-
+
- Because we force termination with
unwind(1), we expectunwindto rank highly.
+ - We do report number of tests succeeding on this table, to aid understanding how well things went overall. +
- The reported reason is the "property class" of the CBMC property that failed. So
assertionmeans an ordinaryassert!()was hit (or something else with this property class).
+ - When multiple properties fail, they are aggregated with
+, such asassertion + overflow.
+ - Currently this table does not properly account for
should_failtests, soassertionmay actually be "success": the test should hit an assertion and did.
+
Promising test cases
+=============================================================================
+ 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).
+How Assess Works
+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:
-
+
- With
--all-featuresturned on
+ - With
unwindalways set to1
+ - In test mode, i.e.
--tests
+ - With test-case reachability mode. Normally Kani looks for proof harnesses and builds only those. Here we switch to building only the test harnesses instead. +
Assess 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.
Using Assess on the top-100 crates
+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
+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.
+Regression testing
+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.
+Kani testing suites
+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 likekanibut contains tests inspired by +Firecracker code.
+prusti: Works likekanibut contains tests from the +Prusti tool.
+smack: Works likekanibut contains tests from the +SMACK tool.
+kani-fixme: Similar tokani, but runs ignored tests from thekanitesting +suite (i.e., tests withfixmeorignorein their name). +Allows us to detect when a previously not supported test becomes +supported. More details in "Fixme" tests.
+expected: Similar tokanibut with an additional check which ensures that +lines appearing in*.expectedfiles appear in the output +generated bykani.
+ui: Works likeexpected, but focuses on the user interface (e.g., +warnings) instead of the verification output.
+cargo-kani: This suite is designed to test thecargo-kanicommand. As such, +this suite works with packages instead of single Rust files. +Arguments can be specified in theCargo.tomlconfiguration file. +Similar to theexpectedsuite, we look for*.expectedfiles +for each harness in the package.
+cargo-ui: Similar tocargo-kani, but focuses on the user interface like theuitest 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 theexecmode, 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).
Testing stages
+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.
Testing options
+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.
"Fixme" tests
+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:
-
+
- Only runs tests whose name contains
fixmeorignore(ignoring the rest).
+ - The expected outcome is failure. In other words, a test is successful if it +fails. +
We welcome contributions with "fixme" tests which demonstrate a bug or +unsupported feature in Kani. Ideally, the test should include some comments +regarding:
+-
+
- The expected result of the test. +
- The actual result of the test (e.g., interesting parts of the output). +
- Links to related issues. +
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.
Rust unit tests
+These tests follow the +Rust unit testing +style.
+At present, Kani runs unit tests from the following packages:
+-
+
cprover_bindings
+kani-compiler
+cargo-kani
+
Python unit tests
+We use the Python unit testing framework to +test the CBMC JSON parser.
+Script-based tests
+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:
+-
+
- Standard library codegen +
- Firecracker virtio codegen +
- Diamond dependency +
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).
The exec mode
+The 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.expectedfile 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.
(Experimental) Testing with a Large Number of Repositories
+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.
+Picking 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 +
- docker-compose. +
-
+
- Start PostgreSQL. Paste in the following yaml file as
+
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.
+-
+
- URL from CSV:
cat top-1k.csv | awk -F ',' '{ print $2 }' | grep -v 'http.*'
+ - Remove long paths:
sed 's/tree\/master.*$//g'
+ - Once processed, you can dedup with
sort | uniq --unique
+
+ - URL from CSV:
Running the List of Repositories
+In 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.
Performance comparisons with benchcomp
+While 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.
Example use-cases
+-
+
- Run one or more benchmark suites with the current and previous versions of Kani. +Exit with a return code of 1 or print a custom summary to the terminal if any benchmark regressed by more than a user-configured amount. +
- Run benchmark suites using several historical versions of Kani and emit a graph of performance over time. +
- Run benchmark suites using different SAT solvers, command-line flags, or environment variables. +
Features
+Benchcomp provides the following features to support your performance-comparison workflow:
+-
+
- Automatically copies benchmark suites into a fresh directories before running with each variant, to ensure that built artifacts do not affect subsequent runtimes +
- Parses the results of different 'kinds' of benchmark suite and combines those results into a single unified format. +This allows you to run benchmarks from external repositories, suites of pre-compiled GOTO-binaries, and other kinds of benchmark all together and view their results in a single dashboard. +
- Driven by a single configuration file that can be sent to colleagues or checked into a repository to be used in continuous integration. +
- Extensible, allowing you to write your own parsers and visualizations. +
- Caches all previous runs and allows you to re-create visualizations for the latest run without actually re-running the suites. +
Quick start
+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 line
+benchcomp 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:
-
+
benchcompwithout any subcommands, which runs the entire performance comparison process as depicted below
+benchcomp 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.
Example config file
+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 file
+benchcomp'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.
Variants
+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}
+Filters
+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).
Built-in visualizations
+The following visualizations are available; these can be added to the visualize list of benchcomp.yaml.
Detailed documentation for these visualizations follows.
+Plot
+Scatterplot configuration options
+dump_markdown_results_table
+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 |
+dump_yaml
+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: '-'
+error_on_regression
+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_command
+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
+Custom parsers
+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.
+Built-in parsers
+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
+Custom parsers
+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.
Contributing custom parsers to Kani
+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).
Limitations
+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:
+-
+
- Discuss the effect of Rust undefined behaviour. +
- Summarize the current support for Rust features. +
- Explain the need for overrides and list all overriden +symbols. +
Undefined Behaviour
+The Effect of Undefined Behaviour on Program Verification
+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.
+What forms of Undefined Behaviour can Rust Exhibit
+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:
+-
+
- Data races.
+
-
+
- Kani focuses on sequential code. +
+ - Breaking the pointer aliasing rules (http://llvm.org/docs/LangRef.html#pointer-aliasing-rules).
+
-
+
- Kani can detect if misuse of pointers causes memory safety or assertion violations, but does not track reference lifetimes. +
+ - Mutating immutable data.
+
-
+
- Kani can detect if modification of immutable data causes memory safety or assertion violations, but does not track reference lifetimes. +
+ - Invoking undefined behavior via compiler intrinsics.
+
-
+
- Kani makes a best effort attempt to check the preconditions of compiler intrinsics, but does not guarantee to do so in all cases. +
+ - Executing code compiled with platform features that the current platform does not support (see target_feature).
+
-
+
- Kani relies on
rustcto check for this case.
+
+ - Kani relies on
- Calling a function with the wrong call ABI or unwinding from a function with the wrong unwind ABI.
+
-
+
- Kani relies on
rustcto check for this case.
+
+ - Kani relies on
- Producing an invalid value, even in private fields and locals.
+
-
+
- Kani won't create invalid values with
kani::any()but it also won't complain if youtransmutean invalid value to a Rust type (for example, a0toNonZeroU32).
+
+ - Kani won't create invalid values with
- Incorrect use of inline assembly.
+
-
+
- Kani does not support inline assembly. +
+ - Using uninitialized memory.
+
-
+
- See the corresponding section in our Rust feature support. +
+
Kani makes a best-effort attempt to detect some cases of UB:
+-
+
- Evaluating a dereference expression (
*expr) on a raw pointer that is dangling or unaligned. +-
+
- Kani can detect invalid dereferences, but may not detect them in place expression context. +
+ - Invoking undefined behavior via compiler intrinsics. + + +
Rust feature support
+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:
+-
+
- Yes: The feature is fully supported. We are not aware of any issue with it. +
- Partial: The feature is at least partially supported. We are aware of some issue with +with it. +
- No: The feature is not supported. Some support may be available but analyses should not be trusted. +
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 |
Notes on partially or unsupported features
+Code generation for unsupported features
+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).
+Assembly
+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.
Concurrency
+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.
+Standard library functions
+Kani overrides a few common functions +(e.g., print macros) to provide a more verification friendly implementation.
+Advanced features
+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:
+-
+
- Sanity check
Varianttype in projections +#448.
+ - Unexpected fat pointer results in +#277, +#327 and +#676. +
We are particularly interested in bug reports concerning +these features, so please file a bug +report +if you're aware of one.
+Panic strategies
+Rust has two different strategies when a panic occurs:
+-
+
- Stack unwinding (default): Walks back the stack cleaning up the data from +each function it encounters. +
- Abortion: Immediately ends the program without cleaning up. +
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.
+Uninitialized memory
+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.
+Destructors
+At present, we are aware of some issues with destructors, in particular those +related to advanced features.
+Intrinsics
+Please refer to Intrinsics for information +on the current support in Kani for Rust compiler intrinsics.
+Floating point operations
+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.
Intrinsics
+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:
+-
+
- Yes: The intrinsic is fully supported. We are not aware of any issue with it. +
- Partial: The intrinsic is at least partially supported. We are aware of some issue with +with it. +
- No: The intrinsic is not supported. +
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.
+Compiler intrinsics
+| 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 | Partial | #3629 |
| floorf32 | Yes | |
| floorf64 | Yes | |
| fmaf32 | Partial | Results are overapproximated |
| fmaf64 | Partial | Results are overapproximated |
| fmul_fast | Partial | #809 |
| forget | Yes | |
| frem_fast | No | |
| fsub_fast | Yes | |
| likely | Yes | |
| log10f32 | Partial | Results are overapproximated |
| log10f64 | Partial | Results are overapproximated |
| log2f32 | Partial | Results are overapproximated |
| log2f64 | Partial | Results are overapproximated |
| 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 | Partial | Results are overapproximated |
| powif64 | Partial | Results are overapproximated |
| 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 | Partial | Results are overapproximated |
| sqrtf64 | Partial | Results are overapproximated |
| 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_nonoverlapping | 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 |
Atomics
+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.
+Platform intrinsics
+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 |
Unstable features
+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:
+-
+
- Generators +
- C-variadics +
Overrides
+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 |
FAQs
+This section collects frequently asked questions about Kani. +Please consider opening an issue if you have a question that would like to see here.
+Questions
+
+Kani doesn't fail after
+
+
+Kani doesn't fail after 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.
+I implemented the
+
+
+
+ I implemented the 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:
-
+
- Importing a copy of the external crate that defines the type, then implement
Arbitrarythere.
+ - Contributing the
Arbitraryimplementation to the external crate that defines the type.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/attributes.html b/reference/attributes.html
new file mode 100644
index 000000000000..ca8ff3dd0ae3
--- /dev/null
+++ b/reference/attributes.html
@@ -0,0 +1,365 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Reference
+This section is the main reference for Kani. +It contains sections that informally describe its main features.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/autoharness.html b/reference/experimental/autoharness.html
new file mode 100644
index 000000000000..6509ac76d8be
--- /dev/null
+++ b/reference/experimental/autoharness.html
@@ -0,0 +1,266 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Attributes
+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.
Example
+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.
Limitations
+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 other words, it's only recommended to write negative harnesses +after having written positive harnesses that successfully verify interesting +properties about the function under verification.
Limitations
+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.
Example
+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:
-
+
- Disable automatic unwinding. +
- Unwind all loops up to
<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.
+Example
+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.
+
Example
+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.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/concrete-playback.html b/reference/experimental/concrete-playback.html
new file mode 100644
index 000000000000..d89aa43f295b
--- /dev/null
+++ b/reference/experimental/concrete-playback.html
@@ -0,0 +1,258 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Automatic Harness Generation
+Recall the harness for estimate_size that we wrote in First Steps:
#[cfg(kani)]
+#[kani::proof]
+fn check_estimate_size() {
+ let x: u32 = kani::any();
+ estimate_size(x);
+}
+This harness first declares a local variable x using kani::any(), then calls estimate_size with argument x.
+Many proof harnesses follow this predictable format—to verify a function foo, we create arbitrary values for each of foo's arguments, then call foo on those arguments.
The autoharness subcommand leverages this observation to automatically generate and run harnesses.
+Kani scans the crate for functions whose arguments all implement the kani::Arbitrary trait, generates harnesses for them, then runs them.
+These harnesses are internal to Kani--i.e., Kani does not make any changes to your source code.
Usage
+Run either:
+# cargo kani autoharness -Z unstable-options
+or
+# kani autoharness -Z unstable-options <FILE>
+If Kani detects that all of a function foo's arguments implement kani::Arbitrary, it will generate and run a #[kani::proof] harness, which prints:
Autoharness: Checking function foo against all possible inputs...
+<VERIFICATION RESULTS>
+However, if Kani detects that foo has a contract, it will instead generate a #[kani::proof_for_contract] harness and verify the contract:
Autoharness: Checking function foo's contract against all possible inputs...
+<VERIFICATION RESULTS>
+Kani generates and runs these harnesses internally—the user only sees the verification results.
+The autoharness subcommand has options --include-function and --exclude-function to include and exclude particular functions.
+These flags look for partial matches against the fully qualified name of a function.
For example, if a module my_module has many functions, but we are only interested in my_module::foo and my_module::bar, we can run:
cargo run autoharness -Z unstable-options --include-function foo include-function bar
+To exclude my_module entirely, run:
cargo run autoharness -Z unstable-options --exclude-function my_module
+Example
+Using the estimate_size example from First Steps again:
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;
+ }
+ }
+}
+We get:
+# cargo kani autoharness -Z unstable-options
+Autoharness: Checking function estimate_size against all possible inputs...
+RESULTS:
+Check 3: estimate_size.assertion.1
+ - Status: FAILURE
+ - Description: "Oh no, a failing corner case!"
+[...]
+
+Verification failed for - estimate_size
+Complete - 0 successfully verified functions, 1 failures, 1 total.
+Request for comments
+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.
+Limitations
+Kani will only generate an automatic harness for a function if it can determine that all of the function's arguments implement Arbitrary. +It does not attempt to derive/implement Arbitrary for any types, even if those types could implement Arbitrary.
+If a function contains a loop with a loop contract, Kani will detect the presence of a loop contract and verify that contract.
+If, however, the loop does not have a contract, then there is currently no way to specify an unwinding bound for the function, meaning that Kani may hang as it tries to unwind the loop.
+We recommend using the --exclude-function option to exclude any functions that have this issue (or --harness-timeout to bail after attempting verification for some amount of time).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/contracts.html b/reference/experimental/contracts.html
new file mode 100644
index 000000000000..270971f5a7d2
--- /dev/null
+++ b/reference/experimental/contracts.html
@@ -0,0 +1,233 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Concrete Playback
+When the result of a certain check comes back as a FAILURE, Kani offers the concrete-playback option to help debug. This feature generates a Rust unit test case that plays back a failing proof harness using a concrete counterexample.
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.
+Usage
+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 bykani::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 togit. +That way, you can easily remove the unit test withgit 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:
-
+
- You can try Kani's experimental extension +provided for VSCode. +
- Otherwise, you can debug the unit test on the command line. +
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.
Example
+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.
Request for comments
+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.
+Limitations
+-
+
- This feature does not generate unit tests for failing non-panic checks (e.g., UB checks). +This is because checks would not trigger runtime errors during concrete playback. +Kani generates warning messages for this. +
- This feature does not support generating unit tests for multiple assertion failures within the same harness. +This limitation might be removed in the future. +Kani generates warning messages for this. +
- This feature requires that you use the same Kani version to generate the test and to playback. +Any extra compilation option used during verification must be used during playback. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/coverage.html b/reference/experimental/coverage.html
new file mode 100644
index 000000000000..5a1cfcf49137
--- /dev/null
+++ b/reference/experimental/coverage.html
@@ -0,0 +1,209 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Contracts
+Consider the following example:
+fn gcd(mut max: u8, mut min: u8) -> u8 {
+ if min > max {
+ std::mem::swap(&mut max, &mut min);
+ }
+
+ let rest = max % min;
+ if rest == 0 { min } else { gcd(min, rest) }
+}
+Let's assume we want to verify some code that calls gcd.
+In the worst case, the number of steps (recursions) in gcd approaches 1.5 times the number of bits needed to represent the input numbers.
+So, for two large 64-bit numbers, a single call to gcd can take almost 96 iterations.
+It would be very expensive for Kani to unroll each of these iterations and then perform symbolic execution.
Instead, we can write contracts with guarantees about gcd's behavior.
+Once Kani verifies that gcd's contracts are correct, it can replace each invocation of gcd with its contracts, which reduces verification time for gcd's callers.
+For example, perhaps we want to ensure that the returned result does indeed divide both max and min.
+In that case, we could write contracts like these:
#[kani::requires(min != 0 && max != 0)]
+#[kani::ensures(|result| *result != 0 && max % *result == 0 && min % *result == 0)]
+#[kani::recursion]
+fn gcd(mut max: u8, mut min: u8) -> u8 { ... }
+Since gcd performs max % min (and perhaps swaps those values), passing zero as an argument could cause a division by zero.
+The requires contract tells Kani to restrict the range of nondeterministic inputs to nonzero ones so that we don't run into this error.
+The ensures contract is what actually checks that the result is a correct divisor for the inputs.
+(The recursion attribute is required when using contracts on recursive functions).
Then, we would write a harness to verify those contracts, like so:
+#[kani::proof_for_contract(gcd)]
+fn check_gcd() {
+ let max: u8 = kani::any();
+ let min: u8 = kani::any();
+ gcd(max, min);
+}
+and verify it by running kani -Z function-contracts.
Once Kani verifies the contracts, we can use Kani's stubbing feature to replace all invocations to gcd with its contracts, for instance:
// Assume foo() invokes gcd().
+// By using stub_verified, we tell Kani to replace
+// invocations of gcd() with its verified contracts.
+#[kani::proof]
+#[kani::stub_verified(gcd)]
+fn check_foo() {
+ let x: u8 = kani::any();
+ foo(x);
+}
+By leveraging the stubbing feature, we can replace the (expensive) gcd call with a verified abstraction of its behavior, greatly reducing verification time for foo.
There is far more to learn about contracts.
+We highly recommend reading our blog post about contracts (from which this gcd example is taken). We also recommend looking at the contracts module in our documentation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/experimental-features.html b/reference/experimental/experimental-features.html
new file mode 100644
index 000000000000..115b17d4727d
--- /dev/null
+++ b/reference/experimental/experimental-features.html
@@ -0,0 +1,186 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Coverage
+Recall our estimate_size example from First steps,
+where we wrote a proof harness constraining the range of inputs to integers less than 4096:
#[cfg(kani)]
+#[kani::proof]
+fn verify_success() {
+ let x: u32 = kani::any();
+ kani::assume(x < 4096);
+ let y = estimate_size(x);
+ assert!(y < 10);
+}
+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.
+In the first-steps-v2 directory, try running:
cargo kani --coverage -Z source-coverage --harness verify_success
+which verifies the harness, then prints coverage information for each line.
+In this case, we see that each line of estimate_size is followed by FULL, indicating that our proof harness provides full coverage.
Try changing the assumption in the proof harness to x < 2048.
+Now the harness won't be testing all possible cases.
+Rerun the command.
+You'll see this line:
src/lib.rs, 24, NONE
+which indicates that the proof no longer covers line 24, which addresses the case where x >= 2048.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/loop-contracts.html b/reference/experimental/loop-contracts.html
new file mode 100644
index 000000000000..0b95e5514166
--- /dev/null
+++ b/reference/experimental/loop-contracts.html
@@ -0,0 +1,312 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Experimental Features
+We elaborate on some of the more commonly used experimental features in Kani.
+This is not an exhaustive list; to see all of Kani's experimental features, run cargo kani --help.
+To use an experimental feature, invoke Kani with the --unstable or -Z flag followed by the name of the feature.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/experimental/stubbing.html b/reference/experimental/stubbing.html
new file mode 100644
index 000000000000..f0968479e652
--- /dev/null
+++ b/reference/experimental/stubbing.html
@@ -0,0 +1,353 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Loop contracts for
+
+
+
+
+ Loop Contracts
+Loop contract are used to specify invariants for loops for the sake of extending Kani's bounded proofs to unbounded proofs. +A loop invariant is an expression that holds upon entering a loop and after every execution of the loop body. +It captures something that does not change about every step of the loop.
+It is worth revisiting the discussion about bounded proof and +loop unwinding. In short, bounds on the number of times Kani unwinds loops also bound the size of inputs, +and hence result in a bounded proof. +Loop contracts are used to abstract out loops as non-loop blocks to avoid loop unwinding, and hence remove the bounds on the inputs.
+Consider the following example:
+fn simple_loop() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ while x > 1 {
+ x = x - 1;
+ }
+
+ assert!(x == 1);
+}
+In this program, the loop repeatedly decrements x until it equals 1. Because we haven't specified an upper bound for x, to verify this function,
+Kani needs to unwind the loop for u64::MAX iterations, which is computationally expensive. Loop contracts allow us to abstract the loop behavior, significantly reducing the verification cost.
With loop contracts, we can specify the loop’s behavior using invariants. For example:
+#![feature(stmt_expr_attributes)]
+#![feature(proc_macro_hygiene)]
+
+fn simple_loop_with_loop_contracts() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while x > 1 {
+ x = x - 1;
+ }
+
+ assert!(x == 1);
+}
+Here, the loop invariant #[kani::loop_invariant(x >= 1)] specifies that the condition x >= 1 must hold true at the start of each iteration before the loop guard is
+checked. Once Kani verifies that the loop invariant is inductive, it will use the invariant to abstract the loop and avoid unwinding.
Now let's run the proof with loop contracts through kani:
+kani simple_loop_with_loop_contracts.rs -Z loop-contracts
+The output reported by Kani on the example will be
+...
+
+
+Check 10: simple_loop_with_loop_contracts.loop_invariant_base.1
+ - Status: SUCCESS
+ - Description: "Check invariant before entry for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 11: simple_loop_with_loop_contracts.loop_assigns.1
+ - Status: SUCCESS
+ - Description: "Check assigns clause inclusion for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 13: simple_loop_with_loop_contracts.assigns.1
+ - Status: SUCCESS
+ - Description: "Check that x is assignable"
+ - Location: simple_while_loop.rs:17:9 in function simple_loop_with_loop_contracts
+
+Check 14: simple_loop_with_loop_contracts.loop_invariant_step.1
+ - Status: SUCCESS
+ - Description: "Check invariant after step for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+Check 15: simple_loop_with_loop_contracts.loop_invariant_step.2
+ - Status: SUCCESS
+ - Description: "Check invariant after step for loop simple_loop_with_loop_contracts.0"
+ - Location: simple_while_loop.rs:15:5 in function simple_loop_with_loop_contracts
+
+...
+
+SUMMARY:
+ ** 0 of 99 failed
+
+VERIFICATION:- SUCCESSFUL
+Verification Time: 0.3897019s
+
+Complete - 1 successfully verified harnesses, 0 failures, 1 total.
+Loop contracts for while loops
+Syntax
+++#[kani::loop_invariant( Expression )]
++
whileExpressionexcept struct expression BlockExpression
An invariant contract #[kani::loop_invariant(cond)] accepts a valid Boolean expression cond over the variables visible at the same scope as the loop.
Semantics
+A loop invariant contract expands to several assumptions and assertions:
+-
+
- The invariant is asserted just before the first iteration. +
- The invariant is assumed on a non-deterministic state to model a non-deterministic iteration. +
- The invariant is finally asserted again to establish its inductiveness. +
Mathematical induction is the working principle here. (1) establishes the base case for induction, and (2) & (3) establish the inductive case. +Therefore, the invariant must hold after the loop execution for any number of iterations. The invariant, together with the negation of the loop guard, +must be sufficient to establish subsequent assertions. If it is not, the abstraction is too imprecise and the user must supply a stronger invariant.
+To illustrate the key idea, we show how Kani abstracts the loop in simple_loop_with_loop_contracts as a non-loop block:
assert!(x >= 1) // check loop invariant for the base case.
+x = kani::any();
+kani::assume(x >= 1);
+if x > 1 {
+ // proof path 1:
+ // both loop guard and loop invariant are satisfied.
+ x = x - 1;
+ assert!(x >= 1); // check that loop invariant is inductive.
+ kani::assume(false) // block this proof path.
+}
+// proof path 2:
+// loop invariant is satisfied and loop guard is violated.
+assert!(x == 1);
+That is, we assume that we are in an arbitrary iteration after checking that the loop invariant holds for the base case. With the inductive hypothesis (kani::assume(x >= 1);),
+we will either enter the loop (proof path 1) or leave the loop (proof path 2). We prove the two paths separately by killing path 1 with kani::assume(false);.
+Note that all assertions after kani::assume(false) will be ignored as false => p can be deduced as true for any p.
In proof path 1, we prove properties inside the loop and at last check that the loop invariant is inductive.
+In proof path 2, we prove properties after leaving the loop. As we leave the loop only when the loop guard is violated, the post condition of the loop can be expressed as
+!guard && inv, which is x <= 1 && x >= 1 in the example. The postcondition implies x == 1—the property we want to prove at the end of simple_loop_with_loop_contracts.
Limitations
+Loop contracts comes with the following limitations.
+-
+
- Only
whileloops are supported. The other three kinds of loops are not supported:looploops +,while letloops, andforloops.
+ - Kani infers loop modifies with alias analysis. Loop modifies are those variables we assume to be arbitrary in the inductive hypothesis, and should cover all memory locations that are written to during +the execution of the loops. A proof will fail if the inferred loop modifies misses some targets written in the loops. +We observed this happens when some fields of structs are modified by some other functions called in the loops. +
- Kani doesn't check if a loop will always terminate in proofs with loop contracts. So it could be that some properties are proved successfully with Kani but actually are unreachable due to the +non-termination of some loops. +
- We don't check if loop invariants are side-effect free. A loop invariant with a side effect could lead to an unsound proof result. Make sure that the specified loop contracts are side-effect free. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/regression-testing.html b/regression-testing.html
new file mode 100644
index 000000000000..e81e0e8f5249
--- /dev/null
+++ b/regression-testing.html
@@ -0,0 +1,362 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The
+An example: stubbing
+
+
+
+
+ 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).
+When to consider stubbing
+In general, we have identified three reasons where users may consider stubbing:
+-
+
- Unsupported features: The code under verification contains features that Kani does not support, such as inline assembly. +
- Bad performance: The code under verification contains features that Kani supports, but it leads to bad verification performance (for example, deserialization code). +
- Compositional reasoning: The code under verification contains code that has been verified separately. +Stubbing the code that has already been verified with a less complex version that mimics its behavior can result in reduced verification workloads. +
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.
+Components
+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.
The #[kani::stub(...)] attribute
+The 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.
+An example: stubbing random
+Let'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.
+Limitations
+In the following, we describe all the limitations of the stubbing feature.
+Usage restrictions
+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
+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:
+-
+
- Types +
- Macros +
- Traits +
- Intrinsics +
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.
+Error conditions
+Given a set of original-replacement pairs, Kani will exit with an error if:
-
+
- a specified
originalfunction does not exist;
+ - a specified
replacementstub does not exist;
+ - the user specifies conflicting stubs for the same harness (e.g., if the same
originalfunction is mapped to multiplereplacementfunctions); or
+ - the signature of the
replacementstub is not compatible with the signature of theoriginalfunction/method (see next section).
+
Stub compatibility and validation
+We consider a stub and a function/method to be compatible if all the following conditions are met:
+-
+
- They have the same number of parameters. +
- They have the same return type. +
- Each parameter in the stub has the same type as the corresponding parameter in the original function/method. +
- The stub must have the same number of generic parameters as the original function/method.
+However, a generic parameter in the stub is allowed to have a different name than the corresponding parameter in the original function/method.
+For example, the stub
bar<A, B>(x: A, y: B) -> Bis considered to have a type compatible with the functionfoo<S, T>(x: S, y: T) -> T.
+ - The bounds for each type parameter don't need to match; however, all calls to the original function must also satisfy the bounds of the stub. +
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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/repo-crawl.html b/repo-crawl.html
new file mode 100644
index 000000000000..3e80446e53c4
--- /dev/null
+++ b/repo-crawl.html
@@ -0,0 +1,269 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The
+
+
+
+
+ Regression testing
+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.
+Kani testing suites
+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 likekanibut contains tests inspired by +Firecracker code.
+prusti: Works likekanibut contains tests from the +Prusti tool.
+smack: Works likekanibut contains tests from the +SMACK tool.
+kani-fixme: Similar tokani, but runs ignored tests from thekanitesting +suite (i.e., tests withfixmeorignorein their name). +Allows us to detect when a previously not supported test becomes +supported. More details in "Fixme" tests.
+expected: Similar tokanibut with an additional check which ensures that +lines appearing in*.expectedfiles appear in the output +generated bykani.
+ui: Works likeexpected, but focuses on the user interface (e.g., +warnings) instead of the verification output.
+cargo-kani: This suite is designed to test thecargo-kanicommand. As such, +this suite works with packages instead of single Rust files. +Arguments can be specified in theCargo.tomlconfiguration file. +Similar to theexpectedsuite, we look for*.expectedfiles +for each harness in the package.
+cargo-ui: Similar tocargo-kani, but focuses on the user interface like theuitest 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 theexecmode, 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).
Testing stages
+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.
Testing options
+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.
"Fixme" tests
+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:
-
+
- Only runs tests whose name contains
fixmeorignore(ignoring the rest).
+ - The expected outcome is failure. In other words, a test is successful if it +fails. +
We welcome contributions with "fixme" tests which demonstrate a bug or +unsupported feature in Kani. Ideally, the test should include some comments +regarding:
+-
+
- The expected result of the test. +
- The actual result of the test (e.g., interesting parts of the output). +
- Links to related issues. +
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.
Rust unit tests
+These tests follow the +Rust unit testing +style.
+At present, Kani runs unit tests from the following packages:
+-
+
cprover_bindings
+kani-compiler
+cargo-kani
+
Python unit tests
+We use the Python unit testing framework to +test the CBMC JSON parser.
+Script-based tests
+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:
+-
+
- Standard library codegen +
- Firecracker virtio codegen +
- Diamond dependency +
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).
The exec mode
+The 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.expectedfile 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/.nojekyll b/rfc/.nojekyll
new file mode 100644
index 000000000000..f17311098f54
--- /dev/null
+++ b/rfc/.nojekyll
@@ -0,0 +1 @@
+This file makes sure that Github Pages doesn't process mdBook's output.
diff --git a/rfc/404.html b/rfc/404.html
new file mode 100644
index 000000000000..afb9c66021ca
--- /dev/null
+++ b/rfc/404.html
@@ -0,0 +1,170 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ (Experimental) Testing with a Large Number of Repositories
+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.
+Picking 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 +
- docker-compose. +
-
+
- Start PostgreSQL. Paste in the following yaml file as
+
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.
+-
+
- URL from CSV:
cat top-1k.csv | awk -F ',' '{ print $2 }' | grep -v 'http.*'
+ - Remove long paths:
sed 's/tree\/master.*$//g'
+ - Once processed, you can dedup with
sort | uniq --unique
+
+ - URL from CSV:
Running the List of Repositories
+In 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/FontAwesome/css/font-awesome.css b/rfc/FontAwesome/css/font-awesome.css
new file mode 100644
index 000000000000..540440ce89f2
--- /dev/null
+++ b/rfc/FontAwesome/css/font-awesome.css
@@ -0,0 +1,4 @@
+/*!
+ * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
+ * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
+ */@font-face{font-family:'FontAwesome';src:url('../fonts/fontawesome-webfont.eot?v=4.7.0');src:url('../fonts/fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'),url('../fonts/fontawesome-webfont.woff2?v=4.7.0') format('woff2'),url('../fonts/fontawesome-webfont.woff?v=4.7.0') format('woff'),url('../fonts/fontawesome-webfont.ttf?v=4.7.0') format('truetype'),url('../fonts/fontawesome-webfont.svg?v=4.7.0#fontawesomeregular') format('svg');font-weight:normal;font-style:normal}.fa{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571429em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14285714em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14285714em;width:2.14285714em;top:.14285714em;text-align:center}.fa-li.fa-lg{left:-1.85714286em}.fa-border{padding:.2em .25em .15em;border:solid .08em #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa.fa-pull-left{margin-right:.3em}.fa.fa-pull-right{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left{margin-right:.3em}.fa.pull-right{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s infinite linear;animation:fa-spin 2s infinite linear}.fa-pulse{-webkit-animation:fa-spin 1s infinite steps(8);animation:fa-spin 1s infinite steps(8)}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scale(-1, 1);-ms-transform:scale(-1, 1);transform:scale(-1, 1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scale(1, -1);-ms-transform:scale(1, -1);transform:scale(1, -1)}:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270,:root .fa-flip-horizontal,:root .fa-flip-vertical{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:"\f000"}.fa-music:before{content:"\f001"}.fa-search:before{content:"\f002"}.fa-envelope-o:before{content:"\f003"}.fa-heart:before{content:"\f004"}.fa-star:before{content:"\f005"}.fa-star-o:before{content:"\f006"}.fa-user:before{content:"\f007"}.fa-film:before{content:"\f008"}.fa-th-large:before{content:"\f009"}.fa-th:before{content:"\f00a"}.fa-th-list:before{content:"\f00b"}.fa-check:before{content:"\f00c"}.fa-remove:before,.fa-close:before,.fa-times:before{content:"\f00d"}.fa-search-plus:before{content:"\f00e"}.fa-search-minus:before{content:"\f010"}.fa-power-off:before{content:"\f011"}.fa-signal:before{content:"\f012"}.fa-gear:before,.fa-cog:before{content:"\f013"}.fa-trash-o:before{content:"\f014"}.fa-home:before{content:"\f015"}.fa-file-o:before{content:"\f016"}.fa-clock-o:before{content:"\f017"}.fa-road:before{content:"\f018"}.fa-download:before{content:"\f019"}.fa-arrow-circle-o-down:before{content:"\f01a"}.fa-arrow-circle-o-up:before{content:"\f01b"}.fa-inbox:before{content:"\f01c"}.fa-play-circle-o:before{content:"\f01d"}.fa-rotate-right:before,.fa-repeat:before{content:"\f01e"}.fa-refresh:before{content:"\f021"}.fa-list-alt:before{content:"\f022"}.fa-lock:before{content:"\f023"}.fa-flag:before{content:"\f024"}.fa-headphones:before{content:"\f025"}.fa-volume-off:before{content:"\f026"}.fa-volume-down:before{content:"\f027"}.fa-volume-up:before{content:"\f028"}.fa-qrcode:before{content:"\f029"}.fa-barcode:before{content:"\f02a"}.fa-tag:before{content:"\f02b"}.fa-tags:before{content:"\f02c"}.fa-book:before{content:"\f02d"}.fa-bookmark:before{content:"\f02e"}.fa-print:before{content:"\f02f"}.fa-camera:before{content:"\f030"}.fa-font:before{content:"\f031"}.fa-bold:before{content:"\f032"}.fa-italic:before{content:"\f033"}.fa-text-height:before{content:"\f034"}.fa-text-width:before{content:"\f035"}.fa-align-left:before{content:"\f036"}.fa-align-center:before{content:"\f037"}.fa-align-right:before{content:"\f038"}.fa-align-justify:before{content:"\f039"}.fa-list:before{content:"\f03a"}.fa-dedent:before,.fa-outdent:before{content:"\f03b"}.fa-indent:before{content:"\f03c"}.fa-video-camera:before{content:"\f03d"}.fa-photo:before,.fa-image:before,.fa-picture-o:before{content:"\f03e"}.fa-pencil:before{content:"\f040"}.fa-map-marker:before{content:"\f041"}.fa-adjust:before{content:"\f042"}.fa-tint:before{content:"\f043"}.fa-edit:before,.fa-pencil-square-o:before{content:"\f044"}.fa-share-square-o:before{content:"\f045"}.fa-check-square-o:before{content:"\f046"}.fa-arrows:before{content:"\f047"}.fa-step-backward:before{content:"\f048"}.fa-fast-backward:before{content:"\f049"}.fa-backward:before{content:"\f04a"}.fa-play:before{content:"\f04b"}.fa-pause:before{content:"\f04c"}.fa-stop:before{content:"\f04d"}.fa-forward:before{content:"\f04e"}.fa-fast-forward:before{content:"\f050"}.fa-step-forward:before{content:"\f051"}.fa-eject:before{content:"\f052"}.fa-chevron-left:before{content:"\f053"}.fa-chevron-right:before{content:"\f054"}.fa-plus-circle:before{content:"\f055"}.fa-minus-circle:before{content:"\f056"}.fa-times-circle:before{content:"\f057"}.fa-check-circle:before{content:"\f058"}.fa-question-circle:before{content:"\f059"}.fa-info-circle:before{content:"\f05a"}.fa-crosshairs:before{content:"\f05b"}.fa-times-circle-o:before{content:"\f05c"}.fa-check-circle-o:before{content:"\f05d"}.fa-ban:before{content:"\f05e"}.fa-arrow-left:before{content:"\f060"}.fa-arrow-right:before{content:"\f061"}.fa-arrow-up:before{content:"\f062"}.fa-arrow-down:before{content:"\f063"}.fa-mail-forward:before,.fa-share:before{content:"\f064"}.fa-expand:before{content:"\f065"}.fa-compress:before{content:"\f066"}.fa-plus:before{content:"\f067"}.fa-minus:before{content:"\f068"}.fa-asterisk:before{content:"\f069"}.fa-exclamation-circle:before{content:"\f06a"}.fa-gift:before{content:"\f06b"}.fa-leaf:before{content:"\f06c"}.fa-fire:before{content:"\f06d"}.fa-eye:before{content:"\f06e"}.fa-eye-slash:before{content:"\f070"}.fa-warning:before,.fa-exclamation-triangle:before{content:"\f071"}.fa-plane:before{content:"\f072"}.fa-calendar:before{content:"\f073"}.fa-random:before{content:"\f074"}.fa-comment:before{content:"\f075"}.fa-magnet:before{content:"\f076"}.fa-chevron-up:before{content:"\f077"}.fa-chevron-down:before{content:"\f078"}.fa-retweet:before{content:"\f079"}.fa-shopping-cart:before{content:"\f07a"}.fa-folder:before{content:"\f07b"}.fa-folder-open:before{content:"\f07c"}.fa-arrows-v:before{content:"\f07d"}.fa-arrows-h:before{content:"\f07e"}.fa-bar-chart-o:before,.fa-bar-chart:before{content:"\f080"}.fa-twitter-square:before{content:"\f081"}.fa-facebook-square:before{content:"\f082"}.fa-camera-retro:before{content:"\f083"}.fa-key:before{content:"\f084"}.fa-gears:before,.fa-cogs:before{content:"\f085"}.fa-comments:before{content:"\f086"}.fa-thumbs-o-up:before{content:"\f087"}.fa-thumbs-o-down:before{content:"\f088"}.fa-star-half:before{content:"\f089"}.fa-heart-o:before{content:"\f08a"}.fa-sign-out:before{content:"\f08b"}.fa-linkedin-square:before{content:"\f08c"}.fa-thumb-tack:before{content:"\f08d"}.fa-external-link:before{content:"\f08e"}.fa-sign-in:before{content:"\f090"}.fa-trophy:before{content:"\f091"}.fa-github-square:before{content:"\f092"}.fa-upload:before{content:"\f093"}.fa-lemon-o:before{content:"\f094"}.fa-phone:before{content:"\f095"}.fa-square-o:before{content:"\f096"}.fa-bookmark-o:before{content:"\f097"}.fa-phone-square:before{content:"\f098"}.fa-twitter:before{content:"\f099"}.fa-facebook-f:before,.fa-facebook:before{content:"\f09a"}.fa-github:before{content:"\f09b"}.fa-unlock:before{content:"\f09c"}.fa-credit-card:before{content:"\f09d"}.fa-feed:before,.fa-rss:before{content:"\f09e"}.fa-hdd-o:before{content:"\f0a0"}.fa-bullhorn:before{content:"\f0a1"}.fa-bell:before{content:"\f0f3"}.fa-certificate:before{content:"\f0a3"}.fa-hand-o-right:before{content:"\f0a4"}.fa-hand-o-left:before{content:"\f0a5"}.fa-hand-o-up:before{content:"\f0a6"}.fa-hand-o-down:before{content:"\f0a7"}.fa-arrow-circle-left:before{content:"\f0a8"}.fa-arrow-circle-right:before{content:"\f0a9"}.fa-arrow-circle-up:before{content:"\f0aa"}.fa-arrow-circle-down:before{content:"\f0ab"}.fa-globe:before{content:"\f0ac"}.fa-wrench:before{content:"\f0ad"}.fa-tasks:before{content:"\f0ae"}.fa-filter:before{content:"\f0b0"}.fa-briefcase:before{content:"\f0b1"}.fa-arrows-alt:before{content:"\f0b2"}.fa-group:before,.fa-users:before{content:"\f0c0"}.fa-chain:before,.fa-link:before{content:"\f0c1"}.fa-cloud:before{content:"\f0c2"}.fa-flask:before{content:"\f0c3"}.fa-cut:before,.fa-scissors:before{content:"\f0c4"}.fa-copy:before,.fa-files-o:before{content:"\f0c5"}.fa-paperclip:before{content:"\f0c6"}.fa-save:before,.fa-floppy-o:before{content:"\f0c7"}.fa-square:before{content:"\f0c8"}.fa-navicon:before,.fa-reorder:before,.fa-bars:before{content:"\f0c9"}.fa-list-ul:before{content:"\f0ca"}.fa-list-ol:before{content:"\f0cb"}.fa-strikethrough:before{content:"\f0cc"}.fa-underline:before{content:"\f0cd"}.fa-table:before{content:"\f0ce"}.fa-magic:before{content:"\f0d0"}.fa-truck:before{content:"\f0d1"}.fa-pinterest:before{content:"\f0d2"}.fa-pinterest-square:before{content:"\f0d3"}.fa-google-plus-square:before{content:"\f0d4"}.fa-google-plus:before{content:"\f0d5"}.fa-money:before{content:"\f0d6"}.fa-caret-down:before{content:"\f0d7"}.fa-caret-up:before{content:"\f0d8"}.fa-caret-left:before{content:"\f0d9"}.fa-caret-right:before{content:"\f0da"}.fa-columns:before{content:"\f0db"}.fa-unsorted:before,.fa-sort:before{content:"\f0dc"}.fa-sort-down:before,.fa-sort-desc:before{content:"\f0dd"}.fa-sort-up:before,.fa-sort-asc:before{content:"\f0de"}.fa-envelope:before{content:"\f0e0"}.fa-linkedin:before{content:"\f0e1"}.fa-rotate-left:before,.fa-undo:before{content:"\f0e2"}.fa-legal:before,.fa-gavel:before{content:"\f0e3"}.fa-dashboard:before,.fa-tachometer:before{content:"\f0e4"}.fa-comment-o:before{content:"\f0e5"}.fa-comments-o:before{content:"\f0e6"}.fa-flash:before,.fa-bolt:before{content:"\f0e7"}.fa-sitemap:before{content:"\f0e8"}.fa-umbrella:before{content:"\f0e9"}.fa-paste:before,.fa-clipboard:before{content:"\f0ea"}.fa-lightbulb-o:before{content:"\f0eb"}.fa-exchange:before{content:"\f0ec"}.fa-cloud-download:before{content:"\f0ed"}.fa-cloud-upload:before{content:"\f0ee"}.fa-user-md:before{content:"\f0f0"}.fa-stethoscope:before{content:"\f0f1"}.fa-suitcase:before{content:"\f0f2"}.fa-bell-o:before{content:"\f0a2"}.fa-coffee:before{content:"\f0f4"}.fa-cutlery:before{content:"\f0f5"}.fa-file-text-o:before{content:"\f0f6"}.fa-building-o:before{content:"\f0f7"}.fa-hospital-o:before{content:"\f0f8"}.fa-ambulance:before{content:"\f0f9"}.fa-medkit:before{content:"\f0fa"}.fa-fighter-jet:before{content:"\f0fb"}.fa-beer:before{content:"\f0fc"}.fa-h-square:before{content:"\f0fd"}.fa-plus-square:before{content:"\f0fe"}.fa-angle-double-left:before{content:"\f100"}.fa-angle-double-right:before{content:"\f101"}.fa-angle-double-up:before{content:"\f102"}.fa-angle-double-down:before{content:"\f103"}.fa-angle-left:before{content:"\f104"}.fa-angle-right:before{content:"\f105"}.fa-angle-up:before{content:"\f106"}.fa-angle-down:before{content:"\f107"}.fa-desktop:before{content:"\f108"}.fa-laptop:before{content:"\f109"}.fa-tablet:before{content:"\f10a"}.fa-mobile-phone:before,.fa-mobile:before{content:"\f10b"}.fa-circle-o:before{content:"\f10c"}.fa-quote-left:before{content:"\f10d"}.fa-quote-right:before{content:"\f10e"}.fa-spinner:before{content:"\f110"}.fa-circle:before{content:"\f111"}.fa-mail-reply:before,.fa-reply:before{content:"\f112"}.fa-github-alt:before{content:"\f113"}.fa-folder-o:before{content:"\f114"}.fa-folder-open-o:before{content:"\f115"}.fa-smile-o:before{content:"\f118"}.fa-frown-o:before{content:"\f119"}.fa-meh-o:before{content:"\f11a"}.fa-gamepad:before{content:"\f11b"}.fa-keyboard-o:before{content:"\f11c"}.fa-flag-o:before{content:"\f11d"}.fa-flag-checkered:before{content:"\f11e"}.fa-terminal:before{content:"\f120"}.fa-code:before{content:"\f121"}.fa-mail-reply-all:before,.fa-reply-all:before{content:"\f122"}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:"\f123"}.fa-location-arrow:before{content:"\f124"}.fa-crop:before{content:"\f125"}.fa-code-fork:before{content:"\f126"}.fa-unlink:before,.fa-chain-broken:before{content:"\f127"}.fa-question:before{content:"\f128"}.fa-info:before{content:"\f129"}.fa-exclamation:before{content:"\f12a"}.fa-superscript:before{content:"\f12b"}.fa-subscript:before{content:"\f12c"}.fa-eraser:before{content:"\f12d"}.fa-puzzle-piece:before{content:"\f12e"}.fa-microphone:before{content:"\f130"}.fa-microphone-slash:before{content:"\f131"}.fa-shield:before{content:"\f132"}.fa-calendar-o:before{content:"\f133"}.fa-fire-extinguisher:before{content:"\f134"}.fa-rocket:before{content:"\f135"}.fa-maxcdn:before{content:"\f136"}.fa-chevron-circle-left:before{content:"\f137"}.fa-chevron-circle-right:before{content:"\f138"}.fa-chevron-circle-up:before{content:"\f139"}.fa-chevron-circle-down:before{content:"\f13a"}.fa-html5:before{content:"\f13b"}.fa-css3:before{content:"\f13c"}.fa-anchor:before{content:"\f13d"}.fa-unlock-alt:before{content:"\f13e"}.fa-bullseye:before{content:"\f140"}.fa-ellipsis-h:before{content:"\f141"}.fa-ellipsis-v:before{content:"\f142"}.fa-rss-square:before{content:"\f143"}.fa-play-circle:before{content:"\f144"}.fa-ticket:before{content:"\f145"}.fa-minus-square:before{content:"\f146"}.fa-minus-square-o:before{content:"\f147"}.fa-level-up:before{content:"\f148"}.fa-level-down:before{content:"\f149"}.fa-check-square:before{content:"\f14a"}.fa-pencil-square:before{content:"\f14b"}.fa-external-link-square:before{content:"\f14c"}.fa-share-square:before{content:"\f14d"}.fa-compass:before{content:"\f14e"}.fa-toggle-down:before,.fa-caret-square-o-down:before{content:"\f150"}.fa-toggle-up:before,.fa-caret-square-o-up:before{content:"\f151"}.fa-toggle-right:before,.fa-caret-square-o-right:before{content:"\f152"}.fa-euro:before,.fa-eur:before{content:"\f153"}.fa-gbp:before{content:"\f154"}.fa-dollar:before,.fa-usd:before{content:"\f155"}.fa-rupee:before,.fa-inr:before{content:"\f156"}.fa-cny:before,.fa-rmb:before,.fa-yen:before,.fa-jpy:before{content:"\f157"}.fa-ruble:before,.fa-rouble:before,.fa-rub:before{content:"\f158"}.fa-won:before,.fa-krw:before{content:"\f159"}.fa-bitcoin:before,.fa-btc:before{content:"\f15a"}.fa-file:before{content:"\f15b"}.fa-file-text:before{content:"\f15c"}.fa-sort-alpha-asc:before{content:"\f15d"}.fa-sort-alpha-desc:before{content:"\f15e"}.fa-sort-amount-asc:before{content:"\f160"}.fa-sort-amount-desc:before{content:"\f161"}.fa-sort-numeric-asc:before{content:"\f162"}.fa-sort-numeric-desc:before{content:"\f163"}.fa-thumbs-up:before{content:"\f164"}.fa-thumbs-down:before{content:"\f165"}.fa-youtube-square:before{content:"\f166"}.fa-youtube:before{content:"\f167"}.fa-xing:before{content:"\f168"}.fa-xing-square:before{content:"\f169"}.fa-youtube-play:before{content:"\f16a"}.fa-dropbox:before{content:"\f16b"}.fa-stack-overflow:before{content:"\f16c"}.fa-instagram:before{content:"\f16d"}.fa-flickr:before{content:"\f16e"}.fa-adn:before{content:"\f170"}.fa-bitbucket:before{content:"\f171"}.fa-bitbucket-square:before{content:"\f172"}.fa-tumblr:before{content:"\f173"}.fa-tumblr-square:before{content:"\f174"}.fa-long-arrow-down:before{content:"\f175"}.fa-long-arrow-up:before{content:"\f176"}.fa-long-arrow-left:before{content:"\f177"}.fa-long-arrow-right:before{content:"\f178"}.fa-apple:before{content:"\f179"}.fa-windows:before{content:"\f17a"}.fa-android:before{content:"\f17b"}.fa-linux:before{content:"\f17c"}.fa-dribbble:before{content:"\f17d"}.fa-skype:before{content:"\f17e"}.fa-foursquare:before{content:"\f180"}.fa-trello:before{content:"\f181"}.fa-female:before{content:"\f182"}.fa-male:before{content:"\f183"}.fa-gittip:before,.fa-gratipay:before{content:"\f184"}.fa-sun-o:before{content:"\f185"}.fa-moon-o:before{content:"\f186"}.fa-archive:before{content:"\f187"}.fa-bug:before{content:"\f188"}.fa-vk:before{content:"\f189"}.fa-weibo:before{content:"\f18a"}.fa-renren:before{content:"\f18b"}.fa-pagelines:before{content:"\f18c"}.fa-stack-exchange:before{content:"\f18d"}.fa-arrow-circle-o-right:before{content:"\f18e"}.fa-arrow-circle-o-left:before{content:"\f190"}.fa-toggle-left:before,.fa-caret-square-o-left:before{content:"\f191"}.fa-dot-circle-o:before{content:"\f192"}.fa-wheelchair:before{content:"\f193"}.fa-vimeo-square:before{content:"\f194"}.fa-turkish-lira:before,.fa-try:before{content:"\f195"}.fa-plus-square-o:before{content:"\f196"}.fa-space-shuttle:before{content:"\f197"}.fa-slack:before{content:"\f198"}.fa-envelope-square:before{content:"\f199"}.fa-wordpress:before{content:"\f19a"}.fa-openid:before{content:"\f19b"}.fa-institution:before,.fa-bank:before,.fa-university:before{content:"\f19c"}.fa-mortar-board:before,.fa-graduation-cap:before{content:"\f19d"}.fa-yahoo:before{content:"\f19e"}.fa-google:before{content:"\f1a0"}.fa-reddit:before{content:"\f1a1"}.fa-reddit-square:before{content:"\f1a2"}.fa-stumbleupon-circle:before{content:"\f1a3"}.fa-stumbleupon:before{content:"\f1a4"}.fa-delicious:before{content:"\f1a5"}.fa-digg:before{content:"\f1a6"}.fa-pied-piper-pp:before{content:"\f1a7"}.fa-pied-piper-alt:before{content:"\f1a8"}.fa-drupal:before{content:"\f1a9"}.fa-joomla:before{content:"\f1aa"}.fa-language:before{content:"\f1ab"}.fa-fax:before{content:"\f1ac"}.fa-building:before{content:"\f1ad"}.fa-child:before{content:"\f1ae"}.fa-paw:before{content:"\f1b0"}.fa-spoon:before{content:"\f1b1"}.fa-cube:before{content:"\f1b2"}.fa-cubes:before{content:"\f1b3"}.fa-behance:before{content:"\f1b4"}.fa-behance-square:before{content:"\f1b5"}.fa-steam:before{content:"\f1b6"}.fa-steam-square:before{content:"\f1b7"}.fa-recycle:before{content:"\f1b8"}.fa-automobile:before,.fa-car:before{content:"\f1b9"}.fa-cab:before,.fa-taxi:before{content:"\f1ba"}.fa-tree:before{content:"\f1bb"}.fa-spotify:before{content:"\f1bc"}.fa-deviantart:before{content:"\f1bd"}.fa-soundcloud:before{content:"\f1be"}.fa-database:before{content:"\f1c0"}.fa-file-pdf-o:before{content:"\f1c1"}.fa-file-word-o:before{content:"\f1c2"}.fa-file-excel-o:before{content:"\f1c3"}.fa-file-powerpoint-o:before{content:"\f1c4"}.fa-file-photo-o:before,.fa-file-picture-o:before,.fa-file-image-o:before{content:"\f1c5"}.fa-file-zip-o:before,.fa-file-archive-o:before{content:"\f1c6"}.fa-file-sound-o:before,.fa-file-audio-o:before{content:"\f1c7"}.fa-file-movie-o:before,.fa-file-video-o:before{content:"\f1c8"}.fa-file-code-o:before{content:"\f1c9"}.fa-vine:before{content:"\f1ca"}.fa-codepen:before{content:"\f1cb"}.fa-jsfiddle:before{content:"\f1cc"}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-saver:before,.fa-support:before,.fa-life-ring:before{content:"\f1cd"}.fa-circle-o-notch:before{content:"\f1ce"}.fa-ra:before,.fa-resistance:before,.fa-rebel:before{content:"\f1d0"}.fa-ge:before,.fa-empire:before{content:"\f1d1"}.fa-git-square:before{content:"\f1d2"}.fa-git:before{content:"\f1d3"}.fa-y-combinator-square:before,.fa-yc-square:before,.fa-hacker-news:before{content:"\f1d4"}.fa-tencent-weibo:before{content:"\f1d5"}.fa-qq:before{content:"\f1d6"}.fa-wechat:before,.fa-weixin:before{content:"\f1d7"}.fa-send:before,.fa-paper-plane:before{content:"\f1d8"}.fa-send-o:before,.fa-paper-plane-o:before{content:"\f1d9"}.fa-history:before{content:"\f1da"}.fa-circle-thin:before{content:"\f1db"}.fa-header:before{content:"\f1dc"}.fa-paragraph:before{content:"\f1dd"}.fa-sliders:before{content:"\f1de"}.fa-share-alt:before{content:"\f1e0"}.fa-share-alt-square:before{content:"\f1e1"}.fa-bomb:before{content:"\f1e2"}.fa-soccer-ball-o:before,.fa-futbol-o:before{content:"\f1e3"}.fa-tty:before{content:"\f1e4"}.fa-binoculars:before{content:"\f1e5"}.fa-plug:before{content:"\f1e6"}.fa-slideshare:before{content:"\f1e7"}.fa-twitch:before{content:"\f1e8"}.fa-yelp:before{content:"\f1e9"}.fa-newspaper-o:before{content:"\f1ea"}.fa-wifi:before{content:"\f1eb"}.fa-calculator:before{content:"\f1ec"}.fa-paypal:before{content:"\f1ed"}.fa-google-wallet:before{content:"\f1ee"}.fa-cc-visa:before{content:"\f1f0"}.fa-cc-mastercard:before{content:"\f1f1"}.fa-cc-discover:before{content:"\f1f2"}.fa-cc-amex:before{content:"\f1f3"}.fa-cc-paypal:before{content:"\f1f4"}.fa-cc-stripe:before{content:"\f1f5"}.fa-bell-slash:before{content:"\f1f6"}.fa-bell-slash-o:before{content:"\f1f7"}.fa-trash:before{content:"\f1f8"}.fa-copyright:before{content:"\f1f9"}.fa-at:before{content:"\f1fa"}.fa-eyedropper:before{content:"\f1fb"}.fa-paint-brush:before{content:"\f1fc"}.fa-birthday-cake:before{content:"\f1fd"}.fa-area-chart:before{content:"\f1fe"}.fa-pie-chart:before{content:"\f200"}.fa-line-chart:before{content:"\f201"}.fa-lastfm:before{content:"\f202"}.fa-lastfm-square:before{content:"\f203"}.fa-toggle-off:before{content:"\f204"}.fa-toggle-on:before{content:"\f205"}.fa-bicycle:before{content:"\f206"}.fa-bus:before{content:"\f207"}.fa-ioxhost:before{content:"\f208"}.fa-angellist:before{content:"\f209"}.fa-cc:before{content:"\f20a"}.fa-shekel:before,.fa-sheqel:before,.fa-ils:before{content:"\f20b"}.fa-meanpath:before{content:"\f20c"}.fa-buysellads:before{content:"\f20d"}.fa-connectdevelop:before{content:"\f20e"}.fa-dashcube:before{content:"\f210"}.fa-forumbee:before{content:"\f211"}.fa-leanpub:before{content:"\f212"}.fa-sellsy:before{content:"\f213"}.fa-shirtsinbulk:before{content:"\f214"}.fa-simplybuilt:before{content:"\f215"}.fa-skyatlas:before{content:"\f216"}.fa-cart-plus:before{content:"\f217"}.fa-cart-arrow-down:before{content:"\f218"}.fa-diamond:before{content:"\f219"}.fa-ship:before{content:"\f21a"}.fa-user-secret:before{content:"\f21b"}.fa-motorcycle:before{content:"\f21c"}.fa-street-view:before{content:"\f21d"}.fa-heartbeat:before{content:"\f21e"}.fa-venus:before{content:"\f221"}.fa-mars:before{content:"\f222"}.fa-mercury:before{content:"\f223"}.fa-intersex:before,.fa-transgender:before{content:"\f224"}.fa-transgender-alt:before{content:"\f225"}.fa-venus-double:before{content:"\f226"}.fa-mars-double:before{content:"\f227"}.fa-venus-mars:before{content:"\f228"}.fa-mars-stroke:before{content:"\f229"}.fa-mars-stroke-v:before{content:"\f22a"}.fa-mars-stroke-h:before{content:"\f22b"}.fa-neuter:before{content:"\f22c"}.fa-genderless:before{content:"\f22d"}.fa-facebook-official:before{content:"\f230"}.fa-pinterest-p:before{content:"\f231"}.fa-whatsapp:before{content:"\f232"}.fa-server:before{content:"\f233"}.fa-user-plus:before{content:"\f234"}.fa-user-times:before{content:"\f235"}.fa-hotel:before,.fa-bed:before{content:"\f236"}.fa-viacoin:before{content:"\f237"}.fa-train:before{content:"\f238"}.fa-subway:before{content:"\f239"}.fa-medium:before{content:"\f23a"}.fa-yc:before,.fa-y-combinator:before{content:"\f23b"}.fa-optin-monster:before{content:"\f23c"}.fa-opencart:before{content:"\f23d"}.fa-expeditedssl:before{content:"\f23e"}.fa-battery-4:before,.fa-battery:before,.fa-battery-full:before{content:"\f240"}.fa-battery-3:before,.fa-battery-three-quarters:before{content:"\f241"}.fa-battery-2:before,.fa-battery-half:before{content:"\f242"}.fa-battery-1:before,.fa-battery-quarter:before{content:"\f243"}.fa-battery-0:before,.fa-battery-empty:before{content:"\f244"}.fa-mouse-pointer:before{content:"\f245"}.fa-i-cursor:before{content:"\f246"}.fa-object-group:before{content:"\f247"}.fa-object-ungroup:before{content:"\f248"}.fa-sticky-note:before{content:"\f249"}.fa-sticky-note-o:before{content:"\f24a"}.fa-cc-jcb:before{content:"\f24b"}.fa-cc-diners-club:before{content:"\f24c"}.fa-clone:before{content:"\f24d"}.fa-balance-scale:before{content:"\f24e"}.fa-hourglass-o:before{content:"\f250"}.fa-hourglass-1:before,.fa-hourglass-start:before{content:"\f251"}.fa-hourglass-2:before,.fa-hourglass-half:before{content:"\f252"}.fa-hourglass-3:before,.fa-hourglass-end:before{content:"\f253"}.fa-hourglass:before{content:"\f254"}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:"\f255"}.fa-hand-stop-o:before,.fa-hand-paper-o:before{content:"\f256"}.fa-hand-scissors-o:before{content:"\f257"}.fa-hand-lizard-o:before{content:"\f258"}.fa-hand-spock-o:before{content:"\f259"}.fa-hand-pointer-o:before{content:"\f25a"}.fa-hand-peace-o:before{content:"\f25b"}.fa-trademark:before{content:"\f25c"}.fa-registered:before{content:"\f25d"}.fa-creative-commons:before{content:"\f25e"}.fa-gg:before{content:"\f260"}.fa-gg-circle:before{content:"\f261"}.fa-tripadvisor:before{content:"\f262"}.fa-odnoklassniki:before{content:"\f263"}.fa-odnoklassniki-square:before{content:"\f264"}.fa-get-pocket:before{content:"\f265"}.fa-wikipedia-w:before{content:"\f266"}.fa-safari:before{content:"\f267"}.fa-chrome:before{content:"\f268"}.fa-firefox:before{content:"\f269"}.fa-opera:before{content:"\f26a"}.fa-internet-explorer:before{content:"\f26b"}.fa-tv:before,.fa-television:before{content:"\f26c"}.fa-contao:before{content:"\f26d"}.fa-500px:before{content:"\f26e"}.fa-amazon:before{content:"\f270"}.fa-calendar-plus-o:before{content:"\f271"}.fa-calendar-minus-o:before{content:"\f272"}.fa-calendar-times-o:before{content:"\f273"}.fa-calendar-check-o:before{content:"\f274"}.fa-industry:before{content:"\f275"}.fa-map-pin:before{content:"\f276"}.fa-map-signs:before{content:"\f277"}.fa-map-o:before{content:"\f278"}.fa-map:before{content:"\f279"}.fa-commenting:before{content:"\f27a"}.fa-commenting-o:before{content:"\f27b"}.fa-houzz:before{content:"\f27c"}.fa-vimeo:before{content:"\f27d"}.fa-black-tie:before{content:"\f27e"}.fa-fonticons:before{content:"\f280"}.fa-reddit-alien:before{content:"\f281"}.fa-edge:before{content:"\f282"}.fa-credit-card-alt:before{content:"\f283"}.fa-codiepie:before{content:"\f284"}.fa-modx:before{content:"\f285"}.fa-fort-awesome:before{content:"\f286"}.fa-usb:before{content:"\f287"}.fa-product-hunt:before{content:"\f288"}.fa-mixcloud:before{content:"\f289"}.fa-scribd:before{content:"\f28a"}.fa-pause-circle:before{content:"\f28b"}.fa-pause-circle-o:before{content:"\f28c"}.fa-stop-circle:before{content:"\f28d"}.fa-stop-circle-o:before{content:"\f28e"}.fa-shopping-bag:before{content:"\f290"}.fa-shopping-basket:before{content:"\f291"}.fa-hashtag:before{content:"\f292"}.fa-bluetooth:before{content:"\f293"}.fa-bluetooth-b:before{content:"\f294"}.fa-percent:before{content:"\f295"}.fa-gitlab:before{content:"\f296"}.fa-wpbeginner:before{content:"\f297"}.fa-wpforms:before{content:"\f298"}.fa-envira:before{content:"\f299"}.fa-universal-access:before{content:"\f29a"}.fa-wheelchair-alt:before{content:"\f29b"}.fa-question-circle-o:before{content:"\f29c"}.fa-blind:before{content:"\f29d"}.fa-audio-description:before{content:"\f29e"}.fa-volume-control-phone:before{content:"\f2a0"}.fa-braille:before{content:"\f2a1"}.fa-assistive-listening-systems:before{content:"\f2a2"}.fa-asl-interpreting:before,.fa-american-sign-language-interpreting:before{content:"\f2a3"}.fa-deafness:before,.fa-hard-of-hearing:before,.fa-deaf:before{content:"\f2a4"}.fa-glide:before{content:"\f2a5"}.fa-glide-g:before{content:"\f2a6"}.fa-signing:before,.fa-sign-language:before{content:"\f2a7"}.fa-low-vision:before{content:"\f2a8"}.fa-viadeo:before{content:"\f2a9"}.fa-viadeo-square:before{content:"\f2aa"}.fa-snapchat:before{content:"\f2ab"}.fa-snapchat-ghost:before{content:"\f2ac"}.fa-snapchat-square:before{content:"\f2ad"}.fa-pied-piper:before{content:"\f2ae"}.fa-first-order:before{content:"\f2b0"}.fa-yoast:before{content:"\f2b1"}.fa-themeisle:before{content:"\f2b2"}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:"\f2b3"}.fa-fa:before,.fa-font-awesome:before{content:"\f2b4"}.fa-handshake-o:before{content:"\f2b5"}.fa-envelope-open:before{content:"\f2b6"}.fa-envelope-open-o:before{content:"\f2b7"}.fa-linode:before{content:"\f2b8"}.fa-address-book:before{content:"\f2b9"}.fa-address-book-o:before{content:"\f2ba"}.fa-vcard:before,.fa-address-card:before{content:"\f2bb"}.fa-vcard-o:before,.fa-address-card-o:before{content:"\f2bc"}.fa-user-circle:before{content:"\f2bd"}.fa-user-circle-o:before{content:"\f2be"}.fa-user-o:before{content:"\f2c0"}.fa-id-badge:before{content:"\f2c1"}.fa-drivers-license:before,.fa-id-card:before{content:"\f2c2"}.fa-drivers-license-o:before,.fa-id-card-o:before{content:"\f2c3"}.fa-quora:before{content:"\f2c4"}.fa-free-code-camp:before{content:"\f2c5"}.fa-telegram:before{content:"\f2c6"}.fa-thermometer-4:before,.fa-thermometer:before,.fa-thermometer-full:before{content:"\f2c7"}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:"\f2c8"}.fa-thermometer-2:before,.fa-thermometer-half:before{content:"\f2c9"}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:"\f2ca"}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:"\f2cb"}.fa-shower:before{content:"\f2cc"}.fa-bathtub:before,.fa-s15:before,.fa-bath:before{content:"\f2cd"}.fa-podcast:before{content:"\f2ce"}.fa-window-maximize:before{content:"\f2d0"}.fa-window-minimize:before{content:"\f2d1"}.fa-window-restore:before{content:"\f2d2"}.fa-times-rectangle:before,.fa-window-close:before{content:"\f2d3"}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:"\f2d4"}.fa-bandcamp:before{content:"\f2d5"}.fa-grav:before{content:"\f2d6"}.fa-etsy:before{content:"\f2d7"}.fa-imdb:before{content:"\f2d8"}.fa-ravelry:before{content:"\f2d9"}.fa-eercast:before{content:"\f2da"}.fa-microchip:before{content:"\f2db"}.fa-snowflake-o:before{content:"\f2dc"}.fa-superpowers:before{content:"\f2dd"}.fa-wpexplorer:before{content:"\f2de"}.fa-meetup:before{content:"\f2e0"}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}
diff --git a/rfc/FontAwesome/fonts/FontAwesome.ttf b/rfc/FontAwesome/fonts/FontAwesome.ttf
new file mode 100644
index 000000000000..35acda2fa119
Binary files /dev/null and b/rfc/FontAwesome/fonts/FontAwesome.ttf differ
diff --git a/rfc/FontAwesome/fonts/fontawesome-webfont.eot b/rfc/FontAwesome/fonts/fontawesome-webfont.eot
new file mode 100644
index 000000000000..e9f60ca953f9
Binary files /dev/null and b/rfc/FontAwesome/fonts/fontawesome-webfont.eot differ
diff --git a/rfc/FontAwesome/fonts/fontawesome-webfont.svg b/rfc/FontAwesome/fonts/fontawesome-webfont.svg
new file mode 100644
index 000000000000..855c845e538b
--- /dev/null
+++ b/rfc/FontAwesome/fonts/fontawesome-webfont.svg
@@ -0,0 +1,2671 @@
+
+
+
diff --git a/rfc/FontAwesome/fonts/fontawesome-webfont.ttf b/rfc/FontAwesome/fonts/fontawesome-webfont.ttf
new file mode 100644
index 000000000000..35acda2fa119
Binary files /dev/null and b/rfc/FontAwesome/fonts/fontawesome-webfont.ttf differ
diff --git a/rfc/FontAwesome/fonts/fontawesome-webfont.woff b/rfc/FontAwesome/fonts/fontawesome-webfont.woff
new file mode 100644
index 000000000000..400014a4b06e
Binary files /dev/null and b/rfc/FontAwesome/fonts/fontawesome-webfont.woff differ
diff --git a/rfc/FontAwesome/fonts/fontawesome-webfont.woff2 b/rfc/FontAwesome/fonts/fontawesome-webfont.woff2
new file mode 100644
index 000000000000..4d13fc60404b
Binary files /dev/null and b/rfc/FontAwesome/fonts/fontawesome-webfont.woff2 differ
diff --git a/rfc/ayu-highlight.css b/rfc/ayu-highlight.css
new file mode 100644
index 000000000000..0c45c6f14608
--- /dev/null
+++ b/rfc/ayu-highlight.css
@@ -0,0 +1,79 @@
+/*
+Based off of the Ayu theme
+Original by Dempfi (https://github.com/dempfi/ayu)
+*/
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #191f26;
+ color: #e6e1cf;
+ padding: 0.5em;
+}
+
+.hljs-comment,
+.hljs-quote {
+ color: #5c6773;
+ font-style: italic;
+}
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-attr,
+.hljs-regexp,
+.hljs-link,
+.hljs-selector-id,
+.hljs-selector-class {
+ color: #ff7733;
+}
+
+.hljs-number,
+.hljs-meta,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+ color: #ffee99;
+}
+
+.hljs-string,
+.hljs-bullet {
+ color: #b8cc52;
+}
+
+.hljs-title,
+.hljs-built_in,
+.hljs-section {
+ color: #ffb454;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-symbol {
+ color: #ff7733;
+}
+
+.hljs-name {
+ color: #36a3d9;
+}
+
+.hljs-tag {
+ color: #00568d;
+}
+
+.hljs-emphasis {
+ font-style: italic;
+}
+
+.hljs-strong {
+ font-weight: bold;
+}
+
+.hljs-addition {
+ color: #91b362;
+}
+
+.hljs-deletion {
+ color: #d96c75;
+}
diff --git a/rfc/book.js b/rfc/book.js
new file mode 100644
index 000000000000..d40440c72317
--- /dev/null
+++ b/rfc/book.js
@@ -0,0 +1,679 @@
+"use strict";
+
+// Fix back button cache problem
+window.onunload = function () { };
+
+// Global variable, shared between modules
+function playground_text(playground) {
+ let code_block = playground.querySelector("code");
+
+ if (window.ace && code_block.classList.contains("editable")) {
+ let editor = window.ace.edit(code_block);
+ return editor.getValue();
+ } else {
+ return code_block.textContent;
+ }
+}
+
+(function codeSnippets() {
+ function fetch_with_timeout(url, options, timeout = 6000) {
+ return Promise.race([
+ fetch(url, options),
+ new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
+ ]);
+ }
+
+ var playgrounds = Array.from(document.querySelectorAll(".playground"));
+ if (playgrounds.length > 0) {
+ fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
+ headers: {
+ 'Content-Type': "application/json",
+ },
+ method: 'POST',
+ mode: 'cors',
+ })
+ .then(response => response.json())
+ .then(response => {
+ // get list of crates available in the rust playground
+ let playground_crates = response.crates.map(item => item["id"]);
+ playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
+ });
+ }
+
+ function handle_crate_list_update(playground_block, playground_crates) {
+ // update the play buttons after receiving the response
+ update_play_button(playground_block, playground_crates);
+
+ // and install on change listener to dynamically update ACE editors
+ if (window.ace) {
+ let code_block = playground_block.querySelector("code");
+ if (code_block.classList.contains("editable")) {
+ let editor = window.ace.edit(code_block);
+ editor.addEventListener("change", function (e) {
+ update_play_button(playground_block, playground_crates);
+ });
+ // add Ctrl-Enter command to execute rust code
+ editor.commands.addCommand({
+ name: "run",
+ bindKey: {
+ win: "Ctrl-Enter",
+ mac: "Ctrl-Enter"
+ },
+ exec: _editor => run_rust_code(playground_block)
+ });
+ }
+ }
+ }
+
+ // updates the visibility of play button based on `no_run` class and
+ // used crates vs ones available on http://play.rust-lang.org
+ function update_play_button(pre_block, playground_crates) {
+ var play_button = pre_block.querySelector(".play-button");
+
+ // skip if code is `no_run`
+ if (pre_block.querySelector('code').classList.contains("no_run")) {
+ play_button.classList.add("hidden");
+ return;
+ }
+
+ // get list of `extern crate`'s from snippet
+ var txt = playground_text(pre_block);
+ var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
+ var snippet_crates = [];
+ var item;
+ while (item = re.exec(txt)) {
+ snippet_crates.push(item[1]);
+ }
+
+ // check if all used crates are available on play.rust-lang.org
+ var all_available = snippet_crates.every(function (elem) {
+ return playground_crates.indexOf(elem) > -1;
+ });
+
+ if (all_available) {
+ play_button.classList.remove("hidden");
+ } else {
+ play_button.classList.add("hidden");
+ }
+ }
+
+ function run_rust_code(code_block) {
+ var result_block = code_block.querySelector(".result");
+ if (!result_block) {
+ result_block = document.createElement('code');
+ result_block.className = 'result hljs language-bash';
+
+ code_block.append(result_block);
+ }
+
+ let text = playground_text(code_block);
+ let classes = code_block.querySelector('code').classList;
+ let edition = "2015";
+ if(classes.contains("edition2018")) {
+ edition = "2018";
+ } else if(classes.contains("edition2021")) {
+ edition = "2021";
+ }
+ var params = {
+ version: "stable",
+ optimize: "0",
+ code: text,
+ edition: edition
+ };
+
+ if (text.indexOf("#![feature") !== -1) {
+ params.version = "nightly";
+ }
+
+ result_block.innerText = "Running...";
+
+ fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
+ headers: {
+ 'Content-Type': "application/json",
+ },
+ method: 'POST',
+ mode: 'cors',
+ body: JSON.stringify(params)
+ })
+ .then(response => response.json())
+ .then(response => {
+ if (response.result.trim() === '') {
+ result_block.innerText = "No output";
+ result_block.classList.add("result-no-output");
+ } else {
+ result_block.innerText = response.result;
+ result_block.classList.remove("result-no-output");
+ }
+ })
+ .catch(error => result_block.innerText = "Playground Communication: " + error.message);
+ }
+
+ // Syntax highlighting Configuration
+ hljs.configure({
+ tabReplace: ' ', // 4 spaces
+ languages: [], // Languages used for auto-detection
+ });
+
+ let code_nodes = Array
+ .from(document.querySelectorAll('code'))
+ // Don't highlight `inline code` blocks in headers.
+ .filter(function (node) {return !node.parentElement.classList.contains("header"); });
+
+ if (window.ace) {
+ // language-rust class needs to be removed for editable
+ // blocks or highlightjs will capture events
+ code_nodes
+ .filter(function (node) {return node.classList.contains("editable"); })
+ .forEach(function (block) { block.classList.remove('language-rust'); });
+
+ Array
+ code_nodes
+ .filter(function (node) {return !node.classList.contains("editable"); })
+ .forEach(function (block) { hljs.highlightBlock(block); });
+ } else {
+ code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
+ }
+
+ // Adding the hljs class gives code blocks the color css
+ // even if highlighting doesn't apply
+ code_nodes.forEach(function (block) { block.classList.add('hljs'); });
+
+ Array.from(document.querySelectorAll("code.language-rust")).forEach(function (block) {
+
+ var lines = Array.from(block.querySelectorAll('.boring'));
+ // If no lines were hidden, return
+ if (!lines.length) { return; }
+ block.classList.add("hide-boring");
+
+ var buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ buttons.innerHTML = "";
+
+ // add expand button
+ var pre_block = block.parentNode;
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+
+ pre_block.querySelector('.buttons').addEventListener('click', function (e) {
+ if (e.target.classList.contains('fa-eye')) {
+ e.target.classList.remove('fa-eye');
+ e.target.classList.add('fa-eye-slash');
+ e.target.title = 'Hide lines';
+ e.target.setAttribute('aria-label', e.target.title);
+
+ block.classList.remove('hide-boring');
+ } else if (e.target.classList.contains('fa-eye-slash')) {
+ e.target.classList.remove('fa-eye-slash');
+ e.target.classList.add('fa-eye');
+ e.target.title = 'Show hidden lines';
+ e.target.setAttribute('aria-label', e.target.title);
+
+ block.classList.add('hide-boring');
+ }
+ });
+ });
+
+ if (window.playground_copyable) {
+ Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
+ var pre_block = block.parentNode;
+ if (!pre_block.classList.contains('playground')) {
+ var buttons = pre_block.querySelector(".buttons");
+ if (!buttons) {
+ buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+ }
+
+ var clipButton = document.createElement('button');
+ clipButton.className = 'fa fa-copy clip-button';
+ clipButton.title = 'Copy to clipboard';
+ clipButton.setAttribute('aria-label', clipButton.title);
+ clipButton.innerHTML = '';
+
+ buttons.insertBefore(clipButton, buttons.firstChild);
+ }
+ });
+ }
+
+ // Process playground code blocks
+ Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
+ // Add play button
+ var buttons = pre_block.querySelector(".buttons");
+ if (!buttons) {
+ buttons = document.createElement('div');
+ buttons.className = 'buttons';
+ pre_block.insertBefore(buttons, pre_block.firstChild);
+ }
+
+ var runCodeButton = document.createElement('button');
+ runCodeButton.className = 'fa fa-play play-button';
+ runCodeButton.hidden = true;
+ runCodeButton.title = 'Run this code';
+ runCodeButton.setAttribute('aria-label', runCodeButton.title);
+
+ buttons.insertBefore(runCodeButton, buttons.firstChild);
+ runCodeButton.addEventListener('click', function (e) {
+ run_rust_code(pre_block);
+ });
+
+ if (window.playground_copyable) {
+ var copyCodeClipboardButton = document.createElement('button');
+ copyCodeClipboardButton.className = 'fa fa-copy clip-button';
+ copyCodeClipboardButton.innerHTML = '';
+ copyCodeClipboardButton.title = 'Copy to clipboard';
+ copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
+
+ buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
+ }
+
+ let code_block = pre_block.querySelector("code");
+ if (window.ace && code_block.classList.contains("editable")) {
+ var undoChangesButton = document.createElement('button');
+ undoChangesButton.className = 'fa fa-history reset-button';
+ undoChangesButton.title = 'Undo changes';
+ undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
+
+ buttons.insertBefore(undoChangesButton, buttons.firstChild);
+
+ undoChangesButton.addEventListener('click', function () {
+ let editor = window.ace.edit(code_block);
+ editor.setValue(editor.originalCode);
+ editor.clearSelection();
+ });
+ }
+ });
+})();
+
+(function themes() {
+ var html = document.querySelector('html');
+ var themeToggleButton = document.getElementById('theme-toggle');
+ var themePopup = document.getElementById('theme-list');
+ var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
+ var stylesheets = {
+ ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
+ tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
+ highlight: document.querySelector("[href$='highlight.css']"),
+ };
+
+ function showThemes() {
+ themePopup.style.display = 'block';
+ themeToggleButton.setAttribute('aria-expanded', true);
+ themePopup.querySelector("button#" + get_theme()).focus();
+ }
+
+ function hideThemes() {
+ themePopup.style.display = 'none';
+ themeToggleButton.setAttribute('aria-expanded', false);
+ themeToggleButton.focus();
+ }
+
+ function get_theme() {
+ var theme;
+ try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
+ if (theme === null || theme === undefined) {
+ return default_theme;
+ } else {
+ return theme;
+ }
+ }
+
+ function set_theme(theme, store = true) {
+ let ace_theme;
+
+ if (theme == 'coal' || theme == 'navy') {
+ stylesheets.ayuHighlight.disabled = true;
+ stylesheets.tomorrowNight.disabled = false;
+ stylesheets.highlight.disabled = true;
+
+ ace_theme = "ace/theme/tomorrow_night";
+ } else if (theme == 'ayu') {
+ stylesheets.ayuHighlight.disabled = false;
+ stylesheets.tomorrowNight.disabled = true;
+ stylesheets.highlight.disabled = true;
+ ace_theme = "ace/theme/tomorrow_night";
+ } else {
+ stylesheets.ayuHighlight.disabled = true;
+ stylesheets.tomorrowNight.disabled = true;
+ stylesheets.highlight.disabled = false;
+ ace_theme = "ace/theme/dawn";
+ }
+
+ setTimeout(function () {
+ themeColorMetaTag.content = getComputedStyle(document.body).backgroundColor;
+ }, 1);
+
+ if (window.ace && window.editors) {
+ window.editors.forEach(function (editor) {
+ editor.setTheme(ace_theme);
+ });
+ }
+
+ var previousTheme = get_theme();
+
+ if (store) {
+ try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
+ }
+
+ html.classList.remove(previousTheme);
+ html.classList.add(theme);
+ }
+
+ // Set theme
+ var theme = get_theme();
+
+ set_theme(theme, false);
+
+ themeToggleButton.addEventListener('click', function () {
+ if (themePopup.style.display === 'block') {
+ hideThemes();
+ } else {
+ showThemes();
+ }
+ });
+
+ themePopup.addEventListener('click', function (e) {
+ var theme;
+ if (e.target.className === "theme") {
+ theme = e.target.id;
+ } else if (e.target.parentElement.className === "theme") {
+ theme = e.target.parentElement.id;
+ } else {
+ return;
+ }
+ set_theme(theme);
+ });
+
+ themePopup.addEventListener('focusout', function(e) {
+ // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
+ if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
+ hideThemes();
+ }
+ });
+
+ // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
+ document.addEventListener('click', function(e) {
+ if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
+ hideThemes();
+ }
+ });
+
+ document.addEventListener('keydown', function (e) {
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+ if (!themePopup.contains(e.target)) { return; }
+
+ switch (e.key) {
+ case 'Escape':
+ e.preventDefault();
+ hideThemes();
+ break;
+ case 'ArrowUp':
+ e.preventDefault();
+ var li = document.activeElement.parentElement;
+ if (li && li.previousElementSibling) {
+ li.previousElementSibling.querySelector('button').focus();
+ }
+ break;
+ case 'ArrowDown':
+ e.preventDefault();
+ var li = document.activeElement.parentElement;
+ if (li && li.nextElementSibling) {
+ li.nextElementSibling.querySelector('button').focus();
+ }
+ break;
+ case 'Home':
+ e.preventDefault();
+ themePopup.querySelector('li:first-child button').focus();
+ break;
+ case 'End':
+ e.preventDefault();
+ themePopup.querySelector('li:last-child button').focus();
+ break;
+ }
+ });
+})();
+
+(function sidebar() {
+ var html = document.querySelector("html");
+ var sidebar = document.getElementById("sidebar");
+ var sidebarLinks = document.querySelectorAll('#sidebar a');
+ var sidebarToggleButton = document.getElementById("sidebar-toggle");
+ var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
+ var firstContact = null;
+
+ function showSidebar() {
+ html.classList.remove('sidebar-hidden')
+ html.classList.add('sidebar-visible');
+ Array.from(sidebarLinks).forEach(function (link) {
+ link.setAttribute('tabIndex', 0);
+ });
+ sidebarToggleButton.setAttribute('aria-expanded', true);
+ sidebar.setAttribute('aria-hidden', false);
+ try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+ }
+
+
+ var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
+
+ function toggleSection(ev) {
+ ev.currentTarget.parentElement.classList.toggle('expanded');
+ }
+
+ Array.from(sidebarAnchorToggles).forEach(function (el) {
+ el.addEventListener('click', toggleSection);
+ });
+
+ function hideSidebar() {
+ html.classList.remove('sidebar-visible')
+ html.classList.add('sidebar-hidden');
+ Array.from(sidebarLinks).forEach(function (link) {
+ link.setAttribute('tabIndex', -1);
+ });
+ sidebarToggleButton.setAttribute('aria-expanded', false);
+ sidebar.setAttribute('aria-hidden', true);
+ try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+ }
+
+ // Toggle sidebar
+ sidebarToggleButton.addEventListener('click', function sidebarToggle() {
+ if (html.classList.contains("sidebar-hidden")) {
+ var current_width = parseInt(
+ document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
+ if (current_width < 150) {
+ document.documentElement.style.setProperty('--sidebar-width', '150px');
+ }
+ showSidebar();
+ } else if (html.classList.contains("sidebar-visible")) {
+ hideSidebar();
+ } else {
+ if (getComputedStyle(sidebar)['transform'] === 'none') {
+ hideSidebar();
+ } else {
+ showSidebar();
+ }
+ }
+ });
+
+ sidebarResizeHandle.addEventListener('mousedown', initResize, false);
+
+ function initResize(e) {
+ window.addEventListener('mousemove', resize, false);
+ window.addEventListener('mouseup', stopResize, false);
+ html.classList.add('sidebar-resizing');
+ }
+ function resize(e) {
+ var pos = (e.clientX - sidebar.offsetLeft);
+ if (pos < 20) {
+ hideSidebar();
+ } else {
+ if (html.classList.contains("sidebar-hidden")) {
+ showSidebar();
+ }
+ pos = Math.min(pos, window.innerWidth - 100);
+ document.documentElement.style.setProperty('--sidebar-width', pos + 'px');
+ }
+ }
+ //on mouseup remove windows functions mousemove & mouseup
+ function stopResize(e) {
+ html.classList.remove('sidebar-resizing');
+ window.removeEventListener('mousemove', resize, false);
+ window.removeEventListener('mouseup', stopResize, false);
+ }
+
+ document.addEventListener('touchstart', function (e) {
+ firstContact = {
+ x: e.touches[0].clientX,
+ time: Date.now()
+ };
+ }, { passive: true });
+
+ document.addEventListener('touchmove', function (e) {
+ if (!firstContact)
+ return;
+
+ var curX = e.touches[0].clientX;
+ var xDiff = curX - firstContact.x,
+ tDiff = Date.now() - firstContact.time;
+
+ if (tDiff < 250 && Math.abs(xDiff) >= 150) {
+ if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+ showSidebar();
+ else if (xDiff < 0 && curX < 300)
+ hideSidebar();
+
+ firstContact = null;
+ }
+ }, { passive: true });
+
+ // Scroll sidebar to current active section
+ var activeSection = document.getElementById("sidebar").querySelector(".active");
+ if (activeSection) {
+ // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
+ activeSection.scrollIntoView({ block: 'center' });
+ }
+})();
+
+(function chapterNavigation() {
+ document.addEventListener('keydown', function (e) {
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+ if (window.search && window.search.hasFocus()) { return; }
+
+ switch (e.key) {
+ case 'ArrowRight':
+ e.preventDefault();
+ var nextButton = document.querySelector('.nav-chapters.next');
+ if (nextButton) {
+ window.location.href = nextButton.href;
+ }
+ break;
+ case 'ArrowLeft':
+ e.preventDefault();
+ var previousButton = document.querySelector('.nav-chapters.previous');
+ if (previousButton) {
+ window.location.href = previousButton.href;
+ }
+ break;
+ }
+ });
+})();
+
+(function clipboard() {
+ var clipButtons = document.querySelectorAll('.clip-button');
+
+ function hideTooltip(elem) {
+ elem.firstChild.innerText = "";
+ elem.className = 'fa fa-copy clip-button';
+ }
+
+ function showTooltip(elem, msg) {
+ elem.firstChild.innerText = msg;
+ elem.className = 'fa fa-copy tooltipped';
+ }
+
+ var clipboardSnippets = new ClipboardJS('.clip-button', {
+ text: function (trigger) {
+ hideTooltip(trigger);
+ let playground = trigger.closest("pre");
+ return playground_text(playground);
+ }
+ });
+
+ Array.from(clipButtons).forEach(function (clipButton) {
+ clipButton.addEventListener('mouseout', function (e) {
+ hideTooltip(e.currentTarget);
+ });
+ });
+
+ clipboardSnippets.on('success', function (e) {
+ e.clearSelection();
+ showTooltip(e.trigger, "Copied!");
+ });
+
+ clipboardSnippets.on('error', function (e) {
+ showTooltip(e.trigger, "Clipboard error!");
+ });
+})();
+
+(function scrollToTop () {
+ var menuTitle = document.querySelector('.menu-title');
+
+ menuTitle.addEventListener('click', function () {
+ document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+ });
+})();
+
+(function controllMenu() {
+ var menu = document.getElementById('menu-bar');
+
+ (function controllPosition() {
+ var scrollTop = document.scrollingElement.scrollTop;
+ var prevScrollTop = scrollTop;
+ var minMenuY = -menu.clientHeight - 50;
+ // When the script loads, the page can be at any scroll (e.g. if you reforesh it).
+ menu.style.top = scrollTop + 'px';
+ // Same as parseInt(menu.style.top.slice(0, -2), but faster
+ var topCache = menu.style.top.slice(0, -2);
+ menu.classList.remove('sticky');
+ var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
+ document.addEventListener('scroll', function () {
+ scrollTop = Math.max(document.scrollingElement.scrollTop, 0);
+ // `null` means that it doesn't need to be updated
+ var nextSticky = null;
+ var nextTop = null;
+ var scrollDown = scrollTop > prevScrollTop;
+ var menuPosAbsoluteY = topCache - scrollTop;
+ if (scrollDown) {
+ nextSticky = false;
+ if (menuPosAbsoluteY > 0) {
+ nextTop = prevScrollTop;
+ }
+ } else {
+ if (menuPosAbsoluteY > 0) {
+ nextSticky = true;
+ } else if (menuPosAbsoluteY < minMenuY) {
+ nextTop = prevScrollTop + minMenuY;
+ }
+ }
+ if (nextSticky === true && stickyCache === false) {
+ menu.classList.add('sticky');
+ stickyCache = true;
+ } else if (nextSticky === false && stickyCache === true) {
+ menu.classList.remove('sticky');
+ stickyCache = false;
+ }
+ if (nextTop !== null) {
+ menu.style.top = nextTop + 'px';
+ topCache = nextTop;
+ }
+ prevScrollTop = scrollTop;
+ }, { passive: true });
+ })();
+ (function controllBorder() {
+ menu.classList.remove('bordered');
+ document.addEventListener('scroll', function () {
+ if (menu.offsetTop === 0) {
+ menu.classList.remove('bordered');
+ } else {
+ menu.classList.add('bordered');
+ }
+ }, { passive: true });
+ })();
+})();
diff --git a/rfc/clipboard.min.js b/rfc/clipboard.min.js
new file mode 100644
index 000000000000..02c549e35c86
--- /dev/null
+++ b/rfc/clipboard.min.js
@@ -0,0 +1,7 @@
+/*!
+ * clipboard.js v2.0.4
+ * https://zenorocha.github.io/clipboard.js
+ *
+ * Licensed MIT © Zeno Rocha
+ */
+!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/intro.html b/rfc/intro.html
new file mode 100644
index 000000000000..b150542743c1
--- /dev/null
+++ b/rfc/intro.html
@@ -0,0 +1,261 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+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.
+When to create an RFC
+You should create an RFC in one of two cases:
+-
+
- The change you are proposing would be a "one way door": e.g. a major change to the public API, a new feature that would be difficult to modify once released, etc. +
- The change you are making has a significant design component, and would benefit from a design review. +
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.
+The RFC process
+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
+-
+
- Create an RFC
+
-
+
- Create a tracking issue for your RFC (e.g.: Issue-1588). +
- Start from a fork of the Kani repository. +
- Copy the template file (
rfc/src/template.md) torfc/src/rfcs/<ID_NUMBER><my-feature>.md.
+ - Fill in the details according to the template instructions. +
-
+
- For the first RFC version, we recommend that you leave the "Software Design" section empty. +
- Focus on the user impact and user experience. +Include a few usage examples if possible. +
-
+
- Add a link to the new RFC inside
rfc/src/SUMMARY.md
+ - Submit a pull request. +
+ - Build consensus and integrate feedback.
+
-
+
- RFCs should get approved by at least 2 Kani developers. +
- Once the RFC has been approved, update the RFC status and merge the PR. +
- If the RFC is not approved, close the PR without merging. +
+ - Feature implementation.
+
-
+
- Start implementing the new feature in your fork. +
- Create a new revision of the RFC to add details about the "Software Design". +
- It is OK to implement the feature incrementally over multiple PRs. +Just ensure that every pull request has a testable end-to-end flow and that it is properly tested. +
- In the implementation stage, the feature should only be accessible if the user explicitly passes
+
-Z <FEATURE_ID>as an argument to Kani.
+ - Document how to use the feature. +
- Keep the RFC up-to-date with the decisions you make during implementation. +
+ - Test and Gather Feedback.
+
-
+
- Fix major issues related to the new feature. +
- Gather user feedback and make necessary adjustments. +
- Resolve RFC open questions. +
- Add regression tests to cover all expected behaviors and unit tests whenever possible. +
+ - Stabilization.
+
-
+
- Propose to stabilize the feature when feature is well tested and UX has received positive feedback. +
- Create a new PR that removes the
-Z <FEATURE_ID>guard and that marks the RFC status as "STABLE". +-
+
- Make sure the RFC reflects the final implementation and user experience. +
+ - In some cases, we might decide not to incorporate a feature +(E.g.: performance degradation, bad user experience, better alternative). +In those cases, please update the RFC status to "CANCELLED as per <PR_LINK | ISSUE_LINK>" and remove the code +that is no longer relevant. +
- Close the tracking issue. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/mark.min.js b/rfc/mark.min.js
new file mode 100644
index 000000000000..163623188347
--- /dev/null
+++ b/rfc/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+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.
+When to create an RFC
+You should create an RFC in one of two cases:
+-
+
- The change you are proposing would be a "one way door": e.g. a major change to the public API, a new feature that would be difficult to modify once released, etc. +
- The change you are making has a significant design component, and would benefit from a design review. +
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.
+The RFC process
+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
+-
+
- Create an RFC
+
-
+
- Create a tracking issue for your RFC (e.g.: Issue-1588). +
- Start from a fork of the Kani repository. +
- Copy the template file (
rfc/src/template.md) torfc/src/rfcs/<ID_NUMBER><my-feature>.md.
+ - Fill in the details according to the template instructions. +
-
+
- For the first RFC version, we recommend that you leave the "Software Design" section empty. +
- Focus on the user impact and user experience. +Include a few usage examples if possible. +
-
+
- Add a link to the new RFC inside
rfc/src/SUMMARY.md
+ - Submit a pull request. +
+ - Build consensus and integrate feedback.
+
-
+
- RFCs should get approved by at least 2 Kani developers. +
- Once the RFC has been approved, update the RFC status and merge the PR. +
- If the RFC is not approved, close the PR without merging. +
+ - Feature implementation.
+
-
+
- Start implementing the new feature in your fork. +
- Create a new revision of the RFC to add details about the "Software Design". +
- It is OK to implement the feature incrementally over multiple PRs. +Just ensure that every pull request has a testable end-to-end flow and that it is properly tested. +
- In the implementation stage, the feature should only be accessible if the user explicitly passes
+
-Z <FEATURE_ID>as an argument to Kani.
+ - Document how to use the feature. +
- Keep the RFC up-to-date with the decisions you make during implementation. +
+ - Test and Gather Feedback.
+
-
+
- Fix major issues related to the new feature. +
- Gather user feedback and make necessary adjustments. +
- Resolve RFC open questions. +
- Add regression tests to cover all expected behaviors and unit tests whenever possible. +
+ - Stabilization.
+
-
+
- Propose to stabilize the feature when feature is well tested and UX has received positive feedback. +
- Create a new PR that removes the
-Z <FEATURE_ID>guard and that marks the RFC status as "STABLE". +-
+
- Make sure the RFC reflects the final implementation and user experience. +
+ - In some cases, we might decide not to incorporate a feature +(E.g.: performance degradation, bad user experience, better alternative). +In those cases, please update the RFC status to "CANCELLED as per <PR_LINK | ISSUE_LINK>" and remove the code +that is no longer relevant. +
- Close the tracking issue. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0001-mir-linker.html b/rfc/rfcs/0001-mir-linker.html
new file mode 100644
index 000000000000..97fda9c67746
--- /dev/null
+++ b/rfc/rfcs/0001-mir-linker.html
@@ -0,0 +1,405 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Alternative #3: The
+
+
+
+Coverage through
+
+Code generation in
+
+
+
+
+The
+The
+
+Procedural macros
+
+
+
+
+
+
+ Introduction
+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.
+When to create an RFC
+You should create an RFC in one of two cases:
+-
+
- The change you are proposing would be a "one way door": e.g. a major change to the public API, a new feature that would be difficult to modify once released, etc. +
- The change you are making has a significant design component, and would benefit from a design review. +
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.
+The RFC process
+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
+-
+
- Create an RFC
+
-
+
- Create a tracking issue for your RFC (e.g.: Issue-1588). +
- Start from a fork of the Kani repository. +
- Copy the template file (
rfc/src/template.md) torfc/src/rfcs/<ID_NUMBER><my-feature>.md.
+ - Fill in the details according to the template instructions. +
-
+
- For the first RFC version, we recommend that you leave the "Software Design" section empty. +
- Focus on the user impact and user experience. +Include a few usage examples if possible. +
-
+
- Add a link to the new RFC inside
rfc/src/SUMMARY.md
+ - Submit a pull request. +
+ - Build consensus and integrate feedback.
+
-
+
- RFCs should get approved by at least 2 Kani developers. +
- Once the RFC has been approved, update the RFC status and merge the PR. +
- If the RFC is not approved, close the PR without merging. +
+ - Feature implementation.
+
-
+
- Start implementing the new feature in your fork. +
- Create a new revision of the RFC to add details about the "Software Design". +
- It is OK to implement the feature incrementally over multiple PRs. +Just ensure that every pull request has a testable end-to-end flow and that it is properly tested. +
- In the implementation stage, the feature should only be accessible if the user explicitly passes
+
-Z <FEATURE_ID>as an argument to Kani.
+ - Document how to use the feature. +
- Keep the RFC up-to-date with the decisions you make during implementation. +
+ - Test and Gather Feedback.
+
-
+
- Fix major issues related to the new feature. +
- Gather user feedback and make necessary adjustments. +
- Resolve RFC open questions. +
- Add regression tests to cover all expected behaviors and unit tests whenever possible. +
+ - Stabilization.
+
-
+
- Propose to stabilize the feature when feature is well tested and UX has received positive feedback. +
- Create a new PR that removes the
-Z <FEATURE_ID>guard and that marks the RFC status as "STABLE". +-
+
- Make sure the RFC reflects the final implementation and user experience. +
+ - In some cases, we might decide not to incorporate a feature +(E.g.: performance degradation, bad user experience, better alternative). +In those cases, please update the RFC status to "CANCELLED as per <PR_LINK | ISSUE_LINK>" and remove the code +that is no longer relevant. +
- Close the tracking issue. +
+
-
+
- Feature Name: Fill me with pretty name and a unique ident 1. Example: New Feature (
new_feature)
+ - Feature Request Issue: Link to issue +
- RFC PR: Link to original PR +
- Status: One of the following: [Under Review | Unstable | Stable | Cancelled] +
- Version: [0-9]* Increment this version whenever you open a new PR to update the RFC (not at every revision). +Start with 0. +
- Proof-of-concept: Optional field. If you have implemented a proof of concept, add a link here +
+
Summary
+Short (1-2 sentences) description of the feature. What is this feature about?
+User Impact
+Imagine this as your elevator pitch directed to users as well as Kani developers.
+-
+
- Why are we doing this? +
- Why should users care about this feature? +
- How will this benefit them? +
- What is the downside? +
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.
+-
+
- If you are unsure you need an RFC, please create a feature request issue and discuss the need with other Kani developers. +
User Experience
+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:
+-
+
- High level user flow description. +
- Any new major functions or attributes that will be added to Kani library. +
- New command line options or subcommands (no need to mention the unstable flag). +
- List failure scenarios and how are they presented (e.g., compilation errors, verification failures, and possible failed user iterations). +
- Substantial changes to existing functionality or Kani output. +
If the RFC is related to architectural changes and there are no visible changes to UX, please state so. +No further explanation is needed.
+Software Design
+We recommend that you leave the Software Design section empty for the first version of your RFC.
+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.
+-
+
- What are the main components that will be modified? (E.g.: changes to
kani-compiler,kani-driver, metadata, proc-macros, installation...)
+ - Will there be changes to the components interface? +
- Any changes to how these components communicate? +
- What corner cases do you anticipate? +
Rationale and alternatives
+This is the section where you discuss the decisions you made.
+-
+
- What are the pros and cons of the UX? What would be the alternatives? +
- What is the impact of not doing this? +
- Any pros / cons on how you designed this? +
Open questions
+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:
+-
+
- Is there any use case that isn't handled yet? +
- Is there any part of the UX that still needs some improvement? +
Make sure all open questions are addressed before stabilization.
+Out of scope / Future Improvements
+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.
+1
+
+This unique ident should be used to enable features proposed in the RFC using -Z <ident> until the feature has been stabilized.
-
+
- Feature Name: MIR Linker (
mir_linker)
+ - RFC Tracking Issue: https://github.com/model-checking/kani/issues/1588 +
- RFC PR: https://github.com/model-checking/kani/pull/1600 +
- Status: Stable +
- Version: 3 +
+
Summary
+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.
+User Impact
+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.
+-
+
- Reduce spurious warnings about unsupported features for cases where the feature is not reachable from any harness. +
- In the verification mode, we will likely see a reduction on the compilation time and memory consumption
+by pruning the inputs of symtab2gb and goto-instrument.
+
-
+
- Compared to linking against the standard library goto-models that take more than 5 GB. +
+ - In a potential assessment mode, only analyze code that is reachable from all public items in the target crate. +
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).
User Experience
+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.
Detailed Design
+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 compiles the user crate as well as all its dependencies.
+For every crate compiled,
kani-compilerwill generate a goto-program. +This model includes everything reachable from the crate's public functions.
+ - After that, Kani links all models together by invoking
goto-cc. +This step will also link against Kani'sClibrary.
+ - For every harness, Kani invokes
goto-instrumentto prune the linked model to only include items reachable from the given harness.
+ - Finally, Kani instruments and verify each harness model via
goto-instrumentandcbmccalls.
+
After this RFC, the system flow would be slightly different:
+-
+
- Kani compiles the user crate dependencies up to the MIR translation.
+I.e., for every crate compiled,
kani-compilerwill generate an artifact that includes the MIR representation +of all items in the crate.
+ - Kani will generate the goto-program only while compiling the target user crate. +It will generate one goto-program that includes all items reachable from any harness in the target crate. +
goto-ccwill still be invoked to link the generated model against Kani'sClibrary.
+- Steps #3 and #4 above will be performed without any change. +
This feature will require three main changes to Kani which are detailed in the sub-sections below.
+Kani's Sysroot
+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.
Cross-Crate Reachability Analysis
+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--reachabilityflag 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-compilerwill 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: Mimicsrustcbehavior 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.
Dependencies vs Target Crate Compilation
+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=harnessestokani-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
+--reachabilityargument, and it will only passharnesses+value to the compiler when compiling the target crate.
+
Rational and Alternatives
+Not doing anything is not an alternative, since this fixes a major gap in Kani's usability.
+Benefits
+-
+
- The MIR linker will allow us to fix the linking issues with Rust's standard library. +
- Once stabilized, the MIR linker will be transparent to the user. +
- It will enable more powerful and precise static analysis to
kani-compiler.
+ - It won't require any changes to our dependencies. +
- This will fix the harnesses' dependency on the
#[no_mangle]annotation +(Issue-661).
+
Risks
+Failures in the linking stage would not impact the tool soundness. I anticipate the following failure scenarios:
+-
+
- ICE (Internal compiler error): Some logic is incorrectly implemented and the linking stage crashes. +Although this is a bad experience for the user, this will not impact the verification result. +
- Missing items: This would either result in ICE during code generation or a verification failure if the missing +item is reachable. +
- Extra items: This shouldn't impact the verification results, and they should be pruned by CBMC's reachability +analysis. +This is already the case today. In extreme cases, this could include a symbol that we cannot compile and cause an ICE. +
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.
Alternatives
+The other options explored were:
+-
+
- Pre-compile the standard library, and the kani library, and ship the generated
*symtab.jsonfiles.
+ - Pre-compile the standard library, and the kani library, convert the standard library and dependencies to goto-program
+(via
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.
+Open questions
+-
+
Should we build or download the sysroot during+We include pre-built MIR artifacts for thekani setup?stdlibrary.
+What's the best way to enable support to run Kani in the entire+We decided to runworkspace?cargo rustcper package.
+Should we codegen all static items no matter what?+We only generate code for static items that are collected by the reachability analysis. +Static objects can only be initialized via constant function. +Thus, it shouldn't have any side effect.
+What's the best way to handle+We are going to use the test profile and iterate over all the targets available in the crate: +cargo kani --tests?-
+
cargo rustc --profile test -- --reachability=harnesses
+
+
Future possibilities
+-
+
- Split the goto-program into two or more items to optimize compilation result caching.
+
-
+
- Dependencies: One model will include items from all the crate dependencies. +This model will likely be more stable and require fewer updates. +
- Target crate: The model for all items in the target crate. +
+ - Do the analysis per-harness. This might be adequate once we have a mechanism to cache translations. +
- Add an option to include external functions to the analysis starting point in order to enable verification when
+calls are made from
Ctorust.
+ - Contribute the reachability analysis code back to upstream. +
-
+
- Feature Name: Function and method stubbing (
function-stubbing)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/1695 +
- RFC PR: https://github.com/model-checking/kani/pull/1723 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: https://github.com/aaronbembenek-aws/kani/tree/mir_transform +
+
Summary
+Allow users to specify that certain functions and methods should be replaced with mock functions (stubs) during verification.
+Scope
+In scope:
+-
+
- Replacing function bodies +
- Replacing method bodies (which means that the new method body will be executed, whether the method is invoked directly or through a vtable) +
Out of scope:
+-
+
- Replacing type definitions +
- Replacing macro definitions +
- Mocking traits +
- Mocking intrinsics +
User impact
+We anticipate that function/method stubbing will have a substantial positive impact on the usability of Kani:
+-
+
- Users might need to stub functions/methods containing features that Kani does not support, such as inline assembly. +
- Users might need to stub functions/methods containing code that Kani supports in principle, but which in practice leads to bad verification performance (for example, if it contains deserialization code). +
- Users could use stubbing to perform compositional reasoning: prove the behavior of a function/method
f, and then in other proofs---that callfindirectly---use a stub offthat 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.
+Mocking randomization
+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.
+User experience
+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.
+Stub sets
+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),
+));
+Error conditions
+Given a set of original-replacement pairs, Kani will exit with an error if
-
+
- a specified
originalfunction/method does not exist;
+ - a specified
replacementstub does not exist;
+ - the user specifies conflicting stubs for the same harness (e.g., if the same
originalfunction is mapped to multiplereplacementfunctions); or
+ - the signature of the
replacementstub is not compatible with the signature of theoriginalfunction/method (see next section).
+
Stub compatibility and validation
+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:
+-
+
- They have the same number of parameters. +
- They have the same return type. +
- Each parameter in the stub has the same type as the corresponding parameter in the original function/method. +
- The stub must have the same number of generic parameters as the original function/method.
+However, a generic parameter in the stub is allowed to have a different name than the corresponding parameter in the original function/method.
+For example, the stub
bar<A, B>(x: A, y: B) -> Bis considered to have a type compatible with the functionfoo<S, T>(x: S, y: T) -> T.
+ - The bounds for each type parameter don't need to match; however, all calls to the original function must also satisfy the bounds of the stub. +
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.
Pedagogy
+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.
+Detailed design
+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.
+Rationale and alternatives: user experience
+Stubbing is a de facto necessity for verification tools, and the lack of stubbing has a negative impact on the usability of Kani.
+Benefits
+-
+
- Because stubs are specified by annotating the harness, the user is able to specify stubs for functions they do not have source access to (like library functions). +This contrasts with annotating the function to be replaced (such as with function contracts). +
- The current design provides the user with flexibility, as they can specify different sets of stubs to use for different harnesses. +This is important if users are trying to perform compositional reasoning using stubbing, since in some harnesses a function/method should be fully verified, in in other harnesses its behavior should be mocked. +
- The stub selections are located adjacent to the harness, which makes it easy to understand which replacements are going to happen for each harness. +
Risks
+-
+
- Users can always write stubs that do not correctly correspond to program behavior, and so a successful verification does not actually mean the program is bug-free. +This is similar to other specification bugs. +All the stubbing code will be available, so it is possible to inspect the assumptions it makes. +
Comparison to function contracts
+-
+
- In many cases, stubs are more user-friendly than contracts. +With contracts, it is sometimes necessary to explicitly provide information that is automatically captured in Rust (such as which memory is written). +Furthermore, contract predicates constitute a DSL of their own that needs to be learned; using stubbing, we can stick to using just Rust. +
- Function contracts sometimes come with a mechanism for verifying that a function satisfies its contract (for example, CBMC provides this). +While we do not plan to provide such a feature, it is possible to emulate this by writing proof harnesses comparing the behavior of the original function and the stub. +Furthermore, our approach provides additional flexibility, as it is not always actually desirable for a stub to be an overapproximation of the function (e.g., we might want the stub to exhibit a certain behavior within a particular harness) or to have a consistent behavior across all harnesses. +
- The currently proposed function contract mechanism does not provide a way to specify contracts on external functions. +In principle, it would be possible to extend it to do so. +Doing so would require some additional UX design decisions (e.g., "How do users specify this?"); with stubbing there does not need to be a distinction between local and external functions. +
Alternative #1: Annotate stubbed functions
+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.
Alternative #2: Annotate stubs
+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.
+Alternative #3: Annotate harnesses and stubs
+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:
+-
+
- How do you mock multiple functions with the same stub?
+(Say harness A wants to use
stub1to mockfoo, and harness B wants to usestub1to mockbar.)
+ - How do you combine stub sets defined via modules? Would you use the module hierarchy? +
- If you use modules to define stub sets, are these modules regular modules or not? +In particular, given that modules can contain other constructs than functions, how should we interpret the extra stuff? +
Alternative #4: Specify stubs in a file
+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.
Rationale and alternatives: stubbing mechanism
+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.
Alternative #1: Conditional compilation
+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.
+Alternative #2: Source-to-source transformation
+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.
Alternative #3: AST-to-AST or HIR-to-HIR transformation
+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).
Open questions
+-
+
- Would there ever be the need to stub a particular monomorphization of a function, as opposed to the polymorphic function? +
- How can the user verify that the stub is an abstraction of the original function/method? +Sometimes it might be important that a stub is an overapproximation or underapproximation of the replaced code. +One possibility would be writing proofs about stubs (possibly relating their behavior to that of the code they are replacing). +
Limitations
+-
+
- Our proposed approach will not work with
--concrete-playback(for now).
+ - We are only able to apply abstractions to some dependencies if the user enables the MIR linker. +
Future possibilities
+-
+
-
+
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::randomcan be replaced with a function returningkani::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 tohavoc_localsbut 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
+selfin methods? +It is possible to do so usingstd::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() { ... } +
+
Appendix: an extended example
+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).
+-
+
- Feature Name: Cover statement (
cover-statement)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/696 +
- RFC PR: https://github.com/model-checking/kani/pull/1906 +
- Status: Stable +
- Version: 2 +
+
Summary
+A new Kani API that allows users to check that a certain condition can occur at a specific location in the code.
+User Impact
+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");
+User Experience
+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
+Impact on Overall Verification Status
+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.
Inclusion in the Verification Summary
+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.
+Interaction with Other Checks
+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.
Detailed Design
+The implementation will touch the following components:
+-
+
- Kani library: The
covermacro will be added there along with acoverfunction with arustc_diagnostic_item
+ kani-compiler: Thecoverfunction 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 thecoverstatement 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: +-
+
- The first (reachability) assertion is proven: report as
FAILURE (UNREACHABLE)
+ - The first assertion fails, and the second one is proven: report as
FAILUREto indicate that the condition is unsatisfiable
+ - The first assertion fails, and the second one fails: report as
SUCCESSto indicate that the condition is satisfiable
+
+- The first (reachability) assertion is proven: report as
Rationale and alternatives
+-
+
-
+
What are the pros and cons of this design? +CBMC has its own cover API (
+__CPROVER_cover), for whichSUCCESSis reported if an execution is found, andFAILUREis 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.
+
Open questions
+-
+
- ~Should we allow format arguments in the macro, e.g.
kani::cover!(x > y, "{} can be greater than {}", x, y)? +Users may expect this to be supported since the macro looks similar to theassertmacro, but Kani doesn't include the formatted string in the message description, since it's not available at compile time.~ +-
+
- For now, this macro will not accept format arguments, since this +is not well handled by Kani. +This is an extesion to this API that can be easily added later on if Kani +ever supports runtime formatting. +
+
Other Considerations
+We need to make sure the concrete playback feature can be used with cover statements that were found to be coverable.
Future possibilities
+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.
-
+
- Feature Name: Loop-contract synthesis (
loop-contract-synthesis)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2214 +
- RFC PR: https://github.com/model-checking/kani/pull/2215 +
- Status: Under Review +
- Version: 0 +
- Proof-of-concept: https://github.com/qinheping/kani/tree/kani-synthesizer +
+
Summary
+A new option that allows users to verify programs without unwinding loops by synthesizing loop contracts for those loops.
+User Impact
+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:
-
+
- the search space is not complete, so it may fail to find a working candidate. The current search space consists of only conjunctions of linear inequalities built from the variables in the loop, which is not expressive enough to capture all loop invariants.
+For example, the loop invariant
a[i] == 0contains 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.
+ - the synthesizer suffers from the same limitation as the loop contract verification in CBMC. For example, it does not support unbounded quantifiers, or dynamic allocations in the loop body. +
User Experience
+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.
Limit Resource Used by Synthesizer for Termination
+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.
Output of Kani when the Synthesizer is Enabled
+When the flag --synthesize-loop-contracts is provided, Kani will report different result for different cases
-
+
- When there exists some loop invariant in the candidate space with which all assertions can be proved, Kani will synthesize the loop contracts, verify the program with the synthesized loop contracts, and report verification SUCCESS; +
- When no working candidate has been found in the search space within the specified limits, Kani will report the verification result with the best-effort-synthesized loop contracts.
+Note that as loop contracts are over-approximations of the loop, the violated assertions in this case may be spurious.
+So we will report the violated assertions as
UNDETERMINEDinstead ofFAILED.
+
A question about how do we print the synthesized loop contracts when users request is discussed in Open question.
+Detailed Design
+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 resource limit of the synthesis; +
- the solver options to specify what SAT solver we use to verify invariant candidates. +
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.
-
+
- If all checks in the program pass,
goto-synthesizerreturns it as a solution.
+ - If the inductive checks pass but some of the other checks fail, the candidate invariant is inductive. +We keep it as an inductive invariant clause. +
- If the inductive checks fail, we discard the candidate.
+When the resource limit is reached,
goto-synthesizerreturns 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.
Rationale and alternatives
+-
+
- Different candidate space.
+The candidate grammar introduced above now only contains a restricted set of operators, which works well for array-manipulating programs with only pointer-checks instrumented by
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.
+
Open questions
+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.
+-
+
- We need to have a consistent way to identify loops. +
- We need to dump loop invariants in
rustinstead ofc.
+ - There are many auxiliary variables we added in Kani-compiled GOTO, such as
var_9,var_10,var_11, andvar_12in the above JSON file. +We need to translate them back to the original variables they represent.
+
Future possibilities
+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.
+1
+
+We say an integer variable is unbounded if there is no other bound on its value besides the width of its bit-vector representation.
+-
+
- Feature Name: The
kani::should_panicattribute (should-panic-attr)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/600 +
- RFC PR: https://github.com/model-checking/kani/pull/2272 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: +
-
+
- Version 0: https://github.com/model-checking/kani/pull/2315 +
- Version 1: https://github.com/model-checking/kani/pull/2532 +
+
Summary
+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.
User Impact
+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.
+User Experience
+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.
+Single Harness
+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:
+-
+
- (Expectation) Was Kani expecting the harness to panic? +
- (Outcome): What's the actual result that Kani produced after the analysis? +This will avoid a potential scenario where the user doesn't know for sure if the attribute has had an effect when verifying the harness. +
Therefore, the representation must make clear both the expectation and the outcome. +Below, we show how we'll represent this result.
+Recommended Representation: As a Global Condition
+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 hadprop.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.
Multiple Harnesses
+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.
+Multiple panics
+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.
Availability
+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:
-
+
- It'd make the design and implementation unnecessarily complex. +
- It'd only be useful when combined with
--harnessto filter negative harnesses.
+ - We could have trouble extending its functionality (see Future possibilities for more details). +
Pedagogy
+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.
+Detailed Design
+At a high level, we expect modifications in the following components:
+-
+
kani-compiler: Changes required to (1) process the new attribute, and (2) extendHarnessMetadatawith ashould_panic: boolfield.
+kani-driver: Changes required to (1) edit information about harnesses printed bykani-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).
+Rationale and alternatives
+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.
+Alternative #1: Generic failures
+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.
+Alternative #2: Name
+We have considered two alternatives for the "expectation" part of the attribute's name: should and expect.
+We avoid expect altogether for two reasons:
-
+
- We may consider adding the
expectedargument to#[kani::should_panic].
+ - We may consider a more granular approach to indicate expectations regarding individual checks and cover statements in the future. One possible name for the attribute is
#[kani::expect].
+ - We heavily use this word for testing in Kani: there is an
expectedmode, which works with*.expectedfiles. Other modes also use such files.
+
Alternative #3: The expected argument
+We 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].
Alternative #4: Granularity
+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:
+-
+
- What if users don't want to only check for failures (e.g., reachability)? +
- In the previous case, would they expect the overall verification to fail or not? +
- How do we want these expectations to be declared? +
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.
+Alternative #5: Kani API
+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.
+Open questions
+Once the feature is available, it'd be good to gather user feedback to answer these questions:
+-
+
- Do we need a mechanism to express more granular expectations? +
- If we need the mechanism in (2), do we really want to collapse them into one feature? +
Resolved questions
+-
+
- What is the best representation to use for this feature? A representation that changes the overall result seems to be preferred, according to feedback we received during a discussion. +
- Do we want to extend
#[kani::should_panic]with anexpectedfield? Yes, but not in this version.
+ - Do we want to allow multiple panic-related failures with
#[kani::should_panic]? Yes (this is now discussed in User Experience).
+
Future possibilities
+-
+
- The attribute could be an argument to
kani::proof(#[kani::proof(should_panic)]reads very well).
+ - Add an
expectedargument to#[kani::should_panic], and replay the harness with concrete playback to get the actual panic string.
+
2
+
+Double negation may not be the best representation, but it's at least accurate with respect to the original result.
+1
+
+This summary is printed in both the default and terse outputs.
+-
+
- Feature Name: Unstable APIs (
unstable-api)
+ - RFC Tracking Issue: https://github.com/model-checking/kani/issues/2279 +
- RFC PR: https://github.com/model-checking/kani/pull/2281 +
- Status: Unstable +
- Version: 0 +
+
Summary
+Provide a standard option for users to enable experimental APIs and features in Kani, +and ensure that those APIs are off by default.
+User Impact
+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.
+User Experience
+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.
+Detailed Design
+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.
+API Stabilization
+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.
API Removal
+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.
Rational and Alternatives
+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.
+Open questions
+-
+
- Should we also add a
stableattribute that documents when an API was stabilized?
+
Future possibilities
+-
+
- Delay the error due to the usage of a unstable API, and only fail at runtime if the API is reachable. +
- Allow users to enable unstable features on a per-harness basis. +
-
+
- Feature Name: Global Conditions (
global-conditions)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2525 +
- RFC PR: https://github.com/model-checking/kani/pull/2516 +
- Status: Unstable +
- Version: 0 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/2532 +
+
Summary
+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.
+User Impact
+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.
+User Experience
+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.
Detailed Design
+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.
+Rationale and alternatives
+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.
+Alternative: Global conditions as regular checks
+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.
+Open questions
+No open questions.
+Future possibilities
+A redesign of Kani's output is likely to change the style/architecture to report global conditions.
+3
+
+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.
+2
+
+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.
1
+
+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.
-
+
- Feature Name: Line coverage (
line-coverage)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2610 +
- RFC PR: https://github.com/model-checking/kani/pull/2609 +
- Status: Cancelled +
- Version: 0 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/2609 (Kani) + https://github.com/model-checking/kani-vscode-extension/pull/122 (Kani VS Code Extension) +
+
Summary
+Add verification-based line coverage reports to Kani.
+User Impact
+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:
+-
+
- Learning: New users are more familiar with coverage reports than property-based results. +
- Development: Some users prefer coverage results to property-based results since they are easier to interpret. +
- CI Integration: Users may want to enforce a minimum percentage of code coverage for new contributions. +
- Debugging: Users may find coverage reports particularly helpful when inputs are over-constrained (missing some corner cases). +
- Evaluation: Users can easily evaluate where and when more verification work is needed (some projects aim for 100% coverage). +
Moreover, adding this option directly to Kani, instead of relying on another tools, is likely to:
+-
+
- Increase the speed of development +
- Improve testing for coverage features +
Which translates into faster and more reliable coverage options for users.
+User Experience
+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.
+High-level changes
+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.
+Experimental output format for coverage results
+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.
+Detailed Design
+Architecture
+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
+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:
-
+
- Hidden from verification results. +
- Postprocessed to produce coverage results. +
In the following, we describe the injection and postprocessing procedures to generate coverage results.
+Injection of Coverage Checks
+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.
+Postprocessing Coverage Checks
+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
+-
+
- if all checks are
SATISFIED: returnFULL
+ - if all checks are
UNSATISFIED: returnNONE
+ - otherwise: return
PARTIAL
+
We won't report coverage status for lines which don't include a coverage check.
+Rationale and alternatives
+Benefits from a native coverage solution
+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:
-
+
- The instrumentation performed on the program. Eventually, this would allow us to report more precise coverage information (maybe similar to Rust's instrument-based code coverage). +
- The format of the coverage report to be generated. Similarly, this would allow us to generate coverage data in different formats (see #1706 for GCOV, or #1777 for LCOV). While technically this is also doable from
cbmc-viewer's output, development is likely to be faster this way.
+
Coverage through cbmc-viewer
+As an alternative, we could fix and use cbmc-viewer to report line coverage.
Most of the issues with cbmc-viewer are generally due to:
-
+
- Missing locations due to non-propagation of locations in either Kani or CBMC. +
- Differences in the definition of a basic block in CBMC and Rust's MIR. +
- Scarce documentation for coverage-related options (i.e.,
--cover <option>) in CBMC.
+ - Limited testing with Rust code in
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.
Other output formats
+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
+Open questions:
+-
+
- Do we want to report line coverage as
COVERED/UNCOVEREDorFULL/PARTIAL/NONE?
+ - Should we report coverage results and verification results or not? Doing both is likely to result in worse performance. We have to perform an experimental evaluation with hard benchmarks. +
- Should we instrument dependencies or not? Doing so is likely to result in worse performance. We have to perform an experimental evaluation. +
- What should be the final UX for this feature? For instance, we could print a coverage summary and generate a report file per harness. But it's not clear if individual results are relevant to users, so another possibility is to automatically combine results. +
- What's the most appropriate and well-established output format we can emit? +
- Determine if there are cases in which coverage information is confusing for users (due to, e.g., constant propagation or other compiler optimizations). How can work around such cases? +
- Do we want to report coverage information for dependencies? For CI, most users may be only interested in their code. Most coverage frameworks have an aggregation tool with an option to exclude dependencies from coverage metrics. +
Feedback to gather before stabilization:
+-
+
- Compare the injection-based approach in this RFC with Rust's instrument-based code coverage? +
Future possibilities
+We expect many incremental improvements in the coverage area:
+-
+
- Consuming the output produced in coverage results from the Kani VS Code extension. +
- Building a tool that produces coverage results by combining the coverage results of more than one harness. +
- Including span information in coverage checks and building region-based coverage reports. +
- Adding new user-requested coverage formats such as GCOV #1706 or LCOV #1777. +
1
+
+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.
+2
+
+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.
-
+
- Feature Name: Function Contracts +
- Feature Request Issue: #2652 and Milestone +
- RFC PR: #2620 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: features/contracts +
- Feature Gate:
-Zfunction-contracts, enforced by compile time error1
+
+
Summary
+Function 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.
+ +User Impact
+ +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.
+-
+
- Scalability: A function contract is an abstraction (sound +overapproximation) of a function's behavior. After verifying the contract +against its implementation we can subsequently use the (cheaper) abstraction +instead of the concrete implementation when analyzing its callers. +Verification is thus modularized and even cacheable. +
- Unbounded Verification: Contracts enable inductive reasoning for recursive +functions where the first call is checked against the contract and recursive +calls are stubbed out using the abstraction. +
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.
+User Experience
+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 andensures(postconditions) which +approximates function outputs in terms of function inputs.
+#[kani::requires(divisor != 0)] +#[kani::ensures(|result : &u32| *result <= dividend)] +fn my_div(dividend: u32, divisor: u32) -> u32 { + dividend / divisor +} +
+requireshere indicates this function expects itsdivisorinput to never +be 0, or it will not execute correctly (for instance panic or cause undefined +behavior).
+ensuresputs a bound on the output, relative to thedividendinput.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 passed into the ensures closure statement by reference. 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
+requiresandensuresclauses 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
+staticvariables.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 referencesTARGET, 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_divKani 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) askani::assumebefore the call +tomy_div, limiting inputs to those the function is actually defined for. +It inserts postconditions (ensures) askani::assertchecks after the +call tomy_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_kani_internal = my_div(dividend, divisor); + kani::assert((|result : &u32| *result <= dividend)(result_kani_internal)); // 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_contractharness for each abstracted function, otherwise an error is +thrown. In addition, by default, it requires allproof_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_divcontract 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_divlooks 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.
+Write Sets and Havocking
+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.
History Expressions
+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(|result : &Option<T>| 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(|result : &Option<T>| { let x = self.is_empty(); old(x) } || result.is_some())]
+Valid ✅: #[kani::ensures(|result : &Option<T>| 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.
Workflow and Attribute Constraints Overview
+-
+
- By default
kaniorcargo kanifirst verifies all contract harnesses +(proof_for_contract) reachable from the file or in the local workspace +respectively.
+ - Each contract (from the local
+crate7) that is used in a
+
stub_verifiedis required to have at least one associated contract harness. +Kani reports any missing contract harnesses as errors.
+ - Kani verifies all regular harnesses if their
stub_verifiedcontracts +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,modifiesandfrees+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 whereTARGETmust +"have a contract". One or moreproof_for_contractharnesses may have the +sameTARGET.A
+proof_for_contractharness may use any harness attributes, including +stubandstub_verified, though theTARGETmay not appear in either.
+ -
+
Kani checks that
+TARGETis reachable from theproof_for_contractharness, +but it does not warn if abstracted functions useTARGET8.
+ -
+
A
+proof_for_contractfunction may not have thekani::proofattribute (it +is already implied byproof_for_contract).
+ -
+
A harness may have multiple
+stub_verified(TARGET)attributes. EachTARGET+must "have a contract". NoTARGETmay appear twice. Each localTARGETis +expected to have at least one associatedproof_for_contractharness which +passes verification, see also the discussion on when to check contracts in +open questions.
+ -
+
Harnesses may combine
+stub(S_TARGET, ..)andstub_verified(V_TARGET)+annotations, though no target may occur inS_TARGETs andV_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.
+
Detailed Design
+ +Kani implements the functionality of function contracts in three places.
+-
+
- Code generation in the
requiresandensuresmacros (kani_macros).
+ - GOTO level contracts using CBMC's contract language generated in
+
kani-compilerformodifiesclauses.
+ - Dependencies and ordering among harnesses in
kani-driverto enforce +contract checking before replacement. Also plumbing between compiler and +driver for enforcement of assigns clauses.
+
Code generation in kani_macros
+The 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(|result : &Option<T>| 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_kani_internal = Self::pop(self);
+ kani::assert((|result : &Option<T>| self.is_empty() || self.len() == old_1 - 1)(result_kani_internal))
+ }
+}
+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(|result : &(&mut [T], &mut [T])| 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:
-
+
- Postconditions are not allowed perform mutation and +
- Post conditions are of type
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.
Recursion
+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.
+Changes to Other Components
+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.
Rationale and alternatives
+ + +We developed the old contract for history expressions via understanding it as a modality originating from Moggi 1991.
+The old monad links the "language of the past" to the "language of the present".
+Implementing the full generality of the monad is rather difficult, so we focus on a particular usage of the monad.
We have an external syntax representation which is what the user inputs. We then parse this and logically manipulate it as a monad, prefixing all the bind operations. We then output the final compiled macro output as Rust code.
In particular, if we have an ensures statement like
+#[kani::ensures(old(*ptr)+1==*ptr)]
+Then we comprehend this as syntax for the statement (not within Rust)
+bind (*ptr : O(u32)) (|remember : u32| remember + 1 == *ptr)
+Here, the O(u32) is taking the type of the past u32 and converting it into a type in the present O(u32) while the bind operation lets you use the value of the past u32 to express a type in the present bool.
This then gets compiled to (within Rust)
+let remember = *ptr;
+let result = ...;
+kani::assert(remember + 1 == *ptr)
+This means that the underlying principle of the monad is there, but external syntax appears to be less like a monad because otherwise it would be too difficult to implement, and the user most likely only cares about this particular construction of prefixing all the bind operations.
This construction requires that old expressions are closed with resprect to the input parameters. This is due to the lifting into the prefixed bind operations.
A major drawback is that eta expansion fails. If we eta expand a function f, it becomes |x|f(x). Note that eta expansions guarantee that the original f and the |x|f(x) are equivalent which makes a lot of sense since you’re just calling the same function. However, we have that old(y) is not equivalent to (|x|old(x))(y). y is a closed expression, so the first statement works. x is a bound variable, so it is an open expression, so compilation will fail.
The reason for this restriction is that the user will most likely only want to use this particular prefixed bind structure for their code, so exposing the concept of monads to the user level would only confuse the user. It is also simpler from an implementation perspective to limit the monad to this particular usage.
As for nested old, such as old(old(*ptr)+*ptr), it is reasonable to interpret this as syntax representing
bind (bind(*ptr)(|remember_1| remember_1 + *ptr)) (|remember_0| ...)
+which compiles to
+let remember_1 = *ptr;
+let remember_0 = remember_1 + *ptr;
+let result = ...;
+...
+so the restriction is just a matter of there not being implementation support for this kind of statement rather than the theory itself. It is not particularly useful to implement this because we claim that there should be no effectful computation within the contracts, so you can substitute the remember_1 into the second line without worrying about the effects. Hence, we opt for simply restricting this behavior instead of implementing it. (Note: it can be implemented by changing denier.visit_expr_mut(e); into self.visit_expr_mut(e);)
Kani-side implementation vs CBMC
+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.
Expanding all contract macros at the same time
+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.
Generating nested functions instead of siblings
+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.
Explicit command line checking/substitution vs attributes:
+Instead of
+adding a new special proof_for_contact attributes we could have instead done:
-
+
- Check contracts on the command line like CBMC does. This makes contract
+checking a separate
kaniinvocation with something like a +--check-contractflag 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.
+ - Check contracts with a
#[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.
+
Polymorphism during contract checking
+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.
User supplied harnesses
+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).
Open questions
+ +-
+
-
+
Returning
+kani::any()in a replacement isn't great, because it wouldn't work +for references as they can't have anArbitraryimplementation. Plus the +soundness then relies on a correct implementation ofArbitrary. 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
+@resultor +kani::result(), though with the latter I worry that people may get confused +because it is syntactic and not subject to usualuserenaming and import +semantics. Alternatively we can let the user pick the name with an additional +argument toensures, 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
+kaniand +cargo kanicheck 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:
+-
+
- By default (
kani/cargo kani) all local contracts are checked, +harnesses are only checked if the contracts they depend on succeeded their check.
+ - With harness selection (
--harness) only those contracts which the +selected harnesses depend on are checked.
+ - For high assurance passing a
--paranoidflag also checks contracts for +dependencies (other crates) when they are used in abstractions.
+ - Per harness the users can disable the checking for specific contracts
+via attribute, like
#[stub_verified(TARGET, trusted)]or +#[stub_unverified(TARGET)]. This also plays nicely withcfg_attr.
+ - On the command line users can similarly disable contract checks by
+passing (multiple times)
--trusted TARGETto skip checking those +contracts.
+ - The bold (or naïve) user can skip all contracts with
--all-trusted.
+ - For the lawyer that is only interested in checking contracts and nothing
+else a
--litigateflag 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.
+
+ - By default (
-
+
Can
+oldaccidentally break scope? Theoldfunction cannot reference local +variables. For instance#[ensures({let x = ...; old(x)})]cannot work as an +AST rewrite because the expression inoldis 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 thatxis unbound, however it is possible that +if there is also a function argumentx, 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 namedxwould +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 valuexin 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.
+
+ -
+
+modifiesclauses 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 themodifiesclause. Howevermodifiesclauses are implemented +asassignsclauses in CBMC which does not have a notion of function header +patterns. Thus it is necessary to project anymodifiesranges deeper by the +fields used in the matched pattern.
+
Future possibilities
+ +-
+
-
+
Quantifiers: Quantifiers are like logic-level loops and a powerful +reasoning helper. CBMC has support for both
+existsandforall, but the +code generation is difficult. The most ergonomic and easy way to implement +quantifiers on the Rust side is as higher-order functions takingFn(T) -> bool, whereTis 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 theFnclosure 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
+VecorRefCell) 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 theimplcontract. 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 parametersPthrough the +traits (T) they are constrained over. We can requireTto carry contracts +on each methodT::m(). During checking we can use a synthetic type that +abstractsT::m()with its contract. This way we checkf()againstTs +contract. Then we later abstractf()we can ensure any instantiations ofP+have passed verification of the contract ofT::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.
+
+
1
+
+Enforced gates means all uses of constructs (functions, annotations, +macros) in this RFC are an error.
+2
+
+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.
+3
+
+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.
4
+
+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.
5
+
+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)]
6
+
+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.
7
+
+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.
8
+
+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.
+-
+
- Feature Name: Quantifiers +
- Feature Request Issue: #2546 and #836 +
- RFC PR: # +
- Status: Unstable +
- Version: 1.0 +
+
Summary
+Quantifiers are logical operators that allow users to express that a property or condition applies to some or all objects within a given domain.
+User Impact
+There are two primary quantifiers: the existential quantifier (∃) and the universal quantifier (∀).
+-
+
-
+
The existential quantifier (∃): represents the statement "there exists." We use to express that there is at least one object in the domain that satisfies a given condition. For example, "∃x P(x)" means "there exists a value x such that P(x) is true."
+
+ -
+
The universal quantifier (∀): represents the statement "for all" or "for every." We use it to express that a given condition is true for every object in the domain. For example, "∀x P(x)" means "for every value x, P(x) is true."
+
+
Rather than exhaustively listing all elements in a domain, quantifiers enable users to make statements about the entire domain at once. This compact representation is crucial when dealing with large or unbounded inputs. Quantifiers also facilitate abstraction and generalization of properties. Instead of specifying properties for specific instances, quantified properties can capture general patterns and behaviors that hold across different objects in a domain. Additionally, by replacing loops in the specification with quantifiers, Kani can encode the properties more efficiently within the specified bounds, making the verification process more manageable and computationally feasible.
+This new feature doesn't introduce any breaking changes to users. It will only allow them to write properites using the existential (∃) and universal (∀) quantifiers.
+User Experience
+We propose a syntax inspired by "Pattern Types". The syntax of existential (i.e., kani::exists) and universal (i.e., kani::forall) quantifiers are:
kani::exists(|<var>: <type> [is <range-expr>] | <boolean-expression>)
+kani::forall(|<var>: <type> [is <range-expr>] | <boolean-expression>)
+If <range-expr> is not provided, we assume <var> can range over all possible values of the given <type> (i.e., syntactic sugar for full range |<var>: <type> as .. |). CBMC's SAT backend only supports bounded quantification under constant lower and upper bounds (for more details, see the documentation for quantifiers in CBMC). The SMT backend, on the other hand, supports arbitrary Boolean expressions. In any case, <boolean-expression> should not have side effects, as the purpose of quantifiers is to assert a condition over a domain of objects without altering the state.
Consider the following example adapted from the documentation for the from_raw_parts function:
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let v = vec![kani::any::<usize>(); 100];
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ }
+}
+Given the v vector has non-deterministic values, there are potential arithmetic overflows that might happen in the for loop. So we need to constrain all values of the array. We may also want to check all values of rebuilt after the operation. Without quantifiers, we might be tempted to use loops as follows:
use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 100];
+ let v = original_v.clone();
+ for i in 0..v.len() {
+ kani::assume(v[i] < 5);
+ }
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ for i in 0..len {
+ assert_eq!(rebuilt[i], original_v[i]+1);
+ }
+ }
+}
+This, however, might unnecessary increase the complexity of the verication process. We can achieve the same effect using quantifiers as shown below.
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 3];
+ let v = original_v.clone();
+ kani::assume(kani::forall(|i: usize is ..v.len() | v[i] < 5));
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ assert!(kani::forall(|i: usize is ..len | rebuilt[i] == original_v[i]+1));
+ }
+}
+The same principle applies if we want to use the existential quantifier.
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 3];
+ let v = original_v.clone();
+ kani::assume(kani::forall(|i: usize is ..v.len() | v[i] < 5));
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ if i == 1 {
+ *p.add(i) = 0;
+ }
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ assert!(kani::exists(|i: usize is ..len | rebuilt[i] == 0));
+ }
+}
+The usage of quantifiers should be valid in any part of the Rust code analysed by Kani.
+Detailed Design
+ +Kani should have the same support that CBMC has for quantifiers. For more details, see Quantifiers.
+Open questions
+ +-
+
- Function Contracts RFC - CBMC has support for both
existsandforall, but the +code generation is difficult. The most ergonomic and easy way to implement +quantifiers on the Rust side is as higher-order functions takingFn(T) -> bool, whereTis 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 theFnclosure to a compliant expression. +-
+
- Which kind of expressions should be accepted as a "compliant expression"? +
+
Future possibilities
+ +-
+
- CBMC has an SMT backend which allows the use of quantifiers with arbitrary Boolean expressions. Kani must include an option for users to experiment with this backend. +
+
-
+
- Feature Name: Source-based code coverage (
source-coverage)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2640 +
- RFC PR: https://github.com/model-checking/kani/pull/3143 +
- Status: Under Review +
- Version: 1 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/3119 (Kani) + https://github.com/model-checking/kani/pull/3121 (
kani-cov)
+
+
Summary
+A source-based code coverage feature for Kani built on top of Rust's coverage instrumentation.
+User Impact
+In our first attempt to add a coverage feature fully managed by Kani, we introduced and made available a line coverage option +(see RFC: Line coverage for more details). +This option has since then allowed us to gather more data around the expectations for a coverage feature in Kani.
+For example, the line coverage output we produced was not easy to interpret +without knowing some implementation details. +Aside from that, the feature requested in +#2795 alludes to the need +of providing coverage-specific tooling in Kani. +Nevertheless, as captured in +#2640, source-based +coverage results provide the clearest and most precise coverage information.
+In this RFC, we propose an integration with Rust's source-based code coverage
+instrumentation.
+This integration would allow us to report source-based code coverage results from Kani.
+Also, we propose adding a new user-facing, coverage-focused tool called kani-cov.
+The tool would allow users to process coverage results generated by Kani and produce
+coverage artifacts such as summaries and reports according to their preferences.
+In the next section, we will explain in more detail how we
+expect kani-cov to assist with coverage-related tasks.
With these changes, we expect our coverage options to become more flexible, +precise and efficient. These options are expected to replace the previous +options available through the line coverage feature. +In the last section of this RFC, we will also discuss +the requirements for a potential integration of this coverage feature with the +LLVM toolchain.
+User Experience
+The proposed experience is partially inspired by that of the most popular +coverage frameworks. +First, let us delve into the LLVM coverage workflow, followed by an explanation +of our proposal.
+The LLVM code coverage workflow
+The LLVM project is home to one of the most popular code coverage frameworks. +The workflow associated to the LLVM framework is described in the documentation for +source-based code coverage1, +but we briefly describe it here to better relate it with our proposal.
+In short, the LLVM code coverage workflow follows three steps:
+-
+
- Compiling with coverage enabled. This causes the compiler to generate an instrumented program. +
- Running the instrumented program. This generates binary-encoded
.profrawfiles.
+ - Using tools to aggregate and export coverage information into other formats. +
When working in a cargo project, step 1 can be done through this command:
RUSTFLAGS='-Cinstrument-coverage' cargo build
+The same flag must to be used for step 2:
+RUSTFLAGS='-Cinstrument-coverage' cargo run
+This should populate the directory with at least one .profraw file.
+Each .profraw file corresponds to a specific source code file in your project.
At this point, we will have produced the artifacts that we generally require for +the LLVM tools:
+-
+
- The instrumented binary which, in addition to the instrumented program, +contains additional information (e.g., the coverage mappings) required to +interpret the profiling results. +
- The
.profrawfiles which essentially includes the profiling results +(e.g., counter values) for each function of the corresponding source code file.
+
For step 3, the commands will depend on what kind of results we want.
+Most likely we will have to merge the .profraw files and produce a .profdata
+file as follows:
llvm-profdata merge -sparse *.profraw -o output.profdata
+The resulting .profdata file will contain the aggregated coverage results from
+the .profraw files passed to the merge command.
Then, we can use a command such as
+llvm-cov show target/debug/binary —instr-profile=output.profdata -show-line-counts-or-regions
+to visualize the code coverage through the terminal as in the image:
+or the command
+llvm-cov report target/debug/binary --instr-profile=output.profdata --show-region-summary
+to produce coverage summaries like this:
+Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover Branches Missed Branches Cover
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+/long/long/path/to/my/project/binary/src/main.rs 9 3 66.67% 3 1 66.67% 14 4 71.43% 0 0 -
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+TOTAL 9 3 66.67% 3 1 66.67% 14 4 71.43% 0 0 -
+1
+
+The LLVM project refers to their own coverage feature as +source-based code coverage. It is not rare to see the term region +coverage being used instead to refer to the same thing. That is because +LLVM's source-based code coverage feature can report coverage for code +regions, but other coverage frameworks do not support the concept of code +regions.
+The Kani coverage workflow
+The two main components of the Kani coverage workflow that we propose are the +following:
+-
+
- The existing
--coverageflag that drives the coverage workflow in Kani, +emits raw coverage data (as in the.profrawfiles), and produces basic +coverage results by default.
+ - A new subcommand
covthat allows users to further process raw coverage +information emitted by Kani to produce customized coverage results (i.e., +different to the ones produced by default with the--coverageoption). +Thecovsubcommand is an alias for thekani-covtool.
+
In contrast to the LLVM workflow, where human-readable coverage results can
+be produced only after a sequence of LLVM tool commands, we provide some
+coverage results by default.
+This aligns better with our UX philosophy, and removes the need for a wrapper
+around our coverage features like
+cargo-llvm-cov.
+Alternatively, the cov subcommand offers the ability of producing more
+specific coverage results if needed.
+We anticipate the cov subcommand being particularly useful in less standard
+project setups, giving the users the flexibility required to produce coverage
+results tailored to their specific needs.
In the following, we describe each one of these components in more detail.
+The --coverage option
+The default coverage workflow will be kicked off through the unstable
+--coverage option:
cargo kani --coverage -Zsource-coverage
+The main difference with respect to the regular verification workflow is that, +at the end of the verification-based coverage run, Kani will generate two coverage +results:
+-
+
- A coverage summary corresponding to the coverage achieved by the harnesses +included in the verification run. This summary will be printed after the +verification output. +
- A coverage report corresponding to the coverage achieved by the harnesses +included in the verification run. The report will be placed in the same target +directory where the raw coverage files are put. The path to the report will +also be printed after the verification output. +
Therefore, a typical --coverage run could look like this:
VERIFICATION:- SUCCESSFUL
+
+Coverage Results:
+
+| Filename | Regions | Missed Regions | Cover | Functions | Missed Functions | Cover |
+| -------- | ------- | -------------- | ----- | --------- | ---------------- | ----- |
+| main.rs | 9 | 3 | 66.67 | 3 | 1 | 33.33 |
+| file.rs | 11 | 5 | 45.45 | 2 | 1 | 50.00 |
+
+Coverage report available in target/kani/x86_64-unknown-linux-gnu/cov/kani_2024-04-26_15-30-00/report/index.html
+The cov subcommand
+The cov subcommand will be used to process raw coverage information generated
+by Kani and produce coverage outputs as indicated by the user.
+Hence, the cov subcommand corresponds to the set of LLVM tools
+(llvm-profdata, llvm-cov, etc.) that are used to produce coverage outputs
+through the LLVM coverage workflow.
In contrast to LLVM, we will have a single subcommand for all Kani
+coverage-related needs. The cov subcommand will just call the kani-cov tool,
+which is expected to be shipped along the rest of Kani binaries.
We suggest that the subcommand initially offers two options:
+-
+
- An option to merge the coverage results from one or more files and coverage +mappings2 into a single file. +
- An option to produce coverage outputs from coverage results, including summaries +or coverage reports in human-readable formats (e.g., HTML). +
Let's assume that we have run cargo kani --coverage -Zsource-coverage and
+generated coverage files in the my-coverage folder. Then, we would use cargo kani cov as follows to combine the coverage results3 for all
+harnesses:
cargo kani cov --merge my-coverage/*.kaniraw -o my-coverage.kanicov
+Let's say the user is first interested in reading a coverage summary through the
+terminal.
+They can use the --summary option for that:
cargo kani cov --summary my-coverage/default.kanimap -instr-profile=my-coverage.kanicov
+The command could print a coverage summary like:
+| Filename | Regions | Missed Regions | Cover | Functions | ...
+| -------- | ------- | -------------- | ----- | --------- | ...
+| main.rs | 9 | 3 | 66.67 | 3 | ...
+[...]
+Now, let's say the user wants to produce an HTML report of the coverage results.
+They will have to use the --report option for that:
cargo kani cov --report my-coverage/default.kanimap -format=html -instr-profile=my-coverage.kanicov -o coverage-report
+This time, the command will generate a coverage-report folder including a
+browsable HTML webpage that highlights the regions covered in the source
+according to the coverage results in my-coverage.kanicov.
4
+
+The llvm-cov tool includes the option
+gcov to
+export into GCC's coverage format Gcov,
+and the option
+export
+to export into the LCOV format. These may be good options to consider for
+kani-cov in the future but we should focus on basic formats for now.
3
+
+Options to exclude certain coverage results (e.g, from the +standard library) will likely be part of this option.
+2
+
+Coverage mappings essentially provide a snapshot of the source +code reports for items that otherwise are unreachable or have been sliced +away during the compilation process.
+Integration with the Kani VS Code Extension
+We will update the coverage feature of the
+Kani VS Code Extension
+to follow this new coverage workflow.
+In other words, the extension will first run Kani with the --coverage option and
+use kani cov to produce a .kanicov file with the coverage results.
+The extension will consume the source-based code coverage results and
+highlight region coverage in the source code seen from VS Code.
We could also consider other coverage-related features in order to enhance the +experience through the Kani VS Code Extension. For example, we could +automatically show the percentage of covered regions in the status bar by +additionally extracting a summary of the coverage results.
+Finally, we could also consider an integration with other code coverage tools.
+For example, if we wanted to integrate with the VS Code extensions
+Code Coverage or
+Coverage Gutters,
+we would only need to extend kani-cov to export coverage results to the LCOV
+format or integrate Kani with LLVM tools as discussed in Integration with LLVM.
Detailed Design
+In this section, we provide more details on:
+-
+
- The Rust coverage instrumentation and how it can be integrated into +Kani to produce source-based code coverage results. +
- The proposed coverage workflow to be run by default in Kani when the
+
--coverageoption is used.
+
This information is mostly intended as a reference for Kani contributors. +Currently, the Rust coverage instrumentation continues to be developed. Because +of that, Rust toolchain upgrades may result in breaking changes to our own +coverage feature. This section should help developers to understand the general +approach and resolve such issues by themselves.
+The Rust coverage instrumentation
+The Rust compiler includes two code coverage implementations:
+-
+
- A source-based coverage implementation which uses LLVM's coverage
+instrumentation to generate precise coverage data. This implementation can be
+enabled with
-C instrument-coverage.
+ - A Gcov-based coverage implementation that derives coverage data based on
+DebugInfo. This implementation can be enabled with
-Z profile.
+
The Instrumentation-based Code Coverage
+chapter from the rustc book describes in detail how to enable and use the LLVM
+instrumentation-based coverage feature. In contrast, the
+LLVM Source-Based Code Coverage
+chapter from the rustc development guide documents how the LLVM
+coverage instrumentation is performed in the Rust compiler.
In this section, we will first summarize some information from the +LLVM Source-Based Code Coverage +chapter, limited to details which are relevant to the development of the +source-based coverage feature in Kani. Then, we will explain how Kani taps into +the Rust coverage instrumentation to perform its own coverage instrumentation +and be able to report source-based code coverage results. This will also include +mentions to current issues with this implementation, which we plan to further +discuss in Future possibilities.
+Understanding the Rust coverage instrumentation
+The LLVM coverage instrumentation is implemented in the Rust compiler as a
+MIR pass called InstrumentCoverage.
The MIR pass first builds a coverage-specific version of the MIR Control Flow
+Graph (CFG) from the MIR. The initial version of this CFG is based on the MIR's
+BasicBlocks, which then gets refined by combining blocks that can be chained
+from a coverage-relevant point of view. The final version of the coverage CFG is
+then used to determine where to inject the
+StatementKind::Coverage
+statements in order to measure coverage for a single region coverage span.
The injection of StatementKind::Coverage statements is the main result we are
+interested in for the integration with Kani. Additionally, the instrumentation
+will also attach the
+FunctionCoverageInfo
+structure to each function's body.5
+This result is also needed at the moment because coverage statements do not
+include information on the code region they are supposed to cover.
+However, FunctionCoverageInfo contains the
+coverage mappings,
+which represent the relation between
+coverage counters
+and code regions.
As explained in MIR Pass:
+InstrumentCoverage,
+many coverage statements will not be converted into a physical
+counter6. Instead, they will be converted into a
+coverage-counter expression that can be calculated based on other coverage
+counters. We highly recommend looking at the example in MIR Pass:
+InstrumentCoverage
+to better understand how this works. This optimization is mainly done for
+performance reasons because incrementing a physical counter causes a
+non-negligible overhead, especially within loops.
The (StatementKind::)Coverage statements that are injected by the Rust coverage
+instrumentation contain a CoverageKind field indicating the type of coverage counter. The variant
+CounterIncrement
+represents physical counters, while
+ExpressionUsed
+represents the counter expressions that we just discussed.
+Other variants such as SpanMarker or BlockMarker are not relevant to this
+work since they should have been erased after the InstrumentCoverage pass.
5
+
+It is important to note that the StableMIR interface does
+not include FunctionCoverageInfo in function bodies. Because of that, we
+need to pull it from the internal rustc function bodies.
6
+
+By physical counter, we refer to a global program +variable that is initialized to zero and incremented by one each time that +the execution passes through.
+Integrating the instrumentation into Kani
+Now that we have explained what the Rust coverage instrumentation does at a high +level, we should be ready to discuss how it can be used from Kani. Here, we will +follow an approach where, during the codegen stage, we generate a Kani +reachability check for each code region and, after the verification stage, we +postprocess the information in those checks to generate the coverage +information. So this section will essentially be a retelling of the +implementation in #3119, and +we will discuss variations/extensions of this approach in the +appropriate sections.
+Clearly, the first step is adding -C instrument-coverage to the rustc flags
+we use when calling the compiler to codegen. This flag enables the Rust coverage
+instrumentation that we discussed earlier, resulting in
-
+
- the injection of
+
Coverage+statements in the MIR code, and
+ - the inclusion of
FunctionCoverageInfoin function bodies.
+
The next step is handling the Coverage statements from codegen_statement.
Each Coverage statement contains opaque coverage
+information7 of the
+CoverageKind
+type which can be processed to determine the type of coverage counter
+(CounterIncrement for physical counters, ExpressionUsed for counter
+expressions) and the ID number of the counter. These two pieces of information allow us to
+uniquely identify the counter within a given function. For example,
+CounterIncrement(0) would generally refer to the first physical counter in the
+function.
Unfortunately, the CoverageKind information does not tell us anything about
+the code region that the counter covers. However, data about the code region can
+be pulled from the coverage mappings included in the FunctionCoverageInfo that
+is attached to the (internal) function body. Note that the coverage mappings
+includes information about all the coverage counters in a function, even for
+counters which have been dropped. Matching the CoverageKind information with
+that of the counters in the coverage mappings allows us to retrieve the code
+region for any counter.
Using all this data, for each coverage statement8 we generate a coverage check +that maintains the essence of the coverage checks described in the RFC for line +coverage:
+++Coverage checks are a new class of checks similar to
+coverchecks. +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 anassert(false)statement (to test reachability) with a fixed description. +In addition, coverage checks are:+
+- Hidden from verification results.
+- Postprocessed to produce coverage results.
+
Therefore, the last step is to postprocess the results from coverage checks to +produce coverage results. This is not too complicated to do since the checks +already include the counter information (type + ID) and the function name in +the check's description. If the span of the code region is also included +(this is what #3119 is +currently doing), we can directly generate a primitive output like this:
+<file_path> (<function_name>)
+ * <region_start> - <region_end> <status>
+ * ...
+ * <region_start> - <region_end> <status>
+For example, for the test case in +#3119 we report this:
+src/main.rs (main)
+ * 14:1 - 19:2 COVERED
+
+src/main.rs (test_cov)
+ * 5:1 - 6:15 COVERED
+ * 6:19 - 6:28 UNCOVERED
+ * 7:9 - 7:13 COVERED
+ * 9:9 - 9:14 UNCOVERED
+ * 11:1 - 11:2 COVERED
+++NOTE: This section has been written according to the implementation in +#3119, which currently +produces a text-based output like the one shown above. There is ongoing work to +store the coverage mappings in a separate file (as described in the next +section), which would save us the need to attach code region data to the +coverage checks.
+
7
+
+The Rust compiler uses the Opaque type to prevent
+others from interfacing with unstable types (e.g., the Coverage type
+here).
+Nonetheless, this can be worked around by serializing its contents and parsing
+it back into an internal data type.
8
+
+We could follow an alternative approach where we +do not instrument each coverage statement, but only those that correspond to +physical counters. Unfortunately, doing so would lead to incorrect coverage +results due to the arithmetic nature of expression-based counters. We elaborate +on this topic in the later parts of this document.
+The default coverage workflow in Kani
+In this section, we describe the default --coverage workflow from a
+developer's point of view. This will hopefully help developers understand how
+the different coverage components in Kani are connected. For example, we'll
+describe the raw coverage information that gets produced throughout the default
+--coverage workflow and define the basic cov commands that it will execute.
The main difference with respect to the regular verification workflow is that, +at the end of the verification-based coverage run, Kani will generate two types +of files:
+-
+
- One single file
.kanimapfile for the project. This file will contain the +coverage mappings for the project's source code.
+ - One
.kanirawfile for each harness. This file will contain the +verification-based results for the coverage-oriented properties corresponding +to a given harness.
+
Note that .kaniraw files correspond to .profraw files in the LLVM coverage
+workflow. Similarly, the .kanimap file corresponds to the coverage-related
+information that's embedded into the project's binaries in the LLVM coverage
+workflow.9
The files will be written into a new timestamped directory associated with the
+coverage run. The path to this directory will be printed to standard output in
+by default. For example, the draft implementation
+writes the coverage files into the target/kani/<target_triple>/cov/ directory.
Users aren't expected to read the information in any of these files. +Therefore, there's no need to restrict their format. +The draft implementation +uses the JSON format but we might consider using a binary format if it doesn't +scale.
+In addition, Kani will produce two types of coverage results:
+-
+
- A coverage summary with the default options. +
- A terminal-based coverage report with the default options. However, we will +only do this if the program is composed of a single source +file10. +
9
+
+Note that the .kanimap generation isn't implemented in
+#3119. The draft
+implementation of
+kani-cov simply reads
+the source files referred to by the code coverage checks, but it doesn't get
+information about code trimmed out by the MIR linker.
10
+
+In other words, standalone kani would always emit
+these terminal-based reports, but cargo kani would not unless the project
+contains a single Rust file (for example, src/main.rs).
Rationale and alternatives
+Other coverage implementations
+In a previous version of this feature, we used an ad-hoc coverage implementation. +In addition to being very inefficient11, the line-based coverage +results were not trivial to interpret by users. +At the moment, there's only another unstable, GCC-compatible code coverage implementation +based on the Gcov format. The Gcov format is line-based so it's not able +to report region coverage results. +In other words, it's not as advanced nor precise as the source-based implementation.
+11
+
+Actual performance benchmarks to follow in +#3119.
+Open questions
+-
+
- Do we want to instrument dependencies by default? Preliminary benchmarking results show a slowdown of 100% and greater. +More evaluations are required to determine how we handle instrumentation for dependencies, and what options we might want +to provide to users. +
- How do we handle features/options for
kani-cov? In particular, do we need more details in this RFC?
+
Future possibilities
+Integration with LLVM
+As part of this work, we explored a potential integration with the LLVM
+framework. The idea behind such an integration would essentially involve
+producing coverage results in formats compatible with the LLVM framework (e.g.,
+the .profraw format). The main advantage of integrating with the LLVM
+framework in this way is that we would not need a tool like kani-cov to
+aggregate coverage results; we could just use LLVM tools such as llvm-profdata
+and llvm-cov to consume them.
However, at this time we recommend against integrating with LLVM due to these reasons:
+-
+
- Generating the instrumented binary used in the LLVM coverage
+workflow requires a standard
rustc+compilation with--cfg kaniin addition to other flags including-C instrument-coverage. This is likely to result in compilation errors since the +standardrustcbackend cannot produce code for Kani APIs, for example.
+ - Producing the
.profrawfiles requires executing the instrumented binary at +least once. This would be an issue for Rust projects which assume a particular +environment for their execution.
+ - There are no stable interfaces to create or modify files in formats
+compatible with the LLVM framework. Even though the documentation for the LLVM
+Code Coverage Mapping Format
+is excellent, the easiest way to interact with files on these format is through
+LLVM tools (e.g.,
+
llvm-cov) +which bring in many other LLVM dependencies. During our exploration, we +attempted to decode and re-encode files in the.profrawto set the counter +data to the values obtained during verification. To this end, we tried tools +likellvm-profparserwhich +can be used as a replacement forllvm-profdataandllvm-covbut failed to +parse coverage files emitted by the Rust compiler (this is also related to the +next point). Another crate that we used is +coverage-dump, +a recent tool in the Rust compiler used for testing purposes.coverage-dump+extracts coverage mappings from LLVM IR assembly files (i.e., human-readable +*.llfiles) but does not work with the binary-encoded formats. Finally, we +also built some ad-hoc tooling to perform these modifications but it soon +became evident that we would need to develop it further in order to handle any +program.
+ - LLVM releases a new version approximately every six months. This would
+likely result in another "toolchain update" problem for Kani in order to
+provide compatibility with newer LLVM versions. Moreover, the Rust compiler
+supplies their own version of LLVM tools (
rust-profdata,rust-cov, etc.) +which are fully compatible with coverage-related artifacts produced byrustc.
+
Optimization with coverage-counter expressions
+In the subsection related to the +integration, we noted that we could +follow an alternative approach where we only instrument coverage statements that +correspond to physical counters. In fact, this would be the logical choice since +the replacement of physical counters by expression-based counters would also be +a performance optimization for us.
+However, the expressions used in expression-based counters are built with the
+arithmetic operators Add (+) and Sub (-). On the other hand, the
+coverage checks performed by Kani have a boolean meaning: you either cover a
+region or you do not. Thus, there are many cases where these two notions of
+coverage counters are incompatible. For example, let's say we have this
+function:
fn check_value(val: u32) {
+ if val == VALUE {
+ do_this();
+ } else {
+ do_that();
+ }
+ do_something_else();
+}
+One way to optimize the counters in this function is to have two physical
+counters for the branches of the if statement (c1 and c2), and then an
+expression-based counter associated to the do_something_else() statement
+adding those (i.e., c3 = c1 + c2). If we have, for example, two executions for
+this program, with each one taking a different branch, then the results for the
+coverage counters will be c1 = 1, c2 = 1 and c3 = c1 + c2 = 2.
But what does c3 = 2 mean in the context of a verification-based coverage
+result? That is not clear. For instance, in a Kani trace, you could have a
+nondeterministic value for val which just happens to be val == VALUE and not
+at the same time. This would result in the same counters (c1 = 1, c2 = 1 and
+c3 = 2), but the program is being run only once!
Note that finding a verification-based replacement for the runtime operators in
+counter-based expressions is an interesting research topic. If we could
+establish a relation between the runtime and verification expressions, then we
+could avoid the instrumentation of coverage checks for expression-based
+counters. For example, could we replace the Add operator (+) with an Or
+operator (||)? Intuitively, this makes sense since verification-based coverage
+counters are binary. It also seems to work for our example since covering any of
+the branches should result in the do_something_else() statement being covered
+as well, with the counter values now being c1 = 1, c2 = 1 and c3 = 1.
+However, it is not clear that this would work for all cases, nor it is clear
+that we can replace Sub with another verification-based operator.
-
+
- Feature Name: Loop Contracts +
- Feature Request Issue: #3168 +
- RFC PR: #3167 +
- Status: Under Review +
- Version: 1 +
- Proof-of-concept: +
+
Summary
+Loop contracts provide way to safely abstract loops of a program, typically +in order to accelerate the verification process, and remove the loop unwinding +bounds. The key idea is to over-approximate the possible set of program states, +while still being precise enough to be able to prove the desired property.
+User Impact
+Loop contracts provide an interface for a verified, sound abstraction. +The goal for specifying loop contracts in the source code is two fold:
+-
+
- Unbounded verification: Currently, proving correctness +(i.e. assertions never fail) on programs with unbounded control flow (e.g. +loops with dynamic bounds) Kani requires unwinding loops for a large number of +times, which is not always feasible. Loop contracts provide a way to abstract +out loops, and hence remove the need for unwinding loops. +
- Faster CI runs: In most cases, the provided contracts would also significantly +improve Kani's verification time since all loops would be unrolled only to +a single iteration. +
Loop 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.
+User Experience
+A loop contract specifies the behavior of a loop as a boolean predicate +(loop invariants clauses) with certain frames conditions (loop modifies clauses) +that can be checked against the loop implementation, and used to abstract out +the loop in the verification process.
+We illustrate the usage of loop contracts with an example. +Consider the following program:
+fn simple_loop() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+}
+The loop in the simple_loop function keep subtracting 1 from x until x is 1.
+However, Kani currently needs to unroll the loop for u64::MAX number of times
+to verify the assertion at the end of the program.
With loop contracts, the user can specify the behavior of the loop as follows:
+fn simple_loop_with_loop_contracts() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+}
+The loop invariant clause #[kani::loop_invariant(x >= 1)] specifies the loop
+invariants that must hold at the beginning of each iteration of the loop right before
+checking the loop guard.
In this case, Kani verifies that the loop invariant x >= 1 is inductive, i.e.,
+x is always greater than or equal to 1 at each iteration before checking x > 1.
Also, once Kani proved that the loop invariant is inductive, it can safely use the loop +invariants to abstract the loop out of the verification process. +The idea is, instead of exploring all possible branches of the loop, Kani only needs to +prove those branches reached from an arbitrary program state that satisfies the loop contracts, +after the execution of one iteration of the loop.
+So, for loops without break statements, we can assume all post-states of the loop satisfying
+inv && !loop_guard for proving post-loops properties.
+The requirement of satisfying the negation of the loop guard comes from the fact that a path
+exits loops without break statements must fail the loop guard.
For example, applying loop contracts in simple_loop function is equivalent to the following:
fn simple_loop_transformed() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ x = kani::any(); // Arbitrary program state that
+ kani::assume( !(x > 1) && x >= 1); // satisfies !`guard` && `inv`
+
+ assert!(x == 1);
+}
+The assumption above is actually equivalent to x == 1, hence the assertion at the end
+of the program is proved.
Write Sets and Havocking
+For those memory locations that are not modified in the loop, loop invariants state
+that they stay unchanged throughout the loop are inductive. In other words, Kani should
+only havoc the memory locations that are modified in the loop. This is achieved by
+specifying the modifies clause for the loop. For example, the following program:
fn simple_loop_two_vars() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+ let mut y: u64 = 1;
+
+ #[kani::loop_invariant(x >= 1)]
+ #[kani::loop_modifies(x)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+ assert!(y == 1);
+}
+write to only x in the loop, hence the modifies clause contains only x.
+Then when use the loop contracts to abstract the loop, Kani will only havoc the memory
+location x and keep y unchanged. Note that if the modifies clause contains also
+y, Kani will havoc both x and y, and hence violate the assertion y == 1.
Kani can employs CBMC's write set inference to infer the write set of the loop.
+So users have to specify the modifies clauses by their self only when the inferred write
+sets are not complete---there exists some target that could be written to in the loop but
+is not in the inferred write set.
Proof of termination
+Loop contracts also provide a way to prove the termination of the loop. +Without the proof of termination, Kani could report success of some assertions that +are actually unreachable due to non-terminating loops. +For example, consider the following program:
+fn simple_loop_non_terminating() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while true{
+ x = x;
+ };
+
+ assert!(x >= 1);
+}
+After abstracting the loop, the loop will be transformed to no-op, and the assertion
+x >= 1 will be proved. However, the loop is actually an infinite loop, and the
+assertion will never be reached.
For this reason, Kani will also require the user to provide a decreases clause that
+specifies a decreasing expression to prove the termination of the loop. For example, in
fn simple_loop_terminating() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ #[kani::loop_decreases(x)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x >= 1);
+}
+, the decreases clause #[kani::loop_decreases(x)] specifies that the value of x
+decreases at each iteration of the loop, and hence the loop will terminate.
Detailed Design
+Kani implements the functionality of loop contracts in three places.
+-
+
- Procedural macros
loop_invariant,loop_modifies, andloop_decreases.
+ - Code generation for builtin functions expanded from the above macros. +
- GOTO-level loop contracts using CBMC's contract language generated in
+
kani-compiler.
+
Procedural macros loop_invariant, loop_modifies, and loop_decreases.
+We will implement the three proc-macros loop_invariant, loop_modifies, and loop_decreases to
+embed the annotation logic as Rust code. Kani will then compile them into MIR-level code.
Code Generation for Builtin Functions
+Then in the MIR, we codegen the loop contracts as GOTO-level expressions and annotate them +into the corresponding loop latches---the jumps back to the loop head.
+The artifact goto-instrument in CBMC will extract the loop contracts from the named-subs
+of the loop latch, and then apply and prove the extracted loop contracts.
GOTO-Level Havocing
+The ordinary havocing in CBMC is not aware of the type constraints of Rust type.
+Hence, we will use customized havocing functions for modifies targets. In detail,
+Kani will generate code for the definition of corresponding kani::any() functions
+for each modifies target. Then Kani will create a map from the modifies target to the
+the name of its kani::any() function, and add the map to the loop latch too.
On the CBMC site, goto-instrument will extract the map and instrument the customized
+havocing functions for the modifies targets.
Rationale and alternatives
+Rust-Level Transformation vs CBMC
+Besides transforming the loops in GOTO level using goto-instrument,
+we could also do the transformation in Rust level using procedural macros, or
+in MIR level.
There are two reasons we prefer the GOTO-level transformation.
+First, goto-instrument is a mature tool that can correctly instrument the frame
+condition checking for the transformed loop, which will save us from reinventing
+the error-prone wheel. Second, the loop contracts synthesis tool we developed and
+are developing are all based on GOTO level. Hence, doing the transformation in
+the GOTO level will make the integration of loop contracts with the synthesis tool
+easier.
Open questions
+-
+
- How do we integrate loop contracts with the synthesis tool? When the user-provided +loop contracts are not enough prove the harness, we expect the loop-contract synthesizer +can fix the loop contracts. +
- How do we translate back modify targets that inferred by CBMC to Rust level? +
- It is not clear how the CBMC loop modifies inference works for Rust code. We need to +experiment more to decide what would be the best UX of using loop modifies. +
- How do we handle havocing in unsafe code where it is fine to break the safety invariant +of Rust? In that case, we may need havocing function that preserves validity invariant +but not safety invariant. +
- What is the proper mechanism for users to specify the loops that they want to opt-out from applying loop contracts, and (optionally) the unwind numbers for them. Such options should be per-harness. +
Future possibilities
+-
+
- We can employ CBMC's decreases inference to infer the decreases clauses to reduce the +user burden of specifying the decreases clauses. +
+
-
+
- Feature Name: List Subcommand +
- Feature Request Issue: #2573, #1612 +
- RFC PR: #3463 +
- Status: Unstable +
- Version: 2 +
+
Summary
+Add a subcommand list that, for each crate under verification, lists the information relevant to its verification.
User Impact
+Currently, there is no automated way for a user to gather metadata about Kani's integration with their project. If, for example, a user wants a list of harnesses for their project, they must search for all the relevant contract attributes (currently #[proof] or #[proof_for_contract]) themselves. If done manually, this process is tedious, especially for large projects. Even with a shell script, it is error-prone--if, for example, we introduce a new type of proof harness, users would have to account for it when searching their project.
Internally, this feature will be useful for tracking our customers' use of Kani and our progress with standard library verification. Externally, users can leverage this feature to get a high-level view of which areas of their projects have harnesses (and, by extension, which areas are still in need of verification).
+This feature will not cause any regressions for exisiting users.
+User Experience
+Users run a list subcommand, which prints metadata about the harnesses and contracts in each crate under verification. The subcommand takes two options:
-
+
--message-format=[pretty|json]: choose the output format. The default ispretty, which prints to the terminal. Thejsonoption creates and writes to a JSON file instead.
+--std: this option should be specified when listing the harnesses and contracts in the standard library. This option is only available forkani list(notcargo kani list), which mirrors the verification workflow for the standard library.
+
This subcommand does not fail. In the case that it does not find any harnesses or contracts, it prints a message informing the user of that fact.
+Pretty Format
+The default format, pretty, prints a "Contracts" table and a "Standard Harnesses" list.
+Each row of the "Contracts" table consists of a function under contract and its contract harnesses.
+The results are printed in lexicographic order.
For example:
+Kani Rust Verifier 0.54.0 (standalone)
+
+Contracts:
+|-------|-------------------------|--------------------------------------------------|
+| | Function | Contract Harnesses (#[kani::proof_for_contract]) |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::bar | example::verify::check_bar |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::baz | example::verify::check_baz |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::foo | example::verify::check_foo_u32 |
+| | | example::verify::check_foo_u64 |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::func | example::verify::check_func |
+|-------|-------------------------|--------------------------------------------------|
+| | example::prep::parse | NONE |
+|-------|-------------------------|--------------------------------------------------|
+| Total | 5 | 5 |
+|-------|-------------------------|--------------------------------------------------|
+
+Standard Harnesses (#[kani::proof]):
+1. example::verify::check_modify
+2. example::verify::check_new
+All sections will be present in the output, regardless of the result.
+If there are no harnesses for a function under contract, Kani inserts NONE in the "Contract Harnesses" column.
+If the "Contracts" section is empty, Kani prints a message that "No contracts or contract harnesses were found."
+If the "Standard Harnesses" section is empty, Kani prints a message that "No standard harnesses were found."
JSON Format
+If the user wants an output format that's more easily parsed by a script, they can use the json option.
The JSON format will contain the same information as the pretty format, with the addition of file paths and file version. +The file version will use semantic versioning. +This way, any users relying on this format for their scripts can detect when we've released a new major version and update their logic accordingly.
+For example:
+{
+ kani-version: 0.54,
+ file-version: 0.1,
+ standard-harnesses: [
+ {
+ file: /Users/johnsmith/example/kani_standard_proofs.rs
+ harnesses: [
+ example::verify::check_modify,
+ example::verify::check_new
+ ]
+ },
+ ],
+ contract-harnesses: [
+ {
+ file: /Users/johnsmith/example/kani_contract_proofs.rs
+ harnesses: [
+ example::verify::check_bar,
+ example::verify::check_baz,
+ example::verify::check_foo_u32,
+ example::verify::check_foo_u64,
+ example::verify::check_func
+ ]
+ },
+ ],
+ contracts: [
+ {
+ function: example::impl::bar
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_bar]
+ },
+ {
+ function: example::impl::baz
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_baz]
+ },
+ {
+ function: example::impl::foo
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [
+ example::verify::check_foo_u32,
+ example::verify::check_foo_u64
+ ]
+ },
+ {
+ function: example::impl::func
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_func]
+ },
+ {
+ function: example::prep::parse
+ file: /Users/johnsmith/example/prep.rs
+ harnesses: []
+ }
+ ],
+ totals: {
+ standard-harnesses: 2,
+ contract-harnesses: 5,
+ functions-with-contracts: 5,
+ }
+}
+All sections will be present in the output, regardless of the result. +If there is no result for a given field (e.g., there are no contracts), Kani will output an empty list (or zero for totals).
+Software Design
+Driver/Metdata Changes
+We add a new list subcommand to kani-driver, which invokes the compiler to collect metadata, then post-processes that metadata and outputs the result.
+We extend KaniMetadata to include a new field containing each function under contract and its contract harnesses.
Compiler Changes
+In codegen_crate, we update the generation of KaniMetadata to include the new contracts information.
+We iterate through each local item in the crate.
+Each time we find a function under contract or a contract harness, we include it in the metadata.
Rationale and alternatives
+Users of Kani may have many questions about their project--not only where their contracts and harnesses are, but also where their stubs are, what kinds of contracts they have, etc. Rather than try to answer every question a user might have, which would make the output quite verbose, we focus on these four:
+-
+
- Where are the harnesses? +
- Where are the contracts? +
- Which contracts are verified, and by which harnesses? +
- How many harnesses and functions under contract are there? +
We believe these questions are the most important for our use cases of tracking verification progress for customers and the standard library. The UX is designed to answer these questions clearly and concisely.
+We could have a more verbose or granular output, e.g., printing the metadata on a per-crate or per-module level, or including stubs or other attributes. Such a design would have the benefit of providing more information, with the disadvantage of being more complex to implement and more information for the user to process. +If we do not implement this feature, users will have to obtain this metadata through manual searching, or by writing a script to do it themselves. This feature will improve our internal productivity by automating the process.
+The Contracts table is close to Markdown, but not quite Markdown--it includes line separators between each row, when Markdown would only have a separator for the header. +We include the separator because without it, it can be difficult to tell from reading the terminal output which entries are in the same row. +The user can transform the table to Markdown by deleting these separators, and we can trivially add a Markdown option in the future if there is demand for it.
+Open questions
+-
+
- Do we want to include more contracts information? We could print more granular information about contracts, e.g., the text of the contracts or the number of contracts. +
- More generally, we could introduce additional options that collect information about other Kani attributes (e.g., stubs). The default would be to leave them out, but this way a user could get more verbose output if they so choose. +
- Do we want to add a filtering option? For instance,
--harnesses <pattern>and--contracts <pattern>, wherepatterncorresponds to a Rust-style path. For example,kani list --harnesses "my_crate::my_module::*"would include all harnesses with that path prefix, whilekani list --contracts "my_crate::my_module::*"would include all functions under contract with that path prefix. (If we do this work, we could use it to improve our--harnesspattern handling for verification).
+
Out of scope / Future Improvements
+It would be nice to differentiate between regular Kani harnesses and Bolero harnesses. Bolero harnesses invoke Kani using conditional compilation, e.g.:
+#[cfg_attr(kani, kani::proof)]
+fn check() {
+ bolero::check!()...
+}
+See this blog post for more information.
+There's no easy way for us to know whether a harness comes from Bolero, since Bolero takes care of rewriting the test to use Kani syntax and invoking the Kani engine. By the time the harness gets to Kani, there's no way for us to tell it apart from a regular harness. Fixing this would require some changes to our Bolero integration.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0002-function-stubbing.html b/rfc/rfcs/0002-function-stubbing.html
new file mode 100644
index 000000000000..02a746999700
--- /dev/null
+++ b/rfc/rfcs/0002-function-stubbing.html
@@ -0,0 +1,609 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: MIR Linker (
mir_linker)
+ - RFC Tracking Issue: https://github.com/model-checking/kani/issues/1588 +
- RFC PR: https://github.com/model-checking/kani/pull/1600 +
- Status: Stable +
- Version: 3 +
+
Summary
+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.
+User Impact
+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.
+-
+
- Reduce spurious warnings about unsupported features for cases where the feature is not reachable from any harness. +
- In the verification mode, we will likely see a reduction on the compilation time and memory consumption
+by pruning the inputs of symtab2gb and goto-instrument.
+
-
+
- Compared to linking against the standard library goto-models that take more than 5 GB. +
+ - In a potential assessment mode, only analyze code that is reachable from all public items in the target crate. +
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).
User Experience
+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.
Detailed Design
+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 compiles the user crate as well as all its dependencies.
+For every crate compiled,
kani-compilerwill generate a goto-program. +This model includes everything reachable from the crate's public functions.
+ - After that, Kani links all models together by invoking
goto-cc. +This step will also link against Kani'sClibrary.
+ - For every harness, Kani invokes
goto-instrumentto prune the linked model to only include items reachable from the given harness.
+ - Finally, Kani instruments and verify each harness model via
goto-instrumentandcbmccalls.
+
After this RFC, the system flow would be slightly different:
+-
+
- Kani compiles the user crate dependencies up to the MIR translation.
+I.e., for every crate compiled,
kani-compilerwill generate an artifact that includes the MIR representation +of all items in the crate.
+ - Kani will generate the goto-program only while compiling the target user crate. +It will generate one goto-program that includes all items reachable from any harness in the target crate. +
goto-ccwill still be invoked to link the generated model against Kani'sClibrary.
+- Steps #3 and #4 above will be performed without any change. +
This feature will require three main changes to Kani which are detailed in the sub-sections below.
+Kani's Sysroot
+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.
Cross-Crate Reachability Analysis
+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--reachabilityflag 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-compilerwill 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: Mimicsrustcbehavior 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.
Dependencies vs Target Crate Compilation
+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=harnessestokani-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
+--reachabilityargument, and it will only passharnesses+value to the compiler when compiling the target crate.
+
Rational and Alternatives
+Not doing anything is not an alternative, since this fixes a major gap in Kani's usability.
+Benefits
+-
+
- The MIR linker will allow us to fix the linking issues with Rust's standard library. +
- Once stabilized, the MIR linker will be transparent to the user. +
- It will enable more powerful and precise static analysis to
kani-compiler.
+ - It won't require any changes to our dependencies. +
- This will fix the harnesses' dependency on the
#[no_mangle]annotation +(Issue-661).
+
Risks
+Failures in the linking stage would not impact the tool soundness. I anticipate the following failure scenarios:
+-
+
- ICE (Internal compiler error): Some logic is incorrectly implemented and the linking stage crashes. +Although this is a bad experience for the user, this will not impact the verification result. +
- Missing items: This would either result in ICE during code generation or a verification failure if the missing +item is reachable. +
- Extra items: This shouldn't impact the verification results, and they should be pruned by CBMC's reachability +analysis. +This is already the case today. In extreme cases, this could include a symbol that we cannot compile and cause an ICE. +
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.
Alternatives
+The other options explored were:
+-
+
- Pre-compile the standard library, and the kani library, and ship the generated
*symtab.jsonfiles.
+ - Pre-compile the standard library, and the kani library, convert the standard library and dependencies to goto-program
+(via
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.
+Open questions
+-
+
Should we build or download the sysroot during+We include pre-built MIR artifacts for thekani setup?stdlibrary.
+What's the best way to enable support to run Kani in the entire+We decided to runworkspace?cargo rustcper package.
+Should we codegen all static items no matter what?+We only generate code for static items that are collected by the reachability analysis. +Static objects can only be initialized via constant function. +Thus, it shouldn't have any side effect.
+What's the best way to handle+We are going to use the test profile and iterate over all the targets available in the crate: +cargo kani --tests?-
+
cargo rustc --profile test -- --reachability=harnesses
+
+
Future possibilities
+-
+
- Split the goto-program into two or more items to optimize compilation result caching.
+
-
+
- Dependencies: One model will include items from all the crate dependencies. +This model will likely be more stable and require fewer updates. +
- Target crate: The model for all items in the target crate. +
+ - Do the analysis per-harness. This might be adequate once we have a mechanism to cache translations. +
- Add an option to include external functions to the analysis starting point in order to enable verification when
+calls are made from
Ctorust.
+ - Contribute the reachability analysis code back to upstream. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0003-cover-statement.html b/rfc/rfcs/0003-cover-statement.html
new file mode 100644
index 000000000000..2c3596e80cbe
--- /dev/null
+++ b/rfc/rfcs/0003-cover-statement.html
@@ -0,0 +1,321 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: Function and method stubbing (
function-stubbing)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/1695 +
- RFC PR: https://github.com/model-checking/kani/pull/1723 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: https://github.com/aaronbembenek-aws/kani/tree/mir_transform +
+
Summary
+Allow users to specify that certain functions and methods should be replaced with mock functions (stubs) during verification.
+Scope
+In scope:
+-
+
- Replacing function bodies +
- Replacing method bodies (which means that the new method body will be executed, whether the method is invoked directly or through a vtable) +
Out of scope:
+-
+
- Replacing type definitions +
- Replacing macro definitions +
- Mocking traits +
- Mocking intrinsics +
User impact
+We anticipate that function/method stubbing will have a substantial positive impact on the usability of Kani:
+-
+
- Users might need to stub functions/methods containing features that Kani does not support, such as inline assembly. +
- Users might need to stub functions/methods containing code that Kani supports in principle, but which in practice leads to bad verification performance (for example, if it contains deserialization code). +
- Users could use stubbing to perform compositional reasoning: prove the behavior of a function/method
f, and then in other proofs---that callfindirectly---use a stub offthat 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.
+Mocking randomization
+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.
+User experience
+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.
+Stub sets
+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),
+));
+Error conditions
+Given a set of original-replacement pairs, Kani will exit with an error if
-
+
- a specified
originalfunction/method does not exist;
+ - a specified
replacementstub does not exist;
+ - the user specifies conflicting stubs for the same harness (e.g., if the same
originalfunction is mapped to multiplereplacementfunctions); or
+ - the signature of the
replacementstub is not compatible with the signature of theoriginalfunction/method (see next section).
+
Stub compatibility and validation
+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:
+-
+
- They have the same number of parameters. +
- They have the same return type. +
- Each parameter in the stub has the same type as the corresponding parameter in the original function/method. +
- The stub must have the same number of generic parameters as the original function/method.
+However, a generic parameter in the stub is allowed to have a different name than the corresponding parameter in the original function/method.
+For example, the stub
bar<A, B>(x: A, y: B) -> Bis considered to have a type compatible with the functionfoo<S, T>(x: S, y: T) -> T.
+ - The bounds for each type parameter don't need to match; however, all calls to the original function must also satisfy the bounds of the stub. +
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.
Pedagogy
+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.
+Detailed design
+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.
+Rationale and alternatives: user experience
+Stubbing is a de facto necessity for verification tools, and the lack of stubbing has a negative impact on the usability of Kani.
+Benefits
+-
+
- Because stubs are specified by annotating the harness, the user is able to specify stubs for functions they do not have source access to (like library functions). +This contrasts with annotating the function to be replaced (such as with function contracts). +
- The current design provides the user with flexibility, as they can specify different sets of stubs to use for different harnesses. +This is important if users are trying to perform compositional reasoning using stubbing, since in some harnesses a function/method should be fully verified, in in other harnesses its behavior should be mocked. +
- The stub selections are located adjacent to the harness, which makes it easy to understand which replacements are going to happen for each harness. +
Risks
+-
+
- Users can always write stubs that do not correctly correspond to program behavior, and so a successful verification does not actually mean the program is bug-free. +This is similar to other specification bugs. +All the stubbing code will be available, so it is possible to inspect the assumptions it makes. +
Comparison to function contracts
+-
+
- In many cases, stubs are more user-friendly than contracts. +With contracts, it is sometimes necessary to explicitly provide information that is automatically captured in Rust (such as which memory is written). +Furthermore, contract predicates constitute a DSL of their own that needs to be learned; using stubbing, we can stick to using just Rust. +
- Function contracts sometimes come with a mechanism for verifying that a function satisfies its contract (for example, CBMC provides this). +While we do not plan to provide such a feature, it is possible to emulate this by writing proof harnesses comparing the behavior of the original function and the stub. +Furthermore, our approach provides additional flexibility, as it is not always actually desirable for a stub to be an overapproximation of the function (e.g., we might want the stub to exhibit a certain behavior within a particular harness) or to have a consistent behavior across all harnesses. +
- The currently proposed function contract mechanism does not provide a way to specify contracts on external functions. +In principle, it would be possible to extend it to do so. +Doing so would require some additional UX design decisions (e.g., "How do users specify this?"); with stubbing there does not need to be a distinction between local and external functions. +
Alternative #1: Annotate stubbed functions
+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.
Alternative #2: Annotate stubs
+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.
+Alternative #3: Annotate harnesses and stubs
+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:
+-
+
- How do you mock multiple functions with the same stub?
+(Say harness A wants to use
stub1to mockfoo, and harness B wants to usestub1to mockbar.)
+ - How do you combine stub sets defined via modules? Would you use the module hierarchy? +
- If you use modules to define stub sets, are these modules regular modules or not? +In particular, given that modules can contain other constructs than functions, how should we interpret the extra stuff? +
Alternative #4: Specify stubs in a file
+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.
Rationale and alternatives: stubbing mechanism
+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.
Alternative #1: Conditional compilation
+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.
+Alternative #2: Source-to-source transformation
+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.
Alternative #3: AST-to-AST or HIR-to-HIR transformation
+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).
Open questions
+-
+
- Would there ever be the need to stub a particular monomorphization of a function, as opposed to the polymorphic function? +
- How can the user verify that the stub is an abstraction of the original function/method? +Sometimes it might be important that a stub is an overapproximation or underapproximation of the replaced code. +One possibility would be writing proofs about stubs (possibly relating their behavior to that of the code they are replacing). +
Limitations
+-
+
- Our proposed approach will not work with
--concrete-playback(for now).
+ - We are only able to apply abstractions to some dependencies if the user enables the MIR linker. +
Future possibilities
+-
+
-
+
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::randomcan be replaced with a function returningkani::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 tohavoc_localsbut 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
+selfin methods? +It is possible to do so usingstd::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() { ... } +
+
Appendix: an extended example
+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).
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0004-loop-contract-synthesis.html b/rfc/rfcs/0004-loop-contract-synthesis.html
new file mode 100644
index 000000000000..a22cd74a2c8e
--- /dev/null
+++ b/rfc/rfcs/0004-loop-contract-synthesis.html
@@ -0,0 +1,377 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: Cover statement (
cover-statement)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/696 +
- RFC PR: https://github.com/model-checking/kani/pull/1906 +
- Status: Stable +
- Version: 2 +
+
Summary
+A new Kani API that allows users to check that a certain condition can occur at a specific location in the code.
+User Impact
+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");
+User Experience
+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
+Impact on Overall Verification Status
+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.
Inclusion in the Verification Summary
+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.
+Interaction with Other Checks
+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.
Detailed Design
+The implementation will touch the following components:
+-
+
- Kani library: The
covermacro will be added there along with acoverfunction with arustc_diagnostic_item
+ kani-compiler: Thecoverfunction 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 thecoverstatement 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: +-
+
- The first (reachability) assertion is proven: report as
FAILURE (UNREACHABLE)
+ - The first assertion fails, and the second one is proven: report as
FAILUREto indicate that the condition is unsatisfiable
+ - The first assertion fails, and the second one fails: report as
SUCCESSto indicate that the condition is satisfiable
+
+- The first (reachability) assertion is proven: report as
Rationale and alternatives
+-
+
-
+
What are the pros and cons of this design? +CBMC has its own cover API (
+__CPROVER_cover), for whichSUCCESSis reported if an execution is found, andFAILUREis 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.
+
Open questions
+-
+
- ~Should we allow format arguments in the macro, e.g.
kani::cover!(x > y, "{} can be greater than {}", x, y)? +Users may expect this to be supported since the macro looks similar to theassertmacro, but Kani doesn't include the formatted string in the message description, since it's not available at compile time.~ +-
+
- For now, this macro will not accept format arguments, since this +is not well handled by Kani. +This is an extesion to this API that can be easily added later on if Kani +ever supports runtime formatting. +
+
Other Considerations
+We need to make sure the concrete playback feature can be used with cover statements that were found to be coverable.
Future possibilities
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0005-should-panic-attr.html b/rfc/rfcs/0005-should-panic-attr.html
new file mode 100644
index 000000000000..81a4bebd5c80
--- /dev/null
+++ b/rfc/rfcs/0005-should-panic-attr.html
@@ -0,0 +1,408 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: Loop-contract synthesis (
loop-contract-synthesis)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2214 +
- RFC PR: https://github.com/model-checking/kani/pull/2215 +
- Status: Under Review +
- Version: 0 +
- Proof-of-concept: https://github.com/qinheping/kani/tree/kani-synthesizer +
+
Summary
+A new option that allows users to verify programs without unwinding loops by synthesizing loop contracts for those loops.
+User Impact
+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:
-
+
- the search space is not complete, so it may fail to find a working candidate. The current search space consists of only conjunctions of linear inequalities built from the variables in the loop, which is not expressive enough to capture all loop invariants.
+For example, the loop invariant
a[i] == 0contains 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.
+ - the synthesizer suffers from the same limitation as the loop contract verification in CBMC. For example, it does not support unbounded quantifiers, or dynamic allocations in the loop body. +
User Experience
+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.
Limit Resource Used by Synthesizer for Termination
+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.
Output of Kani when the Synthesizer is Enabled
+When the flag --synthesize-loop-contracts is provided, Kani will report different result for different cases
-
+
- When there exists some loop invariant in the candidate space with which all assertions can be proved, Kani will synthesize the loop contracts, verify the program with the synthesized loop contracts, and report verification SUCCESS; +
- When no working candidate has been found in the search space within the specified limits, Kani will report the verification result with the best-effort-synthesized loop contracts.
+Note that as loop contracts are over-approximations of the loop, the violated assertions in this case may be spurious.
+So we will report the violated assertions as
UNDETERMINEDinstead ofFAILED.
+
A question about how do we print the synthesized loop contracts when users request is discussed in Open question.
+Detailed Design
+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 resource limit of the synthesis; +
- the solver options to specify what SAT solver we use to verify invariant candidates. +
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.
-
+
- If all checks in the program pass,
goto-synthesizerreturns it as a solution.
+ - If the inductive checks pass but some of the other checks fail, the candidate invariant is inductive. +We keep it as an inductive invariant clause. +
- If the inductive checks fail, we discard the candidate.
+When the resource limit is reached,
goto-synthesizerreturns 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.
Rationale and alternatives
+-
+
- Different candidate space.
+The candidate grammar introduced above now only contains a restricted set of operators, which works well for array-manipulating programs with only pointer-checks instrumented by
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.
+
Open questions
+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.
+-
+
- We need to have a consistent way to identify loops. +
- We need to dump loop invariants in
rustinstead ofc.
+ - There are many auxiliary variables we added in Kani-compiled GOTO, such as
var_9,var_10,var_11, andvar_12in the above JSON file. +We need to translate them back to the original variables they represent.
+
Future possibilities
+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.
+1
+
+
+ We say an integer variable is unbounded if there is no other bound on its value besides the width of its bit-vector representation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0006-unstable-api.html b/rfc/rfcs/0006-unstable-api.html
new file mode 100644
index 000000000000..6ca3d8a5fa7b
--- /dev/null
+++ b/rfc/rfcs/0006-unstable-api.html
@@ -0,0 +1,271 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Alternative #3: The
+
+
+
+
+ -
+
- Feature Name: The
kani::should_panicattribute (should-panic-attr)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/600 +
- RFC PR: https://github.com/model-checking/kani/pull/2272 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: +
-
+
- Version 0: https://github.com/model-checking/kani/pull/2315 +
- Version 1: https://github.com/model-checking/kani/pull/2532 +
+
Summary
+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.
User Impact
+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.
+User Experience
+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.
+Single Harness
+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:
+-
+
- (Expectation) Was Kani expecting the harness to panic? +
- (Outcome): What's the actual result that Kani produced after the analysis? +This will avoid a potential scenario where the user doesn't know for sure if the attribute has had an effect when verifying the harness. +
Therefore, the representation must make clear both the expectation and the outcome. +Below, we show how we'll represent this result.
+Recommended Representation: As a Global Condition
+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 hadprop.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.
Multiple Harnesses
+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.
+Multiple panics
+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.
Availability
+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:
-
+
- It'd make the design and implementation unnecessarily complex. +
- It'd only be useful when combined with
--harnessto filter negative harnesses.
+ - We could have trouble extending its functionality (see Future possibilities for more details). +
Pedagogy
+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.
+Detailed Design
+At a high level, we expect modifications in the following components:
+-
+
kani-compiler: Changes required to (1) process the new attribute, and (2) extendHarnessMetadatawith ashould_panic: boolfield.
+kani-driver: Changes required to (1) edit information about harnesses printed bykani-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).
+Rationale and alternatives
+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.
+Alternative #1: Generic failures
+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.
+Alternative #2: Name
+We have considered two alternatives for the "expectation" part of the attribute's name: should and expect.
+We avoid expect altogether for two reasons:
-
+
- We may consider adding the
expectedargument to#[kani::should_panic].
+ - We may consider a more granular approach to indicate expectations regarding individual checks and cover statements in the future. One possible name for the attribute is
#[kani::expect].
+ - We heavily use this word for testing in Kani: there is an
expectedmode, which works with*.expectedfiles. Other modes also use such files.
+
Alternative #3: The expected argument
+We 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].
Alternative #4: Granularity
+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:
+-
+
- What if users don't want to only check for failures (e.g., reachability)? +
- In the previous case, would they expect the overall verification to fail or not? +
- How do we want these expectations to be declared? +
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.
+Alternative #5: Kani API
+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.
+Open questions
+Once the feature is available, it'd be good to gather user feedback to answer these questions:
+-
+
- Do we need a mechanism to express more granular expectations? +
- If we need the mechanism in (2), do we really want to collapse them into one feature? +
Resolved questions
+-
+
- What is the best representation to use for this feature? A representation that changes the overall result seems to be preferred, according to feedback we received during a discussion. +
- Do we want to extend
#[kani::should_panic]with anexpectedfield? Yes, but not in this version.
+ - Do we want to allow multiple panic-related failures with
#[kani::should_panic]? Yes (this is now discussed in User Experience).
+
Future possibilities
+-
+
- The attribute could be an argument to
kani::proof(#[kani::proof(should_panic)]reads very well).
+ - Add an
expectedargument to#[kani::should_panic], and replay the harness with concrete playback to get the actual panic string.
+
2
+
+Double negation may not be the best representation, but it's at least accurate with respect to the original result.
+1
+
+
+ This summary is printed in both the default and terse outputs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0007-global-conditions.html b/rfc/rfcs/0007-global-conditions.html
new file mode 100644
index 000000000000..1c48ce022b43
--- /dev/null
+++ b/rfc/rfcs/0007-global-conditions.html
@@ -0,0 +1,266 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: Unstable APIs (
unstable-api)
+ - RFC Tracking Issue: https://github.com/model-checking/kani/issues/2279 +
- RFC PR: https://github.com/model-checking/kani/pull/2281 +
- Status: Unstable +
- Version: 0 +
+
Summary
+Provide a standard option for users to enable experimental APIs and features in Kani, +and ensure that those APIs are off by default.
+User Impact
+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.
+User Experience
+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.
+Detailed Design
+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.
+API Stabilization
+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.
API Removal
+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.
Rational and Alternatives
+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.
+Open questions
+-
+
- Should we also add a
stableattribute that documents when an API was stabilized?
+
Future possibilities
+-
+
- Delay the error due to the usage of a unstable API, and only fail at runtime if the API is reachable. +
- Allow users to enable unstable features on a per-harness basis. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0008-line-coverage.html b/rfc/rfcs/0008-line-coverage.html
new file mode 100644
index 000000000000..9cf2d5cc5cda
--- /dev/null
+++ b/rfc/rfcs/0008-line-coverage.html
@@ -0,0 +1,325 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: Global Conditions (
global-conditions)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2525 +
- RFC PR: https://github.com/model-checking/kani/pull/2516 +
- Status: Unstable +
- Version: 0 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/2532 +
+
Summary
+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.
+User Impact
+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.
+User Experience
+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.
Detailed Design
+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.
+Rationale and alternatives
+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.
+Alternative: Global conditions as regular checks
+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.
+Open questions
+No open questions.
+Future possibilities
+A redesign of Kani's output is likely to change the style/architecture to report global conditions.
+3
+
+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.
+2
+
+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.
1
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0009-function-contracts.html b/rfc/rfcs/0009-function-contracts.html
new file mode 100644
index 000000000000..7a723a183a47
--- /dev/null
+++ b/rfc/rfcs/0009-function-contracts.html
@@ -0,0 +1,1004 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Coverage through
+
+
+
+
+ -
+
- Feature Name: Line coverage (
line-coverage)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2610 +
- RFC PR: https://github.com/model-checking/kani/pull/2609 +
- Status: Cancelled +
- Version: 0 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/2609 (Kani) + https://github.com/model-checking/kani-vscode-extension/pull/122 (Kani VS Code Extension) +
+
Summary
+Add verification-based line coverage reports to Kani.
+User Impact
+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:
+-
+
- Learning: New users are more familiar with coverage reports than property-based results. +
- Development: Some users prefer coverage results to property-based results since they are easier to interpret. +
- CI Integration: Users may want to enforce a minimum percentage of code coverage for new contributions. +
- Debugging: Users may find coverage reports particularly helpful when inputs are over-constrained (missing some corner cases). +
- Evaluation: Users can easily evaluate where and when more verification work is needed (some projects aim for 100% coverage). +
Moreover, adding this option directly to Kani, instead of relying on another tools, is likely to:
+-
+
- Increase the speed of development +
- Improve testing for coverage features +
Which translates into faster and more reliable coverage options for users.
+User Experience
+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.
+High-level changes
+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.
+Experimental output format for coverage results
+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.
+Detailed Design
+Architecture
+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
+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:
-
+
- Hidden from verification results. +
- Postprocessed to produce coverage results. +
In the following, we describe the injection and postprocessing procedures to generate coverage results.
+Injection of Coverage Checks
+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.
+Postprocessing Coverage Checks
+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
+-
+
- if all checks are
SATISFIED: returnFULL
+ - if all checks are
UNSATISFIED: returnNONE
+ - otherwise: return
PARTIAL
+
We won't report coverage status for lines which don't include a coverage check.
+Rationale and alternatives
+Benefits from a native coverage solution
+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:
-
+
- The instrumentation performed on the program. Eventually, this would allow us to report more precise coverage information (maybe similar to Rust's instrument-based code coverage). +
- The format of the coverage report to be generated. Similarly, this would allow us to generate coverage data in different formats (see #1706 for GCOV, or #1777 for LCOV). While technically this is also doable from
cbmc-viewer's output, development is likely to be faster this way.
+
Coverage through cbmc-viewer
+As an alternative, we could fix and use cbmc-viewer to report line coverage.
Most of the issues with cbmc-viewer are generally due to:
-
+
- Missing locations due to non-propagation of locations in either Kani or CBMC. +
- Differences in the definition of a basic block in CBMC and Rust's MIR. +
- Scarce documentation for coverage-related options (i.e.,
--cover <option>) in CBMC.
+ - Limited testing with Rust code in
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.
Other output formats
+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
+Open questions:
+-
+
- Do we want to report line coverage as
COVERED/UNCOVEREDorFULL/PARTIAL/NONE?
+ - Should we report coverage results and verification results or not? Doing both is likely to result in worse performance. We have to perform an experimental evaluation with hard benchmarks. +
- Should we instrument dependencies or not? Doing so is likely to result in worse performance. We have to perform an experimental evaluation. +
- What should be the final UX for this feature? For instance, we could print a coverage summary and generate a report file per harness. But it's not clear if individual results are relevant to users, so another possibility is to automatically combine results. +
- What's the most appropriate and well-established output format we can emit? +
- Determine if there are cases in which coverage information is confusing for users (due to, e.g., constant propagation or other compiler optimizations). How can work around such cases? +
- Do we want to report coverage information for dependencies? For CI, most users may be only interested in their code. Most coverage frameworks have an aggregation tool with an option to exclude dependencies from coverage metrics. +
Feedback to gather before stabilization:
+-
+
- Compare the injection-based approach in this RFC with Rust's instrument-based code coverage? +
Future possibilities
+We expect many incremental improvements in the coverage area:
+-
+
- Consuming the output produced in coverage results from the Kani VS Code extension. +
- Building a tool that produces coverage results by combining the coverage results of more than one harness. +
- Including span information in coverage checks and building region-based coverage reports. +
- Adding new user-requested coverage formats such as GCOV #1706 or LCOV #1777. +
1
+
+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.
+2
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0010-quantifiers.html b/rfc/rfcs/0010-quantifiers.html
new file mode 100644
index 000000000000..975228e3ee07
--- /dev/null
+++ b/rfc/rfcs/0010-quantifiers.html
@@ -0,0 +1,362 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Code generation in
+
+
+
+
+
+ -
+
- Feature Name: Function Contracts +
- Feature Request Issue: #2652 and Milestone +
- RFC PR: #2620 +
- Status: Unstable +
- Version: 1 +
- Proof-of-concept: features/contracts +
- Feature Gate:
-Zfunction-contracts, enforced by compile time error1
+
+
Summary
+Function 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.
+ +User Impact
+ +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.
+-
+
- Scalability: A function contract is an abstraction (sound +overapproximation) of a function's behavior. After verifying the contract +against its implementation we can subsequently use the (cheaper) abstraction +instead of the concrete implementation when analyzing its callers. +Verification is thus modularized and even cacheable. +
- Unbounded Verification: Contracts enable inductive reasoning for recursive +functions where the first call is checked against the contract and recursive +calls are stubbed out using the abstraction. +
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.
+User Experience
+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 andensures(postconditions) which +approximates function outputs in terms of function inputs.
+#[kani::requires(divisor != 0)] +#[kani::ensures(|result : &u32| *result <= dividend)] +fn my_div(dividend: u32, divisor: u32) -> u32 { + dividend / divisor +} +
+requireshere indicates this function expects itsdivisorinput to never +be 0, or it will not execute correctly (for instance panic or cause undefined +behavior).
+ensuresputs a bound on the output, relative to thedividendinput.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 passed into the ensures closure statement by reference. 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
+requiresandensuresclauses 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
+staticvariables.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 referencesTARGET, 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_divKani 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) askani::assumebefore the call +tomy_div, limiting inputs to those the function is actually defined for. +It inserts postconditions (ensures) askani::assertchecks after the +call tomy_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_kani_internal = my_div(dividend, divisor); + kani::assert((|result : &u32| *result <= dividend)(result_kani_internal)); // 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_contractharness for each abstracted function, otherwise an error is +thrown. In addition, by default, it requires allproof_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_divcontract 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_divlooks 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.
+Write Sets and Havocking
+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.
History Expressions
+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(|result : &Option<T>| 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(|result : &Option<T>| { let x = self.is_empty(); old(x) } || result.is_some())]
+Valid ✅: #[kani::ensures(|result : &Option<T>| 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.
Workflow and Attribute Constraints Overview
+-
+
- By default
kaniorcargo kanifirst verifies all contract harnesses +(proof_for_contract) reachable from the file or in the local workspace +respectively.
+ - Each contract (from the local
+crate7) that is used in a
+
stub_verifiedis required to have at least one associated contract harness. +Kani reports any missing contract harnesses as errors.
+ - Kani verifies all regular harnesses if their
stub_verifiedcontracts +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,modifiesandfrees+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 whereTARGETmust +"have a contract". One or moreproof_for_contractharnesses may have the +sameTARGET.A
+proof_for_contractharness may use any harness attributes, including +stubandstub_verified, though theTARGETmay not appear in either.
+ -
+
Kani checks that
+TARGETis reachable from theproof_for_contractharness, +but it does not warn if abstracted functions useTARGET8.
+ -
+
A
+proof_for_contractfunction may not have thekani::proofattribute (it +is already implied byproof_for_contract).
+ -
+
A harness may have multiple
+stub_verified(TARGET)attributes. EachTARGET+must "have a contract". NoTARGETmay appear twice. Each localTARGETis +expected to have at least one associatedproof_for_contractharness which +passes verification, see also the discussion on when to check contracts in +open questions.
+ -
+
Harnesses may combine
+stub(S_TARGET, ..)andstub_verified(V_TARGET)+annotations, though no target may occur inS_TARGETs andV_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.
+
Detailed Design
+ +Kani implements the functionality of function contracts in three places.
+-
+
- Code generation in the
requiresandensuresmacros (kani_macros).
+ - GOTO level contracts using CBMC's contract language generated in
+
kani-compilerformodifiesclauses.
+ - Dependencies and ordering among harnesses in
kani-driverto enforce +contract checking before replacement. Also plumbing between compiler and +driver for enforcement of assigns clauses.
+
Code generation in kani_macros
+The 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(|result : &Option<T>| 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_kani_internal = Self::pop(self);
+ kani::assert((|result : &Option<T>| self.is_empty() || self.len() == old_1 - 1)(result_kani_internal))
+ }
+}
+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(|result : &(&mut [T], &mut [T])| 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:
-
+
- Postconditions are not allowed perform mutation and +
- Post conditions are of type
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.
Recursion
+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.
+Changes to Other Components
+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.
Rationale and alternatives
+ + +We developed the old contract for history expressions via understanding it as a modality originating from Moggi 1991.
+The old monad links the "language of the past" to the "language of the present".
+Implementing the full generality of the monad is rather difficult, so we focus on a particular usage of the monad.
We have an external syntax representation which is what the user inputs. We then parse this and logically manipulate it as a monad, prefixing all the bind operations. We then output the final compiled macro output as Rust code.
In particular, if we have an ensures statement like
+#[kani::ensures(old(*ptr)+1==*ptr)]
+Then we comprehend this as syntax for the statement (not within Rust)
+bind (*ptr : O(u32)) (|remember : u32| remember + 1 == *ptr)
+Here, the O(u32) is taking the type of the past u32 and converting it into a type in the present O(u32) while the bind operation lets you use the value of the past u32 to express a type in the present bool.
This then gets compiled to (within Rust)
+let remember = *ptr;
+let result = ...;
+kani::assert(remember + 1 == *ptr)
+This means that the underlying principle of the monad is there, but external syntax appears to be less like a monad because otherwise it would be too difficult to implement, and the user most likely only cares about this particular construction of prefixing all the bind operations.
This construction requires that old expressions are closed with resprect to the input parameters. This is due to the lifting into the prefixed bind operations.
A major drawback is that eta expansion fails. If we eta expand a function f, it becomes |x|f(x). Note that eta expansions guarantee that the original f and the |x|f(x) are equivalent which makes a lot of sense since you’re just calling the same function. However, we have that old(y) is not equivalent to (|x|old(x))(y). y is a closed expression, so the first statement works. x is a bound variable, so it is an open expression, so compilation will fail.
The reason for this restriction is that the user will most likely only want to use this particular prefixed bind structure for their code, so exposing the concept of monads to the user level would only confuse the user. It is also simpler from an implementation perspective to limit the monad to this particular usage.
As for nested old, such as old(old(*ptr)+*ptr), it is reasonable to interpret this as syntax representing
bind (bind(*ptr)(|remember_1| remember_1 + *ptr)) (|remember_0| ...)
+which compiles to
+let remember_1 = *ptr;
+let remember_0 = remember_1 + *ptr;
+let result = ...;
+...
+so the restriction is just a matter of there not being implementation support for this kind of statement rather than the theory itself. It is not particularly useful to implement this because we claim that there should be no effectful computation within the contracts, so you can substitute the remember_1 into the second line without worrying about the effects. Hence, we opt for simply restricting this behavior instead of implementing it. (Note: it can be implemented by changing denier.visit_expr_mut(e); into self.visit_expr_mut(e);)
Kani-side implementation vs CBMC
+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.
Expanding all contract macros at the same time
+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.
Generating nested functions instead of siblings
+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.
Explicit command line checking/substitution vs attributes:
+Instead of
+adding a new special proof_for_contact attributes we could have instead done:
-
+
- Check contracts on the command line like CBMC does. This makes contract
+checking a separate
kaniinvocation with something like a +--check-contractflag 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.
+ - Check contracts with a
#[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.
+
Polymorphism during contract checking
+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.
User supplied harnesses
+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).
Open questions
+ +-
+
-
+
Returning
+kani::any()in a replacement isn't great, because it wouldn't work +for references as they can't have anArbitraryimplementation. Plus the +soundness then relies on a correct implementation ofArbitrary. 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
+@resultor +kani::result(), though with the latter I worry that people may get confused +because it is syntactic and not subject to usualuserenaming and import +semantics. Alternatively we can let the user pick the name with an additional +argument toensures, 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
+kaniand +cargo kanicheck 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:
+-
+
- By default (
kani/cargo kani) all local contracts are checked, +harnesses are only checked if the contracts they depend on succeeded their check.
+ - With harness selection (
--harness) only those contracts which the +selected harnesses depend on are checked.
+ - For high assurance passing a
--paranoidflag also checks contracts for +dependencies (other crates) when they are used in abstractions.
+ - Per harness the users can disable the checking for specific contracts
+via attribute, like
#[stub_verified(TARGET, trusted)]or +#[stub_unverified(TARGET)]. This also plays nicely withcfg_attr.
+ - On the command line users can similarly disable contract checks by
+passing (multiple times)
--trusted TARGETto skip checking those +contracts.
+ - The bold (or naïve) user can skip all contracts with
--all-trusted.
+ - For the lawyer that is only interested in checking contracts and nothing
+else a
--litigateflag 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.
+
+ - By default (
-
+
Can
+oldaccidentally break scope? Theoldfunction cannot reference local +variables. For instance#[ensures({let x = ...; old(x)})]cannot work as an +AST rewrite because the expression inoldis 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 thatxis unbound, however it is possible that +if there is also a function argumentx, 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 namedxwould +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 valuexin 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.
+
+ -
+
+modifiesclauses 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 themodifiesclause. Howevermodifiesclauses are implemented +asassignsclauses in CBMC which does not have a notion of function header +patterns. Thus it is necessary to project anymodifiesranges deeper by the +fields used in the matched pattern.
+
Future possibilities
+ +-
+
-
+
Quantifiers: Quantifiers are like logic-level loops and a powerful +reasoning helper. CBMC has support for both
+existsandforall, but the +code generation is difficult. The most ergonomic and easy way to implement +quantifiers on the Rust side is as higher-order functions takingFn(T) -> bool, whereTis 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 theFnclosure 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
+VecorRefCell) 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 theimplcontract. 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 parametersPthrough the +traits (T) they are constrained over. We can requireTto carry contracts +on each methodT::m(). During checking we can use a synthetic type that +abstractsT::m()with its contract. This way we checkf()againstTs +contract. Then we later abstractf()we can ensure any instantiations ofP+have passed verification of the contract ofT::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.
+
+
1
+
+Enforced gates means all uses of constructs (functions, annotations, +macros) in this RFC are an error.
+2
+
+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.
+3
+
+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.
4
+
+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.
5
+
+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)]
6
+
+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.
7
+
+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.
8
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0011-source-coverage.html b/rfc/rfcs/0011-source-coverage.html
new file mode 100644
index 000000000000..95a5f879b6d9
--- /dev/null
+++ b/rfc/rfcs/0011-source-coverage.html
@@ -0,0 +1,748 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+
+ -
+
- Feature Name: Quantifiers +
- Feature Request Issue: #2546 and #836 +
- RFC PR: # +
- Status: Unstable +
- Version: 1.0 +
+
Summary
+Quantifiers are logical operators that allow users to express that a property or condition applies to some or all objects within a given domain.
+User Impact
+There are two primary quantifiers: the existential quantifier (∃) and the universal quantifier (∀).
+-
+
-
+
The existential quantifier (∃): represents the statement "there exists." We use to express that there is at least one object in the domain that satisfies a given condition. For example, "∃x P(x)" means "there exists a value x such that P(x) is true."
+
+ -
+
The universal quantifier (∀): represents the statement "for all" or "for every." We use it to express that a given condition is true for every object in the domain. For example, "∀x P(x)" means "for every value x, P(x) is true."
+
+
Rather than exhaustively listing all elements in a domain, quantifiers enable users to make statements about the entire domain at once. This compact representation is crucial when dealing with large or unbounded inputs. Quantifiers also facilitate abstraction and generalization of properties. Instead of specifying properties for specific instances, quantified properties can capture general patterns and behaviors that hold across different objects in a domain. Additionally, by replacing loops in the specification with quantifiers, Kani can encode the properties more efficiently within the specified bounds, making the verification process more manageable and computationally feasible.
+This new feature doesn't introduce any breaking changes to users. It will only allow them to write properites using the existential (∃) and universal (∀) quantifiers.
+User Experience
+We propose a syntax inspired by "Pattern Types". The syntax of existential (i.e., kani::exists) and universal (i.e., kani::forall) quantifiers are:
kani::exists(|<var>: <type> [is <range-expr>] | <boolean-expression>)
+kani::forall(|<var>: <type> [is <range-expr>] | <boolean-expression>)
+If <range-expr> is not provided, we assume <var> can range over all possible values of the given <type> (i.e., syntactic sugar for full range |<var>: <type> as .. |). CBMC's SAT backend only supports bounded quantification under constant lower and upper bounds (for more details, see the documentation for quantifiers in CBMC). The SMT backend, on the other hand, supports arbitrary Boolean expressions. In any case, <boolean-expression> should not have side effects, as the purpose of quantifiers is to assert a condition over a domain of objects without altering the state.
Consider the following example adapted from the documentation for the from_raw_parts function:
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let v = vec![kani::any::<usize>(); 100];
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ }
+}
+Given the v vector has non-deterministic values, there are potential arithmetic overflows that might happen in the for loop. So we need to constrain all values of the array. We may also want to check all values of rebuilt after the operation. Without quantifiers, we might be tempted to use loops as follows:
use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 100];
+ let v = original_v.clone();
+ for i in 0..v.len() {
+ kani::assume(v[i] < 5);
+ }
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ for i in 0..len {
+ assert_eq!(rebuilt[i], original_v[i]+1);
+ }
+ }
+}
+This, however, might unnecessary increase the complexity of the verication process. We can achieve the same effect using quantifiers as shown below.
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 3];
+ let v = original_v.clone();
+ kani::assume(kani::forall(|i: usize is ..v.len() | v[i] < 5));
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ assert!(kani::forall(|i: usize is ..len | rebuilt[i] == original_v[i]+1));
+ }
+}
+The same principle applies if we want to use the existential quantifier.
+use std::ptr;
+use std::mem;
+
+#[kani::proof]
+fn main() {
+ let original_v = vec![kani::any::<usize>(); 3];
+ let v = original_v.clone();
+ kani::assume(kani::forall(|i: usize is ..v.len() | v[i] < 5));
+
+ // Prevent running `v`'s destructor so we are in complete control
+ // of the allocation.
+ let mut v = mem::ManuallyDrop::new(v);
+
+ // Pull out the various important pieces of information about `v`
+ let p = v.as_mut_ptr();
+ let len = v.len();
+ let cap = v.capacity();
+
+ unsafe {
+ // Overwrite memory
+ for i in 0..len {
+ *p.add(i) += 1;
+ if i == 1 {
+ *p.add(i) = 0;
+ }
+ }
+
+ // Put everything back together into a Vec
+ let rebuilt = Vec::from_raw_parts(p, len, cap);
+ assert!(kani::exists(|i: usize is ..len | rebuilt[i] == 0));
+ }
+}
+The usage of quantifiers should be valid in any part of the Rust code analysed by Kani.
+Detailed Design
+ +Kani should have the same support that CBMC has for quantifiers. For more details, see Quantifiers.
+Open questions
+ +-
+
- Function Contracts RFC - CBMC has support for both
existsandforall, but the +code generation is difficult. The most ergonomic and easy way to implement +quantifiers on the Rust side is as higher-order functions takingFn(T) -> bool, whereTis 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 theFnclosure to a compliant expression. +-
+
- Which kind of expressions should be accepted as a "compliant expression"? +
+
Future possibilities
+ +-
+
- CBMC has an SMT backend which allows the use of quantifiers with arbitrary Boolean expressions. Kani must include an option for users to experiment with this backend. +
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0012-loop-contracts.html b/rfc/rfcs/0012-loop-contracts.html
new file mode 100644
index 000000000000..e342c0f2a4d4
--- /dev/null
+++ b/rfc/rfcs/0012-loop-contracts.html
@@ -0,0 +1,388 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The
+The
+
+
+
+
+ -
+
- Feature Name: Source-based code coverage (
source-coverage)
+ - Feature Request Issue: https://github.com/model-checking/kani/issues/2640 +
- RFC PR: https://github.com/model-checking/kani/pull/3143 +
- Status: Under Review +
- Version: 1 +
- Proof-of-concept: https://github.com/model-checking/kani/pull/3119 (Kani) + https://github.com/model-checking/kani/pull/3121 (
kani-cov)
+
+
Summary
+A source-based code coverage feature for Kani built on top of Rust's coverage instrumentation.
+User Impact
+In our first attempt to add a coverage feature fully managed by Kani, we introduced and made available a line coverage option +(see RFC: Line coverage for more details). +This option has since then allowed us to gather more data around the expectations for a coverage feature in Kani.
+For example, the line coverage output we produced was not easy to interpret +without knowing some implementation details. +Aside from that, the feature requested in +#2795 alludes to the need +of providing coverage-specific tooling in Kani. +Nevertheless, as captured in +#2640, source-based +coverage results provide the clearest and most precise coverage information.
+In this RFC, we propose an integration with Rust's source-based code coverage
+instrumentation.
+This integration would allow us to report source-based code coverage results from Kani.
+Also, we propose adding a new user-facing, coverage-focused tool called kani-cov.
+The tool would allow users to process coverage results generated by Kani and produce
+coverage artifacts such as summaries and reports according to their preferences.
+In the next section, we will explain in more detail how we
+expect kani-cov to assist with coverage-related tasks.
With these changes, we expect our coverage options to become more flexible, +precise and efficient. These options are expected to replace the previous +options available through the line coverage feature. +In the last section of this RFC, we will also discuss +the requirements for a potential integration of this coverage feature with the +LLVM toolchain.
+User Experience
+The proposed experience is partially inspired by that of the most popular +coverage frameworks. +First, let us delve into the LLVM coverage workflow, followed by an explanation +of our proposal.
+The LLVM code coverage workflow
+The LLVM project is home to one of the most popular code coverage frameworks. +The workflow associated to the LLVM framework is described in the documentation for +source-based code coverage1, +but we briefly describe it here to better relate it with our proposal.
+In short, the LLVM code coverage workflow follows three steps:
+-
+
- Compiling with coverage enabled. This causes the compiler to generate an instrumented program. +
- Running the instrumented program. This generates binary-encoded
.profrawfiles.
+ - Using tools to aggregate and export coverage information into other formats. +
When working in a cargo project, step 1 can be done through this command:
RUSTFLAGS='-Cinstrument-coverage' cargo build
+The same flag must to be used for step 2:
+RUSTFLAGS='-Cinstrument-coverage' cargo run
+This should populate the directory with at least one .profraw file.
+Each .profraw file corresponds to a specific source code file in your project.
At this point, we will have produced the artifacts that we generally require for +the LLVM tools:
+-
+
- The instrumented binary which, in addition to the instrumented program, +contains additional information (e.g., the coverage mappings) required to +interpret the profiling results. +
- The
.profrawfiles which essentially includes the profiling results +(e.g., counter values) for each function of the corresponding source code file.
+
For step 3, the commands will depend on what kind of results we want.
+Most likely we will have to merge the .profraw files and produce a .profdata
+file as follows:
llvm-profdata merge -sparse *.profraw -o output.profdata
+The resulting .profdata file will contain the aggregated coverage results from
+the .profraw files passed to the merge command.
Then, we can use a command such as
+llvm-cov show target/debug/binary —instr-profile=output.profdata -show-line-counts-or-regions
+to visualize the code coverage through the terminal as in the image:
+or the command
+llvm-cov report target/debug/binary --instr-profile=output.profdata --show-region-summary
+to produce coverage summaries like this:
+Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover Branches Missed Branches Cover
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+/long/long/path/to/my/project/binary/src/main.rs 9 3 66.67% 3 1 66.67% 14 4 71.43% 0 0 -
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+TOTAL 9 3 66.67% 3 1 66.67% 14 4 71.43% 0 0 -
+1
+
+The LLVM project refers to their own coverage feature as +source-based code coverage. It is not rare to see the term region +coverage being used instead to refer to the same thing. That is because +LLVM's source-based code coverage feature can report coverage for code +regions, but other coverage frameworks do not support the concept of code +regions.
+The Kani coverage workflow
+The two main components of the Kani coverage workflow that we propose are the +following:
+-
+
- The existing
--coverageflag that drives the coverage workflow in Kani, +emits raw coverage data (as in the.profrawfiles), and produces basic +coverage results by default.
+ - A new subcommand
covthat allows users to further process raw coverage +information emitted by Kani to produce customized coverage results (i.e., +different to the ones produced by default with the--coverageoption). +Thecovsubcommand is an alias for thekani-covtool.
+
In contrast to the LLVM workflow, where human-readable coverage results can
+be produced only after a sequence of LLVM tool commands, we provide some
+coverage results by default.
+This aligns better with our UX philosophy, and removes the need for a wrapper
+around our coverage features like
+cargo-llvm-cov.
+Alternatively, the cov subcommand offers the ability of producing more
+specific coverage results if needed.
+We anticipate the cov subcommand being particularly useful in less standard
+project setups, giving the users the flexibility required to produce coverage
+results tailored to their specific needs.
In the following, we describe each one of these components in more detail.
+The --coverage option
+The default coverage workflow will be kicked off through the unstable
+--coverage option:
cargo kani --coverage -Zsource-coverage
+The main difference with respect to the regular verification workflow is that, +at the end of the verification-based coverage run, Kani will generate two coverage +results:
+-
+
- A coverage summary corresponding to the coverage achieved by the harnesses +included in the verification run. This summary will be printed after the +verification output. +
- A coverage report corresponding to the coverage achieved by the harnesses +included in the verification run. The report will be placed in the same target +directory where the raw coverage files are put. The path to the report will +also be printed after the verification output. +
Therefore, a typical --coverage run could look like this:
VERIFICATION:- SUCCESSFUL
+
+Coverage Results:
+
+| Filename | Regions | Missed Regions | Cover | Functions | Missed Functions | Cover |
+| -------- | ------- | -------------- | ----- | --------- | ---------------- | ----- |
+| main.rs | 9 | 3 | 66.67 | 3 | 1 | 33.33 |
+| file.rs | 11 | 5 | 45.45 | 2 | 1 | 50.00 |
+
+Coverage report available in target/kani/x86_64-unknown-linux-gnu/cov/kani_2024-04-26_15-30-00/report/index.html
+The cov subcommand
+The cov subcommand will be used to process raw coverage information generated
+by Kani and produce coverage outputs as indicated by the user.
+Hence, the cov subcommand corresponds to the set of LLVM tools
+(llvm-profdata, llvm-cov, etc.) that are used to produce coverage outputs
+through the LLVM coverage workflow.
In contrast to LLVM, we will have a single subcommand for all Kani
+coverage-related needs. The cov subcommand will just call the kani-cov tool,
+which is expected to be shipped along the rest of Kani binaries.
We suggest that the subcommand initially offers two options:
+-
+
- An option to merge the coverage results from one or more files and coverage +mappings2 into a single file. +
- An option to produce coverage outputs from coverage results, including summaries +or coverage reports in human-readable formats (e.g., HTML). +
Let's assume that we have run cargo kani --coverage -Zsource-coverage and
+generated coverage files in the my-coverage folder. Then, we would use cargo kani cov as follows to combine the coverage results3 for all
+harnesses:
cargo kani cov --merge my-coverage/*.kaniraw -o my-coverage.kanicov
+Let's say the user is first interested in reading a coverage summary through the
+terminal.
+They can use the --summary option for that:
cargo kani cov --summary my-coverage/default.kanimap -instr-profile=my-coverage.kanicov
+The command could print a coverage summary like:
+| Filename | Regions | Missed Regions | Cover | Functions | ...
+| -------- | ------- | -------------- | ----- | --------- | ...
+| main.rs | 9 | 3 | 66.67 | 3 | ...
+[...]
+Now, let's say the user wants to produce an HTML report of the coverage results.
+They will have to use the --report option for that:
cargo kani cov --report my-coverage/default.kanimap -format=html -instr-profile=my-coverage.kanicov -o coverage-report
+This time, the command will generate a coverage-report folder including a
+browsable HTML webpage that highlights the regions covered in the source
+according to the coverage results in my-coverage.kanicov.
4
+
+The llvm-cov tool includes the option
+gcov to
+export into GCC's coverage format Gcov,
+and the option
+export
+to export into the LCOV format. These may be good options to consider for
+kani-cov in the future but we should focus on basic formats for now.
3
+
+Options to exclude certain coverage results (e.g, from the +standard library) will likely be part of this option.
+2
+
+Coverage mappings essentially provide a snapshot of the source +code reports for items that otherwise are unreachable or have been sliced +away during the compilation process.
+Integration with the Kani VS Code Extension
+We will update the coverage feature of the
+Kani VS Code Extension
+to follow this new coverage workflow.
+In other words, the extension will first run Kani with the --coverage option and
+use kani cov to produce a .kanicov file with the coverage results.
+The extension will consume the source-based code coverage results and
+highlight region coverage in the source code seen from VS Code.
We could also consider other coverage-related features in order to enhance the +experience through the Kani VS Code Extension. For example, we could +automatically show the percentage of covered regions in the status bar by +additionally extracting a summary of the coverage results.
+Finally, we could also consider an integration with other code coverage tools.
+For example, if we wanted to integrate with the VS Code extensions
+Code Coverage or
+Coverage Gutters,
+we would only need to extend kani-cov to export coverage results to the LCOV
+format or integrate Kani with LLVM tools as discussed in Integration with LLVM.
Detailed Design
+In this section, we provide more details on:
+-
+
- The Rust coverage instrumentation and how it can be integrated into +Kani to produce source-based code coverage results. +
- The proposed coverage workflow to be run by default in Kani when the
+
--coverageoption is used.
+
This information is mostly intended as a reference for Kani contributors. +Currently, the Rust coverage instrumentation continues to be developed. Because +of that, Rust toolchain upgrades may result in breaking changes to our own +coverage feature. This section should help developers to understand the general +approach and resolve such issues by themselves.
+The Rust coverage instrumentation
+The Rust compiler includes two code coverage implementations:
+-
+
- A source-based coverage implementation which uses LLVM's coverage
+instrumentation to generate precise coverage data. This implementation can be
+enabled with
-C instrument-coverage.
+ - A Gcov-based coverage implementation that derives coverage data based on
+DebugInfo. This implementation can be enabled with
-Z profile.
+
The Instrumentation-based Code Coverage
+chapter from the rustc book describes in detail how to enable and use the LLVM
+instrumentation-based coverage feature. In contrast, the
+LLVM Source-Based Code Coverage
+chapter from the rustc development guide documents how the LLVM
+coverage instrumentation is performed in the Rust compiler.
In this section, we will first summarize some information from the +LLVM Source-Based Code Coverage +chapter, limited to details which are relevant to the development of the +source-based coverage feature in Kani. Then, we will explain how Kani taps into +the Rust coverage instrumentation to perform its own coverage instrumentation +and be able to report source-based code coverage results. This will also include +mentions to current issues with this implementation, which we plan to further +discuss in Future possibilities.
+Understanding the Rust coverage instrumentation
+The LLVM coverage instrumentation is implemented in the Rust compiler as a
+MIR pass called InstrumentCoverage.
The MIR pass first builds a coverage-specific version of the MIR Control Flow
+Graph (CFG) from the MIR. The initial version of this CFG is based on the MIR's
+BasicBlocks, which then gets refined by combining blocks that can be chained
+from a coverage-relevant point of view. The final version of the coverage CFG is
+then used to determine where to inject the
+StatementKind::Coverage
+statements in order to measure coverage for a single region coverage span.
The injection of StatementKind::Coverage statements is the main result we are
+interested in for the integration with Kani. Additionally, the instrumentation
+will also attach the
+FunctionCoverageInfo
+structure to each function's body.5
+This result is also needed at the moment because coverage statements do not
+include information on the code region they are supposed to cover.
+However, FunctionCoverageInfo contains the
+coverage mappings,
+which represent the relation between
+coverage counters
+and code regions.
As explained in MIR Pass:
+InstrumentCoverage,
+many coverage statements will not be converted into a physical
+counter6. Instead, they will be converted into a
+coverage-counter expression that can be calculated based on other coverage
+counters. We highly recommend looking at the example in MIR Pass:
+InstrumentCoverage
+to better understand how this works. This optimization is mainly done for
+performance reasons because incrementing a physical counter causes a
+non-negligible overhead, especially within loops.
The (StatementKind::)Coverage statements that are injected by the Rust coverage
+instrumentation contain a CoverageKind field indicating the type of coverage counter. The variant
+CounterIncrement
+represents physical counters, while
+ExpressionUsed
+represents the counter expressions that we just discussed.
+Other variants such as SpanMarker or BlockMarker are not relevant to this
+work since they should have been erased after the InstrumentCoverage pass.
5
+
+It is important to note that the StableMIR interface does
+not include FunctionCoverageInfo in function bodies. Because of that, we
+need to pull it from the internal rustc function bodies.
6
+
+By physical counter, we refer to a global program +variable that is initialized to zero and incremented by one each time that +the execution passes through.
+Integrating the instrumentation into Kani
+Now that we have explained what the Rust coverage instrumentation does at a high +level, we should be ready to discuss how it can be used from Kani. Here, we will +follow an approach where, during the codegen stage, we generate a Kani +reachability check for each code region and, after the verification stage, we +postprocess the information in those checks to generate the coverage +information. So this section will essentially be a retelling of the +implementation in #3119, and +we will discuss variations/extensions of this approach in the +appropriate sections.
+Clearly, the first step is adding -C instrument-coverage to the rustc flags
+we use when calling the compiler to codegen. This flag enables the Rust coverage
+instrumentation that we discussed earlier, resulting in
-
+
- the injection of
+
Coverage+statements in the MIR code, and
+ - the inclusion of
FunctionCoverageInfoin function bodies.
+
The next step is handling the Coverage statements from codegen_statement.
Each Coverage statement contains opaque coverage
+information7 of the
+CoverageKind
+type which can be processed to determine the type of coverage counter
+(CounterIncrement for physical counters, ExpressionUsed for counter
+expressions) and the ID number of the counter. These two pieces of information allow us to
+uniquely identify the counter within a given function. For example,
+CounterIncrement(0) would generally refer to the first physical counter in the
+function.
Unfortunately, the CoverageKind information does not tell us anything about
+the code region that the counter covers. However, data about the code region can
+be pulled from the coverage mappings included in the FunctionCoverageInfo that
+is attached to the (internal) function body. Note that the coverage mappings
+includes information about all the coverage counters in a function, even for
+counters which have been dropped. Matching the CoverageKind information with
+that of the counters in the coverage mappings allows us to retrieve the code
+region for any counter.
Using all this data, for each coverage statement8 we generate a coverage check +that maintains the essence of the coverage checks described in the RFC for line +coverage:
+++Coverage checks are a new class of checks similar to
+coverchecks. +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 anassert(false)statement (to test reachability) with a fixed description. +In addition, coverage checks are:+
+- Hidden from verification results.
+- Postprocessed to produce coverage results.
+
Therefore, the last step is to postprocess the results from coverage checks to +produce coverage results. This is not too complicated to do since the checks +already include the counter information (type + ID) and the function name in +the check's description. If the span of the code region is also included +(this is what #3119 is +currently doing), we can directly generate a primitive output like this:
+<file_path> (<function_name>)
+ * <region_start> - <region_end> <status>
+ * ...
+ * <region_start> - <region_end> <status>
+For example, for the test case in +#3119 we report this:
+src/main.rs (main)
+ * 14:1 - 19:2 COVERED
+
+src/main.rs (test_cov)
+ * 5:1 - 6:15 COVERED
+ * 6:19 - 6:28 UNCOVERED
+ * 7:9 - 7:13 COVERED
+ * 9:9 - 9:14 UNCOVERED
+ * 11:1 - 11:2 COVERED
+++NOTE: This section has been written according to the implementation in +#3119, which currently +produces a text-based output like the one shown above. There is ongoing work to +store the coverage mappings in a separate file (as described in the next +section), which would save us the need to attach code region data to the +coverage checks.
+
7
+
+The Rust compiler uses the Opaque type to prevent
+others from interfacing with unstable types (e.g., the Coverage type
+here).
+Nonetheless, this can be worked around by serializing its contents and parsing
+it back into an internal data type.
8
+
+We could follow an alternative approach where we +do not instrument each coverage statement, but only those that correspond to +physical counters. Unfortunately, doing so would lead to incorrect coverage +results due to the arithmetic nature of expression-based counters. We elaborate +on this topic in the later parts of this document.
+The default coverage workflow in Kani
+In this section, we describe the default --coverage workflow from a
+developer's point of view. This will hopefully help developers understand how
+the different coverage components in Kani are connected. For example, we'll
+describe the raw coverage information that gets produced throughout the default
+--coverage workflow and define the basic cov commands that it will execute.
The main difference with respect to the regular verification workflow is that, +at the end of the verification-based coverage run, Kani will generate two types +of files:
+-
+
- One single file
.kanimapfile for the project. This file will contain the +coverage mappings for the project's source code.
+ - One
.kanirawfile for each harness. This file will contain the +verification-based results for the coverage-oriented properties corresponding +to a given harness.
+
Note that .kaniraw files correspond to .profraw files in the LLVM coverage
+workflow. Similarly, the .kanimap file corresponds to the coverage-related
+information that's embedded into the project's binaries in the LLVM coverage
+workflow.9
The files will be written into a new timestamped directory associated with the
+coverage run. The path to this directory will be printed to standard output in
+by default. For example, the draft implementation
+writes the coverage files into the target/kani/<target_triple>/cov/ directory.
Users aren't expected to read the information in any of these files. +Therefore, there's no need to restrict their format. +The draft implementation +uses the JSON format but we might consider using a binary format if it doesn't +scale.
+In addition, Kani will produce two types of coverage results:
+-
+
- A coverage summary with the default options. +
- A terminal-based coverage report with the default options. However, we will +only do this if the program is composed of a single source +file10. +
9
+
+Note that the .kanimap generation isn't implemented in
+#3119. The draft
+implementation of
+kani-cov simply reads
+the source files referred to by the code coverage checks, but it doesn't get
+information about code trimmed out by the MIR linker.
10
+
+In other words, standalone kani would always emit
+these terminal-based reports, but cargo kani would not unless the project
+contains a single Rust file (for example, src/main.rs).
Rationale and alternatives
+Other coverage implementations
+In a previous version of this feature, we used an ad-hoc coverage implementation. +In addition to being very inefficient11, the line-based coverage +results were not trivial to interpret by users. +At the moment, there's only another unstable, GCC-compatible code coverage implementation +based on the Gcov format. The Gcov format is line-based so it's not able +to report region coverage results. +In other words, it's not as advanced nor precise as the source-based implementation.
+11
+
+Actual performance benchmarks to follow in +#3119.
+Open questions
+-
+
- Do we want to instrument dependencies by default? Preliminary benchmarking results show a slowdown of 100% and greater. +More evaluations are required to determine how we handle instrumentation for dependencies, and what options we might want +to provide to users. +
- How do we handle features/options for
kani-cov? In particular, do we need more details in this RFC?
+
Future possibilities
+Integration with LLVM
+As part of this work, we explored a potential integration with the LLVM
+framework. The idea behind such an integration would essentially involve
+producing coverage results in formats compatible with the LLVM framework (e.g.,
+the .profraw format). The main advantage of integrating with the LLVM
+framework in this way is that we would not need a tool like kani-cov to
+aggregate coverage results; we could just use LLVM tools such as llvm-profdata
+and llvm-cov to consume them.
However, at this time we recommend against integrating with LLVM due to these reasons:
+-
+
- Generating the instrumented binary used in the LLVM coverage
+workflow requires a standard
rustc+compilation with--cfg kaniin addition to other flags including-C instrument-coverage. This is likely to result in compilation errors since the +standardrustcbackend cannot produce code for Kani APIs, for example.
+ - Producing the
.profrawfiles requires executing the instrumented binary at +least once. This would be an issue for Rust projects which assume a particular +environment for their execution.
+ - There are no stable interfaces to create or modify files in formats
+compatible with the LLVM framework. Even though the documentation for the LLVM
+Code Coverage Mapping Format
+is excellent, the easiest way to interact with files on these format is through
+LLVM tools (e.g.,
+
llvm-cov) +which bring in many other LLVM dependencies. During our exploration, we +attempted to decode and re-encode files in the.profrawto set the counter +data to the values obtained during verification. To this end, we tried tools +likellvm-profparserwhich +can be used as a replacement forllvm-profdataandllvm-covbut failed to +parse coverage files emitted by the Rust compiler (this is also related to the +next point). Another crate that we used is +coverage-dump, +a recent tool in the Rust compiler used for testing purposes.coverage-dump+extracts coverage mappings from LLVM IR assembly files (i.e., human-readable +*.llfiles) but does not work with the binary-encoded formats. Finally, we +also built some ad-hoc tooling to perform these modifications but it soon +became evident that we would need to develop it further in order to handle any +program.
+ - LLVM releases a new version approximately every six months. This would
+likely result in another "toolchain update" problem for Kani in order to
+provide compatibility with newer LLVM versions. Moreover, the Rust compiler
+supplies their own version of LLVM tools (
rust-profdata,rust-cov, etc.) +which are fully compatible with coverage-related artifacts produced byrustc.
+
Optimization with coverage-counter expressions
+In the subsection related to the +integration, we noted that we could +follow an alternative approach where we only instrument coverage statements that +correspond to physical counters. In fact, this would be the logical choice since +the replacement of physical counters by expression-based counters would also be +a performance optimization for us.
+However, the expressions used in expression-based counters are built with the
+arithmetic operators Add (+) and Sub (-). On the other hand, the
+coverage checks performed by Kani have a boolean meaning: you either cover a
+region or you do not. Thus, there are many cases where these two notions of
+coverage counters are incompatible. For example, let's say we have this
+function:
fn check_value(val: u32) {
+ if val == VALUE {
+ do_this();
+ } else {
+ do_that();
+ }
+ do_something_else();
+}
+One way to optimize the counters in this function is to have two physical
+counters for the branches of the if statement (c1 and c2), and then an
+expression-based counter associated to the do_something_else() statement
+adding those (i.e., c3 = c1 + c2). If we have, for example, two executions for
+this program, with each one taking a different branch, then the results for the
+coverage counters will be c1 = 1, c2 = 1 and c3 = c1 + c2 = 2.
But what does c3 = 2 mean in the context of a verification-based coverage
+result? That is not clear. For instance, in a Kani trace, you could have a
+nondeterministic value for val which just happens to be val == VALUE and not
+at the same time. This would result in the same counters (c1 = 1, c2 = 1 and
+c3 = 2), but the program is being run only once!
Note that finding a verification-based replacement for the runtime operators in
+counter-based expressions is an interesting research topic. If we could
+establish a relation between the runtime and verification expressions, then we
+could avoid the instrumentation of coverage checks for expression-based
+counters. For example, could we replace the Add operator (+) with an Or
+operator (||)? Intuitively, this makes sense since verification-based coverage
+counters are binary. It also seems to work for our example since covering any of
+the branches should result in the do_something_else() statement being covered
+as well, with the counter values now being c1 = 1, c2 = 1 and c3 = 1.
+However, it is not clear that this would work for all cases, nor it is clear
+that we can replace Sub with another verification-based operator.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/rfcs/0013-list.html b/rfc/rfcs/0013-list.html
new file mode 100644
index 000000000000..fdcd368231bd
--- /dev/null
+++ b/rfc/rfcs/0013-list.html
@@ -0,0 +1,336 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Procedural macros
+
+ +
+
+
+
+ -
+
- Feature Name: Loop Contracts +
- Feature Request Issue: #3168 +
- RFC PR: #3167 +
- Status: Under Review +
- Version: 1 +
- Proof-of-concept: +
+
Summary
+Loop contracts provide way to safely abstract loops of a program, typically +in order to accelerate the verification process, and remove the loop unwinding +bounds. The key idea is to over-approximate the possible set of program states, +while still being precise enough to be able to prove the desired property.
+User Impact
+Loop contracts provide an interface for a verified, sound abstraction. +The goal for specifying loop contracts in the source code is two fold:
+-
+
- Unbounded verification: Currently, proving correctness +(i.e. assertions never fail) on programs with unbounded control flow (e.g. +loops with dynamic bounds) Kani requires unwinding loops for a large number of +times, which is not always feasible. Loop contracts provide a way to abstract +out loops, and hence remove the need for unwinding loops. +
- Faster CI runs: In most cases, the provided contracts would also significantly +improve Kani's verification time since all loops would be unrolled only to +a single iteration. +
Loop 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.
+User Experience
+A loop contract specifies the behavior of a loop as a boolean predicate +(loop invariants clauses) with certain frames conditions (loop modifies clauses) +that can be checked against the loop implementation, and used to abstract out +the loop in the verification process.
+We illustrate the usage of loop contracts with an example. +Consider the following program:
+fn simple_loop() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+}
+The loop in the simple_loop function keep subtracting 1 from x until x is 1.
+However, Kani currently needs to unroll the loop for u64::MAX number of times
+to verify the assertion at the end of the program.
With loop contracts, the user can specify the behavior of the loop as follows:
+fn simple_loop_with_loop_contracts() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+}
+The loop invariant clause #[kani::loop_invariant(x >= 1)] specifies the loop
+invariants that must hold at the beginning of each iteration of the loop right before
+checking the loop guard.
In this case, Kani verifies that the loop invariant x >= 1 is inductive, i.e.,
+x is always greater than or equal to 1 at each iteration before checking x > 1.
Also, once Kani proved that the loop invariant is inductive, it can safely use the loop +invariants to abstract the loop out of the verification process. +The idea is, instead of exploring all possible branches of the loop, Kani only needs to +prove those branches reached from an arbitrary program state that satisfies the loop contracts, +after the execution of one iteration of the loop.
+So, for loops without break statements, we can assume all post-states of the loop satisfying
+inv && !loop_guard for proving post-loops properties.
+The requirement of satisfying the negation of the loop guard comes from the fact that a path
+exits loops without break statements must fail the loop guard.
For example, applying loop contracts in simple_loop function is equivalent to the following:
fn simple_loop_transformed() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ x = kani::any(); // Arbitrary program state that
+ kani::assume( !(x > 1) && x >= 1); // satisfies !`guard` && `inv`
+
+ assert!(x == 1);
+}
+The assumption above is actually equivalent to x == 1, hence the assertion at the end
+of the program is proved.
Write Sets and Havocking
+For those memory locations that are not modified in the loop, loop invariants state
+that they stay unchanged throughout the loop are inductive. In other words, Kani should
+only havoc the memory locations that are modified in the loop. This is achieved by
+specifying the modifies clause for the loop. For example, the following program:
fn simple_loop_two_vars() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+ let mut y: u64 = 1;
+
+ #[kani::loop_invariant(x >= 1)]
+ #[kani::loop_modifies(x)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x == 1);
+ assert!(y == 1);
+}
+write to only x in the loop, hence the modifies clause contains only x.
+Then when use the loop contracts to abstract the loop, Kani will only havoc the memory
+location x and keep y unchanged. Note that if the modifies clause contains also
+y, Kani will havoc both x and y, and hence violate the assertion y == 1.
Kani can employs CBMC's write set inference to infer the write set of the loop.
+So users have to specify the modifies clauses by their self only when the inferred write
+sets are not complete---there exists some target that could be written to in the loop but
+is not in the inferred write set.
Proof of termination
+Loop contracts also provide a way to prove the termination of the loop. +Without the proof of termination, Kani could report success of some assertions that +are actually unreachable due to non-terminating loops. +For example, consider the following program:
+fn simple_loop_non_terminating() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ while true{
+ x = x;
+ };
+
+ assert!(x >= 1);
+}
+After abstracting the loop, the loop will be transformed to no-op, and the assertion
+x >= 1 will be proved. However, the loop is actually an infinite loop, and the
+assertion will never be reached.
For this reason, Kani will also require the user to provide a decreases clause that
+specifies a decreasing expression to prove the termination of the loop. For example, in
fn simple_loop_terminating() {
+ let mut x: u64 = kani::any_where(|i| *i >= 1);
+
+ #[kani::loop_invariant(x >= 1)]
+ #[kani::loop_decreases(x)]
+ while x > 1{
+ x = x - 1;
+ };
+
+ assert!(x >= 1);
+}
+, the decreases clause #[kani::loop_decreases(x)] specifies that the value of x
+decreases at each iteration of the loop, and hence the loop will terminate.
Detailed Design
+Kani implements the functionality of loop contracts in three places.
+-
+
- Procedural macros
loop_invariant,loop_modifies, andloop_decreases.
+ - Code generation for builtin functions expanded from the above macros. +
- GOTO-level loop contracts using CBMC's contract language generated in
+
kani-compiler.
+
Procedural macros loop_invariant, loop_modifies, and loop_decreases.
+We will implement the three proc-macros loop_invariant, loop_modifies, and loop_decreases to
+embed the annotation logic as Rust code. Kani will then compile them into MIR-level code.
Code Generation for Builtin Functions
+Then in the MIR, we codegen the loop contracts as GOTO-level expressions and annotate them +into the corresponding loop latches---the jumps back to the loop head.
+The artifact goto-instrument in CBMC will extract the loop contracts from the named-subs
+of the loop latch, and then apply and prove the extracted loop contracts.
GOTO-Level Havocing
+The ordinary havocing in CBMC is not aware of the type constraints of Rust type.
+Hence, we will use customized havocing functions for modifies targets. In detail,
+Kani will generate code for the definition of corresponding kani::any() functions
+for each modifies target. Then Kani will create a map from the modifies target to the
+the name of its kani::any() function, and add the map to the loop latch too.
On the CBMC site, goto-instrument will extract the map and instrument the customized
+havocing functions for the modifies targets.
Rationale and alternatives
+Rust-Level Transformation vs CBMC
+Besides transforming the loops in GOTO level using goto-instrument,
+we could also do the transformation in Rust level using procedural macros, or
+in MIR level.
There are two reasons we prefer the GOTO-level transformation.
+First, goto-instrument is a mature tool that can correctly instrument the frame
+condition checking for the transformed loop, which will save us from reinventing
+the error-prone wheel. Second, the loop contracts synthesis tool we developed and
+are developing are all based on GOTO level. Hence, doing the transformation in
+the GOTO level will make the integration of loop contracts with the synthesis tool
+easier.
Open questions
+-
+
- How do we integrate loop contracts with the synthesis tool? When the user-provided +loop contracts are not enough prove the harness, we expect the loop-contract synthesizer +can fix the loop contracts. +
- How do we translate back modify targets that inferred by CBMC to Rust level? +
- It is not clear how the CBMC loop modifies inference works for Rust code. We need to +experiment more to decide what would be the best UX of using loop modifies. +
- How do we handle havocing in unsafe code where it is fine to break the safety invariant +of Rust? In that case, we may need havocing function that preserves validity invariant +but not safety invariant. +
- What is the proper mechanism for users to specify the loops that they want to opt-out from applying loop contracts, and (optionally) the unwind numbers for them. Such options should be per-harness. +
Future possibilities
+-
+
- We can employ CBMC's decreases inference to infer the decreases clauses to reduce the +user burden of specifying the decreases clauses. +
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rfc/searcher.js b/rfc/searcher.js
new file mode 100644
index 000000000000..d2b0aeed387b
--- /dev/null
+++ b/rfc/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
- Feature Name: List Subcommand +
- Feature Request Issue: #2573, #1612 +
- RFC PR: #3463 +
- Status: Unstable +
- Version: 2 +
+
Summary
+Add a subcommand list that, for each crate under verification, lists the information relevant to its verification.
User Impact
+Currently, there is no automated way for a user to gather metadata about Kani's integration with their project. If, for example, a user wants a list of harnesses for their project, they must search for all the relevant contract attributes (currently #[proof] or #[proof_for_contract]) themselves. If done manually, this process is tedious, especially for large projects. Even with a shell script, it is error-prone--if, for example, we introduce a new type of proof harness, users would have to account for it when searching their project.
Internally, this feature will be useful for tracking our customers' use of Kani and our progress with standard library verification. Externally, users can leverage this feature to get a high-level view of which areas of their projects have harnesses (and, by extension, which areas are still in need of verification).
+This feature will not cause any regressions for exisiting users.
+User Experience
+Users run a list subcommand, which prints metadata about the harnesses and contracts in each crate under verification. The subcommand takes two options:
-
+
--message-format=[pretty|json]: choose the output format. The default ispretty, which prints to the terminal. Thejsonoption creates and writes to a JSON file instead.
+--std: this option should be specified when listing the harnesses and contracts in the standard library. This option is only available forkani list(notcargo kani list), which mirrors the verification workflow for the standard library.
+
This subcommand does not fail. In the case that it does not find any harnesses or contracts, it prints a message informing the user of that fact.
+Pretty Format
+The default format, pretty, prints a "Contracts" table and a "Standard Harnesses" list.
+Each row of the "Contracts" table consists of a function under contract and its contract harnesses.
+The results are printed in lexicographic order.
For example:
+Kani Rust Verifier 0.54.0 (standalone)
+
+Contracts:
+|-------|-------------------------|--------------------------------------------------|
+| | Function | Contract Harnesses (#[kani::proof_for_contract]) |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::bar | example::verify::check_bar |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::baz | example::verify::check_baz |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::foo | example::verify::check_foo_u32 |
+| | | example::verify::check_foo_u64 |
+|-------|-------------------------|--------------------------------------------------|
+| | example::impl::func | example::verify::check_func |
+|-------|-------------------------|--------------------------------------------------|
+| | example::prep::parse | NONE |
+|-------|-------------------------|--------------------------------------------------|
+| Total | 5 | 5 |
+|-------|-------------------------|--------------------------------------------------|
+
+Standard Harnesses (#[kani::proof]):
+1. example::verify::check_modify
+2. example::verify::check_new
+All sections will be present in the output, regardless of the result.
+If there are no harnesses for a function under contract, Kani inserts NONE in the "Contract Harnesses" column.
+If the "Contracts" section is empty, Kani prints a message that "No contracts or contract harnesses were found."
+If the "Standard Harnesses" section is empty, Kani prints a message that "No standard harnesses were found."
JSON Format
+If the user wants an output format that's more easily parsed by a script, they can use the json option.
The JSON format will contain the same information as the pretty format, with the addition of file paths and file version. +The file version will use semantic versioning. +This way, any users relying on this format for their scripts can detect when we've released a new major version and update their logic accordingly.
+For example:
+{
+ kani-version: 0.54,
+ file-version: 0.1,
+ standard-harnesses: [
+ {
+ file: /Users/johnsmith/example/kani_standard_proofs.rs
+ harnesses: [
+ example::verify::check_modify,
+ example::verify::check_new
+ ]
+ },
+ ],
+ contract-harnesses: [
+ {
+ file: /Users/johnsmith/example/kani_contract_proofs.rs
+ harnesses: [
+ example::verify::check_bar,
+ example::verify::check_baz,
+ example::verify::check_foo_u32,
+ example::verify::check_foo_u64,
+ example::verify::check_func
+ ]
+ },
+ ],
+ contracts: [
+ {
+ function: example::impl::bar
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_bar]
+ },
+ {
+ function: example::impl::baz
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_baz]
+ },
+ {
+ function: example::impl::foo
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [
+ example::verify::check_foo_u32,
+ example::verify::check_foo_u64
+ ]
+ },
+ {
+ function: example::impl::func
+ file: /Users/johnsmith/example/impl.rs
+ harnesses: [example::verify::check_func]
+ },
+ {
+ function: example::prep::parse
+ file: /Users/johnsmith/example/prep.rs
+ harnesses: []
+ }
+ ],
+ totals: {
+ standard-harnesses: 2,
+ contract-harnesses: 5,
+ functions-with-contracts: 5,
+ }
+}
+All sections will be present in the output, regardless of the result. +If there is no result for a given field (e.g., there are no contracts), Kani will output an empty list (or zero for totals).
+Software Design
+Driver/Metdata Changes
+We add a new list subcommand to kani-driver, which invokes the compiler to collect metadata, then post-processes that metadata and outputs the result.
+We extend KaniMetadata to include a new field containing each function under contract and its contract harnesses.
Compiler Changes
+In codegen_crate, we update the generation of KaniMetadata to include the new contracts information.
+We iterate through each local item in the crate.
+Each time we find a function under contract or a contract harness, we include it in the metadata.
Rationale and alternatives
+Users of Kani may have many questions about their project--not only where their contracts and harnesses are, but also where their stubs are, what kinds of contracts they have, etc. Rather than try to answer every question a user might have, which would make the output quite verbose, we focus on these four:
+-
+
- Where are the harnesses? +
- Where are the contracts? +
- Which contracts are verified, and by which harnesses? +
- How many harnesses and functions under contract are there? +
We believe these questions are the most important for our use cases of tracking verification progress for customers and the standard library. The UX is designed to answer these questions clearly and concisely.
+We could have a more verbose or granular output, e.g., printing the metadata on a per-crate or per-module level, or including stubs or other attributes. Such a design would have the benefit of providing more information, with the disadvantage of being more complex to implement and more information for the user to process. +If we do not implement this feature, users will have to obtain this metadata through manual searching, or by writing a script to do it themselves. This feature will improve our internal productivity by automating the process.
+The Contracts table is close to Markdown, but not quite Markdown--it includes line separators between each row, when Markdown would only have a separator for the header. +We include the separator because without it, it can be difficult to tell from reading the terminal output which entries are in the same row. +The user can transform the table to Markdown by deleting these separators, and we can trivially add a Markdown option in the future if there is demand for it.
+Open questions
+-
+
- Do we want to include more contracts information? We could print more granular information about contracts, e.g., the text of the contracts or the number of contracts. +
- More generally, we could introduce additional options that collect information about other Kani attributes (e.g., stubs). The default would be to leave them out, but this way a user could get more verbose output if they so choose. +
- Do we want to add a filtering option? For instance,
--harnesses <pattern>and--contracts <pattern>, wherepatterncorresponds to a Rust-style path. For example,kani list --harnesses "my_crate::my_module::*"would include all harnesses with that path prefix, whilekani list --contracts "my_crate::my_module::*"would include all functions under contract with that path prefix. (If we do this work, we could use it to improve our--harnesspattern handling for verification).
+
Out of scope / Future Improvements
+It would be nice to differentiate between regular Kani harnesses and Bolero harnesses. Bolero harnesses invoke Kani using conditional compilation, e.g.:
+#[cfg_attr(kani, kani::proof)]
+fn check() {
+ bolero::check!()...
+}
+See this blog post for more information.
+There's no easy way for us to know whether a harness comes from Bolero, since Bolero takes care of rewriting the test to use Kani syntax and invoking the Kani engine. By the time the harness gets to Kani, there's no way for us to tell it apart from a regular harness. Fixing this would require some changes to our Bolero integration.
+ +