ReadMe for Message Handlers and Scheduler Tutorial

消息处理程序和调度器操作指南自述文件

---

Description（描述）

This tutorial introduces the concepts of Message Handlers and the Scheduler. The BlueCore firmware provides a number of subsystems for on-chip applications but the most fundamental subsystem is the Messaging Subsystem.

本教程介绍了消息处理程序和调度器的概念。BlueCore固件为芯片上的应用程序提供了多个子系统，但是最基本的子系统是消息传递子系统。

All on-chip applications must use a message passing architecture for implementation, which allows them to react to events such as IO and messages from the Firmware.

所有在芯片上的应用程序都必须使用消息传递架构来实现，消息传递架构允许应用程序对事件做出反应，比如来自固件中IO和消息事件。

The Code（代码）

This application implements a simple incremental counter, counting between 0 and 10. The count and display of count value is implemented by a message handler function count_handler(). The message handler uses a count variable to store the current count value.

这个应用程序实现了一个简单的增量计数器，计数在0到10之间。计数和计数值的显示是由消息处理程序函数counthandler()实现的。这个消息处理程序使用一个count变量来存储当前的计数值

In order to use the messaging API, the message.h header file must be included.

为了使用消息传递的API，必须包括message.h头文件

   5: #include <message.h>    

Message handlers often have variables and data associated with them. These can be implemented as globals but it the preferred approach is to encapsulate these variables with the message handler that uses them.

消息处理程序通常具有与之相关的变量和数据。这些可以作为全局变量实现，但是首选方法是使用使用它们的消息处理程序来封装这些变量。

In this application, the count variable is encapsulated in with the message handler function pointer in a structure.

在这个应用程序中，count变量被封装在一个结构的消息处理函数指针中。

    11:    typedef struct _count_task_data     12:    {    13:        TaskData    count_task;    14:        uint8       count;    15:    } CountTaskData;    

To create a message handler, a static void function with exact parameters must be defined. For example, this is the definition of the count_handler() message handler function in this application.

要创建一个消息处理程序，必须定义一个具有明确参数的静态无返回值的函数。例如，这是这个应用程序中的counthandler()消息处理函数的定义。

    17:    static void count_handler(Task t, MessageId id, Message payload)    18:    {      

The struct that has the message handler function pointer and associated variables for that message handler must be initialised before use. Here, it is intialised with the count_handler() function pointer and the initial value for thecount variable.

具有消息处理程序函数指针和消息处理程序相关变量的结构体必须在使用前被初始化。在这里，它被使用了counthandler()函数指针和该变量的初始值。

    47:    static CountTaskData count_task =     48:    {    49:        { count_handler },    50:        0    51:    };    

The main() function for an on-chip application must perform any intialisation and start any initial messaging. In this example it sends an initial message using MessageSend() to the count_handler() function with the message id UP (0), which indicates that the handler should increment the count.

一个芯片应用程序的main()函数必须执行任何初始化，并启动任何初始消息传递。在本例中，它使用MessageSend()函数向count_handler()函数发送一个初始消息，MessageSend()函数使用消息 id UP (0)，这表明处理程序应该增加计数。

    53:    int main(void)    54:    {    55:        MessageSend(    56:            &count_task.count_task,     /* Task the message is sent to */     57:            UP,                         /* Message Id */    58:            0 );                        /* Message Payload */    59:    60:        MessageLoop();    61:    62:        return 0;    63:    }    

The MessageLoop() function is the scheduler that deals with the message passing between on-chip VM applications and the firmware. This function never returns so any code after this function are redundent. However, the return 0;statement is still required for the main() function as omitting it will cause a compiler warning.

MessageLoop()函数是一个调度程序，它处理在芯片上的VM应用程序和固件之间传递的消息。这个函数永远不会返回，因此在这个函数之后的任何代码都是多余的。但是，return 0;main()函数仍然需要这条语句，因为省略它会导致编译器警告。

The intial message is received by the count_handler(). First the task pointer is cast to the message handlers own struct.

该消息是由count_handler()函数接收的。首先，任务指针被赋值为消息处理程序自身的结构体。

      19:  CountTaskData *ctd = (CountTaskData *) t;    

This allows the message handler to access its associated variables via the ctd; pointer.

这允许消息处理程序访问相关变量通过 the ctd;指针

The current count value is output using printf and then the count is incremented or decremented depending on whether the message id value is DOWN (0) or UP (1). If the limits of the count are reached then the direction of the count is changed.

当前的计数值是使用printf输出的，然后计数根据消息id值是否DOWN(0)或UP(1)而递增或下降，如果计数的限制被改变，那么计数的方向就会改变。

     21:   printf("Count %d\n", ctd->count);      22:    23:   if (DOWN == id)    24:   {    25:       ctd->count--;    26:   }    27:   else    28:   {    29:       ctd->count++;    30:   }    31:    32:   if (ctd->count == 10)    33:   {    34:       id = DOWN;    35:   }    36:   else if (ctd->count == 0)    37:   {    38:       id = UP;    39:   }    

The final action of the count_handler is to send a message to itself, to make the next increment or decrement and perpetuate the count.

计数处理程序的最后一个操作是向它自己发送消息，以便进行下一个递增或递减，并使计数持久。

    41:   MessageSend(    42:           t,           /* Task the message is sent to */    43:           id,          /* Message id */    44:           0);          /* Message Payload */    45:   }    

Summary(总结)

This applications demonstrates how to implement a message handler function and associate variables with that handler. It also introduces the MessageLoop() scheduler function that starts the message handling for the application and never returns. 

该应用程序演示了如何实现消息处理程序函数并将变量与该处理程序关联起来。它还引入了MessageLoop()调度器函数，它启动了应用程序的消息处理，并且永远不会返回。

---

Copyright Cambridge Silicon Radio Limited 2005-2014.版权剑桥硅无线电有限公司2005-2014年。

Part of BlueLab 6.4-Release

BlueLab 6.4发行版的一部分