rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-05 15:04:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add Regulator documentation based on V1 functionality

Browse Source
This commit is contained in:
Joel Sherrill 2023-07-18 15:28:20 -05:00
parent ded73ef7c9
commit 7bd117cb00
10 changed files with 879 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
README.txt
View File

@ -120,8 +120,10 @@ Please add your host to this section as you set it up.
The best results are produced with Python3 and a virtual environment`. It can
create a specific python environment using `pip`.
Virtual Environment
~~~~~~~~~~~~~~~~~~~
Similarly, npm packages can be installed into a users $HOME directory.
Python Virtual Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a directory to house the virtual environment, create the environment,
and then activate it. This example assumes Python3 and the `venv` module:
@ -143,6 +145,19 @@ Either way, the prompt will now change. You can install Sphinx with:
When you have finished you enter `deactivate`.
NPM Per User Environment
~~~~~~~~~~~~~~~~~~~~~~~~
Change npm's default directory to a local one:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Subsequent packages installed via `npm install` will be local
to the user. The following shows the PATH changes needed.
export PATH=${HOME}/.npm-global/bin:$PATH
Sphinx Per User Install
~~~~~~~~~~~~~~~~~~~~~~~

1
c-user/index.rst
View File

@ -51,6 +51,7 @@ RTEMS Classic API Guide (|version|).
user-extensions/index
config/index
self_contained_objects
regulator/index
multiprocessing/index
symmetric_multiprocessing_services
pci_library

90
c-user/regulator/background.rst Normal file
View File

@ -0,0 +1,90 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR)
.. _RegulatorManagerBackground:
Background
==========
The regulator provides facilities to accept bursty input and buffer it
as needed before delivering it at a pre-defined periodic rate. The input
is referred to as the Source, with the output referred to as the
Destination. Messages are accepted from the Source and delivered to
the Destination by a user-provided Delivery function.
The Regulator implementation uses the RTEMS Classic API Partition Manager
to manage the buffer pool and the RTEMS Classic API Message Queue
Manager to send the buffer to the Delivery thread. The Delivery thread
invokes a user-provided delivery function to get the message to the
Destination.
Regulator Buffering
-------------------
The regulator is designed to sit logically between two entities -- a
source and a destination, where it limits the traffic sent to the
destination to prevent it from being flooded with messages from the
source. This can be used to accommodate bursts of input from a source
and meter it out to a destination. The maximum number of messages
which can be buffered in the regulator is specified by the
``maximum_messages`` field in the :ref:`InterfaceRtemsRegulatorAttributes`
structure passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`.
The regulator library accepts an input stream of messages from a
source and delivers them to a destination. The regulator assumes that the
input stream from the source contains sporadic bursts of data which can
exceed the acceptable rate of the destination. By limiting the message rate,
the regulator prevents an overflow of messages.
The regulator can be configured for the input buffering required to manage
the maximum burst and for the metering rate for the delivery. The delivery
rate is in messages per second. If the sender produces data too fast,
the regulator will buffer the configured number of messages.
A configuration capability is provided to allow for adaptation to different
message streams. The regulator can also support running multiple instances,
which could be used on independent message streams.
It is assumed that the application has a design limit on the number of
messages which may be buffered. All messages accepted by the regulator,
assuming no overflow on input, will eventually be output by the Delivery
thread.
Message Delivery Rate
---------------------
The Source sends buffers to the Regulator instance. The Regulator
then sends the buffer via a message queue which delivers them to the
Delivery thread. The Delivery thread executes periodically at a rate
specified by the ``delivery_thread_period`` field in the
:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument
to :ref:`InterfaceRtemsRegulatorCreate`.
During each period, the Delivery thread attempts to receive
up to ``maximum_to_dequeue_per_period`` number of buffers and
invoke the Delivery function to deliver each of them to the
Destination. The ``maximum_to_dequeue_per_period`` field in the
:ref:`InterfaceRtemsRegulatorAttributes` structure passed as an argument
to :ref:`InterfaceRtemsRegulatorCreate`.
For example, consider a Source that may produce a burst of up to seven
messages every five seconds. But the Destination cannot handle a burst
of seven and either drops messages or gives an error. This can be
accommodated by a Regulator instance configured as follows:
* ``maximum_messages`` - 7
* ``delivery_thread_period`` - one second
* ``maximum_to_dequeue_per_period`` - 3
In this scenario, the application will use the Delivery thread
:ref:`InterfaceRtemsRegulatorSend` to enqueue the seven messages when they
arrive. The Delivery thread will deliver three messages per second. The
following illustrates this sequence:
* Time 0: Source sends seven messages
* Time 1: Delivery of messages 1 to 3
* Time 3: Delivery of messages 4 to 6
* Time 3: Delivery of message 7
* Time 4: No messages to deliver
This configuration of the regulator ensures that the Destination does
not overflow.

549
c-user/regulator/directives.rst Normal file
View File

@ -0,0 +1,549 @@
.. 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.

19
c-user/regulator/index.rst Normal file
View File

@ -0,0 +1,19 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2023 OAR Corporation
.. index:: regulator
.. _RTEMSAPIRegulator
Regulator Manager
*****************
.. toctree::
introduction
background
operations
directives
.. deprecated-directives
.. removed-directives

25
c-user/regulator/introduction.rst Normal file
View File

@ -0,0 +1,25 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR)
.. _RegulatorManagerIntroduction:
Introduction
============
The Regulator Manager provides a set of directives to manage a data flow
from a source to a destination. The focus is on regulating the bursty
input so that it is delivered to the destination at a regular rate.
The directives provided by the Regulator Manager are:
* :ref:`InterfaceRtemsRegulatorCreate` - Creates a regulator.
* :ref:`InterfaceRtemsRegulatorDelete` - Deletes the regulator.
* :ref:`InterfaceRtemsRegulatorObtainBuffer` - Obtain buffer from a regulator.
* :ref:`InterfaceRtemsRegulatorReleaseBuffer` - Release buffer to a regulator.
* :ref:`InterfaceRtemsRegulatorSend` - Send buffer to a regulator.
* :ref:`InterfaceRtemsRegulatorGetStatistics` - Obtain statistics for a regulator.

67
c-user/regulator/operations.rst Normal file
View File

@ -0,0 +1,67 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2023 On-Line Applications Research Corporation (OAR)
.. _RegulatorManagerOperations:
Operations
==========
Application Sourcing Data
-------------------------
The application interacting with the Source will obtain buffers from
the regulator instance, fill them with information, and send them to
the regulator instance. This allows the regulator to buffer bursty input.
A regulator instance is used as follows from the Source side:
.. code-block:: c
while (1) {
use rtems_regulator_obtain_buffer to obtain a buffer
// Perform some input operation to fetch data into the buffer
rtems_regulator_send(buffer, size of message)
}
The delivery of message buffers to the Destination and subsequent release is
performed in the context of the delivery thread by either the delivery
function or delivery thread. Details are below.
The sequence diagram below shows the interaction between a message Source,
a Regulator instance, and RTEMS, given the usage described in the above
paragraphs.
.. _fig-regulator_input_sequence:
.. figure:: ../../images/c_user/regulator_input_sequence.png
:width: 90%
:alt: Regulator Application Input Source Usage
:figclass: align-center
As illustrated in the preceding sequence diagram, the Source usually
corresponds to application software reading a system input. The Source
obtains a buffer from the Regulator instance and fills it with incoming
data. The application explicitly obtaining a buffer and filling it in
allows for zero copy operations on the Source side.
After the Source has sent the message to the Regulator instance,
the Source is free to process another input and the Regulator
instance will ensure that the buffer is delivered to the Delivery
function and Destination.
Delivery Function
-----------------
The Delivery function is provided by the application for a specific
Regulator instance. Depending on the Destination, it may use a function which
copies the buffer contents (e.g., write()) or which operates directly
on the buffer contents (e.g. DMA from buffer). In the case of a
Destination which copies the buffer contents, the buffer can be released
via :ref:`InterfaceRtemsRegulatorReleaseBuffer` as soon as the function
or copying completes. In the case where the delivery uses the buffer
and returns, the call to :ref:`InterfaceRtemsRegulatorReleaseBuffer`
will occur when the use of the buffer is complete (e.g. completion
of DMA transfer). This explicit and deliberate exposure of buffering
provides the application with the ability to avoid copying the contents.

95
c-user/rtems_data_types.rst
View File

@ -1171,6 +1171,101 @@ executed_since_last_period
postponed_jobs_count
This member contains the count of jobs which are not released yet.
.. Handwritten
.. index:: rtems_regulator_attributes
.. _InterfaceRtemsRegulatorAttributes:
rtems_regulator_attributes
--------------------------
This structure defines the configuration of a regulator created by
:ref:`InterfaceRtemsRegulatorCreate`.
.. rubric:: MEMBERS:
deliverer
This member contains a pointer to an application function invoked by
the Delivery thread to output a message to the destination.
deliverer_context
This member contains a pointer to an application defined context which
is passed to delivery function.
maximum_message_size
This member contains the maximum size message to process.
maximum_messages
This member contains the maximum number of messages to be able to buffer.
output_thread_priority
This member contains the priority of output thread.
output_thread_stack_size
This member contains the Stack size of output thread.
output_thread_period
This member contains the period (in ticks) of output thread.
maximum_to_dequeue_per_period
This member contains the maximum number of messages the output thread
should dequeue and deliver per period.
.. rubric:: NOTES:
This type is passed as an argument to :ref:`InterfaceRtemsRegulatorCreate`.
.. Handwritten
.. index:: rtems_regulator_deliverer
.. _InterfaceRtemsRegulatorDeliverer:
rtems_regulator_deliverer
-------------------------
This type represents the function signature used to specify a delivery
function for the RTEMS Regulator.
.. rubric:: NOTES:
This type is used in the :ref:`InterfaceRtemsRegulatorAttributes`
structure which is passed as an argument to
:ref:`InterfaceRtemsRegulatorCreate`.
.. Handwritten
.. index:: rtems_regulator_statistics
.. _InterfaceRtemsRegulatorStatistics:
rtems_regulator_statistics
--------------------------
This structure defines the statistics maintained by each Regulator instance.
.. rubric:: MEMBERS:
obtained
This member contains the number of successfully obtained buffers.
released
This member contains the number of successfully released buffers.
delivered
This member contains the number of successfully delivered buffers.
period_statistics
This member contains the Rate Monotonic Period
statistics for the Delivery Thread. It is an instance of the
:ref:`InterfaceRtemsRateMonotonicPeriodStatistics` structure.
.. rubric:: NOTES:
This type is passed as an argument to
:ref:`InterfaceRtemsRegulatorGetStatistics`.
.. Generated from spec:/rtems/signal/if/set
.. index:: rtems_signal_set

BIN
images/c_user/regulator_input_sequence.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

16
images/c_user/regulator_input_sequence.puml Normal file
View File

@ -0,0 +1,16 @@
' SPDX-License-Identifier: CC-BY-SA-4.0
' Copyright (C) 2023 OAR Corporatoin
@startuml "Regulator Application Input Source Usage"
Source -> Regulator : rtems_regulator_obtain_buffer(regulator, buffer)
Regulator -> RTEMS : rtems_partition_get_buffer(id, buffer)
RTEMS --> Regulator : rtems_status_code
Regulator --> Source : rtems_status_code
Source -> Regulator : rtems_regulator_send(regulator, message, length)
Regulator -> RTEMS : rtems_message_queue_send(id, message, size)
RTEMS --> Regulator : rtems_status_code
Regulator --> Source : rtems_status_code
@enduml