[keymgr_dpe, dif] Add missing API calls

Add three missing features to the dif of the keymgr_dpe.

- The disable function to transition the keymgr_dpe into the disabled state
- The configuration function to set the re-seeding interval of the keymgr_dpe
- Any sideloaded key on the sideload interface can now be cleared by sw

Add an empty `dif_keymgr_dpe_unittest.cc` file to avoid triggering error
during the top integration, tracked in Issue #30609.

Signed-off-by: Raphael Roth <rroth@lowrisc.org>

Author: rroth-lowrisc

sw/device/lib/dif/dif_keymgr_dpe.c

@@ -166,6 +166,10 @@ dif_result_t dif_keymgr_dpe_initialize(const dif_keymgr_dpe_t *keymgr_dpe,
     return kDifLocked;
   }
 
+  // TODO(#30667): Verify if the max key version needs to be written here too!
+  //              When loading the UDS the RTL fetches the max key version from
+  //              the SW register. Verify that the lock is released when the
+  //              version register is locked.
   uint32_t reg_control = bitfield_field32_write(
       KEYMGR_DPE_CONTROL_SHADOWED_REG_RESVAL,
       KEYMGR_DPE_CONTROL_SHADOWED_SLOT_DST_SEL_FIELD, slot_dst_sel);
@@ -279,6 +283,28 @@ dif_result_t dif_keymgr_dpe_erase_slot(
   return kDifOk;
 }
 
+dif_result_t dif_keymgr_dpe_disable(const dif_keymgr_dpe_t *keymgr_dpe) {
+  if (keymgr_dpe == NULL) {
+    return kDifBadArg;
+  }
+
+  if (!is_ready(keymgr_dpe)) {
+    return kDifLocked;
+  }
+
+  uint32_t reg_control = bitfield_field32_write(
+      KEYMGR_DPE_CONTROL_SHADOWED_REG_RESVAL,
+      KEYMGR_DPE_CONTROL_SHADOWED_OPERATION_FIELD,
+      KEYMGR_DPE_CONTROL_SHADOWED_OPERATION_VALUE_DISABLE);
+  mmio_region_write32_shadowed(keymgr_dpe->base_addr,
+                               KEYMGR_DPE_CONTROL_SHADOWED_REG_OFFSET,
+                               reg_control);
+  mmio_region_write32(keymgr_dpe->base_addr, KEYMGR_DPE_START_REG_OFFSET,
+                      1 << KEYMGR_DPE_START_EN_BIT);
+
+  return kDifOk;
+}
+
 dif_result_t dif_keymgr_dpe_generate(
     const dif_keymgr_dpe_t *keymgr_dpe,
     const dif_keymgr_dpe_generate_params_t *params) {
@@ -405,3 +431,40 @@ dif_result_t dif_keymgr_dpe_get_state(const dif_keymgr_dpe_t *keymgr_dpe,
       bitfield_field32_read(reg_state, KEYMGR_DPE_WORKING_STATE_STATE_FIELD);
   return kDifOk;
 }
+
+dif_result_t dif_keymgr_dpe_clear_sideload_key(
+    const dif_keymgr_dpe_t *keymgr_dpe,
+    dif_keymgr_dpe_sideload_clr_t clear_dest) {
+  if (keymgr_dpe == NULL) {
+    return kDifBadArg;
+  }
+
+  mmio_region_write32(keymgr_dpe->base_addr,
+                      KEYMGR_DPE_SIDELOAD_CLEAR_REG_OFFSET, clear_dest);
+
+  return kDifOk;
+}
+
+dif_result_t dif_keymgr_dpe_configure(const dif_keymgr_dpe_t *keymgr_dpe,
+                                      dif_keymgr_dpe_config_t config) {
+  if (keymgr_dpe == NULL) {
+    return kDifBadArg;
+  }
+
+  // Verify if the register is unlocked
+  uint32_t reseed_regwen = mmio_region_read32(
+      keymgr_dpe->base_addr, KEYMGR_DPE_RESEED_INTERVAL_REGWEN_REG_OFFSET);
+  if (!bitfield_bit32_read(reseed_regwen,
+                           KEYMGR_DPE_RESEED_INTERVAL_REGWEN_EN_BIT)) {
+    return kDifLocked;
+  }
+
+  uint32_t reg_val =
+      bitfield_field32_write(0, KEYMGR_DPE_RESEED_INTERVAL_SHADOWED_VAL_FIELD,
+                             config.entropy_reseed_interval);
+  mmio_region_write32_shadowed(keymgr_dpe->base_addr,
+                               KEYMGR_DPE_RESEED_INTERVAL_SHADOWED_REG_OFFSET,
+                               reg_val);
+
+  return kDifOk;
+}

sw/device/lib/dif/dif_keymgr_dpe.h

@@ -42,6 +42,33 @@ typedef enum dif_keymgr_dpe_state {
   kDifKeymgrDpeStateInvalid = 3
 } dif_keymgr_dpe_state_t;
 
+/**
+ * Enumeration for side load slot clearing.
+ */
+typedef enum dif_keymgr_sideload_clr {
+  kDifKeymgrDpeSideLoadClearNone = 0,
+  kDifKeymgrDpeSideLoadClearAes = 1,
+  kDifKeymgrDpeSideLoadClearKmac = 2,
+  kDifKeymgrDpeSideLoadClearOtbn = 3,
+  // Using different value than those enumerated above should clear all slots,
+  // so we can use the mask value of this field to denote ALL case.
+  kDifKeymgrDpeSideLoadClearAll = 7,
+} dif_keymgr_dpe_sideload_clr_t;
+
+/**
+ * Runtime configuration for keymgr dpe.
+ */
+typedef struct dif_keymgr_dpe_config {
+  /**
+   * Number of keymgr_dpe cycles before the entropy is reseeded.
+   *
+   * Keymgr dpe uses random values generated by the entropy source for
+   * initializing its state and clearing sideload keys. This value determines
+   * the frequency at which this random value is updated.
+   */
+  uint16_t entropy_reseed_interval;
+} dif_keymgr_dpe_config_t;
+
 /**
  * Input parameters for advancing a DPE context/slot.
  */
@@ -252,6 +279,20 @@ dif_result_t dif_keymgr_dpe_erase_slot(
     const dif_keymgr_dpe_t *keymgr_dpe,
     const dif_keymgr_dpe_erase_params_t *params);
 
+/**
+ * Disables key manager dpe.
+ *
+ * This function disables keymgr dpe until the next power cycle by making
+ * it transition to the "disabled" state. The "disabled" state is a terminal
+ * state where the keymgr dpe is no longer operational and its secret value
+ * are wiped.
+ *
+ * @param keymgr_dpe A key manager handle.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_keymgr_dpe_disable(const dif_keymgr_dpe_t *keymgr_dpe);
+
 /**
  * Generate a SW/HW key from a chosen keymgr_dpe slot.
  *
@@ -288,7 +329,7 @@ dif_result_t dif_keymgr_dpe_get_status_codes(
  */
 OT_WARN_UNUSED_RESULT
 dif_result_t dif_keymgr_dpe_get_state(const dif_keymgr_dpe_t *keymgr_dpe,
-                                      uint32_t *state);
+                                      dif_keymgr_dpe_state_t *state);
 
 /**
  * Read the value of SW generated key from its related CSR. It is the
@@ -302,6 +343,33 @@ OT_WARN_UNUSED_RESULT
 dif_result_t dif_keymgr_dpe_read_output(const dif_keymgr_dpe_t *keymgr_dpe,
                                         dif_keymgr_dpe_output_t *output);
 
+/**
+ * Starts or stops clearing of sideload keys.
+ *
+ * Calling this function on a set of output register causes keymgr dpe to clear
+ * sideload keys continuously using randomness. Callers must disable the
+ * clearing of sideload keys to resume normal sideload operation.
+ *
+ * @param keymgr_dpe A key manager handle.
+ * @param clear_dest Target sideload key.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_keymgr_dpe_clear_sideload_key(
+    const dif_keymgr_dpe_t *keymgr_dpe,
+    dif_keymgr_dpe_sideload_clr_t clear_dest);
+
+/**
+ * Runtime configuration for keymgr dpe.
+ *
+ * @param keymgr_dpe A key manager handle.
+ * @param config configuration for the keymgr dpe.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_keymgr_dpe_configure(const dif_keymgr_dpe_t *keymgr_dpe,
+                                      dif_keymgr_dpe_config_t config);
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif  // __cplusplus

sw/device/lib/dif/dif_keymgr_dpe_unittest.cc

@@ -0,0 +1,23 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#include "sw/device/lib/dif/dif_keymgr_dpe.h"
+
+#include <array>
+
+#include "gtest/gtest.h"
+#include "sw/device/lib/base/mmio.h"
+#include "sw/device/lib/base/mock_mmio.h"
+#include "sw/device/lib/dif/dif_base.h"
+#include "sw/device/lib/dif/dif_test_base.h"
+
+#include "hw/top/keymgr_dpe_regs.h"  // Generated
+
+namespace dif_keymgr_dpe_unittest {
+namespace {
+
+// TODO(#30609): Write these unittests
+
+}  // namespace
+}  // namespace dif_keymgr_dpe_unittest