diff --git a/osal/cosit/.gitignore b/osal/cosit/.gitignore new file mode 100644 index 0000000..297fd37 --- /dev/null +++ b/osal/cosit/.gitignore @@ -0,0 +1,54 @@ +# Prerequisites +*.d + +# Object files +*.o +*.ko +*.obj +*.elf + +# Linker output +*.ilk +*.map +*.exp + +# Precompiled Headers +*.gch +*.pch + +# Libraries +*.lib +*.a +*.la +*.lo + +# Shared objects (inc. Windows DLLs) +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app +*.i*86 +*.x86_64 +*.hex + +# Debug files +*.dSYM/ +*.su +*.idb +*.pdb + +# Kernel Module Compile Results +*.mod* +*.cmd +.tmp_versions/ +modules.order +Module.symvers +Mkfile.old +dkms.conf + +.DS_Store diff --git a/osal/cosit/IoT OS软件架构.png b/osal/cosit/IoT OS软件架构.png new file mode 100644 index 0000000..ed184a4 Binary files /dev/null and b/osal/cosit/IoT OS软件架构.png differ diff --git a/osal/cosit/LICENSE b/osal/cosit/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/osal/cosit/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/osal/cosit/README.md b/osal/cosit/README.md new file mode 100644 index 0000000..78a9933 --- /dev/null +++ b/osal/cosit/README.md @@ -0,0 +1,18 @@ +# Cross-Operating System Interface on ioT + +#### 介绍 +围绕物联网操作系统的内核抽象层接口、应用接口和硬件抽象层接口，制定接口实现 + + +#### 软件架构 +![输入图片说明](IoT%20OS%E8%BD%AF%E4%BB%B6%E6%9E%B6%E6%9E%84.png) + + + +#### 参与贡献 + +1. Fork 本仓库 +2. 新建分支 +3. 提交代码 +4. 新建 Pull Request + diff --git a/osal/cosit/components/.keep b/osal/cosit/components/.keep new file mode 100644 index 0000000..e69de29 diff --git a/osal/cosit/documentation/design_guideline.md b/osal/cosit/documentation/design_guideline.md new file mode 100644 index 0000000..a6e5407 --- /dev/null +++ b/osal/cosit/documentation/design_guideline.md @@ -0,0 +1,105 @@ + +定义的API/宏/枚举常量等统一采用前缀**cos**，以保证命名空间的独立性，不会与其他SDK/BSP内的名称重复。注意API采用小写cos_xxx， 宏/枚举采用大写COS_XXX. + +# 设计目标 +标准的设计目标要达到，开发者只需要查看一个模块的标准文档，就能了解模块的功能是什么，如何使用，使用时的注意事项。开发者不需要查看代码具体实现，甚至不需要查看其他资料，就可以进行应用的开发，并最终可以无缝迁移到支持该标准的平台。 + +# 命名规则 +### 命名风格 +统一采用linux命名风格，即API字母全小写，字段之间加下划线分割。如`cos_task_create/cos_mutex_create/cos_queue_send` 。 +宏和枚举变量采用全大写和下划线分割的形式，如`COS_WAIT_FOREVER` 。 + +### API命名 +遵循名词在前，动词在后。 +`cos__[feature]_` + +cos：标准的统一前缀 +component: 必选的，组件名称。如task/mutex/queue +feature: 可选的，组件内部子特性或子名称，如task组件内的name/priority +action: 必选的， API的动作，如get/set/send/recv/ + +命名举例 +- cos_task_create +- cos_task_name_get +- cos_mutex_lock + +### API术语 +一些API命名时术语，可以参考行业各家OS的术语，及其他标准CMSIS/POSIX的术语。可以使用行业内标准缩写。 +**create/delete** +每次调用都会创建一个新的实例的情形使用create，且句柄作为出参。删除实例使用delete。 +```C +cos_status_t cos_task_create(cos_task_t *task, cos_task_entry_t fn, void *arg, cos_task_attr_t *attr) + +cos_status_t cos_task_delete(cos_task_t task) +``` + +**init/deinit** +只能进行一次的初始化，如接口初始化，硬件初始化等，使用init，句柄作为入参，且句柄可省略。 反初始化使用deinit + +```C +cos_status_t cos_init(void) +void cos_deinit(void) +``` + +# 数据类型 +关于API使用的基本数据类型统一采用标准数据类型。 +对于基本正数采用stdint.h中定义的数据类型 +- int8_t +- uint8_t +- int16_t +- uint16_t +- int32_t +- uint32_t +- int64_t +- uint64_t +- uintptr_t +- intprt_t + +和长度相关的数据类型 +- size_t +- ssize_t + +基本指针类型，不做限制如 +- char * +- void * + +内核对象的句柄 +- cos_xxx_t * +如cos_task_t/cos_mutex_t/cos_sem_t/cos_queue_t等。 + +统一的错误码类型 +- cos_status_t + +其他 +- bool + +# 错误码 +标准应采用统一的错误码，支持可扩展。采用`cos_status_t`数据类型，所有的错误码均为负值。返回0代表成功。 +一些例外：如类似read/write API返回ssize_t类型，> 0 代表长度，< 0代表失败。 + +# 模块描述 +标准中对一个功能模块的描述，应包含以下这些内容。 +## 模块功能描述 +包括解释模块功能是什么，阐述工作原理，使用功能的场景及其注意事项。 + +## 模块常量定义 +包括模块定义的宏和枚举常量，命名全大写和下划线，统一**cos_**前缀。 + +## 模块数据类型定义 +包括模块定义的复合数据类型。全小写，统一**cos_**前缀。 + +## 模块API描述内容 +对一个API的描述需要完整，清晰，表达没有歧义。包括如下内容章节。 + +1. API名称和简短说明 +2. API原型 +API的原型申明和应该使用该API时需要包含的头文件。 +3. API的详细描述 +4. API的参数 +包括参数名称，参数类型，参数方向，参数详细描述这几个要素。 +5. API的返回值 +包括API的返回值及其代表的含义。 +6. API的使用注意 +包括API的使用注意事项，例如能否在中断上下文中使用等。 +7. 使用举例 +给出使用该API的例子。 diff --git a/osal/cosit/documentation/ipc.md b/osal/cosit/documentation/ipc.md new file mode 100644 index 0000000..2f7860f --- /dev/null +++ b/osal/cosit/documentation/ipc.md @@ -0,0 +1,704 @@ +## 5.4. 互斥量 + +互斥量又称互斥锁，一般用于共享资源的互斥排他性访问保护。 + +互斥量在任意时刻处于且仅会处于解锁或锁定状态，当一个任务获取到一把锁后（互斥量锁定），其他任务再尝试获得这把锁时会失败或进入阻塞状态，当该任务释放持有的锁时（互斥量解锁），会唤醒一个正阻塞等待此互斥量的任务，被唤醒的任务将会获取这把锁。 + +在多任务运行环境中，有些共享资源不具有多线程可重入性，对于这类不希望被多任务同时访问的资源（临界资源），可以采用互斥量来进行保护。 + +### 5.4.1. 常量 + +#### 5.4.1.1. COS_MUTEX_NEST +```c +#define COS_MUTEX_NEST (0x1u << 0) +``` +互斥锁支持嵌套锁。 + +### 5.4.2. 类型 + +#### 5.4.2.1. cos_mutex_t + +互斥锁的句柄，代表一个互斥锁。可以通过句柄对互斥锁进行操作，如创建、申请、释放、销毁。 + +```c +typedef void * cos_mutex_t; +``` + +### 5.4.3. 函数 + +#### 5.4.3.1. cos_mutex_create + +互斥锁创建 + +**函数原型** +```c +cos_status_t cos_mutex_create(cos_mutex_t *mutex, char *name, uint32_t options); +``` + +**描述** + +创建一个新的互斥锁并初始化，新的互斥锁的句柄由参数mutex返回，后续对互斥锁的操作可以通过参数mutex进行。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|出参|互斥锁句柄| +|name|入参|互斥锁名称| +|options|入参|互斥锁选项，如是否支持嵌套锁| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| +|COS_ERR_PARAM|非法参数| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.4.3.2. cos_mutex_init + +初始化一个互斥锁 + +**函数原型** +```c +cos_status_t cos_mutex_init(cos_mutex_t mutex, char *name, uint32_t options); +``` + +**描述** + +初始化一个新的互斥锁。 + +与创建一个互斥锁类型，区别是互斥锁的控制块内存由调用者传入，一般用于静态分配内存的场景。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|入参|互斥锁的句柄| +|name|入参|互斥锁名称| +|options|入参|互斥锁选项，如是否支持嵌套锁| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| +|COS_ERR_PARAM|非法参数| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.4.3.3. cos_mutex_delete + +删除动态创建的互斥锁 + +**函数原型** +```c +cos_status_t cos_mutex_delete(cos_mutex_t mutex); +``` +**描述** + +销毁互斥锁。系统会唤醒所有等待该互斥锁的任务，返回互斥锁已经被销毁，然后销毁回收其资源。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|cos_mutex_t|入参|互斥锁的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.4.3.4. cos_mutex_deinit + +销毁静态创建的互斥锁 + +**函数原型** +```c +cos_status_t cos_mutex_deinit(cos_mutex_t mutex); +``` + +**描述** + +销毁静态创建的互斥锁。系统会唤醒所有等待该互斥锁的任务，返回互斥锁已经被销毁。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|cos_mutex_t|入参|互斥锁的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.4.3.5. cos_mutex_lock + +互斥锁上锁 + +**函数原型** +```c +cos_status_t cos_mutex_lock(cos_mutex_t mutex, cos_tick_t timeout); +``` +**描述** + +申请互斥锁。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|入参|互斥锁的句柄| +|timeout|入参|申请超时时间，单位为tick| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_TIMEOUT|申请超时| +|COS_ERR_DESTROY|申请的互斥锁已被销毁| +|COS_ERR_MUTEX_NESTING|已经拥有互斥锁，嵌套申请| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.4.3.6. cos_mutex_unlock + +互斥锁解锁 + +**函数原型** +```c +cos_status_t cos_mutex_unlock(cos_mutex_t mutex); +``` + +**描述** + +互斥锁解锁。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|mutex|入参|互斥锁的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_DESTROY|释放的互斥锁已被销毁| +|COS_ERR_MUTEX_NOT_OWNER|未持有该互斥锁| +|COS_ERR_MUTEX_NESTING|已经释放互斥锁，但还在嵌套中| + +### 5.4.4. 示例 +```c + +``` +## 5.5. 信号量 + +信号量是一种实现任务间同步的机制，一般用于多个任务间有限资源竞争访问。 + +通常来说，一个信号量中持有一个整形数值，用以表示可用资源的数量。当一个信号量的可用资源数量大于0时，任务尝试获取该信号量成功，信号量的可用资源数减一；当一个信号量的可用资源数等于0时，任务尝试获取该信号量失败或进入阻塞状态。信号量的这一模式，当可用资源数为1时，可将其用于资源的互斥访问；或者解决生产者-消费者问题中的资源生产-消费问题。编程实例章节会演示生产者-消费者问题的解决范式。 + +### 5.5.1. 常量 + +#### 5.5.1.1. COS_SEM_NO_MAX +```c +#define COS_SEM_NO_MAX (uint32_t)-1 +``` +信号量无最大值，可以用作计数信号量。 + +### 5.5.2. 类型 + +#### 5.5.2.1. cos_sem_t +```c +typedef void * cos_sem_t; +``` + +信号量的句柄，代表一个信号量。可以通过句柄对信号量进行操作，如创建、等待、释放、销毁。 + +### 5.5.3. 函数 + +#### 5.5.3.1. cos_sem_create + +创建一个信号量 + +**函数原型** +```c +cos_status_t cos_sem_create(cos_sem_t *sem, char *name, uint32_t init_count, uint32_t max_count); +``` +**描述** + +创建一个新的信号量并初始化，新的信号量的句柄由参数sem返回，后续对信号量的操作可以通过参数sem进行。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|出参|信号量句柄| +|name|入参|信号量的名称| +|init_count|入参|信号量初始值| +|max_count|入参|信号量最大值| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| +|COS_ERR_PARAM|非法参数| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.5.3.2. cos_sem_init + +初始化一个信号量 + +**函数原型** +```c +cos_status_t cos_sem_init(cos_sem_t sem, char *name, uint32_t init_count, uint32_t max_count); +``` +**描述** + +初始化一个信号量 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量句柄| +|name|入参|信号量的名称| +|init_count|入参|信号量初始值| +|max_count|入参|信号量最大值| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| +|COS_ERR_PARAM|非法参数| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.5.3.3. cos_sem_delete + +删除动态创建的信号量 + +**函数原型** +```c +cos_status_t cos_sem_delete(cos_sem_t sem); +``` +**描述** + +删除动态创建的信号量。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.5.3.4. cos_sem_deinit + +销毁静态创建的信号量 + +**函数原型** +```c +cos_status_t cos_sem_deinit(cos_sem_t sem); +``` +**描述** + +销毁静态创建的信号量。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.5.3.5. cos_sem_wait + +等待信号量 + +**函数原型** +```c +cos_status_t cos_sem_wait(cos_sem_t *sem, cos_tick_t timeout); +``` +**描述** + +等待信号量。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量的句柄| +|timeout|入参|申请超时时间，单位为tick| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_TIMEOUT|申请超时| +|COS_ERR_DESTROY|申请的信号量已被销毁| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.5.3.6. cos_sem_release + +释放信号量 + +**函数原型** +```c +cos_status_t cos_sem_release(cos_sem_t sem); +``` +**描述** + +释放信号量。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_DESTROY|释放的信号量已被销毁| + +#### 5.5.3.7. cos_sem_release_all + +释放信号量 + +**函数原型** +```c +cos_status_t cos_sem_release_all(cos_sem_t sem); +``` +**描述** + +释放信号量，并唤醒所有等待该信号量的任务。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|sem|入参|信号量的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_DESTROY|释放的信号量已被销毁| + +### 5.5.4. 示例 +```c + +``` + +## 5.6. 事件 + +事件提供了一种任务间实现同步和信息传递的机制。一般来说，一个事件中包含了一个旗标，这个旗标的每一位表示一个“事件”。 + +一个任务可以等待一个或者多个“事件”的发生，其他任务在一定的业务条件下可以通过写入特定“事件”唤醒等待此“事件”的任务，实现一种类似信号的编程范式。 + +### 5.6.1. 常量 + +#### 5.6.1.1. COS_EVENT_WAIT_ANY +```c +#define COS_EVENT_WAIT_ANY (0x1u << 0) +``` +等待事件时，用于指定等待其中任意一个。 +#### 5.6.1.2. COS_EVENT_WAIT_ALL +```c +#define COS_EVENT_WAIT_ALL (0x1u << 1) +``` +等待事件时，用于指定等待所有事件。 +#### 5.6.1.3. COS_EVENT_WAIT_CLR +```c +#define COS_EVENT_WAIT_CLR (0x1u << 2) +``` +等待事件时，用于指定等待后清除该事件。 + +#### 5.6.1.4. COS_EVENT_RELEASE_KEEP +```c +#define COS_EVENT_RELEASE_KEEP (0x1u << 3) +``` +释放事件时，用于指定释放后是否保留该事件。 + +### 5.6.2. 类型 + +#### 5.6.2.1. cos_event_t +```c +typedef void * cos_event_t; +``` + +事件的句柄，代表一个事件。可以通过句柄对事件进行操作，如创建、等待、释放、销毁。 + +#### 5.6.2.2. cos_event_flag_t +```c +typedef uint32_t cos_event_flag_t; +``` +用于存储事件标志。 + +### 5.6.3. 函数 + +#### 5.6.3.1. cos_event_create + +事件创建 + +**函数原型** +```c +cos_status_t cos_event_create(cos_event_t *event, char *name, cos_event_flag_t init_flag); +``` +**描述** + +创建一个新的事件并初始化，新的事件的句柄由参数event返回，后续对事件的操作可以通过参数event进行。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|出参|事件的句柄| +|name|入参|事件的名称| +|init_flag|入参|事件初始化标志| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.6.3.2. cos_event_init + +初始化一个事件 + +**函数原型** +```c +cos_status_t cos_event_init(cos_event_t event, char *name, cos_event_flag_t init_flag); +``` +**描述** + +初始化一个事件 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|入参|事件的句柄| +|name|入参|事件的名称| +|init_flag|入参|事件初始化标志| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_NOMEM|内存不足| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.6.3.3. cos_event_delete + +删除动态创建的事件 + +**函数原型** +```c +cos_status_t cos_event_delete(cos_event_t event); +``` +**描述** + +删除动态创建的事件。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|入参|事件的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.6.3.4. cos_event_deinit + +销毁事件 + +**函数原型** +```c +cos_status_t cos_event_deinit(cos_event_t event); +``` +**描述** + +销毁静态创建的事件。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|入参|事件的句柄| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| + +#### 5.6.3.5. cos_event_wait + +等待一个或多个事件。 + +**函数原型** +```c +cos_status_t cos_event_wait(cos_event_t event, cos_event_flag_t expect_flag, cos_tick_t timeout, cos_event_flag_t *match_flag, uint32_t options); +``` +**描述** + +等待一个或多个事件。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|入参|事件的句柄| +|expect_flag|入参|期望等到的事件| +|timeout|入参|申请超时时间，单位为tick| +|match_flag|出参|事件的匹配结果| +|options|入参|事件匹配选项（任意一个匹配或者全部匹配）| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_ISR|在中断上下文中调用| +|COS_ERR_TIMEOUT|申请超时| +|COS_ERR_DESTROY|事件已被销毁| + +**注意** + +此函数不能在中断上下文中使用。 + +#### 5.6.3.6. cos_event_release + +释放事件 + +**函数原型** +```c +cos_status_t cos_event_release(cos_event_t event, cos_event_flag_t flag, uint32_t options); +``` + +**描述** + +释放事件。 + +**参数** + +|参数名称|参数方向|描述| +|:----:|:----:|:----:| +|event|入参|事件的句柄| +|expect_flag|入参|释放的事件| +|options|入参|事件释放选项，释放后是否保留| + +**返回值** + +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 + +|错误码|描述| +|:---:|:---:| +|COS_ERR|未知错误| +|COS_ERR_DESTROY|事件已被销毁| + +### 5.6.4. 示例 +```c + +``` diff --git a/osal/cosit/documentation/mail_box.md b/osal/cosit/documentation/mail_box.md new file mode 100644 index 0000000..c148348 --- /dev/null +++ b/osal/cosit/documentation/mail_box.md @@ -0,0 +1,191 @@ +# 邮箱 + +消息邮箱（Mail Box）是实时操作系统中一种典型的线程间通信方法，邮箱用于线程间通信，特点是开销比较低，效率较高。 + +## 类型 + +```C +typedef void * cos_mb_t; +``` + +邮箱控制块是操作系统用于管理邮箱的一个数据结构，cos_mb_t是邮箱的句柄。 + +## 函数 + +### cos_mb_create + +创建邮箱 + +原型 + +```C + +#include +cos_status_t cos_mb_create(const char* name, size_t msg_size, + uint8_t flag，cos_mb_t* mb); + +``` + +**描述** +创建一个邮箱，由系统动态为邮箱申请内存空间，并返回邮箱的句柄。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| name | const char* | 入参 | 邮箱名称 | +| msg_size | sizebt | 入参 | 邮箱容量 | +| flag | uint8_t | 入参 | 邮箱标志，如： COS_IPC_FLAG_FIFO 或 COS_IPC_FLAG_PRIO | +| mb | cos_mb_t | 出参 | 邮箱句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERROR_MEM | 内存不足 | + +### cos_mb_delete + +删除邮箱 + +原型 + +```C + +#include +cos_status_t cos_mb_delete(cos_mb_t mb); + +``` + +**描述** +删除一个邮箱。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mb | cos_mb_t | 入参 | 邮箱的句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | + +### cos_mb_init + +初始化邮箱 + +原型 + +```C + +#include +cos_status_t cos_mb_init(const char* name, void *msgpool, size_t msg_size, + size_t max_msgs, cos_mb_t mb); + +``` + +**描述** +创建一个静态邮箱，由编译器提前为邮箱在编译时分配内存空间。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | --------------------------- | +| name | const char* | 入参 | 邮箱的名称 | +| msgpool | void* | 入参 | 缓冲区指针 | +| msg_size | size_t | 入参 | 邮箱容量 | +| flag | uint8_t | 入参 | 邮箱工作方式 cos_IPC_FLAG_FIFO 或 cos_IPC_FLAG_PRIO | +| mb | cos_mb_t | 出参 | 邮箱句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | + +### cos_mb_deinit + +删除邮箱 + +原型 + +```C + +#include +cos_status_t cos_mb_deinit(cos_mb_t mb); + +``` + +**描述** +去初始化一个邮箱。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mb | cos_mb_t | 入参 | 邮箱的句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | + +### cos_mb_send + +发送邮件 + +原型 + +```C + +#include +cos_status_t cos_mb_send(cos_mb_t mb，uint32_t value); + +``` + +**描述** +发送邮件，当邮箱中的邮件已经满时，发送邮件的线程或者中断程序会收到 cos_ERROR_mb_FULL 的返回值。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mb | cos_mb_t | 入参 | 邮箱的句柄 | +| value | uint32_t | 入参 | 邮件内容 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERROR_mb_FULL | 邮箱中的邮已满 | + +### cos_mb_recive + +接收邮件 + +原型 + +```C + +#include +cos_status_t cos_mb_recv(cos_mb_t mb，uint32_t* value, + int32_t timeout); + +``` + +**描述** +当邮箱中有邮件时，接收者才能接收邮件，否则接收者会根据超时时间设置，或挂起在邮箱的等待线程队列上，或直接返回。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mb | cos_mb_t | 入参 | 邮箱的句柄 | +| value | void* | 入参 | 邮件内容 | +| timeout | int32_t | 入参 | 指定的超时时间 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERROR_mb_TIMEOUT | 超时 | diff --git a/osal/cosit/documentation/message_queue.md b/osal/cosit/documentation/message_queue.md new file mode 100644 index 0000000..d05e1fc --- /dev/null +++ b/osal/cosit/documentation/message_queue.md @@ -0,0 +1,198 @@ +# 消息队列 + +消息队列（Message Queue）是一种常见的异步任务间通讯方式，用于在任务与任务间，任务与中断间传递不定长的数据。任务能够从队列里面读取消息，当队列中的消息为空时，挂起读取任务；当队列中有新消息时，挂起的读取任务被唤醒并处理新消息。任务也能够往队列里写入消息，当队列已经写满消息时，挂起写入任务；当队列中有空闲消息节点时，挂起的写入任务被唤醒并写入消息。 + +## 类型 + +```C +typedef struct cos_messagequeue* cos_mq_t; +``` + +消息队列控制块，消息队列控制块是操作系统用于管理消息队列的一个数据机构，由结构体cos_messagequeue表示，cos_mq_t是消息队列的句柄。 + +## 函数 + +### cos_mq_create + +创建消息队列 + +原型 + +```C + +#include +cos_status_t cos_mq_create(const char* name, size_t msg_size, + size_t max_msgs, uint8_t flag，cos_mq_t* mq); + +``` + +**描述** +创建一个消息队列，由系统动态为消息队列申请内存空间，并返回消息队列的句柄。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| name | const char* | 入参 | 消息队列的名称 | +| msg_size | size_t | 入参 | 单条消息的最大长度 | +| max_msgs | size_t | 入参 | 消息队列的最大个数 | +| flag | uint8_t | 入参 | 消息队列工作方式 COS_IPC_FLAG_FIFO 或 COS_IPC_FLAG_PRIO | +| mq | cos_mq_t | 出参 | 消息队列句柄 | + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERR_NOMEM | 内存不足 | +| COS_ERR_ISR | 在中断上下文中调用 | +| COS_ERR | 未知错误 | + +### cos_mq_init + +创建消息队列 + +init + +```C + +#include +cos_status_t cos_mq_init(const char* name, void *msgpool, size_t msg_size, + size_t max_msgs, cos_mq_t mq); + +``` + +**描述** +创建一个静态消息队列，由编译器提前为消息队列在编译时分配内存空间。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | --------------------------- | +| name | const char* | 入参 | 消息队列的名称 | +| msgpool | void* | 入参 | 指向存放消息的缓冲区的指针 | +| msg_size | size_t | 入参 | 单条消息的最大长度，单位字节 | +| flag | uint8_t | 入参 | 消息队列工作方式 cos_IPC_FLAG_FIFO 或 cos_IPC_FLAG_PRIO | +| mq | cos_mq_t | 出参 | 消息队列句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | + +### cos_mq_delete + +删除消息队列 + +原型 + +```C + +#include +cos_status_t cos_mq_delete(cos_mq_t mq); + +``` + +**描述** +删除一个消息队列。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mq | cos_mq_t | 入参 | 消息队列的句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | + +### cos_mq_deinit + +去初始化消息队列 + +原型 + +```C + +#include +cos_status_t cos_mq_deinit(cos_mq_t mq); + +``` + +**描述** +去初始化一个消息队列。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mq | cos_mq_t | 入参 | 消息队列的句柄 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +### cos_mq_send + +发送消息 + +原型 + +```C + +#include +cos_status_t cos_mq_send(cos_mq_t mq，void* buffer, size_t size); + +``` + +**描述** +发送消息，线程或者中断服务程序都可以给消息队列发送消息。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mq | cos_mq_t | 入参 | 消息队列的句柄 | +| buffer | void* | 入参 | 消息内容 | +| size | size_t | 入参 | 消息大小 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERROR_MQ_DELETED | 线程挂起时消息队列已被删除 | +| COS_ERROR_MQ_FULL | 消息队列已满 | + +### cos_mq_recive + +接收消息 + +原型 + +```C + +#include +cos_status_t cos_mq_recv(cos_mq_t mq，void* buffer, + size_t size，int32_t timeout); + +``` + +**描述** +当消息队列中有消息时，接收者才能接收消息，否则接收者会根据超时时间设置，或挂起在消息队列的等待线程队列上，或直接返回。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| mq | cos_mq_t | 入参 | 消息队列的句柄 | +| buffer | void* | 入参 | 消息内容 | +| size | size_t | 入参 | 消息大小 | +| timeout | int32_t | 入参 | 指定的超时时间 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| COS_ERROR_PARAM | 非法参数 | +| COS_ERROR_MQ_TIMEOUT | 超时 | +| COS_ERROR_PARAM | 消息队列已满 | +| COS_ERROR_MQ_DELETED | 线程挂起时消息队列已被删除 | diff --git a/osal/cosit/documentation/task_mm_timer.md b/osal/cosit/documentation/task_mm_timer.md new file mode 100644 index 0000000..74843a6 --- /dev/null +++ b/osal/cosit/documentation/task_mm_timer.md @@ -0,0 +1,1119 @@ +## 5.0 通用 +物联网操作系统各模块都会用到的通用的常量、类型、函数定义。 + +### 5.0.1 常量 +#### 5.0.1.1 COS_WAIT_FOREVER +```C +#define COS_WAIT_FOREVER ((cos_tick_t)-1) +``` +表示永久阻塞等待，直到获得系统资源（如互斥量，信号量，事件，队列消息等）才返回。 + +#### 5.0.1.2 COS_NO_WAIT +```C +#define COS_NO_WAIT (0x0U) +``` +表示非阻塞等待，当不能获得系统资源（如互斥量，信号量，事件，队列消息等）时不会等待，而是立即返回。 + +### 5.0.2 类型 +#### 5.0.2.1 cos_tick_t +```C +typedef uint64_t cos_tick_t +``` +系统tick数 + +### 5.0.3 函数 +#### 5.0.3.1 cos_ms_to_tick +把毫秒数转为系统tick数 + +**原型** +```C +cos_tick_t cos_ms_to_tick(uint64_t ms); +``` + +**描述** +把毫秒数转成系统tick数。在物联网操作系统中系统tick一般用于内核调度的基本单位，其频率在系统中是可以配置的。根据系统tick一般只能达到毫秒精度。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| ms | 入 | 毫秒数| + +**返回值** +转换得到的系统tick数 + +**注意** +可以在中断上下文中使用 + +**例子** + +#### 5.0.3.2 cos_tick_to_ms +把系统tick数转为毫秒数 + +**原型** +```C +uint64_t cos_tick_to_ms(cos_tick_t tick); +``` + +**描述** +把系统tick数转成毫秒数。在物联网操作系统中系统tick一般用于内核调度的基本单位，其频率在系统中是可以配置的。根据系统tick一般只能达到毫秒精度。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| tick | 入 | 系统tick数| + +**返回值** +转换得到的毫秒数 + +**注意** +可以在中断上下中使用 + +**例子** + +#### 5.0.3.3 cos_tick_get +把系统tick数转为毫秒数 + +**原型** +```C +cos_tick_t cos_tick_get(void); +``` + +**描述** +获取当前系统tick数。 + +**参数** + +**返回值** +获取到的当前系统tick数。 + +**注意** +可以在中断上下中使用 + +**例子** + + +## 5.1 任务管理 +任务可以认为是一段独享CPU的运行程序，而应用是完成特定功能的多个任务的集合。任务管理就是为多任务环境中的每个任务分配一个上下文（context）（上下文（context）是指当任务被调度执行的所必不可少的一组数据，包括前任务的CPU指令地址（PC指针），当前任务的栈空间，当前任务的CPU寄存器状态等），在任务相继执行过程中，将切出任务的信息保存在任务上下文中，将切入任务的上下文信息恢复，使其得以执行。为维护任务上下文、状态、栈等相关信息，操作系统内核为每个任务定义了一组数据结构，即任务控制块（Task Control Block），来存放这些信息。 任务调度负责将处理器资源分配给关键任务，让其优先运行。所以系统中的每个任务需要根据关键程度分配不同的优先级，那些执行关键操作的任务被赋予高优先级，而一些非关键性任务赋予低优先级。当系统发生调度时，高优先级任务可以抢占低优先级任务的处理器资源得到调度执行。系统在无任务可调度时，就运行空闲任务，其优先级最低。 任务被创建时，需要为任务指定执行体入口地址、栈大小、优先级等信息，创建过程中内核为任务分配任务控制块（TCB）。任务栈空间可以在任务创建时由用户程序指定，也可以由内核根据用户指定大小来动态分配。操作系统内核提供基于软件的栈溢出检测方法，用户可根据需要配置或关闭该功能。 + +### 5.1.1 常量 +#### 5.1.1.1 COS_TASK_OPTION_NORUN +```C +#define COS_TASK_OPTION_NORUN (0x1U << 0) +``` +用来指定创建一个新任务时任务属性的options参数，表示任务创建后处于挂起状态，不会被调度执行，直到被恢复。 +如果没有指定此选项（默认），任务创建后即处于就绪状态，等待调度运行。 + +#### 5.1.1.2 COS_TASK_PRIORITY_MAX +```C +#define COS_TASK_PRIORITY_MAX 100 +``` +最大任务优先级。任务优先级从0 ~ COS_TASK_PRIORITY_MAX优先级别递减，即COS_TASK_PRIORITY_MAX优先级最低。如内核在实现时，若其优先级级别小于`COS_TASK_PRIORITY_MAX`, 当应用传入的优先级超过内核实现的优先级时，内核应调整为应用可设置的最低优先级。 + +如果应用不关心任务的优先级，则可以使用`cos_task_attr_init`初始化为默认优先级即可，不同内核在实现时，其默认优先级可以不同。 + +#### 5.1.1.4 COS_TASK_SCHED_CFS +```C +#define COS_TASK_SCHED_CFS 0x0 +``` +完全公平调度策略（非实时）。采用完全公平调度算法，对任务进行调度。适用于任务比较多的场景，开发者不需要设计每个任务的合理优先级，由调度算法以完全公平的策略调度任务，但开发者可以微调任务的权重，以相对增加或减少任务的运行时间片。 + +**注意：不是所有内核在实现时都支持CFS调度策略** + +#### 5.1.1.5 COS_TASK_SCHED_FIFO +```C +#define COS_TASK_SCHED_FIFO 0x01 +``` +实时，FIFO调度策略。当同优先级的多个任务同时就绪时，按先进先出的顺序依次执行。 + +#### 5.1.1.6 COS_TASK_SCHED_RR +```C +#define COS_TASK_SCHED_RR 0x02 +``` +实时，Round-Robin调度策略. 当同优先级的多个任务同时就绪时，多个任务按时间片轮流执行。 + +### 5.1.2 类型 +#### 5.1.2.1 cos_task_t +```C +typedef void * cos_task_t +``` +任务的句柄，代表一个任务，调用任务创建函数后返回。可以通过句柄对任务进行操作，如挂起，删除等。 + +#### 5.1.2.2 cos_task_entry_t +```C +typedef void (*cos_task_entry_t) (void *); +``` +任务入口函数的原型。 + +#### 5.1.2.3 cos_task_attr_t +```C +typedef struct cos_task_attr { +       const char *name; +       size_t stack_size; +       int32_t priority; + cos_tick_t tick; + uint8_t sched_policy; + uint8_t cpu_bind; + uint8_t inited; +      uint32_t options; + void *reserved; +} cos_task_attr_t; +``` +任务的属性类型，在创建任务时传递给内核，内核根据这些属性创建任务。 + +| 元素 | 描述 | +| -------- | -------- | +| name | 任务名称(可以为NULL) | +| stack_size | 任务栈的大小（单位：Byte） | +| priority | 任务的优先级 | +| tick | 任务使用RR调度策略时，占用的系统tick数 | +| sched_policy | 调度策略，COS_TASK_SCHED_RR/COS_TASK_SCHED_FIFO/COS_TASK_SCHED_CFS | +| cpu_bind | 绑定的CPU号，适用于多核系统 | +| inited | 标识该结构是否被初始化 | +| options | 任务创建时的选项 | +| reserved | 预留字段（可扩展） | + +### 5.1.3 函数 +#### 5.1.3.1 cos_task_attr_init +初始化一个任务属性 + +**原型** +```C +void cos_task_attr_init(cos_task_attr_t *attr); +``` + +**描述** +初始化一个任务属性，为任务属性设置默认值。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| attr | 入 | 任务属性的句柄| + +**返回值** +无 + +**注意** +此函数与创建任务同时使用。 +不同内核实现的默认值可能不同。 + +**例子** + +#### 5.1.3.2 cos_task_create +创建一个新的任务 + +**函数原型** +```C +cos_status_t cos_task_create(cos_task_t *task, cos_task_entry_t fn, void *arg, cos_task_attr_t *attr); +``` + +**描述** +创建一个新任务并初始化，新任务的句柄由参数task返回，通过任务句柄task对新任务进行后续的操作。 +新任务成功创建后，新任务会进入就绪队列等待调度执行。如果选项 COS_TASK_OPTION_NORUN被指定，则任务创建后处于挂起状态，不会被调度执行，需要应用恢复该任务后，才能进入就绪队列等待调度执行。 +当被调度到时从入口函数`fn`开始运行。从任务入口函数返回，代表此任务退出，系统会清理该任务的资源。 +任务的属性`attr`应使用`cos_task_attr_init`初始化。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 出 | 新任务的句柄，后续对此任务的操作通过该句柄进行。| +| fn | 入 | 新任务的入口函数，新任务从此函数开始运行。| +| arg | 入 | 新任务的入口函数的参数。| +| attr | 入 | 新任务的属性| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_TASK_NOMEM | 内存不足 | +| COS_ERR_ISR | 在中断上下文中调用 | + +**注意** +此函数不能在中断上下文中使用。 + +**例子** +```C +#include +#include +#include +  +static void cos_task_test_entry(void *arg) +{ +    printf("%s:%d:new task is running.\n", __func__, __LINE__); +    return; +} +  +int cos_task_create_example() +{ +    cos_status_t ret; +    cos_task_t task; +    cos_task_attr_t attr; + +  cos_task_attr_init(&attr);  +    ret = cos_task_create(&task, cos_task_test_entry, NULL, &attr) +    if (ret != COS_OK) { +        printf("%s:%d: create task fail ret:%d\n", __func__, __LINE__, ret); +        return -1; +    } +  +    return 0; +} +``` + +#### 5.1.3.3 cos_task_delete +删除一个任务 + +**原型** +```C +cos_status_t cos_task_delete(cos_task_t task); +``` + +**描述** +主动删除一个任务回收其资源。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_ISR | 在中断上下文中调用 | +| COS_ERR_PERM | 没有权限删除任务，如删除idle任务 | + +**注意** +此函数不能在中断上下文中使用。 +不能删除系统idle任务。 + +**例子** + +#### 5.1.3.4 cos_task_init +初始化一个任务 + +**函数原型** +```C +cos_status_t cos_task_init(cos_task_t task, cos_task_entry_t fn, void *arg, cos_task_attr_t *attr, void *stack_buf); +``` + +**描述** +初始化一个任务。与创建任务类似，区别是调用者为新任务的控制块分配内存，其大小为任务控制块的数据结构大小，不同内核其任务控制块大小不同。 +通过参数`task`指定任务的控制块地址。 调用者还需要为新任务分配栈内存空间，并通过参数`stack_buf`指定栈内存空间地址，栈空间大小通过`attr`中的stack_size传递。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 新任务控制块句柄，函数对该任务进行初始化| +| fn | 入 | 新任务的入口函数，新任务从此函数开始运行。| +| arg | 入 | 新任务的入口函数的参数。| +| attr | 入 | 新任务的属性| +| stack_buf | 入 | 调用者指定的任务栈空间| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_ISR | 在中断上下文中调用 | + +**注意** +此函数不能在中断上下文中使用。 + +#### 5.1.3.5 cos_task_deinit +反初始化一个任务 + +**原型** +```C +cos_status_t cos_task_deinit(cos_task_t task); +``` + +**描述** +反初始化一个任务。与`cos_task_init`配套使用，销毁其初始化过的任务，把此任务置为销毁状态。如果该任务销毁前处于就绪状态，会把该任务从系统就绪队列中移除。 +根据互斥锁的类型（鲁棒性互斥锁），还会释放其拥有的互斥锁，导致唤醒等待该锁的任务。 但不会释放任务控制块task和任务栈的内存空间，这部分内存应由调用者负责释放。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_ISR | 在中断上下文中调用 | +| COS_ERR_PERM | 没有权限反初始化任务，如idle任务 | + +**注意** +此函数不能在中断上下文中使用。 +不能反初始化系统idle任务。 + +#### 5.1.3.6 cos_task_exit +退出当前任务 + +**原型** +```C +void cos_task_exit(int32_t status); +``` + +**描述** +主动退出当前任务，使系统回收该任务的资源。其作用与从该任务的入口函数返回相同。参数`status`作为后续扩展使用，目前并不支持获取一个任务退出时的状态码。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| status | 入 | 任务退出的状态码（未使用）| + +**返回值** +此函数导致当前任务退出，不会返回。 + +**注意** +此函数不能在中断上下文中使用。 +目前并不支持获取一个任务退出时的状态码。 + +**例子** + +#### 5.1.3.7 cos_task_suspend +挂起一个任务 + +**原型** +```C +cos_status_t cos_task_suspend(cos_task_t task); +``` + +**描述** +挂起一个任务，暂停该任务的执行。可以挂起自身或其他任务，但不允许挂起系统idle任务。当挂起系统其他内置任务时请谨慎，可能会引起系统错误。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_PERM | 没有权限挂起任务，如挂起idle任务 | + +**注意** +可以在中断上下文中使用 + +**例子** + +#### 5.1.3.8 cos_task_resume +恢复一个任务 + +**原型** +```C +cos_status_t cos_task_resume(cos_task_t task); +``` + +**描述** +恢复一个任务，使其处于就绪状态，等待调度执行。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.9 cos_task_yield +当前任务让出CPU + +**原型** +```C +cos_status_t cos_task_yield(void); +``` + +**描述** +使当前正在运行的任务让出CPU，并把当前任务置于其静态优先级的就绪队列的末尾。重新调度，其他任务得到CPU运行。注意根据调度策略，如果该任务是其静态优先级的就绪队列中唯一任务，它会被再次调度到，继续运行。 + +**参数** +无 + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.10 cos_task_self +获取当前任务自身的句柄 + +**原型** +```C +cos_task_t cos_task_self(void); +``` + +**描述** +返回当前任务自身的句柄，用于对自身任务的操作，如挂起和恢复等。 + +**参数** +无 + +**返回值** +函数总是执行成功并返回当前任务自身的句柄。 + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.11 cos_task_get_name +获取一个任务的名称 + +**原型** +```C +cos_status_t cos_task_get_name(cos_task_t task, char *buf, size_t buf_size); +``` +**描述** +返回一个任务的名称，注意调用者应该为存放任务名称分配足够的内存，并把内存首地址和大小通过参数buf和buf_size传入。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| +| buf | 出 | 存放任务名称的内存| +| buf_size | 入 | 存放任务名称的内存大小| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.12 cos_task_find +根据名称查找任务 + +**原型** +```C +cos_task_t cos_task_find(const char *name); +``` + +**描述** +根据任务名称`name`查找任务，若能找到则返回任务的句柄，不能找到则返回`NULL`。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| name | 入 | 任务的名称| + +**返回值** +函数执行成功返回所找到的任务的句柄，失败则返回`NULL`。 + +**注意** +可以在中断上下文中使用。 +当系统中存在多个具有相同名称的任务时，函数会执行成功，但返回哪一个任务的句柄是不确定的，不同的内核实现会有所不同。 + +**例子** + +#### 5.1.3.13 cos_task_sleep +使当前任务睡眠一段时间 + +**原型** +```C +cos_status_t cos_task_sleep(cos_tick_t tick); +``` + +**描述** +使当前任务睡眠`tick`个系统tick的时间，等时间超期或被唤醒后再次进入就绪状态，等待调度执行。 +如果`tick`为0，则等同于`cos_task_yield`。如果`tick`为`COS_WAIT_FOREVER`, 则等同于`cos_task_suspend`。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| tick | 入 | 系统tick个数| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。被提前唤醒时则返回剩余的tick数。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.14 cos_task_wakeup +唤醒一个任务 + +**原型** +```C +cos_status_t cos_task_wakeup(cos_task_t task); +``` + +**描述** +唤醒一个任务。可以用来提前唤醒一个睡眠的任务。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.15 cos_task_get_priority +获取一个任务的优先级 + +**原型** +```C +cos_status_t cos_task_get_priority(cos_task_t task, uint8_t *priority); +``` + +**描述** +获取一个任务的优先级，可以是自身或其他任务。获取的是任务此时的动态优先级，不一定与其创建时指定的静态优先级相同，如任务此时有优先级继承发生。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| +| priority | 出 | 获取到的任务动态优先级| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.16 cos_task_set_priority +设置一个任务的优先级 + +**原型** +```C +cos_status_t cos_task_set_priority(cos_task_t task, uint8_t priority); +``` + +**描述** +设置一个任务的优先级，可以是自身或其他任务。改变的是任务的静态优先级。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| +| priority | 入 | 任务静态优先级| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.17 cos_task_get_time_slice +获取一个RR调度策略的任务的剩余时间片 + +**原型** +```C +cos_status_t cos_task_get_time_slice(cos_task_t task, cos_tick_t *time_slice); +``` + +**描述** +获取一个使用RR调度策略的任务在本次轮转中剩余时间片。此函数仅适用于采用RR调度策略的任务， 对于其他任务，剩余时间片返回0. + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| +| time_slice | 出 | 获取到的任务的剩余时间片| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +#### 5.1.3.18 cos_task_set_time_slice +设置一个RR调度任务的时间片 + +**原型** +```C +cos_status_t cos_task_set_time_slice(cos_task_t task, cos_tick_t time_slice); +``` + +**描述** +设置一个使用RR调度策略的任务在一次轮转中所分配的时间片。此函数仅适用于采用RR调度策略的任务， 对于其他任务，返回错误。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| task | 入 | 任务的句柄| +| time_slice | 入 | RR调度任务的时间片| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +可以在中断上下文中使用。 + +**例子** + +## 5.2 内存管理 +内存管理实现从系统堆内存中动态分配和释放内存，向应用提供动态分配和释放内存的API。 + +### 5.2.1 cos_malloc +申请一块连续的内存 + +**原型** +```C +void *cos_malloc(size_t size) +``` + +**描述** +从系统堆中申请一块`size`大小连续的内存，成功返回申请到内存的首地址，失败返回NULL。 + +**参数** +| 参数名称 | 参数方向 | 描述 | +| -------- | -------- | -------- | +| size | 入 | 想申请内存的大小（单位：Byte） | + +**返回值** +函数执行成功返回申请到内存的首地址，失败则返回NULL。 + +**注意** +此函数不能在中断上下文中使用。 + +**例子** + +### 5.2.2 cos_realloc +改变一块内存的大小 + +**原型** +```C +void *cos_realloc(void *ptr, size_t new_size) +``` + +**描述** +改变一块内存`ptr`的大小，`ptr`应该是之前动态申请内存的返回值。新的内存大小可能扩大或缩小，扩大时原有内存大小的内容保持不变且新增加的内存没有初始化。缩小时，被保留的内存的内容保持不变。如果参数`ptr`为NULL， 不论new_size为多少，则等于cos_malloc(new_size)，如果参数`new_size`为0，则等于cos_free(prt)。如果该函数返回的新的内存首地址与原有地址不同，则原有内存被释放。 + +**参数** +| 参数名称 | 参数方向 | 描述 | +| -------- | -------- | -------- | +| ptr | 入 | 之前动态申请到的内存首地址 | +| new_size | 入 | 内存新大小 | + +**返回值** +函数执行成功返回新申请到内存的首地址，失败则返回NULL。 + +**注意** +此函数不能在中断上下文中使用。 + +**例子** + +### 5.2.3 cos_calloc +申请多块连续的内存 + +**原型** +```C +void *cos_calloc(size_t count, size_t size) +``` + +**描述** +从系统堆中申请`count`个长度为`size`的连续的内存，最终申请到内存大小为`count * size`个字节。 + +**参数** +| 参数名称 | 参数方向 | 描述 | +| -------- | -------- | -------- | +| count | 入 | 申请内存块的个数 | +| size | 入 | 每个内存块的大小 | + +**返回值** +函数执行成功返回申请到内存的首地址，失败则返回NULL。 + +**注意** +此函数不能在中断上下文中使用。 + +**例子** + +### 5.2.4 cos_free +释放内存 + +**原型** +```C +void cos_free(void *ptr) +``` + +**描述** +释放由参数`ptr`指向的一块内存，ptr应该是之前动态申请函数的返回值。 + +**参数** +| 参数名称 | 参数方向 | 描述 | +| -------- | -------- | -------- | +| ptr | 入 | 动态申请到的内存首地址 | + +**返回值** +无 + +**注意** +此函数不能在中断上下文中使用。 + +**例子** + +### 5.2.5 cos_malloc_align +申请内存并按要求地址对齐 + +**原型** +```C +int cos_malloc_align(void **memptr, size_t size, size_t alignment) +``` + +**描述** +从系统堆内存中申请`size`字节的连续内存，并按`alignment`字节对齐，申请到的内存首地址由\*memptr返回。如果参数size为0，则函数立即返回错误码，\*memptr为NULL。 参数alignment应该是`sizeof(void*)`的倍数且是2的幂，否则立即返回错误，\*memptr为NULL。 释放内存通过cos_free函数释放。 + +**参数** +| 参数名称 | 参数方向 | 描述 | +| -------- | -------- | -------- | +| memptr | 出 | 返回申请到的内存首地址 | +| size | 入 | 想申请内存的大小（单位：Byte） | +| alignment | 入 | 内存地址对齐大小（单位：Byte） | + +**返回值** +函数执行成功返回COS_OK, 所申请到内存的首地址由参数\*memptr返回。失败则返回错误码，同时参数\*memptr为NULL。 + +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_NOMEM | 内存不足 | + +**注意** +此函数不能在中断上下文中使用。 + +**例子** + +## 5.3 软件定时器 +软件定时器是由内核提供的隔一段时间单次或周期性触发执行应用函数的功能。应用可以通过设置回调函数，和定时器的周期等参数，让内核周期性地执行应用回调函数。 软件定时器一般由内核的定时器任务，基于系统tick，检查定时器是否超期，超期则在定时器任务的上下文中执行应用回调函数，这是其与硬件定时器不同之处。 + +### 5.3.1 常量 +#### 5.3.1.1 COS_TIMER_OPTION_ACTIVATE +创建时激活选项 + +```C +#define COS_TIMER_OPTION_ACTIVATE (0x1u << 0) +``` +定时器被创建后即开始启动。 + +#### 5.3.1.2 COS_TIMER_OPTION_DEACTIVATE +创建时不激活选项（**默认**） + +```C +#define COS_TIMER_OPTION_DEACTIVATE (0x1u << 1) +``` +定时器被创建后不会立即启动，需要被再次主动调用启动函数来启动。 + +### 5.3.2 类型 +#### 5.3.2.1 cos_timer_t +软件定时器句柄 + +```C +typedef void * cos_timer_t +``` +#### 5.3.2.2 cos_timer_cb_t +软件定时器的回调函数类型 + +```C +typedef void (*cos_timer_cb_t)(void *arg) +``` + +### 5.3.3 函数 +#### 5.3.3.1 cos_timer_create +创建一个定时器 + +**原型** +```C +cos_status_t cos_timer_create(cos_timer_t *timer, const char *name, cos_timer_cb_t cb, void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options); +``` + +**描述** +创建一个定时器，当定时器超期时内核会执行回调函数`cb`， 并传入参数`arg`。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 出 | 定时器句柄| +| name | 入 | 定时器名称(可以为NULL)| +| cb | 入 | 定时器的回调函数| +| arg | 入 | 定时器的回调函数的参数| +| initial | 入 | 定时器的初始定时时间，即从启动到第一次触发的时间间隔，单位：tick个数| +| period | 入 | 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发| +| options | 入 | 定时器的选项，如创建时是否激活 `COS_TIMER_OPTION_ACTIVATE/COS_TIMER_OPTION_DEACTIVATE`| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | +| COS_ERR_NOMEM | 内存不足 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.2 cos_timer_delete +删除一个定时器 + +**原型** +```C +cos_status_t cos_timer_delete(cos_timer_t timer); +``` + +**描述** +删除一个定时器。系统会先停止该定时器，然后删除回收其资源。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.3 cos_timer_init +初始化一个定时器 + +**原型** +```C +cos_status_t cos_timer_init(cos_timer_t timer, const char *name, cos_timer_cb_t cb, void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options); +``` + +**描述** +初始化一个定时器，当定时器超期时内核会执行回调函数`cb`， 并传入参数`arg`。与创建一个定时器类似，区别是定时器的控制块内存时由调用者传入的，一般用于应用希望静态分配内存的场景。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| +| name | 入 | 定时器名称| +| cb | 入 | 定时器的回调函数| +| arg | 入 | 定时器的回调函数的参数| +| initial | 入 | 定时器的初始定时时间，即从启动到第一次触发的时间间隔，单位：tick个数| +| period | 入 | 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发| +| options | 入 | 定时器的选项，如创建时是否激活 `COS_TIMER_OPTION_ACTIVATE/COS_TIMER_OPTION_DEACTIVATE`| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.4 cos_timer_deinit +反初始化一个定时器 + +**原型** +```C +cos_status_t cos_timer_deinit(cos_timer_t timer); +``` + +**描述** +反初始化一个定时器。系统会先停止该定时器，从系统定时器列表中移除。但不会释放`timer`的内存空间，应由调用者释放。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.5 cos_timer_start +启动一个定时器 + +**原型** +```C +cos_status_t cos_timer_start(cos_timer_t timer); +``` + +**描述** +启动一个定时器，内核开始计时，直到定时器超期时执行应用设置的回调函数。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.6 cos_timer_stop +停止一个定时器 + +**原型** +```C +cos_status_t cos_timer_stop(cos_timer_t timer); +``` + +**描述** +停止一个定时器 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.7 cos_timer_change +修改一个定时器 + +**原型** +```C +cos_status_t cos_timer_change(cos_timer_t timer, cos_tick_t initial, cos_tick_t period); +``` + +**描述** +修改一个定时器。一般用于修改其周期性定时时间，如果该定时器创建后还还有启动，也可以修改其初始定时时间。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| +| initial | 入 | 定时器的初始定时时间，即从启动到第一次触发的时间间隔，单位：tick个数| +| period | 入 | 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** + +#### 5.3.3.8 cos_timer_get_time +获取一个定时器的时间 + +**原型** +```C +cos_status_t cos_timer_get_time(cos_timer_t timer, cos_tick_t *remaining, cos_tick_t *period); +``` + +**描述** +返回一个定时器的信息，包括离下次触发还剩余的时间（系统tick），和周期触发的时间间隔（系统tick）。 + +**参数** +| 参数名称 | 参数方向 |描述 | +| -------- | -------- | -------- | +| timer | 入 | 定时器句柄| +| remaining | 出 | 离下次触发还剩余的时间，单位：tick个数| +| period | 出 | 周期触发的时间间隔，单位：tick个数。0：代表单次触发| + +**返回值** +函数执行成功返回COS_OK，失败则返回错误码（均为负值）。 +| 错误码 | 描述 | +| -------- | -------- | +| COS_ERR | 未知错误 | +| COS_ERR_PARAM | 非法参数 | + +**注意** +不可以在中断上下文中使用。 + +**例子** diff --git a/osal/cosit/documentation/work_queue.md b/osal/cosit/documentation/work_queue.md new file mode 100644 index 0000000..097a0ea --- /dev/null +++ b/osal/cosit/documentation/work_queue.md @@ -0,0 +1,200 @@ +# 工作队列 + +工作队列（workqueue）是一种转移任务执行环境的工具，例如当系统产生一个中断时，我们可以在中断处理函数里做一些紧急地操作，然后将另外一些不那么紧急，而且需要一定时间的任务封装成函数交给工作队列执行，此时该函数的执行环境就从 中断环境 变成了 线程环境，即中断处理 “下半部”。 + +## 类型 + +```C +typedef struct cos_workqueue* cos_wq_t; +``` + +工作队列控制块，工作队列控制块是操作系统用于管理工作队列的一个数据结构，由结构体cos_workqueue表示，cos_wq_t是工作队列的句柄，工作队列结构体主要保存了当前系统工作队列的相关信息，如:当前工作项，工作队列的链表，工作队列所使用的线程等。 + +```C +typedef struct cos_work* cos_work_t; +``` + +工作项控制块，工作项控制块用于管理该任务，保存了该任务相关的信息，如：任务函数，用户数据等，当该工作项被执行时就会调用该任务函数。 + +```C +typedef void cos_work_handle_t(void *arg); +``` + +工作项控制块，工作项控制块用于管理该任务，保存了该任务相关的信息，如：任务函数，用户数据等，当该工作项被执行时就会调用该任务函数。 + +## 函数 + +### cos_work_init + +初始化工作项 + +原型 + +```C + +#include +cos_status_t cos_work_init(cos_work_t work, cos_work_handle_t work_func, void *work_data); + +``` + +**描述** +该接口初始化 work 指针指向的工作项，并绑定回调函数 work_func 以及用户自定义数据 work_data。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| work | cos_work_t | 入参 | 工作项 | +| work_func | cos_work_handle_t | 入参 | 工作项的回调函数 | +| work_data | size_t | 入参 | 用户自定义数据，回调函数参数 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | + +### cos_work_dowork + +触发work + +原型 + +```C + +#include +cos_status_t cos_work_dowork(cos_work_t work, cos_tick_t time); + +``` + +**描述** +work触发函数（由系统默认工作队列来执行）。若 time 大于 0，则提交过程会延时 time 个 ticks 。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| work | cos_work_t | 入参 | 工作项 | +| time | cos_tick_t | 入参 | 提交延时，以 tick 为单位 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | + +### cos_work_submit + +向 queue 提交work + +原型 + +```C + +#include +cos_status_t cos_work_submit(cos_wq_t wq, cos_work_t work, cos_tick_t time); + +``` + +**描述** +将 work 指向的工作项提交到 queue 指向的工作队列中，若 time 大于 0，则该提交延时 time 个 tick 之后执行。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| wq | cos_wq_t | 入参 | 工作队列 | +| work | cos_work_t | 入参 | 工作项 | +| time | cos_tick_t | 入参 | 提交延时，以 tick 为单位 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | + +### cos_work_cancel + +取消指定工作项 + +原型 + +```C + +#include +cos_status_t cos_work_cancel(cos_wq_t queue, cos_work_t work); + +``` + +**描述** +从 queue 指向的工作队列中将 work 指向的工作项移除。 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| queue | cos_wq_t | 入参 | 工作队列 | +| work | cos_work_t | 入参 | 工作项 | + + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | +| cos_ERROR_BUSY | 该工作项正在执行 | + +### cos_workqueue_create + +工作队列创建函数 + +原型 + +```C + +#include +cos_status_t cos_workqueue_create(cos_wq_t* wq, const char *name， uint16_t stack_size, uint8_t priority); + +``` + +**描述** +该函数创建并初始化一个工作队列，利用参数 name，stack_size 和 priority 创建工作队列内部线程，最终返回创建的工作队列。下表描述了该函数的输入参数与返回值 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| wq | cos_wq_t | 出参 | 工作队列控制块 | +| name | const char * | 入参 | 线程名字 | +| stack_size | uint16_t | 入参 | 线程栈大小 | +| priority | uint8_t | 入参 | 线程优先级 | + + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | + +### cos_workqueue_destroy + +工作队列销毁函数 + +原型 + +```C + +#include +cos_status_t cos_workqueue_destroy(cos_wq_t wq); + +``` + +**描述** +销毁指定工作队列 + +**参数** +| 参数名称 | 参数类型 | 参数方向 | 描述 | +| ----------- | ----------- | ------------------ | ------------------ | +| wq | cos_wq_t | 入参 | 工作队列控制块 | + +**返回值** +函数执行成功返回cos_OK，失败则返回错误码（均为负值）。 +| 参数名称 | 描述 | +| ----------- | ------------------ | +| cos_ERROR_PARAM | 非法参数 | + diff --git a/osal/cosit/include/cosit.h b/osal/cosit/include/cosit.h new file mode 100644 index 0000000..b29f53b --- /dev/null +++ b/osal/cosit/include/cosit.h @@ -0,0 +1,1612 @@ +/* + * Copyright (C) XXXX + * + * SPDX-License-Identifier: XXXX + * + * Version: 1.1.1 + * + * Change log: + * + * Date Author Note + * 2022-06-15 all first version + * 2022-07-12 Mculover666 Add cos_sem_release_all and cos_tick_get API. + * 2022-07-26 Mculover666 Fix the type error of sem. + */ + +#ifndef _COSIT_H +#define _COSIT_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + + +/** + * @addtogroup cos_status + * COSIT标准状态码 + * @{ + */ +/** + * 状态码格式说明： + * 0:表示成功，错误码均为负值，错误码用16位（不算符号位）的16进制表示。 + * 其中高1~4位：标识模块， 其余为错误码（后续也可扩展为其他标识）。 + * 高1~4 模块名称 + * 0 通用错误 + * 1 任务管理 + * 2 内存管理 + * 3 软件定时器 + * 4 互斥量 + * 5 信号量 + * 7 事件 + * 8 消息队列 + * 9 邮箱 + * A 工作队列 + */ +#define COS_OK 0 /**< 成功 */ + +/* 通用错误码 */ +#define COS_ERR (-0x0001) /**< 未知错误 */ +#define COS_ERR_PARAM (-0x0002) /**< 非法参数 */ +#define COS_ERR_NOMEM (-0x0003) /**< 内存不足 */ +#define COS_ERR_TIMEOUT (-0x0003) /**< 超时 */ +#define COS_ERR_ISR (-0x0004) /**< 不允许在中断上下文中使用 */ +#define COS_ERR_PERM (-0x0005) /**< 权限不允许 */ + +/* 互斥量特有错误码 */ +#define COS_ERR_MUTEX_NOT_OWNER (-0x4001) /**< 不是互斥锁的所有者 */ +#define COS_ERR_MUTEX_NESTING (-0x4002) /**< 已经拥有互斥锁，导致嵌套但并未指定嵌套选项 */ + +/* 邮箱特有错误码 */ +#define COS_ERR_MB_FULL (-0x9001) + +/** + * @} + */ + + +/** + * 表示永久阻塞等待，直到获得系统资源（如互斥量，信号量，事件，队列消息等）才返回。 + */ +#define COS_WAIT_FOREVER ((cos_tick_t)-1) + +/** + * 表示非阻塞等待，当不能获得系统资源（如互斥量，信号量，事件，队列消息等）时不会等待，而是立即返回。 + */ +#define COS_NO_WAIT (0x0U) + +/** + * @addtogroup cos_timer + * 提供软件定时器相关的标准定义 + * @{ + */ +#define COS_TIMER_OPTION_ACTIVATE (0x1u << 0) /**< 创建时激活选项 */ +#define COS_TIMER_OPTION_DEACTIVATE (0x1u << 1) /**< 创建时不激活选项 */ +/** + * @} + */ + +/** + * @addtogroup cos_mutex + * 提供互斥锁相关的标准定义 + * @{ + */ +#define COS_MUTEX_NEST (0x1u << 0) /**< 开启嵌套锁支持 */ +/** + * @} + */ + +/** + * @addtogroup cos_sem + * 提供信号量相关的标准定义 + * @{ + */ + +/** + * 用来指定创建一个新的信号量时的最大值，表示信号量无最大值。 + */ +#define COS_SEM_NO_MAX ((uint32_t)-1) + +/** + * @} + */ + +/** + * @addtogroup cos_event + * 提供事件相关的标准定义 + * @{ + */ + +/** + * 用来指定等待事件和释放事件时的选项。 + */ +#define COS_EVENT_WAIT_ANY (0x1u << 0) /**< 等待任意一个事件 */ +#define COS_EVENT_WAIT_ALL (0x1u << 1) /**< 等待所有事件 */ +#define COS_EVENT_WAIT_CLR (0x1u << 2) /**< 等待到事件后清除该事件 */ +#define COS_EVENT_RELEASE_KEEP (0x1u << 3) /**< 释放事件后是否保留该事件 */ + +/** + * @} + */ + +typedef int32_t cos_status_t; /**< 状态码类型 */ + +typedef uint64_t cos_tick_t; /**< 系统tick类型 */ + + +/** + * @addtogroup cos_mb + * 提供邮箱相关的标准定义 + * @{ + */ +typedef void * cos_mb_t; /**< 邮箱句柄 */ + +#define COS_IPC_FLAG_FIFO 0 +#define COS_IPC_FLAG_PRIO 1 +/** + * @} + */ + +/** + * @addtogroup cos_mq + * 提供消息队列相关的标准定义 + * @{ + */ +typedef void * cos_mq_t; /**< 邮箱句柄 */ +/** + * @} + */ + +/** + * @addtogroup cos_wq + * 提供工作队列相关的标准定义 + * @{ + */ +typedef void * cos_wq_t; /**< 工作队列句柄 */ +typedef void * cos_work_t; /**< 工作项句柄 */ +typedef void (*cos_work_handle_t) (void *); /**< 任务入口函数的原型。*/ +/** + * @} + */ + +/** + * 用来指定创建一个新任务时任务属性的options参数，表示任务创建后处于挂起状态，不会被调度执行， + * 直到被恢复。如果没有指定此选项（默认），任务创建后即处于就绪状态，等待调度运行。 + */ +#define COS_TASK_OPTION_NORUN (0x1U << 0) + +/** + * 最大任务优先级。任务优先级从0 ~ COS_TASK_PRIORITY_MAX优先级别递减，即COS_TASK_PRIORITY_MAX优先级最低。 + * 如内核在实现时，若其优先级级别小于`COS_TASK_PRIORITY_MAX`, 当应用传入的优先级超过内核实现的优先级时， + * 内核应调整为应用可设置的最低优先级。如果应用不关心任务的优先级，则可以使用`cos_task_attr_init`初始化为 + * 默认优先级即可，不同内核在实现时，其默认优先级可以不同。 + */ +#define COS_TASK_PRIORITY_MAX 100 + +/** + * 完全公平调度策略（非实时）。采用完全公平调度算法，对任务进行调度。适用于任务比较多的场景， + * 开发者不需要设计每个任务的合理优先级，由调度算法以完全公平的策略调度任务，但开发者可以微调任务的权重， + * 以相对增加或减少任务的运行时间片。 + */ +#define COS_TASK_SCHED_CFS 0x0 + +/** + * 实时，FIFO调度策略。当同优先级的多个任务同时就绪时，按先进先出的顺序依次执行。 + */ +#define COS_TASK_SCHED_FIFO 0x01 + +/** + * 实时，Round-Robin调度策略. 当同优先级的多个任务同时就绪时，多个任务按时间片轮流执行。 + */ +#define COS_TASK_SCHED_RR 0x02 + +/** + * @} + */ + +/** + * @addtogroup cos_task + * 提供任务管理相关的标准定义 + * @{ + */ + +/** + * 任务的句柄，代表一个任务，调用任务创建函数后返回。可以通过句柄对任务进行操作，如挂起，删除等。 + */ +typedef void * cos_task_t; + +typedef void (*cos_task_entry_t) (void *); /**< 任务入口函数的原型。*/ + +typedef struct cos_task_attr { + const char *name; /**< 任务名称(可以为NULL) */ + size_t stack_size; /**< 任务栈的大小（单位：Byte） */ + uint8_t priority; /**< 任务的优先级 */ + cos_tick_t tick; /**< 任务使用RR调度策略时，占用的系统tick数 */ + uint8_t sched_policy; /**< 调度策略 @ref COS_TASK_SCHED_RR / @ref COS_TASK_SCHED_FIFO / @ref COS_TASK_SCHED_CFS */ + uint8_t cpu_bind; /**< 绑定的CPU号，适用于多核系统 */ + uint8_t inited; /**< 标识该结构是否被初始化 */ + uint32_t options; /**< 任务创建时的选项 */ + void *reserved; /**< 预留字段（可扩展）*/ +} cos_task_attr_t; +/** + * @} + */ + + +/** + * @addtogroup cos_timer + * 提供软件定时器相关的标准定义 + * @{ + */ +typedef void * cos_timer_t; /**< 软件定时器句柄 */ + +typedef void (*cos_timer_cb_t)(void *arg); /**< 软件定时器的回调函数类型 */ +/** + * @} + */ + +/** + * @addtogroup cos_mutex + * 提供互斥锁相关的标准定义 + * @{ + */ +typedef void * cos_mutex_t; /**< 互斥锁句柄 */ + +/** + * @} + */ + +/** + * @addtogroup cos_sem + * 提供信号量相关的标准定义 + * @{ + */ +typedef void * cos_sem_t; /**< 信号量句柄 */ + +/** + * @} + */ + +/** + * @addtogroup cos_event + * 提供事件相关的标准定义 + * @{ + */ +typedef void * cos_event_t; /**< 事件句柄 */ + +typedef uint32_t cos_event_flag_t; /**< 事件标志 */ + +/** + * @} + */ + +/** + * @brief 毫秒数转为系统tick数 + * + * 把毫秒数转成系统tick数。在物联网操作系统中系统tick一般用于内核调度的基本单位， + * 其频率在系统中是可以配置的。根据系统tick一般只能达到毫秒精度。 + * + * @param[in] ms 毫秒数 + * + * @note 可以在中断上下文中使用。 + * + * @return 总是成功，返回转换得到的系统tick数 + */ +cos_tick_t cos_ms_to_tick(uint64_t ms); + +/** + * @brief 系统tick数转为毫秒数 + * + * 把系统tick数转成毫秒数。在物联网操作系统中系统tick一般用于内核调度的基本单位， + * 其频率在系统中是可以配置的。根据系统tick一般只能达到毫秒精度。 + * + * @param[in] tick 系统tick数 + * + * @note 可以在中断上下文中使用。 + * + * @return 总是成功，返回转换得到的毫秒数 + */ +uint64_t cos_tick_to_ms(cos_tick_t tick); + +/** + * @brief 获取当前系统tick数 + * + * @note 可以在中断上下文中使用。 + * + * @return 总是成功，返回得到的当前系统tick数 + */ +cos_tick_t cos_tick_get(void); + +/** + * @addtogroup cos_task + * 提供任务管理相关的标准定义 + * @{ + */ + +/** + * @brief 初始化一个任务属性 + * + * 初始化一个任务属性，为任务属性设置默认值。 + * + * @param[in] attr 任务属性的句柄 + * + * @note 可以在中断上下文中使用。 + * @note 此函数与创建任务同时使用。 + * @note 每个内核实现的默认值可能不同。 + * + * @return 无 + */ +void cos_task_attr_init(cos_task_attr_t *attr); + +/** + * @brief 创建新任务 + * + * 创建一个新任务并初始化，新任务的句柄由参数 @c task 返回，通过任务句柄 @c task 对新任务进行后续的操作。 + * 新任务成功创建后，会进入就绪队列等待调度执行。如果选项 @ref COS_TASK_OPTION_NORUN 被指定， + * 则任务创建后处于挂起状态，不会被调度执行，需要应用恢复该任务后，才能进入就绪队列等待调度执行。 + * 当被调度到时从入口函数fn开始运行。从任务入口函数返回，代表此任务退出，系统会清理该任务的资源。 + * 该函数在创建时内部会动态分配需要的内存，如果不想使用动态内存，请使用 @ref cos_task_init 。 + * + * @param[out] task 新任务的句柄，后续对此任务的操作通过该句柄进行 + * @param[in] fn 新任务的入口函数，新任务从此函数开始运行 + * @param[in] arg 新任务的入口函数的参数 + * @param[in] attr 新任务的属性 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + * + * @see cos_task_init + */ +cos_status_t cos_task_create(cos_task_t *task, cos_task_entry_t fn, void *arg, cos_task_attr_t *attr); + +/** + * @brief 删除任务 + * + * 主动删除一个任务回收其资源。 + * + * @param[in] task 任务的句柄 + * + * @note 不可以在中断上下文中使用。 + * @note 不能删除idle任务。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_delete(cos_task_t task); + +/** + * @brief 初始化一个任务 + * + * 初始化一个任务。与创建任务类似，区别是调用者为新任务的控制块分配内存，其大小为任务控制块的数据结构大小， + * 不同内核其任务控制块大小不同。通过参数 @c task 指定任务的控制块地址。 调用者还需要为新任务分配栈内存空间， + * 并通过参数 @c stack_buf 指定栈内存空间地址，栈空间大小通过 @c attr 中的stack_size传递。 + * + * @param[in] task 新任务的句柄，后续对此任务的操作通过该句柄进行 + * @param[in] fn 新任务的入口函数，新任务从此函数开始运行 + * @param[in] arg 新任务的入口函数的参数 + * @param[in] attr 新任务的属性 + * @param[in] stack_buf 调用者指定的任务栈空间 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + * + * @see cos_task_init + */ +cos_status_t cos_task_init(cos_task_t task, cos_task_entry_t fn, void *arg, + cos_task_attr_t *attr, void *stack_buf); + +/** + * @brief 反初始化一个任务 + * + * 反初始化一个任务。与 @ref cos_task_init 配套使用，销毁其初始化过的任务，把此任务置为销毁状态。 + * 如果该任务销毁前处于就绪状态，会把该任务从系统就绪队列中移除。根据互斥锁的类型（鲁棒性互斥锁）， + * 还会释放其拥有的互斥锁，导致唤醒等待该锁的任务。 + * 但不会释放任务控制块task和任务栈的内存空间，这部分内存应由调用者负责释放。 + * + * @param[in] task 新任务的句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + * + * @see cos_task_init + */ +cos_status_t cos_task_deinit(cos_task_t task); + +/** + * @brief 退出任务 + * + * 主动退出当前任务，使系统回收该任务的资源。其作用与从该任务的入口函数返回相同。 + * 参数 @c status 作为后续扩展使用，目前并不支持获取一个任务退出时的状态码。 + * + * @param[in] status 任务退出状态码 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +void cos_task_exit(int32_t status); + +/** + * @brief 挂起任务 + * + * 挂起一个任务，暂停该任务的执行。可以挂起自身或其他任务，但不允许挂起系统idle任务。 + * 当挂起系统其他内置任务时请谨慎，可能会引起系统错误。 + * + * @param[in] task 任务的句柄 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_suspend(cos_task_t task); + +/** + * @brief 恢复任务 + * + * 恢复一个任务，使其处于就绪状态，等待调度执行。 + * + * @param[in] task 任务的句柄 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_resume(cos_task_t task); + +/** + * @brief 当前任务让出CPU + * + * 使当前正在运行的任务让出CPU，并把当前任务置于其静态优先级的就绪队列的末尾。 + * 重新调度，其他任务得到CPU运行。 + * + * @param 无 + * + * @note 可以在中断上下文中使用。 + * @note 根据调度策略，如果该任务是其静态优先级的就绪队列中唯一任务，它会被再次调度到，继续运行。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_yield(void); + +/** + * @brief 获取当前任务自身的句柄 + * + * 返回当前任务自身的句柄，用于对自身任务的操作，如挂起和恢复等。 + * + * @param 无 + * + * @note 可以在中断上下文中使用。 + * + * @return 函数总是执行成功并返回当前任务自身的句柄。 + */ +cos_task_t cos_task_self(void); + +/** + * @brief 获取一个任务的名称 + * + * 返回一个任务的名称，调用者应该为存放任务名称分配足够的内存， + * 并把内存首地址和大小通过参数 @c buf 和 @c buf_size 传入。 + * + * @param[in] task 任务的句柄 + * @param[out] buf 存放任务名称的内存 + * @param[in] buf_size 存放任务名称的内存大小 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_get_name(cos_task_t task, char *buf, size_t buf_size); + +/** + * @brief 根据名称查找任务 + * + * 根据任务名称 @c name 查找任务的句柄。 + * + * @param[in] name 任务的名称 + * + * @note 可以在中断上下文中使用。 + * @note 当系统中存在多个具有相同名称的任务时，函数会执行成功，但返回哪一个任务 + * 的句柄是不确定的，不同的内核实现会有所不同。 + * + * @return 成功则返回任务的句柄， 失败则返回 NULL + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_task_t cos_task_find(const char *name); + +/** + * @brief 使当前任务睡眠一段时间 + * + * 使当前任务睡眠 @c tick 个系统tick的时间，等时间超期或被唤醒后再次进入就绪状态，等待调度执行。 + * 如果 @c tick 为0，则等同于 @ref cos_task_yield 。如果 @c tick 为 @ref COS_WAIT_FOREVER , 则等同于 @ref cos_task_suspend。 + * + * @param[in] tick 系统tick个数 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败，>0: 提前被唤醒时剩余的tick数 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_sleep(cos_tick_t tick); + +/** + * @brief 唤醒任务 + * + * 唤醒一个任务。可以用来提前唤醒一个睡眠的任务。 + * + * @param[in] task 任务的句柄 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_wakeup(cos_task_t task); + +/** + * @brief 获取一个任务的优先级 + * + * 获取一个任务的优先级，可以是自身或其他任务。获取的是任务此时的动态优先级， + * 不一定与其创建时指定的静态优先级相同，如任务此时有优先级继承发生。 + * + * @param[in] task 任务的句柄 + * @param[out] priority 获取到的任务动态优先级 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_get_priority(cos_task_t task, uint8_t *priority); + +/** + * @brief 设置一个任务的优先级 + * + * 设置一个任务的优先级，可以是自身或其他任务。改变的是任务的静态优先级。 + * + * @param[in] task 任务的句柄 + * @param[in] priority 获取到的任务动态优先级 + * + * @note 可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_set_priority(cos_task_t task, uint8_t priority); + +/** + * @brief 获取任务的剩余时间片 + * + * 获取一个使用RR调度策略的任务在本次轮转中剩余时间片。 + * + * @param[in] task 任务的句柄 + * @param[out] time_slice 获取到的任务的剩余时间片 + * + * @note 可以在中断上下文中使用。 + * @note 此函数仅适用于采用RR调度策略的任务， 对于其他任务，剩余时间片返回0. + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_get_time_slice(cos_task_t task, cos_tick_t *time_slice); + +/** + * @brief 获取任务的剩余时间片 + * + * 设置一个使用RR调度策略的任务在一次轮转中所分配的时间片。 + * + * @param[in] task 任务的句柄 + * @param[in] time_slice 获取到的任务的剩余时间片 + * + * @note 可以在中断上下文中使用。 + * @note 此函数仅适用于采用RR调度策略的任务，对于其他任务，返回错误。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_task_set_time_slice(cos_task_t task, cos_tick_t time_slice); + +/** + * @} + */ + +/** + * @addtogroup cos_timer + * 提供软件定时器相关的标准定义 + * @{ + */ + +/** + * @brief 创建软件定时器 + * + * 创建一个软件定时器，当定时器超期时系统会自动执行回调函数 @c cb 并传入参数 @c arg 。 + * 该函数在创建时内部会动态分配需要的内存，如果不想使用动态内存，请使用 @ref cos_timer_init 。 + * + * @param[out] timer 定时器句柄 + * @param[in] name 定时器名称 + * @param[in] cb 定时器的回调函数 + * @param[in] arg 定时器的回调函数的参数 + * @param[in] initial 定时器的初始定时时间，即从定时器启动到第一次触发的时间间隔，单位：tick个数 + * @param[in] period 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发 + * @param[in] options 定时器的选项，如创建时激活 @ref COS_TIMER_OPTION_ACTIVATE， + * 或者不激活 @ref COS_TIMER_OPTION_DEACTIVATE + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 定时器未知错误 + * + * @see cos_timer_init + */ +cos_status_t cos_timer_create(cos_timer_t *timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options); + +/** + * @brief 删除软件定时器 + * + * 删除一个软件定时器。系统会先停止该定时器，然后删除回收其资源。 + * + * @param[in] timer 定时器句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_delete(cos_timer_t timer); + +/** + * @brief 初始化软件定时器 + * + * 初始化一个软件定时器，当定时器超期时系统会自动执行回调函数 @c cb ， 并传入参数 @c arg 。 + * 与创建一个软件定时器类似，区别是定时器的控制块内存时由调用者传入的，一般用于需要静态内存的场景。 + * + * @param[in] timer 定时器句柄 + * @param[in] name 定时器名称 + * @param[in] cb 定时器的回调函数 + * @param[in] arg 定时器的回调函数的参数 + * @param[in] initial 定时器的初始定时时间，即从定时器启动到第一次触发的时间间隔，单位：tick个数 + * @param[in] period 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发 + * @param[in] options 定时器的选项，如创建时激活 @ref COS_TIMER_OPTION_ACTIVATE， + * 或者不激活 @ref COS_TIMER_OPTION_DEACTIVATE + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 定时器未知错误 + * + * @see cos_timer_create + */ +cos_status_t cos_timer_init(cos_timer_t timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options); + +/** + * @brief 反初始化软件定时器 + * + * 反初始化一个定时器。系统会先停止该定时器，从系统定时器列表中移除。但不会释放 @c timer 的内存空间，应由调用者释放。 + * + * @param[in] timer 定时器句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_deinit(cos_timer_t timer); + +/** + * @brief 启动软件定时器 + * + * 启动一个定时器，系统开始计时，直到定时器超期时执行应用设置的回调函数。 + * + * @param[in] timer 定时器句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_start(cos_timer_t timer); + +/** + * @brief 停止软件定时器 + * + * 停止一个定时器，系统停止为该定时器计时，但不会删除它。 + * + * @param[in] timer 定时器句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_stop(cos_timer_t timer); + +/** + * @brief 修改软件定时器 + * + * 修改一个定时器。一般用于修改其周期性定时时间，如果该定时器创建后还没有启动，也可以修改其初始定时时间。 + * + * @param[in] timer 定时器句柄 + * @param[in] initial 定时器的初始定时时间，即从启动到第一次触发的时间间隔，单位：tick个数 + * @param[in] period 定时器的周期定时时间，即周期性触发的时间间隔，单位：tick个数。0：代表单次触发 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_change(cos_timer_t timer, cos_tick_t initial, cos_tick_t period); + +/** + * @brief 获取定时器的时间 + * + * 返回一个定时器的时间信息，包括离下次触发还剩余的时间（系统tick），和周期触发的时间间隔（系统tick）。 + * + * @param[in] timer 定时器句柄 + * @param[out] remaining 离下次触发还剩余的时间，单位：tick个数 + * @param[out] period 周期触发的时间间隔，单位：tick个数。0：代表单次触发 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 定时器未知错误 + */ +cos_status_t cos_timer_get_time(cos_timer_t timer, cos_tick_t *remaining, cos_tick_t *period); + +/** + * @} + */ + +/** + * @addtogroup cos_memory + * 提供内存管理相关的标准定义 + * @{ + */ + +/** + * @brief 申请一块连续的内存 + * + * 从系统堆中申请一块 @c size 大小连续的内存，成功返回申请到内存的首地址，失败返回NULL。 + * + * @param[in] size 想申请内存的大小（单位：Byte） + * + * @note 不可以在中断上下文中使用。 + * + * @return 成功返回申请到内存的首地址，失败则返回NULL。 + */ +void *cos_malloc(size_t size); + +/** + * @brief 改变一块内存的大小 + * + * 改变一块内存 @c ptr 的大小， @c ptr 应该是之前动态申请内存的返回值。新的内存大小可能扩大或缩小， + * 扩大时原有内存大小的内容保持不变且新增加的内存没有初始化。缩小时，被保留的内存的内容保持不变。 + * 如果参数 @c ptr 为NULL，不论new_size为多少，则等于 @c cos_malloc(new_size) ， + * 如果参数 @c new_size 为0，则等于 @c cos_free(prt) 。如果该函数返回的新的内存首地址与原有地址不同， + * 则原有内存被自动释放。 + * + * @param[in] ptr 之前动态申请到的内存首地址 + * @param[in] new_size 内存新大小 + * + * @note 不可以在中断上下文中使用。 + * + * @return 成功返回新申请到内存的首地址，失败则返回NULL。 + */ +void *cos_realloc(void *ptr, size_t new_size); + +/** + * @brief 申请多块连续的内存 + * + * 从系统堆中申请 @c count 个长度为 @c size 的连续的内存，最终申请到内存大小为count * size个字节。 + * + * @param[in] count 申请内存块的个数 + * @param[in] size 每个内存块的大小 + * + * @note 不可以在中断上下文中使用。 + * + * @return 成功返回申请到内存的首地址，失败则返回NULL。 + */ +void *cos_calloc(size_t count, size_t size); + +/** + * @brief 申请内存并按要求地址对齐 + * + * 从系统堆内存中申请 @c size 字节的连续内存，并按 @c alignment 字节对齐， + * 申请到的内存首地址由 @c *memptr 返回。如果参数 @c size 为0，则函数立即返回错误码， + * @c *memptr 为NULL。 参数 @c alignment 应该是sizeof(void*)的倍数且是2的幂， + * 否则立即返回错误， @c *memptr 为NULL。 释放内存通过 @ref cos_free 函数释放。 + * + * @param[out] memptr 返回申请到的内存首地址 + * @param[in] size 想申请内存的大小（单位：Byte） + * @param[in] alignment 内存地址对齐大小（单位：Byte） + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 内存管理未知错误 + */ +cos_status_t cos_malloc_align(void **memptr, size_t size, size_t alignment); + +/** + * @brief 释放内存 + * + * 释放由参数 @c ptr 指向的一块内存， @c ptr 应该是之前动态申请函数的返回值。 + * + * @param[in] ptr 动态申请到的内存首地址 + * + * @note 不可以在中断上下文中使用。 + * + * @return 无 + */ +void cos_free(void *ptr); + +/** + * @} + */ + +/** + * @addtogroup cos_mb + * 提供邮箱相关的标准定义 + * @{ + */ + +/** + * @brief 创建邮箱 + * + * 从系统堆内存中申请空间创建邮箱控制块 + * + * @param[in] name 邮箱名称 + * + * @param[in] size 邮箱容量 + * + * @param[in] flag 邮箱标志，如： COS_IPC_FLAG_FIFO 或 COS_IPC_FLAG_PRIO + * + * @param[out] mb 邮箱句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_create(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb); + +/** + * @brief 创建邮箱 + * + * 删除邮箱对象并释放系统堆内存空间 + * + * + * @param[in] mb 邮箱句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_delete(cos_mb_t mb); + +/** + * @brief 创建邮箱 + * + * 从系统堆内存中申请空间创建邮箱控制块 + * + * @param[in] name 邮箱名称 + * + * @param[in] msgpool 缓冲区指针 + * + * @param[in] msg_size 邮箱容量 + * + * @param[in] flag 邮箱工作方式 + * + * @param[out] mb 邮箱句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_init(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb); + +/** + * @brief 去初始化邮箱 + * + * 去初始化一个邮箱 + * + * @param[in] mb 邮箱句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_deinit(cos_mb_t mb); + +/** + * @brief 发送邮件 + * + * 发送邮件，当邮箱中的邮件已经满时，发送邮件的线程或者中断程序会收到 cos_ERROR_mb_FULL 的返回值。 + * + * @param[in] mb 邮箱句柄 + * + * @param[in] value 邮件内容 + * + * @note 无 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_send(cos_mb_t mb, uint32_t value); + +/** + * @brief 接收邮件 + * + * 当邮箱中有邮件时，接收者才能接收邮件，否则接收者会根据超时时间设置，或挂起在邮箱的等待线程队列上，或直接返回。 + * + * @param[in] mb 邮箱句柄 + * + * @param[out] value 邮件内容 + * + * @param[in] timeout 指定的超时时间 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mb_recv(cos_mb_t mb, uint32_t* value, + int32_t timeout); +/** + * @} + */ + +/** + * @addtogroup cos_mq + * 提供消息队列相关的标准定义 + * @{ + */ +/** + * @brief 创建消息队列 + * + * 从系统堆内存中申请空间创建消息队列控制块 + * + * @param[in] name 消息队列名称 + * + * @param[in] msg_size 单条消息的最大长 + * + * @param[in] max_msgs 消息队列的最大个数 + * + * @param[in] flag 消息队列工作方式，如： COS_IPC_FLAG_FIFO 或 COS_IPC_FLAG_PRIO + * + * @param[out] mq 消息队列句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_create(const char* name, size_t msg_size, + size_t max_msgs, uint8_t flag, cos_mq_t* mq); + +/** + * @brief 删除邮箱 + * + * 从系统堆内存中删除邮箱控制块 + * + * @param[out] mq 邮箱句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_delete(cos_mq_t mq); + +/** + * @brief 初始化消息队列 + * + * 初始化消息队列控制块 + * + * @param[in] name 消息队列名称 + * + * @param[in] msgpool 指向存放消息的缓冲区的指针 + * + * @param[in] msg_size 单条消息的最大长 + * + * @param[in] flag 消息队列工作方式，如： COS_IPC_FLAG_FIFO 或 COS_IPC_FLAG_PRIO + * + * @param[out] mq 消息队列句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_init(const char* name, void *msgpool, size_t msg_size, + size_t max_msgs, cos_mq_t mq); + +/** + * @brief 去初始化消息队列 + * + * 去初始化消息队列控制块 + * + * @param[out] mq 邮箱句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_delete(cos_mq_t mq); + +/** + * @brief 发送消息 + * + * 发送消息，线程或者中断服务程序都可以给消息队列发送消息。 + * + * @param[in] mq 消息队列的句柄 + * + * @param[in] value 消息内容 + * + * @param[in] size 消息大小 + * + * @note 无 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERROR_MQ_DELETED 线程挂起时消息队列已被删除 + * @retval COS_ERROR_MQ_FULL 消息队列已满 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_send(cos_mq_t mq, void* buffer, size_t size); + +/** + * @brief 接收邮件 + * + * 当邮箱中有邮件时，接收者才能接收邮件，否则接收者会根据超时时间设置，或挂起在邮箱的等待线程队列上，或直接返回。 + * + * @param[in] mq 消息队列的句柄 + * + * @param[out] buffer 消息内容 + * + * @param[in] size 消息大小 + * + * @param[in] timeout 指定的超时时间 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERROR_MQ_DELETED 线程挂起时消息队列已被删除 + * @retval COS_ERROR_MQ_FULL 消息队列已满 + * @retval COS_ERR_ISR 在中断上下文中调用 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_mq_recv(cos_mq_t mq, void* buffer, + size_t size, int32_t timeout); + +/** + * @} + */ + +/** + * @addtogroup cos_wq + * 提供工作队列相关的标准定义 + * @{ + */ +/** + * @brief 初始化工作项 + * + * 初始化工作项，并绑定工作项的回调函数，以及自定义用户数据 + * + * @param[in] work 工作项 + * + * @param[in] work_func 工作项的回调函数 + * + * @param[in] work_data 用户自定义数据，回调函数参数 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_work_init(cos_work_t work, cos_work_handle_t work_func, void *work_data); + +/** + * @brief 删除邮箱 + * + * 从系统堆内存中删除邮箱控制块 + * + * @param[in] work 工作项 + * + * @param[in] time 提交延时，以 tick 为单位 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_work_dowork(cos_work_t work, cos_tick_t time); + +/** + * @brief 向工作队列提交工作项 + * + * 将 work 指向的工作项提交到 queue 指向的工作队列中，若 time 大于 0，则该提交延时 time 个 tick 之后执行。 + * + * @param[in] wq 工作队列 + * + * @param[in] work 工作项 + * + * @param[in] time 提交延时，以 tick 为单位 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_work_submit(cos_wq_t wq, cos_work_t work, cos_tick_t time); + +/** + * @brief 取消指定工作项 + * + * 从 queue 指向的工作队列中将 work 指向的工作项移除。 + * + * @param[in] queue 工作队列 + * + * @param[in] work 工作项 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_work_cancel(cos_wq_t wq, cos_work_t work); + +/** + * @brief 创建工作队列 + * + * 该函数创建并初始化一个工作队列，利用参数 name，stack_size 和 priority 创建工作队列内部线程，最终返回创建的工作队列。下表描述了该函数的输入参数与返回值 + * + * @param[out] wq 工作队列句柄 + * + * @param[in] name 线程名字 + * + * @param[in] stack_size 线程栈大小 + * + * @param[in] priority 线程优先级 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_workqueue_create(cos_wq_t* wq, const char *name, uint16_t stack_size, uint8_t priority); + +/** + * @brief 工作队列销毁函数 + * + * 销毁指定工作队列 + * + * @param[in] wq 工作队列句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 未知错误 + */ +cos_status_t cos_workqueue_destroy(cos_wq_t wq); +/** + * @} + */ + +/** + * @addtogroup cos_mutex + * 提供互斥锁相关的标准定义 + * @{ + */ + +/** + * @brief 创建互斥锁 + * + * 创建一个互斥锁。 + * 该函数在创建时内部会动态分配需要的内存，如果不想使用动态内存，请使用 @ref cos_mutex_init 。 + * + * @param[out] timer 互斥锁句柄 + * @param[in] name 互斥锁名称 + * @param[in] options 互斥锁的选项，如开启嵌套锁支持 @ref COS_MUTEX_NEST + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中使用 + * @retval COS_ERR 互斥锁未知错误 + * + * @see cos_mutex_init + */ +cos_status_t cos_mutex_create(cos_mutex_t *mutex, char *name, uint32_t options); + +/** + * @brief 删除互斥锁 + * + * 删除一个互斥锁。系统会先唤醒所有等待该锁的任务，唤醒原因为互斥锁已被销毁，然后删除回收其资源。 + * + * @param[in] mutex 互斥锁句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 互斥锁未知错误 + */ +cos_status_t cos_mutex_delete(cos_mutex_t mutex); + +/** + * @brief 初始化互斥锁 + * + * 初始化一个互斥锁。 + * 与创建一个互斥锁类似，区别是互斥锁的控制块内存是由调用者传入的，一般用于需要静态内存的场景。 + * + * @param[in] mutex 互斥锁句柄 + * @param[in] name 互斥锁名称 + * @param[in] options 互斥锁的选项，如开启嵌套锁支持 @ref COS_MUTEX_NEST + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR_ISR 在中断上下文中使用 + * @retval COS_ERR 互斥锁未知错误 + * + * @see cos_mutex_create + */ +cos_status_t cos_mutex_init(cos_mutex_t mutex, char *name, uint32_t options); + +/** + * @brief 反初始化互斥锁 + * + * 反初始化一个互斥锁。系统会先唤醒所有等待该锁的任务，唤醒原因为互斥锁已被销毁。但不会释放 @c mutex 的内存空间，应由调用者释放。 + * + * @param[in] mutex 互斥锁句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 互斥锁未知错误 + */ +cos_status_t cos_mutex_deinit(cos_mutex_t mutex); + +/** + * @brief 互斥锁上锁 + * + * @param[in] mutex 互斥锁句柄 + * @param[in] timeout 等待互斥锁的超时时间，单位：tick个数 + * + * @note 不可以在中断上下文中使用。 + * + * @retval COS_ERR 互斥锁未知错误 + * @retval COS_ERR_TIMEOUT 申请上锁超时 + * @retval COS_ERR_DESTROY 互斥锁已被销毁 + * @retval COS_ERR_MUTEX_NESTING 未开启嵌套锁的情况下，进行嵌套申请 + */ +cos_status_t cos_mutex_lock(cos_mutex_t mutex, cos_tick_t timeout); + +/** + * @brief 互斥锁解锁 + * + * @param[in] mutex 互斥锁句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 互斥锁未知错误 + * @retval COS_ERR_DESTROY 互斥锁已被销毁 + * @retval COS_ERR_MUTEX_NOT_OWNER 未持有该互斥锁 + */ +cos_status_t cos_mutex_unlock(cos_mutex_t mutex); + +/** + * @} + */ + +/** + * @addtogroup cos_sem + * 提供信号量相关的标准定义 + * @{ + */ + +/** + * @brief 创建信号量 + * + * 创建一个信号量。 + * 该函数在创建时内部会动态分配需要的内存，如果不想使用动态内存，请使用 @ref cos_sem_init 。 + * + * @param[out] sem 信号量句柄 + * @param[in] name 信号量名称 + * @param[in] init_count 信号量初始值 + * @param[in] max_count 信号量最大值。如果无最大值限制可使用 @ref COS_SEM_NO_MAX。 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 信号量未知错误 + * + * @see cos_sem_init + */ +cos_status_t cos_sem_create(cos_sem_t *sem, char *name, uint32_t init_count, uint32_t max_count); + +/** + * @brief 删除信号量 + * + * 删除一个信号量。系统会先唤醒所有等待该信号量的任务，唤醒原因为信号量已被销毁，然后删除回收其资源。 + * + * @param[in] sem 信号量句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 信号量未知错误 + */ +cos_status_t cos_sem_delete(cos_sem_t sem); + +/** + * @brief 初始化信号量 + * + * 初始化一个信号量。 + * 与创建一个信号量类似，区别是信号量的控制块内存是由调用者传入的，一般用于需要静态内存的场景。 + * + * @param[in] sem 信号量句柄 + * @param[in] name 信号量名称 + * @param[in] init_count 信号量初始值 + * @param[in] max_count 信号量最大值。如果无最大值限制可使用 @ref COS_SEM_NO_MAX。 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 信号量未知错误 + * + * @see cos_sem_create + */ +cos_status_t cos_sem_init(cos_sem_t sem, char *name, uint32_t init_count, uint32_t max_count); + +/** + * @brief 反初始化信号量 + * + * 反初始化一个信号量。系统会先唤醒所有等待该信号量的任务，唤醒原因为信号量已被销毁。但不会释放 @c sem 的内存空间，应由调用者释放。 + * + * @param[in] sem 信号量句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 信号量未知错误 + */ +cos_status_t cos_sem_deinit(cos_sem_t sem); + +/** + * @brief 等待信号量 + * + * @param[in] sem 信号量句柄 + * @param[in] timeout 等待信号量的超时时间，单位：tick个数 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 信号量未知错误 + * @retval COS_ERR_TIMEOUT 申请超时 + * @retval COS_ERR_DESTROY 信号量已被销毁 + */ +cos_status_t cos_sem_wait(cos_sem_t sem, cos_tick_t timeout); + +/** + * @brief 释放信号量 + * + * 释放一个信号量。系统唤醒等待该信号量的最高优先级任务。 + * + * @param[in] sem 信号量句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 信号量未知错误 + * @retval COS_ERR_DESTROY 信号量已被销毁 + */ +cos_status_t cos_sem_release(cos_sem_t sem); + +/** + * @brief 释放信号量，唤醒所有等待任务 + * + * 释放一个信号量。系统唤醒等待该信号量的所有任务。 + * + * @param[in] sem 信号量句柄 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 信号量未知错误 + * @retval COS_ERR_DESTROY 信号量已被销毁 + */ +cos_status_t cos_sem_release_all(cos_sem_t sem); + +/** + * @} + */ + +/** + * @addtogroup cos_event + * 提供事件相关的标准定义 + * @{ + */ +/** + * @brief 创建事件 + * + * 创建一个事件。 + * 该函数在创建时内部会动态分配需要的内存，如果不想使用动态内存，请使用 @ref cos_sem_init 。 + * + * @param[out] event 事件句柄 + * @param[in] name 事件名称 + * @param[in] init_flag 事件初始标志 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 事件未知错误 + * + * @see cos_event_init + */ +cos_status_t cos_event_create(cos_event_t *event, char *name, cos_event_flag_t init_flag); + +/** + * @brief 删除事件 + * + * 删除一个事件。系统会先唤醒所有等待该事件的任务，唤醒原因为事件已被销毁，然后删除回收其资源。 + * + * @param[in] event 事件句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 事件未知错误 + */ +cos_status_t cos_event_delete(cos_event_t event); + +/** + * @brief 初始化事件 + * + * 初始化一个事件。 + * 与创建一个事件类似，区别是事件的控制块内存是由调用者传入的，一般用于需要静态内存的场景。 + * + * @param[out] event 事件句柄 + * @param[in] name 事件名称 + * @param[in] init_flag 事件初始标志 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR_NOMEM 内存不足 + * @retval COS_ERR 事件未知错误 + * + * @see cos_event_create + */ +cos_status_t cos_event_init(cos_event_t event, char *name, cos_event_flag_t init_flag); + +/** + * @brief 反初始化事件 + * + * 反初始化一个事件。系统会先唤醒所有等待该事件的任务，唤醒原因为事件已被销毁。但不会释放 @c event 的内存空间，应由调用者释放。 + * + * @param[in] event 事件句柄 + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 事件未知错误 + */ +cos_status_t cos_event_deinit(cos_event_t event); + +/** + * @brief 等待事件 + * + * @param[in] event 事件句柄 + * @param[in] expect_flag 期望期待的事件标志 + * @param[in] timeout 等待事件的超时时间，单位：tick个数 + * @param[out] match_flag 等待到的事件结果 + * @param[in] options 等待事件的选项，如等待一个事件即可 @ref COS_EVENT_WAIT_ANY， + * 等待全部事件 @ref COS_EVENT_WAIT_ALL, 等待到事件后清除该事件 @ref COS_EVENT_WAIT_CLR + * + * @note 不可以在中断上下文中使用。 + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR_PARAM 传入的参数非法 + * @retval COS_ERR 事件未知错误 + * @retval COS_ERR_TIMEOUT 等待超时 + * @retval COS_ERR_DESTROY 事件已被销毁 + */ +cos_status_t cos_event_wait(cos_event_t event, cos_event_flag_t expect_flag, cos_tick_t timeout, cos_event_flag_t *match_flag, uint32_t options); + +/** + * @brief 释放事件 + * + * @param[in] event 事件句柄 + * @param[in] flag 要释放的事件标志 + * @param[in] options 释放事件的选项，如释放后是否保留该事件 @ref COS_EVENT_RELEASE_KEEP + * + * @return COS_OK: 成功， <0: 失败 + * @retval COS_ERR 事件未知错误 + * @retval COS_ERR_DESTROY 事件已被销毁 + */ +cos_status_t cos_event_release(cos_event_t event, cos_event_flag_t flag, uint32_t options); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /*_COSIT_H*/ \ No newline at end of file diff --git a/osal/cosit/include/cosit_port_types.h b/osal/cosit/include/cosit_port_types.h new file mode 100644 index 0000000..3fe1485 --- /dev/null +++ b/osal/cosit/include/cosit_port_types.h @@ -0,0 +1,63 @@ +/* + * Copyright (C) XXXX + * + * SPDX-License-Identifier: XXXX + * + * Version: 1.0.0 + * + * Change log: + * + * Date Author Note + * 2022-07-12 all first version + */ + +#ifndef _COSIT_PORT_TYPES_H +#define _COSIT_PORT_TYPES_H + +//#define COS_USE_AOS /* AliOS Things */ +//#define COS_USE_TOS /* TencentOS-tiny */ +//#define COS_USE_RTTHREAD /* RT-Thread */ + +/* 提供统一的内核对象类型名称，为调用静态内存API前先开辟合适大小的内存，同时屏蔽底层OS的差异， + * 静态内存API：cos_task_init, cos_timer_init, cos_mb_init, cos_mq_init, cos_work_init, + * cos_mutex_init, cos_sem_init, cos_event_init。 + * 只有当用户使用静态内存类型的API时需要此头文件， 否则不需要。 + * + * 使用举例： + * cos_sem_real_t test_sem; + * ret = cos_sem_init((cos_sem_t)&test_sem, "test_sem", 1, 0xffff); + * cos_sem_wait((cos_sem_t)&test_sem, COS_WAIT_FOREVER); + */ + +#ifdef COS_USE_AOS +#include +/* 提供底层OS内核对象的真实数据类型, 用于 */ +typedef ktask_t cos_task_real_t; +typedef ktimer_t cos_timer_real_t; +typedef kmutex_t cos_mutex_real_t; +typedef ksem_t cos_sem_real_t; +typedef kevent_t cos_event_real_t; +typedef kbuf_queue_t cos_mq_real_t; +typedef kqueue_t cos_mb_real_t; +typedef kwork_t cos_work_real_t; +typedef kworkqueue_t cos_wq_real_t; + +#elif defined (COS_USE_TOS) +#include "tos_k.h" +typedef k_task_t cos_task_real_t; +typedef k_timer_t cos_timer_real_t; +typedef k_mutex_t cos_mutex_real_t; +typedef k_sem_t cos_sem_real_t; +typedef k_event_t cos_event_real_t; +typedef k_mail_q_t cos_mq_real_t; +typedef k_msg_q_t cos_mb_real_t; + +#elif defined (COS_USE_RTTHREAD) + +#else + +#warning "The underlying OS is not defined, so you should take care of the real type of kernel object." + +#endif + +#endif /*_COSIT_PORT_TYPES_H*/ diff --git a/osal/cosit/meeting/2022-05-07.md b/osal/cosit/meeting/2022-05-07.md new file mode 100644 index 0000000..d371456 --- /dev/null +++ b/osal/cosit/meeting/2022-05-07.md @@ -0,0 +1,15 @@ +# 5月7日会议结论 + +1、API前缀统一为COS + - 对应更新API前缀 @RTT + +2、消息邮箱API，5月11日前提交 @RTT + +3、头文件，5月11日在群里讨论确定 @阿里、腾讯、RTT、展锐 + +4、create/delete, init/deinit：分开两对写， @阿里、腾讯、RTT + +5、通用错误码，不带上模块名，各个Owner分别更新API @阿里、腾讯、RTT + + + **下次会议：5月31日，对焦实现进展** \ No newline at end of file diff --git a/osal/cosit/meeting/2022-05-31.md b/osal/cosit/meeting/2022-05-31.md new file mode 100644 index 0000000..f260015 --- /dev/null +++ b/osal/cosit/meeting/2022-05-31.md @@ -0,0 +1,24 @@ +# 5月31日会议结论 + +进展 +1. 腾讯实现了任务管理；下次会议可以完成 +2. RTT实现了消息队列、邮箱；下次会议可以完成 + + +Issue: +1. 在头文件里补充错误码 @阿里 +2. COS_EVENT_RELEASE_KEEP，腾讯check下是否说明了该API的功能@腾讯 +3. 所有静态的API，如何隐藏底层具体OS内核的数据类型（例如cos_mutex_init/cos_sem_init等），调研其他标准如何实现@阿里 + + +会上讨论的技术结论： +1. 内核对象的参数均为第一个参数，大家保持一致。 比如cos_mq_create/cos_mq_init的 mq参数，cos_mb_create/cos_mb_init的mb参数。 +2. timeout参数统一使用cos_tick_t类型，代表tick。 +3. 不支持的一些API的子特性， 统一返回错误码COS_ERR_NOTSUPPORT。 + + +其他 +1. 测试套件—等API适配完成后，确定API没问题再进行 + + + **下次会议：6月14日** \ No newline at end of file diff --git a/osal/cosit/meeting/2022-06-14.md b/osal/cosit/meeting/2022-06-14.md new file mode 100644 index 0000000..fd4ec6d --- /dev/null +++ b/osal/cosit/meeting/2022-06-14.md @@ -0,0 +1,14 @@ +# 6月14日会议结论 + +进展 +1. 腾讯：基本已经完成 +2. RTT：部分完成 + +结论： +1. 后续迁移到基金会的代码库，初期先fork一份，Gitee的仍保留 +2. 目标：7月底基金会峰会，发布标准及相关demo。 +3. 腾讯计划在3-4款开发板实现，RTT计划在1款开发板实现，阿里1款开发板实现。 +4. 测试套采用greatest.h开源框架 + + + **下次会议：6月28日** \ No newline at end of file diff --git a/osal/cosit/meeting/2022-06-28.md b/osal/cosit/meeting/2022-06-28.md new file mode 100644 index 0000000..94cef52 --- /dev/null +++ b/osal/cosit/meeting/2022-06-28.md @@ -0,0 +1,12 @@ +# 6月28日会议结论 + +进展 +1. 腾讯：消息邮箱、消息队列，需要等API确认完后再实现；正在写测试例 +2. RTT：还缺工作队列 +3. 阿里：都实现了 + +结论： +1. 静态初始化，隔离底层OS。建议方式:定义统一的宏，用户来开buffer。新开一个头文件，feature.h @李进良 +2. 新增cos_sem_t、获取tick值、信号量唤醒release-all的issue，跟踪讨论@腾讯 + + **下次会议：7月12日** \ No newline at end of file diff --git a/osal/cosit/meeting/2022-07-12.md b/osal/cosit/meeting/2022-07-12.md new file mode 100644 index 0000000..f169a62 --- /dev/null +++ b/osal/cosit/meeting/2022-07-12.md @@ -0,0 +1,13 @@ +# 7月12日会议结论 + +7月26日发布方案： +1. 各家确定届时参会的同事名单@腾讯、RTT、展锐 +2. 发布视频画面，有发布特效；最终显示“《物联网操作系统内核接口规范 1.0》正式发布” +3. 补充各家的标准实现情况@腾讯、RTT + + +结论： +1. 数量类型抽象（https://gitee.com/IoTOSSWG-atom/cosit/issues/I5EYUC?from=project-issue）@尽良 发起PR进行更新 +2. 补充消息队列工作方式 COS_IPC_FLAG_FIFO、 COS_IPC_FLAG_PRIO这两个常量的定义 @RTT + + **下次会议：峰会之后确定** \ No newline at end of file diff --git a/osal/cosit/rtos/TobudOS/cosit.c b/osal/cosit/rtos/TobudOS/cosit.c new file mode 100644 index 0000000..e6a6630 --- /dev/null +++ b/osal/cosit/rtos/TobudOS/cosit.c @@ -0,0 +1,779 @@ +#include "cosit.h" +#include + +static cos_status_t errno_knl2cosit(k_err_t err) +{ + switch (err) { + case K_ERR_NONE: return COS_OK; + case K_ERR_IN_IRQ: return COS_ERR_ISR; + default: return COS_ERR; + } +} + +cos_tick_t cos_ms_to_tick(uint64_t ms) +{ + return tos_millisec2tick((k_time_t)ms); +} + +uint64_t cos_tick_to_ms(cos_tick_t tick) +{ + return tos_tick2millisec((k_tick_t)tick); +} + +void cos_task_attr_init(cos_task_attr_t *attr) +{ + if (!attr) { + return; + } + + attr->name = "default_task"; + attr->stack_size = 512; + attr->priority = 5; + attr->tick = 10; +} + +cos_status_t cos_task_create(cos_task_t *task, cos_task_entry_t fn, void *arg, cos_task_attr_t *attr) +{ + k_err_t err; + k_stack_t *task_stack; + + if (!attr) { + return COS_ERR_PARAM; + } + +#if TOS_CFG_TASK_DYNAMIC_CREATE_EN > 0u + err = tos_task_create_dyn((k_task_t **)task, attr->name, (k_task_entry_t)fn, arg, + (k_prio_t)attr->priority, attr->stack_size, + (k_timeslice_t)attr->tick); + + return errno_knl2cosit(err); +#endif + + *task = (cos_task_t)tos_mmheap_alloc(sizeof(k_task_t)); + if (!task) { + return COS_ERR_NOMEM; + } + + task_stack = (k_stack_t *)tos_mmheap_alloc(attr->stack_size); + if (!task_stack) { + tos_mmheap_free(task); + return COS_ERR_NOMEM; + } + + err = tos_task_create((k_task_t *)*task, attr->name, (k_task_entry_t)fn, arg, + (k_prio_t)attr->priority, task_stack, attr->stack_size, + (k_timeslice_t)attr->tick); + + if (err != K_ERR_NONE) { + tos_mmheap_free(task); + tos_mmheap_free(task_stack); + } + + return errno_knl2cosit(err); +} + +cos_status_t cos_task_delete(cos_task_t task) +{ + k_err_t err; + k_task_t *the_task = (k_task_t *)task; + +#if TOS_CFG_TASK_DYNAMIC_CREATE_EN > 0u + err = tos_task_destroy_dyn(the_task); + return errno_knl2cosit(err); +#endif + + err = tos_task_destroy(the_task); + tos_mmheap_free(the_task->stk_base); + tos_mmheap_free(task); + + return errno_knl2cosit(err); +} + +cos_status_t cos_task_init(cos_task_t task, cos_task_entry_t fn, void *arg, + cos_task_attr_t *attr, void *stack_buf) +{ + k_err_t err; + + err = tos_task_create((k_task_t *)task, attr->name, (k_task_entry_t)fn, + arg, attr->priority, (k_stack_t *)stack_buf, + attr->stack_size, attr->tick); + + return errno_knl2cosit(err); +} + +cos_status_t cos_task_deinit(cos_task_t task) +{ + return errno_knl2cosit(tos_task_destroy((k_task_t *)task)); +} + +void cos_task_exit(int32_t status) +{ + tos_task_destroy(K_NULL); +} + +cos_status_t cos_task_suspend(cos_task_t task) +{ + return errno_knl2cosit(tos_task_suspend((k_task_t *)task)); +} + +cos_status_t cos_task_resume(cos_task_t task) +{ + return errno_knl2cosit(tos_task_resume((k_task_t *)task)); +} + +cos_status_t cos_task_yield(void) +{ + tos_task_yield(); + + return COS_OK; +} + +cos_task_t cos_task_self(void) +{ + return (cos_task_t)tos_task_curr_task_get(); +} + +cos_status_t cos_task_get_name(cos_task_t task, char *buf, size_t buf_size) +{ + k_task_t *the_task = task; + + if (!the_task || !buf) { + return COS_ERR_PARAM; + } + + strncpy(the_task->name, buf, buf_size); + + return COS_OK; +} + +cos_task_t cos_task_find(const char *name) +{ + return (cos_task_t)tos_task_find(name); +} + +cos_status_t cos_task_sleep(cos_tick_t tick) +{ + return errno_knl2cosit(tos_task_delay((k_tick_t)tick)); +} + +cos_status_t cos_task_wakeup(cos_task_t task) +{ + //todo + return COS_ERR; +} + +cos_status_t cos_task_get_priority(cos_task_t task, uint8_t *priority) +{ + k_task_t *the_task = task; + + if (!the_task || !priority) { + return COS_ERR_PARAM; + } + + *priority = the_task->prio; + + return COS_OK; +} + +cos_status_t cos_task_set_priority(cos_task_t task, uint8_t priority) +{ + return tos_task_prio_change((k_task_t *)task, (k_prio_t)priority); +} + +#if TOS_CFG_ROUND_ROBIN_EN > 0u + +cos_status_t cos_task_get_time_slice(cos_task_t task, cos_tick_t *time_slice) +{ + + k_task_t *the_task = task; + + if (!the_task || !time_slice) { + return COS_ERR_PARAM; + } + + *time_slice = the_task->timeslice; + + return COS_OK; +} + +cos_status_t cos_task_set_time_slice(cos_task_t task, cos_tick_t time_slice) +{ + tos_robin_timeslice_set((k_task_t *)task, (k_timeslice_t)time_slice); + return COS_OK; +} + +#else + +cos_status_t cos_task_get_time_slice(cos_task_t task, cos_tick_t *time_slice) +{ + return COS_ERR; +} + +cos_status_t cos_task_set_time_slice(cos_task_t task, cos_tick_t time_slice) +{ + return COS_ERR; +} + +#endif /* TOS_CFG_ROUND_ROBIN_EN */ + +#if TOS_CFG_TIMER_EN > 0u + +cos_status_t cos_timer_create(cos_timer_t *timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options) +{ + k_err_t err; + k_timer_t **the_timer = (k_timer_t **)timer; + + err = tos_timer_create_dyn(the_timer, (k_tick_t)initial, (k_tick_t)period, + (k_timer_callback_t)cb, arg, TOS_OPT_TIMER_PERIODIC); + + if (err != K_ERR_NONE) { + return errno_knl2cosit(err); + } + + if (options == COS_TIMER_OPTION_ACTIVATE) { + err = tos_timer_start(*the_timer); + return errno_knl2cosit(err); + } + + return COS_OK; +} + +cos_status_t cos_timer_delete(cos_timer_t timer) +{ + return errno_knl2cosit(tos_timer_destroy_dyn((k_timer_t *)timer)); +} + +cos_status_t cos_timer_init(cos_timer_t timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options) +{ + k_err_t err; + k_timer_t *the_timer = (k_timer_t *)timer; + + err = tos_timer_create(the_timer, (k_tick_t)initial, (k_tick_t)period, + (k_timer_callback_t)cb, arg, TOS_OPT_TIMER_PERIODIC); + + if (err != K_ERR_NONE) { + return errno_knl2cosit(err); + } + + if (options == COS_TIMER_OPTION_ACTIVATE) { + err = tos_timer_start(the_timer); + return errno_knl2cosit(err); + } + + return COS_OK; +} + +cos_status_t cos_timer_deinit(cos_timer_t timer) +{ + return errno_knl2cosit(tos_timer_destroy((k_timer_t *)timer)); +} + +cos_status_t cos_timer_start(cos_timer_t timer) +{ + return errno_knl2cosit(tos_timer_start((k_timer_t *)timer)); +} + +cos_status_t cos_timer_stop(cos_timer_t timer) +{ + return errno_knl2cosit(tos_timer_stop((k_timer_t *)timer)); +} + +cos_status_t cos_timer_change(cos_timer_t timer, cos_tick_t initial, cos_tick_t period) +{ + k_err_t err; + k_timer_t *the_timer = (k_timer_t *)timer; + + err = tos_timer_delay_change(the_timer, (k_tick_t)initial); + if (err != K_ERR_NONE) { + return errno_knl2cosit(err); + } + + return errno_knl2cosit(tos_timer_period_change(the_timer, (k_tick_t)period)); +} + +cos_status_t cos_timer_get_time(cos_timer_t timer, cos_tick_t *remaining, cos_tick_t *period) +{ + //todo + return COS_ERR; +} + +#else + +cos_status_t cos_timer_create(cos_timer_t *timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options) +{ + return COS_ERR; +} + +cos_status_t cos_timer_delete(cos_timer_t timer) +{ + return COS_ERR; +} + +cos_status_t cos_timer_init(cos_timer_t timer, const char *name, cos_timer_cb_t cb, + void *arg, cos_tick_t initial, cos_tick_t period, uint32_t options) +{ + return COS_ERR; +} + +cos_status_t cos_timer_deinit(cos_timer_t timer) +{ + return COS_ERR; +} + +cos_status_t cos_timer_start(cos_timer_t timer) +{ + return COS_ERR; +} + +cos_status_t cos_timer_stop(cos_timer_t timer) +{ + return COS_ERR; +} + +cos_status_t cos_timer_change(cos_timer_t timer, cos_tick_t initial, cos_tick_t period) +{ + return COS_ERR; +} + +cos_status_t cos_timer_get_time(cos_timer_t timer, cos_tick_t *remaining, cos_tick_t *period) +{ + return COS_ERR; +} + +#endif /* TOS_CFG_TIMER_EN */ + +void *cos_malloc(size_t size) +{ + return tos_mmheap_alloc(size); +} + +void *cos_realloc(void *ptr, size_t new_size) +{ + return tos_mmheap_realloc(ptr, new_size); +} + +void *cos_calloc(size_t count, size_t size) +{ + return tos_mmheap_calloc(count, size); +} + +cos_status_t cos_malloc_align(void **memptr, size_t size, size_t alignment) +{ +#if TOS_CFG_MMHEAP_EN > 0u + + if (!memptr) { + return COS_ERR_PARAM; + } + + *memptr = tos_mmheap_aligned_alloc(size, alignment); + + return *memptr == NULL ? COS_ERR : COS_OK; + +#else + return COS_ERR; +#endif +} + +void cos_free(void *ptr) +{ + tos_mmheap_free(ptr); +} + +#if TOS_CFG_MESSAGE_QUEUE_EN > 0u + +cos_status_t cos_mb_create(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb) +{ + +} + +cos_status_t cos_mb_delete(cos_mb_t mb) +{ + +} + +cos_status_t cos_mb_init(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb) +{ + //todo + //tosҪûpool +} + +cos_status_t cos_mb_deinit(cos_mb_t mb) +{ + +} + +cos_status_t cos_mb_send(cos_mb_t mb, uint32_t value) +{ + return errno_knl2cosit(tos_msg_q_post((k_msg_q_t *)mb, (void *)value)); +} + +cos_status_t cos_mb_recv(cos_mb_t mb, uint32_t* value, + int32_t timeout) +{ + //note: valueҪûָ룬ǷӦʹöָʾ + return errno_knl2cosit(tos_msg_q_pend((k_msg_q_t *)mb, (void**)value, (k_tick_t)timeout)); +} + +#else + +cos_status_t cos_mb_create(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb) +{ + +} + +cos_status_t cos_mb_delete(cos_mb_t mb) +{ + +} + +cos_status_t cos_mb_init(const char* name, size_t msg_size, + uint8_t flag, cos_mb_t *mb) +{ + +} + +cos_status_t cos_mb_deinit(cos_mb_t mb) +{ + +} + +cos_status_t cos_mb_send(cos_mb_t mb, uint32_t value) +{ + +} + +cos_status_t cos_mb_recv(cos_mb_t mb, uint32_t* value, + int32_t timeout) +{ + +} + +#endif + +#if TOS_CFG_MAIL_QUEUE_EN > 0u + +cos_status_t cos_mq_create(const char* name, size_t msg_size, + size_t max_msgs, uint8_t flag, cos_mq_t* mq) +{ + +} + +cos_status_t cos_mq_delete(cos_mq_t mq) +{ + +} + +cos_status_t cos_mq_init(const char* name, void *msgpool, size_t msg_size, + size_t max_msgs, cos_mq_t mq) +{ + return errno_knl2cosit(tos_mail_q_create((k_mail_q_t *)mq, msgpool, max_msgs, msg_size)); +} + +cos_status_t cos_mq_deinit(cos_mq_t mq) +{ + return errno_knl2cosit(tos_mail_q_destroy((k_mail_q_t *)mq)); +} + +cos_status_t cos_mq_send(cos_mq_t mq, void* buffer, size_t size) +{ + return errno_knl2cosit(tos_mail_q_post((k_mail_q_t *)mq, buffer, size)); +} + +cos_status_t cos_mq_recv(cos_mq_t mq, void* buffer, + size_t size, int32_t timeout) +{ + //todo + // tossizedzΣݽյݴСCOSIT APIΣʾС. + size_t recv_size; + + return errno_knl2cosit(tos_mail_q_pend((k_mail_q_t *)mq, buffer, &recv_size, (k_tick_t)timeout)); +} + +#else + +cos_status_t cos_mq_create(const char* name, size_t msg_size, + size_t max_msgs, uint8_t flag, cos_mq_t* mq) +{ + return COS_ERR; +} + +cos_status_t cos_mq_delete(cos_mq_t mq) +{ + return COS_ERR; +} + +cos_status_t cos_mq_init(const char* name, void *msgpool, size_t msg_size, + size_t max_msgs, cos_mq_t mq) +{ + return COS_ERR; +} + +cos_status_t cos_mq_deinit(cos_mq_t mq) +{ + return COS_ERR; +} + +cos_status_t cos_mq_send(cos_mq_t mq, void* buffer, size_t size) +{ + return COS_ERR; +} + +cos_status_t cos_mq_recv(cos_mq_t mq, void* buffer, + size_t size, int32_t timeout) +{ + return COS_ERR; +} + +#endif + +cos_status_t cos_work_init(cos_work_t work, cos_work_handle_t work_func, void *work_data) +{ + return COS_ERR; +} + +cos_status_t cos_work_dowork(cos_work_t work, cos_tick_t time) +{ + return COS_ERR; +} + +cos_status_t cos_work_submit(cos_wq_t wq, cos_work_t work, cos_tick_t time) +{ + return COS_ERR; +} + +cos_status_t cos_work_cancel(cos_wq_t wq, cos_work_t work) +{ + return COS_ERR; +} + +cos_status_t cos_workqueue_create(cos_wq_t* wq, const char *name, uint16_t stack_size, uint8_t priority) +{ + return COS_ERR; +} + +cos_status_t cos_workqueue_destroy(cos_wq_t wq) +{ + return COS_ERR; +} + +#if TOS_CFG_MUTEX_EN > 0u + +cos_status_t cos_mutex_create(cos_mutex_t *mutex, char *name, uint32_t options) +{ + return errno_knl2cosit(tos_mutex_create_dyn((k_mutex_t **)mutex)); +} + +cos_status_t cos_mutex_delete(cos_mutex_t mutex) +{ + return errno_knl2cosit(tos_mutex_destroy_dyn((k_mutex_t *)mutex)); +} + +cos_status_t cos_mutex_init(cos_mutex_t mutex, char *name, uint32_t options) +{ + return errno_knl2cosit(tos_mutex_create((k_mutex_t *)mutex)); +} + +cos_status_t cos_mutex_deinit(cos_mutex_t mutex) +{ + return errno_knl2cosit(tos_mutex_destroy((k_mutex_t *)mutex)); +} + +cos_status_t cos_mutex_lock(cos_mutex_t mutex, cos_tick_t timeout) +{ + return errno_knl2cosit(tos_mutex_pend_timed((k_mutex_t *)mutex, (k_tick_t)timeout)); +} + +cos_status_t cos_mutex_unlock(cos_mutex_t mutex) +{ + return errno_knl2cosit(tos_mutex_post((k_mutex_t *)mutex)); +} + +#else + +cos_status_t cos_mutex_create(cos_mutex_t *mutex, char *name, uint32_t options) +{ + return COS_ERR; +} + +cos_status_t cos_mutex_delete(cos_mutex_t mutex) +{ + return COS_ERR; +} + +cos_status_t cos_mutex_init(cos_mutex_t mutex, char *name, uint32_t options) +{ + return COS_ERR; +} + +cos_status_t cos_mutex_deinit(cos_mutex_t mutex) +{ + return COS_ERR; +} + +cos_status_t cos_mutex_lock(cos_mutex_t mutex, cos_tick_t timeout) +{ + return COS_ERR; +} + +cos_status_t cos_mutex_unlock(cos_mutex_t mutex) +{ + return COS_ERR; +} + +#endif /* TOS_CFG_MUTEX_EN */ + +#if TOS_CFG_SEM_EN > 0u + +cos_status_t cos_sem_create(cos_sem_t *sem, char *name, uint32_t init_count, uint32_t max_count) +{ + return errno_knl2cosit(tos_sem_create_max_dyn((k_sem_t **)sem, (k_sem_cnt_t)init_count, (k_sem_cnt_t)max_count)); +} + +cos_status_t cos_sem_delete(cos_sem_t sem) +{ + return errno_knl2cosit(tos_sem_destroy_dyn((k_sem_t *)sem)); +} + +cos_status_t cos_sem_init(cos_sem_t sem, char *name, uint32_t init_count, uint32_t max_count) +{ + return errno_knl2cosit(tos_sem_create_max((k_sem_t *)sem, (k_sem_cnt_t)init_count, (k_sem_cnt_t)max_count)); +} + +cos_status_t cos_sem_deinit(cos_sem_t sem) +{ + return errno_knl2cosit(tos_sem_destroy((k_sem_t *)sem)); +} + +cos_status_t cos_sem_wait(cos_sem_t *sem, cos_tick_t timeout) +{ + return errno_knl2cosit(tos_sem_pend((k_sem_t *)sem, (k_tick_t)timeout)); +} + +cos_status_t cos_sem_release(cos_sem_t sem) +{ + return errno_knl2cosit(tos_sem_post((k_sem_t *)sem)); +} + +#else + +cos_status_t cos_sem_create(cos_sem_t *sem, char *name, uint32_t init_count, uint32_t max_count) +{ + return COS_ERR; +} + +cos_status_t cos_sem_delete(cos_sem_t sem) +{ + return COS_ERR; +} + +cos_status_t cos_sem_init(cos_sem_t sem, char *name, uint32_t init_count, uint32_t max_count) +{ + return COS_ERR; +} + +cos_status_t cos_sem_deinit(cos_sem_t sem) +{ + return COS_ERR; +} + +cos_status_t cos_sem_wait(cos_sem_t *sem, cos_tick_t timeout) +{ + return COS_ERR; +} + +cos_status_t cos_sem_release(cos_sem_t sem) +{ + return COS_ERR; +} + +#endif /* TOS_CFG_SEM_EN */ + +#if TOS_CFG_EVENT_EN > 0 + +cos_status_t cos_event_create(cos_event_t *event, char *name, cos_event_flag_t init_flag) +{ + return errno_knl2cosit(tos_event_create_dyn((k_event_t **)event, (k_event_flag_t)init_flag)); +} + +cos_status_t cos_event_delete(cos_event_t event) +{ + return errno_knl2cosit(tos_event_destroy_dyn((k_event_t *)event)); +} + +cos_status_t cos_event_init(cos_event_t event, char *name, cos_event_flag_t init_flag) +{ + return errno_knl2cosit(tos_event_create((k_event_t *)event, (k_event_flag_t)init_flag)); +} + +cos_status_t cos_event_deinit(cos_event_t event) +{ + return errno_knl2cosit(tos_event_destroy((k_event_t *)event)); +} + +cos_status_t cos_event_wait(cos_event_t event, cos_event_flag_t expect_flag, cos_tick_t timeout, cos_event_flag_t *match_flag, uint32_t options) +{ + k_opt_t opt; + + if (options == COS_EVENT_WAIT_ANY) { + opt |= TOS_OPT_EVENT_PEND_ANY; + } else if (options == COS_EVENT_WAIT_ALL) { + opt |= TOS_OPT_EVENT_PEND_ALL; + } + + if (options == COS_EVENT_WAIT_CLR) { + opt |= TOS_OPT_EVENT_PEND_CLR; + } + + return errno_knl2cosit(tos_event_pend((k_event_t *)event, + (k_event_flag_t)expect_flag, (k_event_flag_t *)match_flag, + (k_tick_t)timeout, opt)); +} + +cos_status_t cos_event_release(cos_event_t event, cos_event_flag_t flag, uint32_t options) +{ + if (options == COS_EVENT_RELEASE_KEEP) { + return errno_knl2cosit(tos_event_post_keep((k_event_t *)event, (k_event_flag_t)flag)); + } else { + return errno_knl2cosit(tos_event_post((k_event_t *)event, (k_event_flag_t)flag)); + } +} + +#else + +cos_status_t cos_event_create(cos_event_t *event, char *name, cos_event_flag_t init_flag) +{ + return COS_ERR; +} + +cos_status_t cos_event_delete(cos_event_t event) +{ + return COS_ERR; +} + +cos_status_t cos_event_init(cos_event_t event, char *name, cos_event_flag_t init_flag) +{ + return COS_ERR; +} + +cos_status_t cos_event_deinit(cos_event_t event) +{ + return COS_ERR; +} + +cos_status_t cos_event_wait(cos_event_t event, cos_event_flag_t expect_flag, cos_tick_t timeout, cos_event_flag_t *match_flag, uint32_t options) +{ + return COS_ERR; +} + +cos_status_t cos_event_release(cos_event_t event, cos_event_flag_t flag, uint32_t options) +{ + return COS_ERR; +} + +#endif \ No newline at end of file diff --git a/osal/cosit/test/greatest/LICENSE b/osal/cosit/test/greatest/LICENSE new file mode 100644 index 0000000..2fdef96 --- /dev/null +++ b/osal/cosit/test/greatest/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2011-2018 Scott Vokes + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/osal/cosit/test/greatest/greatest.h b/osal/cosit/test/greatest/greatest.h new file mode 100644 index 0000000..af0c053 --- /dev/null +++ b/osal/cosit/test/greatest/greatest.h @@ -0,0 +1,1266 @@ +/* + * Copyright (c) 2011-2021 Scott Vokes + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#ifndef GREATEST_H +#define GREATEST_H + +#if defined(__cplusplus) && !defined(GREATEST_NO_EXTERN_CPLUSPLUS) +extern "C" { +#endif + +/* 1.5.0 */ +#define GREATEST_VERSION_MAJOR 1 +#define GREATEST_VERSION_MINOR 5 +#define GREATEST_VERSION_PATCH 0 + +/* A unit testing system for C, contained in 1 file. + * It doesn't use dynamic allocation or depend on anything + * beyond ANSI C89. + * + * An up-to-date version can be found at: + * https://github.com/silentbicycle/greatest/ + */ + + +/********************************************************************* + * Minimal test runner template + *********************************************************************/ +#if 0 + +#include "greatest.h" + +TEST foo_should_foo(void) { + PASS(); +} + +static void setup_cb(void *data) { + printf("setup callback for each test case\n"); +} + +static void teardown_cb(void *data) { + printf("teardown callback for each test case\n"); +} + +SUITE(suite) { + /* Optional setup/teardown callbacks which will be run before/after + * every test case. If using a test suite, they will be cleared when + * the suite finishes. */ + SET_SETUP(setup_cb, voidp_to_callback_data); + SET_TEARDOWN(teardown_cb, voidp_to_callback_data); + + RUN_TEST(foo_should_foo); +} + +/* Add definitions that need to be in the test runner's main file. */ +GREATEST_MAIN_DEFS(); + +/* Set up, run suite(s) of tests, report pass/fail/skip stats. */ +int run_tests(void) { + GREATEST_INIT(); /* init. greatest internals */ + /* List of suites to run (if any). */ + RUN_SUITE(suite); + + /* Tests can also be run directly, without using test suites. */ + RUN_TEST(foo_should_foo); + + GREATEST_PRINT_REPORT(); /* display results */ + return greatest_all_passed(); +} + +/* main(), for a standalone command-line test runner. + * This replaces run_tests above, and adds command line option + * handling and exiting with a pass/fail status. */ +int main(int argc, char **argv) { + GREATEST_MAIN_BEGIN(); /* init & parse command-line args */ + RUN_SUITE(suite); + GREATEST_MAIN_END(); /* display results */ +} + +#endif +/*********************************************************************/ + + +#include +#include +#include +#include + +/*********** + * Options * + ***********/ + +/* Default column width for non-verbose output. */ +#ifndef GREATEST_DEFAULT_WIDTH +#define GREATEST_DEFAULT_WIDTH 72 +#endif + +/* FILE *, for test logging. */ +#ifndef GREATEST_STDOUT +#define GREATEST_STDOUT stdout +#endif + +/* Remove GREATEST_ prefix from most commonly used symbols? */ +#ifndef GREATEST_USE_ABBREVS +#define GREATEST_USE_ABBREVS 1 +#endif + +/* Set to 0 to disable all use of setjmp/longjmp. */ +#ifndef GREATEST_USE_LONGJMP +#define GREATEST_USE_LONGJMP 0 +#endif + +/* Make it possible to replace fprintf with another + * function with the same interface. */ +#ifndef GREATEST_FPRINTF +#define GREATEST_FPRINTF fprintf +#endif + +#if GREATEST_USE_LONGJMP +#include +#endif + +/* Set to 0 to disable all use of time.h / clock(). */ +#ifndef GREATEST_USE_TIME +#define GREATEST_USE_TIME 1 +#endif + +#if GREATEST_USE_TIME +#include +#endif + +/* Floating point type, for ASSERT_IN_RANGE. */ +#ifndef GREATEST_FLOAT +#define GREATEST_FLOAT double +#define GREATEST_FLOAT_FMT "%g" +#endif + +/* Size of buffer for test name + optional '_' separator and suffix */ +#ifndef GREATEST_TESTNAME_BUF_SIZE +#define GREATEST_TESTNAME_BUF_SIZE 128 +#endif + + +/********* + * Types * + *********/ + +/* Info for the current running suite. */ +typedef struct greatest_suite_info { + unsigned int tests_run; + unsigned int passed; + unsigned int failed; + unsigned int skipped; + +#if GREATEST_USE_TIME + /* timers, pre/post running suite and individual tests */ + clock_t pre_suite; + clock_t post_suite; + clock_t pre_test; + clock_t post_test; +#endif +} greatest_suite_info; + +/* Type for a suite function. */ +typedef void greatest_suite_cb(void); + +/* Types for setup/teardown callbacks. If non-NULL, these will be run + * and passed the pointer to their additional data. */ +typedef void greatest_setup_cb(void *udata); +typedef void greatest_teardown_cb(void *udata); + +/* Type for an equality comparison between two pointers of the same type. + * Should return non-0 if equal, otherwise 0. + * UDATA is a closure value, passed through from ASSERT_EQUAL_T[m]. */ +typedef int greatest_equal_cb(const void *expd, const void *got, void *udata); + +/* Type for a callback that prints a value pointed to by T. + * Return value has the same meaning as printf's. + * UDATA is a closure value, passed through from ASSERT_EQUAL_T[m]. */ +typedef int greatest_printf_cb(const void *t, void *udata); + +/* Callbacks for an arbitrary type; needed for type-specific + * comparisons via GREATEST_ASSERT_EQUAL_T[m].*/ +typedef struct greatest_type_info { + greatest_equal_cb *equal; + greatest_printf_cb *print; +} greatest_type_info; + +typedef struct greatest_memory_cmp_env { + const unsigned char *exp; + const unsigned char *got; + size_t size; +} greatest_memory_cmp_env; + +/* Callbacks for string and raw memory types. */ +extern greatest_type_info greatest_type_info_string; +extern greatest_type_info greatest_type_info_memory; + +typedef enum { + GREATEST_FLAG_FIRST_FAIL = 0x01, + GREATEST_FLAG_LIST_ONLY = 0x02, + GREATEST_FLAG_ABORT_ON_FAIL = 0x04 +} greatest_flag_t; + +/* Internal state for a PRNG, used to shuffle test order. */ +struct greatest_prng { + unsigned char random_order; /* use random ordering? */ + unsigned char initialized; /* is random ordering initialized? */ + unsigned char pad_0[6]; + unsigned long state; /* PRNG state */ + unsigned long count; /* how many tests, this pass */ + unsigned long count_ceil; /* total number of tests */ + unsigned long count_run; /* total tests run */ + unsigned long a; /* LCG multiplier */ + unsigned long c; /* LCG increment */ + unsigned long m; /* LCG modulus, based on count_ceil */ +}; + +/* Struct containing all test runner state. */ +typedef struct greatest_run_info { + unsigned char flags; + unsigned char verbosity; + unsigned char running_test; /* guard for nested RUN_TEST calls */ + unsigned char exact_name_match; + + unsigned int tests_run; /* total test count */ + + /* currently running test suite */ + greatest_suite_info suite; + + /* overall pass/fail/skip counts */ + unsigned int passed; + unsigned int failed; + unsigned int skipped; + unsigned int assertions; + + /* info to print about the most recent failure */ + unsigned int fail_line; + unsigned int pad_1; + const char *fail_file; + const char *msg; + + /* current setup/teardown hooks and userdata */ + greatest_setup_cb *setup; + void *setup_udata; + greatest_teardown_cb *teardown; + void *teardown_udata; + + /* formatting info for ".....s...F"-style output */ + unsigned int col; + unsigned int width; + + /* only run a specific suite or test */ + const char *suite_filter; + const char *test_filter; + const char *test_exclude; + const char *name_suffix; /* print suffix with test name */ + char name_buf[GREATEST_TESTNAME_BUF_SIZE]; + + struct greatest_prng prng[2]; /* 0: suites, 1: tests */ + +#if GREATEST_USE_TIME + /* overall timers */ + clock_t begin; + clock_t end; +#endif + +#if GREATEST_USE_LONGJMP + int pad_jmp_buf; + unsigned char pad_2[4]; + jmp_buf jump_dest; +#endif +} greatest_run_info; + +struct greatest_report_t { + /* overall pass/fail/skip counts */ + unsigned int passed; + unsigned int failed; + unsigned int skipped; + unsigned int assertions; +}; + +/* Global var for the current testing context. + * Initialized by GREATEST_MAIN_DEFS(). */ +extern greatest_run_info greatest_info; + +/* Type for ASSERT_ENUM_EQ's ENUM_STR argument. */ +typedef const char *greatest_enum_str_fun(int value); + + +/********************** + * Exported functions * + **********************/ + +/* These are used internally by greatest macros. */ +int greatest_test_pre(const char *name); +void greatest_test_post(int res); +int greatest_do_assert_equal_t(const void *expd, const void *got, + greatest_type_info *type_info, void *udata); +void greatest_prng_init_first_pass(int id); +int greatest_prng_init_second_pass(int id, unsigned long seed); +void greatest_prng_step(int id); + +/* These are part of the public greatest API. */ +void GREATEST_SET_SETUP_CB(greatest_setup_cb *cb, void *udata); +void GREATEST_SET_TEARDOWN_CB(greatest_teardown_cb *cb, void *udata); +void GREATEST_INIT(void); +void GREATEST_PRINT_REPORT(void); +int greatest_all_passed(void); +void greatest_set_suite_filter(const char *filter); +void greatest_set_test_filter(const char *filter); +void greatest_set_test_exclude(const char *filter); +void greatest_set_exact_name_match(void); +void greatest_stop_at_first_fail(void); +void greatest_abort_on_fail(void); +void greatest_list_only(void); +void greatest_get_report(struct greatest_report_t *report); +unsigned int greatest_get_verbosity(void); +void greatest_set_verbosity(unsigned int verbosity); +void greatest_set_flag(greatest_flag_t flag); +void greatest_set_test_suffix(const char *suffix); + + +/******************** +* Language Support * +********************/ + +/* If __VA_ARGS__ (C99) is supported, allow parametric testing +* without needing to manually manage the argument struct. */ +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 19901L) || \ + (defined(_MSC_VER) && _MSC_VER >= 1800) +#define GREATEST_VA_ARGS +#endif + + +/********** + * Macros * + **********/ + +/* Define a suite. (The duplication is intentional -- it eliminates + * a warning from -Wmissing-declarations.) */ +#define GREATEST_SUITE(NAME) void NAME(void); void NAME(void) + +/* Declare a suite, provided by another compilation unit. */ +#define GREATEST_SUITE_EXTERN(NAME) void NAME(void) + +/* Start defining a test function. + * The arguments are not included, to allow parametric testing. */ +#define GREATEST_TEST static enum greatest_test_res + +/* PASS/FAIL/SKIP result from a test. Used internally. */ +typedef enum greatest_test_res { + GREATEST_TEST_RES_PASS = 0, + GREATEST_TEST_RES_FAIL = -1, + GREATEST_TEST_RES_SKIP = 1 +} greatest_test_res; + +/* Run a suite. */ +#define GREATEST_RUN_SUITE(S_NAME) greatest_run_suite(S_NAME, #S_NAME) + +/* Run a test in the current suite. */ +#define GREATEST_RUN_TEST(TEST) \ + do { \ + if (greatest_test_pre(#TEST) == 1) { \ + enum greatest_test_res res = GREATEST_SAVE_CONTEXT(); \ + if (res == GREATEST_TEST_RES_PASS) { \ + res = TEST(); \ + } \ + greatest_test_post(res); \ + } \ + } while (0) + +/* Ignore a test, don't warn about it being unused. */ +#define GREATEST_IGNORE_TEST(TEST) (void)TEST + +/* Run a test in the current suite with one void * argument, + * which can be a pointer to a struct with multiple arguments. */ +#define GREATEST_RUN_TEST1(TEST, ENV) \ + do { \ + if (greatest_test_pre(#TEST) == 1) { \ + enum greatest_test_res res = GREATEST_SAVE_CONTEXT(); \ + if (res == GREATEST_TEST_RES_PASS) { \ + res = TEST(ENV); \ + } \ + greatest_test_post(res); \ + } \ + } while (0) + +#ifdef GREATEST_VA_ARGS +#define GREATEST_RUN_TESTp(TEST, ...) \ + do { \ + if (greatest_test_pre(#TEST) == 1) { \ + enum greatest_test_res res = GREATEST_SAVE_CONTEXT(); \ + if (res == GREATEST_TEST_RES_PASS) { \ + res = TEST(__VA_ARGS__); \ + } \ + greatest_test_post(res); \ + } \ + } while (0) +#endif + + +/* Check if the test runner is in verbose mode. */ +#define GREATEST_IS_VERBOSE() ((greatest_info.verbosity) > 0) +#define GREATEST_LIST_ONLY() \ + (greatest_info.flags & GREATEST_FLAG_LIST_ONLY) +#define GREATEST_FIRST_FAIL() \ + (greatest_info.flags & GREATEST_FLAG_FIRST_FAIL) +#define GREATEST_ABORT_ON_FAIL() \ + (greatest_info.flags & GREATEST_FLAG_ABORT_ON_FAIL) +#define GREATEST_FAILURE_ABORT() \ + (GREATEST_FIRST_FAIL() && \ + (greatest_info.suite.failed > 0 || greatest_info.failed > 0)) + +/* Message-less forms of tests defined below. */ +#define GREATEST_PASS() GREATEST_PASSm(NULL) +#define GREATEST_FAIL() GREATEST_FAILm(NULL) +#define GREATEST_SKIP() GREATEST_SKIPm(NULL) +#define GREATEST_ASSERT(COND) \ + GREATEST_ASSERTm(#COND, COND) +#define GREATEST_ASSERT_OR_LONGJMP(COND) \ + GREATEST_ASSERT_OR_LONGJMPm(#COND, COND) +#define GREATEST_ASSERT_FALSE(COND) \ + GREATEST_ASSERT_FALSEm(#COND, COND) +#define GREATEST_ASSERT_EQ(EXP, GOT) \ + GREATEST_ASSERT_EQm(#EXP " != " #GOT, EXP, GOT) +#define GREATEST_ASSERT_NEQ(EXP, GOT) \ + GREATEST_ASSERT_NEQm(#EXP " == " #GOT, EXP, GOT) +#define GREATEST_ASSERT_GT(EXP, GOT) \ + GREATEST_ASSERT_GTm(#EXP " <= " #GOT, EXP, GOT) +#define GREATEST_ASSERT_GTE(EXP, GOT) \ + GREATEST_ASSERT_GTEm(#EXP " < " #GOT, EXP, GOT) +#define GREATEST_ASSERT_LT(EXP, GOT) \ + GREATEST_ASSERT_LTm(#EXP " >= " #GOT, EXP, GOT) +#define GREATEST_ASSERT_LTE(EXP, GOT) \ + GREATEST_ASSERT_LTEm(#EXP " > " #GOT, EXP, GOT) +#define GREATEST_ASSERT_EQ_FMT(EXP, GOT, FMT) \ + GREATEST_ASSERT_EQ_FMTm(#EXP " != " #GOT, EXP, GOT, FMT) +#define GREATEST_ASSERT_IN_RANGE(EXP, GOT, TOL) \ + GREATEST_ASSERT_IN_RANGEm(#EXP " != " #GOT " +/- " #TOL, EXP, GOT, TOL) +#define GREATEST_ASSERT_EQUAL_T(EXP, GOT, TYPE_INFO, UDATA) \ + GREATEST_ASSERT_EQUAL_Tm(#EXP " != " #GOT, EXP, GOT, TYPE_INFO, UDATA) +#define GREATEST_ASSERT_STR_EQ(EXP, GOT) \ + GREATEST_ASSERT_STR_EQm(#EXP " != " #GOT, EXP, GOT) +#define GREATEST_ASSERT_STRN_EQ(EXP, GOT, SIZE) \ + GREATEST_ASSERT_STRN_EQm(#EXP " != " #GOT, EXP, GOT, SIZE) +#define GREATEST_ASSERT_MEM_EQ(EXP, GOT, SIZE) \ + GREATEST_ASSERT_MEM_EQm(#EXP " != " #GOT, EXP, GOT, SIZE) +#define GREATEST_ASSERT_ENUM_EQ(EXP, GOT, ENUM_STR) \ + GREATEST_ASSERT_ENUM_EQm(#EXP " != " #GOT, EXP, GOT, ENUM_STR) + +/* The following forms take an additional message argument first, + * to be displayed by the test runner. */ + +/* Fail if a condition is not true, with message. */ +#define GREATEST_ASSERTm(MSG, COND) \ + do { \ + greatest_info.assertions++; \ + if (!(COND)) { GREATEST_FAILm(MSG); } \ + } while (0) + +/* Fail if a condition is not true, longjmping out of test. */ +#define GREATEST_ASSERT_OR_LONGJMPm(MSG, COND) \ + do { \ + greatest_info.assertions++; \ + if (!(COND)) { GREATEST_FAIL_WITH_LONGJMPm(MSG); } \ + } while (0) + +/* Fail if a condition is not false, with message. */ +#define GREATEST_ASSERT_FALSEm(MSG, COND) \ + do { \ + greatest_info.assertions++; \ + if ((COND)) { GREATEST_FAILm(MSG); } \ + } while (0) + +/* Internal macro for relational assertions */ +#define GREATEST__REL(REL, MSG, EXP, GOT) \ + do { \ + greatest_info.assertions++; \ + if (!((EXP) REL (GOT))) { GREATEST_FAILm(MSG); } \ + } while (0) + +/* Fail if EXP is not ==, !=, >, <, >=, or <= to GOT. */ +#define GREATEST_ASSERT_EQm(MSG,E,G) GREATEST__REL(==, MSG,E,G) +#define GREATEST_ASSERT_NEQm(MSG,E,G) GREATEST__REL(!=, MSG,E,G) +#define GREATEST_ASSERT_GTm(MSG,E,G) GREATEST__REL(>, MSG,E,G) +#define GREATEST_ASSERT_GTEm(MSG,E,G) GREATEST__REL(>=, MSG,E,G) +#define GREATEST_ASSERT_LTm(MSG,E,G) GREATEST__REL(<, MSG,E,G) +#define GREATEST_ASSERT_LTEm(MSG,E,G) GREATEST__REL(<=, MSG,E,G) + +/* Fail if EXP != GOT (equality comparison by ==). + * Warning: FMT, EXP, and GOT will be evaluated more + * than once on failure. */ +#define GREATEST_ASSERT_EQ_FMTm(MSG, EXP, GOT, FMT) \ + do { \ + greatest_info.assertions++; \ + if ((EXP) != (GOT)) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\nExpected: "); \ + GREATEST_FPRINTF(GREATEST_STDOUT, FMT, EXP); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n Got: "); \ + GREATEST_FPRINTF(GREATEST_STDOUT, FMT, GOT); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + GREATEST_FAILm(MSG); \ + } \ + } while (0) + +/* Fail if EXP is not equal to GOT, printing enum IDs. */ +#define GREATEST_ASSERT_ENUM_EQm(MSG, EXP, GOT, ENUM_STR) \ + do { \ + int greatest_EXP = (int)(EXP); \ + int greatest_GOT = (int)(GOT); \ + greatest_enum_str_fun *greatest_ENUM_STR = ENUM_STR; \ + if (greatest_EXP != greatest_GOT) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\nExpected: %s", \ + greatest_ENUM_STR(greatest_EXP)); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n Got: %s\n", \ + greatest_ENUM_STR(greatest_GOT)); \ + GREATEST_FAILm(MSG); \ + } \ + } while (0) \ + +/* Fail if GOT not in range of EXP +|- TOL. */ +#define GREATEST_ASSERT_IN_RANGEm(MSG, EXP, GOT, TOL) \ + do { \ + GREATEST_FLOAT greatest_EXP = (EXP); \ + GREATEST_FLOAT greatest_GOT = (GOT); \ + GREATEST_FLOAT greatest_TOL = (TOL); \ + greatest_info.assertions++; \ + if ((greatest_EXP > greatest_GOT && \ + greatest_EXP - greatest_GOT > greatest_TOL) || \ + (greatest_EXP < greatest_GOT && \ + greatest_GOT - greatest_EXP > greatest_TOL)) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "\nExpected: " GREATEST_FLOAT_FMT \ + " +/- " GREATEST_FLOAT_FMT \ + "\n Got: " GREATEST_FLOAT_FMT \ + "\n", \ + greatest_EXP, greatest_TOL, greatest_GOT); \ + GREATEST_FAILm(MSG); \ + } \ + } while (0) + +/* Fail if EXP is not equal to GOT, according to strcmp. */ +#define GREATEST_ASSERT_STR_EQm(MSG, EXP, GOT) \ + do { \ + GREATEST_ASSERT_EQUAL_Tm(MSG, EXP, GOT, \ + &greatest_type_info_string, NULL); \ + } while (0) \ + +/* Fail if EXP is not equal to GOT, according to strncmp. */ +#define GREATEST_ASSERT_STRN_EQm(MSG, EXP, GOT, SIZE) \ + do { \ + size_t size = SIZE; \ + GREATEST_ASSERT_EQUAL_Tm(MSG, EXP, GOT, \ + &greatest_type_info_string, &size); \ + } while (0) \ + +/* Fail if EXP is not equal to GOT, according to memcmp. */ +#define GREATEST_ASSERT_MEM_EQm(MSG, EXP, GOT, SIZE) \ + do { \ + greatest_memory_cmp_env env; \ + env.exp = (const unsigned char *)EXP; \ + env.got = (const unsigned char *)GOT; \ + env.size = SIZE; \ + GREATEST_ASSERT_EQUAL_Tm(MSG, env.exp, env.got, \ + &greatest_type_info_memory, &env); \ + } while (0) \ + +/* Fail if EXP is not equal to GOT, according to a comparison + * callback in TYPE_INFO. If they are not equal, optionally use a + * print callback in TYPE_INFO to print them. */ +#define GREATEST_ASSERT_EQUAL_Tm(MSG, EXP, GOT, TYPE_INFO, UDATA) \ + do { \ + greatest_type_info *type_info = (TYPE_INFO); \ + greatest_info.assertions++; \ + if (!greatest_do_assert_equal_t(EXP, GOT, \ + type_info, UDATA)) { \ + if (type_info == NULL || type_info->equal == NULL) { \ + GREATEST_FAILm("type_info->equal callback missing!"); \ + } else { \ + GREATEST_FAILm(MSG); \ + } \ + } \ + } while (0) \ + +/* Pass. */ +#define GREATEST_PASSm(MSG) \ + do { \ + greatest_info.msg = MSG; \ + return GREATEST_TEST_RES_PASS; \ + } while (0) + +/* Fail. */ +#define GREATEST_FAILm(MSG) \ + do { \ + greatest_info.fail_file = __FILE__; \ + greatest_info.fail_line = __LINE__; \ + greatest_info.msg = MSG; \ + if (GREATEST_ABORT_ON_FAIL()) { abort(); } \ + return GREATEST_TEST_RES_FAIL; \ + } while (0) + +/* Optional GREATEST_FAILm variant that longjmps. */ +#if GREATEST_USE_LONGJMP +#define GREATEST_FAIL_WITH_LONGJMP() GREATEST_FAIL_WITH_LONGJMPm(NULL) +#define GREATEST_FAIL_WITH_LONGJMPm(MSG) \ + do { \ + greatest_info.fail_file = __FILE__; \ + greatest_info.fail_line = __LINE__; \ + greatest_info.msg = MSG; \ + longjmp(greatest_info.jump_dest, GREATEST_TEST_RES_FAIL); \ + } while (0) +#endif + +/* Skip the current test. */ +#define GREATEST_SKIPm(MSG) \ + do { \ + greatest_info.msg = MSG; \ + return GREATEST_TEST_RES_SKIP; \ + } while (0) + +/* Check the result of a subfunction using ASSERT, etc. */ +#define GREATEST_CHECK_CALL(RES) \ + do { \ + enum greatest_test_res greatest_RES = RES; \ + if (greatest_RES != GREATEST_TEST_RES_PASS) { \ + return greatest_RES; \ + } \ + } while (0) \ + +#if GREATEST_USE_TIME +#define GREATEST_SET_TIME(NAME) \ + NAME = clock(); \ + if (NAME == (clock_t) -1) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "clock error: %s\n", #NAME); \ + exit(EXIT_FAILURE); \ + } + +#define GREATEST_CLOCK_DIFF(C1, C2) \ + GREATEST_FPRINTF(GREATEST_STDOUT, " (%lu ticks, %.3f sec)", \ + (long unsigned int) (C2) - (long unsigned int)(C1), \ + (double)((C2) - (C1)) / (1.0 * (double)CLOCKS_PER_SEC)) +#else +#define GREATEST_SET_TIME(UNUSED) +#define GREATEST_CLOCK_DIFF(UNUSED1, UNUSED2) +#endif + +#if GREATEST_USE_LONGJMP +#define GREATEST_SAVE_CONTEXT() \ + /* setjmp returns 0 (GREATEST_TEST_RES_PASS) on first call * \ + * so the test runs, then RES_FAIL from FAIL_WITH_LONGJMP. */ \ + ((enum greatest_test_res)(setjmp(greatest_info.jump_dest))) +#else +#define GREATEST_SAVE_CONTEXT() \ + /*a no-op, since setjmp/longjmp aren't being used */ \ + GREATEST_TEST_RES_PASS +#endif + +/* Run every suite / test function run within BODY in pseudo-random + * order, seeded by SEED. (The top 3 bits of the seed are ignored.) + * + * This should be called like: + * GREATEST_SHUFFLE_TESTS(seed, { + * GREATEST_RUN_TEST(some_test); + * GREATEST_RUN_TEST(some_other_test); + * GREATEST_RUN_TEST(yet_another_test); + * }); + * + * Note that the body of the second argument will be evaluated + * multiple times. */ +#define GREATEST_SHUFFLE_SUITES(SD, BODY) GREATEST_SHUFFLE(0, SD, BODY) +#define GREATEST_SHUFFLE_TESTS(SD, BODY) GREATEST_SHUFFLE(1, SD, BODY) +#define GREATEST_SHUFFLE(ID, SD, BODY) \ + do { \ + struct greatest_prng *prng = &greatest_info.prng[ID]; \ + greatest_prng_init_first_pass(ID); \ + do { \ + prng->count = 0; \ + if (prng->initialized) { greatest_prng_step(ID); } \ + BODY; \ + if (!prng->initialized) { \ + if (!greatest_prng_init_second_pass(ID, SD)) { break; } \ + } else if (prng->count_run == prng->count_ceil) { \ + break; \ + } \ + } while (!GREATEST_FAILURE_ABORT()); \ + prng->count_run = prng->random_order = prng->initialized = 0; \ + } while(0) + +/* Include several function definitions in the main test file. */ +#define GREATEST_MAIN_DEFS() \ + \ +/* Is FILTER a subset of NAME? */ \ +static int greatest_name_match(const char *name, const char *filter, \ + int res_if_none) { \ + size_t offset = 0; \ + size_t filter_len = filter ? strlen(filter) : 0; \ + if (filter_len == 0) { return res_if_none; } /* no filter */ \ + if (greatest_info.exact_name_match && strlen(name) != filter_len) { \ + return 0; /* ignore substring matches */ \ + } \ + while (name[offset] != '\0') { \ + if (name[offset] == filter[0]) { \ + if (0 == strncmp(&name[offset], filter, filter_len)) { \ + return 1; \ + } \ + } \ + offset++; \ + } \ + \ + return 0; \ +} \ + \ +static void greatest_buffer_test_name(const char *name) { \ + struct greatest_run_info *g = &greatest_info; \ + size_t len = strlen(name), size = sizeof(g->name_buf); \ + memset(g->name_buf, 0x00, size); \ + (void)strncat(g->name_buf, name, size - 1); \ + if (g->name_suffix && (len + 1 < size)) { \ + g->name_buf[len] = '_'; \ + strncat(&g->name_buf[len+1], g->name_suffix, size-(len+2)); \ + } \ +} \ + \ +/* Before running a test, check the name filtering and \ + * test shuffling state, if applicable, and then call setup hooks. */ \ +int greatest_test_pre(const char *name) { \ + struct greatest_run_info *g = &greatest_info; \ + int match; \ + greatest_buffer_test_name(name); \ + match = greatest_name_match(g->name_buf, g->test_filter, 1) && \ + !greatest_name_match(g->name_buf, g->test_exclude, 0); \ + if (GREATEST_LIST_ONLY()) { /* just listing test names */ \ + if (match) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, " %s\n", g->name_buf); \ + } \ + goto clear; \ + } \ + if (match && (!GREATEST_FIRST_FAIL() || g->suite.failed == 0)) { \ + struct greatest_prng *p = &g->prng[1]; \ + if (p->random_order) { \ + p->count++; \ + if (!p->initialized || ((p->count - 1) != p->state)) { \ + goto clear; /* don't run this test yet */ \ + } \ + } \ + if (g->running_test) { \ + fprintf(stderr, "Error: Test run inside another test.\n"); \ + return 0; \ + } \ + GREATEST_SET_TIME(g->suite.pre_test); \ + if (g->setup) { g->setup(g->setup_udata); } \ + p->count_run++; \ + g->running_test = 1; \ + return 1; /* test should be run */ \ + } else { \ + goto clear; /* skipped */ \ + } \ +clear: \ + g->name_suffix = NULL; \ + return 0; \ +} \ + \ +static void greatest_do_pass(void) { \ + struct greatest_run_info *g = &greatest_info; \ + if (GREATEST_IS_VERBOSE()) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "PASS %s: %s", \ + g->name_buf, g->msg ? g->msg : ""); \ + } else { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "."); \ + } \ + g->suite.passed++; \ +} \ + \ +static void greatest_do_fail(void) { \ + struct greatest_run_info *g = &greatest_info; \ + if (GREATEST_IS_VERBOSE()) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "FAIL %s: %s (%s:%u)", g->name_buf, \ + g->msg ? g->msg : "", g->fail_file, g->fail_line); \ + } else { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "F"); \ + g->col++; /* add linebreak if in line of '.'s */ \ + if (g->col != 0) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + g->col = 0; \ + } \ + GREATEST_FPRINTF(GREATEST_STDOUT, "FAIL %s: %s (%s:%u)\n", \ + g->name_buf, g->msg ? g->msg : "", \ + g->fail_file, g->fail_line); \ + } \ + g->suite.failed++; \ +} \ + \ +static void greatest_do_skip(void) { \ + struct greatest_run_info *g = &greatest_info; \ + if (GREATEST_IS_VERBOSE()) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "SKIP %s: %s", \ + g->name_buf, g->msg ? g->msg : ""); \ + } else { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "s"); \ + } \ + g->suite.skipped++; \ +} \ + \ +void greatest_test_post(int res) { \ + GREATEST_SET_TIME(greatest_info.suite.post_test); \ + if (greatest_info.teardown) { \ + void *udata = greatest_info.teardown_udata; \ + greatest_info.teardown(udata); \ + } \ + \ + greatest_info.running_test = 0; \ + if (res <= GREATEST_TEST_RES_FAIL) { \ + greatest_do_fail(); \ + } else if (res >= GREATEST_TEST_RES_SKIP) { \ + greatest_do_skip(); \ + } else if (res == GREATEST_TEST_RES_PASS) { \ + greatest_do_pass(); \ + } \ + greatest_info.name_suffix = NULL; \ + greatest_info.suite.tests_run++; \ + greatest_info.col++; \ + if (GREATEST_IS_VERBOSE()) { \ + GREATEST_CLOCK_DIFF(greatest_info.suite.pre_test, \ + greatest_info.suite.post_test); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + } else if (greatest_info.col % greatest_info.width == 0) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + greatest_info.col = 0; \ + } \ + fflush(GREATEST_STDOUT); \ +} \ + \ +static void report_suite(void) { \ + if (greatest_info.suite.tests_run > 0) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "\n%u test%s - %u passed, %u failed, %u skipped", \ + greatest_info.suite.tests_run, \ + greatest_info.suite.tests_run == 1 ? "" : "s", \ + greatest_info.suite.passed, \ + greatest_info.suite.failed, \ + greatest_info.suite.skipped); \ + GREATEST_CLOCK_DIFF(greatest_info.suite.pre_suite, \ + greatest_info.suite.post_suite); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + } \ +} \ + \ +static void update_counts_and_reset_suite(void) { \ + greatest_info.setup = NULL; \ + greatest_info.setup_udata = NULL; \ + greatest_info.teardown = NULL; \ + greatest_info.teardown_udata = NULL; \ + greatest_info.passed += greatest_info.suite.passed; \ + greatest_info.failed += greatest_info.suite.failed; \ + greatest_info.skipped += greatest_info.suite.skipped; \ + greatest_info.tests_run += greatest_info.suite.tests_run; \ + memset(&greatest_info.suite, 0, sizeof(greatest_info.suite)); \ + greatest_info.col = 0; \ +} \ + \ +static int greatest_suite_pre(const char *suite_name) { \ + struct greatest_prng *p = &greatest_info.prng[0]; \ + if (!greatest_name_match(suite_name, greatest_info.suite_filter, 1) \ + || (GREATEST_FAILURE_ABORT())) { return 0; } \ + if (p->random_order) { \ + p->count++; \ + if (!p->initialized || ((p->count - 1) != p->state)) { \ + return 0; /* don't run this suite yet */ \ + } \ + } \ + p->count_run++; \ + update_counts_and_reset_suite(); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n* Suite %s:\n", suite_name); \ + GREATEST_SET_TIME(greatest_info.suite.pre_suite); \ + return 1; \ +} \ + \ +static void greatest_suite_post(void) { \ + GREATEST_SET_TIME(greatest_info.suite.post_suite); \ + report_suite(); \ +} \ + \ +static void greatest_run_suite(greatest_suite_cb *suite_cb, \ + const char *suite_name) { \ + if (greatest_suite_pre(suite_name)) { \ + suite_cb(); \ + greatest_suite_post(); \ + } \ +} \ + \ +int greatest_do_assert_equal_t(const void *expd, const void *got, \ + greatest_type_info *type_info, void *udata) { \ + int eq = 0; \ + if (type_info == NULL || type_info->equal == NULL) { return 0; } \ + eq = type_info->equal(expd, got, udata); \ + if (!eq) { \ + if (type_info->print != NULL) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\nExpected: "); \ + (void)type_info->print(expd, udata); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n Got: "); \ + (void)type_info->print(got, udata); \ + GREATEST_FPRINTF(GREATEST_STDOUT, "\n"); \ + } \ + } \ + return eq; \ +} \ + \ +static void greatest_usage(const char *name) { \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "Usage: %s [-hlfavex] [-s SUITE] [-t TEST] [-x EXCLUDE]\n" \ + " -h, --help print this Help\n" \ + " -l List suites and tests, then exit (dry run)\n" \ + " -f Stop runner after first failure\n" \ + " -a Abort on first failure (implies -f)\n" \ + " -v Verbose output\n" \ + " -s SUITE only run suites containing substring SUITE\n" \ + " -t TEST only run tests containing substring TEST\n" \ + " -e only run exact name match for -s or -t\n" \ + " -x EXCLUDE exclude tests containing substring EXCLUDE\n", \ + name); \ +} \ + \ +static void greatest_parse_options(int argc, char **argv) { \ + int i = 0; \ + for (i = 1; i < argc; i++) { \ + if (argv[i][0] == '-') { \ + char f = argv[i][1]; \ + if ((f == 's' || f == 't' || f == 'x') && argc <= i + 1) { \ + greatest_usage(argv[0]); exit(EXIT_FAILURE); \ + } \ + switch (f) { \ + case 's': /* suite name filter */ \ + greatest_set_suite_filter(argv[i + 1]); i++; break; \ + case 't': /* test name filter */ \ + greatest_set_test_filter(argv[i + 1]); i++; break; \ + case 'x': /* test name exclusion */ \ + greatest_set_test_exclude(argv[i + 1]); i++; break; \ + case 'e': /* exact name match */ \ + greatest_set_exact_name_match(); break; \ + case 'f': /* first fail flag */ \ + greatest_stop_at_first_fail(); break; \ + case 'a': /* abort() on fail flag */ \ + greatest_abort_on_fail(); break; \ + case 'l': /* list only (dry run) */ \ + greatest_list_only(); break; \ + case 'v': /* first fail flag */ \ + greatest_info.verbosity++; break; \ + case 'h': /* help */ \ + greatest_usage(argv[0]); exit(EXIT_SUCCESS); \ + default: \ + case '-': \ + if (0 == strncmp("--help", argv[i], 6)) { \ + greatest_usage(argv[0]); exit(EXIT_SUCCESS); \ + } else if (0 == strcmp("--", argv[i])) { \ + return; /* ignore following arguments */ \ + } \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "Unknown argument '%s'\n", argv[i]); \ + greatest_usage(argv[0]); \ + exit(EXIT_FAILURE); \ + } \ + } \ + } \ +} \ + \ +int greatest_all_passed(void) { return (greatest_info.failed == 0); } \ + \ +void greatest_set_test_filter(const char *filter) { \ + greatest_info.test_filter = filter; \ +} \ + \ +void greatest_set_test_exclude(const char *filter) { \ + greatest_info.test_exclude = filter; \ +} \ + \ +void greatest_set_suite_filter(const char *filter) { \ + greatest_info.suite_filter = filter; \ +} \ + \ +void greatest_set_exact_name_match(void) { \ + greatest_info.exact_name_match = 1; \ +} \ + \ +void greatest_stop_at_first_fail(void) { \ + greatest_set_flag(GREATEST_FLAG_FIRST_FAIL); \ +} \ + \ +void greatest_abort_on_fail(void) { \ + greatest_set_flag(GREATEST_FLAG_ABORT_ON_FAIL); \ +} \ + \ +void greatest_list_only(void) { \ + greatest_set_flag(GREATEST_FLAG_LIST_ONLY); \ +} \ + \ +void greatest_get_report(struct greatest_report_t *report) { \ + if (report) { \ + report->passed = greatest_info.passed; \ + report->failed = greatest_info.failed; \ + report->skipped = greatest_info.skipped; \ + report->assertions = greatest_info.assertions; \ + } \ +} \ + \ +unsigned int greatest_get_verbosity(void) { \ + return greatest_info.verbosity; \ +} \ + \ +void greatest_set_verbosity(unsigned int verbosity) { \ + greatest_info.verbosity = (unsigned char)verbosity; \ +} \ + \ +void greatest_set_flag(greatest_flag_t flag) { \ + greatest_info.flags = (unsigned char)(greatest_info.flags | flag); \ +} \ + \ +void greatest_set_test_suffix(const char *suffix) { \ + greatest_info.name_suffix = suffix; \ +} \ + \ +void GREATEST_SET_SETUP_CB(greatest_setup_cb *cb, void *udata) { \ + greatest_info.setup = cb; \ + greatest_info.setup_udata = udata; \ +} \ + \ +void GREATEST_SET_TEARDOWN_CB(greatest_teardown_cb *cb, void *udata) { \ + greatest_info.teardown = cb; \ + greatest_info.teardown_udata = udata; \ +} \ + \ +static int greatest_string_equal_cb(const void *expd, const void *got, \ + void *udata) { \ + size_t *size = (size_t *)udata; \ + return (size != NULL \ + ? (0 == strncmp((const char *)expd, (const char *)got, *size)) \ + : (0 == strcmp((const char *)expd, (const char *)got))); \ +} \ + \ +static int greatest_string_printf_cb(const void *t, void *udata) { \ + (void)udata; /* note: does not check \0 termination. */ \ + return GREATEST_FPRINTF(GREATEST_STDOUT, "%s", (const char *)t); \ +} \ + \ +greatest_type_info greatest_type_info_string = { \ + greatest_string_equal_cb, greatest_string_printf_cb, \ +}; \ + \ +static int greatest_memory_equal_cb(const void *expd, const void *got, \ + void *udata) { \ + greatest_memory_cmp_env *env = (greatest_memory_cmp_env *)udata; \ + return (0 == memcmp(expd, got, env->size)); \ +} \ + \ +/* Hexdump raw memory, with differences highlighted */ \ +static int greatest_memory_printf_cb(const void *t, void *udata) { \ + greatest_memory_cmp_env *env = (greatest_memory_cmp_env *)udata; \ + const unsigned char *buf = (const unsigned char *)t; \ + unsigned char diff_mark = ' '; \ + FILE *out = GREATEST_STDOUT; \ + size_t i, line_i, line_len = 0; \ + int len = 0; /* format hexdump with differences highlighted */ \ + for (i = 0; i < env->size; i+= line_len) { \ + diff_mark = ' '; \ + line_len = env->size - i; \ + if (line_len > 16) { line_len = 16; } \ + for (line_i = i; line_i < i + line_len; line_i++) { \ + if (env->exp[line_i] != env->got[line_i]) diff_mark = 'X'; \ + } \ + len += GREATEST_FPRINTF(out, "\n%04x %c ", \ + (unsigned int)i, diff_mark); \ + for (line_i = i; line_i < i + line_len; line_i++) { \ + int m = env->exp[line_i] == env->got[line_i]; /* match? */ \ + len += GREATEST_FPRINTF(out, "%02x%c", \ + buf[line_i], m ? ' ' : '<'); \ + } \ + for (line_i = 0; line_i < 16 - line_len; line_i++) { \ + len += GREATEST_FPRINTF(out, " "); \ + } \ + GREATEST_FPRINTF(out, " "); \ + for (line_i = i; line_i < i + line_len; line_i++) { \ + unsigned char c = buf[line_i]; \ + len += GREATEST_FPRINTF(out, "%c", isprint(c) ? c : '.'); \ + } \ + } \ + len += GREATEST_FPRINTF(out, "\n"); \ + return len; \ +} \ + \ +void greatest_prng_init_first_pass(int id) { \ + greatest_info.prng[id].random_order = 1; \ + greatest_info.prng[id].count_run = 0; \ +} \ + \ +int greatest_prng_init_second_pass(int id, unsigned long seed) { \ + struct greatest_prng *p = &greatest_info.prng[id]; \ + if (p->count == 0) { return 0; } \ + p->count_ceil = p->count; \ + for (p->m = 1; p->m < p->count; p->m <<= 1) {} \ + p->state = seed & 0x1fffffff; /* only use lower 29 bits */ \ + p->a = 4LU * p->state; /* to avoid overflow when */ \ + p->a = (p->a ? p->a : 4) | 1; /* multiplied by 4 */ \ + p->c = 2147483647; /* and so p->c ((2 ** 31) - 1) is */ \ + p->initialized = 1; /* always relatively prime to p->a. */ \ + fprintf(stderr, "init_second_pass: a %lu, c %lu, state %lu\n", \ + p->a, p->c, p->state); \ + return 1; \ +} \ + \ +/* Step the pseudorandom number generator until its state reaches \ + * another test ID between 0 and the test count. \ + * This use a linear congruential pseudorandom number generator, \ + * with the power-of-two ceiling of the test count as the modulus, the \ + * masked seed as the multiplier, and a prime as the increment. For \ + * each generated value < the test count, run the corresponding test. \ + * This will visit all IDs 0 <= X < mod once before repeating, \ + * with a starting position chosen based on the initial seed. \ + * For details, see: Knuth, The Art of Computer Programming \ + * Volume. 2, section 3.2.1. */ \ +void greatest_prng_step(int id) { \ + struct greatest_prng *p = &greatest_info.prng[id]; \ + do { \ + p->state = ((p->a * p->state) + p->c) & (p->m - 1); \ + } while (p->state >= p->count_ceil); \ +} \ + \ +void GREATEST_INIT(void) { \ + /* Suppress unused function warning if features aren't used */ \ + (void)greatest_run_suite; \ + (void)greatest_parse_options; \ + (void)greatest_prng_step; \ + (void)greatest_prng_init_first_pass; \ + (void)greatest_prng_init_second_pass; \ + (void)greatest_set_test_suffix; \ + \ + memset(&greatest_info, 0, sizeof(greatest_info)); \ + greatest_info.width = GREATEST_DEFAULT_WIDTH; \ + GREATEST_SET_TIME(greatest_info.begin); \ +} \ + \ +/* Report passes, failures, skipped tests, the number of \ + * assertions, and the overall run time. */ \ +void GREATEST_PRINT_REPORT(void) { \ + if (!GREATEST_LIST_ONLY()) { \ + update_counts_and_reset_suite(); \ + GREATEST_SET_TIME(greatest_info.end); \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "\nTotal: %u test%s", \ + greatest_info.tests_run, \ + greatest_info.tests_run == 1 ? "" : "s"); \ + GREATEST_CLOCK_DIFF(greatest_info.begin, \ + greatest_info.end); \ + GREATEST_FPRINTF(GREATEST_STDOUT, ", %u assertion%s\n", \ + greatest_info.assertions, \ + greatest_info.assertions == 1 ? "" : "s"); \ + GREATEST_FPRINTF(GREATEST_STDOUT, \ + "Pass: %u, fail: %u, skip: %u.\n", \ + greatest_info.passed, \ + greatest_info.failed, greatest_info.skipped); \ + } \ +} \ + \ +greatest_type_info greatest_type_info_memory = { \ + greatest_memory_equal_cb, greatest_memory_printf_cb, \ +}; \ + \ +greatest_run_info greatest_info + +/* Handle command-line arguments, etc. */ +#define GREATEST_MAIN_BEGIN() \ + do { \ + GREATEST_INIT(); \ + greatest_parse_options(argc, argv); \ + } while (0) + +/* Report results, exit with exit status based on results. */ +#define GREATEST_MAIN_END() \ + do { \ + GREATEST_PRINT_REPORT(); \ + return (greatest_all_passed() ? EXIT_SUCCESS : EXIT_FAILURE); \ + } while (0) + +/* Make abbreviations without the GREATEST_ prefix for the + * most commonly used symbols. */ +#if GREATEST_USE_ABBREVS +#define TEST GREATEST_TEST +#define SUITE GREATEST_SUITE +#define SUITE_EXTERN GREATEST_SUITE_EXTERN +#define RUN_TEST GREATEST_RUN_TEST +#define RUN_TEST1 GREATEST_RUN_TEST1 +#define RUN_SUITE GREATEST_RUN_SUITE +#define IGNORE_TEST GREATEST_IGNORE_TEST +#define ASSERT GREATEST_ASSERT +#define ASSERTm GREATEST_ASSERTm +#define ASSERT_FALSE GREATEST_ASSERT_FALSE +#define ASSERT_EQ GREATEST_ASSERT_EQ +#define ASSERT_NEQ GREATEST_ASSERT_NEQ +#define ASSERT_GT GREATEST_ASSERT_GT +#define ASSERT_GTE GREATEST_ASSERT_GTE +#define ASSERT_LT GREATEST_ASSERT_LT +#define ASSERT_LTE GREATEST_ASSERT_LTE +#define ASSERT_EQ_FMT GREATEST_ASSERT_EQ_FMT +#define ASSERT_IN_RANGE GREATEST_ASSERT_IN_RANGE +#define ASSERT_EQUAL_T GREATEST_ASSERT_EQUAL_T +#define ASSERT_STR_EQ GREATEST_ASSERT_STR_EQ +#define ASSERT_STRN_EQ GREATEST_ASSERT_STRN_EQ +#define ASSERT_MEM_EQ GREATEST_ASSERT_MEM_EQ +#define ASSERT_ENUM_EQ GREATEST_ASSERT_ENUM_EQ +#define ASSERT_FALSEm GREATEST_ASSERT_FALSEm +#define ASSERT_EQm GREATEST_ASSERT_EQm +#define ASSERT_NEQm GREATEST_ASSERT_NEQm +#define ASSERT_GTm GREATEST_ASSERT_GTm +#define ASSERT_GTEm GREATEST_ASSERT_GTEm +#define ASSERT_LTm GREATEST_ASSERT_LTm +#define ASSERT_LTEm GREATEST_ASSERT_LTEm +#define ASSERT_EQ_FMTm GREATEST_ASSERT_EQ_FMTm +#define ASSERT_IN_RANGEm GREATEST_ASSERT_IN_RANGEm +#define ASSERT_EQUAL_Tm GREATEST_ASSERT_EQUAL_Tm +#define ASSERT_STR_EQm GREATEST_ASSERT_STR_EQm +#define ASSERT_STRN_EQm GREATEST_ASSERT_STRN_EQm +#define ASSERT_MEM_EQm GREATEST_ASSERT_MEM_EQm +#define ASSERT_ENUM_EQm GREATEST_ASSERT_ENUM_EQm +#define PASS GREATEST_PASS +#define FAIL GREATEST_FAIL +#define SKIP GREATEST_SKIP +#define PASSm GREATEST_PASSm +#define FAILm GREATEST_FAILm +#define SKIPm GREATEST_SKIPm +#define SET_SETUP GREATEST_SET_SETUP_CB +#define SET_TEARDOWN GREATEST_SET_TEARDOWN_CB +#define CHECK_CALL GREATEST_CHECK_CALL +#define SHUFFLE_TESTS GREATEST_SHUFFLE_TESTS +#define SHUFFLE_SUITES GREATEST_SHUFFLE_SUITES + +#ifdef GREATEST_VA_ARGS +#define RUN_TESTp GREATEST_RUN_TESTp +#endif + +#if GREATEST_USE_LONGJMP +#define ASSERT_OR_LONGJMP GREATEST_ASSERT_OR_LONGJMP +#define ASSERT_OR_LONGJMPm GREATEST_ASSERT_OR_LONGJMPm +#define FAIL_WITH_LONGJMP GREATEST_FAIL_WITH_LONGJMP +#define FAIL_WITH_LONGJMPm GREATEST_FAIL_WITH_LONGJMPm +#endif + +#endif /* USE_ABBREVS */ + +#if defined(__cplusplus) && !defined(GREATEST_NO_EXTERN_CPLUSPLUS) +} +#endif + +#endif