ReadMe for Message Handlers and Scheduler Tutorial

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發行版的一部分