diff mbox

[RFA] (try to) consistently use 'frame level' concept instead of 'frame number'.

Message ID 20180712221536.26845-1-philippe.waroquiers@skynet.be
State New
Headers show

Commit Message

Philippe Waroquiers July 12, 2018, 10:15 p.m. UTC
Following the discussion in the 'frame apply' patch and the patch proposed
in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
the idea is rather to speak about 'frame level' to identify a frame,
rather than 'frame number'.

This patch changes a few occurences of 'frame number' (or 'number') to
'frame level' (or 'level') in the code and in gdb.texinfo.

Note that the doc still has some references to 'trace frame number',
but I think that this is really a number that is numbering a set
of traced frames, and it is not a level. So, such occurences are
kept unchanged.

gdb/doc/ChangeLog
2018-07-12  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Stack Frames):
	Change 'frame number' to 'frame level'.
	(Backtrace): Likewise.
	(Selecting a Frame): Likewise.
	(GDB/MI Stack Manipulation): Likewise.

gdb/ChangeLog
	* stack.c (backtrace_command_1): Change 'frame number' to
	'frame level'.
	(_initialize_stack): Likewise.
---
 gdb/doc/gdb.texinfo | 25 ++++++++++++-------------
 gdb/stack.c         |  6 +++---
 2 files changed, 15 insertions(+), 16 deletions(-)

Comments

Eli Zaretskii July 13, 2018, 6:52 a.m. UTC | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Fri, 13 Jul 2018 00:15:36 +0200
> 
> Following the discussion in the 'frame apply' patch and the patch proposed
> in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
> the idea is rather to speak about 'frame level' to identify a frame,
> rather than 'frame number'.

I question the wisdom of changing such veteran terminology.

> -@cindex frame number
> -@value{GDBN} assigns numbers to all existing stack frames, starting with
> +@cindex frame level
> +In @value{GDBN}, each existing stack frame has a level, starting with
>  zero for the innermost frame, one for the frame that called it,
> -and so on upward.  These numbers do not really exist in your program;
> -they are assigned by @value{GDBN} to give you a way of designating stack
> +and so on upward.  These levels give you a way of designating stack
>  frames in @value{GDBN} commands.

If we are going to make this change, then I would suggest to keep the
index entry, _add_ to it an entry about "frame level", and explain
here what that level is, something like this:

  @value{GDBN} labels each existing stack frame with a @dfn{level}, a
  number that is zero for the innermost frame, one for the frame that
  called it, and so on upward.  These level numbers give you a way of
  designating stack frames in @value{GDBN} commands.

> -it had a separate frame, which is numbered zero as usual, allowing
> +it had a separate frame, which has a level zero as usual, allowing
                                        ^^^^^^^^^^
"level of zero".

> -Select frame number @var{n}.  Recall that frame zero is the innermost
> +Select frame level @var{n}.  Recall that frame zero is the innermost
   ^^^^^^^^^^^^^^^^^^^^^^^^^^
"Select frame whose level is @var{n}."

Thanks.
Philippe Waroquiers July 13, 2018, 7:23 a.m. UTC | #2
On Fri, 2018-07-13 at 09:52 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Fri, 13 Jul 2018 00:15:36 +0200
> > 
> > Following the discussion in the 'frame apply' patch and the patch proposed
> > in https://sourceware.org/ml/gdb-patches/2018-06/msg00170.html
> > the idea is rather to speak about 'frame level' to identify a frame,
> > rather than 'frame number'.
> 
> I question the wisdom of changing such veteran terminology.
Yes, for sure, frame number was used since quite some time.

But the concept of frame level was also already used, and IMO
there is quite some confusions between the 2.

For example, in @node GDB/MI Frame Information.
We also have some places that are defining frame number
as being the level e.g.-stack-list-frames.

And IMO, at other places, level is used where it should
rather be number or count.
E.g. 
'set backtrace limit N'
'set backtrace limit 0'
'set backtrace limit unlimited'
     Limit the backtrace to N levels.  A value of 'unlimited' or zero
     means unlimited levels.

looks somewhat confusing, and should rather be limit the backtrace
to N entries, or N frames, or whatever 
but probably not N levels.

To be further discussed it looks like ...

Thanks

Philippe

> 
> > -@cindex frame number
> > -@value{GDBN} assigns numbers to all existing stack frames, starting with
> > +@cindex frame level
> > +In @value{GDBN}, each existing stack frame has a level, starting with
> >  zero for the innermost frame, one for the frame that called it,
> > -and so on upward.  These numbers do not really exist in your program;
> > -they are assigned by @value{GDBN} to give you a way of designating stack
> > +and so on upward.  These levels give you a way of designating stack
> >  frames in @value{GDBN} commands.
> 
> If we are going to make this change, then I would suggest to keep the
> index entry, _add_ to it an entry about "frame level", and explain
> here what that level is, something like this:
> 
>   @value{GDBN} labels each existing stack frame with a @dfn{level}, a
>   number that is zero for the innermost frame, one for the frame that
>   called it, and so on upward.  These level numbers give you a way of
>   designating stack frames in @value{GDBN} commands.
> 
> > -it had a separate frame, which is numbered zero as usual, allowing
> > +it had a separate frame, which has a level zero as usual, allowing
> 
>                                         ^^^^^^^^^^
> "level of zero".
> 
> > -Select frame number @var{n}.  Recall that frame zero is the innermost
> > +Select frame level @var{n}.  Recall that frame zero is the innermost
> 
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^
> "Select frame whose level is @var{n}."
> 
> Thanks.
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b36a39b5b4..b0d208a121 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7393,11 +7393,10 @@  address serves as the address of the frame.  Usually this address is kept
 in a register called the @dfn{frame pointer register}
 (@pxref{Registers, $fp}) while execution is going on in that frame.
 
-@cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, starting with
+@cindex frame level
+In @value{GDBN}, each existing stack frame has a level, starting with
 zero for the innermost frame, one for the frame that called it,
-and so on upward.  These numbers do not really exist in your program;
-they are assigned by @value{GDBN} to give you a way of designating stack
+and so on upward.  These levels give you a way of designating stack
 frames in @value{GDBN} commands.
 
 @c The -fomit-frame-pointer below perennially causes hbox overflow
@@ -7413,7 +7412,7 @@  This is occasionally done with heavily used library functions to save
 the frame setup time.  @value{GDBN} has limited facilities for dealing
 with these function invocations.  If the innermost function invocation
 has no stack frame, @value{GDBN} nevertheless regards it as though
-it had a separate frame, which is numbered zero as usual, allowing
+it had a separate frame, which has a level zero as usual, allowing
 correct tracing of the function call chain.  However, @value{GDBN} has
 no provision for frameless functions elsewhere in the stack.
 
@@ -7486,7 +7485,7 @@  apply all backtrace}, @value{GDBN} will display the backtrace for all
 the threads; this is handy when you debug a core dump of a
 multi-threaded program.
 
-Each line in the backtrace shows the frame number and the function name.
+Each line in the backtrace shows the frame level and the function name.
 The program counter value is also shown---unless you use @code{set
 print address off}.  The backtrace also shows the source file name and
 line number, as well as the arguments to the function.  The program
@@ -7633,16 +7632,16 @@  of the stack frame just selected.
 @kindex f @r{(@code{frame})}
 @item frame @var{n}
 @itemx f @var{n}
-Select frame number @var{n}.  Recall that frame zero is the innermost
+Select frame level @var{n}.  Recall that frame zero is the innermost
 (currently executing) frame, frame one is the frame that called the
-innermost one, and so on.  The highest-numbered frame is the one for
+innermost one, and so on.  The highest-level frame is the one for
 @code{main}.
 
 @item frame @var{stack-addr} [ @var{pc-addr} ]
 @itemx f @var{stack-addr} [ @var{pc-addr} ]
 Select the frame at address @var{stack-addr}.  This is useful mainly if the
 chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames.  In
+impossible for @value{GDBN} to assign levels properly to all frames.  In
 addition, this can be useful when your program has multiple stacks and
 switches between them.  The optional @var{pc-addr} can also be given to
 specify the value of PC for the stack frame.
@@ -7651,19 +7650,19 @@  specify the value of PC for the stack frame.
 @item up @var{n}
 Move @var{n} frames up the stack; @var{n} defaults to 1.  For positive
 numbers @var{n}, this advances toward the outermost frame, to higher
-frame numbers, to frames that have existed longer.
+frame levels, to frames that have existed longer.
 
 @kindex down
 @kindex do @r{(@code{down})}
 @item down @var{n}
 Move @var{n} frames down the stack; @var{n} defaults to 1.  For
 positive numbers @var{n}, this advances toward the innermost frame, to
-lower frame numbers, to frames that were created more recently.
+lower frame levels, to frames that were created more recently.
 You may abbreviate @code{down} as @code{do}.
 @end table
 
 All of these commands end by printing two lines of output describing the
-frame.  The first line shows the frame number, the function name, the
+frame.  The first line shows the frame level, the function name, the
 arguments, and the source file and line number of execution in that
 frame.  The second line shows the text of that source line.
 
@@ -30074,7 +30073,7 @@  following info:
 
 @table @samp
 @item @var{level}
-The frame number, 0 being the topmost frame, i.e., the innermost function.
+The frame level, 0 being the topmost frame, i.e., the innermost function.
 @item @var{addr}
 The @code{$pc} value for that frame.
 @item @var{func}
diff --git a/gdb/stack.c b/gdb/stack.c
index e51c689f43..c1bcb7b169 100644
--- a/gdb/stack.c
+++ b/gdb/stack.c
@@ -1763,7 +1763,7 @@  backtrace_command_1 (const char *count_exp, frame_filter_flags flags,
 	{
 	  py_start = 0;
 	  /* The argument to apply_ext_lang_frame_filter is the number
-	     of the final frame to print, and frames start at 0.  */
+	     of frames to print, and frame levels start at 0.  */
 	  py_end = count - 1;
 	}
     }
@@ -2746,7 +2746,7 @@  This is useful in command scripts."));
 Select and print a stack frame.\nWith no argument, \
 print the selected stack frame.  (See also \"info frame\").\n\
 An argument specifies the frame to select.\n\
-It can be a stack frame number or the address of the frame."),
+It can be a stack frame level or the address of the frame."),
 		  &frame_cmd_list, "frame ", 1, &cmdlist);
 
   add_com_alias ("f", "frame", class_stack, 1);
@@ -2792,7 +2792,7 @@  shortcut for 'frame apply all -s COMMAND'"));
   add_com_suppress_notification ("select-frame", class_stack, select_frame_command, _("\
 Select a stack frame without printing anything.\n\
 An argument specifies the frame to select.\n\
-It can be a stack frame number or the address of the frame."),
+It can be a stack frame level or the address of the frame."),
 		 &cli_suppress_notification.user_selected_context);
 
   add_com ("backtrace", class_stack, backtrace_command, _("\