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
+.Dt LLVM-OBJDUMP 1
+.Os
+.Sh NAME
+.Nm llvm-objdump
+.Nd LLVM object file dumper
+.Sh SYNOPSIS
+.Nm llvm-objdump
+.Op Ar options
+.Ar objfile ...
+.Sh DESCRIPTION
+.Nm
+prints the contents of object files and final linked images named on the
+command line.
+If no file name is specified,
+.Nm
+will attempt to read from
+.Pa a.out .
+If
+.Pa -
+is used as a file name,
+.Nm
+will process a file on its standard input stream.
+.Nm
+accepts many of the same command line arguments as GNU objdump.
+.Sh OPTIONS
+.Ss General Options
+.Bl -tag -width indent
+.It Fl -aarch64-neon-syntax Ns = Ns Ar value
+Choose style of NEON code to emit from AArch64 backend.
+.Ar value
+may be one of:
+.Bl -tag -width indent
+.It generic
+Generic NEON assembly
+.It apple
+Apple-style NEON assembly
+.El
+.It Fl -arch Ns = Ns Ar value
+Choose architecture(s) from a Mach-O file to dump
+.It Fl -arch-name Ns = Ns ar arch
+Target arch to disassemble for.
+See
+.Fl -version
+for available targets.
+.It Fl -bind
+Display mach-o binding info.
+.It Fl -color
+Use colored syntax highlighting.
+Default autodetect.
+.It Fl -disassemble
+Display assembler mnemonics for machine instructions.
+.It Fl -disassemble-all
+Display assembler mnemonics for the machine instruction in all sections.
+.It Fl -dsym Ns = Ns Ar file
+Use
+.Ar file
+for debug info.
+.It Fl -dwarf Ns = Ns Ar sections
+Dump of dwarf debug sections.
+.Bl -tag -width indent
+.It frames
+.Dv .debug_frame
+.El
+.It Fl -exports-trie
+Display mach-o exported symbols.
+.It Fl -fault-map-section
+Display contents of faultmap section.
+.It Fl -filter-print-funcs Ns = Ns Ar functions
+Only print IR for functions whose name match
+.Ar functions
+for all print-[before|after][-all] options.
+.It Fl -full-leading-addr
+Print full leading address.
+.It Fl g
+Print line information from debug info if available.
+.It Fl h , -headers , -section-headers
+Display summaries of the headers for each section.
+.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.
+.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
+for details.
+.It Fl -no-leading-addr
+Print no leading address.
+.It Fl -no-leading-headers
+Print no leading headers.
+.It Fl -no-show-raw-insn
+When disassembling instructions, do not print the instruction bytes.
+.It Fl -print-imm-hex
+Use hex format for immediate values.
+.It Fl -private-header
+Display only the first format specific file header.
+.It Fl -private-headers
+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
+Emit AT&T-style assembly.
+.It intel
+Emit Intel-style assembly.
+.El
+.El
+.Ss Mach-O Options
+There are a number of options specific to the Mach-O format.
+These are used in combination with the
+.Fl -macho
+option.
+.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.
+.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.
+.It Fl -dylibs-used
+Print the shared libraries used for linked Mach-O files.
+.It Fl -indirect-symbols
+Print indirect symbol table for Mach-O objects.
+.It Fl -info-plist
+Print the info plist section as strings for Mach-O objects.
+.It Fl -link-opt-hints
+Print the linker optimization hints for Mach-O objects.
+.It Fl -no-symbolic-operands
+do not symbolic operands when disassembling.
+.It Fl -non-verbose
+Print the info for Mach-O objects in non-verbose or numeric form.
+.It Fl -objc-meta-data
+Print the Objective-C runtime meta data for Mach-O files.
+.It Fl -universal-headers
+Print Mach-O universal headers.
+.El