Create an all zeros fw image

Creates an image bundle with FMC and Runtime populated with zeros. 0 is an ilegal opcode in risc-v, so the image will immediately NMI. This is useful for testing production signing infrastructure. A production key can be used to sign this image before an official release is ready. The prod-signed zeros binary is benign but can be used to ensure that the prod key was loaded into fuses correctly.
chipsalliance · Jan 15, 2025 · def0910 · def0910
1 parent 6f0a823
commit def0910
Show file tree

Hide file tree

Showing 11 changed files with 233 additions and 13 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -81,6 +81,7 @@ members = [
   "test",
   "test-harness",
   "test-harness/types",
+  "zero_bin",
 ]
 
 [workspace.dependencies]

diff --git a/builder/bin/image_gen.rs b/builder/bin/image_gen.rs
@@ -40,8 +40,9 @@ fn main() {
         .arg(arg!(--"fake-fw" [FILE] "Fake FW bundle image").value_parser(value_parser!(PathBuf)))
         .arg(
             arg!(--"hashes" [FILE] "File path for output JSON file containing image bundle header hashes for external signing tools")
-                .value_parser(value_parser!(PathBuf)),
+                .value_parser(value_parser!(PathBuf))
         )
+        .arg(arg!(--"zeros" "Build an image bundle with zero'd FMC and RT. This will NMI immediately."))
         .get_matches();
 
     if let Some(path) = args.get_one::<PathBuf>("rom-no-log") {
@@ -72,18 +73,33 @@ fn main() {
 
     if let Some(path) = args.get_one::<PathBuf>("fw") {
         // Generate Image Bundle
-        let image = caliptra_builder::build_and_sign_image(
-            &firmware::FMC_WITH_UART,
-            &firmware::APP_WITH_UART,
-            ImageOptions {
-                fmc_version: version::get_fmc_version(),
-                app_version: version::get_runtime_version(),
-                fmc_svn,
-                app_svn,
-                ..Default::default()
-            },
-        )
-        .unwrap();
+        let image = if args.contains_id("zeros") {
+            caliptra_builder::build_and_sign_image(
+                &firmware::FMC_ZEROS,
+                &firmware::APP_ZEROS,
+                ImageOptions {
+                    fmc_version: 0,
+                    app_version: 0,
+                    fmc_svn: 0,
+                    app_svn: 0,
+                    ..Default::default()
+                },
+            )
+            .unwrap()
+        } else {
+            caliptra_builder::build_and_sign_image(
+                &firmware::FMC_WITH_UART,
+                &firmware::APP_WITH_UART,
+                ImageOptions {
+                    fmc_version: version::get_fmc_version(),
+                    app_version: version::get_runtime_version(),
+                    fmc_svn,
+                    app_svn,
+                    ..Default::default()
+                },
+            )
+            .unwrap()
+        };
 
         let contents = image.to_bytes().unwrap();
         std::fs::write(path, contents.clone()).unwrap();

diff --git a/builder/src/firmware.rs b/builder/src/firmware.rs
@@ -75,6 +75,18 @@ pub const APP_WITH_UART_FPGA: FwId = FwId {
     features: &["emu", "fips_self_test", "fpga_realtime"],
 };
 
+pub const APP_ZEROS: FwId = FwId {
+    crate_name: "caliptra-zeros",
+    bin_name: "caliptra-zeros",
+    features: &[],
+};
+
+pub const FMC_ZEROS: FwId = FwId {
+    crate_name: "caliptra-zeros",
+    bin_name: "caliptra-zeros",
+    features: &["fmc"],
+};
+
 pub mod caliptra_builder_tests {
     use super::*;
 
@@ -387,6 +399,8 @@ pub const REGISTERED_FW: &[&FwId] = &[
     &APP_WITH_UART,
     &APP_WITH_UART_FIPS_TEST_HOOKS,
     &APP_WITH_UART_FPGA,
+    &APP_ZEROS,
+    &FMC_ZEROS,
     &caliptra_builder_tests::FWID,
     &hw_model_tests::MAILBOX_RESPONDER,
     &hw_model_tests::MAILBOX_SENDER,

diff --git a/libcaliptra/src/caliptra_api.c b/libcaliptra/src/caliptra_api.c
@@ -353,6 +353,36 @@ bool caliptra_ready_for_firmware(void)
     return true;
 }
 
+/**
+ * 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)
+{
+    uint32_t status;
+    bool ready = false;
+
+    do
+    {
+        status = caliptra_read_status();
+
+        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;
+        }
+        else
+        {
+            caliptra_wait();
+        }
+    } while (ready == false);
+
+    return true;
+}
+
 /*
 * caliptra_is_csr_ready
 *

diff --git a/zero_bin/Cargo.toml b/zero_bin/Cargo.toml
@@ -0,0 +1,23 @@
+# Licensed under the Apache-2.0 license
+
+[package]
+name = "caliptra-zeros"
+version = "0.1.0"
+edition = "2021"
+
+[build-dependencies]
+caliptra_common = { workspace = true, default-features = false }
+caliptra-gen-linker-scripts.workspace = true
+cfg-if.workspace = true
+
+[dev-dependencies]
+caliptra-api.workspace = true
+caliptra-builder.workspace = true
+caliptra-error.workspace = true
+caliptra-hw-model.workspace = true
+
+[features]
+default = ["std"]
+std = ["caliptra_common/std"]
+riscv = []
+fmc = []
diff --git a/zero_bin/build.rs b/zero_bin/build.rs
@@ -0,0 +1,37 @@
+fn main() {
+    cfg_if::cfg_if! {
+        if #[cfg(not(feature = "std"))] {
+            use std::env;
+            use std::fs;
+            use std::path::PathBuf;
+            use caliptra_gen_linker_scripts::gen_memory_x;
+
+            let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+
+            cfg_if::cfg_if! {
+                if #[cfg(feature = "fmc")] {
+                    fs::write(out_dir.join("memory.x"),gen_memory_x(caliptra_common::FMC_ORG, caliptra_common::FMC_SIZE)
+                    .as_bytes())
+                    .expect("Unable to generate memory.x");
+                } else {
+                    fs::write(out_dir.join("memory.x"),gen_memory_x(caliptra_common::RUNTIME_ORG, caliptra_common::RUNTIME_SIZE)
+                    .as_bytes())
+                    .expect("Unable to generate memory.x");
+                }
+            }
+
+            fs::write(out_dir.join("link.x"), include_bytes!("src/link.x")).unwrap();
+
+            let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+
+            println!("cargo:rustc-link-search={}", out_dir.display());
+
+            println!("cargo:rerun-if-changed=memory.x");
+            println!("cargo:rustc-link-arg=-Tmemory.x");
+
+            println!("cargo:rerun-if-changed=link.x");
+            println!("cargo:rustc-link-arg=-Tlink.x");
+            println!("cargo:rerun-if-changed=build.rs");
+        }
+    }
+}
diff --git a/zero_bin/src/link.x b/zero_bin/src/link.x
@@ -0,0 +1,14 @@
+SECTIONS
+{
+  .text : ALIGN(4)
+  {
+      _stext = .;
+
+      KEEP(*(.init .init.*));
+      *(.text .text.*);
+      KEEP(*(.vectors))
+
+      . = ALIGN(4);
+      _etext = .;
+  } > REGION_TEXT
+}
diff --git a/zero_bin/src/main.rs b/zero_bin/src/main.rs
@@ -0,0 +1,15 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(not(feature = "std"), no_main)]
+
+#[cfg(target_arch = "riscv32")]
+core::arch::global_asm!(include_str!("zeros.S"));
+
+#[cfg(feature = "std")]
+pub fn main() {}
+
+// Should not be linked
+#[cfg(not(feature = "std"))]
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
diff --git a/zero_bin/src/zeros.S b/zero_bin/src/zeros.S
@@ -0,0 +1,19 @@
+.section .init.text, "ax"
+.global _start
+_start:
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
+  .word 0
diff --git a/zero_bin/tests/test_zeros.rs b/zero_bin/tests/test_zeros.rs
@@ -0,0 +1,38 @@
+// Licensed under the Apache-2.0 license
+
+use caliptra_api::soc_mgr::SocManager;
+use caliptra_builder::{
+    firmware::{APP_ZEROS, FMC_ZEROS},
+    ImageOptions,
+};
+use caliptra_error::CaliptraError;
+use caliptra_hw_model::{BootParams, HwModel, InitParams};
+
+#[test]
+fn test_zeros() {
+    let rom = caliptra_builder::rom_for_fw_integration_tests().unwrap();
+    let init_params = InitParams {
+        rom: &rom,
+        ..Default::default()
+    };
+
+    let image =
+        caliptra_builder::build_and_sign_image(&FMC_ZEROS, &APP_ZEROS, ImageOptions::default())
+            .unwrap();
+
+    let mut model = caliptra_hw_model::new(
+        init_params,
+        BootParams {
+            fw_image: Some(&image.to_bytes().unwrap()),
+            ..Default::default()
+        },
+    )
+    .unwrap();
+
+    // 0 is an ilegal instruction in risc-v. Image should immediately NMI.
+    model.step_until(|m| m.soc_ifc().cptra_fw_error_fatal().read() != 0);
+    assert_eq!(
+        model.soc_ifc().cptra_fw_error_fatal().read(),
+        u32::from(CaliptraError::ROM_GLOBAL_EXCEPTION)
+    );
+}