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 in all currently loaded
97/// objects. See XRayPatchingStatus for possible result values.
98extern XRayPatchingStatus __xray_patch();
99
100/// This tells XRay to patch the instrumentation points in the given object.
101/// See XRayPatchingStatus for possible result values.
102extern XRayPatchingStatus __xray_patch_object(int32_t ObjId);
103
104/// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
105/// result values.
106extern XRayPatchingStatus __xray_unpatch();
107
108/// Reverses the effect of __xray_patch_object. See XRayPatchingStatus for
109/// possible result values.
110extern 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.
115extern 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.
119extern 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.
125extern 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.
129extern 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.
135extern 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.
140extern 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.).
146extern 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.).
151extern 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.
155extern size_t __xray_num_objects();
156
157/// Unpacks the function id from the given packed id.
158extern int32_t __xray_unpack_function_id(int32_t PackedId);
159
160/// Unpacks the object id from the given packed id.
161extern 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.
166extern 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.
174extern void __xray_init();
175
176} // end extern "C"
177
178#endif // XRAY_XRAY_INTERFACE_H
179