From 7d8fa7f23240e1d612633ea45440f17ca348eea1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B6=E4=B8=AD=E6=96=AD=E5=BB=B6=E8=BF=9F=E7=9A=84RTOS?= Date: Tue, 3 Feb 2026 07:05:55 +0000 Subject: [PATCH] =?UTF-8?q?update=20=E5=86=85=E6=A0=B8=E6=96=87=E4=BB=B6.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 零中断延迟的RTOS --- System/sv_create.h | 288 +++++++ System/ur_api.h | 1967 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 2255 insertions(+) create mode 100644 System/sv_create.h create mode 100644 System/ur_api.h diff --git a/System/sv_create.h b/System/sv_create.h new file mode 100644 index 0000000..5ca70c3 --- /dev/null +++ b/System/sv_create.h @@ -0,0 +1,288 @@ +/**************************************************************************//** + * @item CosyOS-III Kernel + * @file sv_create.h + * @brief 创建服务 + * @details 用于创建 CosyOS 内核对象。 + * @author 迟凯峰 + * @version V2.3.0 + * @date 2026.02.01 + ******************************************************************************/ + +#ifndef __SV_CREATE_H +#define __SV_CREATE_H + +/** + @addtogroup CosyOS_内核服务 + @{ + *//** + \defgroup 创建服务 + \brief 用于创建 CosyOS 内核对象。 + @{ + */ + +/* + * 声明任务 + */ + +/** 简化声明静态任务 */ +#define sCSV_ExtTask(name) \ + extern s_tasknode_ts u_taskhand_##name; \ + void u_task_##name + +/** 简化声明动态任务 */ +#define dCSV_ExtTask(name) \ + extern s_taskhand_ts u_taskhand_##name; \ + void u_task_##name + +/** 完整声明静态任务 */ +#define sCSV_ExternTask(name) \ + extern s_tasknode_tsp name; \ + sCSV_ExtTask(name) + +/** 完整声明动态任务 */ +#define dCSV_ExternTask(name) \ + extern s_tasknode_tsp name; \ + dCSV_ExtTask(name) + + +/* + * 创建任务 + */ + +#if (SYSCFG_DEBUGGING == __ENABLED__) + #if (SYSCFG_SAFERUNTIME == __ENABLED__) + /** 静态创建，启用 DEBUGGING，启用 安全运行时 */ + #define sCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_tasknode_ts u_taskhand_##name = {0, pri, tss, &name, ety, res, srt, u_taskstack_##name, 0} + #else /** 静态创建，启用 DEBUGGING，禁用 安全运行时 */ + #define sCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_tasknode_ts u_taskhand_##name = {0, pri, tss, &name, ety, res, u_taskstack_##name, 0} + #endif +#else + #if (SYSCFG_SAFERUNTIME == __ENABLED__) + /** 静态创建，禁用 DEBUGGING，启用 安全运行时 */ + #define sCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_tasknode_ts u_taskhand_##name = {0, pri, tss, &name, ety, srt, u_taskstack_##name, 0} + #else /** 静态创建，禁用 DEBUGGING，禁用 安全运行时 */ + #define sCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_tasknode_ts u_taskhand_##name = {0, pri, tss, &name, ety, u_taskstack_##name, 0} + #endif +#endif +#if (SYSCFG_DEBUGGING == __ENABLED__) + #if (SYSCFG_SAFERUNTIME == __ENABLED__) + /** 动态创建，启用 DEBUGGING，启用 安全运行时 */ + #define dCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_taskhand_ts u_taskhand_##name = {0, pri, tss, &name, ety, res, srt} + #else /** 动态创建，启用 DEBUGGING，禁用 安全运行时 */ + #define dCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_taskhand_ts u_taskhand_##name = {0, pri, tss, &name, ety, res} + #endif +#else + #if (SYSCFG_SAFERUNTIME == __ENABLED__) + /** 动态创建，禁用 DEBUGGING，启用 安全运行时 */ + #define dCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_taskhand_ts u_taskhand_##name = {0, pri, tss, &name, ety, srt} + #else /** 动态创建，禁用 DEBUGGING，禁用 安全运行时 */ + #define dCSV_CreateTask_0(name, pri, tss, srt, res, ety) \ + s_taskhand_ts u_taskhand_##name = {0, pri, tss, &name, ety} + #endif +#endif + +/** 静态创建一般任务 */ +#define sCSV_CreateTask(name, pri, tss, srt, res) \ + void u_task_##name(void); \ + s_tasknode_ts u_taskhand_##name; \ + s_tasknode_tsp name = &u_taskhand_##name; \ + MCUCFG_STACK_ALIGN static s_u8_t u_taskstack_##name[tss]; \ + sCSV_CreateTask_0(name, pri, tss, srt, res, u_task_##name); \ + void u_task_##name(void) MCUCFG_TASK_ATTRIBUTE + +/** 动态创建一般任务 */ +#define dCSV_CreateTask(name, pri, tss, srt, res) \ + void u_task_##name(void); \ + s_tasknode_tsp name = OS_NULL; \ + dCSV_CreateTask_0(name, pri, tss, srt, res, u_task_##name); \ + void u_task_##name(void) MCUCFG_TASK_ATTRIBUTE + +/** 静态创建私信任务 */ +#define sCSV_CreateTaskmsg(name, pri, tss, srt, res, ntm) \ + s_tasknode_ts u_taskhand_##name; \ + s_tasknode_tsp name = &u_taskhand_##name; \ + MCUCFG_STACK_ALIGN static s_u8_t u_taskstack_##name[tss]; \ + sCSV_CreateTask_0(name, pri, tss, srt, res, OS_NULL); \ + void u_task_##name sCreateTaskMsg_##ntm + +/** 动态创建私信任务 */ +#define dCSV_CreateTaskmsg(name, pri, tss, srt, res, ntm) \ + s_tasknode_tsp name = OS_NULL; \ + dCSV_CreateTask_0(name, pri, tss, srt, res, OS_NULL); \ + void u_task_##name sCreateTaskMsg_##ntm + +/** for 定时任务 */ +#if defined ( __GNUC__ ) +#define s_hookorhand_hand(p) .hand=(s_taskhand_tsp)p +#define s_hookorhand_hook(p) .hook=p +#else +#define s_hookorhand_hand(p) (s_voidvoid_tfp)p +#define s_hookorhand_hook(p) p +#endif +#define OS_TIMQRYINIT (s_timqry_t)(SYSCFG_USERTIMQRYINIT - 1) /*!< 定时查询初始值 */ + +/** 静态创建定时中断任务 */ +#define sCSV_CreateTask_TimInt(tmid, arl, name, pri, tss, srt, res) \ + s_tasknode_ts u_taskhand_##name; \ + s_timinthand_ts _STATIC_MEM_ u_timinthand_##tmid = {0, 0, arl, 1, {s_hookorhand_hand(&u_taskhand_##name)}}; \ + sCSV_CreateTask(name, pri, tss, srt, res) + +/** 动态创建定时中断任务 */ +#define dCSV_CreateTask_TimInt(tmid, arl, name, pri, tss, srt, res) \ + s_taskhand_ts u_taskhand_##name; \ + s_timinthand_ts _STATIC_MEM_ u_timinthand_##tmid = {0, 0, arl, 1, {s_hookorhand_hand(&u_taskhand_##name)}}; \ + dCSV_CreateTask(name, pri, tss, srt, res) + +/** 静态创建定时查询任务 */ +#define sCSV_CreateTask_TimQry(tmid, event, arl, name, pri, tss, srt, res) \ + bool u_timqryevent_##tmid(void) MCUCFG_OSIT_ATTRIBUTE {return (event ? true : false);} \ + s_tasknode_ts u_taskhand_##name; \ + s_timqryhand_ts _STATIC_MEM_ u_timqryhand_##tmid = {OS_TIMQRYINIT, OS_TIMQRYINIT, arl, 1, {s_hookorhand_hand(&u_taskhand_##name)}, u_timqryevent_##tmid}; \ + sCSV_CreateTask(name, pri, tss, srt, res) + +/** 动态创建定时查询任务 */ +#define dCSV_CreateTask_TimQry(tmid, event, arl, name, pri, tss, srt, res) \ + bool u_timqryevent_##tmid(void) MCUCFG_OSIT_ATTRIBUTE {return (event ? true : false);} \ + s_taskhand_ts u_taskhand_##name; \ + s_timqryhand_ts _STATIC_MEM_ u_timqryhand_##tmid = {OS_TIMQRYINIT, OS_TIMQRYINIT, arl, 1, {s_hookorhand_hand(&u_taskhand_##name)}, u_timqryevent_##tmid}; \ + dCSV_CreateTask(name, pri, tss, srt, res) + + +/* + * 创建钩子 + */ + +/** 创建定时中断钩子 */ +#define sCSV_CreateHook_TimInt(tmid, arl) \ + void u_timint_##tmid(void); \ + s_timinthand_ts _STATIC_MEM_ u_timinthand_##tmid = {0, 0, arl, 0, {s_hookorhand_hook(u_timint_##tmid)}}; \ + void u_timint_##tmid(void) MCUCFG_OSIT_ATTRIBUTE + +/** 创建定时查询钩子 */ +#define sCSV_CreateHook_TimQry(tmid, event, arl) \ + void u_timqry_##tmid(void); \ + bool u_timqryevent_##tmid(void) MCUCFG_OSIT_ATTRIBUTE {return (event ? true : false);} \ + s_timqryhand_ts _STATIC_MEM_ u_timqryhand_##tmid = {OS_TIMQRYINIT, OS_TIMQRYINIT, arl, 0, {s_hookorhand_hook(u_timqry_##tmid)}, u_timqryevent_##tmid}; \ + void u_timqry_##tmid(void) MCUCFG_OSIT_ATTRIBUTE + + +/* + * 互斥信号量 + */ + +/** 声明互斥信号量 */ +#define sCSV_ExternMut(name) \ + extern s_mutex_ts name + +/** 创建互斥信号量 */ +#define sCSV_CreateMut(name) \ + s_mutex_ts name/**/sZeroInstall_Group + + +/* + * 二值信号量 + */ + +/** 声明二值信号量 */ +#define sCSV_ExternBin(name) \ + extern s_binary_ts name + +/** 创建二值信号量 */ +#define sCSV_CreateBin(name, init) \ + s_binary_ts name = {OS_NULL, init} + + +/* + * 计数信号量 + */ + +/** 声明计数信号量 */ +#define sCSV_ExternSem(name) \ + extern s_semaph_ts name + +/** 创建计数信号量 */ +#define sCSV_CreateSem(name, init, max) \ + s_semaph_ts name = {OS_NULL, init, max} + + +/* + * 飞信 + */ + +/** 声明信箱 */ +#define sCSV_ExternTionbox(name) \ + extern s_tionbox_ts name + +/** 创建信箱 */ +#define sCSV_CreateTionbox(name) \ + s_tionbox_ts name/**/sZeroInstall_Group + + +/* + * 邮箱 + */ + +/** 声明邮箱 */ +#define sCSV_ExternMailbox(name) \ + extern s_mailbox_ts name + +/** 创建邮箱 */ +#define sCSV_CreateMailbox(name) \ + s_mailbox_ts name/**/sZeroInstall_Group + + +/* + * 消息队列 + */ + +/** 声明静态队列 */ +#define sCSV_ExternQueue_Static(name) \ + extern s_staque_ts name + +/** 声明动态队列 */ +#define sCSV_ExternQueue_Dynamic(name) \ + extern s_dynque_ts name + +/** 创建静态队列 */ +#define sCSV_CreateQueue_Static(name, mode, len) \ + void *u_queue_##name[len]; \ + s_staque_ts name = {OS_NULL, true, 0, __STATIC__, mode, len, u_queue_##name, u_queue_##name + len - 1, u_queue_##name} + +/** 创建动态队列 */ +#define sCSV_CreateQueue_Dynamic(name, mode, len) \ + s_dynque_ts name = {OS_NULL, true, 0, __DYNAMIC__, mode, len, OS_NULL, OS_NULL} + + +/* + * 事件标志组（必须声明） + */ + +/** 声明标志组 */ +#define sCSV_ExternFlagGroup(name, bits) \ + typedef struct{bits}u_##name##_ts; \ + extern volatile u_##name##_ts name + +/** 创建标志组 */ +#define sCSV_CreateFlagGroup(name) \ + volatile u_##name##_ts name + + +/* + * 线程内存 + */ + +/** 创建线程内存池 */ +#define sCSV_CreateMempool() \ + static s_thrmem_ts u_thrmem/**/sZeroInstall_Group + +/** @} */ +/** @} */ + +#endif diff --git a/System/ur_api.h b/System/ur_api.h new file mode 100644 index 0000000..da6136d --- /dev/null +++ b/System/ur_api.h @@ -0,0 +1,1967 @@ +/**************************************************************************//** + * @item CosyOS-III Kernel + * @file ur_api.h + * @brief 用户API + * @details 用户API定义，含注释说明，所有内核服务的API说明均在此文件中，并支持doxygen。 + * @author 迟凯峰 + * @version V2.3.0 + * @date 2026.02.01 + ******************************************************************************/ + +#ifndef __UR_API_H +#define __UR_API_H + +#include "os_redef.h" + +/** + \page CosyOS_API_DESCRIBE 概述：API说明 + 用户通过调用API来实现对系统服务的调用，所有API均为宏定义，所有API参数均支持宏定义。 + +
+ + \li API分类 + + \li 创建API
+ 静态创建：前缀为“u”，分为 声明对象（uExtern）、创建对象（uCreate）、定义对象（uDef）。
+ 动态创建：前缀为“d”，分为 声明对象（dExtern）、创建对象（dCreate）。 + + \li 任务API
+ 前缀为“u”，指仅在 任务 中调用。 + + \li 滴答API
+ 前缀为“t”，指仅在 SysTick中断 中调用，包括在 滴答钩子（tick_hook）、
+ 定时中断钩子（u_timint_##tmid）、定时查询钩子（u_timqry_##tmid）、
+ 定时查询事件（u_timqryevent_##tmid）中调用。 + + \li PSVAPI
+ 前缀为“p”，指仅在 PendSV中断 中调用，包括通过挂起服务调用（iPendSVC）间接调用、
+ 在挂起服务钩子（pendsv_hook）中调用。 + + \li 中断API
+ 前缀为“i”，指仅在 用户中断 中调用，包括 中断本地服务、中断挂起服务_FIFO。 + + \li 公共API
+ 前缀为“x”，指可在 任意处 调用。 + +
+ + \li API返回 + + \li 无返回
+ （1）服务的执行结果一定是成功的，所以不需要返回。
+ （2）所有中断挂起服务_FIFO均无法直接返回，但其中的部分服务允许支持错误调用返回。 + + \li 返回错误码
+ 服务的执行结果可能会失败，导致失败的原因可能有多个。
+ （1）无错误。
+ （2）由于结果已经成功，导致本次并未执行。
+ （3）失败。 + + \li 返回结果
+ 服务的执行结果可能会失败，但导致失败的原因是唯一的。
+ 执行结果为 bool 类型，true 为成功，false 为失败。 + + \li 返回指针
+ 返回一个指针，(void *) 类型，NULL 为失败。 + + \li 返回值
+ 返回一个数值，特定的数据类型，0 为失败。 + +
+ + \li 名词解释 + + \li 无限阻塞
+ 阻塞时间为无限长。 + + \li 无限等待
+ 超时时间为无限长。 + + \li 无限延时
+ 延时时间为无限长。 + + \li 无限同步
+ 仅同步一次，事件处理线程便可不限次数的周期运行处理事件。
+ 仅二值信号量支持该功能，可通过上锁的方式来终止无限同步。 + +
+ */ + +/** + \defgroup CosyOS_用户API + @{ + */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 构建系统 + \brief 系统构建相关服务。 + @{ + */ + +/** + \brief 启动-CosyOS + \param 无 + \return 错误码 + \note 用户应自主创建main函数，并在其末尾处调用该函数来启动-CosyOS；
+ 在正常情况下，该函数并不会返回，而是直接调度至 Starter 运行；
+ 只有在 Sysidle / Starter 启动失败时，才会返回错误码提示用户。 + */ +s_ecode_t uStartCosyOS(void); + +/** + \brief CosyOS-滴答 + \param 无 + \return 无 + \note 对于Arm用户来说，您应自主创建 SysTick_Handler()，并在其中调用该服务。 + \warning 对于51/251用户来说，系统滴答中断固定采用定时器0中断，并由CosyOS托管，
+ 您应屏蔽掉工程中原有的定时器0中断函数以避免冲突。 + */ +void tCosyTick_Handler(void); + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 任务 + \brief 任务线程的声明、创建、启动，及操作。 + @{ + */ + +/** + \ingroup 任务 + \defgroup 声明任务 + \brief 任务线程的声明 + \note 首先，声明任务不一定是必须的，当仅在一个c文件中启动、操作任务时，时常并不需要声明。 + \note 在声明任务时，通常无论是在h文件中声明还是在c文件中声明，都应采用完整声明方式，
+ 只有在编译器发出警告，与该任务相关的全局变量未引用时，再考虑简化声明方式。
+ 通常这种情况并不会发生，典型的是在使用GCC(GNU)编译器时，可能偶尔会出现这种警告。 + @{ + */ + +/** + \brief 简化声明静态一般任务 + \param[in] task 任务名称 + \return 无 + */ +#define uExtTask(task) sCSV_ExtTask(task)(void) + +/** + \brief 简化声明动态一般任务 + \param[in] task 任务名称 + \return 无 + */ +#define dExtTask(task) dCSV_ExtTask(task)(void) + +/** + \brief 完整声明静态一般任务 + \param[in] task 任务名称 + \return 无 + */ +#define uExternTask(task) sCSV_ExternTask(task)(void) + +/** + \brief 完整声明动态一般任务 + \param[in] task 任务名称 + \return 无 + */ +#define dExternTask(task) dCSV_ExternTask(task)(void) + +/** + \brief 简化声明静态私信任务 + \param[in] task 任务名称 + \param[in] add(...) 附加私信形参 + \return 无 + */ +#define uExtTaskmsg(task) sCSV_ExtTask(task) + +/** + \brief 简化声明动态私信任务 + \param[in] task 任务名称 + \param[in] add(...) 附加私信形参 + \return 无 + */ +#define dExtTaskmsg(task) dCSV_ExtTask(task) + +/** + \brief 完整声明静态私信任务 + \param[in] task 任务名称 + \param[in] add(...) 附加私信形参 + \return 无 + */ +#define uExternTaskmsg(task) sCSV_ExternTask(task) + +/** + \brief 完整声明动态私信任务 + \param[in] task 任务名称 + \param[in] add(...) 附加私信形参 + \return 无 + */ +#define dExternTaskmsg(task) dCSV_ExternTask(task) + +/** @} */ + +/** + \ingroup 任务 + \defgroup 创建任务 + \brief 任务线程的创建 + @{ + */ + +/** + \brief 静态创建一般任务 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define uCreateTask(task, pri, tss, srt, res) \ + sCSV_CreateTask(task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** + \brief 动态创建一般任务 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define dCreateTask(task, pri, tss, srt, res) \ + dCSV_CreateTask(task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** + \brief 静态创建私信任务 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] ntm 私信参数数量（1~8 个） + \param[in] add(...) 附加私信形参
+ 形参类型：任意数据类型
+ 形参名称：必须依次为 tm1、tm2...
+ 示 例：(int tm1, float tm2, char *tm3) + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define uCreateTaskmsg(task, pri, tss, srt, res, ntm) \ + sCSV_CreateTaskmsg(task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res), ntm) + +/** + \brief 动态创建私信任务 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] ntm 私信参数数量（1~8 个） + \param[in] add(...) 附加私信形参
+ 形参类型：任意数据类型
+ 形参名称：必须依次为 tm1、tm2...
+ 示 例：(int tm1, float tm2, char *tm3) + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define dCreateTaskmsg(task, pri, tss, srt, res, ntm) \ + dCSV_CreateTaskmsg(task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res), ntm) + +/** + \brief 静态创建定时中断任务 + \param[in] tmid 定时中断定时器ID + \param[in] arl 自动重装载 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define uCreateTask_TimInt(tmid, arl, task, pri, tss, srt, res) \ + sCSV_CreateTask_TimInt(tmid, arl, task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** + \brief 动态创建定时中断任务 + \param[in] tmid 定时中断定时器ID + \param[in] arl 自动重装载 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define dCreateTask_TimInt(tmid, arl, task, pri, tss, srt, res) \ + dCSV_CreateTask_TimInt(tmid, arl, task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** + \brief 静态创建定时查询任务 + \param[in] tmid 定时查询定时器ID + \param[in] event 定时查询事件 + \param[in] arl 自动重装载 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define uCreateTask_TimQry(tmid, event, arl, task, pri, tss, srt, res) \ + sCSV_CreateTask_TimQry(tmid, event, arl, task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** + \brief 动态创建定时查询任务 + \param[in] tmid 定时查询定时器ID + \param[in] event 定时查询事件 + \param[in] arl 自动重装载 + \param[in] task 任务名称 + \param[in] pri 任务优先级 + \param[in] tss 任务栈大小（单位为字节） + \param[in] srt 安全运行时（单位为滴答周期，0为无限长） + \param[in] res 任务名称文本 + \param[in] add{...} 附加任务代码 + \return 无 + */ +#define dCreateTask_TimQry(tmid, event, arl, task, pri, tss, srt, res) \ + dCSV_CreateTask_TimQry(tmid, event, arl, task, pri, tss, srt, SYSCFG_CREATETASKCUSTOM(task, res)) + +/** @} */ + +/** + \ingroup 任务 + \defgroup 启动任务 + \brief 任务线程的启动。任务只有在启动以后，才能加入到任务队列参与调度并运行。 + \warning 所有定时中断任务和定时查询任务均由操作系统自动启动，用户不要启动。 + \warning 不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + @{ + */ + +/** + \brief 启动任务 + \details 启动任务并置任务的初始状态为设定状态。 + \param[in] task 任务名称 + \param[in] status 任务初始状态
+ 就绪状态：OS_STATUS_READY
+ 阻塞状态：OS_STATUS_BLOCKED，阻塞类型为延时阻塞，延时时间为无限长。
+ 挂起状态：OS_STATUS_SUSPENDED，先前状态为就绪状态。 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_OVERFLOW_TASKSTACK 任务栈溢出 + \retval OS_ECODE_MALLOCFAIL_TASKNODE 任务节点内存分配失败 + \retval OS_ECODE_MALLOCFAIL_TASKSTACK 任务栈内存分配失败 + */ +#if (SYSCFG_TASKMSG == __ENABLED__) +#define uStartTask(task, status) \ + sUSV_StartTask_1(&sCat2Str(u_taskhand_, task), status, sCat2Str(u_task_, task)) +#else +#define uStartTask(task, status) \ + sUSV_StartTask_0(&sCat2Str(u_taskhand_, task), status) +#endif + +/** + \brief 启动任务并就绪 + \details 启动任务并置任务的初始状态为就绪状态。 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_OVERFLOW_TASKSTACK 任务栈溢出 + \retval OS_ECODE_MALLOCFAIL_TASKNODE 任务节点内存分配失败 + \retval OS_ECODE_MALLOCFAIL_TASKSTACK 任务栈内存分配失败 + */ +#define uStartTask_Ready(task) \ + uStartTask(task, OS_STATUS_READY) + +/** + \brief 启动任务并阻塞 + \details 启动任务并置任务的初始状态为阻塞状态（阻塞类型为延时阻塞，延时时间为无限长）。 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_OVERFLOW_TASKSTACK 任务栈溢出 + \retval OS_ECODE_MALLOCFAIL_TASKNODE 任务节点内存分配失败 + \retval OS_ECODE_MALLOCFAIL_TASKSTACK 任务栈内存分配失败 + */ +#define uStartTask_Block(task) \ + uStartTask(task, OS_STATUS_BLOCKED) + +/** + \brief 启动任务并挂起 + \details 启动任务并置任务的初始状态为挂起状态（先前状态为就绪状态）。 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_OVERFLOW_TASKSTACK 任务栈溢出 + \retval OS_ECODE_MALLOCFAIL_TASKNODE 任务节点内存分配失败 + \retval OS_ECODE_MALLOCFAIL_TASKSTACK 任务栈内存分配失败 + */ +#define uStartTask_Suspend(task) \ + uStartTask(task, OS_STATUS_SUSPENDED) + +/** @} */ + +/** + \ingroup 任务 + \defgroup 操作任务 + \brief 对任意任务的操作，如 恢复、挂起、删除、设置优先级 等。 + @{ + */ + +/** + \brief 清除就绪延时 + \details 清除当前任务的就绪延时，前提是当前任务已在就绪延时中。 + \param 无 + \return 无 + \note 同型服务：
+ pClearDelay()。
+ iClearDelay()。 + */ +#define tClearDelay() sTSV_ClearDelay() + +/** + \brief 恢复任务 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTSUSPENDED 任务未挂起 + \retval OS_ECODE_TASKSTOPPED 任务已停止 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tResumeTask(task)，同返回。
+ pResumeTask(task)，同返回。
+ iResumeTask(task)，无返回/错误调用返回。 + */ +#define uResumeTask(task) sUSV_ResumeTask(task) + +/** + \brief 挂起任务 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKSUSPENDED 任务已挂起 + \retval OS_ECODE_TASKSTOPPED 任务已停止 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSuspendTask(task)，同返回。
+ pSuspendTask(task)，同返回。
+ iSuspendTask(task)，无返回/错误调用返回。 + */ +#define uSuspendTask(task) sUSV_SuspendTask(task) + +/** + \brief 删除任务 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tDeleteTask(task)，同返回。
+ pDeleteTask(task)，同返回。
+ iDeleteTask(task)，无返回/错误调用返回。 + */ +#define uDeleteTask(task) sUSV_DeleteTask(task) + +/** + \brief 设置任务优先级 + \param[in] task 任务名称 + \param[in] npri 新优先级 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKPRIUNCHANGED 任务优先级未改变 + \retval OS_ECODE_TASKSTOPPED 任务已停止 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetTaskPri(task, npri)，同返回。
+ pSetTaskPri(task, npri)，同返回。
+ iSetTaskPri(task, npri)，无返回/错误调用返回。 + */ +#define uSetTaskPri(task, npri) sUSV_SetTaskPri(task, npri) + +/** + \brief 清除阻塞（状态） + \details 清除指定任务的阻塞状态并使其就绪。 + \param[in] task 任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tClearBlock(task)，同返回。
+ pClearBlock(task)，同返回。
+ iClearBlock(task)，无返回/错误调用返回。 + */ +#define uClearBlock(task) sUSV_ClearBlock(task) + +/** + \ingroup 操作任务 + \defgroup 设置阻塞（时间） + \brief 设置、修改指定任务的阻塞时间，前提是该任务当前已为阻塞状态。 + \note 理想误差：-1tick。 + \warning 按 毫秒、秒钟、分钟、小时 设置，用户需自己保证时间的有效性（可被系统滴答周期整除）。 + \warning 无限阻塞，仅能通过调用 xSetBlock_tc(task, ~0) 来实现。 + @{ + */ + +/** + \brief 设置阻塞-滴答周期 + \param[in] task 任务名称 + \param[in] tc 滴答周期（阻塞时间）
+ +0：清除阻塞
+ ~0：无限阻塞 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetBlock_tc(task, tc)，同返回。
+ pSetBlock_tc(task, tc)，同返回。
+ iSetBlock_tc(task, tc)，无返回/错误调用返回。 + */ +#define uSetBlock_tc(task, tc) sUSV_SetBlock(task, tc) + +/** + \brief 设置阻塞-毫秒 + \param[in] task 任务名称 + \param[in] ms 毫秒（阻塞时间）
+ 0：清除阻塞 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetBlock_ms(task, ms)，同返回。
+ pSetBlock_ms(task, ms)，同返回。
+ iSetBlock_ms(task, ms)，无返回/错误调用返回。 + */ +#define uSetBlock_ms(task, ms) uSetBlock_tc(task, (1000UL * (ms)) / SYSCFG_SYSTICK_CYCLE) + +/** + \brief 设置阻塞-秒钟 + \param[in] task 任务名称 + \param[in] s 秒钟（阻塞时间）
+ 0：清除阻塞 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetBlock_s(task, s)，同返回。
+ pSetBlock_s(task, s)，同返回。
+ iSetBlock_s(task, s)，无返回/错误调用返回。 + */ +#define uSetBlock_s(task, s) uSetBlock_ms(task, 1000UL * (s)) + +/** + \brief 设置阻塞-分钟 + \param[in] task 任务名称 + \param[in] m 分钟（阻塞时间）
+ 0：清除阻塞 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetBlock_m(task, m)，同返回。
+ pSetBlock_m(task, m)，同返回。
+ iSetBlock_m(task, m)，无返回/错误调用返回。 + */ +#define uSetBlock_m(task, m) uSetBlock_s(task, 60UL * (m)) + +/** + \brief 设置阻塞-小时 + \param[in] task 任务名称 + \param[in] h 小时（阻塞时间）
+ 0：清除阻塞 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTBLOCKED 任务未阻塞 + \retval OS_ECODE_TASKNOTSTARTED 任务未启动/已删除 + \note 同型服务：
+ tSetBlock_h(task, h)，同返回。
+ pSetBlock_h(task, h)，同返回。
+ iSetBlock_h(task, h)，无返回/错误调用返回。 + */ +#define uSetBlock_h(task, h) uSetBlock_m(task, 60UL * (h)) + +/** @} */ +/** @} */ +/** + \ingroup 任务 + \defgroup 操作自身任务 + \brief 仅适用于对自身任务的操作 + @{ + */ + +/** + \brief 禅让任务 + \details 自身任务主动禅让CPU使用权，轮转至下一个相同优先级的任务运行。 + \param 无 + \return 无 + \note 多个相同优先级的任务，通过禅让的方式可实现合作式任务。 + \note 禅让是自身任务主动时间片到期，禅让后任务仍为就绪状态。 + \warning 当开启相同优先级任务的时间片轮转调度时，才支持此服务。 + */ +#define uYieldTasking() su_yield_tasking() + +/** + \brief 设置自身任务优先级 + \param[in] npri 新优先级 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TPLUNCHANGED 优先级未改变 + */ +#define uSetTaskingPri(npri) sUSV_SetTaskPri(s_task_current, npri) + +/** + \brief 挂起自身任务 + \param 无 + \return 错误码（s_ecode_t） + \note 虽然也返回错误码，但在正常情况下结果一定是成功的，不必查看错误码。 + */ +#define uSuspendTasking() sUSV_SuspendTask(s_task_current) + +/** + \brief 删除自身任务 + \param 无 + \return 错误码（s_ecode_t） + \note 虽然也返回错误码，但在正常情况下结果一定是成功的，不必查看错误码。 + */ +#define uDeleteTasking() sUSV_DeleteTask(s_task_current) + +/** + \brief 恢复指定任务并挂起自身任务 + \param[in] task 指定任务名称 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval OS_ECODE_TASKNOTREADY 指定任务未就绪 + \retval OS_ECODE_TASKSTOPPED 指定任务已停止 + \retval OS_ECODE_TASKNOTSTARTED 指定任务未启动/已删除 + \note 当返回错误时，指定任务未能恢复为就绪状态，自身任务不会挂起。 + */ +#define uResumeSuspend(task) sUSV_ResumeSuspend(task) + +/** + \ingroup 操作自身任务 + \defgroup 自身任务延时 + \brief 自身任务延时分为阻塞延时和就绪延时。 + \note 阻塞延时：在延时期间，任务会进入阻塞状态，把CPU使用权转让给其它任务。 + \note 就绪延时：在延时期间，任务会维持就绪状态，原地等待延时时间到达，不转让CPU使用权。 + \note 当在任务临界区中，自动选择为就绪延时，否则选择为阻塞延时。 + \note 理想误差：-1tick。 + \warning 按 毫秒、秒钟、分钟、小时 延时，用户需自己保证时间的有效性（可被系统滴答周期整除）。 + \warning 无限延时，仅能通过调用 uDelay_tc(~0) 来实现。 + \warning 不支持在服务层临界区、全局临界区，或关闭总中断时调用。 + @{ + */ + +/** + \brief 延时-滴答周期 + \param[in] tc 滴答周期（延时时间）
+ ~0：无限延时 + \return 无 + */ +#define uDelay_tc(tc) sUSV_Delay(tc) + +/** + \brief 延时-毫秒 + \param[in] ms 毫秒（延时时间） + \return 无 + */ +#define uDelay_ms(ms) uDelay_tc((1000UL * (ms)) / SYSCFG_SYSTICK_CYCLE) + +/** + \brief 延时-秒钟 + \param[in] s 秒钟（延时时间） + \return 无 + */ +#define uDelay_s(s) uDelay_ms(1000UL * (s)) + +/** + \brief 延时-分钟 + \param[in] m 分钟（延时时间） + \return 无 + */ +#define uDelay_m(m) uDelay_s(60UL * (m)) + +/** + \brief 延时-小时 + \param[in] h 小时（延时时间） + \return 无 + */ +#define uDelay_h(h) uDelay_m(60UL * (h)) +/** @} */ +/** @} */ +/** @} */ +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 定时中断 + \brief 由用户定时操作，当定时器溢出时，系统将自动恢复/调用与其绑定的任务/钩子并可自动重复定时。 + \note 理想误差：-1tick。 + \warning 按 毫秒、秒钟、分钟、小时 定时，用户需自己保证时间的有效性（可被系统滴答周期整除）。 + @{ + */ + +/** + \brief 创建定时中断钩子 + \param[in] tmid 定时器ID + \param[in] arl 自动重装载设置
+ 0：关闭自动重装载
+ 1：开启自动重装载 + \param[in] add{...} 附加钩子代码 + \return 无 + */ +#define uCreateHook_TimInt(tmid, arl) \ + sCSV_CreateHook_TimInt(tmid, arl) + +/** + \brief 定时中断-滴答周期 + \param[in] tmid 定时中断定时器ID + \param[in] tc 滴答周期（定时时间） + \return 无 + \note 同型服务：
+ tTimInt_tc(tmid, tc)。
+ iTimInt_tc(tmid, tc)。 + */ +#define uTimInt_tc(tmid, tc) sUSV_TimInt(tmid, tc) + +/** + \brief 定时中断-毫秒 + \param[in] tmid 定时中断定时器ID + \param[in] ms 毫秒（定时时间） + \return 无 + \note 同型服务：
+ tTimInt_ms(tmid, ms)。
+ iTimInt_ms(tmid, ms)。 + */ +#define uTimInt_ms(tmid, ms) uTimInt_tc(tmid, (1000UL * (ms)) / SYSCFG_SYSTICK_CYCLE) + +/** + \brief 定时中断-秒钟 + \param[in] tmid 定时中断定时器ID + \param[in] s 秒钟（定时时间） + \return 无 + \note 同型服务：
+ tTimInt_s(tmid, s)。
+ iTimInt_s(tmid, s)。 + */ +#define uTimInt_s(tmid, s) uTimInt_ms(tmid, 1000UL * (s)) + +/** + \brief 定时中断-分钟 + \param[in] tmid 定时中断定时器ID + \param[in] m 分钟（定时时间） + \return 无 + \note 同型服务：
+ tTimInt_m(tmid, m)。
+ iTimInt_m(tmid, m)。 + */ +#define uTimInt_m(tmid, m) uTimInt_s(tmid, 60UL * (m)) + +/** + \brief 定时中断-小时 + \param[in] tmid 定时中断定时器ID + \param[in] h 小时（定时时间） + \return 无 + \note 同型服务：
+ tTimInt_h(tmid, h)。
+ iTimInt_h(tmid, h)。 + */ +#define uTimInt_h(tmid, h) uTimInt_m(tmid, 60UL * (h)) + +/** + \brief 终止定时中断 + \param[in] tmid 定时中断定时器ID + \return 无 + \note 同型服务：
+ tTimInt_Cancel(tmid)。
+ iTimInt_Cancel(tmid)。 + */ +#define uTimInt_Cancel(tmid) uTimInt_tc(tmid, 0) + +/** + \brief 定时中断定时器自动重装载 + \param[in] tmid 定时中断定时器ID + \param[in] arl 自动重装载设置
+ 0：关闭自动重装载
+ 1：开启自动重装载 + \return 无 + */ +#define xTimInt_AutoReload(tmid, arl) s_timint_autoreload[tmid] = arl + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 定时查询 + \brief 由用户定时操作，当定时器溢出后，系统在每个滴答周期都会查询用户定义的事件， + 若事件为真，系统将自动恢复/调用与其绑定的任务/钩子并可自动重复定时。 + \note 理想误差：-1tick。 + \warning 按 毫秒、秒钟、分钟、小时 定时，用户需自己保证时间的有效性（可被系统滴答周期整除）。 + @{ + */ + +/** + \brief 创建定时查询钩子 + \param[in] tmid 定时器ID + \param[in] event 定时查询事件 + \param[in] arl 自动重装载设置
+ 0：关闭自动重装载
+ 1：开启自动重装载 + \param[in] add{...} 附加钩子代码 + \return 无 + */ +#define uCreateHook_TimQry(tmid, event, arl) \ + sCSV_CreateHook_TimQry(tmid, event, arl) + +/** + \brief 定时查询-滴答周期 + \param[in] tmid 定时查询定时器ID + \param[in] tc 滴答周期（定时时间） + \return 无 + \note 同型服务：
+ tTimQry_tc(tmid, tc)。
+ iTimQry_tc(tmid, tc)。 + */ +#define uTimQry_tc(tmid, tc) sUSV_TimQry(tmid, tc) + +/** + \brief 定时查询-毫秒 + \param[in] tmid 定时查询定时器ID + \param[in] ms 毫秒（定时时间） + \return 无 + \note 同型服务：
+ tTimQry_ms(tmid, ms)。
+ iTimQry_ms(tmid, ms)。 + */ +#define uTimQry_ms(tmid, ms) uTimQry_tc(tmid, (1000UL * (ms)) / SYSCFG_SYSTICK_CYCLE) + +/** + \brief 定时查询-秒钟 + \param[in] tmid 定时查询定时器ID + \param[in] s 秒钟（定时时间） + \return 无 + \note 同型服务：
+ tTimQry_s(tmid, s)。
+ iTimQry_s(tmid, s)。 + */ +#define uTimQry_s(tmid, s) uTimQry_ms(tmid, 1000UL * (s)) + +/** + \brief 定时查询-分钟 + \param[in] tmid 定时查询定时器ID + \param[in] m 分钟（定时时间） + \return 无 + \note 同型服务：
+ tTimQry_m(tmid, m)。
+ iTimQry_m(tmid, m)。 + */ +#define uTimQry_m(tmid, m) uTimQry_s(tmid, 60UL * (m)) + +/** + \brief 定时查询-小时 + \param[in] tmid 定时查询定时器ID + \param[in] h 小时（定时时间） + \return 无 + \note 同型服务：
+ tTimQry_h(tmid, h)。
+ iTimQry_h(tmid, h)。 + */ +#define uTimQry_h(tmid, h) uTimQry_m(tmid, 60UL * (h)) + +/** + \brief 终止定时查询 + \param[in] tmid 定时查询定时器ID + \return 无 + \note 同型服务：
+ tTimQry_Cancel(tmid)。
+ iTimQry_Cancel(tmid)。 + */ +#define uTimQry_Cancel(tmid) uTimQry_tc(tmid, ~0) + +/** + \brief 定时查询定时器自动重装载 + \param[in] tmid 定时查询定时器ID + \param[in] arl 自动重装载设置
+ 0：关闭自动重装载
+ 1：开启自动重装载 + \return 无 + */ +#define xTimQry_AutoReload(tmid, arl) s_timqry_autoreload[tmid] = arl + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 互斥信号量 + \brief 仅适用于在任务中对任务级公共资源的互斥访问。 + \note 有优先级继承/天花板机制，以抑制优先级反转的发生。 + \note 互斥信号量均支持嵌套使用，最大嵌套深度255，获取与归还必须配对使用。 + \note 如果任务中调用了获取互斥量，应谨慎操作该任务，如操作不当可能会导致获取该互斥量的其它任务死锁。 + @{ + */ + +/** + \brief 声明互斥信号量 + \param[in] mut 互斥信号量名称 + \return 无 + */ +#define uExternMut(mut) sCSV_ExternMut(mut) + +/** + \brief 创建互斥信号量 + \param[in] mut 互斥信号量名称 + \return 无 + \warning 创建互斥信号量时，系统将自动赋初值，用户不可赋初值。 + */ +#define uCreateMut(mut) sCSV_CreateMut(mut) + +/** + \brief 获取互斥信号量 + \param[in] mut 互斥信号量名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \warning 不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uTakeMut(mut, tc) sUSV_TakeMut(mut, tc) + +/** + \brief 归还互斥信号量 + \param[in] mut 互斥信号量名称 + \return 无 + */ +#define uBackMut(mut) sUSV_BackMut(mut) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 二值信号量 + \brief 常用于事件同步、互斥访问（中断与任务之间的互斥）。 + @{ + */ + +/** + \brief 声明二值信号量 + \param[in] bin 二值信号量名称 + \return 无 + */ +#define uExternBin(bin) sCSV_ExternBin(bin) + +/** + \brief 创建二值信号量 + \param[in] bin 二值信号量名称 + \param[in] init 二值信号量初始值
+ false（0）：已上锁，无法立即成功获取
+ true（1） ：已解锁，可以立即成功获取 + \return 无 + \note 当用于互斥访问时，初始值应为true。 + */ +#define uCreateBin(bin, init) sCSV_CreateBin(bin, init) + +/** + \brief 上锁二值信号量 + \details 用于终止线程的无限同步。 + \param[in] bin 二值信号量名称 + \return 无 + \note 同型服务：
+ tLockBin(bin)。
+ pLockBin(bin)。
+ iLockBin(bin)。 + */ +#define uLockBin(bin) bin.binary = false + +/** + \brief 等待二值信号量 + \details 在指定的超时时间内等待二值信号量为真，适用于任务的无限同步，与获取的区别是不上锁。 + \param[in] bin 二值信号量名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \warning 不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uWaitBin(bin, tc) sUSV_WaitBin(bin, tc) + +/** + \brief 给予二值信号量 + \details 专用于事件同步。 + \param[in] bin 二值信号量名称 + \return 无 + \note 同型服务：
+ tGiveBin(bin)。
+ pGiveBin(bin)。
+ iGiveBin(bin)。 + */ +#define uGiveBin(bin) sUSV_GiveBin(bin) + +/** + \brief 获取二值信号量 + \details 用于事件同步或互斥访问。 + \param[in] bin 二值信号量名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \note 同型服务：
+ tTakeBin(bin)。
+ iTakeBin(bin)。 + \warning 任务中获取，不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uTakeBin(bin, tc) sUSV_TakeBin(bin, tc) + +/** + \brief 归还二值信号量 + \details 专用于互斥访问。 + \param[in] bin 二值信号量名称 + \return 无 + \note 同型服务：
+ tBackBin(bin)。
+ iBackBin(bin)。 + */ +#define uBackBin(bin) uGiveBin(bin) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 计数信号量 + \brief 常用于事件同步、重入访问（资源管理），是唯一能够实现并发事件同步的手段。 + @{ + */ + +/** + \brief 声明计数信号量 + \param[in] sem 计数信号量名称 + \return 无 + */ +#define uExternSem(sem) sCSV_ExternSem(sem) + +/** + \brief 创建计数信号量 + \param[in] sem 计数信号量名称 + \param[in] init 计数信号量初始值 + \param[in] max 计数信号量最大值 + \return 无 + */ +#define uCreateSem(sem, init, max) sCSV_CreateSem(sem, init, max) + +/** + \brief 给予计数信号量 + \param[in] sem 计数信号量名称 + \return 无 + \note 同型服务：
+ tGiveSem(sem)。
+ iGiveSem(sem)。 + */ +#define uGiveSem(sem) sUSV_GiveSem(sem) + +/** + \brief 获取计数信号量 + \param[in] sem 计数信号量名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \note 同型服务：
+ tTakeSem(sem)。 + \warning 任务中获取，不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uTakeSem(sem, tc) sUSV_TakeSem(sem, tc) + +/** + \brief 归还计数信号量 + \param[in] sem 计数信号量名称 + \return 无 + \note 同型服务：
+ tBackSem(sem)。 + */ +#define uBackSem(sem) uGiveSem(sem) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 事件标志组 + \brief 适用于对一类事件的事件同步。 + \details 某一类事件，它的发生线程可能会有多个，均同步至同一个事件处理线程中统一处理该类事件。 + \note 名词解释
+ 组名：标志组的名称
+ 位名：标志位的名称
+ 空位：空标志位
+ \note 查询标志位：任务、滴答、中断中，均直接查询。 + @{ + */ + +/** + \brief 声明标志组 + \param[in] group 组名 + \param[in] bits 定义各标志位，分号间隔 + \return 无 + */ +#define uExternFlagGroup(group, bits) sCSV_ExternFlagGroup(group, bits) + +/** + \brief 定义标志位 + \param[in] bit 位名 + \return 无 + */ +#define uDefFlagBit(bit) sDefBitField(bit) + +/** + \brief 定义空位 + \param[in] nvb 空位的数量 + \return 无 + */ +#define uDefVoidBits(nvb) sDefVoidBits(nvb) + +/** + \brief 创建标志组 + \param[in] group 组名 + \param[in] add={...} 附加代码（赋初值） + \return 无 + */ +#define uCreateFlagGroup(group) sCSV_CreateFlagGroup(group) + +/** + \brief 等待标志组 + \param[in] group 组名 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \warning 不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + \warning 事件的各个发生线程中设置标志位后，应调用 uClearBlock(task) 来手动完成事件同步。 + */ +#define uWaitFlagGroup(group, tc) sUSV_WaitFlagGroup(group, tc) + +/** + \brief 查询标志组 + \param[in] group 组名 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \note 同型服务：
+ tQueryFlagGroup(group)。
+ iQueryFlagGroup(group)。 + */ +#define uQueryFlagGroup(group) sUSV_QueryFlagGroup(group) + +/** + \brief 清除标志组 + \param[in] group 组名 + \return 无 + \note 同型服务：
+ tClearFlagGroup(group)。
+ iClearFlagGroup(group)。 + */ +#define uClearFlagGroup(group) sUSV_ClearFlagGroup(group) + +/** + \brief 设置标志位 + \param[in] group 组名 + \param[in] bit 位名 + \return 无 + \note 同型服务：
+ tSetFlagBit(group, bit)。
+ iSetFlagBit(group, bit)。 + */ +#define uSetFlagBit(group, bit) uSetFlagBits(group, 1) bit) + +/** + \brief 清除标志位 + \param[in] group 组名 + \param[in] bit 位名 + \return 无 + \note 同型服务：
+ tClearFlagBit(group, bit)。
+ iClearFlagBit(group, bit)。 + */ +#define uClearFlagBit(group, bit) uClearFlagBits(group, 1) bit) + +/** + \brief 设置多标志位 + \param[in] group 组名 + \param[in] nbit 标志位的数量 + \param[in] add...) 各位名，逗号间隔 + \return 无 + \note 同型服务：
+ tSetFlagBits(group, nbit)。
+ iSetFlagBits(group, nbit)。 + */ +#define uSetFlagBits(group, nbit) sUSV_WriteFlagBits(group, true, nbit) + +/** + \brief 清除多标志位 + \param[in] group 组名 + \param[in] nbit 标志位的数量 + \param[in] add...) 各位名，逗号间隔 + \return 无 + \note 同型服务：
+ tClearFlagBits(group, nbit)。
+ iClearFlagBits(group, nbit)。 + */ +#define uClearFlagBits(group, nbit) sUSV_WriteFlagBits(group, false, nbit) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 私信 + \brief 随意定义、灵活多变。 + \details 私信是CosyOS独创的一种任务间通信方式，其实质就是任务函数形参。 + \note 私信参数说明：
+ 1、私信参数的数量支持：1~8 个；
+ 2、各个参数的数据类型可为任意类型，只要编译器支持即可；
+ 3、各个参数的名称必须依次为：tm1、tm2...，用户可自行宏定义别名提高易用性。 + @{ + */ + +/** + \brief 接收私信
+
+ 别名
+           + uRecvTM + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 结果（bool） + \retval false 失败 + \retval true 成功 + \warning 不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uRecvTaskmsg(tc) sUSV_RecvTaskmsg(tc) + +/** + \brief 发送私信
+
+ 别名
+           + uSendTM + \param[in] task 任务名称 + \param[in] add(...) 附加私信实参 + \return 无 + \note 同型服务：
+ tSendTaskmsg(task) / tSendTM。 + \warning 如果在条件分支内调用，分支语句的{}不可省略。 + */ +#define uSendTaskmsg(task) sUSV_SendTaskmsg(task) + +/** + \brief 结束私信任务 + \details 私信任务的最后一句代码。 + \return 无 + */ +#define uEndTaskmsg() }while(true) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 飞信 + \brief 原子类型、传输数据。 + \details 仅使用一个变量，同时即是消息，又是新消息标志。
+ 飞信为0时，表示无消息；飞信非0时，表示有消息；
+ 因此： + \warning 用户传输的有效消息必须为真值。 + \note 架构             数据类型
+ 8051            uint8_t
+ 80251          uint16_t
+ Arm32         uint32_t
+ 通用别名     m_fetion_t
+ @{ + */ + +/** + \brief 声明信箱 + \param[in] tbox 信箱名称 + \return 无 + */ +#define uExternTionbox(tbox) sCSV_ExternTionbox(tbox) + +/** + \brief 创建信箱 + \param[in] tbox 信箱名称 + \return 无 + */ +#define uCreateTionbox(tbox) sCSV_CreateTionbox(tbox) + +/** + \brief 接收飞信
+
+ 别名
+           + uRecvFet + \param[in] tbox 信箱名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 飞信（m_fetion_t） + \retval false 无飞信 + \note 同型服务：
+ tRecvFetion(tbox) / tRecvFet。
+ iRecvFetion(tbox) / iRecvFet。 + \warning 任务中接收，不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uRecvFetion(tbox, tc) sUSV_RecvFetion(tbox, tc) + +/** + \brief 发送飞信
+
+ 别名
+           + uSendFet + \param[in] tbox 信箱名称 + \param[in] tion 飞信 + \return 无 + \note 同型服务：
+ tSendFetion(tbox, tion) / tSendFet。
+ iSendFetion(tbox, tion) / iSendFet。 + */ +#define uSendFetion(tbox, tion) sUSV_SendFetion(tbox, tion) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 消息邮箱 + \brief 任意类型、传输指针。 + @{ + */ + +/** + \brief 声明邮箱 + \param[in] mbox 邮箱名称 + \return 无 + */ +#define uExternMailbox(mbox) sCSV_ExternMailbox(mbox) + +/** + \brief 创建邮箱 + \param[in] mbox 邮箱名称 + \return 无 + */ +#define uCreateMailbox(mbox) sCSV_CreateMailbox(mbox) + +/** + \brief 接收邮件 + \param[in] mbox 邮箱名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 邮件指针（void *） + \retval NULL 无邮件 + \note 同型服务：
+ tRecvMail(mbox)。
+ iRecvMail(mbox)。 + \warning 任务中接收，不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + */ +#define uRecvMail(mbox, tc) sUSV_RecvMail(mbox, tc) + +/** + \brief 发送邮件 + \param[in] mbox 邮箱名称 + \param[in] mail 邮件指针 + \return 无 + \note 同型服务：
+ tSendMail(mbox, mail)。
+ iSendMail(mbox, mail)。 + */ +#define uSendMail(mbox, mail) sUSV_SendMail(mbox, mail) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 消息队列 + \brief 任意类型、传输指针，是唯一能够实现并发消息同步的手段。 + \details 消息队列包括静态队列和动态队列。
+ 静态队列：收发消息的效率高，队列占用固定的内存；
+ 动态队列：收发消息的效率低，接收消息后，队列内存可被回收。 + \note 每个队列，用户应当自己明确消息的类型和size，此事与OS无关。 + @{ + */ + +/** + \brief 声明静态队列 + \param[in] que 队列名称 + \return 无 + */ +#define uExternQueue_Static(que) sCSV_ExternQueue_Static(que) + +/** + \brief 声明动态队列 + \param[in] que 队列名称 + \return 无 + */ +#define uExternQueue_Dynamic(que) sCSV_ExternQueue_Dynamic(que) + +/** + \brief 创建静态队列 + \param[in] que 队列名称 + \param[in] mode 传输模式
+ 0：FIFO（先入先出）
+ 1：LIFO（后入先出） + \param[in] len 队列长度 + \return 无 + */ +#define uCreateQueue_Static(que, mode, len) sCSV_CreateQueue_Static(que, mode, len) + +/** + \brief 创建动态队列 + \param[in] que 队列名称 + \param[in] mode 传输模式
+ 0：FIFO（先入先出）
+ 1：LIFO（后入先出） + \param[in] len 队列长度 + \return 无 + */ +#define uCreateQueue_Dynamic(que, mode, len) sCSV_CreateQueue_Dynamic(que, mode, len) + +/** + \brief 接收消息 + \param[in] que 队列名称 + \param[in] tc 滴答周期（超时时间）
+ +0：立即返回
+ ~0：无限等待 + \return 消息指针（void *） + \retval NULL 无消息 + \note 同型服务：
+ tRecvMsg(que)。
+ iRecvMsg(que)。 + \warning 任务中接收，不支持在临界区中，包括任务临界区、服务层临界区、全局临界区，或关闭总中断时调用。 + \warning 中断中接收，队列只能是静态队列，消息缓存只能是静态缓存。 + */ +#define uRecvMsg(que, tc) sUSV_RecvMsg(que, tc) + +/** + \brief 发送消息 + \param[in] que 队列名称 + \param[in] msg 消息指针 + \return 错误码（s_ecode_t） + \retval OS_ECODE_NOERROR 无错误 + \retval ECODE_OVERFLOW_MSGQUEUE 消息队列溢出 + \retval ECODE_MALLOCFAIL_MSGNODE 消息节点内存分配失败 + \note 同型服务：
+ tSendMsg(que, msg)，同返回。
+ iSendMsg(que, msg)，无返回/错误调用返回。 + \warning 中断中发送，消息缓存只能是静态缓存。 + */ +#define uSendMsg(que, msg) sUSV_SendMsg(que, msg) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 全局变量访问 + \brief 由CosyOS内核提供服务支持，可实现在任务、滴答、中断中，对非原子型 + 全局变量的线程安全访问，同时不会破坏零中断延迟。 + \note 全局的结构体、数组、字符串等，都可视为非原子型全局变量。 + \note 原子型访问：
+ 滴答中：直接->读访问、写访问、自运算。
+ 任务中：直接->读访问、写访问，内核上锁后->自运算。
+ 中断中：直接->读访问，调用服务->写访问、自运算。 + \note 非原子型访问：
+ 滴答中：直接->读访问、写访问、自运算。
+ 任务中：内核上锁后->读访问、写访问、自运算。
+ 中断中：不可以读访问，调用服务->写访问、自运算。 + \note 不可以读访问：
+ 建议挂起到PendSV中，或同步至某任务中处理事件。
+ 挂起到PendSV中：iPendSVC(fp) 或 pendsv_hook()，均可直接->读访问；
+ 同步至某任务中：内核上锁后->读访问。 + @{ + */ + +/** + \brief 写全局变量 + \param[in] gv 全局变量名称 + \param[in] lv 局部变量名称 + \return 无 + */ +#define iWriteGVar(gv, lv) sIPS_WriteGVar((void *)&gv, (void *)&lv, sizeof(gv)) + +/** + \brief 写全局数组 + \param[in] gp 全局数组指针 + \param[in] lp 局部数组指针 + \param[in] size 拷贝的大小（字节数） + \return 无 + */ +#define iWriteGAry(gp, lp, size) sIPS_WriteGVar(gp, lp, size) + +/** + \brief 写全局字符串 + \param[in] gs 全局字符串指针 + \param[in] ls 局部字符串指针 + \return 无 + */ +#define iWriteGStr(gs, ls) sIPS_WriteGVar(gs, ls, 0) + +/** + \brief 挂起服务调用 + \param[in] fp 函数指针 + \return 无 + \note 适用于全局变量自运算、事件处理等。 + */ +#define iPendSVC(fp) sIPS_PendSVC(fp) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 软件RTC + \brief 适用于没有硬件RTC的物联网终端设备。 + \note 实际应用中，可每间隔一段时间（如一小时）同步一次网络时间，以校正误差。 + @{ + */ + +/** + \brief 获取时间 + \param[in] t 本地时间的指针（s_rtc_ts *） + \return t（void *） + \note 同型服务：
+ tGetTime(t)。 + */ +#define uGetTime(t) sUSV_GetTime(t) + +/** + \brief 设置时间 + \param[in] t 本地时间的指针（s_rtc_ts *） + \return 无 + \note 同型服务：
+ tSetTime(t)。
+ iSetTime(t)。 + */ +#define uSetTime(t) sUSV_SetTime(t) + +/** @} */ + +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 动态内存 + @{ + */ + +/** + \ingroup 动态内存 + \defgroup 进程内存 + \brief 以进程为单位初始化内存池，各进程独享自己的内存池。 + @{ + */ + +/** + \brief malloc + \details 在进程内存池或堆中分配一块内存。 + \param[in] size 内存块的大小（字节数） + \return 分配的指针（void _MALLOC_MEM_ *） + \retval NULL 内存分配失败 + */ +#define uMalloc(size) sUSV_Malloc(size) + +/** + \brief calloc + \details 在进程内存池或堆中连续分配多块内存。 + \param[in] nmemb 内存块的数量 + \param[in] size 内存块的大小（字节数） + \return 分配的指针（void _MALLOC_MEM_ *） + \retval NULL 内存分配失败 + */ +#define uCalloc(nmemb, size) sUSV_Calloc(nmemb, size) + +/** + \brief realloc + \details 重新分配内存。 + \param[in] p 预重分配的指针 + \param[in] size 预重分配的大小（字节数） + \return 分配的指针（void _MALLOC_MEM_ *） + \retval NULL 内存分配失败 + */ +#define uRealloc(p, size) sUSV_Realloc(p, size) + +/** + \brief free + \param[in] p 释放的指针 + \return 无 + */ +#define uFree(p) sUSV_Free(p) + +/** @} */ + +/** + \ingroup 动态内存 + \defgroup 线程内存 + \brief 以线程为单位初始化内存池，各线程独享自己的内存池。 + \note 线程内存的分配效率远高于进程内存，因为每一次调用uTalloc都是在自己的线程内存池中直接按序分配内存。 + \note 在某线程中，如果需要多次动态内存分配，可考虑采用线程内存以提高性能。 + \note 线程内存的应用法则：当所有uTalloc的内存都可以释放时，再一次性释放所有内存（线程内存池）。 + @{ + */ + +/** + \brief 创建线程内存池 + \details 实为定义变量（线程内存控制块），C89模式时可考虑在线程的开始处创建。 + \param 无 + \return 无 + */ +#define uCreateMempool() sCSV_CreateMempool() + +/** + \brief 初始化线程内存池 + \details 实质上是通过调用malloc，从进程内存池或堆中分配一块内存来做为线程内存池。 + \param[in] size 线程内存池的大小（字节数） + \return 结果（bool） + \retval false 失败 + \retval true 成功 + */ +#define uInitMempool(size) sUSV_InitMempool(size) + +/** + \brief 线程内存分配 + \details 在线程内存池中分配一块内存。 + \param[in] size 内存块的大小（字节数） + \return 分配的指针（void _MALLOC_MEM_ *） + \retval NULL 内存分配失败 + */ +#define uTalloc(size) sUSV_Talloc(size) + +/** + \brief 释放线程内存池 + \param 无 + \return 无 + */ +#define uFreeMempool() sUSV_FreeMempool() + +/** @} */ +/** @} */ +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 临界区 + \note CosyOS的临界区包括任务临界区、服务层临界区、全局临界区，均支持嵌套使用。
+ 各临界区之间也可随意互相嵌套，但通常推荐在任务临界区中嵌套服务层临界区，
+ 在服务层临界区中嵌套全局临界区，以逐步扩大保护范围。 + @{ + */ + +/** + \ingroup 临界区 + \defgroup 调度锁（任务临界区） + \brief 通过上锁任务调度器的方式，来实现任务级的临界区保护，仅支持在任务中调用。 + \note 仅是上锁任务调度器，不关闭系统中断（SysTick、PendSV），所以即使是长时间的、
+ 对大段的任务级公共资源的独占访问，也不会影响系统节拍和内核服务的执行。 + \note 调度锁支持嵌套使用，最大嵌套深度255，调度上锁与调度解锁必须配对使用。 + \note 调度锁不会破坏零中断延迟，当需要任务级的临界区保护时，可以考虑。 + @{ + */ + +/** + \brief 调度上锁（进入任务临界区） + \param 无 + \return 无 + */ +#define uScheduleLock() su_schedule_locks() + +/** + \brief 调度解锁（退出任务临界区） + \param 无 + \return 无 + */ +#define uScheduleUnlock() su_schedule_unlocks() + +/** @} */ + +/** + \ingroup 临界区 + \defgroup 内核锁（服务层临界区） + \brief OS内核级的临界区保护，会关闭系统中断（SysTick、PendSV），仅支持在任务中调用。 + \note 由SysTick、PendSV、内核锁，共同组成大的服务层临界区，当处理得当时，可实现全局的临界区保护。
+ 实现过程：
+ 滴答中：直接访问即可。
+ 任务中：内核上锁后访问。
+ 中断中：采用中断挂起服务。 + \note 内核锁支持嵌套使用，最大嵌套深度255，内核上锁与内核解锁必须配对使用。 + \note 内核锁不会破坏零中断延迟，当需要全局的临界区保护时，应首先予以考虑。 + \note 内核锁应遵循快进快出的原则，临界段代码的执行时间应远小于系统滴答周期，
+ 否则可能会导致丢失系统节拍、延误其它内核服务的执行，对系统实时性造成不利影响。 + \note 当在任务中访问非原子全局变量时，可采用内核锁实现全局的临界区保护。 + @{ + */ + +/** + \brief 内核上锁（进入服务层临界区） + \param 无 + \return 无 + */ +#define uKernelLock() su_kernel_locks() + +/** + \brief 内核解锁（退出服务层临界区） + \param 无 + \return 无 + */ +#define uKernelUnlock() su_kernel_unlocks() + +/** @} */ + +/** + \ingroup 临界区 + \defgroup 中断锁（全局临界区） + \brief 全局的临界区保护，通常会关闭总中断，支持在任意处调用。 + \note CosyOS内核中从来不会关闭总中断，提供此项服务只是为了便于用户
+ 对全局公共资源和程序过程的保护。 + \note 全局临界区会破坏零中断延迟，应做为最后的选项，慎重使用。 + @{ + */ +#if (MCUCFG_ISA != __ARM__) +/** + \ingroup 全局临界区 + \defgroup 操作-EA + \note 支持嵌套使用，最大嵌套深度255，进入临界区与退出临界区必须配对使用。 + @{ + */ + +/** + \brief 进入全局临界区 + \param 无 + \return 无 + */ +#define xDisableIRQ() mxDisableIRQ() + +/** + \brief 退出全局临界区 + \param 无 + \return 无 + */ +#define xResumeIRQ() mxResumeIRQ() + +/** @} */ +#else +/** + \ingroup 全局临界区 + \defgroup 操作-PRIMASK + \note 支持嵌套使用，进入临界区与退出临界区必须配对使用。 + @{ + */ + +/** + \brief 进入全局临界区 + \param 无 + \return oirq PRIMASK上一次的值（uint32_t类型） + */ +#define xDisableIRQ() mxDisableIRQ() + +/** + \brief 退出全局临界区 + \param[in] oirq PRIMASK上一次的值（uint32_t类型） + \return 无 + */ +#define xResumeIRQ(oirq) mxResumeIRQ(oirq) + +/** @} */ + +/** + \ingroup 全局临界区 + \defgroup 操作-BASEPRI + \note 使用条件：
+ 1、MCU必须有 BASEPRI 寄存器；
+ 2、MCU配置中，系统中断配置必须选择 TIMn_IRQHandler + XXX_IRQHandler。 + \note 使用说明：
+ 1、关于npri，例如中断优先级分组选择 NVIC_PriorityGoup_4，那么中断优先级从高到低为 0~15。
+ 如果需要掩蔽（3~15）的中断，npri应输入3。
+ 2、支持嵌套使用，进入临界区与退出临界区必须配对使用。
+ 3、嵌套使用时，仅能逐步扩大掩蔽范围（npri越来越小），否则新的掩蔽范围不会生效（将维持上一次的掩蔽范围）。 + @{ + */ + +/** + \brief 进入全局临界区 + \param[in] npri 掩蔽范围的最高优先级的优先级号（uint32_t类型） + \return opri BASEPRI的原值（uint32_t类型） + */ +#define xMaskingPRI(npri) mxMaskingPRI(npri) + +/** + \brief 退出全局临界区 + \param[in] opri BASEPRI的原值（uint32_t类型） + \return 无 + */ +#define xResumePRI(opri) mxResumePRI(opri) + +/** @} */ +#endif +/** @} */ +/** @} */ +/**************************************************************************//** + \ingroup CosyOS_用户API + \defgroup 杂项 + @{ + */ + +/** + \ingroup 杂项 + \defgroup 中断挂起服务_FIFO-错误调用返回 + \note 当需要回调时，下列的回调函数可以在用户文件中实现。 + \note 对于8051来说，如果系统中断被配置为使用独立的REGBANK（与任务使用不同的REGBANK），
+ 下列的回调函数需要添加using属性、或声明为相对寄存器访问。参见 tick_hook.c 中示例。 + @{ + */ + +/** + \brief iResumeTask(task) error callback + \param[in] htask 任务句柄 + \return 无 + */ +void pResumeTask_ErrorCallback(s_tasknode_tsp htask); + +/** + \brief iSuspendTask(task) error callback + \param[in] htask 任务句柄 + \return 无 + */ +void pSuspendTask_ErrorCallback(s_tasknode_tsp htask); + +/** + \brief iDeleteTask(task) error callback + \param[in] htask 任务句柄 + \return 无 + */ +void pDeleteTask_ErrorCallback(s_tasknode_tsp htask); + +/** + \brief iClearBlock(task) error callback + \param[in] htask 任务句柄 + \return 无 + */ +void pClearBlock_ErrorCallback(s_tasknode_tsp htask); + +/** + \brief iSetBlock_x(task, x) error callback + \details iSetBlock_tc(task, tc)、iSetBlock_ms(task, ms)、iSetBlock_s(task, s)、 + iSetBlock_m(task, m)、iSetBlock_h(task, h)，都通过该函数实现错误调用返回。 + \param[in] htask 任务句柄 + \param[in] tick 滴答周期（阻塞时间） + \return 无 + */ +void pSetBlock_ErrorCallback(s_tasknode_tsp htask, s_delay_t tick); + +/** + \brief iSetTaskPri(task, npri) error callback + \param[in] htask 任务句柄 + \param[in] npri 新优先级 + \return 无 + */ +void pSetTaskPri_ErrorCallback(s_tasknode_tsp htask, s_u8_t npri); + +/** + \brief iSendMsg(que, msg) error callback + \param[in] hque 队列句柄 + \param[in] msg 消息指针 + \return 无 + */ +void pSendMsg_ErrorCallback(s_msgque_tsp hque, void *msg); + +/** + \brief error code of error callback + \param 无 + \return 错误码（s_ecode_t） + */ +#define pECode_ErrorCallback() s_psvfifo_ecode + +/** @} */ + +/** + \ingroup 杂项 + \defgroup DEBUG + \brief DEBUG接口，串口发送与接收的实现。 + @{ + */ + +/** + \brief DEBUG发送完成 + \param 无 + \return 无 + */ +#define xDebugSend_Complete() s_debug_sendsign = true + +/** + \brief DEBUG接收解析 + \param[in] p 接收缓存的开始指针 + \param[in] len 接收数据包的长度 + \return 无 + */ +#define xDebugRecv_Handler(p, len) \ +do{ \ + s_debug_recvptr = p; \ + s_debug_recvlen = len; \ +}while(false) + +/** @} */ + +/** + \ingroup 杂项 + \defgroup 时间单位转换 + \brief 把其它单位的时间转换为滴答周期。 + @{ + */ + +/** + \brief 毫秒转换为滴答周期 + \param[in] ms 毫秒 + \return 滴答周期 + */ +#define xTick_ms(ms) ((1000UL * (ms)) / SYSCFG_SYSTICK_CYCLE) + +/** + \brief 秒钟转换为滴答周期 + \param[in] s 秒钟 + \return 滴答周期 + */ +#define xTick_s(s) xTick_ms(1000UL * (s)) + +/** + \brief 分钟转换为滴答周期 + \param[in] m 分钟 + \return 滴答周期 + */ +#define xTick_m(m) xTick_s(60UL * (m)) + +/** + \brief 小时转换为滴答周期 + \param[in] h 小时 + \return 滴答周期 + */ +#define xTick_h(h) xTick_m(60UL * (h)) + +/** @} */ + +/** + \brief 触发PendSV + \details 在用户中断中，当采用中断挂起服务FLAG队列执行服务时，用户在设置标志位后，
+ 需手动触发PendSV，而后在 pendsv_hook() 中执行服务。 + \param 无 + \return 无 + */ +#define iPendSV_Set() mPendSV_Set() + +/** @} */ + + +/** @} */ +#endif