ra8_i3c_i2c.c

Go to the documentation of this file.

 
#include "ra8_i3c_i2c.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_i3c_i2c_internal.h"
#include "ra8_i3c_i2c_regs.h"
#include "ra8_log.h"
#include "ra8_mstp.h"

bool priv_i3c_i2c_len_buf_invalid(uint32_t len, const void* buf)
{
  return (len != 0U) && (buf == nullptr);
}

bool priv_i3c_i2c_should_dispatch(uint8_t mask, const void* cb)
{
  return (mask != 0U) && (cb != nullptr);
}

static const char* s_tag = "IIC_B";

typedef enum : uint32_t {
  k_ra8_i3c_i2c_poll_limit = 200000U,
  k_ra8_i3c_i2c_addr_shift = 1U,
  k_ra8_i3c_i2c_addr_rw_write = 0U,
  k_ra8_i3c_i2c_addr_rw_read = 1U,
  k_ra8_i3c_i2c_byte_mask = 0xFFU,
} internal_i3c_i2c_t;

ra8_i3c_i2c_state_t s_iic_b_state[k_ra8_i3c_i2c_channel_count];

RA8_INTERNAL static uint8_t internal_i3c_i2c_half_period(uint32_t bus_hz, uint32_t pclka_hz)
{
  /* mcdc-deactivated: both args validated by ra8_i3c_i2c_init upstream; defensive duplicate. */
  if ((bus_hz == 0U) || (pclka_hz == 0U)) {
    return 0U;
  }
  enum : uint32_t {
    k_ra8_i3c_i2c_period_split = 2U,    
    k_ra8_i3c_i2c_max_field    = 0xFFU, 
  };
  const uint32_t total = pclka_hz / bus_hz;
  const uint32_t half  = total / k_ra8_i3c_i2c_period_split;
  if (half == 0U) {
    return 0U;
  }
  uint32_t value = half - 1U;
  if (value > k_ra8_i3c_i2c_max_field) {
    value = k_ra8_i3c_i2c_max_field;
  }
  return (uint8_t)value;
}

RA8_INTERNAL static ra8_err_t internal_i3c_i2c_wait_ntst(volatile r_i3c_i2c_regs_t* reg,
                                                         uint32_t                   mask)
{
  for (uint32_t i = 0U; i < k_ra8_i3c_i2c_poll_limit; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* HUM Ch 40.2.50 "NTST : Normal Transfer Status Register" p 2498 */
    if (ra8_fake_mmio_poll(&reg->NTST, i, (reg->NTST & mask) != 0U)) {
#else
    /* HUM Ch 40.2.50 "NTST : Normal Transfer Status Register" p 2498 */
    if ((reg->NTST & mask) != 0U) {
#endif
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL static ra8_err_t internal_i3c_i2c_reset(volatile r_i3c_i2c_regs_t* reg)
{
  /* HUM Ch 40.2.4 "RSTCTL : Reset Control Register" p 2451 */
  reg->RSTCTL = k_ra8_i3c_i2c_msk_rstctl_ri3crst;
  reg->RSTCTL = 0U;
  for (uint32_t i = 0U; i < k_ra8_i3c_i2c_poll_limit; i++) {
    /* HUM Ch 40.2.4 "RSTCTL : Reset Control Register" p 2451 */
    const bool reset_clear = (reg->RSTCTL & k_ra8_i3c_i2c_msk_rstctl_ri3crst) == 0U;
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* HUM Ch 40.2.4 "RSTCTL : Reset Control Register" p 2451 */
    const bool observed = ra8_fake_mmio_poll(&reg->RSTCTL, i, reset_clear);
#else
    const bool observed = reset_clear;
#endif
    if (observed) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}

void priv_i3c_i2c_start(volatile r_i3c_i2c_regs_t* reg)
{
  /* HUM Ch 40.2.32 "CNDCTL : Condition Control Register" p 2479 */
  reg->CNDCTL = k_ra8_i3c_i2c_msk_cndctl_stcnd;
}

RA8_INTERNAL static void internal_i3c_i2c_restart(volatile r_i3c_i2c_regs_t* reg)
{
  /* HUM Ch 40.2.32 "CNDCTL : Condition Control Register" p 2479 */
  reg->CNDCTL = k_ra8_i3c_i2c_msk_cndctl_srcnd;
}

void priv_i3c_i2c_stop(volatile r_i3c_i2c_regs_t* reg)
{
  /* Clear the prior STOP-detect flag so the NEXT transaction sees a
   * fresh edge. W0C semantics. */
  reg->BST    = reg->BST & ~k_ra8_i3c_i2c_msk_bst_spcnddf;
  reg->CNDCTL = k_ra8_i3c_i2c_msk_cndctl_spcnd;
}

void priv_i3c_i2c_clear_bst(volatile r_i3c_i2c_regs_t* reg)
{
  enum : uint32_t {
    k_ra8_i3c_i2c_bst_clear_mask = k_ra8_i3c_i2c_msk_bst_stcnddf | k_ra8_i3c_i2c_msk_bst_spcnddf |
                                   k_ra8_i3c_i2c_msk_bst_nackdf | k_ra8_i3c_i2c_msk_bst_tendf |
                                   k_ra8_i3c_i2c_msk_bst_alf |
                                   k_ra8_i3c_i2c_msk_bst_todf, 
  };
  /* HUM Ch 40.2.46 "BST : Bus Status Register" p 2490 */
  reg->BST = reg->BST & ~k_ra8_i3c_i2c_bst_clear_mask;
}

ra8_err_t priv_i3c_i2c_send_address(volatile r_i3c_i2c_regs_t* reg, uint8_t address_byte)
{
  /* Wait for first TDBEF0 (set after START condition is on the bus).
   * HUM Ch 40.2.50 "NTST : Normal Transfer Status Register" p 2498 */
  ra8_err_t err = internal_i3c_i2c_wait_ntst(reg, k_ra8_i3c_i2c_msk_ntst_tdbef0);
  if (err != k_ra8_ok) {
    return err;
  }
  /* HUM Ch 40.2.35 "NTDTBP0 : Normal Transfer Data Buffer Port 0" p 2481 */
  reg->NTDTBP0 = (uint32_t)address_byte;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_i3c_i2c_status_from_bst(uint32_t bst)
{
  if ((bst & k_ra8_i3c_i2c_msk_bst_nackdf) != 0U) {
    return k_ra8_err_nack;
  }
  if ((bst & k_ra8_i3c_i2c_msk_bst_alf) != 0U) {
    return k_ra8_err_hw_error;
  }
  if ((bst & k_ra8_i3c_i2c_msk_bst_todf) != 0U) {
    return k_ra8_err_hw_timeout;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static bool internal_i3c_i2c_bus_free(volatile const r_i3c_i2c_regs_t* reg)
{
  return (reg->BCST & k_ra8_i3c_i2c_msk_bcst_bfref) != 0U;
}
 
/* =============================================================================
 * Init / deinit -- mirrors FSP's controller-open sequence.
 * =============================================================================
 */

RA8_INTERNAL static void internal_i3c_i2c_apply_init_regs(volatile r_i3c_i2c_regs_t* reg,
                                                          const ra8_i3c_i2c_cfg_t*   cfg)
{
  /* HUM Ch 40.2.14 "REFCKCTL : Reference Clock Control Register" p 2463 */
  reg->REFCKCTL = 0U;
 
  /* HUM Ch 40.2.15 "STDBR : Standard Bit Rate Register" p 2463 */
  const uint8_t  half  = internal_i3c_i2c_half_period(cfg->bus_hz, cfg->pclka_hz);
  const uint32_t stdbr = ((uint32_t)half << (uint32_t)k_ra8_i3c_i2c_stdbr_sbrlo_pos) |
                         ((uint32_t)half << (uint32_t)k_ra8_i3c_i2c_stdbr_sbrho_pos);
  reg->STDBR           = stdbr;
 
  /* HUM Ch 40.2.12 "BFCTL : Bus Function Control Register" p 2459 */
  uint32_t bfctl =
    k_ra8_i3c_i2c_msk_bfctl_male | k_ra8_i3c_i2c_msk_bfctl_nale | k_ra8_i3c_i2c_msk_bfctl_scsyne;
  if (cfg->bus_hz >= k_ra8_i3c_i2c_speed_fast_plus) {
    bfctl |= k_ra8_i3c_i2c_msk_bfctl_fmpe;
  }
  reg->BFCTL = bfctl;
 
  /* HUM Ch 40.2.24 "ACKCTL : Acknowledge Control Register" p 2473 */
  reg->ACKCTL = k_ra8_i3c_i2c_msk_ackctl_acktwp;
  /* HUM Ch 40.2.25 "SCSTRCTL : SCL Stretch Control Register" p 2474 */
  reg->SCSTRCTL = 0U;
 
  /* BUSE=1: drive the bus.
   * HUM Ch 40.2.2 "BCTL : Bus Control Register" p 2449 */
  reg->BCTL = k_ra8_i3c_i2c_msk_bctl_buse;
}

RA8_INTERNAL static ra8_err_t internal_i3c_i2c_block_bringup(volatile r_i3c_i2c_regs_t* reg)
{
  /* The I3C/IIC_B shared block needs both MSTPB4 (I3C) AND MSTPB9 */
  /* (IIC0) ungated; ungating only MSTPB4 leaves the channel-0 IIC */
  /* controller powered down and any START hangs in BCST before */
  /* TDBEF0 ever rises. Mirrors */
  /* ra8_board_ek_ra8d2.c::internal_io_expander_apply. */
  /* HUM Ch 11.2.7 "MSTPCRB : Module Stop Control Register B" p 444 */
  const ra8_err_t mst_err = ra8_mstp_enable(k_ra8_mstp_i3c);
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "iic_b_init: mstp i3c");
  const ra8_err_t iic0_err = ra8_mstp_enable(k_ra8_mstp_iic0);
  RA8_RETURN_ON_ERROR(iic0_err, s_tag, "iic_b_init: mstp iic0");
 
  /* HUM Ch 40.2.92 "CECTL : Clock Enable Control Register" p 2543 */
  reg->CECTL = k_ra8_i3c_i2c_msk_cectl_clke;
  /* BUSE=0: detach SCL/SDA before reset.
   * HUM Ch 40.2.2 "BCTL : Bus Control Register" p 2449 */
  reg->BCTL = 0U;
 
  const ra8_err_t reset_err = internal_i3c_i2c_reset(reg);
  RA8_RETURN_ON_ERROR(reset_err, s_tag, "iic_b_init: reset");
 
  /* HUM Ch 40.2.1 "PRTS : Protocol Selection" p 2449 -- the I3C IP
   * defaults to PRTMD=0 (I3C FIFO buffer transfer, command-queue
   * driven). This polling driver writes NTDTBP0 directly, so it must
   * switch the IP into PRTMD=1 (I2C single-buffer transfer) before
   * any START / STOP / address byte is issued. Without this write the
   * peripheral silently swallows writes to NTDTBP0 as stray I3C
   * FIFO entries and never drives SCL. */
  reg->PRTS = k_ra8_i3c_i2c_msk_prts_prtmd;
  return k_ra8_ok;
}
 
ra8_err_t ra8_i3c_i2c_init(uint8_t channel, const ra8_i3c_i2c_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "iic_b_init: cfg");
  if (cfg->bus_hz == 0U) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_i3c_i2c_regs_t* reg = i3c_i2c_regs(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
 
  const ra8_err_t br_err = internal_i3c_i2c_block_bringup(reg);
  RA8_RETURN_ON_ERROR(br_err, s_tag, "iic_b_init: block bringup");
 
  internal_i3c_i2c_apply_init_regs(reg, cfg);
 
  s_iic_b_state[channel].cb          = nullptr;
  s_iic_b_state[channel].ctx         = nullptr;
  s_iic_b_state[channel].initialized = true;
  s_iic_b_state[channel].bus_held    = false;
 
  ra8_log_info_val(s_tag, "iic_b_init channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
ra8_err_t ra8_i3c_i2c_deinit(uint8_t channel)
{
  volatile r_i3c_i2c_regs_t* reg = i3c_i2c_regs(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* BUSE=0: release the bus.
   * HUM Ch 40.2.2 "BCTL : Bus Control Register" p 2449 */
  reg->BCTL = 0U;
  /* HUM Ch 40.2.92 "CECTL : Clock Enable Control Register" p 2543 */
  reg->CECTL                         = 0U;
  s_iic_b_state[channel].cb          = nullptr;
  s_iic_b_state[channel].ctx         = nullptr;
  s_iic_b_state[channel].initialized = false;
  s_iic_b_state[channel].bus_held    = false;
  return ra8_mstp_disable(k_ra8_mstp_i3c);
}
 
ra8_err_t ra8_i3c_i2c_set_clock(uint8_t channel, uint32_t bus_hz, uint32_t pclka_hz)
{
  volatile r_i3c_i2c_regs_t* reg = i3c_i2c_regs(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if ((bus_hz == 0U) || (pclka_hz == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 40.2.15 "STDBR : Standard Bit Rate Register" p 2463 */
  const uint8_t half = internal_i3c_i2c_half_period(bus_hz, pclka_hz);
  reg->STDBR         = ((uint32_t)half << (uint32_t)k_ra8_i3c_i2c_stdbr_sbrlo_pos) |
                       ((uint32_t)half << (uint32_t)k_ra8_i3c_i2c_stdbr_sbrho_pos);
  return k_ra8_ok;
}
 
/* =============================================================================
 * Polling write -- mirrors FSP's controller-run path + TXI.
 * =============================================================================
 */

RA8_INTERNAL static void internal_i3c_i2c_open_phase(volatile r_i3c_i2c_regs_t* reg, bool bus_held)
{
  if (bus_held) {
    internal_i3c_i2c_restart(reg);
  } else {
    priv_i3c_i2c_start(reg);
  }
}

RA8_INTERNAL static ra8_err_t
internal_i3c_i2c_drain_tx(volatile r_i3c_i2c_regs_t* reg, const uint8_t* data, uint32_t len)
{
  ra8_err_t err = k_ra8_ok;
  for (uint32_t i = 0U; i < len; i++) {
    err = internal_i3c_i2c_wait_ntst(reg, k_ra8_i3c_i2c_msk_ntst_tdbef0);
    if (err != k_ra8_ok) {
      break;
    }
    if ((reg->BST & k_ra8_i3c_i2c_msk_bst_nackdf) != 0U) {
      break;
    }
    /* HUM Ch 40.2.35 "NTDTBP0 : Normal Transfer Data Buffer Port 0" p 2481 */
    reg->NTDTBP0 = (uint32_t)data[i];
  }
  return err;
}

RA8_INTERNAL static void internal_i3c_i2c_finalize(volatile r_i3c_i2c_regs_t* reg,
                                                   uint8_t                    channel,
                                                   ra8_err_t                  err,
                                                   bool                       restart)
{
  if ((err != k_ra8_ok) || !restart) {
    priv_i3c_i2c_stop(reg);
    s_iic_b_state[channel].bus_held = false;
  } else {
    s_iic_b_state[channel].bus_held = true;
  }
  priv_i3c_i2c_clear_bst(reg);
}

RA8_INTERNAL static ra8_err_t internal_i3c_i2c_busy_gate(volatile const r_i3c_i2c_regs_t* reg,
                                                         bool                             bus_held)
{
  if (bus_held) {
    return k_ra8_ok;
  }
  return internal_i3c_i2c_bus_free(reg) ? k_ra8_ok : k_ra8_err_busy;
}
 
ra8_err_t ra8_i3c_i2c_write(uint8_t        channel,
                            uint8_t        target_7b,
                            const uint8_t* data,
                            uint32_t       len,
                            bool           restart)
{
  volatile r_i3c_i2c_regs_t* reg = i3c_i2c_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "iic_b_write: channel");
  RA8_CHECK_NULL_PTR(data, s_tag, "iic_b_write: data");
 
  const bool      bus_held  = s_iic_b_state[channel].bus_held;
  const ra8_err_t busy_gate = internal_i3c_i2c_busy_gate(reg, bus_held);
  if (busy_gate != k_ra8_ok) {
    return busy_gate;
  }
 
  priv_i3c_i2c_clear_bst(reg);
  internal_i3c_i2c_open_phase(reg, bus_held);
 
  const uint8_t address_byte =
    (uint8_t)(((uint32_t)target_7b << k_ra8_i3c_i2c_addr_shift) | k_ra8_i3c_i2c_addr_rw_write);
  ra8_err_t err = priv_i3c_i2c_send_address(reg, address_byte);
  if (err != k_ra8_ok) {
    priv_i3c_i2c_stop(reg);
    s_iic_b_state[channel].bus_held = false;
    return err;
  }
 
  err                     = internal_i3c_i2c_drain_tx(reg, data, len);
  const ra8_err_t bst_err = internal_i3c_i2c_status_from_bst(reg->BST);
  if (bst_err != k_ra8_ok) {
    err = bst_err;
  }
  internal_i3c_i2c_finalize(reg, channel, err, restart);
  return err;
}
 
/* =============================================================================
 * Polling read -- mirrors FSP's controller-run path + RXI.
 * =============================================================================
 */

RA8_INTERNAL static ra8_err_t
internal_i3c_i2c_drain_rx(volatile r_i3c_i2c_regs_t* reg, uint8_t* out, uint32_t len)
{
  ra8_err_t err = k_ra8_ok;
  for (uint32_t i = 0U; i < len; i++) {
    if (i == (len - 1U)) {
      /* HUM Ch 40.2.24 "ACKCTL : Acknowledge Control Register" p 2473 */
      reg->ACKCTL = k_ra8_i3c_i2c_msk_ackctl_acktwp | k_ra8_i3c_i2c_msk_ackctl_ackt;
    }
    err = internal_i3c_i2c_wait_ntst(reg, k_ra8_i3c_i2c_msk_ntst_rdbff0);
    if (err != k_ra8_ok) {
      break;
    }
    /* HUM Ch 40.2.35 "NTDTBP0 : Normal Transfer Data Buffer Port 0" p 2481 */
    out[i] = (uint8_t)(reg->NTDTBP0 & k_ra8_i3c_i2c_byte_mask);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t
internal_i3c_i2c_rx_phase(volatile r_i3c_i2c_regs_t* reg, uint8_t* buf, uint32_t len)
{
  ra8_err_t err = internal_i3c_i2c_wait_ntst(reg, k_ra8_i3c_i2c_msk_ntst_rdbff0);
  if (err == k_ra8_ok) {
    (void)reg->NTDTBP0;
    err = internal_i3c_i2c_drain_rx(reg, buf, len);
  }
  reg->ACKCTL = k_ra8_i3c_i2c_msk_ackctl_acktwp;
  return err;
}
 
ra8_err_t
ra8_i3c_i2c_read(uint8_t channel, uint8_t target_7b, uint8_t* buf, uint32_t len, bool restart)
{
  volatile r_i3c_i2c_regs_t* reg = i3c_i2c_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "iic_b_read: channel");
  RA8_CHECK_NULL_PTR(buf, s_tag, "iic_b_read: buf");
  if (len == 0U) {
    return k_ra8_err_invalid_arg;
  }
 
  const bool      bus_held  = s_iic_b_state[channel].bus_held;
  const ra8_err_t busy_gate = internal_i3c_i2c_busy_gate(reg, bus_held);
  if (busy_gate != k_ra8_ok) {
    return busy_gate;
  }
 
  priv_i3c_i2c_clear_bst(reg);
  internal_i3c_i2c_open_phase(reg, bus_held);
 
  const uint8_t address_byte =
    (uint8_t)(((uint32_t)target_7b << k_ra8_i3c_i2c_addr_shift) | k_ra8_i3c_i2c_addr_rw_read);
  ra8_err_t err = priv_i3c_i2c_send_address(reg, address_byte);
  if (err != k_ra8_ok) {
    priv_i3c_i2c_stop(reg);
    s_iic_b_state[channel].bus_held = false;
    return err;
  }
 
  err                     = internal_i3c_i2c_rx_phase(reg, buf, len);
  const ra8_err_t bst_err = internal_i3c_i2c_status_from_bst(reg->BST);
  if (bst_err != k_ra8_ok) {
    err = bst_err;
  }
  internal_i3c_i2c_finalize(reg, channel, err, restart);
  return err;
}
 
/* =============================================================================
 * Combined transfer -- write-then-RESTART-then-read.
 * =============================================================================
 */
 
ra8_err_t ra8_i3c_i2c_transfer(uint8_t        channel,
                               uint8_t        target_7b,
                               const uint8_t* tx,
                               uint32_t       tx_len,
                               uint8_t*       rx,
                               uint32_t       rx_len)
{
  if (i3c_i2c_regs(channel) == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if ((tx_len == 0U) && (rx_len == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  if ((tx_len != 0U) && (tx == nullptr)) {
    return k_ra8_err_null_ptr;
  }
  if (priv_i3c_i2c_len_buf_invalid(rx_len, rx)) {
    return k_ra8_err_null_ptr;
  }
 
  /* Phase 1: write (hold the bus for the upcoming read).
   * Skipped entirely when tx_len == 0 -- this degenerates the call
   * into a plain read, matching FSP's expectation that a zero-byte
   * tx phase means "no register-pointer update needed". */
  if (tx_len != 0U) {
    const ra8_err_t w_err =
      ra8_i3c_i2c_write(channel, target_7b, tx, tx_len, /*restart=*/(rx_len != 0U));
    if (w_err != k_ra8_ok) {
      return w_err;
    }
  }
 
  /* Phase 2: read (close the bus normally). */
  if (rx_len != 0U) {
    const ra8_err_t r_err = ra8_i3c_i2c_read(channel, target_7b, rx, rx_len, /*restart=*/false);
    if (r_err != k_ra8_ok) {
      return r_err;
    }
  }
  return k_ra8_ok;
}