Adds just enough support to allow device drivers to feed entropy to the
central pool.

Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Signed-off-by: Matthew Maurer <mmaurer@google.com>
---
Changes in v4:
- Adjusted documentation phrasing.
- Renamed module from `rand` to `random` to be more in line with the
  header name.
- Link to v3: https://lore.kernel.org/r/20251226-add-entropy-v3-1-a3440823a07d@google.com

Changes in v3:
- Fixed doclink to be srctree-based instead of relative.
- Switched to prelude import instead of fine-grained imports.
- Link to v2: https://lore.kernel.org/r/20251216-add-entropy-v2-1-4d866f251474@google.com

Changes in v2:
- Added more details in the docs about the API, specifically about it
  not crediting entropy and when it ought to be used.
- Link to v1: https://lore.kernel.org/r/20251212-add-entropy-v1-1-e70ad1bc9c65@google.com
---
 rust/kernel/lib.rs    |  1 +
 rust/kernel/random.rs | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index f812cf12004286962985a068665443dc22c389a2..c82e6747043e2472d6b5e4d9043fa8bc6d3c8434 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -130,6 +130,7 @@
 pub mod ptr;
 #[cfg(CONFIG_RUST_PWM_ABSTRACTIONS)]
 pub mod pwm;
+pub mod random;
 pub mod rbtree;
 pub mod regulator;
 pub mod revocable;
diff --git a/rust/kernel/random.rs b/rust/kernel/random.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a9b19698e09665696fef77b4486c4a1a20d0a42e
--- /dev/null
+++ b/rust/kernel/random.rs
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Randomness.
+//!
+//! C header: [`include/linux/random.h`](srctree/include/linux/random.h)
+
+use crate::prelude::*;
+
+/// Adds the given buffer to the entropy pool, but does not credit any entropy.
+///
+/// This function mixes in data that is likely to differ between devices or boots, but may
+/// otherwise be predictable. Examples include MAC addresses or RTC values. This slightly improves
+/// randomness in entropy-constrained environments (especially common for embedded devices).
+pub fn add_device_randomness(buf: &[u8]) {
+    // SAFETY: We just need the pointer to be valid for the length, which a slice provides.
+    unsafe { bindings::add_device_randomness(buf.as_ptr().cast::<c_void>(), buf.len()) };
+}

---
base-commit: 008d3547aae5bc86fac3eda317489169c3fda112
change-id: 20251029-add-entropy-f57e12ebe110

Best regards,
-- 
Matthew Maurer <mmaurer@google.com>

Hi,

Thanks for CCing me Miguel. I find it strange that it was left out on
apparently 4 revisions of it. Yes, this should be added to the
MAINTAINER's normal rng section. I'm happy to maintain this.

However...

On Tue, Dec 30, 2025 at 05:53:57PM +0000, Matthew Maurer wrote:
> Adds just enough support to allow device drivers to feed entropy to the
> central pool.
> [...]
> +/// This function mixes in data that is likely to differ between devices or boots, but may
> +/// otherwise be predictable. Examples include MAC addresses or RTC values. This slightly improves
> +/// randomness in entropy-constrained environments (especially common for embedded devices).

Small nit: There are two existing comments in the C source (one of which
I know you know about because your text is almost that text). Why not
just use those verbatim? Or improve those and sync that to here? I'm not
a big fan of bifurcation.

> +pub fn add_device_randomness(buf: &[u8]) {
> +    // SAFETY: We just need the pointer to be valid for the length, which a slice provides.
> +    unsafe { bindings::add_device_randomness(buf.as_ptr().cast::<c_void>(), buf.len()) };
> +}

Bigger question, perhaps for Miguel: what's the convention for adding
these bindings? Is it, (A) "this is a useful API surface, so let's add the
functions so driver writers can use them later" or is it (B) "add useful
APIs as they're needed by driver writers"?

If (A), then why only add one single function from include/linux/random.h?
Shouldn't you add them all?

If (B), then shouldn't this patch be in a series alongside code that
actually calls this one function that is added? Usually the kernel
doesn't add code "just for the sake of it". APIs need in-tree users.

I think case (B) is closer to what I'm used to seeing, but Rust is a
brave new world so maybe (A) is desirable for bootstrapping it. However,
this patch accomplishes neither (A) nor (B).

Jason

On Wed, Dec 31, 2025 at 1:48 PM Jason A. Donenfeld <Jason@zx2c4.com> wrote:
>
> Thanks for CCing me Miguel. I find it strange that it was left out on
> apparently 4 revisions of it. Yes, this should be added to the
> MAINTAINER's normal rng section. I'm happy to maintain this.

You're welcome, and thanks for the quick reply!

> Bigger question, perhaps for Miguel: what's the convention for adding
> these bindings? Is it, (A) "this is a useful API surface, so let's add the
> functions so driver writers can use them later" or is it (B) "add useful
> APIs as they're needed by driver writers"?

We follow the usual kernel practice, so (B), though sometimes a user
is known to be incoming, so it gets added in a separate series for
convenience or similar.

But, yeah, in such a case, it should be agreed upon / explained where
it is supposed to be used, and the cover letter here should do that
(and you are completely right to ask!).

Cheers,
Miguel

On Wed, Dec 31, 2025 at 7:46 AM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> On Wed, Dec 31, 2025 at 1:48 PM Jason A. Donenfeld <Jason@zx2c4.com> wrote:
> >
> > Thanks for CCing me Miguel. I find it strange that it was left out on
> > apparently 4 revisions of it. Yes, this should be added to the
> > MAINTAINER's normal rng section. I'm happy to maintain this.

Apologies for that, it's my mistake.

>> Small nit: There are two existing comments in the C source (one of which
>> I know you know about because your text is almost that text). Why not
>> just use those verbatim? Or improve those and sync that to here? I'm not
>> a big fan of bifurcation.

It does not need to be different. I'll use it verbatim in the next revision.

>
> You're welcome, and thanks for the quick reply!
>
> > Bigger question, perhaps for Miguel: what's the convention for adding
> > these bindings? Is it, (A) "this is a useful API surface, so let's add the
> > functions so driver writers can use them later" or is it (B) "add useful
> > APIs as they're needed by driver writers"?
>
> We follow the usual kernel practice, so (B), though sometimes a user
> is known to be incoming, so it gets added in a separate series for
> convenience or similar.
>
> But, yeah, in such a case, it should be agreed upon / explained where
> it is supposed to be used, and the cover letter here should do that
> (and you are completely right to ask!).

I'll add it to the cover letter in the next revision, but for now, the
use case is a re-implementation of the qcom-socinfo driver[1] (still
undergoing significant revision) which uses it to deliver the contents
of the SoC info buffer (which notably includes the device serial
number) to the entropy pool.

[1]: https://lore.kernel.org/all/20251213-qcom-socinfo-v1-1-5daa7f5f2a85@google.com/

>
> Cheers,
> Miguel

On Tue, Dec 30, 2025 at 6:54 PM Matthew Maurer <mmaurer@google.com> wrote:
>
>  rust/kernel/random.rs | 17 +++++++++++++++++

We should add this to either "RANDOM NUMBER DRIVER" or add a new
`MAINTAINERS` entry (as a sub-entry of that one, or perhaps of the
Rust one), depending on what the maintainers prefer.

RANDOM NUMBER DRIVER (Ted, Jason) was not Cc'd, so I am doing it here.

Thanks!

Cheers,
Miguel