RTOS-integrated Messaging Framework implementation. More...

Data Structures
struct	sf_message_instance_ctrl_t

Macros
#define	SF_MESSAGE_CODE_VERSION_MAJOR (2U)

#define	SF_MESSAGE_QUEUE_MESSAGE_WORDS (1)

Functions
ssp_err_t	SF_MESSAGE_Open (sf_message_ctrl_t const p_api_ctrl, sf_message_cfg_t const const p_cfg)
	Initialize message framework. This function initiates the messaging framework control block, configures the work memory corresponding to the configuration parameters. More...

ssp_err_t	SF_MESSAGE_Close (sf_message_ctrl_t *const p_api_ctrl)
	Closes message framework. More...

ssp_err_t	SF_MESSAGE_BufferAcquire (sf_message_ctrl_t const const p_api_ctrl, sf_message_header_t pp_buffer, sf_message_acquire_cfg_t const const p_acquire_cfg, uint32_t const wait_option)
	Acquire buffer for message passing from the block. More...

ssp_err_t	SF_MESSAGE_BufferRelease (sf_message_ctrl_t const p_api_ctrl, sf_message_header_t const p_buffer, sf_message_release_option_t const option)
	Release buffer obtained by SF_MESSAGE_BufferAcquire(). More...

ssp_err_t	SF_MESSAGE_Post (sf_message_ctrl_t const p_api_ctrl, sf_message_header_t const const p_buffer, sf_message_post_cfg_t const const p_post_cfg, sf_message_post_err_t const p_post_err, uint32_t const wait_option)
	Post a message to the subscribers. More...

ssp_err_t	SF_MESSAGE_Pend (sf_message_ctrl_t const const p_api_ctrl, TX_QUEUE const const p_queue, sf_message_header_t **pp_buffer, uint32_t const wait_option)
	Pend on a message. More...

ssp_err_t	SF_MESSAGE_VersionGet (ssp_version_t *const p_version)
	Get the version of the messaging framework. Stores version information in provided pointer. More...

Detailed Description

RTOS-integrated Messaging Framework implementation.

Macro Definition Documentation

◆ SF_MESSAGE_CODE_VERSION_MAJOR

#define SF_MESSAGE_CODE_VERSION_MAJOR (2U)

Version of code that implements the API defined in this file

◆ SF_MESSAGE_QUEUE_MESSAGE_WORDS

#define SF_MESSAGE_QUEUE_MESSAGE_WORDS (1)

The size of a message queue in words

Function Documentation

◆ SF_MESSAGE_BufferAcquire()

ssp_err_t SF_MESSAGE_BufferAcquire	(	sf_message_ctrl_t const *const	p_api_ctrl,
		sf_message_header_t **	pp_buffer,
		sf_message_acquire_cfg_t const *const	p_acquire_cfg,
		uint32_t const	wait_option
	)

Acquire buffer for message passing from the block.

Return values

SSP_SUCCESS	Buffer acquisition was successful.
SSP_ERR_ASSERTION	p_ctrl, p_acquire_cfg or pp_buffer is NULL.
SSP_ERR_NOT_OPEN	Message framework module has yet to be opened.
SSP_ERR_NO_MORE_BUFFER	No more buffer found in the memory block pool.
SSP_ERR_TIMEOUT	OS service call returns timeout.
SSP_ERR_INTERNAL	OS service call fails.

Note: This API function allows to be called from not only thread but also ISR.

Allocates buffer in the block memory pool.

Clears buffer control block

Sets the buffer in-use flag

Sets the address of the allocated buffer to 'pp_buffer'

Clears the event class and event code in the buffer. This is because the initial value in the buffer control block is unknown and it would not be safe.

Sets the 'buffer_keep' flag in the buffer control block if SF_MESSAGE_ACQUIRE_OPTION_KEEP is set to the 'option' argument

◆ SF_MESSAGE_BufferRelease()

ssp_err_t SF_MESSAGE_BufferRelease	(	sf_message_ctrl_t *const	p_api_ctrl,
		sf_message_header_t *const	p_buffer,
		sf_message_release_option_t const	option
	)

Release buffer obtained by SF_MESSAGE_BufferAcquire().

Return values

SSP_SUCCESS	Buffer release was successful.
SSP_ERR_NOT_OPEN	Message framework module has yet to be opened.
SSP_ERR_ASSERTION	p_ctrl or p_buffer is NULL.
SSP_ERR_ILLEGAL_BUFFER_ADDRESS	If buffer address is not aligned or p_buffer is not in the block pool range.
SSP_ERR_BUFFER_RELEASED	Buffer has been released.
SSP_ERR_INTERNAL	OS service call fails

Note: This API function allows to be called from thread but also from ISR.

Calculates the address of the buffer control block

Release buffer in the condition below. (1) The counting semaphore is zero and the buffer keep option is not specified. (2) 'option' is set to SF_MESSAGE_RELEASE_OPTION_FORCED_RELEASE.

Clears the flags in the buffer control block.

Release the buffer using ThreadX API "tx_block_release"

Set back the backed up interrupt mask level.

Invokes an user callback function if it is registered in the condition below. (1) The counting semaphore is zero. (2) 'option' is set to SF_MESSAGE_RELEASE_OPTION_FORCED_RELEASE.

Sets SF_MESSAGE_CALLBACK_EVENT_NAK if any subscribers for the message have responded NAK

Sets SF_MESSAGE_CALLBACK_EVENT_ACK if all subscribers for the message have responded ACK

Sets the pointer to the context to kept in the buffer control block

Invokes the registered user callback function.

◆ SF_MESSAGE_Close()

ssp_err_t SF_MESSAGE_Close ( sf_message_ctrl_t *const p_api_ctrl )

Closes message framework.

Return values

SSP_SUCCESS	Successful close.
SSP_ERR_ASSERTION	p_ctrl is NULL.
SSP_ERR_NOT_OPEN	Message framework module has yet to be opened.
SSP_ERR_ILLEGAL_SUBSCRIBER_LISTS	Message subscriber lists is illegal.

Note: This API function only allows to be called from thread context.

Finds subscribers and flushes their queues

Deletes memory pools allocated in the work memory

◆ SF_MESSAGE_Open()

ssp_err_t SF_MESSAGE_Open	(	sf_message_ctrl_t *const	p_api_ctrl,
		sf_message_cfg_t const *const	p_cfg
	)

Initialize message framework. This function initiates the messaging framework control block, configures the work memory corresponding to the configuration parameters.

Return values

SSP_SUCCESS	Initialization was successful.
SSP_ERR_ASSERTION	p_ctrl, p_cfg or p_cfg->p_work_memory_start is NULL.
SSP_ERR_INTERNAL	OS service call fails.
SSP_ERR_IN_USE	The Messaging Framework is in use.
SSP_ERR_INVALID_WORKBUFFER_SIZE	Invalid work buffer size.
SSP_ERR_INVALID_MSG_BUFFER_SIZE	Message buffer size is invalid.
SSP_ERR_ILLEGAL_SUBSCRIBER_LISTS	Message subscriber lists is illegal.

Note: This API function is allowed to be called once per instance. The behavior if called twice is undefined.; This API function only allows to be called from thread context.

Creates the memory pools in the work memory area

Registers subscriber lists

Changes the messaging framework status from CLOSED to OPENED

◆ SF_MESSAGE_Pend()

ssp_err_t SF_MESSAGE_Pend	(	sf_message_ctrl_t const *const	p_api_ctrl,
		TX_QUEUE const *const	p_queue,
		sf_message_header_t **	pp_buffer,
		uint32_t const	wait_option
	)

Pend on a message.

Return values

SSP_SUCCESS	Message pending was successful.
SSP_ERR_ASSERTION	p_ctrl, pp_buffer or p_queue is NULL.
SSP_ERR_NOT_OPEN	Message framework module has yet to be opened.
SSP_ERR_MESSAGE_QUEUE_EMPTY	Queue is empty.
SSP_ERR_TIMEOUT	OS service call returns timeout.
SSP_ERR_INTERNAL	OS service call fails.

Note: This API function allows to be called from not only thread but also ISR(if wait_option is TX_NO_WAIT).

Receiving message here. Receiving data is not message itself but the pointer to the buffer

If there is no data in the message queue and TX_NO_WAIT is specified to wait_option, return immediately with SSP_ERR_MESSAGE_QUEUE_EMPTY error code

◆ SF_MESSAGE_Post()

ssp_err_t SF_MESSAGE_Post	(	sf_message_ctrl_t *const	p_api_ctrl,
		sf_message_header_t const *const	p_buffer,
		sf_message_post_cfg_t const *const	p_post_cfg,
		sf_message_post_err_t *const	p_post_err,
		uint32_t const	wait_option
	)

Post a message to the subscribers.

Return values

SSP_SUCCESS	Message posting was successful.
SSP_ERR_ASSERTION	p_ctrl or p_buffer is NULL.
SSP_ERR_NOT_OPEN	Message framework module has yet to be opened.
SSP_ERR_NO_SUBSCRIBER_FOUND	No subscriber found.
SSP_ERR_BUFFER_RELEASED	Buffer has been released.
SSP_ERR_MESSAGE_QUEUE_FULL	Queue is full (Timeout occurs before sending a message if timeout option is specified)
SSP_ERR_ILLEGAL_BUFFER_ADDRESS	If buffer address is not aligned or p_buffer is not in the block pool range.
SSP_ERR_INTERNAL	OS service call fails

Note: This API function allows to be called from not only thread but also ISR(if wait_option is TX_NO_WAIT).; Another buffer writing to the buffer before the message read by message consumers results data overwriting.

Checks the number of the subscribers of specified event class

Calculates the address of the buffer control block

Counts up the counting semaphore in the buffer control block

Registers user callback function and context passed from user

◆ SF_MESSAGE_VersionGet()

ssp_err_t SF_MESSAGE_VersionGet ( ssp_version_t *const p_version )

Get the version of the messaging framework. Stores version information in provided pointer.

Return values

SSP_SUCCESS	Got version number successfully.
SSP_ERR_ASSERTION	p_version is NULL.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ SF_MESSAGE_CODE_VERSION_MAJOR

◆ SF_MESSAGE_QUEUE_MESSAGE_WORDS

Function Documentation

◆ SF_MESSAGE_BufferAcquire()

◆ SF_MESSAGE_BufferRelease()

◆ SF_MESSAGE_Close()

◆ SF_MESSAGE_Open()

◆ SF_MESSAGE_Pend()

◆ SF_MESSAGE_Post()

◆ SF_MESSAGE_VersionGet()