LuatOS/luat/include/luat_rtos.h

/*
 * Copyright (c) 2022 OpenLuat & AirM2M
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef LUAT_RTOS_H
#define LUAT_RTOS_H

#include "luat_base.h"
#include "luat_rtos_legacy.h"

/**
 * @defgroup luatos_os  操作系统接口
 * @{
 */

/**
 * @brief LUAT_RTOS 超时时间枚举值
 */
typedef enum LUAT_RTOS_WAIT
{
	LUAT_NO_WAIT = 0,						 /**< 超时时间为0 */
	LUAT_WAIT_FOREVER = (uint32_t)0xFFFFFFFF /**< 最大超时时间0xFFFFFFFF*/
} LUAT_RTOS_WAIT_E;

typedef enum
{
	LUAT_FLAG_AND 		= 5,
	LUAT_FLAG_AND_CLEAR 	= 6,
	LUAT_FLAG_OR 			= 7,
	LUAT_FLAG_OR_CLEAR	= 8
} LUAT_FLAG_OP_E;

/* ------------------------------------------------ task begin------------------------------------------------ */
/**
 * @defgroup  luatos_os_Task 线程任务接口函数
 * @{
 */

/**
 *@brief task的入口函数,函数类型
 */
typedef void (*luat_rtos_task_entry) (void*);
/**
 *@brief 定义task任务句柄
 */
typedef void * luat_rtos_task_handle;
/**
 * @brief 创建一个可以带mailbox机制的task
 * 
 * @param task_handle[OUT] 返回创建的句柄
 * @param stack_size task的栈空间大小，单位byte，必须4字节对齐
 * @param priority 优先级，单位是百分比，0%~100%,100%为最高等级，由具体实现转换到底层SDK用的优先级
 * @param task_name task名字
 * @param task_fun task的入口函数
 * @param user_data task的入口参数
 * @param event_cout =0表示不需要使用mailbox机制，>0表示启用mailbox，可以使用下列event和massage api，同时如果底层SDK不支持mailbox，会创建一个queue模拟mailbox，queue里元素为luat_event_t，数量为event_cout
 * @return int =0成功，其他失败
 */
int luat_rtos_task_create(luat_rtos_task_handle *task_handle, uint32_t stack_size, uint8_t priority, const char *task_name, luat_rtos_task_entry task_fun, void* user_data, uint16_t event_cout);

/**
 * @brief 删除task
 * 
 * @param task_handle 
 * @return int =0成功，其他失败
 */
int luat_rtos_task_delete(luat_rtos_task_handle task_handle);

/**
 * @brief 挂起某个task
 * 
 * @param task_handle task句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_task_suspend(luat_rtos_task_handle task_handle);

/**
 * @brief 恢复挂起的task
 * 
 * @param task_handle task句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_task_resume(luat_rtos_task_handle task_handle);

/**
 * @brief 挂起全部task
 * 
 */
void luat_rtos_task_suspend_all(void);

/**
 * @brief 恢复全部task
 * 
 */
void luat_rtos_task_resume_all(void);

/**
 * @brief task休眠一段时间
 * 
 * @param ms 休眠时间，单位ms
 */
void luat_rtos_task_sleep(uint32_t ms);

/**
 * @brief 获取当前task的句柄
 * 
 * @return luat_rtos_task_handle 当前task的句柄
 */
luat_rtos_task_handle luat_rtos_get_current_handle(void);

/**
 * @brief 获取task堆栈剩余的最小值，叫做“高水位线”
 * 
 * @param luat_rtos_task_handle task的句柄
 * @return task堆栈剩余的最小值,单位为字
 */

uint32_t luat_rtos_task_get_high_water_mark(luat_rtos_task_handle task_handle);

/** @}*/
/* ------------------------------------------------ task   end------------------------------------------------ */
/**
 * @defgroup  luatos_os_event 消息事件函数
 * @{
 */
/* ----------------------------------------------- event begin---------------------------------------------- */
/**
 * @brief 在等待event中，如果设置了目标event id，而到来的不是目标event id，可以通过回调函数交给用户处理
 * 
 */
typedef LUAT_RT_RET_TYPE (*luat_rtos_event_wait_callback_t)(LUAT_RT_CB_PARAM);

/**
 * @brief 发送一个event给task的mailbox，只有设置了mailbox启用的task能接收
 * 
 * @param task_handle 需要接收event的task句柄
 * @param id event id
 * @param param1 event参数1
 * @param param2 event参数2
 * @param param3 event参数3
 * @param timeout 发送超时，在task发送才有，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_event_send(luat_rtos_task_handle task_handle, uint32_t id, uint32_t param1, uint32_t param2, uint32_t param3, uint32_t timeout);

/**
 * @brief 接收一个event，只能在task里接收
 * 
 * @param task_handle 需要接收event的task句柄
 * @param wait_event_id 目标event的ID，=0表示不限制，任意event id都会返回
 * @param out_event[OUT] 接收到的event
 * @param callback_fun event的ID不是目标ID时，用户回调函数，可以为NULL，从而抛弃掉这个event
 * @param timeout 接收超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_event_recv(luat_rtos_task_handle task_handle, uint32_t wait_event_id, luat_event_t *out_event, luat_rtos_event_wait_callback_t *callback_fun, uint32_t timeout);

/* ----------------------------------------------- event end---------------------------------------------- */

/* ----------------------------------------------- message begin---------------------------------------------- */
/**
 * @brief 发送一个message给task的mailbox，只有设置了mailbox启用的task能接收，message可以动态创建的，可以任意大小
 * 
 * @param task_handle 需要接收massage的task句柄
 * @param message_id message id
 * @param p_message message内容，传入指针，如果动态创建，需要在接收时释放
 * @return int =0成功，其他失败
 */
int luat_rtos_message_send(luat_rtos_task_handle task_handle, uint32_t message_id, void *p_message);

/**
 * @brief 接收一个message，只能在task里接收
 * 
 * @param task_handle 需要接收massage的task句柄
 * @param message_id[OUT] 接收到的message id
 * @param p_p_message[OUT] message内容，输出一个void *指针，如果是发送时动态创建的，需要释放掉
 * @param timeout 接收超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_message_recv(luat_rtos_task_handle task_handle, uint32_t *message_id, void **p_p_message, uint32_t timeout);
/** @}*/

/* ----------------------------------------------- message   end---------------------------------------------- */

/**
 * @defgroup  luatos_os_semaphore 信号量接口函数
 * @{
 */

/* ---------------------------------------------- semaphore begin--------------------------------------------- */
/**
 * @brief 定义信号量句柄
 */
typedef void * luat_rtos_semaphore_t;
/**
 * @brief 信号量创建，可以在中断中release
 * 
 * @param semaphore_handle[OUT] 信号量句柄
 * @param init_count 初始值
 * @return int =0成功，其他失败
 */
int luat_rtos_semaphore_create(luat_rtos_semaphore_t *semaphore_handle, uint32_t init_count);

/**
 * @brief 删除信号量
 * 
 * @param semaphore_handle 信号量句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_semaphore_delete(luat_rtos_semaphore_t semaphore_handle);

/**
 * @brief 信号量等待获取
 * 
 * @param semaphore_handle 信号量句柄
 * @param timeout 接收超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_semaphore_take(luat_rtos_semaphore_t semaphore_handle, uint32_t timeout);

/**
 * @brief 信号量释放发送
 * 
 * @param semaphore_handle 信号量句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_semaphore_release(luat_rtos_semaphore_t semaphore_handle);
/* ---------------------------------------------- semaphore   end--------------------------------------------- */
/** @}*/

/**
 * @defgroup  luatos_os_mutex 互斥锁接口函数
 * @{
 */
/* ------------------------------------------------ mutex begin----------------------------------------------- */
/**
 * @brief 定义mutex句柄
 */
typedef void * luat_rtos_mutex_t;
/**
 * @brief 互斥锁创建，不能在中断中unlock
 * 
 * @param mutex_handle[OUT] 互斥锁句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_mutex_create(luat_rtos_mutex_t *mutex_handle);

/**
 * @brief 获得锁
 * 
 * @param mutex_handle 互斥锁句柄
 * @param timeout 超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_mutex_lock(luat_rtos_mutex_t mutex_handle, uint32_t timeout);

/**
 * @brief 释放锁
 * 
 * @param mutex_handle 互斥锁句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_mutex_unlock(luat_rtos_mutex_t mutex_handle);

/**
 * @brief 删除互斥锁
 * 
 * @param mutex_handle 互斥锁句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_mutex_delete(luat_rtos_mutex_t mutex_handle);

/* ------------------------------------------------ mutex   end----------------------------------------------- */
/** @}*/

/**
 * @defgroup  luatos_os_queue 队列接口函数
 * @{
 */
/* ------------------------------------------------ queue begin----------------------------------------------- */

/**
 * @brief 定义队列句柄
 */
typedef void * luat_rtos_queue_t;
/**
 * @brief 创建队列
 * 
 * @param queue_handle[OUT] 返回的队列句柄
 * @param msgcount 队列里元素的最大数量
 * @param msgsize 队列里单个元素的大小
 * @return int =0成功，其他失败
 */
int luat_rtos_queue_create(luat_rtos_queue_t *queue_handle, uint32_t item_count, uint32_t item_size);

/**
 * @brief 删除队列
 * 
 * @param queue_handle 队列句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_queue_delete(luat_rtos_queue_t queue_handle);

/**
 * @brief 往队列里发送一个元素
 * 
 * @param queue_handle 队列句柄
 * @param item 元素指针
 * @param item_size 元素大小，这个是兼容性参数，实际上必须于创建时的item_size一致，所以忽略
 * @param timeout 超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_queue_send(luat_rtos_queue_t queue_handle, void *item, uint32_t item_size, uint32_t timeout);

/**
 * @brief 从队列里取出一个元素
 * 
 * @param queue_handle 队列句柄
 * @param item 元素指针
 * @param item_size 元素大小，这个是兼容性参数，实际上必须于创建时的item_size一致，所以忽略
 * @param timeout 超时，单位ms，特殊值见LUAT_RTOS_WAIT_E
 * @return int =0成功，其他失败
 */
int luat_rtos_queue_recv(luat_rtos_queue_t queue_handle, void *item, uint32_t item_size, uint32_t timeout);

/**
 * @brief 查询队列中剩余未处理的元素数量
 * 
 * @param queue_handle 队列句柄
 * @param item_cnt[OUT] 返回未处理的元素数量
 * @return int =0成功，其他失败
 */
int luat_rtos_queue_get_cnt(luat_rtos_queue_t queue_handle, uint32_t *item_cnt);
/* ------------------------------------------------ queue   end----------------------------------------------- */
/** @}*/

/**
 * @defgroup  luatos_os_flag 事件接口函数
 * @{
 */
/* ------------------------------------------------ flag begin----------------------------------------------- */

/**
 * @brief 定义事件句柄
 */
typedef void * luat_rtos_flag_t;
/**
 * @brief 创建事件
 *
 * @param flag_handle[OUT] 返回的事件句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_flag_create(luat_rtos_flag_t	*flag_handle);
/**
 * @brief 等待事件
 * @param mask 等待的事件掩码
 * @param operation 事件触发要求（与操作需要全部满足才触发，或操作有一个就触发）和操作（是否要清除）
 * @param flags[OUT] 当前事件状态值
 * @param timeout 超时时间
 * @return int =0成功，其他失败
 */
int luat_rtos_flag_wait(luat_rtos_flag_t flag_handle, uint32_t mask, LUAT_FLAG_OP_E	operation, uint32_t *flags,uint32_t timeout);
/**
 * @brief 设置事件
 * @param flag_handle 事件句柄
 * @param mask 设置掩码
 * @param operation 事件判断（与或）和操作（是否要清除），freertos支持或操作LUAT_FLAG_OR
 * @return int =0成功，其他失败
 */
int luat_rtos_flag_release(luat_rtos_flag_t	flag_handle, uint32_t mask, LUAT_FLAG_OP_E operation);
/**
 * @brief 删除事件
 *
 * @param flag_handle 事件句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_flag_delete(luat_rtos_flag_t flag_handle);
/* ------------------------------------------------ flag  end----------------------------------------------- */
/** @}*/

/**
 * @defgroup  luatos_os_timer 软件定时器接口函数
 * @{
 */

/* ------------------------------------------------ timer begin----------------------------------------------- */
/**
 * @brief 定时器头数据类型
 */
typedef void * luat_rtos_timer_t;
/**
 * @brief 定义定时器处理函数
 */
typedef LUAT_RT_RET_TYPE (*luat_rtos_timer_callback_t)(LUAT_RT_CB_PARAM);
/**
 * @brief 创建软件定时器
 * 
 * @param timer_handle[OUT] 返回定时器句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_timer_create(luat_rtos_timer_t *timer_handle);

/**
 * @brief 删除软件定时器
 * 
 * @param timer_handle 定时器句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_timer_delete(luat_rtos_timer_t timer_handle);

/**
 * @brief 启动软件定时器
 * 
 * @param timer_handle 定时器句柄
 * @param timeout 超时时间，单位ms，没有特殊值
 * @param repeat 0不重复，其他重复
 * @param callback_fun 定时时间到后的回调函数
 * @param user_param 回调函数时的最后一个输入参数
 * @return int =0成功，其他失败
 */
int luat_rtos_timer_start(luat_rtos_timer_t timer_handle, uint32_t timeout, uint8_t repeat, luat_rtos_timer_callback_t callback_fun, void *user_param);

/**
 * @brief 停止软件定时器
 * 
 * @param timer_handle 定时器句柄
 * @return int =0成功，其他失败
 */
int luat_rtos_timer_stop(luat_rtos_timer_t timer_handle);

/**
 * @brief 检测软件定时器是否处于激活状态
 * 
 * @param timer_handle 定时器句柄
 * @return int =0未激活，1激活，其他失败
 */
int luat_rtos_timer_is_active(luat_rtos_timer_t timer_handle);

/*------------------------------------------------ timer   end----------------------------------------------- */
/** @}*/

/**
 * @defgroup  luatos_os_critical 临界保护接口函数
 * @{
 */

/* ------------------------------------------------ critical begin----------------------------------------------- */
/**
 * @brief 进入临界保护
 * 
 * @return uint32_t 退出临界保护所需参数
 */
uint32_t luat_rtos_entry_critical(void);

/**
 * @brief 退出临界保护
 * 
 * @param critical 进入临界保护时返回的参数
 */
void luat_rtos_exit_critical(uint32_t critical);

uint32_t luat_rtos_get_ipsr(void);
/*------------------------------------------------ critical   end----------------------------------------------- */
/** @}*/
/** @}*/
#endif