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