This group contains the Message Queue Handler implementation. More...

Files
file	coremsg.h
	This header file provides interfaces of the Message Queue Handler which are only used by the implementation.

file	coremsgbuffer.h
	This header file provides interfaces of the Message Queue Handler which are used by the implementation, the Application Configuration, and the API.

file	coremsgimpl.h
	This header file provides interfaces of the Message Queue Handler which are used by the implementation and the Application Configuration.

file	coremsg.c
	This source file contains the implementation of _CORE_message_queue_Initialize().

file	coremsgbroadcast.c
	This source file contains the implementation of _CORE_message_queue_Broadcast().

file	coremsgclose.c
	This source file contains the implementation of _CORE_message_queue_Close().

file	coremsgflush.c
	This source file contains the implementation of _CORE_message_queue_Flush().

file	coremsgflushwait.c
	This source file contains the implementation of _CORE_message_queue_Flush_waiting_threads().

file	coremsginsert.c
	This source file contains the implementation of _CORE_message_queue_Insert_message().

file	coremsgseize.c
	This source file contains the implementation of _CORE_message_queue_Seize().

file	coremsgsubmit.c
	This source file contains the implementation of _CORE_message_queue_Submit().

file	coremsgwkspace.c
	This source file contains the implementation of _CORE_message_queue_Workspace_allocate().

Data Structures
struct	CORE_message_queue_Control
	Control block used to manage each message queue. More...

struct	CORE_message_queue_Buffer
	The structure is used to organize message buffers of a message queue. More...

Macros
#define	RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

#define	RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

#define	CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX
	Used when appending messages onto a message queue.

#define	CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
	Used when prepending messages onto a message queue.

#define	_CORE_message_queue_Set_notify(the_message_queue, the_handler) do { } while ( 0 )
	Initializes notification information.

Typedefs
typedef struct CORE_message_queue_Control	CORE_message_queue_Control

typedef int	CORE_message_queue_Submit_types
	The modes in which a message may be submitted to a message queue.

typedef void (	CORE_message_queue_Allocate_buffers) (CORE_message_queue_Control the_message_queue, size_t size, const void arg)
	This handler shall allocate the message buffer storage area for a message queue.

Enumerations
enum	CORE_message_queue_Disciplines { CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO , CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY }
	The possible blocking disciplines for a message queue. More...

Functions
void *	_CORE_message_queue_Workspace_allocate (CORE_message_queue_Control the_message_queue, size_t size, const void arg)
	This handler allocates the message buffer storage area for a message queue from the RTEMS Workspace.

Status_Control	_CORE_message_queue_Initialize (CORE_message_queue_Control the_message_queue, CORE_message_queue_Disciplines discipline, uint32_t maximum_pending_messages, size_t maximum_message_size, CORE_message_queue_Allocate_buffers allocate_buffers, const void arg)
	Initializes a message queue.

void	_CORE_message_queue_Close (CORE_message_queue_Control the_message_queue, Thread_queue_Context queue_context)
	Closes a message queue.

uint32_t	_CORE_message_queue_Flush (CORE_message_queue_Control the_message_queue, Thread_queue_Context queue_context)
	Flushes pending messages.

Status_Control	_CORE_message_queue_Broadcast (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, uint32_t count, Thread_queue_Context queue_context)
	Broadcasts a message to the message queue.

Status_Control	_CORE_message_queue_Submit (CORE_message_queue_Control the_message_queue, Thread_Control executing, const void buffer, size_t size, CORE_message_queue_Submit_types submit_type, bool wait, Thread_queue_Context queue_context)
	Submits a message to the message queue.

Status_Control	_CORE_message_queue_Seize (CORE_message_queue_Control the_message_queue, Thread_Control executing, void buffer, size_t size_p, bool wait, Thread_queue_Context *queue_context)
	Seizes a message from the message queue.

void	_CORE_message_queue_Insert_message (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer the_message, const void *content_source, size_t content_size, CORE_message_queue_Submit_types submit_type)
	Inserts a message into the message queue.

Detailed Description

This group contains the Message Queue Handler implementation.

This handler encapsulates functionality which provides the foundation Message Queue services used in all of the APIs supported by RTEMS.

Macro Definition Documentation

◆ _CORE_message_queue_Set_notify

#define _CORE_message_queue_Set_notify	(	the_message_queue,
		the_handler
	)	do { } while ( 0 )

Initializes notification information.

This routine initializes the notification information for the_message_queue.

Parameters

[out]	the_message_queue	The message queue to initialize the notification information.
[out]	the_handler	The notification information for the message queue.

◆ CORE_MESSAGE_QUEUE_SEND_REQUEST

#define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX

Used when appending messages onto a message queue.

This is the priority constant used when appending messages onto a message queue.

◆ CORE_MESSAGE_QUEUE_URGENT_REQUEST

#define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN

Used when prepending messages onto a message queue.

This is the priority constant used when prepending messages onto a message queue.

◆ RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

#define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

This macro is defined when an API is enabled that requires the Message Queue Handler include support for blocking send operations.

◆ RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

#define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

This define enables the support for priority based enqueuing of messages in the Message Queue Handler.

Typedef Documentation

◆ CORE_message_queue_Allocate_buffers

typedef void *(* CORE_message_queue_Allocate_buffers) (CORE_message_queue_Control *the_message_queue, size_t size, const void *arg)

This handler shall allocate the message buffer storage area for a message queue.

The handler shall set the CORE_message_queue_Control::free_message_buffers member.

Parameters

[out]	the_message_queue	is the message queue control.
	size	is the message buffer storage area size to allocate.
	arg	is the handler argument.

Return values

NULL	The allocation failed.

Returns: Otherwise the pointer to the allocated message buffer storage area begin shall be returned.

◆ CORE_message_queue_Submit_types

typedef int CORE_message_queue_Submit_types

The modes in which a message may be submitted to a message queue.

The following type details the modes in which a message may be submitted to a message queue. The message may be posted in a send or urgent fashion.

Note: All other values are message priorities. Numerically smaller priorities indicate higher priority messages.

Enumeration Type Documentation

◆ CORE_message_queue_Disciplines

enum CORE_message_queue_Disciplines

The possible blocking disciplines for a message queue.

This enumerated types defines the possible blocking disciplines for a message queue.

Enumerator
CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO	This value indicates that blocking tasks are in FIFO order.
CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY	This value indicates that blocking tasks are in priority order.

Function Documentation

◆ _CORE_message_queue_Broadcast()

Status_Control _CORE_message_queue_Broadcast	(	CORE_message_queue_Control *	the_message_queue,
		const void *	buffer,
		size_t	size,
		uint32_t *	count,
		Thread_queue_Context *	queue_context
	)

Broadcasts a message to the message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function sends a message for every thread waiting on the queue and returns the number of threads made ready by the message.

Parameters

[in,out]	the_message_queue	The message queue to operate upon.
	buffer	The starting address of the message to broadcast.
	size	The size of the message being broadcast.
[out]	count	The variable that will contain the number of tasks that are sent this message.
	queue_context	The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

Return values

STATUS_SUCCESSFUL	The message was successfully broadcast.
STATUS_MESSAGE_INVALID_SIZE	The message size was too big.

◆ _CORE_message_queue_Close()

void _CORE_message_queue_Close	(	CORE_message_queue_Control *	the_message_queue,
		Thread_queue_Context *	queue_context
	)

Closes a message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function closes a message by returning all allocated space and flushing the_message_queue's task wait queue.

Parameters

[in,out]	the_message_queue	The message queue to close.
[in,out]	queue_context	The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

◆ _CORE_message_queue_Flush()

uint32_t _CORE_message_queue_Flush	(	CORE_message_queue_Control *	the_message_queue,
		Thread_queue_Context *	queue_context
	)

Flushes pending messages.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This function flushes the_message_queue's pending message queue. The number of messages flushed from the queue is returned.

Parameters

[in,out]	the_message_queue	The message queue to flush.
	queue_context	The thread queue context with interrupts disabled.

Returns: This method returns the number of message pending messages flushed.

◆ _CORE_message_queue_Initialize()

Status_Control _CORE_message_queue_Initialize	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Disciplines	discipline,
		uint32_t	maximum_pending_messages,
		size_t	maximum_message_size,
		CORE_message_queue_Allocate_buffers	allocate_buffers,
		const void *	arg
	)

Initializes a message queue.

Parameters

[out]	the_message_queue	is the message queue to initialize.
	discipline	is the blocking discipline for the message queue.
	maximum_pending_messages	is the maximum number of messages that will be allowed to be pending at any given time.
	maximum_message_size	is the size of the largest message that may be sent to this message queue instance.
	allocate_buffers	is the message buffer storage area allocation handler.
	arg	is the message buffer storage area allocation handler argument.

Return values

STATUS_SUCCESSFUL	The message queue was initialized.
STATUS_MESSAGE_QUEUE_INVALID_SIZE	Calculations with the maximum pending messages or maximum message size produced an integer overflow.
STATUS_MESSAGE_QUEUE_NO_MEMORY	The message buffer storage area allocation failed.

◆ _CORE_message_queue_Insert_message()

void _CORE_message_queue_Insert_message	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Buffer *	the_message,
		const void *	content_source,
		size_t	content_size,
		CORE_message_queue_Submit_types	submit_type
	)

Inserts a message into the message queue.

Copies the specified content into the message storage space and then inserts the message into the message queue according to the submit type.

Parameters

[in,out]	the_message_queue	The message queue to insert a message in.
[in,out]	the_message	The message to insert in the message queue.
	content_source	The message content source.
	content_size	The message content size in bytes.
	submit_type	Determines whether the message is prepended, appended, or enqueued in priority order.

◆ _CORE_message_queue_Seize()

Status_Control _CORE_message_queue_Seize	(	CORE_message_queue_Control *	the_message_queue,
		Thread_Control *	executing,
		void *	buffer,
		size_t *	size_p,
		bool	wait,
		Thread_queue_Context *	queue_context
	)

Seizes a message from the message queue.

This package is the implementation of the CORE Message Queue Handler. This core object provides task synchronization and communication functions via messages passed to queue objects.

This kernel routine dequeues a message, copies the message buffer to a given destination buffer, and frees the message buffer to the inactive message pool. The thread will be blocked if wait is true, otherwise an error will be given to the thread if no messages are available.

Parameters

[in,out]	the_message_queue	The message queue to seize a message from.
	executing	The executing thread.
[out]	buffer	The starting address of the message buffer to to be filled in with a message.
[out]	size_p	The size of the buffer, indicates the maximum size message that the caller can receive.
	wait	Indicates whether the calling thread is willing to block if the message queue is empty.
	queue_context	The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

Return values

STATUS_SUCCESSFUL	The message was successfully seized from the message queue.
STATUS_UNSATISFIED	Wait was set to false and there is currently no pending message.
STATUS_TIMEOUT	A timeout occurred.

Note: Returns message priority via return area in TCB.

INTERRUPT LATENCY:
- available
- wait

◆ _CORE_message_queue_Submit()

Status_Control _CORE_message_queue_Submit	(	CORE_message_queue_Control *	the_message_queue,
		Thread_Control *	executing,
		const void *	buffer,
		size_t	size,
		CORE_message_queue_Submit_types	submit_type,
		bool	wait,
		Thread_queue_Context *	queue_context
	)

Submits a message to the message queue.

This routine implements the send and urgent message functions. It processes a message that is to be submitted to the designated message queue. The message will either be processed as a send message which it will be inserted at the rear of the queue or it will be processed as an urgent message which will be inserted at the front of the queue.

Parameters

[in,out]	the_message_queue	The message queue to operate upon.
	executing	The executing thread.
	buffer	The starting address of the message to send.
	size	The size of the message being send.
	submit_type	Determines whether the message is prepended, appended, or enqueued in priority order.
	wait	Indicates whether the calling thread is willing to block if the message queue is full.
	queue_context	The thread queue context used for _CORE_message_queue_Acquire() or _CORE_message_queue_Acquire_critical().

Return values

STATUS_SUCCESSFUL	The message was successfully submitted to the message queue.
STATUS_MESSAGE_INVALID_SIZE	The message size was too big.
STATUS_TOO_MANY	No message buffers were available.
STATUS_MESSAGE_QUEUE_WAIT_IN_ISR	The caller is in an ISR, do not block!
STATUS_TIMEOUT	A timeout occurred.

◆ _CORE_message_queue_Workspace_allocate()

void * _CORE_message_queue_Workspace_allocate	(	CORE_message_queue_Control *	the_message_queue,
		size_t	size,
		const void *	arg
	)

This handler allocates the message buffer storage area for a message queue from the RTEMS Workspace.

The handler sets the CORE_message_queue_Control::free_message_buffers to _Workspace_Free().

Parameters

[out]	the_message_queue	is the message queue control.
	size	is the message buffer storage area size to allocate.
	arg	is the unused handler argument.

Return values

NULL	The allocation failed.

Returns: Otherwise the pointer to the allocated message buffer storage area begin is returned.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ _CORE_message_queue_Set_notify

◆ CORE_MESSAGE_QUEUE_SEND_REQUEST

◆ CORE_MESSAGE_QUEUE_URGENT_REQUEST

◆ RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND

◆ RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY

Typedef Documentation

◆ CORE_message_queue_Allocate_buffers

◆ CORE_message_queue_Submit_types

Enumeration Type Documentation

◆ CORE_message_queue_Disciplines

Function Documentation

◆ _CORE_message_queue_Broadcast()

◆ _CORE_message_queue_Close()

◆ _CORE_message_queue_Flush()

◆ _CORE_message_queue_Initialize()

◆ _CORE_message_queue_Insert_message()

◆ _CORE_message_queue_Seize()

◆ _CORE_message_queue_Submit()

◆ _CORE_message_queue_Workspace_allocate()