From 622519b7c22fe3ff82cb967e6e8feeb22ca339bc Mon Sep 17 00:00:00 2001 From: Alessio Morale Date: Tue, 10 Jun 2014 22:13:20 +0200 Subject: [PATCH] OP-1365 Flight code instrumentation API: add documentation to pios_instrumentation_helper, uncrustification --- flight/pios/common/pios_instrumentation.c | 10 +-- flight/pios/inc/pios_instrumentation.h | 10 +-- flight/pios/inc/pios_instrumentation_helper.h | 85 +++++++++++++++---- 3 files changed, 78 insertions(+), 27 deletions(-) diff --git a/flight/pios/common/pios_instrumentation.c b/flight/pios/common/pios_instrumentation.c index ff6e01c62..dcd9d0f6f 100644 --- a/flight/pios/common/pios_instrumentation.c +++ b/flight/pios/common/pios_instrumentation.c @@ -49,12 +49,12 @@ pios_counter_t PIOS_Instrumentation_CreateCounter(uint32_t id) PIOS_Assert(pios_instrumentation_perf_counters && (pios_instrumentation_max_counters > pios_instrumentation_last_used_counter)); pios_counter_t counter_handle = PIOS_Instrumentation_SearchCounter(id); - if(!counter_handle) { + if (!counter_handle) { pios_perf_counter_t *newcounter = &pios_instrumentation_perf_counters[++pios_instrumentation_last_used_counter]; - newcounter ->id = id; - newcounter ->max = INT32_MIN; - newcounter ->min = INT32_MAX; - counter_handle = (pios_counter_t)newcounter; + newcounter->id = id; + newcounter->max = INT32_MIN; + newcounter->min = INT32_MAX; + counter_handle = (pios_counter_t)newcounter; } return counter_handle; } diff --git a/flight/pios/inc/pios_instrumentation.h b/flight/pios/inc/pios_instrumentation.h index 7cbd6b349..1926cc734 100644 --- a/flight/pios/inc/pios_instrumentation.h +++ b/flight/pios/inc/pios_instrumentation.h @@ -51,7 +51,7 @@ inline void PIOS_Instrumentation_updateCounter(pios_counter_t counter_handle, in { PIOS_Assert(pios_instrumentation_perf_counters && counter_handle); vPortEnterCritical(); - pios_perf_counter_t *counter = (pios_perf_counter_t *) counter_handle; + pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle; counter->value = newValue; if (counter->value > counter->max) { counter->max = counter->value; @@ -71,7 +71,7 @@ inline void PIOS_Instrumentation_TimeStart(pios_counter_t counter_handle) { PIOS_Assert(pios_instrumentation_perf_counters && counter_handle); vPortEnterCritical(); - pios_perf_counter_t *counter = (pios_perf_counter_t *) counter_handle; + pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle; counter->lastUpdateTS = PIOS_DELAY_GetRaw(); vPortExitCritical(); @@ -85,7 +85,7 @@ inline void PIOS_Instrumentation_TimeEnd(pios_counter_t counter_handle) { PIOS_Assert(pios_instrumentation_perf_counters && counter_handle); vPortEnterCritical(); - pios_perf_counter_t *counter = (pios_perf_counter_t *) counter_handle; + pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle; counter->value = PIOS_DELAY_DiffuS(counter->lastUpdateTS); if (counter->value > counter->max) { @@ -105,8 +105,8 @@ inline void PIOS_Instrumentation_TimeEnd(pios_counter_t counter_handle) inline void PIOS_Instrumentation_TrackPeriod(pios_counter_t counter_handle) { PIOS_Assert(pios_instrumentation_perf_counters && counter_handle); - pios_perf_counter_t *counter = (pios_perf_counter_t *) counter_handle; - if(counter->lastUpdateTS != 0){ + pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle; + if (counter->lastUpdateTS != 0) { vPortEnterCritical(); uint32_t period = PIOS_DELAY_DiffuS(counter->lastUpdateTS); counter->value = (counter->value * 15 + period) / 16; diff --git a/flight/pios/inc/pios_instrumentation_helper.h b/flight/pios/inc/pios_instrumentation_helper.h index 082d69f3b..2ca62a845 100644 --- a/flight/pios/inc/pios_instrumentation_helper.h +++ b/flight/pios/inc/pios_instrumentation_helper.h @@ -8,22 +8,73 @@ * @see The GNU Public License (GPL) Version 3 * *****************************************************************************/ -/* - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 3 of the License, or +/* + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 3 of the License, or * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * for more details. - * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @addtogroup PIOS PiOS Instrumentation Support + * @{ + */ + +/** +* \par +* This is a collections of helper macros that ease adding instrumentation support. +* \par +* Step by step guide: +* +* Define PIOS_INSTRUMENT_MODULE before including this file to enable instrumentation for a module +* +* 
#define PIOS_INSTRUMENT_MODULE
+* #include
+* +* Declare the variables used to hold counter handlers. +* Place the following code along all module variables declaration. +* 
PERF_DEFINE_COUNTER(counterUpd);
+* PERF_DEFINE_COUNTER(counterAccelSamples);
+* PERF_DEFINE_COUNTER(counterPeriod);
+* PERF_DEFINE_COUNTER(counterAtt);
+* +* Counters needs to be initialized before they are used. +* The following code needs to be added to a function called at module initialization. +* the second parameter is a unique counter Id. +* A good pracice is to use the upper half word as module id and lower as counter id +* 
PERF_INIT_COUNTER(counterUpd, 0xA7710001);
+* PERF_INIT_COUNTER(counterAtt, 0xA7710002);
+* PERF_INIT_COUNTER(counterPeriod, 0xA7710003);
+* PERF_INIT_COUNTER(counterAccelSamples, 0xA7710004);
+* +* At this point you can start using the counters as in the following samples +* +* Track the time spent on a certain function: +* 
PERF_TIMED_SECTION_START(counterAtt);
+* updateAttitude(&accelState, &gyros);
+* PERF_TIMED_SECTION_END(counterAtt);
+* PERF_TIMED_SECTION_[START!STOP] marks the beginning and the end of the code to monitor +* +* Measure the mean of the period a certain point is reached: +* 
PERF_MEASURE_PERIOD(counterPeriod);
+* Note that the value stored in the counter is a long running mean while max and min are single point values +* +* Track an user defined int32_t value: +* 
PERF_TRACK_VALUE(counterAccelSamples, i);
+* the counter is then updated with the value of i. +* +* \par +*/ + #ifndef PIOS_INSTRUMENTATION_HELPER_H #define PIOS_INSTRUMENTATION_HELPER_H @@ -33,20 +84,20 @@ /** * include the following macro together with modules variable declaration */ -#define PERF_DEFINE_COUNTER(x) pios_counter_t x +#define PERF_DEFINE_COUNTER(x) pios_counter_t x /** * this mast be called at some module init code */ -#define PERF_INIT_COUNTER(x, id) x = PIOS_Instrumentation_CreateCounter(id) +#define PERF_INIT_COUNTER(x, id) x = PIOS_Instrumentation_CreateCounter(id) /** * those are the monitoring macros */ #define PERF_TIMED_SECTION_START(x) PIOS_Instrumentation_TimeStart(x) -#define PERF_TIMED_SECTION_END(x) PIOS_Instrumentation_TimeEnd(x) -#define PERF_MEASURE_PERIOD(x) PIOS_Instrumentation_TrackPeriod(x) -#define PERF_TRACK_VALUE(x,y) PIOS_Instrumentation_updateCounter(x, y) +#define PERF_TIMED_SECTION_END(x) PIOS_Instrumentation_TimeEnd(x) +#define PERF_MEASURE_PERIOD(x) PIOS_Instrumentation_TrackPeriod(x) +#define PERF_TRACK_VALUE(x, y) PIOS_Instrumentation_updateCounter(x, y) #else @@ -55,6 +106,6 @@ #define PERF_TIMED_SECTION_START(x) #define PERF_TIMED_SECTION_END(x) #define PERF_MEASURE_PERIOD(x) -#define PERF_TRACK_VALUE(x,y) +#define PERF_TRACK_VALUE(x, y) #endif /* PIOS_INCLUDE_INSTRUMENTATION */ #endif /* PIOS_INSTRUMENTATION_HELPER_H */