From e7b5068cc22f1a5707a9fd0310234b8d7300f227 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Sat, 8 Sep 2018 13:25:34 -0600 Subject: [PATCH] Update Python unwinder documentation 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 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. --- gdb/doc/ChangeLog | 7 +++++++ gdb/doc/python.texi | 55 ++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 53 insertions(+), 9 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 705028a..0baaf93 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,5 +1,12 @@ 2018-09-10 Tom Tromey + 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 + PR python/18909: * python.texi (Events In Python): Fix inferior_call documentation. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 47691c4..ccad593 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -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 by far. The other cases are documented +for completeness but are only useful in specialized situations. -This is the most common case. +@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 -- 2.7.4