UCOSIIAPI参考手册.docx
《UCOSIIAPI参考手册.docx》由会员分享，可在线阅读，更多相关《UCOSIIAPI参考手册.docx（69页珍藏版）》请在冰豆网上搜索。
UCOSIIAPI参考手册
UCOS-IIAPI参考手册
本章提供了μC/OS-Ⅱ的用户指南。
每一个用户可以调用的内核函数都按字母顺序加以说明，包括：
●函数的功能描述
●函数原型
●函数名称及源代码
●函数使用到的常量
●函数参数
●函数返回值
●特殊说明和注意点
OSInit（）
VoidOSInit（void）;
所属文件
调用者
开关量
OS_CORE.C
启动代码
无
OSinit（）初始化μC/OS-Ⅱ，对这个函数的调用必须在调用OSStart（）函数之前，而OSStart（）函数真正开始运行多任务。
参数
无
返回值
无
注意/警告
必须先于OSStart（）函数的调用
范例：
voidmain（void）
{
.
OSInit（）;/*初始化uC/OS-II*/
.
OSStart（）;/*启动多任务内核*/
}
OSIntEnter（）
VoidOSIntEnter（void）;
所属文件
调用者
开关量
OS_CORE.C
中断
无
OSIntEnter（）通知μC/OS-Ⅱ一个中断处理函数正在执行，这有助于μC/OS-Ⅱ掌握中断嵌套的情况。
OSIntEnter（）函数通常和OSIntExit（）函数联合使用。
参数
无
返回值
无
注意/警告
在任务级不能调用该函数。
如果系统使用的处理器能够执行自动的独立执行读取-修改-写入的操作，那么就可以直接递增中断嵌套层数（OSIntNesting），这样可以避免调用函数所带来的额外的开销。
范例一：
（Intel80x86的实模式,在大模式下编译，，realmode，largemodel）
ISRxPROCFAR
PUSHA;保存中断现场
PUSHES
PUSHDS
;
MOVAX,DGROUP;读入数据段
MOVDS,AX
;
CALLFARPTR_OSIntEnter;通知内核进入中断
.
.
POPDS;恢复中断现场
POPES
POPA
IRET;中断返回
ISRxENDP
范例二：
（Intel80x86的实模式,在大模式下编译，,realmode,largemodel）
ISRxPROCFAR
PUSHA;保存中断现场
PUSHES
PUSHDS
;
MOVAX,DGROUP;读入数据段
MOVDS,AX
;
INCBYTEPTR_OSIntNesting;通知内核进入中断
.
.
.
POPDS;恢复中断现场
POPES
POPA
IRET;中断返回
ISRxENDP
OSIntExit（）
VoidOSIntExit（void）;
所属文件
调用者
开关量
OS_CORE.C
中断
无
OSIntExit（）通知μC/OS-Ⅱ一个中断服务已执行完毕，这有助于μC/OS-Ⅱ掌握中断嵌套的情况。
通常OSIntExit（）和OSIntEnter（）联合使用。
当最后一层嵌套的中断执行完毕后，如果有更高优先级的任务准备就绪，μC/OS-Ⅱ会调用任务调度函数，在这种情况下，中断返回到更高优先级的任务而不是被中断了的任务。
参数
无
返回值
无
注意/警告
在任务级不能调用该函数。
并且即使没有调用OSIntEnter（）而是使用直接递增OSIntNesting的方法，也必须调用OSIntExit（）函数。
范例：
（Intel80x86的实模式,在大模式下编译，realmode,largemodel）
ISRxPROCFAR
PUSHA;保存中断现场
PUSHES
PUSHDS
.
.
CALLFARPTR_OSIntExit;通知内核进入中断
POPDS;恢复中断现场
POPES
POPA
IRET;中断返回
ISRxENDP
OSMboxAccept（）
Void*OSMboxAccept（OS_EVENT*pevent）;
所属文件
调用者
开关量
OS_MBOX.C
任务或中断
OS_MBOX_EN
OSMboxAccept（）函数查看指定的消息邮箱是否有需要的消息。
不同于OSMboxPend（）函数，如果没有需要的消息，OSMboxAccept（）函数并不挂起任务。
如果消息已经到达，该消息被传递到用户任务并且从消息邮箱中清除。
通常中断调用该函数，因为中断不允许挂起等待消息。
参数
pevent是指向需要查看的消息邮箱的指针。
当建立消息邮箱时，该指针返回到用户程序。
（参考OSMboxCreate（）函数）。
返回值
如果消息已经到达，返回指向该消息的指针；如果消息邮箱没有消息，返回空指针。
注意/警告
必须先建立消息邮箱，然后使用。
范例：
OS_EVENT*CommMbox;
voidTask（void*pdata）
{
void*msg;
pdata=pdata;
for（;;）{
msg=OSMboxAccept（CommMbox）;/*检查消息邮箱是否有消息*/
if（msg!
=（void*）0）{
./*处理消息*/
.
}else{
./*没有消息*/
.
}
.
.
}
}
OSMboxCreate（）
OS_EVENT*OSMboxCreate（void*msg）;
所属文件
调用者
开关量
OS_MBOX.C
任务或启动代码
OS_MBOX_EN
OSMboxCreate（）建立并初始化一个消息邮箱。
消息邮箱允许任务或中断向其他一个或几个任务发送消息。
参数
msg参数用来初始化建立的消息邮箱。
如果该指针不为空，建立的消息邮箱将含有消息。
返回值
指向分配给所建立的消息邮箱的事件控制块的指针。
如果没有可用的事件控制块，返回空指针。
注意/警告
必须先建立消息邮箱，然后使用。
范例：
OS_EVENT*CommMbox;
voidmain（void）
{
.
.
OSInit（）;/*初始化μC/OS-Ⅱ*/
.
.
CommMbox=OSMboxCreate（（void*）0）;/*建立消息邮箱*/
OSStart（）;/*启动多任务内核*/
}
OSMboxPend（）
Void*OSMboxPend（OS_EVNNT*pevent,INT16Utimeout,int8u*err）;
所属文件
调用者
开关量
OS_MBOX.C
任务
OS_MBOX_EN
OSMboxPend（）用于任务等待消息。
消息通过中断或另外的任务发送给需要的任务。
消息是一个以指针定义的变量，在不同的程序中消息的使用也可能不同。
如果调用OSMboxPend（）函数时消息邮箱已经存在需要的消息，那么该消息被返回给OSMboxPend（）的调用者，消息邮箱中清除该消息。
如果调用OSMboxPend（）函数时消息邮箱中没有需要的消息，OSMboxPend（）函数挂起当前任务直到得到需要的消息或超出定义等待超时的时间。
如果同时有多个任务等待同一个消息，μC/OS-Ⅱ默认最高优先级的任务取得消息并且任务恢复执行。
一个由OSTaskSuspend（）函数挂起的任务也可以接受消息，但这个任务将一直保持挂起状态直到通过调用OSTaskResume（）函数恢复任务的运行。
参数
pevent是指向即将接受消息的消息邮箱的指针。
该指针的值在建立该消息邮箱时可以得到。
（参考OSMboxCreate（）函数）。
Timeout允许一个任务在经过了指定数目的时钟节拍后还没有得到需要的消息时恢复运行。
如果该值为零表示任务将持续的等待消息。
最大的等待时间为65,535个时钟节拍。
这个时间长度并不是非常严格的，可能存在一个时钟节拍的误差，因为只有在一个时钟节拍结束后才会减少定义的等待超时时钟节拍。
Err是指向包含错误码的变量的指针。
OSMboxPend（）函数返回的错误码可能为下述几种：
●OS_NO_ERR：
消息被正确的接受。
●OS_TIMEOUT：
消息没有在指定的周期数内送到。
●OS_ERR_PEND_ISR：
从中断调用该函数。
虽然规定了不允许从中断调用该函数，但μC/OS-Ⅱ仍然包含了检测这种情况的功能。
●OS_ERR_EVENT_TYPE：
pevent不是指向消息邮箱的指针。
返回值
OSMboxPend（）函数返回接受的消息并将*err置为OS_NO_ERR。
如果没有在指定数目的时钟节拍内接受到需要的消息，OSMboxPend（）函数返回空指针并且将*err设置为OS_TIMEOUT。
注意/警告
必须先建立消息邮箱，然后使用。
不允许从中断调用该函数。
范例：
OS_EVENT*CommMbox;
voidCommTask（void*pdata）
{
INT8Uerr;
void*msg;
pdata=pdata;
for（;;）{
.
.
msg=OSMboxPend（CommMbox,10,&err）;
if（err==OS_NO_ERR）{
.
./*消息正确的接受*/
.
}else{
.
./*在指定时间内没有接受到消息*/
.
}
.
.
}
}
OSMboxPost（）
INT8UOSMboxPost（OS_EVENT*pevent,void*msg）;
所属文件
调用者
开关量
OS_MBOX.C
任务或中断
OS_MBOX_EN
OSMboxPost（）函数通过消息邮箱向任务发送消息。
消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。
如果消息邮箱中已经存在消息，返回错误码说明消息邮箱已满。
OSMboxPost（）函数立即返回调用者，消息也没有能够发到消息邮箱。
如果有任何任务在等待消息邮箱的消息，最高优先级的任务将得到这个消息。
如果等待消息的任务优先级比发送消息的任务优先级高，那么高优先级的任务将得到消息而恢复执行，也就是说，发生了一次任务切换。
参数
pevent是指向即将接受消息的消息邮箱的指针。
该指针的值在建立该消息邮箱时可以得到。
（参考OSMboxCreate（）函数）。
Msg是即将实际发送给任务的消息。
消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。
不允许传递一个空指针，因为这意味着消息邮箱为空。
返回值
OSMboxPost（）函数的返回值为下述之一：
●OS_NO_ERR：
消息成功的放到消息邮箱中。
●OS_MBOX_FULL：
消息邮箱已经包含了其他消息，不空。
●OS_ERR_EVENT_TYPE：
pevent不是指向消息邮箱的指针。
注意/警告
必须先建立消息邮箱，然后使用。
不允许传递一个空指针，因为这意味着消息邮箱为空。
范例：
OS_EVENT*CommMbox;
INT8UCommRxBuf[100];
voidCommTaskRx（void*pdata）
{
INT8Uerr;
pdata=pdata;
for（;;）{
.
err=OSMboxPost（CommMbox,（void*）&CommRxBuf[0]）;
.
}
}
OSMboxQuery（）
INT8UOSMboxQuery（OS_EVENT*pevent,OS_MBOX_DATA*pdata）;
所属文件
调用者
开关量
OS_MBOX.C
任务或中断
OS_MBOX_EN
OSMboxQuery（）函数用来取得消息邮箱的信息。
用户程序必须分配一个OS_MBOX_DATA的数据结构，该结构用来从消息邮箱的事件控制块接受数据。
通过调用OSMboxQuery（）函数可以知道任务是否在等待消息以及有多少个任务在等待消息，还可以检查消息邮箱现在的消息。
参数
pevent是指向即将接受消息的消息邮箱的指针。
该指针的值在建立该消息邮箱时可以得到。
（参考OSMboxCreate（）函数）。
Pdata是指向OS_MBOX_DATA数据结构的指针，该数据结构包含下述成员：
Void*OSMsg;/*消息邮箱中消息的复制*/
INT8UOSEventTbl[OS_EVENT_TBL_SIZE];/*消息邮箱等待队列的复制*/
INT8UOSEventGrp；
返回值
OSMboxQuery（）函数的返回值为下述之一：
●OS_NO_ERR：
调用成功
●OS_ERR_EVENT_TYPE：
pevent不是指向消息邮箱的指针。
注意/警告
必须先建立消息邮箱，然后使用。
范例：
OS_EVENT*CommMbox;
voidTask（void*pdata）
{
OS_MBOXDATAmbox_data;
INT8Uerr;
pdata=pdata;
for（;;）{
.
err=OSMboxQuery（CommMbox,&mbox_data）;
if（err==OS_NO_ERR）{
./*如果mbox_data.OSMsg为非空指针，说明消息邮箱非空*/
}
.
}
}
OSMemCreate（）
OS_MEM*OSMemCreate（void*addr,INT32Unblks,INT32Ublksize,INT8U*err）;
所属文件
调用者
开关量
OS_MEM.C
任务或初始代码
OS_/MEM_EN
OSMemCreate（）函数建立并初始化一块内存区。
一块内存区包含指定数目的大小确定的内存块。
程序可以包含这些内存块并在用完后释放回内存区。
参数
addr建立的内存区的起始地址。
内存区可以使用静态数组或在初始化时使用malloc（）函数建立。
Nblks需要的内存块的数目。
每一个内存区最少需要定义两个内存块。
Blksize每个内存块的大小，最少应该能够容纳一个指针。
Err是指向包含错误码的变量的指针。
OSMemCreate（）函数返回的错误码可能为下述几种：
OS_NO_ERR：
成功建立内存区。
OS_MEM_INVALID_PART：
没有空闲的内存区。
OS_MEM_INVALID_BLKS：
没有为每一个内存区建立至少两个内存块。
OS_MEM_INVALID_SIZE：
内存块大小不足以容纳一个指针变量。
返回值
OSMemCreate（）函数返回指向内存区控制块的指针。
如果没有剩余内存区，OSMemCreate（）函数返回空指针。
注意/警告
必须首先建立内存区，然后使用。
范例：
OS_MEM*CommMem;
INT8UCommBuf[16][128];
voidmain（void）
{
INT8Uerr;
OSInit（）;/*初始化μC/OS-Ⅱ*/
.
CommMem=OSMemCreate（&CommBuf[0][0],16,128,&err）;
.
OSStart（）;/*启动多任务内核*/
}
OSMemGet（）
Void*OSMemGet（OS_MEM*pmem,INT8U*err）;
所属文件
调用者
开关量
OS_MEM.C
任务或中断
OS_MEM_EN
OSMemGet（）函数用于从内存区分配一个内存块。
用户程序必须知道所建立的内存块的大小，同时用户程序必须在使用完内存块后释放内存块。
可以多次调用OSMemGet（）函数。
参数
pmem是指向内存区控制块的指针，可以从OSMemCreate（）函数返回得到。
Err是指向包含错误码的变量的指针。
OSMemGet（函数返回的错误码可能为下述几种：
●OS_NO_ERR：
成功得到一个内存块。
●OS_MEM_NO_FREE_BLKS：
内存区已经没有空间分配给内存块。
返回值
OSMemGet（）函数返回指向内存区块的指针。
如果没有空间分配给内存块，OSMemGet（）函数返回空指针。
注意/警告
必须首先建立内存区，然后使用。
范例：
OS_MEM*CommMem;
voidTask（void*pdata）
{
INT8U*msg;
pdata=pdata;
for（;;）{
msg=OSMemGet（CommMem,&err）;
if（msg!
=（INT8U*）0）{
./*内存块已经分配*/
.
}
.
}
}
OSMemPut（）
INT8UOSMemPut（OS_MEM*pmem,void*pblk）;
所属文件
调用者
开关量
OS_MEM.C
任务或中断
OS_MEM_EN
OSMemPut（）函数释放一个内存块，内存块必须释放回原先申请的内存区。
参数
pmem是指向内存区控制块的指针，可以从OSMemCreate（）函数返回得到。
Pblk是指向将被释放的内存块的指针。
返回值
OSMemPut（）函数的返回值为下述之一：
OS_NO_ERR：
成功释放内存块
OS_MEM_FULL：
内存区已经不能再接受更多释放的内存块。
这种情况说明用户程序出现了错误，释放了多于用OSMemGet（）函数得到的内存块。
注意/警告
必须首先建立内存区，然后使用。
内存块必须释放回原先申请的内存区。
范例：
OS_MEM*CommMem;
INT8U*CommMsg;
voidTask（void*pdata）
{
INT8Uerr;
pdata=pdata;
for（;;）{
err=OSMemPut（CommMem,（void*）CommMsg）;
if（err==OS_NO_ERR）{
./*释放内存块*/
}
.
}
}
OSMemQuery（）
INT8UOSMemQuery（OS_MEM*pmem,OS_MEM_DATA*pdata）;
所属文件
调用者
开关量
OS_MEM.C
任务或中断
OS_MEM_EN
OSMemQuery（）函数得到内存区的信息。
该函数返回OS_MEM结构包含的信息，但使用了一个新的OS_MEM_DATA的数据结构。
OS_MEM_DATA数据结构还包含了正被使用的内存块数目的域。
参数
pmem是指向内存区控制块的指针，可以从OSMemCreate（）函数返回得到。
Pdata是指向OS_MEM_DATA数据结构的指针，该数据结构包含了以下的域：
VoidOSAddr;/*指向内存区起始地址的指针*/
VoidOSFreeList;/*指向空闲内存块列表起始地址的指针*/
INT32UOSBlkSize;/*每个内存块的大小*/
INT32UOSNBlks;/*该内存区的内存块总数*/
INT32UOSNFree;/*空闲的内存块数目*/
INT32UOSNUsed;/*使用的内存块数目*/
返回值
OSMemQuery（）函数返回值总是OS_NO_ERR。
注意/警告
必须首先建立内存区，然后使用。
范例：
OS_MEM*CommMem;
voidTask（void*pdata）
{
INT8Uerr;
OS_MEM_DATAmem_data;
pdata=pdata;
for（;;）{
.
err=OSMemQuery（CommMem,&mem_data）;
.
}
}
OSQAccept（）
Void*OSQAccept（OS_EVENT*pevent）;
所属文件
调用者
开关量
OS_Q.C
任务或中断
OS_Q_EN
OSQAccept（）函数检查消息队列中是否已经有需要的消息。
不同于OSQPend（）函数，如果没有需要的消息，OSQAccept（）函数并不挂起任务。
如果消息已经到达，该消息被传递到用户任务。
通常中断调用该函数，因为中断不允许挂起等待消息。
参数
pevent是指向需要查看的消息队列的指针。
当建立消息队列时，该指针返回到用户程序。
（参考OSMboxCreate（）函数）。
返回值
如果消息已经到达，返回指向该消息的指针；如果消息队列没有消息，返回空指针。
注意/警告
必须先建立消息队列，然后使用。
范例：
OS_EVENT*CommQ;
voidTask（void*pdata）
{
void*msg;
pdata=pdata;
for（;;）{
msg=OSQAccept（CommQ）;/*检查消息队列*/
if（msg!
=（void*）0）{
./*处理接受的消息*/
.
}else{
./*没有消息*/
}
.
}
}
OSQCreate（）
OS_EVENT*OSQCreate（void**start,INT8Usize）;
所属文件
调用者
开关量
OS_Q.C
任务或启动代码
OS_Q_EN
OSQCreate（）函数建立一个消息队列。
任务或中断可以通过消息队列向其他一个或多个任务发送消息。
消息的含义是和具体的应用密切相关的。
参数
start是消息内存区的基地址，消息内存区是一个指针数组。
Size是消息内存区的大小。
返回值
OSQCreate（）函数返回一个指向消息队列事件控制块的指针。
如果没有空余的事件空闲块，OSQCreate（）函数返回空指针。
注意/警告
必须先建立消息队列，然后使用。
范例：
OS_EVENT*CommQ;
void*CommMsg[10];
voidmain（void）
{
OSInit（）;/*初始化μC/OS-Ⅱ*/
.
.
CommQ=OSQCreate（&CommMsg[0],10）;/*建立消息队列*/
.
OSStart（）;/*启动多任务内核*/
}
OSQFlush（）
INT8U
升级会员 