[llvm] r364800 - [docs][llvm-readelf] Expand llvm-readelf documentation

Mon Jul 1 09:18:58 PDT 2019

Author: jhenderson
Date: Mon Jul  1 09:18:57 2019
New Revision: 364800

URL: http://llvm.org/viewvc/llvm-project?rev=364800&view=rev
Log:
[docs][llvm-readelf] Expand llvm-readelf documentation

Previously, the llvm-readelf documentation was essentially just a list
of differences to llvm-readobj. Since llvm-readelf is the more likely
goto tool for many people migrating to the LLVM toolchain, it seems like
it would be helpful to document all the switches in the llvm-readelf
document too. This change expands the options listed accordingly.
Additionally, they are unlikely to care what the differences are to
llvm-readobj, since they won't be familiar with the latter as there is
no GNU equivalent, so this change moves the "differences" section to
llvm-readobj's documentation.

Reviewed by: peter.smith

Differential Revision: https://reviews.llvm.org/D63826

Added:
    llvm/trunk/docs/CommandGuide/llvm-readelf.rst
Modified:
    llvm/trunk/docs/CommandGuide/llvm-readobj.rst

Added: llvm/trunk/docs/CommandGuide/llvm-readelf.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/llvm-readelf.rst?rev=364800&view=auto
==============================================================================

--- llvm/trunk/docs/CommandGuide/llvm-readelf.rst (added)
+++ llvm/trunk/docs/CommandGuide/llvm-readelf.rst Mon Jul  1 09:18:57 2019
@@ -0,0 +1,194 @@
+llvm-readelf - GNU-style LLVM Object Reader
+===========================================
+
+.. program:: llvm-readelf
+
+SYNOPSIS
+--------
+
+:program:`llvm-readelf` [*options*] [*input...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-readelf` tool displays low-level format-specific information
+about one or more object files.
+
+If ``input`` is "``-``" or omitted, :program:`llvm-readelf` reads from standard
+input. Otherwise, it will read from the specified ``filenames``.
+
+OPTIONS
+-------
+
+.. option:: --all
+
+ Equivalent to specifying all the main display options.
+
+.. option:: --addrsig
+
+ Display the address-significance table.
+
+.. option:: --arm-attributes
+
+ Display the ARM attributes section. Only applicable for ARM architectures.
+
+.. option:: --color
+
+ Use colors in the output for warnings and errors.
+
+.. option:: --demangle, -C
+
+ Display demangled symbol names in the output.
+
+.. option:: --dyn-relocations
+
+ Display the dynamic relocation entries.
+
+.. option:: --dyn-symbols, --dyn-syms
+
+ Display the dynamic symbol table.
+
+.. option:: --dynamic-table, --dynamic, -d
+
+ Display the dynamic table.
+
+.. option:: --elf-cg-profile
+
+ Display the callgraph profile section.
+
+.. option:: --elf-hash-histogram, --histogram, -I
+
+ Display a bucket list histogram for dynamic symbol hash tables.
+
+.. option:: --elf-linker-options
+
+ Display the linker options section.
+
+.. option:: --elf-output-style=<value>
+
+ Specify the style to dump ELF information in. Valid options are ``LLVM`` and
+ ``GNU``. ``LLVM`` output is an expanded and structured format, whilst ``GNU``
+ (the default) output mimics the equivalent GNU :program:`readelf` output.
+
+.. option:: --elf-section-groups, --section-groups, -g
+
+ Display section groups.
+
+.. option:: --expand-relocs
+
+ When used with :option:`--relocations`, display each relocation in an expanded
+ multi-line format.
+
+.. option:: --file-headers, -h
+
+ Display file headers.
+
+.. option:: --gnu-hash-table
+
+ Display the GNU hash table for dynamic symbols.
+
+.. option:: --hash-symbols
+
+ Display the dynamic symbols derived from the hash table.
+
+.. option:: --hash-table
+
+ Display the hash table for dynamic symbols.
+
+.. option:: --headers, -e
+
+ Equivalent to setting: :option:`--file-headers`, :option:`--program-headers`,
+ and :option:`--sections`.
+
+.. option:: --help
+
+ Display a summary of command line options.
+
+.. option:: --help-list
+
+ Display an uncategorized summary of command line options.
+
+.. option:: --hex-dump=<section[,section,...]>, -x
+
+ Display the specified section(s) as hexadecimal bytes. ``section`` may be a
+ section index or section name.
+
+.. option:: --needed-libs
+
+ Display the needed libraries.
+
+.. option:: --notes, -n
+
+ Display all notes.
+
+.. option:: --program-headers, --segments, -l
+
+ Display the program headers.
+
+.. option:: --raw-relr
+
+ Do not decode relocations in RELR relocation sections when displaying them.
+
+.. option:: --relocations, --relocs, -r
+
+ Display the relocation entries in the file.
+
+.. option:: --sections, --section-headers, -S
+
+ Display all sections.
+
+.. option:: --section-data
+
+ When used with :option:`--sections`, display section data for each section shown.
+
+.. option:: --section-mapping
+
+ Display the section to segment mapping.
+
+.. option:: --section-relocations
+
+ When used with :option:`--sections`, display relocations for each section shown.
+
+.. option:: --section-symbols
+
+ When used with :option:`--sections`, display symbols for each section shown.
+
+.. option:: --stackmap
+
+ Display contents of the stackmap section.
+
+.. option:: --string-dump=<section[,section,...]>, -p
+
+ Display the specified section(s) as a list of strings. ``section`` may be a
+ section index or section name.
+
+.. option:: --symbols, --syms, -s
+
+ Display the symbol table.
+
+.. option:: --unwind, -u
+
+ Display unwind information.
+
+.. option:: --version
+
+ Display the version of this program.
+
+.. option:: --version-info, -V
+
+ Display version sections.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-readelf` returns 0 under normal operation. It returns a non-zero
+exit code if there were any errors.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readobj(1)`

Modified: llvm/trunk/docs/CommandGuide/llvm-readobj.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/llvm-readobj.rst?rev=364800&r1=364799&r2=364800&view=diff
==============================================================================
--- llvm/trunk/docs/CommandGuide/llvm-readobj.rst (original)
+++ llvm/trunk/docs/CommandGuide/llvm-readobj.rst Mon Jul  1 09:18:57 2019
@@ -17,6 +17,30 @@ about one or more object files.
 If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard
 input. Otherwise, it will read from the specified ``filenames``.
 
+DIFFERENCES TO LLVM-READELF
+---------------------------
+
+:program:`llvm-readelf` is an alias for the :manpage:`llvm-readobj` tool with a
+slightly different command-line interface and output that is GNU compatible.
+Following is a list of differences between :program:`llvm-readelf` and
+:program:`llvm-readobj`:
+
+- :program:`llvm-readelf` uses `GNU` for the :option:`--elf-output-style` option
+  by default. :program:`llvm-readobj` uses `LLVM`.
+- :program:`llvm-readelf` allows single-letter grouped flags (e.g.
+  ``llvm-readelf -SW`` is the same as  ``llvm-readelf -S -W``).
+  :program:`llvm-readobj` does not allow grouping.
+- :program:`llvm-readelf` provides :option:`-s` as an alias for
+  :option:`--symbols`, for GNU :program:`readelf` compatibility, whereas it is
+  an alias for :option:`--section-headers` in :program:`llvm-readobj`.
+- :program:`llvm-readobj` provides ``-t`` as an alias for :option:`--symbols`.
+  :program:`llvm-readelf` does not.
+- :program:`llvm-readobj` provides ``--sr``, ``--sd``, ``--st`` and ``--dt`` as
+  aliases for :option:`--section-relocations`, :option:`--section-data`,
+  :option:`--section-symbols` and :option:`--dyn-symbols` respectively.
+  :program:`llvm-readelf` does not provide these aliases, to avoid conflicting
+  with grouped flags.
+
 GENERAL AND MULTI-FORMAT OPTIONS
 --------------------------------
 


