2006-01-24 Jim Blandy <jimb@redhat.com>

	* gdbint.texinfo (Frames): Document the basics of GDB's register
	unwinding model, and explain the existence of the "sentinel" frame.

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index c0400466d2dabf686cf03308735d98e1410a6061..531972d0eaa64c4f9ee81a9916706e147235349c 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2006-01-24  Jim Blandy  <jimb@redhat.com>
+
+       * gdbint.texinfo (Frames): Document the basics of GDB's register
+       unwinding model, and explain the existence of the "sentinel" frame.
+
 2006-01-23  Andrew Stubbs  <andrew.stubbs@st.com>
 
        * gdb.texinfo (Choosing files): Mention that -directory is used

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index f7d7936fe3783d1c6cc84df0f41640c16b91789a..a81cc9b9a4bc5adba9b919d0a277b9c77bd64be9 100644 (file)
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -231,6 +231,36 @@ they use.
 A frame is a construct that @value{GDBN} uses to keep track of calling
 and called functions.
 
+@cindex frame, unwind
+@value{GDBN}'s current frame model is the result of an incremental
+cleanup of working code, not a fresh design, so it's a little weird.
+
+The natural model would have a frame object, with methods that read
+and write that frame's registers.  Reading or writing the youngest
+frame's registers would simply read or write the processor's current
+registers, since the youngest frame is running directly on the
+processor.  Older frames might have some registers saved on the stack
+by younger frames, so accessing the older frames' registers would do a
+mix of memory accesses and register accesses, as appropriate.
+
+@findex frame_register_unwind
+Instead, @value{GDBN}'s model is that you find a frame's registers by
+``unwinding'' them from the next younger frame.  That is, to access
+the registers of frame #1 (the next-to-youngest frame), you actually
+apply @code{frame_register_unwind} to frame #0 (the youngest frame).
+But then the obvious question is: how do you access the registers of
+the youngest frame itself?  How do you ``unwind'' them when they're
+not wound up?
+
+@cindex sentinel frame
+@findex get_frame_type
+@vindex SENTINEL_FRAME
+To answer this question, GDB has the @dfn{sentinel} frame, the
+``-1st'' frame.  Unwinding registers from the sentinel frame gives you
+the current values of the youngest real frame's registers.  If @var{f}
+is a sentinel frame, then @code{get_frame_type (@var{f}) ==
+SENTINEL_FRAME}.
+
 @findex create_new_frame
 @vindex FRAME_FP
 @code{FRAME_FP} in the machine description has no meaning to the