1*3cab2bb3Spatrick //===- xray_interface.h -----------------------------------------*- C++ -*-===// 2*3cab2bb3Spatrick // 3*3cab2bb3Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4*3cab2bb3Spatrick // See https://llvm.org/LICENSE.txt for license information. 5*3cab2bb3Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6*3cab2bb3Spatrick // 7*3cab2bb3Spatrick //===----------------------------------------------------------------------===// 8*3cab2bb3Spatrick // 9*3cab2bb3Spatrick // This file is a part of XRay, a dynamic runtime instrumentation system. 10*3cab2bb3Spatrick // 11*3cab2bb3Spatrick // APIs for controlling XRay functionality explicitly. 12*3cab2bb3Spatrick //===----------------------------------------------------------------------===// 13*3cab2bb3Spatrick 14*3cab2bb3Spatrick #ifndef XRAY_XRAY_INTERFACE_H 15*3cab2bb3Spatrick #define XRAY_XRAY_INTERFACE_H 16*3cab2bb3Spatrick 17*3cab2bb3Spatrick #include <cstddef> 18*3cab2bb3Spatrick #include <cstdint> 19*3cab2bb3Spatrick 20*3cab2bb3Spatrick extern "C" { 21*3cab2bb3Spatrick 22*3cab2bb3Spatrick /// Synchronize this with AsmPrinter::SledKind in LLVM. 23*3cab2bb3Spatrick enum XRayEntryType { 24*3cab2bb3Spatrick ENTRY = 0, 25*3cab2bb3Spatrick EXIT = 1, 26*3cab2bb3Spatrick TAIL = 2, 27*3cab2bb3Spatrick LOG_ARGS_ENTRY = 3, 28*3cab2bb3Spatrick CUSTOM_EVENT = 4, 29*3cab2bb3Spatrick TYPED_EVENT = 5, 30*3cab2bb3Spatrick }; 31*3cab2bb3Spatrick 32*3cab2bb3Spatrick /// Provide a function to invoke for when instrumentation points are hit. This 33*3cab2bb3Spatrick /// is a user-visible control surface that overrides the default implementation. 34*3cab2bb3Spatrick /// The function provided should take the following arguments: 35*3cab2bb3Spatrick /// 36*3cab2bb3Spatrick /// - function id: an identifier that indicates the id of a function; this id 37*3cab2bb3Spatrick /// is generated by xray; the mapping between the function id 38*3cab2bb3Spatrick /// and the actual function pointer is available through 39*3cab2bb3Spatrick /// __xray_table. 40*3cab2bb3Spatrick /// - entry type: identifies what kind of instrumentation point was 41*3cab2bb3Spatrick /// encountered (function entry, function exit, etc.). See the 42*3cab2bb3Spatrick /// enum XRayEntryType for more details. 43*3cab2bb3Spatrick /// 44*3cab2bb3Spatrick /// The user handler must handle correctly spurious calls after this handler is 45*3cab2bb3Spatrick /// removed or replaced with another handler, because it would be too costly for 46*3cab2bb3Spatrick /// XRay runtime to avoid spurious calls. 47*3cab2bb3Spatrick /// To prevent circular calling, the handler function itself and all its 48*3cab2bb3Spatrick /// direct&indirect callees must not be instrumented with XRay, which can be 49*3cab2bb3Spatrick /// achieved by marking them all with: __attribute__((xray_never_instrument)) 50*3cab2bb3Spatrick /// 51*3cab2bb3Spatrick /// Returns 1 on success, 0 on error. 52*3cab2bb3Spatrick extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType)); 53*3cab2bb3Spatrick 54*3cab2bb3Spatrick /// This removes whatever the currently provided handler is. Returns 1 on 55*3cab2bb3Spatrick /// success, 0 on error. 56*3cab2bb3Spatrick extern int __xray_remove_handler(); 57*3cab2bb3Spatrick 58*3cab2bb3Spatrick /// Use XRay to log the first argument of each (instrumented) function call. 59*3cab2bb3Spatrick /// When this function exits, all threads will have observed the effect and 60*3cab2bb3Spatrick /// start logging their subsequent affected function calls (if patched). 61*3cab2bb3Spatrick /// 62*3cab2bb3Spatrick /// Returns 1 on success, 0 on error. 63*3cab2bb3Spatrick extern int __xray_set_handler_arg1(void (*entry)(int32_t, XRayEntryType, 64*3cab2bb3Spatrick uint64_t)); 65*3cab2bb3Spatrick 66*3cab2bb3Spatrick /// Disables the XRay handler used to log first arguments of function calls. 67*3cab2bb3Spatrick /// Returns 1 on success, 0 on error. 68*3cab2bb3Spatrick extern int __xray_remove_handler_arg1(); 69*3cab2bb3Spatrick 70*3cab2bb3Spatrick /// Provide a function to invoke when XRay encounters a custom event. 71*3cab2bb3Spatrick extern int __xray_set_customevent_handler(void (*entry)(void *, std::size_t)); 72*3cab2bb3Spatrick 73*3cab2bb3Spatrick /// This removes whatever the currently provided custom event handler is. 74*3cab2bb3Spatrick /// Returns 1 on success, 0 on error. 75*3cab2bb3Spatrick extern int __xray_remove_customevent_handler(); 76*3cab2bb3Spatrick 77*3cab2bb3Spatrick /// Set a handler for xray typed event logging. The first parameter is a type 78*3cab2bb3Spatrick /// identifier, the second is a payload, and the third is the payload size. 79*3cab2bb3Spatrick extern int __xray_set_typedevent_handler(void (*entry)(uint16_t, const void *, 80*3cab2bb3Spatrick std::size_t)); 81*3cab2bb3Spatrick 82*3cab2bb3Spatrick /// Removes the currently set typed event handler. 83*3cab2bb3Spatrick /// Returns 1 on success, 0 on error. 84*3cab2bb3Spatrick extern int __xray_remove_typedevent_handler(); 85*3cab2bb3Spatrick 86*3cab2bb3Spatrick extern uint16_t __xray_register_event_type(const char *event_type); 87*3cab2bb3Spatrick 88*3cab2bb3Spatrick enum XRayPatchingStatus { 89*3cab2bb3Spatrick NOT_INITIALIZED = 0, 90*3cab2bb3Spatrick SUCCESS = 1, 91*3cab2bb3Spatrick ONGOING = 2, 92*3cab2bb3Spatrick FAILED = 3, 93*3cab2bb3Spatrick }; 94*3cab2bb3Spatrick 95*3cab2bb3Spatrick /// This tells XRay to patch the instrumentation points. See XRayPatchingStatus 96*3cab2bb3Spatrick /// for possible result values. 97*3cab2bb3Spatrick extern XRayPatchingStatus __xray_patch(); 98*3cab2bb3Spatrick 99*3cab2bb3Spatrick /// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible 100*3cab2bb3Spatrick /// result values. 101*3cab2bb3Spatrick extern XRayPatchingStatus __xray_unpatch(); 102*3cab2bb3Spatrick 103*3cab2bb3Spatrick /// This patches a specific function id. See XRayPatchingStatus for possible 104*3cab2bb3Spatrick /// result values. 105*3cab2bb3Spatrick extern XRayPatchingStatus __xray_patch_function(int32_t FuncId); 106*3cab2bb3Spatrick 107*3cab2bb3Spatrick /// This unpatches a specific function id. See XRayPatchingStatus for possible 108*3cab2bb3Spatrick /// result values. 109*3cab2bb3Spatrick extern XRayPatchingStatus __xray_unpatch_function(int32_t FuncId); 110*3cab2bb3Spatrick 111*3cab2bb3Spatrick /// This function returns the address of the function provided a valid function 112*3cab2bb3Spatrick /// id. We return 0 if we encounter any error, even if 0 may be a valid function 113*3cab2bb3Spatrick /// address. 114*3cab2bb3Spatrick extern uintptr_t __xray_function_address(int32_t FuncId); 115*3cab2bb3Spatrick 116*3cab2bb3Spatrick /// This function returns the maximum valid function id. Returns 0 if we 117*3cab2bb3Spatrick /// encounter errors (when there are no instrumented functions, etc.). 118*3cab2bb3Spatrick extern size_t __xray_max_function_id(); 119*3cab2bb3Spatrick 120*3cab2bb3Spatrick /// Initialize the required XRay data structures. This is useful in cases where 121*3cab2bb3Spatrick /// users want to control precisely when the XRay instrumentation data 122*3cab2bb3Spatrick /// structures are initialized, for example when the XRay library is built with 123*3cab2bb3Spatrick /// the XRAY_NO_PREINIT preprocessor definition. 124*3cab2bb3Spatrick /// 125*3cab2bb3Spatrick /// Calling __xray_init() more than once is safe across multiple threads. 126*3cab2bb3Spatrick extern void __xray_init(); 127*3cab2bb3Spatrick 128*3cab2bb3Spatrick } // end extern "C" 129*3cab2bb3Spatrick 130*3cab2bb3Spatrick #endif // XRAY_XRAY_INTERFACE_H 131