---
README.txt | 19 +-
c-user/index.rst | 1 +
c-user/regulator/background.rst | 90 ++++
c-user/regulator/directives.rst | 549 ++++++++++++++++++++
c-user/regulator/index.rst | 19 +
c-user/regulator/introduction.rst | 25 +
c-user/regulator/operations.rst | 67 +++
c-user/rtems_data_types.rst | 95 ++++
images/c_user/regulator_input_sequence.png | Bin 0 -> 38120 bytes
images/c_user/regulator_input_sequence.puml | 16 +
10 files changed, 879 insertions(+), 2 deletions(-)
create mode 100644 c-user/regulator/background.rst
create mode 100644 c-user/regulator/directives.rst
create mode 100644 c-user/regulator/index.rst
create mode 100644 c-user/regulator/introduction.rst
create mode 100644 c-user/regulator/operations.rst
create mode 100644 images/c_user/regulator_input_sequence.png
create mode 100644 images/c_user/regulator_input_sequence.puml
diff --git a/README.txt b/README.txt
index b61a73a..1c4d729 100644
--- a/README.txt
+++ b/README.txt
@@ -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
~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/c-user/index.rst b/c-user/index.rst
index 09aafe8..b4ad322 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -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
diff --git a/c-user/regulator/background.rst b/c-user/regulator/background.rst
new file mode 100644
index 0000000..f6a6bff
--- /dev/null
+++ b/c-user/regulator/background.rst
@@ -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.
diff --git a/c-user/regulator/directives.rst b/c-user/regulator/directives.rst
new file mode 100644
index 0000000..eea3fff
--- /dev/null
+++ b/c-user/regulator/directives.rst
@@ -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.
+
diff --git a/c-user/regulator/index.rst b/c-user/regulator/index.rst
new file mode 100644
index 0000000..4731b7b
--- /dev/null
+++ b/c-user/regulator/index.rst
@@ -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
diff --git a/c-user/regulator/introduction.rst
b/c-user/regulator/introduction.rst
new file mode 100644
index 0000000..3ad90d3
--- /dev/null
+++ b/c-user/regulator/introduction.rst
@@ -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.
diff --git a/c-user/regulator/operations.rst b/c-user/regulator/operations.rst
new file mode 100644
index 0000000..a9e5a44
--- /dev/null
+++ b/c-user/regulator/operations.rst
@@ -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.
+
+
diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst
index 8e4274b..0a5461c 100644
--- a/c-user/rtems_data_types.rst
+++ b/c-user/rtems_data_types.rst
@@ -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
diff --git a/images/c_user/regulator_input_sequence.png
b/images/c_user/regulator_input_sequence.png
new file mode 100644
index
0000000000000000000000000000000000000000..d7f229214473ca742a94049dbcafb2256b2dc9f3
GIT binary patch
literal 38120
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
WPPfh)qlQZ)^G-If@BQ1G<^KS^5Zqh<
literal 0
HcmV?d00001
diff --git a/images/c_user/regulator_input_sequence.puml
b/images/c_user/regulator_input_sequence.puml
new file mode 100644
index 0000000..aa9020c
--- /dev/null
+++ b/images/c_user/regulator_input_sequence.puml
@@ -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
+
--
2.31.1
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
