ra8_esp_hosted_rtos_pool.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.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
#define RA8_ESP_HOSTED_TX_SHIM_IMPL
#include "ra8_esp_hosted_tx_shim_internal.h"
#else
#include "tx_api.h"
#endif
 
#include "port_esp_hosted_host_os.h"

static const char* s_tag = "ESPH_MEM";

typedef enum : uint32_t {
  k_ra8_esp_hosted_hdr_bytes        = 16U,         
  k_ra8_esp_hosted_hdr_magic        = 0x52384D42U, 
  k_ra8_esp_hosted_align_none       = 1U,          
  k_ra8_esp_hosted_align_max        = 64U,         
  k_ra8_esp_hosted_alloc_max        = 8192U,       
  k_ra8_esp_hosted_queue_words_max  = 16U,         
  k_ra8_esp_hosted_queue_word_bytes = 4U,          
  k_ra8_esp_hosted_queue_elems_max  = 64U,         
} ra8_esp_hosted_pool_const_t;

typedef struct {
  void*    base;  
  uint32_t magic; 
  uint32_t size;  
} ra8_esp_hosted_alloc_hdr_t;
 
static_assert(sizeof(ra8_esp_hosted_alloc_hdr_t) <= (size_t)k_ra8_esp_hosted_hdr_bytes,
              "allocation header must fit the documented 16-byte slot");

typedef struct {
  TX_QUEUE cb;       
  void*    storage;  
  uint32_t enqueued; 
  bool     used;     
} ra8_esp_hosted_queue_slot_t;

typedef struct {
  TX_BYTE_POOL transport;  
  TX_BYTE_POOL queue_pool; 
  ra8_esp_hosted_queue_slot_t queues[k_ra8_esp_hosted_max_queues];
  bool                        ready; 
} ra8_esp_hosted_pool_state_t;

static ra8_esp_hosted_pool_state_t s_pool;

alignas(k_ra8_esp_hosted_align_max) static uint8_t s_transport_mem[k_ra8_esp_hosted_pool_bytes];

alignas(k_ra8_esp_hosted_align_max) static uint8_t s_queue_mem[k_ra8_esp_hosted_queue_pool_bytes];

static char s_tx_name_esph_buf[] = "esph_buf";

static char s_tx_name_esph_q[] = "esph_q";
 
/* ----------------------------------------------------------------------- */
/* Fixed-storage allocator */
/* ----------------------------------------------------------------------- */
 
ra8_err_t priv_ra8_esp_hosted_rtos_pool_init(void)
{
  if (s_pool.ready) {
    ra8_log_error(s_tag, "pool already initialised");
    return k_ra8_err_invalid_state;
  }
  (void)memset(&s_pool, 0, sizeof(s_pool));
  if (tx_byte_pool_create(&s_pool.transport,
                          s_tx_name_esph_buf,
                          s_transport_mem,
                          (ULONG)sizeof(s_transport_mem)) != TX_SUCCESS) {
    ra8_log_error(s_tag, "transport byte pool refused");
    return k_ra8_err_rtos_error;
  }
  if (tx_byte_pool_create(&s_pool.queue_pool,
                          s_tx_name_esph_q,
                          s_queue_mem,
                          (ULONG)sizeof(s_queue_mem)) != TX_SUCCESS) {
    (void)tx_byte_pool_delete(&s_pool.transport);
    (void)memset(&s_pool, 0, sizeof(s_pool));
    ra8_log_error(s_tag, "queue byte pool refused");
    return k_ra8_err_rtos_error;
  }
  s_pool.ready = true;
  return k_ra8_ok;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_pool_deinit(void)
{
  if (!s_pool.ready) {
    ra8_log_error(s_tag, "pool 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_queues; ++i) {
    if (!s_pool.queues[i].used) {
      continue;
    }
    if (tx_queue_delete(&s_pool.queues[i].cb) != TX_SUCCESS) {
      worst = k_ra8_err_rtos_error;
    }
    if (tx_byte_release(s_pool.queues[i].storage) != TX_SUCCESS) {
      worst = k_ra8_err_rtos_error;
    }
    s_pool.queues[i].used = false;
  }
  if (tx_byte_pool_delete(&s_pool.queue_pool) != TX_SUCCESS) {
    worst = k_ra8_err_rtos_error;
  }
  if (tx_byte_pool_delete(&s_pool.transport) != TX_SUCCESS) {
    worst = k_ra8_err_rtos_error;
  }
  (void)memset(&s_pool, 0, sizeof(s_pool));
  return worst;
}
 
void priv_ra8_esp_hosted_rtos_pool_stats(uint32_t* out_available, uint32_t* out_fragments)
{
  ULONG available = 0U;
  ULONG fragments = 0U;
  if (s_pool.ready) {
    (void)tx_byte_pool_info_get(&s_pool.transport,
                                nullptr,
                                &available,
                                &fragments,
                                nullptr,
                                nullptr,
                                nullptr);
  }
  if (out_available != nullptr) {
    *out_available = (uint32_t)available;
  }
  if (out_fragments != nullptr) {
    *out_fragments = (uint32_t)fragments;
  }
}
 
void* priv_ra8_esp_hosted_rtos_alloc(size_t size, size_t align)
{
  if (!s_pool.ready) {
    return nullptr;
  }
  if ((size == 0U) || (size > (size_t)k_ra8_esp_hosted_alloc_max)) {
    return nullptr;
  }
  if ((align == 0U) || (align > (size_t)k_ra8_esp_hosted_align_max) ||
      ((align & (align - 1U)) != 0U)) {
    return nullptr;
  }
  void*       base  = nullptr;
  const ULONG total = (ULONG)(size + (size_t)k_ra8_esp_hosted_hdr_bytes + align - 1U);
  /* Two ways to end up with no memory, and both must return null: the pool
     refused, or -- a contract break by the allocator -- it reported success
     without writing the block pointer. `tx_byte_allocate` writes its
     out-parameter only on the success path, so the second term is what makes
     that invariant locally provable; without it the header write below
     computes its destination from address 0, which the clang static analyzer
     reports as a null dereference (docs/STATIC_ANALYSIS.md).
     ONE decision rather than a second early return: this file is at its
     MISRA-C 15.5 single-exit budget, and both conditions get full MC/DC from
     `test_pool_exhaustion_reports_null`. */
  if ((tx_byte_allocate(&s_pool.transport, &base, total, TX_NO_WAIT) != TX_SUCCESS) ||
      (base == nullptr)) {
    return nullptr;
  }
  const uintptr_t            raw     = (uintptr_t)base + (uintptr_t)k_ra8_esp_hosted_hdr_bytes;
  const uintptr_t            aligned = (raw + (uintptr_t)align - 1U) & ~((uintptr_t)align - 1U);
  ra8_esp_hosted_alloc_hdr_t hdr     = {};
  hdr.base                           = base;
  hdr.magic                          = (uint32_t)k_ra8_esp_hosted_hdr_magic;
  hdr.size                           = (uint32_t)size;
  (void)memcpy((void*)(aligned - (uintptr_t)k_ra8_esp_hosted_hdr_bytes), &hdr, sizeof(hdr));
  return (void*)aligned;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_release(void* ptr)
{
  RA8_CHECK_NULL_PTR(ptr, s_tag, "release of a null pointer");
  ra8_esp_hosted_alloc_hdr_t hdr = {};
  (void)memcpy(&hdr,
               (const void*)((uintptr_t)ptr - (uintptr_t)k_ra8_esp_hosted_hdr_bytes),
               sizeof(hdr));
  if (hdr.magic != (uint32_t)k_ra8_esp_hosted_hdr_magic) {
    ra8_log_error(s_tag, "release of a pointer this port never handed out");
    return k_ra8_err_invalid_arg;
  }
  if (tx_byte_release(hdr.base) != TX_SUCCESS) {
    return k_ra8_err_rtos_error;
  }
  return k_ra8_ok;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_block_size(const void* ptr, size_t* out_size)
{
  RA8_CHECK_NULL_PTR(ptr, s_tag, "block_size of a null pointer");
  RA8_CHECK_NULL_PTR(out_size, s_tag, "out_size is NULL");
  ra8_esp_hosted_alloc_hdr_t hdr = {};
  (void)memcpy(&hdr,
               (const void*)((uintptr_t)ptr - (uintptr_t)k_ra8_esp_hosted_hdr_bytes),
               sizeof(hdr));
  if (hdr.magic != (uint32_t)k_ra8_esp_hosted_hdr_magic) {
    return k_ra8_err_invalid_arg;
  }
  *out_size = (size_t)hdr.size;
  return k_ra8_ok;
}
 
uint32_t priv_ra8_esp_hosted_rtos_queue_words(uint32_t item_bytes)
{
  const uint32_t word  = (uint32_t)k_ra8_esp_hosted_queue_word_bytes;
  const uint32_t words = (item_bytes + (word - 1U)) / word;
  if ((item_bytes == 0U) || (words > (uint32_t)k_ra8_esp_hosted_queue_words_max)) {
    return 0U;
  }
  return words;
}
 
/* ----------------------------------------------------------------------- */
/* Memory vtable slots */
/* ----------------------------------------------------------------------- */

RA8_INTERNAL static void* internal_h_memcpy(void* dest, const void* src, uint32_t size)
{
  if ((dest == nullptr) || (src == nullptr)) {
    return nullptr;
  }
  return memcpy(dest, src, (size_t)size);
}

RA8_INTERNAL static void* internal_h_memset(void* buf, int val, size_t len)
{
  if (buf == nullptr) {
    return nullptr;
  }
  return memset(buf, val, len);
}

RA8_INTERNAL static void* internal_h_malloc(size_t size)
{
  return priv_ra8_esp_hosted_rtos_alloc(size, (size_t)k_ra8_esp_hosted_align_none);
}

RA8_INTERNAL static void* internal_h_calloc(size_t blk_no, size_t size)
{
  if ((blk_no == 0U) || (size == 0U)) {
    return nullptr;
  }
  if (blk_no > ((size_t)k_ra8_esp_hosted_alloc_max / size)) {
    return nullptr;
  }
  void* const p =
    priv_ra8_esp_hosted_rtos_alloc(blk_no * size, (size_t)k_ra8_esp_hosted_align_none);
  if (p != nullptr) {
    (void)memset(p, 0, blk_no * size);
  }
  return p;
}

RA8_INTERNAL static void internal_h_free(void* ptr)
{
  (void)priv_ra8_esp_hosted_rtos_release(ptr);
}

RA8_INTERNAL static void* internal_h_realloc(void* mem, size_t newsize)
{
  if (mem == nullptr) {
    return priv_ra8_esp_hosted_rtos_alloc(newsize, (size_t)k_ra8_esp_hosted_align_none);
  }
  if (newsize == 0U) {
    (void)priv_ra8_esp_hosted_rtos_release(mem);
    return nullptr;
  }
  size_t oldsize = 0U;
  if (priv_ra8_esp_hosted_rtos_block_size(mem, &oldsize) != k_ra8_ok) {
    return nullptr;
  }
  void* const fresh = priv_ra8_esp_hosted_rtos_alloc(newsize, (size_t)k_ra8_esp_hosted_align_none);
  if (fresh == nullptr) {
    return nullptr;
  }
  (void)memcpy(fresh, mem, (oldsize < newsize) ? oldsize : newsize);
  (void)priv_ra8_esp_hosted_rtos_release(mem);
  return fresh;
}

RA8_INTERNAL static void* internal_h_malloc_align(size_t size, size_t align)
{
  return priv_ra8_esp_hosted_rtos_alloc(size, align);
}

RA8_INTERNAL static void internal_h_free_align(void* ptr)
{
  (void)priv_ra8_esp_hosted_rtos_release(ptr);
}
 
/* ----------------------------------------------------------------------- */
/* Queue vtable slots */
/* ----------------------------------------------------------------------- */

RA8_INTERNAL static ra8_esp_hosted_queue_slot_t* internal_queue_slot(const void* handle)
{
  if ((handle == nullptr) || !s_pool.ready) {
    return nullptr;
  }
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_max_queues; ++i) {
    if ((handle == (const void*)&s_pool.queues[i]) && s_pool.queues[i].used) {
      return &s_pool.queues[i];
    }
  }
  return nullptr;
}

RA8_INTERNAL static void* internal_h_create_queue(uint32_t qnum_elem, uint32_t qitem_size)
{
  const uint32_t words = priv_ra8_esp_hosted_rtos_queue_words(qitem_size);
  if (!s_pool.ready || (words == 0U)) {
    return nullptr;
  }
  if ((qnum_elem == 0U) || (qnum_elem > (uint32_t)k_ra8_esp_hosted_queue_elems_max)) {
    return nullptr;
  }
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_esp_hosted_max_queues; ++i) {
    if (s_pool.queues[i].used) {
      continue;
    }
    void*       ring  = nullptr;
    const ULONG bytes = (ULONG)qnum_elem * (ULONG)words * (ULONG)k_ra8_esp_hosted_queue_word_bytes;
    if (tx_byte_allocate(&s_pool.queue_pool, &ring, bytes, TX_NO_WAIT) != TX_SUCCESS) {
      return nullptr;
    }
    if (tx_queue_create(&s_pool.queues[i].cb, s_tx_name_esph_q, (UINT)words, ring, bytes) !=
        TX_SUCCESS) {
      (void)tx_byte_release(ring);
      return nullptr;
    }
    s_pool.queues[i].storage  = ring;
    s_pool.queues[i].enqueued = 0U;
    s_pool.queues[i].used     = true;
    return &s_pool.queues[i];
  }
  ra8_log_error(s_tag, "queue table exhausted");
  return nullptr;
}

RA8_INTERNAL static int internal_h_queue_item(void* queue_handle, void* item, int timeout)
{
  ra8_esp_hosted_queue_slot_t* const slot = internal_queue_slot(queue_handle);
  if ((slot == nullptr) || (item == nullptr)) {
    return RET_INVALID;
  }
  const UINT rc =
    tx_queue_send(&slot->cb, item, (ULONG)priv_ra8_esp_hosted_rtos_ms_to_ticks(timeout));
  if (rc == TX_SUCCESS) {
    slot->enqueued++;
    return RET_OK;
  }
  return (rc == TX_QUEUE_FULL) ? RET_FAIL_TIMEOUT : RET_FAIL;
}

RA8_INTERNAL static int internal_h_dequeue_item(void* queue_handle, void* item, int timeout)
{
  ra8_esp_hosted_queue_slot_t* const slot = internal_queue_slot(queue_handle);
  if ((slot == nullptr) || (item == nullptr)) {
    return RET_INVALID;
  }
  const UINT rc =
    tx_queue_receive(&slot->cb, item, (ULONG)priv_ra8_esp_hosted_rtos_ms_to_ticks(timeout));
  if (rc == TX_SUCCESS) {
    if (slot->enqueued > 0U) {
      slot->enqueued--;
    }
    return RET_OK;
  }
  return (rc == TX_QUEUE_EMPTY) ? RET_FAIL_TIMEOUT : RET_FAIL;
}

RA8_INTERNAL static int internal_h_queue_msg_waiting(void* queue_handle)
{
  const ra8_esp_hosted_queue_slot_t* const slot = internal_queue_slot(queue_handle);
  if (slot == nullptr) {
    return RET_INVALID;
  }
  return (int)slot->enqueued;
}

RA8_INTERNAL static int internal_h_reset_queue(void* queue_handle)
{
  ra8_esp_hosted_queue_slot_t* const slot = internal_queue_slot(queue_handle);
  if (slot == nullptr) {
    return RET_INVALID;
  }
  if (tx_queue_flush(&slot->cb) != TX_SUCCESS) {
    return RET_FAIL;
  }
  slot->enqueued = 0U;
  return RET_OK;
}

RA8_INTERNAL static int internal_h_destroy_queue(void* queue_handle)
{
  ra8_esp_hosted_queue_slot_t* const slot = internal_queue_slot(queue_handle);
  if (slot == nullptr) {
    return RET_INVALID;
  }
  int rc = RET_OK;
  if (tx_queue_delete(&slot->cb) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  if (tx_byte_release(slot->storage) != TX_SUCCESS) {
    rc = RET_FAIL;
  }
  slot->storage  = nullptr;
  slot->enqueued = 0U;
  slot->used     = false;
  return rc;
}
 
ra8_err_t priv_ra8_esp_hosted_rtos_bind_pool(hosted_osi_funcs_t* out)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "vtable is NULL");
  out->_h_memcpy            = internal_h_memcpy;
  out->_h_memset            = internal_h_memset;
  out->_h_malloc            = internal_h_malloc;
  out->_h_calloc            = internal_h_calloc;
  out->_h_free              = internal_h_free;
  out->_h_realloc           = internal_h_realloc;
  out->_h_malloc_align      = internal_h_malloc_align;
  out->_h_free_align        = internal_h_free_align;
  out->_h_create_queue      = internal_h_create_queue;
  out->_h_queue_item        = internal_h_queue_item;
  out->_h_dequeue_item      = internal_h_dequeue_item;
  out->_h_queue_msg_waiting = internal_h_queue_msg_waiting;
  out->_h_reset_queue       = internal_h_reset_queue;
  out->_h_destroy_queue     = internal_h_destroy_queue;
  return k_ra8_ok;
}