Queues in Nucleus SE: Einführung und Core Service Calls

View the RTOS Revealed series

Queues wurden in einem früheren Artikel eingeführt. Sie bieten ein flexibleres Mittel, einfache Messages zwischen Tasks zu passen, als Mailboxes.

Queues nutzen

In Nucleus SE werden Queues zur Build Time konfiguriert. Maximal 16 Queues dürfen für eine Applikation definiert werden. Wenn keine Queues konfiguriert sind, omittiert das RTOS alle Queue-bezogenen Data Structures und API Code, was das Binary lean hält.

Eine Queue ist einfach ein Array von Storage Slots, jedes groß genug, um ein einzelnes ADDR Data Item zu halten. Access ist synchronisiert, sodass multiple Tasks sicher enqueue und dequeue Messages können. Tasks können in eine Queue schreiben, bis alle Slots voll sind, und aus einer Queue in First-In-First-Out (FIFO) Order lesen. Versuche, an eine volle Queue zu senden oder von einer leeren zu empfangen, triggern einen Error oder Task Suspension, abhängig von API Optionen und Nucleus SE Konfiguration.

Queues vs. Pipes

Nucleus SE supportet auch Pipes, die primär in Message Size differieren. Während eine Queue ein einzelnes ADDR (typischerweise ein Pointer) transmitiert, trägt ein Pipe einen variable-length Block von Bytes; die Block Size ist zur Configuration Time fixiert. Pipes werden in einem zukünftigen Artikel in Tiefe diskutiert.

Queues konfigurieren

Anzahl Queues

Queue Konfiguration wird durch #define Statements in nuse_config.h kontrolliert. Die Schlüssel Setting ist NUSE_QUEUE_NUMBER, welche bestimmt, wie viele Queues enabled sind. Default ist 0 (keine Queues). Sie können es auf jeden Wert von 0 bis 16 setzen; ein Out-of-Range Wert triggert einen Compile-Time #error produziert von nuse_config_check.h.

Das Setzen von NUSE_QUEUE_NUMBER auf einen Non-Zero Wert aktiviert das Queue Subsystem, allokiert die notwendigen Data Structures und enabled die assoziierten API Calls.

API Enables

Jede Queue API Funktion hat ein Enabling #define Symbol in nuse_config.h:

NUSE_QUEUE_SEND NUSE_QUEUE_RECEIVE NUSE_QUEUE_JAM NUSE_QUEUE_RESET NUSE_QUEUE_INFORMATION NUSE_QUEUE_COUNT 

Standardmäßig sind alle auf FALSE gesetzt, disabling die entsprechenden Service Calls. Um ein particular API zu nutzen, setzen Sie sein Symbol auf TRUE. Enablen eines APIs während keine Queues konfiguriert sind (außer NUSE_Queue_Count(), das immer allowed ist) resultiert in Compile-Time Error. Wenn ein API in Code aufgerufen wird, der nicht enabled wurde, tritt ein Link-Time Error auf, weil die Implementation omitted ist.

#define NUSE_QUEUE_NUMBER 0 /* Number of queues in the system – 0‑16 */ /* Service call enablers */ #define NUSE_QUEUE_SEND FALSE #define NUSE_QUEUE_RECEIVE FALSE #define NUSE_QUEUE_JAM FALSE #define NUSE_QUEUE_RESET FALSE #define NUSE_QUEUE_INFORMATION FALSE #define NUSE_QUEUE_COUNT FALSE 

Queue Service Calls

Nucleus RTOS bietet zehn Queue-bezogene Service Calls, von denen sechs in Nucleus SE implementiert sind. Sie bieten folgende Funktionalität:

• Message senden – NUSE_Queue_Send()
• Message empfangen – NUSE_Queue_Receive()
• Message an Front jammen – NUSE_Queue_Jam()
• Queue resetten – NUSE_Queue_Reset()
• Queue Information abfragen – NUSE_Queue_Information()
• Anzahl konfigurierter Queues erhalten – NUSE_Queue_Count()
• Verbleibende Calls (Create, Delete, Enumerate, Broadcast) sind in Nucleus SE nicht verfügbar.

Die Implementation jedes APIs wird in den folgenden Sektionen detailliert diskutiert.

Writing und Reading Services

Die Kern Operationen auf einer Queue sind Writing (Sending) und Reading (Receiving). Writing an die Front einer Queue wird Jamming genannt. Nucleus RTOS und Nucleus SE exponieren jeweils drei Basic API Calls für diese Actions.

Writing zu einer Queue

Das RTOS API NU_Send_To_Queue() ist hochflexibel, erlaubend indefinite Suspension oder Timeout, wenn die Queue voll ist. Nucleus SE bietet die gleiche Funktion aber Suspending ist optional und Timeouts sind nicht supported. RTOS supportet auch Broadcast Operation, die in SE unavailable ist.

RTOS API: NU_Send_To_Queue()

Prototype:

STATUS NU_Send_To_Queue(NU_QUEUE *queue, VOID *message, UNSIGNED size, UNSIGNED suspend); 

Parameter:

• queue – Pointer zum user-supplied Queue Control Block
• message – Pointer zum zu sendenden Data
• size – Anzahl UNSIGNED Elements; muss Queue's Message Size matchen
• suspend – NU_NO_SUSPEND, NU_SUSPEND, oder ein Timeout Wert

Return Codes inkludieren NU_SUCCESS, NU_QUEUE_FULL, NU_TIMEOUT, und diverse Error Codes für Invalid Pointers oder Queue State.

SE API: NUSE_Queue_Send()

Prototype:

STATUS NUSE_Queue_Send(NUSE_QUEUE queue, ADDR *message, U8 suspend); 

Parameter:

• queue – Queue Index (ID)
• message – Pointer zum ADDR Wert zum Enqueue
• suspend – NUSE_NO_SUSPEND oder NUSE_SUSPEND

Return Values spiegeln die RTOS Funktion aber reflektieren SE's limitiertes Blocking Verhalten.

Implementation Overview

Wenn Blocking disabled ist, checked die Routine einfach auf Space und schreibt entweder den Wert oder returned NUSE_QUEUE_FULL. Mit Blocking enabled loopt die Funktion, suspending den Task, wenn die Queue voll ist, bis Space verfügbar wird oder ein Reset occurs. Die Implementation nutzt NUSE_Queue_Blocking_Count zum Tracken blocked Tasks und NUSE_Task_Blocking_Return zum Resumen, sobald ein Slot öffnet.

if (NUSE_Queue_Items[queue] == NUSE_Queue_Size[queue]) { return_value = NUSE_QUEUE_FULL; } else { NUSE_Queue_Data[queue][NUSE_Queue_Head[queue]++] = *message; if (NUSE_Queue_Head[queue] == NUSE_Queue_Size[queue]) NUSE_Queue_Head[queue] = 0; NUSE_Queue_Items[queue]++; return_value = NUSE_SUCCESS; } 

do { if (NUSE_Queue_Items[queue] == NUSE_Queue_Size[queue]) { if (suspend == NUSE_NO_SUSPEND) { return_value = NUSE_QUEUE_FULL; } else { NUSE_Queue_Blocking_Count[queue]++; NUSE_Suspend_Task(NUSE_Task_Active, (queue << 4) | NUSE_QUEUE_SUSPEND); return_value = NUSE_Task_Blocking_Return[NUSE_Task_Active]; if (return_value != NUSE_SUCCESS) suspend = NUSE_NO_SUSPEND; } } else { NUSE_Queue_Data[queue][NUSE_Queue_Head[queue]++] = *message; if (NUSE_Queue_Head[queue] == NUSE_Queue_Size[queue]) NUSE_Queue_Head[queue] = 0; NUSE_Queue_Items[queue]++; if (NUSE_Queue_Blocking_Count[queue] != 0) { U8 index; NUSE_Queue_Blocking_Count[queue]--; for (index = 0; index < NUSE_TASK_NUMBER; index++) { if ((LONIB(NUSE_Task_Status[index]) == NUSE_QUEUE_SUSPEND) && (HINIB(NUSE_Task_Status[index]) == queue)) { NUSE_Task_Blocking_Return[index] = NUSE_SUCCESS; NUSE_Wake_Task(index); break; } } } return_value = NUSE_SUCCESS; suspend = NUSE_NO_SUSPEND; } } while (suspend == NUSE_SUSPEND); 

Der Loop continued bis eine Message erfolgreich enqueued wird oder der Task durch einen Reset unblocked wird. Die Implementation ensures Thread-Safe Access und effizientes Wake-up von blocked Consumers.