hphp/util/perf-event.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef incl_HPHP_UTIL_PERF_EVENT_H_
  18 #define incl_HPHP_UTIL_PERF_EVENT_H_
  19
  20 #include <cstdint>
  21
  22 namespace HPHP {
  23
  24 ///////////////////////////////////////////////////////////////////////////////
  25
  26 enum class PerfEvent { Load, Store };
  27
  28 struct perf_event_sample_tail;
  29
  30 /*
  31  * Raw data from a sampled perf event.
  32  *
  33  * A perf_event_sample is always followed immediately in memory by the
  34  * corresponding perf_event_sample_tail.
  35  */
  36 struct perf_event_sample {
  37   uintptr_t ip;     // address of the sampled instruction
  38   uint32_t pid;     // process in which the event occurred
  39   uint32_t tid;     // thread in which the event occurred
  40   uintptr_t addr;   // memory address corresponding to the event, if applicable
  41   uint64_t nr;      // number of addresses in the callchain
  42   uintptr_t ips[];  // instruction pointers in the callchain for the event
  43
  44   const perf_event_sample_tail* tail() const {
  45     return reinterpret_cast<const perf_event_sample_tail*>(
  46       reinterpret_cast<const uintptr_t*>(this + 1) + nr
  47     );
  48   }
  49   perf_event_sample_tail* tail() {
  50     return const_cast<perf_event_sample_tail*>(
  51       const_cast<const perf_event_sample*>(this)->tail()
  52     );
  53   }
  54 };
  55
  56 struct perf_event_sample_tail {
  57   uint64_t data_src;
  58 };
  59
  60 /*
  61  * Metadata about the raw `data_src' of a perf_event_sample.
  62  */
  63 struct perf_event_data_src_info {
  64   const char* mem_lvl;  // memory hierarchy level reported
  65   const char* tlb;      // TLB level reported
  66
  67   /*
  68    * Ternary bits: 1 is true, -1 is false, 0 is unknown.
  69    */
  70   int mem_hit : 2;    // cache hit/miss
  71   int snoop : 2;      // snoop?
  72   int snoop_hit : 2;  // snoop hit/miss
  73   int snoop_hitm : 2; // snoop hit modified?
  74   int locked : 2;     // whether the op was part of a locked transaction
  75   int tlb_hit : 2;    // TLB hit/miss
  76 };
  77
  78 /*
  79  * Interpret a raw `data_src' value, based on the event `kind'.
  80  */
  81 perf_event_data_src_info perf_event_data_src(PerfEvent kind, uint64_t data_src);
  82
  83 ///////////////////////////////////////////////////////////////////////////////
  84
  85 using perf_event_signal_fn_t = void (*)(PerfEvent);
  86 using perf_event_consume_fn_t = void (*)(PerfEvent, const perf_event_sample*);
  87
  88 /*
  89  * Enable sampling of load and store instructions on this thread.
  90  *
  91  * Perf events will be sampled roughly `sample_freq' times per second (with
  92  * loads and stores sampled separately).  On each sampled event, `signal_fn'
  93  * will be invoked in the context of the calling thread, via signal handler.
  94  *
  95  * Behavior is undefined if the SIGIO handler is reset, or if SIGIO is masked,
  96  * after calling this function.
  97  *
  98  * Returns true if sampling was successfully enabled, else false (both if
  99  * sampling has already been enabled, or if an error occurs).
 100  */
 101 bool perf_event_enable(uint64_t sample_freq, perf_event_signal_fn_t signal_fn);
 102
 103 /*
 104  * Disable perf memory event sampling on this thread.
 105  *
 106  * All unconsumed samples will be lost, even if sampling is later reenabled.
 107  */
 108 void perf_event_disable();
 109
 110 /*
 111  * Process and clear sampled perf events.
 112  *
 113  * This function can be safely called as long as sampling has been enabled for
 114  * the calling thread.  Each invocation of `signal_fn' indicates that that
 115  * there are events to be consumed---though consuming them from within
 116  * `signal_fn' is discouraged.
 117  *
 118  * Each sampled event is passed to `consume' exactly once.
 119  */
 120 void perf_event_consume(perf_event_consume_fn_t consume);
 121
 122 /*
 123  * Pause or resume sampling for an event.
 124  *
 125  * Can be used instead of perf_event_{enable,disable}() for an event that has
 126  * already been opened, but which should be briefly turned off.
 127  *
 128  * This should likely be called in whatever routine is used to consume events,
 129  * to avoid reentrant sampling.
 130  */
 131 void perf_event_pause();
 132 void perf_event_resume();
 133
 134 ///////////////////////////////////////////////////////////////////////////////
 135
 136 }
 137
 138 #endif