compiler-rt/include/xray/xray_interface.h

   1 //===- xray_interface.h -----------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file is a part of XRay, a dynamic runtime instrumentation system.
  10 //
  11 // APIs for controlling XRay functionality explicitly.
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef XRAY_XRAY_INTERFACE_H
  15 #define XRAY_XRAY_INTERFACE_H
  16
  17 #include <cstddef>
  18 #include <cstdint>
  19
  20 extern "C" {
  21
  22 /// Synchronize this with AsmPrinter::SledKind in LLVM.
  23 enum XRayEntryType {
  24   ENTRY = 0,
  25   EXIT = 1,
  26   TAIL = 2,
  27   LOG_ARGS_ENTRY = 3,
  28   CUSTOM_EVENT = 4,
  29   TYPED_EVENT = 5,
  30 };
  31
  32 /// Provide a function to invoke for when instrumentation points are hit. This
  33 /// is a user-visible control surface that overrides the default implementation.
  34 /// The function provided should take the following arguments:
  35 ///
  36 ///   - function id: an identifier that indicates the id of a function; this id
  37 ///                  is generated by xray; the mapping between the function id
  38 ///                  and the actual function pointer is available through
  39 ///                  __xray_table.
  40 ///   - entry type: identifies what kind of instrumentation point was
  41 ///                 encountered (function entry, function exit, etc.). See the
  42 ///                 enum XRayEntryType for more details.
  43 ///
  44 /// The user handler must handle correctly spurious calls after this handler is
  45 /// removed or replaced with another handler, because it would be too costly for
  46 /// XRay runtime to avoid spurious calls.
  47 /// To prevent circular calling, the handler function itself and all its
  48 /// direct&indirect callees must not be instrumented with XRay, which can be
  49 /// achieved by marking them all with: __attribute__((xray_never_instrument))
  50 ///
  51 /// Returns 1 on success, 0 on error.
  52 extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType));
  53
  54 /// This removes whatever the currently provided handler is. Returns 1 on
  55 /// success, 0 on error.
  56 extern int __xray_remove_handler();
  57
  58 /// Use XRay to log the first argument of each (instrumented) function call.
  59 /// When this function exits, all threads will have observed the effect and
  60 /// start logging their subsequent affected function calls (if patched).
  61 ///
  62 /// Returns 1 on success, 0 on error.
  63 extern int __xray_set_handler_arg1(void (*entry)(int32_t, XRayEntryType,
  64                                                  uint64_t));
  65
  66 /// Disables the XRay handler used to log first arguments of function calls.
  67 /// Returns 1 on success, 0 on error.
  68 extern int __xray_remove_handler_arg1();
  69
  70 /// Provide a function to invoke when XRay encounters a custom event.
  71 extern int __xray_set_customevent_handler(void (*entry)(void *, std::size_t));
  72
  73 /// This removes whatever the currently provided custom event handler is.
  74 /// Returns 1 on success, 0 on error.
  75 extern int __xray_remove_customevent_handler();
  76
  77 /// Set a handler for xray typed event logging. The first parameter is a type
  78 /// identifier, the second is a payload, and the third is the payload size.
  79 /// NOTE: fdrLoggingHandleTypedEvent only supports uint16_t event type.
  80 extern int __xray_set_typedevent_handler(void (*entry)(size_t, const void *,
  81                                                        size_t));
  82
  83 /// Removes the currently set typed event handler.
  84 /// Returns 1 on success, 0 on error.
  85 extern int __xray_remove_typedevent_handler();
  86
  87 extern uint16_t __xray_register_event_type(const char *event_type);
  88
  89 enum XRayPatchingStatus {
  90   NOT_INITIALIZED = 0,
  91   SUCCESS = 1,
  92   ONGOING = 2,
  93   FAILED = 3,
  94 };
  95
  96 /// This tells XRay to patch the instrumentation points in all currently loaded
  97 /// objects. See XRayPatchingStatus for possible result values.
  98 extern XRayPatchingStatus __xray_patch();
  99
 100 /// This tells XRay to patch the instrumentation points in the given object.
 101 /// See XRayPatchingStatus for possible result values.
 102 extern XRayPatchingStatus __xray_patch_object(int32_t ObjId);
 103
 104 /// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
 105 /// result values.
 106 extern XRayPatchingStatus __xray_unpatch();
 107
 108 /// Reverses the effect of __xray_patch_object. See XRayPatchingStatus for
 109 /// possible result values.
 110 extern XRayPatchingStatus __xray_unpatch_object(int32_t ObjId);
 111
 112 /// This unpacks the given (packed) function id and patches
 113 /// the corresponding function.  See XRayPatchingStatus for possible
 114 /// result values.
 115 extern XRayPatchingStatus __xray_patch_function(int32_t FuncId);
 116
 117 /// This patches a specific function in the given object. See XRayPatchingStatus
 118 /// for possible result values.
 119 extern XRayPatchingStatus __xray_patch_function_in_object(int32_t FuncId,
 120                                                           int32_t ObjId);
 121
 122 /// This unpacks the given (packed) function id and unpatches
 123 /// the corresponding function. See XRayPatchingStatus for possible
 124 /// result values.
 125 extern XRayPatchingStatus __xray_unpatch_function(int32_t FuncId);
 126
 127 /// This unpatches a specific function in the given object.
 128 /// See XRayPatchingStatus for possible result values.
 129 extern XRayPatchingStatus __xray_unpatch_function_in_object(int32_t FuncId,
 130                                                             int32_t ObjId);
 131
 132 /// This function unpacks the given (packed) function id and returns the address
 133 /// of the corresponding function. We return 0 if we encounter any error, even
 134 /// if 0 may be a valid function address.
 135 extern uintptr_t __xray_function_address(int32_t FuncId);
 136
 137 /// This function returns the address of the function in the given object
 138 /// provided valid function and object ids. We return 0 if we encounter any
 139 /// error, even if 0 may be a valid function address.
 140 extern uintptr_t __xray_function_address_in_object(int32_t FuncId,
 141                                                    int32_t ObjId);
 142
 143 /// This function returns the maximum valid function id for the main executable
 144 /// (object id = 0). Returns 0 if we encounter errors (when there are no
 145 /// instrumented functions, etc.).
 146 extern size_t __xray_max_function_id();
 147
 148 /// This function returns the maximum valid function id for the given object.
 149 /// Returns 0 if we encounter errors (when there are no instrumented functions,
 150 /// etc.).
 151 extern size_t __xray_max_function_id_in_object(int32_t ObjId);
 152
 153 /// This function returns the number of previously registered objects
 154 /// (executable + loaded DSOs). Returns 0 if XRay has not been initialized.
 155 extern size_t __xray_num_objects();
 156
 157 /// Unpacks the function id from the given packed id.
 158 extern int32_t __xray_unpack_function_id(int32_t PackedId);
 159
 160 /// Unpacks the object id from the given packed id.
 161 extern int32_t __xray_unpack_object_id(int32_t PackedId);
 162
 163 /// Creates and returns a packed id from the given function and object ids.
 164 /// If the ids do not fit within the reserved number of bits for each part, the
 165 /// high bits are truncated.
 166 extern int32_t __xray_pack_id(int32_t FuncId, int32_t ObjId);
 167
 168 /// Initialize the required XRay data structures. This is useful in cases where
 169 /// users want to control precisely when the XRay instrumentation data
 170 /// structures are initialized, for example when the XRay library is built with
 171 /// the XRAY_NO_PREINIT preprocessor definition.
 172 ///
 173 /// Calling __xray_init() more than once is safe across multiple threads.
 174 extern void __xray_init();
 175
 176 } // end extern "C"
 177
 178 #endif // XRAY_XRAY_INTERFACE_H