rram_ctrl.c

// 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/silicon_creator/lib/drivers/rram_ctrl.h"
 
#include <assert.h>
 
#include "sw/device/lib/base/abs_mmio.h"
#include "sw/device/lib/base/bitfield.h"
#include "sw/device/lib/base/hardened.h"
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/memory.h"
#include "sw/device/lib/base/multibits.h"
#include "sw/device/silicon_creator/lib/base/sec_mmio.h"
#include "sw/device/silicon_creator/lib/drivers/otp.h"
#include "sw/device/silicon_creator/lib/error.h"
 
#include "hw/top/otp_ctrl_regs.h"
#include "hw/top/rram_ctrl_regs.h"
#include "hw/top_earlgrey/sw/autogen/top_earlgrey.h"
 
/**
 * Base address of the rram_ctrl registers.
 *
 * There is no devicetree (`dt_rram_ctrl`) support yet, unlike flash_ctrl,
 * so the base address is taken directly from the autogenerated top-level
 * memory map instead of `dt_rram_ctrl_primary_reg_block()`.
 */
static inline uint32_t rram_ctrl_core_base(void) {
  return TOP_EARLGREY_RRAM_CTRL_CORE_BASE_ADDR;
}
 
/**
 * RRAM transaction parameters.
 */
typedef struct transaction_params {
  /**
   * Start address of a RRAM transaction. Full byte address; the controller
   * truncates to the closest word-aligned address.
   */
  uint32_t addr;
  /**
   * Operation type. Must be one of `RRAM_CTRL_CONTROL_OP_VALUE_*`.
   */
  uint32_t op_type;
  /**
   * Whether the transaction targets the info partition (true) or the data
   * partition (false).
   */
  bool is_info;
  /**
   * Number of 32-bit words.
   */
  uint32_t word_count;
} transaction_params_t;
 
/**
 * Starts a RRAM transaction.
 *
 * @param params Transaction parameters, see `transaction_params_t`.
 */
static void transaction_start(transaction_params_t params) {
  abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_ADDR_REG_OFFSET,
                   params.addr);
  uint32_t reg = bitfield_bit32_write(0, RRAM_CTRL_CONTROL_START_BIT, true);
  reg = bitfield_field32_write(reg, RRAM_CTRL_CONTROL_OP_FIELD, params.op_type);
  reg = bitfield_bit32_write(reg, RRAM_CTRL_CONTROL_PARTITION_BIT,
                             params.is_info);
  reg = bitfield_field32_write(reg, RRAM_CTRL_CONTROL_NUM_FIELD,
                               params.word_count - 1);
  abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_CONTROL_REG_OFFSET, reg);
}
 
/**
 * Copies `word_count` words from the read FIFO to the given buffer.
 *
 * @param word_count Number of words to read from the FIFO.
 * @param[out] data Output buffer.
 */
static void fifo_read(size_t word_count, void *data) {
  size_t i = 0, r = word_count - 1;
  for (; launder32(i) < word_count && launder32(r) < word_count; ++i, --r) {
    write_32(
        abs_mmio_read32(rram_ctrl_core_base() + RRAM_CTRL_RD_FIFO_REG_OFFSET),
        data);
    data = (char *)data + sizeof(uint32_t);
  }
  HARDENED_CHECK_EQ(i, word_count);
  HARDENED_CHECK_EQ(r, SIZE_MAX);
}
 
/**
 * Copies `word_count` words from the given buffer to the write FIFO.
 *
 * @param word_count Number of words to write to the FIFO.
 * @param data Input buffer.
 */
static void fifo_write(size_t word_count, const void *data) {
  size_t i = 0, r = word_count - 1;
  for (; launder32(i) < word_count && launder32(r) < word_count; ++i, --r) {
    abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_WR_FIFO_REG_OFFSET,
                     read_32(data));
    data = (const char *)data + sizeof(uint32_t);
  }
  HARDENED_CHECK_EQ(i, word_count);
  HARDENED_CHECK_EQ(r, SIZE_MAX);
}
 
/**
 * Blocks until the current RRAM transaction is complete.
 *
 * @param error Error code to return in case of a RRAM controller error.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
static rom_error_t wait_for_done(rom_error_t error) {
  uint32_t op_status;
  do {
    op_status =
        abs_mmio_read32(rram_ctrl_core_base() + RRAM_CTRL_OP_STATUS_REG_OFFSET);
  } while (!bitfield_bit32_read(op_status, RRAM_CTRL_OP_STATUS_DONE_BIT));
  abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_OP_STATUS_REG_OFFSET, 0u);
 
  if (bitfield_bit32_read(op_status, RRAM_CTRL_OP_STATUS_ERR_BIT)) {
    return error;
  }
  return kErrorOk;
}
 
/**
 * RRAM controller write transaction word granularity: `write_aligned()` can
 * only write a whole number of `kRramWriteGranuleWords`-word granules. All
 * other addr/word_count combinations go through `write()`'s read-modify-write
 * of the leading/trailing partial granules, so callers (like `nvm_ctrl.c`)
 * never have to worry about alignment themselves.
 */
enum {
  kRramWriteGranuleWords = 4,
  kRramWriteGranuleBytes = kRramWriteGranuleWords * (uint32_t)sizeof(uint32_t),
};
static_assert((kRramWriteGranuleBytes & (kRramWriteGranuleBytes - 1)) == 0,
              "RRAM write granule must be a power of two.");
 
/**
 * Reads data from the given partition.
 *
 * @param addr Full byte address to read from.
 * @param is_info Whether to read from the info partition (true) or the data
 *                partition (false).
 * @param word_count Number of bus words to read.
 * @param[out] data Output buffer.
 * @param error Error code to return in case of a RRAM controller error.
 * @return Result of the operation.
 */
OT_WARN_UNUSED_RESULT
static rom_error_t read(uint32_t addr, bool is_info, uint32_t word_count,
                        void *data, rom_error_t error) {
  transaction_start((transaction_params_t){
      .addr = addr,
      .op_type = RRAM_CTRL_CONTROL_OP_VALUE_READ,
      .is_info = is_info,
      .word_count = word_count,
  });
  fifo_read(word_count, data);
  return wait_for_done(error);
}
 
/**
 * Writes a `kRramWriteGranuleWords`-aligned, `kRramWriteGranuleWords`-sized
 * number of words to the given partition.
 *
 * RRAM has no equivalent of flash's program-window restriction; writes are
 * simply chunked to the maximum transaction word count.
 *
 * @param addr Full byte address to write to; must be
 *             `kRramWriteGranuleBytes`-aligned.
 * @param is_info Whether to write to the info partition (true) or the data
 *                partition (false).
 * @param word_count Number of bus words to write; must be a multiple of
 *                    `kRramWriteGranuleWords`.
 * @param data Data to write.
 * @param error Error code to return in case of a RRAM controller error.
 * @return Result of the operation.
 */
OT_WARN_UNUSED_RESULT
static rom_error_t write_aligned(uint32_t addr, bool is_info,
                                 uint32_t word_count, const void *data,
                                 rom_error_t error) {
  enum {
    kMaxWordCount = RRAM_CTRL_CONTROL_NUM_MASK + 1,
  };
  if (word_count % kRramWriteGranuleWords != 0) {
    return error;
  }
 
  while (word_count > 0) {
    uint32_t chunk_word_count =
        word_count < kMaxWordCount ? word_count : kMaxWordCount;
 
    transaction_start((transaction_params_t){
        .addr = addr,
        .op_type = RRAM_CTRL_CONTROL_OP_VALUE_WRITE,
        .is_info = is_info,
        .word_count = chunk_word_count,
    });
 
    fifo_write(chunk_word_count, data);
    RETURN_IF_ERROR(wait_for_done(error));
 
    addr += chunk_word_count * sizeof(uint32_t);
    data = (const char *)data + chunk_word_count * sizeof(uint32_t);
    word_count -= chunk_word_count;
  }
 
  return kErrorOk;
}
 
/**
 * Read-modify-writes a single `kRramWriteGranuleBytes`-sized,
 * `kRramWriteGranuleBytes`-aligned granule: reads the granule at
 * `aligned_addr`, splices in `len` bytes of `data` at byte offset `lead`
 * within it (`lead + len` must not exceed `kRramWriteGranuleBytes`), and
 * writes the granule back.
 */
OT_WARN_UNUSED_RESULT
static rom_error_t granule_rmw(uint32_t aligned_addr, bool is_info, size_t lead,
                               const void *data, size_t len,
                               rom_error_t write_error,
                               rom_error_t read_error) {
  uint8_t buf[kRramWriteGranuleBytes];
  RETURN_IF_ERROR(
      read(aligned_addr, is_info, kRramWriteGranuleWords, buf, read_error));
  memcpy(buf + lead, data, len);
  return write_aligned(aligned_addr, is_info, kRramWriteGranuleWords, buf,
                       write_error);
}
 
/**
 * Writes `word_count` words (need not be a multiple of
 * `kRramWriteGranuleWords`) to `addr` (need not be
 * `kRramWriteGranuleBytes`-aligned) in the given partition.
 *
 * Handles any size via read-modify-write on only the leading and trailing
 * partial granules (at most `kRramWriteGranuleBytes` of stack buffer at a
 * time); the aligned middle portion, if any, is written directly with no
 * read. Unbounded in `word_count`.
 *
 * @param addr Full byte address to write to.
 * @param is_info Whether to write to the info partition (true) or the data
 *                partition (false).
 * @param word_count Number of bus words to write.
 * @param data Data to write.
 * @param write_error Error code to return in case of a write-transaction
 *                     controller error.
 * @param read_error Error code to return in case of a read-transaction
 *                    controller error (only reachable via the RMW path).
 * @return Result of the operation.
 */
OT_WARN_UNUSED_RESULT
static rom_error_t write(uint32_t addr, bool is_info, uint32_t word_count,
                         const void *data, rom_error_t write_error,
                         rom_error_t read_error) {
  if (word_count == 0) {
    return kErrorOk;
  }
 
  size_t byte_count = (size_t)word_count * sizeof(uint32_t);
  uint32_t aligned_addr = addr & ~(uint32_t)(kRramWriteGranuleBytes - 1);
  size_t lead = addr - aligned_addr;
 
  if (lead == 0 && byte_count % kRramWriteGranuleBytes == 0) {
    // Already granule-aligned on both ends: no RMW needed.
    return write_aligned(addr, is_info, word_count, data, write_error);
  }
 
  // Leading (possibly partial) granule.
  size_t first_chunk_len = kRramWriteGranuleBytes - lead;
  if (first_chunk_len > byte_count) {
    first_chunk_len = byte_count;
  }
  RETURN_IF_ERROR(granule_rmw(aligned_addr, is_info, lead, data,
                              first_chunk_len, write_error, read_error));
  data = (const char *)data + first_chunk_len;
  byte_count -= first_chunk_len;
  aligned_addr += kRramWriteGranuleBytes;
 
  // Aligned middle portion, written directly with no read.
  size_t middle_words =
      (byte_count / kRramWriteGranuleBytes) * kRramWriteGranuleWords;
  if (middle_words > 0) {
    RETURN_IF_ERROR(write_aligned(aligned_addr, is_info, (uint32_t)middle_words,
                                  data, write_error));
    size_t middle_bytes = middle_words * sizeof(uint32_t);
    data = (const char *)data + middle_bytes;
    byte_count -= middle_bytes;
    aligned_addr += middle_bytes;
  }
 
  // Trailing partial granule.
  if (byte_count > 0) {
    RETURN_IF_ERROR(granule_rmw(aligned_addr, is_info, 0, data, byte_count,
                                write_error, read_error));
  }
  return kErrorOk;
}
 
void rram_ctrl_init(void) {
  // The linker reserves `_nvm_slot_reserved_bytes` (top_earlgrey_memory.ld)
  // at the tail of every slot; `kRramCtrlReservedPageCount` (rram_ctrl.h)
  // must derive from that same 32KiB. Nothing at compile time ties a C
  // constant to a linker symbol, so check they still agree here instead.
  extern char _nvm_slot_reserved_bytes[];
  HARDENED_CHECK_EQ(
      (uint32_t)_nvm_slot_reserved_bytes,
      kRramCtrlReservedPageCount * RRAM_CTRL_PARAM_BYTES_PER_PAGE);
 
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioInit,
                                  kRramCtrlSecMmioDataDefaultCfgSet);
 
  // Set `HW_INFO_CFG_OVERRIDE` register if needed. Reuses the same OTP word
  // and bit layout as flash_ctrl. This must be done before initializing the
  // rram_ctrl.
  uint32_t reg_val = RRAM_CTRL_HW_INFO_CFG_OVERRIDE_REG_RESVAL;
  uint32_t otp_val =
      otp_read32(OTP_CTRL_PARAM_CREATOR_SW_CFG_NVM_HW_INFO_CFG_OVERRIDE_OFFSET);
  multi_bit_bool_t scramble_dis = bitfield_field32_read(
      otp_val, RRAM_CTRL_OTP_FIELD_HW_INFO_CFG_OVERRIDE_SCRAMBLE_DIS);
  if (scramble_dis == kMultiBitBool4True) {
    reg_val = bitfield_field32_write(
        reg_val, RRAM_CTRL_HW_INFO_CFG_OVERRIDE_SCRAMBLE_DIS_FIELD,
        scramble_dis);
  }
  multi_bit_bool_t ecc_dis = bitfield_field32_read(
      otp_val, RRAM_CTRL_OTP_FIELD_HW_INFO_CFG_OVERRIDE_ECC_DIS);
  if (ecc_dis == kMultiBitBool4True) {
    reg_val = bitfield_field32_write(
        reg_val, RRAM_CTRL_HW_INFO_CFG_OVERRIDE_ECC_DIS_FIELD, ecc_dis);
  }
  if (reg_val != RRAM_CTRL_HW_INFO_CFG_OVERRIDE_REG_RESVAL) {
    sec_mmio_write32(
        rram_ctrl_core_base() + RRAM_CTRL_HW_INFO_CFG_OVERRIDE_REG_OFFSET,
        reg_val);
  }
 
  // Kick off RRAM controller initialization and wait for completion. Unlike
  // flash_ctrl, where memory protection only gates the controller's own
  // transaction-based (FIFO) reads/writes, rram_ctrl's memory protection also
  // gates the direct read path, so RD_EN must be set for the default region
  // below before RRAM can be read at all.
  abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_INIT_REG_OFFSET,
                   bitfield_bit32_write(0, RRAM_CTRL_INIT_VAL_BIT, true));
  rram_ctrl_status_t status;
  do {
    rram_ctrl_status_get(&status);
  } while (!status.init_done);
 
  // Configure default scrambling and ECC settings for the data partition.
  // Reuses the same `CREATOR_SW_CFG_NVM_DATA_DEFAULT_CFG` OTP word and bit
  // layout as flash_ctrl; the high-endurance field does not apply to RRAM.
  otp_val =
      otp_read32(OTP_CTRL_PARAM_CREATOR_SW_CFG_NVM_DATA_DEFAULT_CFG_OFFSET);
  rram_ctrl_cfg_t data_default_cfg = {
      .scrambling =
          bitfield_field32_read(otp_val, RRAM_CTRL_OTP_FIELD_SCRAMBLING),
      .ecc = bitfield_field32_read(otp_val, RRAM_CTRL_OTP_FIELD_ECC),
  };
  rram_ctrl_data_default_cfg_set(data_default_cfg);
}
 
void rram_ctrl_disable(void) {
  abs_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_DIS_REG_OFFSET, 0);
}
 
void rram_ctrl_status_get(rram_ctrl_status_t *status) {
  uint32_t reg =
      abs_mmio_read32(rram_ctrl_core_base() + RRAM_CTRL_STATUS_REG_OFFSET);
  status->rd_full = bitfield_bit32_read(reg, RRAM_CTRL_STATUS_RD_FULL_BIT);
  status->rd_empty = bitfield_bit32_read(reg, RRAM_CTRL_STATUS_RD_EMPTY_BIT);
  status->wr_full = bitfield_bit32_read(reg, RRAM_CTRL_STATUS_WR_FULL_BIT);
  status->wr_empty = bitfield_bit32_read(reg, RRAM_CTRL_STATUS_WR_EMPTY_BIT);
  status->init_done = bitfield_bit32_read(reg, RRAM_CTRL_STATUS_INIT_DONE_BIT);
}
 
void rram_ctrl_error_code_get(rram_ctrl_error_code_t *error_code) {
  uint32_t code =
      abs_mmio_read32(rram_ctrl_core_base() + RRAM_CTRL_ERR_CODE_REG_OFFSET);
  error_code->op_err = bitfield_bit32_read(code, RRAM_CTRL_ERR_CODE_OP_ERR_BIT);
  error_code->mp_err = bitfield_bit32_read(code, RRAM_CTRL_ERR_CODE_MP_ERR_BIT);
  error_code->rd_err = bitfield_bit32_read(code, RRAM_CTRL_ERR_CODE_RD_ERR_BIT);
  error_code->wr_err = bitfield_bit32_read(code, RRAM_CTRL_ERR_CODE_WR_ERR_BIT);
}
 
rom_error_t rram_ctrl_data_read(uint32_t addr, uint32_t word_count,
                                void *data) {
  return read(addr, /*is_info=*/false, word_count, data,
              kErrorRramCtrlDataRead);
}
 
static uint32_t info_page_addr(const rram_ctrl_info_page_t *info_page,
                               uint32_t offset) {
  HARDENED_CHECK_EQ(info_page->emulated, false);
  return info_page->page_id * RRAM_CTRL_PARAM_BYTES_PER_PAGE + offset;
}
 
rom_error_t rram_ctrl_info_read(const rram_ctrl_info_page_t *info_page,
                                uint32_t offset, uint32_t word_count,
                                void *data) {
  return read(info_page_addr(info_page, offset), /*is_info=*/true, word_count,
              data, kErrorRramCtrlInfoRead);
}
 
rom_error_t rram_ctrl_info_read_zeros_on_read_error(
    const rram_ctrl_info_page_t *info_page, uint32_t offset,
    uint32_t word_count, void *data) {
  rom_error_t err = rram_ctrl_info_read(info_page, offset, word_count, data);
  if (err != kErrorOk) {
    rram_ctrl_error_code_t rram_ctrl_err_code;
    rram_ctrl_error_code_get(&rram_ctrl_err_code);
    if (rram_ctrl_err_code.rd_err) {
      // If we encountered a read error, return all 0s.
      memset(data, 0, word_count * sizeof(uint32_t));
      return kErrorOk;
    }
  }
  return err;
}
 
rom_error_t rram_ctrl_data_write(uint32_t addr, uint32_t word_count,
                                 const void *data) {
  return write(addr, /*is_info=*/false, word_count, data,
               kErrorRramCtrlDataWrite, kErrorRramCtrlDataRead);
}
 
rom_error_t rram_ctrl_info_write(const rram_ctrl_info_page_t *info_page,
                                 uint32_t offset, uint32_t word_count,
                                 const void *data) {
  return write(info_page_addr(info_page, offset), /*is_info=*/true, word_count,
               data, kErrorRramCtrlInfoWrite, kErrorRramCtrlInfoRead);
}
 
void rram_ctrl_exec_set(uint32_t exec_val) {
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioExecSet, 1);
  sec_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_EXEC_REG_OFFSET, exec_val);
}
 
void rram_ctrl_data_default_perms_set(rram_ctrl_perms_t perms) {
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioDataDefaultPermsSet, 1);
 
  // Read first to preserve ECC and scrambling bits.
  uint32_t reg = sec_mmio_read32(rram_ctrl_core_base() +
                                 RRAM_CTRL_DEFAULT_REGION_REG_OFFSET);
  reg = bitfield_field32_write(reg, RRAM_CTRL_DEFAULT_REGION_RD_EN_FIELD,
                               perms.read);
  reg = bitfield_field32_write(reg, RRAM_CTRL_DEFAULT_REGION_WR_EN_FIELD,
                               perms.write);
  sec_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_DEFAULT_REGION_REG_OFFSET,
                   reg);
}
 
void rram_ctrl_info_perms_set(const rram_ctrl_info_page_t *info_page,
                              rram_ctrl_perms_t perms) {
  HARDENED_CHECK_EQ(info_page->emulated, false);
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioInfoPermsSet, 1);
 
  uint32_t cfg_offset = RRAM_CTRL_INFO_PAGE_CFG_0_REG_OFFSET +
                        info_page->page_id * sizeof(uint32_t);
  // Read first to preserve ECC and scrambling bits.
  uint32_t reg = sec_mmio_read32(rram_ctrl_core_base() + cfg_offset);
  reg = bitfield_field32_write(reg, RRAM_CTRL_INFO_PAGE_CFG_0_EN_0_FIELD,
                               kMultiBitBool4True);
  reg = bitfield_field32_write(reg, RRAM_CTRL_INFO_PAGE_CFG_0_RD_EN_0_FIELD,
                               perms.read);
  reg = bitfield_field32_write(reg, RRAM_CTRL_INFO_PAGE_CFG_0_WR_EN_0_FIELD,
                               perms.write);
  sec_mmio_write32(rram_ctrl_core_base() + cfg_offset, reg);
}
 
void rram_ctrl_data_default_cfg_set(rram_ctrl_cfg_t cfg) {
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioDataDefaultCfgSet, 1);
 
  // Read first to preserve permission bits.
  uint32_t reg = sec_mmio_read32(rram_ctrl_core_base() +
                                 RRAM_CTRL_DEFAULT_REGION_REG_OFFSET);
  reg = bitfield_field32_write(reg, RRAM_CTRL_DEFAULT_REGION_SCRAMBLE_EN_FIELD,
                               cfg.scrambling);
  reg = bitfield_field32_write(reg, RRAM_CTRL_DEFAULT_REGION_ECC_EN_FIELD,
                               cfg.ecc);
  sec_mmio_write32(rram_ctrl_core_base() + RRAM_CTRL_DEFAULT_REGION_REG_OFFSET,
                   reg);
}
 
rram_ctrl_cfg_t rram_ctrl_data_default_cfg_get(void) {
  const uint32_t default_region = sec_mmio_read32(
      rram_ctrl_core_base() + RRAM_CTRL_DEFAULT_REGION_REG_OFFSET);
  return (rram_ctrl_cfg_t){
      .scrambling = bitfield_field32_read(
          default_region, RRAM_CTRL_DEFAULT_REGION_SCRAMBLE_EN_FIELD),
      .ecc = bitfield_field32_read(default_region,
                                   RRAM_CTRL_DEFAULT_REGION_ECC_EN_FIELD),
  };
}
 
rram_ctrl_cfg_t rram_ctrl_boot_data_cfg_get(void) {
  uint32_t otp_val =
      otp_read32(OTP_CTRL_PARAM_CREATOR_SW_CFG_NVM_INFO_BOOT_DATA_CFG_OFFSET);
  return (rram_ctrl_cfg_t){
      .scrambling =
          bitfield_field32_read(otp_val, RRAM_CTRL_OTP_FIELD_SCRAMBLING),
      .ecc = bitfield_field32_read(otp_val, RRAM_CTRL_OTP_FIELD_ECC),
  };
}
 
void rram_ctrl_data_region_protect(rram_ctrl_region_index_t region,
                                   uint32_t page_offset, uint32_t num_pages,
                                   rram_ctrl_perms_t perms, rram_ctrl_cfg_t cfg,
                                   hardened_bool_t lock) {
  const uint32_t kBase = rram_ctrl_core_base();
  HARDENED_CHECK_GE(region, 0);
  HARDENED_CHECK_LT(region, RRAM_CTRL_PARAM_NUM_REGIONS);
  // The hardware has no way to express an empty region
  // (`rram_ctrl_mp_region_sel.sv` matches `addr <= base + size`, inclusive,
  // so a zero size would protect exactly one page.
  HARDENED_CHECK_GE(num_pages, 1);
  region *= sizeof(uint32_t);
 
  // Reset the region's configuration via the MP_REGION_CFG_${region}
  // register. This temporarily disables memory protection for the region.
  //
  // We use abs_mmio here because we're going to re-write this value later
  // and the intermediate REG_RESVAL should not be considered a valid data
  // pattern in this register when we perform a sec_mmio check.
  abs_mmio_write32(kBase + RRAM_CTRL_MP_REGION_CFG_0_REG_OFFSET + region,
                   RRAM_CTRL_MP_REGION_CFG_0_REG_RESVAL);
 
  // Set the region's bounds in the MP_REGION_${region} register.
  //
  // `rram_ctrl_mp_region_sel.sv` matches `addr <= base + size` (inclusive),
  // one page past the exclusive `[page_offset, page_offset + num_pages)`
  // range this function documents. Write `num_pages - 1` to compensate, so
  // callers keep using the exclusive convention; safe since `num_pages` is
  // checked nonzero above.
  uint32_t mp_region = RRAM_CTRL_MP_REGION_0_REG_RESVAL;
  mp_region = bitfield_field32_write(
      mp_region, RRAM_CTRL_MP_REGION_0_BASE_0_FIELD, page_offset);
  mp_region = bitfield_field32_write(
      mp_region, RRAM_CTRL_MP_REGION_0_SIZE_0_FIELD, num_pages - 1);
  sec_mmio_write32(kBase + RRAM_CTRL_MP_REGION_0_REG_OFFSET + region,
                   mp_region);
 
  // Write the new value of MP_REGION_CFG_${region}.
  uint32_t mp_region_cfg = RRAM_CTRL_MP_REGION_CFG_0_REG_RESVAL;
  mp_region_cfg = bitfield_field32_write(
      mp_region_cfg, RRAM_CTRL_MP_REGION_CFG_0_ECC_EN_0_FIELD, cfg.ecc);
  mp_region_cfg = bitfield_field32_write(
      mp_region_cfg, RRAM_CTRL_MP_REGION_CFG_0_SCRAMBLE_EN_0_FIELD,
      cfg.scrambling);
  mp_region_cfg = bitfield_field32_write(
      mp_region_cfg, RRAM_CTRL_MP_REGION_CFG_0_WR_EN_0_FIELD, perms.write);
  mp_region_cfg = bitfield_field32_write(
      mp_region_cfg, RRAM_CTRL_MP_REGION_CFG_0_RD_EN_0_FIELD, perms.read);
  mp_region_cfg = bitfield_field32_write(
      mp_region_cfg, RRAM_CTRL_MP_REGION_CFG_0_EN_0_FIELD, kMultiBitBool4True);
 
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioDataRegionProtect, 2);
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioDataRegionProtectLock, 1);
  sec_mmio_write32(kBase + RRAM_CTRL_MP_REGION_CFG_0_REG_OFFSET + region,
                   mp_region_cfg);
  if (lock != kHardenedBoolFalse) {
    sec_mmio_write32(kBase + RRAM_CTRL_REGION_CFG_REGWEN_0_REG_OFFSET + region,
                     0);
  }
}
 
void rram_ctrl_info_cfg_set(const rram_ctrl_info_page_t *info_page,
                            rram_ctrl_cfg_t cfg) {
  HARDENED_CHECK_EQ(info_page->emulated, false);
  SEC_MMIO_ASSERT_WRITE_INCREMENT(kRramCtrlSecMmioInfoCfgSet, 1);
 
  uint32_t cfg_offset = RRAM_CTRL_INFO_PAGE_CFG_0_REG_OFFSET +
                        info_page->page_id * sizeof(uint32_t);
  // Read first to preserve permission bits.
  uint32_t reg = sec_mmio_read32(rram_ctrl_core_base() + cfg_offset);
  reg = bitfield_field32_write(reg, RRAM_CTRL_INFO_PAGE_CFG_0_EN_0_FIELD,
                               kMultiBitBool4True);
  reg = bitfield_field32_write(
      reg, RRAM_CTRL_INFO_PAGE_CFG_0_SCRAMBLE_EN_0_FIELD, cfg.scrambling);
  reg = bitfield_field32_write(reg, RRAM_CTRL_INFO_PAGE_CFG_0_ECC_EN_0_FIELD,
                               cfg.ecc);
  sec_mmio_write32(rram_ctrl_core_base() + cfg_offset, reg);
}
 
void rram_ctrl_info_cfg_lock(const rram_ctrl_info_page_t *info_page) {
  HARDENED_CHECK_EQ(info_page->emulated, false);
  uint32_t regwen_offset = RRAM_CTRL_INFO_REGWEN_0_REG_OFFSET +
                           info_page->page_id * sizeof(uint32_t);
  sec_mmio_write32(rram_ctrl_core_base() + regwen_offset, 0);
}
 
void rram_ctrl_info_page_lockdown(const rram_ctrl_info_page_t *info_page) {
  HARDENED_CHECK_EQ(info_page->emulated, false);
  uint32_t cfg_offset = RRAM_CTRL_INFO_PAGE_CFG_0_REG_OFFSET +
                        info_page->page_id * sizeof(uint32_t);
  uint32_t regwen_offset = RRAM_CTRL_INFO_REGWEN_0_REG_OFFSET +
                           info_page->page_id * sizeof(uint32_t);
  sec_mmio_write32(rram_ctrl_core_base() + cfg_offset, 0);
  sec_mmio_write32(rram_ctrl_core_base() + regwen_offset, 0);
}