diff options
| author | Tom Rondeau <trondeau@vt.edu> | 2013-07-14 17:48:28 -0400 |
|---|---|---|
| committer | Johnathan Corgan <johnathan@corganlabs.com> | 2013-07-16 14:37:38 -0700 |
| commit | 212e41e8500348e984dd15082c3727c12d19f20f (patch) | |
| tree | fff60dd3c51e378176b51dbcd8bffcc9ef3a5ace /docs/doxygen | |
| parent | 7c0b10389a609115d8c01591f2c8945a10cd7c83 (diff) | |
docs: added doc page on Performance Counters.
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/other/main_page.dox | 3 | ||||
| -rw-r--r-- | docs/doxygen/other/perf_counters.dox | 97 |
2 files changed, 100 insertions, 0 deletions
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox index 85c3ff4fac..d6cc269f40 100644 --- a/docs/doxygen/other/main_page.dox +++ b/docs/doxygen/other/main_page.dox @@ -42,9 +42,12 @@ More details on GNU Radio concepts: \li \ref page_logger \li \ref page_pmt \li \ref page_msg_passing +\li \ref page_stream_tags \li \ref page_metadata \li \ref volk_guide +\li \ref page_perf_counters \li \ref page_pfb +\li \ref page_affinity \li \ref page_tagged_stream_blocks \li \ref page_ofdm \li \ref page_packet_data diff --git a/docs/doxygen/other/perf_counters.dox b/docs/doxygen/other/perf_counters.dox new file mode 100644 index 0000000000..518b04e780 --- /dev/null +++ b/docs/doxygen/other/perf_counters.dox @@ -0,0 +1,97 @@ +/*! \page page_perf_counters Performance Counters + +\section Introduction + +Each block can have a set of Performance Counters that the schedule +keeps track of. These counters measure and store information about +different performance metrics of their operation. The concept is +fairly extensible, but currently, GNU Radio defines five types of +Performance Counters: + +\li noutput_items: number of items the block can produce. +\li nproduced: the number of items the block produced. +\li input_buffers_full: % of how full each input buffer is. +\li output_buffers_full: % of how full each output buffer is. +\li work_time: number of CPU ticks during the call to general_work(). + +For each Performance Counter, we can retrieve the instantaneous, +average, and variance from the block. Access to these counters is done +through a simple set of functions added to every block in the +flowgraph: + +\code + float pc_<name>[_<type>](); +\endcode + +In the above, the \<name\> field is one of the five counters in the +above list of counters. The optional \<type\> suffix is either 'avg' to +get the average value or 'var' to get the variance. Without a suffix, +the function returns the most recent instantaneous value. + +We can also reset the Performance Counters back to zero to remove any +history of the current average and variance calculations for a +particular block. + +\code + void reset_perf_counters(); +\endcode + + +\section pc_config Compile-time and Run-time Configuration + +Because the Performance Counters are calculated during each call to +work for every block, they increase the computational cost and memory +overhead. The more blocks used, the more impact this may have. So +while it turns out after some experimentation that the Performance +Counters add very little overhead (less than 1% speed degradation for +a 24-block flowgraph), we err on the side of minimizing overhead in +the scheduler. To do so, we have added compile-time and run-time +configuration of the use of Performance Counters. + + +\subsection pc_config_compile Compile-time Config + +By default, GNU Radio will build without Performance Counters +enabled. To enable Performance Counters, we pass the following flag to +cmake: + +\code + -DENABLE_PERFORMANCE_COUNTERS=True +\endcode + +Note that this affects the GNU Radio block class and the scheduler +itself. Out-of-tree projects will inherit directly from GNU Radio +because of the inheritance with gr::block. Turning on Performance +Counters for GNU Radio will require a recompilation of the OOT project +but no extra configuration. + + +\subsection pc_config_runtime Run-time Config + +Given the Performance Counters are enabled in GNU Radio at +compile-time, we can still control if they are used or not at +run-time. For this, we use the GNU Radio preferences file in the +section [PerfCounters]. This section is installed into the +gnuradio-runtime.conf file. As usual with the preferences, this +section or any of the individual options can be overridden in the +user's config.conf file or using a GR_CONF_ environmental variable +(see \ref prefs for more details). + +The options for the [PerfCounters] section are: + +\li on: Turn counters on/off at run-time. +\li export: Allow counters to be exported over ControlPort. +\li clock: sets the type of clock used when calculating work_time +('thread' or 'monotonic'). + + +\section pc_perfmonitor Performance Monitor + +See \ref perfmonitor for some details of using a ControlPort-based +monitor application, gr-perf-monitorx, for visualizing the +counters. This application is particularly useful in learning which +blocks are the computationally complex blocks that could use extra +optimization or work to improve their performance. It can also be used +to understand the current 'health' of the application. + +*/ |