flight/pios/inc/pios_instrumentation.h

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       pios_instrumentation.h
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2014.
   6  * @brief      PiOS instrumentation infrastructure
   7  *             Allow to collects performance indexes and execution times
   8  * @see        The GNU Public License (GPL) Version 3
   9  *
  10  *****************************************************************************/
  11 /*
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 3 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  20  * for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License along
  23  * with this program; if not, write to the Free Software Foundation, Inc.,
  24  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  25  */
  26 #ifndef PIOS_INSTRUMENTATION_H
  27 #define PIOS_INSTRUMENTATION_H
  28 #include <pios.h>
  29 #include <pios_debug.h>
  30 #include <pios_delay.h>
  31 #include <FreeRTOS.h>
  32 typedef struct {
  33     uint32_t id;
  34     int32_t  max;
  35     int32_t  min;
  36     int32_t  value;
  37     uint32_t lastUpdateTS;
  38 } pios_perf_counter_t;
  39
  40 typedef void *pios_counter_t;
  41
  42 extern pios_perf_counter_t *pios_instrumentation_perf_counters;
  43 extern int8_t pios_instrumentation_last_used_counter;
  44
  45 /**
  46  * Update a counter with a new value
  47  * @param counter_handle handle of the counter to update @see PIOS_Instrumentation_SearchCounter @see PIOS_Instrumentation_CreateCounter
  48  * @param newValue the updated value.
  49  */
  50 static inline void PIOS_Instrumentation_updateCounter(pios_counter_t counter_handle, int32_t newValue)
  51 {
  52     PIOS_Assert(pios_instrumentation_perf_counters && counter_handle);
  53     vPortEnterCritical();
  54     pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle;
  55     counter->value = newValue;
  56     counter->max--;
  57     if (counter->value > counter->max) {
  58         counter->max = counter->value;
  59     }
  60     counter->min++;
  61     if (counter->value < counter->min) {
  62         counter->min = counter->value;
  63     }
  64     counter->lastUpdateTS = PIOS_DELAY_GetRaw();
  65     vPortExitCritical();
  66 }
  67
  68 /**
  69  * Used to determine the time duration of a code block, mark the begin of the block. @see PIOS_Instrumentation_TimeEnd
  70  * @param counter_handle handle of the counter @see PIOS_Instrumentation_SearchCounter @see PIOS_Instrumentation_CreateCounter
  71  */
  72 static inline void PIOS_Instrumentation_TimeStart(pios_counter_t counter_handle)
  73 {
  74     PIOS_Assert(pios_instrumentation_perf_counters && counter_handle);
  75     vPortEnterCritical();
  76     pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle;
  77
  78     counter->lastUpdateTS = PIOS_DELAY_GetRaw();
  79     vPortExitCritical();
  80 }
  81
  82 /**
  83  * Used to determine the time duration of a code block, mark the end of the block. @see PIOS_Instrumentation_TimeStart
  84  * @param counter_handle handle of the counter @see PIOS_Instrumentation_SearchCounter @see PIOS_Instrumentation_CreateCounter
  85  */
  86 static inline void PIOS_Instrumentation_TimeEnd(pios_counter_t counter_handle)
  87 {
  88     PIOS_Assert(pios_instrumentation_perf_counters && counter_handle);
  89     vPortEnterCritical();
  90     pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle;
  91
  92     counter->value = PIOS_DELAY_DiffuS(counter->lastUpdateTS);
  93     counter->max--;
  94     if (counter->value > counter->max) {
  95         counter->max = counter->value;
  96     }
  97     counter->min++;
  98     if (counter->value < counter->min) {
  99         counter->min = counter->value;
 100     }
 101     counter->lastUpdateTS = PIOS_DELAY_GetRaw();
 102     vPortExitCritical();
 103 }
 104
 105 /**
 106  * Used to determine the mean period between each call to the function
 107  * @param counter_handle handle of the counter @see PIOS_Instrumentation_SearchCounter @see PIOS_Instrumentation_CreateCounter
 108  */
 109 static inline void PIOS_Instrumentation_TrackPeriod(pios_counter_t counter_handle)
 110 {
 111     PIOS_Assert(pios_instrumentation_perf_counters && counter_handle);
 112     pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle;
 113     if (counter->lastUpdateTS != 0) {
 114         vPortEnterCritical();
 115         uint32_t period = PIOS_DELAY_DiffuS(counter->lastUpdateTS);
 116         counter->value = (counter->value * 15 + period) / 16;
 117         counter->max--;
 118         if ((int32_t)period > counter->max) {
 119             counter->max = period;
 120         }
 121         counter->min++;
 122         if ((int32_t)period < counter->min) {
 123             counter->min = period;
 124         }
 125         vPortExitCritical();
 126     }
 127     counter->lastUpdateTS = PIOS_DELAY_GetRaw();
 128 }
 129
 130 /**
 131  * Increment a counter with a value
 132  * @param counter_handle handle of the counter to update @see PIOS_Instrumentation_SearchCounter @see PIOS_Instrumentation_CreateCounter
 133  * @param increment the value to increment counter with.
 134  */
 135 static inline void PIOS_Instrumentation_incrementCounter(pios_counter_t counter_handle, int32_t increment)
 136 {
 137     PIOS_Assert(pios_instrumentation_perf_counters && counter_handle);
 138     vPortEnterCritical();
 139     pios_perf_counter_t *counter = (pios_perf_counter_t *)counter_handle;
 140     counter->value += increment;
 141     counter->max--;
 142     if (counter->value > counter->max) {
 143         counter->max = counter->value;
 144     }
 145     counter->min++;
 146     if (counter->value < counter->min) {
 147         counter->min = counter->value;
 148     }
 149     counter->lastUpdateTS = PIOS_DELAY_GetRaw();
 150     vPortExitCritical();
 151 }
 152
 153 /**
 154  * Initialize the Instrumentation infrastructure
 155  * @param maxCounters maximum number of allowed counters
 156  */
 157 void PIOS_Instrumentation_Init(int8_t maxCounters);
 158
 159 /**
 160  * Create a new counter.
 161  * @param id the unique id to assign to the counter
 162  * @return the counter handle to be used to manage its content
 163  */
 164 pios_counter_t PIOS_Instrumentation_CreateCounter(uint32_t id);
 165
 166 /**
 167  * search a counter index by its unique Id
 168  * @param id the unique id to assign to the counter.
 169  * If a counter with the same id exists, the previous instance is returned
 170  * @return the counter handle to be used to manage its content
 171  */
 172 pios_counter_t PIOS_Instrumentation_SearchCounter(uint32_t id);
 173
 174 typedef void (*InstrumentationCounterCallback)(const pios_perf_counter_t *counter, const int8_t index, void *context);
 175 /**
 176  * Retrieve and execute the passed callback for each counter
 177  * @param callback to be called for each counter
 178  * @param context a context variable pointer that can be passed to the callback
 179  */
 180 void PIOS_Instrumentation_ForEachCounter(InstrumentationCounterCallback callback, void *context);
 181
 182 #endif /* PIOS_INSTRUMENTATION_H */