1 //===-- xray_log_interface.h ----------------------------------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file is a part of XRay, a function call tracing system.
12 // APIs for installing a new logging implementation.
14 //===----------------------------------------------------------------------===//
16 /// XRay allows users to implement their own logging handlers and install them
17 /// to replace the default runtime-controllable implementation that comes with
18 /// compiler-rt/xray. The "flight data recorder" (FDR) mode implementation uses
19 /// this API to install itself in an XRay-enabled binary. See
20 /// compiler-rt/lib/xray_fdr_logging.{h,cc} for details of that implementation.
22 /// The high-level usage pattern for these APIs look like the following:
24 /// // Before we try initializing the log implementation, we must set it as
25 /// // the log implementation. We provide the function pointers that define
26 /// // the various initialization, finalization, and other pluggable hooks
28 /// __xray_set_log_impl({...});
30 /// // Once that's done, we can now initialize the implementation. Each
31 /// // implementation has a chance to let users customize the implementation
32 /// // with a struct that their implementation supports. Roughly this might
34 /// MyImplementationOptions opts;
35 /// opts.enable_feature = true;
37 /// auto init_status = __xray_log_init(
38 /// BufferSize, MaxBuffers, &opts, sizeof opts);
39 /// if (init_status != XRayLogInitStatus::XRAY_LOG_INITIALIZED) {
40 /// // deal with the error here, if there is one.
43 /// // When the log implementation has had the chance to initialize, we can
44 /// // now patch the sleds.
45 /// auto patch_status = __xray_patch();
46 /// if (patch_status != XRayPatchingStatus::SUCCESS) {
47 /// // deal with the error here, if it is an error.
50 /// // If we want to stop the implementation, we can then finalize it (before
51 /// // optionally flushing the log).
52 /// auto fin_status = __xray_log_finalize();
53 /// if (fin_status != XRayLogInitStatus::XRAY_LOG_FINALIZED) {
54 /// // deal with the error here, if it is an error.
57 /// // We can optionally wait before flushing the log to give other threads a
58 /// // chance to see that the implementation is already finalized. Also, at
59 /// // this point we can optionally unpatch the sleds to reduce overheads at
61 /// auto unpatch_status = __xray_unpatch();
62 /// if (unpatch_status != XRayPatchingStatus::SUCCESS) {
63 // // deal with the error here, if it is an error.
66 /// // If there are logs or data to be flushed somewhere, we can do so only
67 /// // after we've finalized the log. Some implementations may not actually
68 /// // have anything to log (it might keep the data in memory, or periodically
69 /// // be logging the data anyway).
70 /// auto flush_status = __xray_log_flushLog();
71 /// if (flush_status != XRayLogFlushStatus::XRAY_LOG_FLUSHED) {
72 /// // deal with the error here, if it is an error.
76 /// NOTE: Before calling __xray_patch() again, consider re-initializing the
77 /// implementation first. Some implementations might stay in an "off" state when
78 /// they are finalized, while some might be in an invalid/unknown state.
80 #ifndef XRAY_XRAY_LOG_INTERFACE_H
81 #define XRAY_XRAY_LOG_INTERFACE_H
83 #include "xray/xray_interface.h"
88 /// This enum defines the valid states in which the logging implementation can
90 enum XRayLogInitStatus {
91 /// The default state is uninitialized, and in case there were errors in the
92 /// initialization, the implementation MUST return XRAY_LOG_UNINITIALIZED.
93 XRAY_LOG_UNINITIALIZED = 0,
95 /// Some implementations support multi-stage init (or asynchronous init), and
96 /// may return XRAY_LOG_INITIALIZING to signal callers of the API that
97 /// there's an ongoing initialization routine running. This allows
98 /// implementations to support concurrent threads attempting to initialize,
99 /// while only signalling success in one.
100 XRAY_LOG_INITIALIZING = 1,
102 /// When an implementation is done initializing, it MUST return
103 /// XRAY_LOG_INITIALIZED. When users call `__xray_patch()`, they are
104 /// guaranteed that the implementation installed with
105 /// `__xray_set_log_impl(...)` has been initialized.
106 XRAY_LOG_INITIALIZED = 2,
108 /// Some implementations might support multi-stage finalization (or
109 /// asynchronous finalization), and may return XRAY_LOG_FINALIZING to signal
110 /// callers of the API that there's an ongoing finalization routine running.
111 /// This allows implementations to support concurrent threads attempting to
112 /// finalize, while only signalling success/completion in one.
113 XRAY_LOG_FINALIZING = 3,
115 /// When an implementation is done finalizing, it MUST return
116 /// XRAY_LOG_FINALIZED. It is up to the implementation to determine what the
117 /// semantics of a finalized implementation is. Some implementations might
118 /// allow re-initialization once the log is finalized, while some might always
119 /// be on (and that finalization is a no-op).
120 XRAY_LOG_FINALIZED = 4,
123 /// This enum allows an implementation to signal log flushing operations via
124 /// `__xray_log_flushLog()`, and the state of flushing the log.
125 enum XRayLogFlushStatus {
126 XRAY_LOG_NOT_FLUSHING = 0,
127 XRAY_LOG_FLUSHING = 1,
128 XRAY_LOG_FLUSHED = 2,
131 /// A valid XRay logging implementation MUST provide all of the function
132 /// pointers in XRayLogImpl when being installed through `__xray_set_log_impl`.
133 /// To be precise, ALL the functions pointers MUST NOT be nullptr.
135 /// The log initialization routine provided by the implementation, always
136 /// provided with the following parameters:
139 /// - maximum number of buffers
140 /// - a pointer to an argument struct that the implementation MUST handle
141 /// - the size of the argument struct
143 /// See XRayLogInitStatus for details on what the implementation MUST return
146 /// If the implementation needs to install handlers aside from the 0-argument
147 /// function call handler, it MUST do so in this initialization handler.
149 /// See xray_interface.h for available handler installation routines.
150 XRayLogInitStatus (*log_init)(size_t, size_t, void *, size_t);
152 /// The log finalization routine provided by the implementation.
154 /// See XRayLogInitStatus for details on what the implementation MUST return
156 XRayLogInitStatus (*log_finalize)();
158 /// The 0-argument function call handler. XRay logging implementations MUST
159 /// always have a handler for function entry and exit events. In case the
160 /// implementation wants to support arg1 (or other future extensions to XRay
161 /// logging) those MUST be installed by the installed 'log_init' handler.
162 void (*handle_arg0)(int32_t, XRayEntryType);
164 /// The log implementation provided routine for when __xray_log_flushLog() is
167 /// See XRayLogFlushStatus for details on what the implementation MUST return
169 XRayLogFlushStatus (*flush_log)();
172 /// This function installs a new logging implementation that XRay will use. In
173 /// case there are any nullptr members in Impl, XRay will *uninstall any
174 /// existing implementations*. It does NOT patch the instrumentation sleds.
176 /// NOTE: This function does NOT attempt to finalize the currently installed
177 /// implementation. Use with caution.
179 /// It is guaranteed safe to call this function in the following states:
181 /// - When the implementation is UNINITIALIZED.
182 /// - When the implementation is FINALIZED.
183 /// - When there is no current implementation installed.
185 /// It is logging implementation defined what happens when this function is
186 /// called while in any other states.
187 void __xray_set_log_impl(XRayLogImpl Impl);
189 /// This function removes the currently installed implementation. It will also
190 /// uninstall any handlers that have been previously installed. It does NOT
191 /// unpatch the instrumentation sleds.
193 /// NOTE: This function does NOT attempt to finalize the currently installed
194 /// implementation. Use with caution.
196 /// It is guaranteed safe to call this function in the following states:
198 /// - When the implementation is UNINITIALIZED.
199 /// - When the implementation is FINALIZED.
200 /// - When there is no current implementation installed.
202 /// It is logging implementation defined what happens when this function is
203 /// called while in any other states.
204 void __xray_remove_log_impl();
206 /// Invokes the installed implementation initialization routine. See
207 /// XRayLogInitStatus for what the return values mean.
208 XRayLogInitStatus __xray_log_init(size_t BufferSize, size_t MaxBuffers,
209 void *Args, size_t ArgsSize);
211 /// Invokes the installed implementation finalization routine. See
212 /// XRayLogInitStatus for what the return values mean.
213 XRayLogInitStatus __xray_log_finalize();
215 /// Invokes the install implementation log flushing routine. See
216 /// XRayLogFlushStatus for what the return values mean.
217 XRayLogFlushStatus __xray_log_flushLog();
223 // Options used by the LLVM XRay FDR implementation.
224 struct FDRLoggingOptions {
225 bool ReportErrors = false;
229 } // namespace __xray
231 #endif // XRAY_XRAY_LOG_INTERFACE_H