MID_RTO_OSAL_MSG_QUEUES

Files
file	msg_queues.h
	Message queue API.

Data Structures
struct	content_allocator
	Message queue content allocator. More...
struct	msq_queue
	Message queue structure. More...
struct	msg
	Structure for messages with id, type, data. More...

Macros
#define	MSG_QUEUE_MALLOC   OS_MALLOC_FUNC
	Default memory allocation function for queues. More...
#define	MSG_QUEUE_FREE   OS_FREE_FUNC
	Default memory free function for queues. More...

Typedefs
typedef uint16_t	MSG_SIZE
typedef uint16_t	MSG_ID
typedef uint16_t	MSG_TYPE
typedef void(*	MSG_FREE) (void *)
typedef void *(*	MSG_ALLOC) (size_t)
typedef struct content_allocator	content_allocator
	Message queue content allocator. More...
typedef struct msq_queue	msg_queue
	Message queue structure. More...
typedef struct msg	msg
	Structure for messages with id, type, data. More...

Functions
void	msg_queue_create (msg_queue *queue, int queue_size, content_allocator *allocator)
	Create message queue. More...
void	msg_queue_delete (msg_queue *queue)
	Delete message queue. More...
int	msg_queue_put (msg_queue *queue, msg *msg, OS_TICK_TIME timeout)
	Put message in queue. More...
int	msg_queue_get (msg_queue *queue, msg *msg, OS_TICK_TIME timeout)
	Get message from queue. More...
void	msg_init (msg *msg, MSG_ID id, MSG_TYPE type, void *buf, MSG_SIZE size, MSG_FREE free_cb)
	Prepare message with freeing callback. More...
void	msg_release (msg *msg)
	Release message data. More...
int	msg_queue_init_msg (msg_queue *queue, msg *msg, MSG_ID id, MSG_TYPE type, MSG_SIZE size)
	Initialize message with queue specific freeing callback. More...
int	msg_queue_send (msg_queue *queue, MSG_ID id, MSG_TYPE type, void *buf, MSG_SIZE size, OS_TICK_TIME timeout)
	Send data to queue. More...
int	msq_queue_send_zero_copy (msg_queue *queue, MSG_ID id, MSG_TYPE type, void *buf, MSG_SIZE size, OS_TICK_TIME timeout, MSG_FREE free_cb)
	Send data to queue with zero copy. More...

Detailed Description

Macro Definition Documentation

MSG_QUEUE_FREE

#define MSG_QUEUE_FREE   OS_FREE_FUNC

Default memory free function for queues.

If not otherwise specified, default memory free function used by queues will be taken from OS.

MSG_QUEUE_MALLOC

#define MSG_QUEUE_MALLOC   OS_MALLOC_FUNC

Default memory allocation function for queues.

If not otherwise specified, default memory allocation function used by queues will be taken from OS.

Typedef Documentation

content_allocator

typedef struct content_allocator content_allocator

Message queue content allocator.

Content allocator consist of two functions that will allocate and release memory needed by messages in cases when data needs to be copied from sender to receiver. Allocator will be associated with msg_queue so user can initialize messages using correct allocation functions. Those functions will be used when user calls msg_queue_send() function.

If CONFIG_MSG_QUEUE_USE_ALLOCATORS is not defined queues will not have dedicated allocators. In this case MSG_QUEUE_MALLOC and MSG_QUEUE_FREE macros will be used to allocate and free memory.

See also

msg_queue_create

msg_queue_send

msg

typedef struct msg msg

Structure for messages with id, type, data.

Structure that will be passed to message queues. Content of this structure will be copied to queue and can be released by sender except data pointed by data. When message is sent with msg_queue_put() entire msg structure is copied. The data part of variable size pointed by data is not copied at this time. When receiving a message, msg_release() will be called, which will in turn call free_cb(data) if free_cb() is not NULL. free_cb is set by message queue allocator when msg_queue_init_msg() is used to initialize message. It is also set with msg_init() or msq_queue_send_zero_copy() function calls.

MSG_ALLOC

typedef void*(* MSG_ALLOC) (size_t)

Message content allocator

MSG_FREE

typedef void(* MSG_FREE) (void *)

Message content free callback

MSG_ID

typedef uint16_t MSG_ID

Type for message id

msg_queue

typedef struct msq_queue msg_queue

Message queue structure.

This structure wraps OS specific queue with additional data need to handle memory allocations. If user knows that data send over specific queue will never need to be copied, memory allocator can be NULL.

MSG_SIZE

typedef uint16_t MSG_SIZE

Type for content message size

MSG_TYPE

typedef uint16_t MSG_TYPE

Type for message type

Function Documentation

msg_init()

void msg_init	(	msg *	msg,
		MSG_ID	id,
		MSG_TYPE	type,
		void *	buf,
		MSG_SIZE	size,
		MSG_FREE	free_cb
	)

Prepare message with freeing callback.

Basic function to initialize message.

Parameters

[in]	msg	pointer to message to initialize
[in]	id	message id
[in]	type	message type
[in]	buf	data to associate with message
[in]	size	size of data pointed by buf
[in]	free_cb	function to call from msg_release()

See also

msg_queue_put

msg_queue_get

msg_release

msg_queue_init_msg

msg_queue_create()

void msg_queue_create	(	msg_queue *	queue,
		int	queue_size,
		content_allocator *	allocator
	)

Create message queue.

Function creates message queue that will handle messages of type msg with small fixed size part and variable size data part.

Typical usage for task owning queue:

{
        msg_queue q;
        msg_queue_create(&q, 5, DEFAULT_OS_ALLOCATOR);
        while (1) {
               msg m;
 
               msg_queue_get(&q, &m, OS_QUEUE_FOREVER);
 
               switch (m.type) {
               ....
               }
 
               msg_release(&m);
        }
        msg_queue_delete(&q);
}

Parameters

[in]	queue	pointer to queue to initialize
[in]	queue_size	max number of elements that queue can have
[in]	allocator	structure with allocate/free functions for message content memory

See also

msq_queue_delete

msg_queue_get

msg_release

msg_queue_delete()

void msg_queue_delete

(

msg_queue *

queue

)

Delete message queue.

Function deletes message queue created with msq_queue_create().

Parameters

[in]

queue

message queue to delete

See also

msg_queue_create

msg_queue_get()

int msg_queue_get	(	msg_queue *	queue,
		msg *	msg,
		OS_TICK_TIME	timeout
	)

Get message from queue.

Function gets message from the queue. If queue is empty function waits for specified time for message. If in this time queue is still empty function fails. When receiver is done with message it must call msg_release(msg).

See description of msg_queue_create() for usage example.

Parameters

[in]	queue	queue to get message from
[in,out]	msg	pointer for message
[in]	timeout	time to wait before failure if queue is empty in ticks OS_QUEUE_NO_WAIT - do not wait at all if queue is full fail OS_QUEUE_FOREVER - wait till message can be put

Returns

OS_QUEUE_OK if message was taken from queue OS_QUEUE_EMPTY if there was no message

See also

msg_queue_put

msg_queue_create

msg_queue_init_msg()

int msg_queue_init_msg	(	msg_queue *	queue,
		msg *	msg,
		MSG_ID	id,
		MSG_TYPE	type,
		MSG_SIZE	size
	)

Initialize message with queue specific freeing callback.

This function should be called when buffer with specified size should be allocate from queue allocator.

Parameters

[in]	queue	queue to use
[in]	msg	pointer to message to initialize
[in]	id	message id
[in]	type	message type
[in]	size	required data size

Returns

0 if memory can't be allocated, 1 on success

See also

msg_init

msg_release

msg_queue_put()

int msg_queue_put	(	msg_queue *	queue,
		msg *	msg,
		OS_TICK_TIME	timeout
	)

Put message in queue.

Function adds message to the queue. If queue is full function waits for specified time to put message. If in this time queue is still full function fails.

In case function is called from ISR, functions fails immediately if there's not free space in queue (timeout parameter has no effect).

If message was not put in queue, free_cb() will be called immediately.

Typical usage for task posting to queue using msg_queue_put():

{
        msg_queue *q = ....;
        while (1) {
               msg m;
               char msg_data[10]
 
               msg_queue_init_msg(q, &m, (MSG_ID)1, (MSG_TYPE)2, sizeof(msg_data));
               memcpy(m.data, msg_data, sizeof(msg_data));
               msg_queue_put(q, &m, OS_QUEUE_FOREVER);
               ...
               ...
               msg_init(&m, (MSG_ID)1, (MSG_TYPE)2, msg_data, sizeof(msg_data), my_free_cb);
               msg_queue_put(q, &m, OS_QUEUE_FOREVER);
        }
}

Parameters

[in]	queue	queue to put message to
[in]	msg	message to send
[in]	timeout	time to wait before failure if queue is full in ticks OS_QUEUE_NO_WAIT - do not wait at all if queue is full fail OS_QUEUE_FOREVER - wait till message can be put

Returns

OS_QUEUE_OK if message was put in queue OS_QUEUE_FULL if message was not put in queue

See also

msg_queue_get

msg_queue_send()

int msg_queue_send	(	msg_queue *	queue,
		MSG_ID	id,
		MSG_TYPE	type,
		void *	buf,
		MSG_SIZE	size,
		OS_TICK_TIME	timeout
	)

Send data to queue.

This function will allocate data of size and send it to queue. buf is free to use by sender as soon as function returns, data is copied to additional buffer allocated with queue specific allocator. Function can fail in case when queue is full or there is no memory to allocate.

Typical usage for task posting to queue using msq_queue_send():

{
        msg_queue *q = ....;
        while (1) {
               char msg_data[10]
 
               strcpy(msg_data, "Simple1");
               msq_queue_send(q, (MSG_ID)1, (MSG_TYPE)2, msg_data, sizeof(msg_data),
                                                             OS_QUEUE_FOREVER);
               // No need to wait here, msg_data was copied to message buffer
               strcpy(msg_data, "Simple2");
               msq_queue_send(q, (MSG_ID)2, (MSG_TYPE)2, msg_data, sizeof(msg_data),
                                                             OS_QUEUE_FOREVER);
               ...
               ...
        }
}

Parameters

[in]	queue	queue to use
[in]	id	message id
[in]	type	message type
[in]	buf	data to associate with message
[in]	size	required data size
[in]	timeout	time to wait before failure if queue is empty in ticks OS_QUEUE_NO_WAIT - do not wait at all if queue is full fail OS_QUEUE_FOREVER - wait till message can be put

Returns

OS_QUEUE_OK if message was put in queue OS_QUEUE_FULL if message was not put in queue

msg_release()

void msg_release

(

msg *

msg

)

Release message data.

This function must be called by received when message is no longer needed. Depending of how freeing callback of message is done, it can release memory pinter by data, or it can notify sender that memory can be reused.

Parameters

[in]

msg

pointer to message to free

See also

msg_queue_put

msg_queue_get

msg_queue_init

msq_queue_send_zero_copy()

int msq_queue_send_zero_copy	(	msg_queue *	queue,
		MSG_ID	id,
		MSG_TYPE	type,
		void *	buf,
		MSG_SIZE	size,
		OS_TICK_TIME	timeout,
		MSG_FREE	free_cb
	)

Send data to queue with zero copy.

This function will send message to queue and specify callback to call when message was received or not sent at all. This function should be used if no data copy is needed and sender can keep data untouched till free_cb() is called. In this case free_cb() is used as signaling mechanism, it can signal sender by means of OS_EVENT. If message was not put in queue because it was full for specified time, free_cb() will be called anyway. If user don't want to provide freeing callback for synchronization and copy data is ok, msg_queue_send() can be simpler choice.

Typical usage for task posting to queue using msq_queue_send_zero_copy():

{
        msg_queue *q = ....;
        while (1) {
               char msg_data[10]
 
               msq_queue_send_zero_copy(q, (MSG_ID)1, (MSG_TYPE)2, msg_data, sizeof(msg_data),
                                                             OS_QUEUE_FOREVER, my_free_cb);
               ...
               ...
               // Wait for event set by my_free_cb, before using msg_data again
               OS_WAIT_EVENT(event, OS_EVENT_FOREVER);
        }
}

Parameters

[in]	queue	queue to use
[in]	id	message id
[in]	type	message type
[in]	buf	data to associate with message
[in]	size	required data size
[in]	timeout	time to wait before failure if queue is empty in ticks OS_QUEUE_NO_WAIT - do not wait at all if queue is full fail OS_QUEUE_FOREVER - wait till message can be put
[in]	free_cb	function to call from msg_release()

Returns

OS_QUEUE_OK if message was put in queue OS_QUEUE_FULL if message was not put in queue

See also

msg_queue_send