Re: gdb code review, pointer madness

[Jim Blandy <jimb at red-bean dot com>]

On 1/25/06, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Tue, 24 Jan 2006 21:25:44 -0800
> > From: Jim Blandy <jimb@red-bean.com>
> > Cc: ngustavson@emacinc.com, gdb-patches@sourceware.org
> >
> > I'm being lazy.  How's this?
>
> Almost perfect.  If you add a "@cindex sentinel frame" and a
> "@findex frame_register_unwind", it will be _just_ perfect.
>
> Actually, maybe also "@cindex frame, unwind".

I've committed the below, adding @vindex SENTINEL_FRAME:

gdb/doc/ChangeLog:
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.

Index: gdb/doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.235
diff -c -p -r1.235 gdbint.texinfo
*** gdb/doc/gdbint.texinfo	20 Jan 2006 21:58:16 -0000	1.235
--- gdb/doc/gdbint.texinfo	25 Jan 2006 18:45:33 -0000
*************** they use.
*** 231,236 ****
--- 231,266 ----
  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