gdb: introduce new 'maint flush ' prefix command

We currently have two flushing commands 'flushregs' and 'maint
flush-symbol-cache'.  I'm planning to add at least one more so I
thought it might be nice if we bundled these together into one place.

And so I created the 'maint flush ' command prefix.  Currently there
are two commands:

  (gdb) maint flush symbol-cache
  (gdb) maint flush register-cache

Unfortunately, even though both of the existing flush commands are
maintenance commands, I don't know how keen we about deleting existing
commands for fear of breaking things in the wild.  So, both of the
existing flush commands 'maint flush-symbol-cache' and 'flushregs' are
still around as deprecated aliases to the new commands.

I've updated the testsuite to use the new command syntax, and updated
the documentation too.

gdb/ChangeLog:

	* NEWS: Mention new commands, and that the old commands are now
	deprecated.
	* cli/cli-cmds.c (maintenanceflushlist): Define.
	* cli/cli-cmds.h (maintenanceflushlist): Declare.
	* maint.c (_initialize_maint_cmds): Initialise
	maintenanceflushlist.
	* regcache.c: Add 'cli/cli-cmds.h' include.
	(reg_flush_command): Add header comment.
	(_initialize_regcache): Create new 'maint flush register-cache'
	command, make 'flushregs' an alias.
	* symtab.c: Add 'cli/cli-cmds.h' include.
	(_initialize_symtab): Create new 'maint flush symbol-cache'
	command, make old command an alias.

gdb/doc/ChangeLog:

	* gdb.texinfo (Symbols): Document 'maint flush symbol-cache'.
	(Maintenance Commands): Document 'maint flush register-cache'.

gdb/testsuite/ChangeLog:

	* gdb.base/c-linkage-name.exp: Update to use new 'maint flush ...'
	commands.
	* gdb.base/killed-outside.exp: Likewise.
	* gdb.opt/inline-bt.exp: Likewise.
	* gdb.perf/gmonster-null-lookup.py: Likewise.
	* gdb.perf/gmonster-print-cerr.py: Likewise.
	* gdb.perf/gmonster-ptype-string.py: Likewise.
	* gdb.python/py-unwind.exp: Likewise.

gdb/ChangeLog

@@ -1,3 +1,19 @@
+2020-12-13  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* NEWS: Mention new commands, and that the old commands are now
+	deprecated.
+	* cli/cli-cmds.c (maintenanceflushlist): Define.
+	* cli/cli-cmds.h (maintenanceflushlist): Declare.
+	* maint.c (_initialize_maint_cmds): Initialise
+	maintenanceflushlist.
+	* regcache.c: Add 'cli/cli-cmds.h' include.
+	(reg_flush_command): Add header comment.
+	(_initialize_regcache): Create new 'maint flush register-cache'
+	command, make 'flushregs' an alias.
+	* symtab.c: Add 'cli/cli-cmds.h' include.
+	(_initialize_symtab): Create new 'maint flush symbol-cache'
+	command, make old command an alias.
+
 2020-12-11  Andrew Burgess  <andrew.burgess@embecosm.com>
 
 	* cli/cli-decode.c (deprecated_cmd_warning): Ignore the prefix

gdb/NEWS

@@ -39,6 +39,11 @@ set debug event-loop
 show debug event-loop
   Control the display of debug output about GDB's event loop.
 
+maintenance flush symbol-cache
+maintenance flush register-cache
+  These new commands are equivalent to the already existing commands
+  'maintenance flush-symbol-cache' and 'flushregs' respectively.
+
 * Changed commands
 
 break [PROBE_MODIFIER] [LOCATION] [thread THREADNUM]
@@ -61,6 +66,12 @@ condition [-force] N COND
   GDB into defining the condition even when COND is invalid for all the
   current locations of breakpoint N.
 
+flushregs
+maintenance flush-symbol-cache
+  These commands are deprecated in favor of the new commands
+  'maintenance flush register-cache' and 'maintenance flush
+  symbol-cache' respectively.
+
 *** Changes in GDB 10
 
 * There are new feature names for ARC targets: "org.gnu.gdb.arc.core"

gdb/cli/cli-cmds.c

@@ -151,6 +151,10 @@ struct cmd_list_element *maintenanceprintlist;
 
 struct cmd_list_element *maintenancechecklist;
 
+/* Chain containing all defined "maintenance flush" subcommands.  */
+
+struct cmd_list_element *maintenanceflushlist;
+
 struct cmd_list_element *setprintlist;
 
 struct cmd_list_element *showprintlist;

gdb/cli/cli-cmds.h

@@ -89,6 +89,10 @@ extern struct cmd_list_element *maintenanceinfolist;
 
 extern struct cmd_list_element *maintenanceprintlist;
 
+/* Chain containing all defined "maintenance flush" subcommands.  */
+
+extern struct cmd_list_element *maintenanceflushlist;
+
 extern struct cmd_list_element *setprintlist;
 
 extern struct cmd_list_element *showprintlist;

gdb/doc/ChangeLog

@@ -1,3 +1,8 @@
+2020-12-13  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* gdb.texinfo (Symbols): Document 'maint flush symbol-cache'.
+	(Maintenance Commands): Document 'maint flush register-cache'.
+
 2020-12-04  Bernd Edlinger  <bernd.edlinger@hotmail.de>
 
 	* Makefile.in: Delete GDBvn.texi and version.subst only in

gdb/doc/gdb.texinfo

@@ -19503,12 +19503,16 @@ This is useful when debugging symbol cache issues.
 Print symbol cache usage statistics.
 This helps determine how well the cache is being utilized.
 
+@kindex maint flush symbol-cache
 @kindex maint flush-symbol-cache
 @cindex symbol cache, flushing
-@item maint flush-symbol-cache
-Flush the contents of the symbol cache, all entries are removed.
-This command is useful when debugging the symbol cache.
-It is also useful when collecting performance data.
+@item maint flush symbol-cache
+@itemx maint flush-symbol-cache
+Flush the contents of the symbol cache, all entries are removed.  This
+command is useful when debugging the symbol cache.  It is also useful
+when collecting performance data.  The command @code{maint
+flush-symbol-cache} is deprecated in favor of @code{maint flush
+symbol-cache}..
 
 @end table
 
@@ -38859,9 +38863,15 @@ The register groups info looks like this:
  restore    internal
 @end smallexample
 
+@kindex maint flush register-cache
 @kindex flushregs
-@item flushregs
-This command forces @value{GDBN} to flush its internal register cache.
+@cindex register cache, flushing
+@item maint flush register-cache
+@itemx flushregs
+Flush the contents of the register cache and as a consequence the
+frame cache.  This command is useful when debugging issues related to
+register fetching, or frame unwinding.  The command @code{flushregs}
+is deprecated in favor of @code{maint flush register-cache}.
 
 @kindex maint print objfiles
 @cindex info for known object files

gdb/maint.c

@@ -1083,6 +1083,11 @@ lists all sections from all object files, including shared libraries."),
 			&maintenanceprintlist, "maintenance print ", 0,
 			&maintenancelist);
 
+  add_basic_prefix_cmd ("flush", class_maintenance,
+			_("Maintenance command for flushing GDB internal caches."),
+			&maintenanceflushlist, "maintenance flush ", 0,
+			&maintenancelist);
+
   add_basic_prefix_cmd ("set", class_maintenance, _("\
 Set GDB internal variables used by the GDB maintainer.\n\
 Configure variables internal to GDB that aid in GDB's maintenance"),

gdb/regcache.c

@@ -30,6 +30,7 @@
 #include "observable.h"
 #include "regset.h"
 #include <unordered_map>
+#include "cli/cli-cmds.h"
 
 /*
  * DATA STRUCTURE
@@ -1382,6 +1383,8 @@ regcache::debug_print_register (const char *func,  int regno)
   fprintf_unfiltered (gdb_stdlog, "\n");
 }
 
+/* Implement 'maint flush register-cache' command.  */
+
 static void
 reg_flush_command (const char *command, int from_tty)
 {
@@ -2076,14 +2079,20 @@ void _initialize_regcache ();
 void
 _initialize_regcache ()
 {
+  struct cmd_list_element *c;
+
   regcache_descr_handle
     = gdbarch_data_register_post_init (init_regcache_descr);
 
   gdb::observers::target_changed.attach (regcache_observer_target_changed);
   gdb::observers::thread_ptid_changed.attach (regcache_thread_ptid_changed);
 
-  add_com ("flushregs", class_maintenance, reg_flush_command,
-	   _("Force gdb to flush its register cache (maintainer command)."));
+  add_cmd ("register-cache", class_maintenance, reg_flush_command,
+	   _("Force gdb to flush its register and frame cache."),
+	   &maintenanceflushlist);
+  c = add_com_alias ("flushregs", "maintenance flush register-cache",
+		     class_maintenance, 0);
+  deprecate_cmd (c, "maintenance flush register-cache");
 
 #if GDB_SELF_TEST
   selftests::register_test ("get_thread_arch_aspace_regcache",

gdb/symtab.c

@@ -42,6 +42,7 @@
 #include "addrmap.h"
 #include "cli/cli-utils.h"
 #include "cli/cli-style.h"
+#include "cli/cli-cmds.h"
 #include "fnmatch.h"
 #include "hashtab.h"
 #include "typeprint.h"
@@ -6929,10 +6930,13 @@ If zero then the symbol cache is disabled."),
 	   _("Print symbol cache statistics for each program space."),
 	   &maintenanceprintlist);
 
-  add_cmd ("flush-symbol-cache", class_maintenance,
+  add_cmd ("symbol-cache", class_maintenance,
 	   maintenance_flush_symbol_cache,
 	   _("Flush the symbol cache for each program space."),
-	   &maintenancelist);
+	   &maintenanceflushlist);
+  c = add_alias_cmd ("flush-symbol-cache", "flush symbol-cache",
+		     class_maintenance, 0, &maintenancelist);
+  deprecate_cmd (c, "maintenancelist flush symbol-cache");
 
   gdb::observers::executable_changed.attach (symtab_observer_executable_changed);
   gdb::observers::new_objfile.attach (symtab_new_objfile_observer);

gdb/testsuite/ChangeLog

@@ -1,3 +1,14 @@
+2020-12-13  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* gdb.base/c-linkage-name.exp: Update to use new 'maint flush ...'
+	commands.
+	* gdb.base/killed-outside.exp: Likewise.
+	* gdb.opt/inline-bt.exp: Likewise.
+	* gdb.perf/gmonster-null-lookup.py: Likewise.
+	* gdb.perf/gmonster-print-cerr.py: Likewise.
+	* gdb.perf/gmonster-ptype-string.py: Likewise.
+	* gdb.python/py-unwind.exp: Likewise.
+
 2020-12-11  Andrew Burgess  <andrew.burgess@embecosm.com>
 
 	* gdb.base/commands.exp: Update expected results.

gdb/testsuite/gdb.base/c-linkage-name.exp

@@ -64,7 +64,7 @@ gdb_test "maint info symtabs" "\{ symtab \[^\r\n\]*c-linkage-name-2.c.*"
 
 # Flush the symbol cache to prevent the lookup to return the same as before.
 
-gdb_test "maint flush-symbol-cache"
+gdb_test "maint flush symbol-cache"
 
 # Try to print MUNDANE using its linkage name again, after partial
 # symtab expansion.

gdb/testsuite/gdb.base/killed-outside.exp

@@ -115,7 +115,7 @@ with_test_prefix "stepi" {
 # other commands would trigger.
 with_test_prefix "registers" {
     test {
-	gdb_test "flushregs" ".*"
+	gdb_test "maint flush register-cache" ".*"
 	gdb_test "info threads" ".*"
     }
 }

gdb/testsuite/gdb.opt/inline-bt.exp

@@ -61,7 +61,7 @@ gdb_test "info frame" ".*inlined into frame.*" "func2 inlined (3)"
 # function.
 gdb_test_no_output "set backtrace limit 2"
 # Force flushing the frame cache.
-gdb_test "flushregs" "Register cache flushed."
+gdb_test "maint flush register-cache" "Register cache flushed."
 gdb_test "up" "#1  .*func1.*" "up from bar (4)"
 gdb_test "info frame" ".*in func1.*" "info frame still works"
 # Verify the user visible limit works as expected.

gdb/testsuite/gdb.perf/gmonster-null-lookup.py

@@ -40,7 +40,7 @@ class NullLookup(perftest.TestCaseWithBasicMeasurements):
             utils.safe_execute("mt expand-symtabs")
             iteration = 5
             while iteration > 0:
-                utils.safe_execute("mt flush-symbol-cache")
+                utils.safe_execute("mt flush symbol-cache")
                 func = lambda: utils.safe_execute("p symbol_not_found")
                 self.measure.measure(func, run)
                 iteration -= 1

gdb/testsuite/gdb.perf/gmonster-print-cerr.py

@@ -46,7 +46,7 @@ class PrintCerr(perftest.TestCaseWithBasicMeasurements):
             utils.runto_main()
             iteration = 5
             while iteration > 0:
-                utils.safe_execute("mt flush-symbol-cache")
+                utils.safe_execute("mt flush symbol-cache")
                 func = lambda: utils.safe_execute("print gm_std::cerr")
                 self.measure.measure(func, run)
                 iteration -= 1

gdb/testsuite/gdb.perf/gmonster-ptype-string.py

@@ -41,7 +41,7 @@ class GmonsterPtypeString(perftest.TestCaseWithBasicMeasurements):
             utils.safe_execute("mt expand-symtabs")
             iteration = 5
             while iteration > 0:
-                utils.safe_execute("mt flush-symbol-cache")
+                utils.safe_execute("mt flush symbol-cache")
                 func1 = lambda: utils.safe_execute("ptype hello")
                 func = lambda: utils.run_n_times(2, func1)
                 self.measure.measure(func, run)

gdb/testsuite/gdb.python/py-unwind.exp

@@ -57,4 +57,4 @@ gdb_test_sequence "where"  "Backtrace restored by unwinder" {
 }
 
 # Check that the Python unwinder frames can be flushed / released.
-gdb_test "flushregs" "Register cache flushed\\." "flush frames"
+gdb_test "maint flush register-cache" "Register cache flushed\\." "flush frames"