diff options
Diffstat (limited to 'REORG.TODO/manual/probes.texi')
| -rw-r--r-- | REORG.TODO/manual/probes.texi | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/REORG.TODO/manual/probes.texi b/REORG.TODO/manual/probes.texi new file mode 100644 index 0000000000..eb91c62703 --- /dev/null +++ b/REORG.TODO/manual/probes.texi @@ -0,0 +1,416 @@ +@node Internal Probes +@c @node Internal Probes, Tunables, POSIX Threads, Top +@c %MENU% Probes to monitor libc internal behavior +@chapter Internal probes + +In order to aid in debugging and monitoring internal behavior, +@theglibc{} exposes nearly-zero-overhead SystemTap probes marked with +the @code{libc} provider. + +These probes are not part of the @glibcadj{} stable ABI, and they are +subject to change or removal across releases. Our only promise with +regard to them is that, if we find a need to remove or modify the +arguments of a probe, the modified probe will have a different name, so +that program monitors relying on the old probe will not get unexpected +arguments. + +@menu +* Memory Allocation Probes:: Probes in the memory allocation subsystem +* Mathematical Function Probes:: Probes in mathematical functions +* Non-local Goto Probes:: Probes in setjmp and longjmp +@end menu + +@node Memory Allocation Probes +@section Memory Allocation Probes + +These probes are designed to signal relatively unusual situations within +the virtual memory subsystem of @theglibc{}. + +@deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after the main arena is extended by calling +@code{sbrk}. Argument @var{$arg1} is the additional size requested to +@code{sbrk}, and @var{$arg2} is the pointer that marks the end of the +@code{sbrk} area, returned in response to the request. +@end deftp + +@deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after the size of the main arena is decreased by +calling @code{sbrk}. Argument @var{$arg1} is the size released by +@code{sbrk} (the positive value, rather than the negative value passed +to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of +the @code{sbrk} area, returned in response to the request. +@end deftp + +@deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a new heap is @code{mmap}ed. Argument +@var{$arg1} is a pointer to the base of the memory area, where the +@code{heap_info} data structure is held, and @var{$arg2} is the size of +the heap. +@end deftp + +@deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered @emph{before} (unlike the other sbrk and heap +probes) a heap is completely removed via @code{munmap}. Argument +@var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the +heap. +@end deftp + +@deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a trailing portion of an @code{mmap}ed +heap is extended. Argument @var{$arg1} is a pointer to the heap, and +@var{$arg2} is the new size of the heap. +@end deftp + +@deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a trailing portion of an @code{mmap}ed +heap is released. Argument @var{$arg1} is a pointer to the heap, and +@var{$arg2} is the new size of the heap. +@end deftp + +@deftp Probe memory_malloc_retry (size_t @var{$arg1}) +@deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2}) +@deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2}) +@deftpx Probe memory_calloc_retry (size_t @var{$arg1}) +These probes are triggered when the corresponding functions fail to +obtain the requested amount of memory from the arena in use, before they +call @code{arena_get_retry} to select an alternate arena in which to +retry the allocation. Argument @var{$arg1} is the amount of memory +requested by the user; in the @code{calloc} case, that is the total size +computed from both function arguments. In the @code{realloc} case, +@var{$arg2} is the pointer to the memory area being resized. In the +@code{memalign} case, @var{$arg2} is the alignment to be used for the +request, which may be stricter than the value passed to the +@code{memalign} function. A @code{memalign} probe is also used by functions +@code{posix_memalign, valloc} and @code{pvalloc}. + +Note that the argument order does @emph{not} match that of the +corresponding two-argument functions, so that in all of these probes the +user-requested allocation size is in @var{$arg1}. +@end deftp + +@deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2}) +This probe is triggered within @code{arena_get_retry} (the function +called to select the alternate arena in which to retry an allocation +that failed on the first attempt), before the selection of an alternate +arena. This probe is redundant, but much easier to use when it's not +important to determine which of the various memory allocation functions +is failing to allocate on the first try. Argument @var{$arg1} is the +same as in the function-specific probes, except for extra room for +padding introduced by functions that have to ensure stricter alignment. +Argument @var{$arg2} is the arena in which allocation failed. +@end deftp + +@deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered when @code{malloc} allocates and initializes an +additional arena (not the main arena), but before the arena is assigned +to the running thread or inserted into the internal linked list of +arenas. The arena's @code{malloc_state} internal data structure is +located at @var{$arg1}, within a newly-allocated heap big enough to hold +at least @var{$arg2} bytes. +@end deftp + +@deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2}) +This probe is triggered when @code{malloc} has just selected an existing +arena to reuse, and (temporarily) reserved it for exclusive use. +Argument @var{$arg1} is a pointer to the newly-selected arena, and +@var{$arg2} is a pointer to the arena previously used by that thread. + +This occurs within +@code{reused_arena}, right after the mutex mentioned in probe +@code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will +point to the same arena. In this configuration, this will usually only +occur once per thread. The exception is when a thread first selected +the main arena, but a subsequent allocation from it fails: then, and +only then, may we switch to another arena to retry that allocation, and +for further allocations within that thread. +@end deftp + +@deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3}) +This probe is triggered when @code{malloc} is about to wait for an arena +to become available for reuse. Argument @var{$arg1} holds a pointer to +the mutex the thread is going to wait on, @var{$arg2} is a pointer to a +newly-chosen arena to be reused, and @var{$arg3} is a pointer to the +arena previously used by that thread. + +This occurs within +@code{reused_arena}, when a thread first tries to allocate memory or +needs a retry after a failure to allocate from the main arena, there +isn't any free arena, the maximum number of arenas has been reached, and +an existing arena was chosen for reuse, but its mutex could not be +immediately acquired. The mutex in @var{$arg1} is the mutex of the +selected arena. +@end deftp + +@deftp Probe memory_arena_reuse_free_list (void *@var{$arg1}) +This probe is triggered when @code{malloc} has chosen an arena that is +in the free list for use by a thread, within the @code{get_free_list} +function. The argument @var{$arg1} holds a pointer to the selected arena. +@end deftp + +@deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2}) +This probe is triggered when function @code{mallopt} is called to change +@code{malloc} internal configuration parameters, before any change to +the parameters is made. The arguments @var{$arg1} and @var{$arg2} are +the ones passed to the @code{mallopt} function. +@end deftp + +@deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MXFAST}, and the requested +value is in an acceptable range. Argument @var{$arg1} is the requested +value, and @var{$arg2} is the previous value of this @code{malloc} +parameter. +@end deftp + +@deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_TRIM_THRESHOLD}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_TOP_PAD}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, @var{$arg2} is the previous value of this @code{malloc} +parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment +was already disabled. +@end deftp + +@deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MMAP_MAX}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_CHECK_ACTION}. Argument +@var{$arg1} is the requested value, and @var{$arg2} is the previous +value of this @code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_PERTURB}. Argument +@var{$arg1} is the requested value, and @var{$arg2} is the previous +value of this @code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_ARENA_TEST}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, and @var{$arg2} is the previous value of this +@code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_ARENA_MAX}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, and @var{$arg2} is the previous value of this +@code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2}) +This probe is triggered when function @code{free} decides to adjust the +dynamic brk/mmap thresholds. Argument @var{$arg1} and @var{$arg2} are +the adjusted mmap and trim thresholds, respectively. +@end deftp + +@node Mathematical Function Probes +@section Mathematical Function Probes + +Some mathematical functions fall back to multiple precision arithmetic for +some inputs to get last bit precision for their return values. This multiple +precision fallback is much slower than the default algorithms and may have a +significant impact on application performance. The systemtap probe markers +described in this section may help you determine if your application calls +mathematical functions with inputs that may result in multiple-precision +arithmetic. + +Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of +precision in the mantissa of the multiple precision number. Hence, a precision +level of 32 implies 768 bits of precision in the mantissa. + +@deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{exp} function is called with an +input that results in multiple precision computation with precision +6. Argument @var{$arg1} is the input value and @var{$arg2} is the +computed output. +@end deftp + +@deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{exp} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input value and @var{$arg2} is the +computed output. +@end deftp + +@deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is triggered when the @code{pow} function is called with +inputs that result in multiple precision computation with precision +10. Arguments @var{$arg1} and @var{$arg2} are the input values, +@code{$arg3} is the value computed in the fast phase of the algorithm +and @code{$arg4} is the final accurate value. +@end deftp + +@deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is triggered when the @code{pow} function is called with an +input that results in multiple precision computation with precision +32. Arguments @var{$arg1} and @var{$arg2} are the input values, +@code{$arg3} is the value computed in the fast phase of the algorithm +and @code{$arg4} is the final accurate value. +@end deftp + +@deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{log} function is called with an +input that results in multiple precision computation. Argument +@var{$arg1} is the precision with which the computation succeeded. +Argument @var{$arg2} is the input and @var{$arg3} is the computed +output. +@end deftp + +@deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{log} function is called with an +input that results in multiple precision computation and none of the +multiple precision computations result in an accurate result. +Argument @var{$arg1} is the maximum precision with which computations +were performed. Argument @var{$arg2} is the input and @var{$arg3} is +the computed output. +@end deftp + +@deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is triggered when the @code{atan2} function is called with +an input that results in multiple precision computation. Argument +@var{$arg1} is the precision with which computation succeeded. +Arguments @var{$arg2} and @var{$arg3} are inputs to the @code{atan2} +function and @var{$arg4} is the computed result. +@end deftp + +@deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is triggered when the @code{atan} function is called with +an input that results in multiple precision computation and none of +the multiple precision computations result in an accurate result. +Argument @var{$arg1} is the maximum precision with which computations +were performed. Arguments @var{$arg2} and @var{$arg3} are inputs to +the @code{atan2} function and @var{$arg4} is the computed result. +@end deftp + +@deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{atan} function is called with +an input that results in multiple precision computation. Argument +@var{$arg1} is the precision with which computation succeeded. +Argument @var{$arg2} is the input to the @code{atan} function and +@var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{atan} function is called with +an input that results in multiple precision computation and none of +the multiple precision computations result in an accurate result. +Argument @var{$arg1} is the maximum precision with which computations +were performed. Argument @var{$arg2} is the input to the @code{atan} +function and @var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowtan (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{tan} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function and @var{$arg2} +is the computed result. +@end deftp + +@deftp Probe slowasin (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{asin} function is called with +an input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function and @var{$arg2} +is the computed result. +@end deftp + +@deftp Probe slowacos (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{acos} function is called with +an input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function and @var{$arg2} +is the computed result. +@end deftp + +@deftp Probe slowsin (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{sin} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function and @var{$arg2} +is the computed result. +@end deftp + +@deftp Probe slowcos (double @var{$arg1}, double @var{$arg2}) +This probe is triggered when the @code{cos} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function and @var{$arg2} +is the computed result. +@end deftp + +@deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{sin} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function, @var{$arg2} is +the error bound of @var{$arg1} and @var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is triggered when the @code{cos} function is called with an +input that results in multiple precision computation with precision +32. Argument @var{$arg1} is the input to the function, @var{$arg2} is +the error bound of @var{$arg1} and @var{$arg3} is the computed result. +@end deftp + +@node Non-local Goto Probes +@section Non-local Goto Probes + +These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp}, +@code{longjmp} or @code{siglongjmp}. + +@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is +called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} +passed as the first argument of @code{setjmp} or @code{sigsetjmp}, +@var{$arg2} is the second argument of @code{sigsetjmp} or zero if this +is a call to @code{setjmp} and @var{$arg3} is a pointer to the return +address that will be stored in the @code{jmp_buf}. +@end deftp + +@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered whenever @code{longjmp} or @code{siglongjmp} +is called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} +passed as the first argument of @code{longjmp} or @code{siglongjmp}, +@var{$arg2} is the return value passed as the second argument of +@code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to +the return address @code{longjmp} or @code{siglongjmp} will return to. + +The @code{longjmp} probe is triggered at a point where the registers +have not yet been restored to the values in the @code{jmp_buf} and +unwinding will show a call stack including the caller of +@code{longjmp} or @code{siglongjmp}. +@end deftp + +@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered under the same conditions and with the same +arguments as the @code{longjmp} probe. + +The @code{longjmp_target} probe is triggered at a point where the +registers have been restored to the values in the @code{jmp_buf} and +unwinding will show a call stack including the caller of @code{setjmp} +or @code{sigsetjmp}. +@end deftp |