[v2] manual/probes.texi: Add documentation of setjmp/longjmp probes

Message ID 1391078864-19422-1-git-send-email-will.newton@linaro.org
State Superseded
Headers show

Commit Message

Will Newton Jan. 30, 2014, 10:47 a.m.
Add some documentation of the setjmp, longjmp and longjmp_target
Systemtap probe points.

ChangeLog:

2014-01-28  Will Newton  <will.newton@linaro.org>

	* manual/probes.texi (Internal Probes): Add documentation
	of setjmp and longjmp probes.
---
 manual/probes.texi | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

Changes in v2:
 - Fixes based on review feedback
 - Document the expected behaviour of longjmp and longjmp_target probes

Patch

diff --git a/manual/probes.texi b/manual/probes.texi
index 25d06e5..d7ea58a 100644
--- a/manual/probes.texi
+++ b/manual/probes.texi
@@ -17,6 +17,7 @@  arguments.
 @menu
 * Memory Allocation Probes::  Probes in the memory allocation subsystem
 * Mathematical Function Probes::  Probes in mathematical functions
+* setjmp and longjmp Probes::  Probes in setjmp and longjmp
 @end menu
 
 @node Memory Allocation Probes
@@ -368,3 +369,42 @@  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 setjmp and longjmp Probes
+@section setjmp and longjmp Probes
+
+These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp}
+or @code{longjmp}.
+
+@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
+This probe is hit 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 hit whenever @code{longjmp} is called. Argument @var{$arg1}
+is a pointer to the @code{jmp_buf} passed as the first argument of
+@code{longjmp}, @var{$arg2} is the return value passed as the second
+argument of @code{longjmp} and @var{$arg3} is a pointer to the return
+address @code{longjmp} will return to.
+
+The longjmp probe is hit 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}.
+@end deftp
+
+@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
+This probe is hit whenever @code{longjmp} is called. Argument @var{$arg1}
+is a pointer to the @code{jmp_buf} passed as the first argument of
+@code{longjmp}, @var{$arg2} is the return value passed as the second
+argument of @code{longjmp} and @var{$arg3} is a pointer to the return
+address @code{longjmp} will return to.
+
+The longjmp_target probe is hit 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