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 83
