The Mailbox module makes available a set of functions that manipulate
mailbox objects accessed through handles of type Mailbox_Handle.
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.
struct Mailbox_MbxElem |
|
The header used to save each Mailbox message
typedef struct Mailbox_MbxElem {
} Mailbox_MbxElem;
DETAILS
Mailbox messages are stored in a queue that requires a header in
front of each message. This structure defines that header and its
size must be factored into the total data size requirements for a
mailbox instance.
config Mailbox_A_invalidBufSize // module-wide |
|
Assert raised when the bufSize parameter is too small
extern const Assert_Id Mailbox_A_invalidBufSize;
DETAILS
This assert is raised when bufSize is too small to handle
(size of messages + sizeof(MbxElem)) * number of messages.
See
ti.sysbios.knl.MailBox.buf for more information on the buf
parameter.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Mailbox_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Mailbox_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Mailbox_Module_getMask();
// Returns the diagnostics mask for this module
Void Mailbox_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct Mailbox_Object Mailbox_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Mailbox_Struct Mailbox_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct Mailbox_Params {
// Instance config-params structure
// Common per-instance configs
Ptr buf;
// The address of the buffer used for creating messages
UInt bufSize;
// The size of the buffer that 'buf' references
// The IHeap instance used for dynamic creates
// Mailbox not empty event if using Events. Default is null
UInt readerEventId;
// Mailbox not empty event Id if using Events. Default is 1
// Mailbox not full event if using Events. Default is null
UInt writerEventId;
// Mailbox not full event Id if using Events
} Mailbox_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Mailbox_buf // instance |
|
The address of the buffer used for creating messages
DETAILS
This property is only used for dynamically created Mailboxes.
If set to 'null', the messages will be allocated from the heap
during runtime, otherwise the user may set this to a buffer of their
creation to be used for allocating the messages.
The module will split the buf into
ti.sysbios.knl.Mailbox.numMsgs number of blocks (one block per
Mailbox message).
Please note that if the buffer is user supplied, then it is the user's
responsibility to ensure that it is aligned properly and is also large
enough to contain
ti.sysbios.knl.Mailbox.numMsgs number of
blocks. The size of each block is defined as follows:
sizeof(Mailbox_MbxElem) + msgSize
Since the buffer must be a aligned properly, it may be necessary to
'round up' the total size of the buffer to the next multiple of the
alignment for odd sized messages.
SEE
config Mailbox_bufSize // instance |
|
The size of the buffer that 'buf' references
DETAILS
This property is only used for dynamically created Mailboxes.
config Mailbox_heap // instance |
|
The IHeap instance used for dynamic creates
DETAILS
This heap is used only for dynamic instances is ignored for static
instances.
config Mailbox_readerEvent // instance |
|
Mailbox not empty event if using Events. Default is null
DETAILS
Posted whenever a mailbox is written to.
Reader task pends on this event.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
config Mailbox_readerEventId // instance |
|
Mailbox not empty event Id if using Events. Default is 1
DETAILS
Posted whenever a mailbox is written to.
Reader task pends on this eventId.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
config Mailbox_writerEvent // instance |
|
Mailbox not full event if using Events. Default is null
DETAILS
Posted whenever a mailbox is read from.
Writer task pends on this event.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
config Mailbox_writerEventId // instance |
|
Mailbox not full event Id if using Events
DETAILS
Posted whenever a mailbox is read from.
Writer task pends on this eventId.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
msgSize
size of message
numMsgs
length of mailbox
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Mailbox_create creates a mailbox object which is initialized to contain
numMsgs messages of size msgSize.
Instance Deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Mailbox_getMsgSize() // instance |
|
Get the message size
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
Mailbox_getNumFreeMsgs() // instance |
|
Get the number messages available for use
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
Mailbox_getNumPendingMsgs() // instance |
|
Get the number of messages that are ready to be read
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
Mailbox_pend() // instance |
|
Wait for a message from mailbox
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
msg
message pointer
timeout
maximum duration in system clock ticks
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
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.
Mailbox_post() // instance |
|
Post a message to mailbox
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
msg
message pointer
timeout
maximum duration in system clock ticks
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
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.
Instance Built-Ins |
|
Int Mailbox_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
struct Mailbox.MbxElem |
|
The header used to save each Mailbox message
var obj = new Mailbox.MbxElem;
DETAILS
Mailbox messages are stored in a queue that requires a header in
front of each message. This structure defines that header and its
size must be factored into the total data size requirements for a
mailbox instance.
C SYNOPSIS
config Mailbox.A_invalidBufSize // module-wide |
|
Assert raised when the bufSize parameter is too small
msg: "Mailbox_create's bufSize parameter is invalid (too small)"
};
DETAILS
This assert is raised when bufSize is too small to handle
(size of messages + sizeof(MbxElem)) * number of messages.
See
ti.sysbios.knl.MailBox.buf for more information on the buf
parameter.
C SYNOPSIS
metaonly config Mailbox.common$ // module-wide |
|
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
Instance Config Parameters |
|
var params = new Mailbox.Params;
// Instance config-params object
params.buf = Ptr null;
// The address of the buffer used for creating messages
params.bufSize = UInt 0;
// The size of the buffer that 'buf' references
// The IHeap instance used for dynamic creates
// Mailbox not empty event if using Events. Default is null
params.readerEventId = UInt 1;
// Mailbox not empty event Id if using Events. Default is 1
params.sectionName = String null;
// Section name for the buffer managed by the instance
// Mailbox not full event if using Events. Default is null
params.writerEventId = UInt 1;
// Mailbox not full event Id if using Events
config Mailbox.buf // instance |
|
The address of the buffer used for creating messages
var params = new Mailbox.Params;
...
params.buf = Ptr null;
DETAILS
This property is only used for dynamically created Mailboxes.
If set to 'null', the messages will be allocated from the heap
during runtime, otherwise the user may set this to a buffer of their
creation to be used for allocating the messages.
The module will split the buf into
ti.sysbios.knl.Mailbox.numMsgs number of blocks (one block per
Mailbox message).
Please note that if the buffer is user supplied, then it is the user's
responsibility to ensure that it is aligned properly and is also large
enough to contain
ti.sysbios.knl.Mailbox.numMsgs number of
blocks. The size of each block is defined as follows:
sizeof(Mailbox_MbxElem) + msgSize
Since the buffer must be a aligned properly, it may be necessary to
'round up' the total size of the buffer to the next multiple of the
alignment for odd sized messages.
SEE
C SYNOPSIS
config Mailbox.bufSize // instance |
|
The size of the buffer that 'buf' references
var params = new Mailbox.Params;
...
params.bufSize = UInt 0;
DETAILS
This property is only used for dynamically created Mailboxes.
C SYNOPSIS
config Mailbox.heap // instance |
|
The IHeap instance used for dynamic creates
var params = new Mailbox.Params;
...
DETAILS
This heap is used only for dynamic instances is ignored for static
instances.
C SYNOPSIS
config Mailbox.readerEvent // instance |
|
Mailbox not empty event if using Events. Default is null
var params = new Mailbox.Params;
...
DETAILS
Posted whenever a mailbox is written to.
Reader task pends on this event.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
C SYNOPSIS
config Mailbox.readerEventId // instance |
|
Mailbox not empty event Id if using Events. Default is 1
var params = new Mailbox.Params;
...
params.readerEventId = UInt 1;
DETAILS
Posted whenever a mailbox is written to.
Reader task pends on this eventId.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
C SYNOPSIS
config Mailbox.writerEvent // instance |
|
Mailbox not full event if using Events. Default is null
var params = new Mailbox.Params;
...
DETAILS
Posted whenever a mailbox is read from.
Writer task pends on this event.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
C SYNOPSIS
config Mailbox.writerEventId // instance |
|
Mailbox not full event Id if using Events
var params = new Mailbox.Params;
...
params.writerEventId = UInt 1;
DETAILS
Posted whenever a mailbox is read from.
Writer task pends on this eventId.
Note that
Semaphore.supportsEvents has to be
set to true for Mailbox to support Events.
C SYNOPSIS
metaonly config Mailbox.sectionName // instance |
|
Section name for the buffer managed by the instance
var params = new Mailbox.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
Instance Creation |
|
var params =
new Mailbox.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Mailbox.create(SizeT msgSize, UInt numMsgs, params);
// Create an instance-object
ARGUMENTS
msgSize
size of message
numMsgs
length of mailbox
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Mailbox_create creates a mailbox object which is initialized to contain
numMsgs messages of size msgSize.