OpenE2K/binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update Python unwinder documentation

Browse Source 
PR python/19808 points out a few issues in the Python unwinder
documentation.  This patch update the documentation for
create_unwind_info and read_register to address the issues noted, and
adds a cautionary note about writing an unwinder.

gdb/doc/ChangeLog
2018-09-10  Tom Tromey  <tom@tromey.com>

	PR python/19808:
	* python.texi (Unwinding Frames in Python): Rewrite
	create_unwind_info documentation.  Update read_register
	documentation and add a note about unwinder caution.
This commit is contained in:
Tom Tromey 2018-09-08 13:25:34 -06:00
parent fb5af5e335
commit e7b5068cc2
2 changed files with 53 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
gdb/doc/ChangeLog
View File

@ -1,3 +1,10 @@
2018-09-10 Tom Tromey <tom@tromey.com>
PR python/19808:
* python.texi (Unwinding Frames in Python): Rewrite
create_unwind_info documentation. Update read_register
documentation and add a note about unwinder caution.
2018-09-10 Tom Tromey <tom@tromey.com>
PR python/18909:

55
gdb/doc/python.texi
View File

@ -2290,17 +2290,40 @@ return @code{None}. The code in @value{GDBN} that enables writing
unwinders in Python uses this object to return frame's ID and previous
frame registers when @value{GDBN} core asks for them.
An unwinder should do as little work as possible. Some otherwise
innocuous operations can cause problems (even crashes, as this code is
not not well-hardened yet). For example, making an inferior call from
an unwinder is unadvisable, as an inferior call will reset
@value{GDBN}'s stack unwinding process, potentially causing re-entrant
unwinding.
@subheading Unwinder Input
An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
provides a method to read frame's registers:
@defun PendingFrame.read_register (reg)
This method returns the contents of the register @var{regn} in the
This method returns the contents of the register @var{reg} in the
frame as a @code{gdb.Value} object. @var{reg} can be either a
register number or a register name; the values are platform-specific.
They are usually found in the corresponding
@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If
@var{reg} does not name a register for the current architecture, this
method will throw an exception.
Note that this method will always return a @code{gdb.Value} for a
valid register name. This does not mean that the value will be valid.
For example, you may request a register that an earlier unwinder could
not unwind---the value will be unavailable. Instead, the
@code{gdb.Value} returned from this method will be lazy; that is, its
underlying bits will not be fetched until it is first used. So,
attempting to use such a value will cause an exception at the point of
use.
The type of the returned @code{gdb.Value} depends on the register and
the architecture. It is common for registers to have a scalar type,
like @code{long long}; but many other types are possible, such as
pointer, pointer-to-function, floating point or vector types.
@end defun
It also provides a factory method to create a @code{gdb.UnwindInfo}
@ -2313,18 +2336,32 @@ using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes
determine which function will be used, as follows:
@table @code
@item sp, pc, special
@code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
@item sp, pc
@code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
The frame is identified by the given stack address and PC. The stack
address must be chosen so that it is constant throughout the lifetime
of the frame, so a typical choice is the value of the stack pointer at
the start of the function---in the DWARF standard, this would be the
``Call Frame Address''.
This is the most common case.
This is the most common case by far. The other cases are documented
for completeness but are only useful in specialized situations.
@item sp, pc, special
The frame is identified by the stack address, the PC, and a
``special'' address. The special address is used on architectures
that can have frames that do not change the stack, but which are still
distinct, for example the IA-64, which has a second stack for
registers. Both @var{sp} and @var{special} must be constant
throughout the lifetime of the frame.
@item sp
@code{frame_id_build_wild (@var{frame_id}.sp)}
The frame is identified by the stack address only. Any other stack
frame with a matching @var{sp} will be considered to match this frame.
Inside gdb, this is called a ``wild frame''. You will never need
this.
@end table
The attribute values should be @code{gdb.Value}
Each attribute value should be an instance of @code{gdb.Value}.
@end defun