ra8_rmac.c

Go to the documentation of this file.

 
#include "ra8_rmac.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_ether_regs.h"
#include "ra8_hal_internal.h"
#include "ra8_hw_err.h"
#include "ra8_hw_intrinsics.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_rmac_regs.h"

static const char* s_tag = "RMAC";

typedef enum : uint32_t {
  k_rmac_pipp_pos   = 9U,    
  k_rmac_pfrlv_mask = 0x1FU, 
} rmac_field_t;

typedef enum : uint32_t {
  k_ra8_rmac_mdio_poll_budget = 100000UL, 
} ra8_rmac_internal_t;

typedef enum : uint8_t {
  k_ra8_rmac_shift_mpfc_te0    = 16U, 
  k_ra8_rmac_shift_mpfc_te1    = 17U, 
  k_ra8_rmac_shift_mtpfc_pfrlv = 27U, 
  k_ra8_rmac_shift_mtpfc2_pfm  = 26U, 
} ra8_rmac_bit_pos_t;

typedef struct {
  ra8_rmac_event_fn_t cb;            
  void*               ctx;           
  ra8_rmac_mrafc_t    cached_filter; 
  uint8_t             in_use;        
} ra8_rmac_slot_t;

static ra8_rmac_slot_t s_slots[k_ra8_rmac_port_count];

RA8_INTERNAL
static inline bool internal_pis_ok(ra8_rmac_pis_t iface)
{
  if (iface == k_ra8_rmac_pis_mii) {
    return true;
  }
  if (iface == k_ra8_rmac_pis_gmii) {
    return true;
  }
  return false;
}

RA8_INTERNAL
static inline uint32_t internal_calc_psmcs(uint32_t eswclk_hz, uint32_t mdc_hz)
{
  /* Defensive clamp: ESWCLK = 0 means the chip's CGC has not been
   * configured; pick the slowest MDC the field can encode so the PHY
   * has the best chance of latching. ``mdc_hz`` is guaranteed non-zero
   * by the only caller (``internal_program_mac_config`` substitutes
   * ``k_ra8_rmac_mdc_default_hz`` when ``cfg->mdc_hz`` is 0), so a
   * single early-return on eswclk_hz==0 is sufficient. */
  if (eswclk_hz == 0U) {
    return (uint32_t)k_ra8_rmac_mdc_psmcs_max;
  }
  /* Same defensive clamp on mdc_hz to avoid undefined integer div if
   * a future caller bypasses the substitution above. */
  if (mdc_hz == 0U) {
    return (uint32_t)k_ra8_rmac_mdc_psmcs_max;
  }
  uint32_t psmcs = ((eswclk_hz / mdc_hz) / 2U);
  if (psmcs == 0U) {
    psmcs = 1U;
  }
  psmcs -= 1U;
  if (psmcs > (uint32_t)k_ra8_rmac_mdc_psmcs_max) {
    psmcs = (uint32_t)k_ra8_rmac_mdc_psmcs_max;
  }
  return psmcs;
}

RA8_INTERNAL
static inline uint32_t internal_make_mpic(ra8_rmac_pis_t    iface,
                                          ra8_rmac_lsc_t    speed,
                                          ra8_rmac_duplex_t duplex,
                                          uint32_t          psmcs)
{
  /* HUM Ch 33.4 "MPIC : PHY Interfaces Configuration Register" p 1709 */
  const uint32_t pis         = ((uint32_t)iface & k_ra8_rmac_mask_mpic_pis)
                               << (uint32_t)k_ra8_rmac_shift_mpic_pis;
  const uint32_t lsc         = ((uint32_t)speed & k_ra8_rmac_mask_mpic_lsc)
                               << (uint32_t)k_ra8_rmac_shift_mpic_lsc;
  const uint32_t pipp        = (duplex == k_ra8_rmac_duplex_full) ? (1U << k_rmac_pipp_pos) : 0U;
  const uint32_t psmcs_field = (psmcs & k_ra8_rmac_mask_mpic_psmcs)
                               << (uint32_t)k_ra8_rmac_shift_mpic_psmcs;
  return pis | lsc | pipp | psmcs_field;
}

RA8_INTERNAL
static ra8_err_t internal_mdio_drain(volatile r_rmac_regs_t* reg)
{
  /* Bounded wait for MPSM.PSME to self-clear to 0 (HUM Note 2: a write
   * to MPSM while PSME=1 has no effect, so the bus must be idle first).
   * ra8_hw_wait_flag_clear32 runs the same real poll/timeout loop on the
   * host unit-test build, where each iteration is routed through the
   * ra8_fake_mmio seam so a test can drive PSME clearing or a timeout. */
  return ra8_hw_wait_flag_clear32(&reg->MPSM,
                                  (uint32_t)k_ra8_rmac_mpsm_psme,
                                  (uint32_t)k_ra8_rmac_mdio_poll_budget);
}

RA8_INTERNAL
static ra8_err_t internal_mdio_wait(volatile r_rmac_regs_t* reg, uint32_t mask)
{
  for (uint32_t i = 0; i < k_ra8_rmac_mdio_poll_budget; ++i) {
    /* HUM Ch 33.4.1.1 "MPSM : PHY Station Management Register" p 1708 */
    const bool done = ((reg->MPSM & (uint32_t)k_ra8_rmac_mpsm_psme) == 0U);
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam, keyed on MPSM (the polled register). */
    if (ra8_fake_mmio_wait_eval(&reg->MPSM, i, done)) {
      /* HUM Ch 33 "MMID1 / MMIS1" p 1707 */
      reg->MMID1 = mask;
      return k_ra8_ok;
    }
#else
    if (done) {
      /* HUM Ch 33 "MMID1 / MMIS1" p 1707 */
      reg->MMID1 = mask;
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
static void internal_mpsm_issue(volatile r_rmac_regs_t* reg,
                                uint8_t                 pda_5bit,
                                uint8_t                 pra_5bit,
                                ra8_rmac_mdio_op_t      op,
                                uint16_t                prd_16bit,
                                bool                    mff)
{
  /* HUM Ch 33.4.1.1 "MPSM : PHY Station Management Register" p 1707 */
  const uint32_t pda     = ((uint32_t)pda_5bit & k_ra8_rmac_mask_mpsm_phy_reg)
                           << (uint32_t)k_ra8_rmac_shift_mpsm_pda;
  const uint32_t pra     = ((uint32_t)pra_5bit & k_ra8_rmac_mask_mpsm_phy_reg)
                           << (uint32_t)k_ra8_rmac_shift_mpsm_pra;
  const uint32_t pop     = ((uint32_t)op & k_ra8_rmac_mask_mpsm_op)
                           << (uint32_t)k_ra8_rmac_shift_mpsm_pop;
  const uint32_t prd     = ((uint32_t)prd_16bit & k_ra8_rmac_mask_mpsm_data)
                           << (uint32_t)k_ra8_rmac_shift_mpsm_prd;
  uint32_t       mff_bit = 0UL;
  if (mff) {
    mff_bit = (1UL << 2U);
  }
  /* Clear any stale MMIS1 completion bits from the previous
   * transaction BEFORE launching this one, so the post-wait can
   * never short-circuit on a leftover status bit. MMID1 is the
   * write-1-to-clear alias of MMIS1. */
  /* HUM Ch 33 "MMID1 / MMIS1" p 1707 */
  reg->MMID1 = k_ra8_rmac_mask_all;
  /* PSME = bit 0 -- starts the transaction. The caller has already
   * drained PSME to 0 via internal_mdio_drain, so this write is
   * honoured (HUM Note 2: a write while PSME=1 has no effect). */
  /* HUM Ch 33.4.1.1 "MPSM : PHY Station Management Register" p 1707 */
  reg->MPSM = pda | pra | pop | prd | mff_bit | (uint32_t)k_ra8_rmac_mpsm_psme;
  /* Ensure the issuing write reaches the peripheral before the post-wait
   * starts polling MPSM (host no-op via the ra8_hw_intrinsics seam). */
  ra8_hw_dsb();
}

RA8_INTERNAL
static void internal_program_mac_config(volatile r_rmac_regs_t* reg, const ra8_rmac_config_t* cfg)
{
  reg->MIOC             = 0U;
  reg->MTFFC            = 0U;
  reg->MRMAC0           = 0U;
  reg->MRMAC1           = 0U;
  reg->MRGC             = 0U;
  reg->MRAFC            = (uint32_t)cfg->rx_filter;
  reg->MLBC             = 0U;
  reg->MEEEC            = 0U;
  const uint32_t mdc_hz = (cfg->mdc_hz != 0U) ? cfg->mdc_hz : (uint32_t)k_ra8_rmac_mdc_default_hz;
  const uint32_t psmcs  = internal_calc_psmcs(cfg->eswclk_hz, mdc_hz);
  reg->MPIC = internal_make_mpic(cfg->phy_interface, cfg->link_speed, cfg->duplex, psmcs);
}

RA8_INTERNAL
static void internal_program_irq_block(volatile r_rmac_regs_t* reg, const ra8_rmac_config_t* cfg)
{
  reg->MEID  = k_ra8_rmac_mask_all;
  reg->MMID0 = k_ra8_rmac_mask_all;
  reg->MMID1 = k_ra8_rmac_mask_all;
  reg->MMID2 = k_ra8_rmac_mask_all;
 
  reg->MEIE  = cfg->err_irq_enable;
  reg->MMIE0 = cfg->mon0_irq_enable;
  reg->MMIE1 = cfg->mon1_irq_enable;
  reg->MMIE2 = cfg->mon2_irq_enable;
}
 
ra8_err_t ra8_rmac_init(ra8_rmac_port_t port, const ra8_rmac_config_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "rmac_init: cfg must not be nullptr");
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "rmac_init: port out of range");
    return k_ra8_err_invalid_arg;
  }
  if (!internal_pis_ok(cfg->phy_interface)) {
    ra8_log_error(s_tag, "rmac_init: phy_interface out of range");
    return k_ra8_err_invalid_arg;
  }
  if ((uint8_t)cfg->link_speed >= k_ra8_rmac_lsc_count) {
    ra8_log_error(s_tag, "rmac_init: link_speed out of range");
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 11.2.8 "MSTPCRC : Module Stop Control Register C" p 446 */
  const ra8_err_t mst_err = ra8_mstp_enable(k_ra8_mstp_eswm);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "rmac_init: mstp enable");
  /* GCOVR_EXCL_BR_STOP */
 
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  internal_program_mac_config(reg, cfg);
  internal_program_irq_block(reg, cfg);
 
  s_slots[(uint8_t)port].cb            = nullptr;
  s_slots[(uint8_t)port].ctx           = nullptr;
  s_slots[(uint8_t)port].cached_filter = cfg->rx_filter;
  s_slots[(uint8_t)port].in_use        = 1U;
  ra8_log_info(s_tag, "rmac_init");
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_deinit(ra8_rmac_port_t port)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "rmac_deinit: port out of range");
    return k_ra8_err_invalid_arg;
  }
 
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
 
  /* HUM Ch 33.4 "MRAFC : MAC Reception Address Filter Configuration Register" p 1717 */
  reg->MRAFC = 0U;
  /* HUM Ch 33.4 "MRGC : MAC Reception General Configuration Register" p 1715 */
  reg->MRGC = 0U;
  /* HUM Ch 33.4 "MTFFC : MAC Transmission Frame Format Configuration Register" p 1711 */
  reg->MTFFC = 0U;
  /* HUM Ch 33.4 "MLBC : MAC Loopback Configuration Register" p 1726 */
  reg->MLBC = 0U;
  /* HUM Ch 33.4 "MEEEC : MAC Energy Efficient Ethernet Configuration Register" p 1726 */
  reg->MEEEC = 0U;
  /* HUM Ch 33.4 "MEIE : MAC Error Interrupt Enable Register" p 1751 */
  reg->MEIE = 0U;
  /* HUM Ch 33.4 "MMIE0 : MAC Monitoring Interrupt Enable Register 0" p 1757 */
  reg->MMIE0 = 0U;
  /* HUM Ch 33.4 "MMIE1 : MAC Monitoring Interrupt Enable Register 1" p 1759 */
  reg->MMIE1 = 0U;
  /* HUM Ch 33.4 "MMIE2 : MAC Monitoring Interrupt Enable Register 2" p 1762 */
  reg->MMIE2 = 0U;
 
  s_slots[(uint8_t)port].cb     = nullptr;
  s_slots[(uint8_t)port].ctx    = nullptr;
  s_slots[(uint8_t)port].in_use = 0U;
  /* MSTP gate is shared with the rest of the Ethernet subsystem; do
   * NOT drop it here. ra8_eth_deinit owns the final reference. */
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_enter_stop(ra8_rmac_port_t port)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "rmac_enter_stop: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MRAFC : MAC Reception Address Filter Configuration Register" p 1717 */
  ra8_rmac(port)->MRAFC = 0U;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_exit_stop(ra8_rmac_port_t port)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "rmac_exit_stop: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MRAFC : MAC Reception Address Filter Configuration Register" p 1717 */
  ra8_rmac(port)->MRAFC = (uint32_t)s_slots[(uint8_t)port].cached_filter;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_mac_address(ra8_rmac_port_t port,
                                   const uint8_t   mac[k_ra8_rmac_mac_byte_count])
{
  RA8_CHECK_NULL_PTR(mac, s_tag, "set_mac_address: mac must not be nullptr");
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_mac_address: port out of range");
    return k_ra8_err_invalid_arg;
  }
 
  /* MRMAC0.MAU holds the upper 16 bits (bytes 0..1, MSB at bit 15);
   * MRMAC1.MAL holds the lower 32 bits (bytes 2..5, mac[2] in [31:24]).
   * Source: HUM Ch 33.4 "MRMAC0/MRMAC1 : MAC Reception MAC Address
   * Configuration Registers" p 1707, cross-checked against FSP
   * R_RMAC0_Type.MRMAC0_b.MAU and .MRMAC1_b.MAL. */
  const uint32_t b0 = (uint32_t)mac[k_ra8_rmac_mac_byte_0] & k_ra8_rmac_mask_byte;
  const uint32_t b1 = (uint32_t)mac[k_ra8_rmac_mac_byte_1] & k_ra8_rmac_mask_byte;
  const uint32_t b2 = (uint32_t)mac[k_ra8_rmac_mac_byte_2] & k_ra8_rmac_mask_byte;
  const uint32_t b3 = (uint32_t)mac[k_ra8_rmac_mac_byte_3] & k_ra8_rmac_mask_byte;
  const uint32_t b4 = (uint32_t)mac[k_ra8_rmac_mac_byte_4] & k_ra8_rmac_mask_byte;
  const uint32_t b5 = (uint32_t)mac[k_ra8_rmac_mac_byte_5] & k_ra8_rmac_mask_byte;
 
  const uint32_t mrmac0 =
    ((b0 << (uint32_t)k_ra8_rmac_shift_high24) | (b1 << (uint32_t)k_ra8_rmac_shift_high16)) &
    k_ra8_rmac_mask_mrmac0_mau;
  const uint32_t mrmac1 =
    (b2 << (uint32_t)k_ra8_rmac_shift_byte3) | (b3 << (uint32_t)k_ra8_rmac_shift_byte2) |
    (b4 << (uint32_t)k_ra8_rmac_shift_byte1) | (b5 << (uint32_t)k_ra8_rmac_shift_byte0);
 
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* HUM Ch 33.4 "MRMAC0 : MAC Reception MAC Address Configuration Register 0" p 1716 */
  reg->MRMAC0 = mrmac0;
  /* HUM Ch 33.4 "MRMAC1 : MAC Reception MAC Address Configuration Register 1" p 1717 */
  reg->MRMAC1 = mrmac1;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_rx_filter(ra8_rmac_port_t port, ra8_rmac_mrafc_t filter)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_rx_filter: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MRAFC : MAC Reception Address Filter Configuration Register" p 1717 */
  ra8_rmac(port)->MRAFC                = (uint32_t)filter;
  s_slots[(uint8_t)port].cached_filter = filter;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_ptp_filter(ra8_rmac_port_t port,
                                  uint8_t         index,
                                  uint8_t         byte_offset,
                                  uint8_t         value,
                                  bool            tef0,
                                  bool            tef1)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_ptp_filter: port out of range");
    return k_ra8_err_invalid_arg;
  }
  if (index >= k_ra8_rmac_ptp_filter_count) {
    ra8_log_error(s_tag, "set_ptp_filter: index out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MPFCt : MAC PTP Filtering Register Configuration t" p 1724 */
  const uint32_t pfbn = (uint32_t)byte_offset & k_ra8_rmac_mask_byte;
  const uint32_t pfbv = ((uint32_t)value & k_ra8_rmac_mask_byte)
                        << (uint32_t)k_ra8_rmac_shift_mpfc_val;
  uint32_t       te   = 0UL;
  if (tef0) {
    te |= (1UL << (uint32_t)k_ra8_rmac_shift_mpfc_te0);
  }
  if (tef1) {
    te |= (1UL << (uint32_t)k_ra8_rmac_shift_mpfc_te1);
  }
  ra8_rmac(port)->MPFC[index] = pfbn | pfbv | te;
  return k_ra8_ok;
}
 
ra8_err_t
ra8_rmac_set_frame_size(ra8_rmac_port_t port, bool is_pframe, uint16_t min_size, uint16_t max_size)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_frame_size: port out of range");
    return k_ra8_err_invalid_arg;
  }
  if (min_size > max_size) {
    ra8_log_error(s_tag, "set_frame_size: min > max");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MRFSCE / MRFSCP : MAC Reception Frame Size Configuration" p 1707 */
  const uint32_t v =
    (((uint32_t)max_size & k_ra8_rmac_mask_mrfsc) << (uint32_t)k_ra8_rmac_shift_mrfsce_max) |
    (((uint32_t)min_size & k_ra8_rmac_mask_mrfsc) << (uint32_t)k_ra8_rmac_shift_mrfsce_min);
  if (is_pframe) {
    ra8_rmac(port)->MRFSCP = v;
  } else {
    ra8_rmac(port)->MRFSCE = v;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_vlan_framing(ra8_rmac_port_t port, bool disable_pad, bool use_mcrc)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_vlan_framing: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MTFFC : MAC Transmission Frame Format Configuration" p 1711 */
  uint32_t v = 0UL;
  if (disable_pad) {
    v |= k_ra8_rmac_mtffc_dpad;
  }
  if (use_mcrc) {
    v |= k_ra8_rmac_mtffc_fcm;
  }
  ra8_rmac(port)->MTFFC = v;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_pause_frame(ra8_rmac_port_t       port,
                                   ra8_rmac_pause_mode_t mode,
                                   uint16_t              pause_time,
                                   uint8_t               retry_time,
                                   uint8_t               retry_level)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_pause_frame: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MTPFC : MAC Transmission Pause or PFC Frame Configuration" p 1712 */
  const uint32_t pt    = ((uint32_t)pause_time & k_ra8_rmac_mask_mtpfc_pt)
                         << (uint32_t)k_ra8_rmac_shift_mtpfc_pt;
  const uint32_t pfrt  = ((uint32_t)retry_time & k_ra8_rmac_mask_mtpfc_pfrt)
                         << (uint32_t)k_ra8_rmac_shift_mtpfc_pfrt;
  const uint32_t pfrlv = ((uint32_t)retry_level & k_rmac_pfrlv_mask)
                         << (uint32_t)k_ra8_rmac_shift_mtpfc_pfrlv;
  /* HUM Ch 33.4 "MTPFC2 : MAC Transmission Pause or PFC Frame Cfg 2" p 1713 */
  uint32_t pfm = 0UL;
  if (mode == k_ra8_rmac_pause_mode_pfc) {
    pfm = (1UL << (uint32_t)k_ra8_rmac_shift_mtpfc2_pfm);
  }
  ra8_rmac(port)->MTPFC  = pt | pfrt | pfrlv;
  ra8_rmac(port)->MTPFC2 = pfm;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_pfc_group(ra8_rmac_port_t port, ra8_rmac_pfc_group_t group, uint8_t pcp_mask)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_pfc_group: port out of range");
    return k_ra8_err_invalid_arg;
  }
  if ((uint8_t)group >= k_ra8_rmac_pfc_group_count) {
    ra8_log_error(s_tag, "set_pfc_group: group out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MTPFC3t : MAC Transmission PFC Frame Configuration 3" p 1715 */
  ra8_rmac(port)->MTPFC3[(uint8_t)group] = (uint32_t)pcp_mask & k_ra8_rmac_mask_pfc_priority;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_lpi(ra8_rmac_port_t port, bool enable)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_lpi: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MEEEC : MAC Energy Efficient Ethernet Configuration" p 1726 */
  uint32_t meeec = 0UL;
  if (enable) {
    meeec = k_ra8_rmac_meeec_lpitr;
  }
  ra8_rmac(port)->MEEEC = meeec;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_magic_packet(ra8_rmac_port_t port, bool enable)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_magic_packet: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MRGC : MAC Reception General Configuration" p 1715 */
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  uint32_t                v   = reg->MRGC;
  if (enable) {
    v |= k_ra8_rmac_mrgc_mpde;
  } else {
    v &= ~k_ra8_rmac_mrgc_mpde;
  }
  reg->MRGC = v;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_loopback(ra8_rmac_port_t port, bool enable)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_loopback: port out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MLBC : MAC Loopback Configuration Register" p 1726 */
  uint32_t mlbc = 0UL;
  if (enable) {
    mlbc = k_ra8_rmac_mlbc_lbme;
  }
  ra8_rmac(port)->MLBC = mlbc;
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_set_link(ra8_rmac_port_t   port,
                            ra8_rmac_pis_t    iface,
                            ra8_rmac_lsc_t    speed,
                            ra8_rmac_duplex_t duplex)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "set_link: port out of range");
    return k_ra8_err_invalid_arg;
  }
  if (!internal_pis_ok(iface)) {
    ra8_log_error(s_tag, "set_link: iface out of range");
    return k_ra8_err_invalid_arg;
  }
  if ((uint8_t)speed >= k_ra8_rmac_lsc_count) {
    ra8_log_error(s_tag, "set_link: speed out of range");
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 33.4 "MPIC : PHY Interfaces Configuration Register" p 1709
   * Preserve the existing PSMCS (MDC divider) field -- ra8_rmac_init
   * programmed it from cfg->eswclk_hz / mdc_hz; a runtime ra8_rmac_set_link
   * call must NOT clobber the MDC clock the PHY is already using to ack
   * the very transaction that is updating PIS/LSC/PIPP. */
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  const uint32_t          existing_psmcs =
    (reg->MPIC >> (uint32_t)k_ra8_rmac_shift_mpic_psmcs) & (uint32_t)k_ra8_rmac_mask_mpic_psmcs;
  reg->MPIC = internal_make_mpic(iface, speed, duplex, existing_psmcs);
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_mdio_c22_read(ra8_rmac_port_t port,
                                 uint8_t         phy_addr,
                                 uint8_t         reg_addr,
                                 uint16_t*       out_value)
{
  RA8_CHECK_NULL_PTR(out_value, s_tag, "mdio_c22_read: out_value must not be nullptr");
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "mdio_c22_read: port out of range");
    return k_ra8_err_invalid_arg;
  }
 
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* Pre-wait: a write to MPSM while PSME=1 has no effect (HUM Note 2). */
  const ra8_err_t drain_err = internal_mdio_drain(reg);
  if (drain_err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c22_read: pre-drain timeout");
    return drain_err;
  }
  internal_mpsm_issue(reg, phy_addr, reg_addr, k_ra8_rmac_mdio_op_c22_read, 0U, false);
  const ra8_err_t wait_err = internal_mdio_wait(reg, k_ra8_rmac_mmis1_pracs);
  if (wait_err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c22_read: timeout"); /* GCOVR_EXCL_BR_LINE -- MDIO status no stuck */
    return wait_err;
  }
  /* HUM Ch 33.4.1.1 "MPSM : PHY Station Management Register" p 1707 */
  *out_value =
    (uint16_t)((reg->MPSM >> (uint32_t)k_ra8_rmac_shift_mpsm_prd) & k_ra8_rmac_mask_mpsm_data);
  return k_ra8_ok;
}
 
ra8_err_t
ra8_rmac_mdio_c22_write(ra8_rmac_port_t port, uint8_t phy_addr, uint8_t reg_addr, uint16_t value)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "mdio_c22_write: port out of range");
    return k_ra8_err_invalid_arg;
  }
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* Pre-wait: a write to MPSM while PSME=1 has no effect (HUM Note 2). */
  const ra8_err_t drain_err = internal_mdio_drain(reg);
  if (drain_err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c22_write: pre-drain timeout");
    return drain_err;
  }
  internal_mpsm_issue(reg, phy_addr, reg_addr, k_ra8_rmac_mdio_op_c22_write, value, false);
  return internal_mdio_wait(reg, k_ra8_rmac_mmis1_pwacs);
}
 
ra8_err_t ra8_rmac_mdio_c45_read(ra8_rmac_port_t port,
                                 uint8_t         phy_addr,
                                 uint8_t         dev_addr,
                                 uint16_t        reg_addr,
                                 uint16_t*       out_value)
{
  RA8_CHECK_NULL_PTR(out_value, s_tag, "mdio_c45_read: out_value must not be nullptr");
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "mdio_c45_read: port out of range");
    return k_ra8_err_invalid_arg;
  }
 
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* C45 step 1: address frame loads the 16-bit MMD register address. */
  ra8_err_t err = internal_mdio_drain(reg);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_read: addr pre-drain timeout"); /* GCOVR_EXCL_BR_LINE -- stuck */
    return err;
  }
  internal_mpsm_issue(reg, phy_addr, dev_addr, k_ra8_rmac_mdio_op_c45_address, reg_addr, true);
  err = internal_mdio_wait(reg, k_ra8_rmac_mmis1_paacs);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_read: address timeout"); /* GCOVR_EXCL_BR_LINE -- MDIO timeout */
    return err;
  }
  /* C45 step 2: read frame fetches the 16-bit data. */
  err = internal_mdio_drain(reg);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_read: read pre-drain timeout");
    return err;
  }
  internal_mpsm_issue(reg, phy_addr, dev_addr, k_ra8_rmac_mdio_op_c45_read, 0U, true);
  err = internal_mdio_wait(reg, k_ra8_rmac_mmis1_pracs);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_read: read timeout"); /* GCOVR_EXCL_BR_LINE -- no stuck-status */
    return err;
  }
  /* HUM Ch 33.4.1.1 "MPSM : PHY Station Management Register" p 1707 */
  *out_value =
    (uint16_t)((reg->MPSM >> (uint32_t)k_ra8_rmac_shift_mpsm_prd) & k_ra8_rmac_mask_mpsm_data);
  return k_ra8_ok;
}
 
ra8_err_t ra8_rmac_mdio_c45_write(ra8_rmac_port_t port,
                                  uint8_t         phy_addr,
                                  uint8_t         dev_addr,
                                  uint16_t        reg_addr,
                                  uint16_t        value)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "mdio_c45_write: port out of range");
    return k_ra8_err_invalid_arg;
  }
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* Address frame followed by write frame -- both must complete. */
  ra8_err_t err = internal_mdio_drain(reg);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_write: addr pre-drain timeout"); /* GCOVR_EXCL_BR_LINE -- MDIO */
    return err;
  }
  internal_mpsm_issue(reg, phy_addr, dev_addr, k_ra8_rmac_mdio_op_c45_address, reg_addr, true);
  err = internal_mdio_wait(reg, k_ra8_rmac_mmis1_paacs);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "mdio_c45_write: address timeout"); /* GCOVR_EXCL_BR_LINE -- timeout */
    return err;
  }
  err = internal_mdio_drain(reg);
  if (err != k_ra8_ok) {
    ra8_log_error(s_tag, "write pre-drain timeout"); /* GCOVR_EXCL_BR_LINE -- MDIO never stalls */
    return err;
  }
  internal_mpsm_issue(reg, phy_addr, dev_addr, k_ra8_rmac_mdio_op_c45_write, value, true);
  return internal_mdio_wait(reg, k_ra8_rmac_mmis1_pwacs);
}
 
ra8_err_t ra8_rmac_attach_handler(ra8_rmac_port_t port, ra8_rmac_event_fn_t cb, void* ctx)
{
  if (!internal_port_ok(port)) {
    ra8_log_error(s_tag, "attach_handler: port out of range");
    return k_ra8_err_invalid_arg;
  }
  s_slots[(uint8_t)port].cb  = cb;
  s_slots[(uint8_t)port].ctx = ctx;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_rmac_dispatch(ra8_rmac_port_t port)
{
  if (!internal_port_ok(port)) {
    return;
  }
  volatile r_rmac_regs_t* reg = ra8_rmac(port);
  /* HUM Ch 33.4 "MEIS / MMIS0 / MMIS1 / MMIS2" p 1706 */
  const uint32_t            err = reg->MEIS;
  const uint32_t            m0  = reg->MMIS0;
  const uint32_t            m1  = reg->MMIS1;
  const uint32_t            m2  = reg->MMIS2;
  const ra8_rmac_event_fn_t fn  = s_slots[(uint8_t)port].cb;
  void* const               ctx = s_slots[(uint8_t)port].ctx;
  /* HUM Ch 33.4 "MEID / MMID0 / MMID1 / MMID2" p 1706 */
  reg->MEID  = err;
  reg->MMID0 = m0;
  reg->MMID1 = m1;
  reg->MMID2 = m2;
  reg->MEIS  = 0U;
  reg->MMIS0 = 0U;
  reg->MMIS1 = 0U;
  reg->MMIS2 = 0U;
  if (fn != nullptr) {
    fn(ctx, port, err, m0, m1, m2);
  }
}