参考手册

本章提供了μC/OS-Ⅱ的用户指南。每一个用户可以调用的内核函数都按字母顺序加以说明，包括：

l 函数的功能描述

l 函数原型

l 函数名称及源代码

l 函数使用到的常量

l 函数参数

l 函数返回值

l 特殊说明和注意点

 

 

OSInit( )

Void OSInit(void);

 

所属文件	调用者	开关量
OS_CORE.C	启动代码	无

OSinit（）初始化μC/OS-Ⅱ，对这个函数的调用必须在调用OSStart（）函数之前，而OSStart（）函数真正开始运行多任务。

 

 

参数

无

 

 

返回值

无

 

 

注意/警告

必须先于OSStart（）函数的调用

 

 

范例：

void main (void)

{

.

.

OSInit();

.

.

OSStart();

}

 

OSIntEnter( )

Void OSIntEnter（void）;

 

所属文件	调用者	开关量
OS_CORE.C	中断	无

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

 

OSIntExit( )

Void OSIntExit（void）;

 

所属文件	调用者	开关量
OS_CORE.C	中断	无

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.C	任务或中断	OS_MBOX_EN

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 {

.

.

}

.

.

}

}

 

 

OSMboxCreate( )

OS_EVENT *OSMboxCreate（void *msg）;

 

所属文件	调用者	开关量
OS_MBOX.C	任务或启动代码	OS_MBOX_EN

OSMboxCreate（）建立并初始化一个消息邮箱。消息邮箱允许任务或中断向其他一个或几个任务发送消息。

 

 

参数

msg 参数用来初始化建立的消息邮箱。如果该指针不为空，建立的消息邮箱将含有消息。

 

 

返回值

指向分配给所建立的消息邮箱的事件控制块的指针。如果没有可用的事件控制块，返回空指针。

 

注意/警告

必须先建立消息邮箱，然后使用。

 

范例：

 

 

OS_EVENT *CommMbox;

void main(void)

{

.

.

OSInit();

.

.

CommMbox = OSMboxCreate((void *)0);

OSStart();

}

 

 

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（）函数返回的错误码可能为下述几种：

l OS_NO_ERR ：消息被正确的接受。

l OS_TIMEOUT ：消息没有在指定的周期数内送到。

l OS_ERR_PEND_ISR ：从中断调用该函数。虽然规定了不允许从中断调用该函数，但μC/OS-Ⅱ仍然包含了检测这种情况的功能。

l OS_ERR_EVENT_TYPE  ：pevent 不是指向消息邮箱的指针。

 

返回值

OSMboxPend（）函数返回接受的消息并将 *err置为OS_NO_ERR。如果没有在指定数目的时钟节拍内接受到需要的消息，OSMboxPend（）函数返回空指针并且将 *err设置为OS_TIMEOUT。

 

注意/警告

必须先建立消息邮箱，然后使用。

不允许从中断调用该函数。

 

 

 

 

范例：

 

 

OS_EVENT *CommMbox;

void CommTask(void *pdata)

{

INT8U  err;

void  *msg;

pdata = pdata;

for (;;) {

.

.

msg = OSMboxPend(CommMbox, 10, &err);

if (err == OS_NO_ERR) {

.

.

.

} else {

.

.

.

}

.

.

}

}

 

 

 

OSMboxPost( )

INT8U OSMboxPost（OS_EVENT *pevent, void *msg）;

 

所属文件	调用者	开关量
OS_MBOX.C	任务或中断	OS_MBOX_EN

OSMboxPost（）函数通过消息邮箱向任务发送消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。如果消息邮箱中已经存在消息，返回错误码说明消息邮箱已满。OSMboxPost（）函数立即返回调用者，消息也没有能够发到消息邮箱。如果有任何任务在等待消息邮箱的消息，最高优先级的任务将得到这个消息。如果等待消息的任务优先级比发送消息的任务优先级高，那么高优先级的任务将得到消息而恢复执行，也就是说，发生了一次任务切换。

 

 

参数

pevent  是指向即将接受消息的消息邮箱的指针。该指针的值在建立该消息邮箱时可以得到。（参考OSMboxCreate（）函数）。

 

Msg 是即将实际发送给任务的消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针，因为这意味着消息邮箱为空。

返回值

OSMboxPost（）函数的返回值为下述之一：

l OS_NO_ERR ：消息成功的放到消息邮箱中。

l OS_MBOX_FULL ：消息邮箱已经包含了其他消息，不空。

l OS_ERR_EVENT_TYPE  ：pevent 不是指向消息邮箱的指针。

注意/警告

必须先建立消息邮箱，然后使用。

不允许传递一个空指针，因为这意味着消息邮箱为空。

范例：

 

 

OS_EVENT *CommMbox;

INT8U     CommRxBuf[100];

void CommTaskRx(void *pdata)

{

INT8U  err;

pdata = pdata;

for (;;) {

.

.

err = OSMboxPost(CommMbox, (void *)&CommRxBuf[0]);

.

.

}

}

 

 

 

OSMboxQuery( )

INT8U  OSMboxQuery（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; /* 消息邮箱中消息的复制 */

INT8U  OSEventTbl[OS_EVENT_TBL_SIZE];

INT8U OSEventGrp；

 

返回值

OSMboxQuery（）函数的返回值为下述之一：

l OS_NO_ERR ：调用成功

l OS_ERR_EVENT_TYPE  ：pevent 不是指向消息邮箱的指针。

注意/警告

必须先建立消息邮箱，然后使用。

 

范例：

 

 

OS_EVENT *CommMbox;

void Task (void *pdata)

{

OS_MBOXDATA mbox_data;

INT8U       err;

pdata = pdata;

for (;;) {

.

.

err = OSMboxQuery(CommMbox, &mbox_data);

if (err == OS_NO_ERR) {

.

.

.

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（函数返回的错误码可能为下述几种：

l OS_NO_ERR ：成功得到一个内存块。

l OS_MEM_NO_FREE_BLKS ：内存区已经没有空间分配给内存块。

返回值

OSMemGet（）函数返回指向内存区块的指针。如果没有空间分配给内存块，OSMemGet（）函数返回空指针。

 

注意/警告

必须首先建立内存区，然后使用。

 

范例：

 

 

OS_MEM *CommMem;

void Task (void *pdata)

{

INT8U *msg;

pdata = pdata;

for (;;) {

msg = OSMemGet(CommMem, &err);

if (msg != (INT8U *)0) {

.

.

}

.

.

}

}

 

 

 

OSMemPut( )

INT8U OSMemPut( 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;

void Task (void *pdata)

{

INT8U err;

pdata = pdata;

for (;;) {

err = OSMemPut(CommMem, (void *)CommMsg);

if (err == OS_NO_ERR) {

.

.

}

.

.

}

}

 

 

 

OSMemQuery( )

INT8U OSMemQuery(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数据结构的指针，该数据结构包含了以下的域：

Void    OSAddr;

Void OSFreeList;

INT32U OSBlkSize;

INT32U OSNBlks;

INT32U OSNFree;

INT32U OSNUsed; 

 

返回值

OSMemQuery（）函数返回值总是OS_NO_ERR。

 

 

注意/警告

必须首先建立内存区，然后使用。

 

范例：

 

 

OS_MEM      *CommMem;

void Task (void *pdata)

{

INT8U        err;

OS_MEM_DATA  mem_data;

pdata = pdata;

for (;;) {

.

.

err = OSMemQuery(CommMem, &mem_data);

.

.

}

}