path: root/c-user/regulator/directives.rst

.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR)

.. _RegulatorManagerDirectives:

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.

.. *** START of rtems_regulator_create()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_create()
.. index:: create a regulator

.. _InterfaceRtemsRegulatorCreate:

rtems_regulator_create()
------------------------

Creates a regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

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

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

.. rubric:: 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
:ref:`InterfaceRtemsRegulatorAttributes` 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.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``attributes`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``deliverer`` field in the structure pointed to by the
    ``attributes`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INVALID_SIZE`
    The ``maximum_messages`` field in the structure pointed to by the
    ``attributes`` parameter was 0.

:c:macro:`RTEMS_INVALID_NUMBER`
    The ``maximum_to_dequeue_per_period`` field in the structure pointed
    to by the ``attributes`` parameter was 0.

:c:macro:`RTEMS_NO_MEMORY`
    The allocation of memory for the regulator instance failed.

:c:macro:`RTEMS_NO_MEMORY`
    The allocation of memory for the buffers failed.

:c:macro:`RTEMS_NO_MEMORY`
    The allocation of memory for the internal message queue failed.

.. rubric:: NOTES:

:ref:`InterfaceRtemsRegulatorCreate` uses
:ref:`InterfaceRtemsPartitionCreate`,
:ref:`InterfaceRtemsMessageQueueConstruct`,
:ref:`InterfaceRtemsTaskCreate`, and :ref:`InterfaceRtemsTaskStart`. If
any of those directives return a status indicating failure, it will be
returned to the caller.

.. rubric:: 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
  :ref:`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.

.. *** START of rtems_regulator_delete()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_delete()
.. index:: delete a regulator

.. _InterfaceRtemsRegulatorDelete:

rtems_regulator_delete()
------------------------

Deletes the regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

    rtems_status_code rtems_regulator_delete(
      rtems_regulator_instance    *regulator,
      rtems_interval               ticks
    );

.. rubric:: PARAMETERS:

``regulator``
    This parameter points to the regulator instance.

``ticks``
    This parameter specifies the maximum length of time to wait.

.. rubric:: DESCRIPTION:

This directive is used to delete the specified ``regulator``
instance. It will deallocate the resources that were allocated by the
:ref:`InterfaceRtemsRegulatorCreate` 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.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INCORRECT_STATE`
    The ``regulator`` instance was not initialized.

:c:macro:`RTEMS_RESOURCE_IN_USE`
    The ``regulator`` instance has buffers outstanding.

:c:macro:`RTEMS_TIMEOUT`
    The ``regulator`` instance was not able to be deleted within the
    specific number of ``ticks``.

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

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

.. *** START of rtems_regulator_obtain_buffer()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_obtain_buffer()
.. index:: obtain buffer from regulator

.. _InterfaceRtemsRegulatorObtainBuffer:

rtems_regulator_obtain_buffer()
-------------------------------

Obtain buffer from regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

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

.. rubric:: PARAMETERS:

``regulator``
    This parameter is the regulator instance to operate upon.

``buffer``
    This parameter will point to the buffer allocated.

.. rubric:: 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 :ref:`InterfaceRtemsRegulatorSend`.

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 :ref:`InterfaceRtemsRegulatorReleaseBuffer` or used
to send another message.

The ``buffer`` returned is of the maximum_message_size specified in the
attributes passed in to :ref:`InterfaceRtemsRegulatorCreate`.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INCORRECT_STATE`
    The ``regulator`` instance was not initialized.

.. rubric:: NOTES:

:ref:`InterfaceRtemsRegulatorObtainBuffer` uses
:ref:`InterfaceRtemsPartitionGetBuffer` and if it returns a status
indicating failure, it will be returned to the caller.

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

.. *** START of rtems_regulator_release_buffer()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_release_buffer()
.. index:: release buffer back to regulator

.. _InterfaceRtemsRegulatorReleaseBuffer:

rtems_regulator_release_buffer()
--------------------------------

Release buffer to regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

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

.. rubric:: PARAMETERS:

``regulator``
    This parameter is the regulator instance to operate upon.

``buffer``
    This parameter will point to the buffer to be released.

.. rubric:: 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
:ref:`InterfaceRtemsRegulatorObtainBuffer` and NOT yet passed to
:ref:`InterfaceRtemsRegulatorSend`, or it has been sent and delivery
has been completed by the delivery function.

If a subsequent :ref:`InterfaceRtemsRegulatorSend` using this ``buffer``
is successful, the ``buffer`` will eventually be processed by the delivery
thread and released.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INCORRECT_STATE`
    The ``regulator`` instance was not initialized.

.. rubric:: NOTES:

:ref:`InterfaceRtemsRegulatorReleaseBuffer` uses
:ref:`InterfaceRtemsPartitionReturnBuffer` and if it returns a status
indicating failure, it will be returned to the caller.

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

.. *** START of rtems_regulator_send()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_send()
.. index:: send buffer to regulator for delivery

.. _InterfaceRtemsRegulatorSend:

rtems_regulator_send()
----------------------

Send buffer to regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

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

.. rubric:: 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``.

.. rubric:: 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
:ref:`InterfaceRtemsRegulatorObtainBuffer`.

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

If the :ref:`InterfaceRtemsRegulatorSend` 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

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INCORRECT_STATE`
    The ``regulator`` instance was not initialized.

.. rubric:: NOTES:

:ref:`InterfaceRtemsRegulatorSend` uses
:ref:`InterfaceRtemsMessageQueueSend` and if it returns a status
indicating failure, it will be returned to the caller.


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

.. *** START of rtems_regulator_get_statistics()

.. raw:: latex

    \clearpage

.. index:: rtems_regulator_get_statistics()
.. index:: obtain statistics from regulator

.. _InterfaceRtemsRegulatorGetStatistics:

rtems_regulator_get_statistics()
--------------------------------

Obtain statistics from regulator.

.. rubric:: CALLING SEQUENCE:

.. code-block:: c

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

.. rubric:: PARAMETERS:

``regulator``
    This parameter is the regulator instance to operate upon.

``statistics``
    This parameter points to the statistics structure to be filled in.

.. rubric:: 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
  :ref:`InterfaceRtemsRegulatorObtainBuffer`
* the number of buffers released via
  :ref:`InterfaceRtemsRegulatorReleaseBuffer`
* the number of buffers delivered by the Delivery
  Thread via the ``deliverer`` function specified in the
  :ref:`InterfaceRtemsRegulatorAttributes` structure provided to
  :ref:`InterfaceRtemsRegulatorCreate`` via the ``attibutes`` parameter.
* the ``period_statistics`` for the Delivery Thread. For more details on
  period statistics, see :ref:`InterfaceRtemsRateMonotonicPeriodStatistics`.

.. rubric:: RETURN VALUES:

:c:macro:`RTEMS_SUCCESSFUL`
    The requested operation was successful.

:c:macro:`RTEMS_INVALID_ADDRESS`
    The ``regulator`` or ``statistics`` parameter was `NULL
    <https://en.cppreference.com/w/c/types/NULL>`_.

:c:macro:`RTEMS_INCORRECT_STATE`
    The ``regulator`` instance was not initialized.

.. rubric:: NOTES:

The number of buffers outstanding is ``released`` minus
``obtained``. The regulator instance cannot be deleted using
:ref:`InterfaceRtemsRegulatorDelete` 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
(:ref:`InterfaceRtemsRegulatorAttributes`
provided to :ref:`InterfaceRtemsRegulatorCreate`.

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