From 5b72ffe827169560b49753e37e6386276a07b32b Mon Sep 17 00:00:00 2001 From: dim Date: Sat, 27 Jun 2020 11:56:49 +0000 Subject: [PATCH] Regenerate ReStructuredText based manpages for llvm-project tools: * bugpoint.1 * clang.1 * llc.1 * lldb.1 * lli.1 * llvm-ar.1 * llvm-as.1 * llvm-bcanalyzer.1 * llvm-cov.1 * llvm-diff.1 * llvm-dis.1 * llvm-dwarfdump.1 * llvm-extract.1 * llvm-link.1 * llvm-mca.1 * llvm-nm.1 * llvm-pdbutil.1 * llvm-profdata.1 * llvm-symbolizer.1 * llvm-tblgen.1 * opt.1 Add newly generated manpages for: * llvm-addr2line.1 (this is an alias of llvm-symbolizer) * llvm-cxxfilt.1 * llvm-objcopy.1 * llvm-ranlib.1 (this is an alias of llvm-ar) Note that llvm-objdump.1 is an exception, as upstream has both a plain .1 file, and a .rst variant. These will have to be reconciled upstream first. MFC after: 3 days --- tools/build/mk/OptionalObsoleteFiles.inc | 1 + usr.bin/clang/bugpoint/bugpoint.1 | 8 +- usr.bin/clang/clang/clang.1 | 37 +- usr.bin/clang/llc/llc.1 | 34 +- usr.bin/clang/lldb/lldb.1 | 72 +- usr.bin/clang/lli/lli.1 | 9 +- usr.bin/clang/llvm-ar/Makefile | 1 + usr.bin/clang/llvm-ar/llvm-ar.1 | 554 +++++++------- usr.bin/clang/llvm-ar/llvm-ranlib.1 | 52 ++ usr.bin/clang/llvm-as/llvm-as.1 | 8 +- .../clang/llvm-bcanalyzer/llvm-bcanalyzer.1 | 8 +- usr.bin/clang/llvm-cov/llvm-cov.1 | 60 +- usr.bin/clang/llvm-cxxfilt/Makefile | 1 - usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 | 117 +++ usr.bin/clang/llvm-diff/llvm-diff.1 | 6 +- usr.bin/clang/llvm-dis/llvm-dis.1 | 8 +- usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1 | 92 ++- usr.bin/clang/llvm-extract/llvm-extract.1 | 8 +- usr.bin/clang/llvm-link/llvm-link.1 | 8 +- usr.bin/clang/llvm-mca/llvm-mca.1 | 523 +++++++++---- usr.bin/clang/llvm-nm/llvm-nm.1 | 316 ++++++-- usr.bin/clang/llvm-objcopy/Makefile | 1 - usr.bin/clang/llvm-objcopy/llvm-objcopy.1 | 721 ++++++++++++++++++ usr.bin/clang/llvm-objdump/llvm-objdump.1 | 7 +- usr.bin/clang/llvm-pdbutil/llvm-pdbutil.1 | 6 +- usr.bin/clang/llvm-profdata/llvm-profdata.1 | 104 ++- usr.bin/clang/llvm-symbolizer/Makefile | 3 + .../clang/llvm-symbolizer/llvm-addr2line.1 | 66 ++ .../clang/llvm-symbolizer/llvm-symbolizer.1 | 459 +++++++++-- usr.bin/clang/llvm-tblgen/llvm-tblgen.1 | 11 +- usr.bin/clang/opt/opt.1 | 6 +- 31 files changed, 2615 insertions(+), 692 deletions(-) create mode 100644 usr.bin/clang/llvm-ar/llvm-ranlib.1 create mode 100644 usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 create mode 100644 usr.bin/clang/llvm-objcopy/llvm-objcopy.1 create mode 100644 usr.bin/clang/llvm-symbolizer/llvm-addr2line.1 diff --git a/tools/build/mk/OptionalObsoleteFiles.inc b/tools/build/mk/OptionalObsoleteFiles.inc index f2633da40351..159ce799bb25 100644 --- a/tools/build/mk/OptionalObsoleteFiles.inc +++ b/tools/build/mk/OptionalObsoleteFiles.inc @@ -1191,6 +1191,7 @@ OLD_FILES+=usr/bin/clang OLD_FILES+=usr/bin/clang++ OLD_FILES+=usr/bin/clang-cpp OLD_FILES+=usr/bin/clang-tblgen +OLD_FILES+=usr/bin/llvm-addr2line OLD_FILES+=usr/bin/llvm-ar OLD_FILES+=usr/bin/llvm-nm OLD_FILES+=usr/bin/llvm-objdump diff --git a/usr.bin/clang/bugpoint/bugpoint.1 b/usr.bin/clang/bugpoint/bugpoint.1 index 336a9c9c6803..867ceef3325c 100644 --- a/usr.bin/clang/bugpoint/bugpoint.1 +++ b/usr.bin/clang/bugpoint/bugpoint.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "BUGPOINT" "1" "2018-08-02" "7" "LLVM" +.TH "BUGPOINT" "1" "2020-06-26" "10" "LLVM" .SH NAME bugpoint \- automatic test case reduction tool . @@ -300,10 +300,10 @@ If \fBbugpoint\fP succeeds in finding a problem, it will exit with 0. Otherwise if an error occurs, it will exit with a non\-zero value. .SH SEE ALSO .sp -opt|opt +\fBopt(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/clang/clang.1 b/usr.bin/clang/clang/clang.1 index 0220ea7fee5c..1d3e9889da80 100644 --- a/usr.bin/clang/clang/clang.1 +++ b/usr.bin/clang/clang/clang.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "CLANG" "1" "Aug 02, 2018" "7" "Clang" +.TH "CLANG" "1" "2020-06-26" "10" "Clang" .SH NAME clang \- the Clang C, C++, and Objective-C compiler . @@ -89,7 +89,7 @@ an "a.out", ".dylib" or ".so" file. .sp The Clang Static Analyzer is a tool that scans source code to try to find bugs through code analysis. This tool uses many parts of Clang and is built into -the same driver. Please see <\fI\%http://clang\-analyzer.llvm.org\fP> for more details +the same driver. Please see <\fI\%https://clang\-analyzer.llvm.org\fP> for more details on how to use the static analyzer. .SH OPTIONS .SS Stage Selection Options @@ -458,8 +458,21 @@ strings and other optimizations. .UNINDENT .INDENT 0.0 .TP -.B \-flax\-vector\-conversions +.B \-flax\-vector\-conversions, \-flax\-vector\-conversions=, \-fno\-lax\-vector\-conversions Allow loose type checking rules for implicit vector conversions. +Possible values of : +.INDENT 7.0 +.IP \(bu 2 +\fBnone\fP: allow no implicit conversions between vectors +.IP \(bu 2 +\fBinteger\fP: allow implicit bitcasts between integer vectors of the same +overall bit\-width +.IP \(bu 2 +\fBall\fP: allow implicit bitcasts between any vectors of the same +overall bit\-width +.UNINDENT +.sp + defaults to \fBinteger\fP if unspecified. .UNINDENT .INDENT 0.0 .TP @@ -499,7 +512,7 @@ Specify the architecture to build for. .INDENT 0.0 .TP .B \-mmacosx\-version\-min= -When building for Mac OS X, specify the minimum version supported by your +When building for macOS, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 @@ -510,6 +523,18 @@ application. .UNINDENT .INDENT 0.0 .TP +.B \-\-print\-supported\-cpus +Print out a list of supported processors for the given target (specified +through \-\-target= or \-arch ). If no target is +specified, the system default target will be used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-mcpu=?, \-mtune=? +Aliases of \-\-print\-supported\-cpus +.UNINDENT +.INDENT 0.0 +.TP .B \-march= Specify that Clang should generate code for a specific processor family member and later. For example, if you specify \-march=i486, the compiler is @@ -848,7 +873,7 @@ Darwin targets. .UNINDENT .SH BUGS .sp -To report bugs, please visit <\fI\%http://llvm.org/bugs/\fP>. Most bug reports should +To report bugs, please visit <\fI\%https://bugs.llvm.org/\fP>. Most bug reports should include preprocessed source files (use the \fI\%\-E\fP option) and the full output of the compiler, along with information to reproduce. .SH SEE ALSO @@ -857,6 +882,6 @@ output of the compiler, along with information to reproduce. .SH AUTHOR Maintained by the Clang / LLVM Team () .SH COPYRIGHT -2007-2018, The Clang Team +2007-2020, The Clang Team .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llc/llc.1 b/usr.bin/clang/llc/llc.1 index d37f6d12f3d9..cef6fa918bd1 100644 --- a/usr.bin/clang/llc/llc.1 +++ b/usr.bin/clang/llc/llc.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLC" "1" "2018-08-02" "7" "LLVM" +.TH "LLC" "1" "2020-06-26" "10" "LLVM" .SH NAME llc \- LLVM static compiler . @@ -41,7 +41,7 @@ for a specified architecture. The assembly language output can then be passed through a native assembler and linker to generate a native executable. .sp The choice of architecture for the output assembly code is automatically -determined from the input file, unless the \fB\-march\fP option is used to +determined from the input file, unless the \fI\%\-march\fP option is used to override the default. .SH OPTIONS .sp @@ -49,11 +49,11 @@ If \fBfilename\fP is "\fB\-\fP" or omitted, \fBllc\fP reads from standard input. Otherwise, it will from \fBfilename\fP\&. Inputs can be in either the LLVM assembly language format (\fB\&.ll\fP) or the LLVM bitcode format (\fB\&.bc\fP). .sp -If the \fB\-o\fP option is omitted, then \fBllc\fP will send its output -to standard output if the input is from standard input. If the \fB\-o\fP +If the \fI\%\-o\fP option is omitted, then \fBllc\fP will send its output +to standard output if the input is from standard input. If the \fI\%\-o\fP option specifies "\fB\-\fP", then the output will also be sent to standard output. .sp -If no \fB\-o\fP option is specified and an input file other than "\fB\-\fP" is +If no \fI\%\-o\fP option is specified and an input file other than "\fB\-\fP" is specified, then \fBllc\fP creates the output filename by taking the input filename, removing any existing \fB\&.bc\fP extension, and adding a \fB\&.s\fP suffix. .sp @@ -66,6 +66,12 @@ Print a summary of command line options. .UNINDENT .INDENT 0.0 .TP +.B \-o +Use \fB\fP as the output filename. See the summary above for more +details. +.UNINDENT +.INDENT 0.0 +.TP .B \-O=uint Generate code at different optimization levels. These correspond to the \fB\-O0\fP, \fB\-O1\fP, \fB\-O2\fP, and \fB\-O3\fP optimization levels used by @@ -130,8 +136,8 @@ llvm\-as < /dev/null | llc \-march=xyz \-mattr=help .UNINDENT .INDENT 0.0 .TP -.B \-\-disable\-fp\-elim -Disable frame pointer elimination optimization. +.B \-\-frame\-pointer +Specify effect of frame pointer elimination optimization (all,non\-leaf,none). .UNINDENT .INDENT 0.0 .TP @@ -174,7 +180,7 @@ error. .B \-\-load= Dynamically load \fBdso_path\fP (a path to a dynamically shared object) that implements an LLVM target. This will permit the target name to be used with -the \fB\-march\fP option so that code can be generated for that target. +the \fI\%\-march\fP option so that code can be generated for that target. .UNINDENT .INDENT 0.0 .TP @@ -191,6 +197,12 @@ sizes (unsigned LEB128). The stack size values only include the space allocated in the function prologue. Functions with dynamic stack allocations are not included. .UNINDENT +.INDENT 0.0 +.TP +.B \-remarks\-section +Emit the __remarks (MachO) section which contains metadata about remark +diagnostics. +.UNINDENT .SS Tuning/Configuration Options .INDENT 0.0 .TP @@ -265,10 +277,10 @@ If \fBllc\fP succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non\-zero value. .SH SEE ALSO .sp -lli +\fBlli(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/lldb/lldb.1 b/usr.bin/clang/lldb/lldb.1 index 0d800d4a71e6..f4196e248a55 100644 --- a/usr.bin/clang/lldb/lldb.1 +++ b/usr.bin/clang/lldb/lldb.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLDB" "1" "Jan 27, 2020" "8" "LLDB" +.TH "LLDB" "1" "2020-06-26" "8" "LLDB" .SH NAME lldb \- LLDB Documentation . @@ -61,12 +61,12 @@ Tells the debugger to attach to a process with the given pid. .INDENT 0.0 .TP .B \-n -Alias for –attach\-name +Alias for \-\-attach\-name .UNINDENT .INDENT 0.0 .TP .B \-p -Alias for –attach\-pid +Alias for \-\-attach\-pid .UNINDENT .INDENT 0.0 .TP @@ -76,7 +76,7 @@ Tells the debugger to wait for a process with the given pid or name to launch be .INDENT 0.0 .TP .B \-w -Alias for –wait\-for +Alias for \-\-wait\-for .UNINDENT .SH COMMANDS .INDENT 0.0 @@ -87,27 +87,27 @@ Tells the debugger to run the commands from \-s, \-S, \-o & \-O, and then quit. .INDENT 0.0 .TP .B \-b -Alias for –batch +Alias for \-\-batch .UNINDENT .INDENT 0.0 .TP .B \-K -Alias for –source\-on\-crash +Alias for \-\-source\-on\-crash .UNINDENT .INDENT 0.0 .TP .B \-k -Alias for –one\-line\-on\-crash +Alias for \-\-one\-line\-on\-crash .UNINDENT .INDENT 0.0 .TP .B \-\-local\-lldbinit -Allow the debugger to parse the .lldbinit files in the current working directory, unless –no\-lldbinit is passed. +Allow the debugger to parse the .lldbinit files in the current working directory, unless \-\-no\-lldbinit is passed. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-lldbinit -Do not automatically parse any ‘.lldbinit’ files. +Do not automatically parse any \(aq.lldbinit\(aq files. .UNINDENT .INDENT 0.0 .TP @@ -127,17 +127,17 @@ Tells the debugger to execute this one\-line lldb command after any file provide .INDENT 0.0 .TP .B \-O -Alias for –one\-line\-before\-file +Alias for \-\-one\-line\-before\-file .UNINDENT .INDENT 0.0 .TP .B \-o -Alias for –one\-line +Alias for \-\-one\-line .UNINDENT .INDENT 0.0 .TP .B \-Q -Alias for –source\-quietly +Alias for \-\-source\-quietly .UNINDENT .INDENT 0.0 .TP @@ -162,17 +162,17 @@ Tells the debugger to read in and execute the lldb commands in the given file, a .INDENT 0.0 .TP .B \-S -Alias for –source\-before\-file +Alias for \-\-source\-before\-file .UNINDENT .INDENT 0.0 .TP .B \-s -Alias for –source +Alias for \-\-source .UNINDENT .INDENT 0.0 .TP .B \-x -Alias for –no\-lldbinit +Alias for \-\-no\-lldbinit .UNINDENT .SH OPTIONS .INDENT 0.0 @@ -183,7 +183,7 @@ Tells the debugger to use the specified architecture when starting and running t .INDENT 0.0 .TP .B \-a -Alias for –arch +Alias for \-\-arch .UNINDENT .INDENT 0.0 .TP @@ -203,7 +203,7 @@ Tells the debugger to use the full path to as the core file. .INDENT 0.0 .TP .B \-c -Alias for –core +Alias for \-\-core .UNINDENT .INDENT 0.0 .TP @@ -213,17 +213,17 @@ Tells the debugger to print out extra information for debugging itself. .INDENT 0.0 .TP .B \-d -Alias for –debug +Alias for \-\-debug .UNINDENT .INDENT 0.0 .TP .B \-\-editor -Tells the debugger to open source files using the host’s “external editor” mechanism. +Tells the debugger to open source files using the host\(aqs "external editor" mechanism. .UNINDENT .INDENT 0.0 .TP .B \-e -Alias for –editor +Alias for \-\-editor .UNINDENT .INDENT 0.0 .TP @@ -233,7 +233,7 @@ Tells the debugger to use the file as the program to be debugged. .INDENT 0.0 .TP .B \-f -Alias for –file +Alias for \-\-file .UNINDENT .INDENT 0.0 .TP @@ -243,7 +243,7 @@ Prints out the usage information for the LLDB debugger. .INDENT 0.0 .TP .B \-h -Alias for –help +Alias for \-\-help .UNINDENT .INDENT 0.0 .TP @@ -263,18 +263,18 @@ Prints out the current version number of the LLDB debugger. .INDENT 0.0 .TP .B \-v -Alias for –version +Alias for \-\-version .UNINDENT .INDENT 0.0 .TP .B \-X -Alias for –no\-use\-color +Alias for \-\-no\-use\-color .UNINDENT .SH REPL .INDENT 0.0 .TP .B \-r= -Alias for –repl= +Alias for \-\-repl= .UNINDENT .INDENT 0.0 .TP @@ -289,13 +289,13 @@ Runs lldb in REPL mode with a stub process with the given flags. .INDENT 0.0 .TP .B \-R -Alias for –repl\-language +Alias for \-\-repl\-language .UNINDENT .SH SCRIPTING .INDENT 0.0 .TP .B \-l -Alias for –script\-language +Alias for \-\-script\-language .UNINDENT .INDENT 0.0 .TP @@ -305,7 +305,7 @@ Prints out the path to the lldb.py file for this version of lldb. .INDENT 0.0 .TP .B \-P -Alias for –python\-path +Alias for \-\-python\-path .UNINDENT .INDENT 0.0 .TP @@ -317,11 +317,11 @@ Tells the debugger to use the specified scripting language for user\-defined scr The debugger can be started in several modes. .sp Passing an executable as a positional argument prepares \fBlldb\fP to -debug the given executable. Arguments passed after – are considered arguments +debug the given executable. Arguments passed after \-\- are considered arguments to the debugged executable. .INDENT 0.0 .INDENT 3.5 -lldb –arch x86_64 /path/to/program – –arch arvm7 +lldb \-\-arch x86_64 /path/to/program \-\- \-\-arch arvm7 .UNINDENT .UNINDENT .sp @@ -334,14 +334,14 @@ lldb \-n .UNINDENT .UNINDENT .sp -Passing –repl starts \fBlldb\fP in REPL mode. +Passing \-\-repl starts \fBlldb\fP in REPL mode. .INDENT 0.0 .INDENT 3.5 lldb \-r .UNINDENT .UNINDENT .sp -Passing –core causes \fBlldb\fP to debug the core file. +Passing \-\-core causes \fBlldb\fP to debug the core file. .INDENT 0.0 .INDENT 3.5 lldb \-c /path/to/core @@ -353,7 +353,7 @@ run the specified commands before or after events, like loading the file or crashing, in the order provided on the command line. .INDENT 0.0 .INDENT 3.5 -lldb \-O ‘settings set stop\-disassembly\-count 20’ \-o ‘run’ \-o ‘bt’ +lldb \-O \(aqsettings set stop\-disassembly\-count 20\(aq \-o \(aqrun\(aq \-o \(aqbt\(aq lldb \-S /source/before/file \-s /source/after/file lldb \-K /source/before/crash \-k /source/after/crash .UNINDENT @@ -365,12 +365,12 @@ loading the file (via \-o or \-s) will be ignored. .sp In \fBlldb\fP there is a help command which can be used to find descriptions and examples of all \fBlldb\fP commands. To get help on -“breakpoint set” you would type “help breakpoint set”. +"breakpoint set" you would type "help breakpoint set". .sp There is also an apropos command which will search the help text of all commands for a given term ‐‐ this is useful for locating a command by topic. -For instance, “apropos breakpoint” will list any command that has the word -“breakpoint” in its help text. +For instance, "apropos breakpoint" will list any command that has the word +"breakpoint" in its help text. .SH CONFIGURATION FILES .sp \fBlldb\fP reads things like settings, aliases and commands from the diff --git a/usr.bin/clang/lli/lli.1 b/usr.bin/clang/lli/lli.1 index e6bcda65395e..4a54e2f527cf 100644 --- a/usr.bin/clang/lli/lli.1 +++ b/usr.bin/clang/lli/lli.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLI" "1" "2018-08-02" "7" "LLVM" +.TH "LLI" "1" "2020-06-26" "10" "LLVM" .SH NAME lli \- directly execute programs from LLVM bitcode . @@ -162,6 +162,7 @@ Choose the code model from: .nf .ft C default: Target default code model +tiny: Tiny code model small: Small code model kernel: Kernel code model medium: Medium code model @@ -289,10 +290,10 @@ If \fBlli\fP fails to load the program, it will exit with an exit code of 1. Otherwise, it will return the exit code of the program it executes. .SH SEE ALSO .sp -\fBllc\fP +\fBllc(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-ar/Makefile b/usr.bin/clang/llvm-ar/Makefile index e5ac6d54ac5b..86d4538271a1 100644 --- a/usr.bin/clang/llvm-ar/Makefile +++ b/usr.bin/clang/llvm-ar/Makefile @@ -1,6 +1,7 @@ # $FreeBSD$ PROG_CXX= llvm-ar +MAN= llvm-ar.1 llvm-ranlib.1 SRCDIR= llvm/tools/llvm-ar SRCS+= llvm-ar.cpp diff --git a/usr.bin/clang/llvm-ar/llvm-ar.1 b/usr.bin/clang/llvm-ar/llvm-ar.1 index bb9346377a23..f7cbe4076c20 100644 --- a/usr.bin/clang/llvm-ar/llvm-ar.1 +++ b/usr.bin/clang/llvm-ar/llvm-ar.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-AR" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-AR" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-ar \- LLVM archiver . @@ -33,358 +33,388 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -\fBllvm\-ar\fP [\-]{dmpqrtx}[Rabfikou] [relpos] [count] [files...] +\fBllvm\-ar\fP [\-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...] .SH DESCRIPTION .sp -The \fBllvm\-ar\fP command is similar to the common Unix utility, \fBar\fP\&. It -archives several files together into a single file. The intent for this is -to produce archive libraries by LLVM bitcode that can be linked into an -LLVM program. However, the archive can contain any kind of file. By default, -\fBllvm\-ar\fP generates a symbol table that makes linking faster because -only the symbol table needs to be consulted, not each individual file member -of the archive. +The \fBllvm\-ar\fP command is similar to the common Unix utility, +\fBar\fP\&. It archives several files, such as objects and LLVM bitcode +files into a single archive library that can be linked into a program. However, +the archive can contain any kind of file. By default, \fBllvm\-ar\fP +generates a symbol table that makes linking faster because only the symbol +table needs to be consulted, not each individual file member of the archive. .sp -The \fBllvm\-ar\fP command can be used to \fIread\fP SVR4, GNU and BSD style archive -files. However, right now it can only write in the GNU format. If an -SVR4 or BSD style archive is used with the \fBr\fP (replace) or \fBq\fP (quick -update) operations, the archive will be reconstructed in GNU format. +The \fBllvm\-ar\fP command can be used to \fIread\fP archive files in SVR4, +GNU, BSD and Darwin format, and \fIwrite\fP in the GNU, BSD, and Darwin style +archive files. If an SVR4 format archive is used with the \fI\%r\fP +(replace), \fI\%d\fP (delete), \fI\%m\fP (move) or \fI\%q\fP +(quick update) operations, the archive will be reconstructed in the format +defined by \fI\%\-\-format\fP\&. .sp -Here\(aqs where \fBllvm\-ar\fP departs from previous \fBar\fP implementations: +Here\(aqs where \fBllvm\-ar\fP departs from previous \fBar\fP +implementations: +.sp +\fIThe following option is not supported\fP +.INDENT 0.0 +.INDENT 3.5 +[f] \- truncate inserted filenames +.UNINDENT +.UNINDENT +.sp +\fIThe following options are ignored for compatibility\fP +.INDENT 0.0 +.INDENT 3.5 +\-\-plugin= \- load a plugin which adds support for other file formats +.sp +[l] \- ignored in \fBar\fP +.UNINDENT +.UNINDENT .sp \fISymbol Table\fP .INDENT 0.0 .INDENT 3.5 -Since \fBllvm\-ar\fP supports bitcode files. The symbol table it creates -is in GNU format and includes both native and bitcode files. +Since \fBllvm\-ar\fP supports bitcode files, the symbol table it creates +includes both native and bitcode symbols. .UNINDENT .UNINDENT .sp -\fILong Paths\fP +\fIDeterministic Archives\fP .INDENT 0.0 .INDENT 3.5 -Currently \fBllvm\-ar\fP can read GNU and BSD long file names, but only writes -archives with the GNU format. +By default, \fBllvm\-ar\fP always uses zero for timestamps and UIDs/GIDs +to write archives in a deterministic mode. This is equivalent to the +\fI\%D\fP modifier being enabled by default. If you wish to maintain +compatibility with other \fBar\fP implementations, you can pass the +\fI\%U\fP modifier to write actual timestamps and UIDs/GIDs. +.UNINDENT +.UNINDENT +.sp +\fIWindows Paths\fP +.INDENT 0.0 +.INDENT 3.5 +When on Windows \fBllvm\-ar\fP treats the names of archived \fIfiles\fP in the same +case sensitive manner as the operating system. When on a non\-Windows machine +\fBllvm\-ar\fP does not consider character case. .UNINDENT .UNINDENT .SH OPTIONS .sp -The options to \fBllvm\-ar\fP are compatible with other \fBar\fP implementations. -However, there are a few modifiers (\fIR\fP) that are not found in other \fBar\fP -implementations. The options to \fBllvm\-ar\fP specify a single basic operation to -perform on the archive, a variety of modifiers for that operation, the name of -the archive file, and an optional list of file names. These options are used to -determine how \fBllvm\-ar\fP should process the archive file. +\fBllvm\-ar\fP operations are compatible with other \fBar\fP +implementations. However, there are a few modifiers (\fI\%L\fP) that are not +found in other \fBar\fP implementations. The options for +\fBllvm\-ar\fP specify a single basic Operation to perform on the archive, +a variety of Modifiers for that Operation, the name of the archive file, and an +optional list of file names. If the \fIfiles\fP option is not specified, it +generally means either "none" or "all" members, depending on the operation. The +Options, Operations and Modifiers are explained in the sections below. .sp -The Operations and Modifiers are explained in the sections below. The minimal -set of options is at least one operator and the name of the archive. Typically -archive files end with a \fB\&.a\fP suffix, but this is not required. Following -the \fIarchive\-name\fP comes a list of \fIfiles\fP that indicate the specific members -of the archive to operate on. If the \fIfiles\fP option is not specified, it -generally means either "none" or "all" members, depending on the operation. +The minimal set of options is at least one operator and the name of the +archive. .SS Operations -.sp -d .INDENT 0.0 -.INDENT 3.5 -Delete files from the archive. No modifiers are applicable to this operation. -The \fIfiles\fP options specify which members should be removed from the -archive. It is not an error if a specified file does not appear in the archive. -If no \fIfiles\fP are specified, the archive is not modified. +.TP +.B d [NT] +Delete files from the \fBarchive\fP\&. The \fI\%N\fP and \fI\%T\fP modifiers +apply to this operation. The \fIfiles\fP options specify which members should be +removed from the archive. It is not an error if a specified file does not +appear in the archive. If no \fIfiles\fP are specified, the archive is not +modified. .UNINDENT -.UNINDENT -.sp -m[abi] .INDENT 0.0 -.INDENT 3.5 -Move files from one location in the archive to another. The \fIa\fP, \fIb\fP, and -\fIi\fP modifiers apply to this operation. The \fIfiles\fP will all be moved -to the location given by the modifiers. If no modifiers are used, the files -will be moved to the end of the archive. If no \fIfiles\fP are specified, the -archive is not modified. +.TP +.B m [abi] +Move files from one location in the \fBarchive\fP to another. The \fI\%a\fP, +\fI\%b\fP, and \fI\%i\fP modifiers apply to this operation. The \fIfiles\fP +will all be moved to the location given by the modifiers. If no modifiers are +used, the files will be moved to the end of the archive. If no \fIfiles\fP are +specified, the archive is not modified. .UNINDENT -.UNINDENT -.sp -p .INDENT 0.0 -.INDENT 3.5 -Print files to the standard output. This operation simply prints the -\fIfiles\fP indicated to the standard output. If no \fIfiles\fP are -specified, the entire archive is printed. Printing bitcode files is -ill\-advised as they might confuse your terminal settings. The \fIp\fP -operation never modifies the archive. +.TP +.B p [v] +Print \fIfiles\fP to the standard output stream. If no \fIfiles\fP are specified, the +entire \fBarchive\fP is printed. With the \fI\%v\fP modifier, +\fBllvm\-ar\fP also prints out the name of the file being output. Printing +binary files is ill\-advised as they might confuse your terminal settings. The +\fI\%p\fP operation never modifies the archive. .UNINDENT -.UNINDENT -.sp -q .INDENT 0.0 -.INDENT 3.5 -Quickly append files to the end of the archive. This operation quickly adds the -\fIfiles\fP to the archive without checking for duplicates that should be -removed first. If no \fIfiles\fP are specified, the archive is not modified. -Because of the way that \fBllvm\-ar\fP constructs the archive file, its dubious -whether the \fIq\fP operation is any faster than the \fIr\fP operation. +.TP +.B q [LT] +Quickly append files to the end of the \fBarchive\fP without removing +duplicates. If no \fIfiles\fP are specified, the archive is not modified. The +behavior when appending one archive to another depends upon whether the +\fI\%L\fP and \fI\%T\fP modifiers are used: +.INDENT 7.0 +.IP \(bu 2 +Appending a regular archive to a regular archive will append the archive +file. If the \fI\%L\fP modifier is specified the members will be appended +instead. +.IP \(bu 2 +Appending a regular archive to a thin archive requires the \fI\%T\fP +modifier and will append the archive file. The \fI\%L\fP modifier is not +supported. +.IP \(bu 2 +Appending a thin archive to a regular archive will append the archive file. +If the \fI\%L\fP modifier is specified the members will be appended +instead. +.IP \(bu 2 +Appending a thin archive to a thin archive will always quick append its +members. .UNINDENT .UNINDENT -.sp -r[abu] .INDENT 0.0 -.INDENT 3.5 -Replace or insert file members. The \fIa\fP, \fIb\fP, and \fIu\fP -modifiers apply to this operation. This operation will replace existing -\fIfiles\fP or insert them at the end of the archive if they do not exist. If no -\fIfiles\fP are specified, the archive is not modified. -.UNINDENT +.TP +.B r [abTu] +Replace existing \fIfiles\fP or insert them at the end of the \fBarchive\fP if +they do not exist. The \fI\%a\fP, \fI\%b\fP, \fI\%T\fP and \fI\%u\fP +modifiers apply to this operation. If no \fIfiles\fP are specified, the archive +is not modified. .UNINDENT .sp t[v] +.. option:: t [vO] .INDENT 0.0 .INDENT 3.5 Print the table of contents. Without any modifiers, this operation just prints -the names of the members to the standard output. With the \fIv\fP modifier, -\fBllvm\-ar\fP also prints out the file type (B=bitcode, S=symbol -table, blank=regular file), the permission mode, the owner and group, the -size, and the date. If any \fIfiles\fP are specified, the listing is only for -those files. If no \fIfiles\fP are specified, the table of contents for the -whole archive is printed. +the names of the members to the standard output stream. With the \fI\%v\fP +modifier, \fBllvm\-ar\fP also prints out the file type (B=bitcode, +S=symbol table, blank=regular file), the permission mode, the owner and group, +are ignored when extracting \fIfiles\fP and set to placeholder values when adding +size, and the date. With the \fI\%O\fP modifier, display member offsets. If +any \fIfiles\fP are specified, the listing is only for those files. If no \fIfiles\fP +are specified, the table of contents for the whole archive is printed. .UNINDENT .UNINDENT -.sp -x[oP] .INDENT 0.0 -.INDENT 3.5 -Extract archive members back to files. The \fIo\fP modifier applies to this -operation. This operation retrieves the indicated \fIfiles\fP from the archive -and writes them back to the operating system\(aqs file system. If no -\fIfiles\fP are specified, the entire archive is extract. +.TP +.B V +A synonym for the \fI\%\-\-version\fP option. .UNINDENT +.INDENT 0.0 +.TP +.B x [oP] +Extract \fBarchive\fP members back to files. The \fI\%o\fP modifier applies +to this operation. This operation retrieves the indicated \fIfiles\fP from the +archive and writes them back to the operating system\(aqs file system. If no +\fIfiles\fP are specified, the entire archive is extracted. .UNINDENT .SS Modifiers (operation specific) .sp The modifiers below are specific to certain operations. See the Operations -section (above) to determine which modifiers are applicable to which operations. -.sp -[a] +section to determine which modifiers are applicable to which operations. .INDENT 0.0 -.INDENT 3.5 -When inserting or moving member files, this option specifies the destination of -the new files as being after the \fIrelpos\fP member. If \fIrelpos\fP is not found, -the files are placed at the end of the archive. +.TP +.B a +When inserting or moving member files, this option specifies the destination +of the new files as being after the \fIrelpos\fP member. If \fIrelpos\fP is not found, +the files are placed at the end of the \fBarchive\fP\&. \fIrelpos\fP cannot be +consumed without either \fI\%a\fP, \fI\%b\fP or \fI\%i\fP\&. .UNINDENT -.UNINDENT -.sp -[b] .INDENT 0.0 -.INDENT 3.5 -When inserting or moving member files, this option specifies the destination of -the new files as being before the \fIrelpos\fP member. If \fIrelpos\fP is not -found, the files are placed at the end of the archive. This modifier is -identical to the \fIi\fP modifier. +.TP +.B b +When inserting or moving member files, this option specifies the destination +of the new files as being before the \fIrelpos\fP member. If \fIrelpos\fP is not +found, the files are placed at the end of the \fBarchive\fP\&. \fIrelpos\fP cannot +be consumed without either \fI\%a\fP, \fI\%b\fP or \fI\%i\fP\&. This +modifier is identical to the \fI\%i\fP modifier. .UNINDENT -.UNINDENT -.sp -[i] .INDENT 0.0 -.INDENT 3.5 -A synonym for the \fIb\fP option. +.TP +.B i +A synonym for the \fI\%b\fP option. .UNINDENT -.UNINDENT -.sp -[o] .INDENT 0.0 -.INDENT 3.5 -When extracting files, this option will cause \fBllvm\-ar\fP to preserve the -original modification times of the files it writes. +.TP +.B L +When quick appending an \fBarchive\fP, instead quick append its members. This +is a feature for \fBllvm\-ar\fP that is not found in gnu\-ar. .UNINDENT -.UNINDENT -.sp -[u] .INDENT 0.0 -.INDENT 3.5 -When replacing existing files in the archive, only replace those files that have -a time stamp than the time stamp of the member in the archive. +.TP +.B N +When extracting or deleting a member that shares its name with another member, +the \fIcount\fP parameter allows you to supply a positive whole number that +selects the instance of the given name, with "1" indicating the first +instance. If \fI\%N\fP is not specified the first member of that name will +be selected. If \fIcount\fP is not supplied, the operation fails.*count* cannot be .UNINDENT +.INDENT 0.0 +.TP +.B o +When extracting files, use the modification times of any \fIfiles\fP as they +appear in the \fBarchive\fP\&. By default \fIfiles\fP extracted from the archive +use the time of extraction. +.UNINDENT +.INDENT 0.0 +.TP +.B O +Display member offsets inside the archive. +.UNINDENT +.INDENT 0.0 +.TP +.B T +When creating or modifying an archive, this option specifies that the +\fBarchive\fP will be thin. By default, archives are not created as thin +archives and when modifying a thin archive, it will be converted to a regular +archive. +.UNINDENT +.INDENT 0.0 +.TP +.B v +When printing \fIfiles\fP or the \fBarchive\fP table of contents, this modifier +instructs \fBllvm\-ar\fP to include additional information in the output. .UNINDENT .SS Modifiers (generic) .sp The modifiers below may be applied to any operation. -.sp -[c] .INDENT 0.0 -.INDENT 3.5 -For all operations, \fBllvm\-ar\fP will always create the archive if it doesn\(aqt -exist. Normally, \fBllvm\-ar\fP will print a warning message indicating that the -archive is being created. Using this modifier turns off that warning. +.TP +.B c +For the \fI\%r\fP (replace)and \fI\%q\fP (quick update) operations, +\fBllvm\-ar\fP will always create the archive if it doesn\(aqt exist. +Normally, \fBllvm\-ar\fP will print a warning message indicating that the +\fBarchive\fP is being created. Using this modifier turns off +that warning. .UNINDENT -.UNINDENT -.sp -[s] .INDENT 0.0 -.INDENT 3.5 +.TP +.B D +Use zero for timestamps and UIDs/GIDs. This is set by default. +.UNINDENT +.INDENT 0.0 +.TP +.B P +Use full paths when matching member names rather than just the file name. +This can be useful when manipulating an \fBarchive\fP generated by another +archiver, as some allow paths as member names. This is the default behavior +for thin archives. +.UNINDENT +.INDENT 0.0 +.TP +.B s This modifier requests that an archive index (or symbol table) be added to the -archive. This is the default mode of operation. The symbol table will contain -all the externally visible functions and global variables defined by all the -bitcode files in the archive. +\fBarchive\fP, as if using ranlib. The symbol table will contain all the +externally visible functions and global variables defined by all the bitcode +files in the archive. By default \fBllvm\-ar\fP generates symbol tables in +archives. This can also be used as an operation. .UNINDENT -.UNINDENT -.sp -[S] .INDENT 0.0 -.INDENT 3.5 -This modifier is the opposite of the \fIs\fP modifier. It instructs \fBllvm\-ar\fP to -not build the symbol table. If both \fIs\fP and \fIS\fP are used, the last modifier to -occur in the options will prevail. +.TP +.B S +This modifier is the opposite of the \fI\%s\fP modifier. It instructs +\fBllvm\-ar\fP to not build the symbol table. If both \fI\%s\fP and +\fI\%S\fP are used, the last modifier to occur in the options will prevail. .UNINDENT -.UNINDENT -.sp -[v] .INDENT 0.0 -.INDENT 3.5 -This modifier instructs \fBllvm\-ar\fP to be verbose about what it is doing. Each -editing operation taken against the archive will produce a line of output saying -what is being done. +.TP +.B u +Only update \fBarchive\fP members with \fIfiles\fP that have more recent +timestamps. .UNINDENT -.UNINDENT -.SH STANDARDS -.sp -The \fBllvm\-ar\fP utility is intended to provide a superset of the IEEE Std 1003.2 -(POSIX.2) functionality for \fBar\fP\&. \fBllvm\-ar\fP can read both SVR4 and BSD4.4 (or -Mac OS X) archives. If the \fBf\fP modifier is given to the \fBx\fP or \fBr\fP operations -then \fBllvm\-ar\fP will write SVR4 compatible archives. Without this modifier, -\fBllvm\-ar\fP will write BSD4.4 compatible archives that have long names -immediately after the header and indicated using the "#1/ddd" notation for the -name in the header. -.SH FILE FORMAT -.sp -The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX -archive files. In fact, except for the symbol table, the \fBar\fP commands on those -operating systems should be able to read LLVM archive files. The details of the -file format follow. -.sp -Each archive begins with the archive magic number which is the eight printable -characters "!n" where n represents the newline character (0x0A). -Following the magic number, the file is composed of even length members that -begin with an archive header and end with a n padding character if necessary -(to make the length even). Each file member is composed of a header (defined -below), an optional newline\-terminated "long file name" and the contents of -the file. -.sp -The fields of the header are described in the items below. All fields of the -header contain only ASCII characters, are left justified and are right padded -with space characters. -.sp -name \- char[16] .INDENT 0.0 -.INDENT 3.5 -This field of the header provides the name of the archive member. If the name is -longer than 15 characters or contains a slash (/) character, then this field -contains \fB#1/nnn\fP where \fBnnn\fP provides the length of the name and the \fB#1/\fP -is literal. In this case, the actual name of the file is provided in the \fBnnn\fP -bytes immediately following the header. If the name is 15 characters or less, it -is contained directly in this field and terminated with a slash (/) character. +.TP +.B U +Use actual timestamps and UIDs/GIDs. .UNINDENT -.UNINDENT -.sp -date \- char[12] +.SS Other .INDENT 0.0 -.INDENT 3.5 -This field provides the date of modification of the file in the form of a -decimal encoded number that provides the number of seconds since the epoch -(since 00:00:00 Jan 1, 1970) per Posix specifications. +.TP +.B \-\-format= +This option allows for default, gnu, darwin or bsd \fB\fP to be selected. +When creating an \fBarchive\fP, \fB\fP will default to that of the host +machine. .UNINDENT -.UNINDENT -.sp -uid \- char[6] .INDENT 0.0 -.INDENT 3.5 -This field provides the user id of the file encoded as a decimal ASCII string. -This field might not make much sense on non\-Unix systems. On Unix, it is the -same value as the st_uid field of the stat structure returned by the stat(2) -operating system call. +.TP +.B \-h, \-\-help +Print a summary of command\-line options and their meanings. .UNINDENT -.UNINDENT -.sp -gid \- char[6] .INDENT 0.0 -.INDENT 3.5 -This field provides the group id of the file encoded as a decimal ASCII string. -This field might not make much sense on non\-Unix systems. On Unix, it is the -same value as the st_gid field of the stat structure returned by the stat(2) -operating system call. +.TP +.B \-M +This option allows for MRI scripts to be read through the standard input +stream. No other options are compatible with this option. .UNINDENT -.UNINDENT -.sp -mode \- char[8] .INDENT 0.0 -.INDENT 3.5 -This field provides the access mode of the file encoded as an octal ASCII -string. This field might not make much sense on non\-Unix systems. On Unix, it -is the same value as the st_mode field of the stat structure returned by the -stat(2) operating system call. +.TP +.B \-\-version +Display the version of the \fBllvm\-ar\fP executable. .UNINDENT -.UNINDENT -.sp -size \- char[10] .INDENT 0.0 -.INDENT 3.5 -This field provides the size of the file, in bytes, encoded as a decimal ASCII -string. -.UNINDENT +.TP +.B @ +Read command\-line options and commands from response file \fB\fP\&. .UNINDENT +.SH MRI SCRIPTS .sp -fmag \- char[2] -.INDENT 0.0 -.INDENT 3.5 -This field is the archive file member magic number. Its content is always the -two characters back tick (0x60) and newline (0x0A). This provides some measure -utility in identifying archive files that have been corrupted. -.UNINDENT -.UNINDENT +\fBllvm\-ar\fP understands a subset of the MRI scripting interface commonly +supported by archivers following in the ar tradition. An MRI script contains a +sequence of commands to be executed by the archiver. The \fI\%\-M\fP option +allows for an MRI script to be passed to \fBllvm\-ar\fP through the +standard input stream. .sp -offset \- vbr encoded 32\-bit integer +Note that \fBllvm\-ar\fP has known limitations regarding the use of MRI +scripts: .INDENT 0.0 -.INDENT 3.5 -The offset item provides the offset into the archive file where the bitcode -member is stored that is associated with the symbol. The offset value is 0 -based at the start of the first "normal" file member. To derive the actual -file offset of the member, you must add the number of bytes occupied by the file -signature (8 bytes) and the symbol tables. The value of this item is encoded -using variable bit rate encoding to reduce the size of the symbol table. -Variable bit rate encoding uses the high bit (0x80) of each byte to indicate -if there are more bytes to follow. The remaining 7 bits in each byte carry bits -from the value. The final byte does not have the high bit set. -.UNINDENT +.IP \(bu 2 +Each script can only create one archive. +.IP \(bu 2 +Existing archives can not be modified. .UNINDENT +.SS MRI Script Commands .sp -length \- vbr encoded 32\-bit integer +Each command begins with the command\(aqs name and must appear on its own line. +Some commands have arguments, which must be separated from the name by +whitespace. An MRI script should begin with either a \fI\%CREATE\fP or +\fI\%CREATETHIN\fP command and will typically end with a \fI\%SAVE\fP +command. Any text after either \(aq*\(aq or \(aq;\(aq is treated as a comment. .INDENT 0.0 -.INDENT 3.5 -The length item provides the length of the symbol that follows. Like this -\fIoffset\fP item, the length is variable bit rate encoded. +.TP +.B CREATE archive +Begin creation of a regular archive with the specified name. Subsequent +commands act upon this \fBarchive\fP\&. .UNINDENT -.UNINDENT -.sp -symbol \- character array .INDENT 0.0 -.INDENT 3.5 -The symbol item provides the text of the symbol that is associated with the -\fIoffset\fP\&. The symbol is not terminated by any character. Its length is provided -by the \fIlength\fP field. Note that is allowed (but unwise) to use non\-printing -characters (even 0x00) in the symbol. This allows for multiple encodings of -symbol names. +.TP +.B CREATETHIN archive +Begin creation of a thin archive with the specified name. Subsequent +commands act upon this \fBarchive\fP\&. .UNINDENT +.INDENT 0.0 +.TP +.B ADDLIB archive +Append the contents of \fBarchive\fP to the current archive. +.UNINDENT +.INDENT 0.0 +.TP +.B ADDMOD +Append \fB\fP to the current archive. +.UNINDENT +.INDENT 0.0 +.TP +.B DELETE +Delete the member of the current archive whose file name, excluding directory +components, matches \fB\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B SAVE +Write the current archive to the path specified in the previous +\fI\%CREATE\fP/\fI\%CREATETHIN\fP command. +.UNINDENT +.INDENT 0.0 +.TP +.B END +Ends the MRI script (optional). .UNINDENT .SH EXIT STATUS .sp -If \fBllvm\-ar\fP succeeds, it will exit with 0. A usage error, results -in an exit code of 1. A hard (file system typically) error results in an -exit code of 2. Miscellaneous or unknown errors result in an -exit code of 3. -.SH SEE ALSO -.sp -ar(1) +If \fBllvm\-ar\fP succeeds, it will exit with 0. Otherwise, if an error occurs, it +will exit with a non\-zero value. .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-ar/llvm-ranlib.1 b/usr.bin/clang/llvm-ar/llvm-ranlib.1 new file mode 100644 index 000000000000..96b1319e397c --- /dev/null +++ b/usr.bin/clang/llvm-ar/llvm-ranlib.1 @@ -0,0 +1,52 @@ +.\" $FreeBSD$ +.\" Man page generated from reStructuredText. +. +.TH "LLVM-RANLIB" "1" "2020-06-26" "10" "LLVM" +.SH NAME +llvm-ranlib \- generates an archive index +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBllvm\-ranlib\fP [\fIoptions\fP] +.SH DESCRIPTION +.sp +\fBllvm\-ranlib\fP is an alias for the llvm\-ar tool that +generates an index for an archive. It can be used as a replacement for GNU\(aqs +\fBranlib\fP tool. +.sp +Running \fBllvm\-ranlib\fP is equivalent to running \fBllvm\-ar s\fP\&. +.SH SEE ALSO +.sp +\fBllvm\-ar(1)\fP +.SH AUTHOR +Maintained by the LLVM Team (https://llvm.org/). +.SH COPYRIGHT +2003-2020, LLVM Project +.\" Generated by docutils manpage writer. +. diff --git a/usr.bin/clang/llvm-as/llvm-as.1 b/usr.bin/clang/llvm-as/llvm-as.1 index c5d410508c71..29150f757bf2 100644 --- a/usr.bin/clang/llvm-as/llvm-as.1 +++ b/usr.bin/clang/llvm-as/llvm-as.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-AS" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-AS" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-as \- LLVM assembler . @@ -78,10 +78,10 @@ If \fBllvm\-as\fP succeeds, it will exit with 0. Otherwise, if an error occurs, will exit with a non\-zero value. .SH SEE ALSO .sp -llvm\-dis|llvm\-dis, gccas|gccas +\fBllvm\-dis(1)\fP, as(1) .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-bcanalyzer/llvm-bcanalyzer.1 b/usr.bin/clang/llvm-bcanalyzer/llvm-bcanalyzer.1 index 2e49a56c8f41..948ddaeda549 100644 --- a/usr.bin/clang/llvm-bcanalyzer/llvm-bcanalyzer.1 +++ b/usr.bin/clang/llvm-bcanalyzer/llvm-bcanalyzer.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-BCANALYZER" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-BCANALYZER" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-bcanalyzer \- LLVM bitcode analyzer . @@ -467,10 +467,10 @@ Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes. .UNINDENT .SH SEE ALSO .sp -/CommandGuide/llvm\-dis, /BitCodeFormat +\fBllvm\-dis(1)\fP, /BitCodeFormat .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-cov/llvm-cov.1 b/usr.bin/clang/llvm-cov/llvm-cov.1 index bac60c293dbd..b9a161e27c72 100644 --- a/usr.bin/clang/llvm-cov/llvm-cov.1 +++ b/usr.bin/clang/llvm-cov/llvm-cov.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-COV" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-COV" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-cov \- emit coverage information . @@ -178,6 +178,12 @@ option. .B \-version Display the version of llvm\-cov. .UNINDENT +.INDENT 0.0 +.TP +.B \-x, \-\-hash\-filenames +Use md5 hash of file name when naming the coverage output files. The source +file name will be suffixed by \fB##\fP followed by MD5 hash calculated for it. +.UNINDENT .SS EXIT STATUS .sp \fBllvm\-cov gcov\fP returns 1 if it cannot read input files. Otherwise, @@ -192,6 +198,9 @@ The \fBllvm\-cov show\fP command shows line by line coverage of the binaries \fIBIN\fP,... using the profile data \fIPROFILE\fP\&. It can optionally be filtered to only show the coverage for the files listed in \fISOURCES\fP\&. .sp +\fIBIN\fP may be an executable, object file, dynamic library, or archive (thin or +otherwise). +.sp To use \fBllvm\-cov show\fP, you need a program that is compiled with instrumentation to emit profile and coverage data. To build such a program with \fBclang\fP use the \fB\-fprofile\-instr\-generate\fP and \fB\-fcoverage\-mapping\fP @@ -351,6 +360,9 @@ The \fBllvm\-cov report\fP command displays a summary of the coverage of the binaries \fIBIN\fP,... using the profile data \fIPROFILE\fP\&. It can optionally be filtered to only show the coverage for the files listed in \fISOURCES\fP\&. .sp +\fIBIN\fP may be an executable, object file, dynamic library, or archive (thin or +otherwise). +.sp If no source files are provided, a summary line is printed for each file in the coverage data. If any files are provided, summaries can be shown for each function in the listed files if the \fB\-show\-functions\fP option is enabled. @@ -392,9 +404,15 @@ Skip source code files with file paths that match the given regular expression. \fBllvm\-cov export\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP [\fI\-object BIN,...\fP] [[\fI\-object BIN\fP]] [\fISOURCES\fP] .SS DESCRIPTION .sp -The \fBllvm\-cov export\fP command exports regions, functions, expansions, -and summaries of the coverage of the binaries \fIBIN\fP,... using the profile data -\fIPROFILE\fP as JSON. It can optionally be filtered to only export the coverage +The \fBllvm\-cov export\fP command exports coverage data of the binaries +\fIBIN\fP,... using the profile data \fIPROFILE\fP in either JSON or lcov trace file +format. +.sp +When exporting JSON, the regions, functions, expansions, and summaries of the +coverage data will be exported. When exporting an lcov trace file, the +line\-based coverage and summaries will be exported. +.sp +The exported data can optionally be filtered to only export the coverage for the files listed in \fISOURCES\fP\&. .sp For information on compiling programs for coverage and generating profile data, @@ -410,20 +428,46 @@ non\-universal binary. .UNINDENT .INDENT 0.0 .TP +.B \-format= +Use the specified output format. The supported formats are: "text" (JSON), +"lcov". +.UNINDENT +.INDENT 0.0 +.TP .B \-summary\-only Export only summary information for each file in the coverage data. This mode will not export coverage information for smaller units such as individual -functions or regions. The result will be the same as produced by :program: -\fIllvm\-cov report\fP command, but presented in JSON format rather than text. +functions or regions. The result will contain the same information as produced +by the \fBllvm\-cov report\fP command, but presented in JSON or lcov +format rather than text. .UNINDENT .INDENT 0.0 .TP .B \-ignore\-filename\-regex= Skip source code files with file paths that match the given regular expression. +.INDENT 7.0 +.TP +.B \-skip\-expansions +.UNINDENT +.sp +Skip exporting macro expansion coverage data. +.INDENT 7.0 +.TP +.B \-skip\-functions +.UNINDENT +.sp +Skip exporting per\-function coverage data. +.INDENT 7.0 +.TP +.B \-num\-threads=N, \-j=N +.UNINDENT +.sp +Use N threads to export coverage data. When N=0, llvm\-cov auto\-detects an +appropriate number of threads to use. This is the default. .UNINDENT .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-cxxfilt/Makefile b/usr.bin/clang/llvm-cxxfilt/Makefile index f86af88d5210..b5aa8b34b8e2 100644 --- a/usr.bin/clang/llvm-cxxfilt/Makefile +++ b/usr.bin/clang/llvm-cxxfilt/Makefile @@ -1,7 +1,6 @@ # $FreeBSD$ PROG_CXX= llvm-cxxfilt -MAN= SRCDIR= llvm/tools/llvm-cxxfilt SRCS+= llvm-cxxfilt.cpp diff --git a/usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 b/usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 new file mode 100644 index 000000000000..7c80c5543c06 --- /dev/null +++ b/usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 @@ -0,0 +1,117 @@ +.\" $FreeBSD$ +.\" Man page generated from reStructuredText. +. +.TH "LLVM-CXXFILT" "1" "2020-06-26" "10" "LLVM" +.SH NAME +llvm-cxxfilt \- LLVM symbol name demangler +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBllvm\-cxxfilt\fP [\fIoptions\fP] [\fImangled names...\fP] +.SH DESCRIPTION +.sp +\fBllvm\-cxxfilt\fP is a symbol demangler that can be used as a replacement +for the GNU \fBc++filt\fP tool. It takes a series of symbol names and +prints their demangled form on the standard output stream. If a name cannot be +demangled, it is simply printed as is. +.sp +If no names are specified on the command\-line, names are read interactively from +the standard input stream. When reading names from standard input, each input +line is split on characters that are not part of valid Itanium name manglings, +i.e. characters that are not alphanumeric, \(aq.\(aq, \(aq$\(aq, or \(aq_\(aq. Separators between +names are copied to the output as is. +.SH EXAMPLE +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ llvm\-cxxfilt _Z3foov _Z3bari not_mangled +foo() +bar(int) +not_mangled +$ cat input.txt +| _Z3foov *** _Z3bari *** not_mangled | +$ llvm\-cxxfilt < input.txt +| foo() *** bar(int) *** not_mangled | +.ft P +.fi +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-\-format=, \-s +Mangling scheme to assume. Valid values are \fBauto\fP (default, auto\-detect the +style) and \fBgnu\fP (assume GNU/Itanium style). +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-help, \-h +Print a summary of command line options. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-help\-list +Print an uncategorized summary of command line options. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-underscore, \-_ +Discard a single leading underscore, if present, from each input name before +demangling. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-types, \-t +Attempt to demangle names as type names as well as function names. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-version +Display the version of the \fBllvm\-cxxfilt\fP executable. +.UNINDENT +.INDENT 0.0 +.TP +.B @ +Read command\-line options from response file \fI\fP\&. +.UNINDENT +.SH EXIT STATUS +.sp +\fBllvm\-cxxfilt\fP returns 0 unless it encounters a usage error, in which +case a non\-zero exit code is returned. +.SH SEE ALSO +.sp +\fBllvm\-nm(1)\fP +.SH AUTHOR +Maintained by the LLVM Team (https://llvm.org/). +.SH COPYRIGHT +2003-2020, LLVM Project +.\" Generated by docutils manpage writer. +. diff --git a/usr.bin/clang/llvm-diff/llvm-diff.1 b/usr.bin/clang/llvm-diff/llvm-diff.1 index b40d3be0522d..48abcd2c41d8 100644 --- a/usr.bin/clang/llvm-diff/llvm-diff.1 +++ b/usr.bin/clang/llvm-diff/llvm-diff.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-DIFF" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-DIFF" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-diff \- LLVM structural 'diff' . @@ -70,8 +70,8 @@ attributes, are not diagnosed. Changes in memory behavior (for example, coalescing loads) can cause massive detected differences in blocks. .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-dis/llvm-dis.1 b/usr.bin/clang/llvm-dis/llvm-dis.1 index b4cd666bd53a..53fe9e0493aa 100644 --- a/usr.bin/clang/llvm-dis/llvm-dis.1 +++ b/usr.bin/clang/llvm-dis/llvm-dis.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-DIS" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-DIS" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-dis \- LLVM disassembler . @@ -79,10 +79,10 @@ If \fBllvm\-dis\fP succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non\-zero value. .SH SEE ALSO .sp -llvm\-as|llvm\-as +\fBllvm\-as(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1 b/usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1 index 35faa902fb72..bffdedbd3707 100644 --- a/usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1 +++ b/usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-DWARFDUMP" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-DWARFDUMP" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-dwarfdump \- dump and verify DWARF debug information . @@ -40,11 +40,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] archives, and \fI\&.dSYM\fP bundles and prints their contents in human\-readable form. Only the .debug_info section is printed unless one of the section\-specific options or \fI\%\-\-all\fP is specified. +.sp +If no input file is specified, \fIa.out\fP is used instead. If \fI\-\fP is used as the +input file, \fBllvm\-dwarfdump\fP reads the input from its standard input +stream. .SH OPTIONS .INDENT 0.0 .TP .B \-a, \-\-all -Disassemble all supported DWARF sections. +Dump all supported DWARF sections. .UNINDENT .INDENT 0.0 .TP @@ -58,9 +62,14 @@ default. .INDENT 0.0 .TP .B \-c, \-\-show\-children -Show a debug info entry\(aqs children when using -the \fI\%\-\-debug\-info\fP, \fI\%\-\-find\fP, -and \fI\%\-\-name\fP options. +Show a debug info entry\(aqs children when selectively printing with +the \fI=\fP argument of \fI\%\-\-debug\-info\fP, or options such +as \fI\%\-\-find\fP or \fI\%\-\-name\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-color +Use colors in output. .UNINDENT .INDENT 0.0 .TP @@ -83,42 +92,56 @@ Show help and usage for this command. .UNINDENT .INDENT 0.0 .TP -.B \-i, \-\-ignore\-case -Ignore case distinctions in when searching entries by name -or by regular expression. +.B \-\-help\-list +Show help and usage for this command without grouping the options +into categories. .UNINDENT .INDENT 0.0 .TP -.B \-n , \-\-name= +.B \-i, \-\-ignore\-case +Ignore case distinctions when using \fI\%\-\-name\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-n , \-\-name= Find and print all debug info entries whose name -(\fIDW_AT_name\fP attribute) matches the exact text in -. Use the \fI\%\-\-regex\fP option to have - become a regular expression for more flexible -pattern matching. +(\fIDW_AT_name\fP attribute) is . .UNINDENT .INDENT 0.0 .TP .B \-\-lookup=
-Lookup
in the debug information and print out the file, +Look up
in the debug information and print out the file, function, block, and line table details. .UNINDENT .INDENT 0.0 .TP -.B \-o , \-\-out\-file= -Redirect output to a file specified by . +.B \-o +Redirect output to a file specified by , where \fI\-\fP is the +standard output stream. .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-show\-parents -Show a debug info entry\(aqs parent objects when using the -\fI\%\-\-debug\-info\fP, \fI\%\-\-find\fP, and -\fI\%\-\-name\fP options. +Show a debug info entry\(aqs parents when selectively printing with +the \fI=\fP argument of \fI\%\-\-debug\-info\fP, or options such +as \fI\%\-\-find\fP or \fI\%\-\-name\fP\&. .UNINDENT .INDENT 0.0 .TP -.B \-r , \-\-recurse\-depth= -Only recurse to a maximum depth of when dumping debug info -entries. +.B \-\-parent\-recurse\-depth= +When displaying debug info entry parents, only show them to a +maximum depth of . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quiet +Use with \fI\%\-\-verify\fP to not emit to \fISTDOUT\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r , \-\-recurse\-depth= +When displaying debug info entries, only show children to a maximum +depth of . .UNINDENT .INDENT 0.0 .TP @@ -128,9 +151,15 @@ as machine\-readable single\-line JSON output. .UNINDENT .INDENT 0.0 .TP +.B \-\-summarize\-types +Abbreviate the description of type unit entries. +.UNINDENT +.INDENT 0.0 +.TP .B \-x, \-\-regex -Treat any strings as regular expressions when searching -instead of just as an exact string match. +Treat any strings as regular expressions when searching +with \fI\%\-\-name\fP\&. If \fI\%\-\-ignore\-case\fP is also specified, +the regular expression becomes case\-insensitive. .UNINDENT .INDENT 0.0 .TP @@ -163,16 +192,19 @@ Display the version of the tool. .UNINDENT .INDENT 0.0 .TP -.B \-\-debug\-abbrev, \-\-debug\-aranges, \-\-debug\-cu\-index, \-\-debug\-frame [=], \-\-debug\-gnu\-pubnames, \-\-debug\-gnu\-pubtypes, \-\-debug\-info [=], \-\-debug\-line [=], \-\-debug\-loc [=], \-\-debug\-macro, \-\-debug\-pubnames, \-\-debug\-pubtypes, \-\-debug\-ranges, \-\-debug\-str, \-\-debug\-str\-offsets, \-\-debug\-tu\-index, \-\-debug\-types, \-\-eh\-frame, \-\-gdb\-index, \-\-apple\-names, \-\-apple\-types, \-\-apple\-namespaces, \-\-apple\-objc +.B \-\-debug\-abbrev, \-\-debug\-addr, \-\-debug\-aranges, \-\-debug\-cu\-index, \-\-debug\-frame [=], \-\-debug\-gnu\-pubnames, \-\-debug\-gnu\-pubtypes, \-\-debug\-info [=], \-\-debug\-line [=], \-\-debug\-line\-str, \-\-debug\-loc [=], \-\-debug\-loclists [=], \-\-debug\-macro, \-\-debug\-names, \-\-debug\-pubnames, \-\-debug\-pubtypes, \-\-debug\-ranges, \-\-debug\-rnglists, \-\-debug\-str, \-\-debug\-str\-offsets, \-\-debug\-tu\-index, \-\-debug\-types, \-\-eh\-frame [=], \-\-gdb\-index, \-\-apple\-names, \-\-apple\-types, \-\-apple\-namespaces, \-\-apple\-objc Dump the specified DWARF section by name. Only the \fI\&.debug_info\fP section is shown by default. Some entries support adding an \fI=\fP as a way to provide an optional offset of the exact entry to dump within the respective section. When an offset is provided, only the entry at that offset will be dumped, else the entire -section will be dumped. Children of items at a specific -offset can be dumped by also using the -\fI\%\-\-show\-children\fP option where applicable. +section will be dumped. +.UNINDENT +.INDENT 0.0 +.TP +.B @ +Read command\-line options from \fI\fP\&. .UNINDENT .SH EXIT STATUS .sp @@ -182,8 +214,8 @@ successfully. Otherwise, it returns 1. .sp \fBdsymutil(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-extract/llvm-extract.1 b/usr.bin/clang/llvm-extract/llvm-extract.1 index 13608fa41b0a..944a81395ff8 100644 --- a/usr.bin/clang/llvm-extract/llvm-extract.1 +++ b/usr.bin/clang/llvm-extract/llvm-extract.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-EXTRACT" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-EXTRACT" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-extract \- extract a function from an LLVM module . @@ -120,10 +120,10 @@ If \fBllvm\-extract\fP succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non\-zero value. .SH SEE ALSO .sp -bugpoint +\fBbugpoint(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-link/llvm-link.1 b/usr.bin/clang/llvm-link/llvm-link.1 index f39543f4d65e..12218837fd28 100644 --- a/usr.bin/clang/llvm-link/llvm-link.1 +++ b/usr.bin/clang/llvm-link/llvm-link.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-LINK" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-LINK" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-link \- LLVM bitcode linker . @@ -38,7 +38,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .sp \fBllvm\-link\fP takes several LLVM bitcode files and links them together into a single LLVM bitcode file. It writes the output file to standard output, -unless the \fB\-o\fP option is used to specify a filename. +unless the \fI\%\-o\fP option is used to specify a filename. .SH OPTIONS .INDENT 0.0 .TP @@ -82,8 +82,8 @@ library found. If \fBllvm\-link\fP succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non\-zero value. .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-mca/llvm-mca.1 b/usr.bin/clang/llvm-mca/llvm-mca.1 index bc5446d53da3..0897d363479d 100644 --- a/usr.bin/clang/llvm-mca/llvm-mca.1 +++ b/usr.bin/clang/llvm-mca/llvm-mca.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-MCA" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-MCA" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-mca \- LLVM Machine Code Analyzer . @@ -48,55 +48,12 @@ The main goal of this tool is not just to predict the performance of the code when run on the target, but also help with diagnosing potential performance issues. .sp -Given an assembly code sequence, llvm\-mca estimates the Instructions Per Cycle -(IPC), as well as hardware resource pressure. The analysis and reporting style -were inspired by the IACA tool from Intel. +Given an assembly code sequence, \fBllvm\-mca\fP estimates the Instructions +Per Cycle (IPC), as well as hardware resource pressure. The analysis and +reporting style were inspired by the IACA tool from Intel. .sp -\fBllvm\-mca\fP allows the usage of special code comments to mark regions of -the assembly code to be analyzed. A comment starting with substring -\fBLLVM\-MCA\-BEGIN\fP marks the beginning of a code region. A comment starting with -substring \fBLLVM\-MCA\-END\fP marks the end of a code region. For example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# LLVM\-MCA\-BEGIN My Code Region - ... -# LLVM\-MCA\-END -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Multiple regions can be specified provided that they do not overlap. A code -region can have an optional description. If no user\-defined region is specified, -then \fBllvm\-mca\fP assumes a default region which contains every -instruction in the input file. Every region is analyzed in isolation, and the -final performance report is the union of all the reports generated for every -code region. -.sp -Inline assembly directives may be used from source code to annotate the -assembly text: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -int foo(int a, int b) { - __asm volatile("# LLVM\-MCA\-BEGIN foo"); - a += 42; - __asm volatile("# LLVM\-MCA\-END"); - a *= b; - return a; -} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -So for example, you can compile code with clang, output assembly, and pipe it -directly into llvm\-mca for analysis: +For example, you can compile code with clang, output assembly, and pipe it +directly into \fBllvm\-mca\fP for analysis: .INDENT 0.0 .INDENT 3.5 .sp @@ -119,13 +76,24 @@ $ clang foo.c \-O2 \-target x86_64\-unknown\-unknown \-mllvm \-x86\-asm\-syntax= .fi .UNINDENT .UNINDENT +.sp +Scheduling models are not just used to compute instruction latencies and +throughput, but also to understand what processor resources are available +and how to simulate them. +.sp +By design, the quality of the analysis conducted by \fBllvm\-mca\fP is +inevitably affected by the quality of the scheduling models in LLVM. +.sp +If you see that the performance report is not accurate for a processor, +please \fI\%file a bug\fP +against the appropriate backend. .SH OPTIONS .sp If \fBinput\fP is "\fB\-\fP" or omitted, \fBllvm\-mca\fP reads from standard input. Otherwise, it will read from the specified filename. .sp -If the \fB\-o\fP option is omitted, then \fBllvm\-mca\fP will send its output -to standard output if the input is from standard input. If the \fB\-o\fP +If the \fI\%\-o\fP option is omitted, then \fBllvm\-mca\fP will send its output +to standard output if the input is from standard input. If the \fI\%\-o\fP option specifies "\fB\-\fP", then the output will also be sent to standard output. .INDENT 0.0 .TP @@ -134,6 +102,12 @@ Print a summary of command line options. .UNINDENT .INDENT 0.0 .TP +.B \-o +Use \fB\fP as the output filename. See the summary above for more +details. +.UNINDENT +.INDENT 0.0 +.TP .B \-mtriple= Specify a target triple string. .UNINDENT @@ -159,6 +133,12 @@ the analysis report. .UNINDENT .INDENT 0.0 .TP +.B \-print\-imm\-hex +Prefer hex format for numeric literals in the output assembly printed as part +of the report. +.UNINDENT +.INDENT 0.0 +.TP .B \-dispatch= Specify a different dispatch width for the processor. The dispatch width defaults to field \(aqIssueWidth\(aq in the processor scheduling model. If width is @@ -251,6 +231,11 @@ Enable the instruction info view. This is enabled by default. .UNINDENT .INDENT 0.0 .TP +.B \-show\-encoding +Enable the printing of instruction encodings within the instruction info view. +.UNINDENT +.INDENT 0.0 +.TP .B \-all\-stats Print all hardware statistics. This enables extra statistics related to the dispatch logic, the hardware schedulers, the register file(s), and the retire @@ -270,10 +255,127 @@ view because it doesn\(aqt require that the code is simulated. It instead prints the theoretical uniform distribution of resource pressure for every instruction in sequence. .UNINDENT +.INDENT 0.0 +.TP +.B \-bottleneck\-analysis +Print information about bottlenecks that affect the throughput. This analysis +can be expensive, and it is disabled by default. Bottlenecks are highlighted +in the summary view. +.UNINDENT .SH EXIT STATUS .sp \fBllvm\-mca\fP returns 0 on success. Otherwise, an error message is printed to standard error, and the tool returns 1. +.SH USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS +.sp +\fBllvm\-mca\fP allows for the optional usage of special code comments to +mark regions of the assembly code to be analyzed. A comment starting with +substring \fBLLVM\-MCA\-BEGIN\fP marks the beginning of a code region. A comment +starting with substring \fBLLVM\-MCA\-END\fP marks the end of a code region. For +example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# LLVM\-MCA\-BEGIN + ... +# LLVM\-MCA\-END +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If no user\-defined region is specified, then \fBllvm\-mca\fP assumes a +default region which contains every instruction in the input file. Every region +is analyzed in isolation, and the final performance report is the union of all +the reports generated for every code region. +.sp +Code regions can have names. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# LLVM\-MCA\-BEGIN A simple example + add %eax, %eax +# LLVM\-MCA\-END +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The code from the example above defines a region named "A simple example" with a +single instruction in it. Note how the region name doesn\(aqt have to be repeated +in the \fBLLVM\-MCA\-END\fP directive. In the absence of overlapping regions, +an anonymous \fBLLVM\-MCA\-END\fP directive always ends the currently active user +defined region. +.sp +Example of nesting regions: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# LLVM\-MCA\-BEGIN foo + add %eax, %edx +# LLVM\-MCA\-BEGIN bar + sub %eax, %edx +# LLVM\-MCA\-END bar +# LLVM\-MCA\-END foo +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Example of overlapping regions: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# LLVM\-MCA\-BEGIN foo + add %eax, %edx +# LLVM\-MCA\-BEGIN bar + sub %eax, %edx +# LLVM\-MCA\-END foo + add %eax, %edx +# LLVM\-MCA\-END bar +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that multiple anonymous regions cannot overlap. Also, overlapping regions +cannot have the same name. +.sp +There is no support for marking regions from high\-level source code, like C or +C++. As a workaround, inline assembly directives may be used: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int foo(int a, int b) { + __asm volatile("# LLVM\-MCA\-BEGIN foo"); + a += 42; + __asm volatile("# LLVM\-MCA\-END"); + a *= b; + return a; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +However, this interferes with optimizations like loop vectorization and may have +an impact on the code generated. This is because the \fB__asm\fP statements are +seen as real code having important side effects, which limits how the code +around them can be transformed. If users want to make use of inline assembly +to emit markers, then the recommendation is to always verify that the output +assembly is equivalent to the assembly generated in the absence of markers. +The \fI\%Clang options to emit optimization reports\fP +can also help in detecting missed optimizations. .SH HOW LLVM-MCA WORKS .sp \fBllvm\-mca\fP takes assembly code as input. The assembly code is parsed @@ -309,7 +411,10 @@ $ llvm\-mca \-mtriple=x86_64\-unknown\-unknown \-mcpu=btver2 \-iterations=300 do Iterations: 300 Instructions: 900 Total Cycles: 610 +Total uOps: 900 + Dispatch Width: 2 +uOps Per Cycle: 1.48 IPC: 1.48 Block RThroughput: 2.0 @@ -360,40 +465,99 @@ Resource pressure by instruction: .UNINDENT .sp According to this report, the dot\-product kernel has been executed 300 times, -for a total of 900 dynamically executed instructions. +for a total of 900 simulated instructions. The total number of simulated micro +opcodes (uOps) is also 900. .sp The report is structured in three main sections. The first section collects a few performance numbers; the goal of this section is to give a very quick -overview of the performance throughput. In this example, the two important -performance indicators are \fBIPC\fP and \fBBlock RThroughput\fP (Block Reciprocal +overview of the performance throughput. Important performance indicators are +\fBIPC\fP, \fBuOps Per Cycle\fP, and \fBBlock RThroughput\fP (Block Reciprocal Throughput). .sp +Field \fIDispatchWidth\fP is the maximum number of micro opcodes that are dispatched +to the out\-of\-order backend every simulated cycle. +.sp IPC is computed dividing the total number of simulated instructions by the total -number of cycles. A delta between Dispatch Width and IPC is an indicator of a -performance issue. In the absence of loop\-carried data dependencies, the -observed IPC tends to a theoretical maximum which can be computed by dividing -the number of instructions of a single iteration by the \fIBlock RThroughput\fP\&. +number of cycles. .sp -IPC is bounded from above by the dispatch width. That is because the dispatch -width limits the maximum size of a dispatch group. IPC is also limited by the -amount of hardware parallelism. The availability of hardware resources affects -the resource pressure distribution, and it limits the number of instructions -that can be executed in parallel every cycle. A delta between Dispatch -Width and the theoretical maximum IPC is an indicator of a performance -bottleneck caused by the lack of hardware resources. In general, the lower the -Block RThroughput, the better. +Field \fIBlock RThroughput\fP is the reciprocal of the block throughput. Block +throuhgput is a theoretical quantity computed as the maximum number of blocks +(i.e. iterations) that can be executed per simulated clock cycle in the absence +of loop carried dependencies. Block throughput is is superiorly +limited by the dispatch rate, and the availability of hardware resources. .sp -In this example, \fBInstructions per iteration/Block RThroughput\fP is 1.50. Since -there are no loop\-carried dependencies, the observed IPC is expected to approach -1.50 when the number of iterations tends to infinity. The delta between the -Dispatch Width (2.00), and the theoretical maximum IPC (1.50) is an indicator of -a performance bottleneck caused by the lack of hardware resources, and the -\fIResource pressure view\fP can help to identify the problematic resource usage. +In the absence of loop\-carried data dependencies, the observed IPC tends to a +theoretical maximum which can be computed by dividing the number of instructions +of a single iteration by the \fIBlock RThroughput\fP\&. .sp -The second section of the report shows the latency and reciprocal -throughput of every instruction in the sequence. That section also reports -extra information related to the number of micro opcodes, and opcode properties -(i.e., \(aqMayLoad\(aq, \(aqMayStore\(aq, and \(aqHasSideEffects\(aq). +Field \(aquOps Per Cycle\(aq is computed dividing the total number of simulated micro +opcodes by the total number of cycles. A delta between Dispatch Width and this +field is an indicator of a performance issue. In the absence of loop\-carried +data dependencies, the observed \(aquOps Per Cycle\(aq should tend to a theoretical +maximum throughput which can be computed by dividing the number of uOps of a +single iteration by the \fIBlock RThroughput\fP\&. +.sp +Field \fIuOps Per Cycle\fP is bounded from above by the dispatch width. That is +because the dispatch width limits the maximum size of a dispatch group. Both IPC +and \(aquOps Per Cycle\(aq are limited by the amount of hardware parallelism. The +availability of hardware resources affects the resource pressure distribution, +and it limits the number of instructions that can be executed in parallel every +cycle. A delta between Dispatch Width and the theoretical maximum uOps per +Cycle (computed by dividing the number of uOps of a single iteration by the +\fIBlock RThroughput\fP) is an indicator of a performance bottleneck caused by the +lack of hardware resources. +In general, the lower the Block RThroughput, the better. +.sp +In this example, \fBuOps per iteration/Block RThroughput\fP is 1.50. Since there +are no loop\-carried dependencies, the observed \fIuOps Per Cycle\fP is expected to +approach 1.50 when the number of iterations tends to infinity. The delta between +the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is +an indicator of a performance bottleneck caused by the lack of hardware +resources, and the \fIResource pressure view\fP can help to identify the problematic +resource usage. +.sp +The second section of the report is the \fIinstruction info view\fP\&. It shows the +latency and reciprocal throughput of every instruction in the sequence. It also +reports extra information related to the number of micro opcodes, and opcode +properties (i.e., \(aqMayLoad\(aq, \(aqMayStore\(aq, and \(aqHasSideEffects\(aq). +.sp +Field \fIRThroughput\fP is the reciprocal of the instruction throughput. Throughput +is computed as the maximum number of instructions of a same type that can be +executed per clock cycle in the absence of operand dependencies. In this +example, the reciprocal throughput of a vector float multiply is 1 +cycles/instruction. That is because the FP multiplier JFPM is only available +from pipeline JFPU1. +.sp +Instruction encodings are displayed within the instruction info view when flag +\fI\-show\-encoding\fP is specified. +.sp +Below is an example of \fI\-show\-encoding\fP output for the dot\-product kernel: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Instruction Info: +[1]: #uOps +[2]: Latency +[3]: RThroughput +[4]: MayLoad +[5]: MayStore +[6]: HasSideEffects (U) +[7]: Encoding Size + +[1] [2] [3] [4] [5] [6] [7] Encodings: Instructions: + 1 2 1.00 4 c5 f0 59 d0 vmulps %xmm0, %xmm1, %xmm2 + 1 4 1.00 4 c5 eb 7c da vhaddps %xmm2, %xmm2, %xmm3 + 1 4 1.00 4 c5 e3 7c e3 vhaddps %xmm3, %xmm3, %xmm4 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fIEncoding Size\fP column shows the size in bytes of instructions. The +\fIEncodings\fP column shows the actual instruction encodings (byte sequences in +hex). .sp The third section is the \fIResource pressure view\fP\&. This view reports the average number of resource cycles consumed every iteration by instructions @@ -476,6 +640,7 @@ Average Wait times (based on the timeline view): 0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2 1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3 2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4 + 3 3.3 0.5 1.4 .ft P .fi .UNINDENT @@ -536,7 +701,8 @@ and therefore consuming physical registers). .sp Table \fIAverage Wait times\fP helps diagnose performance issues that are caused by the presence of long latency instructions and potentially long data dependencies -which may limit the ILP. Note that \fBllvm\-mca\fP, by default, assumes at +which may limit the ILP. Last row, \fB\fP, shows a global average over all +instructions measured. Note that \fBllvm\-mca\fP, by default, assumes at least 1cy between the dispatch event and the issue event. .sp When the performance is limited by data dependencies and/or long latency @@ -548,14 +714,72 @@ instructions. When performance is mostly limited by the lack of hardware resources, the delta between the two counters is small. However, the number of cycles spent in the queue tends to be larger (i.e., more than 1\-3cy), especially when compared to other low latency instructions. +.SS Bottleneck Analysis +.sp +The \fB\-bottleneck\-analysis\fP command line option enables the analysis of +performance bottlenecks. +.sp +This analysis is potentially expensive. It attempts to correlate increases in +backend pressure (caused by pipeline resource pressure and data dependencies) to +dynamic dispatch stalls. +.sp +Below is an example of \fB\-bottleneck\-analysis\fP output generated by +\fBllvm\-mca\fP for 500 iterations of the dot\-product example on btver2. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Cycles with backend pressure increase [ 48.07% ] +Throughput Bottlenecks: + Resource Pressure [ 47.77% ] + \- JFPA [ 47.77% ] + \- JFPU0 [ 47.77% ] + Data Dependencies: [ 0.30% ] + \- Register Dependencies [ 0.30% ] + \- Memory Dependencies [ 0.00% ] + +Critical sequence based on the simulation: + + Instruction Dependency Information + +\-\-\-\-< 2. vhaddps %xmm3, %xmm3, %xmm4 + | + | < loop carried > + | + | 0. vmulps %xmm0, %xmm1, %xmm2 + +\-\-\-\-> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ] + +\-\-\-\-> 2. vhaddps %xmm3, %xmm3, %xmm4 ## REGISTER dependency: %xmm3 + | + | < loop carried > + | + +\-\-\-\-> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +According to the analysis, throughput is limited by resource pressure and not by +data dependencies. The analysis observed increases in backend pressure during +48.07% of the simulated run. Almost all those pressure increase events were +caused by contention on processor resources JFPA/JFPU0. +.sp +The \fIcritical sequence\fP is the most expensive sequence of instructions according +to the simulation. It is annotated to provide extra information about critical +register dependencies and resource interferences between instructions. +.sp +Instructions from the critical sequence are expected to significantly impact +performance. By construction, the accuracy of this analysis is strongly +dependent on the simulation and (as always) by the quality of the processor +model in llvm. .SS Extra Statistics to Further Diagnose Performance Issues .sp The \fB\-all\-stats\fP command line option enables extra statistics and performance counters for the dispatch logic, the reorder buffer, the retire control unit, and the register file. .sp -Below is an example of \fB\-all\-stats\fP output generated by MCA for the -dot\-product example discussed in the previous sections. +Below is an example of \fB\-all\-stats\fP output generated by \fBllvm\-mca\fP +for 300 iterations of the dot\-product example discussed in the previous +sections. .INDENT 0.0 .INDENT 3.5 .sp @@ -564,30 +788,35 @@ dot\-product example discussed in the previous sections. Dynamic Dispatch Stall Cycles: RAT \- Register unavailable: 0 RCU \- Retire tokens unavailable: 0 -SCHEDQ \- Scheduler full: 272 +SCHEDQ \- Scheduler full: 272 (44.6%) LQ \- Load queue full: 0 SQ \- Store queue full: 0 GROUP \- Static restrictions on the dispatch group: 0 -Dispatch Logic \- number of cycles where we saw N instructions dispatched: +Dispatch Logic \- number of cycles where we saw N micro opcodes dispatched: [# dispatched], [# cycles] 0, 24 (3.9%) 1, 272 (44.6%) 2, 314 (51.5%) -Schedulers \- number of cycles where we saw N instructions issued: +Schedulers \- number of cycles where we saw N micro opcodes issued: [# issued], [# cycles] 0, 7 (1.1%) 1, 306 (50.2%) 2, 297 (48.7%) - Scheduler\(aqs queue usage: -JALU01, 0/20 -JFPU01, 18/18 -JLSAGU, 0/12 +[1] Resource name. +[2] Average number of used buffer entries. +[3] Maximum number of used buffer entries. +[4] Total number of buffer entries. + + [1] [2] [3] [4] +JALU01 0 0 20 +JFPU01 17 18 18 +JLSAGU 0 0 12 Retire Control Unit \- number of cycles where we saw N instructions retired: @@ -596,6 +825,10 @@ Retire Control Unit \- number of cycles where we saw N instructions retired: 1, 102 (16.7%) 2, 399 (65.4%) +Total ROB Entries: 64 +Max Used ROB Entries: 35 ( 54.7% ) +Average Used ROB Entries per cy: 32 ( 50.0% ) + Register File statistics: Total number of mappings created: 900 @@ -617,23 +850,21 @@ Max number of mappings used: 35 .sp If we look at the \fIDynamic Dispatch Stall Cycles\fP table, we see the counter for SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch -logic is unable to dispatch a group of two instructions because the scheduler\(aqs -queue is full. +logic is unable to dispatch a full group because the scheduler\(aqs queue is full. .sp -Looking at the \fIDispatch Logic\fP table, we see that the pipeline was only able -to dispatch two instructions 51.5% of the time. The dispatch group was limited -to one instruction 44.6% of the cycles, which corresponds to 272 cycles. The +Looking at the \fIDispatch Logic\fP table, we see that the pipeline was only able to +dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to +one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The dispatch statistics are displayed by either using the command option \fB\-all\-stats\fP or \fB\-dispatch\-stats\fP\&. .sp The next table, \fISchedulers\fP, presents a histogram displaying a count, -representing the number of instructions issued on some number of cycles. In -this case, of the 610 simulated cycles, single -instructions were issued 306 times (50.2%) and there were 7 cycles where -no instructions were issued. +representing the number of micro opcodes issued on some number of cycles. In +this case, of the 610 simulated cycles, single opcodes were issued 306 times +(50.2%) and there were 7 cycles where no opcodes were issued. .sp -The \fIScheduler\(aqs queue usage\fP table shows that the maximum number of buffer -entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01 +The \fIScheduler\(aqs queue usage\fP table shows that the average and maximum number of +buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01 reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements three schedulers: .INDENT 0.0 @@ -653,36 +884,36 @@ A full scheduler queue is either caused by data dependency chains or by a sub\-optimal usage of hardware resources. Sometimes, resource pressure can be mitigated by rewriting the kernel using different instructions that consume different scheduler resources. Schedulers with a small queue are less resilient -to bottlenecks caused by the presence of long data dependencies. -The scheduler statistics are displayed by -using the command option \fB\-all\-stats\fP or \fB\-scheduler\-stats\fP\&. +to bottlenecks caused by the presence of long data dependencies. The scheduler +statistics are displayed by using the command option \fB\-all\-stats\fP or +\fB\-scheduler\-stats\fP\&. .sp The next table, \fIRetire Control Unit\fP, presents a histogram displaying a count, representing the number of instructions retired on some number of cycles. In -this case, of the 610 simulated cycles, two instructions were retired during -the same cycle 399 times (65.4%) and there were 109 cycles where no -instructions were retired. The retire statistics are displayed by using the -command option \fB\-all\-stats\fP or \fB\-retire\-stats\fP\&. +this case, of the 610 simulated cycles, two instructions were retired during the +same cycle 399 times (65.4%) and there were 109 cycles where no instructions +were retired. The retire statistics are displayed by using the command option +\fB\-all\-stats\fP or \fB\-retire\-stats\fP\&. .sp The last table presented is \fIRegister File statistics\fP\&. Each physical register file (PRF) used by the pipeline is presented in this table. In the case of AMD -Jaguar, there are two register files, one for floating\-point registers -(JFpuPRF) and one for integer registers (JIntegerPRF). The table shows that of -the 900 instructions processed, there were 900 mappings created. Since this -dot\-product example utilized only floating point registers, the JFPuPRF was -responsible for creating the 900 mappings. However, we see that the pipeline -only used a maximum of 35 of 72 available register slots at any given time. We -can conclude that the floating point PRF was the only register file used for -the example, and that it was never resource constrained. The register file -statistics are displayed by using the command option \fB\-all\-stats\fP or +Jaguar, there are two register files, one for floating\-point registers (JFpuPRF) +and one for integer registers (JIntegerPRF). The table shows that of the 900 +instructions processed, there were 900 mappings created. Since this dot\-product +example utilized only floating point registers, the JFPuPRF was responsible for +creating the 900 mappings. However, we see that the pipeline only used a +maximum of 35 of 72 available register slots at any given time. We can conclude +that the floating point PRF was the only register file used for the example, and +that it was never resource constrained. The register file statistics are +displayed by using the command option \fB\-all\-stats\fP or \fB\-register\-file\-stats\fP\&. .sp In this example, we can conclude that the IPC is mostly limited by data dependencies, and not by resource pressure. .SS Instruction Flow .sp -This section describes the instruction flow through MCA\(aqs default out\-of\-order -pipeline, as well as the functional units involved in the process. +This section describes the instruction flow through the default pipeline of +\fBllvm\-mca\fP, as well as the functional units involved in the process. .sp The default pipeline implements the following sequence of stages used to process instructions. @@ -699,9 +930,9 @@ Retire (Instruction is retired; writes are architecturally committed). .sp The default pipeline only models the out\-of\-order portion of a processor. Therefore, the instruction fetch and decode stages are not modeled. Performance -bottlenecks in the frontend are not diagnosed. MCA assumes that instructions -have all been decoded and placed into a queue. Also, MCA does not model branch -prediction. +bottlenecks in the frontend are not diagnosed. \fBllvm\-mca\fP assumes that +instructions have all been decoded and placed into a queue before the simulation +start. Also, \fBllvm\-mca\fP does not model branch prediction. .SS Instruction Dispatch .sp During the dispatch stage, instructions are picked in program order from a @@ -725,19 +956,19 @@ The schedulers are not full. .UNINDENT .sp Scheduling models can optionally specify which register files are available on -the processor. MCA uses that information to initialize register file -descriptors. Users can limit the number of physical registers that are +the processor. \fBllvm\-mca\fP uses that information to initialize register +file descriptors. Users can limit the number of physical registers that are globally available for register renaming by using the command option -\fB\-register\-file\-size\fP\&. A value of zero for this option means \fIunbounded\fP\&. -By knowing how many registers are available for renaming, MCA can predict -dispatch stalls caused by the lack of registers. +\fB\-register\-file\-size\fP\&. A value of zero for this option means \fIunbounded\fP\&. By +knowing how many registers are available for renaming, the tool can predict +dispatch stalls caused by the lack of physical registers. .sp The number of reorder buffer entries consumed by an instruction depends on the -number of micro\-opcodes specified by the target scheduling model. MCA\(aqs -reorder buffer\(aqs purpose is to track the progress of instructions that are -"in\-flight," and to retire instructions in program order. The number of -entries in the reorder buffer defaults to the \fIMicroOpBufferSize\fP provided by -the target scheduling model. +number of micro\-opcodes specified for that instruction by the target scheduling +model. The reorder buffer is responsible for tracking the progress of +instructions that are "in\-flight", and retiring them in program order. The +number of entries in the reorder buffer defaults to the value specified by field +\fIMicroOpBufferSize\fP in the target scheduling model. .sp Instructions that are dispatched to the schedulers consume scheduler buffer entries. \fBllvm\-mca\fP queries the scheduling model to determine the set @@ -763,35 +994,35 @@ available units from the group; by default, the resource manager uses a round\-robin selector to guarantee that resource usage is uniformly distributed between all units of a group. .sp -\fBllvm\-mca\fP\(aqs scheduler implements three instruction queues: +\fBllvm\-mca\fP\(aqs scheduler internally groups instructions into three sets: .INDENT 0.0 .IP \(bu 2 -WaitQueue: a queue of instructions whose operands are not ready. +WaitSet: a set of instructions whose operands are not ready. .IP \(bu 2 -ReadyQueue: a queue of instructions ready to execute. +ReadySet: a set of instructions ready to execute. .IP \(bu 2 -IssuedQueue: a queue of instructions executing. +IssuedSet: a set of instructions executing. .UNINDENT .sp -Depending on the operand availability, instructions that are dispatched to the -scheduler are either placed into the WaitQueue or into the ReadyQueue. +Depending on the operands availability, instructions that are dispatched to the +scheduler are either placed into the WaitSet or into the ReadySet. .sp -Every cycle, the scheduler checks if instructions can be moved from the -WaitQueue to the ReadyQueue, and if instructions from the ReadyQueue can be -issued to the underlying pipelines. The algorithm prioritizes older instructions -over younger instructions. +Every cycle, the scheduler checks if instructions can be moved from the WaitSet +to the ReadySet, and if instructions from the ReadySet can be issued to the +underlying pipelines. The algorithm prioritizes older instructions over younger +instructions. .SS Write\-Back and Retire Stage .sp -Issued instructions are moved from the ReadyQueue to the IssuedQueue. There, +Issued instructions are moved from the ReadySet to the IssuedSet. There, instructions wait until they reach the write\-back stage. At that point, they get removed from the queue and the retire control unit is notified. .sp -When instructions are executed, the retire control unit flags the -instruction as "ready to retire." +When instructions are executed, the retire control unit flags the instruction as +"ready to retire." .sp -Instructions are retired in program order. The register file is notified of -the retirement so that it can free the physical registers that were allocated -for the instruction during the register renaming stage. +Instructions are retired in program order. The register file is notified of the +retirement so that it can free the physical registers that were allocated for +the instruction during the register renaming stage. .SS Load/Store Unit and Memory Consistency Model .sp To simulate an out\-of\-order execution of memory operations, \fBllvm\-mca\fP @@ -879,8 +1110,8 @@ A load may not pass a previous store unless \fB\-noalias\fP is set. A load has to wait until an older load barrier is fully executed. .UNINDENT .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-nm/llvm-nm.1 b/usr.bin/clang/llvm-nm/llvm-nm.1 index c6d7ed129f6e..e1db41b01710 100644 --- a/usr.bin/clang/llvm-nm/llvm-nm.1 +++ b/usr.bin/clang/llvm-nm/llvm-nm.1 @@ -1,7 +1,7 @@ .\" $FreeBSD$ .\" Man page generated from reStructuredText. . -.TH "LLVM-NM" "1" "2018-08-02" "7" "LLVM" +.TH "LLVM-NM" "1" "2020-06-26" "10" "LLVM" .SH NAME llvm-nm \- list LLVM bitcode and object file's symbol table . @@ -36,73 +36,157 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] \fBllvm\-nm\fP [\fIoptions\fP] [\fIfilenames...\fP] .SH DESCRIPTION .sp -The \fBllvm\-nm\fP utility lists the names of symbols from the LLVM bitcode -files, object files, or \fBar\fP archives containing them, named on the -command line. Each symbol is listed along with some simple information about -its provenance. If no file name is specified, or \fI\-\fP is used as a file name, -\fBllvm\-nm\fP will process a file on its standard input stream. +The \fBllvm\-nm\fP utility lists the names of symbols from LLVM bitcode +files, object files, and archives. Each symbol is listed along with some simple +information about its provenance. If no filename is specified, \fIa.out\fP is used +as the input. If \fI\-\fP is used as a filename, \fBllvm\-nm\fP will read a file +from its standard input stream. .sp \fBllvm\-nm\fP\(aqs default output format is the traditional BSD \fBnm\fP -output format. Each such output record consists of an (optional) 8\-digit +output format. Each such output record consists of an (optional) 8\-digit hexadecimal address, followed by a type code character, followed by a name, for -each symbol. One record is printed per line; fields are separated by spaces. +each symbol. One record is printed per line; fields are separated by spaces. When the address is omitted, it is replaced by 8 spaces. .sp -Type code characters currently supported, and their meanings, are as follows: +The supported type code characters are as follows. Where both lower and +upper\-case characters are listed for the same meaning, a lower\-case character +represents a local symbol, whilst an upper\-case character represents a global +(external) symbol: .sp -U +a, A .INDENT 0.0 .INDENT 3.5 -Named object is referenced but undefined in this bitcode file +Absolute symbol. +.UNINDENT +.UNINDENT +.sp +b, B +.INDENT 0.0 +.INDENT 3.5 +Uninitialized data (bss) object. .UNINDENT .UNINDENT .sp C .INDENT 0.0 .INDENT 3.5 -Common (multiple definitions link together into one def) +Common symbol. Multiple definitions link together into one definition. +.UNINDENT +.UNINDENT +.sp +d, D +.INDENT 0.0 +.INDENT 3.5 +Writable data object. +.UNINDENT +.UNINDENT +.sp +i, I +.INDENT 0.0 +.INDENT 3.5 +COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set. +.UNINDENT +.UNINDENT +.sp +n +.INDENT 0.0 +.INDENT 3.5 +ELF: local symbol from non\-alloc section. +.sp +COFF: debug symbol. +.UNINDENT +.UNINDENT +.sp +N +.INDENT 0.0 +.INDENT 3.5 +ELF: debug section symbol, or global symbol from non\-alloc section. +.UNINDENT +.UNINDENT +.sp +s, S +.INDENT 0.0 +.INDENT 3.5 +COFF: section symbol. +.sp +Mach\-O: absolute symbol or symbol from a section other than __TEXT_EXEC __text, +__TEXT __text, __DATA __data, or __DATA __bss. +.UNINDENT +.UNINDENT +.sp +r, R +.INDENT 0.0 +.INDENT 3.5 +Read\-only data object. +.UNINDENT +.UNINDENT +.sp +t, T +.INDENT 0.0 +.INDENT 3.5 +Code (text) object. +.UNINDENT +.UNINDENT +.sp +u +.INDENT 0.0 +.INDENT 3.5 +ELF: GNU unique symbol. +.UNINDENT +.UNINDENT +.sp +U +.INDENT 0.0 +.INDENT 3.5 +Named object is undefined in this file. +.UNINDENT +.UNINDENT +.sp +v +.INDENT 0.0 +.INDENT 3.5 +ELF: Undefined weak object. It is not a link failure if the object is not +defined. +.UNINDENT +.UNINDENT +.sp +V +.INDENT 0.0 +.INDENT 3.5 +ELF: Defined weak object symbol. This definition will only be used if no +regular definitions exist in a link. If multiple weak definitions and no +regular definitions exist, one of the weak definitions will be used. +.UNINDENT +.UNINDENT +.sp +w +.INDENT 0.0 +.INDENT 3.5 +Undefined weak symbol other than an ELF object symbol. It is not a link failure +if the symbol is not defined. .UNINDENT .UNINDENT .sp W .INDENT 0.0 .INDENT 3.5 -Weak reference (multiple definitions link together into zero or one definitions) +Defined weak symbol other than an ELF object symbol. This definition will only +be used if no regular definitions exist in a link. If multiple weak definitions +and no regular definitions exist, one of the weak definitions will be used. .UNINDENT .UNINDENT .sp -t +\- .INDENT 0.0 .INDENT 3.5 -Local function (text) object -.UNINDENT -.UNINDENT -.sp -T -.INDENT 0.0 -.INDENT 3.5 -Global function (text) object -.UNINDENT -.UNINDENT -.sp -d -.INDENT 0.0 -.INDENT 3.5 -Local data object -.UNINDENT -.UNINDENT -.sp -D -.INDENT 0.0 -.INDENT 3.5 -Global data object +Mach\-O: N_STAB symbol. .UNINDENT .UNINDENT .sp ? .INDENT 0.0 .INDENT 3.5 -Something unrecognizable +Something unrecognizable. .UNINDENT .UNINDENT .sp @@ -114,25 +198,23 @@ file. .SH OPTIONS .INDENT 0.0 .TP -.B \-B (default) -Use BSD output format. Alias for \fI\-\-format=bsd\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-P -Use POSIX.2 output format. Alias for \fI\-\-format=posix\fP\&. +.B \-B +Use BSD output format. Alias for \fB\-\-format=bsd\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-debug\-syms, \-a -Show all symbols, even debugger only. +Show all symbols, even those usually suppressed. .UNINDENT .INDENT 0.0 .TP -.B \-\-defined\-only -Print only symbols defined in this file (as opposed to -symbols which may be referenced by objects in this file, but not -defined in this file.) +.B \-\-defined\-only, \-U +Print only symbols defined in this file. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-demangle, \-C +Demangle symbol names. .UNINDENT .INDENT 0.0 .TP @@ -142,29 +224,54 @@ Display dynamic symbols instead of normal symbols. .INDENT 0.0 .TP .B \-\-extern\-only, \-g -Print only symbols whose definitions are external; that is, accessible -from other files. +Print only symbols whose definitions are external; that is, accessible from +other files. .UNINDENT .INDENT 0.0 .TP -.B \-\-no\-weak, \-W -Don\(aqt print any weak symbols in the output. +.B \-\-format=, \-f +Select an output format; \fIformat\fP may be \fIsysv\fP, \fIposix\fP, \fIdarwin\fP, or \fIbsd\fP\&. +The default is \fIbsd\fP\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-format=format, \-f format -Select an output format; \fIformat\fP may be \fIsysv\fP, \fIposix\fP, or \fIbsd\fP\&. The default -is \fIbsd\fP\&. -.UNINDENT -.INDENT 0.0 -.TP -.B \-help +.B \-\-help, \-h Print a summary of command\-line options and their meanings. .UNINDENT .INDENT 0.0 .TP +.B \-\-help\-list +Print an uncategorized summary of command\-line options and their meanings. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-just\-symbol\-name, \-j +Print just the symbol names. +.UNINDENT +.INDENT 0.0 +.TP +.B \-m +Use Darwin format. Alias for \fB\-\-format=darwin\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-demangle +Don\(aqt demangle symbol names. This is the default. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-llvm\-bc +Disable the LLVM bitcode reader. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-no\-sort, \-p -Shows symbols in order encountered. +Show symbols in the order encountered. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-weak, \-W +Don\(aqt print weak symbols. .UNINDENT .INDENT 0.0 .TP @@ -173,13 +280,34 @@ Sort symbols by address. .UNINDENT .INDENT 0.0 .TP +.B \-\-portability, \-P +Use POSIX.2 output format. Alias for \fB\-\-format=posix\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-print\-armap, \-M +Print the archive symbol table, in addition to the symbols. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-print\-file\-name, \-A, \-o Precede each symbol with the file it came from. .UNINDENT .INDENT 0.0 .TP .B \-\-print\-size, \-S -Show symbol size instead of address. +Show symbol size as well as address (not applicable for Mach\-O). +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-radix=, \-t +Specify the radix of the symbol address(es). Values accepted are \fId\fP (decimal), +\fIx\fP (hexadecimal) and \fIo\fP (octal). +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-reverse\-sort, \-r +Sort symbols in reverse order. .UNINDENT .INDENT 0.0 .TP @@ -188,14 +316,61 @@ Sort symbols by size. .UNINDENT .INDENT 0.0 .TP -.B \-\-undefined\-only, \-u -Print only symbols referenced but not defined in this file. +.B \-\-special\-syms +Ignored. For GNU compatibility only. .UNINDENT .INDENT 0.0 .TP -.B \-\-radix=RADIX, \-t -Specify the radix of the symbol address(es). Values accepted d(decimal), -x(hexadecomal) and o(octal). +.B \-\-undefined\-only, \-u +Print only undefined symbols. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-version +Display the version of the \fBllvm\-nm\fP executable. Does not stack with +other commands. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-without\-aliases +Exclude aliases from the output. +.UNINDENT +.INDENT 0.0 +.TP +.B @ +Read command\-line options from response file \fI\fP\&. +.UNINDENT +.SH MACH-O SPECIFIC OPTIONS +.INDENT 0.0 +.TP +.B \-\-add\-dyldinfo +Add symbols from the dyldinfo, if they are not already in the symbol table. +This is the default. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-arch= +Dump the symbols from the specified architecture(s). +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dyldinfo\-only +Dump only symbols from the dyldinfo. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-dyldinfo +Do not add any symbols from the dyldinfo. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s= +Dump only symbols from this segment and section name. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x +Print symbol entry in hex. .UNINDENT .SH BUGS .INDENT 0.0 @@ -212,10 +387,11 @@ x(hexadecomal) and o(octal). \fBllvm\-nm\fP exits with an exit code of zero. .SH SEE ALSO .sp -llvm\-dis, ar(1), nm(1) +\fBllvm\-ar(1)\fP, \fBllvm\-objdump(1)\fP, \fBllvm\-readelf(1)\fP, +\fBllvm\-readobj(1)\fP .SH AUTHOR -Maintained by The LLVM Team (http://llvm.org/). +Maintained by the LLVM Team (https://llvm.org/). .SH COPYRIGHT -2003-2018, LLVM Project +2003-2020, LLVM Project .\" Generated by docutils manpage writer. . diff --git a/usr.bin/clang/llvm-objcopy/Makefile b/usr.bin/clang/llvm-objcopy/Makefile index b7507ad7bbaa..352bacb7685f 100644 --- a/usr.bin/clang/llvm-objcopy/Makefile +++ b/usr.bin/clang/llvm-objcopy/Makefile @@ -1,7 +1,6 @@ # $FreeBSD$ PROG_CXX= llvm-objcopy -MAN= SRCDIR= llvm/tools/llvm-objcopy SRCS+= Buffer.cpp diff --git a/usr.bin/clang/llvm-objcopy/llvm-objcopy.1 b/usr.bin/clang/llvm-objcopy/llvm-objcopy.1 new file mode 100644 index 000000000000..239ed303735b --- /dev/null +++ b/usr.bin/clang/llvm-objcopy/llvm-objcopy.1 @@ -0,0 +1,721 @@ +.\" $FreeBSD$ +.\" Man page generated from reStructuredText. +. +.TH "LLVM-OBJCOPY" "1" "2020-06-26" "10" "LLVM" +.SH NAME +llvm-objcopy \- object copying and editing tool +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBllvm\-objcopy\fP [\fIoptions\fP] \fIinput\fP [\fIoutput\fP] +.SH DESCRIPTION +.sp +\fBllvm\-objcopy\fP is a tool to copy and manipulate objects. In basic +usage, it makes a semantic copy of the input to the output. If any options are +specified, the output may be modified along the way, e.g. by removing sections. +.sp +If no output file is specified, the input file is modified in\-place. If "\-" is +specified for the input file, the input is read from the program\(aqs standard +input stream. If "\-" is specified for the output file, the output is written to +the standard output stream of the program. +.sp +If the input is an archive, any requested operations will be applied to each +archive member individually. +.sp +The tool is still in active development, but in most scenarios it works as a +drop\-in replacement for GNU\(aqs \fBobjcopy\fP\&. +.SH GENERIC AND CROSS-PLATFORM OPTIONS +.sp +The following options are either agnostic of the file format, or apply to +multiple file formats. +.INDENT 0.0 +.TP +.B \-\-add\-gnu\-debuglink +Add a .gnu_debuglink section for \fB\fP to the output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-add\-section +Add a section named \fB
\fP with the contents of \fB\fP to the +output. For ELF objects the section will be of type \fISHT_NOTE\fP, if the name +starts with ".note". Otherwise, it will have type \fISHT_PROGBITS\fP\&. Can be +specified multiple times to add multiple sections. +.sp +For MachO objects, \fB
\fP must be formatted as +\fB,
\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-binary\-architecture , \-B +Ignored for compatibility. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-disable\-deterministic\-archives, \-U +Use real values for UIDs, GIDs and timestamps when updating archive member +headers. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-discard\-all, \-x +Remove most local symbols from the output. Different file formats may limit +this to a subset of the local symbols. For example, file and section symbols in +ELF objects will not be discarded. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dump\-section
= +Dump the contents of section \fB
\fP into the file \fB\fP\&. Can be +specified multiple times to dump multiple sections to different files. +\fB\fP is unrelated to the input and output files provided to +\fBllvm\-objcopy\fP and as such the normal copying and editing +operations will still be performed. No operations are performed on the sections +prior to dumping them. +.sp +For MachO objects, \fB
\fP must be formatted as +\fB,
\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-enable\-deterministic\-archives, \-D +Enable deterministic mode when copying archives, i.e. use 0 for archive member +header UIDs, GIDs and timestamp fields. On by default. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-help, \-h +Print a summary of command line options. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-only\-keep\-debug +Produce a debug file as the output that only preserves contents of sections +useful for debugging purposes. +.sp +For ELF objects, this removes the contents of \fISHF_ALLOC\fP sections that are not +\fISHT_NOTE\fP by making them \fISHT_NOBITS\fP and shrinking the program headers where +possible. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-only\-section
, \-j +Remove all sections from the output, except for sections named \fB
\fP\&. +Can be specified multiple times to keep multiple sections. +.sp +For MachO objects, \fB
\fP must be formatted as +\fB,
\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-redefine\-sym = +Rename symbols called \fB\fP to \fB\fP in the output. Can be specified +multiple times to rename multiple symbols. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-redefine\-syms +Rename symbols in the output as described in the file \fB\fP\&. In the +file, each line represents a single symbol to rename, with the old name and new +name separated by whitespace. Leading and trailing whitespace is ignored, as is +anything following a \(aq#\(aq. Can be specified multiple times to read names from +multiple files. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-regex +If specified, symbol and section names specified by other switches are treated +as extended POSIX regular expression patterns. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-remove\-section
, \-R +Remove the specified section from the output. Can be specified multiple times +to remove multiple sections simultaneously. +.sp +For MachO objects, \fB
\fP must be formatted as +\fB,
\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-set\-section\-alignment
= +Set the alignment of section \fB
\fP to \fI\(ga\fP\&. Can be specified +multiple times to update multiple sections. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-all\-gnu +Remove all symbols, debug sections and relocations from the output. This option +is equivalent to GNU \fBobjcopy\fP\(aqs \fB\-\-strip\-all\fP switch. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-all, \-S +For ELF objects, remove from the output all symbols and non\-alloc sections not +within segments, except for .gnu.warning, .ARM.attribute sections and the +section name table. +.sp +For COFF and Mach\-O objects, remove all symbols, debug sections, and +relocations from the output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-debug, \-g +Remove all debug sections from the output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-symbol , \-N +Remove all symbols named \fB\fP from the output. Can be specified +multiple times to remove multiple symbols. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-symbols +Remove all symbols whose names appear in the file \fB\fP, from the +output. In the file, each line represents a single symbol name, with leading +and trailing whitespace ignored, as is anything following a \(aq#\(aq. Can be +specified multiple times to read names from multiple files. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-unneeded\-symbol +Remove from the output all symbols named \fB\fP that are local or +undefined and are not required by any relocation. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-unneeded\-symbols +Remove all symbols whose names appear in the file \fB\fP, from the +output, if they are local or undefined and are not required by any relocation. +In the file, each line represents a single symbol name, with leading and +trailing whitespace ignored, as is anything following a \(aq#\(aq. Can be specified +multiple times to read names from multiple files. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-strip\-unneeded +Remove from the output all local or undefined symbols that are not required by +relocations. Also remove all debug sections. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-version, \-V +Display the version of the \fBllvm\-objcopy\fP executable. +.UNINDENT +.INDENT 0.0 +.TP +.B @ +Read command\-line options and commands from response file \fI\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wildcard, \-w +Allow wildcard syntax for symbol\-related flags. On by default for +section\-related flags. Incompatible with \-\-regex. +.sp +Wildcard syntax allows the following special symbols: +.TS +center; +|l|l|l|. +_ +T{ +Character +T} T{ +Meaning +T} T{ +Equivalent +T} +_ +T{ +\fB*\fP +T} T{ +Any number of characters +T} T{ +\fB\&.*\fP +T} +_ +T{ +\fB?\fP +T} T{ +Any single character +T} T{ +\fB\&.\fP +T} +_ +T{ +\fB\e\fP +T} T{ +Escape the next character +T} T{ +\fB\e\fP +T} +_ +T{ +\fB[a\-z]\fP +T} T{ +Character class +T} T{ +\fB[a\-z]\fP +T} +_ +T{ +\fB[!a\-z]\fP, \fB[^a\-z]\fP +T} T{ +Negated character class +T} T{ +\fB[^a\-z]\fP +T} +_ +.TE +.sp +Additionally, starting a wildcard with \(aq!\(aq will prevent a match, even if +another flag matches. For example \fB\-w \-N \(aq*\(aq \-N \(aq!x\(aq\fP will strip all symbols +except for \fBx\fP\&. +.sp +The order of wildcards does not matter. For example, \fB\-w \-N \(aq*\(aq \-N \(aq!x\(aq\fP is +the same as \fB\-w \-N \(aq!x\(aq \-N \(aq*\(aq\fP\&. +.UNINDENT +.SH COFF-SPECIFIC OPTIONS +.sp +The following options are implemented only for COFF objects. If used with other +objects, \fBllvm\-objcopy\fP will either emit an error or silently ignore +them. +.SH ELF-SPECIFIC OPTIONS +.sp +The following options are implemented only for ELF objects. If used with other +objects, \fBllvm\-objcopy\fP will either emit an error or silently ignore +them. +.INDENT 0.0 +.TP +.B \-\-add\-symbol =[
:][,] +Add a new symbol called \fB\fP to the output symbol table, in the section +named \fB
\fP, with value \fB\fP\&. If \fB
\fP is not specified, +the symbol is added as an absolute symbol. The \fB\fP affect the symbol +properties. Accepted values are: +.INDENT 7.0 +.IP \(bu 2 +\fIglobal\fP = the symbol will have global binding. +.IP \(bu 2 +\fIlocal\fP = the symbol will have local binding. +.IP \(bu 2 +\fIweak\fP = the symbol will have weak binding. +.IP \(bu 2 +\fIdefault\fP = the symbol will have default visibility. +.IP \(bu 2 +\fIhidden\fP = the symbol will have hidden visibility. +.IP \(bu 2 +\fIprotected\fP = the symbol will have protected visibility. +.IP \(bu 2 +\fIfile\fP = the symbol will be an \fISTT_FILE\fP symbol. +.IP \(bu 2 +\fIsection\fP = the symbol will be an \fISTT_SECTION\fP symbol. +.IP \(bu 2 +\fIobject\fP = the symbol will be an \fISTT_OBJECT\fP symbol. +.IP \(bu 2 +\fIfunction\fP = the symbol will be an \fISTT_FUNC\fP symbol. +.IP \(bu 2 +\fIindirect\-function\fP = the symbol will be an \fISTT_GNU_IFUNC\fP symbol. +.UNINDENT +.sp +Additionally, the following flags are accepted but ignored: \fIdebug\fP, +\fIconstructor\fP, \fIwarning\fP, \fIindirect\fP, \fIsynthetic\fP, \fIunique\-object\fP, \fIbefore\fP\&. +.sp +Can be specified multiple times to add multiple symbols. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-allow\-broken\-links +Allow \fBllvm\-objcopy\fP to remove sections even if it would leave invalid +section references. Any invalid sh_link fields will be set to zero. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-build\-id\-link\-dir +Set the directory used by \fI\%\-\-build\-id\-link\-input\fP and +\fI\%\-\-build\-id\-link\-output\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-build\-id\-link\-input +Hard\-link the input to \fB/xx/xxx\fP, where \fB\fP is the directory +specified by \fI\%\-\-build\-id\-link\-dir\fP\&. The path used is derived from the +hex build ID. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-build\-id\-link\-output +Hard\-link the output to \fB/xx/xxx\fP, where \fB\fP is the directory +specified by \fI\%\-\-build\-id\-link\-dir\fP\&. The path used is derived from the +hex build ID. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-change\-start , \-\-adjust\-start +Add \fB\fP to the program\(aqs start address. Can be specified multiple +times, in which case the values will be applied cumulatively. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-compress\-debug\-sections [