Detailed Description

MessageQueue module for the RTOS Porting Interface.

============================================================================

MessageQueueP objects are RTOS message queues backed by OS-specific queue or mailbox objects.

Message queues can be used for intertask communication. They support sending messages between tasks, and between interrupts and tasks. Message queues can either be allocated statically with MessageQueueP_construct() or dynamically with MessageQueueP_create().

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <ti/devices/DeviceFamily.h>

Include dependency graph for MessageQueueP.h:

Go to the source code of this file.

Data Structures
union	MessageQueueP_Struct
	MessageQueueP structure. More...

Macros
#define	MessageQueueP_STRUCT_SIZE (104)
	Number of bytes greater than or equal to the size of any RTOS Queue/Mailbox data structure. More...

#define	MessageQueueP_BUFFER_SIZE(msgSize, msgCount) ((msgCount) * ((msgSize) + 8))
	Required number of bytes of a statically allocated message queue buffer. More...

#define	MessageQueueP_WAIT_FOREVER ~(0)
	Wait forever define. More...

#define	MessageQueueP_NO_WAIT (0)
	No wait define. More...

Typedefs
typedef union MessageQueueP_Struct	MessageQueueP_Struct
	MessageQueueP structure. More...

typedef void *	MessageQueueP_Handle
	Opaque client reference to an instance of a MessageQueueP. More...

Enumerations
enum	MessageQueueP_Status { MessageQueueP_OK = 0, MessageQueueP_TIMEOUT = -1 }
	Status codes for MessageQueueP APIs. More...

Functions
MessageQueueP_Handle	MessageQueueP_create (size_t msgSize, size_t msgCount)
	Create a MessageQueueP, allocating memory on the heap. More...

MessageQueueP_Handle	MessageQueueP_construct (MessageQueueP_Struct queueStruct, size_t msgSize, size_t msgCount, void msgBuf)
	Construct a MessageQueueP from statically allocated memory. More...

void	MessageQueueP_delete (MessageQueueP_Handle handle)
	Delete a MessageQueueP. More...

void	MessageQueueP_destruct (MessageQueueP_Handle handle)
	Destruct a MessageQueueP. More...

MessageQueueP_Status	MessageQueueP_pend (MessageQueueP_Handle handle, void *message, uint32_t timeout)
	Receive an item from a message queue. More...

MessageQueueP_Status	MessageQueueP_peek (MessageQueueP_Handle handle, void *message, uint32_t timeout)
	Receive an item from a message queue without removing the item from the queue. More...

MessageQueueP_Status	MessageQueueP_post (MessageQueueP_Handle handle, const void *message, uint32_t timeout)
	Post an item on a message queue. More...

MessageQueueP_Status	MessageQueueP_postFront (MessageQueueP_Handle handle, const void *message, uint32_t timeout)
	Post an item in the front of a message queue. More...

size_t	MessageQueueP_getPendingCount (MessageQueueP_Handle handle)
	Get the number of messages stored in a message queue. More...

size_t	MessageQueueP_getFreeCount (MessageQueueP_Handle handle)
	Get the number of free spaces in a message queue. More...

Macro Definition Documentation

§ MessageQueueP_STRUCT_SIZE

#define MessageQueueP_STRUCT_SIZE (104)

Number of bytes greater than or equal to the size of any RTOS Queue/Mailbox data structure.

TI-RTOS7: 104 FreeRTOS: 80

§ MessageQueueP_BUFFER_SIZE

#define MessageQueueP_BUFFER_SIZE	(	msgSize,
		msgCount
	)	((msgCount) * ((msgSize) + 8))

Required number of bytes of a statically allocated message queue buffer.

This macro is defined to support the user in configuring the size of a message queue buffer. A pointer to this user defined buffer is one of the arguments of the MessageQueueP_construct() function. The macro gives the minimal number of bytes required for the message queue. Please note the following for devices supporting TI-RTOS7:

The macro takes into account an eight byte message header which is only required by TI-RTOS and not by FreeRTOS. For user applications only targeting FreeRTOS, SRAM usage can be limited by setting the buffer size to (msgCount * msgSize) instead of using this macro.

§ MessageQueueP_WAIT_FOREVER

#define MessageQueueP_WAIT_FOREVER ~(0)

Wait forever define.

§ MessageQueueP_NO_WAIT

#define MessageQueueP_NO_WAIT (0)

No wait define.

Typedef Documentation

§ MessageQueueP_Struct

typedef union MessageQueueP_Struct MessageQueueP_Struct

MessageQueueP structure.

Opaque structure that should be large enough to hold any of the RTOS specific MessageQueueP objects.

§ MessageQueueP_Handle

typedef void* MessageQueueP_Handle

Opaque client reference to an instance of a MessageQueueP.

A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct() represents that instance. It is then is used in the other instance based functions (e.g. MessageQueueP_pend(), MessageQueueP_post(), etc.).

Enumeration Type Documentation

§ MessageQueueP_Status

enum MessageQueueP_Status

Status codes for MessageQueueP APIs.

Enumerator
MessageQueueP_OK	API completed successfully
MessageQueueP_TIMEOUT	API failed because of a timeout

Function Documentation

§ MessageQueueP_create()

MessageQueueP_Handle MessageQueueP_create	(	size_t	msgSize,
		size_t	msgCount
	)

Create a MessageQueueP, allocating memory on the heap.

MessageQueueP_create creates a new message queue object. MessageQueueP_create returns the handle of the new message queue object or NULL if the message queue could not be created.

The message queue object will be allocated on the heap - make sure you have a sufficiently large heap.

Note: This API cannot be called from interrupt contexts.

For FreeRTOS, configSUPPORT_DYNAMIC_ALLOCATION has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

Parameters

msgSize	The size, in bytes, required to hold each item in the message queue
msgCount	The maximum number of items the message queue can hold at any one time

Return values

MessageQueueP handle (NULL on failure)

§ MessageQueueP_construct()

MessageQueueP_Handle MessageQueueP_construct	(	MessageQueueP_Struct *	queueStruct,
		size_t	msgSize,
		size_t	msgCount,
		void *	msgBuf
	)

Construct a MessageQueueP from statically allocated memory.

MessageQueueP_construct creates a new message queue object. MessageQueueP_construct returns the handle of the new message queue object or NULL if the message queue could not be created.

To use MessageQueueP_construct msgBuf must point to a valid preallocated memory array that is at least large enough to hold the maximum number of items that can be in the message queue at any one time.

When used with FreeRTOS the array size must be at least ( msgCount * msgSize) bytes.
When used with TI-RTOS the array size must be at least ( msgCount * ( msgSize + 8)) bytes.
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.

Note: This API cannot be called from interrupt contexts.

For FreeRTOS, configSUPPORT_STATIC_ALLOCATION has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

Parameters

queueStruct	Must point to a variable that holds the message queue's data structure
msgSize	The size, in bytes, required to hold each item in the message queue
msgCount	The maximum number of items the message queue can hold at any one time
msgBuf	Pointer to variable that holds the message queue's data buffer

Return values

MessageQueueP handle (NULL on failure)

§ MessageQueueP_delete()

void MessageQueueP_delete ( MessageQueueP_Handle handle )

Delete a MessageQueueP.

MessageQueueP_delete finalizes and frees this previously allocated message queue object, setting the referenced handle to NULL. This function should be used when the message queue was created by the MessageQueueP_create() function.

Note: This API cannot be called from interrupt contexts.

Parameters

handle A handle to the message queue to be deleted

§ MessageQueueP_destruct()

void MessageQueueP_destruct ( MessageQueueP_Handle handle )

Destruct a MessageQueueP.

MessageQueueP_destruct finalizes the message queue object inside the provided structure. This function should be used when the message queue was constructed by the MessageQueueP_construct() function.

Note: This API cannot be called from interrupt contexts.

Parameters

handle A handle to the message queue to be destructed

§ MessageQueueP_pend()

MessageQueueP_Status MessageQueueP_pend	(	MessageQueueP_Handle	handle,
		void *	message,
		uint32_t	timeout
	)

Receive an item from a message queue.

MessageQueueP_pend receives an item from the provided message queue.

Parameters

handle	The handle to the message queue from which the item is to be received
message	Pointer to the buffer into which the received item will be copied
timeout	The maximum duration in system clock ticks a task should block waiting for an item to be received. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used.

Return values

Status

of the function

MessageQueueP_OK: Item recieved
MessageQueueP_TIMEOUT: Timed out. Item was not recieved.

§ MessageQueueP_peek()

MessageQueueP_Status MessageQueueP_peek	(	MessageQueueP_Handle	handle,
		void *	message,
		uint32_t	timeout
	)

Receive an item from a message queue without removing the item from the queue.

MessageQueueP_peek receives an item from the provided message queue without removing the item from the queue.

Parameters

handle	The handle to the message queue from which the item is to be received
message	Pointer to the buffer into which the received item will be copied
timeout	The maximum duraton in system clock ticks a task should block waiting for an item to be received. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used.

Return values

Status

of the function

MessageQueueP_OK: Item recieved
MessageQueueP_TIMEOUT: Timed out. Item was not recieved.

§ MessageQueueP_post()

MessageQueueP_Status MessageQueueP_post	(	MessageQueueP_Handle	handle,
		const void *	message,
		uint32_t	timeout
	)

Post an item on a message queue.

MessageQueueP_post posts an item on the provided message queue.

Parameters

handle	The handle to the message queue to which the item is to be posted
message	Pointer to the buffer from which the item to be posted is copied
timeout	The maximum duraton in system clock ticks a task should block waiting for an item to be posted. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used.

Return values

Status

of the function

MessageQueueP_OK: Item posted
MessageQueueP_TIMEOUT: Timed out. Item was not posted.

§ MessageQueueP_postFront()

MessageQueueP_Status MessageQueueP_postFront	(	MessageQueueP_Handle	handle,
		const void *	message,
		uint32_t	timeout
	)

Post an item in the front of a message queue.

MessageQueueP_postFront posts an item in the front of the provided message queue.

Parameters

handle	The handle to the message queue to which the item is to be posted
message	Pointer to the buffer from which the item to be posted is copied
timeout	The maximum duraton in system clock ticks a task should block waiting for an item to be posted. When no wait or wait forever options are wanted the MessageQueueP_NO_WAIT and MessageQueueP_WAIT_FOREVER defines can be used.

Return values

Status

of the function

MessageQueueP_OK: Item posted
MessageQueueP_TIMEOUT: Timed out. Item was not posted.

§ MessageQueueP_getPendingCount()

size_t MessageQueueP_getPendingCount ( MessageQueueP_Handle handle )

Get the number of messages stored in a message queue.

Returns the number of messages in the specified message queue.

Parameters

handle A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct()

Return values

Number of stored messages in the specified message queue

§ MessageQueueP_getFreeCount()

size_t MessageQueueP_getFreeCount ( MessageQueueP_Handle handle )

Get the number of free spaces in a message queue.

Returns the number of free spaces in the specified message queue.

Parameters

handle A MessageQueueP_Handle returned from MessageQueueP_create() or MessageQueueP_construct()

Return values

Number of free spaces in the specified message queue

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ MessageQueueP_STRUCT_SIZE

§ MessageQueueP_BUFFER_SIZE

§ MessageQueueP_WAIT_FOREVER

§ MessageQueueP_NO_WAIT

Typedef Documentation

§ MessageQueueP_Struct

§ MessageQueueP_Handle

Enumeration Type Documentation

§ MessageQueueP_Status

Function Documentation

§ MessageQueueP_create()

§ MessageQueueP_construct()

§ MessageQueueP_delete()

§ MessageQueueP_destruct()

§ MessageQueueP_pend()

§ MessageQueueP_peek()

§ MessageQueueP_post()

§ MessageQueueP_postFront()

§ MessageQueueP_getPendingCount()

§ MessageQueueP_getFreeCount()