New /s modifier for the disassemble command.

The "source centric" /m option to the disassemble command is often
unhelpful, e.g., in the presence of optimized code.
This patch adds a /s modifier that is better.
For one, /m only prints instructions from the originating source file,
leaving out instructions from e.g., inlined functions from other files.

gdb/ChangeLog:

	PR gdb/11833
	* NEWS: Document new /s modifier for the disassemble command.
	* cli/cli-cmds.c (disassemble_command): Add support for /s.
	(_initialize_cli_cmds): Update online docs of disassemble command.
	* disasm.c: #include "source.h".
	(struct deprecated_dis_line_entry): Renamed from dis_line_entry.
	All uses updated.
	(dis_line_entry): New struct.
	(hash_dis_line_entry, eq_dis_line_entry): New functions.
	(allocate_dis_line_table): New functions.
	(maybe_add_dis_line_entry, line_has_code_p): New functions.
	(dump_insns): New arg end_pc.  All callers updated.
	(do_mixed_source_and_assembly_deprecated): Renamed from
	do_mixed_source_and_assembly.  All callers updated.
	(do_mixed_source_and_assembly): New function.
	(gdb_disassembly): Handle /s (DISASSEMBLY_SOURCE).
	* disasm.h (DISASSEMBLY_SOURCE_DEPRECATED): Renamed from
	DISASSEMBLY_SOURCE.  All uses updated.
	(DISASSEMBLY_SOURCE): New macro.
	* mi/mi-cmd-disas.c (mi_cmd_disassemble): New modes 4,5.

gdb/doc/ChangeLog:

	* gdb.texinfo (Machine Code): Update docs for mixed source/assembly
	disassembly.
	(GDB/MI Data Manipulation): Update docs for new disassembly modes.

gdb/testsuite/ChangeLog:

	* gdb.mi/mi-disassemble.exp: Update.
	* gdb.base/disasm-optim.S: New file.
	* gdb.base/disasm-optim.c: New file.
	* gdb.base/disasm-optim.h: New file.
	* gdb.base/disasm-optim.exp: New file.

gdb/cli/cli-cmds.c

@@ -1175,16 +1175,26 @@ disassemble_current_function (int flags)
 /* Dump a specified section of assembly code.
 
    Usage:
-     disassemble [/mr]
+     disassemble [/mrs]
        - dump the assembly code for the function of the current pc
-     disassemble [/mr] addr
+     disassemble [/mrs] addr
        - dump the assembly code for the function at ADDR
-     disassemble [/mr] low,high
-     disassemble [/mr] low,+length
+     disassemble [/mrs] low,high
+     disassemble [/mrs] low,+length
        - dump the assembly code in the range [LOW,HIGH), or [LOW,LOW+length)
 
-   A /m modifier will include source code with the assembly.
-   A /r modifier will include raw instructions in hex with the assembly.  */
+   A /m modifier will include source code with the assembly in a
+   "source centric" view.  This view lists only the file of the first insn,
+   even if other source files are involved (e.g., inlined functions), and
+   the output is in source order, even with optimized code.  This view is
+   considered deprecated as it hasn't been useful in practice.
+
+   A /r modifier will include raw instructions in hex with the assembly.
+
+   A /s modifier will include source code with the assembly, like /m, with
+   two important differences:
+   1) The output is still in pc address order.
+   2) File names and contents for all relevant source files are displayed.  */
 
 static void
 disassemble_command (char *arg, int from_tty)
@@ -1212,11 +1222,14 @@ disassemble_command (char *arg, int from_tty)
 	  switch (*p++)
 	    {
 	    case 'm':
-	      flags |= DISASSEMBLY_SOURCE;
+	      flags |= DISASSEMBLY_SOURCE_DEPRECATED;
 	      break;
 	    case 'r':
 	      flags |= DISASSEMBLY_RAW_INSN;
 	      break;
+	    case 's':
+	      flags |= DISASSEMBLY_SOURCE;
+	      break;
 	    default:
 	      error (_("Invalid disassembly modifier."));
 	    }
@@ -1225,6 +1238,10 @@ disassemble_command (char *arg, int from_tty)
       p = skip_spaces_const (p);
     }
 
+  if ((flags & (DISASSEMBLY_SOURCE_DEPRECATED | DISASSEMBLY_SOURCE))
+      == (DISASSEMBLY_SOURCE_DEPRECATED | DISASSEMBLY_SOURCE))
+    error (_("Cannot specify both /m and /s."));
+
   if (! p || ! *p)
     {
       flags |= DISASSEMBLY_OMIT_FNAME;
@@ -1885,8 +1902,21 @@ the other arg."));
   c = add_com ("disassemble", class_vars, disassemble_command, _("\
 Disassemble a specified section of memory.\n\
 Default is the function surrounding the pc of the selected frame.\n\
+\n\
 With a /m modifier, source lines are included (if available).\n\
+This view is \"source centric\": the output is in source line order,\n\
+regardless of any optimization that is present.  Only the main source file\n\
+is displayed, not those of, e.g., any inlined functions.\n\
+This modifier hasn't proved useful in practice and is deprecated\n\
+in favor of /s.\n\
+\n\
+With a /s modifier, source lines are included (if available).\n\
+This differs from /m in two important respects:\n\
+- the output is still in pc address order, and\n\
+- file names and contents for all relevant source files are displayed.\n\
+\n\
 With a /r modifier, raw instructions in hex are included.\n\
+\n\
 With a single argument, the function surrounding that address is dumped.\n\
 Two arguments (separated by a comma) are taken as a range of memory to dump,\n\
   in the form of \"start,end\", or \"start,+length\".\n\