Nucleus源码分析--Mailbox.doc

多 媒 体 技 术 部文档编号：Nucleus源码分析-Mailbox模块 大唐微电子技术有限公司邵壮页数修改后版本修改者修改日期修改说明备注Document informationFile LocationD:.doc（请说明在文档服务器上的位置）Last saved 2005/1/6 17:25:00目 录1. 概述31.1 功能描述31.2 文件信息32. 实现原理42.1 邮箱结构42.2 邮箱管理42.3 邮箱挂起管理43. 数据结构53.1 MB_MCB 邮箱控制块53.2 MB_SUSPEND 邮箱挂起控制块53.3 模块变量(全局)54. 程序分析64.1 接口函数映射表64.2 MBC.C程序64.2.1 MBC_Create_Mailbox64.2.2 MBC_Delete_Mailbox74.2.3 MBC_Send_To_Mailbox84.2.4 MBC_Receive_From_Mailbox104.2.5 MBC_Cleanup124.3 MBS.C程序134.3.1 MBS_Reset_Mailbox134.3.2 MBS_Broadcast_To_Mailbox144.4 其它164.4.1 MBD.C164.4.2 MBI.C164.4.3 MBF.C174.4.4 MBCE.C174.4.5 MBSE.C171. 概述1.1 功能描述邮箱是一种低负荷传递消息的机制。每个邮箱可容纳一条4 *32位字的消息。通过值的收发来完成消息的传递。发送消息的请求拷贝消息值到邮箱，接受消息请求又从邮箱中将消息取出来。收发邮件的服务有几种挂起选择：无条件被挂起、超时挂起和不挂起。任务因为邮箱挂起可能有几种原因。如果任务试图从一个空的邮箱里接收邮件，它将被挂起等待。如果一个任务试图向一个非空邮箱发送邮件也可能被挂起。当邮箱完成了任务的请求后 ，被挂起的任务就将被恢复。例如，假设一个任务因为等待从邮箱接收消息而被挂起。当消息发到了邮箱，任务就会恢复。多个任务会因某个邮箱而被挂起。对挂起的任务的调度方法可以采用FIFO或者优先权，这根据邮箱建立时设置而定。如果邮箱支持FIFO挂起，任务恢复的顺序与他们挂起的顺序一致。如果邮箱支持优先级挂起，任务的恢复按照告优先级到低优先级的顺序。 1.2 文件信息邮箱组件(MB)包括9个文件，列表如下： 文件名称内容描述MB_DEFS.H该文件定义MB组件特定的数据结构和常量MB_EXTR.H该文件定义MB组件的外部接口MBD.C该文件定义MB组件的全局数据结构MBI.C该文件包括MB组件的初始化代码MBF.C该文件包括提供MB组件信息的相关函数MBC.C该文件包括MB组件的核心函数MBS.C该文件包括MB组件的附加函数MBCE.C该文件包括有错误检查的定义在MBC.C中的函数MBSE.C该文件包括有错误检查的定义在MBS.C中的函数2. 实现原理2.1 邮箱结构每一邮箱空间为4*32b，仅放一条消息。2.2 邮箱管理应用程序在创建邮箱前应建立一个NU_MAILBOX类型的控制块，空间由应用程序提供。所有已创建邮箱的控制块都将被加入由MBD_Created_Mailboxs_List所指向的双向链表中，删除邮箱则将其从此双向链表中删除。结构如下图所示：模块变量MBD_List_Protect用于保护对于此链表的多重访问。2.3 邮箱挂起管理当任务接收或发送消息至邮箱时，在任务栈内会形成一个局部邮箱挂起控制块，若因此次调用而挂起，则将该控制块加入此邮箱的挂起链表。结构如下：当需从挂起恢复时，遍历此链表即可。3. 数据结构3.1 MB_MCB 邮箱控制块typedef struct MB_MCB_STRUCT CS_NODE mb_created; /* 已创建邮箱双向链表结点 */ UNSIGNED mb_id; /*内部 MCB ID */ CHAR mb_nameNU_MAX_NAME; /* 邮箱名称 */ DATA_ELEMENT mb_message_present; /* 当前消息标志 */ DATA_ELEMENT mb_fifo_suspend; /*挂起类型标志 */#if PAD_2 DATA_ELEMENT mb_paddingPAD_2;#endif UNSIGNED mb_tasks_waiting; /* 等待的任务数*/ UNSIGNED /* 邮箱空间 */ mb_message_areaMB_MESSAGE_SIZE; struct MB_SUSPEND_STRUCT *mb_suspension_list; /*挂起列表 */ MB_MCB; 3.2 MB_SUSPEND 邮箱挂起控制块typedef struct MB_SUSPEND_STRUCT CS_NODE mb_suspend_link; /* 挂起列表结点 */ MB_MCB *mb_mailbox; /* 邮箱指针 */ TC_TCB *mb_suspended_task; /* 挂起任务指针 */ UNSIGNED *mb_message_area; /* 邮箱空间指针*/ STATUS mb_return_status; /*返回的状态 */ MB_SUSPEND;3.3 模块变量(全局)CS_NODE *MBD_Created_Mailboxes_List; /已创建邮箱链表头指针UNSIGNED MBD_Total_Mailboxes; /已创建邮箱数量TC_PROTECT MBD_List_Protect; /防止已创建邮箱链表被多重访问4. 程序分析4.1 接口函数映射表API函数对应的内部函数（No Error Check）对应的内部函数（Error Check）NU_Create_MailboxMBC_Create_MailboxMBCE_Create_MailboxNU_Delete_MailboxMBC_Delete_MailboxMBCE_Delete_MailboxNU_Reset_MailboxMBS_Reset_MailboxMBSE_Reset_MailboxNU_Send_To_MailboxMBC_Send_To_MailboxMBCE_Send_To_MailboxNU_Broadcast_To_MailboxMBS_Broadcast_To_MailboxMBSE_Broadcast_To_MailboxNU_Receive_From_MailboxMBC_Receive_From_MailboxMBCE_Receive_From_MailboxNU_Established_MailboxsMBF_Established_MailboxsMBF_Established_MailboxsNU_Mailbox_InformationMBF_Mailbox_InformationMBF_Mailbox_InformationNU_Mailbox_PointersMBF_Mailbox_PointersMBF_Mailbox_Pointers4.2 MBC.C程序4.2.1 MBC_Create_Mailbox函数原型：STATUS MBC_Create_Mailbox(NU_MAILBOX *mailbox_ptr, CHAR *name, OPTION suspend_type)功能描述：创建邮箱扇入函数： Application MBCE_Create_Mailbox扇出函数：CSC_Place_On_List HIC_Make_History_Entry TCT_Check_Stack TCT_Protect TCT_Unprotect 输入参数： mailbox_ptr 邮箱控制块指针name 邮箱名字7个字符，以空字符结束 suspend_type 挂起类型返回值： NU_SUCCESS成功完成函数调用实现流程：4.2.2 MBC_Delete_Mailbox函数原型：STATUS MBC_Delete_Mailbox(NU_MAILBOX *mailbox_ptr)功能描述：删除邮箱并从已创建链表中移出扇入函数： Application MBCE_Delete_Mailbox扇出函数：CSC_Remove_From_List HIC_Make_History_Entry TCT_Check_Stack TCT_Protect TCT_System_Protect TCT_Unprotect TCC_Resume_TaskTCT_Control_To_System TCT_Set_Current_Protect TCT_System_Unprotect输入参数：mailbox_ptrMailbox控制块指针返回值： NU_SUCCESS 成功完成函数调用4.2.3 MBC_Send_To_Mailbox函数原型：STATUS MBC_Send_To_Mailbox(NU_MAILBOX *mailbox_ptr, VOID *message, UNSIGNED suspend)功能描述：发送消息至邮箱扇入函数： Application MBCE_Send_To_Mailbox扇出函数：CSC_Remove_From_List HIC_Make_History_Entry TCT_Check_Stack TCT_System_Protect TCT_Unprotect TCC_Resume_TaskTCT_Control_To_System TCT_System_Unprotect CSC_Place_On_List CSC_Priority_Place_On_List TCC_Suspend_Task TCC_Task_Priority TCT_Current_Thread输入参数： mailbox_ptr 邮箱控制块指针message 发送的消息 suspend_type 挂起类型返回值： NU_SUCCESS 表明service执行成功 NU_MAILBOX_FULL 表明邮箱为满 NU_TIMEOUT 超时 NU_MAILBOX_DELETED当任务被挂起时，邮箱被删除 NU_MAILBOX_RESET 当任务被挂起时，邮箱被复位实现流程：4.2.4 MBC_Receive_From_Mailbox函数原型：STATUS MBC_Receive_From_Mailbox(NU_MAILBOX *mailbox_ptr, VOID *message, UNSIGNED suspend)功能描述：从邮箱接收消息扇入函数： Application MBCE_Receive_From_Mailbox扇出函数：CSC_Remove_From_List HIC_Make_History_Entry TCT_Check_Stack TCT_System_Protect TCT_Unprotect TCC_Resume_TaskTCT_Control_To_System CSC_Place_On_List CSC_Priority_Place_On_List TCC_Suspend_Task TCC_Task_Priority TCT_Current_Thread输入参数： mailbox_ptr 邮箱控制块指针message 接收消息指针 suspend_type 挂起类型返回值： NU_SUCCESS 表明service执行成功 NU_MAILBOX_ EMPTY 表明邮箱为空 NU_TIMEOUT 超时 NU_MAILBOX_DELETED 当任务被挂起时，邮箱被删除 NU_MAILBOX_RESET 当任务被挂起时，邮箱被复位实现流程：4.2.5 MBC_Cleanup函数原型：VOID MBC_Cleanup(VOID *information)功能描述：移除挂起控制块扇入函数：TCC_Timeout TCC_Terminate扇出函数： CSC_Remove_From_List输入参数： information 挂起控制块指针返回值： 无实现流程： 将挂起控制块的返回状态置为NU_TIMEOUT后，将其从挂起链表中删除。4.3 MBS.C程序4.3.1 MBS_Reset_Mailbox函数原型：STATUS MBS_Reset_Mailbox(NU_MAILBOX *mailbox_ptr)功能描述：复位邮箱扇入函数： Application MBSE_Reset_Mailbox扇出函数：TCC_Resume_Task HIC_Make_History_Entry TCT_Check_Stack TCT_System_Protect TCT_Unprotect TCT_Control_To_System输入参数：mailbox_ptrMailbox控制块指针返回值： NU_SUCCESS成功完成函数调用实现流程：4.3.2 MBS_Broadcast_To_Mailbox函数原型：STATUS MBS_Broadcast_To_Mailbox(NU_MAILBOX *mailbox_ptr, VOID *message, UNSIGNED suspend)功能描述：发送广播消息至邮箱扇入函数： Application MBSE_Broadcast_To_Mailbox扇出函数：CSC_Remove_From_ListCSC_Place_On_List CSC_Priority_Place_On_List HIC_Make_History_Entry TCT_Check_Stack TCT_System_Protect TCT_Unprotect TCC_Resume_TaskTCC_Suspend_Task TCC_Task_Priority TCT_Control_To_System TCT_Current_Thread输入参数： mailbox_ptr 邮箱控制块指针message 发送的消息 suspend_type 挂起类型返回值： NU_SUCCESS 表明service执行成功 NU_MAILBOX_FULL 表明邮箱为满 NU_TIMEOUT 超时 NU_MAILBOX_DELETED当任务被挂起时，邮箱被删除 NU_MAILBOX_RESET 当任务被挂起时，邮箱被复位实现流程：4.4 其它4.4.1 MBD.C模块全局变量定义。4.4.2 MBI.C模块初始化函数VOID MBI_Initialize(VOID)函数功能：初始化模块全局变量。4.4.3 MBF.C获取模块信息函数UNSIGNED MBF_Established_Mailboxs(VOID);函数功能：得到已建立Mailbox的数量STATUS MBF_Mailbox_Information(NU_MAILBOX *Mailbox_ptr, CHAR *name, OPTION *enable, UNSIGNED *expirations, UNSIGNED *id, UNSIGNED *initial_time, UNSIGNED *reschedule_time);函数功能：得到指定Mailbox的相关信息UNSIGNED MBF_Mailbox_Pointers(NU_MAILBOX *pointer_list, UNSIGNED maximum_pointers); 函数功能：建立一个系统中所有Established Mailboxs的指针列表 4.4.4 MBCE.C带参数有效性检验的MBS.C相关函数接口STATUS MBCE_Create_Mailbox(NU_MAILBOX *mailbox_ptr, CHAR *name, OPTION suspend_type)函数功能：若输入参数有效则调用MBC_Create_MailboxSTATUS MBCE_Delete_Mailbox(NU_MAILBOX *mailbox_ptr)函数功能：若输入参数有效则调用MBC_Delete_MailboxSTATUS MBCE_Send_To_Mailbox(NU_MAILBOX *mailbox_ptr, VOID *message, UNSIGNED suspend)函数功能：若输入参数有效则调用MBC_ S