ra8_mstp.c

Go to the documentation of this file.

 
#include "ra8_mstp.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_bit_constants.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp_internal.h"
#include "ra8_mstp_regs.h"
 
/* =============================================================================
 * Local constants
 * =============================================================================
 */
 
static const char* s_tag = "MSTP";

typedef enum : uint8_t {
  k_ra8_mstp_reg_count = 5U,  
  k_ra8_mstp_bit_count = 32U, 
} ra8_mstp_dim_t;

typedef enum : uint16_t {
  k_ra8_mstp_readback_spin = 0x100U, 
} ra8_mstp_spin_t;

typedef enum : uint32_t {
  k_ra8_mstp_all_stopped    = 0xFFFFFFFFU, 
  k_ra8_mstp_safe_stopped_a = 0xFFFFFFF0U, 
} ra8_mstp_init_val_t;

typedef enum : uintptr_t {
  k_ra8_mstp_psarb_addr = 0x40204004U, 
  k_ra8_mstp_psarc_addr = 0x40204008U, 
  k_ra8_mstp_psard_addr = 0x4020400CU, 
  k_ra8_mstp_psare_addr = 0x40204010U, 
} ra8_mstp_psar_t;
 
/* =============================================================================
 * State
 * =============================================================================
 */

static uint8_t s_refcount[k_ra8_mstp_reg_count][k_ra8_mstp_bit_count];
 
/* =============================================================================
 * Public id decoders (declared in ra8_mstp_regs.h)
 * =============================================================================
 */
 
ra8_mstp_reg_t ra8_mstp_id_reg(ra8_mstp_t id)
{
  return (ra8_mstp_reg_t)(((uint16_t)id >> k_ra8_bits_per_byte) & k_ra8_mask_byte);
}
 
uint8_t ra8_mstp_id_bit(ra8_mstp_t id)
{
  return (uint8_t)((uint16_t)id & k_ra8_mask_byte);
}
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_INTERNAL static bool internal_decode(ra8_mstp_t id, uint8_t* out_reg, uint8_t* out_bit)
{
  const ra8_mstp_reg_t reg_id = ra8_mstp_id_reg(id);
  const uint8_t        reg    = (uint8_t)reg_id;
  const uint8_t        bit    = ra8_mstp_id_bit(id);
  if (reg >= k_ra8_mstp_reg_count) {
    return false;
  }
  if (bit >= k_ra8_mstp_bit_count) {
    return false;
  }
  *out_reg = reg;
  *out_bit = bit;
  return true;
}

RA8_INTERNAL static volatile uint32_t* internal_reg_ptr(uint8_t reg)
{
  return &(&ra8_mstp()->MSTPCRA)[reg];
}

RA8_INTERNAL static ra8_err_t
internal_wait_readback(uint8_t reg, uint8_t bit, bool expected_stopped)
{
  volatile const uint32_t* p    = internal_reg_ptr(reg);
  const uint32_t           mask = (uint32_t)1U << bit;
  for (uint16_t i = 0U; i < k_ra8_mstp_readback_spin; ++i) {
    const bool seen_stopped = (*p & mask) != 0U;
    const bool settled      = (seen_stopped == expected_stopped);
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam, keyed on the polled MSTPCR register. */
    if (ra8_fake_mmio_wait_eval(p, (uint32_t)i, settled)) {
      return k_ra8_ok;
    }
#else
    if (settled) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

ra8_err_t priv_ra8_mstp_wait_reg_settle_internal(uint8_t reg, uint32_t expect, uint32_t care_mask)
{
  volatile const uint32_t* p = internal_reg_ptr(reg);
  for (uint16_t i = 0U; i < k_ra8_mstp_readback_spin; ++i) {
    const bool settled = ((*p & care_mask) == (expect & care_mask));
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam, keyed on the polled MSTPCR register. */
    if (ra8_fake_mmio_wait_eval(p, (uint32_t)i, settled)) {
      return k_ra8_ok;
    }
#else
    if (settled) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

uint32_t priv_ra8_mstp_ns_mask_internal(uint8_t reg)
{
  /* MSTPCRA has no PSAR: always fully Secure-owned. */
  static const uintptr_t k_psar_addr[k_ra8_mstp_reg_count] = {
    0U,
    (uintptr_t)k_ra8_mstp_psarb_addr,
    (uintptr_t)k_ra8_mstp_psarc_addr,
    (uintptr_t)k_ra8_mstp_psard_addr,
    (uintptr_t)k_ra8_mstp_psare_addr,
  };
  if (k_psar_addr[reg] == 0U) {
    return 0U;
  }
  /* Read PSARB..PSARE (reg 1..4); the Non-secure-attributed bit mask.
   * HUM Ch 51.8.1 "PSARB : Peripheral Security Attribution Register B" p 3284 */
  return *(volatile const uint32_t*)k_psar_addr[reg];
}
 
/* =============================================================================
 * Public API
 * =============================================================================
 */
 
ra8_err_t ra8_mstp_init(void)
{
  ra8_log_info(s_tag, "ra8_mstp_init -- gating all modules");
 
  /* Reset every ref count. */
  for (uint8_t reg = 0U; reg < k_ra8_mstp_reg_count; ++reg) {
    for (uint8_t bit = 0U; bit < k_ra8_mstp_bit_count; ++bit) {
      s_refcount[reg][bit] = 0U;
    }
  }
 
  /* Stop all peripherals. MSTPCRA bits 0..3 (SRAM0..3) must stay 0
   * (running) or the CPU stack becomes inaccessible and causes a
   * BusFault. All other registers use the full all-stopped pattern.
   * HUM Ch 11.2.6..10 p 443..449. */
  static const uint32_t k_init_vals[k_ra8_mstp_reg_count] = {
    (uint32_t)k_ra8_mstp_safe_stopped_a, /* MSTPCRA: SRAM0-3 kept running */
    (uint32_t)k_ra8_mstp_all_stopped,    /* MSTPCRB                       */
    (uint32_t)k_ra8_mstp_all_stopped,    /* MSTPCRC                       */
    (uint32_t)k_ra8_mstp_all_stopped,    /* MSTPCRD                       */
    (uint32_t)k_ra8_mstp_all_stopped,    /* MSTPCRE                       */
  };
  /* HUM Ch 11.2.6 "MSTPCRA : Module Stop Control Register A", p 443 */
  *internal_reg_ptr(0U) = k_init_vals[0U];
  /* HUM Ch 11.2.7 "MSTPCRB : Module Stop Control Register B", p 444 */
  *internal_reg_ptr(1U) = k_init_vals[1U];
  /* HUM Ch 11.2.8 "MSTPCRC : Module Stop Control Register C", p 446 */
  *internal_reg_ptr(2U) = k_init_vals[2U];
  /* HUM Ch 11.2.9 "MSTPCRD : Module Stop Control Register D", p 448 */
  *internal_reg_ptr(3U) = k_init_vals[3U];
  /* HUM Ch 11.2.10 "MSTPCRE : Module Stop Control Register E", p 449 */
  *internal_reg_ptr(4U) = k_init_vals[4U];
 
  /* Read-back: each register must settle to the value written, but only for
   * the bits the Secure side actually owns. A Non-secure-attributed module
   * (PSAR bit set -- e.g. a USB controller delegated to a Non-secure world)
   * ignores the Secure module-stop write, so its bit will not read back the
   * commanded state; requiring it would spuriously fail boot on every
   * TrustZone system that delegates a peripheral. Masking the read-back by the
   * Secure-owned bits keeps a genuine stuck Secure module a hard failure while
   * tolerating the by-design Non-secure ones. On a non-TrustZone system the
   * mask is all-ones, so the check stays fully strict. */
  for (uint8_t reg = 0U; reg < k_ra8_mstp_reg_count; ++reg) {
    const uint32_t care = ~priv_ra8_mstp_ns_mask_internal(reg);
    if (priv_ra8_mstp_wait_reg_settle_internal(reg, k_init_vals[reg], care) != k_ra8_ok) {
      ra8_log_error_val(s_tag, "init read-back failed reg", (uint32_t)reg);
      return k_ra8_err_hw_timeout;
    }
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_mstp_enable(ra8_mstp_t id)
{
  uint8_t reg = 0U;
  uint8_t bit = 0U;
  if (!internal_decode(id, &reg, &bit)) {
    ra8_log_error_val(s_tag, "enable: invalid id", (uint32_t)id);
    return k_ra8_err_invalid_arg;
  }
 
  const uint8_t prev = s_refcount[reg][bit];
  if (prev == UINT8_MAX) {
    /* Defensive: 255 simultaneous users would mean a bug elsewhere. */
    ra8_log_error_val(s_tag, "enable: refcount saturated", (uint32_t)id);
    return k_ra8_err_invalid_state;
  }
  s_refcount[reg][bit] = (uint8_t)(prev + 1U);
 
  if (prev != 0U) {
    /* Already running. Nothing else to do. */
    return k_ra8_ok;
  }
 
  /* HUM Ch 11.2.6 "MSTPCRA : Module Stop Control Register A", p 443
   * -- bit clear == ungate the peripheral. */
  volatile uint32_t* p    = internal_reg_ptr(reg);
  const uint32_t     mask = (uint32_t)1U << bit;
  *p                      = *p & ~mask;
 
  const ra8_err_t err = internal_wait_readback(reg, bit, false);
  if (err != k_ra8_ok) {
    /* Roll the ref count back so a retry from the caller starts
     * fresh rather than thinking the module is already on. */
    s_refcount[reg][bit] = prev;
    ra8_log_error_val(s_tag, "enable: read-back timeout id", (uint32_t)id);
    return err;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_mstp_disable(ra8_mstp_t id)
{
  uint8_t reg = 0U;
  uint8_t bit = 0U;
  if (!internal_decode(id, &reg, &bit)) {
    ra8_log_error_val(s_tag, "disable: invalid id", (uint32_t)id);
    return k_ra8_err_invalid_arg;
  }
 
  const uint8_t prev = s_refcount[reg][bit];
  if (prev == 0U) {
    ra8_log_error_val(s_tag, "disable: refcount underflow", (uint32_t)id);
    return k_ra8_err_invalid_state;
  }
  s_refcount[reg][bit] = (uint8_t)(prev - 1U);
 
  if (prev != 1U) {
    /* Other users still active. Leave the bit cleared. */
    return k_ra8_ok;
  }
 
  /* HUM Ch 11.2.6 "MSTPCRA : Module Stop Control Register A", p 443
   * -- bit set == gate the peripheral. */
  volatile uint32_t* p    = internal_reg_ptr(reg);
  const uint32_t     mask = (uint32_t)1U << bit;
  *p                      = *p | mask;
 
  const ra8_err_t err = internal_wait_readback(reg, bit, true);
  if (err != k_ra8_ok) {
    /* Roll back so the next caller still sees the resource as in
     * use and we don't lose track of pending ungates. */
    s_refcount[reg][bit] = prev;
    ra8_log_error_val(s_tag, "disable: read-back timeout id", (uint32_t)id);
    return err;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_mstp_get_refcount(ra8_mstp_t id, uint8_t* out_ref)
{
  RA8_CHECK_NULL_PTR(out_ref, s_tag, "get_refcount: out_ref");
  uint8_t reg = 0U;
  uint8_t bit = 0U;
  if (!internal_decode(id, &reg, &bit)) {
    return k_ra8_err_invalid_arg;
  }
  *out_ref = s_refcount[reg][bit];
  return k_ra8_ok;
}
 
ra8_err_t ra8_mstp_is_stopped(ra8_mstp_t id, bool* out_stopped)
{
  RA8_CHECK_NULL_PTR(out_stopped, s_tag, "is_stopped: out_stopped");
  uint8_t reg = 0U;
  uint8_t bit = 0U;
  if (!internal_decode(id, &reg, &bit)) {
    return k_ra8_err_invalid_arg;
  }
  volatile const uint32_t* p    = internal_reg_ptr(reg);
  const uint32_t           mask = (uint32_t)1U << bit;
  *out_stopped                  = ((*p & mask) != 0U);
  return k_ra8_ok;
}