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 179