From 422e7e0522da64b4b1dbe930d62f7a37582c4ebe Mon Sep 17 00:00:00 2001 From: Dhaval Khandla Date: Sat, 16 Sep 2023 15:15:34 +0530 Subject: [PATCH] am243x/am263x: rtlibs: Update documentation Fixes: PINDSW-6566 Signed-off-by: Dhaval Khandla --- docs_src/docs/api_guide/components/dcl/dcl.md | 37 ++++++++++--------- source/dcl/common/dcl_aux.h | 3 +- source/dcl/common/dcl_css.h | 4 +- source/dcl/common/dcl_zpk3.h | 2 +- source/dcl/df/dcl_df11.h | 4 +- source/dcl/df/dcl_df13.h | 2 +- source/dcl/df/dcl_df22.h | 4 +- source/dcl/df/dcl_df23.h | 4 +- source/dcl/misc/dcl_error.h | 2 +- source/dcl/misc/dcl_fdlog.h | 2 + source/dcl/pi/dcl_pi.h | 4 +- source/dcl/pi/dcl_pi2.h | 4 +- source/dcl/pid/dcl_pid.h | 4 +- source/dcl/pid/dcl_pidf64.h | 4 +- 14 files changed, 41 insertions(+), 39 deletions(-) diff --git a/docs_src/docs/api_guide/components/dcl/dcl.md b/docs_src/docs/api_guide/components/dcl/dcl.md index 5ccd009..ea5cb29 100644 --- a/docs_src/docs/api_guide/components/dcl/dcl.md +++ b/docs_src/docs/api_guide/components/dcl/dcl.md @@ -54,79 +54,80 @@ A benchmark on R5F core has been conducted to observe the following results when PI Controller DCL_runPISeries - 49.15 + 49 DCL_runPIParallel - 50.00 + 50 DCL_runPISeriesTustin - 56.35 + 56 DCL_runPIParallelEnhanced - 62.57 + 62 PI2 Controller DCL_runPI2Series - 74.00 + 74 PID Controller DCL_runPIDSeries - 64.68 + 65 DCL_runPIDParallel - 64.84 + 65 DF11 Controller DCL_runDF11 - 24.00 + 24 DF13 Controller DCL_runDF13 - 43.00 + 43 DCL_runDF13Clamp - 53.00 + 53 DF22 Controller DCL_runDF22 - 27.00 + 27 DCL_runDF22Clamp - 41.00 + 41 DF23 Controller DCL_runDF23 - 29.00 + 29 DCL_runDF23Clamp - 45.00 + 45 PID 64bit Controller DCL_runPIDF64Series - 185.14 + 185 DCL_runPIDF64Parallel - 173.63 + 174 -- Ran with TI Clang Compiler v2.1.3.LTS, with -Os flag and functions in ram, obtained the average result from 600 consecutive reading of running the controller with DPL CycleCountP. -- Actual result may vary depending on provided datasets and memory configuration. +- Ran with TI Clang Compiler v2.1.3.LTS, with -Os flag and all DCL functions inlined, obtained the average result from 600 consecutive reading of running the controller with DPL CycleCountP. +- Simulated inputs are based on arbitrary sinusoidal waves and saturation condition that roughly clamps ~50% of the time. For functions with clamp (PI,PI2,PID and DF Clamps), clock cycle varies depending on clamping condition and provided inputs. +- Actual result may vary depending on provided datasets and memory configuration. For R5F, it is recommended for users to map control loops to TCM for the best performance. ## Provided Examples diff --git a/source/dcl/common/dcl_aux.h b/source/dcl/common/dcl_aux.h index 544d169..7203fe5 100644 --- a/source/dcl/common/dcl_aux.h +++ b/source/dcl/common/dcl_aux.h @@ -84,7 +84,6 @@ extern "C" { //! \code //! float32_t s = DCL_rand(1.0f); //! \endcode -//! #define DCL_rand(a) (a * ((float32_t) rand() / (float32_t) (RAND_MAX >> 1) - 1.0f)) #define DCL_randF64(a) (a * ((float64_t) rand() / (float64_t) (RAND_MAX >> 1) - 1.0L)) @@ -94,7 +93,7 @@ extern "C" { #define DCL_c2Limit ((2.0f - CONST_PI) / (2.0f + CONST_PI)) #define DCL_c2LimitF64 ((2.0L - CONST_PI_F64) / (2.0L + CONST_PI_F64)) -/** @} */ +/** @} */ #ifdef __cplusplus } diff --git a/source/dcl/common/dcl_css.h b/source/dcl/common/dcl_css.h index 5d28335..6ddad69 100644 --- a/source/dcl/common/dcl_css.h +++ b/source/dcl/common/dcl_css.h @@ -86,10 +86,10 @@ typedef struct dcl_css64 { //! CSS pointer must be configured first //! //! \param[in] p Pointer to the controller structure -//! \param[in] a Sample period in seconds +//! \param[in] T Sample period in seconds //! \return None //! -#define DCL_setControllerPeriod(p,a) ((p)->css->T = a) +#define DCL_setControllerPeriod(p,T) ((p)->css->t_sec = T) //--- Status word ------------------------------------------------------------ diff --git a/source/dcl/common/dcl_zpk3.h b/source/dcl/common/dcl_zpk3.h index 417f0ec..b77318f 100644 --- a/source/dcl/common/dcl_zpk3.h +++ b/source/dcl/common/dcl_zpk3.h @@ -56,7 +56,7 @@ extern "C" { //! \details Allows controllers to be defined in terms of complex pole //! and zero frequencies. The common structure consists of //! three complex zeros, three complex poles, and a real gain. -//! All frequencies must be specified in radians/sec. <--- TODO: Conflicting units compared with the documentation,rad/s or hz? +//! All frequencies must be specified in radians/sec. //! typedef struct dcl_zpk3 { diff --git a/source/dcl/df/dcl_df11.h b/source/dcl/df/dcl_df11.h index 9e33335..fc168fb 100644 --- a/source/dcl/df/dcl_df11.h +++ b/source/dcl/df/dcl_df11.h @@ -51,7 +51,7 @@ extern "C" { //--- Direct Form 1 - 1st order ---------------------------------------------- -//! \brief Defines the DCL_DF11 shadow parameter set +//! \brief Defines DCL_DF11 shadow parameter set //! used for updating compensator parameter //! typedef struct dcl_df11_sps @@ -63,7 +63,7 @@ typedef struct dcl_df11_sps #define DF11_SPS_DEFAULTS { 0.5f, 0.5f, 1.0f } -//! \brief DF11 object for storing df11 specific parameters +//! \brief DCL_DF11 object for storing df11 specific parameters //! typedef _DCL_VOLATILE struct dcl_df11 { diff --git a/source/dcl/df/dcl_df13.h b/source/dcl/df/dcl_df13.h index c68e493..c71817b 100644 --- a/source/dcl/df/dcl_df13.h +++ b/source/dcl/df/dcl_df13.h @@ -66,7 +66,7 @@ typedef struct dcl_df13_sps { #define DF13_SPS_DEFAULTS { 0.25f, 0.25f, 0.25f, 0.25f, 0.0f, 0.0f, 0.0f } -//! \brief DF13 object for storing df13 specific parameters +//! \brief DCL_DF13 object for storing df13 specific parameters //! typedef _DCL_VOLATILE struct dcl_df13 { diff --git a/source/dcl/df/dcl_df22.h b/source/dcl/df/dcl_df22.h index 4ed9626..976e1b8 100644 --- a/source/dcl/df/dcl_df22.h +++ b/source/dcl/df/dcl_df22.h @@ -51,7 +51,7 @@ extern "C" { //--- Direct Form 2 - 2nd order ---------------------------------------------- -//! \brief Defines the DCL_DF22 shadow parameter set +//! \brief Defines DCL_DF22 shadow parameter set //! used for updating compensator parameter //! typedef struct dcl_df22_sps @@ -65,7 +65,7 @@ typedef struct dcl_df22_sps #define DF22_SPS_DEFAULTS { 1.0f, 0.0f, 0.0f, 0.0f, 0.0f } -//! \brief DF22 object for storing df22 specific parameters +//! \brief DCL_DF22 object for storing df22 specific parameters //! typedef _DCL_VOLATILE struct dcl_df22 { diff --git a/source/dcl/df/dcl_df23.h b/source/dcl/df/dcl_df23.h index 3a35ad4..2891374 100644 --- a/source/dcl/df/dcl_df23.h +++ b/source/dcl/df/dcl_df23.h @@ -51,7 +51,7 @@ extern "C" { //--- Direct Form 2 - 3rd order ---------------------------------------------- -//! \brief Defines the DCL_DF23 shadow parameter set +//! \brief Defines DCL_DF23 shadow parameter set //! used for updating compensator parameter //! typedef struct dcl_df23_sps @@ -67,7 +67,7 @@ typedef struct dcl_df23_sps #define DF23_SPS_DEFAULTS { 1.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f } -//! \brief DF23 object for storing df23 specific parameters +//! \brief DCL_DF23 object for storing df23 specific parameters //! typedef _DCL_VOLATILE struct dcl_df23 { diff --git a/source/dcl/misc/dcl_error.h b/source/dcl/misc/dcl_error.h index fdc9a36..b01c53d 100644 --- a/source/dcl/misc/dcl_error.h +++ b/source/dcl/misc/dcl_error.h @@ -49,7 +49,7 @@ extern "C" { //--- Error handling --------------------------------------------------------- -//! \brief Defines the library enumerated error codes +//! \brief Defines the library enumerated error codes. //! These will be applied as bit masks in the error handler //! typedef enum diff --git a/source/dcl/misc/dcl_fdlog.h b/source/dcl/misc/dcl_fdlog.h index 26fc58b..57e61e0 100644 --- a/source/dcl/misc/dcl_fdlog.h +++ b/source/dcl/misc/dcl_fdlog.h @@ -69,6 +69,8 @@ extern "C" { #include "../dcl_common.h" +//! \brief Defines the data logger strcture for 32-bit float +//! typedef _DCL_VOLATILE struct dcl_fdlog { float32_t *fptr; //!< Pointer to first buffer element diff --git a/source/dcl/pi/dcl_pi.h b/source/dcl/pi/dcl_pi.h index 1f8bd01..91d6704 100644 --- a/source/dcl/pi/dcl_pi.h +++ b/source/dcl/pi/dcl_pi.h @@ -49,7 +49,7 @@ extern "C" { //--- Linear PI controller --------------------------------------------------- -//! \brief Defines the DCL_PI shadow parameter set +//! \brief Defines DCL_PI shadow parameter set //! used for updating controller parameter //! typedef struct dcl_pi_sps @@ -64,7 +64,7 @@ typedef struct dcl_pi_sps //! #define PI_SPS_DEFAULTS { 1.0f, 0.0f, 1.0f, -1.0f } -//! \brief PI object for storing PI specific parameters +//! \brief DCL_PI object for storing PI specific parameters //! typedef _DCL_VOLATILE struct dcl_pi { diff --git a/source/dcl/pi/dcl_pi2.h b/source/dcl/pi/dcl_pi2.h index 9d97c56..13b6b5e 100644 --- a/source/dcl/pi/dcl_pi2.h +++ b/source/dcl/pi/dcl_pi2.h @@ -49,7 +49,7 @@ extern "C" { //--- Linear PI2 controller -------------------------------------------------- -//! \brief Defines the DCL_PI2 shadow parameter set +//! \brief Defines DCL_PI2 shadow parameter set //! used for updating controller parameter //! typedef struct dcl_pi2_sps @@ -64,7 +64,7 @@ typedef struct dcl_pi2_sps //! #define PI2_SPS_DEFAULTS { 1.0f, 0.0f, 1.0f, -1.0f } -//! \brief PI2 object for storing PI2 specific parameters +//! \brief DCL_PI2 object for storing PI2 specific parameters //! PI2 - PI controller with double integrators //! typedef _DCL_VOLATILE struct dcl_pi2 diff --git a/source/dcl/pid/dcl_pid.h b/source/dcl/pid/dcl_pid.h index 04ce65c..7a234eb 100644 --- a/source/dcl/pid/dcl_pid.h +++ b/source/dcl/pid/dcl_pid.h @@ -49,7 +49,7 @@ extern "C" { //--- Linear PID controller -------------------------------------------------- -//! \brief Defines the DCL_PID shadow parameter set +//! \brief Defines DCL_PID shadow parameter set //! used for updating controller parameter //! typedef struct dcl_pid_sps @@ -68,7 +68,7 @@ typedef struct dcl_pid_sps //! #define PID_SPS_DEFAULTS { 1.0f, 0.0f, 0.0f, 1.0f, 1.0f, 0.0f, 1.0f, -1.0f } -//! \brief PID object for storing PID specific parameters +//! \brief DCL_PID object for storing PID specific parameters //! typedef _DCL_VOLATILE struct dcl_pid { diff --git a/source/dcl/pid/dcl_pidf64.h b/source/dcl/pid/dcl_pidf64.h index e96d0cc..9f0fb88 100644 --- a/source/dcl/pid/dcl_pidf64.h +++ b/source/dcl/pid/dcl_pidf64.h @@ -49,7 +49,7 @@ extern "C" { //--- Linear PID 64bit controller -------------------------------------------------- -//! \brief Defines the shadow PID64 controller structure +//! \brief Defines DCL_PIDF64 shadow PID64 controller structure //! used for updating controller parameter //! typedef struct dcl_pid64_sps { @@ -67,7 +67,7 @@ typedef struct dcl_pid64_sps { //! #define PIDF64_SPS_DEFAULTS { 1.0L, 0.0L, 0.0L, 1.0L, 1.0L, 0.0L, 1.0L, -1.0L } -//! \brief PID 64bit object for storing PID specific 64bit parameters +//! \brief DCL_PIDF64 object for storing 64bit PID specific parameters //! typedef _DCL_VOLATILE struct dcl_pidf64 { /* controller parameter */