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-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#ifdef __cplusplus
18#include <cstddef>
19#include <cstdint>
20#else
21#include <stddef.h>
22#include <stdint.h>
23#endif
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
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. This
40/// 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 id
44/// is generated by xray; the mapping between the function id
45/// and the actual function pointer is available through
46/// __xray_table.
47/// - entry type: identifies what kind of instrumentation point was
48/// encountered (function entry, function exit, etc.). See the
49/// enum XRayEntryType for more details.
50///
51/// The user handler must handle correctly spurious calls after this handler is
52/// removed or replaced with another handler, because it would be too costly for
53/// XRay runtime to avoid spurious calls.
54/// To prevent circular calling, the handler function itself and all its
55/// direct&indirect callees must not be instrumented with XRay, which can be
56/// 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 on
62/// 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 and
67/// 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 type
85/// 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 loaded
104/// 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 possible
112/// result values.
113extern enum XRayPatchingStatus __xray_unpatch();
114
115/// Reverses the effect of __xray_patch_object. See XRayPatchingStatus for
116/// possible result values.
117extern enum XRayPatchingStatus __xray_unpatch_object(int32_t ObjId);
118
119/// This unpacks the given (packed) function id and patches
120/// the corresponding function. See XRayPatchingStatus for possible
121/// result values.
122extern enum XRayPatchingStatus __xray_patch_function(int32_t FuncId);
123
124/// This patches a specific function in the given object. See XRayPatchingStatus
125/// 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 unpatches
130/// the corresponding function. See XRayPatchingStatus for possible
131/// 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 address
140/// of the corresponding function. We return 0 if we encounter any error, even
141/// 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 object
145/// provided valid function and object ids. We return 0 if we encounter any
146/// 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 executable
151/// (object id = 0). Returns 0 if we encounter errors (when there are no
152/// 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 objects
161/// (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, the
172/// 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 where
176/// users want to control precisely when the XRay instrumentation data
177/// structures are initialized, for example when the XRay library is built with
178/// 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 __cplusplus
184} // end extern "C"
185#endif
186
187#endif // XRAY_XRAY_INTERFACE_H
188