UCOS-II API 参考手册
本章提供了μC/OS-Ⅱ的用户指南。每一个用户可以调用的内核函数都按字母顺序加以说
明,包括:
函数的功能描述
函数原型
函数名称及源代码
函数使用到的常量
函数参数
函数返回值
特殊说明和注意点
所属文件
OS_CORE.C
OSInit( )
Void OSInit(void);
调用者
启动代码
开关量
无
OSinit()初始化μC/OS-Ⅱ,对这个函数的调用必须在调用 OSStart()函数之前,而 OSStart
()函数真正开始运行多任务。
参数
无
返回值
无
注意/警告
必须先于 OSStart()函数的调用
范例:
void main (void)
{
.
OSInit(); /* 初始化 uC/OS-II */
.
OSStart(); /*启动多任务内核 */
}
μC/OS-II:实时操作系统内核
所属文件
OS_CORE.C
OSIntEnter( )
Void OSIntEnter(void);
调用者
中断
开关量
无
OSIntEnter()通知μC/OS-Ⅱ一个中断处理函数正在执行,这有助于μC/OS-Ⅱ掌握中断嵌套的
情况。OSIntEnter()函数通常和 OSIntExit()函数联合使用。
参数
无
返回值
无
注意/警告
在任务级不能调用该函数。
如果系统使用的处理器能够执行自动的独立执行读取-修改-写入的操作,那么就可以直接递增中
断嵌套层数(OSIntNesting),这样可以避免调用函数所带来的额外的开销。
范例一:
(Intel 80x86 的实模式, 在大模式下编译,,real mode,large model)
ISRx PROC FAR
PUSHA ; 保存中断现场
PUSH ES
PUSH DS
;
MOV AX, DGROUP ; 读入数据段
MOV DS, AX
;
CALL FAR PTR _OSIntEnter ; 通知内核进入中断
.
.
POP DS ; 恢复中断现场
POP ES
POPA
IRET ; 中断返回
ISRx ENDP
范例二:
(Intel 80x86 的实模式, 在大模式下编译,, real mode , large model)
参考手册
ISRx PROC FAR
PUSHA ; 保存中断现场
PUSH ES
PUSH DS
;
MOV AX, DGROUP ; 读入数据段
MOV DS, AX
;
INC BYTE PTR _OSIntNesting ; 通知内核进入中断
.
.
.
POP DS ; 恢复中断现场
POP ES
POPA
IRET ; 中断返回
ISRx ENDP
μC/OS-II:实时操作系统内核
所属文件
OS_CORE.C
OSIntExit( )
Void OSIntExit(void);
调用者
中断
开关量
无
OSIntExit()通知μC/OS-Ⅱ一个中断服务已执行完毕,这有助于μC/OS-Ⅱ掌握中断嵌套的情
况。通常 OSIntExit()和 OSIntEnter()联合使用。当最后一层嵌套的中断执行完毕后,如果
有更高优先级的任务准备就绪,μC/OS-Ⅱ会调用任务调度函数,在这种情况下,中断返回到更
高优先级的任务而不是被中断了的任务。
参数
无
返回值
无
注意/警告
在任务级不能调用该函数。并且即使没有调用 OSIntEnter()而是使用直接递增 OSIntNesting
的方法,也必须调用 OSIntExit()函数。
范例:
(Intel 80x86 的实模式, 在大模式下编译, real mode , large model)
ISRx PROC FAR
PUSHA ; 保存中断现场
PUSH ES
PUSH DS
.
.
CALL FAR PTR _OSIntExit ; 通知内核进入中断
POP DS ; 恢复中断现场
POP ES
POPA
IRET ; 中断返回
ISRx ENDP
参考手册
OSMboxAccept( )
Void *OSMboxAccept(OS_EVENT *pevent);
调用者
任务或中断
开关量
OS_MBOX_EN
所属文件
OS_MBOX.C
OSMboxAccept()函数查看指定的消息邮箱是否有需要的消息。不同于 OSMboxPend()函数,
如果没有需要的消息,OSMboxAccept()函数并不挂起任务。如果消息已经到达,该消息被传
递到用户任务并且从消息邮箱中清除。通常中断调用该函数,因为中断不允许挂起等待消息。
参数
pevent 是指向需要查看的消息邮箱的指针。当建立消息邮箱时,该指针返回到用户程序。(参考
OSMboxCreate()函数)。
返回值
如果消息已经到达,返回指向该消息的指针;如果消息邮箱没有消息,返回空指针。
注意/警告
必须先建立消息邮箱,然后使用。
范例:
OS_EVENT *CommMbox;
void Task (void *pdata)
{
void *msg;
pdata = pdata;
for (;;) {
msg = OSMboxAccept(CommMbox); /* 检查消息邮箱是否有消息
if (msg != (void *)0) {
. /* 处理消息
.
} else {
. /*没有消息
.
}
.
.
*/
*/
*/
μC/OS-II:实时操作系统内核
}
}
参考手册
OSMboxCreate( )
OS_EVENT *OSMboxCreate(void *msg);
所属文件
OS_MBOX.C
调用者
任务或启动代码
开关量
OS_MBOX_EN
OSMboxCreate()建立并初始化一个消息邮箱。消息邮箱允许任务或中断向其他一个或几个任
务发送消息。
参数
msg 参数用来初始化建立的消息邮箱。如果该指针不为空,建立的消息邮箱将含有消息。
返回值
指向分配给所建立的消息邮箱的事件控制块的指针。如果没有可用的事件控制块,返回空指针。
注意/警告
必须先建立消息邮箱,然后使用。
范例:
OS_EVENT *CommMbox;
void main(void)
{
.
.
OSInit(); /* 初始化μC/OS-Ⅱ */
.
.
CommMbox = OSMboxCreate((void *)0); /* 建立消息邮箱 */
OSStart(); /* 启动多任务内核 */
}
μC/OS-II:实时操作系统内核
OSMboxPend( )
Void *OSMboxPend ( OS_EVNNT *pevent, INT16U timeout, 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。
注意/警告
必须先建立消息邮箱,然后使用。
不允许从中断调用该函数。
范例: