d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Regenerate ReStructuredText based manpages for llvm-project tools:

Browse Source 
* 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
This commit is contained in:
dim 2020-06-27 11:56:49 +00:00
parent 69056dde94
commit 5b72ffe827
31 changed files with 2615 additions and 692 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
tools/build/mk/OptionalObsoleteFiles.inc
View File

@ -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

8
usr.bin/clang/bugpoint/bugpoint.1
View File

@ -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.
.

37
usr.bin/clang/clang/clang.1
View File

@ -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=<kind>, \-fno\-lax\-vector\-conversions
Allow loose type checking rules for implicit vector conversions.
Possible values of <kind>:
.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
<kind> 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=<version>
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=<architecture> or \-arch <architecture>). 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=<cpu>
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 (<http://clang.llvm.org>)
.SH COPYRIGHT
2007-2018, The Clang Team
2007-2020, The Clang Team
.\" Generated by docutils manpage writer.
.

34
usr.bin/clang/llc/llc.1
View File

@ -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 <filename>
Use \fB<filename>\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=<dso_path>
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.
.

72
usr.bin/clang/lldb/lldb.1
View File

@ -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 <value>
Alias for –attach\-name
Alias for \-\-attach\-name
.UNINDENT
.INDENT 0.0
.TP
.B \-p <value>
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 <value>
Alias for –source\-on\-crash
Alias for \-\-source\-on\-crash
.UNINDENT
.INDENT 0.0
.TP
.B \-k <value>
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 <value>
Alias for –one\-line\-before\-file
Alias for \-\-one\-line\-before\-file
.UNINDENT
.INDENT 0.0
.TP
.B \-o <value>
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 <value>
Alias for –source\-before\-file
Alias for \-\-source\-before\-file
.UNINDENT
.INDENT 0.0
.TP
.B \-s <value>
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 <value>
Alias for –arch
Alias for \-\-arch
.UNINDENT
.INDENT 0.0
.TP
@ -203,7 +203,7 @@ Tells the debugger to use the full path to <filename> as the core file.
.INDENT 0.0
.TP
.B \-c <value>
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 <filename> as the program to be debugged.
.INDENT 0.0
.TP
.B \-f <value>
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=<flags>
Alias for –repl=<flags>
Alias for \-\-repl=<flags>
.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 <value>
Alias for –repl\-language
Alias for \-\-repl\-language
.UNINDENT
.SH SCRIPTING
.INDENT 0.0
.TP
.B \-l <value>
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 <process\-name>
.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

9
usr.bin/clang/lli/lli.1
View File

@ -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.
.

1
usr.bin/clang/llvm-ar/Makefile
View File

@ -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

554
usr.bin/clang/llvm-ar/llvm-ar.1
View File

@ -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] <archive> [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=<string> \- 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 "!<arch>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=<type>
This option allows for default, gnu, darwin or bsd \fB<type>\fP to be selected.
When creating an \fBarchive\fP, \fB<type>\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 @<FILE>
Read command\-line options and commands from response file \fB<FILE>\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 <file>
Append \fB<file>\fP to the current archive.
.UNINDENT
.INDENT 0.0
.TP
.B DELETE <file>
Delete the member of the current archive whose file name, excluding directory
components, matches \fB<file>\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.
.

52
usr.bin/clang/llvm-ar/llvm-ranlib.1 Normal file
View File

@ -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.
.

8
usr.bin/clang/llvm-as/llvm-as.1
View File

@ -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.
.

8
usr.bin/clang/llvm-bcanalyzer/llvm-bcanalyzer.1
View File

@ -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.
.

60
usr.bin/clang/llvm-cov/llvm-cov.1
View File

@ -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=<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=<PATTERN>
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.
.

1
usr.bin/clang/llvm-cxxfilt/Makefile
View File

@ -1,7 +1,6 @@
# $FreeBSD$
PROG_CXX= llvm-cxxfilt
MAN=
SRCDIR= llvm/tools/llvm-cxxfilt
SRCS+= llvm-cxxfilt.cpp

117
usr.bin/clang/llvm-cxxfilt/llvm-cxxfilt.1 Normal file
View File

@ -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=<value>, \-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 @<FILE>
Read command\-line options from response file \fI<FILE>\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.
.

6
usr.bin/clang/llvm-diff/llvm-diff.1
View File

@ -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.
.

8
usr.bin/clang/llvm-dis/llvm-dis.1
View File

@ -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.
.

92
usr.bin/clang/llvm-dwarfdump/llvm-dwarfdump.1
View File

@ -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=<offset>\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 <pattern>, \-\-name=<pattern>
.B \-i, \-\-ignore\-case
Ignore case distinctions when using \fI\%\-\-name\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-n <name>, \-\-name=<name>
Find and print all debug info entries whose name
(\fIDW_AT_name\fP attribute) matches the exact text in
<pattern>. Use the \fI\%\-\-regex\fP option to have
<pattern> become a regular expression for more flexible
pattern matching.
(\fIDW_AT_name\fP attribute) is <name>.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-lookup=<address>
Lookup <address> in the debug information and print out the file,
Look up <address> in the debug information and print out the file,
function, block, and line table details.
.UNINDENT
.INDENT 0.0
.TP
.B \-o <path>, \-\-out\-file=<path>
Redirect output to a file specified by <path>.
.B \-o <path>
Redirect output to a file specified by <path>, 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=<offset>\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 <n>, \-\-recurse\-depth=<n>
Only recurse to a maximum depth of <n> when dumping debug info
entries.
.B \-\-parent\-recurse\-depth=<N>
When displaying debug info entry parents, only show them to a
maximum depth of <N>.
.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 <N>, \-\-recurse\-depth=<N>
When displaying debug info entries, only show children to a maximum
depth of <N>.
.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 <pattern> strings as regular expressions when searching
instead of just as an exact string match.
Treat any <name> 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 [=<offset>], \-\-debug\-gnu\-pubnames, \-\-debug\-gnu\-pubtypes, \-\-debug\-info [=<offset>], \-\-debug\-line [=<offset>], \-\-debug\-loc [=<offset>], \-\-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 [=<offset>], \-\-debug\-gnu\-pubnames, \-\-debug\-gnu\-pubtypes, \-\-debug\-info [=<offset>], \-\-debug\-line [=<offset>], \-\-debug\-line\-str, \-\-debug\-loc [=<offset>], \-\-debug\-loclists [=<offset>], \-\-debug\-macro, \-\-debug\-names, \-\-debug\-pubnames, \-\-debug\-pubtypes, \-\-debug\-ranges, \-\-debug\-rnglists, \-\-debug\-str, \-\-debug\-str\-offsets, \-\-debug\-tu\-index, \-\-debug\-types, \-\-eh\-frame [=<offset>], \-\-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=<offset>\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 @<FILE>
Read command\-line options from \fI<FILE>\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.
.

8
usr.bin/clang/llvm-extract/llvm-extract.1
View File

@ -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.
.

8
usr.bin/clang/llvm-link/llvm-link.1
View File

@ -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.
.

523
usr.bin/clang/llvm-mca/llvm-mca.1
View File

@ -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 <filename>
Use \fB<filename>\fP as the output filename. See the summary above for more
details.
.UNINDENT
.INDENT 0.0
.TP
.B \-mtriple=<target triple>
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=<width>
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 <total>
.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<total>\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.
.

312
usr.bin/clang/llvm-nm/llvm-nm.1
View File

@ -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,11 +36,11 @@ 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
@ -48,61 +48,145 @@ 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.
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=<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=<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 @<FILE>
Read command\-line options from response file \fI<FILE>\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=<arch1[,arch2,...]>
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=<segment section>
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.
.

1
usr.bin/clang/llvm-objcopy/Makefile
View File

@ -1,7 +1,6 @@
# $FreeBSD$
PROG_CXX= llvm-objcopy
MAN=
SRCDIR= llvm/tools/llvm-objcopy
SRCS+= Buffer.cpp

721
usr.bin/clang/llvm-objcopy/llvm-objcopy.1 Normal file
View File

@ -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 <debug\-file>
Add a .gnu_debuglink section for \fB<debug\-file>\fP to the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-add\-section <section=file>
Add a section named \fB<section>\fP with the contents of \fB<file>\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<section>\fP must be formatted as
\fB<segment name>,<section name>\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-binary\-architecture <arch>, \-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 <section>=<file>
Dump the contents of section \fB<section>\fP into the file \fB<file>\fP\&. Can be
specified multiple times to dump multiple sections to different files.
\fB<file>\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<section>\fP must be formatted as
\fB<segment name>,<section name>\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 <section>, \-j
Remove all sections from the output, except for sections named \fB<section>\fP\&.
Can be specified multiple times to keep multiple sections.
.sp
For MachO objects, \fB<section>\fP must be formatted as
\fB<segment name>,<section name>\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-redefine\-sym <old>=<new>
Rename symbols called \fB<old>\fP to \fB<new>\fP in the output. Can be specified
multiple times to rename multiple symbols.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-redefine\-syms <filename>
Rename symbols in the output as described in the file \fB<filename>\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 <section>, \-R
Remove the specified section from the output. Can be specified multiple times
to remove multiple sections simultaneously.
.sp
For MachO objects, \fB<section>\fP must be formatted as
\fB<segment name>,<section name>\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-set\-section\-alignment <section>=<align>
Set the alignment of section \fB<section>\fP to \fI<align>\(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 <symbol>, \-N
Remove all symbols named \fB<symbol>\fP from the output. Can be specified
multiple times to remove multiple symbols.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-symbols <filename>
Remove all symbols whose names appear in the file \fB<filename>\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 <symbol>
Remove from the output all symbols named \fB<symbol>\fP that are local or
undefined and are not required by any relocation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-unneeded\-symbols <filename>
Remove all symbols whose names appear in the file \fB<filename>\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 @<FILE>
Read command\-line options and commands from response file \fI<FILE>\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 <name>=[<section>:]<value>[,<flags>]
Add a new symbol called \fB<name>\fP to the output symbol table, in the section
named \fB<section>\fP, with value \fB<value>\fP\&. If \fB<section>\fP is not specified,
the symbol is added as an absolute symbol. The \fB<flags>\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 <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 <suffix>
Hard\-link the input to \fB<dir>/xx/xxx<suffix>\fP, where \fB<dir>\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 <suffix>
Hard\-link the output to \fB<dir>/xx/xxx<suffix>\fP, where \fB<dir>\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 <incr>, \-\-adjust\-start
Add \fB<incr>\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 [<style>]
Compress DWARF debug sections in the output, using the specified style.
Supported styles are \fIzlib\-gnu\fP and \fIzlib\fP\&. Defaults to \fIzlib\fP if no style is
specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-decompress\-debug\-sections
Decompress any compressed DWARF debug sections in the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-discard\-locals, \-X
Remove local symbols starting with ".L" from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-extract\-dwo
Remove all sections that are not DWARF .dwo sections from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-extract\-main\-partition
Extract the main partition from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-extract\-partition <name>
Extract the named partition from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-globalize\-symbol <symbol>
Mark any defined symbols named \fB<symbol>\fP as global symbols in the output.
Can be specified multiple times to mark multiple symbols.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-globalize\-symbols <filename>
Read a list of names from the file \fB<filename>\fP and mark defined symbols with
those names as global in the output. In the file, each line represents a single
symbol, 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 \-\-input\-target <format>, \-I
Read the input as the specified format. See \fI\%SUPPORTED FORMATS\fP for a list of
valid \fB<format>\fP values. If unspecified, \fBllvm\-objcopy\fP will attempt
to determine the format automatically.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-file\-symbols
Keep symbols of type \fISTT_FILE\fP, even if they would otherwise be stripped.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-global\-symbol <symbol>
Make all symbols local in the output, except for symbols with the name
\fB<symbol>\fP\&. Can be specified multiple times to ignore multiple symbols.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-global\-symbols <filename>
Make all symbols local in the output, except for symbols named in the file
\fB<filename>\fP\&. In the file, each line represents a single symbol, 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 \-\-keep\-section <section>
When removing sections from the output, do not remove sections named
\fB<section>\fP\&. Can be specified multiple times to keep multiple sections.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-symbol <symbol>, \-K
When removing symbols from the output, do not remove symbols named
\fB<symbol>\fP\&. Can be specified multiple times to keep multiple symbols.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-symbols <filename>
When removing symbols from the output do not remove symbols named in the file
\fB<filename>\fP\&. In the file, each line represents a single symbol, 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 \-\-localize\-hidden
Make all symbols with hidden or internal visibility local in the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-localize\-symbol <symbol>, \-L
Mark any defined non\-common symbol named \fB<symbol>\fP as a local symbol in the
output. Can be specified multiple times to mark multiple symbols as local.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-localize\-symbols <filename>
Read a list of names from the file \fB<filename>\fP and mark defined non\-common
symbols with those names as local in the output. In the file, each line
represents a single symbol, 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 \-\-new\-symbol\-visibility <visibility>
Specify the visibility of the symbols automatically created when using binary
input or \fI\%\-\-add\-symbol\fP\&. Valid options are:
.INDENT 7.0
.IP \(bu 2
\fIdefault\fP
.IP \(bu 2
\fIhidden\fP
.IP \(bu 2
\fIinternal\fP
.IP \(bu 2
\fIprotected\fP
.UNINDENT
.sp
The default is \fIdefault\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-output\-target <format>, \-O
Write the output as the specified format. See \fI\%SUPPORTED FORMATS\fP for a list
of valid \fB<format>\fP values. If unspecified, the output format is assumed to
be the same as the input file\(aqs format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-prefix\-alloc\-sections <prefix>
Add \fB<prefix>\fP to the front of the names of all allocatable sections in the
output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-prefix\-symbols <prefix>
Add \fB<prefix>\fP to the front of every symbol name in the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-preserve\-dates, \-p
Preserve access and modification timestamps in the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-rename\-section <old>=<new>[,<flag>,...]
Rename sections called \fB<old>\fP to \fB<new>\fP in the output, and apply any
specified \fB<flag>\fP values. See \fI\%\-\-set\-section\-flags\fP for a list of
supported flags. Can be specified multiple times to rename multiple sections.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-set\-section\-flags <section>=<flag>[,<flag>,...]
Set section properties in the output of section \fB<section>\fP based on the
specified \fB<flag>\fP values. Can be specified multiple times to update multiple
sections.
.sp
Following is a list of supported flags and their effects:
.INDENT 7.0
.IP \(bu 2
\fIalloc\fP = add the \fISHF_ALLOC\fP flag.
.IP \(bu 2
\fIload\fP = if the section has \fISHT_NOBITS\fP type, mark it as a \fISHT_PROGBITS\fP
section.
.IP \(bu 2
\fIreadonly\fP = if this flag is not specified, add the \fISHF_WRITE\fP flag.
.IP \(bu 2
\fIcode\fP = add the \fISHF_EXECINSTR\fP flag.
.IP \(bu 2
\fImerge\fP = add the \fISHF_MERGE\fP flag.
.IP \(bu 2
\fIstrings\fP = add the \fISHF_STRINGS\fP flag.
.IP \(bu 2
\fIcontents\fP = if the section has \fISHT_NOBITS\fP type, mark it as a \fISHT_PROGBITS\fP
section.
.UNINDENT
.sp
The following flags are also accepted, but are ignored for GNU compatibility:
\fInoload\fP, \fIdebug\fP, \fIdata\fP, \fIrom\fP, \fIshare\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-set\-start\-addr <addr>
Set the start address of the output to \fB<addr>\fP\&. Overrides any previously
specified \fI\%\-\-change\-start\fP or \fI\%\-\-adjust\-start\fP options.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-split\-dwo <dwo\-file>
Equivalent to running \fBllvm\-objcopy\fP with \fI\%\-\-extract\-dwo\fP and
\fB<dwo\-file>\fP as the output file and no other options, and then with
\fI\%\-\-strip\-dwo\fP on the input file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-dwo
Remove all DWARF .dwo sections from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-non\-alloc
Remove from the output all non\-allocatable sections that are not within
segments.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-sections
Remove from the output all section headers and all section data not within
segments. Note that many tools will not be able to use an object without
section headers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-target <format>, \-F
Equivalent to \fI\%\-\-input\-target\fP and \fI\%\-\-output\-target\fP for the
specified format. See \fI\%SUPPORTED FORMATS\fP for a list of valid \fB<format>\fP
values.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-weaken\-symbol <symbol>, \-W
Mark any global symbol named \fB<symbol>\fP as a weak symbol in the output. Can
be specified multiple times to mark multiple symbols as weak.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-weaken\-symbols <filename>
Read a list of names from the file \fB<filename>\fP and mark global symbols with
those names as weak in the output. In the file, each line represents a single
symbol, 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 \-\-weaken
Mark all defined global symbols as weak in the output.
.UNINDENT
.SH SUPPORTED FORMATS
.sp
The following values are currently supported by \fBllvm\-objcopy\fP for the
\fI\%\-\-input\-target\fP, \fI\%\-\-output\-target\fP, and \fI\%\-\-target\fP
options. For GNU \fBobjcopy\fP compatibility, the values are all bfdnames.
.INDENT 0.0
.IP \(bu 2
\fIbinary\fP
.IP \(bu 2
\fIihex\fP
.IP \(bu 2
\fIelf32\-i386\fP
.IP \(bu 2
\fIelf32\-x86\-64\fP
.IP \(bu 2
\fIelf64\-x86\-64\fP
.IP \(bu 2
\fIelf32\-iamcu\fP
.IP \(bu 2
\fIelf32\-littlearm\fP
.IP \(bu 2
\fIelf64\-aarch64\fP
.IP \(bu 2
\fIelf64\-littleaarch64\fP
.IP \(bu 2
\fIelf32\-littleriscv\fP
.IP \(bu 2
\fIelf64\-littleriscv\fP
.IP \(bu 2
\fIelf32\-powerpc\fP
.IP \(bu 2
\fIelf32\-powerpcle\fP
.IP \(bu 2
\fIelf64\-powerpc\fP
.IP \(bu 2
\fIelf64\-powerpcle\fP
.IP \(bu 2
\fIelf32\-bigmips\fP
.IP \(bu 2
\fIelf32\-ntradbigmips\fP
.IP \(bu 2
\fIelf32\-ntradlittlemips\fP
.IP \(bu 2
\fIelf32\-tradbigmips\fP
.IP \(bu 2
\fIelf32\-tradlittlemips\fP
.IP \(bu 2
\fIelf64\-tradbigmips\fP
.IP \(bu 2
\fIelf64\-tradlittlemips\fP
.IP \(bu 2
\fIelf32\-sparc\fP
.IP \(bu 2
\fIelf32\-sparcel\fP
.UNINDENT
.sp
Additionally, all targets except \fIbinary\fP and \fIihex\fP can have \fI\-freebsd\fP as a
suffix.
.SH BINARY INPUT AND OUTPUT
.sp
If \fIbinary\fP is used as the value for \fI\%\-\-input\-target\fP, the input file
will be embedded as a data section in an ELF relocatable object, with symbols
\fB_binary_<file_name>_start\fP, \fB_binary_<file_name>_end\fP, and
\fB_binary_<file_name>_size\fP representing the start, end and size of the data,
where \fB<file_name>\fP is the path of the input file as specified on the command
line with non\-alphanumeric characters converted to \fB_\fP\&.
.sp
If \fIbinary\fP is used as the value for \fI\%\-\-output\-target\fP, the output file
will be a raw binary file, containing the memory image of the input file.
Symbols and relocation information will be discarded. The image will start at
the address of the first loadable section in the output.
.SH EXIT STATUS
.sp
\fBllvm\-objcopy\fP exits with a non\-zero exit code if there is an error.
Otherwise, it exits with code 0.
.SH BUGS
.sp
To report bugs, please visit <\fI\%http://llvm.org/bugs/\fP>.
.sp
There is a known issue with \fI\%\-\-input\-target\fP and \fI\%\-\-target\fP
causing only \fBbinary\fP and \fBihex\fP formats to have any effect. Other values
will be ignored and \fBllvm\-objcopy\fP will attempt to guess the input
format.
.SH SEE ALSO
.sp
\fBllvm\-strip(1)\fP
.SH AUTHOR
Maintained by the LLVM Team (https://llvm.org/).
.SH COPYRIGHT
2003-2020, LLVM Project
.\" Generated by docutils manpage writer.
.

7
usr.bin/clang/llvm-objdump/llvm-objdump.1
View File

@ -1,7 +1,8 @@
.\" This file is distributed under the University of Illinois Open Source
.\" License.
.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
.\" See https://llvm.org/LICENSE.txt for license information.
.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
.\"
.Dd November 27, 2018
.Dd December 19, 2018
.Dt LLVM-OBJDUMP 1
.Os
.Sh NAME

6
usr.bin/clang/llvm-pdbutil/llvm-pdbutil.1
View File

@ -1,7 +1,7 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "LLVM-PDBUTIL" "1" "2018-08-02" "7" "LLVM"
.TH "LLVM-PDBUTIL" "1" "2020-06-26" "10" "LLVM"
.SH NAME
llvm-pdbutil \- PDB File forensics and diagnostics
.
@ -738,8 +738,8 @@ Merge two PDB files into a single file.
.sp
Write the resulting PDB to the specified file.
.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.
.

104
usr.bin/clang/llvm-profdata/llvm-profdata.1
View File

@ -1,7 +1,7 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "LLVM-PROFDATA" "1" "2018-08-02" "7" "LLVM"
.TH "LLVM-PROFDATA" "1" "2020-06-26" "10" "LLVM"
.SH NAME
llvm-profdata \- Profile data tool
.
@ -44,6 +44,8 @@ data files.
\fI\%merge\fP
.IP \(bu 2
\fI\%show\fP
.IP \(bu 2
\fI\%overlap\fP
.UNINDENT
.SH MERGE
.SS SYNOPSIS
@ -94,6 +96,17 @@ be of the form <filename> or <weight>,<filename>.
.UNINDENT
.INDENT 0.0
.TP
.B \-remapping\-file=path, \-r=path
Specify a file which contains a remapping from symbol names in the input
profile to the symbol names that should be used in the output profile. The
file should consist of lines of the form \fB<input\-symbol> <output\-symbol>\fP\&.
Blank lines and lines starting with \fB#\fP are skipped.
.sp
The llvm\-cxxmap tool can be used to generate the symbol
remapping file.
.UNINDENT
.INDENT 0.0
.TP
.B \-instr (default)
Specify that the input profile is an instrumentation\-based profile.
.UNINDENT
@ -139,6 +152,15 @@ optimization during PGO.
Use N threads to perform profile merging. When N=0, llvm\-profdata auto\-detects
an appropriate number of threads to use. This is the default.
.UNINDENT
.INDENT 0.0
.TP
.B \-failure\-mode=[any|all]
Set the failure mode. There are two options: \(aqany\(aq causes the merge command to
fail if any profiles are invalid, and \(aqall\(aq causes the merge command to fail
only if all profiles are invalid. If \(aqall\(aq is set, information from any
invalid profiles is excluded from the final merged product. The default
failure mode is \(aqany\(aq.
.UNINDENT
.SS EXAMPLES
.SS Basic Usage
.sp
@ -247,13 +269,89 @@ Specify that the input profile is a sample\-based profile.
.B \-memop\-sizes
Show the profiled sizes of the memory intrinsic calls for shown functions.
.UNINDENT
.INDENT 0.0
.TP
.B \-value\-cutoff=n
Show only those functions whose max count values are greater or equal to \fBn\fP\&.
By default, the value\-cutoff is set to 0.
.UNINDENT
.INDENT 0.0
.TP
.B \-list\-below\-cutoff
Only output names of functions whose max count value are below the cutoff
value.
.UNINDENT
.INDENT 0.0
.TP
.B \-showcs
Only show context sensitive profile counts. The default is to filter all
context sensitive profile counts.
.UNINDENT
.SH OVERLAP
.SS SYNOPSIS
.sp
\fBllvm\-profdata overlap\fP [\fIoptions\fP] [\fIbase profile file\fP] [\fItest profile file\fP]
.SS DESCRIPTION
.sp
\fBllvm\-profdata overlap\fP takes two profile data files and displays the
\fIoverlap\fP of counter distribution between the whole files and between any of the
specified functions.
.sp
In this command, \fIoverlap\fP is defined as follows:
Suppose \fIbase profile file\fP has the following counts:
{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
and \fItest profile file\fP has
{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
\fIbase profile file\fP and \fItest profile file\fP, respectively.
Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and
sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
\fIoverlap\fP = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
+ min(c1_n/sum_1, c2_n/sum_2).
.sp
The result overlap distribution is a percentage number, ranging from 0.0% to
100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
overlap.
.sp
Here is an example, if \fIbase profile file\fP has counts of {400, 600}, and
\fItest profile file\fP has matched counts of {60000, 40000}. The \fIoverlap\fP is 80%.
.SS OPTIONS
.INDENT 0.0
.TP
.B \-function=string
Print details for a function if the function\(aqs name contains the given string.
.UNINDENT
.INDENT 0.0
.TP
.B \-help
Print a summary of command line options.
.UNINDENT
.INDENT 0.0
.TP
.B \-o=output or \-o output
Specify the output file name. If \fIoutput\fP is \fB\-\fP or it isn\(aqt specified,
then the output is sent to standard output.
.UNINDENT
.INDENT 0.0
.TP
.B \-value\-cutoff=n
Show only those functions whose max count values are greater or equal to \fBn\fP\&.
By default, the value\-cutoff is set to max of unsigned long long.
.UNINDENT
.INDENT 0.0
.TP
.B \-cs
Only show overlap for the context sensitive profile counts. The default is to show
non\-context sensitive profile counts.
.UNINDENT
.SH EXIT STATUS
.sp
\fBllvm\-profdata\fP returns 1 if the command is omitted or is invalid,
if it cannot read input files, or if there is a mismatch between their data.
.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.
.

3
usr.bin/clang/llvm-symbolizer/Makefile
View File

@ -1,10 +1,13 @@
# $FreeBSD$
PROG_CXX= llvm-symbolizer
MAN= llvm-symbolizer.1 llvm-addr2line.1
SRCDIR= llvm/tools/llvm-symbolizer
SRCS+= llvm-symbolizer.cpp
LIBADD+= z
LINKS+= ${BINDIR}/llvm-symbolizer ${BINDIR}/llvm-addr2line
.include "../llvm.prog.mk"

66
usr.bin/clang/llvm-symbolizer/llvm-addr2line.1 Normal file
View File

@ -0,0 +1,66 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "LLVM-ADDR2LINE" "1" "2020-06-26" "10" "LLVM"
.SH NAME
llvm-addr2line \- a drop-in replacement for addr2line
.
.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\-addr2line\fP [\fIoptions\fP]
.SH DESCRIPTION
.sp
\fBllvm\-addr2line\fP is an alias for the \fBllvm\-symbolizer(1)\fP
tool with different defaults. The goal is to make it a drop\-in replacement for
GNU\(aqs \fBaddr2line\fP\&.
.sp
Here are some of those differences:
.INDENT 0.0
.IP \(bu 2
Defaults not to print function names. Use \fI\%\-f\fP to enable that.
.IP \(bu 2
Defaults not to demangle function names. Use \fI\%\-C\fP to switch the
demangling on.
.IP \(bu 2
Defaults not to print inlined frames. Use \fI\%\-i\fP to show inlined
frames for a source code location in an inlined function.
.IP \(bu 2
Uses \fI\%\-\-output\-style=GNU\fP by default.
.IP \(bu 2
Parses options from the environment variable \fBLLVM_ADDR2LINE_OPTS\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBllvm\-symbolizer(1)\fP
.SH AUTHOR
Maintained by the LLVM Team (https://llvm.org/).
.SH COPYRIGHT
2003-2020, LLVM Project
.\" Generated by docutils manpage writer.
.

459
usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1
View File

@ -1,7 +1,7 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "LLVM-SYMBOLIZER" "1" "2018-08-02" "7" "LLVM"
.TH "LLVM-SYMBOLIZER" "1" "2020-06-26" "10" "LLVM"
.SH NAME
llvm-symbolizer \- convert addresses into source code locations
.
@ -33,64 +33,180 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBllvm\-symbolizer\fP [options]
\fBllvm\-symbolizer\fP [\fIoptions\fP] [\fIaddresses...\fP]
.SH DESCRIPTION
.sp
\fBllvm\-symbolizer\fP reads object file names and addresses from standard
input and prints corresponding source code locations to standard output.
If object file is specified in command line, \fBllvm\-symbolizer\fP
processes only addresses from standard input, the rest is output verbatim.
This program uses debug info sections and symbol table in the object files.
.SH EXAMPLE
\fBllvm\-symbolizer\fP reads object file names and addresses from the
command\-line and prints corresponding source code locations to standard output.
.sp
If no address is specified on the command\-line, it reads the addresses from
standard input. If no object file is specified on the command\-line, but
addresses are, or if at any time an input value is not recognized, the input is
simply echoed to the output.
.sp
A positional argument or standard input value can be preceded by "DATA" or
"CODE" to indicate that the address should be symbolized as data or executable
code respectively. If neither is specified, "CODE" is assumed. DATA is
symbolized as address and symbol size rather than line number.
.sp
Object files can be specified together with the addresses either on standard
input or as positional arguments on the command\-line, following any "DATA" or
"CODE" prefix.
.sp
\fBllvm\-symbolizer\fP parses options from the environment variable
\fBLLVM_SYMBOLIZER_OPTS\fP after parsing options from the command line.
\fBLLVM_SYMBOLIZER_OPTS\fP is primarily useful for supplementing the command\-line
options when \fBllvm\-symbolizer\fP is invoked by another program or
runtime.
.SH EXAMPLES
.sp
All of the following examples use the following two source files as input. They
use a mixture of C\-style and C++\-style linkage to illustrate how these names are
printed differently (see \fI\%\-\-demangle\fP).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// test.h
extern "C" inline int foz() {
return 1234;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// test.cpp
#include "test.h"
int bar=42;
int foo() {
return bar;
}
int baz() {
volatile int k = 42;
return foz() + k;
}
int main() {
return foo() + baz();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These files are built as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ clang \-g test.cpp \-o test.elf
$ clang \-g \-O2 test.cpp \-o inlined.elf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example 1 \- addresses and object on command\-line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=test.elf 0x4004d0 0x400490
foz
/tmp/test.h:1:0
baz()
/tmp/test.cpp:11:0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example 2 \- addresses on standard input:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat addr.txt
a.out 0x4004f4
/tmp/b.out 0x400528
/tmp/c.so 0x710
/tmp/mach_universal_binary:i386 0x1f84
/tmp/mach_universal_binary:x86_64 0x100000f24
$ llvm\-symbolizer < addr.txt
0x4004a0
0x400490
0x4004d0
$ llvm\-symbolizer \-\-obj=test.elf < addr.txt
main
/tmp/a.cc:4
/tmp/test.cpp:15:0
f(int, int)
/tmp/b.cc:11
baz()
/tmp/test.cpp:11:0
h_inlined_into_g
/tmp/header.h:2
g_inlined_into_f
/tmp/header.h:7
f_inlined_into_main
/tmp/source.cc:3
main
/tmp/source.cc:8
foz
/tmp/./test.h:1:0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example 3 \- object specified with address:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
baz()
/tmp/test.cpp:11:0
_main
/tmp/source_i386.cc:8
foo()
/tmp/test.cpp:8:10
_main
/tmp/source_x86_64.cc:8
$ cat addr2.txt
0x4004f4
0x401000
$ llvm\-symbolizer \-obj=a.out < addr2.txt
main
/tmp/a.cc:4
test.elf 0x4004a0
inlined.elf 0x400480
foo(int)
/tmp/a.cc:12
$cat addr.txt
0x40054d
$llvm\-symbolizer \-inlining \-print\-address \-pretty\-print \-obj=addr.exe < addr.txt
0x40054d: inc at /tmp/x.c:3:3
(inlined by) main at /tmp/x.c:9:0
$llvm\-symbolizer \-inlining \-pretty\-print \-obj=addr.exe < addr.txt
inc at /tmp/x.c:3:3
(inlined by) main at /tmp/x.c:9:0
$ llvm\-symbolizer < addr2.txt
main
/tmp/test.cpp:15:0
foo()
/tmp/test.cpp:8:10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example 4 \- CODE and DATA prefixes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=test.elf "CODE 0x400490" "DATA 0x601028"
baz()
/tmp/test.cpp:11:0
bar
6295592 4
$ cat addr3.txt
CODE test.elf 0x4004a0
DATA inlined.elf 0x601028
$ llvm\-symbolizer < addr3.txt
main
/tmp/test.cpp:15:0
bar
6295592 4
.ft P
.fi
.UNINDENT
@ -98,66 +214,259 @@ inc at /tmp/x.c:3:3
.SH OPTIONS
.INDENT 0.0
.TP
.B \-obj
Path to object file to be symbolized.
.B \-\-adjust\-vma <offset>
Add the specified offset to object file addresses when performing lookups.
This can be used to perform lookups as if the object were relocated by the
offset.
.UNINDENT
.INDENT 0.0
.TP
.B \-functions=[none|short|linkage]
Specify the way function names are printed (omit function name,
print short function name, or print full linkage name, respectively).
Defaults to \fBlinkage\fP\&.
.B \-\-basenames, \-s
Strip directories when printing the file path.
.UNINDENT
.INDENT 0.0
.TP
.B \-use\-symbol\-table
Prefer function names stored in symbol table to function names
in debug info sections. Defaults to true.
.B \-\-demangle, \-C
Print demangled function names, if the names are mangled (e.g. the mangled
name \fI_Z3bazv\fP becomes \fIbaz()\fP, whilst the non\-mangled name \fIfoz\fP is printed
as is). Defaults to true.
.UNINDENT
.INDENT 0.0
.TP
.B \-demangle
Print demangled function names. Defaults to true.
.B \-\-dwp <path>
Use the specified DWP file at \fB<path>\fP for any CUs that have split DWARF
debug data.
.UNINDENT
.INDENT 0.0
.TP
.B \-inlining
If a source code location is in an inlined function, prints all the
inlnied frames. Defaults to true.
.B \-\-fallback\-debug\-path <path>
When a separate file contains debug data, and is referenced by a GNU debug
link section, use the specified path as a basis for locating the debug data if
it cannot be found relative to the object.
.UNINDENT
.INDENT 0.0
.TP
.B \-default\-arch
If a binary contains object files for multiple architectures (e.g. it is a
Mach\-O universal binary), symbolize the object file for a given architecture.
You can also specify architecture by writing \fBbinary_name:arch_name\fP in the
input (see example above). If architecture is not specified in either way,
address will not be symbolized. Defaults to empty string.
.B \-\-functions [<none|short|linkage>], \-f
Specify the way function names are printed (omit function name, print short
function name, or print full linkage name, respectively). Defaults to
\fBlinkage\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-dsym\-hint=<path/to/file.dSYM>
(Darwin\-only flag). If the debug info for a binary isn\(aqt present in the default
location, look for the debug info at the .dSYM path provided via the
\fB\-dsym\-hint\fP flag. This flag can be used multiple times.
.B \-\-help, \-h
Show help and usage for this command.
.UNINDENT
.INDENT 0.0
.TP
.B \-print\-address
.B \-\-help\-list
Show help and usage for this command without grouping the options into categories.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-inlining, \-\-inlines, \-i
If a source code location is in an inlined function, prints all the inlined
frames. Defaults to true.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-demangle
Don\(aqt print demangled function names.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-obj <path>, \-\-exe, \-e
Path to object file to be symbolized. If \fB\-\fP is specified, read the object
directly from the standard input stream.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-output\-style <LLVM|GNU>
Specify the preferred output style. Defaults to \fBLLVM\fP\&. When the output
style is set to \fBGNU\fP, the tool follows the style of GNU\(aqs \fBaddr2line\fP\&.
The differences from the \fBLLVM\fP style are:
.INDENT 7.0
.IP \(bu 2
Does not print the column of a source code location.
.IP \(bu 2
Does not add an empty line after the report for an address.
.IP \(bu 2
Does not replace the name of an inlined function with the name of the
topmost caller when inlined frames are not shown and \fI\%\-\-use\-symbol\-table\fP
is on.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be 0x400486 \-p
baz() at /tmp/test.cpp:11:18
(inlined by) main at /tmp/test.cpp:15:0
foo() at /tmp/test.cpp:6:3
$ llvm\-symbolizer \-\-output\-style=LLVM \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-i=0
main at /tmp/test.cpp:11:18
foo() at /tmp/test.cpp:6:3
$ llvm\-symbolizer \-\-output\-style=GNU \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-i=0
baz() at /tmp/test.cpp:11
foo() at /tmp/test.cpp:6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pretty\-print, \-p
Print human readable output. If \fI\%\-\-inlining\fP is specified, the
enclosing scope is prefixed by (inlined by).
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-inlining \-\-pretty\-print
baz() at /tmp/test.cpp:11:18
(inlined by) main at /tmp/test.cpp:15:0
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-print\-address, \-\-addresses, \-a
Print address before the source code location. Defaults to false.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=inlined.elf \-\-print\-address 0x4004be
0x4004be
baz()
/tmp/test.cpp:11:18
main
/tmp/test.cpp:15:0
$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-pretty\-print \-\-print\-address
0x4004be: baz() at /tmp/test.cpp:11:18
(inlined by) main at /tmp/test.cpp:15:0
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-pretty\-print
Print human readable output. If \fB\-inlining\fP is specified, enclosing scope is
prefixed by (inlined by). Refer to listed examples.
.B \-\-print\-source\-context\-lines <N>
Print \fBN\fP lines of source context for each symbolized address.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=test.elf 0x400490 \-\-print\-source\-context\-lines=2
baz()
/tmp/test.cpp:11:0
10 : volatile int k = 42;
11 >: return foz() + k;
12 : }
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-use\-symbol\-table
Prefer function names stored in symbol table to function names in debug info
sections. Defaults to true.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verbose
Print verbose line and column information.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ llvm\-symbolizer \-\-obj=inlined.elf \-\-verbose 0x4004be
baz()
Filename: /tmp/test.cpp
Function start line: 9
Line: 11
Column: 18
main
Filename: /tmp/test.cpp
Function start line: 14
Line: 15
Column: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Print version information for the tool.
.UNINDENT
.INDENT 0.0
.TP
.B @<FILE>
Read command\-line options from response file \fI<FILE>\fP\&.
.UNINDENT
.SH MACH-O SPECIFIC OPTIONS
.INDENT 0.0
.TP
.B \-\-default\-arch <arch>
If a binary contains object files for multiple architectures (e.g. it is a
Mach\-O universal binary), symbolize the object file for a given architecture.
You can also specify the architecture by writing \fBbinary_name:arch_name\fP in
the input (see example below). If the architecture is not specified in either
way, the address will not be symbolized. Defaults to empty string.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat addr.txt
/tmp/mach_universal_binary:i386 0x1f84
/tmp/mach_universal_binary:x86_64 0x100000f24
$ llvm\-symbolizer < addr.txt
_main
/tmp/source_i386.cc:8
_main
/tmp/source_x86_64.cc:8
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dsym\-hint <path/to/file.dSYM>
If the debug info for a binary isn\(aqt present in the default location, look for
the debug info at the .dSYM path provided via this option. This flag can be
used multiple times.
.UNINDENT
.SH EXIT STATUS
.sp
\fBllvm\-symbolizer\fP returns 0. Other exit codes imply internal program error.
\fBllvm\-symbolizer\fP returns 0. Other exit codes imply an internal program
error.
.SH SEE ALSO
.sp
\fBllvm\-addr2line(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.
.

11
usr.bin/clang/llvm-tblgen/llvm-tblgen.1
View File

@ -1,7 +1,7 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "TBLGEN" "1" "2018-08-02" "7" "LLVM"
.TH "TBLGEN" "1" "2020-06-26" "10" "LLVM"
.SH NAME
tblgen \- Target Description To C++ Code Generator
.
@ -178,6 +178,11 @@ Generate enhanced disassembly info.
.UNINDENT
.INDENT 0.0
.TP
.B \-gen\-exegesis
Generate llvm\-exegesis tables.
.UNINDENT
.INDENT 0.0
.TP
.B \-version
Show the version number of this program.
.UNINDENT
@ -186,8 +191,8 @@ Show the version number of this program.
If \fBtblgen\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.
.

6
usr.bin/clang/opt/opt.1
View File

@ -1,7 +1,7 @@
.\" $FreeBSD$
.\" Man page generated from reStructuredText.
.
.TH "OPT" "1" "2018-08-02" "7" "LLVM"
.TH "OPT" "1" "2020-06-26" "10" "LLVM"
.SH NAME
opt \- LLVM optimizer
.
@ -163,8 +163,8 @@ Print module after each transformation.
If \fBopt\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.
.