Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
Thanks. If you do turn up something once it is merged, there is always the option to fix it. :) Chris said I addressed his bigger concerns. Deletion and statistics. On Fri, Aug 11, 2023 at 12:32 AM Sebastian Huber < sebastian.hu...@embedded-brains.de> wrote: > On 11.08.23 00:14, Joel Sherrill wrote: > > I should have asked if you want another round of patches or just go > > ahead and merge. This set of changes was pretty minor. > > This is fine, I had only some cosmetic things. > > -- > embedded brains GmbH > Herr Sebastian HUBER > Dornierstr. 4 > 82178 Puchheim > Germany > email: sebastian.hu...@embedded-brains.de > phone: +49-89-18 94 741 - 16 > fax: +49-89-18 94 741 - 08 > > Registergericht: Amtsgericht München > Registernummer: HRB 157899 > Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler > Unsere Datenschutzerklärung finden Sie hier: > https://embedded-brains.de/datenschutzerklaerung/ > ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
On 11.08.23 00:14, Joel Sherrill wrote: I should have asked if you want another round of patches or just go ahead and merge. This set of changes was pretty minor. This is fine, I had only some cosmetic things. -- embedded brains GmbH Herr Sebastian HUBER Dornierstr. 4 82178 Puchheim Germany email: sebastian.hu...@embedded-brains.de phone: +49-89-18 94 741 - 16 fax: +49-89-18 94 741 - 08 Registergericht: Amtsgericht München Registernummer: HRB 157899 Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler Unsere Datenschutzerklärung finden Sie hier: https://embedded-brains.de/datenschutzerklaerung/ ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
On 11/8/2023 8:14 am, Joel Sherrill wrote: > I should have asked if you want another round of patches or just go ahead and > merge. This set of changes was pretty minor. I am fine with the changes being pushed. Chris ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
I should have asked if you want another round of patches or just go ahead and merge. This set of changes was pretty minor. --joel On Thu, Aug 10, 2023 at 5:13 PM Joel Sherrill wrote: > I think I have addressed all of your comments and Chris'. > > The conversion to rtems-central might be nice but it isn't going to happen > soon. > > --joel > > On Thu, Aug 10, 2023 at 12:10 AM Sebastian Huber < > sebastian.hu...@embedded-brains.de> wrote: > >> On 09.08.23 17:42, 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 | 499 +++ >> > cpukit/include/rtems/regulatorimpl.h | 135 ++ >> > cpukit/libmisc/regulator/regulator.c | 683 + >> > 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 | 1310 + >> > .../libtests/regulator01/regulator01.doc | 67 + >> > .../libtests/regulator01/rtems_config.c | 59 + >> > 10 files changed, 2796 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..362a99f6bc >> > --- /dev/null >> > +++ b/cpukit/include/rtems/regulator.h >> > @@ -0,0 +1,499 @@ >> > +/* SPDX-License-Identifier: BSD-2-Clause */ >> >> In the header file template we have SPDX, Doxygen @file, copyright. >> >> > + >> > +/** >> > + * @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 >> >> Do you really want to add this to the main page? >> >> [...] >> > + >> > +/** >> > + * @addtogroup RegulatorAPI >> > + * >> > + * @file >> > + * >> > + * @brief This header file defines the Regulator API. >> > + * >> > + */ >> >> This should be @file followed by @ingroup RegulatorAPI. >> >> [...] >> > +/** >> > + * @ingroup RegulatorAPI >> > + * >> > + * @brief Regulator Instance >> > + * >> > + * This is used by the application as the handle to a Regulator >> instance. >> > + */ >> > +typedef void *rtems_regulator_instance; >> >> I think this should be rtems_regulator_control. You can also use a >> forward declaration >> >> struct rtems_regulator_control; >> >> typedef struct rtems_regulator_control rtems_regulator_control; >> >> to provide a type safe API and ease debugging. >> >> If you use the interface specification in rtems-central for this new >> API, you can keep the Doxygen and Classic API documentation in >> synchronization. You could use it also to write validation tests. >> >> [...] >> >> -- >> embedded brains GmbH >> Herr Sebastian HUBER >> Dornierstr. 4 >> 82178 Puchheim >> Germany >> email: sebastian.hu...@embedded-brains.de >> phone: +49-89-18 94 741 - 16 >> fax: +49-89-18 94 741 - 08 >> >> Registergericht: Amtsgericht München >> Registernummer: HRB 157899 >> Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler >> Unsere Datenschutzerklärung finden Sie hier: >> https://embedded-brains.de/datenschutzerklaerung/ >> > ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
I think I have addressed all of your comments and Chris'. The conversion to rtems-central might be nice but it isn't going to happen soon. --joel On Thu, Aug 10, 2023 at 12:10 AM Sebastian Huber < sebastian.hu...@embedded-brains.de> wrote: > On 09.08.23 17:42, 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 | 499 +++ > > cpukit/include/rtems/regulatorimpl.h | 135 ++ > > cpukit/libmisc/regulator/regulator.c | 683 + > > 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 | 1310 + > > .../libtests/regulator01/regulator01.doc | 67 + > > .../libtests/regulator01/rtems_config.c | 59 + > > 10 files changed, 2796 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..362a99f6bc > > --- /dev/null > > +++ b/cpukit/include/rtems/regulator.h > > @@ -0,0 +1,499 @@ > > +/* SPDX-License-Identifier: BSD-2-Clause */ > > In the header file template we have SPDX, Doxygen @file, copyright. > > > + > > +/** > > + * @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 > > Do you really want to add this to the main page? > > [...] > > + > > +/** > > + * @addtogroup RegulatorAPI > > + * > > + * @file > > + * > > + * @brief This header file defines the Regulator API. > > + * > > + */ > > This should be @file followed by @ingroup RegulatorAPI. > > [...] > > +/** > > + * @ingroup RegulatorAPI > > + * > > + * @brief Regulator Instance > > + * > > + * This is used by the application as the handle to a Regulator > instance. > > + */ > > +typedef void *rtems_regulator_instance; > > I think this should be rtems_regulator_control. You can also use a > forward declaration > > struct rtems_regulator_control; > > typedef struct rtems_regulator_control rtems_regulator_control; > > to provide a type safe API and ease debugging. > > If you use the interface specification in rtems-central for this new > API, you can keep the Doxygen and Classic API documentation in > synchronization. You could use it also to write validation tests. > > [...] > > -- > embedded brains GmbH > Herr Sebastian HUBER > Dornierstr. 4 > 82178 Puchheim > Germany > email: sebastian.hu...@embedded-brains.de > phone: +49-89-18 94 741 - 16 > fax: +49-89-18 94 741 - 08 > > Registergericht: Amtsgericht München > Registernummer: HRB 157899 > Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler > Unsere Datenschutzerklärung finden Sie hier: > https://embedded-brains.de/datenschutzerklaerung/ > ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
On 09.08.23 17:42, 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 | 499 +++ cpukit/include/rtems/regulatorimpl.h | 135 ++ cpukit/libmisc/regulator/regulator.c | 683 + 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 | 1310 + .../libtests/regulator01/regulator01.doc | 67 + .../libtests/regulator01/rtems_config.c | 59 + 10 files changed, 2796 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..362a99f6bc --- /dev/null +++ b/cpukit/include/rtems/regulator.h @@ -0,0 +1,499 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ In the header file template we have SPDX, Doxygen @file, copyright. + +/** + * @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 Do you really want to add this to the main page? [...] + +/** + * @addtogroup RegulatorAPI + * + * @file + * + * @brief This header file defines the Regulator API. + * + */ This should be @file followed by @ingroup RegulatorAPI. [...] +/** + * @ingroup RegulatorAPI + * + * @brief Regulator Instance + * + * This is used by the application as the handle to a Regulator instance. + */ +typedef void *rtems_regulator_instance; I think this should be rtems_regulator_control. You can also use a forward declaration struct rtems_regulator_control; typedef struct rtems_regulator_control rtems_regulator_control; to provide a type safe API and ease debugging. If you use the interface specification in rtems-central for this new API, you can keep the Doxygen and Classic API documentation in synchronization. You could use it also to write validation tests. [...] -- embedded brains GmbH Herr Sebastian HUBER Dornierstr. 4 82178 Puchheim Germany email: sebastian.hu...@embedded-brains.de phone: +49-89-18 94 741 - 16 fax: +49-89-18 94 741 - 08 Registergericht: Amtsgericht München Registernummer: HRB 157899 Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler Unsere Datenschutzerklärung finden Sie hier: https://embedded-brains.de/datenschutzerklaerung/ ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems v3 1/1] Add the Regulator Interface and test
Hi Joel, This looks good. A minor nit relates to pointer checks. We have: https://docs.rtems.org/branches/master/eng/coding-conventions.html#language-and-compiler I do not know how well enforced the pointer check for NULL in `if` is? Chris On 10/8/2023 1:42 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 | 499 +++ > cpukit/include/rtems/regulatorimpl.h | 135 ++ > cpukit/libmisc/regulator/regulator.c | 683 + > 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 | 1310 + > .../libtests/regulator01/regulator01.doc | 67 + > .../libtests/regulator01/rtems_config.c | 59 + > 10 files changed, 2796 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..362a99f6bc > --- /dev/null > +++ b/cpukit/include/rtems/regulator.h > @@ -0,0 +1,499 @@ > +/* 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 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 destination. > + * > + * 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 from the producer/source side: > + * > + * @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) > + * @endcode > + * > + * 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. > + * > + * \startuml "Regulator
[PATCH rtems v3 1/1] 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 | 499 +++ cpukit/include/rtems/regulatorimpl.h | 135 ++ cpukit/libmisc/regulator/regulator.c | 683 + 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 | 1310 + .../libtests/regulator01/regulator01.doc | 67 + .../libtests/regulator01/rtems_config.c | 59 + 10 files changed, 2796 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..362a99f6bc --- /dev/null +++ b/cpukit/include/rtems/regulator.h @@ -0,0 +1,499 @@ +/* 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 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 destination. + * + * 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 from the producer/source side: + * + * @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) + * @endcode + * + * 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. + * + * \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 +
