mono/linux-packaging-mono
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Imported Upstream version 5.18.0.207

Browse Source 
Former-commit-id: 3b152f462918d427ce18620a2cbe4f8b79650449
This commit is contained in:
Xamarin Public Jenkins (auto-signing)
2018-11-17 08:23:10 +00:00
parent 8e12397d70
commit eb85e2fc17
28480 changed files with 72 additions and 3866936 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
external/llvm/docs/CommandGuide/FileCheck.rst vendored
View File

File diff suppressed because it is too large Load Diff

196
external/llvm/docs/CommandGuide/bugpoint.rst vendored
View File

@ -1,196 +0,0 @@
bugpoint - automatic test case reduction tool
=============================================
SYNOPSIS
--------
**bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
*program arguments*
DESCRIPTION
-----------
**bugpoint** narrows down the source of problems in LLVM tools and passes. It
can be used to debug three types of failures: optimizer crashes, miscompilations
by optimizers, or bad native code generation (including problems in the static
and JIT compilers). It aims to reduce large test cases to small, useful ones.
For more information on the design and inner workings of **bugpoint**, as well as
advice for using bugpoint, see :doc:`/Bugpoint` in the LLVM
distribution.
OPTIONS
-------
**--additional-so** *library*
Load the dynamic shared object *library* into the test program whenever it is
run. This is useful if you are debugging programs which depend on non-LLVM
libraries (such as the X or curses libraries) to run.
**--append-exit-code**\ =\ *{true,false}*
Append the test programs exit code to the output file so that a change in exit
code is considered a test failure. Defaults to false.
**--args** *program args*
Pass all arguments specified after **--args** to the test program whenever it runs.
Note that if any of the *program args* start with a "``-``", you should use:
.. code-block:: bash
bugpoint [bugpoint args] --args -- [program args]
The "``--``" right after the **--args** option tells **bugpoint** to consider
any options starting with "``-``" to be part of the **--args** option, not as
options to **bugpoint** itself.
**--tool-args** *tool args*
Pass all arguments specified after **--tool-args** to the LLVM tool under test
(**llc**, **lli**, etc.) whenever it runs. You should use this option in the
following way:
.. code-block:: bash
bugpoint [bugpoint args] --tool-args -- [tool args]
The "``--``" right after the **--tool-args** option tells **bugpoint** to
consider any options starting with "``-``" to be part of the **--tool-args**
option, not as options to **bugpoint** itself. (See **--args**, above.)
**--safe-tool-args** *tool args*
Pass all arguments specified after **--safe-tool-args** to the "safe" execution
tool.
**--gcc-tool-args** *gcc tool args*
Pass all arguments specified after **--gcc-tool-args** to the invocation of
**gcc**.
**--opt-args** *opt args*
Pass all arguments specified after **--opt-args** to the invocation of **opt**.
**--disable-{dce,simplifycfg}**
Do not run the specified passes to clean up and reduce the size of the test
program. By default, **bugpoint** uses these passes internally when attempting to
reduce test programs. If you're trying to find a bug in one of these passes,
**bugpoint** may crash.
**--enable-valgrind**
Use valgrind to find faults in the optimization phase. This will allow
bugpoint to find otherwise asymptomatic problems caused by memory
mis-management.
**-find-bugs**
Continually randomize the specified passes and run them on the test program
until a bug is found or the user kills **bugpoint**.
**-help**
Print a summary of command line options.
**--input** *filename*
Open *filename* and redirect the standard input of the test program, whenever
it runs, to come from that file.
**--load** *plugin*
Load the dynamic object *plugin* into **bugpoint** itself. This object should
register new optimization passes. Once loaded, the object will add new command
line options to enable various optimizations. To see the new complete list of
optimizations, use the **-help** and **--load** options together; for example:
.. code-block:: bash
bugpoint --load myNewPass.so -help
**--mlimit** *megabytes*
Specifies an upper limit on memory usage of the optimization and codegen. Set
to zero to disable the limit.
**--output** *filename*
Whenever the test program produces output on its standard output stream, it
should match the contents of *filename* (the "reference output"). If you
do not use this option, **bugpoint** will attempt to generate a reference output
by compiling the program with the "safe" backend and running it.
**--run-{int,jit,llc,custom}**
Whenever the test program is compiled, **bugpoint** should generate code for it
using the specified code generator. These options allow you to choose the
interpreter, the JIT compiler, the static native code compiler, or a
custom command (see **--exec-command**) respectively.
**--safe-{llc,custom}**
When debugging a code generator, **bugpoint** should use the specified code
generator as the "safe" code generator. This is a known-good code generator
used to generate the "reference output" if it has not been provided, and to
compile portions of the program that as they are excluded from the testcase.
These options allow you to choose the
static native code compiler, or a custom command, (see **--exec-command**)
respectively. The interpreter and the JIT backends cannot currently
be used as the "safe" backends.
**--exec-command** *command*
This option defines the command to use with the **--run-custom** and
**--safe-custom** options to execute the bitcode testcase. This can
be useful for cross-compilation.
**--compile-command** *command*
This option defines the command to use with the **--compile-custom**
option to compile the bitcode testcase. The command should exit with a
failure exit code if the file is "interesting" and should exit with a
success exit code (i.e. 0) otherwise (this is the same as if it crashed on
"interesting" inputs).
This can be useful for
testing compiler output without running any link or execute stages. To
generate a reduced unit test, you may add CHECK directives to the
testcase and pass the name of an executable compile-command script in this form:
.. code-block:: sh
#!/bin/sh
llc "$@"
not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
This script will "fail" as long as FileCheck passes. So the result
will be the minimum bitcode that passes FileCheck.
**--safe-path** *path*
This option defines the path to the command to execute with the
**--safe-{int,jit,llc,custom}**
option.
**--verbose-errors**\ =\ *{true,false}*
The default behavior of bugpoint is to print "<crash>" when it finds a reduced
test that crashes compilation. This flag prints the output of the crashing
program to stderr. This is useful to make sure it is the same error being
tracked down and not a different error that happens to crash the compiler as
well. Defaults to false.
EXIT STATUS
-----------
If **bugpoint** succeeds in finding a problem, it will exit with 0. Otherwise,
if an error occurs, it will exit with a non-zero value.
SEE ALSO
--------
opt|opt

89
external/llvm/docs/CommandGuide/dsymutil.rst vendored
View File

@ -1,89 +0,0 @@
dsymutil - manipulate archived DWARF debug symbol files
=======================================================
SYNOPSIS
--------
| :program:`dsymutil` [*options*] *executable*
DESCRIPTION
-----------
:program:`dsymutil` links the DWARF debug information found in the object files
for an executable *executable* by using debug symbols information contained in
its symbol table. By default, the linked debug information is placed in a
``.dSYM`` bundle with the same name as the executable.
OPTIONS
-------
.. option:: --arch=<arch>
Link DWARF debug information only for specified CPU architecture types.
Architectures may be specified by name. When using this option, an error will
be returned if any architectures can not be properly linked. This option can
be specified multiple times, once for each desired architecture. All CPU
architectures will be linked by default and any architectures that can't be
properly linked will cause :program:`dsymutil` to return an error.
.. option:: --dump-debug-map
Dump the *executable*'s debug-map (the list of the object files containing the
debug information) in YAML format and exit. Not DWARF link will take place.
.. option:: -f, --flat
Produce a flat dSYM file. A ``.dwarf`` extension will be appended to the
executable name unless the output file is specified using the -o option.
.. option:: --no-odr
Do not use ODR (One Definition Rule) for uniquing C++ types.
.. option:: --no-output
Do the link in memory, but do not emit the result file.
.. option:: --no-swiftmodule-timestamp
Don't check the timestamp for swiftmodule files.
.. option:: -j <n>, --num-threads=<n>
Specifies the maximum number (``n``) of simultaneous threads to use when
linking multiple architectures.
.. option:: -o <filename>
Specifies an alternate ``path`` to place the dSYM bundle. The default dSYM
bundle path is created by appending ``.dSYM`` to the executable name.
.. option:: --oso-prepend-path=<path>
Specifies a ``path`` to prepend to all debug symbol object file paths.
.. option:: -s, --symtab
Dumps the symbol table found in *executable* or object file(s) and exits.
.. option:: -v, --verbose
Display verbose information when linking.
.. option:: --version
Display the version of the tool.
.. option:: -y
Treat *executable* as a YAML debug-map rather than an executable.
EXIT STATUS
-----------
:program:`dsymutil` returns 0 if the DWARF debug information was linked
successfully. Otherwise, it returns 1.
SEE ALSO
--------
:manpage:`llvm-dwarfdump(1)`

56
external/llvm/docs/CommandGuide/index.rst vendored
View File

@ -1,56 +0,0 @@
LLVM Command Guide
------------------
The following documents are command descriptions for all of the LLVM tools.
These pages describe how to use the LLVM commands and what their options are.
Note that these pages do not describe all of the options available for all
tools. To get a complete listing, pass the ``--help`` (general options) or
``--help-hidden`` (general and debugging options) arguments to the tool you are
interested in.
Basic Commands
~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
llvm-as
llvm-dis
opt
llc
lli
llvm-link
llvm-ar
llvm-lib
llvm-nm
llvm-config
llvm-diff
llvm-cov
llvm-profdata
llvm-stress
llvm-symbolizer
llvm-dwarfdump
dsymutil
Debugging Tools
~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
bugpoint
llvm-extract
llvm-bcanalyzer
Developer Tools
~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
FileCheck
tblgen
lit
llvm-build
llvm-pdbutil
llvm-readobj

478
external/llvm/docs/CommandGuide/lit.rst vendored
View File

@ -1,478 +0,0 @@
lit - LLVM Integrated Tester
============================
SYNOPSIS
--------
:program:`lit` [*options*] [*tests*]
DESCRIPTION
-----------
:program:`lit` is a portable tool for executing LLVM and Clang style test
suites, summarizing their results, and providing indication of failures.
:program:`lit` is designed to be a lightweight testing tool with as simple a
user interface as possible.
:program:`lit` should be run with one or more *tests* to run specified on the
command line. Tests can be either individual test files or directories to
search for tests (see :ref:`test-discovery`).
Each specified test will be executed (potentially in parallel) and once all
tests have been run :program:`lit` will print summary information on the number
of tests which passed or failed (see :ref:`test-status-results`). The
:program:`lit` program will execute with a non-zero exit code if any tests
fail.
By default :program:`lit` will use a succinct progress display and will only
print summary information for test failures. See :ref:`output-options` for
options controlling the :program:`lit` progress display and output.
:program:`lit` also includes a number of options for controlling how tests are
executed (specific features may depend on the particular test format). See
:ref:`execution-options` for more information.
Finally, :program:`lit` also supports additional options for only running a
subset of the options specified on the command line, see
:ref:`selection-options` for more information.
Users interested in the :program:`lit` architecture or designing a
:program:`lit` testing implementation should see :ref:`lit-infrastructure`.
GENERAL OPTIONS
---------------
.. option:: -h, --help
Show the :program:`lit` help message.
.. option:: -j N, --threads=N
Run ``N`` tests in parallel. By default, this is automatically chosen to
match the number of detected available CPUs.
.. option:: --config-prefix=NAME
Search for :file:`{NAME}.cfg` and :file:`{NAME}.site.cfg` when searching for
test suites, instead of :file:`lit.cfg` and :file:`lit.site.cfg`.
.. option:: -D NAME[=VALUE], --param NAME[=VALUE]
Add a user defined parameter ``NAME`` with the given ``VALUE`` (or the empty
string if not given). The meaning and use of these parameters is test suite
dependent.
.. _output-options:
OUTPUT OPTIONS
--------------
.. option:: -q, --quiet
Suppress any output except for test failures.
.. option:: -s, --succinct
Show less output, for example don't show information on tests that pass.
.. option:: -v, --verbose
Show more information on test failures, for example the entire test output
instead of just the test result.
.. option:: -vv, --echo-all-commands
Echo all commands to stdout, as they are being executed.
This can be valuable for debugging test failures, as the last echoed command
will be the one which has failed.
This option implies ``--verbose``.
.. option:: -a, --show-all
Show more information about all tests, for example the entire test
commandline and output.
.. option:: --no-progress-bar
Do not use curses based progress bar.
.. option:: --show-unsupported
Show the names of unsupported tests.
.. option:: --show-xfail
Show the names of tests that were expected to fail.
.. _execution-options:
EXECUTION OPTIONS
-----------------
.. option:: --path=PATH
Specify an additional ``PATH`` to use when searching for executables in tests.
.. option:: --vg
Run individual tests under valgrind (using the memcheck tool). The
``--error-exitcode`` argument for valgrind is used so that valgrind failures
will cause the program to exit with a non-zero status.
When this option is enabled, :program:`lit` will also automatically provide a
"``valgrind``" feature that can be used to conditionally disable (or expect
failure in) certain tests.
.. option:: --vg-arg=ARG
When :option:`--vg` is used, specify an additional argument to pass to
:program:`valgrind` itself.
.. option:: --vg-leak
When :option:`--vg` is used, enable memory leak checks. When this option is
enabled, :program:`lit` will also automatically provide a "``vg_leak``"
feature that can be used to conditionally disable (or expect failure in)
certain tests.
.. option:: --time-tests
Track the wall time individual tests take to execute and includes the results
in the summary output. This is useful for determining which tests in a test
suite take the most time to execute. Note that this option is most useful
with ``-j 1``.
.. _selection-options:
SELECTION OPTIONS
-----------------
.. option:: --max-tests=N
Run at most ``N`` tests and then terminate.
.. option:: --max-time=N
Spend at most ``N`` seconds (approximately) running tests and then terminate.
.. option:: --shuffle
Run the tests in a random order.
.. option:: --num-shards=M
Divide the set of selected tests into ``M`` equal-sized subsets or
"shards", and run only one of them. Must be used with the
``--run-shard=N`` option, which selects the shard to run. The environment
variable ``LIT_NUM_SHARDS`` can also be used in place of this
option. These two options provide a coarse mechanism for paritioning large
testsuites, for parallel execution on separate machines (say in a large
testing farm).
.. option:: --run-shard=N
Select which shard to run, assuming the ``--num-shards=M`` option was
provided. The two options must be used together, and the value of ``N``
must be in the range ``1..M``. The environment variable
``LIT_RUN_SHARD`` can also be used in place of this option.
.. option:: --filter=REGEXP
Run only those tests whose name matches the regular expression specified in
``REGEXP``. The environment variable ``LIT_FILTER`` can be also used in place
of this option, which is especially useful in environments where the call
to ``lit`` is issued indirectly.
ADDITIONAL OPTIONS
------------------
.. option:: --debug
Run :program:`lit` in debug mode, for debugging configuration issues and
:program:`lit` itself.
.. option:: --show-suites
List the discovered test suites and exit.
.. option:: --show-tests
List all of the discovered tests and exit.
EXIT STATUS
-----------
:program:`lit` will exit with an exit code of 1 if there are any FAIL or XPASS
results. Otherwise, it will exit with the status 0. Other exit codes are used
for non-test related failures (for example a user error or an internal program
error).
.. _test-discovery:
TEST DISCOVERY
--------------
The inputs passed to :program:`lit` can be either individual tests, or entire
directories or hierarchies of tests to run. When :program:`lit` starts up, the
first thing it does is convert the inputs into a complete list of tests to run
as part of *test discovery*.
In the :program:`lit` model, every test must exist inside some *test suite*.
:program:`lit` resolves the inputs specified on the command line to test suites
by searching upwards from the input path until it finds a :file:`lit.cfg` or
:file:`lit.site.cfg` file. These files serve as both a marker of test suites
and as configuration files which :program:`lit` loads in order to understand
how to find and run the tests inside the test suite.
Once :program:`lit` has mapped the inputs into test suites it traverses the
list of inputs adding tests for individual files and recursively searching for
tests in directories.
This behavior makes it easy to specify a subset of tests to run, while still
allowing the test suite configuration to control exactly how tests are
interpreted. In addition, :program:`lit` always identifies tests by the test
suite they are in, and their relative path inside the test suite. For
appropriately configured projects, this allows :program:`lit` to provide
convenient and flexible support for out-of-tree builds.
.. _test-status-results:
TEST STATUS RESULTS
-------------------
Each test ultimately produces one of the following six results:
**PASS**
The test succeeded.
**XFAIL**
The test failed, but that is expected. This is used for test formats which allow
specifying that a test does not currently work, but wish to leave it in the test
suite.
**XPASS**
The test succeeded, but it was expected to fail. This is used for tests which
were specified as expected to fail, but are now succeeding (generally because
the feature they test was broken and has been fixed).
**FAIL**
The test failed.
**UNRESOLVED**
The test result could not be determined. For example, this occurs when the test
could not be run, the test itself is invalid, or the test was interrupted.
**UNSUPPORTED**
The test is not supported in this environment. This is used by test formats
which can report unsupported tests.
Depending on the test format tests may produce additional information about
their status (generally only for failures). See the :ref:`output-options`
section for more information.
.. _lit-infrastructure:
LIT INFRASTRUCTURE
------------------
This section describes the :program:`lit` testing architecture for users interested in
creating a new :program:`lit` testing implementation, or extending an existing one.
:program:`lit` proper is primarily an infrastructure for discovering and running
arbitrary tests, and to expose a single convenient interface to these
tests. :program:`lit` itself doesn't know how to run tests, rather this logic is
defined by *test suites*.
TEST SUITES
~~~~~~~~~~~
As described in :ref:`test-discovery`, tests are always located inside a *test
suite*. Test suites serve to define the format of the tests they contain, the
logic for finding those tests, and any additional information to run the tests.
:program:`lit` identifies test suites as directories containing ``lit.cfg`` or
``lit.site.cfg`` files (see also :option:`--config-prefix`). Test suites are
initially discovered by recursively searching up the directory hierarchy for
all the input files passed on the command line. You can use
:option:`--show-suites` to display the discovered test suites at startup.
Once a test suite is discovered, its config file is loaded. Config files
themselves are Python modules which will be executed. When the config file is
executed, two important global variables are predefined:
**lit_config**
The global **lit** configuration object (a *LitConfig* instance), which defines
the builtin test formats, global configuration parameters, and other helper
routines for implementing test configurations.
**config**
This is the config object (a *TestingConfig* instance) for the test suite,
which the config file is expected to populate. The following variables are also
available on the *config* object, some of which must be set by the config and
others are optional or predefined:
**name** *[required]* The name of the test suite, for use in reports and
diagnostics.
**test_format** *[required]* The test format object which will be used to
discover and run tests in the test suite. Generally this will be a builtin test
format available from the *lit.formats* module.
**test_source_root** The filesystem path to the test suite root. For out-of-dir
builds this is the directory that will be scanned for tests.
**test_exec_root** For out-of-dir builds, the path to the test suite root inside
the object directory. This is where tests will be run and temporary output files
placed.
**environment** A dictionary representing the environment to use when executing
tests in the suite.
**suffixes** For **lit** test formats which scan directories for tests, this
variable is a list of suffixes to identify test files. Used by: *ShTest*.
**substitutions** For **lit** test formats which substitute variables into a test
script, the list of substitutions to perform. Used by: *ShTest*.
**unsupported** Mark an unsupported directory, all tests within it will be
reported as unsupported. Used by: *ShTest*.
**parent** The parent configuration, this is the config object for the directory
containing the test suite, or None.
**root** The root configuration. This is the top-most :program:`lit` configuration in
the project.
**pipefail** Normally a test using a shell pipe fails if any of the commands
on the pipe fail. If this is not desired, setting this variable to false
makes the test fail only if the last command in the pipe fails.
**available_features** A set of features that can be used in `XFAIL`,
`REQUIRES`, and `UNSUPPORTED` directives.
TEST DISCOVERY
~~~~~~~~~~~~~~
Once test suites are located, :program:`lit` recursively traverses the source
directory (following *test_source_root*) looking for tests. When :program:`lit`
enters a sub-directory, it first checks to see if a nested test suite is
defined in that directory. If so, it loads that test suite recursively,
otherwise it instantiates a local test config for the directory (see
:ref:`local-configuration-files`).
Tests are identified by the test suite they are contained within, and the
relative path inside that suite. Note that the relative path may not refer to
an actual file on disk; some test formats (such as *GoogleTest*) define
"virtual tests" which have a path that contains both the path to the actual
test file and a subpath to identify the virtual test.
.. _local-configuration-files:
LOCAL CONFIGURATION FILES
~~~~~~~~~~~~~~~~~~~~~~~~~
When :program:`lit` loads a subdirectory in a test suite, it instantiates a
local test configuration by cloning the configuration for the parent directory
--- the root of this configuration chain will always be a test suite. Once the
test configuration is cloned :program:`lit` checks for a *lit.local.cfg* file
in the subdirectory. If present, this file will be loaded and can be used to
specialize the configuration for each individual directory. This facility can
be used to define subdirectories of optional tests, or to change other
configuration parameters --- for example, to change the test format, or the
suffixes which identify test files.
PRE-DEFINED SUBSTITUTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~
:program:`lit` provides various patterns that can be used with the RUN command.
These are defined in TestRunner.py. The base set of substitutions are:
========== ==============
Macro Substitution
========== ==============
%s source path (path to the file currently being run)
%S source dir (directory of the file currently being run)
%p same as %S
%{pathsep} path separator
%t temporary file name unique to the test
%T temporary directory unique to the test
%% %
========== ==============
Other substitutions are provided that are variations on this base set and
further substitution patterns can be defined by each test module. See the
modules :ref:`local-configuration-files`.
More detailed information on substitutions can be found in the
:doc:`../TestingGuide`.
TEST RUN OUTPUT FORMAT
~~~~~~~~~~~~~~~~~~~~~~
The :program:`lit` output for a test run conforms to the following schema, in
both short and verbose modes (although in short mode no PASS lines will be
shown). This schema has been chosen to be relatively easy to reliably parse by
a machine (for example in buildbot log scraping), and for other tools to
generate.
Each test result is expected to appear on a line that matches:
.. code-block:: none
<result code>: <test name> (<progress info>)
where ``<result-code>`` is a standard test result such as PASS, FAIL, XFAIL,
XPASS, UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and
REGRESSED are also allowed.
The ``<test name>`` field can consist of an arbitrary string containing no
newline.
The ``<progress info>`` field can be used to report progress information such
as (1/300) or can be empty, but even when empty the parentheses are required.
Each test result may include additional (multiline) log information in the
following format:
.. code-block:: none
<log delineator> TEST '(<test name>)' <trailing delineator>
... log message ...
<log delineator>
where ``<test name>`` should be the name of a preceding reported test, ``<log
delineator>`` is a string of "*" characters *at least* four characters long
(the recommended length is 20), and ``<trailing delineator>`` is an arbitrary
(unparsed) string.
The following is an example of a test run output which consists of four tests A,
B, C, and D, and a log message for the failing test C:
.. code-block:: none
PASS: A (1 of 4)
PASS: B (2 of 4)
FAIL: C (3 of 4)
******************** TEST 'C' FAILED ********************
Test 'C' failed as a result of exit code 1.
********************
PASS: D (4 of 4)
LIT EXAMPLE TESTS
~~~~~~~~~~~~~~~~~
The :program:`lit` distribution contains several example implementations of
test suites in the *ExampleTests* directory.
SEE ALSO
--------
valgrind(1)

204
external/llvm/docs/CommandGuide/llc.rst vendored
View File

@ -1,204 +0,0 @@
llc - LLVM static compiler
==========================
SYNOPSIS
--------
:program:`llc` [*options*] [*filename*]
DESCRIPTION
-----------
The :program:`llc` command compiles LLVM source inputs into assembly language
for a specified architecture. The assembly language output can then be passed
through a native assembler and linker to generate a native executable.
The choice of architecture for the output assembly code is automatically
determined from the input file, unless the :option:`-march` option is used to
override the default.
OPTIONS
-------
If ``filename`` is "``-``" or omitted, :program:`llc` reads from standard input.
Otherwise, it will from ``filename``. Inputs can be in either the LLVM assembly
language format (``.ll``) or the LLVM bitcode format (``.bc``).
If the :option:`-o` option is omitted, then :program:`llc` will send its output
to standard output if the input is from standard input. If the :option:`-o`
option specifies "``-``", then the output will also be sent to standard output.
If no :option:`-o` option is specified and an input file other than "``-``" is
specified, then :program:`llc` creates the output filename by taking the input
filename, removing any existing ``.bc`` extension, and adding a ``.s`` suffix.
Other :program:`llc` options are described below.
End-user Options
~~~~~~~~~~~~~~~~
.. option:: -help
Print a summary of command line options.
.. option:: -O=uint
Generate code at different optimization levels. These correspond to the
``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by
:program:`clang`.
.. option:: -mtriple=<target triple>
Override the target triple specified in the input file with the specified
string.
.. option:: -march=<arch>
Specify the architecture for which to generate assembly, overriding the target
encoded in the input file. See the output of ``llc -help`` for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
.. option:: -mcpu=<cpuname>
Specify a specific chip in the current architecture to generate code for.
By default this is inferred from the target triple and autodetected to
the current architecture. For a list of available CPUs, use:
.. code-block:: none
llvm-as < /dev/null | llc -march=xyz -mcpu=help
.. option:: -filetype=<output file type>
Specify what kind of output ``llc`` should generated. Options are: ``asm``
for textual assembly ( ``'.s'``), ``obj`` for native object files (``'.o'``)
and ``null`` for not emitting anything (for performance testing).
Note that not all targets support all options.
.. option:: -mattr=a1,+a2,-a3,...
Override or control specific attributes of the target, such as whether SIMD
operations are enabled or not. The default set of attributes is set by the
current CPU. For a list of available attributes, use:
.. code-block:: none
llvm-as < /dev/null | llc -march=xyz -mattr=help
.. option:: --disable-fp-elim
Disable frame pointer elimination optimization.
.. option:: --disable-excess-fp-precision
Disable optimizations that may produce excess precision for floating point.
Note that this option can dramatically slow down code on some systems
(e.g. X86).
.. option:: --enable-no-infs-fp-math
Enable optimizations that assume no Inf values.
.. option:: --enable-no-nans-fp-math
Enable optimizations that assume no NAN values.
.. option:: --enable-unsafe-fp-math
Enable optimizations that make unsafe assumptions about IEEE math (e.g. that
addition is associative) or may not work for all input ranges. These
optimizations allow the code generator to make use of some instructions which
would otherwise not be usable (such as ``fsin`` on X86).
.. option:: --stats
Print statistics recorded by code-generation passes.
.. option:: --time-passes
Record the amount of time needed for each pass and print a report to standard
error.
.. option:: --load=<dso_path>
Dynamically load ``dso_path`` (a path to a dynamically shared object) that
implements an LLVM target. This will permit the target name to be used with
the :option:`-march` option so that code can be generated for that target.
.. option:: -meabi=[default|gnu|4|5]
Specify which EABI version should conform to. Valid EABI versions are *gnu*,
*4* and *5*. Default value (*default*) depends on the triple.
.. option:: -stack-size-section
Emit the .stack_sizes section which contains stack size metadata. The section
contains an array of pairs of function symbol references (8 byte) and stack
sizes (unsigned LEB128). The stack size values only include the space allocated
in the function prologue. Functions with dynamic stack allocations are not
included.
Tuning/Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. option:: --print-machineinstrs
Print generated machine code between compilation phases (useful for debugging).
.. option:: --regalloc=<allocator>
Specify the register allocator to use.
Valid register allocators are:
*basic*
Basic register allocator.
*fast*
Fast register allocator. It is the default for unoptimized code.
*greedy*
Greedy register allocator. It is the default for optimized code.
*pbqp*
Register allocator based on 'Partitioned Boolean Quadratic Programming'.
.. option:: --spiller=<spiller>
Specify the spiller to use for register allocators that support it. Currently
this option is used only by the linear scan register allocator. The default
``spiller`` is *local*. Valid spillers are:
*simple*
Simple spiller
*local*
Local spiller
Intel IA-32-specific Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. option:: --x86-asm-syntax=[att|intel]
Specify whether to emit assembly code in AT&T syntax (the default) or Intel
syntax.
EXIT STATUS
-----------
If :program:`llc` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
lli

214
external/llvm/docs/CommandGuide/lli.rst vendored
View File

@ -1,214 +0,0 @@
lli - directly execute programs from LLVM bitcode
=================================================
SYNOPSIS
--------
:program:`lli` [*options*] [*filename*] [*program args*]
DESCRIPTION
-----------
:program:`lli` directly executes programs in LLVM bitcode format. It takes a program
in LLVM bitcode format and executes it using a just-in-time compiler or an
interpreter.
:program:`lli` is *not* an emulator. It will not execute IR of different architectures
and it can only interpret (or JIT-compile) for the host architecture.
The JIT compiler takes the same arguments as other tools, like :program:`llc`,
but they don't necessarily work for the interpreter.
If `filename` is not specified, then :program:`lli` reads the LLVM bitcode for the
program from standard input.
The optional *args* specified on the command line are passed to the program as
arguments.
GENERAL OPTIONS
---------------
.. option:: -fake-argv0=executable
Override the ``argv[0]`` value passed into the executing program.
.. option:: -force-interpreter={false,true}
If set to true, use the interpreter even if a just-in-time compiler is available
for this architecture. Defaults to false.
.. option:: -help
Print a summary of command line options.
.. option:: -load=pluginfilename
Causes :program:`lli` to load the plugin (shared object) named *pluginfilename* and use
it for optimization.
.. option:: -stats
Print statistics from the code-generation passes. This is only meaningful for
the just-in-time compiler, at present.
.. option:: -time-passes
Record the amount of time needed for each code-generation pass and print it to
standard error.
.. option:: -version
Print out the version of :program:`lli` and exit without doing anything else.
TARGET OPTIONS
--------------
.. option:: -mtriple=target triple
Override the target triple specified in the input bitcode file with the
specified string. This may result in a crash if you pick an
architecture which is not compatible with the current system.
.. option:: -march=arch
Specify the architecture for which to generate assembly, overriding the target
encoded in the bitcode file. See the output of **llc -help** for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
.. option:: -mcpu=cpuname
Specify a specific chip in the current architecture to generate code for.
By default this is inferred from the target triple and autodetected to
the current architecture. For a list of available CPUs, use:
**llvm-as < /dev/null | llc -march=xyz -mcpu=help**
.. option:: -mattr=a1,+a2,-a3,...
Override or control specific attributes of the target, such as whether SIMD
operations are enabled or not. The default set of attributes is set by the
current CPU. For a list of available attributes, use:
**llvm-as < /dev/null | llc -march=xyz -mattr=help**
FLOATING POINT OPTIONS
----------------------
.. option:: -disable-excess-fp-precision
Disable optimizations that may increase floating point precision.
.. option:: -enable-no-infs-fp-math
Enable optimizations that assume no Inf values.
.. option:: -enable-no-nans-fp-math
Enable optimizations that assume no NAN values.
.. option:: -enable-unsafe-fp-math
Causes :program:`lli` to enable optimizations that may decrease floating point
precision.
.. option:: -soft-float
Causes :program:`lli` to generate software floating point library calls instead of
equivalent hardware instructions.
CODE GENERATION OPTIONS
-----------------------
.. option:: -code-model=model
Choose the code model from:
.. code-block:: text
default: Target default code model
small: Small code model
kernel: Kernel code model
medium: Medium code model
large: Large code model
.. option:: -disable-post-RA-scheduler
Disable scheduling after register allocation.
.. option:: -disable-spill-fusing
Disable fusing of spill code into instructions.
.. option:: -jit-enable-eh
Exception handling should be enabled in the just-in-time compiler.
.. option:: -join-liveintervals
Coalesce copies (default=true).
.. option:: -nozero-initialized-in-bss
Don't place zero-initialized symbols into the BSS section.
.. option:: -pre-RA-sched=scheduler
Instruction schedulers available (before register allocation):
.. code-block:: text
=default: Best scheduler for the target
=none: No scheduling: breadth first sequencing
=simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
=simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
=list-burr: Bottom-up register reduction list scheduling
=list-tdrr: Top-down register reduction list scheduling
=list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
.. option:: -regalloc=allocator
Register allocator to use (default=linearscan)
.. code-block:: text
=bigblock: Big-block register allocator
=linearscan: linear scan register allocator =local - local register allocator
=simple: simple register allocator
.. option:: -relocation-model=model
Choose relocation model from:
.. code-block:: text
=default: Target default relocation model
=static: Non-relocatable code =pic - Fully relocatable, position independent code
=dynamic-no-pic: Relocatable external references, non-relocatable code
.. option:: -spiller
Spiller to use (default=local)
.. code-block:: text
=simple: simple spiller
=local: local spiller
.. option:: -x86-asm-syntax=syntax
Choose style of code to emit from X86 backend:
.. code-block:: text
=att: Emit AT&T-style assembly
=intel: Emit Intel-style assembly
EXIT STATUS
-----------
If :program:`lli` 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.
SEE ALSO
--------
:program:`llc`

367
external/llvm/docs/CommandGuide/llvm-ar.rst vendored
View File

@ -1,367 +0,0 @@
llvm-ar - LLVM archiver
=======================
SYNOPSIS
--------
**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
DESCRIPTION
-----------
The **llvm-ar** command is similar to the common Unix utility, ``ar``. 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,
**llvm-ar** 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 **llvm-ar** command can be used to *read* 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 ``r`` (replace) or ``q`` (quick
update) operations, the archive will be reconstructed in GNU format.
Here's where **llvm-ar** departs from previous ``ar`` implementations:
*Symbol Table*
Since **llvm-ar** supports bitcode files. The symbol table it creates
is in GNU format and includes both native and bitcode files.
*Long Paths*
Currently **llvm-ar** can read GNU and BSD long file names, but only writes
archives with the GNU format.
OPTIONS
-------
The options to **llvm-ar** are compatible with other ``ar`` implementations.
However, there are a few modifiers (*R*) that are not found in other ``ar``
implementations. The options to **llvm-ar** 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 **llvm-ar** should process the archive file.
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 ``.a`` suffix, but this is not required. Following
the *archive-name* comes a list of *files* that indicate the specific members
of the archive to operate on. If the *files* option is not specified, it
generally means either "none" or "all" members, depending on the operation.
Operations
~~~~~~~~~~
d
Delete files from the archive. No modifiers are applicable to this operation.
The *files* 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 *files* are specified, the archive is not modified.
m[abi]
Move files from one location in the archive to another. The *a*, *b*, and
*i* modifiers apply to this operation. The *files* 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 *files* are specified, the
archive is not modified.
p
Print files to the standard output. This operation simply prints the
*files* indicated to the standard output. If no *files* are
specified, the entire archive is printed. Printing bitcode files is
ill-advised as they might confuse your terminal settings. The *p*
operation never modifies the archive.
q
Quickly append files to the end of the archive. This operation quickly adds the
*files* to the archive without checking for duplicates that should be
removed first. If no *files* are specified, the archive is not modified.
Because of the way that **llvm-ar** constructs the archive file, its dubious
whether the *q* operation is any faster than the *r* operation.
r[abu]
Replace or insert file members. The *a*, *b*, and *u*
modifiers apply to this operation. This operation will replace existing
*files* or insert them at the end of the archive if they do not exist. If no
*files* are specified, the archive is not modified.
t[v]
Print the table of contents. Without any modifiers, this operation just prints
the names of the members to the standard output. With the *v* modifier,
**llvm-ar** 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 *files* are specified, the listing is only for
those files. If no *files* are specified, the table of contents for the
whole archive is printed.
x[oP]
Extract archive members back to files. The *o* modifier applies to this
operation. This operation retrieves the indicated *files* from the archive
and writes them back to the operating system's file system. If no
*files* are specified, the entire archive is extract.
Modifiers (operation specific)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The modifiers below are specific to certain operations. See the Operations
section (above) to determine which modifiers are applicable to which operations.
[a]
When inserting or moving member files, this option specifies the destination of
the new files as being after the *relpos* member. If *relpos* is not found,
the files are placed at the end of the archive.
[b]
When inserting or moving member files, this option specifies the destination of
the new files as being before the *relpos* member. If *relpos* is not
found, the files are placed at the end of the archive. This modifier is
identical to the *i* modifier.
[i]
A synonym for the *b* option.
[o]
When extracting files, this option will cause **llvm-ar** to preserve the
original modification times of the files it writes.
[u]
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.
Modifiers (generic)
~~~~~~~~~~~~~~~~~~~
The modifiers below may be applied to any operation.
[c]
For all operations, **llvm-ar** will always create the archive if it doesn't
exist. Normally, **llvm-ar** will print a warning message indicating that the
archive is being created. Using this modifier turns off that warning.
[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.
[S]
This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
not build the symbol table. If both *s* and *S* are used, the last modifier to
occur in the options will prevail.
[v]
This modifier instructs **llvm-ar** 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.
STANDARDS
---------
The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
**llvm-ar** 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.
FILE FORMAT
-----------
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 ``ar`` commands on those
operating systems should be able to read LLVM archive files. The details of the
file format follow.
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.
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.
name - char[16]
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 ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
is literal. In this case, the actual name of the file is provided in the ``nnn``
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.
date - char[12]
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.
uid - char[6]
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.
gid - char[6]
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.
mode - char[8]
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.
size - char[10]
This field provides the size of the file, in bytes, encoded as a decimal ASCII
string.
fmag - char[2]
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.
offset - vbr encoded 32-bit integer
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.
length - vbr encoded 32-bit integer
The length item provides the length of the symbol that follows. Like this
*offset* item, the length is variable bit rate encoded.
symbol - character array
The symbol item provides the text of the symbol that is associated with the
*offset*. The symbol is not terminated by any character. Its length is provided
by the *length* 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.
EXIT STATUS
-----------
If **llvm-ar** 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.
SEE ALSO
--------
ar(1)

56
external/llvm/docs/CommandGuide/llvm-as.rst vendored
View File

@ -1,56 +0,0 @@
llvm-as - LLVM assembler
========================
SYNOPSIS
--------
**llvm-as** [*options*] [*filename*]
DESCRIPTION
-----------
**llvm-as** is the LLVM assembler. It reads a file containing human-readable
LLVM assembly language, translates it to LLVM bitcode, and writes the result
into a file or to standard output.
If *filename* is omitted or is ``-``, then **llvm-as** reads its input from
standard input.
If an output file is not specified with the **-o** option, then
**llvm-as** sends its output to a file or standard output by following
these rules:
* If the input is standard input, then the output is standard output.
* If the input is a file that ends with ``.ll``, then the output file is of the
same name, except that the suffix is changed to ``.bc``.
* If the input is a file that does not end with the ``.ll`` suffix, then the
output file has the same name as the input file, except that the ``.bc``
suffix is appended.
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **llvm-as** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-as** will write raw bitcode regardless of the output device.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output file name. If *filename* is ``-``, then **llvm-as**
sends its output to standard output.
EXIT STATUS
-----------
If **llvm-as** succeeds, it will exit with 0. Otherwise, if an error occurs, it
will exit with a non-zero value.
SEE ALSO
--------
llvm-dis|llvm-dis, gccas|gccas

305
external/llvm/docs/CommandGuide/llvm-bcanalyzer.rst vendored
View File

@ -1,305 +0,0 @@
llvm-bcanalyzer - LLVM bitcode analyzer
=======================================
SYNOPSIS
--------
:program:`llvm-bcanalyzer` [*options*] [*filename*]
DESCRIPTION
-----------
The :program:`llvm-bcanalyzer` command is a small utility for analyzing bitcode
files. The tool reads a bitcode file (such as generated with the
:program:`llvm-as` tool) and produces a statistical report on the contents of
the bitcode file. The tool can also dump a low level but human readable
version of the bitcode file. This tool is probably not of much interest or
utility except for those working directly with the bitcode file format. Most
LLVM users can just ignore this tool.
If *filename* is omitted or is ``-``, then :program:`llvm-bcanalyzer` reads its
input from standard input. This is useful for combining the tool into a
pipeline. Output is written to the standard output.
OPTIONS
-------
.. program:: llvm-bcanalyzer
.. option:: -nodetails
Causes :program:`llvm-bcanalyzer` to abbreviate its output by writing out only
a module level summary. The details for individual functions are not
displayed.
.. option:: -dump
Causes :program:`llvm-bcanalyzer` to dump the bitcode in a human readable
format. This format is significantly different from LLVM assembly and
provides details about the encoding of the bitcode file.
.. option:: -verify
Causes :program:`llvm-bcanalyzer` to verify the module produced by reading the
bitcode. This ensures that the statistics generated are based on a consistent
module.
.. option:: -help
Print a summary of command line options.
EXIT STATUS
-----------
If :program:`llvm-bcanalyzer` succeeds, it will exit with 0. Otherwise, if an
error occurs, it will exit with a non-zero value, usually 1.
SUMMARY OUTPUT DEFINITIONS
--------------------------
The following items are always printed by llvm-bcanalyzer. They comprize the
summary output.
**Bitcode Analysis Of Module**
This just provides the name of the module for which bitcode analysis is being
generated.
**Bitcode Version Number**
The bitcode version (not LLVM version) of the file read by the analyzer.
**File Size**
The size, in bytes, of the entire bitcode file.
**Module Bytes**
The size, in bytes, of the module block. Percentage is relative to File Size.
**Function Bytes**
The size, in bytes, of all the function blocks. Percentage is relative to File
Size.
**Global Types Bytes**
The size, in bytes, of the Global Types Pool. Percentage is relative to File
Size. This is the size of the definitions of all types in the bitcode file.
**Constant Pool Bytes**
The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
Size.
**Module Globals Bytes**
Ths size, in bytes, of the Global Variable Definitions and their initializers.
Percentage is relative to File Size.
**Instruction List Bytes**
The size, in bytes, of all the instruction lists in all the functions.
Percentage is relative to File Size. Note that this value is also included in
the Function Bytes.
**Compaction Table Bytes**
The size, in bytes, of all the compaction tables in all the functions.
Percentage is relative to File Size. Note that this value is also included in
the Function Bytes.
**Symbol Table Bytes**
The size, in bytes, of all the symbol tables in all the functions. Percentage is
relative to File Size. Note that this value is also included in the Function
Bytes.
**Dependent Libraries Bytes**
The size, in bytes, of the list of dependent libraries in the module. Percentage
is relative to File Size. Note that this value is also included in the Module
Global Bytes.
**Number Of Bitcode Blocks**
The total number of blocks of any kind in the bitcode file.
**Number Of Functions**
The total number of function definitions in the bitcode file.
**Number Of Types**
The total number of types defined in the Global Types Pool.
**Number Of Constants**
The total number of constants (of any type) defined in the Constant Pool.
**Number Of Basic Blocks**
The total number of basic blocks defined in all functions in the bitcode file.
**Number Of Instructions**
The total number of instructions defined in all functions in the bitcode file.
**Number Of Long Instructions**
The total number of long instructions defined in all functions in the bitcode
file. Long instructions are those taking greater than 4 bytes. Typically long
instructions are GetElementPtr with several indices, PHI nodes, and calls to
functions with large numbers of arguments.
**Number Of Operands**
The total number of operands used in all instructions in the bitcode file.
**Number Of Compaction Tables**
The total number of compaction tables in all functions in the bitcode file.
**Number Of Symbol Tables**
The total number of symbol tables in all functions in the bitcode file.
**Number Of Dependent Libs**
The total number of dependent libraries found in the bitcode file.
**Total Instruction Size**
The total size of the instructions in all functions in the bitcode file.
**Average Instruction Size**
The average number of bytes per instruction across all functions in the bitcode
file. This value is computed by dividing Total Instruction Size by Number Of
Instructions.
**Maximum Type Slot Number**
The maximum value used for a type's slot number. Larger slot number values take
more bytes to encode.
**Maximum Value Slot Number**
The maximum value used for a value's slot number. Larger slot number values take
more bytes to encode.
**Bytes Per Value**
The average size of a Value definition (of any type). This is computed by
dividing File Size by the total number of values of any type.
**Bytes Per Global**
The average size of a global definition (constants and global variables).
**Bytes Per Function**
The average number of bytes per function definition. This is computed by
dividing Function Bytes by Number Of Functions.
**# of VBR 32-bit Integers**
The total number of 32-bit integers encoded using the Variable Bit Rate
encoding scheme.
**# of VBR 64-bit Integers**
The total number of 64-bit integers encoded using the Variable Bit Rate encoding
scheme.
**# of VBR Compressed Bytes**
The total number of bytes consumed by the 32-bit and 64-bit integers that use
the Variable Bit Rate encoding scheme.
**# of VBR Expanded Bytes**
The total number of bytes that would have been consumed by the 32-bit and 64-bit
integers had they not been compressed with the Variable Bit Rage encoding
scheme.
**Bytes Saved With VBR**
The total number of bytes saved by using the Variable Bit Rate encoding scheme.
The percentage is relative to # of VBR Expanded Bytes.
DETAILED OUTPUT DEFINITIONS
---------------------------
The following definitions occur only if the -nodetails option was not given.
The detailed output provides additional information on a per-function basis.
**Type**
The type signature of the function.
**Byte Size**
The total number of bytes in the function's block.
**Basic Blocks**
The number of basic blocks defined by the function.
**Instructions**
The number of instructions defined by the function.
**Long Instructions**
The number of instructions using the long instruction format in the function.
**Operands**
The number of operands used by all instructions in the function.
**Instruction Size**
The number of bytes consumed by instructions in the function.
**Average Instruction Size**
The average number of bytes consumed by the instructions in the function.
This value is computed by dividing Instruction Size by Instructions.
**Bytes Per Instruction**
The average number of bytes used by the function per instruction. This value
is computed by dividing Byte Size by Instructions. Note that this is not the
same as Average Instruction Size. It computes a number relative to the total
function size not just the size of the instruction list.
**Number of VBR 32-bit Integers**
The total number of 32-bit integers found in this function (for any use).
**Number of VBR 64-bit Integers**
The total number of 64-bit integers found in this function (for any use).
**Number of VBR Compressed Bytes**
The total number of bytes in this function consumed by the 32-bit and 64-bit
integers that use the Variable Bit Rate encoding scheme.
**Number of VBR Expanded Bytes**
The total number of bytes in this function that would have been consumed by
the 32-bit and 64-bit integers had they not been compressed with the Variable
Bit Rate encoding scheme.
**Bytes Saved With VBR**
The total number of bytes saved in this function by using the Variable Bit
Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
SEE ALSO
--------
:doc:`/CommandGuide/llvm-dis`, :doc:`/BitCodeFormat`

102
external/llvm/docs/CommandGuide/llvm-build.rst vendored
View File

@ -1,102 +0,0 @@
llvm-build - LLVM Project Build Utility
=======================================
SYNOPSIS
--------
**llvm-build** [*options*]
DESCRIPTION
-----------
**llvm-build** is a tool for working with LLVM projects that use the LLVMBuild
system for describing their components.
At heart, **llvm-build** is responsible for loading, verifying, and manipulating
the project's component data. The tool is primarily designed for use in
implementing build systems and tools which need access to the project structure
information.
OPTIONS
-------
**-h**, **--help**
Print the builtin program help.
**--source-root**\ =\ *PATH*
If given, load the project at the given source root path. If this option is not
given, the location of the project sources will be inferred from the location of
the **llvm-build** script itself.
**--print-tree**
Print the component tree for the project.
**--write-library-table**
Write out the C++ fragment which defines the components, library names, and
required libraries. This C++ fragment is built into llvm-config|llvm-config
in order to provide clients with the list of required libraries for arbitrary
component combinations.
**--write-llvmbuild**
Write out new *LLVMBuild.txt* files based on the loaded components. This is
useful for auto-upgrading the schema of the files. **llvm-build** will try to a
limited extent to preserve the comments which were written in the original
source file, although at this time it only preserves block comments that precede
the section names in the *LLVMBuild* files.
**--write-cmake-fragment**
Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
consumed by the CMake based build system. The exact contents and format of this
file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's
top-level CMakeLists.txt.
**--write-make-fragment**
Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
consumed by a Make based build system. The exact contents and format of this
file are closely tied to how LLVMBuild is integrated with the Makefiles, see
LLVM's Makefile.rules.
**--llvmbuild-source-root**\ =\ *PATH*
If given, expect the *LLVMBuild* files for the project to be rooted at the
given path, instead of inside the source tree itself. This option is primarily
designed for use in conjunction with **--write-llvmbuild** to test changes to
*LLVMBuild* schema.
EXIT STATUS
-----------
**llvm-build** exits with 0 if operation was successful. Otherwise, it will exist
with a non-zero value.

176
external/llvm/docs/CommandGuide/llvm-config.rst vendored
View File

@ -1,176 +0,0 @@
llvm-config - Print LLVM compilation options
============================================
SYNOPSIS
--------
**llvm-config** *option* [*components*...]
DESCRIPTION
-----------
**llvm-config** makes it easier to build applications that use LLVM. It can
print the compiler flags, linker flags and object libraries needed to link
against LLVM.
EXAMPLES
--------
To link against the JIT:
.. code-block:: sh
g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
`llvm-config --libs engine bcreader scalaropts`
OPTIONS
-------
**--version**
Print the version number of LLVM.
**-help**
Print a summary of **llvm-config** arguments.
**--prefix**
Print the installation prefix for LLVM.
**--src-root**
Print the source root from which LLVM was built.
**--obj-root**
Print the object root used to build LLVM.
**--bindir**
Print the installation directory for LLVM binaries.
**--includedir**
Print the installation directory for LLVM headers.
**--libdir**
Print the installation directory for LLVM libraries.
**--cxxflags**
Print the C++ compiler flags needed to use LLVM headers.
**--ldflags**
Print the flags needed to link against LLVM libraries.
**--libs**
Print all the libraries needed to link against the specified LLVM
*components*, including any dependencies.
**--libnames**
Similar to **--libs**, but prints the bare filenames of the libraries
without **-l** or pathnames. Useful for linking against a not-yet-installed
copy of LLVM.
**--libfiles**
Similar to **--libs**, but print the full path to each library file. This is
useful when creating makefile dependencies, to ensure that a tool is relinked if
any library it uses changes.
**--components**
Print all valid component names.
**--targets-built**
Print the component names for all targets supported by this copy of LLVM.
**--build-mode**
Print the build mode used when LLVM was built (e.g. Debug or Release)
COMPONENTS
----------
To print a list of all available components, run **llvm-config
--components**. In most cases, components correspond directly to LLVM
libraries. Useful "virtual" components include:
**all**
Includes all LLVM libraries. The default if no components are specified.
**backend**
Includes either a native backend or the C backend.
**engine**
Includes either a native JIT or the bitcode interpreter.
EXIT STATUS
-----------
If **llvm-config** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.

391
external/llvm/docs/CommandGuide/llvm-cov.rst vendored
View File

@ -1,391 +0,0 @@
llvm-cov - emit coverage information
====================================
SYNOPSIS
--------
:program:`llvm-cov` *command* [*args...*]
DESCRIPTION
-----------
The :program:`llvm-cov` tool shows code coverage information for
programs that are instrumented to emit profile data. It can be used to
work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
based profiling.
If the program is invoked with a base name of ``gcov``, it will behave as if
the :program:`llvm-cov gcov` command were called. Otherwise, a command should
be provided.
COMMANDS
--------
* :ref:`gcov <llvm-cov-gcov>`
* :ref:`show <llvm-cov-show>`
* :ref:`report <llvm-cov-report>`
* :ref:`export <llvm-cov-export>`
.. program:: llvm-cov gcov
.. _llvm-cov-gcov:
GCOV COMMAND
------------
SYNOPSIS
^^^^^^^^
:program:`llvm-cov gcov` [*options*] *SOURCEFILE*
DESCRIPTION
^^^^^^^^^^^
The :program:`llvm-cov gcov` tool reads code coverage data files and displays
the coverage information for a specified source file. It is compatible with the
``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
later versions of ``gcov``.
To use :program:`llvm-cov gcov`, you must first build an instrumented version
of your application that collects coverage data as it runs. Compile with the
``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
instrumentation. (Alternatively, you can use the ``--coverage`` option, which
includes both of those other options.) You should compile with debugging
information (``-g``) and without optimization (``-O0``); otherwise, the
coverage data cannot be accurately mapped back to the source code.
At the time you compile the instrumented code, a ``.gcno`` data file will be
generated for each object file. These ``.gcno`` files contain half of the
coverage data. The other half of the data comes from ``.gcda`` files that are
generated when you run the instrumented program, with a separate ``.gcda``
file for each object file. Each time you run the program, the execution counts
are summed into any existing ``.gcda`` files, so be sure to remove any old
files if you do not want their contents to be included.
By default, the ``.gcda`` files are written into the same directory as the
object files, but you can override that by setting the ``GCOV_PREFIX`` and
``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
variable specifies a number of directory components to be removed from the
start of the absolute path to the object file directory. After stripping those
directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
environment variables allow you to run the instrumented program on a machine
where the original object file directories are not accessible, but you will
then need to copy the ``.gcda`` files back to the object file directories
where :program:`llvm-cov gcov` expects to find them.
Once you have generated the coverage data files, run :program:`llvm-cov gcov`
for each main source file where you want to examine the coverage results. This
should be run from the same directory where you previously ran the
compiler. The results for the specified source file are written to a file named
by appending a ``.gcov`` suffix. A separate output file is also created for
each file included by the main source file, also with a ``.gcov`` suffix added.
The basic content of an ``.gcov`` output file is a copy of the source file with
an execution count and line number prepended to every line. The execution
count is shown as ``-`` if a line does not contain any executable code. If
a line contains code but that code was never executed, the count is displayed
as ``#####``.
OPTIONS
^^^^^^^
.. option:: -a, --all-blocks
Display all basic blocks. If there are multiple blocks for a single line of
source code, this option causes llvm-cov to show the count for each block
instead of just one count for the entire line.
.. option:: -b, --branch-probabilities
Display conditional branch probabilities and a summary of branch information.
.. option:: -c, --branch-counts
Display branch counts instead of probabilities (requires -b).
.. option:: -f, --function-summaries
Show a summary of coverage for each function instead of just one summary for
an entire source file.
.. option:: --help
Display available options (--help-hidden for more).
.. option:: -l, --long-file-names
For coverage output of files included from the main source file, add the
main file name followed by ``##`` as a prefix to the output file names. This
can be combined with the --preserve-paths option to use complete paths for
both the main file and the included file.
.. option:: -n, --no-output
Do not output any ``.gcov`` files. Summary information is still
displayed.
.. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
Find objects in DIR or based on FILE's path. If you specify a particular
object file, the coverage data files are expected to have the same base name
with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
files are expected in that directory with the same base name as the source
file.
.. option:: -p, --preserve-paths
Preserve path components when naming the coverage output files. In addition
to the source file name, include the directories from the path to that
file. The directories are separate by ``#`` characters, with ``.`` directories
removed and ``..`` directories replaced by ``^`` characters. When used with
the --long-file-names option, this applies to both the main file name and the
included file name.
.. option:: -u, --unconditional-branches
Include unconditional branches in the output for the --branch-probabilities
option.
.. option:: -version
Display the version of llvm-cov.
EXIT STATUS
^^^^^^^^^^^
:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
it exits with zero.
.. program:: llvm-cov show
.. _llvm-cov-show:
SHOW COMMAND
------------
SYNOPSIS
^^^^^^^^
:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
DESCRIPTION
^^^^^^^^^^^
The :program:`llvm-cov show` command shows line by line coverage of the
binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
filtered to only show the coverage for the files listed in *SOURCES*.
To use :program:`llvm-cov show`, you need a program that is compiled with
instrumentation to emit profile and coverage data. To build such a program with
``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
to the link stage to make sure the necessary runtime libraries are linked in.
The coverage information is stored in the built executable or library itself,
and this is what you should pass to :program:`llvm-cov show` as a *BIN*
argument. The profile data is generated by running this instrumented program
normally. When the program exits it will write out a raw profile file,
typically called ``default.profraw``, which can be converted to a format that
is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
tool.
OPTIONS
^^^^^^^
.. option:: -show-line-counts
Show the execution counts for each line. Defaults to true, unless another
``-show`` option is used.
.. option:: -show-expansions
Expand inclusions, such as preprocessor macros or textual inclusions, inline
in the display of the source file. Defaults to false.
.. option:: -show-instantiations
For source regions that are instantiated multiple times, such as templates in
``C++``, show each instantiation separately as well as the combined summary.
Defaults to true.
.. option:: -show-regions
Show the execution counts for each region by displaying a caret that points to
the character where the region starts. Defaults to false.
.. option:: -show-line-counts-or-regions
Show the execution counts for each line if there is only one region on the
line, but show the individual regions if there are multiple on the line.
Defaults to false.
.. option:: -use-color
Enable or disable color output. By default this is autodetected.
.. option:: -arch=[*NAMES*]
Specify a list of architectures such that the Nth entry in the list
corresponds to the Nth specified binary. If the covered object is a universal
binary, this specifies the architecture to use. It is an error to specify an
architecture that is not included in the universal binary or to use an
architecture that does not match a non-universal binary.
.. option:: -name=<NAME>
Show code coverage only for functions with the given name.
.. option:: -name-whitelist=<FILE>
Show code coverage only for functions listed in the given file. Each line in
the file should start with `whitelist_fun:`, immediately followed by the name
of the function to accept. This name can be a wildcard expression.
.. option:: -name-regex=<PATTERN>
Show code coverage only for functions that match the given regular expression.
.. option:: -format=<FORMAT>
Use the specified output format. The supported formats are: "text", "html".
.. option:: -tab-size=<TABSIZE>
Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
only supported for the html format.
.. option:: -output-dir=PATH
Specify a directory to write coverage reports into. If the directory does not
exist, it is created. When used in function view mode (i.e when -name or
-name-regex are used to select specific functions), the report is written to
PATH/functions.EXTENSION. When used in file view mode, a report for each file
is written to PATH/REL_PATH_TO_FILE.EXTENSION.
.. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
Specify a symbol demangler. This can be used to make reports more
human-readable. This option can be specified multiple times to supply
arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
The demangler is expected to read a newline-separated list of symbols from
stdin and write a newline-separated list of the same length to stdout.
.. option:: -num-threads=N, -j=N
Use N threads to write file reports (only applicable when -output-dir is
specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
use. This is the default.
.. option:: -line-coverage-gt=<N>
Show code coverage only for functions with line coverage greater than the
given threshold.
.. option:: -line-coverage-lt=<N>
Show code coverage only for functions with line coverage less than the given
threshold.
.. option:: -region-coverage-gt=<N>
Show code coverage only for functions with region coverage greater than the
given threshold.
.. option:: -region-coverage-lt=<N>
Show code coverage only for functions with region coverage less than the given
threshold.
.. option:: -path-equivalence=<from>,<to>
Map the paths in the coverage data to local source file paths. This allows you
to generate the coverage data on one machine, and then use llvm-cov on a
different machine where you have the same files on a different path.
.. program:: llvm-cov report
.. _llvm-cov-report:
REPORT COMMAND
--------------
SYNOPSIS
^^^^^^^^
:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
DESCRIPTION
^^^^^^^^^^^
The :program:`llvm-cov report` command displays a summary of the coverage of
the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
filtered to only show the coverage for the files listed in *SOURCES*.
If no source files are provided, a summary line is printed for each file in the
coverage data. If any files are provided, summaries are shown for each function
in the listed files instead.
For information on compiling programs for coverage and generating profile data,
see :ref:`llvm-cov-show`.
OPTIONS
^^^^^^^
.. option:: -use-color[=VALUE]
Enable or disable color output. By default this is autodetected.
.. option:: -arch=<name>
If the covered binary is a universal binary, select the architecture to use.
It is an error to specify an architecture that is not included in the
universal binary or to use an architecture that does not match a
non-universal binary.
.. option:: -show-functions
Show coverage summaries for each function. Defaults to false.
.. option:: -show-instantiation-summary
Show statistics for all function instantiations. Defaults to false.
.. program:: llvm-cov export
.. _llvm-cov-export:
EXPORT COMMAND
--------------
SYNOPSIS
^^^^^^^^
:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]]
DESCRIPTION
^^^^^^^^^^^
The :program:`llvm-cov export` command exports regions, functions, expansions,
and summaries of the coverage of the binaries *BIN*,... using the profile data
*PROFILE* as JSON.
For information on compiling programs for coverage and generating profile data,
see :ref:`llvm-cov-show`.
OPTIONS
^^^^^^^
.. option:: -arch=<name>
If the covered binary is a universal binary, select the architecture to use.
It is an error to specify an architecture that is not included in the
universal binary or to use an architecture that does not match a
non-universal binary.
.. option:: -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:
`llvm-cov report` command, but presented in JSON format rather than text.

56
external/llvm/docs/CommandGuide/llvm-diff.rst vendored
View File

@ -1,56 +0,0 @@
llvm-diff - LLVM structural 'diff'
==================================
SYNOPSIS
--------
**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
DESCRIPTION
-----------
**llvm-diff** compares the structure of two LLVM modules, primarily
focusing on differences in function definitions. Insignificant
differences, such as changes in the ordering of globals or in the
names of local values, are ignored.
An input module will be interpreted as an assembly file if its name
ends in '.ll'; otherwise it will be read in as a bitcode file.
If a list of global names is given, just the values with those names
are compared; otherwise, all global values are compared, and
diagnostics are produced for globals which only appear in one module
or the other.
**llvm-diff** compares two functions by comparing their basic blocks,
beginning with the entry blocks. If the terminators seem to match,
then the corresponding successors are compared; otherwise they are
ignored. This algorithm is very sensitive to changes in control flow,
which tend to stop any downstream changes from being detected.
**llvm-diff** is intended as a debugging tool for writers of LLVM
passes and frontends. It does not have a stable output format.
EXIT STATUS
-----------
If **llvm-diff** finds no differences between the modules, it will exit
with 0 and produce no output. Otherwise it will exit with a non-zero
value.
BUGS
----
Many important differences, like changes in linkage or function
attributes, are not diagnosed.
Changes in memory behavior (for example, coalescing loads) can cause
massive detected differences in blocks.

69
external/llvm/docs/CommandGuide/llvm-dis.rst vendored
View File

@ -1,69 +0,0 @@
llvm-dis - LLVM disassembler
============================
SYNOPSIS
--------
**llvm-dis** [*options*] [*filename*]
DESCRIPTION
-----------
The **llvm-dis** command is the LLVM disassembler. It takes an LLVM
bitcode file and converts it into human-readable LLVM assembly language.
If filename is omitted or specified as ``-``, **llvm-dis** reads its
input from standard input.
If the input is being read from standard input, then **llvm-dis**
will send its output to standard output by default. Otherwise, the
output will be written to a file named after the input file, with
a ``.ll`` suffix added (any existing ``.bc`` suffix will first be
removed). You can override the choice of output file using the
**-o** option.
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **llvm-dis** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-dis** will write raw bitcode regardless of the output device.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output file name. If *filename* is -, then the output is sent
to standard output.
EXIT STATUS
-----------
If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
llvm-as|llvm-as

142
external/llvm/docs/CommandGuide/llvm-dwarfdump.rst vendored
View File

@ -1,142 +0,0 @@
llvm-dwarfdump - dump and verify DWARF debug information
========================================================
SYNOPSIS
--------
:program:`llvm-dwarfdump` [*options*] [*filename ...*]
DESCRIPTION
-----------
:program:`llvm-dwarfdump` parses DWARF sections in object files,
archives, and `.dSYM` bundles and prints their contents in
human-readable form. Only the .debug_info section is printed unless one of
the section-specific options or :option:`--all` is specified.
OPTIONS
-------
.. option:: -a, --all
Disassemble all supported DWARF sections.
.. option:: --arch=<arch>
Dump DWARF debug information for the specified CPU architecture.
Architectures may be specified by name or by number. This
option can be specified multiple times, once for each desired
architecture. All CPU architectures will be printed by
default.
.. option:: -c, --show-children
Show a debug info entry's children when using
the :option:`--debug-info`, :option:`--find`,
and :option:`--name` options.
.. option:: -f <name>, --find=<name>
Search for the exact text <name> in the accelerator tables
and print the matching debug information entries.
When there is no accelerator tables or the name of the DIE
you are looking for is not found in the accelerator tables,
try using the slower but more complete :option:`--name` option.
.. option:: -F, --show-form
Show DWARF form types after the DWARF attribute types.
.. option:: -h, --help
Show help and usage for this command.
.. option:: -i, --ignore-case
Ignore case distinctions in when searching entries by name
or by regular expression.
.. option:: -n <pattern>, --name=<pattern>
Find and print all debug info entries whose name
(`DW_AT_name` attribute) matches the exact text in
<pattern>. Use the :option:`--regex` option to have
<pattern> become a regular expression for more flexible
pattern matching.
.. option:: --lookup=<address>
Lookup <address> in the debug information and print out the file,
function, block, and line table details.
.. option:: -o <path>, --out-file=<path>
Redirect output to a file specified by <path>.
.. option:: -p, --show-parents
Show a debug info entry's parent objects when using the
:option:`--debug-info`, :option:`--find`, and
:option:`--name` options.
.. option:: -r <n>, --recurse-depth=<n>
Only recurse to a maximum depth of <n> when dumping debug info
entries.
.. option:: --statistics
Collect debug info quality metrics and print the results
as machine-readable single-line JSON output.
.. option:: -x, --regex
Treat any <pattern> strings as regular expressions when searching
instead of just as an exact string match.
.. option:: -u, --uuid
Show the UUID for each architecture.
.. option:: --diff
Dump the output in a format that is more friendly for comparing
DWARF output from two different files.
.. option:: -v, --verbose
Display verbose information when dumping. This can help to debug
DWARF issues.
.. option:: --verify
Verify the structure of the DWARF information by verifying the
compile unit chains, DIE relationships graph, address
ranges, and more.
.. option:: --version
Display the version of the tool.
.. option:: --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
Dump the specified DWARF section by name. Only the
`.debug_info` section is shown by default. Some entries
support adding an `=<offset>` 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
:option:`--show-children` option where applicable.
EXIT STATUS
-----------
:program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
successfully. Otherwise, it returns 1.
SEE ALSO
--------
:manpage:`dsymutil(1)`

79
external/llvm/docs/CommandGuide/llvm-extract.rst vendored
View File

@ -1,79 +0,0 @@
llvm-extract - extract a function from an LLVM module
=====================================================
SYNOPSIS
--------
:program:`llvm-extract` [*options*] **--func** *function-name* [*filename*]
DESCRIPTION
-----------
The :program:`llvm-extract` command takes the name of a function and extracts
it from the specified LLVM bitcode file. It is primarily used as a debugging
tool to reduce test cases from larger programs that are triggering a bug.
In addition to extracting the bitcode of the specified function,
:program:`llvm-extract` will also remove unreachable global variables,
prototypes, and unused types.
The :program:`llvm-extract` command reads its input from standard input if
filename is omitted or if filename is ``-``. The output is always written to
standard output, unless the **-o** option is specified (see below).
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, :program:`llvm-extract` will
refuse to write raw bitcode output if the output stream is a terminal. With
this option, :program:`llvm-extract` will write raw bitcode regardless of the
output device.
**--func** *function-name*
Extract the function named *function-name* from the LLVM bitcode. May be
specified multiple times to extract multiple functions at once.
**--rfunc** *function-regular-expr*
Extract the function(s) matching *function-regular-expr* from the LLVM bitcode.
All functions matching the regular expression will be extracted. May be
specified multiple times.
**--glob** *global-name*
Extract the global variable named *global-name* from the LLVM bitcode. May be
specified multiple times to extract multiple global variables at once.
**--rglob** *glob-regular-expr*
Extract the global variable(s) matching *global-regular-expr* from the LLVM
bitcode. All global variables matching the regular expression will be
extracted. May be specified multiple times.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output filename. If filename is "-" (the default), then
:program:`llvm-extract` sends its output to standard output.
**-S**
Write output in LLVM intermediate language (instead of bitcode).
EXIT STATUS
-----------
If :program:`llvm-extract` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
bugpoint

31
external/llvm/docs/CommandGuide/llvm-lib.rst vendored
View File

@ -1,31 +0,0 @@
llvm-lib - LLVM lib.exe compatible library tool
===============================================
SYNOPSIS
--------
**llvm-lib** [/libpath:<path>] [/out:<output>] [/llvmlibthin]
[/ignore] [/machine] [/nologo] [files...]
DESCRIPTION
-----------
The **llvm-lib** command is intended to be a ``lib.exe`` compatible
tool. See https://msdn.microsoft.com/en-us/library/7ykb2k5f for the
general description.
**llvm-lib** has the following extensions:
* Bitcode files in symbol tables.
**llvm-lib** includes symbols from both bitcode files and regular
object files in the symbol table.
* Creating thin archives.
The /llvmlibthin option causes **llvm-lib** to create thin archive
that contain only the symbol table and the header for the various
members. These files are much smaller, but are not compatible with
link.exe (lld can handle them).

56
external/llvm/docs/CommandGuide/llvm-link.rst vendored
View File

@ -1,56 +0,0 @@
llvm-link - LLVM bitcode linker
===============================
SYNOPSIS
--------
:program:`llvm-link` [*options*] *filename ...*
DESCRIPTION
-----------
:program:`llvm-link` 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 :option:`-o` option is used to specify a filename.
OPTIONS
-------
.. option:: -f
Enable binary output on terminals. Normally, :program:`llvm-link` will refuse
to write raw bitcode output if the output stream is a terminal. With this
option, :program:`llvm-link` will write raw bitcode regardless of the output
device.
.. option:: -o filename
Specify the output file name. If ``filename`` is "``-``", then
:program:`llvm-link` will write its output to standard output.
.. option:: -S
Write output in LLVM intermediate language (instead of bitcode).
.. option:: -d
If specified, :program:`llvm-link` prints a human-readable version of the
output bitcode file to standard error.
.. option:: -help
Print a summary of command line options.
.. option:: -v
Verbose mode. Print information about what :program:`llvm-link` is doing.
This typically includes a message for each bitcode file linked in and for each
library found.
EXIT STATUS
-----------
If :program:`llvm-link` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.

148
external/llvm/docs/CommandGuide/llvm-nm.rst vendored
View File

@ -1,148 +0,0 @@
llvm-nm - list LLVM bitcode and object file's symbol table
==========================================================
SYNOPSIS
--------
:program:`llvm-nm` [*options*] [*filenames...*]
DESCRIPTION
-----------
The :program:`llvm-nm` utility lists the names of symbols from the LLVM bitcode
files, object files, or :program:`ar` 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 *-* is used as a file name,
:program:`llvm-nm` will process a file on its standard input stream.
:program:`llvm-nm`'s default output format is the traditional BSD :program:`nm`
output format. Each such output record consists of an (optional) 8-digit
hexadecimal address, followed by a type code character, followed by a name, for
each symbol. One record is printed per line; fields are separated by spaces.
When the address is omitted, it is replaced by 8 spaces.
Type code characters currently supported, and their meanings, are as follows:
U
Named object is referenced but undefined in this bitcode file
C
Common (multiple definitions link together into one def)
W
Weak reference (multiple definitions link together into zero or one definitions)
t
Local function (text) object
T
Global function (text) object
d
Local data object
D
Global data object
?
Something unrecognizable
Because LLVM bitcode files typically contain objects that are not considered to
have addresses until they are linked into an executable image or dynamically
compiled "just-in-time", :program:`llvm-nm` does not print an address for any
symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
file.
OPTIONS
-------
.. program:: llvm-nm
.. option:: -B (default)
Use BSD output format. Alias for `--format=bsd`.
.. option:: -P
Use POSIX.2 output format. Alias for `--format=posix`.
.. option:: --debug-syms, -a
Show all symbols, even debugger only.
.. option:: --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.)
.. option:: --dynamic, -D
Display dynamic symbols instead of normal symbols.
.. option:: --extern-only, -g
Print only symbols whose definitions are external; that is, accessible
from other files.
.. option:: --format=format, -f format
Select an output format; *format* may be *sysv*, *posix*, or *bsd*. The default
is *bsd*.
.. option:: -help
Print a summary of command-line options and their meanings.
.. option:: --no-sort, -p
Shows symbols in order encountered.
.. option:: --numeric-sort, -n, -v
Sort symbols by address.
.. option:: --print-file-name, -A, -o
Precede each symbol with the file it came from.
.. option:: --print-size, -S
Show symbol size instead of address.
.. option:: --size-sort
Sort symbols by size.
.. option:: --undefined-only, -u
Print only symbols referenced but not defined in this file.
.. option:: --radix=RADIX, -t
Specify the radix of the symbol address(es). Values accepted d(decimal),
x(hexadecomal) and o(octal).
BUGS
----
* :program:`llvm-nm` does not support the full set of arguments that GNU
:program:`nm` does.
EXIT STATUS
-----------
:program:`llvm-nm` exits with an exit code of zero.
SEE ALSO
--------
llvm-dis, ar(1), nm(1)

Some files were not shown because too many files have changed in this diff Show More