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 20extern "C" { 21 22/// Synchronize this with AsmPrinter::SledKind in LLVM. 23enum 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. 52extern 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. 56extern 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. 63extern 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. 68extern int __xray_remove_handler_arg1(); 69 70/// Provide a function to invoke when XRay encounters a custom event. 71extern 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. 75extern 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. 80extern 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. 85extern int __xray_remove_typedevent_handler(); 86 87extern uint16_t __xray_register_event_type(const char *event_type); 88 89enum 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. See XRayPatchingStatus 97/// for possible result values. 98extern XRayPatchingStatus __xray_patch(); 99 100/// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible 101/// result values. 102extern XRayPatchingStatus __xray_unpatch(); 103 104/// This patches a specific function id. See XRayPatchingStatus for possible 105/// result values. 106extern XRayPatchingStatus __xray_patch_function(int32_t FuncId); 107 108/// This unpatches a specific function id. See XRayPatchingStatus for possible 109/// result values. 110extern XRayPatchingStatus __xray_unpatch_function(int32_t FuncId); 111 112/// This function returns the address of the function provided a valid function 113/// id. We return 0 if we encounter any error, even if 0 may be a valid function 114/// address. 115extern uintptr_t __xray_function_address(int32_t FuncId); 116 117/// This function returns the maximum valid function id. Returns 0 if we 118/// encounter errors (when there are no instrumented functions, etc.). 119extern size_t __xray_max_function_id(); 120 121/// Initialize the required XRay data structures. This is useful in cases where 122/// users want to control precisely when the XRay instrumentation data 123/// structures are initialized, for example when the XRay library is built with 124/// the XRAY_NO_PREINIT preprocessor definition. 125/// 126/// Calling __xray_init() more than once is safe across multiple threads. 127extern void __xray_init(); 128 129} // end extern "C" 130 131#endif // XRAY_XRAY_INTERFACE_H 132