ra8_log.c

Go to the documentation of this file.

 
#include "ra8_log.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_scb.h"
 
/* =============================================================================
 * Optional byte sink -- redirect log output off ITM at run time.
 * =============================================================================
 */

static ra8_log_byte_sink_fn_t s_byte_sink = nullptr;

static void* s_byte_sink_ctx = nullptr;
 
void ra8_log_set_byte_sink(ra8_log_byte_sink_fn_t fn, void* ctx)
{
  s_byte_sink     = fn;
  s_byte_sink_ctx = ctx;
}
 
/* =============================================================================
 * ITM stimulus port 0 -- CoreSight ITM (Cortex-M85 has one).
 * =============================================================================
 */
 
typedef enum : uintptr_t {
  k_ra8_itm_stim_base = 0xE0000000UL, 
  k_ra8_itm_tcr_addr  = 0xE0000E80UL, 
  k_ra8_itm_tenr_addr = 0xE0000E00UL, 
} ra8_itm_addr_t;
 
#ifndef RA8_OFF_TARGET
RA8_HW_REGISTER_ACCESS RA8_INTERNAL static inline volatile uint32_t* internal_itm_stim0(void)
{
  return (volatile uint32_t*)k_ra8_itm_stim_base;
}

RA8_HW_REGISTER_ACCESS RA8_INTERNAL static inline volatile uint32_t* internal_itm_tcr(void)
{
  return (volatile uint32_t*)k_ra8_itm_tcr_addr;
}

RA8_HW_REGISTER_ACCESS RA8_INTERNAL static inline volatile uint32_t* internal_itm_tenr(void)
{
  return (volatile uint32_t*)k_ra8_itm_tenr_addr;
}
#endif

RA8_INTERNAL static inline bool internal_itm_ready(void)
{
  /* A redirected byte sink needs no ITM/debugger -- it is always ready.
   * Off target that is the complete readiness condition. On target the
   * architectural checks still run when no sink is installed. */
#ifdef RA8_OFF_TARGET
  return s_byte_sink != nullptr;
#else
  if (s_byte_sink != nullptr) {
    return true;
  }
  /* Hardening: if DEMCR.TRCENA is clear the ITM block is powered down
   * and any read of its registers (TCR, TENR, STIM) will bus-fault.
   * Pre-check TRCENA via the shared ra8_scb primitive (DEMCR is always
   * accessible) before touching ITM.
   *
   * This was the root cause of escalation-to-LOCKUP observed during
   * USB bring-up: the original USB fault entered the fault handler,
   * which called this function, which read ITM_TCR with TRCENA=0 ->
   * second fault -> LOCKUP at PC=0xEFFFFFFE, hiding the real PC. */
  if (!ra8_scb_trace_enabled()) {
    return false;
  }
  /* Additional belt-and-braces: never poke ITM from a fault context.
   * IPSR != 0 means we are inside an exception handler. Even if
   * TRCENA happens to be on, dropping log lines is preferable to a
   * second fault that masks the original PC. */
  volatile uint32_t ipsr = 0U;
  __asm__ volatile("mrs %0, ipsr" : "=r"(ipsr));
  if (ipsr != 0U) {
    return false;
  }
  const uint32_t tcr  = *internal_itm_tcr();
  const uint32_t tenr = *internal_itm_tenr();
  /* TCR bit 0 = ITMENA. TENR bit 0 = stimulus port 0 enabled. */
  if ((tcr & 1U) == 0U) {
    return false;
  }
  if ((tenr & 1U) == 0U) {
    return false;
  }
  return *internal_itm_stim0() != 0U;
#endif
}

RA8_INTERNAL static inline void internal_itm_putc(uint8_t byte)
{
  if (s_byte_sink != nullptr) {
    s_byte_sink(s_byte_sink_ctx, byte);
    return;
  }
#ifdef RA8_OFF_TARGET
  /* Hosted builds reach this only with no sink installed, and
   * `internal_itm_ready()` already reported the backend unavailable in that
   * case, so every caller has returned before here. Compiling the ITM
   * fallback out completes commit "keep hosted logging off target MMIO":
   * the target-only accessors above are already excluded the same way, and
   * leaving this loop in would be the one remaining host reference to
   * `k_ra8_itm_stim_base`. */
  (void)byte;
#else
  /* A real build should pre-check `internal_itm_ready()` once during
   * init and skip the call entirely when the debugger is absent. For
   * now we poll with a small bound so a disconnected debugger never
   * stalls the firmware. */
  enum : uint32_t {
    k_ra8_itm_poll_limit = 1000U, 
  };
  for (uint32_t i = 0U; i < k_ra8_itm_poll_limit; i++) {
    if (*internal_itm_stim0() != 0U) {
      *(volatile uint8_t*)k_ra8_itm_stim_base = byte;
      return;
    }
  }
#endif
}

RA8_INTERNAL static inline void internal_itm_puts(const char* s)
{
  while (*s != '\0') {
    internal_itm_putc((uint8_t)*s++);
  }
}

typedef enum : uint8_t {
  k_ra8_u32_max_digits = 10U, 
  k_ra8_decimal_base   = 10U, 
} ra8_log_u32_t;
 
/* Itm put u32 -- see implementation for details. */
RA8_INTERNAL static inline void internal_itm_put_u32(uint32_t value)
{
  char    buf[k_ra8_u32_max_digits + 1U] = {};
  uint8_t i                              = 0U;
  if (value == 0U) {
    internal_itm_putc('0');
    return;
  }
  /* mcdc-deactivated: internal_itm_put_u32 digit-buffer watchdog; UINT32_MAX is exactly 10 decimal digits and k_ra8_u32_max_digits == 10, so `value` reaches 0 on or before the tenth iteration and `i < k_ra8_u32_max_digits` is constant-true whenever it is evaluated. */
  while (value != 0U && i < k_ra8_u32_max_digits) {
    buf[i++] = (char)('0' + (char)(value % (uint32_t)k_ra8_decimal_base));
    value /= (uint32_t)k_ra8_decimal_base;
  }
  /* Digits were pushed LSB-first; emit MSB-first. */
  while (i > 0U) {
    i--;
    internal_itm_putc((uint8_t)buf[i]);
  }
}

RA8_INTERNAL static inline void internal_itm_put_i32(int32_t value)
{
  if (value < 0) {
    internal_itm_putc((uint8_t)'-');
    /* Casting INT32_MIN negated is UB; subtract through uint32_t. */
    internal_itm_put_u32((uint32_t)(-(int64_t)value));
    return;
  }
  internal_itm_put_u32((uint32_t)value);
}
 
/* =============================================================================
 * Public API (weak so downstream can override)
 * =============================================================================
 */

void ra8_log_init(void)
{
  /* ITM is set up by the debugger when it attaches. Nothing to do here
   * in the default backend. A UART-backed override would configure its
   * SCI channel in its own ra8_log_init(). */
}

RA8_INTERNAL static void internal_emit_line(const char* level, const char* tag, const char* msg)
{
  if (!internal_itm_ready()) {
    return;
  }
  internal_itm_putc((uint8_t)'[');
  internal_itm_puts(tag);
  internal_itm_putc((uint8_t)']');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(level);
  internal_itm_putc((uint8_t)':');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(msg);
  internal_itm_putc((uint8_t)'\r');
  internal_itm_putc((uint8_t)'\n');
}

RA8_INTERNAL static void
internal_emit_line_u(const char* level, const char* tag, const char* msg, uint32_t value)
{
  if (!internal_itm_ready()) {
    return;
  }
  internal_itm_putc((uint8_t)'[');
  internal_itm_puts(tag);
  internal_itm_putc((uint8_t)']');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(level);
  internal_itm_putc((uint8_t)':');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(msg);
  internal_itm_putc((uint8_t)'=');
  internal_itm_put_u32(value);
  internal_itm_putc((uint8_t)'\r');
  internal_itm_putc((uint8_t)'\n');
}

RA8_INTERNAL static void
internal_emit_line_i(const char* level, const char* tag, const char* msg, int32_t value)
{
  if (!internal_itm_ready()) {
    return;
  }
  internal_itm_putc((uint8_t)'[');
  internal_itm_puts(tag);
  internal_itm_putc((uint8_t)']');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(level);
  internal_itm_putc((uint8_t)':');
  internal_itm_putc((uint8_t)' ');
  internal_itm_puts(msg);
  internal_itm_putc((uint8_t)'=');
  internal_itm_put_i32(value);
  internal_itm_putc((uint8_t)'\r');
  internal_itm_putc((uint8_t)'\n');
}
 
/* ---- plain string log -------------------------------------------------- */
 
[[gnu::weak]] void ra8_log_emit_error(const char* tag, const char* message)
{
  internal_emit_line("ERROR", tag, message);
}
 
[[gnu::weak]] void ra8_log_emit_warn(const char* tag, const char* message)
{
  internal_emit_line("WARN", tag, message);
}
 
[[gnu::weak]] void ra8_log_emit_info(const char* tag, const char* message)
{
  internal_emit_line("INFO", tag, message);
}
 
[[gnu::weak]] void ra8_log_emit_debug(const char* tag, const char* message)
{
  internal_emit_line("DEBUG", tag, message);
}
 
/* ---- string + value log ------------------------------------------------- */

[[gnu::weak]] void ra8_log_emit_error_val(const char* tag, const char* message, uint32_t value)
{
  internal_emit_line_u("ERROR", tag, message, value);
}

[[gnu::weak]] void ra8_log_emit_warn_val(const char* tag, const char* message, uint32_t value)
{
  internal_emit_line_u("WARN", tag, message, value);
}

[[gnu::weak]] void ra8_log_emit_info_val(const char* tag, const char* message, uint32_t value)
{
  internal_emit_line_u("INFO", tag, message, value);
}

[[gnu::weak]] void ra8_log_emit_debug_val(const char* tag, const char* message, int32_t value)
{
  internal_emit_line_i("DEBUG", tag, message, value);
}
 
/* =============================================================================
 * ra8_err_to_str (lives here because the log backend is the only user)
 * =============================================================================
 */
 
#include "ra8_err.h"

typedef struct {
  ra8_err_t   code; 
  const char* name; 
} ra8_err_name_entry_t;

static const ra8_err_name_entry_t s_ra8_err_names[] = {
  {k_ra8_ok, "ok"},
  {k_ra8_fail, "fail"},
  {k_ra8_err_no_mem, "no_mem"},
  {k_ra8_err_invalid_arg, "invalid_arg"},
  {k_ra8_err_invalid_state, "invalid_state"},
  {k_ra8_err_invalid_size, "invalid_size"},
  {k_ra8_err_not_found, "not_found"},
  {k_ra8_err_not_supported, "not_supported"},
  {k_ra8_err_timeout, "timeout"},
  {k_ra8_err_busy, "busy"},
  {k_ra8_err_no_data, "no_data"},
  {k_ra8_err_would_block, "would_block"},
  {k_ra8_err_exists, "exists"},
  {k_ra8_err_empty, "empty"},
  {k_ra8_err_cancelled, "cancelled"},
  {k_ra8_err_not_initialized, "not_initialized"},
  {k_ra8_err_estop, "estop"},
  {k_ra8_err_not_empty, "not_empty"},
  {k_ra8_err_access_denied, "access_denied"},
  {k_ra8_err_hw_init_failed, "hw_init_failed"},
  {k_ra8_err_hw_not_ready, "hw_not_ready"},
  {k_ra8_err_hw_timeout, "hw_timeout"},
  {k_ra8_err_hw_error, "hw_error"},
  {k_ra8_err_gpio_conflict, "gpio_conflict"},
  {k_ra8_err_gpio_invalid_port, "gpio_invalid_port"},
  {k_ra8_err_gpio_invalid_pin, "gpio_invalid_pin"},
  {k_ra8_err_out_of_range, "out_of_range"},
  {k_ra8_err_hw_unmapped, "hw_unmapped"},
  {k_ra8_err_rtos_error, "rtos_error"},
  {k_ra8_err_rtos_thread_create, "rtos_thread_create"},
  {k_ra8_err_rtos_semaphore, "rtos_semaphore"},
  {k_ra8_err_rtos_mutex, "rtos_mutex"},
  {k_ra8_err_rtos_queue, "rtos_queue"},
  {k_ra8_err_rtos_timer, "rtos_timer"},
  {k_ra8_err_comm_error, "comm_error"},
  {k_ra8_err_spi_error, "spi_error"},
  {k_ra8_err_uart_error, "uart_error"},
  {k_ra8_err_i2c_error, "i2c_error"},
  {k_ra8_err_crc_mismatch, "crc_mismatch"},
  {k_ra8_err_protocol_error, "protocol_error"},
  {k_ra8_err_nack, "nack"},
  {k_ra8_err_conflict, "conflict"},
  {k_ra8_err_retry_limit, "retry_limit"},
  {k_ra8_err_validation_failed, "validation_failed"},
  {k_ra8_err_checksum_mismatch, "checksum_mismatch"},
  {k_ra8_err_range_check_failed, "range_check_failed"},
  {k_ra8_err_null_ptr, "null_ptr"},
  {k_ra8_err_decomp_output_cap, "decomp_output_cap"},
  {k_ra8_err_decomp_ratio, "decomp_ratio"},
  {k_ra8_err_decomp_entries, "decomp_entries"},
  {k_ra8_err_decomp_depth, "decomp_depth"},
  {k_ra8_err_decomp_iterations, "decomp_iterations"},
};

static const uint32_t s_ra8_err_names_count =
  (uint32_t)(sizeof(s_ra8_err_names) / sizeof(s_ra8_err_names[0]));

const char* ra8_err_to_str(ra8_err_t err)
{
  for (uint32_t i = 0; i < s_ra8_err_names_count; i++) {
    if (s_ra8_err_names[i].code == err) {
      return s_ra8_err_names[i].name;
    }
  }
  return "unknown";
}