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  <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.

1 files changed, 46 insertions, 9 deletions

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