Mailboxes in Nucleus SE: Praktischer Guide zu Konfiguration und Nutzung

View the RTOS Revealed series

Mailboxes wurden in einem früheren Artikel als einer der unkompliziertesten Inter-Task Communication Mechanismen in Nucleus SE eingeführt – direkt nach Signals. Sie bieten einen Low-Cost, hochflexiblen Weg, einfache Daten zwischen Tasks zu transferieren.

Mailboxes nutzen

In Nucleus SE werden Mailboxes zur Build-Zeit definiert. Maximal 16 Mailboxes können pro Applikation konfiguriert werden. Wenn Sie null Mailboxes konfigurieren, omittiert der Compiler alle zugehörigen Data Structures und API Code, was das Binary lean hält.

Eine Mailbox ist im Wesentlichen ein Storage Slot, der eine einzelne Variable vom Typ ADDR halten kann. Nur ein Task darf zur Zeit in eine Mailbox schreiben. Einmal voll, werden weitere Write Versuche fehlschlagen, bis die Mailbox gelesen oder resetet wird. Abhängig von API Optionen kann ein Versuch, in eine volle Mailbox zu schreiben, einen Error returnen oder den Task suspenden, bis Platz verfügbar wird.

Mailboxes vs. Queues

Einige Operating Systems ersetzen Mailboxes mit Single-Entry Queues. Während eine Queue das Verhalten einer Mailbox mimiken kann, trägt sie Extra Overhead – Head und Tail Pointers, größere Data Structures, mehr Code Paths – was zu höherem Memory Usage und Execution Time führt.

In Nucleus SE können Sie entweder Mailboxes oder Queues wählen. Wenn Ihr Design viele Queues aber wenige Mailboxes nutzt, wird das Tauschen einer Mailbox für eine Queue die Data Size leicht erhöhen, aber Mailbox-spezifischen API Code entfernen, was Maintenance vereinfacht. Es ist einfach, beide Konfigurationen zu testen, um Memory Footprint und Performance zu vergleichen.

Queues werden in einem zukünftigen Artikel behandelt.

Mailboxes konfigurieren

Anzahl Mailboxes

Der Schlüssel Macro in nuse_config.h ist NUSE_MAILBOX_NUMBER. Der Default Wert ist 0, was bedeutet, keine Mailboxes sind enabled. Sie können es auf jedes Integer zwischen 1 und 16 setzen. Ein Compile-Time Check in nuse_config_check.h triggert einen Error, wenn der Wert out of range ist.

Ein Non-Zero Wert aktiviert das Mailbox Subsystem: Data Structures werden gesized, und API Enabling Symbols werden verarbeitet.

API Enables

Jeder Mailbox API Call hat ein entsprechendes #define in nuse_config.h:

• NUSE_MAILBOX_SEND
• NUSE_MAILBOX_RECEIVE
• NUSE_MAILBOX_RESET
• NUSE_MAILBOX_INFORMATION
• NUSE_MAILBOX_COUNT

Standardmäßig sind alle auf FALSE gesetzt, was den Call und seine Implementation disabled. Um ein API zu nutzen, enablen Sie das entsprechende Macro, indem Sie es auf TRUE setzen. Enablen eines APIs ohne konfigurierte Mailboxes verursacht einen Compile-Time Error (außer NUSE_Mailbox_Count(), das immer verfügbar ist). Nutzung eines disabled APIs produziert einen Link-Time Error.

/* 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 

Mailbox Service Calls

Nucleus SE bietet neun Mailbox-bezogene Service Calls. Die in SE implementierten sind:

• NUSE_Mailbox_Send() – Nachricht in Mailbox schreiben.
• NUSE_Mailbox_Receive() – Nachricht aus Mailbox lesen.
• NUSE_Mailbox_Reset() – Mailbox clearen ohne Tasks zu suspenden.
• NUSE_Mailbox_Information() – Status einer Mailbox abfragen.
• NUSE_Mailbox_Count() – Anzahl konfigurierter Mailboxes zurückgeben.

Andere Funktionen wie Creation, Deletion, Bulk Retrieval und Broadcast sind in SE nicht implementiert.

Write und Read Operationen

Mailboxes unterstützen zwei Kernoperationen: Sending (Writing) und Receiving (Reading). Beide APIs sind in Nucleus RTOS und Nucleus SE verfügbar, mit einigen Unterschieden in Flexibilität und Error Handling.

Sending an eine Mailbox

In Nucleus RTOS unterstützt der NU_Send_To_Mailbox Call indefinite oder timed Suspension, wenn die Mailbox voll ist. Nucleus SE bietet eine vereinfachte Version: Suspension ist optional und Timeouts werden nicht unterstützt.

Sample Prototype für Nucleus SE:

STATUS NUSE_Mailbox_Send(NUSE_MAILBOX mailbox, ADDR *message, U8 suspend);

Parameter:

• mailbox – Mailbox Index.
• message – Pointer auf eine ADDR Variable.
• suspend – NUSE_NO_SUSPEND oder NUSE_SUSPEND.

Return Values inkludieren NUSE_SUCCESS, NUSE_INVALID_MAILBOX, NUSE_MAILBOX_FULL, und NUSE_MAILBOX_WAS_RESET.

Implementation Overview

Wenn Blocking disabled ist, prüft die Routine den Mailbox Status Flag. Wenn die Mailbox leer ist, schreibt sie die Data und markiert die Mailbox als voll; andernfalls returned sie NUSE_MAILBOX_FULL.

Mit Blocking enabled loopt der Code, bis die Message erfolgreich gepostet wurde oder der Task durch eine Receive Operation geweckt wird. Wenn ein Task auf der Mailbox suspended ist, wird er sofort nach erfolgreichem Send resumed.

Der folgende Auszug demonstriert die Kernlogik, wenn Blocking enabled ist (vereinfacht für Lesbarkeit):

do { if (!NUSE_Mailbox_Status[mailbox]) { // Mailbox leer – Data speichern und wartenden Task wecken falls vorhanden. } else if (suspend == NUSE_NO_SUSPEND) { return NUSE_MAILBOX_FULL; } else { // Task suspenden bis Mailbox leer wird. } } while (suspend == NUSE_SUSPEND); 

Zusammenfassend balanciert die Mailbox API Simplicity und Flexibilität, indem sie Entwicklern die Wahl zwischen immediate Failure oder Task Suspension basierend auf ihrer Applikation's Timing Requirements lässt.