Add Regulator documentation based on V1 functionality

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
 ~~~~~~~~~~~~~~~~~~~~~~~
 

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

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.

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.
+

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

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.

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.
+
+

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

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
+