gdb: Change how frames are selected for 'frame' and 'info frame'.

The 'frame' command, and thanks to code reuse the 'info frame' and
'select-frame' commands, currently have an overloaded mechanism for
selecting a frame.

These commands take one or two parameters, if it's one parameter then
we first try to use the parameter as an integer to select a frame by
level (or depth in the stack).  If that fails then we treat the
parameter as an address and try to select a stack frame by
stack-address.  If we still have not selected a stack frame, or we
initially had two parameters, then GDB allows the user to view a stack
frame that is not part of the current backtrace.  Internally, a new
frame is created with the given stack and pc addresses, and this is
shown to the user.

The result of this is that a typo by the user, entering the wrong stack
frame level for example, can result in a brand new frame being viewed
rather than an error.

The purpose of this commit is to remove this overloading, while still
offering the same functionality through some new sub-commands.  By
making the default behaviour of 'frame' (and friends) be to select a
stack frame by level index, it is hoped that enough
backwards-compatibility is maintained that users will not be overly
inconvenienced.

The 'frame', 'select-frame', and 'info frame' commands now all take a
frame specification string as an argument, this string can be any of the
following:

  (1) An integer.  This is treated as a frame level.  If a frame for
  that level does not exist then the user gets an error.

  (2) A string like 'level <LEVEL>', where <LEVEL> is a frame level
  as in option (1) above.

  (3) A string like 'address <STACK-ADDRESS>', where <STACK-ADDRESS>
  is a stack-frame address.  If there is no frame for this address
  then the user gets an error.

  (4) A string like 'function <NAME>', where <NAME> is a function name,
  the inner most frame for function <NAME> is selected.  If there is no
  frame for function <NAME> then the user gets an error.

  (5) A string like 'view <STACK-ADDRESS>', this views a new frame
  with stack address <STACK-ADDRESS>.

  (6) A string like 'view <STACK-ADDRESS> <PC-ADDRESS>', this views
  a new frame with stack address <STACK-ADDRESS> and the pc <PC-ADDRESS>.

This change assumes that the most common use of the commands like
'frame' is to select a frame by frame level, it is for this reason
that this is the behaviour that is kept for backwards compatibility.
Any of the alternative behaviours, which are assumed to be less used,
now require a change in user behaviour.

The MI command '-stack-select-frame' has not been changed.  This
ensures that we maintain backwards compatibility for existing
frontends.

gdb/ChangeLog:

	(NEWS): Mention changes to frame related commands.
	* cli/cli-decode.c (add_cmd_suppress_notification): New function.
	(add_prefix_cmd_suppress_notification): New function.
	(add_com_suppress_notification): Call
	add_cmd_suppress_notification.
	* command.h (add_cmd_suppress_notification): Declare.
	(add_prefix_cmd_suppress_notification): Declare.
	* mi/mi-cmd-stack.c: Add 'safe-ctype.h' include.
	(parse_frame_specification): Moved from stack.c, with
	simplification to handle a single argument.
	(mi_cmd_stack_select_frame): Use parse_frame_specification, the
	switch to the selected frame.  Add a header comment.
	* stack.c: Remove 'safe-ctype.h' include.
	(find_frame_for_function): Add declaration.
	(find_frame_for_address): New function.
	(parse_frame_specification): Moved into mi/mi-cmd-stack.c.
	(frame_selection_by_function_completer): New function.
	(info_frame_command): Rename to...
	(info_frame_command_core): ...this, and update parameter types.
	(select_frame_command): Rename to...
	(select_frame_command_core): ...this, and update parameter types.
	(frame_command): Rename to...
	(frame_command_core): ...this, and update parameter types.
	(class frame_command_helper): New class to wrap implementations of
	frame related sub-commands.
	(frame_apply_cmd_list): New static global.
	(frame_cmd_list): Make static.
	(select_frame_cmd_list): New global for sub-commands.
	(info_frame_cmd_list): New global for sub-commands.
	(_initialize_stack): Register sub-commands for 'frame',
	'select-frame', and 'info frame'.  Update 'frame apply' commands
	to use frame_apply_cmd_list.  Move function local static
	frame_apply_list to file static frame_apply_cmd_list for
	consistency.
	* stack.h (select_frame_command): Delete declarationn.
	(select_frame_for_mi): Declare new function.

gdb/doc/ChangeLog:

	* gdb.texinfo (Frames): Rewrite the description of 'frame number'
	to highlight that the number is also the frame's level.
	(Selection): Rewrite documentation for 'frame' and 'select-frame'
	commands.
	(Frame Info): Rewrite documentation for 'info frame' command.

gdb/testsuite/ChangeLog:

	* gdb.base/frame-selection.exp: New file.
	* gdb.base/frame-selection.c: New file.

2 files changed, 92 insertions, 27 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 4285a4d..45aed88 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,11 @@
+2018-09-28  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* gdb.texinfo (Frames): Rewrite the description of 'frame number'
+	to highlight that the number is also the frame's level.
+	(Selection): Rewrite documentation for 'frame' and 'select-frame'
+	commands.
+	(Frame Info): Rewrite documentation for 'info frame' command.
+
 2018-09-23  Tom Tromey  <tom@tromey.com>
 
 	PR python/18852:
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b5b6089..6248641 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7401,12 +7401,14 @@ 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 level
 @cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, 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
-frames in @value{GDBN} commands.
+@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.  The terms
+@dfn{frame number} and @dfn{frame level} can be used interchangeably to
+describe this number.
 
 @c The -fomit-frame-pointer below perennially causes hbox overflow
 @c underflow problems.
@@ -7639,21 +7641,75 @@ of the stack frame just selected.
 @table @code
 @kindex frame@r{, selecting}
 @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
+@item frame @r{[} @var{frame-selection-spec} @r{]}
+@item f @r{[} @var{frame-selection-spec} @r{]}
+The @command{frame} command allows different stack frames to be
+selected.  The @var{frame-selection-spec} can be any of the following:
+
+@table @code
+@kindex frame level
+@item @var{num}
+@item level @var{num}
+Select frame level @var{num}.  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
-@code{main}.
+innermost one, and so on.  The highest level frame is usually the one
+for @code{main}.
+
+As this is the most common method of navigating the frame stack, the
+string @command{level} can be omitted.  For example, the following two
+commands are equivalent:
 
-@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
-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.
+@smallexample
+(@value{GDBP}) frame 3
+(@value{GDBP}) frame level 3
+@end smallexample
+
+@kindex frame address
+@item address @var{stack-address}
+Select the frame with stack address @var{stack-address}.  The
+@var{stack-address} for a frame can be seen in the output of
+@command{info frame}, for example:
+
+@smallexample
+(gdb) info frame
+Stack level 1, frame at 0x7fffffffda30:
+ rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
+ tail call frame, caller of frame at 0x7fffffffda30
+ source language c++.
+ Arglist at unknown address.
+ Locals at unknown address, Previous frame's sp is 0x7fffffffda30
+@end smallexample
+
+The @var{stack-address} for this frame is @code{0x7fffffffda30} as
+indicated by the line:
+
+@smallexample
+Stack level 1, frame at 0x7fffffffda30:
+@end smallexample
+
+@kindex frame function
+@item function @var{function-name}
+Select the stack frame for function @var{function-name}.  If there are
+multiple stack frames for function @var{function-name} then the inner
+most stack frame is selected.
+
+@kindex frame view
+@item view @var{stack-address} @r{[} @var{pc-addr} @r{]}
+View a frame that is not part of @value{GDBN}'s backtrace.  The frame
+viewed has stack address @var{stack-addr}, and optionally, a program
+counter address of @var{pc-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 addition, this can be useful
+when your program has multiple stacks and switches between them.
+
+When viewing a frame outside the current backtrace using
+@command{frame view} then you can always return to the original
+stack using one of the previous stack frame selection instructions,
+for example @command{frame level 0}.
+
+@end table
 
 @kindex up
 @item up @var{n}
@@ -7696,11 +7752,13 @@ for details.
 
 @table @code
 @kindex select-frame
-@item select-frame
+@item select-frame @r{[} @var{frame-selection-spec} @r{]}
 The @code{select-frame} command is a variant of @code{frame} that does
 not display the new frame after selecting it.  This command is
 intended primarily for use in @value{GDBN} command scripts, where the
-output might be unnecessary and distracting.
+output might be unnecessary and distracting.  The
+@var{frame-selection-spec} is as for the @command{frame} command
+described in @ref{Selection, ,Selecting a Frame}.
 
 @kindex down-silently
 @kindex up-silently
@@ -7758,13 +7816,12 @@ which registers were saved in the frame
 something has gone wrong that has made the stack format fail to fit
 the usual conventions.
 
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame.  The selected frame remains unchanged by this
-command.  This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
+@item info frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx info f @r{[} @var{frame-selection-spec} @r{]}
+Print a verbose description of the frame selected by
+@var{frame-selection-spec}.  The @var{frame-selection-spec} is the
+same as for the @command{frame} command (@pxref{Selection, ,Selecting
+a Frame}).  The selected frame remains unchanged by this command.
 
 @kindex info args
 @item info args