第章参考手册模板.doc

OSInit( )
第11章
参考手册
本章提供了μC/OS-Ⅱ用户指南。每一个用户能够调用内核函数全部按字母次序加以说明，包含：
l 函数功效描述
l 函数原型
l 函数名称及源代码
l 函数使用到常量
l 函数参数
l 函数返回值
l 特殊说明和注意点

Void OSInit(void);

所属文件
调用者
开关量
OS_CORE.C
开启代码
无
OSinit（）初始化μC/OS-Ⅱ，对这个函数调用必需在调用OSStart（）函数之前，而OSStart（）函数真正开始运行多任务。
参数
无

返回值
无

注意/警告
必需先于OSStart（）函数调用

范例：
void main (void)
{
.
OSInit(); /* 初始化 uC/OS-II */
.
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(); /* 初始化μC/OS-Ⅱ */
.
.
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) {
. /* 假如mbox_data.OSMsg为非空指针，说明消息邮箱非空*/
}
.
}
}
OSMemCreate( )
OS_MEM *OSMemCreate( void *addr, INT32U nblks ,INT32U blksize, 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;
INT8U CommBuf[16][128];

void main(void)
{
INT8U err;

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（函数返回错误码可能为下述多个：
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);
.
}
}
OSQAccept( )
Void *OSQAccept(OS_EVENT *pevent);

所属文件
调用者
开关量
OS_Q.C
任务或中止
OS_Q_EN
OSQAccept（）函数检验消息队列中是否已经有需要消息。不一样于OSQPend（）函数，假如没有需要消息，OSQAccept（）函数并不挂起任务。假如消息已经抵达，该消息被传输到用户任务。通常中止调用该函数，因为中止不许可挂起等候消息。

参数
pevent 是指向需要查看消息队列指针。当建立消息队列时，该指针返回到用户程序。（参考OSMboxCreate（）函数）。

返回值
假如消息已经抵达，返回指向该消息指针；假如消息队列没有消息，返回空指针。

注意/警告
必需先建立消息队列，然后使用。

范例：

OS_EVENT *CommQ;

void Task (void *pdata)
{
void *msg;

pdata = pdata;
for (;;) {
msg = OSQAccept(CommQ); /* 检验消息队列 */
if (msg != (void *)0) {
. /* 处理接收消息 */
.
} else {
. /* 没有消息 */
}
.
}
}
OSQCreate( )
OS_EVENT *OSQCreate( void **start, INT8U size);

所属文件
调用者
开关量
OS_Q.C
任务或开启代码
OS_Q_EN
OSQCreate（）函数建立一个消息队列。任务或中止能够经过消息队列向其它一个或多个任务发送消息。消息含义是和具体应用亲密相关。

参数
start 是消息内存区基地址，消息内存区是一个指针数组。
Size 是消息内存区大小。

返回值
OSQCreate（）函数返回一个指向消息队列事件控制块指针。假如没有空余事件空闲块，OSQCreate（）函数返回空指针。

注意/警告
必需先建立消息队列，然后使用。

范例：
OS_EVENT *CommQ;
void *CommMsg[10];

void main(void)
{
OSInit(); /* 初始化μC/OS-Ⅱ */
.
.
CommQ = OSQCreate(&CommMsg[0], 10); /*建立消息队列 */
.
OSStart(); /* 开启多任务内核 */
}

OSQFlush( )
INT8U *SOQFlush（OS_EVENT *pevent）;

所属文件
调用者
开关量
OS_Q.C
任务或中止
OS_Q_EN
OSQFlush（）函数清空消息队列而且忽略发送往队列全部消息。不管队列中是否有消息，这个函数实施时间全部是相同。

参数
pevent 是指向消息队列指针。该指针值在建立该队列时能够得到。（参考OSQCreate（）函数）。

返回值
OSQFlush（）函数返回值为下述之一：
l OS_NO_ERR ：消息队列被成功清空
l OS_ERR_EVENT_TYPE ：试图清除不是消息队列对象
注意/警告
必需先建立消息队列，然后使用。

范例：
OS_EVENT *CommQ;

void main(void)
{
INT8U err;
OSInit(); /* 初始化μC/OS-Ⅱ */
.
err = OSQFlush(CommQ);
.
OSStart(); /* 开启多任务内核 */
}
OSQPend( )
Void *OSQPend( OS_EVENT *pevent, INT16U timeout, INT8U *err);

所属文件
调用者
开关量
OS_Q.C
任务
OS_Q_EN
OSQPend（）函数用于任务等候消息。消息经过中止或另外任务发送给需要任务。消息是一个以指针定义变量，在不一样程序中消息使用也可能不一样。假如调用OSQPend（）函数时队列中已经存在需要消息，那么该消息被返回给OSQPend（）函数调用者，队列中清除该消息。假如调用OSQPend（）函数时队列中没有需要消息，OSQPend（）函数挂起目前任务直到得到需要消息或超出定义超时时间。假如同时有多个任务等候同一个消息，μC/OS-Ⅱ默认最高优先级任务取得消息而且任务恢复实施。一个由OSTaskSuspend（）函数挂起任务也能够接收消息，但这个任务将一直保持挂起状态直到经过调用OSTaskResume（）函数恢复任务运行。

参数
pevent 是指向立即接收消息队列指针。该指针值在建立该队列时能够得到。（参考OSMboxCreate（）函数）。

Timeout 许可一个任务在经过了指定数目标时钟节拍后还没有得到需要消息时恢复运行状态。假如该值为零表示任务将连续等候消息。最大等候时间为65535个时钟节拍。这个时间长度并不是很严格，可能存在一个时钟节拍误差，因为只有在一个时钟节拍结束后才会降低定义等候超时时钟节拍。

Err 是指向包含错误码变量指针。OSQPend（）函数返回错误码可能为下述多个：
l OS_NO_ERR ：消息被正确接收。
l OS_TIMEOUT ：消息没有在指定周期数内送到。
l OS_ERR_PEND_ISR ：从中止调用该函数。即使要求了不许可从中止调用该函数，但μC/OS-Ⅱ仍然包含了检测这种情况功效。
l OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列指针。

返回值
OSQPend（）函数返回接收消息并将 *err置为OS_NO_ERR。假如没有在指定数目标时钟节拍内接收到需要消息，OSQPend（）函数返回空指针而且将 *err设置为OS_TIMEOUT。

注意/警告
必需先建立消息邮箱，然后使用。
不许可从中止调用该函数。

范例：
OS_EVENT *CommQ;

void CommTask(void *data)
{
INT8U err;
void *msg;

pdata = pdata;
for (;;) {
.
.
msg = OSQPend(CommQ, 100, &err);
if (err == OS_NO_ERR) {
.
. /* 在指定时间内接收到消息 */
.
} else {
.
. /* 在指定时间内没有接收到指定消息 */
}
.
}
}

OSQPost( )
INT8U OSQPost(OS_EVENT *pevent, void *msg);

所属文件
调用者
开关量
OS_Q.C
任务或中止
OS_Q_EN
OSQPost（）函数经过消息队列向任务发送消息。消息是一个指针长度变量，在不一样程序中消息使用也可能不一样。假如队列中已经存满消息，返回错误码。OSQPost（）函数立即返回调用者，消息也没有能够发到队列。假如有任何任务在等候队列中消息，最高优先级任务将得到这个消息。假如等候消息任务优先级比发送消息任务优先级高，那么高优先级任务将得到消息而恢复实施，也就是说，发生了一次任务切换。消息队列是先入先出（FIFO）机制，优异入队列消息先被传输给任务。

参数
pevent 是指向立即接收消息消息队列指针。该指针值在建立该队列时能够得到。（参考OSQCreate（）函数）。

Msg 是立即实际发送给任务消息。消息是一个指针长度变量，在不一样程序中消息使用也可能不一样。不许可传输一个空指针。
返回值
OSQPost（）函数返回值为下述之一：
l OS_NO_ERR ：消息成功放到消息队列中。
l OS_MBOX_FULL ：消息队列已满。
l OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列指针。
注意/警告
必需先建立消息队列，然后使用。
不许可传输一个空指针。

范例：

OS_EVENT *CommQ;
INT8U CommRxBuf[100];

void CommTaskRx(void *pdata)
{
INT8U err;

pdata = pdata;
for (;;) {
.
.
err = OSQPost(CommQ, (void *)&CommRxBuf[0]);
if (err == OS_NO_ERR) {
. /* 将消息放入消息队列 */
.
} else {
. /* 消息队列已满 */
.
}
.
.
}
}

OSQPostFront( )
INT8U OSQPostFront(OS_EVENT *pevent, void *msg);

所属文件
调用者
开关量
OS_Q.C
任务或中止
OS_Q_EN
OSQPostFront（）函数经过消息队列向任务发送消息