ra8_agt.c

Go to the documentation of this file.

 
#include "ra8_agt.h"
 
#include <stdint.h>
 
#include "ra8_agt_regs.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
 
static const char* s_tag = "AGT";

typedef enum : uint8_t {
  k_ra8_agt_mstp_id_count = 2U, 
} ra8_agt_mstp_limit_t;

static const ra8_mstp_t s_agt_mstp_table[k_ra8_agt_mstp_id_count] = {
  k_ra8_mstp_agt0,
  k_ra8_mstp_agt1,
};

static bool s_agt_mstp_held[k_ra8_agt_mstp_id_count];

RA8_INTERNAL static ra8_err_t internal_agt_mstp_acquire(uint8_t channel)
{
  if (channel >= k_ra8_agt_mstp_id_count) {
    return k_ra8_ok;
  }
  if (s_agt_mstp_held[channel]) {
    return k_ra8_ok;
  }
  /* HUM Ch 11.2.9 "MSTPCRD : Module Stop Control Register D" p 448 */
  const ra8_err_t err = ra8_mstp_enable(s_agt_mstp_table[channel]);
  if (err != k_ra8_ok) {
    return err;
  }
  s_agt_mstp_held[channel] = true;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_agt_mstp_release(uint8_t channel)
{
  if (channel >= k_ra8_agt_mstp_id_count) {
    return k_ra8_ok;
  }
  if (!s_agt_mstp_held[channel]) {
    return k_ra8_ok;
  }
  s_agt_mstp_held[channel] = false;
  /* HUM Ch 11.2.9 "MSTPCRD : Module Stop Control Register D" p 448 */
  return ra8_mstp_disable(s_agt_mstp_table[channel]);
}
 
[[nodiscard]] ra8_err_t ra8_agt_start_free_run(uint8_t channel, uint16_t reload)
{
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
 
  /* Acquire the per-channel MSTP reference once (issue #68). */
  const ra8_err_t mst_err = internal_agt_mstp_acquire(channel);
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "agt_start: mstp enable");
 
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  /* HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168 -- timer mode,
   * PCLKB source. */
  reg->AGTMR1 = 0U;
  /* HUM Ch 24.2.6 "AGTMR2 : AGT Mode Register 2" p 1169 */
  reg->AGTMR2 = 0U;
  /* HUM Ch 24.2.1 "AGT : AGT Counter" p 1165 */
  reg->AGT = reload;
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  /* TSTART = 1. */
  reg->AGTCR = 0x01U;
 
  ra8_log_info_val(s_tag, "start channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_agt_stop(uint8_t channel)
{
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  return k_ra8_ok;
}
 
/* =============================================================================
 * full build-out
 * =============================================================================
 */
 
static ra8_agt_event_fn_t s_agt_fn;
static void*              s_agt_ctx;

ra8_err_t ra8_agt_deinit(uint8_t channel)
{
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  return internal_agt_mstp_release(channel);
}

ra8_err_t ra8_agt_set_reload(uint8_t channel, uint16_t reload)
{
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
  /* HUM Ch 24.2.1 "AGT : AGT Counter" p 1165 */
  reg->AGT = reload;
  return k_ra8_ok;
}

ra8_err_t ra8_agt_get_status(uint8_t channel, uint8_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "out_mask must not be nullptr");
  volatile const r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  *out_mask = reg->AGTCR;
  return k_ra8_ok;
}

ra8_err_t ra8_agt_attach_handler(ra8_agt_event_fn_t fn, void* ctx)
{
  s_agt_fn  = fn;
  s_agt_ctx = ctx;
  return k_ra8_ok;
}

RA8_ISR_SAFE
void ra8_agt_dispatch(uint8_t channel)
{
  if (ra8_agt(channel) == nullptr) {
    return;
  }
  const ra8_agt_event_fn_t fn  = s_agt_fn;
  void* const              ctx = s_agt_ctx;
  if (fn != nullptr) {
    fn(ctx, channel);
  }
}

ra8_err_t ra8_agt_enter_stop(uint8_t channel)
{
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  return internal_agt_mstp_release(channel);
}

ra8_err_t ra8_agt_exit_stop(uint8_t channel)
{
  if (ra8_agt(channel) == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  return internal_agt_mstp_acquire(channel);
}
 
/* =============================================================================
 * Pulse-output mode -- HUM Ch 24.3.4 p 1177
 * =============================================================================
 */

RA8_INTERNAL static uint8_t internal_agt_pulse_agtioc_value(ra8_agt_output_polarity_t polarity)
{
  uint8_t v = (uint8_t)k_ra8_agt_agtioc_toe_msk;
  if (polarity == k_ra8_agt_output_polarity_active_high) {
    v |= (uint8_t)k_ra8_agt_agtioc_tedgsel_msk;
  }
  return v;
}

RA8_INTERNAL static uint8_t internal_agt_pulse_agtcmsr_value(ra8_agt_pulse_compare_t compare)
{
  if (compare == k_ra8_agt_pulse_compare_a) {
    return (uint8_t)(k_ra8_agt_agtcmsr_tcmea_msk | k_ra8_agt_agtcmsr_toea_msk);
  }
  if (compare == k_ra8_agt_pulse_compare_b) {
    return (uint8_t)(k_ra8_agt_agtcmsr_tcmeb_msk | k_ra8_agt_agtcmsr_toeb_msk);
  }
  return 0U;
}

RA8_INTERNAL static void internal_agt_pulse_program_compare(volatile r_agt_regs_t*  reg,
                                                            ra8_agt_pulse_compare_t compare,
                                                            uint16_t                duty)
{
  const uint16_t parked = (uint16_t)k_ra8_agt_compare_parked_value;
  /* HUM Ch 24.2.2 "AGTCMA : AGT Compare Match A Register" p 1166 */
  reg->AGTCMA = (compare == k_ra8_agt_pulse_compare_a) ? duty : parked;
  /* HUM Ch 24.2.3 "AGTCMB : AGT Compare Match B Register" p 1166 */
  reg->AGTCMB = (compare == k_ra8_agt_pulse_compare_b) ? duty : parked;
}

RA8_INTERNAL static ra8_err_t internal_agt_pulse_validate_cfg(const ra8_agt_pulse_cfg_t* cfg)
{
  if ((cfg->compare != k_ra8_agt_pulse_compare_none) &&
      (cfg->compare != k_ra8_agt_pulse_compare_a) && (cfg->compare != k_ra8_agt_pulse_compare_b)) {
    return k_ra8_err_invalid_arg;
  }
  if ((cfg->polarity != k_ra8_agt_output_polarity_active_high) &&
      (cfg->polarity != k_ra8_agt_output_polarity_active_low)) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_agt_pulse_program_registers(volatile r_agt_regs_t*     reg,
                                                              const ra8_agt_pulse_cfg_t* cfg)
{
  /* Stop first. */
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  /* TMOD=001b (pulse output mode), TCK = PCLKB. */
  /* HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168 */
  reg->AGTMR1 = (uint8_t)k_ra8_agt_agtmr1_tmod_pulse_output;
  /* HUM Ch 24.2.6 "AGTMR2 : AGT Mode Register 2" p 1169 */
  reg->AGTMR2 = 0U;
  /* TOE = 1, polarity from the config. */
  /* HUM Ch 24.2.7 "AGTIOC : AGT I/O Control Register" p 1170 */
  reg->AGTIOC = internal_agt_pulse_agtioc_value(cfg->polarity);
  /* HUM Ch 24.2.9 "AGTCMSR : AGT Compare Match Function Select" p 1172 */
  reg->AGTCMSR = internal_agt_pulse_agtcmsr_value(cfg->compare);
  internal_agt_pulse_program_compare(reg, cfg->compare, cfg->duty);
  /* HUM Ch 24.2.1 "AGT : AGT Counter" p 1165 */
  reg->AGT = cfg->period;
}

ra8_err_t ra8_agt_start_pulse_output(uint8_t channel, const ra8_agt_pulse_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  volatile r_agt_regs_t* reg = ra8_agt(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
 
  const ra8_err_t verr = internal_agt_pulse_validate_cfg(cfg);
  RA8_RETURN_ON_ERROR(verr, s_tag, "agt_pulse: cfg validation");
 
  /* Acquire the per-channel MSTP reference once (issue #68). */
  const ra8_err_t mst_err = internal_agt_mstp_acquire(channel);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "agt_pulse: mstp enable");
  /* GCOVR_EXCL_BR_STOP */
 
  internal_agt_pulse_program_registers(reg, cfg);
 
  /* TSTART = 1. */
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = (uint8_t)k_ra8_agt_agtcr_tstart_msk;
 
  /* One-shot mode is implemented at the polling layer: the caller
   * inspects AGTCR.TUNDF and calls ra8_agt_stop() once it sees the
   * first underflow. The hardware itself only knows continuous
   * pulse output (HUM Ch 24.3.4 p 1177). */
  (void)cfg->mode;
 
  ra8_log_info_val(s_tag, "pulse start channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
/* =============================================================================
 * Cascade mode -- HUM Ch 24.1 Table 24.1 p 1164 + Ch 24.2.5 p 1168 note 6
 * =============================================================================
 */

RA8_INTERNAL static ra8_err_t internal_agt_cascade_clock_to_tck(ra8_agt_cascade_clk_t clock,
                                                                uint8_t*              out_tck)
{
  switch (clock) {
    case k_ra8_agt_cascade_clk_pclkb:
      *out_tck = (uint8_t)k_ra8_agt_agtmr1_tck_pclkb;
      return k_ra8_ok;
    case k_ra8_agt_cascade_clk_pclkb_div8:
      *out_tck = (uint8_t)k_ra8_agt_agtmr1_tck_pclkb_div8;
      return k_ra8_ok;
    case k_ra8_agt_cascade_clk_pclkb_div2:
      *out_tck = (uint8_t)k_ra8_agt_agtmr1_tck_pclkb_div2;
      return k_ra8_ok;
    default:
      return k_ra8_err_invalid_arg;
  }
}

RA8_INTERNAL static void
internal_agt_cascade_arm_half(volatile r_agt_regs_t* reg, uint8_t tmr1, uint16_t reload)
{
  /* Stop the channel before touching the mode-control regs. */
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  reg->AGTCR = 0U;
  /* HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168 */
  reg->AGTMR1 = tmr1;
  /* HUM Ch 24.2.6 "AGTMR2 : AGT Mode Register 2" p 1169 */
  reg->AGTMR2 = 0U;
  /* No external output in cascade timer mode. */
  /* HUM Ch 24.2.7 "AGTIOC : AGT I/O Control Register" p 1170 */
  reg->AGTIOC = 0U;
  /* No compare-match output. */
  /* HUM Ch 24.2.9 "AGTCMSR : AGT Compare Match Function Select" p 1172 */
  reg->AGTCMSR = 0U;
  /* HUM Ch 24.2.1 "AGT : AGT Counter" p 1165 */
  reg->AGT = reload;
}

typedef enum : uint32_t {
  k_ra8_agt_cascade_lo_mask  = 0xFFFFU, 
  k_ra8_agt_cascade_hi_shift = 16U,     
} ra8_agt_cascade_split_t;

RA8_INTERNAL static ra8_err_t internal_agt_cascade_mstp_enable_both(void)
{
  /* One MSTP reference per channel (issue #68): re-arming the cascade every
   * AGT1 underflow must not leak a fresh AGT0/AGT1 reference per period. */
  const ra8_err_t m0 = internal_agt_mstp_acquire((uint8_t)k_ra8_agt_cascade_lo_channel);
  RA8_RETURN_ON_ERROR(m0, s_tag, "cascade: mstp AGT0");
  const ra8_err_t m1 = internal_agt_mstp_acquire((uint8_t)k_ra8_agt_cascade_hi_channel);
  RA8_RETURN_ON_ERROR(m1, s_tag, "cascade: mstp AGT1");
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_agt_cascade_program_and_start(volatile r_agt_regs_t* lo,
                                                                volatile r_agt_regs_t* hi,
                                                                uint32_t               reload32,
                                                                uint8_t                tck_lo)
{
  const uint16_t reload_lo = (uint16_t)(reload32 & (uint32_t)k_ra8_agt_cascade_lo_mask);
  const uint16_t reload_hi = (uint16_t)((reload32 >> (uint32_t)k_ra8_agt_cascade_hi_shift) &
                                        (uint32_t)k_ra8_agt_cascade_lo_mask);
 
  /* HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168 */
  const uint8_t tmr1_lo = (uint8_t)((uint8_t)k_ra8_agt_agtmr1_tmod_timer | tck_lo);
  /* HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168 */
  const uint8_t tmr1_hi =
    (uint8_t)((uint8_t)k_ra8_agt_agtmr1_tmod_timer | (uint8_t)k_ra8_agt_agtmr1_tck_agt0_underflow);
 
  internal_agt_cascade_arm_half(lo, tmr1_lo, reload_lo);
  internal_agt_cascade_arm_half(hi, tmr1_hi, reload_hi);
 
  /* Start AGT1 first so it samples the AGT0 underflow on the very */
  /* first cycle. */
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  hi->AGTCR = (uint8_t)k_ra8_agt_agtcr_tstart_msk;
  /* HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 */
  lo->AGTCR = (uint8_t)k_ra8_agt_agtcr_tstart_msk;
}

RA8_INTERNAL static void internal_agt_cascade_install_callback(const ra8_agt_cascade_cfg_t* cfg)
{
  if (cfg->on_underflow != nullptr) {
    s_agt_fn  = cfg->on_underflow;
    s_agt_ctx = cfg->ctx;
  }
}

RA8_INTERNAL static ra8_err_t internal_agt_cascade_resolve_halves(volatile r_agt_regs_t** out_lo,
                                                                  volatile r_agt_regs_t** out_hi)
{
  *out_lo = ra8_agt((uint8_t)k_ra8_agt_cascade_lo_channel);
  *out_hi = ra8_agt((uint8_t)k_ra8_agt_cascade_hi_channel);
  RA8_CHECK_NULL_PTR(*out_lo, s_tag, "cascade: AGT0 unavailable");
  RA8_CHECK_NULL_PTR(*out_hi, s_tag, "cascade: AGT1 unavailable");
  return k_ra8_ok;
}

ra8_err_t ra8_agt_start_cascade(const ra8_agt_cascade_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  uint8_t         tck_lo = 0U;
  const ra8_err_t cerr   = internal_agt_cascade_clock_to_tck(cfg->clock, &tck_lo);
  RA8_RETURN_ON_ERROR(cerr, s_tag, "cascade: bad clock enum");
 
  volatile r_agt_regs_t* lo   = nullptr;
  volatile r_agt_regs_t* hi   = nullptr;
  const ra8_err_t        herr = internal_agt_cascade_resolve_halves(&lo, &hi);
  RA8_RETURN_ON_ERROR(herr, s_tag, "cascade: half resolve");
 
  const ra8_err_t merr = internal_agt_cascade_mstp_enable_both();
  RA8_RETURN_ON_ERROR(merr, s_tag, "cascade: mstp enable");
 
  internal_agt_cascade_program_and_start(lo, hi, cfg->reload32, tck_lo);
  internal_agt_cascade_install_callback(cfg);
  ra8_log_info_val(s_tag, "cascade start", cfg->reload32);
  return k_ra8_ok;
}