M2MB OS Q

This section describes the M2MB APIs to perform OS queue operations. More...

#define	M2MB_OS_Q_INVALID   0
#define	M2MB_OS_Q_INVALID_ATTR   0
#define	M2MB_OS_Q_TX_PRIORITIZE   1
enum	M2MB_OS_Q_SEL_CMD_E {   M2MB_OS_Q_SEL_CMD_CREATE_ATTR,   M2MB_OS_Q_SEL_CMD_DEL_ATTR,   M2MB_OS_Q_SEL_CMD_NAME,   M2MB_OS_Q_SEL_CMD_USRNAME,   M2MB_OS_Q_SEL_CMD_MSG_SIZE,   M2MB_OS_Q_SEL_CMD_QSTART,   M2MB_OS_Q_SEL_CMD_QSIZE,   M2MB_OS_Q_SEL_CMD_SUSPENDED_COUNT,   M2MB_OS_Q_SEL_CMD_1ST_SUSP,   M2MB_OS_Q_SEL_CMD_ENQUEUED,   M2MB_OS_Q_SEL_CMD_QROOM,   M2MB_OS_Q_SEL_CMD_END }
typedef HANDLE	M2MB_OS_Q_HANDLE
typedef HANDLE	M2MB_OS_Q_ATTR_HANDLE
M2MB_OS_RESULT_E	m2mb_os_q_init (M2MB_OS_Q_HANDLE *pQHandle, M2MB_OS_Q_ATTR_HANDLE *pQAttrHandle)
	Message Queue creation. More...
M2MB_OS_RESULT_E	m2mb_os_q_deinit (M2MB_OS_Q_HANDLE qHandle)
	Message Queue Deinit or Deletion. More...
M2MB_OS_RESULT_E	m2mb_os_q_rx (M2MB_OS_Q_HANDLE qHandle, void *pDest, UINT32 timeoutTicks)
	Receive message from the queue. More...
M2MB_OS_RESULT_E	m2mb_os_q_tx (M2MB_OS_Q_HANDLE qHandle, void *pSource, UINT32 timeoutTicks, UINT8 priority)
	Send message to the queue. More...
M2MB_OS_RESULT_E	m2mb_os_q_hptf (M2MB_OS_Q_HANDLE queueHandle)
	Prioritize queue suspension list Set HPTF: Highest Priority Task First to receive the message from queue (one shot) More...
M2MB_OS_RESULT_E	m2mb_os_q_clear (M2MB_OS_Q_HANDLE qHandle)
	Clear all messages from the queue. More...
M2MB_OS_RESULT_E	m2mb_os_q_setAttrItem (M2MB_OS_Q_ATTR_HANDLE *pQAttrHandle, UINT8 nCmds,...)
	Set specific attribute for queue creation. More...
M2MB_OS_RESULT_E	m2mb_os_q_getItem (M2MB_OS_Q_HANDLE qHandle, M2MB_OS_Q_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
	Get specific properties of the queue. More...
M2MB_OS_RESULT_E	m2mb_os_q_setItem (M2MB_OS_Q_HANDLE qHandle, M2MB_OS_Q_SEL_CMD_E selCmd, void *pIn)
	Set specific properties of the queue. More...

Detailed Description

This section describes the M2MB APIs to perform OS queue operations.

Macro Definition Documentation

M2MB_OS_Q_INVALID

#define M2MB_OS_Q_INVALID   0

Definition at line 52 of file m2mb_os_q.h.

M2MB_OS_Q_INVALID_ATTR

#define M2MB_OS_Q_INVALID_ATTR   0

Definition at line 53 of file m2mb_os_q.h.

M2MB_OS_Q_TX_PRIORITIZE

#define M2MB_OS_Q_TX_PRIORITIZE   1

Definition at line 54 of file m2mb_os_q.h.

Typedef Documentation

M2MB_OS_Q_ATTR_HANDLE

typedef HANDLE M2MB_OS_Q_ATTR_HANDLE

Definition at line 78 of file m2mb_os_q.h.

M2MB_OS_Q_HANDLE

typedef HANDLE M2MB_OS_Q_HANDLE

Definition at line 77 of file m2mb_os_q.h.

Enumeration Type Documentation

M2MB_OS_Q_SEL_CMD_E

enum M2MB_OS_Q_SEL_CMD_E

Enumerator
M2MB_OS_Q_SEL_CMD_CREATE_ATTR
M2MB_OS_Q_SEL_CMD_DEL_ATTR
M2MB_OS_Q_SEL_CMD_NAME	use as Os name
M2MB_OS_Q_SEL_CMD_USRNAME	if set, user name could be different from Os
M2MB_OS_Q_SEL_CMD_MSG_SIZE	size of message in 32 bit words: 1 to 16 max
M2MB_OS_Q_SEL_CMD_QSTART	if not specified will be allocated by system
M2MB_OS_Q_SEL_CMD_QSIZE	size in byte
M2MB_OS_Q_SEL_CMD_SUSPENDED_COUNT	number of task suspended on the queue
M2MB_OS_Q_SEL_CMD_1ST_SUSP	first task (M2MB_OS_TASK_HANDLE) to be served when msg will be enqueued
M2MB_OS_Q_SEL_CMD_ENQUEUED	number of messages enqueued on the queue
M2MB_OS_Q_SEL_CMD_QROOM	number of messages the queue currently has space for
M2MB_OS_Q_SEL_CMD_END

Definition at line 57 of file m2mb_os_q.h.

Function Documentation

m2mb_os_q_clear()

M2MB_OS_RESULT_E m2mb_os_q_clear

(

M2MB_OS_Q_HANDLE

qHandle

)

Clear all messages from the queue.

This service deletes all messages stored in the specified message queue identified by its handle. If the queue is full, messages of all suspended tasks are discarded. Each suspended task is then resumed with a return status that indicates the message send was successful. If the queue is empty, this service does nothing.

Parameters

[in]

qHandle

handle of queue to be clear

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful queue operation. M2MB_OS_QUEUE_ERROR Invalid counting queue handle

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible Yes

Example

<C code example>

m2mb_os_q_deinit()

M2MB_OS_RESULT_E m2mb_os_q_deinit

(

M2MB_OS_Q_HANDLE

qHandle

)

Message Queue Deinit or Deletion.

This service deletes the specified message queue. All tasks suspended waiting for a message from this queue are resumed with a return value equal to M2MB_OS_DELETED The resources will be released It is the application's responsibility to manage the memory area associated with the queue, which is available after this service completes, if qStart with M2MB_OS_Q_SEL_CMD_QSTART was specified. It is the application's responsibility to prevent the use of a deleted queue.

Parameters

[in]

qHandle

Handle of the queue

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid arguments M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

It is the application's responsibility to prevent the use of a deleted queue. Allowed From tasks Preemption Possible Yes

Example

<C code example>

m2mb_os_q_getItem()

M2MB_OS_RESULT_E m2mb_os_q_getItem	(	M2MB_OS_Q_HANDLE	qHandle,
		M2MB_OS_Q_SEL_CMD_E	selCmd,
		MEM_W *	pOut,
		void *	pIn
	)

Get specific properties of the queue.

This service retrieves values for a specified parameter of the specified queue Selecting cmd, a parameter to be retrieved can be set To be used when queue is already created: its right use is under application responsibility

Parameters

[in]	qHandle	Handle of queue
[in]	selCmd	Select parameter to be retrieved (see M2MB_OS_Q_SEL_CMD_E)
[out]	pOut	Pointer Output parameter got: its meaning depend on selCmd used. See examples as a general pointer, it is set to UINT32
[in]	pIn	Pointer to void general Parameter to be specified, if any, to get the right output. See examples If the parameter is not needed, use NULL

Returns

M2MB_OS_SUCCESS in case of success (others in case of error : see m2mb_os_types.h)

M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid arguments

Note

Not all the M2MB_OS_Q_SEL_CMD_E are always available. Of course M2MB_OS_Q_SEL_CMD_CREATE_ATTR is not right for this function M2MB_OS_Q_SEL_CMD_NAME, M2MB_OS_Q_SEL_CMD_USRNAME, M2MB_OS_Q_SEL_CMD_MSG_SIZE M2MB_OS_Q_SEL_CMD_QSTART, M2MB_OS_Q_SEL_CMD_QSIZE, M2MB_OS_Q_SEL_CMD_1ST_SUSP, M2MB_OS_Q_SEL_CMD_SUSPENDED_COUNT, M2MB_OS_Q_SEL_CMD_ENQUEUED, M2MB_OS_Q_SEL_CMD_QROOM are ok

Example

M2MB_OS_Q_ATTR_HANDLE       qAttrHandle;
M2MB_OS_Q_HANDLE            queueHandle;
MEM_W                       qRoom;
MEM_W                       enqueueHandled;
MEM_W                       suspended, qsize;
M2MB_OS_TASK                fisrtEnq;


m2mb_os_q_getItem( queueHandle, M2MB_OS_Q_SEL_CMD_SUSPENDED_COUNT,  &suspended, NULL );
m2mb_os_q_getItem( queueHandle, M2MB_OS_Q_SEL_CMD_ENQUEUED, &enqueueHandled, NULL );
m2mb_os_q_getItem( queueHandle, M2MB_OS_Q_SEL_CMD_QROOM, &qRoom, NULL );
m2mb_os_q_getItem( queueHandle, M2MB_OS_Q_SEL_CMD_QSIZE, &qsize, NULL );

m2mb_os_q_hptf()

M2MB_OS_RESULT_E m2mb_os_q_hptf

(

M2MB_OS_Q_HANDLE

queueHandle

)

Prioritize queue suspension list Set HPTF: Highest Priority Task First to receive the message from queue (one shot)

This service sets the task waiting for this queue which has currently the highest priority, on the top of FIFO suspension list

Parameters

[in]

queueHandle

Handle of queue

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful queue operation. M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid oneShot parameter

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible No

Example: Set highest priority task waiting on the queue, at the top of FIFO suspension list

M2MB_OS_Q_HANDLE queueHandle;
//...
//already created... used queue
//just put highest priority task on top of suspension list
m2mb_os_q_HPTF( queueHandle);

m2mb_os_q_init()

M2MB_OS_RESULT_E m2mb_os_q_init	(	M2MB_OS_Q_HANDLE *	pQHandle,
		M2MB_OS_Q_ATTR_HANDLE *	pQAttrHandle
	)

Message Queue creation.

This service creates a message queue that is typically used for inter- task communication. The total number of messages is calculated from the specified message size and the total number of bytes in the queue. Specifies the size of each message in the queue. Message sizes range from 1 32-bit word to 16 32-bit words. Valid message size options are numerical values from 1 through 16, inclusive.

Parameters

[out]	pQHandle	Pointer to queue handle
[in]	pQAttrHandle	Pointer to queue attribute handle

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid arguments M2MB_OS_SIZE_ERROR Size of the message queue is invalid. M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

If the total number of bytes specified in the queue's memory area is not evenly divisible by the specified message size, the remaining bytes in the memory area are not used. After successful queue creation, queue attribute will be deleted, their resources free and pQAttr set to M2MB_OS_Q_INVALID_ATTR Allowed From Initialization and tasks Preemption Possible No

Example

 M2MB_OS_RESULT_E       osRes;
 M2MB_OS_Q_ATTR_HANDLE  qAttrHandle;
 M2MB_OS_Q_HANDLE       queueHandle;
 UINT32                 msgSize = 5;           // 5 * 4Byte => 20 bytes; message sizes range from 1 32-bit word to 16 32-bit words. Valid message size options are numerical values from 1 through 16, inclusive.
 static UINT8           QueueArea[100 * 5*4];  // just to contain  100 of  5 word32
                                               // message size =>20 byte each msg

 if ( m2mb_os_q_setAttrItem(  &qAttrHandle, 1, M2MB_OS_Q_SEL_CMD_CREATE_ATTR,  NULL  ) != M2MB_OS_SUCCESS )
     exit(error_creating attribute queueHandle);

 osRes = m2mb_os_q_setAttrItem( &qAttrHandle, 4,
                                M2MB_OS_Q_SEL_CMD_NAME, M2MB_OS_Q_SEL_CMD_MSG_SIZE,
                                M2MB_OS_Q_SEL_CMD_QSTART, M2MB_OS_Q_SEL_CMD_QSIZE,
                                "Myqueue", msgSize, &QueueArea, sizeof(QueueArea)
                              );


 // or simply using CMDS_ARGS(...) macro
 // m2mb_os_q_setAttrItem( &qAttrHandle,
 //                        CMDS_ARGS
 //                        (
 //                          M2MB_OS_Q_SEL_CMD_NAME, "Myqueue",
 //                          M2MB_OS_Q_SEL_CMD_QSTART, &QueueArea,
 //                          M2MB_OS_Q_SEL_CMD_MSG_SIZE, msgSize,
 //                          M2MB_OS_Q_SEL_CMD_QSIZE, sizeof(QueueArea)
 //                        )
 //                       );

if ( osRes != M2MB_OS_SUCCESS )
    exit(...)

 m2mb_os_q_init( &queueHandle, &qAttrHandle );

 // by not specifying QueueArea, or setting to NULL
 // OS will provide allocation for qsize: the number of messages that queueHandle can keep depend
 // on the size specified in M2MB_OS_Q_SEL_CMD_MSG_SIZE
 // e.g queuesize = 2000 and msgSize = 5 (20 bytes) => max msgs = 2000/20 = 100

m2mb_os_q_rx()

M2MB_OS_RESULT_E m2mb_os_q_rx	(	M2MB_OS_Q_HANDLE	qHandle,
		void *	pDest,
		UINT32	timeoutTicks
	)

Receive message from the queue.

This service retrieves a message from the specified message queue identified by its handle. The retrieved message is copied from the queue into the memory area specified by the destination pointer. That message is then removed from the queue.

Parameters

[in]	qHandle	Handle of queue
[in]	pDest	Pointer to destination where to copy the received message
[in]	timeoutTicks	If timeout is specified and messages are not available on queue, task will be suspended for a maximum time of timeout ticks

Returns

M2MB_OS_SUCCESS in case of success (others in case of error : see m2mb_os_types.h)

M2MB_OS_SUCCESS Successful retrieval of a queue instance. M2MB_OS_DELETED Queue was deleted while the task was suspended. M2MB_OS_WAIT_ABORTED Suspension was aborted by another task, timer, or ISR. M2MB_OS_QUEUE_ERROR Invalid counting queue handle. M2MB_OS_WAIT_ERROR A wait option other than M2MB_OS_NO_WAIT was specified on a call from a non-task. M2MB_OS_CALLER_ERROR Invalid caller of this service.

Note

The specified destination memory area must be large enough to hold the message; i.e., the message destination pointed to by pDest must be at least as large as the message size for this queue. Otherwise, if the destination is not large enough, memory corruption occurs in the following memory area. Allowed From Initialization, tasks, timers, and ISRs Preemption Possible Yes

Example

static UINT32 myMsg[5];
m2mb_os_q_rx( myQHandle, myMsg, M2MB_OS_WAIT_FOREVER );

m2mb_os_q_setAttrItem()

M2MB_OS_RESULT_E m2mb_os_q_setAttrItem	(	M2MB_OS_Q_ATTR_HANDLE *	pQAttrHandle,
		UINT8	nCmds,
			...
	)

Set specific attribute for queue creation.

This service sets the attribute (or create it) to be used for queue creation Selecting cmd, a parameter to be set can be selected

Parameters

[in]	pQAttrHandle	Pointer to event attribute of event
[in]	nCmds	Number of commands to be issued at once
[in]	...	Variable inputs, N cmds (see M2MB_OS_Q_SEL_CMD_E) followed by N arguments for their respective issued commands. CMDS(...) and CMDS_ARGS(...) macro can be used to better insert cmd and parameters and to better control right insertion

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful queue operation. M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid pQAttr or pIn

Note

The attribute set are useful for queue creation. Once created, use instead m2mb_os_q_setItem() to set only available queue properties After m2mb_os_q_init, resources of M2MB_OS_Q_ATTR_HANDLE will be released and handle set to M2MB_OS_Q_INVALID_ATTR It is under application's responsibility the right use of m2mb_os_q_setAttrItem. For instance, multi creation of attrHandle without free of previous resources ( M2MB_OS_Q_SEL_CMD_CREATE_ATTR without M2MB_OS_Q_SEL_CMD_DEL_ATTR in case no m2mb_os_q_init is used in the between ) will waste memory.

Example

 M2MB_OS_RESULT_E       osRes;
 M2MB_OS_Q_ATTR_HANDLE  qAttrHandle;
 M2MB_OS_Q_HANDLE       queueHandle;
 UINT32                 msgSize = 5 ; //  Message sizes range from 1 32-bit word to 16 32-bit words. Valid message size options are numerical values from 1 through 16, inclusive.
 static UINT8           QueueArea[100 * 5*4];  // just to contain  100 of
                                               // 5 word32 message size =>20 byte each msg

 if ( m2mb_os_q_setAttrItem( &qAttrHandle, 1, M2MB_OS_Q_SEL_CMD_CREATE_ATTR,  NULL ) != M2MB_OS_SUCCESS )
     exit(error_creating attribute queueHandle);

 osRes = m2mb_os_q_setAttrItem( &qAttrHandle, 4,
                                M2MB_OS_Q_SEL_CMD_NAME, M2MB_OS_Q_SEL_CMD_QSTART,
                                M2MB_OS_Q_SEL_CMD_MSG_SIZE, M2MB_OS_Q_SEL_CMD_QSIZE,
                                Myqueue", &QueueArea, msgSize, sizeof(QueueArea)
                              )

 // or using CMDS_ARGS(...) macro
 // m2mb_os_q_setAttrItem( &qAttrHandle,
 //                        CMDS_ARGS
 //                        (
 //                          M2MB_OS_Q_SEL_CMD_NAME, "Myqueue",
 //                          M2MB_OS_Q_SEL_CMD_QSTART, &QueueArea,
 //                          M2MB_OS_Q_SEL_CMD_MSG_SIZE, msgSize,
 //                          M2MB_OS_Q_SEL_CMD_QSIZE, sizeof(QueueArea)
 //                        )
 //                       );

if ( osRes != M2MB_OS_SUCCESS )
    exit(...)

 m2mb_os_q_init( &queueHandle, &qAttrHandle );

m2mb_os_q_setItem()

M2MB_OS_RESULT_E m2mb_os_q_setItem	(	M2MB_OS_Q_HANDLE	qHandle,
		M2MB_OS_Q_SEL_CMD_E	selCmd,
		void *	pIn
	)

Set specific properties of the queue.

This service sets value for a specified parameter of the specified queue, if available. Selecting cmd, a parameter to be set can be selected To be used when queue is already created: its right use is under application's responsibility

Parameters

[in]	qHandle	Handle of queue
[in]	selCmd	Select parameter to be set (see M2MB_OS_Q_SEL_CMD_E)
[in]	pIn	Pointer to value to be set. If a simple value, can be easily casted to (void*) For example, int value -3 has to be passed, use (void*)-3 NULL if no value is needed

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_QUEUE_ERROR Invalid counting queue handle M2MB_OS_INVALID_ARG Invalid arguments

Note

Not all the M2MB_OS_Q_SEL_CMD_E are always available. Of course M2MB_OS_Q_SEL_CMD_CREATE_ATTR is not right for this function Only M2MB_OS_Q_SEL_CMD_NAME, M2MB_OS_Q_SEL_CMD_USRNAME, are ok

Example

m2mb_os_q_setItem(queueHandle, M2MB_OS_Q_SEL_CMD_HPTF, (void*)1 );
// this will force every put to release the highest priority task waiting for queue
m2mb_os_q_setItem(queueHandle, M2MB_OS_Q_SEL_CMD_HPTF, (void*)0 );
//will set standard FIFO rule again
m2mb_os_q_setItem(queueHandle, M2MB_OS_Q_SEL_CMD_USRNAME, (void*)"ThisIsUserName");

m2mb_os_q_tx()

M2MB_OS_RESULT_E m2mb_os_q_tx	(	M2MB_OS_Q_HANDLE	qHandle,
		void *	pSource,
		UINT32	timeoutTicks,
		UINT8	priority
	)

Send message to the queue.

This service sends a message to the specified message queue identified by its handler. The sent message is copied to the queue from the memory area specified by the pSource pointer. If priority M2MB_OS_Q_TX_PRIORITIZE or a value higher then 0 is selected, the message is placed at the top of the queue, therefore first to be received

Parameters

[in]	qHandle	Handle of queue
[in]	pSource	Pointer of Source message to be sent in queue
[in]	timeoutTicks	If timeout is specified and there is no room available on queue, the task will be suspended for a maximum numbers of timeout ticks
[in]	priority	With priority > 0 or M2MB_OS_Q_TX_PRIORITIZE the message is copied to the front of the queue from the memory area specified by the pSource pointer

Returns

M2MB_OS_SUCCESS in case of success

M2MB_OS_SUCCESS Successful queue put. M2MB_OS_QUEUE_ERROR Invalid queue handle M2MB_OS_CALLER_ERROR Invalid caller of this service. M2MB_OS_QUEUE_FULL Service was unable to send message because the queue was full for the duration of the specified time to wait. M2MB_OS_WAIT_ERROR A wait option other than M2MB_OS_NO_WAIT was specified on a call from a non-task. M2MB_OS_WAIT_ABORTED Suspension was aborted by another task, timer, or ISR.

Note

Allowed From Initialization, tasks, timers, and ISRs Preemption Possible Yes

Example

//Send a message to "my_queue." Return immediately regardless of success.
//This wait option is used for calls from initialization, timers, and ISRs.
// make use of prioritization; put highest task waiting on the queue at the top of priority list
m2mb_os_q_tx( myQHandle, myMsg, M2MB_OS_NO_WAIT, M2MB_OS_Q_TX_PRIORITIZE);
// or simply send message with no prioritization
m2mb_os_q_tx( myQHandle, myMsg, M2MB_OS_NO_WAIT, 0);
//If status equals M2MB_OS_SUCCESS, the message is in the queue