ra8_hw_err.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
 
#include "ra8_err.h"
 
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
/* Host unit-test MMIO fault seam (tests/mocks/src/ra8_fake_mmio.c). Consulted once per
 * poll below so a test can drive a bounded wait to timeout or succeed-after-N,
 * exercising the real poll/timeout legs on host with the driver short-circuits
 * deleted (T1-01). Forward-declared here -- rather than including the test-only
 * header -- so this production header stays test-clean; the definition links
 * only into the host test binary. Absent in firmware and ra8_emulator builds, which
 * do not define UNIT_TEST and take the plain register-read path below. */
[[nodiscard]] bool ra8_fake_mmio_wait_eval(const volatile void* reg, uint32_t iter, bool real_cond);
/* Real-condition-honoring poll consult for the raw-loop status polls in the
 * i2c / i3c / sdhi drivers -- those were NOT written against ra8_hw_wait_* and
 * must keep their "flag_set -> exit, else spin to the bounded timeout" contract.
 * Unlike ra8_fake_mmio_wait_eval (unarmed -> true, the T1-01 short-circuit drop-in),
 * this returns @p flag_set when the register is unarmed, so an unprimed flag
 * still times out exactly as the pre-seam raw loop did and every existing test
 * keeps its behaviour. It also invokes any registered synchronous poll-hook first
 * (see ra8_fake_mmio_set_poll_hook) so a host test can model the peripheral on the
 * driver's OWN poll thread, deterministically and thread-free. */
[[nodiscard]] bool ra8_fake_mmio_poll(const volatile void* reg, uint32_t iter, bool flag_set);
[[nodiscard]] uint32_t ra8_fake_mmio_read_to_set32(volatile uint32_t* reg, uint32_t set_mask);

void ra8_fake_mmio_write1_clear32(volatile uint32_t* reg, uint32_t w1c_mask, uint32_t value);
#endif
 
/* =============================================================================
 * Default budgets
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_hw_budget_short  = 0x00000400U, 
  k_ra8_hw_budget_medium = 0x00004000U, 
  k_ra8_hw_budget_long   = 0x00040000U, 
  k_ra8_hw_budget_xlong  = 0x00400000U, 
} ra8_hw_err_budget_t;
 
/* =============================================================================
 * 8-bit waiters
 * =============================================================================
 */

static inline ra8_err_t
ra8_hw_wait_flag_set8(volatile const uint8_t* reg, uint8_t mask, uint32_t budget)
{
  if (reg == nullptr) {
    return k_ra8_err_null_ptr;
  }
  for (uint32_t i = 0U; i < budget; ++i) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(reg, i, ((*reg & mask) != 0U))) {
      return k_ra8_ok;
    }
#else
    if ((*reg & mask) != 0U) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

static inline ra8_err_t
ra8_hw_wait_flag_clear8(volatile const uint8_t* reg, uint8_t mask, uint32_t budget)
{
  if (reg == nullptr) {
    return k_ra8_err_null_ptr;
  }
  for (uint32_t i = 0U; i < budget; ++i) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(reg, i, ((*reg & mask) == 0U))) {
      return k_ra8_ok;
    }
#else
    if ((*reg & mask) == 0U) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}
 
/* =============================================================================
 * 32-bit waiters
 * =============================================================================
 */

static inline ra8_err_t
ra8_hw_wait_flag_set32(volatile const uint32_t* reg, uint32_t mask, uint32_t budget)
{
  if (reg == nullptr) {
    return k_ra8_err_null_ptr;
  }
  for (uint32_t i = 0U; i < budget; ++i) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(reg, i, ((*reg & mask) != 0U))) {
      return k_ra8_ok;
    }
#else
    if ((*reg & mask) != 0U) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

static inline ra8_err_t
ra8_hw_wait_flag_clear32(volatile const uint32_t* reg, uint32_t mask, uint32_t budget)
{
  if (reg == nullptr) {
    return k_ra8_err_null_ptr;
  }
  for (uint32_t i = 0U; i < budget; ++i) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    if (ra8_fake_mmio_wait_eval(reg, i, ((*reg & mask) == 0U))) {
      return k_ra8_ok;
    }
#else
    if ((*reg & mask) == 0U) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}
 
#ifdef __cplusplus
}
#endif