ra8_esp_hosted_rtos.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_esp_hosted_port.h"
#include "ra8_esp_hosted_rtos_internal.h"
#include "ra8_log.h"
 
#ifdef RA8_OFF_TARGET
#include "ra8_esp_hosted_tx_shim_sync_internal.h"
#else
#include "tx_api.h"
#endif
 
#include "port_esp_hosted_host_os.h"

static const char* s_tag = "ESPH_RTOS";

typedef enum : uint32_t {
  k_ra8_esp_hosted_ms_per_tick          = 1U,          
  k_ra8_esp_hosted_us_per_ms            = 1000U,       
  k_ra8_esp_hosted_ms_per_sec           = 1000U,       
  k_ra8_esp_hosted_hz_per_mhz           = 1000000U,    
  k_ra8_esp_hosted_spin_cycles_per_iter = 4U,          
  k_ra8_esp_hosted_spin_iters_max       = 250000U,     
  k_ra8_esp_hosted_delay_iters_max      = 1000000U,    
  k_ra8_esp_hosted_default_cpu_hz       = 1000000000U, 
  k_ra8_esp_hosted_thread_stack_bytes   = 5120U,       
  k_ra8_esp_hosted_name_max             = 16U,         
} ra8_esp_hosted_rtos_const_t;

typedef void (*ra8_esp_hosted_thread_entry_t)(void const* arg);

typedef void (*ra8_esp_hosted_timer_cb_t)(void* arg);

typedef struct {
  TX_THREAD                     cb;     
  ra8_esp_hosted_thread_entry_t entry;  
  void*                         arg;    
  char name[k_ra8_esp_hosted_name_max]; 
} ra8_esp_hosted_thread_slot_t;

typedef struct {
  TX_TIMER                  cb;         
  ra8_esp_hosted_timer_cb_t cb_fn;      
  void*                     arg;        
  char name[k_ra8_esp_hosted_name_max]; 
} ra8_esp_hosted_timer_slot_t;

typedef struct {
  ra8_esp_hosted_thread_slot_t threads[k_ra8_esp_hosted_max_threads];
  bool thread_used[k_ra8_esp_hosted_max_threads];
  ra8_esp_hosted_timer_slot_t timers[k_ra8_esp_hosted_max_timers];
  bool     timer_used[k_ra8_esp_hosted_max_timers];
  uint32_t cpu_hz;     
  uint32_t last_ticks; 
  uint64_t tick_epoch; 
  bool     ready;      
} ra8_esp_hosted_rtos_state_t;

static ra8_esp_hosted_rtos_state_t s_rtos;

static uint8_t s_thread_stacks[k_ra8_esp_hosted_max_threads][k_ra8_esp_hosted_thread_stack_bytes];
 
/* ----------------------------------------------------------------------- */
/* Table helpers */
/* ----------------------------------------------------------------------- */
 
uint32_t priv_ra8_esp_hosted_rtos_slot_take(bool* used, uint32_t count)
{
  if (used == nullptr) {
    return count;
  }
  for (uint32_t i = 0U; i < count; ++i) {
    if (!used[i]) {
      used[i] = true;
      return i;
    }
  }
  return count;
}
 
uint32_t priv_ra8_esp_hosted_rtos_slot_index(const void* handle,
                                             const void* base,
                                             size_t      stride,
                                             uint32_t    count,
                                             const bool* used)
{
  if ((handle == nullptr) || (base == nullptr) || (used == nullptr)) {
    return count;
  }
  for (uint32_t i = 0U; i < count; ++i) {
    const void* const row = (const void*)((const uint8_t*)base + ((size_t)i * stride));
    if ((row == handle) && used[i]) {
      return i;
    }
  }
  return count;
}

RA8_INTERNAL static void internal_copy_name(char* dst, size_t cap, const char* src)
{
  (void)memset(dst, 0, cap);
  if (src == nullptr) {
    return;
  }
  const size_t limit = cap - 1U;
  size_t       n     = 0U;
  while ((n < limit) && (src[n] != '\0')) {
    dst[n] = src[n];
    n++;
  }
  dst[n] = '\0';
}

RA8_INTERNAL static void internal_thread_entry(ULONG index)
{
  const uint32_t idx = (uint32_t)index;
  if (idx >= (uint32_t)k_ra8_esp_hosted_max_threads) {
    return;
  }
  if (s_rtos.thread_used[idx]) {
    s_rtos.threads[idx].entry(s_rtos.threads[idx].arg);
  }
}

RA8_INTERNAL static void internal_timer_expiry(ULONG index)
{
  const uint32_t idx = (uint32_t)index;
  if (idx >= (uint32_t)k_ra8_esp_hosted_max_timers) {
    return;
  }
  if (s_rtos.timer_used[idx]) {
    s_rtos.timers[idx].cb_fn(s_rtos.timers[idx].arg);
  }
}

RA8_INTERNAL
RA8_BOUNDED_LOOP(k_ra8_esp_hosted_spin_iters_max)
static void internal_spin_us(uint32_t usec)
{
  const uint32_t    iters = priv_ra8_esp_hosted_rtos_us_spin_iters(s_rtos.cpu_hz, usec);
  volatile uint32_t sink  = 0U;
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_spin_iters_max; ++i) {
    if (i >= iters) {
      break;
    }
    sink = sink + 1U;
  }
}
 
/* ----------------------------------------------------------------------- */
/* Testable arithmetic */
/* ----------------------------------------------------------------------- */
 
uint32_t priv_ra8_esp_hosted_rtos_ms_to_ticks(int timeout_ms)
{
  if (timeout_ms < 0) {
    return (uint32_t)TX_WAIT_FOREVER;
  }
  if (timeout_ms == 0) {
    return (uint32_t)TX_NO_WAIT;
  }
  return (uint32_t)timeout_ms / (uint32_t)k_ra8_esp_hosted_ms_per_tick;
}
 
uint32_t priv_ra8_esp_hosted_rtos_us_spin_iters(uint32_t cpu_hz, uint32_t usec)
{
  if ((cpu_hz == 0U) || (usec == 0U)) {
    return 0U;
  }
  const uint32_t cycles_per_us = cpu_hz / (uint32_t)k_ra8_esp_hosted_hz_per_mhz;
  const uint32_t iters = (cycles_per_us * usec) / (uint32_t)k_ra8_esp_hosted_spin_cycles_per_iter;
  if (iters == 0U) {
    return 1U;
  }
  if (iters > (uint32_t)k_ra8_esp_hosted_spin_iters_max) {
    return (uint32_t)k_ra8_esp_hosted_spin_iters_max;
  }
  return iters;
}
 
/* ----------------------------------------------------------------------- */
/* Thread and sleep vtable slots */
/* ----------------------------------------------------------------------- */

RA8_INTERNAL static void* internal_h_thread_create(const char*                   tname,
                                                   uint32_t                      tprio,
                                                   uint32_t                      tstack_size,
                                                   ra8_esp_hosted_thread_entry_t start_routine,
                                                   void*                         sr_arg)
{
  if (!s_rtos.ready || (start_routine == nullptr)) {
    return nullptr;
  }
  if ((tstack_size < (uint32_t)TX_MINIMUM_STACK) ||
      (tstack_size > (uint32_t)k_ra8_esp_hosted_thread_stack_bytes)) {
    return nullptr;
  }
  const uint32_t idx =
    priv_ra8_esp_hosted_rtos_slot_take(s_rtos.thread_used, k_ra8_esp_hosted_max_threads);
  if (idx == (uint32_t)k_ra8_esp_hosted_max_threads) {
    ra8_log_error(s_tag, "thread table exhausted");
    return nullptr;
  }
  ra8_esp_hosted_thread_slot_t* const slot = &s_rtos.threads[idx];
  slot->entry                              = start_routine;
  slot->arg                                = sr_arg;
  internal_copy_name(slot->name, sizeof(slot->name), tname);
  if (tx_thread_create(&slot->cb,
                       slot->name,
                       internal_thread_entry,
                       (ULONG)idx,
                       s_thread_stacks[idx],
                       (ULONG)tstack_size,
                       (UINT)tprio,
                       (UINT)tprio,
                       TX_NO_TIME_SLICE,
                       TX_AUTO_START) != TX_SUCCESS) {
    s_rtos.thread_used[idx] = false;
    return nullptr;
  }
  return slot;
}

RA8_INTERNAL static int internal_h_thread_cancel(void* thread_handle)
{
  const uint32_t idx = priv_ra8_esp_hosted_rtos_slot_index(thread_handle,
                                                           s_rtos.threads,
                                                           sizeof(s_rtos.threads[0]),
                                                           k_ra8_esp_hosted_max_threads,
                                                           s_rtos.thread_used);
  if (idx == (uint32_t)k_ra8_esp_hosted_max_threads) {
    return RET_INVALID;
  }
  int rc = RET_OK;
  if (tx_thread_terminate(&s_rtos.threads[idx].cb) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  if (tx_thread_delete(&s_rtos.threads[idx].cb) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  s_rtos.threads[idx].entry = nullptr;
  s_rtos.thread_used[idx]   = false;
  return rc;
}

RA8_INTERNAL static void internal_h_thread_yield(void)
{
  if (s_rtos.ready) {
    tx_thread_relinquish();
  }
}

RA8_INTERNAL static unsigned int internal_h_msleep(unsigned int mseconds)
{
  if (s_rtos.ready) {
    (void)tx_thread_sleep((ULONG)mseconds * (ULONG)k_ra8_esp_hosted_ms_per_tick);
  }
  return mseconds;
}

RA8_INTERNAL static unsigned int internal_h_sleep(unsigned int seconds)
{
  (void)internal_h_msleep(seconds * (unsigned int)k_ra8_esp_hosted_ms_per_sec);
  return seconds;
}

RA8_INTERNAL static unsigned int internal_h_usleep(unsigned int useconds)
{
  if (useconds == 0U) {
    return 0U;
  }
  const uint32_t whole_ms = (uint32_t)useconds / (uint32_t)k_ra8_esp_hosted_us_per_ms;
  const uint32_t rem_us   = (uint32_t)useconds % (uint32_t)k_ra8_esp_hosted_us_per_ms;
  if (whole_ms > 0U) {
    (void)internal_h_msleep(whole_ms);
  }
  internal_spin_us(rem_us);
  return useconds;
}

RA8_INTERNAL
RA8_BOUNDED_LOOP(k_ra8_esp_hosted_delay_iters_max)
static unsigned int internal_h_blocking_delay(unsigned int number)
{
  const uint32_t    iters = (number > (unsigned int)k_ra8_esp_hosted_delay_iters_max)
                              ? (uint32_t)k_ra8_esp_hosted_delay_iters_max
                              : (uint32_t)number;
  volatile uint32_t sink  = 0U;
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_delay_iters_max; ++i) {
    if (i >= iters) {
      break;
    }
    sink = sink + 1U;
  }
  return number;
}
 
/* ----------------------------------------------------------------------- */
/* Timer and clock vtable slots */
/* ----------------------------------------------------------------------- */

RA8_INTERNAL static void* internal_h_timer_start(const char*               name,
                                                 int                       duration_ms,
                                                 int                       type,
                                                 ra8_esp_hosted_timer_cb_t timeout_handler,
                                                 void*                     arg)
{
  if (!s_rtos.ready || (timeout_handler == nullptr) || (duration_ms <= 0)) {
    return nullptr;
  }
  if ((type != H_TIMER_TYPE_ONESHOT) && (type != H_TIMER_TYPE_PERIODIC)) {
    return nullptr;
  }
  const uint32_t idx =
    priv_ra8_esp_hosted_rtos_slot_take(s_rtos.timer_used, k_ra8_esp_hosted_max_timers);
  if (idx == (uint32_t)k_ra8_esp_hosted_max_timers) {
    ra8_log_error(s_tag, "timer table exhausted");
    return nullptr;
  }
  ra8_esp_hosted_timer_slot_t* const slot = &s_rtos.timers[idx];
  slot->cb_fn                             = timeout_handler;
  slot->arg                               = arg;
  internal_copy_name(slot->name, sizeof(slot->name), name);
  const ULONG ticks  = (ULONG)priv_ra8_esp_hosted_rtos_ms_to_ticks(duration_ms);
  const ULONG repeat = (type == H_TIMER_TYPE_PERIODIC) ? ticks : 0U;
  if (tx_timer_create(&slot->cb,
                      slot->name,
                      internal_timer_expiry,
                      (ULONG)idx,
                      ticks,
                      repeat,
                      TX_AUTO_ACTIVATE) != TX_SUCCESS) {
    s_rtos.timer_used[idx] = false;
    return nullptr;
  }
  return slot;
}

RA8_INTERNAL static int internal_h_timer_stop(void* timer_handle)
{
  const uint32_t idx = priv_ra8_esp_hosted_rtos_slot_index(timer_handle,
                                                           s_rtos.timers,
                                                           sizeof(s_rtos.timers[0]),
                                                           k_ra8_esp_hosted_max_timers,
                                                           s_rtos.timer_used);
  if (idx == (uint32_t)k_ra8_esp_hosted_max_timers) {
    return RET_INVALID;
  }
  int rc = RET_OK;
  if (tx_timer_deactivate(&s_rtos.timers[idx].cb) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  if (tx_timer_delete(&s_rtos.timers[idx].cb) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  s_rtos.timers[idx].cb_fn = nullptr;
  s_rtos.timer_used[idx]   = false;
  return rc;
}

RA8_INTERNAL static uint64_t internal_h_get_time_ms(void)
{
  if (!s_rtos.ready) {
    return 0U;
  }
  const uint32_t now = (uint32_t)tx_time_get();
  if (now < s_rtos.last_ticks) {
    s_rtos.tick_epoch += ((uint64_t)UINT32_MAX + 1U);
  }
  s_rtos.last_ticks = now;
  return (s_rtos.tick_epoch + (uint64_t)now) * (uint64_t)k_ra8_esp_hosted_ms_per_tick;
}
 
/* ----------------------------------------------------------------------- */
/* Lifecycle and binding */
/* ----------------------------------------------------------------------- */
 
bool priv_ra8_esp_hosted_rtos_is_ready(void)
{
  return s_rtos.ready;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_init(void)
{
  if (s_rtos.ready) {
    ra8_log_error(s_tag, "RTOS substrate already initialised");
    return k_ra8_err_invalid_state;
  }
  (void)memset(&s_rtos, 0, sizeof(s_rtos));
  RA8_RETURN_ON_ERROR(priv_ra8_esp_hosted_rtos_pool_init(), s_tag, "byte pools refused");
  RA8_RETURN_ON_ERROR(priv_ra8_esp_hosted_rtos_sync_init(), s_tag, "sync tables refused");
  uint32_t cpu_hz = 0U;
  if (ra8_cgc_get_clock_hz(k_ra8_clock_id_cpuclk0, &cpu_hz) != k_ra8_ok) {
    cpu_hz = (uint32_t)k_ra8_esp_hosted_default_cpu_hz;
    ra8_log_warn(s_tag, "core rate query failed; usleep uses the fallback rate");
  }
  s_rtos.cpu_hz     = cpu_hz;
  s_rtos.last_ticks = (uint32_t)tx_time_get();
  s_rtos.ready      = true;
  return k_ra8_ok;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_deinit(void)
{
  if (!s_rtos.ready) {
    ra8_log_error(s_tag, "RTOS substrate not initialised");
    return k_ra8_err_not_initialized;
  }
  ra8_err_t worst = k_ra8_ok;
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_max_timers; ++i) {
    if (s_rtos.timer_used[i] && (internal_h_timer_stop(&s_rtos.timers[i]) != RET_OK)) {
      worst = k_ra8_err_rtos_error;
    }
  }
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_max_threads; ++i) {
    if (s_rtos.thread_used[i] && (internal_h_thread_cancel(&s_rtos.threads[i]) != RET_OK)) {
      worst = k_ra8_err_rtos_error;
    }
  }
  if (priv_ra8_esp_hosted_rtos_sync_deinit() != k_ra8_ok) {
    worst = k_ra8_err_rtos_error;
  }
  if (priv_ra8_esp_hosted_rtos_pool_deinit() != k_ra8_ok) {
    worst = k_ra8_err_rtos_error;
  }
  (void)memset(&s_rtos, 0, sizeof(s_rtos));
  return worst;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_bind(hosted_osi_funcs_t* out)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "vtable is NULL");
  out->_h_thread_create  = internal_h_thread_create;
  out->_h_thread_cancel  = internal_h_thread_cancel;
  out->_h_thread_yield   = internal_h_thread_yield;
  out->_h_msleep         = internal_h_msleep;
  out->_h_usleep         = internal_h_usleep;
  out->_h_sleep          = internal_h_sleep;
  out->_h_blocking_delay = internal_h_blocking_delay;
  out->_h_timer_start    = internal_h_timer_start;
  out->_h_timer_stop     = internal_h_timer_stop;
  out->_h_get_time_ms    = internal_h_get_time_ms;
  return k_ra8_ok;
}