flight/pios/inc/pios_instrumentation_helper.h

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       pios_instrumentation_helper.h
   5  * @author     The LibrePilot Project, http://www.librepilot.org, Copyright (C) 2016
   6  *             The OpenPilot Team, http://www.openpilot.org Copyright (C) 2014.
   7  * @brief      Macros to easily add optional performance monitoring to a module
   8  *
   9  * @see        The GNU Public License (GPL) Version 3
  10  *
  11  *****************************************************************************/
  12 /*
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 3 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  21  * for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License along
  24  * with this program; if not, write to the Free Software Foundation, Inc.,
  25  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  26  */
  27
  28 /**
  29  * @addtogroup PIOS PiOS Instrumentation Support
  30  * @{
  31  */
  32
  33 /**
  34  * \par
  35  * This is a collections of helper macros that ease adding instrumentation support.
  36  * \par
  37  * Step by step guide:
  38  *
  39  * Define PIOS_INSTRUMENT_MODULE before including this file to enable instrumentation for a module
  40  *
  41  * <pre>#define PIOS_INSTRUMENT_MODULE
  42  * #include <pios_instrumentation_helper.h></pre>
  43  *
  44  * Declare the variables used to hold counter handlers.
  45  * Place the following code along all module variables declaration.
  46  * <pre>PERF_DEFINE_COUNTER(counterUpd);
  47  * PERF_DEFINE_COUNTER(counterAccelSamples);
  48  * PERF_DEFINE_COUNTER(counterPeriod);
  49  * PERF_DEFINE_COUNTER(counterAtt);</pre>
  50  *
  51  * Counters needs to be initialized before they are used.
  52  * The following code needs to be added to a function called at module initialization.
  53  * the second parameter is a unique counter Id.
  54  * A good pracice is to use the upper half word as module id and lower as counter id
  55  * Optionally three strings containing Module Name, Counter description and unit of measure can be passed.
  56  * Those strings will be used in future to automatically extract the list of counters from code to managed
  57  * by GCS or some other custom tool.
  58  *
  59  * PERF_INIT_COUNTER(counterVariable, id, "MODULE NAME","COUNTER DESCRIPTION","UNIT OF MEASURE");
  60  *
  61  * <pre>PERF_INIT_COUNTER(counterUpd, 0xA7710001, "ATTITUDE", "Sensor update execution time", "us");
  62  * PERF_INIT_COUNTER(counterAtt, 0xA7710002, "ATTITUDE", "Attitude estimation execution time", "us");
  63  * PERF_INIT_COUNTER(counterPeriod, 0xA7710003, "ATTITUDE", "Sensor update period", "us");
  64  * PERF_INIT_COUNTER(counterAccelSamples, 0xA7710004, "ATTITUDE", "Samples for each sensor cycle", "count");</pre>
  65  *
  66  * At this point you can start using the counters as in the following samples
  67  *
  68  * Track the time spent on a certain function:
  69  * <pre>PERF_TIMED_SECTION_START(counterAtt);
  70  * updateAttitude(&accelState, &gyros);
  71  * PERF_TIMED_SECTION_END(counterAtt);</pre>
  72  * PERF_TIMED_SECTION_[START!STOP] marks the beginning and the end of the code to monitor
  73  *
  74  * Measure the mean of the period a certain point is reached:
  75  * <pre>PERF_MEASURE_PERIOD(counterPeriod);</pre>
  76  * Note that the value stored in the counter is a long running mean while max and min are single point values
  77  *
  78  * Track an user defined int32_t value:
  79  * <pre>PERF_TRACK_VALUE(counterAccelSamples, i);</pre>
  80  * the counter is then updated with the value of i.
  81  *
  82  * \par
  83  */
  84
  85 #ifndef PIOS_INSTRUMENTATION_HELPER_H
  86 #define PIOS_INSTRUMENTATION_HELPER_H
  87
  88 #if defined(PIOS_INCLUDE_INSTRUMENTATION) && defined(PIOS_INSTRUMENT_MODULE)
  89
  90 #include <pios_instrumentation.h>
  91 /**
  92  * include the following macro together with modules variable declaration
  93  */
  94 #define PERF_DEFINE_COUNTER(x)        static pios_counter_t x
  95
  96 /**
  97  * this mast be called at some module init code
  98  */
  99 #define PERF_INIT_COUNTER(x, id, ...) x = PIOS_Instrumentation_CreateCounter(id)
 100
 101 /**
 102  * those are the monitoring macros
 103  */
 104 #define PERF_TIMED_SECTION_START(x)   PIOS_Instrumentation_TimeStart(x)
 105 #define PERF_TIMED_SECTION_END(x)     PIOS_Instrumentation_TimeEnd(x)
 106 #define PERF_MEASURE_PERIOD(x)        PIOS_Instrumentation_TrackPeriod(x)
 107 #define PERF_TRACK_VALUE(x, y)        PIOS_Instrumentation_updateCounter(x, y)
 108 #define PERF_INCREMENT_VALUE(x)       PIOS_Instrumentation_incrementCounter(x, 1)
 109 #define PERF_DECREMENT_VALUE(x)       PIOS_Instrumentation_incrementCounter(x, -1)
 110
 111 #else
 112
 113 #define PERF_DEFINE_COUNTER(x)
 114 #define PERF_INIT_COUNTER(x, id, ...)
 115 #define PERF_TIMED_SECTION_START(x)
 116 #define PERF_TIMED_SECTION_END(x)
 117 #define PERF_MEASURE_PERIOD(x)
 118 #define PERF_TRACK_VALUE(x, y) (void)y
 119 #define PERF_INCREMENT_VALUE(x)
 120 #define PERF_DECREMENT_VALUE(x)
 121 #endif /* PIOS_INCLUDE_INSTRUMENTATION */
 122 #endif /* PIOS_INSTRUMENTATION_HELPER_H */