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

Collaboration diagram for Message Queue Handler:

Files
file	coremsg.c
	Initialize a Message Queue.

file	coremsgbroadcast.c
	Broadcast a Message to the Message Queue.

file	coremsgclose.c
	Close a Message Queue.

file	coremsgflush.c
	Flush Messages Routine.

file	coremsgflushwait.c
	Flush Waiting Threads.

file	coremsginsert.c
	Insert a Message into the Message Queue.

file	coremsgseize.c
	Size a Message from the Message Queue.

file	coremsgsubmit.c
	CORE Message Queue Submit.

Data Structures
struct	CORE_message_queue_Buffer
	Data types needed to manipulate the contents of message buffers. More...

struct	CORE_message_queue_Buffer_control
	The organization of a message buffer. More...

struct	CORE_message_queue_Attributes
	Control block used to manage the attributes of each message queue. More...

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

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

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

#define	CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
	Core message queue last status value. More...

#define	_CORE_message_queue_Set_notify(the_message_queue, the_handler, the_argument)
	This routine initializes the notification information for the_message_queue.

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

typedef void(*	CORE_message_queue_API_mp_support_callout) (Thread_Control *, Objects_Id)
	Callout provides to support global/multiprocessor operations. More...

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...

enum	CORE_message_queue_Status { CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL, CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE, CORE_MESSAGE_QUEUE_STATUS_TOO_MANY, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT, CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED, CORE_MESSAGE_QUEUE_STATUS_TIMEOUT, CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT }
	The possible set of Core Message Queue handler return statuses. More...

Functions
bool	_CORE_message_queue_Initialize (CORE_message_queue_Control the_message_queue, CORE_message_queue_Attributes the_message_queue_attributes, uint32_t maximum_pending_messages, size_t maximum_message_size)
	Initialize a message queue. More...

void	_CORE_message_queue_Close (CORE_message_queue_Control *the_message_queue, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Close a message queue. More...

uint32_t	_CORE_message_queue_Flush (CORE_message_queue_Control the_message_queue, ISR_lock_Context lock_context)
	Flush pending messages. More...

CORE_message_queue_Status	_CORE_message_queue_Broadcast (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, uint32_t count, ISR_lock_Context lock_context)
	Broadcast a message to the message queue. More...

CORE_message_queue_Status	_CORE_message_queue_Submit (CORE_message_queue_Control the_message_queue, Thread_Control executing, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, CORE_message_queue_Submit_types submit_type, bool wait, Watchdog_Interval timeout, ISR_lock_Context lock_context)
	Submit a message to the message queue. More...

void	_CORE_message_queue_Seize (CORE_message_queue_Control the_message_queue, Thread_Control executing, Objects_Id id, void buffer, size_t size_p, bool wait, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	Size a message from the message queue. More...

void	_CORE_message_queue_Insert_message (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer_control the_message, CORE_message_queue_Submit_types submit_type)
	Insert a message into the message queue. More...

RTEMS_INLINE_ROUTINE CORE_message_queue_Status	_CORE_message_queue_Send (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, bool wait, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	This routine sends a message to the end of the specified message queue.

RTEMS_INLINE_ROUTINE CORE_message_queue_Status	_CORE_message_queue_Urgent (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, Objects_Id id, CORE_message_queue_API_mp_support_callout api_message_queue_mp_support, bool wait, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	This routine sends a message to the front of the specified message queue.

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Acquire (CORE_message_queue_Control the_message_queue, ISR_lock_Context lock_context)

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Acquire_critical (CORE_message_queue_Control the_message_queue, ISR_lock_Context lock_context)

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Release (CORE_message_queue_Control the_message_queue, ISR_lock_Context lock_context)

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Copy_buffer (const void source, void destination, size_t size)
	This routine copies the contents of the source message buffer to the destination message buffer.

RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control *	_CORE_message_queue_Allocate_message_buffer (CORE_message_queue_Control *the_message_queue)
	This function allocates a message buffer from the inactive message buffer chain.

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Free_message_buffer (CORE_message_queue_Control the_message_queue, CORE_message_queue_Buffer_control the_message)
	This routine frees a message buffer to the inactive message buffer chain.

RTEMS_INLINE_ROUTINE int	_CORE_message_queue_Get_message_priority (const CORE_message_queue_Buffer_control *the_message)
	This function returns the priority of the_message. More...

RTEMS_INLINE_ROUTINE void	_CORE_message_queue_Set_message_priority (CORE_message_queue_Buffer_control *the_message, int priority)
	This function sets the priority of the_message. More...

RTEMS_INLINE_ROUTINE CORE_message_queue_Buffer_control *	_CORE_message_queue_Get_pending_message (CORE_message_queue_Control *the_message_queue)
	This function removes the first message from the_message_queue and returns a pointer to it.

RTEMS_INLINE_ROUTINE bool	_CORE_message_queue_Is_priority (CORE_message_queue_Attributes *the_attribute)
	This function returns true if the priority attribute is enabled in the attribute_set and false otherwise.

RTEMS_INLINE_ROUTINE Thread_Control *	_CORE_message_queue_Dequeue_receiver (CORE_message_queue_Control the_message_queue, const void buffer, size_t size, CORE_message_queue_Submit_types submit_type, ISR_lock_Context *lock_context)

Detailed Description

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_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_STATUS_LAST

#define CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT

Core message queue last status value.

This is the last status value.

Referenced by _POSIX_Message_queue_Translate_core_message_queue_return_code().

◆ 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.

Typedef Documentation

◆ CORE_message_queue_API_mp_support_callout

typedef void( * CORE_message_queue_API_mp_support_callout) (Thread_Control *, Objects_Id)

Callout provides to support global/multiprocessor operations.

The following type defines the callout which the API provides to support global/multiprocessor operations on message_queues.

◆ 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.

◆ CORE_message_queue_Status

enum CORE_message_queue_Status

The possible set of Core Message Queue handler return statuses.

This enumerated type defines the possible set of Core Message Queue handler return statuses.

Enumerator
CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL	This value indicates the operation completed sucessfully.
CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE	This value indicates that the message was too large for this queue.
CORE_MESSAGE_QUEUE_STATUS_TOO_MANY	This value indicates that there are too many messages pending.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED	This value indicates that a receive was unsuccessful.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT	This value indicates that a blocking send was unsuccessful.
CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED	This value indicates that the message queue being blocked upon was deleted while the thread was waiting.
CORE_MESSAGE_QUEUE_STATUS_TIMEOUT	This value indicates that the thread had to timeout while waiting to receive a message because one did not become available.
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT	This value indicates that a blocking receive was unsuccessful.

Function Documentation

◆ _CORE_message_queue_Broadcast()

CORE_message_queue_Status _CORE_message_queue_Broadcast	(	CORE_message_queue_Control *	the_message_queue,
		const void *	buffer,
		size_t	size,
		Objects_Id	id,
		CORE_message_queue_API_mp_support_callout	api_message_queue_mp_support,
		uint32_t *	count,
		ISR_lock_Context *	lock_context
	)

Broadcast 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]	the_message_queue	points to the message queue
[in]	buffer	is the starting address of the message to broadcast
[in]	size	is the size of the message being broadcast
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	api_message_queue_mp_support	is the routine to invoke if a thread that is unblocked is actually a remote thread.
[out]	count	points to the variable that will contain the number of tasks that are sent this message
[in]	lock_context	The lock context of the interrupt disable.

Return values

◆ _CORE_message_queue_Close()

void _CORE_message_queue_Close	(	CORE_message_queue_Control *	the_message_queue,
		Thread_queue_Flush_callout	remote_extract_callout,
		uint32_t	status
	)

Close 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]	the_message_queue	points to the message queue to close
[in]	remote_extract_callout	is the routine to call for each thread that is extracted from the set of waiting threads
[in]	status	is the status that each waiting thread will return from it's blocking service

Referenced by _POSIX_Message_queue_Delete().

◆ _CORE_message_queue_Flush()

uint32_t _CORE_message_queue_Flush	(	CORE_message_queue_Control *	the_message_queue,
		ISR_lock_Context *	lock_context
	)

Flush 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]	the_message_queue	points to the message queue to flush
[in]	lock_context	The lock context of the interrupt disable.

Return values

This	method returns the number of message pending messages flushed.

◆ _CORE_message_queue_Get_message_priority()

RTEMS_INLINE_ROUTINE int _CORE_message_queue_Get_message_priority ( const CORE_message_queue_Buffer_control * the_message )

This function returns the priority of the_message.

Note: It encapsulates the optional behavior that message priority is disabled if no API requires it.

◆ _CORE_message_queue_Initialize()

bool _CORE_message_queue_Initialize	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Attributes *	the_message_queue_attributes,
		uint32_t	maximum_pending_messages,
		size_t	maximum_message_size
	)

Initialize 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 routine initializes the_message_queue based on the parameters passed.

Parameters

[in]	the_message_queue	points to the message queue to initialize
[in]	the_message_queue_attributes	points to the attributes that will be used with this message queue instance
[in]	maximum_pending_messages	is the maximum number of messages that will be allowed to pend at any given time
[in]	maximum_message_size	is the size of largest message that may be sent to this message queue instance

Return values

true	if the message queue can be initialized. In general, false will only be returned if memory for the pending messages cannot be allocated.

References _CORE_message_queue_Set_notify, CORE_message_queue_Control::maximum_message_size, CORE_message_queue_Control::maximum_pending_messages, and CORE_message_queue_Control::number_of_pending_messages.

◆ _CORE_message_queue_Insert_message()

void _CORE_message_queue_Insert_message	(	CORE_message_queue_Control *	the_message_queue,
		CORE_message_queue_Buffer_control *	the_message,
		CORE_message_queue_Submit_types	submit_type
	)

Insert a message into the message queue.

This kernel routine inserts the specified message into the message queue. It is assumed that the message has been filled in before this routine is called.

Parameters

[in]	the_message_queue	points to the message queue
[in]	the_message	is the message to enqueue
[in]	submit_type	determines whether the message is prepended, appended, or enqueued in priority order.

INTERRUPT LATENCY:
- insert

◆ _CORE_message_queue_Seize()

void _CORE_message_queue_Seize	(	CORE_message_queue_Control *	the_message_queue,
		Thread_Control *	executing,
		Objects_Id	id,
		void *	buffer,
		size_t *	size_p,
		bool	wait,
		Watchdog_Interval	timeout,
		ISR_lock_Context *	lock_context
	)

Size 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]	the_message_queue	points to the message queue
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	buffer	is the starting address of the message buffer to to be filled in with a message
[in]	size_p	is a pointer to the size of the buffer and indicates the maximum size message that the caller can receive.
[in]	wait	indicates whether the calling thread is willing to block if the message queue is empty.
[in]	timeout	is the maximum number of clock ticks that the calling thread is willing to block if the message queue is empty.
[in]	lock_context	The lock context of the interrupt disable.

Return values

indication of the successful completion or reason for failure. On success, the location pointed to size_p will contain the size of the received message.

Note: Returns message priority via return area in TCB.

INTERRUPT LATENCY:
- available
- wait

◆ _CORE_message_queue_Set_message_priority()

RTEMS_INLINE_ROUTINE void _CORE_message_queue_Set_message_priority	(	CORE_message_queue_Buffer_control *	the_message,
		int	priority
	)

This function sets the priority of the_message.

Note: It encapsulates the optional behavior that message priority is disabled if no API requires it.

References RTEMS_INLINE_ROUTINE.

◆ _CORE_message_queue_Submit()

CORE_message_queue_Status _CORE_message_queue_Submit	(	CORE_message_queue_Control *	the_message_queue,
		Thread_Control *	executing,
		const void *	buffer,
		size_t	size,
		Objects_Id	id,
		CORE_message_queue_API_mp_support_callout	api_message_queue_mp_support,
		CORE_message_queue_Submit_types	submit_type,
		bool	wait,
		Watchdog_Interval	timeout,
		ISR_lock_Context *	lock_context
	)

Submit 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]	the_message_queue	points to the message queue
[in]	buffer	is the starting address of the message to send
[in]	size	is the size of the message being send
[in]	id	is the RTEMS object Id associated with this message queue. It is used when unblocking a remote thread.
[in]	api_message_queue_mp_support	is the routine to invoke if a thread that is unblocked is actually a remote thread.
[in]	submit_type	determines whether the message is prepended, appended, or enqueued in priority order.
[in]	wait	indicates whether the calling thread is willing to block if the message queue is full.
[in]	timeout	is the maximum number of clock ticks that the calling thread is willing to block if the message queue is full.
[in]	lock_context	The lock context of the interrupt disable.

Return values

indication of the successful completion or reason for failure

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CORE_MESSAGE_QUEUE_SEND_REQUEST

◆ CORE_MESSAGE_QUEUE_STATUS_LAST

◆ CORE_MESSAGE_QUEUE_URGENT_REQUEST

Typedef Documentation

◆ CORE_message_queue_API_mp_support_callout

◆ CORE_message_queue_Submit_types

Enumeration Type Documentation

◆ CORE_message_queue_Disciplines

◆ CORE_message_queue_Status

Function Documentation

◆ _CORE_message_queue_Broadcast()

◆ _CORE_message_queue_Close()

◆ _CORE_message_queue_Flush()

◆ _CORE_message_queue_Get_message_priority()

◆ _CORE_message_queue_Initialize()

◆ _CORE_message_queue_Insert_message()

◆ _CORE_message_queue_Seize()

◆ _CORE_message_queue_Set_message_priority()

◆ _CORE_message_queue_Submit()