xref: /openbsd-src/gnu/llvm/compiler-rt/include/xray/xray_interface.h (revision 3cab2bb3f667058bece8e38b12449a63a9d73c4b)
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