mmosal.h

/*
 * Copyright 2021-2023 Morse Micro
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#pragma once
 
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
#include "mmport.h"
 
#ifdef __cplusplus
extern "C"
{
#endif
 
typedef void (*mmosal_app_init_cb_t)(void);
 
int mmosal_main(mmosal_app_init_cb_t app_init_cb);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
void *mmosal_malloc_(size_t size);
 
void *mmosal_malloc_dbg(size_t size, const char *name, unsigned line_number);
 
void mmosal_free(void *p);
 
void *mmosal_realloc(void *ptr, size_t size);
 
void *mmosal_calloc(size_t nitems, size_t size);
 
#ifndef MMOSAL_TRACK_ALLOCATIONS
#define mmosal_malloc(size) mmosal_malloc_(size)
#else
/* Note: we use function name because it should be shorter than the full filename path. */
#define mmosal_malloc(size) mmosal_malloc_dbg(size, __func__, __LINE__)
#endif
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
typedef void (*mmosal_task_fn_t)(void *arg);
 
enum mmosal_task_priority
{
    MMOSAL_TASK_PRI_IDLE,
    MMOSAL_TASK_PRI_MIN,
    MMOSAL_TASK_PRI_LOW,
    MMOSAL_TASK_PRI_NORM,
    MMOSAL_TASK_PRI_HIGH,
};
 
struct mmosal_task *mmosal_task_create(mmosal_task_fn_t task_fn,
                                       void *argument,
                                       enum mmosal_task_priority priority,
                                       unsigned stack_size_u32,
                                       const char *name);
 
void mmosal_task_delete(struct mmosal_task *task);
 
struct mmosal_task *mmosal_task_get_active(void);
 
void mmosal_task_yield(void);
 
void mmosal_task_sleep(uint32_t duration_ms);
 
#define MMOSAL_TASK_ENTER_CRITICAL()  \
    do {                              \
        MMPORT_MEM_SYNC();            \
        mmosal_task_enter_critical(); \
    } while (0)
 
#define MMOSAL_TASK_EXIT_CRITICAL()  \
    do {                             \
        MMPORT_MEM_SYNC();           \
        mmosal_task_exit_critical(); \
    } while (0)
 
void mmosal_task_enter_critical(void);
 
void mmosal_task_exit_critical(void);
 
void mmosal_disable_interrupts(void);
 
void mmosal_enable_interrupts(void);
 
const char *mmosal_task_name(void);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
struct mmosal_mutex *mmosal_mutex_create(const char *name);
 
void mmosal_mutex_delete(struct mmosal_mutex *mutex);
 
bool mmosal_mutex_get(struct mmosal_mutex *mutex, uint32_t timeout_ms);
 
bool mmosal_mutex_release(struct mmosal_mutex *mutex);
 
#define MMOSAL_MUTEX_GET_INF(_mutex)                        \
    do {                                                    \
        bool ok__ = mmosal_mutex_get((_mutex), UINT32_MAX); \
        MMOSAL_ASSERT(ok__);                                \
    } while (0)
 
#define MMOSAL_MUTEX_RELEASE(_mutex)              \
    do {                                          \
        bool ok__ = mmosal_mutex_release(_mutex); \
        MMOSAL_ASSERT(ok__);                      \
    } while (0)
 
bool mmosal_mutex_is_held_by_active_task(struct mmosal_mutex *mutex);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
struct mmosal_sem *mmosal_sem_create(unsigned max_count, unsigned initial_count, const char *name);
 
void mmosal_sem_delete(struct mmosal_sem *sem);
 
bool mmosal_sem_give(struct mmosal_sem *sem);
 
bool mmosal_sem_give_from_isr(struct mmosal_sem *sem);
 
bool mmosal_sem_wait(struct mmosal_sem *sem, uint32_t timeout_ms);
 
uint32_t mmosal_sem_get_count(struct mmosal_sem *sem);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
struct mmosal_semb *mmosal_semb_create(const char *name);
 
void mmosal_semb_delete(struct mmosal_semb *semb);
 
bool mmosal_semb_give(struct mmosal_semb *semb);
 
bool mmosal_semb_give_from_isr(struct mmosal_semb *semb);
 
bool mmosal_semb_wait(struct mmosal_semb *semb, uint32_t timeout_ms);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
struct mmosal_queue *mmosal_queue_create(size_t num_items, size_t item_size, const char *name);
 
void mmosal_queue_delete(struct mmosal_queue *queue);
 
bool mmosal_queue_pop(struct mmosal_queue *queue, void *item, uint32_t timeout_ms);
 
bool mmosal_queue_push(struct mmosal_queue *queue, const void *item, uint32_t timeout_ms);
 
bool mmosal_queue_pop_from_isr(struct mmosal_queue *queue, void *item);
 
bool mmosal_queue_push_from_isr(struct mmosal_queue *queue, const void *item);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
uint32_t mmosal_get_time_ms(void);
 
uint32_t mmosal_get_time_ticks(void);
 
uint32_t mmosal_ticks_per_second(void);
 
static inline bool mmosal_time_lt(uint32_t a, uint32_t b)
{
    return ((int32_t)(a - b)) < 0;
}
 
static inline bool mmosal_time_le(uint32_t a, uint32_t b)
{
    return ((int32_t)(a - b)) <= 0;
}
 
static inline uint32_t mmosal_time_max(uint32_t a, uint32_t b)
{
    if (mmosal_time_lt(a, b))
    {
        return b;
    }
    else
    {
        return a;
    }
}
 
static inline bool mmosal_time_has_passed(uint32_t t)
{
    return mmosal_time_le(t, mmosal_get_time_ms());
}
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
struct mmosal_timer;
 
typedef void (*timer_callback_t)(struct mmosal_timer *timer);
 
struct mmosal_timer *mmosal_timer_create(const char *name,
                                         uint32_t timer_period_ms,
                                         bool auto_reload,
                                         void *arg,
                                         timer_callback_t callback);
 
void mmosal_timer_delete(struct mmosal_timer *timer);
 
bool mmosal_timer_start(struct mmosal_timer *timer);
 
bool mmosal_timer_stop(struct mmosal_timer *timer);
 
bool mmosal_timer_change_period(struct mmosal_timer *timer, uint32_t new_period);
 
void *mmosal_timer_get_arg(struct mmosal_timer *timer);
 
bool mmosal_is_timer_active(struct mmosal_timer *timer);
 
/*
 * ---------------------------------------------------------------------------------------------
 */
 
#ifndef MMOSAL_FILEID
#define MMOSAL_FILEID 0
#endif
 
#ifndef MMOSAL_MAX_FAILURE_RECORDS
#define MMOSAL_MAX_FAILURE_RECORDS 4
#endif
 
struct mmosal_failure_info
{
    uint32_t pc;
    uint32_t lr;
    uint32_t fileid;
    uint32_t line;
    uint32_t platform_info[4];
};
 
void mmosal_log_failure_info(const struct mmosal_failure_info *info);
 
#ifdef MMOSAL_NO_DEBUGLOG
#define MMOSAL_LOG_FAILURE_INFO(...)
#else
#define MMOSAL_LOG_FAILURE_INFO(...)          \
    do {                                      \
        void *pc;                             \
        struct mmosal_failure_info info = {   \
            .lr = (uint32_t)MMPORT_GET_LR(),  \
            .fileid = MMOSAL_FILEID,          \
            .line = __LINE__,                 \
            .platform_info = { __VA_ARGS__ }, \
        };                                    \
        MMPORT_GET_PC(pc);                    \
        info.pc = (uint32_t)pc;               \
        mmosal_log_failure_info(&info);       \
    } while (0)
#endif
 
void mmosal_impl_assert(void);
 
/* Note that running with no assertions is untested and not recommended. */
#ifndef MMOSAL_NOASSERT
#ifndef MMOSAL_ASSERT
#define MMOSAL_ASSERT(expr)             \
    do {                                \
        if (!(expr))                    \
        {                               \
            MMOSAL_LOG_FAILURE_INFO(0); \
            mmosal_impl_assert();       \
            while (1)                   \
            {                           \
            }                           \
        }                               \
    } while (0)
#endif
 
#ifndef MMOSAL_ASSERT_LOG_DATA
#define MMOSAL_ASSERT_LOG_DATA(expr, ...)         \
    do {                                          \
        if (!(expr))                              \
        {                                         \
            MMOSAL_LOG_FAILURE_INFO(__VA_ARGS__); \
            mmosal_impl_assert();                 \
            while (1)                             \
            {                                     \
            }                                     \
        }                                         \
    } while (0)
#endif
#else
#define MMOSAL_ASSERT(expr)               (void)(expr)
#define MMOSAL_ASSERT_LOG_DATA(expr, ...) (void)(expr)
#endif
 
#ifdef ENABLE_MMOSAL_DEV_ASSERT
#define MMOSAL_DEV_ASSERT(x) MMOSAL_ASSERT(x)
#define MMOSAL_DEV_ASSERT_LOG_DATA(x, ...) MMOSAL_ASSERT_LOG_DATA(x, __VA_ARGS__)
#else
#define MMOSAL_DEV_ASSERT(x)               ((void)(x))
#define MMOSAL_DEV_ASSERT_LOG_DATA(x, ...) ((void)(x))
#endif
 
#if defined(ENABLE_MANUAL_FAILURE_LOG_PROCESSING) && ENABLE_MANUAL_FAILURE_LOG_PROCESSING
bool mmosal_extract_failure_info(struct mmosal_failure_info *buf, uint32_t *failure_count);
#endif
int mmosal_printf(const char *format, ...);
 
static inline bool mmosal_safer_strcpy(char *dst, const char *src, size_t size)
{
    bool ret;
 
    if (size == 0)
    {
        return true;
    }
 
    strncpy(dst, src, size);
 
    ret = dst[size - 1] != '\0';
    dst[size - 1] = '\0';
    return ret;
}
 
#ifndef MMOSAL_DEPRECATED_API_ENABLED
#define MMOSAL_DEPRECATED_API_ENABLED (1)
#endif
 
#if MMOSAL_DEPRECATED_API_ENABLED
 
void mmosal_task_join(struct mmosal_task *task);
 
bool mmosal_task_wait_for_notification(uint32_t timeout_ms);
 
void mmosal_task_notify(struct mmosal_task *task);
 
void mmosal_task_notify_from_isr(struct mmosal_task *task);
 
#endif
 
#ifdef __cplusplus
}
#endif