Merge pull request #718 from jannic/rand-docs

Add a short explanation on how to use RingOscillator as a random number source

rp2040-hal/Cargo.toml

@@ -50,6 +50,7 @@ rp2040-boot2 = "0.3.0"
 hd44780-driver = "0.4.0"
 pio-proc = "0.2.0"
 dht-sensor = "0.2.1"
+rand = { version = "0.8.5", default-features = false }
 
 [features]
 # Minimal startup / runtime for Cortex-M microcontrollers

rp2040-hal/src/rosc.rs

@@ -1,6 +1,18 @@
 //! Ring Oscillator (ROSC)
-// See [Chapter 2 Section 17](https://datasheets.raspberrypi.org/rp2040/rp2040_datasheet.pdf) for more details
-
+//!
+//! See [Chapter 2 Section 17](https://datasheets.raspberrypi.org/rp2040/rp2040_datasheet.pdf) for more details
+//!
+//! In addition to its obvious role as a clock source, [`RingOscillator`] can also be used as a random number source
+//! for the [`rand`] crate:
+//!
+//! ```no_run
+//! # let mut pac = rp2040_pac::Peripherals::take().unwrap();
+//! use rp2040_hal::rosc::RingOscillator;
+//! use rand::Rng;
+//! let mut rnd = RingOscillator::new(pac.ROSC).initialize();
+//! let random_value: u32 = rnd.gen();
+//! ```
+//! [`rand`]: https://docs.rs/rand
 use fugit::HertzU32;
 
 use crate::{pac::ROSC, typelevel::Sealed};