1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
//! True Random Number Generator (TRNG) driver for WS63.
//!
//! The WS63 TRNG generates true random numbers using physical entropy
//! sources (FRO — Free-Running Oscillator). Random data is read from
//! a FIFO register.
//!
//! # Usage
//!
//! ```ignore
//! let trng = Trng::new(peripherals.TRNG);
//! let random_word: u32 = trng.read_blocking().unwrap();
//! ```
use crate::peripherals::Trng;
/// TRNG error type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TrngError {
/// No data available in the FIFO.
NoData,
/// Timeout waiting for entropy generation.
Timeout,
}
/// True Random Number Generator driver.
pub struct TrngDriver<'d> {
_trng: Trng<'d>,
}
impl<'d> TrngDriver<'d> {
/// Create a new TRNG driver.
pub fn new(trng: Trng<'d>) -> Self {
Self { _trng: trng }
}
fn regs(&self) -> &'static ws63_pac::trng::RegisterBlock {
// SAFETY: PAC peripheral pointer is a static physical MMIO address, always valid
unsafe { &*Trng::ptr() }
}
/// Check if random data is ready in the FIFO.
pub fn data_ready(&self) -> bool {
self.regs().trng_fifo_ready().read().bits() & 0x01 != 0
}
/// Check if the TRNG generation is complete.
pub fn done(&self) -> bool {
self.regs().trng_fifo_ready().read().bits() & 0x02 != 0
}
/// Read a 32-bit random word from the TRNG FIFO.
///
/// Returns `Err(NoData)` if no data is available.
pub fn read(&self) -> Result<u32, TrngError> {
if !self.data_ready() {
return Err(TrngError::NoData);
}
Ok(self.regs().trng_fifo_data().read().bits())
}
/// Read a random word, blocking until data is available.
///
/// Returns `Err(Timeout)` if the TRNG fails to produce entropy after
/// ~4ms (1,000,000 spin-loop iterations at 240MHz). On cold start,
/// the FRO-based entropy source may need several attempts to stabilize;
/// retry the call if the first attempt times out.
pub fn read_blocking(&self) -> Result<u32, TrngError> {
for _ in 0..1_000_000 {
if self.data_ready() {
return Ok(self.regs().trng_fifo_data().read().bits());
}
core::hint::spin_loop();
}
Err(TrngError::Timeout)
}
/// Fill a buffer with random bytes.
///
/// Each 32-bit word produces 4 bytes. Returns `Err(Timeout)` if the TRNG
/// hardware fails to produce entropy.
pub fn fill_bytes(&self, buf: &mut [u8]) -> Result<(), TrngError> {
let mut i = 0;
while i < buf.len() {
let word = self.read_blocking()?;
let bytes = word.to_le_bytes();
for &b in &bytes {
if i < buf.len() {
buf[i] = b;
i += 1;
}
}
}
Ok(())
}
/// Fill a buffer with random 32-bit words.
///
/// Returns `Err(Timeout)` if the TRNG hardware fails to produce entropy.
pub fn fill_words(&self, buf: &mut [u32]) -> Result<(), TrngError> {
for word in buf.iter_mut() {
*word = self.read_blocking()?;
}
Ok(())
}
/// Select the FRO sample clock source.
///
/// * `external` — `true` for external clock, `false` for internal clock.
pub fn set_sample_clock(&mut self, external: bool) {
unsafe {
self.regs().trng_fro_sample_clk_sel().write(|w| w.bits(if external { 1 } else { 0 }));
}
}
/// Set the FRO divider count.
///
/// Controls the sampling rate of the FRO entropy source.
/// Default is 0x1b (27).
pub fn set_divider(&mut self, div: u8) {
unsafe {
self.regs().trng_fro_div_cnt().write(|w| w.bits(div as u32));
}
}
/// Get the data status register value (for debugging).
pub fn data_status(&self) -> u32 {
self.regs().trng_data_st().read().bits()
}
}
// ── Tests ──────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_trng_error_type_variants() {
assert_ne!(TrngError::NoData as u8, TrngError::Timeout as u8);
}
#[test]
fn test_trng_data_ready_bit() {
// data_ready checks fifo_ready bit 0
let ready: u32 = 0x01;
assert!((ready & 0x01) != 0); // data ready
let not_ready: u32 = 0x00;
assert!((not_ready & 0x01) == 0); // not ready
}
#[test]
fn test_trng_done_bit() {
// done checks fifo_ready bit 1
let done: u32 = 0x02;
assert!((done & 0x02) != 0); // generation done
let not_done: u32 = 0x00;
assert!((not_done & 0x02) == 0); // not done
}
#[test]
fn test_trng_read_blocking_timeout_logic() {
// Simulate the timeout loop: should return Err after retries exhausted
let max_retries = 10u32;
let mut data_ready = false;
let mut retries = 0;
let result = loop {
if data_ready {
break Ok(42u32);
}
if retries >= max_retries {
break Err(TrngError::Timeout);
}
retries += 1;
};
assert_eq!(result, Err(TrngError::Timeout));
assert_eq!(retries, 10);
}
#[test]
fn test_trng_read_blocking_success_first_try() {
let data_ready = true;
let result = if data_ready { Ok(0xDEAD_BEEFu32) } else { Err(TrngError::Timeout) };
assert_eq!(result.unwrap(), 0xDEAD_BEEF);
}
}