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 // Synchronize this with AsmPrinter::SledKind in LLVM.
  22 enum XRayEntryType {
  23   ENTRY = 0,
  24   EXIT = 1,
  25   TAIL = 2,
  26   LOG_ARGS_ENTRY = 3,
  27 };
  28
  29 // Provide a function to invoke for when instrumentation points are hit. This is
  30 // a user-visible control surface that overrides the default implementation. The
  31 // function provided should take the following arguments:
  32 //
  33 //   - function id: an identifier that indicates the id of a function; this id
  34 //                  is generated by xray; the mapping between the function id
  35 //                  and the actual function pointer is available through
  36 //                  __xray_table.
  37 //   - entry type: identifies what kind of instrumentation point was encountered
  38 //                 (function entry, function exit, etc.). See the enum
  39 //                 XRayEntryType for more details.
  40 //
  41 // The user handler must handle correctly spurious calls after this handler is
  42 // removed or replaced with another handler, because it would be too costly for
  43 // XRay runtime to avoid spurious calls.
  44 // To prevent circular calling, the handler function itself and all its
  45 // direct&indirect callees must not be instrumented with XRay, which can be
  46 // achieved by marking them all with: __attribute__((xray_never_instrument))
  47 //
  48 // Returns 1 on success, 0 on error.
  49 extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType));
  50
  51 // This removes whatever the currently provided handler is. Returns 1 on
  52 // success, 0 on error.
  53 extern int __xray_remove_handler();
  54
  55 enum XRayPatchingStatus {
  56   NOT_INITIALIZED = 0,
  57   SUCCESS = 1,
  58   ONGOING = 2,
  59   FAILED = 3,
  60 };
  61
  62 // This tells XRay to patch the instrumentation points. See XRayPatchingStatus
  63 // for possible result values.
  64 extern XRayPatchingStatus __xray_patch();
  65
  66 // Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
  67 // result values.
  68 extern XRayPatchingStatus __xray_unpatch();
  69
  70 // Use XRay to log the first argument of each (instrumented) function call.
  71 // When this function exits, all threads will have observed the effect and
  72 // start logging their subsequent affected function calls (if patched).
  73 //
  74 // Returns 1 on success, 0 on error.
  75 extern int __xray_set_handler_arg1(void (*)(int32_t, XRayEntryType, uint64_t));
  76
  77 // Disables the XRay handler used to log first arguments of function calls.
  78 // Returns 1 on success, 0 on error.
  79 extern int __xray_remove_handler_arg1();
  80 }
  81
  82 #endif