RTOSについての真実。 記事＃21。 メールボックス：紹介と基本サービス

メールボックスは、以前の記事（＃5）のいずれかで言及されました。 Nucleus SEでサポートされている2番目に簡単な信号対信号マルチタスク方式であり、タスク間で簡単なメッセージを転送するための低コストで柔軟な方法を提供します。

シリーズの以前の記事：
記事20。 セマフォ：補助サービスとデータ構造
記事＃19。 セマフォ：紹介と基本サービス
記事＃18。 イベントフラググループ：ヘルパーサービスとデータ構造
記事＃17。 イベントフラググループ：紹介と基本サービス
記事＃16。 信号
記事＃15。 メモリパーティション：サービスとデータ構造
記事＃14。 メモリのセクション：紹介と基本サービス
記事＃13。 タスクデータ構造とサポートされていないAPI呼び出し
記事＃12。 タスクを操作するためのサービス
記事＃11。 タスク：APIの構成と紹介
記事＃10。 スケジューラ：高度な機能とコンテキストの保存
記事＃9。 スケジューラ：実装
記事＃8。 Nucleus SE：内部設計と展開
記事＃7。 Nucleus SE：はじめに
記事＃6。 その他のRTOSサービス
記事5。 タスクの相互作用と同期
記事4。 タスク、コンテキストの切り替え、および割り込み
記事＃3。 タスクと計画
記事＃2。 RTOS：構造とリアルタイム
記事＃1。 RTOS：はじめに。

メールボックスを使用する

Nucleus SEでは、メールボックスはビルドフェーズ中に定義されます。 アプリケーションは最大16個のメールボックスを持つことができます。 アプリケーションにメールボックスがない場合、メールボックスに関連付けられたサービス呼び出しコードとデータ構造はアプリケーションに含まれません。

メールボックスはデータを保存する場所であり、そのサイズはADDR型の変数を保存するのに十分なサイズであり、複数のタスクが使用できるようにアクセスを制御します。 タスクはデータをメールボックスに送信できます。 その結果、メールボックスがいっぱいになり、一部のタスクがメールボックスの読み取り操作を実行するか、メールボックスが空になるまで、タスクはデータを送信できなくなります。 完全なメールボックスにデータを送信しようとしたり、空のメールボックスを読み取ろうとすると、選択したAPIコール設定とNucleus SEの構成に応じて、エラーまたはタスクの中断が発生します。

メールボックスとキュー

OSの一部の実装では、メールボックスは実装されていませんが、代わりにキューを使用することが提案されています。 このようなキューはメールボックスと同じ機能を提供するため、これは論理的に聞こえます。 ただし、キューはより複雑なデータ構造であり、より多くの補助データ、コードを保持し、サービス時間が長くなります。

Nucleus RTOSと同様に、Nucleus SEでは、これらのタイプのオブジェクトのいずれかを選択できます。
アプリケーションに複数のキューと1つのメールボックスがある場合、メールボックスをキューに置き換えることを検討するのは理にかなっています。 これにより、オーバーヘッドの量はわずかに増加しますが、メールボックスに関連付けられているすべてのAPIコードが削除されます。 または、両方の方法でアプリケーションを構成し、データ量とパフォーマンスを比較できます。

キューについては、今後の記事で説明します。

メールボックスを構成する

メールボックスの数

ほとんどのNucleus SEオブジェクトと同様に、メールボックスの構成は主にnuse_config.hファイルの#defineディレクティブによって定義されます。 メインパラメータはNUSE_MAILBOX_NUMBERで、アプリケーション内のメールボックスの数を決定します。 デフォルト値はゼロ（つまり、メールボックスがない）で、最大16の値を取ることができます。誤った値は、コンパイル中にエラーになります。エラーは、 nuse_config_check.hでチェックして生成されます。 ）、 ＃errorディレクティブをトリガーします。

ゼロ以外の値を選択することが、メールボックスの主要なアクティベーターです。 このパラメーターは、データ構造を定義するときに使用され、そのサイズはその値に依存します（これについては次の記事で詳しく説明します）。 さらに、ゼロ以外の値はAPI設定をアクティブにします。

API呼び出しをアクティブにする

Nucleus SEの各API関数（ユーティリティ呼び出し）は、 nuse_config.hファイルの#defineディレクティブによってアクティブにされます。 メールボックスの場合、これらのディレクティブは次のとおりです。

NUSE_MAILBOX_SEND NUSE_MAILBOX_RECEIVE NUSE_MAILBOX_RESET NUSE_MAILBOX_INFORMATION NUSE_MAILBOX_COUNT 

デフォルトでは、これらはFALSEに設定されているため、すべてのサービス呼び出しが無効になり、それらを実装するコードの組み込みがブロックされます。 アプリケーションでメールボックスを構成するには、必要なAPI呼び出しを選択してTRUEに設定する必要があります。

以下は、 nuse_config.hファイルのコードのセクションです。

 /* Number of mailboxes in the system - 0-16 */ #define NUSE_MAILBOX_NUMBER 0 /* Service call enablers: */ #define NUSE_MAILBOX_SEND FALSE #define NUSE_MAILBOX_RECEIVE FALSE #define NUSE_MAILBOX_RESET FALSE #define NUSE_MAILBOX_INFORMATION FALSE #define NUSE_MAILBOX_COUNT FALSE 

メールボックスAPI機能がアクティブで、アプリケーションにメールボックスがない場合（常に有効になっているNUSE_Mailbox_Count（）を除く）、コンパイルエラーが発生します。 アクティブ化されていないAPI呼び出しをコードで使用すると、アプリケーションに実装コードが含まれていなかったため、レイアウトエラーが発生します。

メールボックスサービスの呼び出し

Nucleus RTOSは、メールボックスに関連付けられた9つのサービスコールをサポートし、次の機能を提供します。

• メールボックスにメッセージを送信します。 Nucleus SEはNUSE_Mailbox_Send（）関数に実装されています。
• メールボックスからメッセージを読む。 Nucleus SEはNUSE_Mailbox_Receive（）関数を実装しています。
• 中断されたすべてのタスクのリリースでメールボックスを未使用状態に復元する（リセット）。 Nucleus SEはNUSE_Mailbox_Reset（）に実装されています。
• 特定のメールボックスに関する情報を提供します。 Nucleus SEはNUSE_Mailbox_Information（）を実装しています。
• アプリケーションで現在構成されているメールボックスの数を返します。 Nucleus SEでは、 NUSE_Mailbox_Count（）で実装されています。
• 新しいメールボックスの追加（作成）。 Nucleus SEは実装されていません。
• メールボックスを削除します。 Nucleus SEは実装されていません。
• アプリケーション内のすべてのメールボックスへのポインターを返します。 Nucleus SEは実装されていません。
• メールボックスで中断されているすべてのタスクにメッセージを送信する（ブロードキャスト）。 Nucleus SEは実装されていません。

各サービス呼び出しの実装を詳細に検討してください。

メールボックスの読み取りおよび書き込みサービスコール

メールボックスで実行できる基本的な操作は、データの書き込みと読み取り（送信と受信）です。 Nucleus RTOSおよびNucleus SEは、これらの操作のための2つの基本的なAPI呼び出しを提供します。これについては以下で説明します。

メールボックスに書き込む

Nucleus RTOS APIを呼び出してメールボックスに書き込むのは非常に柔軟です。これにより、操作をすぐに完了できない場合（たとえば、満杯のメールボックスに書き込む場合）に暗黙的にまたはタイムアウトでタスクを一時停止できます。 Nucleus SEは同様のサービスコールを提供します。タスクの一時停止のみがオプションであり、タイムアウトは実装されていません。

Nucleus RTOSは、データをメールボックスにブロードキャストするためのサービスコールも提供します;このコールはNucleus SEではサポートされておらず、次の記事の「Unrealized APIコール」セクションで説明します。

Nucleus RTOSのメールボックスに書き込むための呼び出し
サービスコールのプロトタイプ：
STATUS NU_Send_To_Mailbox（NU_MAILBOX *メールボックス、VOID *メッセージ、UNSIGNEDサスペンド）;

パラメータ：
メールボックス - メールボックスへのポインタ。
message-送信されるメッセージへのポインター。unsigned型の4つの要素で構成されます。
suspend-タスクの一時停止の仕様。値NU_NO_SUSPEND 、 NU_SUSPENDまたはタイムアウト値を取ることができます。

戻り値：
NU_SUCCESS-呼び出しは正常に完了しました。
NU_INVALID_MAILBOX-無効なメールボックスポインター。
NU_INVALID_POINTER-メッセージへのNULLポインター（ NULL ）;
NU_INVALID_SUSPEND-非タスク関連スレッドからの中断の試行。
NU_MAILBOX_FULL-メールボックスはいっぱいですが、一時停止のタイプは指定されていません。
NU_TIMEOUT-メールボックスは、指定された期間の一時停止後もまだいっぱいです。
NU_MAILBOX_DELETED-タスクが中断されている間にメールボックスが削除されました。
NU_MAILBOX_WAS_RESET-タスクの中断中にメールボックスがリセットされました。

Nucleus SEのメールボックスに書き込むための呼び出し
このAPIコールは、Nucleus RTOS APIのコア機能をサポートしています。

サービスコールのプロトタイプ：
STATUS NUSE_Mailbox_Send（NUSE_MAILBOXメールボックス、ADDR *メッセージ、U8サスペンド）;

パラメータ：
メールボックス - メールボックスインデックス（ID）。
message-送信されるメッセージへのポインター;これはADDRタイプの1つの変数です。
suspend-タスクの中断の指定 。値NUSE_NO_SUSPENDまたはNUSE_SUSPENDを取ることができます。

戻り値：
NUSE_SUCCESS-呼び出しは正常に完了しました。
NUSE_INVALID_MAILBOX-無効なメールボックスインデックス。
NUSE_INVALID_POINTER-メッセージへのNULLポインター（ NULL ）;
NUSE_INVALID_SUSPEND-関連のないスレッドからの中断の試み、またはAPI呼び出しのブロック機能が無効になっている場合。
NUSE_MAILBOX_FULL-メールボックスはいっぱいですが、一時停止のタイプは指定されていません。
NUSE_MAILBOX_WAS_RESET-タスクの中断中にメールボックスがリセットされました。

Nucleus SEでのメールボックス書き込みの実装
API関数コードNUSE_Mailbox_Send（）のバージョン（パラメーターの確認後）は、API呼び出しのサポートがブロック（タスクの中断）のためにアクティブになっているかどうかに応じて、条件付きコンパイルを使用して選択されます。 両方のオプションを検討してください。

タスクのロックが無効になっている場合、このAPI呼び出しのロジックは非常に単純で、コードの説明は不要です。

 if (NUSE_Mailbox_Status[mailbox]) /* mailbox full */ { return_value = NUSE_MAILBOX_FULL; } else /* mailbox empty */ { NUSE_Mailbox_Data[mailbox] = *message; NUSE_Mailbox_Status[mailbox] = TRUE; return_value = NUSE_SUCCESS; } 

メッセージは対応する要素NUSE_Mailbox_Data []に保存され、メールボックスは使用済みとしてマークされます。

タスクのロックが有効になっている場合、コードはより複雑になります。

 do { if (!NUSE_Mailbox_Status[mailbox]) /* mailbox empty */ { NUSE_Mailbox_Data[mailbox] = *message; NUSE_Mailbox_Status[mailbox] = TRUE; if (NUSE_Mailbox_Blocking_Count[mailbox] != 0) { U8 index; /* check whether a task is blocked */ /* on this mailbox */ NUSE_Mailbox_Blocking_Count[mailbox]--; for (index=0; index<NUSE_TASK_NUMBER; index++) { if ((LONIB(NUSE_Task_Status[index]) == NUSE_MAILBOX_SUSPEND) && (HINIB(NUSE_Task_Status[index]) == mailbox)) { NUSE_Task_Blocking_Return[index] = NUSE_SUCCESS; NUSE_Wake_Task(index); break; } } } return_value = NUSE_SUCCESS; suspend = NUSE_NO_SUSPEND; } else /* mailbox full */ { if (suspend == NUSE_NO_SUSPEND) { return_value = NUSE_MAILBOX_FULL; } else { /* block task */ NUSE_Mailbox_Blocking_Count[mailbox]++; NUSE_Suspend_Task(NUSE_Task_Active, (mailbox << 4) | NUSE_MAILBOX_SUSPEND); return_value = NUSE_Task_Blocking_Return[NUSE_Task_Active]; if (return_value != NUSE_SUCCESS) { suspend = NUSE_NO_SUSPEND; } } } } while (suspend == NUSE_SUSPEND); 

いくつかの説明が役立つ場合があります。

コードはdo ... whileループで囲まれています。このループは、 suspendパラメーターがNUSE_SUSPENDの間に実行されます。

メールボックスが空の場合、メッセージが記録され、メールボックスのステータスが変化して、メールボックスがいっぱいであることを示します。 このメールボックスで一時停止中のタスク（読み取り待ち）をチェックします。 そのようなタスクがある場合、最初のタスクが再開されます。 サスペンド変数はNUSE_NO_SUSPENDに設定され、API呼び出しは終了してNUSE_SUCCESSを返します。

メールボックスがいっぱいでサスペンドがNUSE_NO_SUSPENDの場合、API呼び出しはNUSE_MAILBOX_FULLを返します 。 suspendがNUSE_SUSPENDの場合、タスクは一時停止します。 関数が終了した後（タスクの再開時など）、戻り値がNUSE_SUCCESS （メールボックスがリセットされたのではなく、メッセージが読み取られたためにタスクが再開されたことを示す）の場合、サイクルは最初から始まります。

メールボックスを読む

メールボックスを読み取るためのNucleus RTOS APIユーティリティコールは非常に柔軟性があり、操作をすぐに完了できない場合（空のメールボックスから読み取る場合など）に暗黙的にまたはタイムアウトでタスクを一時停止できます。 Nucleus SEは同様のサービスを提供します。タスクの一時停止のみがオプションであり、タイムアウトは実装されていません。

Nucleus RTOSでメールボックスを読み取るための呼び出し
サービスコールのプロトタイプ：
STATUS NU_Receive_From_Mailbox（NU_MAILBOX *メールボックス、VOID *メッセージ、UNSIGNEDサスペンド）;

パラメータ：
メールボックス -ユーザーが提供するメールボックスコントロールユニットへのポインタ。
message-受信メッセージのストレージへのポインタ。サイズはunsigned型の4つの変数に等しくなります。
suspend-タスクの一時停止の仕様。値NUSE_NO_SUSPEND 、 NUSE_SUSPENDまたはタイムアウト値を取ることができます。

戻り値：
NU_SUCCESS-呼び出しは正常に完了しました。
NU_INVALID_MAILBOX-無効なメールボックスポインター。
NU_INVALID_POINTER-メッセージへのNULLポインター（ NULL ）;
NU_INVALID_SUSPEND-無効なストリーム（ストリームのタスクに関連付けられていない）からの中断を試みます。
NU_MAILBOX_EMPTY-メールボックスは空であり、一時停止のタイプは指定されていません。
NU_TIMEOUT-指定されたタイムアウト値でタスクが一時停止された後でも、メールボックスは空のままです。
NU_MAILBOX_DELETED-タスクが中断されている間にメールボックスが削除されました。
NU_MAILBOX_WAS_RESET-タスクの中断中にメールボックスがリセットされました。

Nucleus SEでメールボックスを読み取るための呼び出し
このAPIコールは、Nucleus RTOS APIのコア機能をサポートしています。

サービスコールのプロトタイプ：
STATUS NUSE_Mailbox_Receive（NUSE_MAILBOXメールボックス、ADDR *メッセージ、U8サスペンド）;

パラメータ：
メールボックス - メールボックスインデックス（ID）。
message-受信したメッセージのストレージへのポインタは、タイプADDRの 1つの変数です。
suspend-タスクの中断の指定 。値NUSE_NO_SUSPENDまたはNUSE_SUSPENDを取ることができます。

戻り値：
NUSE_SUCCESS-呼び出しは正常に完了しました。
NUSE_INVALID_MAILBOX-無効なメールボックスインデックス。
NUSE_INDALID_POINTER-メッセージへのNULLポインター（ NULL ）;
NUSE_INVALID_SUSPEND-不正なストリームからの中断の試行、またはタスクをブロックするためにAPI呼び出しが無効になっている場合。
NUSE_MAILBOX_EMPTY-メールボックスは空で、タスクの一時停止の種類は指定されていません。
NUSE_MAILBOX_WAS_RESET-タスクの中断中にメールボックスがリセットされました。

Nucleus SEでのメールボックスリーダーの実装
API関数コードNUSE_Mailbox_Receive（） （パラメーターのチェック後）のバージョンは、API呼び出しがブロック（タスクの中断）のためにアクティブになっているかどうかに応じて、条件付きコンパイルを使用して選択されます。 両方のオプションを検討します。

タスクのロックが無効になっている場合、このAPI呼び出しのロジックは非常に単純で、コードの説明は不要です。

 if (!NUSE_Mailbox_Status[mailbox]) /* mailbox empty */ { return_value = NUSE_MAILBOX_EMPTY; } else { /* mailbox full */ *message = NUSE_Mailbox_Data[mailbox]; NUSE_Mailbox_Status[mailbox] = FALSE; return_value = NUSE_SUCCESS; } 

メッセージは対応するNUSE_Mailbox_Data []要素から読み取られ、メールボックスは空としてマークされます。

タスクのロックが有効になっている場合、コードはより複雑になります。

 do { if (NUSE_Mailbox_Status[mailbox]) /* mailbox full */ { *message = NUSE_Mailbox_Data[mailbox]; NUSE_Mailbox_Status[mailbox] = FALSE; if (NUSE_Mailbox_Blocking_Count[mailbox] != 0) { U8 index; /* check whether a task is blocked */ /* on this mailbox */ NUSE_Mailbox_Blocking_Count[mailbox]--; for (index=0; index<NUSE_TASK_NUMBER; index++) { if ((LONIB(NUSE_Task_Status[index]) == NUSE_MAILBOX_SUSPEND) && (HINIB(NUSE_Task_Status[index]) == mailbox)) { NUSE_Task_Blocking_Return[index] = NUSE_SUCCESS; NUSE_Wake_Task(index); break; } } } return_value = NUSE_SUCCESS; suspend = NUSE_NO_SUSPEND; } else /* mailbox empty */ { if (suspend == NUSE_NO_SUSPEND) { return_value = NUSE_MAILBOX_EMPTY; } else { /* block task */ NUSE_Mailbox_Blocking_Count[mailbox]++; NUSE_Suspend_Task(NUSE_Task_Active, (mailbox << 4) | NUSE_MAILBOX_SUSPEND); return_value = NUSE_Task_Blocking_Return[NUSE_Task_Active]; if (return_value != NUSE_SUCCESS) { suspend = NUSE_NO_SUSPEND; } } } } while (suspend == NUSE_SUSPEND); 

いくつかの説明が役立つ場合があります。

コードはdo ... whileループで囲まれています。このループは、 suspendパラメーターがNUSE_SUSPENDの間に実行されます。

メールボックスがいっぱいの場合、保存されたメッセージが返され、メールボックスの状態が変化して空であることを示します。 このメールボックスで一時停止されたタスク（記録を待機している）を確認します。 そのようなタスクがある場合、最初のタスクが再開されます。 サスペンド変数はNUSE_NO_SUSPENDに設定され、API呼び出しは終了してNUSE_SUCCESSを返します。

メールボックスが空で、 サスペンドパラメータがNUSE_NO_SUSPENDの場合、API呼び出しはNUSE_MAILBOX_EMPTYを返します。 suspendがNUSE_SUSPENDの場合、タスクは一時停止します。 呼び出しの終わりに戻り値がNUSE_SUCCESSである場合、メッセージが送信されたためにタスクが再開されたことを示します（メールボックスがリセットされたことではありません）。サイクルは最初から始まります。

次の記事では、メールボックスに関連付けられた追加のAPI呼び出しと、対応するデータ構造を調べます。

著者について： Colin Wallsは電子業界で30年以上働いており、ほとんどの時間をファームウェアに費やしています。 現在、Mentor Embedded（Mentor Graphicsの一部門）のファームウェアエンジニアです。 Colin Wallsは、カンファレンスやセミナー、多くの技術記事の著者、ファームウェアに関する2冊の本でよく話します。 英国に住んでいます。 Colinのプロフェッショナルブログ 、電子メール：colin_walls@mentor.com。