mono/metadata/profiler.h

   1 /*
   2  * Licensed to the .NET Foundation under one or more agreements.
   3  * The .NET Foundation licenses this file to you under the MIT license.
   4  * See the LICENSE file in the project root for more information.
   5  */
   6
   7 #ifndef __MONO_PROFILER_H__
   8 #define __MONO_PROFILER_H__
   9
  10 #include <mono/metadata/appdomain.h>
  11 #include <mono/metadata/mono-gc.h>
  12 #include <mono/metadata/object.h>
  13
  14 MONO_BEGIN_DECLS
  15
  16 /**
  17  * This value will be incremented whenever breaking changes to the profiler API
  18  * are made. This macro is intended for use in profiler modules that wish to
  19  * support older versions of the profiler API.
  20  *
  21  * Version 2:
  22  * - Major overhaul of the profiler API.
  23  * Version 3:
  24  * - Added mono_profiler_enable_clauses (). This must now be called to enable
  25  *   raising exception_clause events.
  26  * - The exception argument to exception_clause events can now be NULL for
  27  *   finally clauses invoked in the non-exceptional case.
  28  * - The type argument to exception_clause events will now correctly indicate
  29  *   that the catch portion of the clause is being executed in the case of
  30  *   try-filter-catch clauses.
  31  * - Removed the iomap_report event.
  32  * - Removed the old gc_event event and renamed gc_event2 to gc_event.
  33  */
  34 #define MONO_PROFILER_API_VERSION 3
  35
  36 typedef struct _MonoProfiler MonoProfiler;
  37 typedef struct _MonoProfilerDesc *MonoProfilerHandle;
  38
  39 typedef void (*MonoProfilerCleanupCallback) (MonoProfiler *prof);
  40
  41 MONO_API void mono_profiler_load (const char *desc);
  42 MONO_API MonoProfilerHandle mono_profiler_create (MonoProfiler *prof);
  43 MONO_API void mono_profiler_set_cleanup_callback (MonoProfilerHandle handle, MonoProfilerCleanupCallback cb);
  44
  45 typedef struct {
  46         MonoMethod *method;
  47         uint32_t il_offset;
  48         uint32_t counter;
  49         const char *file_name;
  50         uint32_t line;
  51         uint32_t column;
  52 } MonoProfilerCoverageData;
  53
  54 typedef mono_bool (*MonoProfilerCoverageFilterCallback) (MonoProfiler *prof, MonoMethod *method);
  55 typedef void (*MonoProfilerCoverageCallback) (MonoProfiler *prof, const MonoProfilerCoverageData *data);
  56
  57 MONO_API mono_bool mono_profiler_enable_coverage (void);
  58 MONO_API void mono_profiler_set_coverage_filter_callback (MonoProfilerHandle handle, MonoProfilerCoverageFilterCallback cb);
  59 MONO_API mono_bool mono_profiler_get_coverage_data (MonoProfilerHandle handle, MonoMethod *method, MonoProfilerCoverageCallback cb);
  60
  61 typedef enum {
  62         /**
  63          * Do not perform sampling. Will make the sampling thread sleep until the
  64          * sampling mode is changed to one of the below modes.
  65          */
  66         MONO_PROFILER_SAMPLE_MODE_NONE = 0,
  67         /**
  68          * Try to base sampling frequency on process activity. Falls back to
  69          * MONO_PROFILER_SAMPLE_MODE_REAL if such a clock is not available.
  70          */
  71         MONO_PROFILER_SAMPLE_MODE_PROCESS = 1,
  72         /**
  73          * Base sampling frequency on wall clock time. Uses a monotonic clock when
  74          * available (all major platforms).
  75          */
  76         MONO_PROFILER_SAMPLE_MODE_REAL = 2,
  77 } MonoProfilerSampleMode;
  78
  79 MONO_API mono_bool mono_profiler_enable_sampling (MonoProfilerHandle handle);
  80 MONO_API mono_bool mono_profiler_set_sample_mode (MonoProfilerHandle handle, MonoProfilerSampleMode mode, uint32_t freq);
  81 MONO_API mono_bool mono_profiler_get_sample_mode (MonoProfilerHandle handle, MonoProfilerSampleMode *mode, uint32_t *freq);
  82
  83 MONO_API mono_bool mono_profiler_enable_allocations (void);
  84 MONO_API mono_bool mono_profiler_enable_clauses (void);
  85
  86 typedef struct _MonoProfilerCallContext MonoProfilerCallContext;
  87
  88 typedef enum {
  89         /**
  90          * Do not instrument calls.
  91          */
  92         MONO_PROFILER_CALL_INSTRUMENTATION_NONE = 0,
  93         /**
  94          * Instrument method entries.
  95          */
  96         MONO_PROFILER_CALL_INSTRUMENTATION_ENTER = 1 << 1,
  97         /**
  98          * Also capture a call context for method entries.
  99          */
 100         MONO_PROFILER_CALL_INSTRUMENTATION_ENTER_CONTEXT = 1 << 2,
 101         /**
 102          * Instrument method exits.
 103          */
 104         MONO_PROFILER_CALL_INSTRUMENTATION_LEAVE = 1 << 3,
 105         /**
 106          * Also capture a call context for method exits.
 107          */
 108         MONO_PROFILER_CALL_INSTRUMENTATION_LEAVE_CONTEXT = 1 << 4,
 109         /**
 110          * Instrument method exits as a result of a tail call.
 111          */
 112         MONO_PROFILER_CALL_INSTRUMENTATION_TAIL_CALL = 1 << 5,
 113         /**
 114          * Instrument exceptional method exits.
 115          */
 116         MONO_PROFILER_CALL_INSTRUMENTATION_EXCEPTION_LEAVE = 1 << 6,
 117 } MonoProfilerCallInstrumentationFlags;
 118
 119 typedef MonoProfilerCallInstrumentationFlags (*MonoProfilerCallInstrumentationFilterCallback) (MonoProfiler *prof, MonoMethod *method);
 120
 121 MONO_API void mono_profiler_set_call_instrumentation_filter_callback (MonoProfilerHandle handle, MonoProfilerCallInstrumentationFilterCallback cb);
 122 MONO_API mono_bool mono_profiler_enable_call_context_introspection (void);
 123 MONO_API void *mono_profiler_call_context_get_this (MonoProfilerCallContext *context);
 124 MONO_API void *mono_profiler_call_context_get_argument (MonoProfilerCallContext *context, uint32_t position);
 125 MONO_API void *mono_profiler_call_context_get_local (MonoProfilerCallContext *context, uint32_t position);
 126 MONO_API void *mono_profiler_call_context_get_result (MonoProfilerCallContext *context);
 127 MONO_API void mono_profiler_call_context_free_buffer (void *buffer);
 128
 129 typedef enum {
 130         /**
 131          * The \c data parameter is a \c MonoMethod pointer.
 132          */
 133         MONO_PROFILER_CODE_BUFFER_METHOD = 0,
 134         /**
 135          * \deprecated No longer used.
 136          */
 137         MONO_PROFILER_CODE_BUFFER_METHOD_TRAMPOLINE = 1,
 138         /**
 139          * The \c data parameter is a \c MonoMethod pointer.
 140          */
 141         MONO_PROFILER_CODE_BUFFER_UNBOX_TRAMPOLINE = 2,
 142         MONO_PROFILER_CODE_BUFFER_IMT_TRAMPOLINE = 3,
 143         MONO_PROFILER_CODE_BUFFER_GENERICS_TRAMPOLINE = 4,
 144         /**
 145          * The \c data parameter is a C string.
 146          */
 147         MONO_PROFILER_CODE_BUFFER_SPECIFIC_TRAMPOLINE = 5,
 148         MONO_PROFILER_CODE_BUFFER_HELPER = 6,
 149         /**
 150          * \deprecated No longer used.
 151          */
 152         MONO_PROFILER_CODE_BUFFER_MONITOR = 7,
 153         MONO_PROFILER_CODE_BUFFER_DELEGATE_INVOKE = 8,
 154         MONO_PROFILER_CODE_BUFFER_EXCEPTION_HANDLING = 9,
 155 } MonoProfilerCodeBufferType;
 156
 157 typedef enum {
 158         MONO_GC_EVENT_PRE_STOP_WORLD = 6,
 159         /**
 160          * When this event arrives, the GC and suspend locks are acquired.
 161          */
 162         MONO_GC_EVENT_PRE_STOP_WORLD_LOCKED = 10,
 163         MONO_GC_EVENT_POST_STOP_WORLD = 7,
 164         MONO_GC_EVENT_START = 0,
 165         MONO_GC_EVENT_END = 5,
 166         MONO_GC_EVENT_PRE_START_WORLD = 8,
 167         /**
 168          * When this event arrives, the GC and suspend locks are released.
 169          */
 170         MONO_GC_EVENT_POST_START_WORLD_UNLOCKED = 11,
 171         MONO_GC_EVENT_POST_START_WORLD = 9,
 172 } MonoProfilerGCEvent;
 173
 174 /*
 175  * The macros below will generate the majority of the callback API. Refer to
 176  * mono/metadata/profiler-events.h for a list of callbacks. They are expanded
 177  * like so:
 178  *
 179  * typedef void (*MonoProfilerRuntimeInitializedCallback (MonoProfiler *prof);
 180  * MONO_API void mono_profiler_set_runtime_initialized_callback (MonoProfiler *prof, MonoProfilerRuntimeInitializedCallback cb);
 181  *
 182  * typedef void (*MonoProfilerRuntimeShutdownCallback (MonoProfiler *prof);
 183  * MONO_API void mono_profiler_set_runtime_shutdown_callback (MonoProfiler *prof, MonoProfilerRuntimeShutdownCallback cb);
 184  *
 185  * typedef void (*MonoProfilerContextLoadedCallback (MonoProfiler *prof);
 186  * MONO_API void mono_profiler_set_context_loaded_callback (MonoProfiler *prof, MonoProfilerContextLoadedCallback cb);
 187  *
 188  * typedef void (*MonoProfilerContextUnloadedCallback (MonoProfiler *prof);
 189  * MONO_API void mono_profiler_set_context_unloaded_callback (MonoProfiler *prof, MonoProfilerContextUnloadedCallback cb);
 190  *
 191  * Etc.
 192  *
 193  * To remove a callback, pass NULL instead of a valid function pointer.
 194  * Callbacks can be changed at any point, but note that doing so is inherently
 195  * racy with respect to threads that aren't suspended, i.e. you may still see a
 196  * call from another thread right after you change a callback.
 197  *
 198  * These functions are async safe.
 199  */
 200
 201 #define _MONO_PROFILER_EVENT(type, ...) \
 202         typedef void (*MonoProfiler ## type ## Callback) (__VA_ARGS__);
 203 #define MONO_PROFILER_EVENT_0(name, type) \
 204                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof)
 205 #define MONO_PROFILER_EVENT_1(name, type, arg1_type, arg1_name) \
 206                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof, arg1_type arg1_name)
 207 #define MONO_PROFILER_EVENT_2(name, type, arg1_type, arg1_name, arg2_type, arg2_name) \
 208                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof, arg1_type arg1_name, arg2_type arg2_name)
 209 #define MONO_PROFILER_EVENT_3(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name) \
 210                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof, arg1_type arg1_name, arg2_type arg2_name, arg3_type arg3_name)
 211 #define MONO_PROFILER_EVENT_4(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name, arg4_type, arg4_name) \
 212                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof, arg1_type arg1_name, arg2_type arg2_name, arg3_type arg3_name, arg4_type arg4_name)
 213 #define MONO_PROFILER_EVENT_5(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name, arg4_type, arg4_name, arg5_type, arg5_name) \
 214                 _MONO_PROFILER_EVENT(type, MonoProfiler *prof, arg1_type arg1_name, arg2_type arg2_name, arg3_type arg3_name, arg4_type arg4_name, arg5_type arg5_name)
 215 #include <mono/metadata/profiler-events.h>
 216 #undef MONO_PROFILER_EVENT_0
 217 #undef MONO_PROFILER_EVENT_1
 218 #undef MONO_PROFILER_EVENT_2
 219 #undef MONO_PROFILER_EVENT_3
 220 #undef MONO_PROFILER_EVENT_4
 221 #undef MONO_PROFILER_EVENT_5
 222 #undef _MONO_PROFILER_EVENT
 223
 224 #define _MONO_PROFILER_EVENT(name, type) \
 225         MONO_API void mono_profiler_set_ ## name ## _callback (MonoProfilerHandle handle, MonoProfiler ## type ## Callback cb);
 226 #define MONO_PROFILER_EVENT_0(name, type) \
 227         _MONO_PROFILER_EVENT(name, type)
 228 #define MONO_PROFILER_EVENT_1(name, type, arg1_type, arg1_name) \
 229         _MONO_PROFILER_EVENT(name, type)
 230 #define MONO_PROFILER_EVENT_2(name, type, arg1_type, arg1_name, arg2_type, arg2_name) \
 231         _MONO_PROFILER_EVENT(name, type)
 232 #define MONO_PROFILER_EVENT_3(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name) \
 233         _MONO_PROFILER_EVENT(name, type)
 234 #define MONO_PROFILER_EVENT_4(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name, arg4_type, arg4_name) \
 235         _MONO_PROFILER_EVENT(name, type)
 236 #define MONO_PROFILER_EVENT_5(name, type, arg1_type, arg1_name, arg2_type, arg2_name, arg3_type, arg3_name, arg4_type, arg4_name, arg5_type, arg5_name) \
 237         _MONO_PROFILER_EVENT(name, type)
 238 #include <mono/metadata/profiler-events.h>
 239 #undef MONO_PROFILER_EVENT_0
 240 #undef MONO_PROFILER_EVENT_1
 241 #undef MONO_PROFILER_EVENT_2
 242 #undef MONO_PROFILER_EVENT_3
 243 #undef MONO_PROFILER_EVENT_4
 244 #undef MONO_PROFILER_EVENT_5
 245 #undef _MONO_PROFILER_EVENT
 246
 247 MONO_END_DECLS
 248
 249 #endif // __MONO_PROFILER_H__