Add spec for Wait-on-Reservation-Set Instructions (#640)

Spec for extension Zawrs instructions (#224)
- `wrs.nto`
- `wrs.sto`

Author: sudo-abdullah

arch/inst/Zawrs/wrs.nto.yaml

@@ -3,11 +3,44 @@
 $schema: "inst_schema.json#"
 kind: instruction
 name: wrs.nto
-long_name: No synopsis available
+long_name: Wait-on-Reservation-Set-with-No-Timeout
 description: |
-  No description available.
+  -id: inst-wrs.nto-behaviour
+  -normative: false
+  -text: |
+    To mitigate the wasteful looping in such usages, a `wrs.nto` (WRS-with-no-timeout) instruction is provided.
+    Instead of polling for a store to a specific memory location, software registers a reservation set that
+    includes all the bytes of the memory location using the LR instruction. Then a subsequent `wrs.nto`
+    instruction would cause the hart to temporarily stall execution in a low-power state until a store
+    occurs to the reservation set or an interrupt is observed.
+
+    This instruction is not supported in a constrained LR/SC loop.
+    While stalled, an implementation is permitted to occasionally terminate the stall and complete
+    execution for any reason.
+
+    `wrs.nto` follows the rules of the WFI instruction for resuming execution
+    on a pending interrupt.
+
+    When the TW (Timeout Wait) bit in `mstatus` is set and `wrs.nto` is executed
+    in any privilege mode otherthan M mode, and it does not complete within an implementation-specific
+    bounded time limit, the `wrs.nto` instruction will cause an illegal instruction exception.
+
+    When executing in VS or VU mode, if the VTW bit is set in `hstatus`, the TW bit in `mstatus` is clear,
+    and the `wrs.nto` does not complete within an implementation-specific bounded time limit,
+    the `wrs.nto` instruction will cause a virtual instruction exception.
+
+    [Note]
+    Since `wrs.nto` can complete execution for reasons other than stores to the reservation set,
+    software will likely need a means of looping until the required stores have occurred.
+
+    [Note]
+    `wrs.nto`, unlike WFI, is not specified to cause an illegal instruction exception if executed in U-mode
+    when the governing TW bit is 0. WFI is typically not expected to be used in U-mode and on many systems
+    may promptly cause an illegal instruction exception if used at U-mode.
+    Unlike WFI, `wrs.nto` is expected to be used by software in U-mode when waiting on memory but without
+    a deadline for that wait.
 definedBy: Zawrs
-assembly: wrs_nto
+assembly: ""
 encoding:
   match: "00000000110100000000000001110011"
   variables: []

arch/inst/Zawrs/wrs.sto.yaml

@@ -3,11 +3,40 @@
 $schema: "inst_schema.json#"
 kind: instruction
 name: wrs.sto
-long_name: No synopsis available
+long_name: Wait-on-Reservation-Set-with-Short-Timeout
 description: |
-  No description available.
+  -id: inst-wrs.sto-behaviour
+  -normative: false
+  -text: |
+    Instead of polling for a store to a specific memory location, software registers a
+    reservation set that includes all the bytes of the memory location using the LR instruction.
+    A subsequent `wrs.sto` instruction would cause the hart to temporarily stall execution in a
+    low-power state until a store occurs to the reservation set or an interrupt is observed.
+    Sometimes the program waiting on a memory update may also need to carry out a task at a future time
+    or otherwise place an upper bound on the wait. To support such use cases, `wrs.sto` bounds the
+    stall duration to an implementation-define short timeout such that the stall is terminated on the
+    timeout if no other conditions have occurred to terminate the stall. The program using this instruction
+    may then determine if its deadline has been reached.
+    `wrs.sto` causes the hart to temporarily stall execution in a low-power state as long as the reservation
+    set is valid and no pending interrupts, even if disabled, are observed. For `wrs.sto` the stall duration
+    is bounded by an implementation defined short timeout. These instructions are not supported in a
+    constrained LR/SC loop.
+    Hart execution may be stalled while the following conditions are all satisfied:
+    a. The reservation set is valid
+    b. If `wrs.sto`, a "short" duration since start of stall has not elapsed
+    c. No pending interrupt is observed (see the rules below)
+
+    While stalled, an implementation is permitted to occasionally terminate the stall and complete
+    execution for any reason. `wrs.sto` follows the rules of the WFI instruction for resuming execution
+    on a pending interrupt. Since `wrs.sto` can complete execution for reasons other than stores to
+    the reservation set, software will likely need a means of looping until the required stores have occurred.
+
+    [Note]
+    The duration of a `wrs.sto` instruction's timeout may vary significantly within and among implementations.
+    In typical implementations this duration should be roughly in the range of 10 to 100 times an on-chip
+    cache miss latency or a cacheless access to main memory.
 definedBy: Zawrs
-assembly: wrs_sto
+assembly: ""
 encoding:
   match: "00000001110100000000000001110011"
   variables: []