28.4. Directives¶

This section details the directives of the Regulator Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

28.4.1. rtems_regulator_create()¶

Creates a regulator.

CALLING SEQUENCE:

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

PARAMETERS:

attributes: This parameter is the attributes associated with the regulator being created.
regulator: This parameter is the pointer to a regulator instance. When the directive call is successful, a pointer to the created regulator will be stored in this object.

DESCRIPTION:

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 parameter points to an instance of rtems_regulator_attributes which is filled in to reflect the desired configuration of the regulator instance. It defines multiple characteristics of the the Delivery thread dedicated to this regulator instance including the priority and stack size. 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 to the contents and a length field.
A RTEMS Classic API Partition.
A RTEMS Classic API Rate Monotonic Period.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The attributes parameter was NULL.
RTEMS_INVALID_ADDRESS: The regulator parameter was NULL.
RTEMS_INVALID_ADDRESS: The deliverer field in the structure pointed to by the attributes parameter was NULL.
RTEMS_INVALID_SIZE: The maximum_messages field in the structure pointed to by the attributes parameter was 0.
RTEMS_INVALID_NUMBER: The maximum_to_dequeue_per_period field in the structure pointed to by the attributes parameter was 0.
RTEMS_NO_MEMORY: The allocation of memory for the regulator instance failed.
RTEMS_NO_MEMORY: The allocation of memory for the buffers failed.
RTEMS_NO_MEMORY: The allocation of memory for the internal message queue failed.

NOTES:

rtems_regulator_create() uses rtems_partition_create(), rtems_message_queue_construct(), rtems_task_create(), and rtems_task_start(). If any of those directives return a status indicating failure, it will be returned to the caller.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
The number of tasks available to the application is configured through the CONFIGURE_MAXIMUM_TASKS application configuration option.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.

28.4.2. rtems_regulator_delete()¶

Deletes the regulator.

CALLING SEQUENCE:

rtems_status_code rtems_regulator_delete(
  rtems_regulator_instance    *regulator,
  rtems_interval               ticks
);

PARAMETERS:

regulator: This parameter points to the regulator instance.
ticks: This parameter specifies the maximum length of time to wait.

DESCRIPTION:

This directive is used to delete the specified regulator instance. It will deallocate the resources that were allocated by the rtems_regulator_create() directive.

This directive ensures that no buffers are outstanding either because the Source is holding one of more buffers or because they are being held by the regulator instance pending delivery.

If the Delivery Thread has been created and is running, this directive will request the thread to voluntarily exit. This call will wait up to ticks for the thread to exit.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The regulator parameter was NULL.
RTEMS_INCORRECT_STATE: The regulator instance was not initialized.
RTEMS_RESOURCE_IN_USE: The regulator instance has buffers outstanding.
RTEMS_TIMEOUT: The regulator instance was not able to be deleted within the specific number of ticks.

NOTES:

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

It is the responsibility of the user to ensure that all buffers associated with this regulator instance have been released and that none are in the process of being delivered.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
The calling task does not have to be the task that created the object. Any local task that knows the object identifier can delete the object.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may free memory to the RTEMS Workspace.

28.4.3. rtems_regulator_obtain_buffer()¶

Obtain buffer from regulator.

CALLING SEQUENCE:

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

PARAMETERS:

regulator: This parameter is the regulator instance to operate upon.
buffer: This parameter will point to the buffer allocated.

DESCRIPTION:

This function is used to obtain a buffer from the regulator’s pool. The buffer returned is assumed to be filled in with contents and used in a subsequent call to rtems_regulator_send().

When the buffer is delivered, it is expected to be released. If the buffer is not successfully accepted by this method, then it should be returned using rtems_regulator_release_buffer() or used to send another message.

The buffer returned is of the maximum_message_size specified in the attributes passed in to rtems_regulator_create().

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The regulator parameter was NULL.
RTEMS_INCORRECT_STATE: The regulator instance was not initialized.

NOTES:

rtems_regulator_obtain_buffer() uses rtems_partition_get_buffer() and if it returns a status indicating failure, it will be returned to the caller.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.

28.4.4. rtems_regulator_release_buffer()¶

Release buffer to regulator.

CALLING SEQUENCE:

rtems_status_code rtems_regulator_release_buffer(
  rtems_regulator_instance  *regulator,
  void                      *buffer
);

PARAMETERS:

regulator: This parameter is the regulator instance to operate upon.
buffer: This parameter will point to the buffer to be released.

DESCRIPTION:

This function is used to release a buffer to the regulator’s pool. It is assumed that the buffer returned will not be used by the application anymore.

The buffer must have previously been allocated by rtems_regulator_obtain_buffer() and NOT yet passed to rtems_regulator_send(), or it has been sent and delivery has been completed by the delivery function.

If a subsequent rtems_regulator_send() using this buffer is successful, the buffer will eventually be processed by the delivery thread and released.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The regulator parameter was NULL.
RTEMS_INCORRECT_STATE: The regulator instance was not initialized.

NOTES:

rtems_regulator_release_buffer() uses rtems_partition_return_buffer() and if it returns a status indicating failure, it will be returned to the caller.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.

28.4.5. rtems_regulator_send()¶

Send buffer to regulator.

CALLING SEQUENCE:

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

PARAMETERS:

regulator: This parameter is the regulator instance to operate upon.
message: This parameter points to the buffer to send.
length: This parameter specifies the number of bytes in the message.

DESCRIPTION:

This method 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 message buffer is enqueued inside the regulator instance for subsequent delivery. After the message is delivered, it may be released by either delivery function or other 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

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The regulator parameter was NULL.
RTEMS_INCORRECT_STATE: The regulator instance was not initialized.

NOTES:

rtems_regulator_send() uses rtems_message_queue_send() and if it returns a status indicating failure, it will be returned to the caller.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.

28.4.6. rtems_regulator_get_statistics()¶

Obtain statistics from regulator.

CALLING SEQUENCE:

rtems_status_code rtems_regulator_get_statistics(
  rtems_regulator_instance   *regulator,
  rtems_regulator_statistics *statistics
);

PARAMETERS:

regulator: This parameter is the regulator instance to operate upon.
statistics: This parameter points to the statistics structure to be filled in.

DESCRIPTION:

This method is used by the application to obtain the current statistics for this regulator. The statistics information provided includes:

the number of buffers obtained via rtems_regulator_obtain_buffer()
the number of buffers released via rtems_regulator_release_buffer()
the number of buffers delivered by the Delivery Thread via the deliverer function specified in the rtems_regulator_attributes structure provided to InterfaceRtemsRegulatorCreate` via the attibutes parameter.
the period_statistics for the Delivery Thread. For more details on period statistics, see rtems_rate_monotonic_period_statistics.

RETURN VALUES:

RTEMS_SUCCESSFUL: The requested operation was successful.
RTEMS_INVALID_ADDRESS: The regulator or statistics parameter was NULL.
RTEMS_INCORRECT_STATE: The regulator instance was not initialized.

NOTES:

The number of buffers outstanding is released minus obtained. The regulator instance cannot be deleted using rtems_regulator_delete() until all buffers are released.

The obtained and released values are cumulative over the life of the Regulator instance and are likely to larger than the maximum_messages value in the attributes structure (rtems_regulator_attributes provided to rtems_regulator_create().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.