[sw/dif] Add FW override support to entropy src.
The entropy src allows the firmware to disconnect the raw entropy from
the pre-conditioner block at the output of the health checks. This
allows firmware to access raw entropy.
The firmware can also write data into the pre-conditioner block to
provide firmware-controlled entropy at the output of the entropy src.
This functionality can be useful to implement KAT tests of the
pre-conditioner block.
Signed-off-by: Miguel Osorio <miguelosorio@google.com>
diff --git a/sw/device/lib/dif/dif_entropy_src.c b/sw/device/lib/dif/dif_entropy_src.c
index c6cdee6..90afed8 100644
--- a/sw/device/lib/dif/dif_entropy_src.c
+++ b/sw/device/lib/dif/dif_entropy_src.c
@@ -16,7 +16,7 @@
* Sets the `entropy` source configuration register with the settings
* derived from `config`.
*/
-static void set_config_register(const dif_entropy_src_t *entropy_src,
+static void config_register_set(const dif_entropy_src_t *entropy_src,
const dif_entropy_src_config_t *config) {
// TODO: Make this configurable at the API level.
uint32_t reg = bitfield_field32_write(
@@ -26,6 +26,10 @@
reg = bitfield_field32_write(reg, ENTROPY_SRC_CONF_HEALTH_TEST_CLR_FIELD,
health_clr_sel);
+ reg = bitfield_field32_write(reg,
+ ENTROPY_SRC_CONF_ENTROPY_DATA_REG_ENABLE_FIELD,
+ config->route_to_firmware ? 0xa : 0x5);
+
// Configure single RNG bit mode
uint32_t rng_bit_en =
(config->single_bit_mode == kDifEntropySrcSingleBitModeDisabled) ? 0x5
@@ -47,6 +51,35 @@
mmio_region_write32(entropy_src->base_addr, ENTROPY_SRC_CONF_REG_OFFSET, reg);
}
+/**
+ * Sets the `entropy` source firmware override register with the settings
+ * derived from `config`.
+ */
+static dif_result_t fw_override_set(
+ const dif_entropy_src_t *entropy_src,
+ const dif_entropy_src_fw_override_config_t *config) {
+ if (config->buffer_threshold > kDifEntropySrcFifoMaxCapacity) {
+ return kDifBadArg;
+ }
+
+ if (config->entropy_insert_enable && !config->enable) {
+ return kDifBadArg;
+ }
+ mmio_region_write32(entropy_src->base_addr,
+ ENTROPY_SRC_OBSERVE_FIFO_THRESH_REG_OFFSET,
+ config->buffer_threshold);
+
+ uint32_t reg =
+ bitfield_field32_write(0, ENTROPY_SRC_FW_OV_CONTROL_FW_OV_MODE_FIELD,
+ config->enable ? 0xa : 0x5);
+ reg = bitfield_field32_write(
+ reg, ENTROPY_SRC_FW_OV_CONTROL_FW_OV_ENTROPY_INSERT_FIELD,
+ config->entropy_insert_enable ? 0xa : 0x5);
+ mmio_region_write32(entropy_src->base_addr,
+ ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET, reg);
+ return kDifOk;
+}
+
dif_result_t dif_entropy_src_init(mmio_region_t base_addr,
dif_entropy_src_t *entropy_src) {
if (entropy_src == NULL) {
@@ -62,8 +95,15 @@
return kDifBadArg;
}
- // Conditioning bypass is hardcoded to enabled. Bypass is not intended as
- // a regular mode of operation.
+ dif_result_t result = fw_override_set(entropy_src, &config.fw_override);
+ if (result != kDifOk) {
+ return result;
+ }
+
+ // TODO: Add test configuration parameters.
+
+ // Conditioning bypass is hardcoded to disabled. Conditioning bypass is not
+ // intended as a regular mode of operation.
uint32_t es_route_val = config.route_to_firmware ? 0xa : 0x5;
uint32_t reg = bitfield_field32_write(
0, ENTROPY_SRC_ENTROPY_CONTROL_ES_ROUTE_FIELD, es_route_val);
@@ -71,14 +111,7 @@
0x5);
mmio_region_write32(entropy_src->base_addr,
ENTROPY_SRC_ENTROPY_CONTROL_REG_OFFSET, reg);
-
- // TODO: Add test configuration parameters.
-
- // TODO: Add support for FIFO mode.
- mmio_region_write32(entropy_src->base_addr,
- ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET, 0x55);
-
- set_config_register(entropy_src, &config);
+ config_register_set(entropy_src, &config);
return kDifOk;
}
@@ -119,9 +152,80 @@
return kDifOk;
}
+dif_result_t dif_entropy_src_fifo_read(const dif_entropy_src_t *entropy_src,
+ uint32_t *buf, size_t len) {
+ if (entropy_src == NULL) {
+ return kDifBadArg;
+ }
+
+ uint32_t reg = mmio_region_read32(entropy_src->base_addr,
+ ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET);
+ if (bitfield_field32_read(reg, ENTROPY_SRC_FW_OV_CONTROL_FW_OV_MODE_FIELD) !=
+ 0xa) {
+ return kDifError;
+ }
+
+ reg = mmio_region_read32(entropy_src->base_addr,
+ ENTROPY_SRC_OBSERVE_FIFO_THRESH_REG_OFFSET);
+ if (reg < len) {
+ return kDifBadArg;
+ }
+
+ do {
+ reg = mmio_region_read32(entropy_src->base_addr,
+ ENTROPY_SRC_INTR_STATE_REG_OFFSET);
+ } while (!bitfield_bit32_read(
+ reg, ENTROPY_SRC_INTR_STATE_ES_OBSERVE_FIFO_READY_BIT));
+
+ for (size_t i = 0; i < len; ++i) {
+ reg = mmio_region_read32(entropy_src->base_addr,
+ ENTROPY_SRC_FW_OV_RD_DATA_REG_OFFSET);
+ if (buf != NULL) {
+ buf[i] = reg;
+ }
+ }
+
+ // Clear the status bit.
+ reg = bitfield_bit32_write(
+ 0, ENTROPY_SRC_INTR_STATE_ES_OBSERVE_FIFO_READY_BIT, true);
+ mmio_region_write32(entropy_src->base_addr, ENTROPY_SRC_INTR_STATE_REG_OFFSET,
+ reg);
+ return kDifOk;
+}
+
+dif_result_t dif_entropy_src_fifo_write(const dif_entropy_src_t *entropy_src,
+ const uint32_t *buf, size_t len) {
+ if (entropy_src == NULL || buf == NULL) {
+ return kDifBadArg;
+ }
+
+ uint32_t reg = mmio_region_read32(entropy_src->base_addr,
+ ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET);
+ if (bitfield_field32_read(reg, ENTROPY_SRC_FW_OV_CONTROL_FW_OV_MODE_FIELD) !=
+ 0xa ||
+ bitfield_field32_read(
+ reg, ENTROPY_SRC_FW_OV_CONTROL_FW_OV_ENTROPY_INSERT_FIELD) != 0xa) {
+ return kDifBadArg;
+ }
+
+ for (size_t i = 0; i < len; ++i) {
+ mmio_region_write32(entropy_src->base_addr,
+ ENTROPY_SRC_FW_OV_WR_DATA_REG_OFFSET, buf[i]);
+ }
+ return kDifOk;
+}
+
dif_result_t dif_entropy_src_disable(const dif_entropy_src_t *entropy_src) {
+ if (entropy_src == NULL) {
+ return kDifBadArg;
+ }
// TODO: should first check if entropy is locked and return error if it is.
mmio_region_write32(entropy_src->base_addr, ENTROPY_SRC_CONF_REG_OFFSET, 0);
- return kDifOk;
+ const dif_entropy_src_fw_override_config_t kDefaultFwOverrideConfig = {
+ .enable = false,
+ .entropy_insert_enable = false,
+ .buffer_threshold = kDifEntropyFifoIntDefaultThreshold,
+ };
+ return fw_override_set(entropy_src, &kDefaultFwOverrideConfig);
}
diff --git a/sw/device/lib/dif/dif_entropy_src.h b/sw/device/lib/dif/dif_entropy_src.h
index 691e1eb..8e2387f 100644
--- a/sw/device/lib/dif/dif_entropy_src.h
+++ b/sw/device/lib/dif/dif_entropy_src.h
@@ -29,6 +29,14 @@
*/
// TODO: Synchronize value with hardware.
kDifEntropySrcFifoMaxCapacity = 64,
+
+ /**
+ * Default firmware observe FIFO threshold.
+ *
+ * Default value used to trigger the `kDifEntropySrcIrqEsObserveFifoReady`
+ * interrupt when enabled.
+ */
+ kDifEntropyFifoIntDefaultThreshold = 32,
};
/**
@@ -175,6 +183,33 @@
} dif_entropy_src_test_config_t;
/**
+ * Firmware override parameters for an entropy source.
+ */
+typedef struct dif_entropy_src_fw_override_config {
+ /**
+ * Enables firmware monitoring of the post-health test entropy via
+ * `dif_entropy_fifo_read()` calls.
+ */
+ bool enable;
+
+ /**
+ * Enables fimrware to insert entropy bits back into the pre-coditioner block
+ * via `dif_entropy_fifo_write()` calls. This feature is useful when the
+ * firmware is required to implement additional health checks, and to perform
+ * known answer tests of the preconditioner function.
+ *
+ * This field requires `fw_override_enable` to be set.
+ */
+ bool entropy_insert_enable;
+
+ /**
+ * This field sets the depth of the observe FIFO hardware buffer used when
+ * `fw_override_enable` is set to true.
+ */
+ uint8_t buffer_threshold;
+} dif_entropy_src_fw_override_config_t;
+
+/**
* Runtime configuration for an entropy source.
*
* This struct describes runtime information for one-time configuration of the
@@ -232,6 +267,10 @@
*/
dif_entropy_src_test_config_t test_config;
+ /**
+ * Configuration parameters for firmware override buffer.
+ */
+ dif_entropy_src_fw_override_config_t fw_override;
} dif_entropy_src_config_t;
/**
@@ -407,9 +446,9 @@
/**
* Performs an override read from the entropy pipeline.
*
- * This function pauses entropy flow out of the pre-conditioner FIFO and
- * instead flows words into `buf`. Normal operation of the entropy pipeline
- * will not resume until `dif_entropy_src_fifo_reconnect()` is called.
+ * Entropy source must be configured with firmware override mode enabled, and
+ * the `len` parameter must be strictly less than the FIFO threshold set in the
+ * firware override parameters.
*
* `buf` may be `NULL`; in this case, reads will be discarded.
*
@@ -425,9 +464,9 @@
/**
* Performs an override write to the entropy pipeline.
*
- * This function pauses entropy flow into the pre-conditioner FIFO and
- * instead flows words out of `buf`. Normal operation of the entropy pipeline
- * will not resume until `dif_entropy_src_fifo_reconnect()` is called.
+ * Entropy source must be configured with firmware override and insert mode
+ * enabled, otherwise the function will return
+ * `kDifBadArg`.
*
* @param entropy An entropy source handle.
* @param buf A buffer to push words from into the pipeline.
@@ -439,58 +478,6 @@
const uint32_t *buf, size_t len);
/**
- * Gets the current number of entries in the pre-conditioner FIFO.
- *
- * This function pauses the flow through the FIFO.
- *
- * @param entropy An entropy source handle.
- * @param[out] len The number of words in the FIFO.
- * @return The result of the operation.
- */
-OT_WARN_UNUSED_RESULT
-dif_result_t dif_entropy_src_fifo_get_len(const dif_entropy_src_t *entropy_src,
- uint8_t *len);
-
-/**
- * Gets the current capacity of the pre-conditioner FIFO.
- *
- * @param entropy An entropy source handle.
- * @param[out] capacity The number of words of capacity in the FIFO.
- * @return The result of the operation.
- */
-OT_WARN_UNUSED_RESULT
-dif_result_t dif_entropy_src_fifo_get_capacity(
- const dif_entropy_src_t *entropy_src, uint8_t *capacity);
-
-/**
- * Sets the current capacity of the pre-conditioner FIFO.
- *
- * The `capacity` value must be less or equal to the physical capacity
- * of the fifo, defined as `kDifEntropySrcFifoMaxCapacity`.
- *
- * @param entropy An entropy source handle.
- * @param capacity The new capacity for the FIFO.
- * @return The result of the operation.
- */
-OT_WARN_UNUSED_RESULT
-dif_result_t dif_entropy_src_fifo_set_capacity(
- const dif_entropy_src_t *entropy_src, uint8_t capacity);
-
-/**
- * Reconnects the entropy pipeline after an operation that pauses it.
- *
- * This is a separate function call to avoid races between software and hardware
- * when performing multiple such operations, such as getting the length followed
- * by a read.
- *
- * @param entropy An entropy source handle.
- * @return The result of the operation.
- */
-OT_WARN_UNUSED_RESULT
-dif_result_t dif_entropy_src_fifo_reconnect(
- const dif_entropy_src_t *entropy_src);
-
-/**
* Disables the entropy module
*
* @param entropy An entropy source handle.
diff --git a/sw/device/lib/dif/dif_entropy_src_unittest.cc b/sw/device/lib/dif/dif_entropy_src_unittest.cc
index 14a2354..cd173f2 100644
--- a/sw/device/lib/dif/dif_entropy_src_unittest.cc
+++ b/sw/device/lib/dif/dif_entropy_src_unittest.cc
@@ -40,6 +40,12 @@
.route_to_firmware = false,
.fips_mode = false,
.test_config = {0},
+ .fw_override =
+ {
+ .enable = false,
+ .entropy_insert_enable = false,
+ .buffer_threshold = kDifEntropyFifoIntDefaultThreshold,
+ },
};
};
@@ -47,6 +53,17 @@
EXPECT_EQ(dif_entropy_src_configure(nullptr, {}), kDifBadArg);
}
+TEST_F(ConfigTest, InvalidFifoThreshold) {
+ config_.fw_override.buffer_threshold = 65;
+ EXPECT_EQ(dif_entropy_src_configure(&entropy_src_, config_), kDifBadArg);
+}
+
+TEST_F(ConfigTest, InvalidFwOverrideSettings) {
+ config_.fw_override.enable = false;
+ config_.fw_override.entropy_insert_enable = true;
+ EXPECT_EQ(dif_entropy_src_configure(&entropy_src_, config_), kDifBadArg);
+}
+
struct ConfigParams {
dif_entropy_src_mode_t mode;
dif_entropy_src_single_bit_mode_t single_bit_mode;
@@ -69,13 +86,23 @@
config_.route_to_firmware = test_param.route_to_firmware;
config_.reset_health_test_registers = test_param.reset_health_test_registers;
+ EXPECT_WRITE32(ENTROPY_SRC_OBSERVE_FIFO_THRESH_REG_OFFSET,
+ config_.fw_override.buffer_threshold);
+ EXPECT_WRITE32(
+ ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET,
+ {
+ {ENTROPY_SRC_FW_OV_CONTROL_FW_OV_MODE_OFFSET,
+ (uint32_t)(config_.fw_override.enable ? 0xa : 0x5)},
+ {ENTROPY_SRC_FW_OV_CONTROL_FW_OV_ENTROPY_INSERT_OFFSET,
+ (uint32_t)(config_.fw_override.entropy_insert_enable ? 0xa : 0x5)},
+ });
+
EXPECT_WRITE32(ENTROPY_SRC_ENTROPY_CONTROL_REG_OFFSET,
{
{ENTROPY_SRC_ENTROPY_CONTROL_ES_ROUTE_OFFSET,
(uint32_t)(test_param.route_to_firmware ? 0xa : 0x5)},
{ENTROPY_SRC_ENTROPY_CONTROL_ES_TYPE_OFFSET, 0x5},
});
- EXPECT_WRITE32(ENTROPY_SRC_FW_OV_CONTROL_REG_OFFSET, 0x55);
// Current dif does not perform a read modified write
// EXPECT_READ32(ENTROPY_SRC_CONF_REG_OFFSET, 0);
@@ -84,6 +111,7 @@
uint32_t route_to_fw = test_param.route_to_firmware ? 0xa : 0x5;
uint32_t enable =
test_param.expected_mode != kDifEntropySrcModeDisabled ? 0xa : 0x5;
+
uint32_t reset_ht = test_param.reset_health_test_registers ? 0xa : 0x5;
EXPECT_WRITE32(
ENTROPY_SRC_CONF_REG_OFFSET,
diff --git a/sw/device/lib/testing/entropy_testutils.c b/sw/device/lib/testing/entropy_testutils.c
index 1d1939a..ae7fb89 100644
--- a/sw/device/lib/testing/entropy_testutils.c
+++ b/sw/device/lib/testing/entropy_testutils.c
@@ -33,7 +33,11 @@
.reset_health_test_registers = false,
.single_bit_mode = kDifEntropySrcSingleBitModeDisabled,
.route_to_firmware = false,
- };
+ .fw_override = {
+ .enable = false,
+ .entropy_insert_enable = false,
+ .buffer_threshold = kDifEntropyFifoIntDefaultThreshold,
+ }};
CHECK_DIF_OK(dif_entropy_src_configure(&entropy_src, config));
}
diff --git a/sw/device/tests/entropy_src_fw_ovr_test.c b/sw/device/tests/entropy_src_fw_ovr_test.c
new file mode 100644
index 0000000..0bca986
--- /dev/null
+++ b/sw/device/tests/entropy_src_fw_ovr_test.c
@@ -0,0 +1,123 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+#include "sw/device/lib/base/memory.h"
+#include "sw/device/lib/base/mmio.h"
+#include "sw/device/lib/dif/dif_entropy_src.h"
+#include "sw/device/lib/runtime/log.h"
+#include "sw/device/lib/testing/check.h"
+#include "sw/device/lib/testing/test_framework/test_main.h"
+
+#include "hw/top_earlgrey/sw/autogen/top_earlgrey.h" // Generated.
+
+const test_config_t kTestConfig;
+
+enum {
+ /**
+ * The size of the buffer used in firmware to process the entropy bits in
+ * firmware override mode.
+ */
+ kEntropyFifoBufferSize = 32,
+};
+
+/**
+ * Flushes the data entropy buffer until there is no data available to read.
+ *
+ * Asserts test error if any of the returned words is equal to zero. Logs the
+ * number of entropy words flushed in a single call.
+ *
+ * @param entropy An entropy source instance.
+ */
+static void entropy_data_flush(dif_entropy_src_t *entropy_src) {
+ uint32_t entropy_bits;
+ uint32_t read_count = 0;
+
+ // TODO: Remove this limit. Entropy source should block if there is no entropy
+ // available in FW override mode.
+ const uint32_t kMaxReadCount = 12;
+
+ while (dif_entropy_src_avail(entropy_src) == kDifOk) {
+ CHECK_DIF_OK(dif_entropy_src_read(entropy_src, &entropy_bits));
+ CHECK(entropy_bits != 0);
+ read_count++;
+ if (read_count >= kMaxReadCount) {
+ break;
+ }
+ }
+ LOG_INFO("Flushed %d entropy words.", read_count);
+}
+
+/**
+ * Configures the entropy source module in firmware override mode.
+ *
+ * Output is routed to firmware, and the fw_override mode is enabled to get data
+ * post-health tests and before the pre conditioner block.
+ *
+ * @param entropy An entropy source instance.
+ */
+static void entropy_with_fw_override_enable(dif_entropy_src_t *entropy_src) {
+ const dif_entropy_src_config_t config = {
+ .mode = kDifEntropySrcModePtrng,
+ .tests =
+ {
+ [kDifEntropySrcTestRepCount] = false,
+ [kDifEntropySrcTestAdaptiveProportion] = false,
+ [kDifEntropySrcTestBucket] = false,
+ [kDifEntropySrcTestMarkov] = false,
+ [kDifEntropySrcTestMailbox] = false,
+ [kDifEntropySrcTestVendorSpecific] = false,
+ },
+ .reset_health_test_registers = false,
+ .single_bit_mode = kDifEntropySrcSingleBitModeDisabled,
+ .route_to_firmware = true,
+ .fw_override =
+ {
+ .enable = true,
+ .entropy_insert_enable = true,
+ .buffer_threshold = kEntropyFifoBufferSize,
+ },
+ };
+ CHECK_DIF_OK(dif_entropy_src_configure(entropy_src, config));
+}
+
+/**
+ * Test the firmware override path.
+ *
+ * This tests disconnects the observation buffer from the entropy src
+ * pre-conditioner block to read the raw entropy data after the hardware
+ * health tests. It then feeds the data back into the conditioner block until
+ * there is data available in the output FIFO.
+ *
+ * @param entropy An Entropy handle.
+ */
+void test_firmware_override(dif_entropy_src_t *entropy) {
+ CHECK_DIF_OK(dif_entropy_src_disable(entropy));
+ entropy_with_fw_override_enable(entropy);
+ entropy_data_flush(entropy);
+
+ // Read data from the obeservation and write it back into the pre conditioner
+ // until there is data available in the output buffer.
+ uint32_t buf[kEntropyFifoBufferSize] = {0};
+ uint32_t word_count = 0;
+ do {
+ CHECK_DIF_OK(
+ dif_entropy_src_fifo_read(entropy, buf, kEntropyFifoBufferSize));
+ for (size_t i = 0; i < kEntropyFifoBufferSize; ++i) {
+ CHECK(buf[i] != 0);
+ }
+ CHECK_DIF_OK(
+ dif_entropy_src_fifo_write(entropy, buf, kEntropyFifoBufferSize));
+ word_count += kEntropyFifoBufferSize;
+ } while (dif_entropy_src_avail(entropy) == kDifUnavailable);
+ LOG_INFO("Processed %d words via FIFO_OVR buffer.", word_count);
+ entropy_data_flush(entropy);
+}
+
+bool test_main() {
+ dif_entropy_src_t entropy_src;
+ CHECK_DIF_OK(dif_entropy_src_init(
+ mmio_region_from_addr(TOP_EARLGREY_ENTROPY_SRC_BASE_ADDR), &entropy_src));
+ test_firmware_override(&entropy_src);
+ return true;
+}
diff --git a/sw/device/tests/entropy_src_smoketest.c b/sw/device/tests/entropy_src_smoketest.c
index 55e6bdb..c5d3baf 100644
--- a/sw/device/tests/entropy_src_smoketest.c
+++ b/sw/device/tests/entropy_src_smoketest.c
@@ -42,7 +42,12 @@
// this field needs to manually toggled by software. Disable for now
.reset_health_test_registers = false,
.single_bit_mode = kDifEntropySrcSingleBitModeDisabled,
- .route_to_firmware = true};
+ .route_to_firmware = true,
+ .fw_override = {
+ .enable = false,
+ .entropy_insert_enable = false,
+ .buffer_threshold = kDifEntropyFifoIntDefaultThreshold,
+ }};
CHECK_DIF_OK(dif_entropy_src_configure(&entropy_src, config));
uint32_t entropy_data[kEntropyDataNumWords];
diff --git a/sw/device/tests/meson.build b/sw/device/tests/meson.build
index 230bbb6..eb67901 100644
--- a/sw/device/tests/meson.build
+++ b/sw/device/tests/meson.build
@@ -252,6 +252,23 @@
}
}
+entropy_src_fw_ovr_test_lib = declare_dependency(
+ link_with: static_library(
+ 'entropy_src_fw_ovr_test_lib',
+ sources: ['entropy_src_fw_ovr_test.c'],
+ dependencies: [
+ sw_lib_dif_entropy_src,
+ sw_lib_mmio,
+ sw_lib_runtime_log,
+ ],
+ ),
+)
+sw_tests += {
+ 'entropy_src_fw_ovr_test': {
+ 'library': entropy_src_fw_ovr_test_lib,
+ }
+}
+
entropy_src_smoketest_lib = declare_dependency(
link_with: static_library(
'entropy_src_smoketest_lib',
