UCOSII API 参考手册.docx

《UCOSII API 参考手册.docx》由会员分享，可在线阅读，更多相关《UCOSII API 参考手册.docx（76页珍藏版）》请在三一办公上搜索。

1、UCOSII API 参考手册UCOS-II API 参考手册 本章提供了C/OS-的用户指南。每一个用户可以调用的内核函数都按字母顺序加以说明，包括： l 函数的功能描述 l 函数原型 l 函数名称及源代码 l 函数使用到的常量 l 函数参数 l 函数返回值 l 特殊说明和注意点 OSInit( ) 所属文件 OS_CORE.C Void OSInit(void); 调用者 开关量 启动代码 无 OSinit初始化C/OS-，对这个函数的调用必须在调用OSStart函数之前，而OSStart函数真正开始运行多任务。 参数 无 返回值 无 注意/警告 必须先于OSStart函数的调用 范例：

2、void main (void) . OSInit; /* 初始化 uC/OS-II */ . OSStart; /*启动多任务内核 */ C/OS-II:实时操作系统内核 OSIntEnter( ) 所属文件 OS_CORE.C Void OSIntEnter; 调用者 开关量 中断 无 OSIntEnter通知C/OS-一个中断处理函数正在执行，这有助于C/OS-掌握中断嵌套的情况。OSIntEnter函数通常和OSIntExit函数联合使用。 参数 无 返回值 无 注意/警告 在任务级不能调用该函数。 如果系统使用的处理器能够执行自动的独立执行读取-修改-写入的操作，那么就可以直接递增中

3、断嵌套层数，这样可以避免调用函数所带来的额外的开销。 范例一： 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 范例二： 参考手册 ISRx PROC FAR PUSHA ; 保存中断现场 PUSH ES PUSH DS ; MOV AX, DGROUP ; 读入数据段 MOV DS, AX ; IN

4、C BYTE PTR _OSIntNesting ; 通知内核进入中断 . . . POP DS ; 恢复中断现场 POP ES POPA IRET ; 中断返回 ISRx ENDP C/OS-II:实时操作系统内核 OSIntExit( ) 所属文件 OS_CORE.C Void OSIntExit; 调用者 开关量 中断 无 OSIntExit通知C/OS-一个中断服务已执行完毕，这有助于C/OS-掌握中断嵌套的情况。通常OSIntExit和OSIntEnter联合使用。当最后一层嵌套的中断执行完毕后，如果有更高优先级的任务准备就绪，C/OS-会调用任务调度函数，在这种情况下，中断返回到更

5、高优先级的任务而不是被中断了的任务。 参数 无 返回值 无 注意/警告 在任务级不能调用该函数。并且即使没有调用OSIntEnter而是使用直接递增OSIntNesting的方法，也必须调用OSIntExit函数。 范例： ISRx PROC FAR PUSHA ; 保存中断现场 PUSH ES PUSH DS . . CALL FAR PTR _OSIntExit ; 通知内核进入中断 POP DS ; 恢复中断现场 POP ES POPA IRET ; 中断返回 ISRx ENDP 参考手册 OSMboxAccept( ) Void *OSMboxAccept; 所属文件 调用者 开关量

6、OS_MBOX_EN 任务或中断 OSMboxAccept函数查看指定的消息邮箱是否有需要的消息。不同于OSMboxPend函数，如果没有需要的消息，OSMboxAccept函数并不挂起任务。如果消息已经到达，该消息被传递到用户任务并且从消息邮箱中清除。通常中断调用该函数，因为中断不允许挂起等待消息。 OS_MBOX.C 参数 pevent 是指向需要查看的消息邮箱的指针。当建立消息邮箱时，该指针返回到用户程序。 返回值 如果消息已经到达，返回指向该消息的指针；如果消息邮箱没有消息，返回空指针。 注意/警告 必须先建立消息邮箱，然后使用。 范例： OS_EVENT *CommMbox; voi

7、d Task (void *pdata) void *msg; pdata = pdata; for (;) msg = OSMboxAccept(CommMbox); /* 检查消息邮箱是否有消息 if (msg != (void *)0) . /* 处理消息 . else . /*没有消息 . . . */ */ */ C/OS-II:实时操作系统内核 参考手册 OSMboxCreate( ) OS_EVENT *OSMboxCreate; 所属文件 调用者 开关量 OS_MBOX_EN 任务或启动代码 OSMboxCreate建立并初始化一个消息邮箱。消息邮箱允许任务或中断向其他一个或几

8、个任务发送消息。 OS_MBOX.C 参数 msg 参数用来初始化建立的消息邮箱。如果该指针不为空，建立的消息邮箱将含有消息。 返回值 指向分配给所建立的消息邮箱的事件控制块的指针。如果没有可用的事件控制块，返回空指针。 注意/警告 必须先建立消息邮箱，然后使用。 范例： OS_EVENT *CommMbox; void main(void) . . OSInit; /* 初始化C/OS- */ . . CommMbox = OSMboxCreate(void *)0); /* 建立消息邮箱 */ OSStart; /* 启动多任务内核 */ C/OS-II:实时操作系统内核 OSMboxPe

9、nd( ) Void *OSMboxPend ( OS_EVNNT *pevent, INT16U timeout, int8u *err ); 所属文件 调用者 开关量 OS_MBOX_EN 任务 OSMboxPend用于任务等待消息。消息通过中断或另外的任务发送给需要的任务。消息是一个以指针定义的变量，在不同的程序中消息的使用也可能不同。如果调用OSMboxPend函数时消息邮箱已经存在需要的消息，那么该消息被返回给OSMboxPend的调用者，消息邮箱中清除该消息。如果调用OSMboxPend函数时消息邮箱中没有需要的消息，OSMboxPend函数挂起当前任务直到得到需要的消息或超出定义

10、等待超时的时间。如果同时有多个任务等待同一个消息，C/OS-默认最高优先级的任务取得消息并且任务恢复执行。一个由OSTaskSuspend函数挂起的任务也可以接受消息，但这个任务将一直保持挂起状态直到通过调用OSTaskResume函数恢复任务的运行。 OS_MBOX.C 参数 pevent 是指向即将接受消息的消息邮箱的指针。该指针的值在建立该消息邮箱时可以得到。 Timeout 允许一个任务在经过了指定数目的时钟节拍后还没有得到需要的消息时恢复运行。如果该值为零表示任务将持续的等待消息。最大的等待时间为65,535个时钟节拍。这个时间长度并不是非常严格的，可能存在一个时钟节拍的误差，因为只

11、有在一个时钟节拍结束后才会减少定义的等待超时时钟节拍。 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。如果没有在指定数目的时钟节拍内接受到需要的消息

12、，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 . . /* 在指定时间内没有接受到消息*/ . . . C/OS-I

13、I:实时操作系统内核 OSMboxPost( ) INT8U OSMboxPost; 所属文件 调用者 开关量 OS_MBOX_EN 任务或中断 OSMboxPost函数通过消息邮箱向任务发送消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。如果消息邮箱中已经存在消息，返回错误码说明消息邮箱已满。OSMboxPost函数立即返回调用者，消息也没有能够发到消息邮箱。如果有任何任务在等待消息邮箱的消息，最高优先级的任务将得到这个消息。如果等待消息的任务优先级比发送消息的任务优先级高，那么高优先级的任务将得到消息而恢复执行，也就是说，发生了一次任务切换。 OS_MBOX.C 参数

14、pevent 是指向即将接受消息的消息邮箱的指针。该指针的值在建立该消息邮箱时可以得到。 Msg 是即将实际发送给任务的消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针，因为这意味着消息邮箱为空。 返回值 OSMboxPost函数的返回值为下述之一： l OS_NO_ERR ：消息成功的放到消息邮箱中。 l OS_MBOX_FULL ：消息邮箱已经包含了其他消息，不空。 l OS_ERR_EVENT_TYPE ：pevent 不是指向消息邮箱的指针。 注意/警告 必须先建立消息邮箱，然后使用。 不允许传递一个空指针，因为这意味着消息邮箱为空。 范例： O

15、S_EVENT *CommMbox; INT8U CommRxBuf100; void CommTaskRx(void *pdata) INT8U err; pdata = pdata; for (;) . err = OSMboxPost(CommMbox, (void *)&CommRxBuf0); . 参考手册 C/OS-II:实时操作系统内核 OSMboxQuery( ) INT8U OSMboxQuery; 所属文件 调用者 开关量 OS_MBOX_EN 任务或中断 OSMboxQuery函数用来取得消息邮箱的信息。用户程序必须分配一个OS_MBOX_DATA的数据结构，该结构用来从

16、消息邮箱的事件控制块接受数据。通过调用OSMboxQuery函数可以知道任务是否在等待消息以及有多少个任务在等待消息，还可以检查消息邮箱现在的消息。 OS_MBOX.C 参数 pevent 是指向即将接受消息的消息邮箱的指针。该指针的值在建立该消息邮箱时可以得到。 Pdata 是指向OS_MBOX_DATA数据结构的指针，该数据结构包含下述成员： Void *OSMsg; /* 消息邮箱中消息的复制 */ INT8U OSEventTblOS_EVENT_TBL_SIZE; /*消息邮箱等待队列的复制*/ INT8U OSEventGrp； 返回值 OSMboxQuery函数的返回值为下述之一

17、： 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为非空指针，说明消息邮箱非空*/ 参考手册 . C/

18、OS-II:实时操作系统内核 OSMemCreate( ) OS_MEM *OSMemCreate( void *addr, INT32U nblks ,INT32U blksize, INT8U *err); 所属文件 调用者 开关量 OS_/MEM_EN 任务或初始代码 OSMemCreate函数建立并初始化一块内存区。一块内存区包含指定数目的大小确定的内存块。程序可以包含这些内存块并在用完后释放回内存区。 OS_MEM.C 参数 addr 建立的内存区的起始地址。内存区可以使用静态数组或在初始化时使用malloc函数建立。 Nblks 需要的内存块的数目。每一个内存区最少需要定义两个内存

19、块。 Blksize 每个内存块的大小，最少应该能够容纳一个指针。 Err 是指向包含错误码的变量的指针。OSMemCreate函数返回的错误码可能为下述几种： OS_NO_ERR ：成功建立内存区。 OS_MEM_INVALID_PART ：没有空闲的内存区。 OS_MEM_INVALID_BLKS ：没有为每一个内存区建立至少两个内存块。 OS_MEM_INVALID_SIZE ：内存块大小不足以容纳一个指针变量。 返回值 OSMemCreate函数返回指向内存区控制块的指针。如果没有剩余内存区，OSMemCreate函数返回空指针。 注意/警告 必须首先建立内存区，然后使用。 范例： O

20、S_MEM *CommMem; INT8U CommBuf16128; void main(void) INT8U err; OSInit; /* 初始化C/OS- */ . CommMem = OSMemCreate(&CommBuf00, 16, 128, &err); . OSStart; /* 启动多任务内核 */ 参考手册 OSMemGet( ) Void *OSMemGet(OS_MEM *pmem, INT8U *err); 所属文件 调用者 开关量 OS_MEM_EN 任务或中断 OSMemGet函数用于从内存区分配一个内存块。用户程序必须知道所建立的内存块的大小，同时用户程序

21、必须在使用完内存块后释放内存块。可以多次调用OSMemGet函数。 OS_MEM.C 参数 pmem 是指向内存区控制块的指针，可以从OSMemCreate函数返回得到。 Err 是指向包含错误码的变量的指针。OSMemGet。 返回值 如果消息已经到达，返回指向该消息的指针；如果消息队列没有消息，返回空指针。 注意/警告 必须先建立消息队列，然后使用。 范例： OS_EVENT *CommQ; void Task (void *pdata) void *msg; pdata = pdata; for (;) msg = OSQAccept(CommQ); /* 检查消息队列 */ if (m

22、sg != (void *)0) . /* 处理接受的消息 */ . else . /* 没有消息 */ . 参考手册 C/OS-II:实时操作系统内核 OSQCreate( ) OS_EVENT *OSQCreate( void *start, INT8U size); 所属文件 调用者 开关量 OS_Q_EN 任务或启动代码 OSQCreate函数建立一个消息队列。任务或中断可以通过消息队列向其他一个或多个任务发送消息。消息的含义是和具体的应用密切相关的。 OS_Q.C 参数 start 是消息内存区的基地址，消息内存区是一个指针数组。 Size 是消息内存区的大小。 返回值 OSQCre

23、ate函数返回一个指向消息队列事件控制块的指针。如果没有空余的事件空闲块，OSQCreate函数返回空指针。 注意/警告 必须先建立消息队列，然后使用。 范例： OS_EVENT *CommQ; void *CommMsg10; void main(void) OSInit; /* 初始化C/OS- */ . . CommQ = OSQCreate(&CommMsg0, 10); /*建立消息队列 */ . OSStart; /* 启动多任务内核 */ 参考手册 OSQFlush( ) INT8U *SOQFlush; 所属文件 调用者 开关量 OS_Q_EN 任务或中断 OSQFlush函数

24、清空消息队列并且忽略发送往队列的所有消息。不管队列中是否有消息，这个函数的执行时间都是相同的。 OS_Q.C 参数 pevent 是指向消息队列的指针。该指针的值在建立该队列时可以得到。 返回值 OSQFlush函数的返回值为下述之一： l OS_NO_ERR ：消息队列被成功清空 l OS_ERR_EVENT_TYPE ：试图清除不是消息队列的对象 注意/警告 必须先建立消息队列，然后使用。 范例： OS_EVENT *CommQ; void main(void) INT8U err; OSInit; /* 初始化C/OS- */ . err = OSQFlush(CommQ); . OSS

25、tart; /* 启动多任务内核 */ C/OS-II:实时操作系统内核 OSQPend( ) Void *OSQPend( OS_EVENT *pevent, INT16U timeout, INT8U *err); 所属文件 调用者 开关量 OS_Q_EN 任务 OSQPend函数用于任务等待消息。消息通过中断或另外的任务发送给需要的任务。消息是一个以指针定义的变量，在不同的程序中消息的使用也可能不同。如果调用OSQPend函数时队列中已经存在需要的消息，那么该消息被返回给OSQPend函数的调用者，队列中清除该消息。如果调用OSQPend函数时队列中没有需要的消息，OSQPend函数挂起

26、当前任务直到得到需要的消息或超出定义的超时时间。如果同时有多个任务等待同一个消息，C/OS-默认最高优先级的任务取得消息并且任务恢复执行。一个由OSTaskSuspend函数挂起的任务也可以接受消息，但这个任务将一直保持挂起状态直到通过调用OSTaskResume函数恢复任务的运行。 OS_Q.C 参数 pevent 是指向即将接受消息的队列的指针。该指针的值在建立该队列时可以得到。 Timeout 允许一个任务在经过了指定数目的时钟节拍后还没有得到需要的消息时恢复运行状态。如果该值为零表示任务将持续的等待消息。最大的等待时间为65535个时钟节拍。这个时间长度并不是非常严格的，可能存在一个时

27、钟节拍的误差，因为只有在一个时钟节拍结束后才会减少定义的等待超时时钟节拍。 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。如果没有在指定数目的时钟节拍内接受到需

28、要的消息，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 . . /* 在指定的时间内没有接受到指定的消息 */ . C/OS-II:实

29、时操作系统内核 OSQPost( ) INT8U OSQPost(OS_EVENT *pevent, void *msg); 所属文件 调用者 开关量 OS_Q_EN 任务或中断 OSQPost函数通过消息队列向任务发送消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。如果队列中已经存满消息，返回错误码。OSQPost函数立即返回调用者，消息也没有能够发到队列。如果有任何任务在等待队列中的消息，最高优先级的任务将得到这个消息。如果等待消息的任务优先级比发送消息的任务优先级高，那么高优先级的任务将得到消息而恢复执行，也就是说，发生了一次任务切换。消息队列是先入先出机制的，先进入

30、队列的消息先被传递给任务。 OS_Q.C 参数 pevent 是指向即将接受消息的消息队列的指针。该指针的值在建立该队列时可以得到。 Msg 是即将实际发送给任务的消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针。 返回值 OSQPost函数的返回值为下述之一： l OS_NO_ERR ：消息成功的放到消息队列中。 l OS_MBOX_FULL ：消息队列已满。 l OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列的指针。 注意/警告 必须先建立消息队列，然后使用。 不允许传递一个空指针。 范例： OS_EVENT *CommQ; I

31、NT8U CommRxBuf100; void CommTaskRx(void *pdata) INT8U err; pdata = pdata; 参考手册 for (;) . . err = OSQPost(CommQ, (void *)&CommRxBuf0); if (err = OS_NO_ERR) . /* 将消息放入消息队列 */ . else . /* 消息队列已满 */ . . . C/OS-II:实时操作系统内核 OSQPostFront( ) INT8U OSQPostFront(OS_EVENT *pevent, void *msg); 所属文件 调用者 开关量 OS_Q

32、_EN 任务或中断 OSQPostFront函数通过消息队列向任务发送消息。OSQPostFront函数和OSQPost函数非常相似，不同之处在于OSQPostFront函数将发送的消息插到消息队列的最前端。也就是说，OSQPostFront函数使得消息队列按照后入先出的方式工作，而不是先入先出。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。如果队列中已经存满消息，返回错误码。OSQPost函数立即返回调用者，消息也没能发到队列。如果有任何任务在等待队列中的消息，最高优先级的任务将得到这个消息。如果等待消息的任务优先级比发送消息的任务优先级高，那么高优先级的任务将得到消息而恢复

33、执行，也就是说，发生了一次任务切换 OS_Q.C 参数 pevent 是指向即将接受消息的消息队列的指针。该指针的值在建立该队列时可以得到。 Msg 是即将实际发送给任务的消息。消息是一个指针长度的变量，在不同的程序中消息的使用也可能不同。不允许传递一个空指针。 返回值 OSQPost函数的返回值为下述之一： l OS_NO_ERR ：消息成功的放到消息队列中。 l OS_MBOX_FULL ：消息队列已满。 l OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列的指针。 注意/警告 必须先建立消息队列，然后使用。 不允许传递一个空指针。 范例： OS_EVENT *Comm

34、Q; INT8U CommRxBuf100; void CommTaskRx(void *pdata) INT8U err; pdata = pdata; for (;) . 参考手册 err = OSQPostFront(CommQ, (void *)&CommRxBuf0); if (err = OS_NO_ERR) . /* 将消息放入消息队列 */ else . /* 消息队列已满 */ . . C/OS-II:实时操作系统内核 OSQQuery( ) INT8U OSQQuery(OS_EVENT *pevent, OS_Q_DATA *pdata); 所属文件 调用者 开关量 OS

35、_Q_EN 任务或中断 OSQQuery函数用来取得消息队列的信息。用户程序必须建立一个OS_Q_DATA的数据结构，该结构用来保存从消息队列的事件控制块得到的数据。通过调用OSQQuery函数可以知道任务是否在等待消息、有多少个任务在等待消息、队列中有多少消息以及消息队列可以容纳的消息数。OSQQuery函数还可以得到即将被传递给任务的消息的信息。 OS_Q.C 参数 pevent 是指向即将接受消息的消息邮箱的指针。该指针的值在建立该消息邮箱时可以得到。 Pdata 是指向OS_Q_DATA数据结构的指针，该数据结构包含下述成员： Void *OSMsg; /* 下一个可用的消息*/ IN

36、T16U OSNMsgs； /* 队列中的消息数目*/ INT16U OSQSize； /* 消息队列的大小 */ INT8U OSEventTblOS_EVENT_TBL_SIZE; /* 消息队列的等待队列*/ INT8U OSEventGrp； 返回值 OSQQuery函数的返回值为下述之一： l OS_NO_ERR ：调用成功 l OS_ERR_EVENT_TYPE ：pevent 不是指向消息队列的指针。 注意/警告 必须先建立消息队列，然后使用。 范例： OS_EVENT *CommQ; void Task (void *pdata) OS_Q_DATA qdata; INT8U

37、err; 参考手册 pdata = pdata; for (;) . . err = OSQQuery(CommQ, &qdata); if (err = OS_NO_ERR) . /* 取得消息队列的信息 */ . . C/OS-II:实时操作系统内核 OSSchedLock( ) 所属文件 OS_CORE.C Void OSSchedLock(void); 调用者 开关量 N/A 任务或中断 OSSchedLock函数停止任务调度，只有使用配对的函数OSSchedUnlock才能重新开始内核的任务调度。调用OSSchedLock函数的任务独占CPU，不管有没有其他高优先级的就绪任务。在这种情况下，中断仍然可以被接受和执行。OSSchedLock函数和OSSchedUnlock函数必须配对使用。C/OS-可以支持多达254层的OSSchedLock函数嵌套，必须调用同样次数的OSSchedUnlock函数才能恢复任务调度。 参数 无 返回值 无 注意/警告 任务调用了OSSchedLock函数后，