mirror of
https://git.rtems.org/rtems-docs/
synced 2025-06-09 11:00:00 +08:00
550 lines
16 KiB
ReStructuredText
550 lines
16 KiB
ReStructuredText
.. 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.
|
|
|