188 lines · c
1//===- xray_interface.h ---------------------------------------------------===//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-exception6//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_H15#define XRAY_XRAY_INTERFACE_H16 17#ifdef __cplusplus18#include <cstddef>19#include <cstdint>20#else21#include <stddef.h>22#include <stdint.h>23#endif24 25#ifdef __cplusplus26extern "C" {27#endif28 29/// Synchronize this with AsmPrinter::SledKind in LLVM.30enum XRayEntryType {31 ENTRY = 0,32 EXIT = 1,33 TAIL = 2,34 LOG_ARGS_ENTRY = 3,35 CUSTOM_EVENT = 4,36 TYPED_EVENT = 5,37};38 39/// Provide a function to invoke for when instrumentation points are hit. This40/// is a user-visible control surface that overrides the default implementation.41/// The function provided should take the following arguments:42///43/// - function id: an identifier that indicates the id of a function; this id44/// is generated by xray; the mapping between the function id45/// and the actual function pointer is available through46/// __xray_table.47/// - entry type: identifies what kind of instrumentation point was48/// encountered (function entry, function exit, etc.). See the49/// enum XRayEntryType for more details.50///51/// The user handler must handle correctly spurious calls after this handler is52/// removed or replaced with another handler, because it would be too costly for53/// XRay runtime to avoid spurious calls.54/// To prevent circular calling, the handler function itself and all its55/// direct&indirect callees must not be instrumented with XRay, which can be56/// achieved by marking them all with: __attribute__((xray_never_instrument))57///58/// Returns 1 on success, 0 on error.59extern int __xray_set_handler(void (*entry)(int32_t, enum XRayEntryType));60 61/// This removes whatever the currently provided handler is. Returns 1 on62/// success, 0 on error.63extern int __xray_remove_handler();64 65/// Use XRay to log the first argument of each (instrumented) function call.66/// When this function exits, all threads will have observed the effect and67/// start logging their subsequent affected function calls (if patched).68///69/// Returns 1 on success, 0 on error.70extern int __xray_set_handler_arg1(void (*entry)(int32_t, enum XRayEntryType,71 uint64_t));72 73/// Disables the XRay handler used to log first arguments of function calls.74/// Returns 1 on success, 0 on error.75extern int __xray_remove_handler_arg1();76 77/// Provide a function to invoke when XRay encounters a custom event.78extern int __xray_set_customevent_handler(void (*entry)(void *, size_t));79 80/// This removes whatever the currently provided custom event handler is.81/// Returns 1 on success, 0 on error.82extern int __xray_remove_customevent_handler();83 84/// Set a handler for xray typed event logging. The first parameter is a type85/// identifier, the second is a payload, and the third is the payload size.86/// NOTE: fdrLoggingHandleTypedEvent only supports uint16_t event type.87extern int __xray_set_typedevent_handler(void (*entry)(size_t, const void *,88 size_t));89 90/// Removes the currently set typed event handler.91/// Returns 1 on success, 0 on error.92extern int __xray_remove_typedevent_handler();93 94extern uint16_t __xray_register_event_type(const char *event_type);95 96enum XRayPatchingStatus {97 NOT_INITIALIZED = 0,98 SUCCESS = 1,99 ONGOING = 2,100 FAILED = 3,101};102 103/// This tells XRay to patch the instrumentation points in all currently loaded104/// objects. See XRayPatchingStatus for possible result values.105extern enum XRayPatchingStatus __xray_patch();106 107/// This tells XRay to patch the instrumentation points in the given object.108/// See XRayPatchingStatus for possible result values.109extern enum XRayPatchingStatus __xray_patch_object(int32_t ObjId);110 111/// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible112/// result values.113extern enum XRayPatchingStatus __xray_unpatch();114 115/// Reverses the effect of __xray_patch_object. See XRayPatchingStatus for116/// possible result values.117extern enum XRayPatchingStatus __xray_unpatch_object(int32_t ObjId);118 119/// This unpacks the given (packed) function id and patches120/// the corresponding function. See XRayPatchingStatus for possible121/// result values.122extern enum XRayPatchingStatus __xray_patch_function(int32_t FuncId);123 124/// This patches a specific function in the given object. See XRayPatchingStatus125/// for possible result values.126extern enum XRayPatchingStatus __xray_patch_function_in_object(int32_t FuncId,127 int32_t ObjId);128 129/// This unpacks the given (packed) function id and unpatches130/// the corresponding function. See XRayPatchingStatus for possible131/// result values.132extern enum XRayPatchingStatus __xray_unpatch_function(int32_t FuncId);133 134/// This unpatches a specific function in the given object.135/// See XRayPatchingStatus for possible result values.136extern enum XRayPatchingStatus __xray_unpatch_function_in_object(int32_t FuncId,137 int32_t ObjId);138 139/// This function unpacks the given (packed) function id and returns the address140/// of the corresponding function. We return 0 if we encounter any error, even141/// if 0 may be a valid function address.142extern uintptr_t __xray_function_address(int32_t FuncId);143 144/// This function returns the address of the function in the given object145/// provided valid function and object ids. We return 0 if we encounter any146/// error, even if 0 may be a valid function address.147extern uintptr_t __xray_function_address_in_object(int32_t FuncId,148 int32_t ObjId);149 150/// This function returns the maximum valid function id for the main executable151/// (object id = 0). Returns 0 if we encounter errors (when there are no152/// instrumented functions, etc.).153extern size_t __xray_max_function_id();154 155/// This function returns the maximum valid function id for the given object.156/// Returns 0 if we encounter errors (when there are no instrumented functions,157/// etc.).158extern size_t __xray_max_function_id_in_object(int32_t ObjId);159 160/// This function returns the number of previously registered objects161/// (executable + loaded DSOs). Returns 0 if XRay has not been initialized.162extern size_t __xray_num_objects();163 164/// Unpacks the function id from the given packed id.165extern int32_t __xray_unpack_function_id(int32_t PackedId);166 167/// Unpacks the object id from the given packed id.168extern int32_t __xray_unpack_object_id(int32_t PackedId);169 170/// Creates and returns a packed id from the given function and object ids.171/// If the ids do not fit within the reserved number of bits for each part, the172/// high bits are truncated.173extern int32_t __xray_pack_id(int32_t FuncId, int32_t ObjId);174 175/// Initialize the required XRay data structures. This is useful in cases where176/// users want to control precisely when the XRay instrumentation data177/// structures are initialized, for example when the XRay library is built with178/// the XRAY_NO_PREINIT preprocessor definition.179///180/// Calling __xray_init() more than once is safe across multiple threads.181extern void __xray_init();182 183#ifdef __cplusplus184} // end extern "C"185#endif186 187#endif // XRAY_XRAY_INTERFACE_H188