Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 35 additions & 3 deletions docs/src/reference/experimental/autoharness.md
Original file line number Diff line number Diff line change
Expand Up @@ -322,7 +322,11 @@ pointee and constructs a new smart pointer around it. These arguments require no

The generation models require allocation support and use the default allocator. They cover
the pointee's generated values; `Rc` and `Arc` start with one strong reference and no weak
references, so states with existing owners or weak references are not explored. Unsized
references, so states with existing owners or weak references are not explored. A harness
whose generated values contain an `Rc` or `Arc`, directly or nested (e.g. `Box<Rc<T>>`,
`(u8, Rc<T>)`, `&Arc<T>`, or a struct with an `Arc` field), is therefore marked "(refcount)"
(see [Summary table and markers](#summary-table-and-markers) and
[Reference counts](#reference-counts)). Unsized
pointees such as `str` and `[T]` are outside these models; some types, such as `Box<[T]>`,
can instead be generated through `BoundedArbitrary` with `--bounded-arguments`.

Expand Down Expand Up @@ -704,8 +708,14 @@ may carry one or both of these markers:
Harnesses filtered only by the mined invariants of a type with its own `Arbitrary`
implementation are currently not marked; see
[Mined-invariant heuristic](#mined-invariant-heuristic).

A `Success` without either marker still has the limitations described in
- **"(refcount)"**: some generated values contain an `Rc` or `Arc`, whose reference counts are
modeled with only finitely many states (see [Reference counts](#reference-counts)). Unlike
"(bounded)", this needs no option: `Rc`/`Arc` arguments are generated by default and set
`has_refcount_caveat`, not `is_bounded`. A note after the table repeats the limitation, the
per-function "Checking function ..." message qualifies "all possible inputs", and the
`--export-json` document sets `has_refcount_caveat` for the harness.

A `Success` without any of these markers still has the limitations described in
[Soundness caveats](#soundness-caveats).

## Soundness caveats
Expand Down Expand Up @@ -752,6 +762,28 @@ or a larger `BoundedArbitrary` value, is not found. The bounds a run used are pr
after the summary table. Arguments that are generated without bounds by default, such as slices
and `Vec`s of primitive integers or floats, are not affected.

### Reference counts

Harnesses marked "(refcount)" generate `Rc`/`Arc` values whose reference counts are modeled with
only finitely many states: currently every generated `Rc`/`Arc` is uniquely owned
(`strong_count == 1`, `weak_count == 0`); [#4752](https://github.com/model-checking/kani/issues/4752)
tracks generating shared states. What such a result does and does not cover:

- **Exact counts.** A real caller can pass an `Rc` with any number of other strong and weak
references, but only the uniquely owned state is checked. In particular, the shared outcomes
of the uniqueness checks in `get_mut`, `try_unwrap`, `into_inner` and `make_mut` are never
reached, and code that reads `strong_count` or `weak_count` (e.g. `Rc::strong_count(&x) > 1`)
is only verified for the counts 1 and 0.
- **No other holders.** Since no other strong or weak reference exists, nothing that another
holder could do is covered, e.g. keep a `RefCell` borrow active, upgrade a `Weak`, or access
the value from another thread.
- **No aliasing between arguments.** Distinct `Rc`/`Arc` arguments never share an allocation
(`Rc::ptr_eq(&a, &b)` is never true).
- **Detection** follows the argument types, including references, tuples, arrays, slices, `Box`,
struct and enum fields and generic arguments (skipping `PhantomData`), so it may also mark a
harness whose type mentions an `Rc`/`Arc` that the generated value never holds. Manual
harnesses calling `kani::any::<Rc<T>>()` are not marked.

### Vacuous constructors

This applies to harnesses marked "(ctor)", i.e. runs with `--constructor-args` (see
Expand Down
33 changes: 31 additions & 2 deletions kani-compiler/src/kani_middle/codegen_units.rs
Original file line number Diff line number Diff line change
Expand Up @@ -421,6 +421,7 @@ fn get_all_automatic_harnesses(
harness.mangled_name(),
caveats.is_bounded,
caveats.is_ctor_based,
caveats.has_refcount_caveat,
);
(harness, metadata)
})
Expand Down Expand Up @@ -1161,13 +1162,17 @@ fn choose_generic_instantiation(
}

/// The caveats that apply to a generated harness, reported in the summary table and stored in
/// its metadata. They are independent: a harness can be both bounded and constructor-based.
/// its metadata. They are independent: a harness can be, e.g., both bounded and constructor-based.
#[derive(Clone, Copy, Debug, Default)]
struct AutoHarnessCaveats {
/// Some argument uses *bounded* nondeterministic values, c.f. `--bounded-arguments`.
is_bounded: bool,
/// Some value is generated through a type's public constructor, c.f. `--constructor-args`.
is_ctor_based: bool,
/// Some generated value contains an `Rc`/`Arc`, whose reference counts are modeled with
/// finitely many states, c.f. `contains_refcounted_ptr`. Unlike `is_bounded`, this does not
/// require (or depend on) `--bounded-arguments`.
has_refcount_caveat: bool,
}

/// Partition every function in the crate into (chosen, skipped), where `chosen` is a vector of the Instances for which we'll generate automatic harnesses,
Expand Down Expand Up @@ -1412,7 +1417,31 @@ fn automatic_harness_partition(
)
})
});
chosen.push((instance, AutoHarnessCaveats { is_bounded, is_ctor_based }));
// Whether any generated value contains an `Rc`/`Arc`, whose reference-count
// state is only modeled finitely, which the summary reports as "(refcount)".
// Formatting trait harnesses generate a value of the impl's self type rather
// than of the function's arguments (`&self`, `&mut Formatter`), c.f.
// `fmt_impl_self_ty`.
let has_refcount_caveat = match fmt_impl_self_ty(tcx, instance) {
Some((_, self_ty)) => crate::kani_middle::contains_refcounted_ptr(
tcx,
self_ty,
&mut FxHashSet::default(),
),
None => instance.body().is_some_and(|body| {
body.arg_locals().iter().any(|arg| {
crate::kani_middle::contains_refcounted_ptr(
tcx,
arg.ty,
&mut FxHashSet::default(),
)
})
}),
};
chosen.push((
instance,
AutoHarnessCaveats { is_bounded, is_ctor_based, has_refcount_caveat },
));
}
}
}
Expand Down
3 changes: 3 additions & 0 deletions kani-compiler/src/kani_middle/metadata.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ pub fn gen_proof_metadata(tcx: TyCtxt, instance: Instance, base_name: &Path) ->
is_automatically_generated: false,
is_bounded: false,
is_ctor_based: false,
has_refcount_caveat: false,
}
}

Expand Down Expand Up @@ -128,6 +129,7 @@ pub fn gen_automatic_proof_metadata(
harness_mangled_name: String,
is_bounded: bool,
is_ctor_based: bool,
has_refcount_caveat: bool,
) -> HarnessMetadata {
let def = fn_to_verify.def;
let pretty_name = readable_name(*fn_to_verify);
Expand Down Expand Up @@ -172,5 +174,6 @@ pub fn gen_automatic_proof_metadata(
is_automatically_generated: true,
is_bounded,
is_ctor_based,
has_refcount_caveat,
}
}
63 changes: 62 additions & 1 deletion kani-compiler/src/kani_middle/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
use std::collections::HashSet;

use crate::kani_queries::QueryDb;
use rustc_data_structures::fx::FxHashMap;
use rustc_data_structures::fx::{FxHashMap, FxHashSet};
use rustc_hir::{def::DefKind, def_id::DefId as InternalDefId, def_id::LOCAL_CRATE};
use rustc_middle::ty::TyCtxt;
use rustc_public::mir::mono::{Instance, MonoItem};
Expand Down Expand Up @@ -1050,6 +1050,67 @@ fn smart_pointer_pointee(tcx: TyCtxt, ty: Ty) -> Option<(SmartPointerKind, Ty)>
Some((kind, pointee))
}

/// Whether a nondeterministic value of `ty` can contain an `Rc` or `Arc`.
///
/// Kani models the reference-count state of generated `Rc`/`Arc` values with only finitely many
/// representatives (<https://github.com/model-checking/kani/issues/4752>), so automatic harnesses
/// generating such values are marked "(refcount)" in reports, c.f. `AutoHarnessCaveats`.
///
/// The walk follows references, raw pointers, arrays, slices, tuples, pattern types, ADT fields
/// (with the ADT's generic arguments substituted) and ADT generic arguments, so `Rc`/`Arc`
/// nested in other types (`Box<Rc<T>>`, `Vec<Arc<T>>`, structs with `Rc` fields, ...) is found
/// regardless of how the enclosing value is generated: a hand-written `Arbitrary`
/// implementation that builds an `Rc` itself also produces a finitely modeled count.
/// `PhantomData<T>` holds no value of `T` and is skipped.
///
/// This over-approximates (a type parameter only used, e.g., as a marker in a non-`PhantomData`
/// field of a foreign type would still be reported), which only risks a spurious caveat. To keep
/// that the only failure mode, the walk reports `true` if it exceeds its budget (e.g. for
/// polymorphically recursive types). Values not visible in the type (behind `dyn Trait`, or
/// function pointers) cannot be generated by automatic harnesses and are not considered.
pub(crate) fn contains_refcounted_ptr(tcx: TyCtxt, ty: Ty, visited: &mut FxHashSet<Ty>) -> bool {
const BUDGET: usize = 256;
if !visited.insert(ty) {
return false;
}
if visited.len() > BUDGET {
return true;
}
match ty.kind() {
TyKind::RigidTy(
RigidTy::Ref(_, inner, _)
| RigidTy::RawPtr(inner, _)
| RigidTy::Array(inner, _)
| RigidTy::Slice(inner)
| RigidTy::Pat(inner, _),
) => contains_refcounted_ptr(tcx, inner, visited),
TyKind::RigidTy(RigidTy::Tuple(elems)) => {
elems.iter().any(|elem| contains_refcounted_ptr(tcx, *elem, visited))
}
TyKind::RigidTy(RigidTy::Adt(def, args)) => {
let def_id = rustc_internal::internal(tcx, def.def_id());
if tcx.get_diagnostic_item(rustc_span::sym::Rc) == Some(def_id)
|| tcx.get_diagnostic_item(rustc_span::sym::Arc) == Some(def_id)
{
return true;
}
if tcx.adt_def(def_id).is_phantom_data() {
return false;
}
def.variants_iter().any(|variant| {
variant
.fields()
.iter()
.any(|field| contains_refcounted_ptr(tcx, field.ty_with_args(&args), visited))
}) || args.0.iter().any(|arg| match arg {
GenericArgKind::Type(t) => contains_refcounted_ptr(tcx, *t, visited),
_ => false,
})
}
_ => false,
}
}

/// If `ty` is a supported smart-pointer type whose generation model is available, resolve the
/// model for the pointee and return it together with the pointee type. Returns `None` if the
/// model's return type does not match `ty` exactly (e.g. for a non-default allocator).
Expand Down
81 changes: 69 additions & 12 deletions kani-driver/src/autoharness/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,30 @@ use kani_metadata::{AutoHarnessSkipReason, HarnessMetadata, KaniMetadata};
const AUTOHARNESS_TIMEOUT: &str = "60s";
const LOOP_UNWIND_DEFAULT: u32 = 20;

/// Printed after the summary table if some harness is marked "(refcount)", c.f.
/// `HarnessMetadata::has_refcount_caveat`. Deliberately states only that the modeled counts are
/// finite, not which ones: the representatives are an implementation detail of the `Rc`/`Arc`
/// generators (<https://github.com/model-checking/kani/issues/4752>).
const REFCOUNT_NOTE: &str = "Note: harnesses marked \"(refcount)\" generate Rc/Arc values whose reference counts are modeled with only finitely many states\n\
(this needs no --bounded-arguments). Their verification results do not cover every reference count a caller could produce,\n\
e.g. code that compares strong_count/weak_count against specific values may not be fully verified.";

/// The "Kind of Automatic Harness" column of the summary table: the harness kind, followed by a
/// marker for each caveat that restricts which inputs its verification result covers.
fn harness_kind_label(harness: &HarnessMetadata) -> String {
let mut kind = harness.attributes.kind.to_string();
if harness.is_bounded {
kind.push_str(" (bounded)");
}
if harness.is_ctor_based {
kind.push_str(" (ctor)");
}
if harness.has_refcount_caveat {
kind.push_str(" (refcount)");
}
kind
}

pub fn autoharness_cargo(args: CargoAutoharnessArgs) -> Result<()> {
let mut session = KaniSession::new(args.verify_opts)?;
setup_session(&mut session, &args.common_autoharness_args);
Expand Down Expand Up @@ -277,37 +301,30 @@ impl KaniSession {
"Verification Result",
]);

let harness_kind = |harness: &HarnessMetadata| {
let mut kind = harness.attributes.kind.to_string();
if harness.is_bounded {
kind.push_str(" (bounded)");
}
if harness.is_ctor_based {
kind.push_str(" (ctor)");
}
kind
};
let mut any_bounded = false;
let mut any_ctor = false;
let mut any_refcount = false;

for success in successes {
any_bounded |= success.harness.is_bounded;
any_ctor |= success.harness.is_ctor_based;
any_refcount |= success.harness.has_refcount_caveat;
verified_fns.add_row(vec![
success.harness.crate_name.clone(),
success.harness.pretty_name.clone(),
harness_kind(success.harness),
harness_kind_label(success.harness),
success.result.status.to_string(),
]);
}

for failure in failures {
any_bounded |= failure.harness.is_bounded;
any_ctor |= failure.harness.is_ctor_based;
any_refcount |= failure.harness.has_refcount_caveat;
verified_fns.add_row(vec![
failure.harness.crate_name.clone(),
failure.harness.pretty_name.clone(),
harness_kind(failure.harness),
harness_kind_label(failure.harness),
failure.result.status.to_string(),
]);
}
Expand All @@ -332,6 +349,9 @@ impl KaniSession {
their verification results only cover values reachable through that constructor."
);
}
if any_refcount {
println!("{REFCOUNT_NOTE}");
}

if failing > 0 {
println!(
Expand All @@ -351,3 +371,40 @@ impl KaniSession {
}
}
}

#[cfg(test)]
mod tests {
use super::{REFCOUNT_NOTE, harness_kind_label};
use crate::metadata::tests::mock_proof_harness;

/// Each caveat adds its own marker; "(refcount)" is independent of "(bounded)", since
/// `Rc`/`Arc` arguments need no --bounded-arguments (#4752).
#[test]
fn harness_kind_label_marks_each_caveat() {
let mut h = mock_proof_harness("f", None, None, None);
assert_eq!(harness_kind_label(&h), "#[kani::proof]");
h.has_refcount_caveat = true;
assert_eq!(harness_kind_label(&h), "#[kani::proof] (refcount)");
h.is_bounded = true;
h.is_ctor_based = true;
assert_eq!(harness_kind_label(&h), "#[kani::proof] (bounded) (ctor) (refcount)");
}

/// The marker fits the summary table's "Kind of Automatic Harness" header, so marking a
/// proof harness does not widen the column (and shift every row) of existing tables.
#[test]
fn refcount_label_fits_kind_column_header() {
let mut h = mock_proof_harness("f", None, None, None);
h.has_refcount_caveat = true;
assert!(harness_kind_label(&h).len() <= "Kind of Automatic Harness".len());
}

/// The note names the marker, says it needs no --bounded-arguments, and does not claim
/// complete coverage.
#[test]
fn refcount_note_states_the_caveat() {
assert!(REFCOUNT_NOTE.contains("\"(refcount)\""));
assert!(REFCOUNT_NOTE.contains("no --bounded-arguments"));
assert!(REFCOUNT_NOTE.contains("do not cover every reference count"));
}
}
Loading
Loading