Regulator Internal Information. More...

Files
file	regulatorimpl.h
	Regulator Library Implementation Support.

Data Structures
struct	_Regulator_Message_t
	Regulator Message Instance Management Structure. More...

struct	_Regulator_Statistics
	Regulator Statistics Private Structure. More...

struct	_Regulator_Control
	Regulator Instance Private Structure. More...

Macros
#define	REGULATOR_INITIALIZED 0xDeadF00d

Functions
rtems_status_code	rtems_regulator_create (rtems_regulator_attributes attributes, rtems_regulator_instance *regulator)
	Create a regulator.

rtems_status_code	rtems_regulator_delete (rtems_regulator_instance *regulator, rtems_interval ticks)
	Delete a regulator.

rtems_status_code	rtems_regulator_obtain_buffer (rtems_regulator_instance regulator, void *buffer)
	Obtain Buffer from Regulator.

rtems_status_code	rtems_regulator_release_buffer (rtems_regulator_instance regulator, void buffer)
	Release Previously Obtained Regulator Buffer.

rtems_status_code	rtems_regulator_send (rtems_regulator_instance regulator, void message, size_t length)
	Send to regulator instance.

rtems_status_code	rtems_regulator_get_statistics (rtems_regulator_instance regulator, rtems_regulator_statistics statistics)
	Obtain statistics for regulator instance.

Detailed Description

Regulator Internal Information.

This concerns implementation information about the Regulator.

Macro Definition Documentation

◆ REGULATOR_INITIALIZED

#define REGULATOR_INITIALIZED 0xDeadF00d

This constant is used to indicate the regulator instance is initialized.

Function Documentation

◆ rtems_regulator_create()

rtems_status_code rtems_regulator_create	(	rtems_regulator_attributes *	attributes,
		rtems_regulator_instance **	regulator
	)

Create a regulator.

This function creates an instance of a regulator. It uses the provided attributes to create the instance return in regulator. This instance will allocate the buffers associated with the regulator instance as well as the Delivery thread.

The attributes structure defines the priority and stack size of the Delivery thread dedicated to this regulator instance. It also defines the period of the Delivery thread and the maximum number of messages that may be delivered per period via invocation of the delivery function.

For each regulator instance, the following resources are allocated:

A memory area for the regulator control block using malloc().
A RTEMS Classic API Message Queue is constructed with message buffer memory allocated using malloc(). Each message consists of a pointer and a length.
A RTEMS Classic API Partition.
A RTEMS Classic API Rate Monotonic Period.

Parameters

[in]	attributes	specify the regulator instance attributes
[in,out]	regulator	will point to the regulator instance

Returns: an RTEMS status code indicating success or failure.

Note: This function allocates memory for the buffers holding messages, an Delivery thread and an RTEMS partition. When it executes, the Delivery thread will create an RTEMS rate monotonic period.

Perform basic validation of parameters

Verify attributes are OK. Some are checked by calls to object create methods. Specifically the following are not checked:

delivery_thread_priority by rtems_task_create()
delivery_thread_stack_size can be any value

Allocate memory for regulator instance

We do NOT want the delivery_thread_id field to be initialized to 0. If the rtems_task_create() fails, then the field will not be overwritten. This results in an attempt to rtems_task_delete(0) during clean up. The thread ID of 0 is self which results in the calling thread accidentally deleting itself.

Copy the attributes to an internal area for later use

Allocate memory for the messages. There is no need to zero out the message memory because the user should fill that in.

Associate message memory with a partition so allocations are atomic

Create the message queue between the sender and output thread

Note: A rate monotonic period object must be created by the thread using it. Thus that specific create operation is not included in this method. All other resources are allocated here.

Create the output thread Using the priority and stack size attributes specified by the user.

Start the output thread.

Note: There should be no way this call can fail. The task id is valid, the regulator output thread entry point is valid, and the argument is valid.

The regulator is successfully initialized. Set the initialized field to reflect this and return the instance pointer.

◆ rtems_regulator_delete()

rtems_status_code rtems_regulator_delete	(	rtems_regulator_instance *	regulator,
		rtems_interval	ticks
	)

Delete a regulator.

This function is used to delete the specified regulator instance.

It is the responsibility of the user to ensure that any resources such as sockets or open file descriptors used by the delivery function are also deleted. It is likely safer to delete those delivery resources after deleting the regulator instance rather than before.

Parameters

[in]	regulator	is the instance to delete
[in]	ticks	is the maximum number of ticks to wait for the delivery thread to shutdown.

Returns: an RTEMS status code indicating success or failure.

Note: This function deallocates the resources allocated during rtems_regulator_create().

Convert external handle to internal instance pointer

There can be no buffers outstanding

Free the resources associated with this regulator instance.

◆ rtems_regulator_get_statistics()

rtems_status_code rtems_regulator_get_statistics	(	rtems_regulator_instance *	regulator,
		rtems_regulator_statistics *	statistics
	)

Obtain statistics for regulator instance.

This function is used by the application to obtain statistics information about the regulator instance.

If the obtained and released fields in the returned statistics structure are equal, then there are no buffers outstanding from this regulator instance.

Parameters

[in]	regulator	is the regulator instance to operate upon
[in,out]	statistics	points to the statistics structure to fill in

Returns: an RTEMS status code indicating success or failure.

Validate the arguments and ensure the regulator was successfully initialized.

Convert external handle to internal instance pointer

Zero out the statistics structure in case the get period statistics fails below.

Fill in the caller's statistics structure from information maintained by the regulator instance about buffers processed.

Attempt to retrieve the delivery thread's period's statistics.

NOTE; If the Delivery Thread has not run yet, the period will not exist yet. We should not fail for this reason but it is why we zeroed out the entire structure above.

◆ rtems_regulator_obtain_buffer()

rtems_status_code rtems_regulator_obtain_buffer	(	rtems_regulator_instance *	regulator,
		void **	buffer
	)

Obtain Buffer from Regulator.

Allocate a buffer for the caller using the internal partition.

Convert external handle to internal instance pointer

Allocate a buffer for the user application from the buffer pool managed by an Classic API partition.

◆ rtems_regulator_release_buffer()

rtems_status_code rtems_regulator_release_buffer	(	rtems_regulator_instance *	regulator,
		void *	buffer
	)

Release Previously Obtained Regulator Buffer.

Allocate a buffer for the caller using the internal partition.

Convert external handle to internal instance pointer

Deallocate the buffer to the buffer pool managed by a Classic API partition.

◆ rtems_regulator_send()

rtems_status_code rtems_regulator_send	(	rtems_regulator_instance *	regulator,
		void *	message,
		size_t	length
	)

Send to regulator instance.

This function is used by the producer to send a message to the regulator for later delivery by the Delivery thread. The message is contained in the memory pointed to by message and is length bytes in length.

It is required that the message buffer was obtained via rtems_regulator_obtain_buffer().

It is assumed that the message buffer has been filled in with application content to deliver.

If the rtems_regulator_send() is successful, the buffer is enqueued inside the regulator instance for subsequent delivery. After the message is delivered, it may be released by either delivery function or the application code depending on the implementation.

The status RTEMS_TOO_MANY is returned if the regulator's internal queue is full. This indicates that the configured maximum number of messages was insufficient. It is the responsibility of the caller to decide whether to hold messages, drop them, or print a message that the maximum number of messages should be increased.

If rtems_regulator_send() is unsuccessful, it is the application's responsibility to release the buffer. If it is successfully sent, then it becomes the responsibility of the delivery function to release it.

Parameters

[in]	regulator	is the regulator instance to operate upon
[out]	message	points to the message to deliver
[out]	length	is the size of the message in bytes

Returns: an RTEMS status code indicating success or failure.

Validate the arguments and ensure the regulator was successfully initialized.

Convert external handle to internal instance pointer

Place the message pointer and length into a temporary structure. This lets the implementation internally send the message by reference and have a zero-copy implementation.

Send the application message to the output thread for delivery using a Classic API message queue.

Files

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ REGULATOR_INITIALIZED

Function Documentation

◆ rtems_regulator_create()

◆ rtems_regulator_delete()

◆ rtems_regulator_get_statistics()

◆ rtems_regulator_obtain_buffer()

◆ rtems_regulator_release_buffer()

◆ rtems_regulator_send()