Detailed Description

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:

const Mailbox = scripting.addModule("/ti/sysbios/knl/Mailbox");

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.

Calling Context

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'.) Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. after Mailbox_init() has been called). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. before Mailbox_init() has been called).

#include <ti/sysbios/knl/Event.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Semaphore.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for Mailbox.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_post (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...

Macro Definition Documentation

§ Mailbox_A_invalidBufSize

#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 Documentation

§ Mailbox_Params

typedef struct Mailbox_Params Mailbox_Params

§ Mailbox_Object

typedef struct Mailbox_Struct Mailbox_Object

§ Mailbox_Struct

typedef struct Mailbox_Struct Mailbox_Struct

§ Mailbox_Handle

typedef struct Mailbox_Struct* Mailbox_Handle

Function Documentation

§ Mailbox_create()

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.

Parameters

msgSize	size of message
numMsgs	length of mailbox
prms	mailbox parameters
eb	error block

Return values

Mailbox handle (NULL on failure)

§ Mailbox_construct()

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.

Parameters

obj	pointer to a Mailbox object
msgSize	size of message
numMsgs	length of mailbox
prms	mailbox parameters
eb	error block

Return values

Mailbox handle (NULL on failure)

§ Mailbox_delete()

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.

Parameters

mailbox pointer to Task handle

§ Mailbox_destruct()

void Mailbox_destruct ( Mailbox_Struct * obj )

Destruct a mailbox.

Mailbox_destruct destructs a Mailbox object.

Parameters

obj	pointer to Mailbox object

§ Mailbox_getMsgSize()

size_t Mailbox_getMsgSize ( Mailbox_Handle mailbox )

Get the message size.

Parameters

mailbox Mailbox handle

Return values

mailbox message size

§ Mailbox_getNumFreeMsgs()

int Mailbox_getNumFreeMsgs ( Mailbox_Handle mailbox )

Get the number messages available for use.

Parameters

mailbox Mailbox handle

Return values

mailbox message size

§ Mailbox_getNumPendingMsgs()

int Mailbox_getNumPendingMsgs ( Mailbox_Handle mailbox )

Get the number of messages that are ready to be read.

Parameters

mailbox Mailbox handle

Return values

number of pending messages

§ Mailbox_pend()

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.

Event Object Note

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.

Warning: Be careful with the 'msg' parameter! The size of the buffer that 'msg' points to must match the 'msgSize' that was specified when the mailbox was created. This function does a blind copy of the message from the mailbox to the destination pointer, so the destination buffer must be big enough to handle this copy.

Parameters

mailbox	Mailbox handle
msg	message pointer
timeout	maximum duration in system clock ticks

Return values

true	if successful, false if timeout

§ Mailbox_post()

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.

Event Object Note

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.

Note: The operation of adding a message to the mailbox and signalling the task (if any) waiting on the mailbox is not atomic. This can result in a priority inversion with respect to message delivery. This can for example affect the order of message delivery for 2 tasks with different priorities. The lower priority task's message may be delivered first while the higher priority task's message may not unblock the task waiting on the mailbox until the lower priority task resumes and completes its Mailbox_post() call.

Parameters

mailbox	Mailbox handle
msg	message pointer
timeout	maximum duration in system clock ticks

Return values

true	if successful, false if timeout

§ Mailbox_Params_init()

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.

Parameters

prms	pointer to uninitialized params structure

§ Mailbox_Object_first()

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.

Return values

Mailbox handle

§ Mailbox_Object_next()

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.

Parameters

mbx	Mailbox handle

Return values

Mailbox handle

Detailed Description

Calling Context

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ Mailbox_A_invalidBufSize

Typedef Documentation

§ Mailbox_Params

§ Mailbox_Object

§ Mailbox_Struct

§ Mailbox_Handle

Function Documentation

§ Mailbox_create()

§ Mailbox_construct()

§ Mailbox_delete()

§ Mailbox_destruct()

§ Mailbox_getMsgSize()

§ Mailbox_getNumFreeMsgs()

§ Mailbox_getNumPendingMsgs()

§ Mailbox_pend()

Event Object Note

§ Mailbox_post()

Event Object Note

§ Mailbox_Params_init()

§ Mailbox_Object_first()

§ Mailbox_Object_next()