SYS/BIOS
7.00
|
Mailbox Manager.
The Mailbox module makes available a set of functions that manipulate mailbox objects accessed through handles of type Mailbox_Handle.
Mailbox_pend is used to wait for a message from a mailbox. The timeout parameter to Mailbox_pend allows the task to wait until a timeout specified in terms of system clock ticks. A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message. A timeout value of BIOS_NO_WAIT causes Mailbox_pend to return immediately. Mailbox_pend's return value indicates whether the mailbox was signaled successfully.
When a Mailbox has been configured with a readerEvent Event object and a task has returned from Event_pend with the corresponding readerEventId, then BIOS_NO_WAIT should be passed to Mailbox_pend() to retrieve the message.
NOTE: Since only a single reader can pend on a readerEvent Event object, a Mailbox configured with a readerEvent Event object does not support multiple readers.
Mailbox_post is used to send a message to a mailbox. The timeout parameter to Mailbox_post specifies the amount of time the calling task waits if the mailbox is full.
When a Mailbox has been configured with a writerEvent Event object and a task has returned from Event_pend with the corresponding writerEventId, then BIOS_NO_WAIT should be passed to Mailbox_post() knowing that the message will be successfully posted.
To use the Mailbox module, the following must be added to the app.syscfg file:
NOTE: Since only a single writer can pend on a writerEvent Event object, a Mailbox configured with a writerEvent Event object does not support multiple writers.
Function | Hwi | Swi | Task | Main | Startup |
---|---|---|---|---|---|
Mailbox_Params_init | Y | Y | Y | Y | Y |
Mailbox_construct | N | N | Y | Y | N |
Mailbox_create | N | N | Y | Y | N |
Mailbox_delete | N | N | Y | Y | N |
Mailbox_destruct | N | N | Y | Y | N |
Mailbox_getNumFreeMsgs | Y | Y | Y | N | N |
Mailbox_getNumPendingMsgs | Y | Y | Y | N | N |
Mailbox_pend | N* | N* | Y | N* | N |
Mailbox_post | N* | N* | Y | N* | N |
Definitions: (N* means OK to call iff the timeout
parameter is set to '0'.)
|
#include <ti/sysbios/knl/Event.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Semaphore.h>
#include <ti/sysbios/runtime/Error.h>
Go to the source code of this file.
Data Structures | |
struct | Mailbox_Params |
struct | Mailbox_Struct |
Macros | |
#define | Mailbox_A_invalidBufSize "Mailbox_create's bufSize parameter is invalid (too small)" |
Assert raised when Mailbox_Params.bufSize is too small to handle (size of messages + sizeof(MbxElem)) * number of messages. See Mailbox_Params.buf for more information on the buf parameter. More... | |
Typedefs | |
typedef struct Mailbox_Params | Mailbox_Params |
typedef struct Mailbox_Struct | Mailbox_Object |
typedef struct Mailbox_Struct | Mailbox_Struct |
typedef struct Mailbox_Struct * | Mailbox_Handle |
Functions | |
Mailbox_Handle | Mailbox_create (size_t msgSize, unsigned int numMsgs, const Mailbox_Params *prms, Error_Block *eb) |
Create a mailbox. More... | |
Mailbox_Handle | Mailbox_construct (Mailbox_Struct *obj, size_t msgSize, unsigned int numMsgs, const Mailbox_Params *prms, Error_Block *eb) |
Construct a task. More... | |
void | Mailbox_delete (Mailbox_Handle *mailbox) |
Delete a mailbox. More... | |
void | Mailbox_destruct (Mailbox_Struct *obj) |
Destruct a mailbox. More... | |
size_t | Mailbox_getMsgSize (Mailbox_Handle mailbox) |
Get the message size. More... | |
int | Mailbox_getNumFreeMsgs (Mailbox_Handle mailbox) |
Get the number messages available for use. More... | |
int | Mailbox_getNumPendingMsgs (Mailbox_Handle mailbox) |
Get the number of messages that are ready to be read. More... | |
bool | Mailbox_pend (Mailbox_Handle mailbox, void *msg, uint32_t timeout) |
Wait for a message from mailbox. More... | |
bool | Mailbox_peek (Mailbox_Handle mailbox, void *msg, uint32_t timeout) |
Peek a message from the mailbox. More... | |
bool | Mailbox_post (Mailbox_Handle mailbox, void *msg, uint32_t timeout) |
Post a message to mailbox. More... | |
bool | Mailbox_putHead (Mailbox_Handle mailbox, void *msg, uint32_t timeout) |
Post a message to mailbox. More... | |
void | Mailbox_Params_init (Mailbox_Params *prms) |
Initialize the Mailbox_Params structure with default values. More... | |
Mailbox_Handle | Mailbox_Object_first (void) |
return handle of the first Mailbox on Mailbox list More... | |
Mailbox_Handle | Mailbox_Object_next (Mailbox_Handle mbx) |
return handle of the next Mailbox on Mailbox list More... | |
#define Mailbox_A_invalidBufSize "Mailbox_create's bufSize parameter is invalid (too small)" |
Assert raised when Mailbox_Params.bufSize is too small to handle (size of messages + sizeof(MbxElem)) * number of messages. See Mailbox_Params.buf for more information on the buf parameter.
typedef struct Mailbox_Params Mailbox_Params |
typedef struct Mailbox_Struct Mailbox_Object |
typedef struct Mailbox_Struct Mailbox_Struct |
typedef struct Mailbox_Struct* Mailbox_Handle |
Mailbox_Handle Mailbox_create | ( | size_t | msgSize, |
unsigned int | numMsgs, | ||
const Mailbox_Params * | prms, | ||
Error_Block * | eb | ||
) |
Create a mailbox.
Mailbox_create creates a mailbox object which is initialized to contain numMsgs messages of size msgSize.
msgSize | size of message |
numMsgs | length of mailbox |
prms | mailbox parameters |
eb | error block |
Mailbox | handle (NULL on failure) |
Mailbox_Handle Mailbox_construct | ( | Mailbox_Struct * | obj, |
size_t | msgSize, | ||
unsigned int | numMsgs, | ||
const Mailbox_Params * | prms, | ||
Error_Block * | eb | ||
) |
Construct a task.
Mailbox_construct is equivalent to Mailbox_create except that the Mailbox_Struct is pre-allocated. See Mailbox_create() for a description of this API.
obj | pointer to a Mailbox object |
msgSize | size of message |
numMsgs | length of mailbox |
prms | mailbox parameters |
eb | error block |
Mailbox | handle (NULL on failure) |
void Mailbox_delete | ( | Mailbox_Handle * | mailbox | ) |
Delete a mailbox.
Mailbox_delete deletes a Mailbox object. Note that Mailbox_delete takes a pointer to a Mailbox_Handle which enables Mailbox_delete to set the Mailbox_handle to NULL.
mailbox | pointer to Task handle |
void Mailbox_destruct | ( | Mailbox_Struct * | obj | ) |
Destruct a mailbox.
Mailbox_destruct destructs a Mailbox object.
obj | pointer to Mailbox object |
size_t Mailbox_getMsgSize | ( | Mailbox_Handle | mailbox | ) |
Get the message size.
mailbox | Mailbox handle |
mailbox | message size |
int Mailbox_getNumFreeMsgs | ( | Mailbox_Handle | mailbox | ) |
Get the number messages available for use.
mailbox | Mailbox handle |
mailbox | message size |
int Mailbox_getNumPendingMsgs | ( | Mailbox_Handle | mailbox | ) |
Get the number of messages that are ready to be read.
mailbox | Mailbox handle |
number | of pending messages |
bool Mailbox_pend | ( | Mailbox_Handle | mailbox, |
void * | msg, | ||
uint32_t | timeout | ||
) |
Wait for a message from mailbox.
If the mailbox is not empty, Mailbox_pend copies the first message into msg and returns true. Otherwise, Mailbox_pend suspends the execution of the current task until Mailbox_post is called or the timeout expires.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message.
A timeout value of BIOS_NO_WAIT causes Mailbox_pend to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_pend to retrieve a message after Event_pend() is called outside of Mailbox_pend to wait on an incoming message.
Mailbox_pend's return value indicates whether the mailbox was signaled successfully.
If the Mailbox object has been configured with an embedded readerEvent Event object, then prior to returnig from this function, the Event object's state is updated to reflect whether messages are available in the Mailbox after the current message is removed. If there are no more messages available, then the readerEventId is cleared in the Event object. If more messages are available, then the readerEventId is set in the Event object.
mailbox | Mailbox handle |
msg | message pointer |
timeout | maximum duration in system clock ticks |
true | if successful, false if timeout |
bool Mailbox_peek | ( | Mailbox_Handle | mailbox, |
void * | msg, | ||
uint32_t | timeout | ||
) |
Peek a message from the mailbox.
If the mailbox is not empty, Mailbox_peek copies the first message into msg and returns true. Otherwise, Mailbox_peek suspends the execution of the current task until Mailbox_post is called or the timeout expires. Unlike Mailbox_pend, Mailbox_peek does not remove the message from the queue after copying it to the destination.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message.
A timeout value of BIOS_NO_WAIT causes Mailbox_peek to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_peek to retrieve a message after Event_pend() is called outside of Mailbox_peek to wait on an incoming message.
Mailbox_peek's return value indicates whether the mailbox was signaled successfully.
If the Mailbox object has been configured with an embedded readerEvent Event object, then prior to returnig from this function, the Event object's state is updated to reflect whether messages are available in the Mailbox after the current message is removed. If there are no more messages available, then the readerEventId is cleared in the Event object. If more messages are available, then the readerEventId is set in the Event object.
mailbox | Mailbox handle |
msg | message pointer |
timeout | maximum duration in system clock ticks |
true | if successful, false if timeout |
bool Mailbox_post | ( | Mailbox_Handle | mailbox, |
void * | msg, | ||
uint32_t | timeout | ||
) |
Post a message to mailbox.
Mailbox_post checks to see if there are any free message slots before copying msg into the mailbox. Mailbox_post readies the first task (if any) waiting on the mailbox. If the mailbox is full and a timeout is specified the task remains suspended until Mailbox_pend is called or the timeout expires.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a free slot.
A timeout value of BIOS_NO_WAIT causes Mailbox_post to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_post() to post a message after Event_pend() is called outside of Mailbox_post to wait on an available message buffer.
Mailbox_post's return value indicates whether the msg was copied or not.
If the Mailbox object has been configured with an embedded writerEvent Event object, then prior to returnig from this function, the Event object's state is updated to reflect whether more messages can be posted to the Mailbox after the current message has been posted. If no more room is available, then the writerEventId is cleared in the Event object. If more room is available, then the writerEventId is set in the Event object.
mailbox | Mailbox handle |
msg | message pointer |
timeout | maximum duration in system clock ticks |
true | if successful, false if timeout |
bool Mailbox_putHead | ( | Mailbox_Handle | mailbox, |
void * | msg, | ||
uint32_t | timeout | ||
) |
Post a message to mailbox.
Mailbox_putHead checks to see if there are any free message slots before posting a msg to the head position of the mailbox. Mailbox_putHead readies the first task (if any) waiting on the mailbox. If the mailbox is full and a timeout is specified the task remains suspended until Mailbox_pend is called or the timeout expires. A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a free slot.
A timeout value of BIOS_NO_WAIT causes Mailbox_putHead to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_putHead() to post a message to the front of the mailbox after Event_pend() is called outside of Mailbox_putHead to wait on an available message buffer.
Mailbox_putHead's return value indicates whether the msg was copied or not.
If the Mailbox object has been configured with an embedded writerEvent Event object, then prior to returnig from this function, the Event object's state is updated to reflect whether more messages can be posted to the Mailbox after the current message has been posted. If no more room is available, then the writerEventId is cleared in the Event object. If more room is available, then the writerEventId is set in the Event object.
mailbox | Mailbox handle |
msg | message pointer |
timeout | maximum duration in system clock ticks |
true | if successful, false if timeout |
void Mailbox_Params_init | ( | Mailbox_Params * | prms | ) |
Initialize the Mailbox_Params structure with default values.
Mailbox_Params_init initializes the Mailbox_Params structure with default values. Mailbox_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.
prms | pointer to uninitialized params structure |
Mailbox_Handle Mailbox_Object_first | ( | void | ) |
return handle of the first Mailbox on Mailbox list
Return the handle of the first Mailbox on the create/construct list. NULL if no Mailbox instances have been created or constructed.
Mailbox | handle |
Mailbox_Handle Mailbox_Object_next | ( | Mailbox_Handle | mbx | ) |
return handle of the next Mailbox on Mailbox list
Return the handle of the next mailbox on the create/construct list. NULL if no more Mailboxs are on the list.
mbx | Mailbox handle |
Mailbox | handle |