[PATCH v2] fault-inject: rust: add a Rust API for fault-injection

[PATCH v2] fault-inject: rust: add a Rust API for fault-injection

[Andreas Hindborg]

Add a way for Rust code to create fault-injection control points. The
control points can be attached to a configfs tree as default groups and
controlled from user space. On the kernel side, provide a `should_fail`
method to query if an operation should fail.

Cc: Akinobu Mita <akinobu.mita@gmail.com>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
This patch is a dependency for the rust null block driver fault
injection feature.
---
Changes in v2:
- Mark `should_fail` as `#[inline]` (Gary).
- Expand `should_fail` rustdoc to describe the `size` parameter,
  including the negative-`size` replenish semantics, and link to the
  fault injection documentation (Gary).
- Link to v1: https://msgid.link/20260215-rust-fault-inject-v1-1-6ec459cb5ccb@kernel.org

To: Miguel Ojeda <ojeda@kernel.org>
To: Boqun Feng <boqun@kernel.org>
To: Gary Guo <gary@garyguo.net>
To: Björn Roy Baron <bjorn3_gh@protonmail.com>
To: Benno Lossin <lossin@kernel.org>
To: Andreas Hindborg <a.hindborg@kernel.org>
To: Alice Ryhl <aliceryhl@google.com>
To: Trevor Gross <tmgross@umich.edu>
To: Danilo Krummrich <dakr@kernel.org>
Cc: linux-kernel@vger.kernel.org
Cc: rust-for-linux@vger.kernel.org
---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/fault_injection.rs  | 101 ++++++++++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |   2 +
 3 files changed, 104 insertions(+)

diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 446dbeaf0866..bfa5153d2ce8 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -57,6 +57,7 @@
 #include <linux/errname.h>
 #include <linux/ethtool.h>
 #include <linux/fdtable.h>
+#include <linux/fault-inject.h>
 #include <linux/file.h>
 #include <linux/firmware.h>
 #include <linux/fs.h>
diff --git a/rust/kernel/fault_injection.rs b/rust/kernel/fault_injection.rs
new file mode 100644
index 000000000000..4a9468536767
--- /dev/null
+++ b/rust/kernel/fault_injection.rs
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Fault injection capabilities infrastructure.
+//!
+//! This module provides a Rust API for the kernel fault injection framework.
+//! Fault injection allows simulation of failures in kernel code paths to test
+//! error handling.
+//!
+//! [`FaultConfig`] represents a fault injection control point that can be:
+//!
+//! - Attached to a configfs tree as a default group, allowing userspace control
+//!   of fault injection parameters.
+//! - Queried via [`FaultConfig::should_fail`] to determine if an operation
+//!   should be simulated as failing.
+//!
+//! Please see the [fault injection documentation] for details on configuring
+//! and using fault injection from userspace.
+//!
+//! C header: [`include/linux/fault-inject.h`](srctree/include/linux/fault-inject.h)
+//!
+//! [fault injection documentation]: srctree/Documentation/fault-injection/fault-injection.rst
+
+use crate::{prelude::*, types::Opaque};
+
+/// A fault injection control point.
+///
+/// This type wraps a `struct fault_config` from the C fault injection
+/// framework. It provides a way to create controllable fault injection points
+/// that can be configured via configfs.
+///
+/// When attached to a configfs subsystem as a default group, userspace can
+/// configure fault injection parameters through the configfs interface. The
+/// kernel code can then query [`FaultConfig::should_fail`] to determine
+/// whether to simulate a failure.
+///
+/// # Invariants
+///
+/// - `self.inner` is always a valid `struct fault_config`.
+#[pin_data]
+pub struct FaultConfig {
+    #[pin]
+    inner: Opaque<bindings::fault_config>,
+}
+
+impl FaultConfig {
+    /// Create a new [`FaultConfig`].
+    ///
+    /// If attached to a configfs group, this [`FaultConfig`] will appear as a directory named
+    /// `name`.
+    pub fn new(name: &CStr) -> impl PinInit<Self> + use<'_> {
+        pin_init!(Self {
+            // INVARIANT: `self.inner` is initialized in ffi_init.
+            inner <- Opaque::zeroed().chain(|inner| {
+                let ptr = inner.get();
+                // SAFETY: `ptr` points to a zeroed allocation and the second argument is null
+                // terminated string.
+                unsafe { bindings::fault_config_init( ptr, name.as_char_ptr()) };
+                Ok(())
+            }),
+        })
+    }
+}
+
+impl kernel::configfs::CDefaultGroup for FaultConfig {
+    fn group_ptr(&self) -> *mut bindings::config_group {
+        // SAFETY: By type invariant, `self.inner` is valid.
+        unsafe { &raw mut (*self.inner.get()).group }
+    }
+}
+
+impl FaultConfig {
+    /// Query for failure.
+    ///
+    /// Returns `true` if the operation should fail.
+    ///
+    /// `size` is the amount of the resource consumed by the operation. It is subtracted from the
+    /// configured `space` budget on each call, and failure injection is suppressed while `space` is
+    /// greater than `size`. For allocation-style users this is typically the number of bytes; users
+    /// that inject based on the number of operations performed pass `1`. A negative `size`
+    /// replenishes the `space` budget by `-size` (i.e. grows the budget) and suppresses the failure
+    /// for that call.
+    ///
+    /// See the `space` field in the [fault injection documentation] for
+    /// details.
+    ///
+    /// [fault injection documentation]: srctree/Documentation/fault-injection/fault-injection.rst
+    #[inline]
+    pub fn should_fail(&self, size: isize) -> bool {
+        // SAFETY: By type invariant, self is always valid.
+        let attr = unsafe { &raw const (*self.inner.get()).attr };
+
+        // SAFETY: By type invariant, self is always valid.
+        unsafe { bindings::should_fail(attr.cast_mut(), size) }
+    }
+}
+
+// SAFETY: FaultConfig can be used from any task.
+unsafe impl Send for FaultConfig {}
+
+// SAFETY: FaultConfig applies internal synchronization.
+unsafe impl Sync for FaultConfig {}
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index b72b2fbe046d..8ba0083139b6 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -67,6 +67,8 @@
 #[cfg(CONFIG_DRM = "y")]
 pub mod drm;
 pub mod error;
+#[cfg(all(CONFIG_FAULT_INJECTION, CONFIG_FAULT_INJECTION_CONFIGFS))]
+pub mod fault_injection;
 pub mod faux;
 #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
 pub mod firmware;

---
base-commit: 9e0898f1c0f134c6bad146ca8578f73c3e40ac0a
change-id: 20260215-rust-fault-inject-bc62f1083502
prerequisite-change-id: 20260215-configfs-c-default-groups-bdb0a44633a6:v2
prerequisite-patch-id: 03b8e71b79be89a73946f3c1f7248671c28ccd42

Best regards,
--  
Andreas Hindborg <a.hindborg@kernel.org>

Re: [PATCH v2] fault-inject: rust: add a Rust API for fault-injection

[Miguel Ojeda]

Hi Andreas,

Some quick comments scanning your patch diagonally since I was here
for something else.

On Fri, Jun 5, 2026 at 3:27 PM Andreas Hindborg <a.hindborg@kernel.org> wrote:
>
>  #include <linux/ethtool.h>
>  #include <linux/fdtable.h>
> +#include <linux/fault-inject.h>
>  #include <linux/file.h>

Please keep them sorted :)

> +// SAFETY: FaultConfig can be used from any task.

`FaultConfig`

> +        // SAFETY: By type invariant, self is always valid.

`self`

> +    /// Returns `true` if the operation should fail.

[`true`]

> +            // INVARIANT: `self.inner` is initialized in ffi_init.

I was going to say `ffi_init`, but there is no such call here. Isn't
it getting initialized by the C side? I guess this got copy-pasted
from somewhere else?

Cheers,
Miguel

Re: [PATCH v2] fault-inject: rust: add a Rust API for fault-injection

[Andreas Hindborg]

Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> writes:

> Hi Andreas,
>
> Some quick comments scanning your patch diagonally since I was here
> for something else.
>
> On Fri, Jun 5, 2026 at 3:27 PM Andreas Hindborg <a.hindborg@kernel.org> wrote:
>>
>>  #include <linux/ethtool.h>
>>  #include <linux/fdtable.h>
>> +#include <linux/fault-inject.h>
>>  #include <linux/file.h>
>
> Please keep them sorted :)
>
>> +// SAFETY: FaultConfig can be used from any task.
>
> `FaultConfig`
>
>> +        // SAFETY: By type invariant, self is always valid.
>
> `self`
>
>> +    /// Returns `true` if the operation should fail.
>
> [`true`]

Thanks, I'll correct these for next version.

>
>> +            // INVARIANT: `self.inner` is initialized in ffi_init.
>
> I was going to say `ffi_init`, but there is no such call here. Isn't
> it getting initialized by the C side? I guess this got copy-pasted
> from somewhere else?

Thanks for catching this, it is a stale comment. I was using
`Opaque::ffi_init` in an earlier version (pre v1, this was also present
in v1).


Best regards,
Andreas Hindborg