| Message ID | 20131110162819.GA6525@intel.com |
|---|---|
| State | New |
| Headers | show |
On Nov 10, 2013, at 8:28 AM, H.J. Lu <hongjiu.lu@intel.com> wrote: > This patch documents __builtin_setjmp and __builtin_longjmp. OK to > install? I like it. I think these two should be documented.
On Sun, 10 Nov 2013, H.J. Lu wrote: > +@code{__builtin_setjmp} and @code{__builtin_longjmp} may not be used > +in the same function with the same @code{setjmp} buffer. Are there any other restrictions? Do they, for example, guarantee to restore all call-saved registers to their values at the time of the __builtin_longjmp call, including those for which libc's setjmp and longjmp need to test for existence at runtime (but they may have been used in an intermediate stack frame, even if not enabled in either the setjmp or longjmp frames)? Either you need to document all the semantics so as to make clear to users exactly when they can use these functions safely, or you need to state that there are undocumented restrictions that may change from GCC version to GCC version and that these functions are only intended for internal use as part of GCC's exception handling implementation.
> Are there any other restrictions? Do they, for example, guarantee to > restore all call-saved registers to their values at the time of the > __builtin_longjmp call, including those for which libc's setjmp and > longjmp need to test for existence at runtime (but they may have been used > in an intermediate stack frame, even if not enabled in either the setjmp > or longjmp frames)? __builtin_longjmp/__builtin_setjmp don't save or restore anything themselves. They cause the compiler to generate code that saves and restores registers live across the non-local goto paths, but of course only registers known to the compiler and known to be used in the code. > Either you need to document all the semantics so as to make clear to users > exactly when they can use these functions safely, or you need to state > that there are undocumented restrictions that may change from GCC version > to GCC version and that these functions are only intended for internal use > as part of GCC's exception handling implementation. The restrictions have probably not changed since the builtins were invented.
On Nov 15, 2013, at 4:32 AM, Eric Botcazou <ebotcazou@adacore.com> wrote: >> Either you need to document all the semantics so as to make clear to users >> exactly when they can use these functions safely, or you need to state >> that there are undocumented restrictions that may change from GCC version >> to GCC version and that these functions are only intended for internal use >> as part of GCC's exception handling implementation. > > The restrictions have probably not changed since the builtins were invented. :-) Yeah, don't think I've seen too much change swirling around these two.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 0d72819..44b7c59 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -27,6 +27,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Local Labels:: Labels local to a block. * Labels as Values:: Getting pointers to labels, and computed gotos. * Nested Functions:: As in Algol and Pascal, lexical scoping of functions. +* Nonlocal Gotos:: Nonlocal gotos * Constructing Calls:: Dispatching a call to another function. * Typeof:: @code{typeof}: referring to the type of an expression. * Conditionals:: Omitting the middle operand of a @samp{?:} expression. @@ -518,6 +519,36 @@ bar (int *array, int offset, int size) @} @end smallexample +@node Nonlocal Gotos +@section Nonlocal Gotos +@cindex nonlocal gotos + +GCC provides builtin functions @code{__builtin_setjmp} and +@code{__builtin_longjmp} which operate similarly to the C library +functions of the same name, but are more efficient. + +@deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf}) +This function saves the current stack context in @code{setjmp} buffer, +@var{buf}. @code{__builtin_setjmp} returns 0 when returning directly, +and @var{1} when returning from @code{__builtin_longjmp} using the same +@code{setjmp} buffer. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val}) +This function restores the stack context in @code{setjmp} buffer, +@var{buf}, saved by the last call of @code{__builtin_setjmp}. After +@code{__builtin_longjmp} is finished, program resumes execution as +if the last @code{__builtin_setjmp} just returns the value @var{val}, +which must be @var{1}. +@end deftypefn + +The @code{setjmp} buffer is an array of five @code{intptr_t}. The buffer +will generally contain the frame address, the resume address and the stack +address. The other elements may be used in a machine-specific way. + +@code{__builtin_setjmp} and @code{__builtin_longjmp} may not be used +in the same function with the same @code{setjmp} buffer. + @node Constructing Calls @section Constructing Function Calls @cindex constructing calls