[hw] Integrate KMAC and enabled ROM scrambling

Integrate KMAC hardware block for use with the ROM checker only.
No other KMAC interfaces are connected.

Modify the SW build system to generate a scrambled boot-ROM image.
Attempting to run an un-scrambled image will be blocked by the
in-hardware ROM checker.

Add minimal HJSON files required for ROM image scrambling script.
These use the OT testing secrets for now.

Author: elliotb-lowrisc

doc/ref/dev_guide.md

@@ -116,6 +116,9 @@ cmake --build build/sw -j $(nproc)
 
 Outputs with the suffix "_sram" exist only for UVM-based tests, as they presently lack a DRAM backdoor-load mechanism.
 
+The boot-ROM output with the "_scrambled" suffix is the only binary run through the ROM image scrambling script.
+Attempting to run any unscrambled binary from the scrambled ROM will be blocked by the in-hardware ROM checker.
+
 ### Code Quality
 
 For software written in C, `clang-format` and `clang-tidy` are used to format and lint the code.
@@ -138,7 +141,7 @@ To build and run a Verilator simulation of Mocha, run:
 # Build simulator.
 fusesoc --cores-root=. run --target=sim --tool=verilator --setup --build lowrisc:mocha:top_chip_verilator --verilator_options="-j 4 --threads 2 --trace-threads 2" --make_options="-j 4"
 # Run simulator.
-build/lowrisc_mocha_top_chip_verilator_0/sim-verilator/Vtop_chip_verilator -E build/sw/device/bootrom/bootrom -E build/sw/device/examples/hello_world
+build/lowrisc_mocha_top_chip_verilator_0/sim-verilator/Vtop_chip_verilator -r build/sw/device/bootrom/bootrom_scrambled.vmem -E build/sw/device/examples/hello_world
 ```
 
 Note that the `-j 4` arguments speed up simulator building, while the `--threads 2 --trace-threads 2` arguments speed up simulator running.
@@ -173,7 +176,7 @@ usermod -a -G plugdev $USER
 
 To build a bitstream with the boot-ROM, make sure that Vivado is on your path, then run:
 ```sh
-fusesoc --cores-root=. run --target=synth --setup --build lowrisc:mocha:chip_mocha_genesys2 --RomInitFile=$PWD/build/sw/device/bootrom/bootrom.vmem
+fusesoc --cores-root=. run --target=synth --setup --build lowrisc:mocha:chip_mocha_genesys2 --RomInitFile=$PWD/build/sw/device/bootrom/bootrom_scrambled.vmem
 # Nix alternative: `nix run .#bitstream-build`
 ```
 

hw/data/secrets.testing.hjson

@@ -0,0 +1,54 @@
+// Copyright lowRISC contributors (COSMIC Project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Minimal hand-crafted secrets config HJSON file for scrambled ROM generation.
+//
+// CRITICAL: CHANGE THE SECRET VALUES BELOW BEFORE ANY REAL-WORLD DEPLOYMENT!
+//
+{
+  module:
+  [
+    {
+      name: rom_ctrl
+      type: rom_ctrl
+      base_addrs:
+      {
+        rom:
+        {
+          hart: 0x00080000
+        }
+      }
+      memory:
+      {
+        rom:
+        {
+          size: 0x8000
+        }
+      }
+      param_list:
+      [
+        {
+          name: RndCnstScrNonce
+          desc: Fixed nonce used for address / data scrambling
+          type: bit [63:0]
+          randcount: 64
+          randtype: data
+          name_top: RndCnstRomCtrlScrNonce
+          default: 0xd35500e5a51bba34
+          randwidth: 64
+        }
+        {
+          name: RndCnstScrKey
+          desc: Randomised constant used as a scrambling key for ROM data
+          type: bit [127:0]
+          randcount: 128
+          randtype: data
+          name_top: RndCnstRomCtrlScrKey
+          default: 0xa71d81e9eb876b6f1996b2be4b58dfcf
+          randwidth: 128
+        }
+      ]
+    }
+  ]
+}

hw/data/top.hjson

@@ -0,0 +1,28 @@
+// Copyright lowRISC contributors (COSMIC Project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Minimal hand-crafted top config HJSON file for scrambled ROM generation.
+//
+{
+  name: mocha
+  type: top
+  module:
+  [
+    {
+      name: rom_ctrl
+      type: rom_ctrl
+      param_decl:
+      {
+        SecDisableScrambling: 1'b0
+      }
+      param_list:
+      [
+        {
+          name: SecDisableScrambling
+          type: bit
+        }
+      ]
+    }
+  ]
+}

hw/top_chip/dv/tb/chip_hier_macros.svh

@@ -7,7 +7,7 @@
 `define CPU_HIER `SYSTEM_HIER.i_cva6
 `define SRAM_MEM_HIER `SYSTEM_HIER.u_axi_sram.u_ram.mem
 `define TAG_MEM_HIER `SYSTEM_HIER.u_axi_sram.u_tag_ram.mem
-`define ROM_MEM_HIER `SYSTEM_HIER.u_rom_ctrl.gen_rom_scramble_disabled.u_rom.u_prim_rom.mem
+`define ROM_MEM_HIER `SYSTEM_HIER.u_rom_ctrl.gen_rom_scramble_enabled.u_rom.u_rom.u_prim_rom.mem
 
 // Testbench related
 `define SIM_SRAM_IF u_sim_sram.u_sim_sram_if