Add support to readelf and objdump for following links to separate debug information files.

Hi Guys,

  I am applying the rather large patch attached to this email to enhance
  the readelf and objdump programs so that they now have the ability to
  follow links to separate debug info files.  (As requested by PR
  15152).  So for example whereas before we had this output:

    $ readelf -wi main.exe

    Contents of the .debug_info section:
    [...]
    <15>   DW_AT_comp_dir    : (alt indirect string, offset: 0x30c)
    [...]

  With the new option enabled we get:

    $ readelf -wiK main.exe

    main.exe: Found separate debug info file: dwz.debug
    Contents of the .debug_info section (loaded from main.exe):
    [...]
    <15>   DW_AT_comp_dir    : (alt indirect string, offset: 0x30c) /home/nickc/Downloads/dwzm
    [...]

  The link following feature also means that we can get two lots of
  output if the same section exists in both the main file and the
  separate debug info file:

    $ readelf -wiK main.exe
    main.exe: Found separate debug info file: dwz.debug
    Contents of the .debug_info section (loaded from main.exe):
    [...]
    Contents of the .debug_info section (loaded from dwz.debug):
    [...]

  The patch also adds the ability to display the contents of debuglink
  sections:

    $ readelf -wk main.exe
    Contents of the .gnu_debugaltlink section:

      Separate debug info file: dwz.debug
      Build-ID (0x14 bytes):
     c4 a8 89 8d 64 cf 70 8a 35 68 21 f2 ed 24 45 3e 18 7a 7a 93

  Naturally there are long versions of these options (=follow-links and
  =links).  The documentation has been updated as well, and since both
  readelf and objdump use the same set of debug display options, I have
  moved the text into a separate file.  There are also a couple of new
  binutils tests to exercise the new behaviour.

  There are a couple of missing features in the current patch however,
  although I do intend to address them in follow up submissions:

  Firstly the code does not check the build-id inside separate debug
  info files when it is searching for a file specified by a
  .gnu_debugaltlink section.  It just assumes that if the file is there,
  then it contains the information being sought.

  Secondly I have not checked the DWARF-5 version of these link
  features, so there will probably be code to add there.

  Thirdly I have only implemented link following for the
  DW_FORM_GNU_strp_alt format.  Other alternate formats (eg
  DW_FORM_GNU_ref_alt) have yet to be implemented.

  Lastly, whilst implementing this feature I found it necessary to move
  some of the global variables used by readelf (eg section_headers) into
  a structure that can be passed around.  I have moved all of the global
  variables that were necessary to get the patch working, but I need to
  complete the operation and move the remaining, file-specific variables
  (eg dynamic_strings).

Cheers
  Nick

binutils	PR 15152
	* dwarf.h (enum dwarf_section_display_enum): Add gnu_debuglink,
	gnu_debugaltlink and separate_debug_str.
	(struct dwarf_section): Add filename field.
	Add prototypes for load_separate_debug_file, close_debug_file and
	open_debug_file.
	* dwarf.c (do_debug_links): New.
	(do_follow_links): New.
	(separate_debug_file, separate_debug_filename): New.
	(fetch_alt_indirect_string): New function.  Retrieves a string
	from the debug string table in the separate debug info file.
	(read_and_display_attr_value): Use it with DW_FORM_GNU_strp_alt.
	(load_debug_section_with_follow): New function.  Like
	load_debug_section, but if the first attempt fails, then tries
	again in the separate debug info file.
	(introduce): New function.
	(process_debug_info): Use load_debug_section_with_follow and
	introduce.
	(load_debug_info): Likewise.
	(display_debug_lines_raw): Likewise.
	(display_debug_lines_decoded): Likewise.
	(display_debug_macinfo): Likewise.
	(display_debug_macro): Likewise.
	(display_debug_abbrev): Likewise.
	(display_debug_loc): Likewise.
	(display_debug_str): Likewise.
	(display_debug_aranges): Likewise.
	(display_debug_addr); Likewise.
	(display_debug_frames): Likewise.
	(display_gdb_index): Likewise.
	(process_cu_tu_index): Likewise.
	(load_cu_tu_indexes): Likewise.
	(display_debug_links): New function.  Displays the contents of a
	.gnu_debuglink or .gnu_debugaltlink section.
	(calc_gnu_debuglink_ctc32):New function.  Calculates a CRC32
	value.
	(check_gnu_debuglink): New function.  Checks the CRC of a
	potential separate debug info file.
	(parse_gnu_debuglink): New function.  Reads a CRC value out of a
	.gnu_debuglink section.
	(check_gnu_debugaltlink): New function.
	(parse_gnu_debugaltlink): New function.  Reads the build-id value
	out of a .gnu_debugaltlink section.
	(load_separate_debug_info): New function.  Finds and loads a
	separate debug info file.
	(load_separate_debug_file): New function. Attempts to find and
	follow a link to a separate debug info file.
	(free_debug_memory): Free the separate debug info file
	information.
	(opts_table): Add "follow-links" and "links".
	(dwarf_select_sections_by_letters): Add "k" and "K".
	(debug_displays): Reformat.  Add .gnu-debuglink and
	.gnu_debugaltlink.
	Add an extra entry for .debug_str in a separate debug info file.
	* doc/binutils.texi: Move description of debug dump features
	common to both readelf and objdump into...
	* objdump.c (usage): Add -Wk and -WK.
	(load_specific_debug_section): Initialise the filename field in
	the dwarf_section structure.
	(close_debug_file): New function.
	(open_debug_file): New function.
	(dump_dwarf): Load and dump the separate debug info sections.
	* readelf.c (struct filedata): New structure.  Contains various
	variables that used to be global:
	(current_file_size, string_table, string_table_length, elf_header)
	(section_headers, program_headers, dump_sects, num_dump_sects):
	Move into filedata structure.
	(cmdline): New global variable.  Contains list of sections to dump
	by number, as specified on the command line.
	Add filedata parameter to most functions.
	(load_debug_section): Load the string table if it has not already
	been retrieved.
	(close_file): New function.
	(close_debug_file): New function.
	(open_file): New function.
	(open_debug_file): New function.
	(process_object): Process sections in any separate debug info files.
	* doc/debug.options.texi: New file.  Add description of =links and
	=follow-links options.
	* NEWS: Mention the new feature.
	* elfcomm.c: Have the byte gte functions take a const pointer.
	* elfcomm.h: Update prototypes.
	* testsuite/binutils-all/dw5.W: Update expected output.
	* testsuite/binutils-all/objdump.WL: Update expected output.
	* testsuite/binutils-all/objdump.exp: Add test of -WK and -Wk.
	* testsuite/binutils-all/readelf.exp: Add test of -wK and -wk.
	* testsuite/binutils-all/readelf.k: New file.
	* testsuite/binutils-all/objdump.Wk: New file.
	* testsuite/binutils-all/objdump.WK2: New file.
	* testsuite/binutils-all/linkdebug.s: New file.
	* testsuite/binutils-all/debuglink.s: New file.

gas	* testsuite/gas/avr/large-debug-line-table.d: Update expected
	output.
	* testsuite/gas/elf/dwarf2-11.d: Likewise.
	* testsuite/gas/elf/dwarf2-12.d: Likewise.
	* testsuite/gas/elf/dwarf2-13.d: Likewise.
	* testsuite/gas/elf/dwarf2-14.d: Likewise.
	* testsuite/gas/elf/dwarf2-15.d: Likewise.
	* testsuite/gas/elf/dwarf2-16.d: Likewise.
	* testsuite/gas/elf/dwarf2-17.d: Likewise.
	* testsuite/gas/elf/dwarf2-18.d: Likewise.
	* testsuite/gas/elf/dwarf2-5.d: Likewise.
	* testsuite/gas/elf/dwarf2-6.d: Likewise.
	* testsuite/gas/elf/dwarf2-7.d: Likewise.

ld	* testsuite/ld-avr/gc-section-debugline.d: Update expected
	output.

2 files changed, 151 insertions, 81 deletions

diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
index 03706db..a14c827 100644
--- a/binutils/doc/binutils.texi
+++ b/binutils/doc/binutils.texi
@@ -2071,11 +2071,8 @@ objdump [@option{-a}|@option{--archive-headers}]
         [@option{-r}|@option{--reloc}]
         [@option{-R}|@option{--dynamic-reloc}]
         [@option{-s}|@option{--full-contents}]
-        [@option{-W[lLiaprmfFsoRt]}|
-         @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames]
-                 [=aranges,=macro,=frames,=frames-interp,=str,=loc]
-                 [=Ranges,=pubtypes,=trace_info,=trace_abbrev]
-                 [=trace_aranges,=gdb_index]
+        [@option{-W[lLiaprmfFsoRtUuTgAckK]}|
+         @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
         [@option{-G}|@option{--stabs}]
         [@option{-t}|@option{--syms}]
         [@option{-T}|@option{--dynamic-syms}]
@@ -2560,42 +2557,9 @@ This is the default when @option{--prefix-addresses} is used.
 Display @var{width} bytes on a single line when disassembling
 instructions.
 
-@item -W[lLiaprmfFsoRt]
-@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames]
-@itemx --dwarf[=aranges,=macro,=frames,=frames-interp,=str,=loc]
-@itemx --dwarf[=Ranges,=pubtypes,=trace_info,=trace_abbrev]
-@itemx --dwarf[=trace_aranges,=gdb_index]
-@cindex DWARF
-@cindex debug symbols
-Displays the contents of the debug sections in the file, if any are
-present.  If one of the optional letters or words follows the switch
-then only data found in those specific sections will be dumped.
-
-Note that there is no single letter option to display the content of
-trace sections or .gdb_index.
-
-Note: the output from the @option{=info} option can also be affected
-by the options @option{--dwarf-depth}, the @option{--dwarf-start} and
-the @option{--dwarf-check}.
-
-@item --dwarf-depth=@var{n}
-Limit the dump of the @code{.debug_info} section to @var{n} children.
-This is only useful with @option{--dwarf=info}.  The default is
-to print all DIEs; the special value 0 for @var{n} will also have this
-effect.
-
-With a non-zero value for @var{n}, DIEs at or deeper than @var{n}
-levels will not be printed.  The range for @var{n} is zero-based.
-
-@item --dwarf-start=@var{n}
-Print only DIEs beginning with the DIE numbered @var{n}.  This is only
-useful with @option{--dwarf=info}.
-
-If specified, this option will suppress printing of any header
-information and all DIEs before the DIE numbered @var{n}.  Only
-siblings and children of the specified DIE will be printed.
-
-This can be used in conjunction with @option{--dwarf-depth}.
+@item -W[lLiaprmfFsoRtUuTgAckK]
+@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
+@include debug.options.texi
 
 @item --dwarf-check
 Enable additional checks for consistency of Dwarf information.
@@ -4627,8 +4591,8 @@ readelf [@option{-a}|@option{--all}]
         [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
         [@option{-z}|@option{--decompress}]
         [@option{-c}|@option{--archive-index}]
-        [@option{-w[lLiaprmfFsoRt]}|
-         @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index]]
+        [@option{-w[lLiaprmfFsoRtUuTgAckK]}|
+         @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]]
         [@option{--dwarf-depth=@var{n}}]
         [@option{--dwarf-start=@var{n}}]
         [@option{-I}|@option{--histogram}]
@@ -4803,44 +4767,9 @@ Displays the file symbol index information contained in the header part
 of binary archives.  Performs the same function as the @option{t}
 command to @command{ar}, but without using the BFD library.  @xref{ar}.
 
-@item -w[lLiaprmfFsoRt]
-@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index]
-Displays the contents of the debug sections in the file, if any are
-present.  If one of the optional letters or words follows the switch
-then only data found in those specific sections will be dumped.
-
-Note that there is no single letter option to display the content of
-trace sections or .gdb_index.
-
-Note: the @option{=decodedline} option will display the interpreted
-contents of a .debug_line section whereas the @option{=rawline} option
-dumps the contents in a raw format.
-
-Note: the @option{=frames-interp} option will display the interpreted
-contents of a .debug_frame section whereas the @option{=frames} option
-dumps the contents in a raw format.
-
-Note: the output from the @option{=info} option can also be affected
-by the options @option{--dwarf-depth} and @option{--dwarf-start}.
-
-@item --dwarf-depth=@var{n}
-Limit the dump of the @code{.debug_info} section to @var{n} children.
-This is only useful with @option{--debug-dump=info}.  The default is
-to print all DIEs; the special value 0 for @var{n} will also have this
-effect.
-
-With a non-zero value for @var{n}, DIEs at or deeper than @var{n}
-levels will not be printed.  The range for @var{n} is zero-based.
-
-@item --dwarf-start=@var{n}
-Print only DIEs beginning with the DIE numbered @var{n}.  This is only
-useful with @option{--debug-dump=info}.
-
-If specified, this option will suppress printing of any header
-information and all DIEs before the DIE numbered @var{n}.  Only
-siblings and children of the specified DIE will be printed.
-
-This can be used in conjunction with @option{--dwarf-depth}.
+@item -w[lLiaprmfFsoRtUuTgAckK]
+@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
+@include debug.options.texi
 
 @item -I
 @itemx --histogram
diff --git a/binutils/doc/debug.options.texi b/binutils/doc/debug.options.texi
new file mode 100644
index 0000000..9204b2b
--- /dev/null
+++ b/binutils/doc/debug.options.texi
@@ -0,0 +1,141 @@
+@c This file contains the entry for the -w/--debug-dump (readelf) and
+@c  -W/--dwarf (objdump) option that is common to both readelf and objdump.
+
+Displays the contents of the DWARF debug sections in the file, if any
+are present.  Compressed debug sections are automatically decompressed
+(temporarily) before they are displayed.  If one or more of the
+optional letters or words follows the switch then only those type(s)
+of data will be dumped.  The letters and words refer to the following
+information:
+
+@c Please Keep This Table Alpha Sorted.
+@table @code
+@item a
+@itemx =abbrev
+Displays the contents of the @samp{.debug_abbrev} section.
+
+@item A
+@itemx =addr
+Displays the contents of the @samp{.debug_addr} section.
+
+@item c
+@itemx =cu_index
+Displays the contents of the @samp{.debug_cu_index} and/or
+@samp{.debug_tu_index} sections.
+
+@item f
+@itemx =frames
+Display the raw contents of a @samp{.debug_frame} section.
+
+@item F
+@item =frame-interp
+Display the interpreted contents of a @samp{.debug_frame} section.
+
+@item g
+@itemx =gdb_index
+Displays the contents of the @samp{.gdb_index} and/or
+@samp{.debug_names} sections.
+
+@item i
+@itemx =info
+Displays the contents of the @samp{.debug_info} section.  Note: the
+output from this option can also be restricted by the use of the 
+@option{--dwarf-depth} and @option{--dwarf-start} options.
+
+@item k
+@itemx =links
+Displays the contents of the @samp{.gnu_debuglink} and/or
+@samp{.gnu_debugaltlink} sections.
+
+@item K
+@itemx =follow-links
+Display the contents of any selected debug sections that are found in
+a linked, separate debug info file.  This can result in multiple
+versions of the same debug section being displayed if both the main
+file and the separate debug info file contain sections with the same
+name.
+
+When displaying other debug information, if a link is encountered to
+a separate debug info file, then attempt to follow the link and
+display the referenced contents.
+
+@item l
+@itemx =rawline
+Displays the contents of the @samp{.debug_line} section in a raw
+format.
+
+@item L
+@item =decodedline
+Displays the interpreted contents of the @samp{.debug_line} section.
+
+@item m
+@itemx =macro
+Displays the contents of the @samp{.debug_macro} and/or
+@samp{.debug_macinfo} sections.
+
+@item o
+@itemx =loc
+Displays the contents of the @samp{.debug_loc} and/or
+@samp{.debug_loclists} sections.
+
+@item p
+@itemx =pubnames
+Displays the contents of the @samp{.debug_pubnames} and/or
+@samp{.debug_gnu_pubnames} sections.
+
+@item r
+@itemx =aranges
+Displays the contents of the @samp{.debug_aranges} section.
+
+@item R
+@itemx =Ranges
+Displays the contents of the @samp{.debug_ranges} and/or
+@samp{.debug_rnglists} sections.
+
+@item s
+@itemx =str
+Displays the contents of the @samp{.debug_str}, @samp{.debug_line_str}
+and/or @samp{.debug_str_offsets} sections.
+
+@item t
+@itemx =pubtype
+Displays the contents of the @samp{.debug_pubtypes} and/or
+@samp{.debug_gnu_pubtypes} sections.
+
+@item T
+@itemx =trace_aranges
+Displays the contents of the @samp{.trace_aranges} section.
+
+@item u
+@itemx =trace_abbrev
+Displays the contents of the @samp{.trace_abbrev} section.
+
+@item U
+@itemx =trace_info
+Displays the contents of the @samp{.trace_info} section.
+
+@end table
+
+Note: displaying the contents of @samp{.debug_static_funcs},
+@samp{.debug_static_vars} and @samp{debug_weaknames} sections is not
+currently supported.
+
+@item --dwarf-depth=@var{n}
+Limit the dump of the @code{.debug_info} section to @var{n} children.
+This is only useful with @option{--debug-dump=info}.  The default is
+to print all DIEs; the special value 0 for @var{n} will also have this
+effect.
+
+With a non-zero value for @var{n}, DIEs at or deeper than @var{n}
+levels will not be printed.  The range for @var{n} is zero-based.
+
+@item --dwarf-start=@var{n}
+Print only DIEs beginning with the DIE numbered @var{n}.  This is only
+useful with @option{--debug-dump=info}.
+
+If specified, this option will suppress printing of any header
+information and all DIEs before the DIE numbered @var{n}.  Only
+siblings and children of the specified DIE will be printed.
+
+This can be used in conjunction with @option{--dwarf-depth}.
+