From c5b0187af67133194c16bd3018e5a7938ea12f48 Mon Sep 17 00:00:00 2001 From: Dean Michael Berris Date: Thu, 4 May 2017 06:27:51 +0000 Subject: [XRay][compiler-rt][NFC] Update comments to doxygen format; group functions better. git-svn-id: https://llvm.org/svn/llvm-project/compiler-rt/trunk@302121 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/xray/xray_interface.h | 82 ++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 40 deletions(-) (limited to 'include/xray') diff --git a/include/xray/xray_interface.h b/include/xray/xray_interface.h index e2d0a89d6..469bfffe5 100644 --- a/include/xray/xray_interface.h +++ b/include/xray/xray_interface.h @@ -18,7 +18,7 @@ extern "C" { -// Synchronize this with AsmPrinter::SledKind in LLVM. +/// Synchronize this with AsmPrinter::SledKind in LLVM. enum XRayEntryType { ENTRY = 0, EXIT = 1, @@ -26,32 +26,43 @@ enum XRayEntryType { LOG_ARGS_ENTRY = 3, }; -// Provide a function to invoke for when instrumentation points are hit. This is -// a user-visible control surface that overrides the default implementation. The -// function provided should take the following arguments: -// -// - function id: an identifier that indicates the id of a function; this id -// is generated by xray; the mapping between the function id -// and the actual function pointer is available through -// __xray_table. -// - entry type: identifies what kind of instrumentation point was encountered -// (function entry, function exit, etc.). See the enum -// XRayEntryType for more details. -// -// The user handler must handle correctly spurious calls after this handler is -// removed or replaced with another handler, because it would be too costly for -// XRay runtime to avoid spurious calls. -// To prevent circular calling, the handler function itself and all its -// direct&indirect callees must not be instrumented with XRay, which can be -// achieved by marking them all with: __attribute__((xray_never_instrument)) -// -// Returns 1 on success, 0 on error. +/// Provide a function to invoke for when instrumentation points are hit. This +/// is a user-visible control surface that overrides the default implementation. +/// The function provided should take the following arguments: +/// +/// - function id: an identifier that indicates the id of a function; this id +/// is generated by xray; the mapping between the function id +/// and the actual function pointer is available through +/// __xray_table. +/// - entry type: identifies what kind of instrumentation point was +/// encountered (function entry, function exit, etc.). See the +/// enum XRayEntryType for more details. +/// +/// The user handler must handle correctly spurious calls after this handler is +/// removed or replaced with another handler, because it would be too costly for +/// XRay runtime to avoid spurious calls. +/// To prevent circular calling, the handler function itself and all its +/// direct&indirect callees must not be instrumented with XRay, which can be +/// achieved by marking them all with: __attribute__((xray_never_instrument)) +/// +/// Returns 1 on success, 0 on error. extern int __xray_set_handler(void (*entry)(int32_t, XRayEntryType)); -// This removes whatever the currently provided handler is. Returns 1 on -// success, 0 on error. +/// This removes whatever the currently provided handler is. Returns 1 on +/// success, 0 on error. extern int __xray_remove_handler(); +/// Use XRay to log the first argument of each (instrumented) function call. +/// When this function exits, all threads will have observed the effect and +/// start logging their subsequent affected function calls (if patched). +/// +/// Returns 1 on success, 0 on error. +extern int __xray_set_handler_arg1(void (*)(int32_t, XRayEntryType, uint64_t)); + +/// Disables the XRay handler used to log first arguments of function calls. +/// Returns 1 on success, 0 on error. +extern int __xray_remove_handler_arg1(); + enum XRayPatchingStatus { NOT_INITIALIZED = 0, SUCCESS = 1, @@ -59,32 +70,23 @@ enum XRayPatchingStatus { FAILED = 3, }; -// This tells XRay to patch the instrumentation points. See XRayPatchingStatus -// for possible result values. +/// This tells XRay to patch the instrumentation points. See XRayPatchingStatus +/// for possible result values. extern XRayPatchingStatus __xray_patch(); -// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible -// result values. +/// Reverses the effect of __xray_patch(). See XRayPatchingStatus for possible +/// result values. extern XRayPatchingStatus __xray_unpatch(); -// This patches a specific function id. See XRayPatchingStatus for possible -// result values. +/// This patches a specific function id. See XRayPatchingStatus for possible +/// result values. extern XRayPatchingStatus __xray_patch_function(int32_t FuncId); -// This unpatches a specific function id. See XRayPatchingStatus for possible -// result values. +/// This unpatches a specific function id. See XRayPatchingStatus for possible +/// result values. extern XRayPatchingStatus __xray_unpatch_function(int32_t FuncId); -// Use XRay to log the first argument of each (instrumented) function call. -// When this function exits, all threads will have observed the effect and -// start logging their subsequent affected function calls (if patched). -// -// Returns 1 on success, 0 on error. -extern int __xray_set_handler_arg1(void (*)(int32_t, XRayEntryType, uint64_t)); -// Disables the XRay handler used to log first arguments of function calls. -// Returns 1 on success, 0 on error. -extern int __xray_remove_handler_arg1(); } #endif -- cgit v1.2.3