diff mbox

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

Message ID 1390919614-30727-2-git-send-email-will.newton@linaro.org
State Superseded
Headers show

Commit Message

Will Newton Jan. 28, 2014, 2:33 p.m. UTC 
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 | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

Comments

Will Newton Jan. 28, 2014, 8:27 p.m. UTC | #1 
On 28 January 2014 16:40, Siddhesh Poyarekar <siddhesh@redhat.com> wrote:
> On Tue, Jan 28, 2014 at 02:33:34PM +0000, Will Newton wrote:
>> +These probes can be used to notify the debugger of a call to @code{setjmp},
>> +@code{sigsetjmp} or @code{longjmp}.
>> +
>
> Suggest: These probes are used to signal calls to setjmp, sigsetjmp or
> longjmp.
>
> i.e., avoid mentioning that they're for the debugger, since their
> usage is not limited to gdb.  Likewise for the gdb mention in the last
> line.

Thanks for the suggestions, will fix.

>> +@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.
>> +@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.
>> +
>> +This probe is implemented on some architectures. It is not clear how it
>> +differs from the @code{longjmp} probe and it is not used by gdb.
>> +@end deftp
>
> The AFAIU, the longjmp probe marks the entry point of the longjmp
> call, while longjmp_target is hit after unwinding and just before
> jumping to the target.  One might want separate notifications of
> having hit longjmp and then having successfully unwound and jumped to
> the target.

Yeah, I figured that out not long after I sent the patch. Not sure how
I missed it in the SystemTap testsuite.

I'll send an updated patch.
diff mbox

Patch

diff --git a/manual/probes.texi b/manual/probes.texi
index 25d06e5..f825850 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,37 @@  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 can be used to notify the debugger of a call 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.
+@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.
+
+This probe is implemented on some architectures. It is not clear how it
+differs from the @code{longjmp} probe and it is not used by gdb.
+@end deftp