From 7bd117cb00b68e5cb89aa8c237a813730876817e Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 18 Jul 2023 15:28:20 -0500 Subject: [PATCH] Add Regulator documentation based on V1 functionality --- 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 + `_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``regulator`` parameter was `NULL + `_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``deliverer`` field in the structure pointed to by the + ``attributes`` parameter was `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 + `_. + +: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 + `_. + +: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 + `_. + +: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 + `_. + +: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 + `_. + +: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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 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 +