Re: [PATCH rtems v2] Add the Regulator Interface and test
On 15/7/2023 9:48 am, Joel Sherrill wrote: > Updates #4924. > > The Regulator is an application support class which is used to > deal with the scenario where there is a bursty input source > which needs to be metered out to a destination sink. The maximum > size of bursts needs to be known and the delivery method must > be configured to deliver messages at a rate that allows the > traffic to not overflow. > --- > cpukit/include/rtems/regulator.h | 439 ++ > cpukit/include/rtems/regulatorimpl.h | 103 ++ > cpukit/libmisc/regulator/regulator.c | 522 > spec/build/cpukit/librtemscpu.yml |2 + > spec/build/cpukit/objregulator.yml| 18 + > spec/build/testsuites/libtests/grp.yml|2 + > .../build/testsuites/libtests/regulator01.yml | 21 + > testsuites/libtests/regulator01/regulator01.c | 1192 + > .../libtests/regulator01/regulator01.doc | 68 + > .../libtests/regulator01/rtems_config.c | 59 + > 10 files changed, 2426 insertions(+) > create mode 100644 cpukit/include/rtems/regulator.h > create mode 100644 cpukit/include/rtems/regulatorimpl.h > create mode 100644 cpukit/libmisc/regulator/regulator.c > create mode 100644 spec/build/cpukit/objregulator.yml > create mode 100644 spec/build/testsuites/libtests/regulator01.yml > create mode 100644 testsuites/libtests/regulator01/regulator01.c > create mode 100644 testsuites/libtests/regulator01/regulator01.doc > create mode 100644 testsuites/libtests/regulator01/rtems_config.c > > diff --git a/cpukit/include/rtems/regulator.h > b/cpukit/include/rtems/regulator.h > new file mode 100644 > index 00..74f0d00f2e > --- /dev/null > +++ b/cpukit/include/rtems/regulator.h > @@ -0,0 +1,439 @@ > +/* SPDX-License-Identifier: BSD-2-Clause */ > + > +/** > + * @defgroup RegulatorAPI Regulator API > + * > + * @brief Regulator APIs > + * > + * The Regulator provides a set of APIs to manage input sources which > + * produces bursts of message traffic. > + */ > + > +/** > + * @mainpage > + * > + * The regulator is designed to sit logically between two entities -- a > + * source and a sink/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 > + * @a maximum_messages field in the @a rtems_regulator_attributes > + * structure passed as an argument to @a rtems_regulator_create(). > + * > + * 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 output. The output > 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. > + * > + * The regulator provides a simple interface to the application for avoiding > + * bursts of input from a fast source overflowing a slower output sink. > + * > + * 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. > + * > + * A regulator instance is used as follows: > + * > + * @code > + * while (1) > + * use rtems_regulator_obtain_buffer to obtain a buffer > + * input operation to fetch data into the buffer > + * rtems_regulator_send(buffer, size of message) > + * // rtems_regulator_send() will release the buffer automatically > when done OK however ... > + * @endcode > + * > + * The sequence diagram below shows the interaction between a message Source, > + * a Regulator instance, and RTEMS, given the usage described in the above > + * paragraphs. > + * > + * \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 :
[PATCH rtems v2] Add the Regulator Interface and test
Updates #4924. The Regulator is an application support class which is used to deal with the scenario where there is a bursty input source which needs to be metered out to a destination sink. The maximum size of bursts needs to be known and the delivery method must be configured to deliver messages at a rate that allows the traffic to not overflow. --- cpukit/include/rtems/regulator.h | 439 ++ cpukit/include/rtems/regulatorimpl.h | 103 ++ cpukit/libmisc/regulator/regulator.c | 522 spec/build/cpukit/librtemscpu.yml |2 + spec/build/cpukit/objregulator.yml| 18 + spec/build/testsuites/libtests/grp.yml|2 + .../build/testsuites/libtests/regulator01.yml | 21 + testsuites/libtests/regulator01/regulator01.c | 1192 + .../libtests/regulator01/regulator01.doc | 68 + .../libtests/regulator01/rtems_config.c | 59 + 10 files changed, 2426 insertions(+) create mode 100644 cpukit/include/rtems/regulator.h create mode 100644 cpukit/include/rtems/regulatorimpl.h create mode 100644 cpukit/libmisc/regulator/regulator.c create mode 100644 spec/build/cpukit/objregulator.yml create mode 100644 spec/build/testsuites/libtests/regulator01.yml create mode 100644 testsuites/libtests/regulator01/regulator01.c create mode 100644 testsuites/libtests/regulator01/regulator01.doc create mode 100644 testsuites/libtests/regulator01/rtems_config.c diff --git a/cpukit/include/rtems/regulator.h b/cpukit/include/rtems/regulator.h new file mode 100644 index 00..74f0d00f2e --- /dev/null +++ b/cpukit/include/rtems/regulator.h @@ -0,0 +1,439 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @defgroup RegulatorAPI Regulator API + * + * @brief Regulator APIs + * + * The Regulator provides a set of APIs to manage input sources which + * produces bursts of message traffic. + */ + +/** + * @mainpage + * + * The regulator is designed to sit logically between two entities -- a + * source and a sink/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 + * @a maximum_messages field in the @a rtems_regulator_attributes + * structure passed as an argument to @a rtems_regulator_create(). + * + * 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 output. The output 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. + * + * The regulator provides a simple interface to the application for avoiding + * bursts of input from a fast source overflowing a slower output sink. + * + * 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. + * + * A regulator instance is used as follows: + * + * @code + * while (1) + * use rtems_regulator_obtain_buffer to obtain a buffer + * input operation to fetch data into the buffer + * rtems_regulator_send(buffer, size of message) + * // rtems_regulator_send() will release the buffer automatically when done + * @endcode + * + * The sequence diagram below shows the interaction between a message Source, + * a Regulator instance, and RTEMS, given the usage described in the above + * paragraphs. + * + * \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 + * + * As illustrated in the sequence diagram, the Source usually corresponds + * to application software reading a system input. The Source
