[otbn] Specify the KMAC interface

This adapts the current simulator-only KMAC interface specification such that the new dynamic
KMAC app interface can be used.

Signed-off-by: Pascal Etterli <pascal.etterli@lowrisc.org>

Author: etterli

hw/ip/otbn/README.md

@@ -29,6 +29,7 @@ See that document for integration overview within the broader top level system.
 * Full control-flow support with conditional branch and unconditional jump instructions, hardware loops, and hardware-managed call/return stacks.
 * Reduced, security-focused instruction set architecture for easier verification and the prevention of data leaks.
 * Built-in access to random numbers.
+* CSR / WSR based interface to KMAC HWIP to offload hashing operations.
 
 ## Description
 
@@ -378,10 +379,10 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
     <tr>
       <td>0x7D9</td>
       <td>RW</td>
-      <td>KMAC_IF_STATUS</td>
+      <td>KMAC_STATUS</td>
       <td>
-        Write a 1 to bits 1 or 2 to clear the error bits.
-        KMAC_IF_STATUS is a CSR that exposes status information for the OTBN-KMAC interface.
+        KMAC_STATUS exposes status information for the OTBN-KMAC interface.
+        All fields are read only except CTRL_ERROR, MSG_WRITE_ERROR, and RSP_ERROR, which are W1C.
         <table>
           <thead>
             <tr><th>Bit</th><th>Description</th></tr>
@@ -390,29 +391,35 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
             <tr>
               <td>0</td>
               <td>
-                MSG_WRITE_RDY indicates whether the KMAC_DATA_S0/1 WSR is ready for the next word.
+                READY indicates whether the interface is ready to accept a command and/or new data in KMAC_DATA_S0/1.
               </td>
             </tr>
             <tr>
               <td>1</td>
               <td>
-                MSG_SEND_ERROR (W1C) indicates whether an error occurred after issuing a message send command.
+                CTRL_ERROR indicates whether a command was issued while the interface was not ready for it or the command violates the order. The command(s) raising this error are ignored. Is cleared (W1C) when SW writes a 1 to it.
               </td>
             </tr>
             <tr>
               <td>2</td>
               <td>
-                MSG_WRITE_ERROR (W1C) indicates whether an error occurred after writing to the KMAC_DATA_S0/1 WSR.
+                MSG_WRITE_ERROR indicates whether a write to KMAC_DATA_S0/1 occurred while the interface was not ready to accept new message data. Is cleared (W1C) when SW writes a 1 to it.
               </td>
             </tr>
             <tr>
               <td>3</td>
               <td>
-                DIGEST_VALID indicates whether the 64 bit word in KMAC_DATA_S0/1 WSR is valid.
+                RSP_VALID indicates that the lowest 64 bit words in KMAC_DATA_S0/1 contain valid data (actual digest data is only valid if RSP_ERROR is not 1). Is cleared once KMAC_DATA_S0 and KMAC_DATA_S1 have been read.
               </td>
             </tr>
             <tr>
-              <td>31:4</td>
+              <td>4</td>
+              <td>
+                RSP_ERROR is set to 1 and held when a response is received that signals an error on the KMAC HWIP side. If 1, all received digest data (incl. previously received) must be considered as invalid. Is cleared (W1C) when SW writes a 1 to it.
+              </td>
+            </tr>
+            <tr>
+              <td>31:5</td>
               <td>
                 Reserved. Always reads as 0. Any write is ignored.
               </td>
@@ -424,9 +431,10 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
     <tr>
       <td>0x7DA</td>
       <td>RW</td>
-      <td>KMAC_INTR</td>
+      <td>KMAC_CTRL</td>
       <td>
-        KMAC_INTR is a CSR that exposes the KMAC_ERROR interrupt of the KMAC HWIP.
+        The KMAC control register is used to control the KMAC interface.
+        Always reads as 0.
         <table>
           <thead>
             <tr><th>Bit</th><th>Description</th></tr>
@@ -435,141 +443,75 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
             <tr>
               <td>0</td>
               <td>
-                KMAC_ERROR (W1C) indicates whether an error occurred in the KMAC HWIP.
+                START: Writing 1 to this bit issues a START command.
               </td>
             </tr>
             <tr>
-              <td>31:1</td>
+              <td>1</td>
               <td>
-                Reserved. Always reads as 0. Any write is ignored.
+                SEND: Writing 1 to this bit starts sending the current message in KMAC_DATA_S0/1. If `KMAC_STRB` is partial (i.e. not all bytes are valid), issuing this command will simultaneously also send the PROCESS command.
               </td>
             </tr>
-          </tbody>
-        </table>
-      </td>
-    </tr>
-    <tr>
-      <td>0x7DB</td>
-      <td>RW</td>
-      <td>KMAC_CFG</td>
-      <td>
-        A configuration register for the KMAC interface.
-        The encodings for the fields are equivalent to the encodings for the CFG_SHADOWED register in the KMAC HWIP.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
             <tr>
-              <td>0</td>
+              <td>2</td>
               <td>
-                KMAC_EN enables keyed operation in the KMAC HWIP (kmac_en = 0/1).
+                PROCESS: Writing 1 to this bit issues a PROCESS command. Can be issued to terminate the message phase if the last message is not a partial message (which will automatically trigger the PROCESS command).
               </td>
             </tr>
             <tr>
-              <td>3:1</td>
+              <td>3</td>
               <td>
-                STRENGTH allows OTBN to select the desired security strength (kstrength = L128 / L224 / L256 / L384 / L512).
+                DONE: Writing 1 to this bit issues a DONE command.
               </td>
             </tr>
             <tr>
-              <td>5:4</td>
+              <td>9:4</td>
               <td>
-                MODE allows OTBN to set the KMAC hashing mode (mode = SHAKE / cSHAKE / SHA3).
+                Reserved. Any write is ignored. Always reads as 0.
               </td>
             </tr>
             <tr>
-              <td>31:6</td>
+              <td>10</td>
               <td>
-                Reserved. Always reads as 0. Any write is ignored.
+                EN_XOF enables the eXtendable Output Function (XOF) operation. If 1, XOF operation is enabled and the KMAC HWIP will automatically trigger a RUN command once the full rate has been pushed. If 0, KMAC HWIP will only push the first rate, and no other digest will be produced. Usually enabled for SHAKE and cSHAKE and disabled for SHA3 and KMAC modes.
               </td>
             </tr>
-          </tbody>
-        </table>
-      </td>
-    </tr>
-    <tr>
-      <td>0x7DC</td>
-      <td>RW</td>
-      <td>KMAC_MSG_SEND</td>
-      <td>
-        A command register to send a message to KMAC.
-        Reads from this register always return a 0.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
             <tr>
-              <td>0</td>
+              <td>13:11</td>
               <td>
-                MSG_SEND can be set to send the contents of KMAC_DATA_S0 and KMAC_DATA_S1 to KMAC.
+                STRENGTH defines the security strength of the operation. Valid values are L128, L224, L256, L384, and L512. See KMAC HWIP for encoding of values. The selected value must be compatible with chosen mode (see corresponding standards).  If STRENGTH = L224 and MODE = SHA3, the digest size is not a multiple of 64 bits. As of this, in the last digest response (response 4) only the lower 32 bits contain valid data.
               </td>
             </tr>
             <tr>
-              <td>31:1</td>
+              <td>15:14</td>
               <td>
-                Reserved. Always reads as 0. Any write is ignored.
+                MODE defines the hashing mode. This can be SHA3, SHAKE, cSHAKE, or KMAC. See KMAC HWIP for encoding of values. Note, cSHAKE uses prefix from KMAC HWIP CSRs (configured by SW), and KMAC always uses hard coded "KMAC" prefix.
               </td>
             </tr>
-          </tbody>
-        </table>
-      </td>
-    </tr>
-    <tr>
-      <td>0x7DD</td>
-      <td>RW</td>
-      <td>KMAC_CMD</td>
-      <td>
-        The encodings for the commands are equivalent to the encodings for the CMD register in the KMAC HWIP.
-        Reads from this register always return a 0.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
             <tr>
-              <td>5:0</td>
+              <td>31:16</td>
               <td>
-                CMD is the KMAC command field used to issue START, PROCESS, RUN and DONE commands to KMAC.
-              </td>
-            </tr>
-            <tr>
-              <td>31:6</td>
-              <td>
-                Reserved. Always reads as 0. Any write is ignored.
+                Reserved. Any write is ignored.
               </td>
             </tr>
           </tbody>
         </table>
       </td>
     </tr>
     <tr>
-      <td>0x7DE</td>
+      <td>0x7DB</td>
       <td>RW</td>
-      <td>KMAC_BYTE_STROBE</td>
+      <td>KMAC_STRB</td>
       <td>
-        The input bytes of KMAC_DATA_S0/1 that are valid and should be consumed by KMAC.
+        Defines which of the bytes of KMAC_DATA_S0/1 are valid and should be sent towards the KMAC HWIP.
+        Each bit corresponds to one byte in KMAC_DATA_S0/1, with bit 0 corresponding to the least significant byte.
         <br>
-        For all message chunks except the final one, BYTE_STROBE must be programmed to all ones, indicating that all bytes in KMAC_DATA are valid. For the final message chunk, selected bits may be cleared to indicate unused bytes.
+        For all message chunks except the final one, BYTE_STROBE must be programmed to all ones, indicating that all bytes in KMAC_DATA are valid.
+        For the final message chunk, selected bits may be cleared to indicate unused bytes.
         Any cleared bits must correspond to the most-significant bytes only, that is, the mask must be contiguous, with no zero bit followed by a one at a higher significance.
-        This needs to be the case, because that's how SHA3 inside KMAC expects the data.
         If a non contiguous strobe is defined the behaviour is undefined.
         <br>
-        Reads from this register return the current configuration of the KMAC_BYTE_STROBE CSR.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>31:0</td>
-              <td>
-                BYTE_STROBE is the KMAC byte strobe field.
-              </td>
-            </tr>
-          </tbody>
-        </table>
+        Reads from this register return the current strobe.
       </td>
     </tr>
     <tr>
@@ -636,75 +578,6 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
         Reads never stall.
       </td>
     </tr>
-    <tr>
-      <td>0xFC2</td>
-      <td>RO</td>
-      <td>KMAC_STATUS</td>
-      <td>
-        Writes to this CSR are always ignored.
-        This CSR exposes the internal state of the SHA3 FSM within KMAC.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>0</td>
-              <td>
-                SHA3_IDLE indicates whether the SHA3 core is in the idle state.
-              </td>
-            </tr>
-            <tr>
-              <td>1</td>
-              <td>
-                SHA3_ABSORB indicates whether the SHA3 core is in the absorb state.
-              </td>
-            </tr>
-            <tr>
-              <td>2</td>
-              <td>
-                SHA3_SQUEEZE indicates whether the SHA3 core is in the squeeze state.
-              </td>
-            </tr>
-            <tr>
-              <td>31:3</td>
-              <td>
-                Reserved. Always reads as 0. Any write is ignored.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </td>
-    </tr>
-    <tr>
-      <td>0xFC3</td>
-      <td>RO</td>
-      <td>KMAC_ERROR</td>
-      <td>
-        Writes to this register are ignored.
-        This register exposes the error code from the KMAC HWIP ERR_CODE register.
-        No other information from the KMAC HWIP ERR_CODE register is exposed.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>7:0</td>
-              <td>
-                ERROR_CODE contains the error code coming directly from the KMAC HWIP.
-              </td>
-            </tr>
-            <tr>
-              <td>31:8</td>
-              <td>
-                Reserved. Always reads as 0. Any write is ignored.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </td>
-    </tr>
     <tr>
       <td>0xFCA</td>
       <td>RO</td>
@@ -870,16 +743,18 @@ All read-write (RW) WSRs are set to 0 when OTBN starts an operation (when 1 is w
       <td>RW</td>
       <td><a name="kmac-data-s0">KMAC_DATA_S0</a></td>
       <td>
-        KMAC_DATA_S0 is the first 256-bit share of the masked message or digest interface.
+        KMAC_DATA_S0 and KMAC_DATA_S1 are used to send message parts towards the KMAC HWIP as well as to receive the resulting digest.
         <br>
-        For masked operations, provide the first share here and the second share in KMAC_DATA_S1.
+        For sending message parts, i.e., when writing to the WSRs, the WSRs are 256-bit wide.
+        The message is sent towards the KMAC HWIP in 64-bit parts, starting with the least significant word.
+        To send a masked message, provide the first share in KMAC_DATA_S0 and the second share in KMAC_DATA_S1.
+        If no masking is required, set one share to the plaintext data and the other share to all-zeros.
         <br>
-        If masking is not required:
-        - Set this share to the plaintext data.
-        - Set the other share to all-zeros.
+        When receiving the digest, i.e., reading from the WSRs, the digest data is only 64-bit wide and is placed in the least significant 64 bits while the other bits read as `'0`.
+        If a valid response is present (indicated by KMAC_STATUS.RSP_VALID), once both KMAC_DATA_S0 and KMAC_DATA_S1 are read, the KMAC interface starts accepting the next digest part.
         <br>
-        The digest data is provided in chunks of 64 bits at a time.
-        For plaintext retrieval of the digest, software must XOR the values from KMAC_DATA_S0 and KMAC_DATA_S1.
+        The provided digest is always shared, even if no masking is used for the message.
+        To retrieve the plaintext digest, software must XOR the values from KMAC_DATA_S0 and KMAC_DATA_S1.
         <table>
           <thead>
             <tr><th>Bit</th><th>Description</th></tr>
@@ -906,35 +781,7 @@ All read-write (RW) WSRs are set to 0 when OTBN starts an operation (when 1 is w
       <td>RW</td>
       <td><a name="kmac-data-s1">KMAC_DATA_S1</a></td>
       <td>
-        KMAC_DATA_S1 is the second 256-bit share of the masked message or digest interface.
-        <br>
-        For masked operations, provide the second share here and the second share in KMAC_DATA_S0.
-        <br>
-        If masking is not required:
-        - Set this share to the plaintext data.
-        - Set the other share to all-zeros.
-        <br>
-        The digest data is provided in chunks of 64 bits at a time.
-        For plaintext retrieval of the digest, software must XOR the values from KMAC_DATA_S0 and KMAC_DATA_S1.
-        <table>
-          <thead>
-            <tr><th>Bit</th><th>Description</th></tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>63:0</td>
-              <td>
-                Write: Least significant word of the message share. Read: Current 64-bit word of the digest share.
-              </td>
-            </tr>
-            <tr>
-              <td>255:64</td>
-              <td>
-                Write: Words 1-3 of the message share. Read: Returns `0`. Digest shares are read out via the least significant word only.
-              </td>
-            </tr>
-          </tbody>
-        </table>
+        KMAC_DATA_S1 is the counterpart of KMAC_DATA_S0, see its documentation for details.
       </td>
     </tr>
     <tr>