uC/OS-II 函数之内存管理相关函数
最后更新于：2022-04-01 11:42:45
上文主要介绍了邮箱管理相关的函数，本文介绍内存管理相关的函数：OSMemCreate()内存块创建函数，OSMemGet()函数，OSMemPut()函数，OSMemQuery()函数.以前用过的uC/OS-II笔记分享到这里。
## 内存管理介绍
在ANSI C中可以用malloc()和free()两个函数动态地分配内存和释放内存。但是，在嵌入式实时操作系统中，多次这样做会把原来很大的一块连续内存区域，逐渐地分割成许多非常小而且彼此又不相邻的内存区域，也就是内存碎片。由于这些碎片的大量存在，使得程序到后来连非常小的内存也分配不到。另外，由于内存管理算法的原因，malloc()和free()函数执行时间是不确定的。
在μC/OS-II中，操作系统把连续的大块内存按分区来管理。每个分区中包含有整数个大小相同的内存块。利用这种机制，μC/OS-II 对malloc()和free()函数进行了改进，使得它们可以分配和释放固定大小的内存块。这样一来，malloc()和free()函数的执行时间也是固定的了。
在一个系统中可以有多个内存分区。这样，用户的应用程序就可以从不同的内存分区中得到不同大小的内存块。但是，特定的内存块在释放时必须重新放回它以前所属于的内存分区。显然，采用这样的内存管理算法，上面的内存碎片问题就得到了解决。
为了便于内存的管理，在μC/OS-II中使用内存控制块（memory control blocks）的数据结构来跟踪每一个内存分区，系统中的每个内存分区都有它自己的内存控制块。
内存控制块的定义如下：
~~~
typedef struct {
void *OSMemAddr; //指向内存分区起始地址的指针
void *OSMemFreeList; //是指向下一个空闲内存控制块或者下一个空闲的内存块的指针
INT32U OSMemBlkSize; //是内存分区中内存块的大小
INT32U OSMemNBlks; //内存分区中总的内存块数量
INT32U OSMemNFree; //内存分区中当前可以得空闲内存块数量
} OS_MEM;
~~~
如果要在μC/OS-II中使用内存管理，需要在OS_CFG.H文件中将开关量OS_MEM_EN设置为1。这样μC/OS-II 在启动时就会对内存管理器进行初始化[由OSInit()调用OSMemInit()实现]。常数OS_MAX_MEM_PART（见文件OS_CFG.H）定义了最大的内存分区数，该常数值最小应为2。
## 注意的事项
使用内存管理模块需要做的工作还有：
1．打开配置文件OS_CFG.H，将开关量OS_MEM_EN设置为1：
#define OS_MEM_EN 0
2．打开配置文件OS_CFG.H，设置系统要建立的任务分区的数量：
#define OS_MAX_MEM_PART 2
## OSMemCreate()内存块创建函数
1 主要作用： 该函数建立并初始化一个用于动态内存分配的区域，该内存区域包含指定数目的、大小确定的内存块。应用可以动态申请这些内存块并在用完后将其释放回这个内存区域。该函数的返回值就是指向这个内存区域控制块的指针，并作为OSMemGet()，OSMemPut()，OSMemQuery() 等相关调用的参数。
2函数原型：OS_MEM *OSMemCreate( void *addr, INT32U nblks, INT32U blksize, INT8U *err );
3参数说明：addr 建立的内存区域的起始地址。可以使用静态数组或在系统初始化时使用 malloc() 函数来分配这个区域的空间。
nblks 内存块的数目。每一个内存区域最少需要定义两个内存块。
blksize 每个内存块的大小，最小应该能够容纳一个指针变量。
err 是指向包含错误码的变量的指针。Err可能是如下几种情况：
OS_NO_ERR ：成功建立内存区域。
OS_MEM_INVALID_ADDR ：非法地址，即地址为空指针。
OS_MEM_INVALID_PART ：没有空闲的内存区域。
OS_MEM_INVALID_BLKS ：没有为内存区域建立至少两个内存块。
OS_MEM_INVALID_SIZE ：内存块大小不足以容纳一个指针变量。
5、函数主体在os_men.c中
4返回值说明：
OSMemCreate() 函数返回指向所创建的内存区域控制块的指针。如果创建失败，函数返回空指针。
## OSMemGet()函数
1 主要作用： 该函数用于从内存区域分配一个内存块。用户程序必须知道所建立的内存块的大小，并必须在使用完内存块后释放它。可以多次调用 OSMemGet() 函数。它的返回值就是指向所分配内存块的指针，并作为 OSMemPut() 函数的参数。
2函数原型：void *OSMemGet(OS_MEM *pmem, INT8U *err);
3参数说明：pmem 是指向内存区域控制块的指针，可以从 OSMemCreate() 函数的返回值中得到。
err 是指向包含错误码的变量的指针。Err可能是如下情况：
OS_NO_ERR ：成功得到一个内存块。
OS_MEM_NO_FREE_BLKS ：内存区域中已经没有足够的内存块。
4返回值说明：
OSMemGet() 函数返回指向所分配内存块的指针。如果没有可分配的内存块，OSMemGet() 函数返回空指针。
5、函数主体在os_men.c中
## OSMemPut()
1 主要作用：该函数用于释放一个内存块，内存块必须释放回它原先所在的内存区域，否则会造成系统错误。
2函数原型：INT8U OSMemPut (OS_MEM *pmem, void *pblk);
3参数说明：pmem 是指向内存区域控制块的指针，可以从 OSMemCreate() 函数的返回值中得到。
pblk 是指向将被释放的内存块的指针。
4返回值说明：
OSMemPut() 函数的返回值为下述之一：
OS_NO_ERR ：成功释放内存块
OS_MEM_FULL ：内存区域已满，不能再接受更多释放的内存块。这种情况说明用户程序出现了错误，释放了多于用 OSMemGet() 函数得到的内存块。
5、函数主体在os_men.c中
## OSMemQuery()
1 主要作用：该函数用于得到内存区域的信息。
2函数原型：INT8U OSMemQuery(OS_MEM *pmem, OS_MEM_DATA *pdata);
3参数说明：pmem 是指向内存区域控制块的指针，可以从 OSMemCreate() 函数的返回值中得到。
pdata 是一个指向 OS_MEM_DATA 数据结构的指针，该数据结构包含了以下的域：
~~~
void OSAddr; /* 指向内存区域起始地址的指针 */
void OSFreeList; /* 指向空闲内存块列表起始地址的指针 */
INT32U OSBlkSize; /* 每个内存块的大小 */
INT32U OSNBlks; /* 该内存区域中的内存块总数 */
INT32U OSNFree; /* 空闲的内存块数目 */
INT32U OSNUsed; /* 已使用的内存块数目 */
~~~
4返回值说明：函数返回值总是OS_NO_ERR。
5、函数主体在os_men.c中
## 附os_men.c代码
~~~
/*
*********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* MEMORY MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_MEM.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
#if (OS_MEM_EN > 0u) && (OS_MAX_MEM_PART > 0u)
/*
*********************************************************************************************************
* CREATE A MEMORY PARTITION
*
* Description : Create a fixed-sized memory partition that will be managed by uC/OS-II.
*
* Arguments : addr is the starting address of the memory partition
*
* nblks is the number of memory blocks to create from the partition.
*
* blksize is the size (in bytes) of each block in the memory partition.
*
* perr is a pointer to a variable containing an error message which will be set by
* this function to either:
*
* OS_ERR_NONE if the memory partition has been created correctly.
* OS_ERR_MEM_INVALID_ADDR if you are specifying an invalid address for the memory
* storage of the partition or, the block does not align
* on a pointer boundary
* OS_ERR_MEM_INVALID_PART no free partitions available
* OS_ERR_MEM_INVALID_BLKS user specified an invalid number of blocks (must be >= 2)
* OS_ERR_MEM_INVALID_SIZE user specified an invalid block size
* - must be greater than the size of a pointer
* - must be able to hold an integral number of pointers
* Returns : != (OS_MEM *)0 is the partition was created
* == (OS_MEM *)0 if the partition was not created because of invalid arguments or, no
* free partition is available.
*********************************************************************************************************
*/
OS_MEM *OSMemCreate (void *addr,
INT32U nblks,
INT32U blksize,
INT8U *perr)
{
OS_MEM *pmem;
INT8U *pblk;
void **plink;
INT32U loops;
INT32U i;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_MEM *)0);
}
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_MEM *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (addr == (void *)0) { /* Must pass a valid address for the memory part.*/
*perr = OS_ERR_MEM_INVALID_ADDR;
return ((OS_MEM *)0);
}
if (((INT32U)addr & (sizeof(void *) - 1u)) != 0u){ /* Must be pointer size aligned */
*perr = OS_ERR_MEM_INVALID_ADDR;
return ((OS_MEM *)0);
}
if (nblks < 2u) { /* Must have at least 2 blocks per partition */
*perr = OS_ERR_MEM_INVALID_BLKS;
return ((OS_MEM *)0);
}
if (blksize < sizeof(void *)) { /* Must contain space for at least a pointer */
*perr = OS_ERR_MEM_INVALID_SIZE;
return ((OS_MEM *)0);
}
#endif
OS_ENTER_CRITICAL();
pmem = OSMemFreeList; /* Get next free memory partition */
if (OSMemFreeList != (OS_MEM *)0) { /* See if pool of free partitions was empty */
OSMemFreeList = (OS_MEM *)OSMemFreeList->OSMemFreeList;
}
OS_EXIT_CRITICAL();
if (pmem == (OS_MEM *)0) { /* See if we have a memory partition */
*perr = OS_ERR_MEM_INVALID_PART;
return ((OS_MEM *)0);
}
plink = (void **)addr; /* Create linked list of free memory blocks */
pblk = (INT8U *)addr;
loops = nblks - 1u;
for (i = 0u; i < loops; i++) {
pblk += blksize; /* Point to the FOLLOWING block */
*plink = (void *)pblk; /* Save pointer to NEXT block in CURRENT block */
plink = (void **)pblk; /* Position to NEXT block */
}
*plink = (void *)0; /* Last memory block points to NULL */
pmem->OSMemAddr = addr; /* Store start address of memory partition */
pmem->OSMemFreeList = addr; /* Initialize pointer to pool of free blocks */
pmem->OSMemNFree = nblks; /* Store number of free blocks in MCB */
pmem->OSMemNBlks = nblks;
pmem->OSMemBlkSize = blksize; /* Store block size of each memory blocks */
*perr = OS_ERR_NONE;
return (pmem);
}
/*$PAGE*/
/*
*********************************************************************************************************
* GET A MEMORY BLOCK
*
* Description : Get a memory block from a partition
*
* Arguments : pmem is a pointer to the memory partition control block
*
* perr is a pointer to a variable containing an error message which will be set by this
* function to either:
*
* OS_ERR_NONE if the memory partition has been created correctly.
* OS_ERR_MEM_NO_FREE_BLKS if there are no more free memory blocks to allocate to caller
* OS_ERR_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
*
* Returns : A pointer to a memory block if no error is detected
* A pointer to NULL if an error is detected
*********************************************************************************************************
*/
void *OSMemGet (OS_MEM *pmem,
INT8U *perr)
{
void *pblk;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((void *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pmem == (OS_MEM *)0) { /* Must point to a valid memory partition */
*perr = OS_ERR_MEM_INVALID_PMEM;
return ((void *)0);
}
#endif
OS_ENTER_CRITICAL();
if (pmem->OSMemNFree > 0u) { /* See if there are any free memory blocks */
pblk = pmem->OSMemFreeList; /* Yes, point to next free memory block */
pmem->OSMemFreeList = *(void **)pblk; /* Adjust pointer to new free list */
pmem->OSMemNFree--; /* One less memory block in this partition */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE; /* No error */
return (pblk); /* Return memory block to caller */
}
OS_EXIT_CRITICAL();
*perr = OS_ERR_MEM_NO_FREE_BLKS; /* No, Notify caller of empty memory partition */
return ((void *)0); /* Return NULL pointer to caller */
}
/*$PAGE*/
/*
*********************************************************************************************************
* GET THE NAME OF A MEMORY PARTITION
*
* Description: This function is used to obtain the name assigned to a memory partition.
*
* Arguments : pmem is a pointer to the memory partition
*
* pname is a pointer to a pointer to an ASCII string that will receive the name of the memory partition.
*
* perr is a pointer to an error code that can contain one of the following values:
*
* OS_ERR_NONE if the name was copied to 'pname'
* OS_ERR_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
* OS_ERR_PNAME_NULL You passed a NULL pointer for 'pname'
* OS_ERR_NAME_GET_ISR You called this function from an ISR
*
* Returns : The length of the string or 0 if 'pmem' is a NULL pointer.
*********************************************************************************************************
*/
#if OS_MEM_NAME_EN > 0u
INT8U OSMemNameGet (OS_MEM *pmem,
INT8U **pname,
INT8U *perr)
{
INT8U len;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pmem == (OS_MEM *)0) { /* Is 'pmem' a NULL pointer? */
*perr = OS_ERR_MEM_INVALID_PMEM;
return (0u);
}
if (pname == (INT8U **)0) { /* Is 'pname' a NULL pointer? */
*perr = OS_ERR_PNAME_NULL;
return (0u);
}
#endif
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
*perr = OS_ERR_NAME_GET_ISR;
return (0u);
}
OS_ENTER_CRITICAL();
*pname = pmem->OSMemName;
len = OS_StrLen(*pname);
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (len);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* ASSIGN A NAME TO A MEMORY PARTITION
*
* Description: This function assigns a name to a memory partition.
*
* Arguments : pmem is a pointer to the memory partition
*
* pname is a pointer to an ASCII string that contains the name of the memory partition.
*
* perr is a pointer to an error code that can contain one of the following values:
*
* OS_ERR_NONE if the name was copied to 'pname'
* OS_ERR_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
* OS_ERR_PNAME_NULL You passed a NULL pointer for 'pname'
* OS_ERR_MEM_NAME_TOO_LONG if the name doesn't fit in the storage area
* OS_ERR_NAME_SET_ISR if you called this function from an ISR
*
* Returns : None
*********************************************************************************************************
*/
#if OS_MEM_NAME_EN > 0u
void OSMemNameSet (OS_MEM *pmem,
INT8U *pname,
INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pmem == (OS_MEM *)0) { /* Is 'pmem' a NULL pointer? */
*perr = OS_ERR_MEM_INVALID_PMEM;
return;
}
if (pname == (INT8U *)0) { /* Is 'pname' a NULL pointer? */
*perr = OS_ERR_PNAME_NULL;
return;
}
#endif
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
*perr = OS_ERR_NAME_SET_ISR;
return;
}
OS_ENTER_CRITICAL();
pmem->OSMemName = pname;
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* RELEASE A MEMORY BLOCK
*
* Description : Returns a memory block to a partition
*
* Arguments : pmem is a pointer to the memory partition control block
*
* pblk is a pointer to the memory block being released.
*
* Returns : OS_ERR_NONE if the memory block was inserted into the partition
* OS_ERR_MEM_FULL if you are returning a memory block to an already FULL memory
* partition (You freed more blocks than you allocated!)
* OS_ERR_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
* OS_ERR_MEM_INVALID_PBLK if you passed a NULL pointer for the block to release.
*********************************************************************************************************
*/
INT8U OSMemPut (OS_MEM *pmem,
void *pblk)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pmem == (OS_MEM *)0) { /* Must point to a valid memory partition */
return (OS_ERR_MEM_INVALID_PMEM);
}
if (pblk == (void *)0) { /* Must release a valid block */
return (OS_ERR_MEM_INVALID_PBLK);
}
#endif
OS_ENTER_CRITICAL();
if (pmem->OSMemNFree >= pmem->OSMemNBlks) { /* Make sure all blocks not already returned */
OS_EXIT_CRITICAL();
return (OS_ERR_MEM_FULL);
}
*(void **)pblk = pmem->OSMemFreeList; /* Insert released block into free block list */
pmem->OSMemFreeList = pblk;
pmem->OSMemNFree++; /* One more memory block in this partition */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE); /* Notify caller that memory block was released */
}
/*$PAGE*/
/*
*********************************************************************************************************
* QUERY MEMORY PARTITION
*
* Description : This function is used to determine the number of free memory blocks and the number of
* used memory blocks from a memory partition.
*
* Arguments : pmem is a pointer to the memory partition control block
*
* p_mem_data is a pointer to a structure that will contain information about the memory
* partition.
*
* Returns : OS_ERR_NONE if no errors were found.
* OS_ERR_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
* OS_ERR_MEM_INVALID_PDATA if you passed a NULL pointer to the data recipient.
*********************************************************************************************************
*/
#if OS_MEM_QUERY_EN > 0u
INT8U OSMemQuery (OS_MEM *pmem,
OS_MEM_DATA *p_mem_data)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pmem == (OS_MEM *)0) { /* Must point to a valid memory partition */
return (OS_ERR_MEM_INVALID_PMEM);
}
if (p_mem_data == (OS_MEM_DATA *)0) { /* Must release a valid storage area for the data */
return (OS_ERR_MEM_INVALID_PDATA);
}
#endif
OS_ENTER_CRITICAL();
p_mem_data->OSAddr = pmem->OSMemAddr;
p_mem_data->OSFreeList = pmem->OSMemFreeList;
p_mem_data->OSBlkSize = pmem->OSMemBlkSize;
p_mem_data->OSNBlks = pmem->OSMemNBlks;
p_mem_data->OSNFree = pmem->OSMemNFree;
OS_EXIT_CRITICAL();
p_mem_data->OSNUsed = p_mem_data->OSNBlks - p_mem_data->OSNFree;
return (OS_ERR_NONE);
}
#endif /* OS_MEM_QUERY_EN */
/*$PAGE*/
/*
*********************************************************************************************************
* INITIALIZE MEMORY PARTITION MANAGER
*
* Description : This function is called by uC/OS-II to initialize the memory partition manager. Your
* application MUST NOT call this function.
*
* Arguments : none
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-II and your application should not call it.
*********************************************************************************************************
*/
void OS_MemInit (void)
{
#if OS_MAX_MEM_PART == 1u
OS_MemClr((INT8U *)&OSMemTbl[0], sizeof(OSMemTbl)); /* Clear the memory partition table */
OSMemFreeList = (OS_MEM *)&OSMemTbl[0]; /* Point to beginning of free list */
#if OS_MEM_NAME_EN > 0u
OSMemFreeList->OSMemName = (INT8U *)"?"; /* Unknown name */
#endif
#endif
#if OS_MAX_MEM_PART >= 2u
OS_MEM *pmem;
INT16U i;
OS_MemClr((INT8U *)&OSMemTbl[0], sizeof(OSMemTbl)); /* Clear the memory partition table */
for (i = 0u; i < (OS_MAX_MEM_PART - 1u); i++) { /* Init. list of free memory partitions */
pmem = &OSMemTbl[i]; /* Point to memory control block (MCB) */
pmem->OSMemFreeList = (void *)&OSMemTbl[i + 1u]; /* Chain list of free partitions */
#if OS_MEM_NAME_EN > 0u
pmem->OSMemName = (INT8U *)(void *)"?";
#endif
}
pmem = &OSMemTbl[i];
pmem->OSMemFreeList = (void *)0; /* Initialize last node */
#if OS_MEM_NAME_EN > 0u
pmem->OSMemName = (INT8U *)(void *)"?";
#endif
OSMemFreeList = &OSMemTbl[0]; /* Point to beginning of free list */
#endif
}
#endif /* OS_MEM_EN */
~~~
uC/OS-II 函数之邮箱管理相关函数
最后更新于：2022-04-01 11:42:42
获得更多资料欢迎进入[我的网站](http://rlovep.com/)或者 [csdn](http://blog.csdn.net/peace1213)或者[博客园](http://www.cnblogs.com/onepeace/)
上文主要介绍了消息队列相关的函数，本文介绍邮箱管理相关的函数：OSMboxCreate()建立一个邮箱,OSMboxDel()删除一个邮箱,OSMboxPend()等待邮箱中的消息,OSMboxPost()向邮箱发送一则消息，OSMboxQuery()查询一个邮箱的状态
## 邮箱管里介绍
邮箱是µC/OS-II中另一种通讯机制，它可以使一个任务或者中断服务子程序向另一个任务发送一个指针型的变量。该指针指向一个包含了特定“消息”的数据结构。为了在µC/OS-II中使用邮箱，必须将OS_CFG.H中的OS_MBOX_EN常数置为1。
使用邮箱之前，必须先建立该邮箱。该操作可以通过调用OSMboxCreate()函数来完成（见下节），并且要指定指针的初始值。一般情况下，这个初始值是NULL，但也可以初始化一个邮箱，使其在最开始就包含一条消息。如果使用邮箱的目的是用来通知一个事件的发生（发送一条消息），那么就要初始化该邮箱为NULL，因为在开始时，事件还没有发生。如果用户用邮箱来共享某些资源，那么就要初始化该邮箱为一个非NULL的指针。在这种情况下，邮箱被当成一个二值信号量使用。
µC/OS-II提供了6种对邮箱的操作：OSMboxCreate()，OSMboxDel()，OSMboxPend()，OSMboxPost()，OSMboxAccept()和OSMboxQuery()函数。图 F10.6描述了任务、中断服务子程序和邮箱之间的关系，这里用符号“I”表示邮箱。邮箱包含的内容是一个指向一条消息的指针。一个邮箱只能包含一个这样的指针（邮箱为满时），或者一个指向NULL的指针（邮箱为空时）。从图 F10.6可以看出，任务或者中断服务子程序可以调用函数OSMboxPost()，但是只有任务可以调用函数OSMboxPend()和OSMboxQuery()。
## OSMboxCreate()建立一个邮箱
1主要作用：基本上和函数OSSemCreate()相似。建立一个邮箱变量；
2函数原型：OS_EVENT *OSMboxCreate (void *msg)
3参数说明：msg 是一个要在任务间传递的变量指针
4返回值说明：OSMboxCreate()函数的返回值是一个指向事件控制块的指针[L10.14(3)]。这个指针在调用函数OSMboxPend()，OSMboxPost()，OSMboxAccept()和OSMboxQuery()时使用。因此，该指针可以看作是对应邮箱的句柄。值得注意的是，如果系统中已经没有事件控制块可用，函数OSMboxCreate()将返回一个NULL指针。
5函数主体在os_mbox.c中
## OSMboxDel()删除一个邮箱
1、主要作用：对一个不再使用的消息邮箱要及时删除以释放资源。
2、函数原型：OS_EVENT *OSMboxDel (OS_EVENT *pevent, INT8U opt, INT8U *err)
3、参数说明：*pevent邮箱句柄
opt == OS_DEL_NO_PEND 如果没有等待任务时删除邮箱；
opt == OS_DEL_ALWAYS 无条件删除又向，所有等待该事件的任务急转到就绪状态；
err 是本函数执行状态的返回值，*err 的值含义：
ØOS_NO_ERR —- 函数成功，指定的邮箱被删除；
ØOS_INVALID_OPT —- 删除方式数据错；
ØOS_ERR_EVENT_TYPE —- 欲删除的事件类型不是邮箱；
ØOS_ERR_DEL_ISR —- 不支持ISR中的消息邮箱删除操作；
ØOS_ERR_PEVENT_NULL —- 指定的事件为空（不存在）；
ØOS_ERR_TASK_WAITING —- 邮箱中还有等待任务；
4、返回值说明：删除的句柄
5函数主体在os_mbox.c中
## OSMboxPend()等待邮箱中的消息
1、主要作用 ：所谓的 “请求消息邮箱” 就是等待一个消息传送到消息邮箱，或取得一个消息数据。
2、函数原型：void *OSMboxPend (OS_EVENT *pevent, INT16U timeout, INT8U *err)
3、参数说明：*pevent消息邮箱指针；timeout等待时限；err函数执行信息；
4、返回值说明：返回值为空时意味着未得到消息，此时uC/OS-II执行OS_Sched()；可能消息未准备好，或指示的事件出错、超时等，此时函数直接返回，用户应查阅 *err的状态。
当返回值 != Null 时，返回值就是一个预期消息的指针；
5函数主体在os_mbox.c中
## OSMboxPost()向邮箱发送一则消息，
1、主要作用：可以调用系统函数OSMboxPost( )函数向消息邮箱发送消息；
2、函数原型：INT8U OSMboxPost (OS_EVENT *pevent, void *msg)
3、参数说明：形参 msg 是一个要在任务间传递的变量指针；形参 pevent 是消息邮箱指针；
4、返回值说明：
1、OS_NO_ERR —- 消息发送成功；
2、 OS_MBOX_FULL —- 不能向满邮箱再发送消息；
3、OS_ERR_EVENT_TYPE —- 指定的事件不是消息邮箱类型；
4、OS_ERR_PEVENT_NULL —- 不能向不存在的消息邮箱发送消息；
5、OS_ERR_POST_NULL_PTR —- 消息缓冲区不能为空；
5函数主体在os_mbox.c中
向邮箱发送一则消息可以用下面函数，功能更强大，可发送广播消息
INT8U OSMboxPostOpt (OS_EVENT *pevent, void *msg, INT8U opt)
## OSMboxQuery()查询一个邮箱的状态
1、主要作用：函数使应用程序可以随时查询一个邮箱的当前状态
2、函数原型：INT8U OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *pdata)
3、参数说明：一个是指向邮箱的指针pevent。该指针是在建立该邮箱时，由OSMboxCreate()函数返回的；另一个是指向用来保存有关邮箱的信息的OS_MBOX_DATA（见uCOS_II.H）数据结构的指针pdata。
４、返回值说明：OS_NO_ERR ：调用成功
OS_ERR_EVENT_TYPE ：pevent 不是指向消息邮箱的指针。
注意/警告:必须先建立消息邮箱，然后使用。
5函数主体在os_mbox.c中
## 附os_mbox.c代码：
~~~
/*
*********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* MESSAGE MAILBOX MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_MBOX.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
#if OS_MBOX_EN > 0u
/*
*********************************************************************************************************
* ACCEPT MESSAGE FROM MAILBOX
*
* Description: This function checks the mailbox to see if a message is available. Unlike OSMboxPend(),
* OSMboxAccept() does not suspend the calling task if a message is not available.
*
* Arguments : pevent is a pointer to the event control block
*
* Returns : != (void *)0 is the message in the mailbox if one is available. The mailbox is cleared
* so the next time OSMboxAccept() is called, the mailbox will be empty.
* == (void *)0 if the mailbox is empty or,
* if 'pevent' is a NULL pointer or,
* if you didn't pass the proper event pointer.
*********************************************************************************************************
*/
#if OS_MBOX_ACCEPT_EN > 0u
void *OSMboxAccept (OS_EVENT *pevent)
{
void *pmsg;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return ((void *)0);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
return ((void *)0);
}
OS_ENTER_CRITICAL();
pmsg = pevent->OSEventPtr;
pevent->OSEventPtr = (void *)0; /* Clear the mailbox */
OS_EXIT_CRITICAL();
return (pmsg); /* Return the message received (or NULL) */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CREATE A MESSAGE MAILBOX
*
* Description: This function creates a message mailbox if free event control blocks are available.
*
* Arguments : pmsg is a pointer to a message that you wish to deposit in the mailbox. If
* you set this value to the NULL pointer (i.e. (void *)0) then the mailbox
* will be considered empty.
*
* Returns : != (OS_EVENT *)0 is a pointer to the event control clock (OS_EVENT) associated with the
* created mailbox
* == (OS_EVENT *)0 if no event control blocks were available
*********************************************************************************************************
*/
OS_EVENT *OSMboxCreate (void *pmsg)
{
OS_EVENT *pevent;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
if (OSIntNesting > 0u) { /* See if called from ISR ... */
return ((OS_EVENT *)0); /* ... can't CREATE from an ISR */
}
OS_ENTER_CRITICAL();
pevent = OSEventFreeList; /* Get next free event control block */
if (OSEventFreeList != (OS_EVENT *)0) { /* See if pool of free ECB pool was empty */
OSEventFreeList = (OS_EVENT *)OSEventFreeList->OSEventPtr;
}
OS_EXIT_CRITICAL();
if (pevent != (OS_EVENT *)0) {
pevent->OSEventType = OS_EVENT_TYPE_MBOX;
pevent->OSEventCnt = 0u;
pevent->OSEventPtr = pmsg; /* Deposit message in event control block */
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
OS_EventWaitListInit(pevent);
}
return (pevent); /* Return pointer to event control block */
}
/*$PAGE*/
/*
*********************************************************************************************************
* DELETE A MAIBOX
*
* Description: This function deletes a mailbox and readies all tasks pending on the mailbox.
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* mailbox.
*
* opt determines delete options as follows:
* opt == OS_DEL_NO_PEND Delete the mailbox ONLY if no task pending
* opt == OS_DEL_ALWAYS Deletes the mailbox even if tasks are waiting.
* In this case, all the tasks pending will be readied.
*
* perr is a pointer to an error code that can contain one of the following values:
* OS_ERR_NONE The call was successful and the mailbox was deleted
* OS_ERR_DEL_ISR If you attempted to delete the mailbox from an ISR
* OS_ERR_INVALID_OPT An invalid option was specified
* OS_ERR_TASK_WAITING One or more tasks were waiting on the mailbox
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a mailbox
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : pevent upon error
* (OS_EVENT *)0 if the mailbox was successfully deleted.
*
* Note(s) : 1) This function must be used with care. Tasks that would normally expect the presence of
* the mailbox MUST check the return code of OSMboxPend().
* 2) OSMboxAccept() callers will not know that the intended mailbox has been deleted!
* 3) This call can potentially disable interrupts for a long time. The interrupt disable
* time is directly proportional to the number of tasks waiting on the mailbox.
* 4) Because ALL tasks pending on the mailbox will be readied, you MUST be careful in
* applications where the mailbox is used for mutual exclusion because the resource(s)
* will no longer be guarded by the mailbox.
* 5) All tasks that were waiting for the mailbox will be readied and returned an
* OS_ERR_PEND_ABORT if OSMboxDel() was called with OS_DEL_ALWAYS
*********************************************************************************************************
*/
#if OS_MBOX_DEL_EN > 0u
OS_EVENT *OSMboxDel (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
BOOLEAN tasks_waiting;
OS_EVENT *pevent_return;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (pevent);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (pevent);
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_DEL_ISR; /* ... can't DELETE from an ISR */
return (pevent);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any tasks waiting on mailbox */
tasks_waiting = OS_TRUE; /* Yes */
} else {
tasks_waiting = OS_FALSE; /* No */
}
switch (opt) {
case OS_DEL_NO_PEND: /* Delete mailbox only if no task waiting */
if (tasks_waiting == OS_FALSE) {
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Mailbox has been deleted */
} else {
OS_EXIT_CRITICAL();
*perr = OS_ERR_TASK_WAITING;
pevent_return = pevent;
}
break;
case OS_DEL_ALWAYS: /* Always delete the mailbox */
while (pevent->OSEventGrp != 0u) { /* Ready ALL tasks waiting for mailbox */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_MBOX, OS_STAT_PEND_ABORT);
}
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
if (tasks_waiting == OS_TRUE) { /* Reschedule only if task(s) were waiting */
OS_Sched(); /* Find highest priority task ready to run */
}
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Mailbox has been deleted */
break;
default:
OS_EXIT_CRITICAL();
*perr = OS_ERR_INVALID_OPT;
pevent_return = pevent;
break;
}
return (pevent_return);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* PEND ON MAILBOX FOR A MESSAGE
*
* Description: This function waits for a message to be sent to a mailbox
*
* Arguments : pevent is a pointer to the event control block associated with the desired mailbox
*
* timeout is an optional timeout period (in clock ticks). If non-zero, your task will
* wait for a message to arrive at the mailbox up to the amount of time
* specified by this argument. If you specify 0, however, your task will wait
* forever at the specified mailbox or, until a message arrives.
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE The call was successful and your task received a
* message.
* OS_ERR_TIMEOUT A message was not received within the specified 'timeout'.
* OS_ERR_PEND_ABORT The wait on the mailbox was aborted.
* OS_ERR_EVENT_TYPE Invalid event type
* OS_ERR_PEND_ISR If you called this function from an ISR and the result
* would lead to a suspension.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_PEND_LOCKED If you called this function when the scheduler is locked
*
* Returns : != (void *)0 is a pointer to the message received
* == (void *)0 if no message was received or,
* if 'pevent' is a NULL pointer or,
* if you didn't pass the proper pointer to the event control block.
*********************************************************************************************************
*/
/*$PAGE*/
void *OSMboxPend (OS_EVENT *pevent,
INT32U timeout,
INT8U *perr)
{
void *pmsg;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((void *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return ((void *)0);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return ((void *)0);
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_PEND_ISR; /* ... can't PEND from an ISR */
return ((void *)0);
}
if (OSLockNesting > 0u) { /* See if called with scheduler locked ... */
*perr = OS_ERR_PEND_LOCKED; /* ... can't PEND when locked */
return ((void *)0);
}
OS_ENTER_CRITICAL();
pmsg = pevent->OSEventPtr;
if (pmsg != (void *)0) { /* See if there is already a message */
pevent->OSEventPtr = (void *)0; /* Clear the mailbox */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (pmsg); /* Return the message received (or NULL) */
}
OSTCBCur->OSTCBStat |= OS_STAT_MBOX; /* Message not available, task will pend */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK;
OSTCBCur->OSTCBDly = timeout; /* Load timeout in TCB */
OS_EventTaskWait(pevent); /* Suspend task until event or timeout occurs */
OS_EXIT_CRITICAL();
OS_Sched(); /* Find next highest priority task ready to run */
OS_ENTER_CRITICAL();
switch (OSTCBCur->OSTCBStatPend) { /* See if we timed-out or aborted */
case OS_STAT_PEND_OK:
pmsg = OSTCBCur->OSTCBMsg;
*perr = OS_ERR_NONE;
break;
case OS_STAT_PEND_ABORT:
pmsg = (void *)0;
*perr = OS_ERR_PEND_ABORT; /* Indicate that we aborted */
break;
case OS_STAT_PEND_TO:
default:
OS_EventTaskRemove(OSTCBCur, pevent);
pmsg = (void *)0;
*perr = OS_ERR_TIMEOUT; /* Indicate that we didn't get event within TO */
break;
}
OSTCBCur->OSTCBStat = OS_STAT_RDY; /* Set task status to ready */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK; /* Clear pend status */
OSTCBCur->OSTCBEventPtr = (OS_EVENT *)0; /* Clear event pointers */
#if (OS_EVENT_MULTI_EN > 0u)
OSTCBCur->OSTCBEventMultiPtr = (OS_EVENT **)0;
#endif
OSTCBCur->OSTCBMsg = (void *)0; /* Clear received message */
OS_EXIT_CRITICAL();
return (pmsg); /* Return received message */
}
/*$PAGE*/
/*
*********************************************************************************************************
* ABORT WAITING ON A MESSAGE MAILBOX
*
* Description: This function aborts & readies any tasks currently waiting on a mailbox. This function
* should be used to fault-abort the wait on the mailbox, rather than to normally signal
* the mailbox via OSMboxPost() or OSMboxPostOpt().
*
* Arguments : pevent is a pointer to the event control block associated with the desired mailbox.
*
* opt determines the type of ABORT performed:
* OS_PEND_OPT_NONE ABORT wait for a single task (HPT) waiting on the
* mailbox
* OS_PEND_OPT_BROADCAST ABORT wait for ALL tasks that are waiting on the
* mailbox
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE No tasks were waiting on the mailbox.
* OS_ERR_PEND_ABORT At least one task waiting on the mailbox was readied
* and informed of the aborted wait; check return value
* for the number of tasks whose wait on the mailbox
* was aborted.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a mailbox.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : == 0 if no tasks were waiting on the mailbox, or upon error.
* > 0 if one or more tasks waiting on the mailbox are now readied and informed.
*********************************************************************************************************
*/
#if OS_MBOX_PEND_ABORT_EN > 0u
INT8U OSMboxPendAbort (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
INT8U nbr_tasks;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (0u);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (0u);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task waiting on mailbox? */
nbr_tasks = 0u;
switch (opt) {
case OS_PEND_OPT_BROADCAST: /* Do we need to abort ALL waiting tasks? */
while (pevent->OSEventGrp != 0u) { /* Yes, ready ALL tasks waiting on mailbox */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_MBOX, OS_STAT_PEND_ABORT);
nbr_tasks++;
}
break;
case OS_PEND_OPT_NONE:
default: /* No, ready HPT waiting on mailbox */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_MBOX, OS_STAT_PEND_ABORT);
nbr_tasks++;
break;
}
OS_EXIT_CRITICAL();
OS_Sched(); /* Find HPT ready to run */
*perr = OS_ERR_PEND_ABORT;
return (nbr_tasks);
}
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (0u); /* No tasks waiting on mailbox */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST MESSAGE TO A MAILBOX
*
* Description: This function sends a message to a mailbox
*
* Arguments : pevent is a pointer to the event control block associated with the desired mailbox
*
* pmsg is a pointer to the message to send. You MUST NOT send a NULL pointer.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_MBOX_FULL If the mailbox already contains a message. You can can only send one
* message at a time and thus, the message MUST be consumed before you
* are allowed to send another one.
* OS_ERR_EVENT_TYPE If you are attempting to post to a non mailbox.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_POST_NULL_PTR If you are attempting to post a NULL pointer
*
* Note(s) : 1) HPT means Highest Priority Task
*********************************************************************************************************
*/
#if OS_MBOX_POST_EN > 0u
INT8U OSMboxPost (OS_EVENT *pevent,
void *pmsg)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (pmsg == (void *)0) { /* Make sure we are not posting a NULL pointer */
return (OS_ERR_POST_NULL_PTR);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task pending on mailbox */
/* Ready HPT waiting on event */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_MBOX, OS_STAT_PEND_OK);
OS_EXIT_CRITICAL();
OS_Sched(); /* Find highest priority task ready to run */
return (OS_ERR_NONE);
}
if (pevent->OSEventPtr != (void *)0) { /* Make sure mailbox doesn't already have a msg */
OS_EXIT_CRITICAL();
return (OS_ERR_MBOX_FULL);
}
pevent->OSEventPtr = pmsg; /* Place message in mailbox */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST MESSAGE TO A MAILBOX
*
* Description: This function sends a message to a mailbox
*
* Arguments : pevent is a pointer to the event control block associated with the desired mailbox
*
* pmsg is a pointer to the message to send. You MUST NOT send a NULL pointer.
*
* opt determines the type of POST performed:
* OS_POST_OPT_NONE POST to a single waiting task
* (Identical to OSMboxPost())
* OS_POST_OPT_BROADCAST POST to ALL tasks that are waiting on the mailbox
*
* OS_POST_OPT_NO_SCHED Indicates that the scheduler will NOT be invoked
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_MBOX_FULL If the mailbox already contains a message. You can can only send one
* message at a time and thus, the message MUST be consumed before you
* are allowed to send another one.
* OS_ERR_EVENT_TYPE If you are attempting to post to a non mailbox.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_POST_NULL_PTR If you are attempting to post a NULL pointer
*
* Note(s) : 1) HPT means Highest Priority Task
*
* Warning : Interrupts can be disabled for a long time if you do a 'broadcast'. In fact, the
* interrupt disable time is proportional to the number of tasks waiting on the mailbox.
*********************************************************************************************************
*/
#if OS_MBOX_POST_OPT_EN > 0u
INT8U OSMboxPostOpt (OS_EVENT *pevent,
void *pmsg,
INT8U opt)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (pmsg == (void *)0) { /* Make sure we are not posting a NULL pointer */
return (OS_ERR_POST_NULL_PTR);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task pending on mailbox */
if ((opt & OS_POST_OPT_BROADCAST) != 0x00u) { /* Do we need to post msg to ALL waiting tasks ? */
while (pevent->OSEventGrp != 0u) { /* Yes, Post to ALL tasks waiting on mailbox */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_MBOX, OS_STAT_PEND_OK);
}
} else { /* No, Post to HPT waiting on mbox */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_MBOX, OS_STAT_PEND_OK);
}
OS_EXIT_CRITICAL();
if ((opt & OS_POST_OPT_NO_SCHED) == 0u) { /* See if scheduler needs to be invoked */
OS_Sched(); /* Find HPT ready to run */
}
return (OS_ERR_NONE);
}
if (pevent->OSEventPtr != (void *)0) { /* Make sure mailbox doesn't already have a msg */
OS_EXIT_CRITICAL();
return (OS_ERR_MBOX_FULL);
}
pevent->OSEventPtr = pmsg; /* Place message in mailbox */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* QUERY A MESSAGE MAILBOX
*
* Description: This function obtains information about a message mailbox.
*
* Arguments : pevent is a pointer to the event control block associated with the desired mailbox
*
* p_mbox_data is a pointer to a structure that will contain information about the message
* mailbox.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_EVENT_TYPE If you are attempting to obtain data from a non mailbox.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_PDATA_NULL If 'p_mbox_data' is a NULL pointer
*********************************************************************************************************
*/
#if OS_MBOX_QUERY_EN > 0u
INT8U OSMboxQuery (OS_EVENT *pevent,
OS_MBOX_DATA *p_mbox_data)
{
INT8U i;
OS_PRIO *psrc;
OS_PRIO *pdest;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (p_mbox_data == (OS_MBOX_DATA *)0) { /* Validate 'p_mbox_data' */
return (OS_ERR_PDATA_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_MBOX) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
p_mbox_data->OSEventGrp = pevent->OSEventGrp; /* Copy message mailbox wait list */
psrc = &pevent->OSEventTbl[0];
pdest = &p_mbox_data->OSEventTbl[0];
for (i = 0u; i < OS_EVENT_TBL_SIZE; i++) {
*pdest++ = *psrc++;
}
p_mbox_data->OSMsg = pevent->OSEventPtr; /* Get message from mailbox */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif /* OS_MBOX_QUERY_EN */
#endif /* OS_MBOX_EN */
~~~
uC/OS-II 函数之消息队列相关函数
最后更新于：2022-04-01 11:42:40
> 上文主要介绍了信号量相关的函数，本文介绍消息队列相关的函数：OSQCreate()建立消息队列函数,OSQPend()任务等待消息函数,其他的消息函数.
## 消息队列介绍
消息队列是µC/OS-II中另一种通讯机制，它可以使一个任务或者中断服务子程序向另一个任务发送以指针方式定义的变量。因具体的应用有所不同，每个指针指向的数据结构变量也有所不同。为了使用µC/OS-II的消息队列功能，需要在OS_CFG.H 文件中，将OS_Q_EN常数设置为1，并且通过常数OS_MAX_QS来决定µC/OS-II支持的最多消息队列数。
## OSQCreate()建立消息队列函数
1、主要作用：该函数用于建立一个消息队列。任务或中断可以通过消息队列向一个或多个任务发送消息。消息的含义是和具体的应用密切相关的。
2、函数原型：OS_EVENT *OSQCreate (void **start, INT8U size);
3、参数说明：start 是消息内存区的首地址，消息内存区是一个指针数组
size 是消息内存区的大小。
4、返回值说明：OSQCreate() 函数返回一个指向消息队列控制块的指针。如果没有空闲的控制块，OSQCreate() 函数返回空指针
5、函数主体在os_q.c中
## OSQPend()任务等待消息函数
1、主要作用： 该函数用于任务等待消息。消息通过中断或任务发送给需要的任务。消息是一个指针变量，在不同的应用中消息的具体含义不同。如果调用 OSQPend() 函数时队列中已经存在消息，那么该消息被返回给 OSQPend() 函数的调用者，该消息同时从队列中清除。如果调用 OSQPend() 函数时队列中没有消息，OSQPend() 函数挂起调用任务直到得到消息或超出定义的超时时间。如果同时有多个任务等待同一个消息，μC/OS-Ⅱ默认最高优先级的任务取得消息。一个由 OSTaskSuspend() 函数挂起的任务也可以接受消息，但这个任务将一直保持挂起状态直到通过调用 OSTaskResume() 函数恢复任务的运行。
2、函数原型：void *OSQPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);
3、参数说明：pevent 是指向消息队列的指针，该指针的值在建立该队列时可以得到。（参考 OSQCreate() 函数）。 timeout 允许一个任务以指定数目的时钟节拍等待消息。超时后如果还没有得到消息则恢复成就绪状态。如果该值设置成零则表示任务将持续地等待消息，最大的等待时间为65535个时钟节拍。这个时间长度并不是非常严格的，可能存在一个时钟节拍的误差。
err 是指向包含错误码的变量的指针。OSQPend() 函数返回的错误码可能为下述几种：
* OS_NO_ERR ：消息被正确地接受。
* OS_TIMEOUT ：消息没有在指定的时钟周期数内接收到消息。
* OS_ERR_PEND_ISR ：从中断调用该函数。虽然规定了不允许从中断中调用该函数，但μC/OS-Ⅱ仍然包含了检测这种情况的功能。
* OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列的指针。
4、返回值说明：OSQPend() 函数返回取得的消息并将 *err 置为 OS_NO_ERR。如果没有在指定数目的时钟节拍内接受到消息，OSQPend() 函数返回空指针并将 *err 设置为 OS_TIMEOUT。
5、函数主体在os_q.c中
## 其他的消息函数
INT8U OSQPost (OS_EVENT *pevent, void *msg)
发送一个消息到消息队列 FIFO模式
INT8U OSQPostFront (OS_EVENT *pevent, void *msg)
发送一个消息到消息队列 FIFO模式
void *OSQAccept (OS_EVENT *pevent)
无等待地从消息队列中得到一个消息
INT8U OSQFlush (OS_EVENT *pevent)
清空一个消息队列
INT8U OSQQuery (OS_EVENT *pevent, OS_Q_DATA *pdata)
查询一个消息队列的当前状态
使用消息队列的通常步骤为：
1）定义指针： OS_EVENT *proSQ
定义指针数组： void *start[4]
2) 在主程序中建立信号列队：*proSQ = OSQCreate(start,4);
3）在任务中等待消息列队中得到消息或者给消息列队发送消息
## 附os_q.c代码
~~~
/**********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* MESSAGE QUEUE MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_Q.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
#if (OS_Q_EN > 0u) && (OS_MAX_QS > 0u)
/*
*********************************************************************************************************
* ACCEPT MESSAGE FROM QUEUE
*
* Description: This function checks the queue to see if a message is available. Unlike OSQPend(),
* OSQAccept() does not suspend the calling task if a message is not available.
*
* Arguments : pevent is a pointer to the event control block
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE The call was successful and your task received a
* message.
* OS_ERR_EVENT_TYPE You didn't pass a pointer to a queue
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_Q_EMPTY The queue did not contain any messages
*
* Returns : != (void *)0 is the message in the queue if one is available. The message is removed
* from the so the next time OSQAccept() is called, the queue will contain
* one less entry.
* == (void *)0 if you received a NULL pointer message
* if the queue is empty or,
* if 'pevent' is a NULL pointer or,
* if you passed an invalid event type
*
* Note(s) : As of V2.60, you can now pass NULL pointers through queues. Because of this, the argument
* 'perr' has been added to the API to tell you about the outcome of the call.
*********************************************************************************************************
*/
#if OS_Q_ACCEPT_EN > 0u
void *OSQAccept (OS_EVENT *pevent,
INT8U *perr)
{
void *pmsg;
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((void *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return ((void *)0);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) {/* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return ((void *)0);
}
OS_ENTER_CRITICAL();
pq = (OS_Q *)pevent->OSEventPtr; /* Point at queue control block */
if (pq->OSQEntries > 0u) { /* See if any messages in the queue */
pmsg = *pq->OSQOut++; /* Yes, extract oldest message from the queue */
pq->OSQEntries--; /* Update the number of entries in the queue */
if (pq->OSQOut == pq->OSQEnd) { /* Wrap OUT pointer if we are at the end of the queue */
pq->OSQOut = pq->OSQStart;
}
*perr = OS_ERR_NONE;
} else {
*perr = OS_ERR_Q_EMPTY;
pmsg = (void *)0; /* Queue is empty */
}
OS_EXIT_CRITICAL();
return (pmsg); /* Return message received (or NULL) */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CREATE A MESSAGE QUEUE
*
* Description: This function creates a message queue if free event control blocks are available.
*
* Arguments : start is a pointer to the base address of the message queue storage area. The
* storage area MUST be declared as an array of pointers to 'void' as follows
*
* void *MessageStorage[size]
*
* size is the number of elements in the storage area
*
* Returns : != (OS_EVENT *)0 is a pointer to the event control clock (OS_EVENT) associated with the
* created queue
* == (OS_EVENT *)0 if no event control blocks were available or an error was detected
*********************************************************************************************************
*/
OS_EVENT *OSQCreate (void **start,
INT16U size)
{
OS_EVENT *pevent;
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
if (OSIntNesting > 0u) { /* See if called from ISR ... */
return ((OS_EVENT *)0); /* ... can't CREATE from an ISR */
}
OS_ENTER_CRITICAL();
pevent = OSEventFreeList; /* Get next free event control block */
if (OSEventFreeList != (OS_EVENT *)0) { /* See if pool of free ECB pool was empty */
OSEventFreeList = (OS_EVENT *)OSEventFreeList->OSEventPtr;
}
OS_EXIT_CRITICAL();
if (pevent != (OS_EVENT *)0) { /* See if we have an event control block */
OS_ENTER_CRITICAL();
pq = OSQFreeList; /* Get a free queue control block */
if (pq != (OS_Q *)0) { /* Were we able to get a queue control block ? */
OSQFreeList = OSQFreeList->OSQPtr; /* Yes, Adjust free list pointer to next free*/
OS_EXIT_CRITICAL();
pq->OSQStart = start; /* Initialize the queue */
pq->OSQEnd = &start[size];
pq->OSQIn = start;
pq->OSQOut = start;
pq->OSQSize = size;
pq->OSQEntries = 0u;
pevent->OSEventType = OS_EVENT_TYPE_Q;
pevent->OSEventCnt = 0u;
pevent->OSEventPtr = pq;
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
OS_EventWaitListInit(pevent); /* Initialize the wait list */
} else {
pevent->OSEventPtr = (void *)OSEventFreeList; /* No, Return event control block on error */
OSEventFreeList = pevent;
OS_EXIT_CRITICAL();
pevent = (OS_EVENT *)0;
}
}
return (pevent);
}
/*$PAGE*/
/*
*********************************************************************************************************
* DELETE A MESSAGE QUEUE
*
* Description: This function deletes a message queue and readies all tasks pending on the queue.
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* queue.
*
* opt determines delete options as follows:
* opt == OS_DEL_NO_PEND Delete the queue ONLY if no task pending
* opt == OS_DEL_ALWAYS Deletes the queue even if tasks are waiting.
* In this case, all the tasks pending will be readied.
*
* perr is a pointer to an error code that can contain one of the following values:
* OS_ERR_NONE The call was successful and the queue was deleted
* OS_ERR_DEL_ISR If you tried to delete the queue from an ISR
* OS_ERR_INVALID_OPT An invalid option was specified
* OS_ERR_TASK_WAITING One or more tasks were waiting on the queue
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : pevent upon error
* (OS_EVENT *)0 if the queue was successfully deleted.
*
* Note(s) : 1) This function must be used with care. Tasks that would normally expect the presence of
* the queue MUST check the return code of OSQPend().
* 2) OSQAccept() callers will not know that the intended queue has been deleted unless
* they check 'pevent' to see that it's a NULL pointer.
* 3) This call can potentially disable interrupts for a long time. The interrupt disable
* time is directly proportional to the number of tasks waiting on the queue.
* 4) Because ALL tasks pending on the queue will be readied, you MUST be careful in
* applications where the queue is used for mutual exclusion because the resource(s)
* will no longer be guarded by the queue.
* 5) If the storage for the message queue was allocated dynamically (i.e. using a malloc()
* type call) then your application MUST release the memory storage by call the counterpart
* call of the dynamic allocation scheme used. If the queue storage was created statically
* then, the storage can be reused.
* 6) All tasks that were waiting for the queue will be readied and returned an
* OS_ERR_PEND_ABORT if OSQDel() was called with OS_DEL_ALWAYS
*********************************************************************************************************
*/
#if OS_Q_DEL_EN > 0u
OS_EVENT *OSQDel (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
BOOLEAN tasks_waiting;
OS_EVENT *pevent_return;
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (pevent);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (pevent);
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_DEL_ISR; /* ... can't DELETE from an ISR */
return (pevent);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any tasks waiting on queue */
tasks_waiting = OS_TRUE; /* Yes */
} else {
tasks_waiting = OS_FALSE; /* No */
}
switch (opt) {
case OS_DEL_NO_PEND: /* Delete queue only if no task waiting */
if (tasks_waiting == OS_FALSE) {
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pq = (OS_Q *)pevent->OSEventPtr; /* Return OS_Q to free list */
pq->OSQPtr = OSQFreeList;
OSQFreeList = pq;
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Queue has been deleted */
} else {
OS_EXIT_CRITICAL();
*perr = OS_ERR_TASK_WAITING;
pevent_return = pevent;
}
break;
case OS_DEL_ALWAYS: /* Always delete the queue */
while (pevent->OSEventGrp != 0u) { /* Ready ALL tasks waiting for queue */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_Q, OS_STAT_PEND_ABORT);
}
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pq = (OS_Q *)pevent->OSEventPtr; /* Return OS_Q to free list */
pq->OSQPtr = OSQFreeList;
OSQFreeList = pq;
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
if (tasks_waiting == OS_TRUE) { /* Reschedule only if task(s) were waiting */
OS_Sched(); /* Find highest priority task ready to run */
}
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Queue has been deleted */
break;
default:
OS_EXIT_CRITICAL();
*perr = OS_ERR_INVALID_OPT;
pevent_return = pevent;
break;
}
return (pevent_return);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* FLUSH QUEUE
*
* Description : This function is used to flush the contents of the message queue.
*
* Arguments : none
*
* Returns : OS_ERR_NONE upon success
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
*
* WARNING : You should use this function with great care because, when to flush the queue, you LOOSE
* the references to what the queue entries are pointing to and thus, you could cause
* 'memory leaks'. In other words, the data you are pointing to that's being referenced
* by the queue entries should, most likely, need to be de-allocated (i.e. freed).
*********************************************************************************************************
*/
#if OS_Q_FLUSH_EN > 0u
INT8U OSQFlush (OS_EVENT *pevent)
{
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
#endif
OS_ENTER_CRITICAL();
pq = (OS_Q *)pevent->OSEventPtr; /* Point to queue storage structure */
pq->OSQIn = pq->OSQStart;
pq->OSQOut = pq->OSQStart;
pq->OSQEntries = 0u;
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* PEND ON A QUEUE FOR A MESSAGE
*
* Description: This function waits for a message to be sent to a queue
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue
*
* timeout is an optional timeout period (in clock ticks). If non-zero, your task will
* wait for a message to arrive at the queue up to the amount of time
* specified by this argument. If you specify 0, however, your task will wait
* forever at the specified queue or, until a message arrives.
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE The call was successful and your task received a
* message.
* OS_ERR_TIMEOUT A message was not received within the specified 'timeout'.
* OS_ERR_PEND_ABORT The wait on the queue was aborted.
* OS_ERR_EVENT_TYPE You didn't pass a pointer to a queue
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_PEND_ISR If you called this function from an ISR and the result
* would lead to a suspension.
* OS_ERR_PEND_LOCKED If you called this function with the scheduler is locked
*
* Returns : != (void *)0 is a pointer to the message received
* == (void *)0 if you received a NULL pointer message or,
* if no message was received or,
* if 'pevent' is a NULL pointer or,
* if you didn't pass a pointer to a queue.
*
* Note(s) : As of V2.60, this function allows you to receive NULL pointer messages.
*********************************************************************************************************
*/
void *OSQPend (OS_EVENT *pevent,
INT32U timeout,
INT8U *perr)
{
void *pmsg;
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((void *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return ((void *)0);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) {/* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return ((void *)0);
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_PEND_ISR; /* ... can't PEND from an ISR */
return ((void *)0);
}
if (OSLockNesting > 0u) { /* See if called with scheduler locked ... */
*perr = OS_ERR_PEND_LOCKED; /* ... can't PEND when locked */
return ((void *)0);
}
OS_ENTER_CRITICAL();
pq = (OS_Q *)pevent->OSEventPtr; /* Point at queue control block */
if (pq->OSQEntries > 0u) { /* See if any messages in the queue */
pmsg = *pq->OSQOut++; /* Yes, extract oldest message from the queue */
pq->OSQEntries--; /* Update the number of entries in the queue */
if (pq->OSQOut == pq->OSQEnd) { /* Wrap OUT pointer if we are at the end of the queue */
pq->OSQOut = pq->OSQStart;
}
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (pmsg); /* Return message received */
}
OSTCBCur->OSTCBStat |= OS_STAT_Q; /* Task will have to pend for a message to be posted */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK;
OSTCBCur->OSTCBDly = timeout; /* Load timeout into TCB */
OS_EventTaskWait(pevent); /* Suspend task until event or timeout occurs */
OS_EXIT_CRITICAL();
OS_Sched(); /* Find next highest priority task ready to run */
OS_ENTER_CRITICAL();
switch (OSTCBCur->OSTCBStatPend) { /* See if we timed-out or aborted */
case OS_STAT_PEND_OK: /* Extract message from TCB (Put there by QPost) */
pmsg = OSTCBCur->OSTCBMsg;
*perr = OS_ERR_NONE;
break;
case OS_STAT_PEND_ABORT:
pmsg = (void *)0;
*perr = OS_ERR_PEND_ABORT; /* Indicate that we aborted */
break;
case OS_STAT_PEND_TO:
default:
OS_EventTaskRemove(OSTCBCur, pevent);
pmsg = (void *)0;
*perr = OS_ERR_TIMEOUT; /* Indicate that we didn't get event within TO */
break;
}
OSTCBCur->OSTCBStat = OS_STAT_RDY; /* Set task status to ready */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK; /* Clear pend status */
OSTCBCur->OSTCBEventPtr = (OS_EVENT *)0; /* Clear event pointers */
#if (OS_EVENT_MULTI_EN > 0u)
OSTCBCur->OSTCBEventMultiPtr = (OS_EVENT **)0;
#endif
OSTCBCur->OSTCBMsg = (void *)0; /* Clear received message */
OS_EXIT_CRITICAL();
return (pmsg); /* Return received message */
}
/*$PAGE*/
/*
*********************************************************************************************************
* ABORT WAITING ON A MESSAGE QUEUE
*
* Description: This function aborts & readies any tasks currently waiting on a queue. This function
* should be used to fault-abort the wait on the queue, rather than to normally signal
* the queue via OSQPost(), OSQPostFront() or OSQPostOpt().
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue.
*
* opt determines the type of ABORT performed:
* OS_PEND_OPT_NONE ABORT wait for a single task (HPT) waiting on the
* queue
* OS_PEND_OPT_BROADCAST ABORT wait for ALL tasks that are waiting on the
* queue
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE No tasks were waiting on the queue.
* OS_ERR_PEND_ABORT At least one task waiting on the queue was readied
* and informed of the aborted wait; check return value
* for the number of tasks whose wait on the queue
* was aborted.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : == 0 if no tasks were waiting on the queue, or upon error.
* > 0 if one or more tasks waiting on the queue are now readied and informed.
*********************************************************************************************************
*/
#if OS_Q_PEND_ABORT_EN > 0u
INT8U OSQPendAbort (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
INT8U nbr_tasks;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (0u);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (0u);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task waiting on queue? */
nbr_tasks = 0u;
switch (opt) {
case OS_PEND_OPT_BROADCAST: /* Do we need to abort ALL waiting tasks? */
while (pevent->OSEventGrp != 0u) { /* Yes, ready ALL tasks waiting on queue */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_Q, OS_STAT_PEND_ABORT);
nbr_tasks++;
}
break;
case OS_PEND_OPT_NONE:
default: /* No, ready HPT waiting on queue */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_Q, OS_STAT_PEND_ABORT);
nbr_tasks++;
break;
}
OS_EXIT_CRITICAL();
OS_Sched(); /* Find HPT ready to run */
*perr = OS_ERR_PEND_ABORT;
return (nbr_tasks);
}
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (0u); /* No tasks waiting on queue */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST MESSAGE TO A QUEUE
*
* Description: This function sends a message to a queue
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue
*
* pmsg is a pointer to the message to send.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_Q_FULL If the queue cannot accept any more messages because it is full.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
*
* Note(s) : As of V2.60, this function allows you to send NULL pointer messages.
*********************************************************************************************************
*/
#if OS_Q_POST_EN > 0u
INT8U OSQPost (OS_EVENT *pevent,
void *pmsg)
{
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task pending on queue */
/* Ready highest priority task waiting on event */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_Q, OS_STAT_PEND_OK);
OS_EXIT_CRITICAL();
OS_Sched(); /* Find highest priority task ready to run */
return (OS_ERR_NONE);
}
pq = (OS_Q *)pevent->OSEventPtr; /* Point to queue control block */
if (pq->OSQEntries >= pq->OSQSize) { /* Make sure queue is not full */
OS_EXIT_CRITICAL();
return (OS_ERR_Q_FULL);
}
*pq->OSQIn++ = pmsg; /* Insert message into queue */
pq->OSQEntries++; /* Update the nbr of entries in the queue */
if (pq->OSQIn == pq->OSQEnd) { /* Wrap IN ptr if we are at end of queue */
pq->OSQIn = pq->OSQStart;
}
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST MESSAGE TO THE FRONT OF A QUEUE
*
* Description: This function sends a message to a queue but unlike OSQPost(), the message is posted at
* the front instead of the end of the queue. Using OSQPostFront() allows you to send
* 'priority' messages.
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue
*
* pmsg is a pointer to the message to send.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_Q_FULL If the queue cannot accept any more messages because it is full.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
*
* Note(s) : As of V2.60, this function allows you to send NULL pointer messages.
*********************************************************************************************************
*/
#if OS_Q_POST_FRONT_EN > 0u
INT8U OSQPostFront (OS_EVENT *pevent,
void *pmsg)
{
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task pending on queue */
/* Ready highest priority task waiting on event */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_Q, OS_STAT_PEND_OK);
OS_EXIT_CRITICAL();
OS_Sched(); /* Find highest priority task ready to run */
return (OS_ERR_NONE);
}
pq = (OS_Q *)pevent->OSEventPtr; /* Point to queue control block */
if (pq->OSQEntries >= pq->OSQSize) { /* Make sure queue is not full */
OS_EXIT_CRITICAL();
return (OS_ERR_Q_FULL);
}
if (pq->OSQOut == pq->OSQStart) { /* Wrap OUT ptr if we are at the 1st queue entry */
pq->OSQOut = pq->OSQEnd;
}
pq->OSQOut--;
*pq->OSQOut = pmsg; /* Insert message into queue */
pq->OSQEntries++; /* Update the nbr of entries in the queue */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST MESSAGE TO A QUEUE
*
* Description: This function sends a message to a queue. This call has been added to reduce code size
* since it can replace both OSQPost() and OSQPostFront(). Also, this function adds the
* capability to broadcast a message to ALL tasks waiting on the message queue.
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue
*
* pmsg is a pointer to the message to send.
*
* opt determines the type of POST performed:
* OS_POST_OPT_NONE POST to a single waiting task
* (Identical to OSQPost())
* OS_POST_OPT_BROADCAST POST to ALL tasks that are waiting on the queue
* OS_POST_OPT_FRONT POST as LIFO (Simulates OSQPostFront())
* OS_POST_OPT_NO_SCHED Indicates that the scheduler will NOT be invoked
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_Q_FULL If the queue cannot accept any more messages because it is full.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a queue.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
*
* Warning : Interrupts can be disabled for a long time if you do a 'broadcast'. In fact, the
* interrupt disable time is proportional to the number of tasks waiting on the queue.
*********************************************************************************************************
*/
#if OS_Q_POST_OPT_EN > 0u
INT8U OSQPostOpt (OS_EVENT *pevent,
void *pmsg,
INT8U opt)
{
OS_Q *pq;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0x00u) { /* See if any task pending on queue */
if ((opt & OS_POST_OPT_BROADCAST) != 0x00u) { /* Do we need to post msg to ALL waiting tasks ? */
while (pevent->OSEventGrp != 0u) { /* Yes, Post to ALL tasks waiting on queue */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_Q, OS_STAT_PEND_OK);
}
} else { /* No, Post to HPT waiting on queue */
(void)OS_EventTaskRdy(pevent, pmsg, OS_STAT_Q, OS_STAT_PEND_OK);
}
OS_EXIT_CRITICAL();
if ((opt & OS_POST_OPT_NO_SCHED) == 0u) { /* See if scheduler needs to be invoked */
OS_Sched(); /* Find highest priority task ready to run */
}
return (OS_ERR_NONE);
}
pq = (OS_Q *)pevent->OSEventPtr; /* Point to queue control block */
if (pq->OSQEntries >= pq->OSQSize) { /* Make sure queue is not full */
OS_EXIT_CRITICAL();
return (OS_ERR_Q_FULL);
}
if ((opt & OS_POST_OPT_FRONT) != 0x00u) { /* Do we post to the FRONT of the queue? */
if (pq->OSQOut == pq->OSQStart) { /* Yes, Post as LIFO, Wrap OUT pointer if we ... */
pq->OSQOut = pq->OSQEnd; /* ... are at the 1st queue entry */
}
pq->OSQOut--;
*pq->OSQOut = pmsg; /* Insert message into queue */
} else { /* No, Post as FIFO */
*pq->OSQIn++ = pmsg; /* Insert message into queue */
if (pq->OSQIn == pq->OSQEnd) { /* Wrap IN ptr if we are at end of queue */
pq->OSQIn = pq->OSQStart;
}
}
pq->OSQEntries++; /* Update the nbr of entries in the queue */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* QUERY A MESSAGE QUEUE
*
* Description: This function obtains information about a message queue.
*
* Arguments : pevent is a pointer to the event control block associated with the desired queue
*
* p_q_data is a pointer to a structure that will contain information about the message
* queue.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_EVENT_TYPE If you are attempting to obtain data from a non queue.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer
* OS_ERR_PDATA_NULL If 'p_q_data' is a NULL pointer
*********************************************************************************************************
*/
#if OS_Q_QUERY_EN > 0u
INT8U OSQQuery (OS_EVENT *pevent,
OS_Q_DATA *p_q_data)
{
OS_Q *pq;
INT8U i;
OS_PRIO *psrc;
OS_PRIO *pdest;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (p_q_data == (OS_Q_DATA *)0) { /* Validate 'p_q_data' */
return (OS_ERR_PDATA_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_Q) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
p_q_data->OSEventGrp = pevent->OSEventGrp; /* Copy message queue wait list */
psrc = &pevent->OSEventTbl[0];
pdest = &p_q_data->OSEventTbl[0];
for (i = 0u; i < OS_EVENT_TBL_SIZE; i++) {
*pdest++ = *psrc++;
}
pq = (OS_Q *)pevent->OSEventPtr;
if (pq->OSQEntries > 0u) {
p_q_data->OSMsg = *pq->OSQOut; /* Get next message to return if available */
} else {
p_q_data->OSMsg = (void *)0;
}
p_q_data->OSNMsgs = pq->OSQEntries;
p_q_data->OSQSize = pq->OSQSize;
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif /* OS_Q_QUERY_EN */
/*$PAGE*/
/*
*********************************************************************************************************
* QUEUE MODULE INITIALIZATION
*
* Description : This function is called by uC/OS-II to initialize the message queue module. Your
* application MUST NOT call this function.
*
* Arguments : none
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-II and your application should not call it.
*********************************************************************************************************
*/
void OS_QInit (void)
{
#if OS_MAX_QS == 1u
OSQFreeList = &OSQTbl[0]; /* Only ONE queue! */
OSQFreeList->OSQPtr = (OS_Q *)0;
#endif
#if OS_MAX_QS >= 2u
INT16U ix;
INT16U ix_next;
OS_Q *pq1;
OS_Q *pq2;
OS_MemClr((INT8U *)&OSQTbl[0], sizeof(OSQTbl)); /* Clear the queue table */
for (ix = 0u; ix < (OS_MAX_QS - 1u); ix++) { /* Init. list of free QUEUE control blocks */
ix_next = ix + 1u;
pq1 = &OSQTbl[ix];
pq2 = &OSQTbl[ix_next];
pq1->OSQPtr = pq2;
}
pq1 = &OSQTbl[ix];
pq1->OSQPtr = (OS_Q *)0;
OSQFreeList = &OSQTbl[0];
#endif
}
#endif /* OS_Q_EN */
~~~
uC/OS-II 函数之信号量相关函数
最后更新于：2022-04-01 11:42:38
> 上文主要介绍了时间相关的函数，本文介绍信号量相关的函数：OSSemCreate()建立信号量函数,OSSemPend()取得使用权函数,OSSemPost()使用权递加函数
## 信号量介绍
如果我们想对一个公共资源进行互斥访问，例如：如果我们想让两个任务Task1和Task2都可以调用Fun()函数，但不能同时调用，最好定义信号量：Semp = OSSemCreate(1)，同理在各自的任务中都需要调用OSSemPend(Semp,0,&err)请求此信号量，如果可用，则调用Fun（），然后再用OSSemPost(Semp)释放该信号量。这里就实现了一个资源的互斥访问。
（注：初始化OSSemCreate(1)，那么一个任务中有OSSemPend，那么可以执行，执行之后cnt==0，其他任务的OSSemPend无法获得sem，只能等待，除非任务一有OSSemPost，使其cnt++，这样其他任务的Pend可以执行。）
同理，如果一个任务要等待n个事件发生后才能执行，则应定义为Semp = OSSemCreate(n)。然后在这n个任务分别运行时调用OSSemPost(Semp),直到这n个事件均发生后，这个任务才能运行。
OSSemCreate(cnt)赋初始值cnt，OSSemPend一次，cnt– 一次，OSSemPost一次，cnt++一次。
下面对信号量函数做简要介绍：
## OSSemCreate()建立信号量函数
1、主要作用：该函数建立并初始化一个信号量，信号量的作用如下：
允许一个任务和其他任务或者中断同步
取得设备的使用权
标志事件的发生
2、函数原型：OS_EVENT *OSSemCreate(INT16U value);
3、参数说明：value 参数是所建立的信号量的初始值，可以取0到65535之间的任何值。
4、返回值：OSSemCreate() 函数返回指向分配给所建立的信号量的控制块的指针。如果没有可用的控制块，OSSemCreate() 函数返回空指针。
5、函数主体在os_sem.c中
## OSSemPend()取得使用权函数
1、主要作用： 该函数用于任务试图取得设备的使用权、任务需要和其他任务或中断同步、任务需要等待特定事件的发生的场合。如果任务调用OSSemPend() 函数时，信号量的值大于零，OSSemPend() 函数递减该值。如果调用时信号量值等于零，OSSemPend() 函数将任务加入该信号量的等待队列。OSSemPend() 函数挂起当前任务直到其他的任务或中断设置信号量或超出等待的预期时间。如果在预期的时钟节拍内信号量被设置，μC/OS-Ⅱ默认让最高优先级的任务取得信号量并回到就绪状态。一个被OSTaskSuspend() 函数挂起的任务也可以接受信号量，但这个任务将一直保持挂起状态直到通过调用OSTaskResume() 函数恢复该任务的运行。
2、函数原型：void OSSemPend ( OS_EVNNT *pevent, INT16U timeout, int8u *err );
3、参数说明：
pevent 是指向信号量的指针。该指针的值在建立该信号量时可以得到。（参考OSSemCreate() 函数）。
timeout 允许一个任务在经过了指定数目的时钟节拍后还没有得到需要的信号量时恢复就绪状态。如果该值为零表示任务将持续地等待信号量，最大的等待时间为65535个时钟节拍。这个时间长度并不是非常严格的，可能存在一个时钟节拍的误差。
err 是指向包含错误码的变量的指针，返回的错误码可能为下述几种：
OS_NO_ERR ：信号量不为零。
OS_TIMEOUT ：信号量没有在指定数目的时钟周期内被设置。
OS_ERR_PEND_ISR ：从中断调用该函数。虽然规定了不允许从中断调用该函数，但μC/OS-Ⅱ仍然包含了检测这种情况的功能。
OS_ERR_EVENT_TYPE ：pevent 不是指向信号量的指针。
4、返回值：无
5、函数主体在os_sem.c中
## OSSemPost()使用权放弃函数
1、主要作用： 该函数用于设置指定的信号量。如果指定的信号量是零或大于零，OSSemPost() 函数递增该信号量的值并返回。如果有任何任务在等待该信号量，则最高优先级的任务将得到信号量并进入就绪状态。任务调度函数将进行任务调度，决定当前运行的任务是否仍然为最高优先级的就绪任务。
2、函数原型：INT8U OSSemPost（OS_EVENT *pevent）;
3、参数说明：pevent 是指向信号量的指针。该指针的值在建立该信号量时可以得到。（参考OSSemCreate() 函数）。
4、返回值：
OS_NO_ERR ：信号量被成功地设置
OS_SEM_OVF ：信号量的值溢出
OS_ERR_EVENT_TYPE ：pevent 不是指向信号量的指针
5、函数主体在os_sem.c中
## 附os_sem.c
~~~
/*
*********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* SEMAPHORE MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_SEM.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
#if OS_SEM_EN > 0u
/*$PAGE*/
/*
*********************************************************************************************************
* ACCEPT SEMAPHORE
*
* Description: This function checks the semaphore to see if a resource is available or, if an event
* occurred. Unlike OSSemPend(), OSSemAccept() does not suspend the calling task if the
* resource is not available or the event did not occur.
*
* Arguments : pevent is a pointer to the event control block
*
* Returns : > 0 if the resource is available or the event did not occur the semaphore is
* decremented to obtain the resource.
* == 0 if the resource is not available or the event did not occur or,
* if 'pevent' is a NULL pointer or,
* if you didn't pass a pointer to a semaphore
*********************************************************************************************************
*/
#if OS_SEM_ACCEPT_EN > 0u
INT16U OSSemAccept (OS_EVENT *pevent)
{
INT16U cnt;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (0u);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
return (0u);
}
OS_ENTER_CRITICAL();
cnt = pevent->OSEventCnt;
if (cnt > 0u) { /* See if resource is available */
pevent->OSEventCnt--; /* Yes, decrement semaphore and notify caller */
}
OS_EXIT_CRITICAL();
return (cnt); /* Return semaphore count */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CREATE A SEMAPHORE
*
* Description: This function creates a semaphore.
*
* Arguments : cnt is the initial value for the semaphore. If the value is 0, no resource is
* available (or no event has occurred). You initialize the semaphore to a
* non-zero value to specify how many resources are available (e.g. if you have
* 10 resources, you would initialize the semaphore to 10).
*
* Returns : != (void *)0 is a pointer to the event control block (OS_EVENT) associated with the
* created semaphore
* == (void *)0 if no event control blocks were available
*********************************************************************************************************
*/
OS_EVENT *OSSemCreate (INT16U cnt)
{
OS_EVENT *pevent;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
if (OSIntNesting > 0u) { /* See if called from ISR ... */
return ((OS_EVENT *)0); /* ... can't CREATE from an ISR */
}
OS_ENTER_CRITICAL();
pevent = OSEventFreeList; /* Get next free event control block */
if (OSEventFreeList != (OS_EVENT *)0) { /* See if pool of free ECB pool was empty */
OSEventFreeList = (OS_EVENT *)OSEventFreeList->OSEventPtr;
}
OS_EXIT_CRITICAL();
if (pevent != (OS_EVENT *)0) { /* Get an event control block */
pevent->OSEventType = OS_EVENT_TYPE_SEM;
pevent->OSEventCnt = cnt; /* Set semaphore value */
pevent->OSEventPtr = (void *)0; /* Unlink from ECB free list */
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
OS_EventWaitListInit(pevent); /* Initialize to 'nobody waiting' on sem. */
}
return (pevent);
}
/*$PAGE*/
/*
*********************************************************************************************************
* DELETE A SEMAPHORE
*
* Description: This function deletes a semaphore and readies all tasks pending on the semaphore.
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* semaphore.
*
* opt determines delete options as follows:
* opt == OS_DEL_NO_PEND Delete semaphore ONLY if no task pending
* opt == OS_DEL_ALWAYS Deletes the semaphore even if tasks are waiting.
* In this case, all the tasks pending will be readied.
*
* perr is a pointer to an error code that can contain one of the following values:
* OS_ERR_NONE The call was successful and the semaphore was deleted
* OS_ERR_DEL_ISR If you attempted to delete the semaphore from an ISR
* OS_ERR_INVALID_OPT An invalid option was specified
* OS_ERR_TASK_WAITING One or more tasks were waiting on the semaphore
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a semaphore
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : pevent upon error
* (OS_EVENT *)0 if the semaphore was successfully deleted.
*
* Note(s) : 1) This function must be used with care. Tasks that would normally expect the presence of
* the semaphore MUST check the return code of OSSemPend().
* 2) OSSemAccept() callers will not know that the intended semaphore has been deleted unless
* they check 'pevent' to see that it's a NULL pointer.
* 3) This call can potentially disable interrupts for a long time. The interrupt disable
* time is directly proportional to the number of tasks waiting on the semaphore.
* 4) Because ALL tasks pending on the semaphore will be readied, you MUST be careful in
* applications where the semaphore is used for mutual exclusion because the resource(s)
* will no longer be guarded by the semaphore.
* 5) All tasks that were waiting for the semaphore will be readied and returned an
* OS_ERR_PEND_ABORT if OSSemDel() was called with OS_DEL_ALWAYS
*********************************************************************************************************
*/
#if OS_SEM_DEL_EN > 0u
OS_EVENT *OSSemDel (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
BOOLEAN tasks_waiting;
OS_EVENT *pevent_return;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((OS_EVENT *)0);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (pevent);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (pevent);
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_DEL_ISR; /* ... can't DELETE from an ISR */
return (pevent);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any tasks waiting on semaphore */
tasks_waiting = OS_TRUE; /* Yes */
} else {
tasks_waiting = OS_FALSE; /* No */
}
switch (opt) {
case OS_DEL_NO_PEND: /* Delete semaphore only if no task waiting */
if (tasks_waiting == OS_FALSE) {
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Semaphore has been deleted */
} else {
OS_EXIT_CRITICAL();
*perr = OS_ERR_TASK_WAITING;
pevent_return = pevent;
}
break;
case OS_DEL_ALWAYS: /* Always delete the semaphore */
while (pevent->OSEventGrp != 0u) { /* Ready ALL tasks waiting for semaphore */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_SEM, OS_STAT_PEND_ABORT);
}
#if OS_EVENT_NAME_EN > 0u
pevent->OSEventName = (INT8U *)(void *)"?";
#endif
pevent->OSEventType = OS_EVENT_TYPE_UNUSED;
pevent->OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */
pevent->OSEventCnt = 0u;
OSEventFreeList = pevent; /* Get next free event control block */
OS_EXIT_CRITICAL();
if (tasks_waiting == OS_TRUE) { /* Reschedule only if task(s) were waiting */
OS_Sched(); /* Find highest priority task ready to run */
}
*perr = OS_ERR_NONE;
pevent_return = (OS_EVENT *)0; /* Semaphore has been deleted */
break;
default:
OS_EXIT_CRITICAL();
*perr = OS_ERR_INVALID_OPT;
pevent_return = pevent;
break;
}
return (pevent_return);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* PEND ON SEMAPHORE
*
* Description: This function waits for a semaphore.
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* semaphore.
*
* timeout is an optional timeout period (in clock ticks). If non-zero, your task will
* wait for the resource up to the amount of time specified by this argument.
* If you specify 0, however, your task will wait forever at the specified
* semaphore or, until the resource becomes available (or the event occurs).
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE The call was successful and your task owns the resource
* or, the event you are waiting for occurred.
* OS_ERR_TIMEOUT The semaphore was not received within the specified
* 'timeout'.
* OS_ERR_PEND_ABORT The wait on the semaphore was aborted.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a semaphore.
* OS_ERR_PEND_ISR If you called this function from an ISR and the result
* would lead to a suspension.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
* OS_ERR_PEND_LOCKED If you called this function when the scheduler is locked
*
* Returns : none
*********************************************************************************************************
*/
/*$PAGE*/
void OSSemPend (OS_EVENT *pevent,
INT32U timeout,
INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return;
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return;
}
if (OSIntNesting > 0u) { /* See if called from ISR ... */
*perr = OS_ERR_PEND_ISR; /* ... can't PEND from an ISR */
return;
}
if (OSLockNesting > 0u) { /* See if called with scheduler locked ... */
*perr = OS_ERR_PEND_LOCKED; /* ... can't PEND when locked */
return;
}
OS_ENTER_CRITICAL();
if (pevent->OSEventCnt > 0u) { /* If sem. is positive, resource available ... */
pevent->OSEventCnt--; /* ... decrement semaphore only if positive. */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return;
}
/* Otherwise, must wait until event occurs */
OSTCBCur->OSTCBStat |= OS_STAT_SEM; /* Resource not available, pend on semaphore */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK;
OSTCBCur->OSTCBDly = timeout; /* Store pend timeout in TCB */
OS_EventTaskWait(pevent); /* Suspend task until event or timeout occurs */
OS_EXIT_CRITICAL();
OS_Sched(); /* Find next highest priority task ready */
OS_ENTER_CRITICAL();
switch (OSTCBCur->OSTCBStatPend) { /* See if we timed-out or aborted */
case OS_STAT_PEND_OK:
*perr = OS_ERR_NONE;
break;
case OS_STAT_PEND_ABORT:
*perr = OS_ERR_PEND_ABORT; /* Indicate that we aborted */
break;
case OS_STAT_PEND_TO:
default:
OS_EventTaskRemove(OSTCBCur, pevent);
*perr = OS_ERR_TIMEOUT; /* Indicate that we didn't get event within TO */
break;
}
OSTCBCur->OSTCBStat = OS_STAT_RDY; /* Set task status to ready */
OSTCBCur->OSTCBStatPend = OS_STAT_PEND_OK; /* Clear pend status */
OSTCBCur->OSTCBEventPtr = (OS_EVENT *)0; /* Clear event pointers */
#if (OS_EVENT_MULTI_EN > 0u)
OSTCBCur->OSTCBEventMultiPtr = (OS_EVENT **)0;
#endif
OS_EXIT_CRITICAL();
}
/*$PAGE*/
/*
*********************************************************************************************************
* ABORT WAITING ON A SEMAPHORE
*
* Description: This function aborts & readies any tasks currently waiting on a semaphore. This function
* should be used to fault-abort the wait on the semaphore, rather than to normally signal
* the semaphore via OSSemPost().
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* semaphore.
*
* opt determines the type of ABORT performed:
* OS_PEND_OPT_NONE ABORT wait for a single task (HPT) waiting on the
* semaphore
* OS_PEND_OPT_BROADCAST ABORT wait for ALL tasks that are waiting on the
* semaphore
*
* perr is a pointer to where an error message will be deposited. Possible error
* messages are:
*
* OS_ERR_NONE No tasks were waiting on the semaphore.
* OS_ERR_PEND_ABORT At least one task waiting on the semaphore was readied
* and informed of the aborted wait; check return value
* for the number of tasks whose wait on the semaphore
* was aborted.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a semaphore.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*
* Returns : == 0 if no tasks were waiting on the semaphore, or upon error.
* > 0 if one or more tasks waiting on the semaphore are now readied and informed.
*********************************************************************************************************
*/
#if OS_SEM_PEND_ABORT_EN > 0u
INT8U OSSemPendAbort (OS_EVENT *pevent,
INT8U opt,
INT8U *perr)
{
INT8U nbr_tasks;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return (0u);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return (0u);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task waiting on semaphore? */
nbr_tasks = 0u;
switch (opt) {
case OS_PEND_OPT_BROADCAST: /* Do we need to abort ALL waiting tasks? */
while (pevent->OSEventGrp != 0u) { /* Yes, ready ALL tasks waiting on semaphore */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_SEM, OS_STAT_PEND_ABORT);
nbr_tasks++;
}
break;
case OS_PEND_OPT_NONE:
default: /* No, ready HPT waiting on semaphore */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_SEM, OS_STAT_PEND_ABORT);
nbr_tasks++;
break;
}
OS_EXIT_CRITICAL();
OS_Sched(); /* Find HPT ready to run */
*perr = OS_ERR_PEND_ABORT;
return (nbr_tasks);
}
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (0u); /* No tasks waiting on semaphore */
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* POST TO A SEMAPHORE
*
* Description: This function signals a semaphore
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* semaphore.
*
* Returns : OS_ERR_NONE The call was successful and the semaphore was signaled.
* OS_ERR_SEM_OVF If the semaphore count exceeded its limit. In other words, you have
* signaled the semaphore more often than you waited on it with either
* OSSemAccept() or OSSemPend().
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a semaphore
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
*********************************************************************************************************
*/
INT8U OSSemPost (OS_EVENT *pevent)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
if (pevent->OSEventGrp != 0u) { /* See if any task waiting for semaphore */
/* Ready HPT waiting on event */
(void)OS_EventTaskRdy(pevent, (void *)0, OS_STAT_SEM, OS_STAT_PEND_OK);
OS_EXIT_CRITICAL();
OS_Sched(); /* Find HPT ready to run */
return (OS_ERR_NONE);
}
if (pevent->OSEventCnt < 65535u) { /* Make sure semaphore will not overflow */
pevent->OSEventCnt++; /* Increment semaphore count to register event */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
OS_EXIT_CRITICAL(); /* Semaphore value has reached its maximum */
return (OS_ERR_SEM_OVF);
}
/*$PAGE*/
/*
*********************************************************************************************************
* QUERY A SEMAPHORE
*
* Description: This function obtains information about a semaphore
*
* Arguments : pevent is a pointer to the event control block associated with the desired
* semaphore
*
* p_sem_data is a pointer to a structure that will contain information about the
* semaphore.
*
* Returns : OS_ERR_NONE The call was successful and the message was sent
* OS_ERR_EVENT_TYPE If you are attempting to obtain data from a non semaphore.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
* OS_ERR_PDATA_NULL If 'p_sem_data' is a NULL pointer
*********************************************************************************************************
*/
#if OS_SEM_QUERY_EN > 0u
INT8U OSSemQuery (OS_EVENT *pevent,
OS_SEM_DATA *p_sem_data)
{
INT8U i;
OS_PRIO *psrc;
OS_PRIO *pdest;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
return (OS_ERR_PEVENT_NULL);
}
if (p_sem_data == (OS_SEM_DATA *)0) { /* Validate 'p_sem_data' */
return (OS_ERR_PDATA_NULL);
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
return (OS_ERR_EVENT_TYPE);
}
OS_ENTER_CRITICAL();
p_sem_data->OSEventGrp = pevent->OSEventGrp; /* Copy message mailbox wait list */
psrc = &pevent->OSEventTbl[0];
pdest = &p_sem_data->OSEventTbl[0];
for (i = 0u; i < OS_EVENT_TBL_SIZE; i++) {
*pdest++ = *psrc++;
}
p_sem_data->OSCnt = pevent->OSEventCnt; /* Get semaphore count */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif /* OS_SEM_QUERY_EN */
/*$PAGE*/
/*
*********************************************************************************************************
* SET SEMAPHORE
*
* Description: This function sets the semaphore count to the value specified as an argument. Typically,
* this value would be 0.
*
* You would typically use this function when a semaphore is used as a signaling mechanism
* and, you want to reset the count value.
*
* Arguments : pevent is a pointer to the event control block
*
* cnt is the new value for the semaphore count. You would pass 0 to reset the
* semaphore count.
*
* perr is a pointer to an error code returned by the function as follows:
*
* OS_ERR_NONE The call was successful and the semaphore value was set.
* OS_ERR_EVENT_TYPE If you didn't pass a pointer to a semaphore.
* OS_ERR_PEVENT_NULL If 'pevent' is a NULL pointer.
* OS_ERR_TASK_WAITING If tasks are waiting on the semaphore.
*********************************************************************************************************
*/
#if OS_SEM_SET_EN > 0u
void OSSemSet (OS_EVENT *pevent,
INT16U cnt,
INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if OS_ARG_CHK_EN > 0u
if (pevent == (OS_EVENT *)0) { /* Validate 'pevent' */
*perr = OS_ERR_PEVENT_NULL;
return;
}
#endif
if (pevent->OSEventType != OS_EVENT_TYPE_SEM) { /* Validate event block type */
*perr = OS_ERR_EVENT_TYPE;
return;
}
OS_ENTER_CRITICAL();
*perr = OS_ERR_NONE;
if (pevent->OSEventCnt > 0u) { /* See if semaphore already has a count */
pevent->OSEventCnt = cnt; /* Yes, set it to the new value specified. */
} else { /* No */
if (pevent->OSEventGrp == 0u) { /* See if task(s) waiting? */
pevent->OSEventCnt = cnt; /* No, OK to set the value */
} else {
*perr = OS_ERR_TASK_WAITING;
}
}
OS_EXIT_CRITICAL();
}
#endif
#endif /* OS_SEM_EN */
~~~
uC/OS-II 函数之时间相关函数
最后更新于：2022-04-01 11:42:35
获得更多资料欢迎进入[我的网站](http://rlovep.com/)或者 [csdn](http://blog.csdn.net/peace1213)或者[博客园](http://www.cnblogs.com/onepeace/)
> 对于有热心的小伙伴在[微博](http://weibo.com/u/2026326475/)上私信我，说我的[uC/OS-II 一些函数简介](http://blog.csdn.net/peace1213/article/details/47056651)篇幅有些过于长应该分开介绍。应小伙伴的要求，特此将文章分开进行讲解。上文主要介绍了任务相关的函数，本文介绍时间相关的函数：OSTimeDly()延时节拍函数，OSTimeDlyHMSM()系统延时函数，OSTimeDlyResume()延时恢复函数
## OSTimeDly()延时节拍函数
1、主要作用：调用该函数的任务将自己延时一段时间并执行一次任务调度，一旦规定的延时时间完成或有其它的任务通过调用OSTimeDlyResume()取消了延时，调用OSTimeDly()函数的任务马上进入就绪状态（前提是先将任务调度后执行的任务执行到程序尾，且调用OSTimeDly的任务此时优先级最高）。
2、函数原型：void OSTimeDly (INT16U ticks);
3、参数说明：ticks为需要延时的时钟节拍数；
4、返回值：无
5、函数主体在os_time.c中
## OSTimeDlyHMSM()系统延时函数
1、主要作用：函数是以小时(H)、分(M)、秒(S)和毫秒(m)四个参数来定义延时时间的，函数在内部把这些参数转换为时钟节拍，再通过单次或多次调用OSTimeDly()进行延时和任务调度，所以延时原理和调用延时函数OSTimeDly()是一样的。调用 OSTimeDlyHMSM() 后，如果延时时间不为0，系统将立即进行任务调度。
2、函数原型：INT8U OSTimeDlyHMSM (INT8U hours，INT8U minutes，INT8U seconds，INT16U milli);
3、参数说明：
hours 为延时小时数，范围从0-255。
minutes 为延时分钟数，范围从0-59
seconds 为延时秒数，范围从0-59
milli 为延时毫秒数，范围从0-999
4、返回值说明：
OS_NO_ERR：函数调用成功。
OS_TIME_INVALID_MINUTES：参数错误，分钟数大于59。
OS_TIME_INVALID_SECONDS：参数错误，秒数大于59。
OS_TIME_INVALID_MILLI：参数错误，毫秒数大于999。
OS_TIME_ZERO_DLY：四个参数全为0。
5、函数主体在os_time.c中
## OSTimeDlyResume()延时恢复函数
1、主要作用：任务在延时之后，进入阻塞态。当延时时间到了就从阻塞态恢复到就绪态，可以被操作系统调度执行。但是，并非回到就绪态就只有这么一种可能，因为即便任务的延时时间没到，还是可以通过函数OSTimeDlyResume恢复该任务到就绪态的。另外，OSTimeDlyResume也不仅仅能恢复使用OSTimeDly或OSTimeDlyHMSM而延时的任务。对于因等待事件发生而阻塞的，并且设置了超时（timeout）时间的任务，也可以使用OSTimeDlyResume来恢复。对这些任务使用了OSTimeDlyResume，就好像已经等待超时了一样。但是，对于采用OSTaskSuspend挂起的任务，是不允许采用OSTimeDlyResume来恢复的。
2、函数原型：INT8U OSTimeDlyResume (INT8U prio)
3.参数说明：prio 被恢复任务的优先级
4、返回值：
OS_ERR_TASK_NOT_EXIST：任务优先级指针表中没有此任务
OS_NO_ERR：函数调用成功。
OS_ERR_PRIO_INVALID：参数指定的优先级大于或等于OS_LOWEST_PRIO。
OS_ERR_TIME_NOT_DLY：任务没有被延时阻塞
5、函数主体在os_time.c中
## 附os_time.c代码
~~~
/*
*********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* TIME MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_TIME.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
/*
*********************************************************************************************************
* DELAY TASK 'n' TICKS
*
* Description: This function is called to delay execution of the currently running task until the
* specified number of system ticks expires. This, of course, directly equates to delaying
* the current task for some time to expire. No delay will result If the specified delay is
* 0. If the specified delay is greater than 0 then, a context switch will result.
*
* Arguments : ticks is the time delay that the task will be suspended in number of clock 'ticks'.
* Note that by specifying 0, the task will not be delayed.
*
* Returns : none
*********************************************************************************************************
*/
void OSTimeDly (INT32U ticks)
{
INT8U y;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
return;
}
if (OSLockNesting > 0u) { /* See if called with scheduler locked */
return;
}
if (ticks > 0u) { /* 0 means no delay! */
OS_ENTER_CRITICAL();
y = OSTCBCur->OSTCBY; /* Delay current task */
OSRdyTbl[y] &= (OS_PRIO)~OSTCBCur->OSTCBBitX;
if (OSRdyTbl[y] == 0u) {
OSRdyGrp &= (OS_PRIO)~OSTCBCur->OSTCBBitY;
}
OSTCBCur->OSTCBDly = ticks; /* Load ticks in TCB */
OS_EXIT_CRITICAL();
OS_Sched(); /* Find next task to run! */
}
}
/*$PAGE*/
/*
*********************************************************************************************************
* DELAY TASK FOR SPECIFIED TIME
*
* Description: This function is called to delay execution of the currently running task until some time
* expires. This call allows you to specify the delay time in HOURS, MINUTES, SECONDS and
* MILLISECONDS instead of ticks.
*
* Arguments : hours specifies the number of hours that the task will be delayed (max. is 255)
* minutes specifies the number of minutes (max. 59)
* seconds specifies the number of seconds (max. 59)
* ms specifies the number of milliseconds (max. 999)
*
* Returns : OS_ERR_NONE
* OS_ERR_TIME_INVALID_MINUTES
* OS_ERR_TIME_INVALID_SECONDS
* OS_ERR_TIME_INVALID_MS
* OS_ERR_TIME_ZERO_DLY
* OS_ERR_TIME_DLY_ISR
*
* Note(s) : The resolution on the milliseconds depends on the tick rate. For example, you can't do
* a 10 mS delay if the ticker interrupts every 100 mS. In this case, the delay would be
* set to 0. The actual delay is rounded to the nearest tick.
*********************************************************************************************************
*/
#if OS_TIME_DLY_HMSM_EN > 0u
INT8U OSTimeDlyHMSM (INT8U hours,
INT8U minutes,
INT8U seconds,
INT16U ms)
{
INT32U ticks;
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
return (OS_ERR_TIME_DLY_ISR);
}
if (OSLockNesting > 0u) { /* See if called with scheduler locked */
return (OS_ERR_SCHED_LOCKED);
}
#if OS_ARG_CHK_EN > 0u
if (hours == 0u) {
if (minutes == 0u) {
if (seconds == 0u) {
if (ms == 0u) {
return (OS_ERR_TIME_ZERO_DLY);
}
}
}
}
if (minutes > 59u) {
return (OS_ERR_TIME_INVALID_MINUTES); /* Validate arguments to be within range */
}
if (seconds > 59u) {
return (OS_ERR_TIME_INVALID_SECONDS);
}
if (ms > 999u) {
return (OS_ERR_TIME_INVALID_MS);
}
#endif
/* Compute the total number of clock ticks required.. */
/* .. (rounded to the nearest tick) */
ticks = ((INT32U)hours * 3600uL + (INT32U)minutes * 60uL + (INT32U)seconds) * OS_TICKS_PER_SEC
+ OS_TICKS_PER_SEC * ((INT32U)ms + 500uL / OS_TICKS_PER_SEC) / 1000uL;
OSTimeDly(ticks);
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* RESUME A DELAYED TASK
*
* Description: This function is used resume a task that has been delayed through a call to either
* OSTimeDly() or OSTimeDlyHMSM(). Note that you can call this function to resume a
* task that is waiting for an event with timeout. This would make the task look
* like a timeout occurred.
*
* Arguments : prio specifies the priority of the task to resume
*
* Returns : OS_ERR_NONE Task has been resumed
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO)
* OS_ERR_TIME_NOT_DLY Task is not waiting for time to expire
* OS_ERR_TASK_NOT_EXIST The desired task has not been created or has been assigned to a Mutex.
*********************************************************************************************************
*/
#if OS_TIME_DLY_RESUME_EN > 0u
INT8U OSTimeDlyResume (INT8U prio)
{
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
if (prio >= OS_LOWEST_PRIO) {
return (OS_ERR_PRIO_INVALID);
}
OS_ENTER_CRITICAL();
ptcb = OSTCBPrioTbl[prio]; /* Make sure that task exist */
if (ptcb == (OS_TCB *)0) {
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST); /* The task does not exist */
}
if (ptcb == OS_TCB_RESERVED) {
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST); /* The task does not exist */
}
if (ptcb->OSTCBDly == 0u) { /* See if task is delayed */
OS_EXIT_CRITICAL();
return (OS_ERR_TIME_NOT_DLY); /* Indicate that task was not delayed */
}
ptcb->OSTCBDly = 0u; /* Clear the time delay */
if ((ptcb->OSTCBStat & OS_STAT_PEND_ANY) != OS_STAT_RDY) {
ptcb->OSTCBStat &= ~OS_STAT_PEND_ANY; /* Yes, Clear status flag */
ptcb->OSTCBStatPend = OS_STAT_PEND_TO; /* Indicate PEND timeout */
} else {
ptcb->OSTCBStatPend = OS_STAT_PEND_OK;
}
if ((ptcb->OSTCBStat & OS_STAT_SUSPEND) == OS_STAT_RDY) { /* Is task suspended? */
OSRdyGrp |= ptcb->OSTCBBitY; /* No, Make ready */
OSRdyTbl[ptcb->OSTCBY] |= ptcb->OSTCBBitX;
OS_EXIT_CRITICAL();
OS_Sched(); /* See if this is new highest priority */
} else {
OS_EXIT_CRITICAL(); /* Task may be suspended */
}
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* GET CURRENT SYSTEM TIME
*
* Description: This function is used by your application to obtain the current value of the 32-bit
* counter which keeps track of the number of clock ticks.
*
* Arguments : none
*
* Returns : The current value of OSTime
*********************************************************************************************************
*/
#if OS_TIME_GET_SET_EN > 0u
INT32U OSTimeGet (void)
{
INT32U ticks;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
OS_ENTER_CRITICAL();
ticks = OSTime;
OS_EXIT_CRITICAL();
return (ticks);
}
#endif
/*
*********************************************************************************************************
* SET SYSTEM CLOCK
*
* Description: This function sets the 32-bit counter which keeps track of the number of clock ticks.
*
* Arguments : ticks specifies the new value that OSTime needs to take.
*
* Returns : none
*********************************************************************************************************
*/
#if OS_TIME_GET_SET_EN > 0u
void OSTimeSet (INT32U ticks)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
OS_ENTER_CRITICAL();
OSTime = ticks;
OS_EXIT_CRITICAL();
}
#endif
~~~
uC/OS-II 函数之任务相关函数
最后更新于：2022-04-01 11:42:33
获得更多资料欢迎进入[我的网站](http://rlovep.com/)或者 [csdn](http://blog.csdn.net/peace1213)或者[博客园](http://www.cnblogs.com/onepeace/)
> 对于有热心的小伙伴在[微博](http://weibo.com/u/2026326475/)上私信我，说我的[uC/OS-II 一些函数简介](http://blog.csdn.net/peace1213/article/details/47056651)篇幅有些过于长应该分开介绍。应小伙伴的要求，特此将文章分开进行讲解。上文主要介绍了OSInit()初始化函数，本文介绍任务相关的函数：OSTaskCreate()任务创建函数1，OSTaskCreateExt任务创建函数2，OSTaskSuspend()任务挂起，OSTaskResume()唤醒任务
## OSTaskCreate()任务创建函数
1、主要作用：建立一个新任务。任务的建立可以在多任务环境启动之前，也可以在正在运行的任务中建立。中断处理程序中不能建立任务；注意，ISR中禁止建立任务，一个任务必须为无限循环结构。
2、函数原型：INT8U OSTaskCreate(void (*task)(void *pd), void *pdata, OS_STK *ptos, INT8U prio);
3、参数说明：
void (*task)(void *pd):指向任务代码首地址的指针。
void *pdata:指向一个数据结构，该结构用来在建立任务时向任务传递参数。
OS_STK *ptos: 指向堆栈任务栈顶的指针
INT8U prio：任务优先级
4、返回值介绍：
OS_NO_ERR：函数调用成功。
OS_PRIO_EXIST：具有该优先级的任务已经存在。
OS_PRIO_INVALID：参数指定的优先级大于OS_LOWEST_PRIO。
OS_NO_MORE_TCB：系统中没有OS_TCB可以分配给任务了。
5、函数主体在os_task.c中
## OSTaskCreateExt任务创建函数2
1、主要作用：建立一个新任务。与OSTaskCreate()不同的是,OSTaskCreateExt()允许用户设置更多的细节内容。任务的建立可以在多任务环境启动之前,也可以在正在运行的任务中建立,但中断处理程序中不能建立新任务。,且不
2、函数原型：NT8U OSTaskCreateExt (void (*task)(void *pd),void *pdata, OS_STK *ptos,INT8U prio ，INT16U id, OS_STK *pbos,INT32U stk_size,void *pext,INT16U opt)
3、参数说明：
void (*task)(void *pd):指向任务代码首地址的指针。
void *pdata:指向一个数据结构，该结构用来在建立任务时向任务传递参数。
OS_STK *ptos: 指向堆栈任务栈顶的指针
INT8U prio：任务优先级
INT16U id： 任务ID，2.52版本，无实际作用，保留作为扩展用
OS_STK *pbos： 指向堆栈底部的指针，用于OSTaskStkChk()函数
INT32U stk_size：指定任务堆栈的大小，由OS_STK类型决定
void *pext：定义数据结构的指针，作为TCB的扩展
INT16U opt) ：存放于任务操作相关的信息，详见uCOS-II.H
4、返回值说明：
OS_NO_ERR：函数调用成功。
OS_PRIO_EXIST：具有该优先级的任务已经存在。
OS_PRIO_INVALID：参数指定的优先级大于OS_LOWEST_PRIO。
OS_NO_MORE_TCB：系统中没有OS_TCB可以分配给任务了。
5、函数主体在os_task.c中
## OSTaskSuspend()任务挂起：
1、主要作用： 无条件挂起一个任务。调用此函数的任务也可以传递参数 OS_PRIO_SELF，挂起调用任务本身。当前任务挂起后，只有其他任务才能唤醒被挂起的任务。任务挂起后，系统会重新进行任务调度，运行下一个优先级最高的就绪任务。唤醒挂起任务需要调用函数OSTaskResume()。任务的挂起是可以叠加到其他操作上的。例如，任务被挂起时正在进行延时操作，那么任务的唤醒就需要两个条件：延时的结束以及其他任务的唤醒操作。又如，任务被挂起时正在等待信号量，当任务从信号量的等待对列中清除后也不能立即运行，而必须等到被唤醒后。
2、函数原型：INT8U OSTaskSuspend(INT8U prio);
3、参数说明:prio为指定要获取挂起的任务优先级，也可以指定参数 OS_PRIO_SELF，挂起任务本身。此时，下一个优先级最高的就绪任务将运行。
4、返回值说明：
OS_NO_ERR：函数调用成功。
OS_TASK_SUSPEND_IDLE：试图挂起μC/OS-II中的空闲任务（Idle task）。此为非法操作。
OS_PRIO_INVALID：参数指定的优先级大于 OS_LOWEST_PRIO 或没有设定 OS_PRIO_SELF 的值。
OS_TASK_SUSPEND_PRIO：要挂起的任务不存在。
5、函数主体在os_task.c中
## OSTaskResume()唤醒任务
1、主要作用： 唤醒一个用 OSTaskSuspend() 函数挂起的任务。OSTaskResume() 也是唯一能“解挂”挂起任务的函数。
2、函数原型：INT8U OSTaskResume(INT8U prio);
3、参数说明：prio指定要唤醒任务的优先级。
4、返回值说明：
OS_NO_ERR：函数调用成功。
OS_TASK_RESUME_PRIO：要唤醒的任务不存在
OS_TASK_NOT_SUSPENDED：要唤醒的任务不在挂起状态。
OS_PRIO_INVALID：参数指定的优先级大于或等于OS_LOWEST_PRIO。
5、函数主体在os_task.c中、
## 附os_task.c代码：
~~~
/*
*********************************************************************************************************
* uC/OS-II
* The Real-Time Kernel
* TASK MANAGEMENT
*
* (c) Copyright 1992-2013, Micrium, Weston, FL
* All Rights Reserved
*
* File : OS_TASK.C
* By : Jean J. Labrosse
* Version : V2.92.08
*
* LICENSING TERMS:
* ---------------
* uC/OS-II is provided in source form for FREE evaluation, for educational use or for peaceful research.
* If you plan on using uC/OS-II in a commercial product you need to contact Micrium to properly license
* its use in your product. We provide ALL the source code for your convenience and to help you experience
* uC/OS-II. The fact that the source is provided does NOT mean that you can use it without paying a
* licensing fee.
*********************************************************************************************************
*/
#define MICRIUM_SOURCE
#ifndef OS_MASTER_FILE
#include <ucos_ii.h>
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CHANGE PRIORITY OF A TASK
*
* Description: This function allows you to change the priority of a task dynamically. Note that the new
* priority MUST be available.
*
* Arguments : oldp is the old priority
*
* newp is the new priority
*
* Returns : OS_ERR_NONE is the call was successful
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO)
* OS_ERR_PRIO_EXIST if the new priority already exist.
* OS_ERR_PRIO there is no task with the specified OLD priority (i.e. the OLD task does
* not exist.
* OS_ERR_TASK_NOT_EXIST if the task is assigned to a Mutex PIP.
*********************************************************************************************************
*/
#if OS_TASK_CHANGE_PRIO_EN > 0u
INT8U OSTaskChangePrio (INT8U oldprio,
INT8U newprio)
{
#if (OS_EVENT_EN)
OS_EVENT *pevent;
#if (OS_EVENT_MULTI_EN > 0u)
OS_EVENT **pevents;
#endif
#endif
OS_TCB *ptcb;
INT8U y_new;
INT8U x_new;
INT8U y_old;
OS_PRIO bity_new;
OS_PRIO bitx_new;
OS_PRIO bity_old;
OS_PRIO bitx_old;
#if OS_CRITICAL_METHOD == 3u
OS_CPU_SR cpu_sr = 0u; /* Storage for CPU status register */
#endif
/*$PAGE*/
#if OS_ARG_CHK_EN > 0u
if (oldprio >= OS_LOWEST_PRIO) {
if (oldprio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
if (newprio >= OS_LOWEST_PRIO) {
return (OS_ERR_PRIO_INVALID);
}
#endif
OS_ENTER_CRITICAL();
if (OSTCBPrioTbl[newprio] != (OS_TCB *)0) { /* New priority must not already exist */
OS_EXIT_CRITICAL();
return (OS_ERR_PRIO_EXIST);
}
if (oldprio == OS_PRIO_SELF) { /* See if changing self */
oldprio = OSTCBCur->OSTCBPrio; /* Yes, get priority */
}
ptcb = OSTCBPrioTbl[oldprio];
if (ptcb == (OS_TCB *)0) { /* Does task to change exist? */
OS_EXIT_CRITICAL(); /* No, can't change its priority! */
return (OS_ERR_PRIO);
}
if (ptcb == OS_TCB_RESERVED) { /* Is task assigned to Mutex */
OS_EXIT_CRITICAL(); /* No, can't change its priority! */
return (OS_ERR_TASK_NOT_EXIST);
}
#if OS_LOWEST_PRIO <= 63u
y_new = (INT8U)(newprio >> 3u); /* Yes, compute new TCB fields */
x_new = (INT8U)(newprio & 0x07u);
#else
y_new = (INT8U)((INT8U)(newprio >> 4u) & 0x0Fu);
x_new = (INT8U)(newprio & 0x0Fu);
#endif
bity_new = (OS_PRIO)(1uL << y_new);
bitx_new = (OS_PRIO)(1uL << x_new);
OSTCBPrioTbl[oldprio] = (OS_TCB *)0; /* Remove TCB from old priority */
OSTCBPrioTbl[newprio] = ptcb; /* Place pointer to TCB @ new priority */
y_old = ptcb->OSTCBY;
bity_old = ptcb->OSTCBBitY;
bitx_old = ptcb->OSTCBBitX;
if ((OSRdyTbl[y_old] & bitx_old) != 0u) { /* If task is ready make it not */
OSRdyTbl[y_old] &= (OS_PRIO)~bitx_old;
if (OSRdyTbl[y_old] == 0u) {
OSRdyGrp &= (OS_PRIO)~bity_old;
}
OSRdyGrp |= bity_new; /* Make new priority ready to run */
OSRdyTbl[y_new] |= bitx_new;
}
#if (OS_EVENT_EN)
pevent = ptcb->OSTCBEventPtr;
if (pevent != (OS_EVENT *)0) {
pevent->OSEventTbl[y_old] &= (OS_PRIO)~bitx_old; /* Remove old task prio from wait list */
if (pevent->OSEventTbl[y_old] == 0u) {
pevent->OSEventGrp &= (OS_PRIO)~bity_old;
}
pevent->OSEventGrp |= bity_new; /* Add new task prio to wait list */
pevent->OSEventTbl[y_new] |= bitx_new;
}
#if (OS_EVENT_MULTI_EN > 0u)
if (ptcb->OSTCBEventMultiPtr != (OS_EVENT **)0) {
pevents = ptcb->OSTCBEventMultiPtr;
pevent = *pevents;
while (pevent != (OS_EVENT *)0) {
pevent->OSEventTbl[y_old] &= (OS_PRIO)~bitx_old; /* Remove old task prio from wait lists */
if (pevent->OSEventTbl[y_old] == 0u) {
pevent->OSEventGrp &= (OS_PRIO)~bity_old;
}
pevent->OSEventGrp |= bity_new; /* Add new task prio to wait lists */
pevent->OSEventTbl[y_new] |= bitx_new;
pevents++;
pevent = *pevents;
}
}
#endif
#endif
ptcb->OSTCBPrio = newprio; /* Set new task priority */
ptcb->OSTCBY = y_new;
ptcb->OSTCBX = x_new;
ptcb->OSTCBBitY = bity_new;
ptcb->OSTCBBitX = bitx_new;
OS_EXIT_CRITICAL();
if (OSRunning == OS_TRUE) {
OS_Sched(); /* Find new highest priority task */
}
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CREATE A TASK
*
* Description: This function is used to have uC/OS-II manage the execution of a task. Tasks can either
* be created prior to the start of multitasking or by a running task. A task cannot be
* created by an ISR.
*
* Arguments : task is a pointer to the task's code
*
* p_arg is a pointer to an optional data area which can be used to pass parameters to
* the task when the task first executes. Where the task is concerned it thinks
* it was invoked and passed the argument 'p_arg' as follows:
*
* void Task (void *p_arg)
* {
* for (;;) {
* Task code;
* }
* }
*
* ptos is a pointer to the task's top of stack. If the configuration constant
* OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high
* memory to low memory). 'pstk' will thus point to the highest (valid) memory
* location of the stack. If OS_STK_GROWTH is set to 0, 'pstk' will point to the
* lowest memory location of the stack and the stack will grow with increasing
* memory locations.
*
* prio is the task's priority. A unique priority MUST be assigned to each task and the
* lower the number, the higher the priority.
*
* Returns : OS_ERR_NONE if the function was successful.
* OS_ERR_PRIO_EXIST if the task priority already exist
* (each task MUST have a unique priority).
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum
* allowed (i.e. >= OS_LOWEST_PRIO)
* OS_ERR_TASK_CREATE_ISR if you tried to create a task from an ISR.
* OS_ERR_ILLEGAL_CREATE_RUN_TIME if you tried to create a task after safety critical
* operation started.
*********************************************************************************************************
*/
#if OS_TASK_CREATE_EN > 0u
INT8U OSTaskCreate (void (*task)(void *p_arg),
void *p_arg,
OS_STK *ptos,
INT8U prio)
{
OS_STK *psp;
INT8U err;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (OS_ERR_ILLEGAL_CREATE_RUN_TIME);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Make sure priority is within allowable range */
return (OS_ERR_PRIO_INVALID);
}
#endif
OS_ENTER_CRITICAL();
if (OSIntNesting > 0u) { /* Make sure we don't create the task from within an ISR */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_CREATE_ISR);
}
if (OSTCBPrioTbl[prio] == (OS_TCB *)0) { /* Make sure task doesn't already exist at this priority */
OSTCBPrioTbl[prio] = OS_TCB_RESERVED;/* Reserve the priority to prevent others from doing ... */
/* ... the same thing until task is created. */
OS_EXIT_CRITICAL();
psp = OSTaskStkInit(task, p_arg, ptos, 0u); /* Initialize the task's stack */
err = OS_TCBInit(prio, psp, (OS_STK *)0, 0u, 0u, (void *)0, 0u);
if (err == OS_ERR_NONE) {
if (OSRunning == OS_TRUE) { /* Find highest priority task if multitasking has started */
OS_Sched();
}
} else {
OS_ENTER_CRITICAL();
OSTCBPrioTbl[prio] = (OS_TCB *)0;/* Make this priority available to others */
OS_EXIT_CRITICAL();
}
return (err);
}
OS_EXIT_CRITICAL();
return (OS_ERR_PRIO_EXIST);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CREATE A TASK (Extended Version)
*
* Description: This function is used to have uC/OS-II manage the execution of a task. Tasks can either
* be created prior to the start of multitasking or by a running task. A task cannot be
* created by an ISR. This function is similar to OSTaskCreate() except that it allows
* additional information about a task to be specified.
*
* Arguments : task is a pointer to the task's code
*
* p_arg is a pointer to an optional data area which can be used to pass parameters to
* the task when the task first executes. Where the task is concerned it thinks
* it was invoked and passed the argument 'p_arg' as follows:
*
* void Task (void *p_arg)
* {
* for (;;) {
* Task code;
* }
* }
*
* ptos is a pointer to the task's top of stack. If the configuration constant
* OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high
* memory to low memory). 'ptos' will thus point to the highest (valid) memory
* location of the stack. If OS_STK_GROWTH is set to 0, 'ptos' will point to the
* lowest memory location of the stack and the stack will grow with increasing
* memory locations. 'ptos' MUST point to a valid 'free' data item.
*
* prio is the task's priority. A unique priority MUST be assigned to each task and the
* lower the number, the higher the priority.
*
* id is the task's ID (0..65535)
*
* pbos is a pointer to the task's bottom of stack. If the configuration constant
* OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high
* memory to low memory). 'pbos' will thus point to the LOWEST (valid) memory
* location of the stack. If OS_STK_GROWTH is set to 0, 'pbos' will point to the
* HIGHEST memory location of the stack and the stack will grow with increasing
* memory locations. 'pbos' MUST point to a valid 'free' data item.
*
* stk_size is the size of the stack in number of elements. If OS_STK is set to INT8U,
* 'stk_size' corresponds to the number of bytes available. If OS_STK is set to
* INT16U, 'stk_size' contains the number of 16-bit entries available. Finally, if
* OS_STK is set to INT32U, 'stk_size' contains the number of 32-bit entries
* available on the stack.
*
* pext is a pointer to a user supplied memory location which is used as a TCB extension.
* For example, this user memory can hold the contents of floating-point registers
* during a context switch, the time each task takes to execute, the number of times
* the task has been switched-in, etc.
*
* opt contains additional information (or options) about the behavior of the task. The
* LOWER 8-bits are reserved by uC/OS-II while the upper 8 bits can be application
* specific. See OS_TASK_OPT_??? in uCOS-II.H. Current choices are:
*
* OS_TASK_OPT_STK_CHK Stack checking to be allowed for the task
* OS_TASK_OPT_STK_CLR Clear the stack when the task is created
* OS_TASK_OPT_SAVE_FP If the CPU has floating-point registers, save them
* during a context switch.
*
* Returns : OS_ERR_NONE if the function was successful.
* OS_ERR_PRIO_EXIST if the task priority already exist
* (each task MUST have a unique priority).
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum
* allowed (i.e. > OS_LOWEST_PRIO)
* OS_ERR_TASK_CREATE_ISR if you tried to create a task from an ISR.
* OS_ERR_ILLEGAL_CREATE_RUN_TIME if you tried to create a task after safety critical
* operation started.
*********************************************************************************************************
*/
/*$PAGE*/
#if OS_TASK_CREATE_EXT_EN > 0u
INT8U OSTaskCreateExt (void (*task)(void *p_arg),
void *p_arg,
OS_STK *ptos,
INT8U prio,
INT16U id,
OS_STK *pbos,
INT32U stk_size,
void *pext,
INT16U opt)
{
OS_STK *psp;
INT8U err;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL_IEC61508
if (OSSafetyCriticalStartFlag == OS_TRUE) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (OS_ERR_ILLEGAL_CREATE_RUN_TIME);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Make sure priority is within allowable range */
return (OS_ERR_PRIO_INVALID);
}
#endif
OS_ENTER_CRITICAL();
if (OSIntNesting > 0u) { /* Make sure we don't create the task from within an ISR */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_CREATE_ISR);
}
if (OSTCBPrioTbl[prio] == (OS_TCB *)0) { /* Make sure task doesn't already exist at this priority */
OSTCBPrioTbl[prio] = OS_TCB_RESERVED;/* Reserve the priority to prevent others from doing ... */
/* ... the same thing until task is created. */
OS_EXIT_CRITICAL();
#if (OS_TASK_STAT_STK_CHK_EN > 0u)
OS_TaskStkClr(pbos, stk_size, opt); /* Clear the task stack (if needed) */
#endif
psp = OSTaskStkInit(task, p_arg, ptos, opt); /* Initialize the task's stack */
err = OS_TCBInit(prio, psp, pbos, id, stk_size, pext, opt);
if (err == OS_ERR_NONE) {
if (OSRunning == OS_TRUE) { /* Find HPT if multitasking has started */
OS_Sched();
}
} else {
OS_ENTER_CRITICAL();
OSTCBPrioTbl[prio] = (OS_TCB *)0; /* Make this priority avail. to others */
OS_EXIT_CRITICAL();
}
return (err);
}
OS_EXIT_CRITICAL();
return (OS_ERR_PRIO_EXIST);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* DELETE A TASK
*
* Description: This function allows you to delete a task. The calling task can delete itself by
* its own priority number. The deleted task is returned to the dormant state and can be
* re-activated by creating the deleted task again.
*
* Arguments : prio is the priority of the task to delete. Note that you can explicitly delete
* the current task without knowing its priority level by setting 'prio' to
* OS_PRIO_SELF.
*
* Returns : OS_ERR_NONE if the call is successful
* OS_ERR_TASK_DEL_IDLE if you attempted to delete uC/OS-II's idle task
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
* OS_ERR_TASK_DEL if the task is assigned to a Mutex PIP.
* OS_ERR_TASK_NOT_EXIST if the task you want to delete does not exist.
* OS_ERR_TASK_DEL_ISR if you tried to delete a task from an ISR
*
* Notes : 1) To reduce interrupt latency, OSTaskDel() 'disables' the task:
* a) by making it not ready
* b) by removing it from any wait lists
* c) by preventing OSTimeTick() from making the task ready to run.
* The task can then be 'unlinked' from the miscellaneous structures in uC/OS-II.
* 2) The function OS_Dummy() is called after OS_EXIT_CRITICAL() because, on most processors,
* the next instruction following the enable interrupt instruction is ignored.
* 3) An ISR cannot delete a task.
* 4) The lock nesting counter is incremented because, for a brief instant, if the current
* task is being deleted, the current task would not be able to be rescheduled because it
* is removed from the ready list. Incrementing the nesting counter prevents another task
* from being schedule. This means that an ISR would return to the current task which is
* being deleted. The rest of the deletion would thus be able to be completed.
*********************************************************************************************************
*/
#if OS_TASK_DEL_EN > 0u
INT8U OSTaskDel (INT8U prio)
{
#if (OS_FLAG_EN > 0u) && (OS_MAX_FLAGS > 0u)
OS_FLAG_NODE *pnode;
#endif
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
if (OSIntNesting > 0u) { /* See if trying to delete from ISR */
return (OS_ERR_TASK_DEL_ISR);
}
if (prio == OS_TASK_IDLE_PRIO) { /* Not allowed to delete idle task */
return (OS_ERR_TASK_DEL_IDLE);
}
#if OS_ARG_CHK_EN > 0u
if (prio >= OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
#endif
/*$PAGE*/
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if requesting to delete self */
prio = OSTCBCur->OSTCBPrio; /* Set priority to delete to current */
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Task to delete must exist */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
if (ptcb == OS_TCB_RESERVED) { /* Must not be assigned to Mutex */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_DEL);
}
OSRdyTbl[ptcb->OSTCBY] &= (OS_PRIO)~ptcb->OSTCBBitX;
if (OSRdyTbl[ptcb->OSTCBY] == 0u) { /* Make task not ready */
OSRdyGrp &= (OS_PRIO)~ptcb->OSTCBBitY;
}
#if (OS_EVENT_EN)
if (ptcb->OSTCBEventPtr != (OS_EVENT *)0) {
OS_EventTaskRemove(ptcb, ptcb->OSTCBEventPtr); /* Remove this task from any event wait list */
}
#if (OS_EVENT_MULTI_EN > 0u)
if (ptcb->OSTCBEventMultiPtr != (OS_EVENT **)0) { /* Remove this task from any events' wait lists*/
OS_EventTaskRemoveMulti(ptcb, ptcb->OSTCBEventMultiPtr);
}
#endif
#endif
#if (OS_FLAG_EN > 0u) && (OS_MAX_FLAGS > 0u)
pnode = ptcb->OSTCBFlagNode;
if (pnode != (OS_FLAG_NODE *)0) { /* If task is waiting on event flag */
OS_FlagUnlink(pnode); /* Remove from wait list */
}
#endif
ptcb->OSTCBDly = 0u; /* Prevent OSTimeTick() from updating */
ptcb->OSTCBStat = OS_STAT_RDY; /* Prevent task from being resumed */
ptcb->OSTCBStatPend = OS_STAT_PEND_OK;
if (OSLockNesting < 255u) { /* Make sure we don't context switch */
OSLockNesting++;
}
OS_EXIT_CRITICAL(); /* Enabling INT. ignores next instruc. */
OS_Dummy(); /* ... Dummy ensures that INTs will be */
OS_ENTER_CRITICAL(); /* ... disabled HERE! */
if (OSLockNesting > 0u) { /* Remove context switch lock */
OSLockNesting--;
}
OSTaskDelHook(ptcb); /* Call user defined hook */
#if OS_TASK_CREATE_EXT_EN > 0u
#if defined(OS_TLS_TBL_SIZE) && (OS_TLS_TBL_SIZE > 0u)
OS_TLS_TaskDel(ptcb); /* Call TLS hook */
#endif
#endif
OSTaskCtr--; /* One less task being managed */
OSTCBPrioTbl[prio] = (OS_TCB *)0; /* Clear old priority entry */
if (ptcb->OSTCBPrev == (OS_TCB *)0) { /* Remove from TCB chain */
ptcb->OSTCBNext->OSTCBPrev = (OS_TCB *)0;
OSTCBList = ptcb->OSTCBNext;
} else {
ptcb->OSTCBPrev->OSTCBNext = ptcb->OSTCBNext;
ptcb->OSTCBNext->OSTCBPrev = ptcb->OSTCBPrev;
}
ptcb->OSTCBNext = OSTCBFreeList; /* Return TCB to free TCB list */
OSTCBFreeList = ptcb;
#if OS_TASK_NAME_EN > 0u
ptcb->OSTCBTaskName = (INT8U *)(void *)"?";
#endif
OS_EXIT_CRITICAL();
if (OSRunning == OS_TRUE) {
OS_Sched(); /* Find new highest priority task */
}
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* REQUEST THAT A TASK DELETE ITSELF
*
* Description: This function is used to:
* a) notify a task to delete itself.
* b) to see if a task requested that the current task delete itself.
* This function is a little tricky to understand. Basically, you have a task that needs
* to be deleted however, this task has resources that it has allocated (memory buffers,
* semaphores, mailboxes, queues etc.). The task cannot be deleted otherwise these
* resources would not be freed. The requesting task calls OSTaskDelReq() to indicate that
* the task needs to be deleted. Deleting of the task is however, deferred to the task to
* be deleted. For example, suppose that task #10 needs to be deleted. The requesting task
* example, task #5, would call OSTaskDelReq(10). When task #10 gets to execute, it calls
* this function by specifying OS_PRIO_SELF and monitors the returned value. If the return
* value is OS_ERR_TASK_DEL_REQ, another task requested a task delete. Task #10 would look like
* this:
*
* void Task(void *p_arg)
* {
* .
* .
* while (1) {
* OSTimeDly(1);
* if (OSTaskDelReq(OS_PRIO_SELF) == OS_ERR_TASK_DEL_REQ) {
* Release any owned resources;
* De-allocate any dynamic memory;
* OSTaskDel(OS_PRIO_SELF);
* }
* }
* }
*
* Arguments : prio is the priority of the task to request the delete from
*
* Returns : OS_ERR_NONE if the task exist and the request has been registered
* OS_ERR_TASK_NOT_EXIST if the task has been deleted. This allows the caller to know whether
* the request has been executed.
* OS_ERR_TASK_DEL if the task is assigned to a Mutex.
* OS_ERR_TASK_DEL_IDLE if you requested to delete uC/OS-II's idle task
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
* OS_ERR_TASK_DEL_REQ if a task (possibly another task) requested that the running task be
* deleted.
*********************************************************************************************************
*/
/*$PAGE*/
#if OS_TASK_DEL_EN > 0u
INT8U OSTaskDelReq (INT8U prio)
{
INT8U stat;
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
if (prio == OS_TASK_IDLE_PRIO) { /* Not allowed to delete idle task */
return (OS_ERR_TASK_DEL_IDLE);
}
#if OS_ARG_CHK_EN > 0u
if (prio >= OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
#endif
if (prio == OS_PRIO_SELF) { /* See if a task is requesting to ... */
OS_ENTER_CRITICAL(); /* ... this task to delete itself */
stat = OSTCBCur->OSTCBDelReq; /* Return request status to caller */
OS_EXIT_CRITICAL();
return (stat);
}
OS_ENTER_CRITICAL();
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Task to delete must exist */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST); /* Task must already be deleted */
}
if (ptcb == OS_TCB_RESERVED) { /* Must NOT be assigned to a Mutex */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_DEL);
}
ptcb->OSTCBDelReq = OS_ERR_TASK_DEL_REQ; /* Set flag indicating task to be DEL. */
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* GET THE NAME OF A TASK
*
* Description: This function is called to obtain the name of a task.
*
* Arguments : prio is the priority of the task that you want to obtain the name from.
*
* pname is a pointer to a pointer to an ASCII string that will receive the name of the task.
*
* perr is a pointer to an error code that can contain one of the following values:
*
* OS_ERR_NONE if the requested task is resumed
* OS_ERR_TASK_NOT_EXIST if the task has not been created or is assigned to a Mutex
* OS_ERR_PRIO_INVALID if you specified an invalid priority:
* A higher value than the idle task or not OS_PRIO_SELF.
* OS_ERR_PNAME_NULL You passed a NULL pointer for 'pname'
* OS_ERR_NAME_GET_ISR You called this function from an ISR
*
*
* Returns : The length of the string or 0 if the task does not exist.
*********************************************************************************************************
*/
#if OS_TASK_NAME_EN > 0u
INT8U OSTaskNameGet (INT8U prio,
INT8U **pname,
INT8U *perr)
{
OS_TCB *ptcb;
INT8U len;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
*perr = OS_ERR_PRIO_INVALID; /* No */
return (0u);
}
}
if (pname == (INT8U **)0) { /* Is 'pname' a NULL pointer? */
*perr = OS_ERR_PNAME_NULL; /* Yes */
return (0u);
}
#endif
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
*perr = OS_ERR_NAME_GET_ISR;
return (0u);
}
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if caller desires it's own name */
prio = OSTCBCur->OSTCBPrio;
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Does task exist? */
OS_EXIT_CRITICAL(); /* No */
*perr = OS_ERR_TASK_NOT_EXIST;
return (0u);
}
if (ptcb == OS_TCB_RESERVED) { /* Task assigned to a Mutex? */
OS_EXIT_CRITICAL(); /* Yes */
*perr = OS_ERR_TASK_NOT_EXIST;
return (0u);
}
*pname = ptcb->OSTCBTaskName;
len = OS_StrLen(*pname);
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (len);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* ASSIGN A NAME TO A TASK
*
* Description: This function is used to set the name of a task.
*
* Arguments : prio is the priority of the task that you want the assign a name to.
*
* pname is a pointer to an ASCII string that contains the name of the task.
*
* perr is a pointer to an error code that can contain one of the following values:
*
* OS_ERR_NONE if the requested task is resumed
* OS_ERR_TASK_NOT_EXIST if the task has not been created or is assigned to a Mutex
* OS_ERR_PNAME_NULL You passed a NULL pointer for 'pname'
* OS_ERR_PRIO_INVALID if you specified an invalid priority:
* A higher value than the idle task or not OS_PRIO_SELF.
* OS_ERR_NAME_SET_ISR if you called this function from an ISR
*
* Returns : None
*********************************************************************************************************
*/
#if OS_TASK_NAME_EN > 0u
void OSTaskNameSet (INT8U prio,
INT8U *pname,
INT8U *perr)
{
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
*perr = OS_ERR_PRIO_INVALID; /* No */
return;
}
}
if (pname == (INT8U *)0) { /* Is 'pname' a NULL pointer? */
*perr = OS_ERR_PNAME_NULL; /* Yes */
return;
}
#endif
if (OSIntNesting > 0u) { /* See if trying to call from an ISR */
*perr = OS_ERR_NAME_SET_ISR;
return;
}
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if caller desires to set it's own name */
prio = OSTCBCur->OSTCBPrio;
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Does task exist? */
OS_EXIT_CRITICAL(); /* No */
*perr = OS_ERR_TASK_NOT_EXIST;
return;
}
if (ptcb == OS_TCB_RESERVED) { /* Task assigned to a Mutex? */
OS_EXIT_CRITICAL(); /* Yes */
*perr = OS_ERR_TASK_NOT_EXIST;
return;
}
ptcb->OSTCBTaskName = pname;
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* RESUME A SUSPENDED TASK
*
* Description: This function is called to resume a previously suspended task. This is the only call that
* will remove an explicit task suspension.
*
* Arguments : prio is the priority of the task to resume.
*
* Returns : OS_ERR_NONE if the requested task is resumed
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO)
* OS_ERR_TASK_RESUME_PRIO if the task to resume does not exist
* OS_ERR_TASK_NOT_EXIST if the task is assigned to a Mutex PIP
* OS_ERR_TASK_NOT_SUSPENDED if the task to resume has not been suspended
*********************************************************************************************************
*/
#if OS_TASK_SUSPEND_EN > 0u
INT8U OSTaskResume (INT8U prio)
{
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (prio >= OS_LOWEST_PRIO) { /* Make sure task priority is valid */
return (OS_ERR_PRIO_INVALID);
}
#endif
OS_ENTER_CRITICAL();
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Task to suspend must exist */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_RESUME_PRIO);
}
if (ptcb == OS_TCB_RESERVED) { /* See if assigned to Mutex */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
if ((ptcb->OSTCBStat & OS_STAT_SUSPEND) != OS_STAT_RDY) { /* Task must be suspended */
ptcb->OSTCBStat &= (INT8U)~(INT8U)OS_STAT_SUSPEND; /* Remove suspension */
if (ptcb->OSTCBStat == OS_STAT_RDY) { /* See if task is now ready */
if (ptcb->OSTCBDly == 0u) {
OSRdyGrp |= ptcb->OSTCBBitY; /* Yes, Make task ready to run */
OSRdyTbl[ptcb->OSTCBY] |= ptcb->OSTCBBitX;
OS_EXIT_CRITICAL();
if (OSRunning == OS_TRUE) {
OS_Sched(); /* Find new highest priority task */
}
} else {
OS_EXIT_CRITICAL();
}
} else { /* Must be pending on event */
OS_EXIT_CRITICAL();
}
return (OS_ERR_NONE);
}
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_SUSPENDED);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* STACK CHECKING
*
* Description: This function is called to check the amount of free memory left on the specified task's
* stack.
*
* Arguments : prio is the task priority
*
* p_stk_data is a pointer to a data structure of type OS_STK_DATA.
*
* Returns : OS_ERR_NONE upon success
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. > OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
* OS_ERR_TASK_NOT_EXIST if the desired task has not been created or is assigned to a Mutex PIP
* OS_ERR_TASK_OPT if you did NOT specified OS_TASK_OPT_STK_CHK when the task was created
* OS_ERR_PDATA_NULL if 'p_stk_data' is a NULL pointer
*********************************************************************************************************
*/
#if (OS_TASK_STAT_STK_CHK_EN > 0u) && (OS_TASK_CREATE_EXT_EN > 0u)
INT8U OSTaskStkChk (INT8U prio,
OS_STK_DATA *p_stk_data)
{
OS_TCB *ptcb;
OS_STK *pchk;
INT32U nfree;
INT32U size;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Make sure task priority is valid */
if (prio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
if (p_stk_data == (OS_STK_DATA *)0) { /* Validate 'p_stk_data' */
return (OS_ERR_PDATA_NULL);
}
#endif
p_stk_data->OSFree = 0u; /* Assume failure, set to 0 size */
p_stk_data->OSUsed = 0u;
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if check for SELF */
prio = OSTCBCur->OSTCBPrio;
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Make sure task exist */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
if (ptcb == OS_TCB_RESERVED) {
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
if ((ptcb->OSTCBOpt & OS_TASK_OPT_STK_CHK) == 0u) { /* Make sure stack checking option is set */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_OPT);
}
nfree = 0u;
size = ptcb->OSTCBStkSize;
pchk = ptcb->OSTCBStkBottom;
OS_EXIT_CRITICAL();
#if OS_STK_GROWTH == 1u
while (*pchk++ == (OS_STK)0) { /* Compute the number of zero entries on the stk */
nfree++;
}
#else
while (*pchk-- == (OS_STK)0) {
nfree++;
}
#endif
p_stk_data->OSFree = nfree; /* Store number of free entries on the stk */
p_stk_data->OSUsed = size - nfree; /* Compute number of entries used on the stk */
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* SUSPEND A TASK
*
* Description: This function is called to suspend a task. The task can be the calling task if the
* priority passed to OSTaskSuspend() is the priority of the calling task or OS_PRIO_SELF.
*
* Arguments : prio is the priority of the task to suspend. If you specify OS_PRIO_SELF, the
* calling task will suspend itself and rescheduling will occur.
*
* Returns : OS_ERR_NONE if the requested task is suspended
* OS_ERR_TASK_SUSPEND_IDLE if you attempted to suspend the idle task which is not allowed.
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. >= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
* OS_ERR_TASK_SUSPEND_PRIO if the task to suspend does not exist
* OS_ERR_TASK_NOT_EXITS if the task is assigned to a Mutex PIP
*
* Note : You should use this function with great care. If you suspend a task that is waiting for
* an event (i.e. a message, a semaphore, a queue ...) you will prevent this task from
* running when the event arrives.
*********************************************************************************************************
*/
#if OS_TASK_SUSPEND_EN > 0u
INT8U OSTaskSuspend (INT8U prio)
{
BOOLEAN self;
OS_TCB *ptcb;
INT8U y;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (prio == OS_TASK_IDLE_PRIO) { /* Not allowed to suspend idle task */
return (OS_ERR_TASK_SUSPEND_IDLE);
}
if (prio >= OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
#endif
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if suspend SELF */
prio = OSTCBCur->OSTCBPrio;
self = OS_TRUE;
} else if (prio == OSTCBCur->OSTCBPrio) { /* See if suspending self */
self = OS_TRUE;
} else {
self = OS_FALSE; /* No suspending another task */
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Task to suspend must exist */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_SUSPEND_PRIO);
}
if (ptcb == OS_TCB_RESERVED) { /* See if assigned to Mutex */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
y = ptcb->OSTCBY;
OSRdyTbl[y] &= (OS_PRIO)~ptcb->OSTCBBitX; /* Make task not ready */
if (OSRdyTbl[y] == 0u) {
OSRdyGrp &= (OS_PRIO)~ptcb->OSTCBBitY;
}
ptcb->OSTCBStat |= OS_STAT_SUSPEND; /* Status of task is 'SUSPENDED' */
OS_EXIT_CRITICAL();
if (self == OS_TRUE) { /* Context switch only if SELF */
OS_Sched(); /* Find new highest priority task */
}
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* QUERY A TASK
*
* Description: This function is called to obtain a copy of the desired task's TCB.
*
* Arguments : prio is the priority of the task to obtain information from.
*
* p_task_data is a pointer to where the desired task's OS_TCB will be stored.
*
* Returns : OS_ERR_NONE if the requested task is suspended
* OS_ERR_PRIO_INVALID if the priority you specify is higher that the maximum allowed
* (i.e. > OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
* OS_ERR_PRIO if the desired task has not been created
* OS_ERR_TASK_NOT_EXIST if the task is assigned to a Mutex PIP
* OS_ERR_PDATA_NULL if 'p_task_data' is a NULL pointer
*********************************************************************************************************
*/
#if OS_TASK_QUERY_EN > 0u
INT8U OSTaskQuery (INT8U prio,
OS_TCB *p_task_data)
{
OS_TCB *ptcb;
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
#if OS_ARG_CHK_EN > 0u
if (prio > OS_LOWEST_PRIO) { /* Task priority valid ? */
if (prio != OS_PRIO_SELF) {
return (OS_ERR_PRIO_INVALID);
}
}
if (p_task_data == (OS_TCB *)0) { /* Validate 'p_task_data' */
return (OS_ERR_PDATA_NULL);
}
#endif
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if suspend SELF */
prio = OSTCBCur->OSTCBPrio;
}
ptcb = OSTCBPrioTbl[prio];
if (ptcb == (OS_TCB *)0) { /* Task to query must exist */
OS_EXIT_CRITICAL();
return (OS_ERR_PRIO);
}
if (ptcb == OS_TCB_RESERVED) { /* Task to query must not be assigned to a Mutex */
OS_EXIT_CRITICAL();
return (OS_ERR_TASK_NOT_EXIST);
}
/* Copy TCB into user storage area */
OS_MemCopy((INT8U *)p_task_data, (INT8U *)ptcb, sizeof(OS_TCB));
OS_EXIT_CRITICAL();
return (OS_ERR_NONE);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* GET THE CURRENT VALUE OF A TASK REGISTER
*
* Description: This function is called to obtain the current value of a task register. Task registers
* are application specific and can be used to store task specific values such as 'error
* numbers' (i.e. errno), statistics, etc. Each task register can hold a 32-bit value.
*
* Arguments : prio is the priority of the task you want to get the task register from. If you
* specify OS_PRIO_SELF then the task register of the current task will be obtained.
*
* id is the 'id' of the desired task register. Note that the 'id' must be less
* than OS_TASK_REG_TBL_SIZE
*
* perr is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE if the call was successful
* OS_ERR_PRIO_INVALID if you specified an invalid priority
* OS_ERR_ID_INVALID if the 'id' is not between 0 and OS_TASK_REG_TBL_SIZE-1
*
* Returns : The current value of the task's register or 0 if an error is detected.
*
* Note(s) : The maximum number of task variables is 254
*********************************************************************************************************
*/
#if OS_TASK_REG_TBL_SIZE > 0u
INT32U OSTaskRegGet (INT8U prio,
INT8U id,
INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
INT32U value;
OS_TCB *ptcb;
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return (0u);
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio >= OS_LOWEST_PRIO) {
if (prio != OS_PRIO_SELF) {
*perr = OS_ERR_PRIO_INVALID;
return (0u);
}
}
if (id >= OS_TASK_REG_TBL_SIZE) {
*perr = OS_ERR_ID_INVALID;
return (0u);
}
#endif
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if need to get register from current task */
ptcb = OSTCBCur;
} else {
ptcb = OSTCBPrioTbl[prio];
}
value = ptcb->OSTCBRegTbl[id];
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (value);
}
#endif
/*$PAGE*/
/*
************************************************************************************************************************
* ALLOCATE THE NEXT AVAILABLE TASK REGISTER ID
*
* Description: This function is called to obtain a task register ID. This function thus allows task registers IDs to be
* allocated dynamically instead of statically.
*
* Arguments : p_err is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE if the call was successful
* OS_ERR_NO_MORE_ID_AVAIL if you are attempting to assign more task register IDs than you
* have available through OS_TASK_REG_TBL_SIZE.
*
* Returns : The next available task register 'id' or OS_TASK_REG_TBL_SIZE if an error is detected.
************************************************************************************************************************
*/
#if OS_TASK_REG_TBL_SIZE > 0u
INT8U OSTaskRegGetID (INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
INT8U id;
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return ((INT8U)OS_TASK_REG_TBL_SIZE);
}
#endif
OS_ENTER_CRITICAL();
if (OSTaskRegNextAvailID >= OS_TASK_REG_TBL_SIZE) { /* See if we exceeded the number of IDs available */
*perr = OS_ERR_NO_MORE_ID_AVAIL; /* Yes, cannot allocate more task register IDs */
OS_EXIT_CRITICAL();
return ((INT8U)OS_TASK_REG_TBL_SIZE);
}
id = OSTaskRegNextAvailID; /* Assign the next available ID */
OSTaskRegNextAvailID++; /* Increment available ID for next request */
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
return (id);
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* SET THE CURRENT VALUE OF A TASK VARIABLE
*
* Description: This function is called to change the current value of a task register. Task registers
* are application specific and can be used to store task specific values such as 'error
* numbers' (i.e. errno), statistics, etc. Each task register can hold a 32-bit value.
*
* Arguments : prio is the priority of the task you want to set the task register for. If you
* specify OS_PRIO_SELF then the task register of the current task will be obtained.
*
* id is the 'id' of the desired task register. Note that the 'id' must be less
* than OS_TASK_REG_TBL_SIZE
*
* value is the desired value for the task register.
*
* perr is a pointer to a variable that will hold an error code related to this call.
*
* OS_ERR_NONE if the call was successful
* OS_ERR_PRIO_INVALID if you specified an invalid priority
* OS_ERR_ID_INVALID if the 'id' is not between 0 and OS_TASK_REG_TBL_SIZE-1
*
* Returns : The current value of the task's variable or 0 if an error is detected.
*
* Note(s) : The maximum number of task variables is 254
*********************************************************************************************************
*/
#if OS_TASK_REG_TBL_SIZE > 0u
void OSTaskRegSet (INT8U prio,
INT8U id,
INT32U value,
INT8U *perr)
{
#if OS_CRITICAL_METHOD == 3u /* Allocate storage for CPU status register */
OS_CPU_SR cpu_sr = 0u;
#endif
OS_TCB *ptcb;
#ifdef OS_SAFETY_CRITICAL
if (perr == (INT8U *)0) {
OS_SAFETY_CRITICAL_EXCEPTION();
return;
}
#endif
#if OS_ARG_CHK_EN > 0u
if (prio >= OS_LOWEST_PRIO) {
if (prio != OS_PRIO_SELF) {
*perr = OS_ERR_PRIO_INVALID;
return;
}
}
if (id >= OS_TASK_REG_TBL_SIZE) {
*perr = OS_ERR_ID_INVALID;
return;
}
#endif
OS_ENTER_CRITICAL();
if (prio == OS_PRIO_SELF) { /* See if need to get register from current task */
ptcb = OSTCBCur;
} else {
ptcb = OSTCBPrioTbl[prio];
}
ptcb->OSTCBRegTbl[id] = value;
OS_EXIT_CRITICAL();
*perr = OS_ERR_NONE;
}
#endif
/*$PAGE*/
/*
*********************************************************************************************************
* CATCH ACCIDENTAL TASK RETURN
*
* Description: This function is called if a task accidentally returns without deleting itself. In other
* words, a task should either be an infinite loop or delete itself if it's done.
*
* Arguments : none
*
* Returns : none
*
* Note(s) : This function is INTERNAL to uC/OS-II and your application should not call it.
*********************************************************************************************************
*/
void OS_TaskReturn (void)
{
OSTaskReturnHook(OSTCBCur); /* Call hook to let user decide on what to do */
#if OS_TASK_DEL_EN > 0u
(void)OSTaskDel(OS_PRIO_SELF); /* Delete task if it accidentally returns! */
#else
for (;;) {
OSTimeDly(OS_TICKS_PER_SEC);
}
#endif
}
/*$PAGE*/
/*
*********************************************************************************************************
* CLEAR TASK STACK
*
* Description: This function is used to clear the stack of a task (i.e. write all zeros)
*
* Arguments : pbos is a pointer to the task's bottom of stack. If the configuration constant
* OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high
* memory to low memory). 'pbos' will thus point to the lowest (valid) memory
* location of the stack. If OS_STK_GROWTH is set to 0, 'pbos' will point to the
* highest memory location of the stack and the stack will grow with increasing
* memory locations. 'pbos' MUST point to a valid 'free' data item.
*
* size is the number of 'stack elements' to clear.
*
* opt contains additional information (or options) about the behavior of the task. The
* LOWER 8-bits are reserved by uC/OS-II while the upper 8 bits can be application
* specific. See OS_TASK_OPT_??? in uCOS-II.H.
*
* Returns : none
*********************************************************************************************************
*/
#if (OS_TASK_STAT_STK_CHK_EN > 0u) && (OS_TASK_CREATE_EXT_EN > 0u)
void OS_TaskStkClr (OS_STK *pbos,
INT32U size,
INT16U opt)
{
if ((opt & OS_TASK_OPT_STK_CHK) != 0x0000u) { /* See if stack checking has been enabled */
if ((opt & OS_TASK_OPT_STK_CLR) != 0x0000u) { /* See if stack needs to be cleared */
#if OS_STK_GROWTH == 1u
while (size > 0u) { /* Stack grows from HIGH to LOW memory */
size--;
*pbos++ = (OS_STK)0; /* Clear from bottom of stack and up! */
}
#else
while (size > 0u) { /* Stack grows from LOW to HIGH memory */
size--;
*pbos-- = (OS_STK)0; /* Clear from bottom of stack and down */
}
#endif
}
}
}
#endif
~~~
uC/OS-II 函数之OSInit()
最后更新于：2022-04-01 11:42:31
获得更多资料欢迎进入[我的网站](http://rlovep.com/)或者 [csdn](http://blog.csdn.net/peace1213)或者[博客园](http://www.cnblogs.com/onepeace/)
> 对于有热心的小伙伴在[微博](http://weibo.com/u/2026326475/)上私信我，说我的[uC/OS-II 一些函数简介](http://blog.csdn.net/peace1213/article/details/47056651)篇幅有些过于长应该分开介绍。应小伙伴的要求，特此将文章分开进行讲解。本文主要介绍OSInit()初始化函数
## OSInit()主要作用
在uC/OS II的学习中，OSInit(OS_CORE.C )（函数原型位于）;是一个重要的函数，它在OS应用中的main（）函数中首先被调用，是OS运行的第一个函数,它完成各初始变量的初始化。
## 主要工作：完成下面的初始化；
~~~
OSInitHookBegin(); /* 调用用户特定的初始化代码（通过一个接口函数实现用户要求的插件式进入系统中）*/
OS_InitMisc(); /* 初始化变量*/
OS_InitRdyList(); /* 初始化就绪列表*/
OS_InitTCBList(); /* 初始化OS_TCB空闲列表*/
OS_InitEventList(); /* 初始化OS_EVENT空闲列表*/
OS_InitTaskIdle(); /*创建空闲任务*/
~~~
## 程序注释详解：
~~~
void OSInit (void)
{
#if OS_TASK_CREATE_EXT_EN > 0u
#if defined(OS_TLS_TBL_SIZE) && (OS_TLS_TBL_SIZE > 0u)
INT8U err;
#endif
#endif
OSInitHookBegin(); /* 调用用户特定的初始化代码（通过一个接口函数实现用户要求的插件式进入系统中）*/
OS_InitMisc(); /* 初始化变量*/ /* Initialize miscellaneous variables */
OS_InitRdyList(); /* 初始化就绪列表*/ /* Initialize the Ready List */
OS_InitTCBList(); /* 初始化OS_TCB空闲列表*/ /* Initialize the free list of OS_TCBs */
OS_InitEventList(); /* 初始化OS_EVENT空闲列表*/ /* Initialize the free list of OS_EVENTs */
#if (OS_FLAG_EN > 0u) && (OS_MAX_FLAGS > 0u)
OS_FlagInit(); /* 初始化事件标志结构*/ /* Initialize the event flag structures */
#endif
#if (OS_MEM_EN > 0u) && (OS_MAX_MEM_PART > 0u)
OS_MemInit(); /* 初始化内存管理器*/ /* Initialize the memory manager */
#endif
#if (OS_Q_EN > 0u) && (OS_MAX_QS > 0u)
OS_QInit(); /* 初始化消息队列结构*/ /* Initialize the message queue structures */
#endif
#if OS_TASK_CREATE_EXT_EN > 0u
#if defined(OS_TLS_TBL_SIZE) && (OS_TLS_TBL_SIZE > 0u)
OS_TLS_Init(&err); /* 创建任务前初始化TLS*/ /* Initialize TLS, before creating tasks */
if (err != OS_ERR_NONE) {
return;
}
#endif
#endif
OS_InitTaskIdle(); /* 创建空闲任务(无条件)Create the Idle Task */
#if OS_TASK_STAT_EN > 0u
OS_InitTaskStat(); /* 创建统计任务*/ /* Create the Statistic Task */
#endif
#if OS_TMR_EN > 0u
OSTmr_Init(); /* 初始化时间管理器*/ /* Initialize the Timer Manager */
#endif
OSInitHookEnd(); /*调用用户特定的初始化代码*/
#if OS_DEBUG_EN > 0u
OSDebugInit();
#endif
}
~~~
前言
最后更新于：2022-04-01 11:42:29
> 原文出处：[uC/OS-II函数介绍](http://blog.csdn.net/column/details/uc-os2.html)
作者：[peace1213](http://blog.csdn.net/peace1213)
**本系列文章经作者授权在看云整理发布，未经作者允许，请勿转载！**
# uC/OS-II函数介绍
> uC/OS-II的一些常用函数介绍，包括任务，时间，邮箱，信号量，消息队列，内存管理等相关的函数介绍。