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 66