ra8_i2c.c

Go to the documentation of this file.

 
#include "ra8_i2c.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_i2c_internal.h"
#include "ra8_i2c_regs.h"

const char* const g_i2c_tag = "I2C";

typedef enum : uint32_t {
  k_ra8_i2c_poll_limit = 200000U,
  k_ra8_i2c_addr_shift = 1U,
  k_ra8_i2c_addr_rw_write = 0U,
  k_ra8_i2c_addr_rw_read = 1U,
} ra8_i2c_internal_t;

typedef enum : uint32_t {
  k_ra8_i2c_rx_short_len   = 2U, 
  k_ra8_i2c_rx_single_len  = 1U, 
  k_ra8_i2c_rx_remain_wait = 3U, 
  k_ra8_i2c_rx_remain_nack = 2U, 
  k_ra8_i2c_rx_remain_stop = 1U, 
} ra8_i2c_rx_phase_t;

bool priv_ra8_i2c_internal_clk_invalid(uint32_t bus_hz, uint32_t pclkb_hz)
{
  return (bus_hz == 0U) || (pclkb_hz == 0U);
}

ra8_i2c_state_t s_i2c_state[k_ra8_i2c_channel_count];

RA8_INTERNAL static ra8_err_t internal_i2c_wait_icsr2(volatile const r_i2c_regs_t* reg,
                                                      uint8_t                      mask)
{
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_i2c_poll_limit; i++) {
    /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
    if (ra8_fake_mmio_poll(&reg->ICSR2, i, (reg->ICSR2 & mask) != 0U)) {
#else
    /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
    if ((reg->ICSR2 & mask) != 0U) {
#endif
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL static ra8_err_t internal_i2c_status_from_icsr2(uint8_t icsr2)
{
  if ((icsr2 & (uint8_t)k_ra8_i2c_msk_icsr2_nackf) != 0U) {
    return k_ra8_err_nack;
  }
  if ((icsr2 & (uint8_t)k_ra8_i2c_msk_icsr2_al) != 0U) {
    return k_ra8_err_hw_error;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_i2c_clear_status(volatile r_i2c_regs_t* reg)
{
  enum : uint8_t {
    k_ra8_i2c_status_clear_mask =
      (uint8_t)((1U << (uint8_t)k_ra8_i2c_icsr2_start_pos) | (uint8_t)k_ra8_i2c_msk_icsr2_stop |
                (uint8_t)k_ra8_i2c_msk_icsr2_nackf |
                (uint8_t)k_ra8_i2c_msk_icsr2_al), 
  };
  /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2 -- W0C" p 2384 */
  reg->ICSR2 = (uint8_t)(reg->ICSR2 & (uint8_t)~(uint8_t)k_ra8_i2c_status_clear_mask);
}

RA8_INTERNAL static void internal_i2c_start(volatile r_i2c_regs_t* reg)
{
  /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
  reg->ICCR2 = (uint8_t)(reg->ICCR2 | (uint8_t)k_ra8_i2c_msk_iccr2_st);
}

RA8_INTERNAL static void internal_i2c_restart(volatile r_i2c_regs_t* reg)
{
  /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
  reg->ICCR2 = (uint8_t)(reg->ICCR2 | (uint8_t)k_ra8_i2c_msk_iccr2_rs);
  /* RS auto-clears once the restart condition is issued. The peripheral
   * address must be written to ICDRT only after RS reads 0 -- a write
   * while RS = 1 is silently dropped (HUM Ch 39.11 "Issuing a Restart
   * Condition" Note, p 2434). After a send_stop=false write TDRE is
   * already 1, so without this wait send_address would write the address
   * before the restart completed and the transmit would never happen. */
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_i2c_poll_limit; i++) {
    /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
    const bool restart_complete = (reg->ICCR2 & (uint8_t)k_ra8_i2c_msk_iccr2_rs) == 0U;
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
    const bool observed = ra8_fake_mmio_poll(&reg->ICCR2, i, restart_complete);
#else
    const bool observed = restart_complete;
#endif
    if (observed) {
      break;
    }
  }
}

RA8_INTERNAL static void internal_i2c_wait_bus_free(volatile const r_i2c_regs_t* reg)
{
  /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2 -- BBSY" p 2371 */
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_i2c_poll_limit; i++) {
    /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
    if ((reg->ICCR2 & (uint8_t)k_ra8_i2c_msk_iccr2_bbsy) == 0U) {
      break;
    }
  }
}

RA8_INTERNAL static void internal_i2c_stop_request(volatile r_i2c_regs_t* reg)
{
  /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
  reg->ICSR2 = (uint8_t)(reg->ICSR2 & (uint8_t)~(uint8_t)k_ra8_i2c_msk_icsr2_stop);
  /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2" p 2371 */
  reg->ICCR2 = (uint8_t)(reg->ICCR2 | (uint8_t)k_ra8_i2c_msk_iccr2_sp);
}

RA8_INTERNAL static void internal_i2c_stop(volatile r_i2c_regs_t* reg)
{
  internal_i2c_stop_request(reg);
  internal_i2c_wait_bus_free(reg);
}

RA8_INTERNAL static void internal_i2c_set_nack(volatile r_i2c_regs_t* reg)
{
  /* HUM Ch 39.2.5 "ICMR3 : I2C Bus Mode Register 3 -- ACKWP/ACKBT" p 2376 */
  reg->ICMR3 = (uint8_t)(reg->ICMR3 | (uint8_t)k_ra8_i2c_msk_icmr3_ackwp);
  reg->ICMR3 = (uint8_t)(reg->ICMR3 | (uint8_t)k_ra8_i2c_msk_icmr3_ackbt);
  reg->ICMR3 = (uint8_t)(reg->ICMR3 & (uint8_t)~(uint8_t)k_ra8_i2c_msk_icmr3_ackwp);
}

RA8_INTERNAL static void internal_i2c_open_phase(volatile r_i2c_regs_t* reg, bool bus_held)
{
  if (bus_held) {
    internal_i2c_restart(reg);
  } else {
    internal_i2c_start(reg);
  }
}

RA8_INTERNAL static ra8_err_t internal_i2c_busy_gate(volatile const r_i2c_regs_t* reg,
                                                     bool                         bus_held)
{
  if (bus_held) {
    return k_ra8_ok;
  }
  /* HUM Ch 39.2.2 "ICCR2 : I2C Bus Control Register 2 -- BBSY" p 2371 */
  return ((reg->ICCR2 & (uint8_t)k_ra8_i2c_msk_iccr2_bbsy) == 0U) ? k_ra8_ok : k_ra8_err_busy;
}

RA8_INTERNAL static ra8_err_t internal_i2c_send_address(volatile r_i2c_regs_t* reg,
                                                        uint8_t                address_byte)
{
  /* Wait for TDRE (set after START issues and TRS = transmit).
   * HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
  ra8_err_t err = internal_i2c_wait_icsr2(reg, (uint8_t)k_ra8_i2c_msk_icsr2_tdre);
  if (err != k_ra8_ok) {
    return err;
  }
  /* HUM Ch 39.2.17 "ICDRT : I2C Bus Transmit Data Register" p 2393 */
  reg->ICDRT = address_byte;
  return internal_i2c_status_from_icsr2(reg->ICSR2);
}

RA8_INTERNAL static ra8_err_t
internal_i2c_drain_tx(volatile r_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_i2c_wait_icsr2(reg, (uint8_t)k_ra8_i2c_msk_icsr2_tdre);
    if (err != k_ra8_ok) {
      break;
    }
    /* HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2 -- NACKF" p 2384 */
    if ((reg->ICSR2 & (uint8_t)k_ra8_i2c_msk_icsr2_nackf) != 0U) {
      err = k_ra8_err_nack;
      break;
    }
    /* HUM Ch 39.2.17 "ICDRT : I2C Bus Transmit Data Register" p 2393 */
    reg->ICDRT = data[i];
  }
  return err;
}

RA8_INTERNAL static ra8_err_t
internal_i2c_finish_tx(volatile r_i2c_regs_t* reg, uint8_t channel, ra8_err_t err, bool send_stop)
{
  if (err == k_ra8_ok) {
    /* Wait for TEND before issuing STOP (Controller Transmit step 5).
     * HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
    err = internal_i2c_wait_icsr2(reg, (uint8_t)k_ra8_i2c_msk_icsr2_tend);
  }
  if ((err != k_ra8_ok) || send_stop) {
    internal_i2c_stop(reg);
    internal_i2c_clear_status(reg);
    s_i2c_state[channel].bus_held = false;
  } else {
    s_i2c_state[channel].bus_held = true;
  }
  return err;
}
 
ra8_err_t ra8_i2c_write(uint8_t        channel,
                        uint8_t        peripheral_7b,
                        const uint8_t* data,
                        uint32_t       len,
                        bool           send_stop)
{
  volatile r_i2c_regs_t* reg = ra8_i2c_regs(channel);
  RA8_CHECK_NULL_PTR(reg, g_i2c_tag, "i2c_write: channel");
  RA8_CHECK_NULL_PTR(data, g_i2c_tag, "i2c_write: data");
 
  const bool      bus_held  = s_i2c_state[channel].bus_held;
  const ra8_err_t busy_gate = internal_i2c_busy_gate(reg, bus_held);
  if (busy_gate != k_ra8_ok) {
    return busy_gate;
  }
 
  internal_i2c_clear_status(reg);
  internal_i2c_open_phase(reg, bus_held);
 
  const uint8_t address_byte =
    (uint8_t)(((uint32_t)peripheral_7b << (uint32_t)k_ra8_i2c_addr_shift) |
              (uint32_t)k_ra8_i2c_addr_rw_write);
  ra8_err_t err = internal_i2c_send_address(reg, address_byte);
  if (err != k_ra8_ok) {
    internal_i2c_stop(reg);
    s_i2c_state[channel].bus_held = false;
    return err;
  }
 
  err = internal_i2c_drain_tx(reg, data, len);
  return internal_i2c_finish_tx(reg, channel, err, send_stop);
}

RA8_INTERNAL static ra8_err_t
internal_i2c_drain_rx(volatile r_i2c_regs_t* reg, uint8_t* out, uint32_t len)
{
  /* First RDRF marks the address-phase completion. Arm the short-read
   * end-of-frame controls before the dummy read kicks off the data clock.
   * HUM Ch 39.3.4 "Controller Receive Operation" p 2400 */
  ra8_err_t err = internal_i2c_wait_icsr2(reg, (uint8_t)k_ra8_i2c_msk_icsr2_rdrf);
  if (err != k_ra8_ok) {
    return err;
  }
  if (len <= (uint32_t)k_ra8_i2c_rx_short_len) {
    /* HUM Ch 39.2.5 "ICMR3 : I2C Bus Mode Register 3 -- WAIT" p 2376 */
    reg->ICMR3 = (uint8_t)(reg->ICMR3 | (uint8_t)k_ra8_i2c_msk_icmr3_wait);
  }
  if (len == (uint32_t)k_ra8_i2c_rx_single_len) {
    internal_i2c_set_nack(reg);
  }
  /* Dummy read starts the data clock.
   * HUM Ch 39.2.18 "ICDRR : I2C Bus Receive Data Register" p 2393 */
  (void)reg->ICDRR;
 
  for (uint32_t loaded = 0U; loaded < len; loaded++) {
    err = internal_i2c_wait_icsr2(reg, (uint8_t)k_ra8_i2c_msk_icsr2_rdrf);
    if (err != k_ra8_ok) {
      break;
    }
    const uint32_t remain = len - loaded;
    if (remain == (uint32_t)k_ra8_i2c_rx_remain_wait) {
      /* HUM Ch 39.2.5 "ICMR3 : I2C Bus Mode Register 3 -- WAIT" p 2376 */
      reg->ICMR3 = (uint8_t)(reg->ICMR3 | (uint8_t)k_ra8_i2c_msk_icmr3_wait);
    } else if (remain == (uint32_t)k_ra8_i2c_rx_remain_nack) {
      internal_i2c_set_nack(reg);
    } else if (remain == (uint32_t)k_ra8_i2c_rx_remain_stop) {
      internal_i2c_stop_request(reg);
    } else {
      /* Mid-stream byte: no end-of-frame control to arm. */
    }
    /* HUM Ch 39.2.18 "ICDRR : I2C Bus Receive Data Register" p 2393 */
    out[loaded] = reg->ICDRR;
  }
  /* Clear WAIT (lets the requested STOP fire) and ACKBT for the next
   * transaction, then wait for the bus to be released.
   * HUM Ch 39.2.5 "ICMR3 : I2C Bus Mode Register 3" p 2376 */
  reg->ICMR3 = (uint8_t)(reg->ICMR3 & (uint8_t)~(uint8_t)((uint8_t)k_ra8_i2c_msk_icmr3_wait |
                                                          (uint8_t)k_ra8_i2c_msk_icmr3_ackbt));
  internal_i2c_wait_bus_free(reg);
  return err;
}
 
ra8_err_t ra8_i2c_read(uint8_t channel, uint8_t peripheral_7b, uint8_t* data, uint32_t len)
{
  volatile r_i2c_regs_t* reg = ra8_i2c_regs(channel);
  RA8_CHECK_NULL_PTR(reg, g_i2c_tag, "i2c_read: channel");
  RA8_CHECK_NULL_PTR(data, g_i2c_tag, "i2c_read: data");
  if (len == 0U) {
    return k_ra8_err_invalid_arg;
  }
 
  const bool      bus_held  = s_i2c_state[channel].bus_held;
  const ra8_err_t busy_gate = internal_i2c_busy_gate(reg, bus_held);
  if (busy_gate != k_ra8_ok) {
    return busy_gate;
  }
 
  internal_i2c_clear_status(reg);
  internal_i2c_open_phase(reg, bus_held);
 
  const uint8_t address_byte =
    (uint8_t)(((uint32_t)peripheral_7b << (uint32_t)k_ra8_i2c_addr_shift) |
              (uint32_t)k_ra8_i2c_addr_rw_read);
  ra8_err_t err = internal_i2c_send_address(reg, address_byte);
  if (err != k_ra8_ok) {
    internal_i2c_stop(reg);
    s_i2c_state[channel].bus_held = false;
    return err;
  }
 
  err                        = internal_i2c_drain_rx(reg, data, len);
  const ra8_err_t status_err = internal_i2c_status_from_icsr2(reg->ICSR2);
  if (status_err != k_ra8_ok) {
    err = status_err;
  }
  internal_i2c_clear_status(reg);
  s_i2c_state[channel].bus_held = false;
  return err;
}
 
ra8_err_t ra8_i2c_transfer(uint8_t        channel,
                           uint8_t        peripheral_7b,
                           const uint8_t* wr,
                           uint32_t       wr_len,
                           uint8_t*       rd,
                           uint32_t       rd_len)
{
  if (ra8_i2c_regs(channel) == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if ((wr_len == 0U) && (rd_len == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  if ((wr_len != 0U) && (wr == nullptr)) {
    return k_ra8_err_null_ptr;
  }
  if ((rd_len != 0U) && (rd == nullptr)) {
    return k_ra8_err_null_ptr;
  }
 
  /* Phase 1: write, holding the bus when a read phase follows. */
  if (wr_len != 0U) {
    const ra8_err_t w_err =
      ra8_i2c_write(channel, peripheral_7b, wr, wr_len, /*send_stop=*/(rd_len == 0U));
    if (w_err != k_ra8_ok) {
      return w_err;
    }
  }
 
  /* Phase 2: read (issues STOP and releases the bus). */
  if (rd_len != 0U) {
    return ra8_i2c_read(channel, peripheral_7b, rd, rd_len);
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_i2c_scan(uint8_t channel, uint8_t peripheral_7b, bool* out_acked)
{
  volatile r_i2c_regs_t* reg = ra8_i2c_regs(channel);
  RA8_CHECK_NULL_PTR(reg, g_i2c_tag, "i2c_scan: channel");
  RA8_CHECK_NULL_PTR(out_acked, g_i2c_tag, "i2c_scan: out_acked");
 
  *out_acked                = false;
  const ra8_err_t busy_gate = internal_i2c_busy_gate(reg, s_i2c_state[channel].bus_held);
  if (busy_gate != k_ra8_ok) {
    return busy_gate;
  }
 
  internal_i2c_clear_status(reg);
  internal_i2c_start(reg);
 
  const uint8_t address_byte =
    (uint8_t)(((uint32_t)peripheral_7b << (uint32_t)k_ra8_i2c_addr_shift) |
              (uint32_t)k_ra8_i2c_addr_rw_write);
  ra8_err_t err = internal_i2c_send_address(reg, address_byte);
  /* Address NACK is a valid probe outcome, not a hard failure. */
  if ((err != k_ra8_ok) && (err != k_ra8_err_nack)) {
    internal_i2c_stop(reg);
    s_i2c_state[channel].bus_held = false;
    return err;
  }
 
  /* Wait for TEND (peripheral ACKed) or NACKF (no peripheral answered).
   * HUM Ch 39.2.10 "ICSR2 : I2C Bus Status Register 2" p 2384 */
  err = internal_i2c_wait_icsr2(
    reg,
    (uint8_t)((uint8_t)k_ra8_i2c_msk_icsr2_tend | (uint8_t)k_ra8_i2c_msk_icsr2_nackf));
  if (err == k_ra8_ok) {
    *out_acked = (reg->ICSR2 & (uint8_t)k_ra8_i2c_msk_icsr2_nackf) == 0U;
  }
 
  internal_i2c_stop(reg);
  internal_i2c_clear_status(reg);
  s_i2c_state[channel].bus_held = false;
  return err;
}