The Mailbox module makes available a set of functions that manipulate
mailbox objects accessed through handles of type Mailbox_Handle.
metaonly struct Mailbox.BasicView |
|
XDCscript usage |
meta-domain |
var obj = new Mailbox.BasicView;
obj.label = String ...
obj.msgSize = SizeT ...
obj.numMsgs = UInt ...
metaonly struct Mailbox.DetailedView |
|
XDCscript usage |
meta-domain |
var obj = new Mailbox.DetailedView;
obj.label = String ...
obj.msgSize = SizeT ...
obj.numMsgs = UInt ...
obj.curNumMsgs = UInt ...
obj.freeSlots = UInt ...
obj.pendQueue = String[] ...
obj.postQueue = String[] ...
struct Mailbox.MbxElem |
|
XDCscript usage |
meta-domain |
var obj = new Mailbox.MbxElem;
typedef struct Mailbox_MbxElem {
} Mailbox_MbxElem;
config Mailbox.A_invalidBufSize // module-wide |
|
Assert raised when the bufSize parameter is too small
to handle (size of messages + sizeof(MbxElem)) * number of messages. See
ti.sysbios.ipc.MailBox.buf for more information on the buf
parameter
XDCscript usage |
meta-domain |
msg: "Mailbox_create's bufSize parameter is invalid (too small)"
};
extern const Assert_Id Mailbox_A_invalidBufSize;
metaonly config Mailbox.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
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.
metaonly config Mailbox.rovViewInfo // module-wide |
|
XDCscript usage |
meta-domain |
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
per-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
per-instance config parameters |
|
XDCscript usage |
meta-domain |
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' points to
// 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. Default is 1
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' points to
// 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. Default is 1
} Mailbox_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Mailbox.buf // per-instance |
|
The address of the buffer used for creating messages
XDCscript usage |
meta-domain |
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. In either case,
the
ti.sysbios.ipc.Mailbox module will use the
ti.sysbios.heaps.HeapBuf module for handling the allocation of
all messages.
The
ti.sysbios.heaps.HeapBuf module will split the buf into
ti.sysbios.ipc.Mailbox.numMsgs number of blocks (one block per
Mailbox message). This
ti.sysbios.heaps.HeapBuf instance is
then used for managing the Mailbox messages.
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.ipc.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. Please refer to the alignment rules
specified by the
ti.sysbios.heaps.HeapBuf module's
ti.sysbios.heaps.HeapBuf.align paremeter for more
information on alignment. If the buffer is not properly aligned, an
Assert will be raised.
config Mailbox.bufSize // per-instance |
|
The size of the buffer that 'buf' points to
XDCscript usage |
meta-domain |
var params = new Mailbox.Params;
...
params.bufSize = UInt 0;
DETAILS
This property is only used for dynamically created Mailboxes.
config Mailbox.heap // per-instance |
|
The IHeap instance used for dynamic creates
XDCscript usage |
meta-domain |
var params = new Mailbox.Params;
...
DETAILS
This heap is used only for dynamic instances is ignored for static
instances.
config Mailbox.readerEvent // per-instance |
|
Mailbox not empty event if using Events. Default is null
XDCscript usage |
meta-domain |
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.
config Mailbox.readerEventId // per-instance |
|
Mailbox not empty event Id if using Events. Default is 1
XDCscript usage |
meta-domain |
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.
config Mailbox.writerEvent // per-instance |
|
Mailbox not full event if using Events. Default is null
XDCscript usage |
meta-domain |
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.
config Mailbox.writerEventId // per-instance |
|
Mailbox not full event Id if using Events. Default is 1
XDCscript usage |
meta-domain |
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.
metaonly config Mailbox.sectionName // per-instance |
|
Section name for the buffer managed by the instance
XDCscript usage |
meta-domain |
var params = new Mailbox.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
per-instance creation |
|
XDCscript usage |
meta-domain |
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
// 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.
per-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.getNumFreeMsgs( ) // per-instance |
|
Returns the number messages available for use for a Mailbox instance
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
Mailbox.getNumPendingMsgs( ) // per-instance |
|
Returns the number of messages that are ready to be read for a Mailbox
instance
ARGUMENTS
handle
handle of a previously-created Mailbox instance object
Mailbox.pend( ) // per-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( ) // per-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 immediatly.
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.
per-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