1 //===-- xray_interface.h ----------------------------------------*- C++ -*-===//
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 dynamic runtime instrumentation system.
12 // APIs for controlling XRay functionality explicitly.
13 //===----------------------------------------------------------------------===//
14 #ifndef XRAY_XRAY_INTERFACE_H
15 #define XRAY_XRAY_INTERFACE_H
21 enum XRayEntryType { ENTRY = 0, EXIT = 1, TAIL = 2 };
23 // Provide a function to invoke for when instrumentation points are hit. This is
24 // a user-visible control surface that overrides the default implementation. The
25 // function provided should take the following arguments:
27 // - function id: an identifier that indicates the id of a function; this id
28 // is generated by xray; the mapping between the function id
29 // and the actual function pointer is available through
31 // - entry type: identifies what kind of instrumentation point was encountered
32 // (function entry, function exit, etc.). See the enum
33 // XRayEntryType for more details.
35 // The user handler must handle correctly spurious calls after this handler is
36 // removed or replaced with another handler, because it would be too costly for
37 // XRay runtime to avoid spurious calls.
38 // To prevent circular calling, the handler function itself and all its
39 // direct&indirect callees must not be instrumented with XRay, which can be
40 // achieved by marking them all with: __attribute__((xray_never_instrument))
42 // Returns 1 on success, 0 on error.
43 extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType));
45 // This removes whatever the currently provided handler is. Returns 1 on
46 // success, 0 on error.
47 extern int __xray_remove_handler();
49 enum XRayPatchingStatus {
56 // This tells XRay to patch the instrumentation points. See XRayPatchingStatus
57 // for possible result values.
58 extern XRayPatchingStatus __xray_patch();
60 // Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible
62 extern XRayPatchingStatus __xray_unpatch();