diff options
Diffstat (limited to 'docs/CommandGuide')
| -rw-r--r-- | docs/CommandGuide/FileCheck.rst | 221 | ||||
| -rw-r--r-- | docs/CommandGuide/bugpoint.rst | 84 | ||||
| -rw-r--r-- | docs/CommandGuide/index.rst | 3 | ||||
| -rw-r--r-- | docs/CommandGuide/lit.rst | 428 | ||||
| -rw-r--r-- | docs/CommandGuide/llc.rst | 176 | ||||
| -rw-r--r-- | docs/CommandGuide/lli.rst | 2 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-bcanalyzer.rst | 221 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-cov.rst | 40 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-link.rst | 86 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-stress.rst | 30 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-symbolizer.rst | 65 | ||||
| -rw-r--r-- | docs/CommandGuide/opt.rst | 182 | ||||
| -rw-r--r-- | docs/CommandGuide/tblgen.rst | 139 |
13 files changed, 624 insertions, 1053 deletions
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst index 1d7a462..fce63ba 100644 --- a/docs/CommandGuide/FileCheck.rst +++ b/docs/CommandGuide/FileCheck.rst @@ -1,99 +1,79 @@ FileCheck - Flexible pattern matching file verifier =================================================== - SYNOPSIS -------- - -**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] - +: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. -**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. llc) contains the expected information (for example, a movsd from esp or -whatever is interesting). This is similar to using 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 +The ``match-filename`` file specifies the file that contains the patterns to match. The file to verify is always read from standard input. - OPTIONS ------- - - -**-help** +.. 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 a specific prefix to match. -**--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 **--check-prefix** argument allows you to specify - a specific prefix to match. - - - -**--input-file** *filename* +.. option:: --input-file filename File to check (defaults to stdin). - -**--strict-whitespace** +.. 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 --strict-whitespace argument disables this behavior. - - + The :option:`--strict-whitespace` argument disables this behavior. End-of-line + sequences are canonicalized to UNIX-style '\n' in all modes. -**-version** +.. option:: -version Show the version number of this program. - - - EXIT STATUS ----------- - -If **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. - +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): - +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 @@ -113,32 +93,30 @@ let's look at the rest of the .ll file (after the RUN line): 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. -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 +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. +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. +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 llc. Here's a simple example: - +The FileCheck :option:`-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 @@ -157,21 +135,17 @@ testing different architectural variants with llc. Here's a simple example: ; 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: - +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 @@ -193,22 +167,18 @@ example, something like this works as you'd expect: ; CHECK-NEXT: ret } - -CHECK-NEXT: directives reject the input unless there is exactly one newline -between it an the previous directive. A CHECK-NEXT cannot be the first -directive in a file. - +"``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-NOT:" directive ~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The CHECK-NOT: directive is used to verify that a string doesn't occur +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) { @@ -224,27 +194,22 @@ can be used: ; CHECK: ret i8 } - - FileCheck Pattern Matching Syntax ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The CHECK: and CHECK-NOT: directives both 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}}**. 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: - +The "``CHECK:``" and "``CHECK-NOT:``" directives both 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}}``. 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. @@ -252,19 +217,16 @@ 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. - +``{{[{][{]}}`` 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, FileCheck -allows named variables to be defined and substituted into patterns. Here is a -simple example: - +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 @@ -272,19 +234,46 @@ simple example: ; 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. + +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 -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". 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. - -FileCheck variables can be defined multiple times, and uses always get the -latest value. Note that variables are all read at the start of a "CHECK" line -and are all defined at the end. This means that if you have something like -"**CHECK: [[XYZ:.\\*]]x[[XYZ]]**", the check line will read the previous -value of the XYZ variable and define a new one after the match is performed. If -you need to do something like this you can probably take advantage of the fact -that FileCheck is not actually line-oriented when it matches, this allows you to -define two separate CHECK lines that match on the same line. diff --git a/docs/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst index c1b3b6e..e4663e5 100644 --- a/docs/CommandGuide/bugpoint.rst +++ b/docs/CommandGuide/bugpoint.rst @@ -1,19 +1,15 @@ 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 @@ -22,82 +18,61 @@ For more information on the design and inner workings of **bugpoint**, as well a advice for using bugpoint, see *llvm/docs/Bugpoint.html* 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: - + 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:: perl + .. 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. - - + 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 + 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:: perl + .. 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.) - - + 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 @@ -105,36 +80,26 @@ OPTIONS 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 @@ -143,20 +108,15 @@ OPTIONS optimizations, use the **-help** and **--load** options together; for example: - .. code-block:: perl + .. 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 @@ -164,14 +124,10 @@ OPTIONS do not use this option, **bugpoint** will attempt to generate a reference output by compiling the program with the "safe" backend and running it. - - **--profile-info-file** *filename* Profile file loaded by **--profile-loader**. - - **--run-{int,jit,llc,custom}** Whenever the test program is compiled, **bugpoint** should generate code for it @@ -179,8 +135,6 @@ OPTIONS 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 @@ -192,16 +146,12 @@ OPTIONS 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** @@ -210,38 +160,28 @@ OPTIONS 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. - - - 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/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst index 73a4835..ac8a944 100644 --- a/docs/CommandGuide/index.rst +++ b/docs/CommandGuide/index.rst @@ -1,5 +1,3 @@ -.. _commands: - LLVM Command Guide ------------------ @@ -30,6 +28,7 @@ Basic Commands llvm-diff llvm-cov llvm-stress + llvm-symbolizer Debugging Tools ~~~~~~~~~~~~~~~ diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst index 9e96cd2..40c7646 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -1,351 +1,278 @@ lit - LLVM Integrated Tester ============================ - SYNOPSIS -------- - -**lit** [*options*] [*tests*] - +: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. -**lit** is a portable tool for executing LLVM and Clang style test suites, -summarizing their results, and providing indication of failures. **lit** is -designed to be a lightweight testing tool with as simple a user interface as -possible. - -**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 "TEST DISCOVERY"). +: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 **lit** will print summary information on the number of tests -which passed or failed (see "TEST STATUS RESULTS"). The **lit** program will -execute with a non-zero exit code if any tests fail. - -By default **lit** will use a succinct progress display and will only print -summary information for test failures. See "OUTPUT OPTIONS" for options -controlling the **lit** progress display and output. +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. -**lit** also includes a number of options for controlling how tests are executed -(specific features may depend on the particular test format). See "EXECUTION -OPTIONS" for more information. +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. -Finally, **lit** also supports additional options for only running a subset of -the options specified on the command line, see "SELECTION OPTIONS" for -more information. +: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. -Users interested in the **lit** architecture or designing a **lit** testing -implementation should see "LIT INFRASTRUCTURE" +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. -**-h**, **--help** - - Show the **lit** help message. - - - -**-j** *N*, **--threads**\ =\ *N* - - Run *N* tests in parallel. By default, this is automatically chosen to match - the number of detected available CPUs. - - +.. option:: -j N, --threads=N -**--config-prefix**\ =\ *NAME* + Run ``N`` tests in parallel. By default, this is automatically chosen to + match the number of detected available CPUs. - Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites, - instead of *lit.cfg* and *lit.site.cfg*. +.. 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:: --param NAME, --param NAME=VALUE -**--param** *NAME*, **--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 + 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 -------------- - - -**-q**, **--quiet** +.. option:: -q, --quiet Suppress any output except for test failures. - - -**-s**, **--succinct** +.. option:: -s, --succinct Show less output, for example don't show information on tests that pass. - - -**-v**, **--verbose** +.. option:: -v, --verbose Show more information on test failures, for example the entire test output instead of just the test result. - - -**--no-progress-bar** +.. option:: --no-progress-bar Do not use curses based progress bar. - - +.. _execution-options: EXECUTION OPTIONS ----------------- +.. option:: --path=PATH + Specify an additional ``PATH`` to use when searching for executables in tests. -**--path**\ =\ *PATH* - - Specify an addition *PATH* to use when searching for executables in tests. - - - -**--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, **lit** will also automatically provide a - "valgrind" feature that can be used to conditionally disable (or expect failure - in) certain tests. - - - -**--vg-arg**\ =\ *ARG* - - When *--vg* is used, specify an additional argument to pass to valgrind itself. - +.. 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. -**--vg-leak** + 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. - When *--vg* is used, enable memory leak checks. When this option is enabled, - **lit** will also automatically provide a "vg_leak" 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. -**--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*. - +.. 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. -**--max-tests**\ =\ *N* - - Run at most *N* tests and then terminate. - - - -**--max-time**\ =\ *N* +.. option:: --max-time=N - Spend at most *N* seconds (approximately) running tests and then terminate. + Spend at most ``N`` seconds (approximately) running tests and then terminate. - - -**--shuffle** +.. option:: --shuffle Run the tests in a random order. - - - ADDITIONAL OPTIONS ------------------ +.. option:: --debug + Run :program:`lit` in debug mode, for debugging configuration issues and + :program:`lit` itself. -**--debug** - - Run **lit** in debug mode, for debugging configuration issues and **lit** itself. - - - -**--show-suites** +.. option:: --show-suites List the discovered test suites as part of the standard output. +.. option:: --repeat=N - -**--no-tcl-as-sh** - - Run Tcl scripts internally (instead of converting to shell scripts). - - - -**--repeat**\ =\ *N* - - Run each test *N* times. Currently this is primarily useful for timing tests, - other results are not collated in any reasonable fashion. - - - + Run each test ``N`` times. Currently this is primarily useful for timing + tests, other results are not collated in any reasonable fashion. EXIT STATUS ----------- - -**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 +: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*. -The inputs passed to **lit** can be either individual tests, or entire -directories or hierarchies of tests to run. When **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 **lit** model, every test must exist inside some *test suite*. **lit** -resolves the inputs specified on the command line to test suites by searching -upwards from the input path until it finds a *lit.cfg* or *lit.site.cfg* -file. These files serve as both a marker of test suites and as configuration -files which **lit** loads in order to understand how to find and run the tests -inside the test suite. +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 **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. +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, **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 **lit** to provide convenient and flexible -support for out-of-tree builds. +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 + 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 + 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 + 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 + 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 Output|"OUTPUT OPTIONS" +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. -This section describes the **lit** testing architecture for users interested in -creating a new **lit** testing implementation, or extending an existing one. - -**lit** proper is primarily an infrastructure for discovering and running +:program:`lit` proper is primarily an infrastructure for discovering and running arbitrary tests, and to expose a single convenient interface to these -tests. **lit** itself doesn't know how to run tests, rather this logic is +tests. :program:`lit` itself doesn't know how to run tests, rather this logic is defined by *test suites*. TEST SUITES ~~~~~~~~~~~ - -As described in "TEST DISCOVERY", tests are always located inside a *test -suite*. Test suites serve to define the format of the tests they contain, the +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. -**lit** identifies test suites as directories containing *lit.cfg* or -*lit.site.cfg* files (see also **--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 **--show-suites** to display the -discovered test suites at startup. +: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 +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** 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 + 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: @@ -353,135 +280,132 @@ executed, two important global variables are predefined: 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 + discover and run tests in the test suite. Generally this will be a builtin test format available from the *lit.formats* module. - **test_src_root** The filesystem path to the test suite root. For out-of-dir + **test_src_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 + 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*, - *TclTest*. + 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*, *TclTest*. + 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*, *TclTest*. + 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 **lit** configuration in + **root** The root configuration. This is the top-most :program:`lit` configuration in the project. **on_clone** The config is actually cloned for every subdirectory inside a test - suite, to allow local configuration on a per-directory basis. The *on_clone* + suite, to allow local configuration on a per-directory basis. The *on_clone* variable can be set to a Python function which will be called whenever a - configuration is cloned (for a subdirectory). The function should takes three + configuration is cloned (for a subdirectory). The function should takes three arguments: (1) the parent configuration, (2) the new configuration (which the *on_clone* function will generally modify), and (3) the test path to the new directory being scanned. - - - TEST DISCOVERY ~~~~~~~~~~~~~~ - -Once test suites are located, **lit** recursively traverses the source directory -(following *test_src_root*) looking for tests. When **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 "LOCAL CONFIGURATION -FILES"). +Once test suites are located, :program:`lit` recursively traverses the source +directory (following *test_src_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. +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 **lit** loads a subdirectory in a test suite, it instantiates a local test -configuration by cloning the configuration for the parent direction -- the root -of this configuration chain will always be a test suite. Once the test -configuration is cloned **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. - +When :program:`lit` loads a subdirectory in a test suite, it instantiates a +local test configuration by cloning the configuration for the parent direction +--- 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. TEST RUN OUTPUT FORMAT ~~~~~~~~~~~~~~~~~~~~~~ - -The b<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. +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: -<result code>: <test name> (<progress info>) +.. 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 +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 ``<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. +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. +following format: + +.. code-block:: none -<log delineator> TEST '(<test name>)' <trailing delineator> -... log message ... -<log delineator> + <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. +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:: +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 ******************** Test 'C' failed as a result of exit code 1. - \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* + ******************** PASS: D (4 of 4) - LIT EXAMPLE TESTS ~~~~~~~~~~~~~~~~~ - -The **lit** distribution contains several example implementations of test suites -in the *ExampleTests* directory. - +The :program:`lit` distribution contains several example implementations of +test suites in the *ExampleTests* directory. SEE ALSO -------- - valgrind(1) diff --git a/docs/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst index 6f1c486..70354b0 100644 --- a/docs/CommandGuide/llc.rst +++ b/docs/CommandGuide/llc.rst @@ -1,251 +1,187 @@ llc - LLVM static compiler ========================== - SYNOPSIS -------- - -**llc** [*options*] [*filename*] - +:program:`llc` [*options*] [*filename*] DESCRIPTION ----------- - -The **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 :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 **-march** option is used to override -the default. - +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 *filename* is - or omitted, **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 the **-o** option is omitted, then **llc** will send its output to standard -output if the input is from standard input. If the **-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. -If no **-o** option is specified and an input file other than - is specified, -then **llc** creates the output filename by taking the input filename, -removing any existing *.bc* extension, and adding a *.s* suffix. - -Other **llc** options are as follows: +Other :program:`llc` options are described below. End-user Options ~~~~~~~~~~~~~~~~ - - -**-help** +.. 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:`llvm-gcc` and :program:`clang`. -**-O**\ =\ *uint* - - Generate code at different optimization levels. These correspond to the *-O0*, - *-O1*, *-O2*, and *-O3* optimization levels used by **llvm-gcc** and - **clang**. - - - -**-mtriple**\ =\ *target triple* +.. option:: -mtriple=<target triple> Override the target triple specified in the input file with the specified string. - - -**-march**\ =\ *arch* +.. 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 + 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. - - -**-mcpu**\ =\ *cpuname* +.. 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** + .. code-block:: none + llvm-as < /dev/null | llc -march=xyz -mcpu=help -**-mattr**\ =\ *a1,+a2,-a3,...* +.. 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** + .. code-block:: none + llvm-as < /dev/null | llc -march=xyz -mattr=help -**--disable-fp-elim** +.. option:: --disable-fp-elim Disable frame pointer elimination optimization. - - -**--disable-excess-fp-precision** +.. 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). - - -**--enable-no-infs-fp-math** +.. option:: --enable-no-infs-fp-math Enable optimizations that assume no Inf values. - - -**--enable-no-nans-fp-math** +.. option:: --enable-no-nans-fp-math Enable optimizations that assume no NAN values. - - -**--enable-unsafe-fp-math** +.. 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). - + would otherwise not be usable (such as ``fsin`` on X86). +.. option:: --enable-correct-eh-support -**--enable-correct-eh-support** + Instruct the **lowerinvoke** pass to insert code for correct exception + handling support. This is expensive and is by default omitted for efficiency. - Instruct the **lowerinvoke** pass to insert code for correct exception handling - support. This is expensive and is by default omitted for efficiency. - - - -**--stats** +.. option:: --stats Print statistics recorded by code-generation passes. - - -**--time-passes** +.. option:: --time-passes Record the amount of time needed for each pass and print a report to standard error. +.. option:: --load=<dso_path> - -**--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 - **-march** option so that code can be generated for that target. - - - + 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. Tuning/Configuration Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -**--print-machineinstrs** +.. option:: --print-machineinstrs Print generated machine code between compilation phases (useful for debugging). +.. option:: --regalloc=<allocator> - -**--regalloc**\ =\ *allocator* - - Specify the register allocator to use. The default *allocator* is *local*. + Specify the register allocator to use. The default ``allocator`` is *local*. Valid register allocators are: - *simple* Very simple "always spill" register allocator - - *local* Local register allocator - - *linearscan* Linear scan global register allocator - - *iterativescan* Iterative scan global register allocator - - - - -**--spiller**\ =\ *spiller* +.. 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: - + 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] - -**--x86-asm-syntax=att|intel** - - Specify whether to emit assembly code in AT&T syntax (the default) or intel + Specify whether to emit assembly code in AT&T syntax (the default) or Intel syntax. - - - - EXIT STATUS ----------- - -If **llc** succeeds, it will exit with 0. Otherwise, if an error occurs, -it will exit with a non-zero value. - +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 -lli|lli diff --git a/docs/CommandGuide/lli.rst b/docs/CommandGuide/lli.rst index 7cc1284..a9aaf31 100644 --- a/docs/CommandGuide/lli.rst +++ b/docs/CommandGuide/lli.rst @@ -50,7 +50,7 @@ GENERAL OPTIONS -**-load**\ =\ *puginfilename* +**-load**\ =\ *pluginfilename* Causes **lli** to load the plugin (shared object) named *pluginfilename* and use it for optimization. diff --git a/docs/CommandGuide/llvm-bcanalyzer.rst b/docs/CommandGuide/llvm-bcanalyzer.rst index f1e4eac..7254088 100644 --- a/docs/CommandGuide/llvm-bcanalyzer.rst +++ b/docs/CommandGuide/llvm-bcanalyzer.rst @@ -1,424 +1,305 @@ llvm-bcanalyzer - LLVM bitcode analyzer ======================================= - SYNOPSIS -------- - -**llvm-bcanalyzer** [*options*] [*filename*] - +: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. -The **llvm-bcanalyzer** command is a small utility for analyzing bitcode files. -The tool reads a bitcode file (such as generated with the **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 **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. - +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 -**-nodetails** - - Causes **llvm-bcanalyzer** to abbreviate its output by writing out only a module - level summary. The details for individual functions are not displayed. - - + Causes :program:`llvm-bcanalyzer` to abbreviate its output by writing out only + a module level summary. The details for individual functions are not + displayed. -**-dump** +.. option:: -dump - Causes **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. + 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 - -**-verify** - - Causes **llvm-bcanalyzer** to verify the module produced by reading the - bitcode. This ensures that the statistics generated are based on a consistent + 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. - - -**-help** +.. option:: -help Print a summary of command line options. - - - EXIT STATUS ----------- - -If **llvm-bcanalyzer** succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value, usually 1. - +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 +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. - - + 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 + 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. - - + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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. - - + 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. - - + 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. - - - + Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes. SEE ALSO -------- +:doc:`/CommandGuide/llvm-dis`, :doc:`/BitCodeFormat` -llvm-dis|llvm-dis, `http://llvm.org/docs/BitCodeFormat.html <http://llvm.org/docs/BitCodeFormat.html>`_ diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst index 09275f6..524f240 100644 --- a/docs/CommandGuide/llvm-cov.rst +++ b/docs/CommandGuide/llvm-cov.rst @@ -1,51 +1,39 @@ llvm-cov - emit coverage information ==================================== - SYNOPSIS -------- - -**llvm-cov** [-gcno=filename] [-gcda=filename] [dump] - +:program:`llvm-cov` [-gcno=filename] [-gcda=filename] [dump] DESCRIPTION ----------- - -The experimental **llvm-cov** tool reads in description file generated by compiler -and coverage data file generated by instrumented program. This program assumes -that the description and data file uses same format as gcov files. - +The experimental :program:`llvm-cov` tool reads in description file generated +by compiler and coverage data file generated by instrumented program. This +program assumes that the description and data file uses same format as gcov +files. OPTIONS ------- +.. option:: -gcno=filename + This option selects input description file generated by compiler while + instrumenting program. -**-gcno=filename]** - - This option selects input description file generated by compiler while instrumenting - program. - - - -**-gcda=filename]** +.. option:: -gcda=filename This option selects coverage data file generated by instrumented compiler. +.. option:: -dump - -**-dump** - - This options enables output dump that is suitable for a developer to help debug - **llvm-cov** itself. - - - + This options enables output dump that is suitable for a developer to help + debug :program:`llvm-cov` itself. EXIT STATUS ----------- +:program:`llvm-cov` returns 1 if it cannot read input files. Otherwise, it +exits with zero. -**llvm-cov** returns 1 if it cannot read input files. Otherwise, it exits with zero. diff --git a/docs/CommandGuide/llvm-link.rst b/docs/CommandGuide/llvm-link.rst index 63019d7..3bcfa68 100644 --- a/docs/CommandGuide/llvm-link.rst +++ b/docs/CommandGuide/llvm-link.rst @@ -1,96 +1,56 @@ -llvm-link - LLVM linker -======================= - +llvm-link - LLVM bitcode linker +=============================== SYNOPSIS -------- - -**llvm-link** [*options*] *filename ...* - +:program:`llvm-link` [*options*] *filename ...* DESCRIPTION ----------- - -**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 **-o** option is used to specify a filename. - -**llvm-link** attempts to load the input files from the current directory. If -that fails, it looks for each file in each of the directories specified by the -**-L** options on the command line. The library search paths are global; each -one is searched for every input file if necessary. The directories are searched -in the order they were specified on the command line. - +: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. -**-L** *directory* - - Add the specified *directory* to the library search path. When looking for - libraries, **llvm-link** will look in path name for libraries. This option can be - specified multiple times; **llvm-link** will search inside these directories in - the order in which they were specified on the command line. - - - -**-f** - - Enable binary output on terminals. Normally, **llvm-link** will refuse to - write raw bitcode output if the output stream is a terminal. With this option, - **llvm-link** will write raw bitcode regardless of the output device. - - - -**-o** *filename* - - Specify the output file name. If *filename* is ``-``, then **llvm-link** will - write its output to standard output. +.. option:: -o filename + Specify the output file name. If ``filename`` is "``-``", then + :program:`llvm-link` will write its output to standard output. - -**-S** +.. 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. -**-d** - - If specified, **llvm-link** prints a human-readable version of the output - bitcode file to standard error. - - - -**-help** +.. option:: -help Print a summary of command line options. +.. option:: -v - -**-v** - - Verbose mode. Print information about what **llvm-link** is doing. This - typically includes a message for each bitcode file linked in and for each + 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 **llvm-link** succeeds, it will exit with 0. Otherwise, if an error +If :program:`llvm-link` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. -SEE ALSO --------- - - -gccld|gccld diff --git a/docs/CommandGuide/llvm-stress.rst b/docs/CommandGuide/llvm-stress.rst index 44aa32c..fb006f5 100644 --- a/docs/CommandGuide/llvm-stress.rst +++ b/docs/CommandGuide/llvm-stress.rst @@ -1,48 +1,34 @@ llvm-stress - generate random .ll files ======================================= - SYNOPSIS -------- - -**llvm-stress** [-size=filesize] [-seed=initialseed] [-o=outfile] - +:program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile] DESCRIPTION ----------- - -The **llvm-stress** tool is used to generate random .ll files that can be used to -test different components of LLVM. - +The :program:`llvm-stress` tool is used to generate random ``.ll`` files that +can be used to test different components of LLVM. OPTIONS ------- - - -**-o** *filename* +.. option:: -o filename Specify the output filename. +.. option:: -size size + Specify the size of the generated ``.ll`` file. -**-size** *size* - - Specify the size of the generated .ll file. - - - -**-seed** *seed* +.. option:: -seed seed Specify the seed to be used for the randomly generated instructions. - - - EXIT STATUS ----------- +:program:`llvm-stress` returns 0. -**llvm-stress** returns 0. diff --git a/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst new file mode 100644 index 0000000..73babb1 --- /dev/null +++ b/docs/CommandGuide/llvm-symbolizer.rst @@ -0,0 +1,65 @@ +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. 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 + $ 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 + +OPTIONS +------- + +.. option:: -functions + + Print function names as well as source file/line locations. Defaults to true. + +.. option:: -use-symbol-table + + Prefer function names stored in symbol table to function names + in debug info sections. Defaults to true. + +.. option:: -demangle + + 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. + +EXIT STATUS +----------- + +:program:`llvm-symbolizer` returns 0. Other exit codes imply internal program error. diff --git a/docs/CommandGuide/opt.rst b/docs/CommandGuide/opt.rst index 72f1903..179c297 100644 --- a/docs/CommandGuide/opt.rst +++ b/docs/CommandGuide/opt.rst @@ -1,183 +1,143 @@ opt - LLVM optimizer ==================== - SYNOPSIS -------- - -**opt** [*options*] [*filename*] - +: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 :option:`-analyze` option is +given. -The **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 -**opt** depends on whether the **-analyze** option is given. - -When **-analyze** is specified, **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 +When :option:`-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, **opt** attempts to produce an optimized -output file. The optimizations available via **opt** depend upon what -libraries were linked into it as well as any additional libraries that have -been loaded with the **-load** option. Use the **-help** option to determine -what optimizations you can use. - -If *filename* is omitted from the command line or is *-*, **opt** reads its -input from standard input. Inputs can be in either the LLVM assembly language -format (.ll) or the LLVM bitcode format (.bc). +While :option:`-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 an output filename is not specified with the **-o** option, **opt** -writes its output to the standard output. +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. -**-f** - - Enable binary output on terminals. Normally, **opt** will refuse to - write raw bitcode output if the output stream is a terminal. With this option, - **opt** will write raw bitcode regardless of the output device. - - - -**-help** +.. option:: -help Print a summary of command line options. - - -**-o** *filename* +.. option:: -o <filename> Specify the output filename. - - -**-S** +.. 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). -**-{passname}** - - **opt** provides the ability to run any of LLVM's optimization or analysis passes - in any order. The **-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). - - - -**-std-compile-opts** +.. option:: -std-compile-opts This is short hand for a standard list of *compile time optimization* passes. - This is typically used to optimize the output from the llvm-gcc front end. It - might be useful for other front end compilers as well. To discover the full set - of options available, use the following command: - + This is typically used to optimize the output from the llvm-gcc front end. It + might be useful for other front end compilers as well. To discover the full + set of options available, use the following command: .. code-block:: sh llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments +.. option:: -disable-inlining + This option is only meaningful when :option:`-std-compile-opts` is given. It + simply removes the inlining pass from the standard list. +.. option:: -disable-opt -**-disable-inlining** - - This option is only meaningful when **-std-compile-opts** is given. It simply - removes the inlining pass from the standard list. - - - -**-disable-opt** - - This option is only meaningful when **-std-compile-opts** is given. It disables - most, but not all, of the **-std-compile-opts**. The ones that remain are - **-verify**, **-lower-setjmp**, and **-funcresolve**. + This option is only meaningful when :option:`-std-compile-opts` is given. It + disables most, but not all, of the :option:`-std-compile-opts`. The ones that + remain are :option:`-verify`, :option:`-lower-setjmp`, and + :option:`-funcresolve`. - - -**-strip-debug** +.. 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. - - - -**-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. The combination of **-std-compile-opts** and **-verify-each** - can quickly track down this kind of problem. + applying other optimizations. It is essentially the same as :option:`-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 :option:`-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. The combination of + :option:`-std-compile-opts` and :option:`-verify-each` can quickly track down + this kind of problem. -**-profile-info-file** *filename* +.. option:: -profile-info-file <filename> - Specify the name of the file loaded by the -profile-loader option. + Specify the name of the file loaded by the ``-profile-loader`` option. - - -**-stats** +.. option:: -stats Print statistics. - - -**-time-passes** +.. 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 ``DEBUG()`` macro. See the `LLVM Programmer's Manual + <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information. -**-debug** - - If this is a debug build, this option will enable debug printouts - from passes which use the *DEBUG()* macro. See the **LLVM Programmer's - Manual**, section *#DEBUG* for more information. - - - -**-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 **-help** and **-load** options together. For example: +.. 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 - - - -**-p** +.. option:: -p Print module after each transformation. - - - EXIT STATUS ----------- - -If **opt** succeeds, it will exit with 0. Otherwise, if an error +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/docs/CommandGuide/tblgen.rst b/docs/CommandGuide/tblgen.rst index 2d19167..1858ee4 100644 --- a/docs/CommandGuide/tblgen.rst +++ b/docs/CommandGuide/tblgen.rst @@ -1,186 +1,129 @@ tblgen - Target Description To C++ Code Generator ================================================= - SYNOPSIS -------- - -**tblgen** [*options*] [*filename*] - +: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. -**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 **tblgen** is beyond the scope of this short -introduction. Please see the *CodeGeneration* page in the LLVM documentation. - -The *filename* argument specifies the name of a Target Description (.td) file -to read as input. +The input and output of :program:`tblgen` is beyond the scope of this short +introduction. Please see :doc:`../TableGenFundamentals`. +The *filename* argument specifies the name of a Target Description (``.td``) +file to read as input. OPTIONS ------- - - -**-help** +.. 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. -**-o** *filename* - - Specify the output file name. If *filename* is ``-``, then **tblgen** - sends its output to standard output. - - - -**-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. - - - -**-asmparsernum** *N* +.. option:: -I directory - Make -gen-asm-parser emit assembly writer number *N*. + 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``. -**-asmwriternum** *N* +.. option:: -asmwriternum N - Make -gen-asm-writer emit assembly writer number *N*. + Make -gen-asm-writer emit assembly writer number ``N``. - - -**-class** *class Name* +.. option:: -class className Print the enumeration list for this class. - - -**-print-records** +.. option:: -print-records Print all records to standard output (default). - - -**-print-enums** +.. option:: -print-enums Print enumeration values for a class - - -**-print-sets** +.. option:: -print-sets Print expanded sets for testing DAG exprs. - - -**-gen-emitter** +.. option:: -gen-emitter Generate machine code emitter. - - -**-gen-register-info** +.. option:: -gen-register-info Generate registers and register classes info. - - -**-gen-instr-info** +.. option:: -gen-instr-info Generate instruction descriptions. - - -**-gen-asm-writer** +.. option:: -gen-asm-writer Generate the assembly writer. - - -**-gen-disassembler** +.. option:: -gen-disassembler Generate disassembler. - - -**-gen-pseudo-lowering** +.. option:: -gen-pseudo-lowering Generate pseudo instruction lowering. - - -**-gen-dag-isel** +.. option:: -gen-dag-isel Generate a DAG (Directed Acycle Graph) instruction selector. - - -**-gen-asm-matcher** +.. option:: -gen-asm-matcher Generate assembly instruction matcher. - - -**-gen-dfa-packetizer** +.. option:: -gen-dfa-packetizer Generate DFA Packetizer for VLIW targets. - - -**-gen-fast-isel** +.. option:: -gen-fast-isel Generate a "fast" instruction selector. - - -**-gen-subtarget** +.. option:: -gen-subtarget Generate subtarget enumerations. - - -**-gen-intrinsic** +.. option:: -gen-intrinsic Generate intrinsic information. - - -**-gen-tgt-intrinsic** +.. option:: -gen-tgt-intrinsic Generate target intrinsic information. - - -**-gen-enhanced-disassembly-info** +.. option:: -gen-enhanced-disassembly-info Generate enhanced disassembly info. - - -**-version** +.. option:: -version Show the version number of this program. - - - EXIT STATUS ----------- - -If **tblgen** succeeds, it will exit with 0. Otherwise, if an error +If :program:`tblgen` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. |
