1//===- xray_interface.h -----------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file is a part of XRay, a dynamic runtime instrumentation system.
11//
12// APIs for controlling XRay functionality explicitly.
13//===----------------------------------------------------------------------===//
14
15#ifndef XRAY_XRAY_INTERFACE_H
16#define XRAY_XRAY_INTERFACE_H
17
18#include <cstddef>
19#include <cstdint>
20
21extern "C" {
22
23/// Synchronize this with AsmPrinter::SledKind in LLVM.
24enum XRayEntryType {
25  ENTRY = 0,
26  EXIT = 1,
27  TAIL = 2,
28  LOG_ARGS_ENTRY = 3,
29  CUSTOM_EVENT = 4,
30  TYPED_EVENT = 5,
31};
32
33/// Provide a function to invoke for when instrumentation points are hit. This
34/// is a user-visible control surface that overrides the default implementation.
35/// The function provided should take the following arguments:
36///
37///   - function id: an identifier that indicates the id of a function; this id
38///                  is generated by xray; the mapping between the function id
39///                  and the actual function pointer is available through
40///                  __xray_table.
41///   - entry type: identifies what kind of instrumentation point was
42///                 encountered (function entry, function exit, etc.). See the
43///                 enum XRayEntryType for more details.
44///
45/// The user handler must handle correctly spurious calls after this handler is
46/// removed or replaced with another handler, because it would be too costly for
47/// XRay runtime to avoid spurious calls.
48/// To prevent circular calling, the handler function itself and all its
49/// direct&indirect callees must not be instrumented with XRay, which can be
50/// achieved by marking them all with: __attribute__((xray_never_instrument))
51///
52/// Returns 1 on success, 0 on error.
53extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType));
54
55/// This removes whatever the currently provided handler is. Returns 1 on
56/// success, 0 on error.
57extern int __xray_remove_handler();
58
59/// Use XRay to log the first argument of each (instrumented) function call.
60/// When this function exits, all threads will have observed the effect and
61/// start logging their subsequent affected function calls (if patched).
62///
63/// Returns 1 on success, 0 on error.
64extern int __xray_set_handler_arg1(void (*entry)(int32_t, XRayEntryType,
65                                                 uint64_t));
66
67/// Disables the XRay handler used to log first arguments of function calls.
68/// Returns 1 on success, 0 on error.
69extern int __xray_remove_handler_arg1();
70
71/// Provide a function to invoke when XRay encounters a custom event.
72extern int __xray_set_customevent_handler(void (*entry)(void *, std::size_t));
73
74/// This removes whatever the currently provided custom event handler is.
75/// Returns 1 on success, 0 on error.
76extern int __xray_remove_customevent_handler();
77
78/// Set a handler for xray typed event logging. The first parameter is a type
79/// identifier, the second is a payload, and the third is the payload size.
80extern int __xray_set_typedevent_handler(void (*entry)(uint16_t, const void *,
81                                                       std::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