flight/pios/inc/pios_instrumentation_helper.h

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       pios_instrumentation_helper.h
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2014.
   6  * @brief      Macros to easily add optional performance monitoring to a module
   7  *
   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
  27 /**
  28  * @addtogroup PIOS PiOS Instrumentation Support
  29  * @{
  30  */
  31
  32 /**
  33  * \par
  34  * This is a collections of helper macros that ease adding instrumentation support.
  35  * \par
  36  * Step by step guide:
  37  *
  38  * Define PIOS_INSTRUMENT_MODULE before including this file to enable instrumentation for a module
  39  *
  40  * <pre>#define PIOS_INSTRUMENT_MODULE
  41  * #include <pios_instrumentation_helper.h></pre>
  42  *
  43  * Declare the variables used to hold counter handlers.
  44  * Place the following code along all module variables declaration.
  45  * <pre>PERF_DEFINE_COUNTER(counterUpd);
  46  * PERF_DEFINE_COUNTER(counterAccelSamples);
  47  * PERF_DEFINE_COUNTER(counterPeriod);
  48  * PERF_DEFINE_COUNTER(counterAtt);</pre>
  49  *
  50  * Counters needs to be initialized before they are used.
  51  * The following code needs to be added to a function called at module initialization.
  52  * the second parameter is a unique counter Id.
  53  * A good pracice is to use the upper half word as module id and lower as counter id
  54  * <pre>PERF_INIT_COUNTER(counterUpd, 0xA7710001);
  55  * PERF_INIT_COUNTER(counterAtt, 0xA7710002);
  56  * PERF_INIT_COUNTER(counterPeriod, 0xA7710003);
  57  * PERF_INIT_COUNTER(counterAccelSamples, 0xA7710004);</pre>
  58  *
  59  * At this point you can start using the counters as in the following samples
  60  *
  61  * Track the time spent on a certain function:
  62  * <pre>PERF_TIMED_SECTION_START(counterAtt);
  63  * updateAttitude(&accelState, &gyros);
  64  * PERF_TIMED_SECTION_END(counterAtt);</pre>
  65  * PERF_TIMED_SECTION_[START!STOP] marks the beginning and the end of the code to monitor
  66  *
  67  * Measure the mean of the period a certain point is reached:
  68  * <pre>PERF_MEASURE_PERIOD(counterPeriod);</pre>
  69  * Note that the value stored in the counter is a long running mean while max and min are single point values
  70  *
  71  * Track an user defined int32_t value:
  72  * <pre>PERF_TRACK_VALUE(counterAccelSamples, i);</pre>
  73  * the counter is then updated with the value of i.
  74  *
  75  * \par
  76  */
  77
  78 #ifndef PIOS_INSTRUMENTATION_HELPER_H
  79 #define PIOS_INSTRUMENTATION_HELPER_H
  80
  81 #if defined(PIOS_INCLUDE_INSTRUMENTATION) && defined(PIOS_INSTRUMENT_MODULE)
  82
  83 #include <pios_instrumentation.h>
  84 /**
  85  * include the following macro together with modules variable declaration
  86  */
  87 #define PERF_DEFINE_COUNTER(x)      pios_counter_t x
  88
  89 /**
  90  * this mast be called at some module init code
  91  */
  92 #define PERF_INIT_COUNTER(x, id)    x = PIOS_Instrumentation_CreateCounter(id)
  93
  94 /**
  95  * those are the monitoring macros
  96  */
  97 #define PERF_TIMED_SECTION_START(x) PIOS_Instrumentation_TimeStart(x)
  98 #define PERF_TIMED_SECTION_END(x)   PIOS_Instrumentation_TimeEnd(x)
  99 #define PERF_MEASURE_PERIOD(x)      PIOS_Instrumentation_TrackPeriod(x)
 100 #define PERF_TRACK_VALUE(x, y)      PIOS_Instrumentation_updateCounter(x, y)
 101
 102 #else
 103
 104 #define PERF_DEFINE_COUNTER(x)
 105 #define PERF_INIT_COUNTER(x, id)
 106 #define PERF_TIMED_SECTION_START(x)
 107 #define PERF_TIMED_SECTION_END(x)
 108 #define PERF_MEASURE_PERIOD(x)
 109 #define PERF_TRACK_VALUE(x, y)
 110 #endif /* PIOS_INCLUDE_INSTRUMENTATION */
 111 #endif /* PIOS_INSTRUMENTATION_HELPER_H */