diff options
author | Joel Sherrill <joel@rtems.org> | 2023-07-18 15:28:20 -0500 |
---|---|---|
committer | Joel Sherrill <joel@rtems.org> | 2023-08-09 10:40:56 -0500 |
commit | 7bd117cb00b68e5cb89aa8c237a813730876817e (patch) | |
tree | acb0bab9398635e363f712afe39d06b09b77f4fb | |
parent | eng: add Apache License 2.0 restriction (diff) | |
download | rtems-docs-7bd117cb00b68e5cb89aa8c237a813730876817e.tar.bz2 |
Add Regulator documentation based on V1 functionality
-rw-r--r-- | README.txt | 19 | ||||
-rw-r--r-- | c-user/index.rst | 1 | ||||
-rw-r--r-- | c-user/regulator/background.rst | 90 | ||||
-rw-r--r-- | c-user/regulator/directives.rst | 549 | ||||
-rw-r--r-- | c-user/regulator/index.rst | 19 | ||||
-rw-r--r-- | c-user/regulator/introduction.rst | 25 | ||||
-rw-r--r-- | c-user/regulator/operations.rst | 67 | ||||
-rw-r--r-- | c-user/rtems_data_types.rst | 95 | ||||
-rw-r--r-- | images/c_user/regulator_input_sequence.png | bin | 0 -> 38120 bytes | |||
-rw-r--r-- | images/c_user/regulator_input_sequence.puml | 16 |
10 files changed, 879 insertions, 2 deletions
@@ -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 Binary files differnew file mode 100644 index 0000000..d7f2292 --- /dev/null +++ b/images/c_user/regulator_input_sequence.png 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 + |