diff options
Diffstat (limited to 'gnu/llvm/docs/CommandGuide')
32 files changed, 0 insertions, 6432 deletions
diff --git a/gnu/llvm/docs/CommandGuide/FileCheck.rst b/gnu/llvm/docs/CommandGuide/FileCheck.rst deleted file mode 100644 index 721d2c2e782..00000000000 --- a/gnu/llvm/docs/CommandGuide/FileCheck.rst +++ /dev/null @@ -1,603 +0,0 @@ -FileCheck - Flexible pattern matching file verifier -=================================================== - -SYNOPSIS --------- - -:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] - -DESCRIPTION ------------ - -:program:`FileCheck` reads two files (one from standard input, and one -specified on the command line) and uses one to verify the other. This -behavior is particularly useful for the testsuite, which wants to verify that -the output of some tool (e.g. :program:`llc`) contains the expected information -(for example, a movsd from esp or whatever is interesting). This is similar to -using :program:`grep`, but it is optimized for matching multiple different -inputs in one file in a specific order. - -The ``match-filename`` file specifies the file that contains the patterns to -match. The file to verify is read from standard input unless the -:option:`--input-file` option is used. - -OPTIONS -------- - -Options are parsed from the environment variable ``FILECHECK_OPTS`` -and from the command line. - -.. option:: -help - - Print a summary of command line options. - -.. option:: --check-prefix prefix - - FileCheck searches the contents of ``match-filename`` for patterns to - match. By default, these patterns are prefixed with "``CHECK:``". - If you'd like to use a different prefix (e.g. because the same input - file is checking multiple different tool or options), the - :option:`--check-prefix` argument allows you to specify one or more - prefixes to match. Multiple prefixes are useful for tests which might - change for different run options, but most lines remain the same. - -.. option:: --check-prefixes prefix1,prefix2,... - - An alias of :option:`--check-prefix` that allows multiple prefixes to be - specified as a comma separated list. - -.. option:: --input-file filename - - File to check (defaults to stdin). - -.. option:: --match-full-lines - - By default, FileCheck allows matches of anywhere on a line. This - option will require all positive matches to cover an entire - line. Leading and trailing whitespace is ignored, unless - :option:`--strict-whitespace` is also specified. (Note: negative - matches from ``CHECK-NOT`` are not affected by this option!) - - Passing this option is equivalent to inserting ``{{^ *}}`` or - ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive - check pattern. - -.. option:: --strict-whitespace - - By default, FileCheck canonicalizes input horizontal whitespace (spaces and - tabs) which causes it to ignore these differences (a space will match a tab). - The :option:`--strict-whitespace` argument disables this behavior. End-of-line - sequences are canonicalized to UNIX-style ``\n`` in all modes. - -.. option:: --implicit-check-not check-pattern - - Adds implicit negative checks for the specified patterns between positive - checks. The option allows writing stricter tests without stuffing them with - ``CHECK-NOT``\ s. - - For example, "``--implicit-check-not warning:``" can be useful when testing - diagnostic messages from tools that don't have an option similar to ``clang - -verify``. With this option FileCheck will verify that input does not contain - warnings not covered by any ``CHECK:`` patterns. - -.. option:: --dump-input <mode> - - Dump input to stderr, adding annotations representing currently enabled - diagnostics. Do this either 'always', on 'fail', or 'never'. Specify 'help' - to explain the dump format and quit. - -.. option:: --dump-input-on-failure - - When the check fails, dump all of the original input. This option is - deprecated in favor of `--dump-input=fail`. - -.. option:: --enable-var-scope - - Enables scope for regex variables. - - Variables with names that start with ``$`` are considered global and - remain set throughout the file. - - All other variables get undefined after each encountered ``CHECK-LABEL``. - -.. option:: -D<VAR=VALUE> - - Sets a filecheck variable ``VAR`` with value ``VALUE`` that can be used in - ``CHECK:`` lines. - -.. option:: -version - - Show the version number of this program. - -.. option:: -v - - Print directive pattern matches. - -.. option:: -vv - - Print information helpful in diagnosing internal FileCheck issues, such as - discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches, - and ``CHECK-NOT:`` patterns that do not have matches. Implies ``-v``. - -.. option:: --allow-deprecated-dag-overlap - - Enable overlapping among matches in a group of consecutive ``CHECK-DAG:`` - directives. This option is deprecated and is only provided for convenience - as old tests are migrated to the new non-overlapping ``CHECK-DAG:`` - implementation. - -.. option:: --color - - Use colors in output (autodetected by default). - -EXIT STATUS ------------ - -If :program:`FileCheck` verifies that the file matches the expected contents, -it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a -non-zero value. - -TUTORIAL --------- - -FileCheck is typically used from LLVM regression tests, being invoked on the RUN -line of the test. A simple example of using FileCheck from a RUN line looks -like this: - -.. code-block:: llvm - - ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s - -This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe -that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This -means that FileCheck will be verifying its standard input (the llc output) -against the filename argument specified (the original ``.ll`` file specified by -"``%s``"). To see how this works, let's look at the rest of the ``.ll`` file -(after the RUN line): - -.. code-block:: llvm - - define void @sub1(i32* %p, i32 %v) { - entry: - ; CHECK: sub1: - ; CHECK: subl - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) - ret void - } - - define void @inc4(i64* %p) { - entry: - ; CHECK: inc4: - ; CHECK: incq - %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) - ret void - } - -Here you can see some "``CHECK:``" lines specified in comments. Now you can -see how the file is piped into ``llvm-as``, then ``llc``, and the machine code -output is what we are verifying. FileCheck checks the machine code output to -verify that it matches what the "``CHECK:``" lines specify. - -The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that -must occur in order. FileCheck defaults to ignoring horizontal whitespace -differences (e.g. a space is allowed to match a tab) but otherwise, the contents -of the "``CHECK:``" line is required to match some thing in the test file exactly. - -One nice thing about FileCheck (compared to grep) is that it allows merging -test cases together into logical groups. For example, because the test above -is checking for the "``sub1:``" and "``inc4:``" labels, it will not match -unless there is a "``subl``" in between those labels. If it existed somewhere -else in the file, that would not count: "``grep subl``" matches if "``subl``" -exists anywhere in the file. - -The FileCheck -check-prefix option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The FileCheck `-check-prefix` option allows multiple test -configurations to be driven from one `.ll` file. This is useful in many -circumstances, for example, testing different architectural variants with -:program:`llc`. Here's a simple example: - -.. code-block:: llvm - - ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X32 - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X64 - - define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { - %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1 - ret <4 x i32> %tmp1 - ; X32: pinsrd_1: - ; X32: pinsrd $1, 4(%esp), %xmm0 - - ; X64: pinsrd_1: - ; X64: pinsrd $1, %edi, %xmm0 - } - -In this case, we're testing that we get the expected code generation with -both 32-bit and 64-bit code generation. - -The "CHECK-NEXT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you want to match lines and would like to verify that matches -happen on exactly consecutive lines with no other lines in between them. In -this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify -this. If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``". -For example, something like this works as you'd expect: - -.. code-block:: llvm - - define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { - %tmp3 = load <2 x double>* %A, align 16 - %tmp7 = insertelement <2 x double> undef, double %B, i32 0 - %tmp9 = shufflevector <2 x double> %tmp3, - <2 x double> %tmp7, - <2 x i32> < i32 0, i32 2 > - store <2 x double> %tmp9, <2 x double>* %r, align 16 - ret void - - ; CHECK: t2: - ; CHECK: movl 8(%esp), %eax - ; CHECK-NEXT: movapd (%eax), %xmm0 - ; CHECK-NEXT: movhpd 12(%esp), %xmm0 - ; CHECK-NEXT: movl 4(%esp), %eax - ; CHECK-NEXT: movapd %xmm0, (%eax) - ; CHECK-NEXT: ret - } - -"``CHECK-NEXT:``" directives reject the input unless there is exactly one -newline between it and the previous directive. A "``CHECK-NEXT:``" cannot be -the first directive in a file. - -The "CHECK-SAME:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you want to match lines and would like to verify that matches happen -on the same line as the previous match. In this case, you can use "``CHECK:``" -and "``CHECK-SAME:``" directives to specify this. If you specified a custom -check prefix, just use "``<PREFIX>-SAME:``". - -"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``" -(described below). - -For example, the following works like you'd expect: - -.. code-block:: llvm - - !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2) - - ; CHECK: !DILocation(line: 5, - ; CHECK-NOT: column: - ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]] - -"``CHECK-SAME:``" directives reject the input if there are any newlines between -it and the previous directive. A "``CHECK-SAME:``" cannot be the first -directive in a file. - -The "CHECK-EMPTY:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to check that the next line has nothing on it, not even whitespace, -you can use the "``CHECK-EMPTY:``" directive. - -.. code-block:: llvm - - declare void @foo() - - declare void @bar() - ; CHECK: foo - ; CHECK-EMPTY: - ; CHECK-NEXT: bar - -Just like "``CHECK-NEXT:``" the directive will fail if there is more than one -newline before it finds the next blank line, and it cannot be the first -directive in a file. - -The "CHECK-NOT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur -between two matches (or before the first match, or after the last match). For -example, to verify that a load is removed by a transformation, a test like this -can be used: - -.. code-block:: llvm - - define i8 @coerce_offset0(i32 %V, i32* %P) { - store i32 %V, i32* %P - - %P2 = bitcast i32* %P to i8* - %P3 = getelementptr i8* %P2, i32 2 - - %A = load i8* %P3 - ret i8 %A - ; CHECK: @coerce_offset0 - ; CHECK-NOT: load - ; CHECK: ret i8 - } - -The "CHECK-COUNT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to match multiple lines with the same pattern over and over again -you can repeat a plain ``CHECK:`` as many times as needed. If that looks too -boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where -``<num>`` is a positive decimal number. It will match the pattern exactly -``<num>`` times, no more and no less. If you specified a custom check prefix, -just use "``<PREFIX>-COUNT-<num>:``" for the same effect. -Here is a simple example: - -.. code-block:: text - - Loop at depth 1 - Loop at depth 1 - Loop at depth 1 - Loop at depth 1 - Loop at depth 2 - Loop at depth 3 - - ; CHECK-COUNT-6: Loop at depth {{[0-9]+}} - ; CHECK-NOT: Loop at depth {{[0-9]+}} - -The "CHECK-DAG:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If it's necessary to match strings that don't occur in a strictly sequential -order, "``CHECK-DAG:``" could be used to verify them between two matches (or -before the first match, or after the last match). For example, clang emits -vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks -in the natural order: - -.. code-block:: c++ - - // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s - - struct Foo { virtual void method(); }; - Foo f; // emit vtable - // CHECK-DAG: @_ZTV3Foo = - - struct Bar { virtual void method(); }; - Bar b; - // CHECK-DAG: @_ZTV3Bar = - -``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to -exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result, -the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all -occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind -occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example, - -.. code-block:: llvm - - ; CHECK-DAG: BEFORE - ; CHECK-NOT: NOT - ; CHECK-DAG: AFTER - -This case will reject input strings where ``BEFORE`` occurs after ``AFTER``. - -With captured variables, ``CHECK-DAG:`` is able to match valid topological -orderings of a DAG with edges from the definition of a variable to its use. -It's useful, e.g., when your test cases need to match different output -sequences from the instruction scheduler. For example, - -.. code-block:: llvm - - ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2 - ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4 - ; CHECK: mul r5, [[REG1]], [[REG2]] - -In this case, any order of that two ``add`` instructions will be allowed. - -If you are defining `and` using variables in the same ``CHECK-DAG:`` block, -be aware that the definition rule can match `after` its use. - -So, for instance, the code below will pass: - -.. code-block:: text - - ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0] - ; CHECK-DAG: vmov.32 [[REG2]][1] - vmov.32 d0[1] - vmov.32 d0[0] - -While this other code, will not: - -.. code-block:: text - - ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0] - ; CHECK-DAG: vmov.32 [[REG2]][1] - vmov.32 d1[1] - vmov.32 d0[0] - -While this can be very useful, it's also dangerous, because in the case of -register sequence, you must have a strong order (read before write, copy before -use, etc). If the definition your test is looking for doesn't match (because -of a bug in the compiler), it may match further away from the use, and mask -real bugs away. - -In those cases, to enforce the order, use a non-DAG directive between DAG-blocks. - -A ``CHECK-DAG:`` directive skips matches that overlap the matches of any -preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block. Not only -is this non-overlapping behavior consistent with other directives, but it's -also necessary to handle sets of non-unique strings or patterns. For example, -the following directives look for unordered log entries for two tasks in a -parallel program, such as the OpenMP runtime: - -.. code-block:: text - - // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin - // CHECK-DAG: [[THREAD_ID]]: task_end - // - // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin - // CHECK-DAG: [[THREAD_ID]]: task_end - -The second pair of directives is guaranteed not to match the same log entries -as the first pair even though the patterns are identical and even if the text -of the log entries is identical because the thread ID manages to be reused. - -The "CHECK-LABEL:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes in a file containing multiple tests divided into logical blocks, one -or more ``CHECK:`` directives may inadvertently succeed by matching lines in a -later block. While an error will usually eventually be generated, the check -flagged as causing the error may not actually bear any relationship to the -actual source of the problem. - -In order to produce better error messages in these cases, the "``CHECK-LABEL:``" -directive can be used. It is treated identically to a normal ``CHECK`` -directive except that FileCheck makes an additional assumption that a line -matched by the directive cannot also be matched by any other check present in -``match-filename``; this is intended to be used for lines containing labels or -other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides -the input stream into separate blocks, each of which is processed independently, -preventing a ``CHECK:`` directive in one block matching a line in another block. -If ``--enable-var-scope`` is in effect, all local variables are cleared at the -beginning of the block. - -For example, - -.. code-block:: llvm - - define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) { - entry: - ; CHECK-LABEL: C_ctor_base: - ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0 - ; CHECK: bl A_ctor_base - ; CHECK: mov r0, [[SAVETHIS]] - %0 = bitcast %struct.C* %this to %struct.A* - %call = tail call %struct.A* @A_ctor_base(%struct.A* %0) - %1 = bitcast %struct.C* %this to %struct.B* - %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x) - ret %struct.C* %this - } - - define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) { - entry: - ; CHECK-LABEL: D_ctor_base: - -The use of ``CHECK-LABEL:`` directives in this case ensures that the three -``CHECK:`` directives only accept lines corresponding to the body of the -``@C_ctor_base`` function, even if the patterns match lines found later in -the file. Furthermore, if one of these three ``CHECK:`` directives fail, -FileCheck will recover by continuing to the next block, allowing multiple test -failures to be detected in a single invocation. - -There is no requirement that ``CHECK-LABEL:`` directives contain strings that -correspond to actual syntactic labels in a source or output language: they must -simply uniquely match a single line in the file being verified. - -``CHECK-LABEL:`` directives cannot contain variable definitions or uses. - -FileCheck Pattern Matching Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All FileCheck directives take a pattern to match. -For most uses of FileCheck, fixed string matching is perfectly sufficient. For -some things, a more flexible form of matching is desired. To support this, -FileCheck allows you to specify regular expressions in matching strings, -surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX -regular expression matcher; it supports Extended POSIX regular expressions -(ERE). Because we want to use fixed string matching for a majority of what we -do, FileCheck has been designed to support mixing and matching fixed string -matching with regular expressions. This allows you to write things like this: - -.. code-block:: llvm - - ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} - -In this case, any offset from the ESP register will be allowed, and any xmm -register will be allowed. - -Because regular expressions are enclosed with double braces, they are -visually distinct, and you don't need to use escape characters within the double -braces like you would in C. In the rare case that you want to match double -braces explicitly from the input, you can use something ugly like -``{{[{][{]}}`` as your pattern. - -FileCheck Variables -~~~~~~~~~~~~~~~~~~~ - -It is often useful to match a pattern and then verify that it occurs again -later in the file. For codegen tests, this can be useful to allow any register, -but verify that that register is used consistently later. To do this, -:program:`FileCheck` allows named variables to be defined and substituted into -patterns. Here is a simple example: - -.. code-block:: llvm - - ; CHECK: test5: - ; CHECK: notw [[REGISTER:%[a-z]+]] - ; CHECK: andw {{.*}}[[REGISTER]] - -The first check line matches a regex ``%[a-z]+`` and captures it into the -variable ``REGISTER``. The second line verifies that whatever is in -``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck` -variable references are always contained in ``[[ ]]`` pairs, and their names can -be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``. If a colon follows the name, -then it is a definition of the variable; otherwise, it is a use. - -:program:`FileCheck` variables can be defined multiple times, and uses always -get the latest value. Variables can also be used later on the same line they -were defined on. For example: - -.. code-block:: llvm - - ; CHECK: op [[REG:r[0-9]+]], [[REG]] - -Can be useful if you want the operands of ``op`` to be the same register, -and don't care exactly which register it is. - -If ``--enable-var-scope`` is in effect, variables with names that -start with ``$`` are considered to be global. All others variables are -local. All local variables get undefined at the beginning of each -CHECK-LABEL block. Global variables are not affected by CHECK-LABEL. -This makes it easier to ensure that individual tests are not affected -by variables set in preceding tests. - -FileCheck Expressions -~~~~~~~~~~~~~~~~~~~~~ - -Sometimes there's a need to verify output which refers line numbers of the -match file, e.g. when testing compiler diagnostics. This introduces a certain -fragility of the match file structure, as "``CHECK:``" lines contain absolute -line numbers in the same file, which have to be updated whenever line numbers -change due to text addition or deletion. - -To support this case, FileCheck allows using ``[[@LINE]]``, -``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These -expressions expand to a number of the line where a pattern is located (with an -optional integer offset). - -This way match patterns can be put near the relevant test lines and include -relative line number references, for example: - -.. code-block:: c++ - - // CHECK: test.cpp:[[@LINE+4]]:6: error: expected ';' after top level declarator - // CHECK-NEXT: {{^int a}} - // CHECK-NEXT: {{^ \^}} - // CHECK-NEXT: {{^ ;}} - int a - -Matching Newline Characters -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To match newline characters in regular expressions the character class -``[[:space:]]`` can be used. For example, the following pattern: - -.. code-block:: c++ - - // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd" - -matches output of the form (from llvm-dwarfdump): - -.. code-block:: text - - DW_AT_location [DW_FORM_sec_offset] (0x00000233) - DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd") - -letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value -``0x00000233``, extracted from the line immediately preceding "``intd``". diff --git a/gnu/llvm/docs/CommandGuide/bugpoint.rst b/gnu/llvm/docs/CommandGuide/bugpoint.rst deleted file mode 100644 index 8c2a0d12498..00000000000 --- a/gnu/llvm/docs/CommandGuide/bugpoint.rst +++ /dev/null @@ -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 diff --git a/gnu/llvm/docs/CommandGuide/dsymutil.rst b/gnu/llvm/docs/CommandGuide/dsymutil.rst deleted file mode 100644 index ceaa54019a8..00000000000 --- a/gnu/llvm/docs/CommandGuide/dsymutil.rst +++ /dev/null @@ -1,115 +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:: -z, --minimize - - When used when creating a dSYM file, this option will suppress the emission of - the .debug_inlines, .debug_pubnames, and .debug_pubtypes sections since - dsymutil currently has better equivalents: .apple_names and .apple_types. When - used in conjunction with --update option, this option will cause redundant - accelerator tables to be removed. - -.. 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:: --papertrail - - When running dsymutil as part of your build system, it can be desirable for - warnings to be part of the end product, rather than just being emitted to the - output stream. When enabled warnings are embedded in the linked DWARF debug - information. - -.. option:: -s, --symtab - - Dumps the symbol table found in *executable* or object file(s) and exits. - -.. option:: --toolchain - - Embed the toolchain in the dSYM bundle's property list. - -.. option:: -u, --update - - Update an existing dSYM file to contain the latest accelerator tables and - other DWARF optimizations. This option will rebuild the '.apple_names' and - '.apple_types' hashed accelerator tables. - -.. 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)` diff --git a/gnu/llvm/docs/CommandGuide/index.rst b/gnu/llvm/docs/CommandGuide/index.rst deleted file mode 100644 index 9108ae6a96b..00000000000 --- a/gnu/llvm/docs/CommandGuide/index.rst +++ /dev/null @@ -1,60 +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-objdump - llvm-config - llvm-cxxmap - llvm-diff - llvm-cov - llvm-profdata - llvm-stress - llvm-symbolizer - llvm-dwarfdump - dsymutil - llvm-mca - -Debugging Tools -~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 1 - - bugpoint - llvm-extract - llvm-bcanalyzer - -Developer Tools -~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 1 - - FileCheck - tblgen - lit - llvm-build - llvm-exegesis - llvm-pdbutil - llvm-readobj diff --git a/gnu/llvm/docs/CommandGuide/lit.rst b/gnu/llvm/docs/CommandGuide/lit.rst deleted file mode 100644 index e0d09ae977d..00000000000 --- a/gnu/llvm/docs/CommandGuide/lit.rst +++ /dev/null @@ -1,482 +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. - :program:`lit` normally inserts a no-op command (``:`` in the case of bash) - with argument ``'RUN: at line N'`` before each command pipeline, and this - option also causes those no-op commands to be echoed to stdout to help you - locate the source line of the failed command. - 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 parent directory of %t (not unique, deprecated, do not use) - %% % - ========== ============== - -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) diff --git a/gnu/llvm/docs/CommandGuide/llc.rst b/gnu/llvm/docs/CommandGuide/llc.rst deleted file mode 100644 index da096f1263a..00000000000 --- a/gnu/llvm/docs/CommandGuide/llc.rst +++ /dev/null @@ -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:: --frame-pointer - - Specify effect of frame pointer elimination optimization (all,non-leaf,none). - -.. 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 values (pointer size) 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 - diff --git a/gnu/llvm/docs/CommandGuide/lli.rst b/gnu/llvm/docs/CommandGuide/lli.rst deleted file mode 100644 index 1132ac3e6be..00000000000 --- a/gnu/llvm/docs/CommandGuide/lli.rst +++ /dev/null @@ -1,215 +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 - tiny: Tiny 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` diff --git a/gnu/llvm/docs/CommandGuide/llvm-ar.rst b/gnu/llvm/docs/CommandGuide/llvm-ar.rst deleted file mode 100644 index d3ee993f738..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-ar.rst +++ /dev/null @@ -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) diff --git a/gnu/llvm/docs/CommandGuide/llvm-as.rst b/gnu/llvm/docs/CommandGuide/llvm-as.rst deleted file mode 100644 index 1b499bbe970..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-as.rst +++ /dev/null @@ -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 diff --git a/gnu/llvm/docs/CommandGuide/llvm-bcanalyzer.rst b/gnu/llvm/docs/CommandGuide/llvm-bcanalyzer.rst deleted file mode 100644 index 7254088ec94..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-bcanalyzer.rst +++ /dev/null @@ -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` - diff --git a/gnu/llvm/docs/CommandGuide/llvm-build.rst b/gnu/llvm/docs/CommandGuide/llvm-build.rst deleted file mode 100644 index f788f7c5a83..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-build.rst +++ /dev/null @@ -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. diff --git a/gnu/llvm/docs/CommandGuide/llvm-config.rst b/gnu/llvm/docs/CommandGuide/llvm-config.rst deleted file mode 100644 index 34075d0b308..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-config.rst +++ /dev/null @@ -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. diff --git a/gnu/llvm/docs/CommandGuide/llvm-cov.rst b/gnu/llvm/docs/CommandGuide/llvm-cov.rst deleted file mode 100644 index 71924e997d9..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-cov.rst +++ /dev/null @@ -1,416 +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:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths 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 can be shown for each -function in the listed files if the ``-show-functions`` option is enabled. - -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. - -.. option:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths that match the given regular expression. - -.. program:: llvm-cov export - -.. _llvm-cov-export: - -EXPORT COMMAND --------------- - -SYNOPSIS -^^^^^^^^ - -:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] - -DESCRIPTION -^^^^^^^^^^^ - -The :program:`llvm-cov export` command exports coverage data of the binaries -*BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file -format. - -When exporting JSON, the regions, functions, expansions, and summaries of the -coverage data will be exported. When exporting an lcov trace file, the -line-based coverage and summaries will be exported. - -The exported data can optionally be filtered to only export the coverage -for the files listed in *SOURCES*. - -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:: -format=<FORMAT> - - Use the specified output format. The supported formats are: "text" (JSON), - "lcov". - -.. 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 contain the same information as produced - by the :program:`llvm-cov report` command, but presented in JSON or lcov - format rather than text. - -.. option:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths that match the given regular expression. diff --git a/gnu/llvm/docs/CommandGuide/llvm-cxxmap.rst b/gnu/llvm/docs/CommandGuide/llvm-cxxmap.rst deleted file mode 100644 index 7293f60b55d..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-cxxmap.rst +++ /dev/null @@ -1,91 +0,0 @@ -llvm-cxxmap - Mangled name remapping tool -========================================= - -SYNOPSIS --------- - -:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2* - -DESCRIPTION ------------ - -The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names, -based on a file describing name components that should be considered equivalent. - -The symbol files should contain a list of C++ mangled names (one per line). -Blank lines and lines starting with ``#`` are ignored. The output is a list -of pairs of equivalent symbols, one per line, of the form - -.. code-block:: none - - <symbol-1> <symbol-2> - -where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is -a symbol from *symbol-file-2*. Mappings for which the two symbols are identical -are omitted. - -OPTIONS -------- - -.. program:: llvm-cxxmap - -.. option:: -remapping-file=file, -r=file - - Specify a file containing a list of equivalence rules that should be used - to determine whether two symbols are equivalent. Required. - See :ref:`remapping-file`. - -.. option:: -output=file, -o=file - - Specify a file to write the list of matched names to. If unspecified, the - list will be written to stdout. - -.. option:: -Wambiguous - - Produce a warning if there are multiple equivalent (but distinct) symbols in - *symbol-file-2*. - -.. option:: -Wincomplete - - Produce a warning if *symbol-file-1* contains a symbol for which there is no - equivalent symbol in *symbol-file-2*. - -.. _remapping-file: - -REMAPPING FILE --------------- - -The remapping file is a text file containing lines of the form - -.. code-block:: none - - fragmentkind fragment1 fragment2 - -where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, -indicating whether the following mangled name fragments are -<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, -<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or -<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, -respectively. -Blank lines and lines starting with ``#`` are ignored. - -For convenience, built-in <substitution>s such as ``St`` and ``Ss`` -are accepted as <name>s (even though they technically are not <name>s). - -For example, to specify that ``absl::string_view`` and ``std::string_view`` -should be treated as equivalent, the following remapping file could be used: - -.. code-block:: none - - # absl::string_view is considered equivalent to std::string_view - type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE - - # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++ - name St St3__1 - name St St7__cxx11 - -.. note:: - - Symbol remapping is currently only supported for C++ mangled names - following the Itanium C++ ABI mangling scheme. This covers all C++ targets - supported by Clang other than Windows targets. diff --git a/gnu/llvm/docs/CommandGuide/llvm-diff.rst b/gnu/llvm/docs/CommandGuide/llvm-diff.rst deleted file mode 100644 index 991d4fece04..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-diff.rst +++ /dev/null @@ -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. diff --git a/gnu/llvm/docs/CommandGuide/llvm-dis.rst b/gnu/llvm/docs/CommandGuide/llvm-dis.rst deleted file mode 100644 index 85cdca85ecd..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-dis.rst +++ /dev/null @@ -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 diff --git a/gnu/llvm/docs/CommandGuide/llvm-dwarfdump.rst b/gnu/llvm/docs/CommandGuide/llvm-dwarfdump.rst deleted file mode 100644 index a3b62664cbe..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-dwarfdump.rst +++ /dev/null @@ -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)` diff --git a/gnu/llvm/docs/CommandGuide/llvm-exegesis-analysis.png b/gnu/llvm/docs/CommandGuide/llvm-exegesis-analysis.png Binary files differdeleted file mode 100644 index e232f5f1235..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-exegesis-analysis.png +++ /dev/null diff --git a/gnu/llvm/docs/CommandGuide/llvm-exegesis.rst b/gnu/llvm/docs/CommandGuide/llvm-exegesis.rst deleted file mode 100644 index f27db9e57ed..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-exegesis.rst +++ /dev/null @@ -1,236 +0,0 @@ -llvm-exegesis - LLVM Machine Instruction Benchmark -================================================== - -SYNOPSIS --------- - -:program:`llvm-exegesis` [*options*] - -DESCRIPTION ------------ - -:program:`llvm-exegesis` is a benchmarking tool that uses information available -in LLVM to measure host machine instruction characteristics like latency or port -decomposition. - -Given an LLVM opcode name and a benchmarking mode, :program:`llvm-exegesis` -generates a code snippet that makes execution as serial (resp. as parallel) as -possible so that we can measure the latency (resp. uop decomposition) of the -instruction. -The code snippet is jitted and executed on the host subtarget. The time taken -(resp. resource usage) is measured using hardware performance counters. The -result is printed out as YAML to the standard output. - -The main goal of this tool is to automatically (in)validate the LLVM's TableDef -scheduling models. To that end, we also provide analysis of the results. - -:program:`llvm-exegesis` can also benchmark arbitrary user-provided code -snippets. - -EXAMPLE 1: benchmarking instructions ------------------------------------- - -Assume you have an X86-64 machine. To measure the latency of a single -instruction, run: - -.. code-block:: bash - - $ llvm-exegesis -mode=latency -opcode-name=ADD64rr - -Measuring the uop decomposition of an instruction works similarly: - -.. code-block:: bash - - $ llvm-exegesis -mode=uops -opcode-name=ADD64rr - -The output is a YAML document (the default is to write to stdout, but you can -redirect the output to a file using `-benchmarks-file`): - -.. code-block:: none - - --- - key: - opcode_name: ADD64rr - mode: latency - config: '' - cpu_name: haswell - llvm_triple: x86_64-unknown-linux-gnu - num_repetitions: 10000 - measurements: - - { key: latency, value: 1.0058, debug_string: '' } - error: '' - info: 'explicit self cycles, selecting one aliasing configuration. - Snippet: - ADD64rr R8, R8, R10 - ' - ... - -To measure the latency of all instructions for the host architecture, run: - -.. code-block:: bash - - #!/bin/bash - readonly INSTRUCTIONS=$(($(grep INSTRUCTION_LIST_END build/lib/Target/X86/X86GenInstrInfo.inc | cut -f2 -d=) - 1)) - for INSTRUCTION in $(seq 1 ${INSTRUCTIONS}); - do - ./build/bin/llvm-exegesis -mode=latency -opcode-index=${INSTRUCTION} | sed -n '/---/,$p' - done - -FIXME: Provide an :program:`llvm-exegesis` option to test all instructions. - - -EXAMPLE 2: benchmarking a custom code snippet ---------------------------------------------- - -To measure the latency/uops of a custom piece of code, you can specify the -`snippets-file` option (`-` reads from standard input). - -.. code-block:: bash - - $ echo "vzeroupper" | llvm-exegesis -mode=uops -snippets-file=- - -Real-life code snippets typically depend on registers or memory. -:program:`llvm-exegesis` checks the liveliness of registers (i.e. any register -use has a corresponding def or is a "live in"). If your code depends on the -value of some registers, you have two options: - -- Mark the register as requiring a definition. :program:`llvm-exegesis` will - automatically assign a value to the register. This can be done using the - directive `LLVM-EXEGESIS-DEFREG <reg name> <hex_value>`, where `<hex_value>` - is a bit pattern used to fill `<reg_name>`. If `<hex_value>` is smaller than - the register width, it will be sign-extended. -- Mark the register as a "live in". :program:`llvm-exegesis` will benchmark - using whatever value was in this registers on entry. This can be done using - the directive `LLVM-EXEGESIS-LIVEIN <reg name>`. - -For example, the following code snippet depends on the values of XMM1 (which -will be set by the tool) and the memory buffer passed in RDI (live in). - -.. code-block:: none - - # LLVM-EXEGESIS-LIVEIN RDI - # LLVM-EXEGESIS-DEFREG XMM1 42 - vmulps (%rdi), %xmm1, %xmm2 - vhaddps %xmm2, %xmm2, %xmm3 - addq $0x10, %rdi - - -EXAMPLE 3: analysis -------------------- - -Assuming you have a set of benchmarked instructions (either latency or uops) as -YAML in file `/tmp/benchmarks.yaml`, you can analyze the results using the -following command: - -.. code-block:: bash - - $ llvm-exegesis -mode=analysis \ - -benchmarks-file=/tmp/benchmarks.yaml \ - -analysis-clusters-output-file=/tmp/clusters.csv \ - -analysis-inconsistencies-output-file=/tmp/inconsistencies.html - -This will group the instructions into clusters with the same performance -characteristics. The clusters will be written out to `/tmp/clusters.csv` in the -following format: - -.. code-block:: none - - cluster_id,opcode_name,config,sched_class - ... - 2,ADD32ri8_DB,,WriteALU,1.00 - 2,ADD32ri_DB,,WriteALU,1.01 - 2,ADD32rr,,WriteALU,1.01 - 2,ADD32rr_DB,,WriteALU,1.00 - 2,ADD32rr_REV,,WriteALU,1.00 - 2,ADD64i32,,WriteALU,1.01 - 2,ADD64ri32,,WriteALU,1.01 - 2,MOVSX64rr32,,BSWAP32r_BSWAP64r_MOVSX64rr32,1.00 - 2,VPADDQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.02 - 2,VPSUBQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.01 - 2,ADD64ri8,,WriteALU,1.00 - 2,SETBr,,WriteSETCC,1.01 - ... - -:program:`llvm-exegesis` will also analyze the clusters to point out -inconsistencies in the scheduling information. The output is an html file. For -example, `/tmp/inconsistencies.html` will contain messages like the following : - -.. image:: llvm-exegesis-analysis.png - :align: center - -Note that the scheduling class names will be resolved only when -:program:`llvm-exegesis` is compiled in debug mode, else only the class id will -be shown. This does not invalidate any of the analysis results though. - - -OPTIONS -------- - -.. option:: -help - - Print a summary of command line options. - -.. option:: -opcode-index=<LLVM opcode index> - - Specify the opcode to measure, by index. See example 1 for details. - Either `opcode-index`, `opcode-name` or `snippets-file` must be set. - -.. option:: -opcode-name=<opcode name 1>,<opcode name 2>,... - - Specify the opcode to measure, by name. Several opcodes can be specified as - a comma-separated list. See example 1 for details. - Either `opcode-index`, `opcode-name` or `snippets-file` must be set. - - .. option:: -snippets-file=<filename> - - Specify the custom code snippet to measure. See example 2 for details. - Either `opcode-index`, `opcode-name` or `snippets-file` must be set. - -.. option:: -mode=[latency|uops|analysis] - - Specify the run mode. - -.. option:: -num-repetitions=<Number of repetition> - - Specify the number of repetitions of the asm snippet. - Higher values lead to more accurate measurements but lengthen the benchmark. - -.. option:: -benchmarks-file=</path/to/file> - - File to read (`analysis` mode) or write (`latency`/`uops` modes) benchmark - results. "-" uses stdin/stdout. - -.. option:: -analysis-clusters-output-file=</path/to/file> - - If provided, write the analysis clusters as CSV to this file. "-" prints to - stdout. - -.. option:: -analysis-inconsistencies-output-file=</path/to/file> - - If non-empty, write inconsistencies found during analysis to this file. `-` - prints to stdout. - -.. option:: -analysis-numpoints=<dbscan numPoints parameter> - - Specify the numPoints parameters to be used for DBSCAN clustering - (`analysis` mode). - -.. option:: -analysis-espilon=<dbscan epsilon parameter> - - Specify the numPoints parameters to be used for DBSCAN clustering - (`analysis` mode). - -.. option:: -ignore-invalid-sched-class=false - - If set, ignore instructions that do not have a sched class (class idx = 0). - - .. option:: -mcpu=<cpu name> - - If set, measure the cpu characteristics using the counters for this CPU. This - is useful when creating new sched models (the host CPU is unknown to LLVM). - -EXIT STATUS ------------ - -:program:`llvm-exegesis` returns 0 on success. Otherwise, an error message is -printed to standard error, and the tool returns a non 0 value. diff --git a/gnu/llvm/docs/CommandGuide/llvm-extract.rst b/gnu/llvm/docs/CommandGuide/llvm-extract.rst deleted file mode 100644 index d0e9c1c255a..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-extract.rst +++ /dev/null @@ -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 - diff --git a/gnu/llvm/docs/CommandGuide/llvm-lib.rst b/gnu/llvm/docs/CommandGuide/llvm-lib.rst deleted file mode 100644 index ecd0a7db7e3..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-lib.rst +++ /dev/null @@ -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). diff --git a/gnu/llvm/docs/CommandGuide/llvm-link.rst b/gnu/llvm/docs/CommandGuide/llvm-link.rst deleted file mode 100644 index 3bcfa68c259..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-link.rst +++ /dev/null @@ -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. - - diff --git a/gnu/llvm/docs/CommandGuide/llvm-mca.rst b/gnu/llvm/docs/CommandGuide/llvm-mca.rst deleted file mode 100644 index bc50794e0cb..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-mca.rst +++ /dev/null @@ -1,769 +0,0 @@ -llvm-mca - LLVM Machine Code Analyzer -===================================== - -SYNOPSIS --------- - -:program:`llvm-mca` [*options*] [input] - -DESCRIPTION ------------ - -:program:`llvm-mca` is a performance analysis tool that uses information -available in LLVM (e.g. scheduling models) to statically measure the performance -of machine code in a specific CPU. - -Performance is measured in terms of throughput as well as processor resource -consumption. The tool currently works for processors with an out-of-order -backend, for which there is a scheduling model available in LLVM. - -The main goal of this tool is not just to predict the performance of the code -when run on the target, but also help with diagnosing potential performance -issues. - -Given an assembly code sequence, :program:`llvm-mca` estimates the Instructions -Per Cycle (IPC), as well as hardware resource pressure. The analysis and -reporting style were inspired by the IACA tool from Intel. - -For example, you can compile code with clang, output assembly, and pipe it -directly into :program:`llvm-mca` for analysis: - -.. code-block:: bash - - $ clang foo.c -O2 -target x86_64-unknown-unknown -S -o - | llvm-mca -mcpu=btver2 - -Or for Intel syntax: - -.. code-block:: bash - - $ clang foo.c -O2 -target x86_64-unknown-unknown -mllvm -x86-asm-syntax=intel -S -o - | llvm-mca -mcpu=btver2 - -OPTIONS -------- - -If ``input`` is "``-``" or omitted, :program:`llvm-mca` reads from standard -input. Otherwise, it will read from the specified filename. - -If the :option:`-o` option is omitted, then :program:`llvm-mca` 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. - - -.. option:: -help - - Print a summary of command line options. - -.. option:: -mtriple=<target triple> - - Specify a target triple string. - -.. option:: -march=<arch> - - Specify the architecture for which to analyze the code. It defaults to the - host default target. - -.. option:: -mcpu=<cpuname> - - Specify the processor for which to analyze the code. By default, the cpu name - is autodetected from the host. - -.. option:: -output-asm-variant=<variant id> - - Specify the output assembly variant for the report generated by the tool. - On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables - the AT&T (vic. Intel) assembly format for the code printed out by the tool in - the analysis report. - -.. option:: -dispatch=<width> - - Specify a different dispatch width for the processor. The dispatch width - defaults to field 'IssueWidth' in the processor scheduling model. If width is - zero, then the default dispatch width is used. - -.. option:: -register-file-size=<size> - - Specify the size of the register file. When specified, this flag limits how - many physical registers are available for register renaming purposes. A value - of zero for this flag means "unlimited number of physical registers". - -.. option:: -iterations=<number of iterations> - - Specify the number of iterations to run. If this flag is set to 0, then the - tool sets the number of iterations to a default value (i.e. 100). - -.. option:: -noalias=<bool> - - If set, the tool assumes that loads and stores don't alias. This is the - default behavior. - -.. option:: -lqueue=<load queue size> - - Specify the size of the load queue in the load/store unit emulated by the tool. - By default, the tool assumes an unbound number of entries in the load queue. - A value of zero for this flag is ignored, and the default load queue size is - used instead. - -.. option:: -squeue=<store queue size> - - Specify the size of the store queue in the load/store unit emulated by the - tool. By default, the tool assumes an unbound number of entries in the store - queue. A value of zero for this flag is ignored, and the default store queue - size is used instead. - -.. option:: -timeline - - Enable the timeline view. - -.. option:: -timeline-max-iterations=<iterations> - - Limit the number of iterations to print in the timeline view. By default, the - timeline view prints information for up to 10 iterations. - -.. option:: -timeline-max-cycles=<cycles> - - Limit the number of cycles in the timeline view. By default, the number of - cycles is set to 80. - -.. option:: -resource-pressure - - Enable the resource pressure view. This is enabled by default. - -.. option:: -register-file-stats - - Enable register file usage statistics. - -.. option:: -dispatch-stats - - Enable extra dispatch statistics. This view collects and analyzes instruction - dispatch events, as well as static/dynamic dispatch stall events. This view - is disabled by default. - -.. option:: -scheduler-stats - - Enable extra scheduler statistics. This view collects and analyzes instruction - issue events. This view is disabled by default. - -.. option:: -retire-stats - - Enable extra retire control unit statistics. This view is disabled by default. - -.. option:: -instruction-info - - Enable the instruction info view. This is enabled by default. - -.. option:: -all-stats - - Print all hardware statistics. This enables extra statistics related to the - dispatch logic, the hardware schedulers, the register file(s), and the retire - control unit. This option is disabled by default. - -.. option:: -all-views - - Enable all the view. - -.. option:: -instruction-tables - - Prints resource pressure information based on the static information - available from the processor model. This differs from the resource pressure - view because it doesn't require that the code is simulated. It instead prints - the theoretical uniform distribution of resource pressure for every - instruction in sequence. - - -EXIT STATUS ------------ - -:program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed -to standard error, and the tool returns 1. - -USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS ---------------------------------------------- -:program:`llvm-mca` allows for the optional usage of special code comments to -mark regions of the assembly code to be analyzed. A comment starting with -substring ``LLVM-MCA-BEGIN`` marks the beginning of a code region. A comment -starting with substring ``LLVM-MCA-END`` marks the end of a code region. For -example: - -.. code-block:: none - - # LLVM-MCA-BEGIN My Code Region - ... - # LLVM-MCA-END - -Multiple regions can be specified provided that they do not overlap. A code -region can have an optional description. If no user-defined region is specified, -then :program:`llvm-mca` assumes a default region which contains every -instruction in the input file. Every region is analyzed in isolation, and the -final performance report is the union of all the reports generated for every -code region. - -Inline assembly directives may be used from source code to annotate the -assembly text: - -.. code-block:: c++ - - int foo(int a, int b) { - __asm volatile("# LLVM-MCA-BEGIN foo"); - a += 42; - __asm volatile("# LLVM-MCA-END"); - a *= b; - return a; - } - -HOW LLVM-MCA WORKS ------------------- - -:program:`llvm-mca` takes assembly code as input. The assembly code is parsed -into a sequence of MCInst with the help of the existing LLVM target assembly -parsers. The parsed sequence of MCInst is then analyzed by a ``Pipeline`` module -to generate a performance report. - -The Pipeline module simulates the execution of the machine code sequence in a -loop of iterations (default is 100). During this process, the pipeline collects -a number of execution related statistics. At the end of this process, the -pipeline generates and prints a report from the collected statistics. - -Here is an example of a performance report generated by the tool for a -dot-product of two packed float vectors of four elements. The analysis is -conducted for target x86, cpu btver2. The following result can be produced via -the following command using the example located at -``test/tools/llvm-mca/X86/BtVer2/dot-product.s``: - -.. code-block:: bash - - $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=300 dot-product.s - -.. code-block:: none - - Iterations: 300 - Instructions: 900 - Total Cycles: 610 - Total uOps: 900 - - Dispatch Width: 2 - uOps Per Cycle: 1.48 - IPC: 1.48 - Block RThroughput: 2.0 - - - Instruction Info: - [1]: #uOps - [2]: Latency - [3]: RThroughput - [4]: MayLoad - [5]: MayStore - [6]: HasSideEffects (U) - - [1] [2] [3] [4] [5] [6] Instructions: - 1 2 1.00 vmulps %xmm0, %xmm1, %xmm2 - 1 3 1.00 vhaddps %xmm2, %xmm2, %xmm3 - 1 3 1.00 vhaddps %xmm3, %xmm3, %xmm4 - - - Resources: - [0] - JALU0 - [1] - JALU1 - [2] - JDiv - [3] - JFPA - [4] - JFPM - [5] - JFPU0 - [6] - JFPU1 - [7] - JLAGU - [8] - JMul - [9] - JSAGU - [10] - JSTC - [11] - JVALU0 - [12] - JVALU1 - [13] - JVIMUL - - - Resource pressure per iteration: - [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] - - - - 2.00 1.00 2.00 1.00 - - - - - - - - - Resource pressure by instruction: - [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Instructions: - - - - - 1.00 - 1.00 - - - - - - - vmulps %xmm0, %xmm1, %xmm2 - - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm2, %xmm2, %xmm3 - - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm3, %xmm3, %xmm4 - -According to this report, the dot-product kernel has been executed 300 times, -for a total of 900 simulated instructions. The total number of simulated micro -opcodes (uOps) is also 900. - -The report is structured in three main sections. The first section collects a -few performance numbers; the goal of this section is to give a very quick -overview of the performance throughput. Important performance indicators are -**IPC**, **uOps Per Cycle**, and **Block RThroughput** (Block Reciprocal -Throughput). - -IPC is computed dividing the total number of simulated instructions by the total -number of cycles. In the absence of loop-carried data dependencies, the -observed IPC tends to a theoretical maximum which can be computed by dividing -the number of instructions of a single iteration by the *Block RThroughput*. - -Field 'uOps Per Cycle' is computed dividing the total number of simulated micro -opcodes by the total number of cycles. A delta between Dispatch Width and this -field is an indicator of a performance issue. In the absence of loop-carried -data dependencies, the observed 'uOps Per Cycle' should tend to a theoretical -maximum throughput which can be computed by dividing the number of uOps of a -single iteration by the *Block RThroughput*. - -Field *uOps Per Cycle* is bounded from above by the dispatch width. That is -because the dispatch width limits the maximum size of a dispatch group. Both IPC -and 'uOps Per Cycle' are limited by the amount of hardware parallelism. The -availability of hardware resources affects the resource pressure distribution, -and it limits the number of instructions that can be executed in parallel every -cycle. A delta between Dispatch Width and the theoretical maximum uOps per -Cycle (computed by dividing the number of uOps of a single iteration by the -*Block RTrhoughput*) is an indicator of a performance bottleneck caused by the -lack of hardware resources. -In general, the lower the Block RThroughput, the better. - -In this example, ``uOps per iteration/Block RThroughput`` is 1.50. Since there -are no loop-carried dependencies, the observed *uOps Per Cycle* is expected to -approach 1.50 when the number of iterations tends to infinity. The delta between -the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is -an indicator of a performance bottleneck caused by the lack of hardware -resources, and the *Resource pressure view* can help to identify the problematic -resource usage. - -The second section of the report shows the latency and reciprocal -throughput of every instruction in the sequence. That section also reports -extra information related to the number of micro opcodes, and opcode properties -(i.e., 'MayLoad', 'MayStore', and 'HasSideEffects'). - -The third section is the *Resource pressure view*. This view reports -the average number of resource cycles consumed every iteration by instructions -for every processor resource unit available on the target. Information is -structured in two tables. The first table reports the number of resource cycles -spent on average every iteration. The second table correlates the resource -cycles to the machine instruction in the sequence. For example, every iteration -of the instruction vmulps always executes on resource unit [6] -(JFPU1 - floating point pipeline #1), consuming an average of 1 resource cycle -per iteration. Note that on AMD Jaguar, vector floating-point multiply can -only be issued to pipeline JFPU1, while horizontal floating-point additions can -only be issued to pipeline JFPU0. - -The resource pressure view helps with identifying bottlenecks caused by high -usage of specific hardware resources. Situations with resource pressure mainly -concentrated on a few resources should, in general, be avoided. Ideally, -pressure should be uniformly distributed between multiple resources. - -Timeline View -^^^^^^^^^^^^^ -The timeline view produces a detailed report of each instruction's state -transitions through an instruction pipeline. This view is enabled by the -command line option ``-timeline``. As instructions transition through the -various stages of the pipeline, their states are depicted in the view report. -These states are represented by the following characters: - -* D : Instruction dispatched. -* e : Instruction executing. -* E : Instruction executed. -* R : Instruction retired. -* = : Instruction already dispatched, waiting to be executed. -* \- : Instruction executed, waiting to be retired. - -Below is the timeline view for a subset of the dot-product example located in -``test/tools/llvm-mca/X86/BtVer2/dot-product.s`` and processed by -:program:`llvm-mca` using the following command: - -.. code-block:: bash - - $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=3 -timeline dot-product.s - -.. code-block:: none - - Timeline view: - 012345 - Index 0123456789 - - [0,0] DeeER. . . vmulps %xmm0, %xmm1, %xmm2 - [0,1] D==eeeER . . vhaddps %xmm2, %xmm2, %xmm3 - [0,2] .D====eeeER . vhaddps %xmm3, %xmm3, %xmm4 - [1,0] .DeeE-----R . vmulps %xmm0, %xmm1, %xmm2 - [1,1] . D=eeeE---R . vhaddps %xmm2, %xmm2, %xmm3 - [1,2] . D====eeeER . vhaddps %xmm3, %xmm3, %xmm4 - [2,0] . DeeE-----R . vmulps %xmm0, %xmm1, %xmm2 - [2,1] . D====eeeER . vhaddps %xmm2, %xmm2, %xmm3 - [2,2] . D======eeeER vhaddps %xmm3, %xmm3, %xmm4 - - - Average Wait times (based on the timeline view): - [0]: Executions - [1]: Average time spent waiting in a scheduler's queue - [2]: Average time spent waiting in a scheduler's queue while ready - [3]: Average time elapsed from WB until retire stage - - [0] [1] [2] [3] - 0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2 - 1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3 - 2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4 - -The timeline view is interesting because it shows instruction state changes -during execution. It also gives an idea of how the tool processes instructions -executed on the target, and how their timing information might be calculated. - -The timeline view is structured in two tables. The first table shows -instructions changing state over time (measured in cycles); the second table -(named *Average Wait times*) reports useful timing statistics, which should -help diagnose performance bottlenecks caused by long data dependencies and -sub-optimal usage of hardware resources. - -An instruction in the timeline view is identified by a pair of indices, where -the first index identifies an iteration, and the second index is the -instruction index (i.e., where it appears in the code sequence). Since this -example was generated using 3 iterations: ``-iterations=3``, the iteration -indices range from 0-2 inclusively. - -Excluding the first and last column, the remaining columns are in cycles. -Cycles are numbered sequentially starting from 0. - -From the example output above, we know the following: - -* Instruction [1,0] was dispatched at cycle 1. -* Instruction [1,0] started executing at cycle 2. -* Instruction [1,0] reached the write back stage at cycle 4. -* Instruction [1,0] was retired at cycle 10. - -Instruction [1,0] (i.e., vmulps from iteration #1) does not have to wait in the -scheduler's queue for the operands to become available. By the time vmulps is -dispatched, operands are already available, and pipeline JFPU1 is ready to -serve another instruction. So the instruction can be immediately issued on the -JFPU1 pipeline. That is demonstrated by the fact that the instruction only -spent 1cy in the scheduler's queue. - -There is a gap of 5 cycles between the write-back stage and the retire event. -That is because instructions must retire in program order, so [1,0] has to wait -for [0,2] to be retired first (i.e., it has to wait until cycle 10). - -In the example, all instructions are in a RAW (Read After Write) dependency -chain. Register %xmm2 written by vmulps is immediately used by the first -vhaddps, and register %xmm3 written by the first vhaddps is used by the second -vhaddps. Long data dependencies negatively impact the ILP (Instruction Level -Parallelism). - -In the dot-product example, there are anti-dependencies introduced by -instructions from different iterations. However, those dependencies can be -removed at register renaming stage (at the cost of allocating register aliases, -and therefore consuming physical registers). - -Table *Average Wait times* helps diagnose performance issues that are caused by -the presence of long latency instructions and potentially long data dependencies -which may limit the ILP. Note that :program:`llvm-mca`, by default, assumes at -least 1cy between the dispatch event and the issue event. - -When the performance is limited by data dependencies and/or long latency -instructions, the number of cycles spent while in the *ready* state is expected -to be very small when compared with the total number of cycles spent in the -scheduler's queue. The difference between the two counters is a good indicator -of how large of an impact data dependencies had on the execution of the -instructions. When performance is mostly limited by the lack of hardware -resources, the delta between the two counters is small. However, the number of -cycles spent in the queue tends to be larger (i.e., more than 1-3cy), -especially when compared to other low latency instructions. - -Extra Statistics to Further Diagnose Performance Issues -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``-all-stats`` command line option enables extra statistics and performance -counters for the dispatch logic, the reorder buffer, the retire control unit, -and the register file. - -Below is an example of ``-all-stats`` output generated by :program:`llvm-mca` -for 300 iterations of the dot-product example discussed in the previous -sections. - -.. code-block:: none - - Dynamic Dispatch Stall Cycles: - RAT - Register unavailable: 0 - RCU - Retire tokens unavailable: 0 - SCHEDQ - Scheduler full: 272 (44.6%) - LQ - Load queue full: 0 - SQ - Store queue full: 0 - GROUP - Static restrictions on the dispatch group: 0 - - - Dispatch Logic - number of cycles where we saw N micro opcodes dispatched: - [# dispatched], [# cycles] - 0, 24 (3.9%) - 1, 272 (44.6%) - 2, 314 (51.5%) - - - Schedulers - number of cycles where we saw N instructions issued: - [# issued], [# cycles] - 0, 7 (1.1%) - 1, 306 (50.2%) - 2, 297 (48.7%) - - Scheduler's queue usage: - [1] Resource name. - [2] Average number of used buffer entries. - [3] Maximum number of used buffer entries. - [4] Total number of buffer entries. - - [1] [2] [3] [4] - JALU01 0 0 20 - JFPU01 17 18 18 - JLSAGU 0 0 12 - - - Retire Control Unit - number of cycles where we saw N instructions retired: - [# retired], [# cycles] - 0, 109 (17.9%) - 1, 102 (16.7%) - 2, 399 (65.4%) - - Total ROB Entries: 64 - Max Used ROB Entries: 35 ( 54.7% ) - Average Used ROB Entries per cy: 32 ( 50.0% ) - - - Register File statistics: - Total number of mappings created: 900 - Max number of mappings used: 35 - - * Register File #1 -- JFpuPRF: - Number of physical registers: 72 - Total number of mappings created: 900 - Max number of mappings used: 35 - - * Register File #2 -- JIntegerPRF: - Number of physical registers: 64 - Total number of mappings created: 0 - Max number of mappings used: 0 - -If we look at the *Dynamic Dispatch Stall Cycles* table, we see the counter for -SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch -logic is unable to dispatch a full group because the scheduler's queue is full. - -Looking at the *Dispatch Logic* table, we see that the pipeline was only able to -dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to -one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The -dispatch statistics are displayed by either using the command option -``-all-stats`` or ``-dispatch-stats``. - -The next table, *Schedulers*, presents a histogram displaying a count, -representing the number of instructions issued on some number of cycles. In -this case, of the 610 simulated cycles, single instructions were issued 306 -times (50.2%) and there were 7 cycles where no instructions were issued. - -The *Scheduler's queue usage* table shows that the average and maximum number of -buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01 -reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements -three schedulers: - -* JALU01 - A scheduler for ALU instructions. -* JFPU01 - A scheduler floating point operations. -* JLSAGU - A scheduler for address generation. - -The dot-product is a kernel of three floating point instructions (a vector -multiply followed by two horizontal adds). That explains why only the floating -point scheduler appears to be used. - -A full scheduler queue is either caused by data dependency chains or by a -sub-optimal usage of hardware resources. Sometimes, resource pressure can be -mitigated by rewriting the kernel using different instructions that consume -different scheduler resources. Schedulers with a small queue are less resilient -to bottlenecks caused by the presence of long data dependencies. The scheduler -statistics are displayed by using the command option ``-all-stats`` or -``-scheduler-stats``. - -The next table, *Retire Control Unit*, presents a histogram displaying a count, -representing the number of instructions retired on some number of cycles. In -this case, of the 610 simulated cycles, two instructions were retired during the -same cycle 399 times (65.4%) and there were 109 cycles where no instructions -were retired. The retire statistics are displayed by using the command option -``-all-stats`` or ``-retire-stats``. - -The last table presented is *Register File statistics*. Each physical register -file (PRF) used by the pipeline is presented in this table. In the case of AMD -Jaguar, there are two register files, one for floating-point registers (JFpuPRF) -and one for integer registers (JIntegerPRF). The table shows that of the 900 -instructions processed, there were 900 mappings created. Since this dot-product -example utilized only floating point registers, the JFPuPRF was responsible for -creating the 900 mappings. However, we see that the pipeline only used a -maximum of 35 of 72 available register slots at any given time. We can conclude -that the floating point PRF was the only register file used for the example, and -that it was never resource constrained. The register file statistics are -displayed by using the command option ``-all-stats`` or -``-register-file-stats``. - -In this example, we can conclude that the IPC is mostly limited by data -dependencies, and not by resource pressure. - -Instruction Flow -^^^^^^^^^^^^^^^^ -This section describes the instruction flow through the default pipeline of -:program:`llvm-mca`, as well as the functional units involved in the process. - -The default pipeline implements the following sequence of stages used to -process instructions. - -* Dispatch (Instruction is dispatched to the schedulers). -* Issue (Instruction is issued to the processor pipelines). -* Write Back (Instruction is executed, and results are written back). -* Retire (Instruction is retired; writes are architecturally committed). - -The default pipeline only models the out-of-order portion of a processor. -Therefore, the instruction fetch and decode stages are not modeled. Performance -bottlenecks in the frontend are not diagnosed. :program:`llvm-mca` assumes that -instructions have all been decoded and placed into a queue before the simulation -start. Also, :program:`llvm-mca` does not model branch prediction. - -Instruction Dispatch -"""""""""""""""""""" -During the dispatch stage, instructions are picked in program order from a -queue of already decoded instructions, and dispatched in groups to the -simulated hardware schedulers. - -The size of a dispatch group depends on the availability of the simulated -hardware resources. The processor dispatch width defaults to the value -of the ``IssueWidth`` in LLVM's scheduling model. - -An instruction can be dispatched if: - -* The size of the dispatch group is smaller than processor's dispatch width. -* There are enough entries in the reorder buffer. -* There are enough physical registers to do register renaming. -* The schedulers are not full. - -Scheduling models can optionally specify which register files are available on -the processor. :program:`llvm-mca` uses that information to initialize register -file descriptors. Users can limit the number of physical registers that are -globally available for register renaming by using the command option -``-register-file-size``. A value of zero for this option means *unbounded*. By -knowing how many registers are available for renaming, the tool can predict -dispatch stalls caused by the lack of physical registers. - -The number of reorder buffer entries consumed by an instruction depends on the -number of micro-opcodes specified for that instruction by the target scheduling -model. The reorder buffer is responsible for tracking the progress of -instructions that are "in-flight", and retiring them in program order. The -number of entries in the reorder buffer defaults to the value specified by field -`MicroOpBufferSize` in the target scheduling model. - -Instructions that are dispatched to the schedulers consume scheduler buffer -entries. :program:`llvm-mca` queries the scheduling model to determine the set -of buffered resources consumed by an instruction. Buffered resources are -treated like scheduler resources. - -Instruction Issue -""""""""""""""""" -Each processor scheduler implements a buffer of instructions. An instruction -has to wait in the scheduler's buffer until input register operands become -available. Only at that point, does the instruction becomes eligible for -execution and may be issued (potentially out-of-order) for execution. -Instruction latencies are computed by :program:`llvm-mca` with the help of the -scheduling model. - -:program:`llvm-mca`'s scheduler is designed to simulate multiple processor -schedulers. The scheduler is responsible for tracking data dependencies, and -dynamically selecting which processor resources are consumed by instructions. -It delegates the management of processor resource units and resource groups to a -resource manager. The resource manager is responsible for selecting resource -units that are consumed by instructions. For example, if an instruction -consumes 1cy of a resource group, the resource manager selects one of the -available units from the group; by default, the resource manager uses a -round-robin selector to guarantee that resource usage is uniformly distributed -between all units of a group. - -:program:`llvm-mca`'s scheduler internally groups instructions into three sets: - -* WaitSet: a set of instructions whose operands are not ready. -* ReadySet: a set of instructions ready to execute. -* IssuedSet: a set of instructions executing. - -Depending on the operands availability, instructions that are dispatched to the -scheduler are either placed into the WaitSet or into the ReadySet. - -Every cycle, the scheduler checks if instructions can be moved from the WaitSet -to the ReadySet, and if instructions from the ReadySet can be issued to the -underlying pipelines. The algorithm prioritizes older instructions over younger -instructions. - -Write-Back and Retire Stage -""""""""""""""""""""""""""" -Issued instructions are moved from the ReadySet to the IssuedSet. There, -instructions wait until they reach the write-back stage. At that point, they -get removed from the queue and the retire control unit is notified. - -When instructions are executed, the retire control unit flags the instruction as -"ready to retire." - -Instructions are retired in program order. The register file is notified of the -retirement so that it can free the physical registers that were allocated for -the instruction during the register renaming stage. - -Load/Store Unit and Memory Consistency Model -"""""""""""""""""""""""""""""""""""""""""""" -To simulate an out-of-order execution of memory operations, :program:`llvm-mca` -utilizes a simulated load/store unit (LSUnit) to simulate the speculative -execution of loads and stores. - -Each load (or store) consumes an entry in the load (or store) queue. Users can -specify flags ``-lqueue`` and ``-squeue`` to limit the number of entries in the -load and store queues respectively. The queues are unbounded by default. - -The LSUnit implements a relaxed consistency model for memory loads and stores. -The rules are: - -1. A younger load is allowed to pass an older load only if there are no - intervening stores or barriers between the two loads. -2. A younger load is allowed to pass an older store provided that the load does - not alias with the store. -3. A younger store is not allowed to pass an older store. -4. A younger store is not allowed to pass an older load. - -By default, the LSUnit optimistically assumes that loads do not alias -(`-noalias=true`) store operations. Under this assumption, younger loads are -always allowed to pass older stores. Essentially, the LSUnit does not attempt -to run any alias analysis to predict when loads and stores do not alias with -each other. - -Note that, in the case of write-combining memory, rule 3 could be relaxed to -allow reordering of non-aliasing store operations. That being said, at the -moment, there is no way to further relax the memory model (``-noalias`` is the -only option). Essentially, there is no option to specify a different memory -type (e.g., write-back, write-combining, write-through; etc.) and consequently -to weaken, or strengthen, the memory model. - -Other limitations are: - -* The LSUnit does not know when store-to-load forwarding may occur. -* The LSUnit does not know anything about cache hierarchy and memory types. -* The LSUnit does not know how to identify serializing operations and memory - fences. - -The LSUnit does not attempt to predict if a load or store hits or misses the L1 -cache. It only knows if an instruction "MayLoad" and/or "MayStore." For -loads, the scheduling model provides an "optimistic" load-to-use latency (which -usually matches the load-to-use latency for when there is a hit in the L1D). - -:program:`llvm-mca` does not know about serializing operations or memory-barrier -like instructions. The LSUnit conservatively assumes that an instruction which -has both "MayLoad" and unmodeled side effects behaves like a "soft" -load-barrier. That means, it serializes loads without forcing a flush of the -load queue. Similarly, instructions that "MayStore" and have unmodeled side -effects are treated like store barriers. A full memory barrier is a "MayLoad" -and "MayStore" instruction with unmodeled side effects. This is inaccurate, but -it is the best that we can do at the moment with the current information -available in LLVM. - -A load/store barrier consumes one entry of the load/store queue. A load/store -barrier enforces ordering of loads/stores. A younger load cannot pass a load -barrier. Also, a younger store cannot pass a store barrier. A younger load -has to wait for the memory/load barrier to execute. A load/store barrier is -"executed" when it becomes the oldest entry in the load/store queue(s). That -also means, by construction, all of the older loads/stores have been executed. - -In conclusion, the full set of load/store consistency rules are: - -#. A store may not pass a previous store. -#. A store may not pass a previous load (regardless of ``-noalias``). -#. A store has to wait until an older store barrier is fully executed. -#. A load may pass a previous load. -#. A load may not pass a previous store unless ``-noalias`` is set. -#. A load has to wait until an older load barrier is fully executed. diff --git a/gnu/llvm/docs/CommandGuide/llvm-nm.rst b/gnu/llvm/docs/CommandGuide/llvm-nm.rst deleted file mode 100644 index 2a2f8275ffc..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-nm.rst +++ /dev/null @@ -1,152 +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:: --no-weak, -W - - Don't print any weak symbols in the output. - -.. 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) diff --git a/gnu/llvm/docs/CommandGuide/llvm-objdump.rst b/gnu/llvm/docs/CommandGuide/llvm-objdump.rst deleted file mode 100644 index c3e7c166005..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-objdump.rst +++ /dev/null @@ -1,123 +0,0 @@ -llvm-objdump - LLVM's object file dumper -======================================== - -SYNOPSIS --------- - -:program:`llvm-objdump` [*commands*] [*options*] [*filenames...*] - -DESCRIPTION ------------ -The :program:`llvm-objdump` utility prints the contents of object files and -final linked images named on the command line. If no file name is specified, -:program:`llvm-objdump` will attempt to read from *a.out*. If *-* is used as a -file name, :program:`llvm-objdump` will process a file on its standard input -stream. - -COMMANDS --------- -At least one of the following commands are required, and some commands can be -combined with other commands: - -.. option:: -d, -disassemble - - Display assembler mnemonics for the machine instructions. Disassembles all - text sections found in the input file(s). - -.. option:: -D, -disassemble-all - - Display assembler mnemonics for the machine instructions. Disassembles all - sections found in the input file(s). - -.. option:: -help - - Display usage information and exit. Does not stack with other commands. - -.. option:: -r - - Display the relocation entries in the file. - -.. option:: -s - - Display the content of each section. - -.. option:: -section-headers - - Display summaries of the headers for each section. - -.. option:: -t - - Display the symbol table. - -.. option:: -version - - Display the version of this program. Does not stack with other commands. - -OPTIONS -------- -:program:`llvm-objdump` supports the following options: - -.. option:: -arch=<architecture> - - Specify the architecture to disassemble. see ``-version`` for available - architectures. - -.. option:: -cfg - - Create a CFG for every symbol in the object file and write it to a graphviz - file (Mach-O-only). - -.. option:: -dsym=<string> - - Use .dSYM file for debug info. - -.. option:: -g - - Print line information from debug info if available. - -.. option:: -m, -macho - - Use Mach-O specific object file parser. Commands and other options may behave - differently when used with ``-macho``. - -.. option:: -mattr=<a1,+a2,-a3,...> - - Target specific attributes. - -.. option:: -mc-x86-disable-arith-relaxation - - Disable relaxation of arithmetic instruction for X86. - -.. option:: -stats - - Enable statistics output from program. - -.. option:: -triple=<string> - - Target triple to disassemble for, see ``-version`` for available targets. - -.. option:: -x86-asm-syntax=<style> - - When used with the ``-disassemble`` option, choose style of code to emit from - X86 backend. Supported values are: - - .. option:: att - - AT&T-style assembly - - .. option:: intel - - Intel-style assembly - - - The default disassembly style is **att**. - -BUGS ----- - -To report bugs, please visit <http://llvm.org/bugs/>. - -SEE ALSO --------- - -:manpage:`llvm-nm(1)` diff --git a/gnu/llvm/docs/CommandGuide/llvm-pdbutil.rst b/gnu/llvm/docs/CommandGuide/llvm-pdbutil.rst deleted file mode 100644 index 29d487e0e74..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-pdbutil.rst +++ /dev/null @@ -1,585 +0,0 @@ -llvm-pdbutil - PDB File forensics and diagnostics -================================================= - -.. contents:: - :local: - -Synopsis --------- - -:program:`llvm-pdbutil` [*subcommand*] [*options*] - -Description ------------ - -Display types, symbols, CodeView records, and other information from a -PDB file, as well as manipulate and create PDB files. :program:`llvm-pdbutil` -is normally used by FileCheck-based tests to test LLVM's PDB reading and -writing functionality, but can also be used for general PDB file investigation -and forensics, or as a replacement for cvdump. - -Subcommands ------------ - -:program:`llvm-pdbutil` is separated into several subcommands each tailored to -a different purpose. A brief summary of each command follows, with more detail -in the sections that follow. - - * :ref:`pretty_subcommand` - Dump symbol and type information in a format that
- tries to look as much like the original source code as possible. - * :ref:`dump_subcommand` - Dump low level types and structures from the PDB
- file, including CodeView records, hash tables, PDB streams, etc. - * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,
- types, symbols, etc as raw bytes. - * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
- a valid PDB file that matches that description. - * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
- description of some or all of the file in a way that the PDB can be
- reconstructed. - * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the
- result of merging the two input PDBs. - -.. _pretty_subcommand: - -pretty -~~~~~~ - -.. program:: llvm-pdbutil pretty - -.. important:: - The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
- supported on non-Windows platforms. - -USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file> - -Summary -^^^^^^^^^^^ - -The *pretty* subcommand displays a very high level representation of your
-program's debug info. Since it is built on the Windows DIA SDK which is the
-standard API that Windows tools and debuggers query debug information, it
-presents a more authoritative view of how a debugger is going to interpret your
-debug information than a mode which displays low-level CodeView records. - -Options -^^^^^^^ - -Filtering and Sorting Options -+++++++++++++++++++++++++++++ - -.. note:: - *exclude* filters take priority over *include* filters. So if a filter
- matches both an include and an exclude rule, then it is excluded. - -.. option:: -exclude-compilands=<string> - - When dumping compilands, compiland source-file contributions, or per-compiland
- symbols, this option instructs **llvm-pdbutil** to omit any compilands that
- match the specified regular expression. - -.. option:: -exclude-symbols=<string> - - When dumping global, public, or per-compiland symbols, this option instructs
- **llvm-pdbutil** to omit any symbols that match the specified regular
- expression. - -.. option:: -exclude-types=<string> - - When dumping types, this option instructs **llvm-pdbutil** to omit any types
- that match the specified regular expression. - -.. option:: -include-compilands=<string> - - When dumping compilands, compiland source-file contributions, or per-compiland
- symbols, limit the initial search to only those compilands that match the
- specified regular expression. - -.. option:: -include-symbols=<string> - - When dumping global, public, or per-compiland symbols, limit the initial
- search to only those symbols that match the specified regular expression. - -.. option:: -include-types=<string> - - When dumping types, limit the initial search to only those types that match
- the specified regular expression. - -.. option:: -min-class-padding=<uint> - - Only display types that have at least the specified amount of alignment
- padding, accounting for padding in base classes and aggregate field members. - -.. option:: -min-class-padding-imm=<uint> - - Only display types that have at least the specified amount of alignment
- padding, ignoring padding in base classes and aggregate field members. - -.. option:: -min-type-size=<uint> - - Only display types T where sizeof(T) is greater than or equal to the specified
- amount. - -.. option:: -no-compiler-generated - - Don't show compiler generated types and symbols - -.. option:: -no-enum-definitions - - When dumping an enum, don't show the full enum (e.g. the individual enumerator
- values). - -.. option:: -no-system-libs - - Don't show symbols from system libraries - -Symbol Type Options -+++++++++++++++++++ -.. option:: -all - - Implies all other options in this category. - -.. option:: -class-definitions=<format> - - Displays class definitions in the specified format. - - .. code-block:: text - - =all - Display all class members including data, constants, typedefs, functions, etc (default) - =layout - Only display members that contribute to class size. - =none - Don't display class definitions (e.g. only display the name and base list) - -.. option:: -class-order - - Displays classes in the specified order. - - .. code-block:: text - - =none - Undefined / no particular sort order (default) - =name - Sort classes by name - =size - Sort classes by size - =padding - Sort classes by amount of padding - =padding-pct - Sort classes by percentage of space consumed by padding - =padding-imm - Sort classes by amount of immediate padding - =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding - -.. option:: -class-recurse-depth=<uint> - - When dumping class definitions, stop after recursing the specified number of times. The - default is 0, which is no limit. - -.. option:: -classes - - Display classes - -.. option:: -compilands - - Display compilands (e.g. object files) - -.. option:: -enums - - Display enums - -.. option:: -externals - - Dump external (e.g. exported) symbols - -.. option:: -globals - - Dump global symbols - -.. option:: -lines - - Dump the mappings between source lines and code addresses. - -.. option:: -module-syms - - Display symbols (variables, functions, etc) for each compiland - -.. option:: -sym-types=<types> - - Type of symbols to dump when -globals, -externals, or -module-syms is - specified. (default all) - - .. code-block:: text - - =thunks - Display thunk symbols - =data - Display data symbols - =funcs - Display function symbols - =all - Display all symbols (default) - -.. option:: -symbol-order=<order> - - For symbols dumped via the -module-syms, -globals, or -externals options, sort - the results in specified order. - - .. code-block:: text - - =none - Undefined / no particular sort order - =name - Sort symbols by name - =size - Sort symbols by size - -.. option:: -typedefs - - Display typedef types - -.. option:: -types - - Display all types (implies -classes, -enums, -typedefs) - -Other Options -+++++++++++++ - -.. option:: -color-output - - Force color output on or off. By default, color if used if outputting to a
- terminal. - -.. option:: -load-address=<uint> - - When displaying relative virtual addresses, assume the process is loaded at the
- given address and display what would be the absolute address. - -.. _dump_subcommand: - -dump -~~~~ - -USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file> - -.. program:: llvm-pdbutil dump - -Summary -^^^^^^^^^^^ - -The **dump** subcommand displays low level information about the structure of a
-PDB file. It is used heavily by LLVM's testing infrastructure, but can also be
-used for PDB forensics. It serves a role similar to that of Microsoft's
-`cvdump` tool.
-
-.. note::
- The **dump** subcommand exposes internal details of the file format. As
- such, the reader should be familiar with :doc:`/PDB/index` before using this
- command. - -Options -^^^^^^^ - -MSF Container Options -+++++++++++++++++++++ - -.. option:: -streams - - dump a summary of all of the streams in the PDB file. - -.. option:: -stream-blocks - - In conjunction with :option:`-streams`, add information to the output about - what blocks the specified stream occupies. - -.. option:: -summary - - Dump MSF and PDB header information. - -Module & File Options -+++++++++++++++++++++ - -.. option:: -modi=<uint> - - For all options that dump information from each module/compiland, limit to - the specified module. - -.. option:: -files - - Dump the source files that contribute to each displayed module. - -.. option:: -il - - Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection) - -.. option:: -l - - Dump line information (DEBUG_S_LINES CodeView subsection) - -.. option:: -modules - - Dump compiland information - -.. option:: -xme - - Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection) - -.. option:: -xmi - - Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection) - -Symbol Options -++++++++++++++ - -.. option:: -globals - - dump global symbol records - -.. option:: -global-extras - - dump additional information about the globals, such as hash buckets and hash - values. - -.. option:: -publics - - dump public symbol records - -.. option:: -public-extras - - dump additional information about the publics, such as hash buckets and hash - values. - -.. option:: -symbols - - dump symbols (functions, variables, etc) for each module dumped. - -.. option:: -sym-data - - For each symbol record dumped as a result of the :option:`-symbols` option, - display the full bytes of the record in binary as well. - -Type Record Options -+++++++++++++++++++ - -.. option:: -types - - Dump CodeView type records from TPI stream - -.. option:: -type-extras - - Dump additional information from the TPI stream, such as hashes and the type - index offsets array. - -.. option:: -type-data - - For each type record dumped, display the full bytes of the record in binary as - well. - -.. option:: -type-index=<uint> - - Only dump types with the specified type index. - -.. option:: -ids - - Dump CodeView type records from IPI stream. - -.. option:: -id-extras - - Dump additional information from the IPI stream, such as hashes and the type - index offsets array. - -.. option:: -id-data - - For each ID record dumped, display the full bytes of the record in binary as - well. - -.. option:: -id-index=<uint> - - only dump ID records with the specified hexadecimal type index. - -.. option:: -dependents - - When used in conjunction with :option:`-type-index` or :option:`-id-index`, - dumps the entire dependency graph for the specified index instead of just the - single record with the specified index. For example, if type index 0x4000 is - a function whose return type has index 0x3000, and you specify
- `-dependents=0x4000`, then this would dump both records (as well as any other
- dependents in the tree). - -Miscellaneous Options -+++++++++++++++++++++ - -.. option:: -all - - Implies most other options. - -.. option:: -section-contribs - - Dump section contributions. - -.. option:: -section-headers - - Dump image section headers. - -.. option:: -section-map - - Dump section map. - -.. option:: -string-table - - Dump PDB string table. - -.. _bytes_subcommand: - -bytes -~~~~~ - -USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file> - -.. program:: llvm-pdbutil bytes - -Summary -^^^^^^^ - -Like the **dump** subcommand, the **bytes** subcommand displays low level -information about the structure of a PDB file, but it is used for even deeper -forensics. The **bytes** subcommand finds various structures in a PDB file -based on the command line options specified, and dumps them in hex. Someone -working on support for emitting PDBs would use this heavily, for example, to -compare one PDB against another PDB to ensure byte-for-byte compatibility. It -is not enough to simply compare the bytes of an entire file, or an entire stream -because it's perfectly fine for the same structure to exist at different -locations in two different PDBs, and "finding" the structure is half the battle. - -Options -^^^^^^^ - -MSF File Options -++++++++++++++++ - -.. option:: -block-range=<start[-end]> - - Dump binary data from specified range of MSF file blocks. - -.. option:: -byte-range=<start[-end]> - - Dump binary data from specified range of bytes in the file. - -.. option:: -fpm - - Dump the MSF free page map. - -.. option:: -stream-data=<string> - - Dump binary data from the specified streams. Format is SN[:Start][@Size]. - For example, `-stream-data=7:3@12` dumps 12 bytes from stream 7, starting - at offset 3 in the stream. - -PDB Stream Options -++++++++++++++++++ - -.. option:: -name-map - - Dump bytes of PDB Name Map - -DBI Stream Options -++++++++++++++++++ - -.. option:: -ec - - Dump the edit and continue map substream of the DBI stream. - -.. option:: -files - - Dump the file info substream of the DBI stream. - -.. option:: -modi - - Dump the modi substream of the DBI stream. - -.. option:: -sc - - Dump section contributions substream of the DBI stream. - -.. option:: -sm - - Dump the section map from the DBI stream. - -.. option:: -type-server - - Dump the type server map from the DBI stream. - -Module Options -++++++++++++++ - -.. option:: -mod=<uint> - - Limit all options in this category to the specified module index. By default, - options in this category will dump bytes from all modules. - -.. option:: -chunks - - Dump the bytes of each module's C13 debug subsection. - -.. option:: -split-chunks - - When specified with :option:`-chunks`, split the C13 debug subsection into a - separate chunk for each subsection type, and dump them separately. - -.. option:: -syms - - Dump the symbol record substream from each module. - -Type Record Options -+++++++++++++++++++ - -.. option:: -id=<uint> - - Dump the record from the IPI stream with the given type index. - -.. option:: -type=<uint> - - Dump the record from the TPI stream with the given type index. - -.. _pdb2yaml_subcommand: - -pdb2yaml -~~~~~~~~ - -USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file> - -.. program:: llvm-pdbutil pdb2yaml - -Summary -^^^^^^^ - -Options -^^^^^^^ - -.. _yaml2pdb_subcommand: - -yaml2pdb -~~~~~~~~ - -USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file> - -.. program:: llvm-pdbutil yaml2pdb - -Summary -^^^^^^^ - -Generate a PDB file from a YAML description. The YAML syntax is not described -here. Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and -examine the output for an example starting point. - -Options -^^^^^^^ - -.. option:: -pdb=<file-name> - -Write the resulting PDB to the specified file. - -.. _merge_subcommand: - -merge -~~~~~ - -USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2> - -.. program:: llvm-pdbutil merge - -Summary -^^^^^^^ - -Merge two PDB files into a single file. - -Options -^^^^^^^ - -.. option:: -pdb=<file-name> - -Write the resulting PDB to the specified file. diff --git a/gnu/llvm/docs/CommandGuide/llvm-profdata.rst b/gnu/llvm/docs/CommandGuide/llvm-profdata.rst deleted file mode 100644 index f66fb499697..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-profdata.rst +++ /dev/null @@ -1,233 +0,0 @@ -llvm-profdata - Profile data tool -================================= - -SYNOPSIS --------- - -:program:`llvm-profdata` *command* [*args...*] - -DESCRIPTION ------------ - -The :program:`llvm-profdata` tool is a small utility for working with profile -data files. - -COMMANDS --------- - -* :ref:`merge <profdata-merge>` -* :ref:`show <profdata-show>` - -.. program:: llvm-profdata merge - -.. _profdata-merge: - -MERGE ------ - -SYNOPSIS -^^^^^^^^ - -:program:`llvm-profdata merge` [*options*] [*filename...*] - -DESCRIPTION -^^^^^^^^^^^ - -:program:`llvm-profdata merge` takes several profile data files -generated by PGO instrumentation and merges them together into a single -indexed profile data file. - -By default profile data is merged without modification. This means that the -relative importance of each input file is proportional to the number of samples -or counts it contains. In general, the input from a longer training run will be -interpreted as relatively more important than a shorter run. Depending on the -nature of the training runs it may be useful to adjust the weight given to each -input file by using the ``-weighted-input`` option. - -Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional -arguments are processed once for each time they are seen. - - -OPTIONS -^^^^^^^ - -.. option:: -help - - Print a summary of command line options. - -.. option:: -output=output, -o=output - - Specify the output file name. *Output* cannot be ``-`` as the resulting - indexed profile data can't be written to standard output. - -.. option:: -weighted-input=weight,filename - - Specify an input file name along with a weight. The profile counts of the - supplied ``filename`` will be scaled (multiplied) by the supplied - ``weight``, where where ``weight`` is a decimal integer >= 1. - Input files specified without using this option are assigned a default - weight of 1. Examples are shown below. - -.. option:: -input-files=path, -f=path - - Specify a file which contains a list of files to merge. The entries in this - file are newline-separated. Lines starting with '#' are skipped. Entries may - be of the form <filename> or <weight>,<filename>. - -.. option:: -remapping-file=path, -r=path - - Specify a file which contains a remapping from symbol names in the input - profile to the symbol names that should be used in the output profile. The - file should consist of lines of the form ``<input-symbol> <output-symbol>``. - Blank lines and lines starting with ``#`` are skipped. - - The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol - remapping file. - -.. option:: -instr (default) - - Specify that the input profile is an instrumentation-based profile. - -.. option:: -sample - - Specify that the input profile is a sample-based profile. - - The format of the generated file can be generated in one of three ways: - - .. option:: -binary (default) - - Emit the profile using a binary encoding. For instrumentation-based profile - the output format is the indexed binary format. - - .. option:: -text - - Emit the profile in text mode. This option can also be used with both - sample-based and instrumentation-based profile. When this option is used - the profile will be dumped in the text format that is parsable by the profile - reader. - - .. option:: -gcc - - Emit the profile using GCC's gcov format (Not yet supported). - -.. option:: -sparse[=true|false] - - Do not emit function records with 0 execution count. Can only be used in - conjunction with -instr. Defaults to false, since it can inhibit compiler - optimization during PGO. - -.. option:: -num-threads=N, -j=N - - Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects - an appropriate number of threads to use. This is the default. - -EXAMPLES -^^^^^^^^ -Basic Usage -+++++++++++ -Merge three profiles: - -:: - - llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata - -Weighted Input -++++++++++++++ -The input file `foo.profdata` is especially important, multiply its counts by 10: - -:: - - llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata - -Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation): - -:: - - llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata - -.. program:: llvm-profdata show - -.. _profdata-show: - -SHOW ----- - -SYNOPSIS -^^^^^^^^ - -:program:`llvm-profdata show` [*options*] [*filename*] - -DESCRIPTION -^^^^^^^^^^^ - -:program:`llvm-profdata show` takes a profile data file and displays the -information about the profile counters for this file and -for any of the specified function(s). - -If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its -input from standard input. - -OPTIONS -^^^^^^^ - -.. option:: -all-functions - - Print details for every function. - -.. option:: -counts - - Print the counter values for the displayed functions. - -.. option:: -function=string - - Print details for a function if the function's name contains the given string. - -.. option:: -help - - Print a summary of command line options. - -.. option:: -output=output, -o=output - - Specify the output file name. If *output* is ``-`` or it isn't specified, - then the output is sent to standard output. - -.. option:: -instr (default) - - Specify that the input profile is an instrumentation-based profile. - -.. option:: -text - - Instruct the profile dumper to show profile counts in the text format of the - instrumentation-based profile data representation. By default, the profile - information is dumped in a more human readable form (also in text) with - annotations. - -.. option:: -topn=n - - Instruct the profile dumper to show the top ``n`` functions with the - hottest basic blocks in the summary section. By default, the topn functions - are not dumped. - -.. option:: -sample - - Specify that the input profile is a sample-based profile. - -.. option:: -memop-sizes - - Show the profiled sizes of the memory intrinsic calls for shown functions. - -.. option:: -value-cutoff=n - - Show only those functions whose max count values are greater or equal to ``n``. - By default, the value-cutoff is set to 0. - -.. option:: -list-below-cutoff - - Only output names of functions whose max count value are below the cutoff - value. - -EXIT STATUS ------------ - -:program:`llvm-profdata` returns 1 if the command is omitted or is invalid, -if it cannot read input files, or if there is a mismatch between their data. diff --git a/gnu/llvm/docs/CommandGuide/llvm-readobj.rst b/gnu/llvm/docs/CommandGuide/llvm-readobj.rst deleted file mode 100644 index 417fcd05c8a..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-readobj.rst +++ /dev/null @@ -1,90 +0,0 @@ -llvm-readobj - LLVM Object Reader -================================= - -SYNOPSIS --------- - -:program:`llvm-readobj` [*options*] [*input...*] - -DESCRIPTION ------------ - -The :program:`llvm-readobj` tool displays low-level format-specific information -about one or more object files. The tool and its output is primarily designed -for use in FileCheck-based tests. - -OPTIONS -------- - -If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard -input. Otherwise, it will read from the specified ``filenames``. - -.. option:: -help - - Print a summary of command line options. - -.. option:: -version - - Display the version of this program - -.. option:: -file-headers, -h - - Display file headers. - -.. option:: -sections, -s - - Display all sections. - -.. option:: -section-data, -sd - - When used with ``-sections``, display section data for each section shown. - -.. option:: -section-relocations, -sr - - When used with ``-sections``, display relocations for each section shown. - -.. option:: -section-symbols, -st - - When used with ``-sections``, display symbols for each section shown. - -.. option:: -relocations, -r - - Display the relocation entries in the file. - -.. option:: -symbols, -t - - Display the symbol table. - -.. option:: -dyn-symbols - - Display the dynamic symbol table (only for ELF object files). - -.. option:: -unwind, -u - - Display unwind information. - -.. option:: -expand-relocs - - When used with ``-relocations``, display each relocation in an expanded - multi-line format. - -.. option:: -dynamic-table - - Display the ELF .dynamic section table (only for ELF object files). - -.. option:: -needed-libs - - Display the needed libraries (only for ELF object files). - -.. option:: -program-headers - - Display the ELF program headers (only for ELF object files). - -.. option:: -elf-section-groups, -g - - Display section groups (only for ELF object files). - -EXIT STATUS ------------ - -:program:`llvm-readobj` returns 0. diff --git a/gnu/llvm/docs/CommandGuide/llvm-stress.rst b/gnu/llvm/docs/CommandGuide/llvm-stress.rst deleted file mode 100644 index fb006f562b1..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-stress.rst +++ /dev/null @@ -1,34 +0,0 @@ -llvm-stress - generate random .ll files -======================================= - -SYNOPSIS --------- - -:program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile] - -DESCRIPTION ------------ - -The :program:`llvm-stress` tool is used to generate random ``.ll`` files that -can be used to test different components of LLVM. - -OPTIONS -------- - -.. option:: -o filename - - Specify the output filename. - -.. option:: -size size - - Specify the size of the generated ``.ll`` file. - -.. option:: -seed seed - - Specify the seed to be used for the randomly generated instructions. - -EXIT STATUS ------------ - -:program:`llvm-stress` returns 0. - diff --git a/gnu/llvm/docs/CommandGuide/llvm-symbolizer.rst b/gnu/llvm/docs/CommandGuide/llvm-symbolizer.rst deleted file mode 100644 index 3c7a26e486f..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-symbolizer.rst +++ /dev/null @@ -1,121 +0,0 @@ -llvm-symbolizer - convert addresses into source code locations -============================================================== - -SYNOPSIS --------- - -:program:`llvm-symbolizer` [options] - -DESCRIPTION ------------ - -:program:`llvm-symbolizer` reads object file names and addresses from standard -input and prints corresponding source code locations to standard output. -If object file is specified in command line, :program:`llvm-symbolizer` -processes only addresses from standard input, the rest is output verbatim. -This program uses debug info sections and symbol table in the object files. - -EXAMPLE --------- - -.. code-block:: console - - $ cat addr.txt - a.out 0x4004f4 - /tmp/b.out 0x400528 - /tmp/c.so 0x710 - /tmp/mach_universal_binary:i386 0x1f84 - /tmp/mach_universal_binary:x86_64 0x100000f24 - $ llvm-symbolizer < addr.txt - main - /tmp/a.cc:4 - - f(int, int) - /tmp/b.cc:11 - - h_inlined_into_g - /tmp/header.h:2 - g_inlined_into_f - /tmp/header.h:7 - f_inlined_into_main - /tmp/source.cc:3 - main - /tmp/source.cc:8 - - _main - /tmp/source_i386.cc:8 - - _main - /tmp/source_x86_64.cc:8 - $ cat addr2.txt - 0x4004f4 - 0x401000 - $ llvm-symbolizer -obj=a.out < addr2.txt - main - /tmp/a.cc:4 - - foo(int) - /tmp/a.cc:12 - $cat addr.txt - 0x40054d - $llvm-symbolizer -inlining -print-address -pretty-print -obj=addr.exe < addr.txt - 0x40054d: inc at /tmp/x.c:3:3 - (inlined by) main at /tmp/x.c:9:0 - $llvm-symbolizer -inlining -pretty-print -obj=addr.exe < addr.txt - inc at /tmp/x.c:3:3 - (inlined by) main at /tmp/x.c:9:0 - -OPTIONS -------- - -.. option:: -obj, -exe, -e - - Path to object file to be symbolized. - -.. option:: -functions=[none|short|linkage] - - Specify the way function names are printed (omit function name, - print short function name, or print full linkage name, respectively). - Defaults to ``linkage``. - -.. option:: -use-symbol-table - - Prefer function names stored in symbol table to function names - in debug info sections. Defaults to true. - -.. option:: -demangle, -C - - Print demangled function names. Defaults to true. - -.. option:: -inlining - - If a source code location is in an inlined function, prints all the - inlnied frames. Defaults to true. - -.. option:: -default-arch - - If a binary contains object files for multiple architectures (e.g. it is a - Mach-O universal binary), symbolize the object file for a given architecture. - You can also specify architecture by writing ``binary_name:arch_name`` in the - input (see example above). If architecture is not specified in either way, - address will not be symbolized. Defaults to empty string. - -.. option:: -dsym-hint=<path/to/file.dSYM> - - (Darwin-only flag). If the debug info for a binary isn't present in the default - location, look for the debug info at the .dSYM path provided via the - ``-dsym-hint`` flag. This flag can be used multiple times. - -.. option:: -print-address, -addresses, -a - - Print address before the source code location. Defaults to false. - -.. option:: -pretty-print, -p - - Print human readable output. If ``-inlining`` is specified, enclosing scope is - prefixed by (inlined by). Refer to listed examples. - -EXIT STATUS ------------ - -:program:`llvm-symbolizer` returns 0. Other exit codes imply internal program error. diff --git a/gnu/llvm/docs/CommandGuide/opt.rst b/gnu/llvm/docs/CommandGuide/opt.rst deleted file mode 100644 index 2b2fffa063a..00000000000 --- a/gnu/llvm/docs/CommandGuide/opt.rst +++ /dev/null @@ -1,123 +0,0 @@ -opt - LLVM optimizer -==================== - -SYNOPSIS --------- - -:program:`opt` [*options*] [*filename*] - -DESCRIPTION ------------ - -The :program:`opt` command is the modular LLVM optimizer and analyzer. It -takes LLVM source files as input, runs the specified optimizations or analyses -on it, and then outputs the optimized file or the analysis results. The -function of :program:`opt` depends on whether the `-analyze` option is -given. - -When `-analyze` is specified, :program:`opt` performs various analyses -of the input source. It will usually print the results on standard output, but -in a few cases, it will print output to standard error or generate a file with -the analysis output, which is usually done when the output is meant for another -program. - -While `-analyze` is *not* given, :program:`opt` attempts to produce an -optimized output file. The optimizations available via :program:`opt` depend -upon what libraries were linked into it as well as any additional libraries -that have been loaded with the :option:`-load` option. Use the :option:`-help` -option to determine what optimizations you can use. - -If ``filename`` is omitted from the command line or is "``-``", :program:`opt` -reads its input from standard input. Inputs can be in either the LLVM assembly -language format (``.ll``) or the LLVM bitcode format (``.bc``). - -If an output filename is not specified with the :option:`-o` option, -:program:`opt` writes its output to the standard output. - -OPTIONS -------- - -.. option:: -f - - Enable binary output on terminals. Normally, :program:`opt` will refuse to - write raw bitcode output if the output stream is a terminal. With this option, - :program:`opt` will write raw bitcode regardless of the output device. - -.. option:: -help - - Print a summary of command line options. - -.. option:: -o <filename> - - Specify the output filename. - -.. option:: -S - - Write output in LLVM intermediate language (instead of bitcode). - -.. option:: -{passname} - - :program:`opt` provides the ability to run any of LLVM's optimization or - analysis passes in any order. The :option:`-help` option lists all the passes - available. The order in which the options occur on the command line are the - order in which they are executed (within pass constraints). - -.. option:: -disable-inlining - - This option simply removes the inlining pass from the standard list. - -.. option:: -disable-opt - - This option is only meaningful when `-std-link-opts` is given. It - disables most passes. - -.. option:: -strip-debug - - This option causes opt to strip debug information from the module before - applying other optimizations. It is essentially the same as `-strip` - but it ensures that stripping of debug information is done first. - -.. option:: -verify-each - - This option causes opt to add a verify pass after every pass otherwise - specified on the command line (including `-verify`). This is useful - for cases where it is suspected that a pass is creating an invalid module but - it is not clear which pass is doing it. - -.. option:: -stats - - Print statistics. - -.. option:: -time-passes - - Record the amount of time needed for each pass and print it to standard - error. - -.. option:: -debug - - If this is a debug build, this option will enable debug printouts from passes - which use the ``LLVM_DEBUG()`` macro. See the `LLVM Programmer's Manual - <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information. - -.. option:: -load=<plugin> - - Load the dynamic object ``plugin``. This object should register new - optimization or analysis passes. Once loaded, the object will add new command - line options to enable various optimizations or analyses. To see the new - complete list of optimizations, use the :option:`-help` and :option:`-load` - options together. For example: - - .. code-block:: sh - - opt -load=plugin.so -help - -.. option:: -p - - Print module after each transformation. - -EXIT STATUS ------------ - -If :program:`opt` succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value. - diff --git a/gnu/llvm/docs/CommandGuide/tblgen.rst b/gnu/llvm/docs/CommandGuide/tblgen.rst deleted file mode 100644 index 3105e0c8076..00000000000 --- a/gnu/llvm/docs/CommandGuide/tblgen.rst +++ /dev/null @@ -1,145 +0,0 @@ -tblgen - Target Description To C++ Code Generator -================================================= - -SYNOPSIS --------- - -:program:`tblgen` [*options*] [*filename*] - -DESCRIPTION ------------ - -:program:`tblgen` translates from target description (``.td``) files into C++ -code that can be included in the definition of an LLVM target library. Most -users of LLVM will not need to use this program. It is only for assisting with -writing an LLVM target backend. - -The input and output of :program:`tblgen` is beyond the scope of this short -introduction; please see the :doc:`introduction to TableGen -<../TableGen/index>`. - -The *filename* argument specifies the name of a Target Description (``.td``) -file to read as input. - -OPTIONS -------- - -.. program:: tblgen - -.. option:: -help - - Print a summary of command line options. - -.. option:: -o filename - - Specify the output file name. If ``filename`` is ``-``, then - :program:`tblgen` sends its output to standard output. - -.. option:: -I directory - - Specify where to find other target description files for inclusion. The - ``directory`` value should be a full or partial path to a directory that - contains target description files. - -.. option:: -asmparsernum N - - Make -gen-asm-parser emit assembly writer number ``N``. - -.. option:: -asmwriternum N - - Make -gen-asm-writer emit assembly writer number ``N``. - -.. option:: -class className - - Print the enumeration list for this class. - -.. option:: -print-records - - Print all records to standard output (default). - -.. option:: -dump-json - - Print a JSON representation of all records, suitable for further - automated processing. - -.. option:: -print-enums - - Print enumeration values for a class. - -.. option:: -print-sets - - Print expanded sets for testing DAG exprs. - -.. option:: -gen-emitter - - Generate machine code emitter. - -.. option:: -gen-register-info - - Generate registers and register classes info. - -.. option:: -gen-instr-info - - Generate instruction descriptions. - -.. option:: -gen-asm-writer - - Generate the assembly writer. - -.. option:: -gen-disassembler - - Generate disassembler. - -.. option:: -gen-pseudo-lowering - - Generate pseudo instruction lowering. - -.. option:: -gen-dag-isel - - Generate a DAG (Directed Acycle Graph) instruction selector. - -.. option:: -gen-asm-matcher - - Generate assembly instruction matcher. - -.. option:: -gen-dfa-packetizer - - Generate DFA Packetizer for VLIW targets. - -.. option:: -gen-fast-isel - - Generate a "fast" instruction selector. - -.. option:: -gen-subtarget - - Generate subtarget enumerations. - -.. option:: -gen-intrinsic-enums - - Generate intrinsic enums. - -.. option:: -gen-intrinsic-impl - - Generate intrinsic implementation. - -.. option:: -gen-tgt-intrinsic - - Generate target intrinsic information. - -.. option:: -gen-enhanced-disassembly-info - - Generate enhanced disassembly info. - -.. option:: -gen-exegesis - - Generate llvm-exegesis tables. - -.. option:: -version - - Show the version number of this program. - -EXIT STATUS ------------ - -If :program:`tblgen` succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value. |
