port_esp_hosted_host_os.h

Go to the documentation of this file.

 
#pragma once
 
#include "ra8_check.h"
#ifndef assert
/* NOLINTNEXTLINE(readability-identifier-naming) -- upstream-fixed lower-case macro spelling. */
#define assert(expr) RA8_ASSERT(expr, "esp-hosted assertion")
#endif
#include <inttypes.h>
#include <stddef.h>
#include <stdint.h>
 
/* ESP-IDF hosts reach these through their own build; on this host the
   port supplies them, and this header is where the vendored core expects
   its environment to arrive from. ``esp_heap_caps.h`` carries the
   allocation capability flags the transport passes through,
   ``<inttypes.h>`` carries the PRIu32 family the serial driver formats
   with, ``<stdlib.h>`` declares the ``calloc`` that
   ``transport_util_calloc`` reaches for on the non-DMA arm, and
   ``<assert.h>`` carries the ``assert`` macro ``spi_drv.c`` guards every
   handle creation in ``bus_init_internal`` with. Without the latter two
   the vendored translation units compiled with C89 implicit declarations:
   ``calloc`` came back as ``int`` (``-Wbuiltin-declaration-mismatch``) and
   ``assert`` became a CALL to a function nothing defines, so the check was
   not a check. */
#include "esp_heap_caps.h"
 
/* The allocation macros below expand to calls through ``g_h``, so the
   vtable declaration has to come with them -- several vendored
   translation units include this header and nothing else that declares
   it. */
#include "esp_hosted_os_abstraction.h"
#include "ra8_esp_hosted_port.h"
 
/* ----------------------------------------------------------------------- */
/* Opaque RTOS handles */
/*                                                                          */
/* The vendored core stores these and hands them back to the vtable; it */
/* never dereferences one. Keeping them void* is what lets the concrete */
/* ThreadX control blocks stay entirely inside the port. */
/* ----------------------------------------------------------------------- */

typedef void* queue_handle_t;

typedef void* semaphore_handle_t;

typedef void* mutex_handle_t;

typedef void* thread_handle_t;

typedef void* spinlock_handle_t;

typedef uint8_t gpio_pin_state_t;
 
/* ----------------------------------------------------------------------- */
/* Return codes */
/* ----------------------------------------------------------------------- */

#define RET_OK (0)

#define RET_FAIL (-1)

#define RET_INVALID (-2)

#define RET_FAIL_TIMEOUT (-3)
 
/* ----------------------------------------------------------------------- */
/* Blocking policy */
/* ----------------------------------------------------------------------- */

#define HOSTED_BLOCKING (1)

#define HOSTED_BLOCK_MAX (0xFFFFFFFF)

#define SEC_TO_MILLISEC(x) ((x) * (1000))
 
/* ----------------------------------------------------------------------- */
/* Memory */
/* ----------------------------------------------------------------------- */

#define HOSTED_MEM_ALIGNMENT_64 (64)

#define HOSTED_UNLIKELY(x) (__builtin_expect(!!(x), 0))

#define HOSTED_LIKELY(x) (__builtin_expect(!!(x), 1))

static inline void* heap_caps_malloc(size_t size, uint32_t caps)
{
  void* result = nullptr;
  if (g_h.funcs != nullptr) {
    if (size != 0U) {
      if ((caps & (uint32_t)MALLOC_CAP_DMA) != 0U) {
        result = g_h.funcs->_h_malloc_align(size, (size_t)HOSTED_MEM_ALIGNMENT_64);
      } else {
        result = g_h.funcs->_h_malloc(size);
      }
    }
  }
  return result;
}

#define HOSTED_FREE(buff)                                                                          \
  do {                                                                                             \
    if (buff) {                                                                                    \
      g_h.funcs->_h_free(buff);                                                                    \
      (buff) = nullptr;                                                                            \
    }                                                                                              \
  } while (0)
 
/*
 * HOSTED_CALLOC is DELIBERATELY NOT DEFINED. Read this before adding it.
 *
 * Upstream's version is an allocate-or-bail macro whose failure arm is a
 * ``goto`` to a caller-supplied label. Defining it here would put a ``goto``
 * in first-party code, which NASA Power of 10 Rule 1 forbids and
 * ``scripts/checks/check_no_goto_setjmp.py`` rejects outright -- that gate has
 * no allowlist, by design.
 *
 * Three ways out were considered and two were rejected:
 *   - Keeping the ``goto`` and waiving the gate. That is the allowlist this
 *     project deliberately does not have.
 *   - Substituting a plain ``return`` for the jump. This one looks tempting
 *     and is simply wrong: of the two call sites at the pinned commit, the one
 *     in ``host/drivers/serial/serial_drv.c`` jumps to a ``free_bufs`` label
 *     that releases two buffers before returning. A bare ``return`` there
 *     leaks both. The two sites also return different types, so no single
 *     substitution could serve both.
 *   - Leaving the macro out, which is what this port does.
 *
 * The consequence is bounded and stated in ``cmake/esp_hosted.cmake``:
 * ``serial_drv.c`` and ``serial_if.c`` are the only vendored translation units
 * that expand this macro, and neither is compiled. Nothing else needs it --
 * their consumers are in the RPC layer, which does not compile in this build
 * for an unrelated reason (it wants ESP-IDF's Wi-Fi API). When the RPC layer
 * is brought in, those two files need a jump-free allocate-or-bail path, and
 * that is a change to make there rather than a rule to bend here.
 */

#define MEM_DUMP(s) ra8_esp_hosted_mem_dump(s)
 
/* ----------------------------------------------------------------------- */
/* Thread budgets */
/*                                                                          */
/* ThreadX priorities run 0 (highest) to TX_MAX_PRIORITIES-1 (lowest), the */
/* opposite sense to FreeRTOS. The values below are already in ThreadX */
/* order, so the port passes them through unchanged. */
/* ----------------------------------------------------------------------- */

#define DFLT_TASK_PRIO (12)

#define DFLT_TASK_STACK_SIZE (4096)

#define RPC_TASK_PRIO (14)

#define RPC_TASK_STACK_SIZE (5120)
 
/* ----------------------------------------------------------------------- */
/* Timers */
/* ----------------------------------------------------------------------- */

#define H_TIMER_TYPE_ONESHOT (1)

#define H_TIMER_TYPE_PERIODIC (2)
 
/* ----------------------------------------------------------------------- */
/* GPIO modes and pulls */
/* ----------------------------------------------------------------------- */

#define H_GPIO_MODE_DEF_INPUT (0)

#define H_GPIO_MODE_DEF_OUTPUT (1)

#define H_GPIO_PULL_UP (0)

#define H_GPIO_PULL_DOWN (1)
 
/* ----------------------------------------------------------------------- */
/* Payload bound */
/* ----------------------------------------------------------------------- */

#define MAX_PAYLOAD_SIZE (MAX_TRANSPORT_BUFFER_SIZE - H_ESP_PAYLOAD_HEADER_OFFSET)
 
/* ----------------------------------------------------------------------- */
/* Placement and linkage attributes */
/* ----------------------------------------------------------------------- */

#define FAST_RAM_ATTR

#define H_IRAM_ATTR

#define H_WEAK_REF [[gnu::weak]]