Add ready_for_runtime API

Add API that waits until RT firmware is ready to receive commands. Additionally: * Fix the ready_for_firmware documentation to clarify that it will wait until the bit is set or an error. * Update both APIs to check for fatal errors
chipsalliance · Feb 6, 2025 · cf170c1 · cf170c1
1 parent 951209a
commit cf170c1
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 8 deletions.
diff --git a/libcaliptra/examples/generic/test.c b/libcaliptra/examples/generic/test.c
@@ -402,6 +402,13 @@ int rt_test_all_commands(const test_info* info)
         printf("FW Load: OK\n");
     }
 
+    status = caliptra_ready_for_runtime();
+    if (status) {
+        printf("Firmware Boot Failed: 0x%x\n", status);
+        dump_caliptra_error_codes();
+        failure = 1;
+    }
+
     // GET_IDEV_CERT
     struct caliptra_get_idev_cert_req idev_cert_req = {};
     struct caliptra_get_idev_cert_resp idev_cert_resp;

diff --git a/libcaliptra/inc/caliptra_api.h b/libcaliptra/inc/caliptra_api.h
@@ -40,8 +40,25 @@ bool caliptra_ready_for_fuses(void);
 //          STILL_READY_FOR_FUSES   - Flow status still indicates ready for fuses after writing fuse done
 int caliptra_init_fuses(const struct caliptra_fuses *fuses);
 
-// Query if ROM is ready for firmware
-bool caliptra_ready_for_firmware(void);
+/**
+ * caliptra_ready_for_firmware
+ *
+ * Waits until Caliptra hardware is ready for firmware upload or until
+ * Caliptra reports an error
+ *
+ * @return bool True if ready, false otherwise
+ */
+uint32_t caliptra_ready_for_firmware(void);
+
+/**
+ * caliptra_ready_for_runtime
+ *
+ * Waits until Caliptra hardware is ready for runtime commands or until
+ * Caliptra reports an error
+ *
+ * @return int 0 if ready, Caliptra error otherwise
+ */
+uint32_t caliptra_ready_for_runtime(void);
 
 // Read the value of the caliptra FW non-fatal error code
 // returns: Caliptra error code (see error/src/lib.rs)

diff --git a/libcaliptra/src/caliptra_api.c b/libcaliptra/src/caliptra_api.c
@@ -327,20 +327,27 @@ uint32_t caliptra_read_fw_fatal_error()
 /**
  * caliptra_ready_for_firmware
  *
- * Reports if the Caliptra hardware is ready for firmware upload
+ * Waits until Caliptra hardware is ready for firmware upload or until
+ * Caliptra reports an error
  *
  * @return bool True if ready, false otherwise
  */
-bool caliptra_ready_for_firmware(void)
+uint32_t caliptra_ready_for_firmware(void)
 {
     uint32_t status;
+    uint32_t fatal_error;
     bool ready = false;
 
     do
     {
         status = caliptra_read_status();
+        fatal_error = caliptra_read_fw_fatal_error();
 
-        if ((status & GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK) == GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK)
+        if (fatal_error != 0)
+        {
+            return fatal_error;
+        }
+        else if ((status & GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK) == GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK)
         {
             ready = true;
         }
@@ -350,7 +357,7 @@ bool caliptra_ready_for_firmware(void)
         }
     } while (ready == false);
 
-    return true;
+    return 0;
 }
 
 /**
@@ -364,13 +371,19 @@ bool caliptra_ready_for_firmware(void)
 uint32_t caliptra_ready_for_runtime(void)
 {
     uint32_t status;
+    uint32_t fatal_error;
     bool ready = false;
 
     do
     {
         status = caliptra_read_status();
+        fatal_error = caliptra_read_fw_fatal_error();
 
-        if ((status & GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK) == GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_FW_MASK)
+        if (fatal_error != 0)
+        {
+            return fatal_error;
+        }
+        else if ((status & GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_RUNTIME_MASK) == GENERIC_AND_FUSE_REG_CPTRA_FLOW_STATUS_READY_FOR_RUNTIME_MASK)
         {
             ready = true;
         }
@@ -380,7 +393,7 @@ uint32_t caliptra_ready_for_runtime(void)
         }
     } while (ready == false);
 
-    return true;
+    return 0;
 }
 
 /*