[kmac] Improve handling of manual PRNG reseeding requests

This commit modifies the design to latch manual PRNG reseeding requests
and to indicate the status of the PRNG via new bits in the status
register. This allows software to verify that a reseed request has
indeed been accepted and prevents the accidental dropping of such
requests in case they reach the PRNG while the SHA3 engine is busy.

Signed-off-by: Pirmin Vogel <vogelpi@lowrisc.org>

Author: vogelpi

hw/ip/kmac/data/kmac.hjson

@@ -676,7 +676,9 @@
                 Software can set this bit to 1 to manually trigger the reseeding of the internal PRNG when running in EDN mode.
                 This will also clear !!ENTROPY_REFRESH_HASH_CNT.
 
-                Note that the hardware may miss the trigger pulse if the module is not idle, or if the module is currently performing a reseed operation.
+                After setting this bit, the !!STATUS.entropy_ready bit should read as 0 and the !!STATUS.entropy_reseeding bit as 1 indicating that a reseed operation is ongoing.
+
+                If masking is disabled, this bit is ignored.
                 '''
         }
         { bits: "9"
@@ -715,6 +717,23 @@
                 In this stage, SW can manually run the hashing engine.
                 '''
         }
+        { bits: "4"
+          name: "entropy_ready"
+          desc: '''If 1, the internal PRNG is ready.
+                If 0, the internal PRNG is either not configured in EDN mode or software mode, or currently performing a reseed operation via EDN or waiting for software to provide a new seed.
+
+                If masking is disabled, this bit mirrors the !!CFG_SHADOWED.entropy_ready bit.
+                '''
+          resval: "0"
+        }
+        { bits: "5"
+          name: "entropy_reseeding"
+          desc: '''If 1, the internal PRNG is currently performing a reseed operation via EDN or waiting for software to provide a new seed.
+
+                If masking is disabled, this always reads as 0.
+                '''
+          resval: "0"
+        }
         { bits: "12:8"
           name: "fifo_depth"
           desc: "Count of occupied entries in the message FIFO."

hw/ip/kmac/doc/programmers_guide.md

@@ -94,18 +94,11 @@ If the value of [`ENTROPY_REFRESH_HASH_CNT`](registers.md#entropy_refresh_hash_c
 1. Ensure that the entropy complex is running.
 2. Check that the KMAC module is idle by reading the [`STATUS.sha3_idle`](registers.md#status--sha3_idle) bit.
 3. Trigger a manual reseed operation by setting the [`CMD.entropy_req`](registers.md#cmd--entropy_req) bit.
-4. Configure the module to process a message in cSHAKE mode (but not in KMAC mode).
-   More precisely, set [`CFG_SHADOWED.mode`](registers.md#cfg_shadowed--mode) to `0x3` and [`CFG_SHADOWED.kmac_en`](registers.md#cfg_shadowed--kmac_en) to 0.
-5. Configure the module to use the PRNG and block any hashing operation if the PRNG is not ready by setting [`CFG_SHADOWED.entropy_fast_process`](registers.md#cfg_shadowed--entropy_fast_process) to 0.
-6. Send the `start` command to the [`CMD`](registers.md#cmd) register.
-   The SHA3 engine will start loading and hashing the function name `N` and the customization string `S` first.
-7. Send the `process` command to the [`CMD`](registers.md#cmd) register.
-8. Wait for the [`STATUS.sha3_squeeze`](registers.md#status--sha3_squeeze) bit to get set.
-   Due to the ongoing reseed operation, the [`STATUS.sha3_squeeze`](registers.md#status--sha3_squeeze) bit should remain 0 for an extended period of time.
-9. Send the `done` command to the [`CMD`](registers.md#cmd) register to finish processing.
+4. Wait for the [`STATUS.entropy_reseeding`](registers.md#status--entropy_reseeding) bit to get set.
+   Due to the ongoing reseed operation, the [`STATUS.entropy_reseeding`](registers.md#status--entropy_reseeding) bit should remain 1 for an extended period of time.
+5. Wait for the [`STATUS.entropy_reseeding`](registers.md#status--entropy_reseeding) bit to get cleared and the [`STATUS.entropy_ready`](registers.md#status--entropy_ready) bit to get set.
 
 The [`ENTROPY_REFRESH_HASH_CNT`](registers.md#entropy_refresh_hash_cnt) register should now read as 0.
-Note however that if the manual reseed operation is triggered while the KMAC module is busy, the reseed operation may get skipped despite the hash counter being cleared back to 0.
 
 
 #### Checking Message FIFO depth before pushing data

hw/ip/kmac/doc/registers.md

@@ -369,7 +369,9 @@ Software can set this bit to 1 to manually clear [`ENTROPY_REFRESH_HASH_CNT.`](#
 Software can set this bit to 1 to manually trigger the reseeding of the internal PRNG when running in EDN mode.
 This will also clear [`ENTROPY_REFRESH_HASH_CNT.`](#entropy_refresh_hash_cnt)
 
-Note that the hardware may miss the trigger pulse if the module is not idle, or if the module is currently performing a reseed operation.
+After setting this bit, the [`STATUS.entropy_ready`](#status) bit should read as 0 and the [`STATUS.entropy_reseeding`](#status) bit as 1 indicating that a reseed operation is ongoing.
+
+If masking is disabled, this bit is ignored.
 
 ### CMD . cmd
 Issue a command to the KMAC/SHA3 IP. The command is sparse
@@ -389,12 +391,12 @@ Other values are reserved.
 KMAC/SHA3 Status register.
 - Offset: `0x1c`
 - Reset default: `0x4001`
-- Reset mask: `0x3df07`
+- Reset mask: `0x3df37`
 
 ### Fields
 
 ```wavejson
-{"reg": [{"name": "sha3_idle", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_absorb", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_squeeze", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 5}, {"name": "fifo_depth", "bits": 5, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_full", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_FATAL_FAULT", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_RECOV_CTRL_UPDATE_ERR", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 14}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}
+{"reg": [{"name": "sha3_idle", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_absorb", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_squeeze", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "entropy_ready", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "entropy_reseeding", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 2}, {"name": "fifo_depth", "bits": 5, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_full", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_FATAL_FAULT", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_RECOV_CTRL_UPDATE_ERR", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 14}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}
 ```
 
 |  Bits  |  Type  |  Reset  | Name                                                                |
@@ -406,7 +408,10 @@ KMAC/SHA3 Status register.
 |   14   |   ro   |   0x1   | [fifo_empty](#status--fifo_empty)                                   |
 |   13   |        |         | Reserved                                                            |
 |  12:8  |   ro   |    x    | [fifo_depth](#status--fifo_depth)                                   |
-|  7:3   |        |         | Reserved                                                            |
+|  7:6   |        |         | Reserved                                                            |
+|   5    |   ro   |   0x0   | [entropy_reseeding](#status--entropy_reseeding)                     |
+|   4    |   ro   |   0x0   | [entropy_ready](#status--entropy_ready)                             |
+|   3    |        |         | Reserved                                                            |
 |   2    |   ro   |    x    | [sha3_squeeze](#status--sha3_squeeze)                               |
 |   1    |   ro   |    x    | [sha3_absorb](#status--sha3_absorb)                                 |
 |   0    |   ro   |   0x1   | [sha3_idle](#status--sha3_idle)                                     |
@@ -444,6 +449,17 @@ See the "Message FIFO" section in the spec for the reason.
 ### STATUS . fifo_depth
 Count of occupied entries in the message FIFO.
 
+### STATUS . entropy_reseeding
+If 1, the internal PRNG is currently performing a reseed operation via EDN or waiting for software to provide a new seed.
+
+If masking is disabled, this always reads as 0.
+
+### STATUS . entropy_ready
+If 1, the internal PRNG is ready.
+If 0, the internal PRNG is either not configured in EDN mode or software mode, or currently performing a reseed operation via EDN or waiting for software to provide a new seed.
+
+If masking is disabled, this bit mirrors the [`CFG_SHADOWED.entropy_ready`](#cfg_shadowed) bit.
+
 ### STATUS . sha3_squeeze
 If 1, SHA3 completes sponge absorbing stage.
 In this stage, SW can manually run the hashing engine.

hw/ip/kmac/dv/env/kmac_env_pkg.sv

@@ -123,6 +123,8 @@ package kmac_env_pkg;
     KmacStatusSha3Idle = 0,
     KmacStatusSha3Absorb = 1,
     KmacStatusSha3Squeeze = 2,
+    KmacStatusEntropyReady = 4,
+    KmacStatusEntropyReseeding = 5,
     KmacStatusFifoDepthLSB = 8,
     KmacStatusFifoDepthMSB = 12,
     KmacStatusFifoEmpty = 14,

hw/ip/kmac/dv/env/kmac_scoreboard.sv

@@ -79,6 +79,10 @@ class kmac_scoreboard extends cip_base_scoreboard #(.CFG_T(kmac_env_cfg),
   bit sha3_absorb;
   bit sha3_squeeze;
 
+  // PRNG status bits
+  bit status_entropy_ready;
+  bit status_entropy_reseeding;
+
   // FIFO status bits
   bit cmd_process_triggered;
   bit msgfifo_access;
@@ -966,6 +970,8 @@ class kmac_scoreboard extends cip_base_scoreboard #(.CFG_T(kmac_env_cfg),
           exp_status[KmacStatusSha3Absorb]  = sha3_absorb;
           exp_status[KmacStatusSha3Squeeze] = sha3_squeeze;
 
+          exp_status[KmacStatusEntropyReady]     = status_entropy_ready;
+          exp_status[KmacStatusEntropyReseeding] = status_entropy_reseeding;
 
           void'(ral.status.predict(.value(exp_status), .kind(UVM_PREDICT_READ)));
 
@@ -1837,9 +1843,15 @@ class kmac_scoreboard extends cip_base_scoreboard #(.CFG_T(kmac_env_cfg),
 
   function void set_entropy_fetch(bit val);
     if (val) begin
-      if (entropy_mode == EntropyModeEdn) in_edn_fetch = cfg.enable_masking;
+      if (entropy_mode == EntropyModeEdn) begin
+        in_edn_fetch = cfg.enable_masking;
+        status_entropy_reseeding = cfg.enable_masking;
+        status_entropy_ready = cfg.enable_masking ? 0 : entropy_ready;
+      end
     end else begin
       in_edn_fetch = 0;
+      status_entropy_reseeding = 0;
+      status_entropy_ready = 1;
       `uvm_info(`gfn, "dropped in_edn_fetch", UVM_HIGH)
     end
   endfunction

hw/ip/kmac/rtl/kmac.sv

@@ -306,6 +306,9 @@ module kmac
 
   prim_mubi_pkg::mubi4_t entropy_configured;
 
+  logic status_entropy_ready;
+  logic status_entropy_reseeding;
+
   // Message Masking
   logic msg_mask_en, cfg_msg_mask;
   logic [MsgWidth-1:0] msg_mask;
@@ -465,6 +468,9 @@ module kmac
   assign hw2reg.status.sha3_absorb.d   = sha3_fsm == sha3_pkg::StAbsorb;
   assign hw2reg.status.sha3_squeeze.d  = sha3_fsm == sha3_pkg::StSqueeze;
 
+  assign hw2reg.status.entropy_ready.d     = status_entropy_ready;
+  assign hw2reg.status.entropy_reseeding.d = status_entropy_reseeding;
+
   // FIFO related status
   assign hw2reg.status.fifo_depth.d[MsgFifoDepthW-1:0] = msgfifo_depth;
   if ($bits(hw2reg.status.fifo_depth.d) != MsgFifoDepthW) begin : gen_fifo_depth_tie
@@ -1308,6 +1314,8 @@ module kmac
       .hash_threshold_i (entropy_hash_threshold),
 
       .entropy_configured_o (entropy_configured),
+      .entropy_ready_o      (status_entropy_ready),
+      .entropy_reseeding_o  (status_entropy_reseeding),
 
       // LC escalation
       .lc_escalate_en_i (lc_escalate_en[5]),
@@ -1363,6 +1371,12 @@ module kmac
     // If Masking is off, always entropy configured
     assign entropy_configured = prim_mubi_pkg::MuBi4True;
 
+    // Mirror the entropy_ready bit written by software to simplify DV and software.
+    assign status_entropy_ready = reg2hw.cfg_shadowed.entropy_ready.q;
+
+    // No reseed operation is ever happening.
+    assign status_entropy_reseeding = 1'b 0;
+
     logic unused_edn_clk_rst;
     assign unused_edn_clk_rst = ^{clk_edn_i, rst_edn_ni};
 

hw/ip/kmac/rtl/kmac_entropy.sv

@@ -70,6 +70,8 @@ module kmac_entropy
   input        [HashCntW-1:0] hash_threshold_i,
 
   output prim_mubi_pkg::mubi4_t entropy_configured_o,
+  output logic                  entropy_ready_o,
+  output logic                  entropy_reseeding_o,
 
   // Life cycle
   input  lc_ctrl_pkg::lc_tx_t lc_escalate_en_i,
@@ -297,7 +299,6 @@ module kmac_entropy
 
   // Hash Counter
   logic threshold_hit;
-  logic threshold_hit_q, threshold_hit_clr; // latched hit
 
   logic hash_progress_d, hash_progress_q;
   always_ff @(posedge clk_i or negedge rst_ni) begin
@@ -337,15 +338,29 @@ module kmac_entropy
   assign threshold_hit = |hash_threshold_i && (hash_threshold_i <= hash_cnt_o);
 
   always_ff @(posedge clk_i or negedge rst_ni) begin
-    if (!rst_ni)                threshold_hit_q <= 1'b 0;
-    else if (threshold_hit_clr) threshold_hit_q <= 1'b 0;
-    else if (threshold_hit)     threshold_hit_q <= 1'b 1;
+    if (!rst_ni)         mode_q <= EntropyModeNone;
+    else if (mode_latch) mode_q <= mode_i;
   end
 
+  // EDN reseed triggering ====================================================
+  logic edn_trigger_clr;
+  logic edn_trigger_d, edn_trigger_q;
+
+  // The entropy_refresh_req_i input from software and the threshold_hit signal
+  // are both pulses. Latch them.
+  assign edn_trigger_d =
+      ((mode_q == EntropyModeEdn) &&
+          (entropy_refresh_req_i || threshold_hit)) ? 1'b1 :
+      edn_trigger_clr                               ? 1'b0 : edn_trigger_q;
+
   always_ff @(posedge clk_i or negedge rst_ni) begin
-    if (!rst_ni)         mode_q <= EntropyModeNone;
-    else if (mode_latch) mode_q <= mode_i;
+    if (!rst_ni) begin
+      edn_trigger_q <= 1'b0;
+    end else begin
+      edn_trigger_q <= edn_trigger_d;
+    end
   end
+  // EDN reseed triggering ----------------------------------------------------
 
   // PRNG primitive ===========================================================
 
@@ -497,7 +512,7 @@ module kmac_entropy
     timer_enable = 1'b 0;
     timer_update = 1'b 0;
 
-    threshold_hit_clr = 1'b 0;
+    edn_trigger_clr = 1'b 0;
 
     // rand is valid when this logic expands the entropy.
     // FSM sets the valid signal, the signal is cleared by `consume` signal
@@ -521,6 +536,10 @@ module kmac_entropy
     data_update = 1'b 0;
     aux_update = 1'b 0;
 
+    // Status
+    entropy_ready_o     = 1'b 0;
+    entropy_reseeding_o = 1'b 0;
+
     // Error
     err_o = '{valid: 1'b 0, code: ErrNone, info: '0};
 
@@ -570,6 +589,8 @@ module kmac_entropy
 
         prng_en = prng_en_rand_q[0];
 
+        entropy_ready_o = 1'b 1;
+
         if ((rand_update_i || rand_consumed_i) &&
             ((fast_process_i && in_keyblock_i) || !fast_process_i)) begin
           // If fast_process is set, don't clear the rand valid, even
@@ -586,17 +607,13 @@ module kmac_entropy
           end else begin
             st_d = StRandReady;
           end
-        end else if ((mode_q == EntropyModeEdn) &&
-            (entropy_refresh_req_i || threshold_hit_q)) begin
+        end else if (edn_trigger_q) begin
           // Start reseeding the PRNG via EDN.
           seed_en = 1'b 1;
           st_d = StRandEdn;
 
           // Timer reset
           timer_update = 1'b 1;
-
-          // Clear the threshold as it refreshes the hash
-          threshold_hit_clr = 1'b 1;
         end else begin
           st_d = StRandReady;
         end
@@ -609,6 +626,9 @@ module kmac_entropy
         // Wait timer
         timer_enable = 1'b 1;
 
+        // Status
+        entropy_reseeding_o = 1'b 1;
+
         if (timer_expired && non_zero_wait_timer_limit) begin
           // If timer count is non-zero and expired;
           st_d = StRandErrWaitExpired;
@@ -617,6 +637,7 @@ module kmac_entropy
           seed_ack = 1'b 1;
 
           if (seed_done) begin
+            edn_trigger_clr = 1'b 1;
             st_d = StRandGenerate;
 
             if ((fast_process_i && in_keyblock_i) || !fast_process_i) begin
@@ -648,6 +669,9 @@ module kmac_entropy
         // Forward ack driven by software.
         seed_ack = seed_req & seed_update_i;
 
+        // Status
+        entropy_reseeding_o = 1'b 1;
+
         if (seed_done) begin
           st_d = StRandGenerate;
 
@@ -678,6 +702,8 @@ module kmac_entropy
         rand_valid_set = 1'b 1;
         prng_en = prng_en_rand_q[0];
 
+        entropy_ready_o = 1'b 1;
+
         st_d = StRandReady;
       end
 

hw/ip/kmac/rtl/kmac_reduced.sv

@@ -82,6 +82,8 @@ module kmac_reduced
 
   // Entropy status signals
   output prim_mubi_pkg::mubi4_t entropy_configured_o,
+  output logic                  entropy_ready_o,
+  output logic                  entropy_reseeding_o,
   input  logic [HashCntW-1:0]   entropy_hash_threshold_i, // drive to max
   input  logic                  entropy_hash_clr_i,       // drive to 0
   output logic [HashCntW-1:0]   entropy_hash_cnt_o,
@@ -298,6 +300,8 @@ module kmac_reduced
     .hash_cnt_o      (entropy_hash_cnt_o),
 
     .entropy_configured_o(entropy_configured_o),
+    .entropy_ready_o     (entropy_ready_o),
+    .entropy_reseeding_o (entropy_reseeding_o),
 
     // LC escalation
     .lc_escalate_en_i(lc_escalate_en[1]),

hw/ip/kmac/rtl/kmac_reg_pkg.sv

@@ -218,6 +218,12 @@ package kmac_reg_pkg;
     struct packed {
       logic [4:0]  d;
     } fifo_depth;
+    struct packed {
+      logic        d;
+    } entropy_reseeding;
+    struct packed {
+      logic        d;
+    } entropy_ready;
     struct packed {
       logic        d;
     } sha3_squeeze;
@@ -259,9 +265,9 @@ package kmac_reg_pkg;
 
   // HW -> register type
   typedef struct packed {
-    kmac_hw2reg_intr_state_reg_t intr_state; // [62:57]
-    kmac_hw2reg_cfg_regwen_reg_t cfg_regwen; // [56:56]
-    kmac_hw2reg_status_reg_t status; // [55:44]
+    kmac_hw2reg_intr_state_reg_t intr_state; // [64:59]
+    kmac_hw2reg_cfg_regwen_reg_t cfg_regwen; // [58:58]
+    kmac_hw2reg_status_reg_t status; // [57:44]
     kmac_hw2reg_entropy_refresh_hash_cnt_reg_t entropy_refresh_hash_cnt; // [43:33]
     kmac_hw2reg_err_code_reg_t err_code; // [32:0]
   } kmac_hw2reg_t;
@@ -338,6 +344,8 @@ package kmac_reg_pkg;
   parameter logic [10:0] KMAC_CMD_RESVAL = 11'h 0;
   parameter logic [17:0] KMAC_STATUS_RESVAL = 18'h 4001;
   parameter logic [0:0] KMAC_STATUS_SHA3_IDLE_RESVAL = 1'h 1;
+  parameter logic [0:0] KMAC_STATUS_ENTROPY_READY_RESVAL = 1'h 0;
+  parameter logic [0:0] KMAC_STATUS_ENTROPY_RESEEDING_RESVAL = 1'h 0;
   parameter logic [0:0] KMAC_STATUS_FIFO_EMPTY_RESVAL = 1'h 1;
   parameter logic [0:0] KMAC_STATUS_ALERT_FATAL_FAULT_RESVAL = 1'h 0;
   parameter logic [0:0] KMAC_STATUS_ALERT_RECOV_CTRL_UPDATE_ERR_RESVAL = 1'h 0;