[RTL][DOC] Update MCI RESET_RESON register and add HITLESS flows to spec

.github/workflow_metadata/pr_hash

@@ -1 +1 @@
-f296249f25954cc65cf93a09432e71795001f3d3bab56c4fb62334ebe0d274037a9122919b804fbb511f9198d2fb902b
+fedfb38a183d454fa845f640e41afbb8a87a31cc673148d45207baba319c1fe82e755bb523ee704ca01cd11565b6b230

.github/workflow_metadata/pr_timestamp

@@ -1 +1 @@
-1743812480
+1744043049

docs/CaliptraSSHardwareSpecification.md

@@ -1269,25 +1269,20 @@ MCU SRAM is accessible via DMI, see [DMI MCU SRAM Access](#dmi-mcu-sram-access)
 
 #### MCU Hitless Update Handshake
 
-The hitless flow is described in full in [Caliptra Top Spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates). This section is focused on the HW registers both Caliptra and MCU will used to complete the flow. 
+The hitless flow is described in full in [Caliptra Top Spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates). The [Caliptra SS Integration Spec](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSIntegrationSpecification.md#mci) contains all MCI warm reset and hitless update flows and restrictions. This section is focused on the HW registers both Caliptra and MCU will used to complete the flow. 
 
-1. While MCU is waiting for Caliptra to verify the image. MCU should use ```notif_cptra_mcu_reset_req_sts``` interrupt to know when Caliptra has cleared the EXEC Lock bit. MCU can either poll or enable the interrupt. 
-2. Caliptra clears FW_EXEC_CTL[2]
-3. MCU sees request from Caliptra and should clear the interrupt status bit then set ```RESET_REQUEST.mcu_req``` in MCI.
-4. MCI does an MCU halt req/ack handshake to ensure the MCU is idle.
-5. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
-6. Caliptra will gain access to MCU SRAM Updatable Execution Region and update the FW image
-7. Caliptra sets FW_EXEC_CTL[2]
-8. MCU is brought out of reset and checks MCI's ```RESET_REASON``` 
-9. If it is a FW update MCU jumps to MCU SRAM for execution
-
-MCI tracks two different hitless update types in ```RESET_RESON```. 
-
-| Hitless update type    | Description     |
+MCI tracks three different ```RESET_REASON``` in its register bank:
+| Reset type    | Description     |
 |------------------|------------------|
+|```WARM_RESET```| MCI reset cycle. MCU SRAM has FW image but need Caliptra interaction before jumping to the FW image.|
 | ```FW_BOOT_UPD_RESET```      | First hitless update since MCI warm reset. MCU SRAM needs full initialization.      | 
 | ```FW_HITLESS_UPD_RESET```      | Second or greater hitless update since MCI warm reset. MCU SRAM can be partially initialized since valid content still exists in the MCU SRAM from previous firmware.| 
 
+```WARM_RESET``` will be set by hardware when a warm reset occurs. It should be cleared by the Caliptra Core during a firmware boot or hitless update flow.
+
+```FW_BOOT_UPD_RESET``` and ```FW_HITLESS_UPD_RESET``` are typically set and cleared by the Caliptra Core during a firmware boot or hitless update flow. If Caliptra Core is not used in the design, the SoC needs to designate a different trusted entity to control these registers.
+
+```FW_EXEC_CTLR[2]``` is an input signal to the MCI and is sent as an interrupt (```notif_cptra_mcu_reset_req_sts```) to the MCU. This interrupt should be cleared by the MCU before the requested reset with ```RESET_REQUEST.req```. After a warm reset, setting ```FW_EXEC_CTRL[2]``` will trigger an interrupt to the MCU, indicating that the MCU should reset itself with ```RESET_REQUEST.req```. After the first MCU reset request, when this input signal is cleared, it triggers the interrupt. The MCU is held in reset until ```FW_EXEC_CTRL[2]``` is set, with a minimum reset time determined by the ```MIN_MCU_RST_COUNTER``` MCI parameter.
 
 ### MCI AXI Subordinate
 

docs/CaliptraSSIntegrationSpecification.md

@@ -75,7 +75,10 @@
     - [Mailbox FIXME waiting on Caliptra MBOX integration spec updates before doing this section](#mailbox-fixme-waiting-on-caliptra-mbox-integration-spec-updates-before-doing-this-section)
   - [Sequences : Reset, Boot,](#sequences--reset-boot)
     - [MCI Boot Sequencer](#mci-boot-sequencer)
-    - [MCU Hitless Patch Flow](#mcu-hitless-patch-flow)
+    - [MCU FW Update Flows](#mcu-fw-update-flows)
+      - [MCU FW Boot Update](#mcu-fw-boot-update)
+      - [MCU Hitless Update Update](#mcu-hitless-update-update)
+      - [MCU Warm Reset FW Update](#mcu-warm-reset-fw-update)
     - [Error Flows](#error-flows)
   - [How to test : Smoke \& more](#how-to-test--smoke--more-1)
   - [Other requirements](#other-requirements)
@@ -380,6 +383,7 @@ The `cptra_ss_reset_n` signal is the primary reset input for the Caliptra Subsys
      - The reset signal must be synchronized to the 200 MHz `cptra_ss_clk_i` clock to prevent metastability issues.
      - If the reset source is asynchronous, a synchronizer circuit must be used before connecting to the subsystem.
      - During SoC initialization, assert this reset signal until all subsystem clocks and required power domains are stable.
+     - It is **illegal** to only toggle ```cptra_ss_reset_n``` until both Caliptra and MCU have received at least one FW update. Failure to follow this requirement could cause them to execute out of an uninitialized SRAM.
 
 ### Power Good Signal 
 
@@ -1389,20 +1393,66 @@ The following table defines the order in which resets can get asserted. A "\>\>"
 | **mcu\_rst\_b** |  |  | N/A |  |
 | **cptra\_rst\_b** |  |  |  | N/A |
 
-### MCU Hitless Patch Flow
 
-Once both MCU and Caliptra have been brought up the MCI Boot Sequencer is in a “listening” state waiting for a MCU reset request. 
-
-To see the MCU Hitless Flow please see the following spec: [Caliptra Hitless Update Support](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates)
-
-MCI registers relevant to this flow are:
+### MCU FW Update Flows 
+The hitless flow is described in full in [Caliptra Top Spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-support-for-hitless-updates). The [Caliptra SS HW Spec](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#mcu-hitless-update-handshake) spec gives details about the registers used in theese flow. This section is meant to elaborate on how to use the given HW to meet the architectual spec.
 
+Registers relevant to these flows:
 - Caliptra
-   - SS_GENERIC_FW_EXEC_CTRL[0].go[2]
+   - ```SS_GENERIC_FW_EXEC_CTRL[0].go[2]```
 - MCI 
-   - RESET_STATUS.mcu
-   - MCU_RESET_REQ
-   - RESET_REASON
+   - ```RESET_STATUS.mcu```
+   - ```MCU_RESET_REQ```
+   - ```RESET_REASON```
+   - ```notif_cptra_mcu_reset_req_sts```
+
+#### MCU FW Boot Update
+
+First MCU FW Update after a Cold Reset.
+
+1. Out of Cold Boot Caliptra has access to MCU SRAM since ```FW_EXEC_CTRL[2]``` is reset to 0.
+2. MCU ROM should use ```notif_cptra_mcu_reset_req_sts``` interrupt to know when Caliptra has a FW image for MCU. MCU ROM can either poll or enable the interrupt. 
+3. Caliptra sets MCI's ```RESET_REASON.FW_BOOT_UPD_RESET``` and Caliptra's ```FW_EXEC_CTRL[2]``` indicating a FW image is ready for MCU in MCU SRAM.
+4. MCU sees request from Caliptra and shall clear the interrupt status.
+5. MCU sets ```RESET_REQUEST.mcu_req``` in MCI to request a reset.
+6. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
+7. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
+8. MCU is brought out of reset and checks MCI's ```RESET_REASON``` 
+9. MCU jumps to MCU SRAM
+
+#### MCU Hitless Update Update
+
+Subsequenc MCU FW Update after FW Boot Update.
+
+1. MCU FW should use ```notif_cptra_mcu_reset_req_sts``` interrupt to know when Caliptra has a FW image for MCU. MCU FW can either poll or enable the interrupt. 
+2. Caliptra clears ```FW_EXEC_CTRL[2]``` indicating a FW image is ready for MCU.
+3. MCU sees request from Caliptra and shall clear the interrupt status.
+4. MCU sets ```RESET_REQUEST.mcu_req``` in MCI to request a reset.
+5. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
+6. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
+7. Caliptra will gain access to MCU SRAM Updatable Execution Region and update the FW image.
+8. Caliptra sets ```RESET_REASON.FW_HITLESS_UPD_RESET```
+9. Caliptra sets ```FW_EXEC_CTRL[2]```
+10. MCU is brought out of reset and checks MCI's ```RESET_REASON``` 
+11. MCU jumps to MCU SRAM
+
+#### MCU Warm Reset FW Update 
+
+Caliptra SS reset toggle without powergood toggle. 
+
+**IMPORTANT** - Can only happen after both Caliptra Core and MCU have received at least one FW update. Otherwise only Cold Reset is allowed.
+1. MCU ROM comes out of reset and sees ```WARM_RESET```. It cannot jump to MCU SRAM since it is locked and needs Caliptra to unlock.
+2. MCU ROM brings Caliptra out of reset
+3. Caliptra sees Warm Reset and starts executing from its ICCM (SRAM image)
+4. Caliptra clears MCI's ```RESET_REASON.WARM_RESET``` and sets ```RESET_REASON.FW_BOOT_UPD_RESET```
+5. Caliptra sets ```FW_EXEC_CTRL[2]```
+6. MCU sees request from Caliptra and shall clear the interrupt status.
+7. MCU sets ```RESET_REQUEST.mcu_req``` in MCI to request a reset.
+8. MCI does an MCU halt req/ack handshake to ensure the MCU is idle
+9. MCI asserts MCU reset (min reset time for MCU is until MIN_MCU_RST_COUNTER overflows)
+10. MCU is brought out of reset and checks MCI's ```RESET_REASON``` 
+11. MCU jumps to MCU SRAM
+
 
 ### Error Flows
 

src/integration/test_suites/mcu_cptra_bringup/cptra_bringup.c

@@ -12,9 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+#include "soc_address_map.h"
 #include "caliptra_defines.h"
 #include "riscv_hw_if.h"
 #include "soc_ifc.h"
+#include "soc_ifc_ss.h"
 #include <stdint.h>
 #include "printf.h"
 #include "caliptra_isr.h"
@@ -102,6 +104,9 @@ void main () {
     VPRINTF(LOW, "FW: Wait for SoC to reset execute register\n");
     while((lsu_read_32(CLP_MBOX_CSR_MBOX_EXECUTE) & MBOX_CSR_MBOX_EXECUTE_EXECUTE_MASK) == 1);
 
+    VPRINTF(LOW, "FW: Setting MCI FW_BOOT_UPD\n");
+    cptra_axi_dword_write(SOC_MCI_TOP_MCI_REG_RESET_REASON, MCI_REG_RESET_REASON_FW_BOOT_UPD_RESET_MASK);
+
     // Set FW EXEC REGION LOCK to enable MCU SRAM check
     VPRINTF(LOW, "FW: Setting FW_EXEC_CTRL\n");
     lsu_write_32(CLP_SOC_IFC_REG_SS_GENERIC_FW_EXEC_CTRL_0, 0x4);

src/integration/test_suites/mcu_cptra_bringup/mcu_cptra_bringup.yml

@@ -3,5 +3,5 @@ seed: 1
 testname: mcu_cptra_bringup
 pre-exec: |
   echo "Running pre_exec for [mcu_cptra_bringup]"
-  CALIPTRA_ROOT=$CALIPTRA_SS_ROOT/third_party/caliptra-rtl make -f $CALIPTRA_SS_ROOT/third_party/caliptra-rtl/tools/scripts/Makefile CALIPTRA_INTERNAL_TRNG=0 TEST_DIR=$CALIPTRA_SS_ROOT/src/integration/test_suites/mcu_cptra_bringup TESTNAME=cptra_bringup program.hex
   make -f $CALIPTRA_SS_ROOT/tools/scripts/Makefile TESTNAME=mcu_cptra_bringup mcu_program.hex
+  CALIPTRA_ROOT=$CALIPTRA_SS_ROOT/third_party/caliptra-rtl make -f $CALIPTRA_SS_ROOT/third_party/caliptra-rtl/tools/scripts/Makefile CALIPTRA_INTERNAL_TRNG=0 AUX_LIB_DIR=$CALIPTRA_SS_ROOT/src/integration/test_suites/libs/soc_ifc_ss AUX_OFILES=soc_ifc_ss.o AUX_HEADER_FILES=$CALIPTRA_SS_ROOT/src/integration/test_suites/libs/soc_ifc_ss/soc_ifc_ss.h TEST_DIR=$CALIPTRA_SS_ROOT/src/integration/test_suites/mcu_cptra_bringup TESTNAME=cptra_bringup program.hex

src/integration/testbench/caliptra_ss_top_tb_services.sv

@@ -56,6 +56,7 @@ import tb_top_pkg::*;
     logic                       mailbox_data_val;
     logic                       mailbox_write;
     logic        [63:0]         mailbox_data;
+    logic        [63:0]         prev_mailbox_data;
 
     string                      abi_reg[32]; // ABI register names
 
@@ -118,9 +119,25 @@ import tb_top_pkg::*;
 
     integer fd, tp, el;
 
+    always @(negedge clk or negedge rst_l) begin
+        if(!rst_l) begin
+            prev_mailbox_data <= '0;
+        end
+        else begin
+            if( mailbox_data_val & mailbox_write) begin
+                prev_mailbox_data <= mailbox_data;
+            end
+        end
+
+    end
+
     always @(negedge clk) begin
         // console Monitor
         if( mailbox_data_val & mailbox_write) begin
+            if (prev_mailbox_data[7:0] inside {8'h0A,8'h0D}) begin
+                $fwrite(fd,"%0t - ", $time);
+                $write("%0t - ", $time);
+            end
             $fwrite(fd,"%c", mailbox_data[7:0]);
             $write("%c", mailbox_data[7:0]);
             if (mailbox_data[7:0] inside {8'h0A,8'h0D}) begin // CR/LF

src/mci/rtl/mci_boot_seqr.sv

@@ -40,8 +40,6 @@ import mci_pkg::*;
     input  logic caliptra_boot_go,
     input  logic mci_bootfsm_go,
     input  logic mcu_rst_req,
-    output logic fw_boot_upd_reset,     // First MCU reset request
-    output logic fw_hitless_upd_reset,  // Other MCU reset requests
     output logic mcu_reset_once, // Has MCU been reset before?
     output mci_boot_fsm_state_e boot_fsm,
 
@@ -79,8 +77,6 @@ logic cptra_rst_b_ff;
 logic mcu_rst_b_nxt;
 logic cptra_rst_b_nxt;
 
-logic fw_boot_upd_reset_nxt;     // First MCU reset request
-logic fw_hitless_upd_reset_nxt;  // Other MCU reset requests
 logic mcu_reset_once_nxt;
 
 logic mcu_cpu_halt_req_nxt;
@@ -142,8 +138,6 @@ always_ff @(posedge clk or negedge mci_rst_b) begin
         mcu_rst_b_ff                <= '0;
         cptra_rst_b_ff              <= '0;
         mcu_reset_once              <= '0;
-        fw_boot_upd_reset           <= '0;     
-        fw_hitless_upd_reset        <= '0;  
         min_mcu_rst_count_elapsed   <= '0;
         min_mcu_rst_count           <= '0;
     end
@@ -155,8 +149,6 @@ always_ff @(posedge clk or negedge mci_rst_b) begin
         mcu_rst_b_ff    <= mcu_rst_b_nxt;
         cptra_rst_b_ff  <= cptra_rst_b_nxt;
         mcu_reset_once  <= mcu_reset_once_nxt;
-        fw_boot_upd_reset <= fw_boot_upd_reset_nxt;     
-        fw_hitless_upd_reset <= fw_hitless_upd_reset_nxt;  
         min_mcu_rst_count_elapsed <= min_mcu_rst_count_elapsed_nxt;
         min_mcu_rst_count <= min_mcu_rst_count_nxt;       
     end
@@ -171,8 +163,6 @@ always_comb begin
     cptra_rst_b_nxt = cptra_rst_b_ff;
     mcu_reset_once_nxt  = mcu_reset_once;
     mcu_cpu_halt_req_nxt = 1'b0;
-    fw_boot_upd_reset_nxt = fw_boot_upd_reset;     
-    fw_hitless_upd_reset_nxt = fw_hitless_upd_reset;  
     unique case(boot_fsm)
         BOOT_IDLE: begin
             // Can only transition into IDLE on MCI reset
@@ -245,8 +235,6 @@ always_comb begin
         BOOT_WAIT_MCU_HALTED: begin
             if (mcu_cpu_halt_status_i) begin
                 boot_fsm_nxt        = BOOT_RST_MCU;
-                fw_boot_upd_reset_nxt   = !mcu_reset_once;
-                fw_hitless_upd_reset_nxt = mcu_reset_once;
             end
         end
         BOOT_RST_MCU: begin

src/mci/rtl/mci_reg.rdl

@@ -47,6 +47,10 @@ addrmap mci_reg {
         desc = "Indicates when there is a valid AXI request from MCU or SoC Config Agent AND the CAP_LOCK register is not set";
     } axi_mcu_req_or_mci_soc_config_req__cap_unlock;
 
+    signal {
+        desc = "Indicates when there is a valid AXI request from MCU or the SoC Config Agent.";
+    } axi_mcu_or_mcu_sram_config_req;
+
     // AXI Request + SS_CONFIG_DONE Signals
     signal {
         desc = "Indicates when there is a valid AXI request from MCU or the SoC Config Agent.";
@@ -139,12 +143,12 @@ addrmap mci_reg {
     reg {
         name = "Reset Reason";
         desc = "Indicates to ROM the originating cause for the PC to be reset to 0.
-                Firmware Update Reset indicator is reset by the warm reset.
+                Firmware Update Reset indicator is reset by the warm reset and updated by SW applying MCU FW updated.
                 Warm Reset indicator is reset by the cold reset.
                 [br]TAP Access [with debug intent set]: RO";
-        field {desc = "FW update reset has been executed for the second+ time since MCI reset"; sw=r; hw=rw; resetsignal = mci_rst_b;  } FW_HITLESS_UPD_RESET=0;
-        field {desc = "FW update reset has been executed first time since MCI reset"; sw=r; hw=rw; resetsignal = mci_rst_b;  } FW_BOOT_UPD_RESET=0;
-        field {desc = "Warm reset has been executed";      sw=r; hw=rw;          resetsignal = mci_pwrgood;} WARM_RESET=0;
+        field {desc = "FW update reset has been executed for the second+ time since MCI reset"; swwe = axi_mcu_or_mcu_sram_config_req; sw=rw; resetsignal = mci_rst_b;  } FW_HITLESS_UPD_RESET=0;
+        field {desc = "FW update reset has been executed first time since MCI reset";swwe = axi_mcu_or_mcu_sram_config_req;  sw=rw; resetsignal = mci_rst_b;  } FW_BOOT_UPD_RESET=0;
+        field {desc = "Warm reset has been executed";  swwe = axi_mcu_or_mcu_sram_config_req;    sw=rw; hw=rw; we;          resetsignal = mci_pwrgood;} WARM_RESET=0;
     } RESET_REASON;
 
     reg {

src/mci/rtl/mci_reg.sv

@@ -6381,10 +6381,10 @@ module mci_reg (
         automatic logic load_next_c;
         next_c = field_storage.RESET_REASON.FW_HITLESS_UPD_RESET.value;
         load_next_c = '0;
-
-        // HW Write
-        next_c = hwif_in.RESET_REASON.FW_HITLESS_UPD_RESET.next;
-        load_next_c = '1;
+        if(decoded_reg_strb.RESET_REASON && decoded_req_is_wr && hwif_in.axi_mcu_or_mcu_sram_config_req) begin // SW write
+            next_c = (field_storage.RESET_REASON.FW_HITLESS_UPD_RESET.value & ~decoded_wr_biten[0:0]) | (decoded_wr_data[0:0] & decoded_wr_biten[0:0]);
+            load_next_c = '1;
+        end
         field_combo.RESET_REASON.FW_HITLESS_UPD_RESET.next = next_c;
         field_combo.RESET_REASON.FW_HITLESS_UPD_RESET.load_next = load_next_c;
     end
@@ -6395,17 +6395,16 @@ module mci_reg (
             field_storage.RESET_REASON.FW_HITLESS_UPD_RESET.value <= field_combo.RESET_REASON.FW_HITLESS_UPD_RESET.next;
         end
     end
-    assign hwif_out.RESET_REASON.FW_HITLESS_UPD_RESET.value = field_storage.RESET_REASON.FW_HITLESS_UPD_RESET.value;
     // Field: mci_reg.RESET_REASON.FW_BOOT_UPD_RESET
     always_comb begin
         automatic logic [0:0] next_c;
         automatic logic load_next_c;
         next_c = field_storage.RESET_REASON.FW_BOOT_UPD_RESET.value;
         load_next_c = '0;
-
-        // HW Write
-        next_c = hwif_in.RESET_REASON.FW_BOOT_UPD_RESET.next;
-        load_next_c = '1;
+        if(decoded_reg_strb.RESET_REASON && decoded_req_is_wr && hwif_in.axi_mcu_or_mcu_sram_config_req) begin // SW write
+            next_c = (field_storage.RESET_REASON.FW_BOOT_UPD_RESET.value & ~decoded_wr_biten[1:1]) | (decoded_wr_data[1:1] & decoded_wr_biten[1:1]);
+            load_next_c = '1;
+        end
         field_combo.RESET_REASON.FW_BOOT_UPD_RESET.next = next_c;
         field_combo.RESET_REASON.FW_BOOT_UPD_RESET.load_next = load_next_c;
     end
@@ -6416,17 +6415,19 @@ module mci_reg (
             field_storage.RESET_REASON.FW_BOOT_UPD_RESET.value <= field_combo.RESET_REASON.FW_BOOT_UPD_RESET.next;
         end
     end
-    assign hwif_out.RESET_REASON.FW_BOOT_UPD_RESET.value = field_storage.RESET_REASON.FW_BOOT_UPD_RESET.value;
     // Field: mci_reg.RESET_REASON.WARM_RESET
     always_comb begin
         automatic logic [0:0] next_c;
         automatic logic load_next_c;
         next_c = field_storage.RESET_REASON.WARM_RESET.value;
         load_next_c = '0;
-
-        // HW Write
-        next_c = hwif_in.RESET_REASON.WARM_RESET.next;
-        load_next_c = '1;
+        if(decoded_reg_strb.RESET_REASON && decoded_req_is_wr && hwif_in.axi_mcu_or_mcu_sram_config_req) begin // SW write
+            next_c = (field_storage.RESET_REASON.WARM_RESET.value & ~decoded_wr_biten[2:2]) | (decoded_wr_data[2:2] & decoded_wr_biten[2:2]);
+            load_next_c = '1;
+        end else if(hwif_in.RESET_REASON.WARM_RESET.we) begin // HW Write - we
+            next_c = hwif_in.RESET_REASON.WARM_RESET.next;
+            load_next_c = '1;
+        end
         field_combo.RESET_REASON.WARM_RESET.next = next_c;
         field_combo.RESET_REASON.WARM_RESET.load_next = load_next_c;
     end