[otbn] Document LOOP/LOOPI error conditions
Signed-off-by: Rupert Swarbrick <rswarbrick@lowrisc.org>
diff --git a/hw/ip/otbn/data/base-insns.yml b/hw/ip/otbn/data/base-insns.yml
index 5073c70..777d5b1 100644
--- a/hw/ip/otbn/data/base-insns.yml
+++ b/hw/ip/otbn/data/base-insns.yml
@@ -442,15 +442,19 @@
type: uimm+1
doc: Number of instructions in the loop body
straight-line: false
- note: &loop-note |
- The LOOP and LOOPI instructions are under-specified, and improvements
- to them are being discussed. See
- https://github.com/lowRISC/opentitan/issues/2496 for up-to-date
- information.
doc: |
Repeats a sequence of code multiple times. The number of iterations is
read from `grs`, treated as an unsigned value. The number of
instructions in the loop is given in the `bodysize` immediate.
+
+ The `LOOP` instruction doesn't support a zero iteration count.
+ If the value in `grs` is zero, OTBN stops with the `ErrCodeLoop` error.
+ Starting a loop pushes an entry on to the loop stack.
+ If the stack is already full, OTBN stops with the `ErrCodeLoop` error.
+
+ There are also conditions on the code inside a loop.
+ A `LOOP`, `LOOPI`, jump or branch instruction may not appear as the last instruction in a loop.
+ OTBN will stop on that instruction with the `ErrCodeLoop` error.
encoding:
scheme: loop
mapping:
@@ -465,12 +469,18 @@
doc: Number of iterations
- *bodysize-operand
straight-line: false
- note: *loop-note
doc: |
Repeats a sequence of code multiple times. The `iterations`
unsigned immediate operand gives the number of iterations and
the `bodysize` unsigned immediate operand gives the number of
instructions in the body.
+
+ Starting a loop pushes an entry on to the loop stack.
+ If the stack is already full, OTBN stops with the `ErrCodeLoop` error.
+
+ There are also conditions on the code inside a loop.
+ A `LOOP`, `LOOPI`, jump or branch instruction may not appear as the last instruction in a loop.
+ OTBN will stop on that instruction with the `ErrCodeLoop` error.
encoding:
scheme: loopi
mapping:
diff --git a/hw/ip/otbn/doc/_index.md b/hw/ip/otbn/doc/_index.md
index e3e7ecb..b47f7c7 100644
--- a/hw/ip/otbn/doc/_index.md
+++ b/hw/ip/otbn/doc/_index.md
@@ -356,9 +356,10 @@
### Loop Stack
-The LOOP instruction allows for nested loops; the active loops are stored on the loop stack.
-Each loop stack entry is a tuple of loop count, start address, and end address.
-The number of entries in the loop stack is implementation-dependent.
+OTBN has two instructions for hardware-assisted loops: [`LOOP`]({{< relref "hw/ip/otbn/doc/isa#loop" >}}) and [`LOOPI`]({{< relref "hw/ip/otbn/doc/isa#loopi" >}}).
+Both use the same state for tracking control flow.
+This is a stack of tuples containing a loop count, start address and end address.
+The stack has a maximum depth of eight and the top of the stack is the current loop.
# Theory of Operations
