contrib/compiler-rt/include/xray/xray_interface.h

   1 //===-- xray_interface.h ----------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file is a part of XRay, a dynamic runtime instrumentation system.
  11 //
  12 // APIs for controlling XRay functionality explicitly.
  13 //===----------------------------------------------------------------------===//
  14 #ifndef XRAY_XRAY_INTERFACE_H
  15 #define XRAY_XRAY_INTERFACE_H
  16
  17 #include <cstdint>
  18
  19 extern "C" {
  20
  21 enum XRayEntryType { ENTRY = 0, EXIT = 1, TAIL = 2 };
  22
  23 // Provide a function to invoke for when instrumentation points are hit. This is
  24 // a user-visible control surface that overrides the default implementation. The
  25 // function provided should take the following arguments:
  26 //
  27 //   - function id: an identifier that indicates the id of a function; this id
  28 //                  is generated by xray; the mapping between the function id
  29 //                  and the actual function pointer is available through
  30 //                  __xray_table.
  31 //   - entry type: identifies what kind of instrumentation point was encountered
  32 //                 (function entry, function exit, etc.). See the enum
  33 //                 XRayEntryType for more details.
  34 //
  35 // The user handler must handle correctly spurious calls after this handler is
  36 // removed or replaced with another handler, because it would be too costly for
  37 // XRay runtime to avoid spurious calls.
  38 // To prevent circular calling, the handler function itself and all its
  39 // direct&indirect callees must not be instrumented with XRay, which can be
  40 // achieved by marking them all with: __attribute__((xray_never_instrument))
  41 //
  42 // Returns 1 on success, 0 on error.
  43 extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType));
  44
  45 // This removes whatever the currently provided handler is. Returns 1 on
  46 // success, 0 on error.
  47 extern int __xray_remove_handler();
  48
  49 enum XRayPatchingStatus {
  50   NOT_INITIALIZED = 0,
  51   SUCCESS = 1,
  52   ONGOING = 2,
  53   FAILED = 3,
  54 };
  55
  56 // This tells XRay to patch the instrumentation points. See XRayPatchingStatus
  57 // for possible result values.
  58 extern XRayPatchingStatus __xray_patch();
  59
  60 // Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
  61 // result values.
  62 extern XRayPatchingStatus __xray_unpatch();
  63 }
  64
  65 #endif