Skip to content
Merged
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
24 changes: 24 additions & 0 deletions docs/src/reference/experimental/autoharness.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,30 @@ execution.

Nested slice references (e.g. `&&[u8]`) and slices inside user-defined types remain unsupported.

## Debug and Display Implementations
For the `fmt` methods of `Debug` and `Display` implementations, the `&mut Formatter` argument
cannot be generated nondeterministically. Instead, Kani generates a harness that formats a
nondeterministic value of the implementing type into a sink that discards the output: the
`Formatter` is constructed by the core formatting machinery (so it is always valid), and panics
or undefined behavior inside the `fmt` implementation are detected as usual.
These harnesses are unbounded with respect to the implementing type (its value is generated with
`kani::any`), so they are generated by default and are unaffected by `--bounded-arguments`. If the
implementing type implements [`Invariant`](#type-safety-invariants), the generated value is assumed
to satisfy it, as for any other automatic harness.

Current limitations:
- The `Formatter` carries the default formatting parameters, i.e. it is the one that
`format!("{:?}", value)`/`format!("{}", value)` would produce. Code paths that a `fmt`
implementation takes only for a non-default width, precision, fill, alignment, sign, or the
alternate (`{:#?}`) flag are therefore not covered.
- The sink never fails, so `fmt` implementations that propagate write errors with `?` are not
verified against the error path.
- Because the harness goes through `core::fmt`, the core formatting machinery is verified along
with the `fmt` implementation, so a reported failure may point at a location inside `core`.
- A `fmt` method that carries a [function contract](contracts.md) is not handled this way: the
automatic contract harness calls the function directly, so it is skipped for its
`&mut Formatter` argument like any other function Kani cannot call.

## Limitations
### Arguments Implementing Arbitrary
Kani will only generate an automatic harness for a function if it can represent each of its arguments nondeterministically.
Expand Down
24 changes: 23 additions & 1 deletion kani-compiler/src/kani_middle/codegen_units.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,10 @@ use crate::kani_middle::metadata::{
};
use crate::kani_middle::reachability::filter_crate_items;
use crate::kani_middle::stubbing::{check_compatibility, harness_stub_map};
use crate::kani_middle::{ArgSupport, SmartPointerModels, autoharness_supported_arg_ty};
use crate::kani_middle::{
ArgSupport, SmartPointerModels, autoharness_supported_arg_ty, can_derive_arbitrary,
fmt_impl_self_ty, implements_arbitrary,
};
use crate::kani_queries::QueryDb;
use kani_metadata::{
ArtifactType, AssignsContract, AutoHarnessMetadata, AutoHarnessSkipReason, HarnessMetadata,
Expand Down Expand Up @@ -577,6 +580,25 @@ fn automatic_harness_partition(
return Err(AutoHarnessSkipReason::UserFilter);
}

// Debug/Display fmt implementations are handled specially: their `&mut Formatter`
// argument cannot be generated, but the generated harness formats a nondeterministic
// value of the self type into a discarding sink instead, c.f. `fmt_impl_self_ty`.
// The self type is generated with `kani::any`, so it must implement (or be able to
// derive) Arbitrary; argument-position-only support (raw/smart pointers, bounded types)
// does not apply here, and these harnesses are therefore never bounded.
if let Some((_, self_ty)) = fmt_impl_self_ty(tcx, instance) {
return if implements_arbitrary(self_ty, kani_any_def, &mut ty_arbitrary_cache)
|| can_derive_arbitrary(self_ty, kani_any_def, &mut ty_arbitrary_cache)
{
Ok(false)
} else {
Err(AutoHarnessSkipReason::MissingArbitraryImpl(vec![(
"self".to_string(),
format!("{self_ty}"),
)]))
};
}

// Each argument of `instance` must be supported by automatic harness generation, i.e.,
// implement Arbitrary (or be capable of deriving it), be a raw pointer, be a supported
// smart pointer (`Box`/`Rc`/`Arc` of a derivable pointee), or -- if the user opted in via
Expand Down
4 changes: 4 additions & 0 deletions kani-compiler/src/kani_middle/kani_functions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ pub enum KaniModel {
AssumeSafe,
#[strum(serialize = "BoundedAnyModel")]
BoundedAny,
#[strum(serialize = "CheckDebugFmtModel")]
CheckDebugFmt,
#[strum(serialize = "CheckDisplayFmtModel")]
CheckDisplayFmt,
#[strum(serialize = "CopyInitStateModel")]
CopyInitState,
#[strum(serialize = "CopyInitStateSingleModel")]
Expand Down
49 changes: 49 additions & 0 deletions kani-compiler/src/kani_middle/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,55 @@ fn implements_bounded_arbitrary(tcx: TyCtxt, ty: Ty, kani_bounded_any_def: FnDef
false
}

/// The formatting traits whose implementations automatic harnesses can verify via dedicated
/// models (c.f. `KaniModel::CheckDebugFmt`/`CheckDisplayFmt`).
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum FmtTrait {
Debug,
Display,
}

/// If `instance` is the `fmt` method of a `Debug` or `Display` implementation, return the
/// trait and the implementing (self) type. Such methods take a `&mut Formatter` argument that
/// cannot be generated nondeterministically; instead, the generated harness formats a
/// nondeterministic value of the self type into a discarding sink, which exercises `fmt`
/// through the core formatting machinery with a real `Formatter`.
///
/// Both the eligibility check (`automatic_harness_partition`) and the harness generation
/// (`AutomaticHarnessPass`) go through this function, so that they cannot disagree on whether a
/// given function is handled by the formatting models.
fn fmt_impl_self_ty(tcx: TyCtxt, instance: Instance) -> Option<(FmtTrait, Ty)> {
let def_id = rustc_internal::internal(tcx, instance.def.def_id());

// A `fmt` method carrying a function contract is out of scope: the automatic *contract*
// harness calls the function directly (and would therefore need a `Formatter`), and the
// formatting models reach `fmt` through a function pointer, where contract dispatch does
// not apply. Bail out so that such a function is reported as skipped for its
// `&mut Formatter` argument, just like any other function we cannot call.
if KaniAttributes::for_item(tcx, def_id).has_contract() {
return None;
}

let impl_def_id = tcx.trait_impl_of_assoc(def_id)?;
let trait_def_id = tcx.impl_trait_ref(impl_def_id).skip_binder().def_id;

let fmt_trait = if Some(trait_def_id) == tcx.get_diagnostic_item(rustc_span::sym::Debug) {
FmtTrait::Debug
} else if Some(trait_def_id) == tcx.get_diagnostic_item(rustc_span::sym::Display) {
FmtTrait::Display
} else {
return None;
};

// The `fmt` method's first input is `&Self`; peel the reference to obtain the
// (monomorphic) self type.
let sig = instance.ty().kind().fn_sig()?.skip_binder();
let TyKind::RigidTy(RigidTy::Ref(_, self_ty, _)) = sig.inputs().first()?.kind() else {
return None;
};
Some((fmt_trait, self_ty))
}

/// Is `ty` a struct or enum whose fields/variants implement Arbitrary, or a reference to such a
/// type?
fn can_derive_arbitrary(
Expand Down
55 changes: 53 additions & 2 deletions kani-compiler/src/kani_middle/transform/automatic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ use crate::kani_middle::kani_functions::{KaniHook, KaniIntrinsic, KaniModel};
use crate::kani_middle::transform::body::{InsertPosition, MutableBody, SourceInstruction};
use crate::kani_middle::transform::{TransformPass, TransformationType};
use crate::kani_middle::{
SmartPointerModels, can_derive_arbitrary, implements_arbitrary, implements_invariant,
smart_pointer_model_instance,
FmtTrait, SmartPointerModels, can_derive_arbitrary, fmt_impl_self_ty, implements_arbitrary,
implements_invariant, smart_pointer_model_instance,
};
use crate::kani_queries::QueryDb;
use rustc_data_structures::fx::FxHashMap;
Expand Down Expand Up @@ -650,6 +650,10 @@ impl AutomaticArbitraryPass {
pub struct AutomaticHarnessPass {
/// The Kani model functions used to construct nondeterministic values.
models: AnyModels,
/// The FnDef of KaniModel::CheckDebugFmt
kani_check_debug_fmt: FnDef,
/// The FnDef of KaniModel::CheckDisplayFmt
kani_check_display_fmt: FnDef,
init_contracts_hook: Instance,
reset_clause_depth: Instance,
kani_autoharness_intrinsic: FnDef,
Expand All @@ -660,6 +664,8 @@ impl AutomaticHarnessPass {
let kani_fns = query_db.kani_functions();
let kani_autoharness_intrinsic =
*kani_fns.get(&KaniIntrinsic::AutomaticHarness.into()).unwrap();
let kani_check_debug_fmt = *kani_fns.get(&KaniModel::CheckDebugFmt.into()).unwrap();
let kani_check_display_fmt = *kani_fns.get(&KaniModel::CheckDisplayFmt.into()).unwrap();
let init_contracts_hook = *kani_fns.get(&KaniHook::InitContracts.into()).unwrap();
let init_contracts_hook =
Instance::resolve(init_contracts_hook, &GenericArgs(vec![])).unwrap();
Expand All @@ -669,6 +675,8 @@ impl AutomaticHarnessPass {
Instance::resolve(reset_clause_depth, &GenericArgs(vec![])).unwrap();
Self {
models: AnyModels::new(query_db),
kani_check_debug_fmt,
kani_check_display_fmt,
init_contracts_hook,
reset_clause_depth,
kani_autoharness_intrinsic,
Expand Down Expand Up @@ -709,6 +717,49 @@ impl TransformPass for AutomaticHarnessPass {
harness_body.clear_body(TerminatorKind::Return);
let mut source = SourceInstruction::Terminator { bb: 0 };

// Debug/Display fmt implementations are exercised through the corresponding check
// model, which formats a nondeterministic value of the self type into a discarding
// sink: their `&mut Formatter` argument cannot be generated nondeterministically,
// and the model reaches `fn_to_verify` through the core formatting machinery with a
// real `Formatter`.
if let Some((fmt_trait, self_ty)) = fmt_impl_self_ty(tcx, fn_to_verify) {
// Generate `&self_ty` directly: `call_kani_any_for_ty` creates the nondeterministic
// value (assuming its safety invariant, if any) in a local of the harness body --
// which therefore outlives the model call -- and borrows it.
let ref_ty =
Ty::new_ref(Region { kind: RegionKind::ReErased }, self_ty, Mutability::Not);
let mut invariant_cache = FxHashMap::default();
let ref_lcl = call_kani_any_for_ty(
tcx,
self.models,
&mut harness_body,
ref_ty,
Mutability::Not,
&mut source,
&mut invariant_cache,
);
let model = match fmt_trait {
FmtTrait::Debug => self.kani_check_debug_fmt,
FmtTrait::Display => self.kani_check_display_fmt,
};
let model_inst =
Instance::resolve(model, &GenericArgs(vec![GenericArgKind::Type(self_ty)]))
.unwrap();
let ret_lcl = harness_body.new_local(
Ty::from_rigid_kind(RigidTy::Tuple(vec![])),
source.span(harness_body.blocks()),
Mutability::Not,
);
harness_body.insert_call(
&model_inst,
&mut source,
InsertPosition::Before,
vec![Operand::Move(Place::from(ref_lcl))],
Place::from(ret_lcl),
);
return (true, harness_body.into());
}

// Contract harnesses need a free(NULL) statement, c.f. kani_core::init_contracts().
//
// Order matters: `reset_contract_clause_depth` must execute BEFORE
Expand Down
36 changes: 36 additions & 0 deletions library/kani_core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,42 @@ macro_rules! kani_intrinsics {
T::any()
}

/// A [`core::fmt::Write`] sink that discards everything written to it, used by the
/// `check_debug_fmt`/`check_display_fmt` models below. Writing never fails, so `fmt`
/// implementations are not verified against the write-error path.
struct DiscardingSink;

impl core_path::fmt::Write for DiscardingSink {
fn write_str(&mut self, _s: &str) -> core_path::fmt::Result {
Ok(())
}
}

/// Exercise a type's `Debug` implementation by formatting a value into a sink that
/// discards the output. The `Formatter` is constructed by the core formatting
/// machinery, so it is always valid; panics or undefined behavior inside the `fmt`
/// implementation are detected as usual. Note that the `Formatter` carries the default
/// formatting parameters, i.e. paths that `fmt` takes only for a non-default width,
/// precision, fill, alignment, sign, or the alternate (`{:#?}`) flag are not covered.
///
/// This model is used by the compiler to generate automatic harnesses for `Debug::fmt`
/// implementations (`kani autoharness`), whose `&mut Formatter` argument cannot be
/// generated nondeterministically.
#[kanitool::fn_marker = "CheckDebugFmtModel"]
#[inline(never)]
#[doc(hidden)]
pub fn check_debug_fmt<T: core_path::fmt::Debug>(value: &T) {
let _ = core_path::fmt::write(&mut DiscardingSink, format_args!("{value:?}"));
}

/// Like [check_debug_fmt], but for `Display` implementations.
#[kanitool::fn_marker = "CheckDisplayFmtModel"]
#[inline(never)]
#[doc(hidden)]
pub fn check_display_fmt<T: core_path::fmt::Display>(value: &T) {
let _ = core_path::fmt::write(&mut DiscardingSink, format_args!("{value}"));
}

/// Creates a symbolic value *bounded* by `N`. Bounded means `|T| <= N`. The type
/// implementing BoundedArbitrary decides exactly what size means for them.
///
Expand Down
10 changes: 10 additions & 0 deletions tests/script-based-pre/cargo_autoharness_fmt_impls/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Copyright Kani Contributors
# SPDX-License-Identifier: Apache-2.0 OR MIT

[package]
name = "cargo_autoharness_fmt_impls"
version = "0.1.0"
edition = "2024"

[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(kani)'] }
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Copyright Kani Contributors
# SPDX-License-Identifier: Apache-2.0 OR MIT
script: fmt-impls.sh
expected: fmt-impls.expected
exit_code: 1
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
| cargo_autoharness_fmt_impls | <Borrowed<'_> as std::fmt::Debug>::fmt | Missing Arbitrary implementation for argument(s) self: Borrowed<'_> |
| cargo_autoharness_fmt_impls | <Contracted as std::fmt::Debug>::fmt | Missing Arbitrary implementation for argument(s) f: &mut std::fmt::Formatter<'_> |
| cargo_autoharness_fmt_impls | <NotGen as std::fmt::Debug>::fmt | Missing Arbitrary implementation for argument(s) self: NotGen |
Failed Checks: "invalid level"
Failed Checks: "invalid percent"
| cargo_autoharness_fmt_impls | <Derived as std::fmt::Debug>::fmt | #[kani::proof] | Success |
| cargo_autoharness_fmt_impls | <Even as std::fmt::Display>::fmt | #[kani::proof] | Success |
| cargo_autoharness_fmt_impls | <Safe as std::fmt::Display>::fmt | #[kani::proof] | Success |
| cargo_autoharness_fmt_impls | <Level as std::fmt::Display>::fmt | #[kani::proof] | Failure |
| cargo_autoharness_fmt_impls | <Percent as std::fmt::Debug>::fmt | #[kani::proof] | Failure |
Complete - 3 successfully verified functions, 2 failures, 5 total.
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#!/usr/bin/env bash
# Copyright Kani Contributors
# SPDX-License-Identifier: Apache-2.0 OR MIT

cargo kani autoharness -Z autoharness -Z function-contracts
Loading
Loading