[otbn] Add URND/RND details to documentation
Signed-off-by: Greg Chadwick <gac@lowrisc.org>
diff --git a/hw/ip/otbn/doc/_index.md b/hw/ip/otbn/doc/_index.md
index 8d4777c..1f64a73 100644
--- a/hw/ip/otbn/doc/_index.md
+++ b/hw/ip/otbn/doc/_index.md
@@ -260,6 +260,27 @@
<td>
<strong>RND</strong>.
A random number.
+ The number is sourced from the EDN via a single-entry cache.
+ Reads when the cache is empty will cause OTBN to be stalled until a new random number is available.
+ </td>
+ </tr>
+ <tr>
+ <td>0xFC1</td>
+ <td>RW</td>
+ <td>
+ <strong>RND_PREFETCH</strong>.
+ Write to this CSR to begin a request to fill the RND cache.
+ Always reads as 0.
+ </td>
+ </tr>
+ <tr>
+ <td>0xFC2</td>
+ <td>R</td>
+ <td>
+ <strong>URND</strong>.
+ A random number.
+ The number is sourced from an LFSR.
+ Reads never stall.
</td>
</tr>
</tbody>
@@ -317,6 +338,8 @@
<td>R</td>
<td>
A random number.
+ The number is sourced from the EDN via a single-entry cache.
+ Reads when the cache is empty will cause OTBN to be stalled until a new random number is fetched from the EDN.
</td>
</tr>
<tr>
@@ -327,6 +350,16 @@
The accumulator register used by the BN.MULQACC instruction.
</td>
</tr>
+ <tr>
+ <td>0x3</td>
+ <td><strong>URND</strong></td>
+ <td>R</td>
+ <td>
+ A random number.
+ The number is sourced from an LFSR.
+ Reads never stall.
+ </td>
+ </tr>
</tbody>
</table>
@@ -393,6 +426,25 @@
A host processor can check whether OTBN is busy by reading the {{< regref "STATUS.busy">}} flag.
All memory accesses through the register interface must be word-aligned 32b word accesses.
+### Random Numbers
+
+OTBN is connected to the [Entropy Distribution Network (EDN)]({{< relref "hw/ip/edn/doc" >}}) which can provide random numbers via the `RND` and `URND` CSRs and WSRs.
+
+`RND` provides bits taken directly from the EDN.
+As an EDN request can take time, `RND` is backed by a single-entry cache containing the result of the most recent EDN request.
+A read from `RND` empties this cache.
+A prefetch into the cache, which can be used to hide the EDN latency, is triggered on any write to the `RND_PREFETCH` CSR.
+Writes to `RND_PREFETCH` will be ignored whilst a prefetch is in progress or when the cache is already full.
+OTBN will stall until the request provides bits.
+Both the `RND` CSR and WSR take their bits from the same cache.
+`RND` CSR reads simply discard the other 192 bits on a read.
+When stalling on an `RND` read, OTBN will unstall on the cycle after `otbn_core` receives WLEN RND data from the EDN.
+
+`URND` provides bits from an LFSR; reads from it never stall.
+The `URND` LFSR is seeded once from the EDN when OTBN starts execution.
+Each new execution of OTBN will reseed the `URND` LFSR.
+The LFSR state is advanced every cycle when OTBN is running.
+
### Error Handling and Reporting
By design, OTBN is a simple processor and provides no error handling support to code that runs on it.
