[PATCH rtems v3 1/1] Add the Regulator Interface and test

[Sebastian Huber]

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 0000000000..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.huber at 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/