Introduce llvm-objdump man page

[emaste]

Summary

This is an initial take on a man page for llvm-objdump based on usage output and LLVM's doc.

[Higuoxing]

lgtm, but seems that some hidden/alias options are not listed here (I could help add them). I am not expert in this area, so I will leave the decision to @kristina

[MaskRay]

usr.bin/clang/llvm-objdump/llvm-objdump.1

69 ↗

(On Diff #175132)

There is no -verify-debug-info

70 ↗

(On Diff #175132)

This option is unfortunately pulled in from a static constructor defined in`lib/IR/Dominators.cpp`. It is not an llvm-objdump option.

[MaskRay]

BTW, usr.bin/clang/llvm-objdump/llvm-objdump.1 here is not FreeBSD phabricator :) (My biggest complaint there is that for someone who doesn't have a @FreeBSD.org email address, the username is weirdly mangled from the email address and it cannot be changed)

[MaskRay]

usr.bin/clang/llvm-objdump/llvm-objdump.1

12 ↗

(On Diff #175132)

It does not seem very necessary to list all options in SYNOPSIS.

218 ↗

(On Diff #175132)

-print-after-all is a legacy PM option defined in lib/IR/LegacyPassManager.cpp. llvm-objdump doesn't need it.

These cl::opt options should at some point be refactored to use tablegen as llvm-objcopy does...

238 ↗

(On Diff #175132)

It should be accompanied by -full-sections. My preference is that these options are sorted and aligned by their full names and the single-letter aliases follow (not following GNU convention), as what lld/docs/ld.lld1.1 does:

.It Fl -emit-relocs , Fl q
Generate relocations in the output.
.It Fl -enable-new-dtags
Enable new dynamic tags.

[emaste]

In D54864#1307053, @Higuoxing wrote:

lgtm, but seems that some hidden/alias options are not listed here (I could help add them). I am not expert in this area, so I will leave the decision to @kristina

I just based this on the usage output. I will update with added/removed options and we can iterate on it from there.

In D54864#1307061, @MaskRay wrote:

BTW, usr.bin/clang/llvm-objdump/llvm-objdump.1 here is not FreeBSD phabricator :)

Sorry about that :)

Next upload will be from the proper llvm location - since the content is the same I just uploaded the same diff here.

usr.bin/clang/llvm-objdump/llvm-objdump.1

12 ↗

(On Diff #175132)

Same comment was raised in a separate review for FreeBSD in https://reviews.freebsd.org/D18309. Will update.

69 ↗

(On Diff #175132)

Will delete.

70 ↗

(On Diff #175132)

Will delete.

218 ↗

(On Diff #175132)

Will delete.

238 ↗

(On Diff #175132)

It was pointed out in some ld.lld.1 review that preference should be for sorting by short option, but I believe that some of the short options are still not listed in ld.lld.1.

[kristina]

Everything that is explicitly marked as non-hidden should be in the man-page.

These cl::opt options should at some point be refactored to use tablegen as llvm-objcopy does...

Yes that's on my todo list still, been trying to deal with an annoying Clang bug as well as reviewing the Hurd driver for Clang and Hurd's addition to supported OS targets. I wrote up the TableGen file, but still need to fix a lot of help lines as well as clean everything up.

I'll try to get on it ASAP.

[emaste]

Review feedback

[emaste]

usr.bin/clang/llvm-objdump/llvm-objdump.1

218 ↗

(On Diff #175132)

Presumably --print-before-all also.

238 ↗

(On Diff #175132)

Note GNU objdump lists -s|--full-contents

[emaste]

Additional comment that wasn't submitted while reviews.llvm.org was down on Friday: I started working on this as it's needed for us to switch from GNU objdump to llvm-objdump in FreeBSD (FreeBSD PR229046).

As an aside, there are a few outstanding issues in llvm-objdump that we'd like to have addressed (LLVM PRs):
39101 llvm-objdump does not support --demangle
37895 llvm-objdump --help omits many single-letter options
37151 llvm-objdump does not accept -z option
31679 llvm-objdump does not accept combined args as GNU objdump does
30241 llvm-objdump -p omits dynamic headers (in comparison to GNU objdump)
27249 llvm-objdump --dwarf=frames printing wrong values
26892 llvm-objdump -t includes reserved undefined symbol in output, compared with GNU objdump
25124 llvm-objdump prints unknown for relocation info on PPC
21059 llvm-objdump -r reports relocation against symbol `Unknown' on x86
18293 llvm-objdump: warning: invalid instruction encoding
18154 llvm-objdump should have a option to start disassembly at a specified symbol name

It seems that there are option parsing improvements to be made in llvm-objdump, as well as in its usage information. I hope that we can commit this man page and then keep it updates as that work is done.

[MaskRay]

docs/llvm-objdump.1

120

-rng-seed is in lib/Support/RandomNumberGenerator.cpp

145

-time-passes is from a static constructor EnableTiming defined in lib/IR/PassTimingInfo.cpp. It, -stats and -stat-json should also be removed.

[emaste]

I have an interim copy in FreeBSD and am updating it based on the feedback here; I'll update this review shortly.

The FreeBSD version is here: https://svnweb.freebsd.org/base/head/usr.bin/clang/llvm-objdump/llvm-objdump.1?view=annotate

[emaste]

• fix warnings from mandoc -Tlint and/or igor
• remove options that should not be listed

[emaste]

Can I go ahead with this version as a starting point?

[kristina]

LGTM.

[kristina]

Ping for author, this has been approved for a while, do you need this committed?

docs/llvm-objdump.1

 .\" This file is distributed under the University of Illinois Open Source
 .\" License. See LICENSE.TXT for details.
 .\"
-.Dd November 26, 2018
+.Dd December 3, 2018
 .Dt LLVM-OBJDUMP 1
 .Os
 .Sh NAME
 .Nm llvm-objdump
 .Nd LLVM object file dumper
 .Sh SYNOPSIS
 .Nm llvm-objdump
 .Op Ar options

 .It Fl -help
 Display available options.
 Use
 .Fl -help-hidden
 for more.
 .It Fl -lazy-bind
 Display mach-o lazy binding info.
 .It Fl -line-numbers
-Display source line numbers with disassembly. Implies disassemble object.
+Display source line numbers with disassembly.
+Implies disassemble object.
 .It Fl -macho
 Use MachO specific object file parser.
 .It Fl -mattr Ns = Ns Ar attribute ...
 Target specific attributes.
 .It Fl -mcpu Ns = Ns Ar CPU
 Target a specific cpu type.
 Use
 .Fl mcpu Ns = Ns help

 Display format specific file headers.
 .It Fl r
 Display the relocation entries in the file.
 .It Fl -raw-clang-ast
 Dump the raw binary contents of the clang AST section.
 .It Fl -rebase
 Display mach-o rebasing info.
 .It Fl -reverse-iterate
 Reverse iterate.
-.It Fl -rng-seed Ns = Ns Ar seed
-Seed for the random number generator.
 .It Fl s
 Display the content of each section.
 .It Fl -section Ns = Ns Ar section
 Operate on the specified sections only.
 With
 .Fl -macho
 dump segment,section.
 .It Fl -source
 Display source inline with disassembly.
 Implies disassmble object.
 .It Fl -start-address Ns = Ns Ar address
 Disassemble beginning at
 .Ar address .
-.It Fl -stats
-Enable statistics output from program.
-Available with Asserts builds.
-.It Fl -stats-json
-Display statistics as json data.
 .It Fl -stop-address Ns = Ns Ar address
 Stop disassembly at
 .Ar address .
 .It Fl t
 Display the symbol table.
-.It Fl -time-passes
-Time each pass, printing elapsed time for each on exit
 .It Fl -triple Ns = Ns Ar triple
 Target triple to disassemble for.
 See
 .Fl -version
 for available targets.
 .It Fl -unwind-info
 Display unwind information.
 .It Fl -version
 Display the version of this program.
 .It Fl -weak-bind
 Display mach-o weak binding info.
 .It Fl -x86-asm-syntax Ns = Ns Ar syntax
 Choose style of code to emit from X86 backend.
 .Bl -tag -width indent
 .It att

 .Bl -tag -width indent
 .It Fl -archive-headers
 Print archive headers for Mach-O archives.
 .It Fl -archive-member-offsets
 Print the offset to each archive member for Mach-O archives.
 Requires
 .Fl -macho
 and
-.Fl -archive-headers.
+.Fl -archive-headers .
 .It Fl -data-in-code
 Print the data in code table for Mach-O objects.
 .It Fl -dis-symname Ns = Ns Ar symbol
 Disassemble just
 .Ar symbol 's
 instructions.
 .It Fl -dylib-id
 Print the shared library's id for the dylib Mach-O file.