[llvm-branch-commits] [llvm] [docs] Convert CommandGuide docs to Markdown (PR #219625)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Aug 28 21:29:27 PDT 2026
https://github.com/rnk created https://github.com/llvm/llvm-project/pull/219625
Tracking issue: #201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #219624 , which will be a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
This was prepared with rst2myst plus LLM-assisted cleanup. I paged through all the generated HTML looking for migration artifacts, and all of the differences I could find appear to be formatting error corrections. Please spot check my work and approve if it looks good. You can use the HTML links below to confirm it renders properly.
-----
The [pixel diff overview](https://llvmdocs.staging.reidkleckner.dev/diff.html) summarizes the rendered before/after differences.
Before/after validation links:
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `llvm/docs/CommandGuide/FileCheck.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/FileCheck.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/FileCheck.html) |
| `llvm/docs/CommandGuide/clang-tblgen.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/clang-tblgen.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/clang-tblgen.html) |
| `llvm/docs/CommandGuide/dsymutil.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/dsymutil.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/dsymutil.html) |
| `llvm/docs/CommandGuide/lit.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/lit.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/lit.html) |
| `llvm/docs/CommandGuide/llc.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llc.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llc.html) |
| `llvm/docs/CommandGuide/lldb-tblgen.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/lldb-tblgen.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/lldb-tblgen.html) |
| `llvm/docs/CommandGuide/lli.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/lli.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/lli.html) |
| `llvm/docs/CommandGuide/llubi.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llubi.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llubi.html) |
| `llvm/docs/CommandGuide/llvm-addr2line.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-addr2line.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-addr2line.html) |
| `llvm/docs/CommandGuide/llvm-ar.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-ar.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-ar.html) |
| `llvm/docs/CommandGuide/llvm-as.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-as.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-as.html) |
| `llvm/docs/CommandGuide/llvm-bcanalyzer.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-bcanalyzer.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-bcanalyzer.html) |
| `llvm/docs/CommandGuide/llvm-calc-occupancy.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-calc-occupancy.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-calc-occupancy.html) |
| `llvm/docs/CommandGuide/llvm-cgdata.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-cgdata.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-cgdata.html) |
| `llvm/docs/CommandGuide/llvm-config.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-config.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-config.html) |
| `llvm/docs/CommandGuide/llvm-cov.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-cov.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-cov.html) |
| `llvm/docs/CommandGuide/llvm-cxxfilt.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-cxxfilt.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-cxxfilt.html) |
| `llvm/docs/CommandGuide/llvm-cxxmap.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-cxxmap.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-cxxmap.html) |
| `llvm/docs/CommandGuide/llvm-debuginfo-analyzer.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.html) |
| `llvm/docs/CommandGuide/llvm-diff.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-diff.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-diff.html) |
| `llvm/docs/CommandGuide/llvm-dis.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-dis.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-dis.html) |
| `llvm/docs/CommandGuide/llvm-dwarfdump.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-dwarfdump.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-dwarfdump.html) |
| `llvm/docs/CommandGuide/llvm-dwarfutil.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-dwarfutil.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-dwarfutil.html) |
| `llvm/docs/CommandGuide/llvm-exegesis.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-exegesis.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-exegesis.html) |
| `llvm/docs/CommandGuide/llvm-extract-bundle-entry.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-extract-bundle-entry.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-extract-bundle-entry.html) |
| `llvm/docs/CommandGuide/llvm-extract.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-extract.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-extract.html) |
| `llvm/docs/CommandGuide/llvm-gsymutil.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-gsymutil.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-gsymutil.html) |
| `llvm/docs/CommandGuide/llvm-ifs.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-ifs.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-ifs.html) |
| `llvm/docs/CommandGuide/llvm-install-name-tool.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-install-name-tool.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-install-name-tool.html) |
| `llvm/docs/CommandGuide/llvm-ir2vec.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-ir2vec.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-ir2vec.html) |
| `llvm/docs/CommandGuide/llvm-lib.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/llvm/docs/CommandGuide/llvm-lib.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/llvm/docs/CommandGuide/llvm-lib.html) |
>From e714fce0e8a6c652ccf2ccf90948c0946829f7ca Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Fri, 28 Aug 2026 04:56:19 +0000
Subject: [PATCH] [docs] Convert CommandGuide docs to Markdown
---
llvm/docs/CommandGuide/FileCheck.md | 1269 +++---
llvm/docs/CommandGuide/clang-tblgen.md | 23 +-
llvm/docs/CommandGuide/dsymutil.md | 423 +-
llvm/docs/CommandGuide/lit.md | 1215 +++---
llvm/docs/CommandGuide/llc.md | 360 +-
llvm/docs/CommandGuide/lldb-tblgen.md | 23 +-
llvm/docs/CommandGuide/lli.md | 370 +-
llvm/docs/CommandGuide/llubi.md | 155 +-
llvm/docs/CommandGuide/llvm-addr2line.md | 72 +-
llvm/docs/CommandGuide/llvm-ar.md | 614 ++-
llvm/docs/CommandGuide/llvm-as.md | 58 +-
llvm/docs/CommandGuide/llvm-bcanalyzer.md | 241 +-
llvm/docs/CommandGuide/llvm-calc-occupancy.md | 175 +-
llvm/docs/CommandGuide/llvm-cgdata.md | 68 +-
llvm/docs/CommandGuide/llvm-config.md | 122 +-
llvm/docs/CommandGuide/llvm-cov.md | 1020 +++--
llvm/docs/CommandGuide/llvm-cxxfilt.md | 114 +-
llvm/docs/CommandGuide/llvm-cxxmap.md | 126 +-
.../CommandGuide/llvm-debuginfo-analyzer.md | 3601 ++++++++---------
llvm/docs/CommandGuide/llvm-diff.md | 32 +-
llvm/docs/CommandGuide/llvm-dis.md | 49 +-
llvm/docs/CommandGuide/llvm-dwarfdump.md | 554 ++-
llvm/docs/CommandGuide/llvm-dwarfutil.md | 153 +-
llvm/docs/CommandGuide/llvm-exegesis.md | 684 ++--
.../CommandGuide/llvm-extract-bundle-entry.md | 66 +-
llvm/docs/CommandGuide/llvm-extract.md | 97 +-
llvm/docs/CommandGuide/llvm-gsymutil.md | 260 +-
llvm/docs/CommandGuide/llvm-ifs.md | 319 +-
.../CommandGuide/llvm-install-name-tool.md | 137 +-
llvm/docs/CommandGuide/llvm-ir2vec.md | 364 +-
llvm/docs/CommandGuide/llvm-lib.md | 23 +-
31 files changed, 6299 insertions(+), 6488 deletions(-)
diff --git a/llvm/docs/CommandGuide/FileCheck.md b/llvm/docs/CommandGuide/FileCheck.md
index 22101d3ef2ac7..c64b6d9ae22a7 100644
--- a/llvm/docs/CommandGuide/FileCheck.md
+++ b/llvm/docs/CommandGuide/FileCheck.md
@@ -1,580 +1,568 @@
-FileCheck - Flexible pattern matching file verifier
-===================================================
+# FileCheck - Flexible pattern matching file verifier
+```{eval-rst}
.. program:: FileCheck
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`FileCheck` *match-filename* [*--check-prefixes=XXX*] [*--strict-whitespace*]
+{program}`FileCheck` *match-filename* \[*--check-prefixes=XXX*\] \[*--strict-whitespace*\]
-DESCRIPTION
------------
+## 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
+{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
+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.
+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
-Options are parsed from the environment variable ``FILECHECK_OPTS``
+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-prefixes prefix1,prefix2,...
-
- 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-prefixes` argument allows you to specify (without the trailing
- "``:``") 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.
-
- FileCheck does not permit duplicate prefixes, even if one is a check prefix
- and one is a comment prefix (see :option:`--comment-prefixes` below).
-
-.. option:: --check-prefix prefix1,prefix2,...
-
- An alias of :option:`--check-prefixes`.
-
-.. option:: --comment-prefixes prefix1,prefix2,...
-
- By default, FileCheck ignores any occurrence in ``match-filename`` of any check
- prefix if it is preceded on the same line by "``COM:``" or "``RUN:``". See the
- section `The "COM:" directive`_ for usage details.
-
- These default comment prefixes can be overridden by
- :option:`--comment-prefixes` if they are not appropriate for your testing
- environment. However, doing so is not recommended in LLVM's LIT-based test
- suites, which should be easier to maintain if they all follow a consistent
- comment style. In that case, consider proposing a change to the default
- comment prefixes instead.
-
-.. option:: --allow-unused-prefixes
-
- This option controls the behavior when using more than one prefix as specified
- by :option:`--check-prefixes`, and some of these
- prefixes are missing in the test file. If true, this is allowed, if false,
- FileCheck will report an error, listing the missing prefixes. The default value
- is false.
-
-.. 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:: --ignore-case
-
- By default, FileCheck uses case-sensitive matching. This option causes
- FileCheck to use case-insensitive matching.
-
-.. 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 <value>
-
- Dump input to stderr, adding annotations representing currently enabled
- diagnostics. When there are multiple occurrences of this option, the
- ``<value>`` that appears earliest in the list below has precedence. The
- default is ``fail``.
-
- * ``help`` - Explain input dump and quit
- * ``always`` - Always dump input
- * ``fail`` - Dump input on failure
- * ``never`` - Never dump input
-
-.. option:: --dump-input-context <N>
-
- In the dump requested by ``--dump-input``, print ``<N>`` input lines before
- and ``<N>`` input lines after any lines specified by ``--dump-input-filter``.
- When there are multiple occurrences of this option, the largest specified
- ``<N>`` has precedence. The default is 5.
-
-.. option:: --dump-input-filter <value>
-
- In the dump requested by ``--dump-input``, print only input lines of kind
- ``<value>`` plus any context specified by ``--dump-input-context``. When
- there are multiple occurrences of this option, the ``<value>`` that appears
- earliest in the list below has precedence. The default is ``error`` when
- ``--dump-input=fail``, and it's ``all`` when ``--dump-input=always``.
-
- * ``all`` - All input lines
- * ``annotation-full`` - Input lines with annotations
- * ``annotation`` - Input lines with starting points of annotations
- * ``error`` - Input lines with starting points of error annotations
-
-.. 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 pattern variable ``VAR`` with value ``VALUE`` that can be
- used in ``CHECK:`` lines.
-
-.. option:: -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
-
- Sets a filecheck numeric variable ``NUMVAR`` of matching format ``FMT`` to
- the result of evaluating ``<NUMERIC EXPRESSION>`` that can be used in
- ``CHECK:`` lines. See section
- ``FileCheck Numeric Variables and Expressions`` for details on supported
- numeric expressions.
-
-.. option:: -version
-
- Show the version number of this program.
-
-.. option:: -v
-
- Print good directive pattern matches. However, if ``-dump-input=fail`` or
- ``-dump-input=always``, add those matches as input annotations instead.
-
-.. 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``.
- However, if ``-dump-input=fail`` or ``-dump-input=always``, just add that
- information as input annotations instead.
-
-.. 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:: --allow-empty
-
- Allow checking empty input. By default, empty input is rejected.
-
-.. 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
+:::{option} -help
+Print a summary of command line options.
+:::
+
+:::{option} --check-prefixes prefix1,prefix2,...
+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-prefixes` argument allows you to specify (without the trailing
+"`:`") 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.
+
+FileCheck does not permit duplicate prefixes, even if one is a check prefix
+and one is a comment prefix (see {option}`--comment-prefixes` below).
+:::
+
+:::{option} --check-prefix prefix1,prefix2,...
+An alias of {option}`--check-prefixes`.
+:::
+
+:::{option} --comment-prefixes prefix1,prefix2,...
+By default, FileCheck ignores any occurrence in `match-filename` of any check
+prefix if it is preceded on the same line by "`COM:`" or "`RUN:`". See the
+section [The "COM:" directive] for usage details.
+
+These default comment prefixes can be overridden by
+{option}`--comment-prefixes` if they are not appropriate for your testing
+environment. However, doing so is not recommended in LLVM's LIT-based test
+suites, which should be easier to maintain if they all follow a consistent
+comment style. In that case, consider proposing a change to the default
+comment prefixes instead.
+:::
+
+:::{option} --allow-unused-prefixes
+This option controls the behavior when using more than one prefix as specified
+by {option}`--check-prefixes`, and some of these
+prefixes are missing in the test file. If true, this is allowed, if false,
+FileCheck will report an error, listing the missing prefixes. The default value
+is false.
+:::
+
+:::{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} --ignore-case
+By default, FileCheck uses case-sensitive matching. This option causes
+FileCheck to use case-insensitive matching.
+:::
+
+:::{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 <value>
+Dump input to stderr, adding annotations representing currently enabled
+diagnostics. When there are multiple occurrences of this option, the
+`<value>` that appears earliest in the list below has precedence. The
+default is `fail`.
+
+- `help` - Explain input dump and quit
+- `always` - Always dump input
+- `fail` - Dump input on failure
+- `never` - Never dump input
+:::
+
+:::{option} --dump-input-context <N>
+In the dump requested by `--dump-input`, print `<N>` input lines before
+and `<N>` input lines after any lines specified by `--dump-input-filter`.
+When there are multiple occurrences of this option, the largest specified
+`<N>` has precedence. The default is 5.
+:::
+
+:::{option} --dump-input-filter <value>
+In the dump requested by `--dump-input`, print only input lines of kind
+`<value>` plus any context specified by `--dump-input-context`. When
+there are multiple occurrences of this option, the `<value>` that appears
+earliest in the list below has precedence. The default is `error` when
+`--dump-input=fail`, and it's `all` when `--dump-input=always`.
+
+- `all` - All input lines
+- `annotation-full` - Input lines with annotations
+- `annotation` - Input lines with starting points of annotations
+- `error` - Input lines with starting points of error annotations
+:::
+
+:::{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 pattern variable `VAR` with value `VALUE` that can be
+used in `CHECK:` lines.
+:::
+
+:::{option} -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
+Sets a filecheck numeric variable `NUMVAR` of matching format `FMT` to
+the result of evaluating `<NUMERIC EXPRESSION>` that can be used in
+`CHECK:` lines. See section
+`FileCheck Numeric Variables and Expressions` for details on supported
+numeric expressions.
+:::
+
+:::{option} -version
+Show the version number of this program.
+:::
+
+:::{option} -v
+Print good directive pattern matches. However, if `-dump-input=fail` or
+`-dump-input=always`, add those matches as input annotations instead.
+:::
+
+:::{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`.
+However, if `-dump-input=fail` or `-dump-input=always`, just add that
+information as input annotations instead.
+:::
+
+:::{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} --allow-empty
+Allow checking empty input. By default, empty input is rejected.
+:::
+
+:::{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
---------
+## 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
+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
+```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
+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
+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
+```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.
+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``"
+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-prefixes option
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### The FileCheck -check-prefixes option
The FileCheck `-check-prefixes` option allows multiple test
-configurations to be driven from one `.ll` file. This is useful in many
+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
+{program}`llc`. Here's a simple example:
- ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
- ; RUN: | FileCheck %s -check-prefixes=X32
- ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
- ; RUN: | FileCheck %s -check-prefixes=X64
+```llvm
+; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
+; RUN: | FileCheck %s -check-prefixes=X32
+; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
+; RUN: | FileCheck %s -check-prefixes=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
+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
- }
+; 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 "COM:" directive
-~~~~~~~~~~~~~~~~~~~~
+### The "COM:" directive
Sometimes you want to disable a FileCheck directive without removing it
entirely, or you want to write comments that mention a directive by name. The
-"``COM:``" directive makes it easy to do this. For example, you might have:
+"`COM:`" directive makes it easy to do this. For example, you might have:
-.. code-block:: llvm
+```llvm
+; X32: pinsrd_1:
+; X32: pinsrd $1, 4(%esp), %xmm0
- ; X32: pinsrd_1:
- ; X32: pinsrd $1, 4(%esp), %xmm0
+; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but
+; COM: X64 will have something similar to X32:
+; COM:
+; COM: X64: pinsrd_1:
+; COM: X64: pinsrd $1, %edi, %xmm0
+```
- ; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but
- ; COM: X64 will have something similar to X32:
- ; COM:
- ; COM: X64: pinsrd_1:
- ; COM: X64: pinsrd $1, %edi, %xmm0
-
-Without "``COM:``", you would need to use some combination of rewording and
+Without "`COM:`", you would need to use some combination of rewording and
directive syntax mangling to prevent FileCheck from recognizing the commented
-occurrences of "``X32:``" and "``X64:``" above as directives. Moreover,
+occurrences of "`X32:`" and "`X64:`" above as directives. Moreover,
FileCheck diagnostics have been proposed that might complain about the above
-occurrences of "``X64``" that don't have the trailing "``:``" because they look
+occurrences of "`X64`" that don't have the trailing "`:`" because they look
like directive typos. Dodging all these problems can be tedious for a test
author, and directive syntax mangling can make the purpose of test code unclear.
-"``COM:``" avoids all these problems.
+"`COM:`" avoids all these problems.
A few important usage notes:
-* "``COM:``" within another directive's pattern does *not* comment out the
+- "`COM:`" within another directive's pattern does *not* comment out the
remainder of the pattern. For example:
- .. code-block:: llvm
-
- ; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern!
+ ```llvm
+ ; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern!
+ ```
If you need to temporarily comment out part of a directive's pattern, move it
- to another line. The reason is that FileCheck parses "``COM:``" in the same
+ to another line. The reason is that FileCheck parses "`COM:`" in the same
manner as any other directive: only the first directive on the line is
recognized as a directive.
-* For the sake of LIT, FileCheck treats "``RUN:``" just like "``COM:``". If this
- is not suitable for your test environment, see :option:`--comment-prefixes`.
+- For the sake of LIT, FileCheck treats "`RUN:`" just like "`COM:`". If this
+ is not suitable for your test environment, see {option}`--comment-prefixes`.
-* FileCheck does not recognize "``COM``", "``RUN``", or any user-defined comment
+- FileCheck does not recognize "`COM`", "`RUN`", or any user-defined comment
prefix as a comment directive if it's combined with one of the usual check
- directive suffixes, such as "``-NEXT:``" or "``-NOT:``", discussed below.
+ directive suffixes, such as "`-NEXT:`" or "`-NOT:`", discussed below.
FileCheck treats such a combination as plain text instead. If it needs to act
as a comment directive for your test environment, define it as such with
- :option:`--comment-prefixes`.
+ {option}`--comment-prefixes`.
-The "CHECK-NEXT:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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:``".
+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
+```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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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:``".
+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:``"
+"`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)
+```llvm
+!0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
- ; CHECK: !DILocation(line: 5,
- ; CHECK-NOT: column:
- ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]
+; 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
+"`CHECK-SAME:`" directives reject the input if there are any newlines between
it and the previous directive.
-"``CHECK-SAME:``" is also useful to avoid writing matchers for irrelevant
+"`CHECK-SAME:`" is also useful to avoid writing matchers for irrelevant
fields. For example, suppose you're writing a test which parses a tool that
generates output like this:
-.. code-block:: text
-
- Name: foo
- Field1: ...
- Field2: ...
- Field3: ...
- Value: 1
-
- Name: bar
- Field1: ...
- Field2: ...
- Field3: ...
- Value: 2
-
- Name: baz
- Field1: ...
- Field2: ...
- Field3: ...
- Value: 1
-
-To write a test that verifies ``foo`` has the value ``1``, you might first
+```text
+Name: foo
+Field1: ...
+Field2: ...
+Field3: ...
+Value: 1
+
+Name: bar
+Field1: ...
+Field2: ...
+Field3: ...
+Value: 2
+
+Name: baz
+Field1: ...
+Field2: ...
+Field3: ...
+Value: 1
+```
+
+To write a test that verifies `foo` has the value `1`, you might first
write this:
-.. code-block:: text
-
- CHECK: Name: foo
- CHECK: Value: 1{{$}}
-
-However, this would be a bad test: if the value for ``foo`` changes, the test
-would still pass because the "``CHECK: Value: 1``" line would match the value
-from ``baz``. To fix this, you could add ``CHECK-NEXT`` matchers for every
-``FieldN:`` line, but that would be verbose, and need to be updated when
-``Field4`` is added. A more succinct way to write the test using the
-"``CHECK-SAME:``" matcher would be as follows:
+```text
+CHECK: Name: foo
+CHECK: Value: 1{{$}}
+```
-.. code-block:: text
+However, this would be a bad test: if the value for `foo` changes, the test
+would still pass because the "`CHECK: Value: 1`" line would match the value
+from `baz`. To fix this, you could add `CHECK-NEXT` matchers for every
+`FieldN:` line, but that would be verbose, and need to be updated when
+`Field4` is added. A more succinct way to write the test using the
+"`CHECK-SAME:`" matcher would be as follows:
- CHECK: Name: foo
- CHECK: Value:
- CHECK-SAME: {{ 1$}}
+```text
+CHECK: Name: foo
+CHECK: Value:
+CHECK-SAME: {{ 1$}}
+```
-This verifies that the *next* time "``Value:``" appears in the output, it has
-the value ``1``.
+This verifies that the *next* time "`Value:`" appears in the output, it has
+the value `1`.
-Note: a "``CHECK-SAME:``" cannot be the first directive in a file.
+Note: a "`CHECK-SAME:`" cannot be the first directive in a file.
-The "CHECK-EMPTY:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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.
+you can use the "`CHECK-EMPTY:`" directive.
-.. code-block:: llvm
+```llvm
+declare void @foo()
- declare void @foo()
+declare void @bar()
+; CHECK: foo
+; CHECK-EMPTY:
+; CHECK-NEXT: bar
+```
- declare void @bar()
- ; CHECK: foo
- ; CHECK-EMPTY:
- ; CHECK-NEXT: bar
-
-Just like "``CHECK-NEXT:``" the directive will fail if there is more than one
+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
-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
+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
+```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
+ %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
- }
+ %A = load i8* %P3
+ ret i8 %A
+; CHECK: @coerce_offset0
+; CHECK-NOT: load
+; CHECK: ret i8
+}
+```
-The "CHECK-COUNT:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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.
+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
+```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]+}}
+; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
+; CHECK-NOT: Loop at depth {{[0-9]+}}
+```
-The "CHECK-DAG:" directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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
+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
+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 =
+```c++
+// RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
- struct Bar { virtual void method(); };
- Bar b;
- // CHECK-DAG: @_ZTV3Bar =
+struct Foo { virtual void method(); };
+Foo f; // emit vtable
+// CHECK-DAG: @_ZTV3Foo =
-``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,
+struct Bar { virtual void method(); };
+Bar b;
+// CHECK-DAG: @_ZTV3Bar =
+```
-.. code-block:: llvm
+`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,
- ; CHECK-DAG: BEFORE
- ; CHECK-NOT: NOT
- ; CHECK-DAG: AFTER
+```llvm
+; CHECK-DAG: BEFORE
+; CHECK-NOT: NOT
+; CHECK-DAG: AFTER
+```
-This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.
+This case will reject input strings where `BEFORE` occurs after `AFTER`.
-With captured variables, ``CHECK-DAG:`` is able to match valid topological
+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
+```llvm
+; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
+; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
+; CHECK: mul r5, [[REG1]], [[REG2]]
+```
- ; 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.
-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,
+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]
+```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]
+```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
@@ -584,252 +572,243 @@ 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
+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,
+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
+```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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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
+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``
+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
+`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
+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,
+```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
+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.
+`CHECK-LABEL:` directives cannot contain variable definitions or uses.
-Directive modifiers
-~~~~~~~~~~~~~~~~~~~
+### Directive modifiers
A directive modifier can be append to a directive by following the directive
-with ``{<modifier>}`` where the only supported value for ``<modifier>`` is
-``LITERAL``.
+with `{<modifier>}` where the only supported value for `<modifier>` is
+`LITERAL`.
-The ``LITERAL`` directive modifier can be used to perform a literal match. The
+The `LITERAL` directive modifier can be used to perform a literal match. The
modifier results in the directive not recognizing any syntax to perform regex
matching, variable capture or any substitutions. This is useful when the text
to match would require excessive escaping otherwise. For example, the
following will perform literal matches rather than considering these as
regular expressions:
-.. code-block:: text
-
- Input: [[[10, 20]], [[30, 40]]]
- Output %r10: [[10, 20]]
- Output %r10: [[30, 40]]
+```text
+Input: [[[10, 20]], [[30, 40]]]
+Output %r10: [[10, 20]]
+Output %r10: [[30, 40]]
- ; CHECK{LITERAL}: [[[10, 20]], [[30, 40]]]
- ; CHECK-DAG{LITERAL}: [[30, 40]]
- ; CHECK-DAG{LITERAL}: [[10, 20]]
+; CHECK{LITERAL}: [[[10, 20]], [[30, 40]]]
+; CHECK-DAG{LITERAL}: [[30, 40]]
+; CHECK-DAG{LITERAL}: [[10, 20]]
+```
-FileCheck Regex Matching Syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### FileCheck Regex 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,
+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
+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
+matching with regular expressions. This allows you to write things like this:
- ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}
+```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 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. Or if you are using the repetition count
-syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you
-would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid
+`{{[}][}]}}` as your pattern. Or if you are using the repetition count
+syntax, for example `[[:xdigit:]]{8}` to match exactly 8 hex digits, you
+would need to add parentheses like this `{{([[:xdigit:]]{8})}}` to avoid
confusion with FileCheck's closing double-brace.
-FileCheck String Substitution Blocks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### FileCheck String Substitution Blocks
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` supports string substitution blocks that allow
-string variables to be defined and substituted into patterns. Here is a simple
+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` supports string substitution blocks that allow
+string 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
-string variable ``REGISTER``. The second line verifies that whatever is in
-``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`
-string substitution blocks are always contained in ``[[ ]]`` pairs, and string
-variable names can be formed with the regex ``\$[a-zA-Z_][a-zA-Z0-9_]*``. If a
+```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
+string variable `REGISTER`. The second line verifies that whatever is in
+`REGISTER` occurs later in the file after an "`andw`". {program}`FileCheck`
+string substitution blocks are always contained in `[[ ]]` pairs, and string
+variable 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 substitution.
-:program:`FileCheck` variables can be defined multiple times, and substitutions
-always get the latest value. Variables can also be substituted later on the
+{program}`FileCheck` variables can be defined multiple times, and substitutions
+always get the latest value. Variables can also be substituted later on the
same line they were defined on. For example:
-.. code-block:: llvm
-
- ; CHECK: op [[REG:r[0-9]+]], [[REG]]
+```llvm
+; CHECK: op [[REG:r[0-9]+]], [[REG]]
+```
-Can be useful if you want the operands of ``op`` to be the same register,
+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
+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 Numeric Substitution Blocks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### FileCheck Numeric Substitution Blocks
-:program:`FileCheck` also supports numeric substitution blocks that allow
+{program}`FileCheck` also supports numeric substitution blocks that allow
defining numeric variables and checking for numeric values that satisfy a
numeric expression constraint based on those variables via a numeric
-substitution. This allows ``CHECK:`` directives to verify a numeric relation
+substitution. This allows `CHECK:` directives to verify a numeric relation
between two numbers, such as the need for consecutive registers to be used.
The syntax to capture a numeric value is
-``[[#%<fmtspec>,<NUMVAR>:]]`` where:
+`[[#%<fmtspec>,<NUMVAR>:]]` where:
-* ``%<fmtspec>,`` is an optional format specifier to indicate what number
+- `%<fmtspec>,` is an optional format specifier to indicate what number
format to match and the minimum number of digits to expect.
-
-* ``<NUMVAR>:`` is an optional definition of variable ``<NUMVAR>`` from the
+- `<NUMVAR>:` is an optional definition of variable `<NUMVAR>` from the
captured value.
-The syntax of ``<fmtspec>`` is: ``#.<precision><conversion specifier>`` where:
+The syntax of `<fmtspec>` is: `#.<precision><conversion specifier>` where:
-* ``#`` is an optional flag available for hex values (see
- ``<conversion specifier>`` below) which requires the value matched to be
- prefixed by ``0x``.
-* ``.<precision>`` is an optional printf-style precision specifier in which
- ``<precision>`` indicates the minimum number of digits that the value matched
+- `#` is an optional flag available for hex values (see
+ `<conversion specifier>` below) which requires the value matched to be
+ prefixed by `0x`.
+- `.<precision>` is an optional printf-style precision specifier in which
+ `<precision>` indicates the minimum number of digits that the value matched
must have, expecting leading zeros if needed.
-
-* ``<conversion specifier>`` is an optional scanf-style conversion specifier
- to indicate what number format to match (e.g. hex number). Currently
- accepted format specifiers are ``%u``, ``%d``, ``%x`` and ``%X``. If absent,
- the format specifier defaults to ``%u``.
-
+- `<conversion specifier>` is an optional scanf-style conversion specifier
+ to indicate what number format to match (e.g. hex number). Currently
+ accepted format specifiers are `%u`, `%d`, `%x` and `%X`. If absent,
+ the format specifier defaults to `%u`.
For example:
-.. code-block:: llvm
+```llvm
+; CHECK: mov r[[#REG:]], 0x[[#%.8X,ADDR:]]
+```
- ; CHECK: mov r[[#REG:]], 0x[[#%.8X,ADDR:]]
-
-would match ``mov r5, 0x0000FEFE`` and set ``REG`` to the value ``5`` and
-``ADDR`` to the value ``0xFEFE``. Note that due to the precision it would fail
-to match ``mov r5, 0xFEFE``.
+would match `mov r5, 0x0000FEFE` and set `REG` to the value `5` and
+`ADDR` to the value `0xFEFE`. Note that due to the precision it would fail
+to match `mov r5, 0xFEFE`.
As a result of the numeric variable definition being optional, it is possible
to only check that a numeric value is present in a given format. This can be
useful when the value itself is not useful, for instance:
-.. code-block:: gas
-
- ; CHECK-NOT: mov r0, r[[#]]
+```gas
+; CHECK-NOT: mov r0, r[[#]]
+```
to check that a value is synthesized rather than moved around.
-
The syntax of a numeric substitution is
-``[[#%<fmtspec>, <constraint> <expr>]]`` where:
+`[[#%<fmtspec>, <constraint> <expr>]]` where:
-* ``<fmtspec>`` is the same format specifier as for defining a variable but
+- `<fmtspec>` is the same format specifier as for defining a variable but
in this context indicating how a numeric expression value should be matched
against. If absent, both components of the format specifier are inferred from
the matching format of the numeric variable(s) used by the expression
- constraint if any, and defaults to ``%u`` if no numeric variable is used,
+ constraint if any, and defaults to `%u` if no numeric variable is used,
denoting that the value should be unsigned with no leading zeros. In case of
conflict between format specifiers of several numeric variables, the
conversion specifier becomes mandatory but the precision specifier remains
optional.
-* ``<constraint>`` is the constraint describing how the value to match must
+- `<constraint>` is the constraint describing how the value to match must
relate to the value of the numeric expression. The only currently accepted
- constraint is ``==`` for an exact match and is the default if
- ``<constraint>`` is not provided. No matching constraint must be specified
- when the ``<expr>`` is empty.
+ constraint is `==` for an exact match and is the default if
+ `<constraint>` is not provided. No matching constraint must be specified
+ when the `<expr>` is empty.
-* ``<expr>`` is an expression. An expression is in turn recursively defined
+- `<expr>` is an expression. An expression is in turn recursively defined
as:
- * a numeric operand, or
- * an expression followed by an operator and a numeric operand.
+ - a numeric operand, or
+ - an expression followed by an operator and a numeric operand.
A numeric operand is a previously defined numeric variable, an integer
literal, or a function. Spaces are accepted before, after and between any of
@@ -839,123 +818,121 @@ The syntax of a numeric substitution is
The supported operators are:
- * ``+`` - Returns the sum of its two operands.
- * ``-`` - Returns the difference of its two operands.
+> - `+` - Returns the sum of its two operands.
+> - `-` - Returns the difference of its two operands.
-The syntax of a function call is ``<name>(<arguments>)`` where:
+The syntax of a function call is `<name>(<arguments>)` where:
-* ``name`` is a predefined string literal. Accepted values are:
+- `name` is a predefined string literal. Accepted values are:
- * add - Returns the sum of its two operands.
- * div - Returns the quotient of its two operands.
- * max - Returns the largest of its two operands.
- * min - Returns the smallest of its two operands.
- * mul - Returns the product of its two operands.
- * sub - Returns the difference of its two operands.
+ - add - Returns the sum of its two operands.
+ - div - Returns the quotient of its two operands.
+ - max - Returns the largest of its two operands.
+ - min - Returns the smallest of its two operands.
+ - mul - Returns the product of its two operands.
+ - sub - Returns the difference of its two operands.
-* ``<arguments>`` is a comma separated list of expressions.
+- `<arguments>` is a comma separated list of expressions.
For example:
-.. code-block:: llvm
-
- ; CHECK: load r[[#REG:]], [r0]
- ; CHECK: load r[[#REG+1]], [r1]
- ; CHECK: Loading from 0x[[#%x,ADDR:]]
- ; CHECK-SAME: to 0x[[#ADDR + 7]]
+```llvm
+; CHECK: load r[[#REG:]], [r0]
+; CHECK: load r[[#REG+1]], [r1]
+; CHECK: Loading from 0x[[#%x,ADDR:]]
+; CHECK-SAME: to 0x[[#ADDR + 7]]
+```
The above example would match the text:
-.. code-block:: gas
-
- load r5, [r0]
- load r6, [r1]
- Loading from 0xa0463440 to 0xa0463447
+```gas
+load r5, [r0]
+load r6, [r1]
+Loading from 0xa0463440 to 0xa0463447
+```
but would not match the text:
-.. code-block:: gas
-
- load r5, [r0]
- load r7, [r1]
- Loading from 0xa0463440 to 0xa0463443
-
-Due to ``7`` being unequal to ``5 + 1`` and ``a0463443`` being unequal to
-``a0463440 + 7``.
+```gas
+load r5, [r0]
+load r7, [r1]
+Loading from 0xa0463440 to 0xa0463443
+```
+Due to `7` being unequal to `5 + 1` and `a0463443` being unequal to
+`a0463440 + 7`.
A numeric variable can also be defined to the result of a numeric expression,
in which case the numeric expression constraint is checked and if verified the
variable is assigned to the value. The unified syntax for both checking a
numeric expression and capturing its value into a numeric variable is thus
-``[[#%<fmtspec>,<NUMVAR>: <constraint> <expr>]]`` with each element as
+`[[#%<fmtspec>,<NUMVAR>: <constraint> <expr>]]` with each element as
described previously. One can use this syntax to make a testcase more
self-describing by using variables instead of values:
-.. code-block:: gas
-
- ; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]
- ; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]
+```gas
+; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]
+; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]
+```
which would match:
-.. code-block:: gas
-
- mov r4, 0xC
- load r6, [r5, r4]
+```gas
+mov r4, 0xC
+load r6, [r5, r4]
+```
-The ``--enable-var-scope`` option has the same effect on numeric variables as
+The `--enable-var-scope` option has the same effect on numeric variables as
on string variables.
Important note: In its current implementation, an expression cannot use a
numeric variable defined earlier in the same CHECK directive.
-FileCheck Pseudo Numeric Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### FileCheck Pseudo Numeric Variables
Sometimes there's a need to verify output that contains 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
+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 expressions understand the ``@LINE`` pseudo
+To support this case, FileCheck expressions understand the `@LINE` pseudo
numeric variable which evaluates to the line number of the CHECK pattern where
it is found.
This way match patterns can be put near the relevant test lines and include
relative line number references, for example:
-.. code-block:: c++
+```c++
+// CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
+// CHECK-NEXT: {{^int a}}
+// CHECK-NEXT: {{^ \^}}
+// CHECK-NEXT: {{^ ;}}
+int a
+```
- // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
- // CHECK-NEXT: {{^int a}}
- // CHECK-NEXT: {{^ \^}}
- // CHECK-NEXT: {{^ ;}}
- int a
+To support legacy uses of `@LINE` as a special string variable,
+{program}`FileCheck` also accepts the following uses of `@LINE` with string
+substitution block syntax: `[[@LINE]]`, `[[@LINE+<offset>]]` and
+`[[@LINE-<offset>]]` without any spaces inside the brackets and where
+`offset` is an integer.
-To support legacy uses of ``@LINE`` as a special string variable,
-:program:`FileCheck` also accepts the following uses of ``@LINE`` with string
-substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
-``[[@LINE-<offset>]]`` without any spaces inside the brackets and where
-``offset`` is an integer.
-
-Matching Newline Characters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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++
+`[[:space:]]` can be used. For example, the following pattern:
- // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
+```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
+```text
+DW_AT_location [DW_FORM_sec_offset] (0x00000233)
+DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")
+```
- 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`".
-letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value
-``0x00000233``, extracted from the line immediately preceding "``intd``".
diff --git a/llvm/docs/CommandGuide/clang-tblgen.md b/llvm/docs/CommandGuide/clang-tblgen.md
index 9a1ce8de0c361..e40f77426aa39 100644
--- a/llvm/docs/CommandGuide/clang-tblgen.md
+++ b/llvm/docs/CommandGuide/clang-tblgen.md
@@ -1,22 +1,21 @@
-clang-tblgen - Description to C++ Code for Clang
-================================================
+# clang-tblgen - Description to C++ Code for Clang
+```{eval-rst}
.. program:: clang-tblgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`clang-tblgen` [*options*] [*filename*]
+{program}`clang-tblgen` \[*options*\] \[*filename*\]
+## DESCRIPTION
-DESCRIPTION
------------
-
-:program:`clang-tblgen` is a program that translates compiler-related target
-description (``.td``) files into C++ code and other output formats. Most
+{program}`clang-tblgen` is a program that translates compiler-related target
+description (`.td`) files into C++ code and other output formats. Most
users of LLVM will not need to use this program. It is used only for writing
parts of the compiler.
-Please see :doc:`tblgen - Description to C++ Code<./tblgen>`
+Please see {doc}`tblgen - Description to C++ Code<./tblgen>`
for a description of the *filename* argument and options, including the
-options common to all :program:`*-tblgen` programs.
+options common to all {program}`*-tblgen` programs.
+
diff --git a/llvm/docs/CommandGuide/dsymutil.md b/llvm/docs/CommandGuide/dsymutil.md
index f9b0c5bdcd21a..52b260643dbf3 100644
--- a/llvm/docs/CommandGuide/dsymutil.md
+++ b/llvm/docs/CommandGuide/dsymutil.md
@@ -1,223 +1,222 @@
-dsymutil - manipulate archived DWARF debug symbol files
-=======================================================
+# dsymutil - manipulate archived DWARF debug symbol files
+```{eval-rst}
.. program:: dsymutil
+```
-SYNOPSIS
---------
+## SYNOPSIS
-| :program:`dsymutil` [*options*] *executable*
+{program}`dsymutil` \[*options*\] *executable*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`dsymutil` links the DWARF debug information found in the object files
+{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:: --accelerator=<accelerator type>
-
- Specify the desired type of accelerator table. Valid options are 'Apple',
- 'Dwarf', 'Default' and 'None'.
-
-.. option:: --allow <path>
-
- Only process debug map objects listed in the YAML file at <path>. Only filters
- N_OSO entries. If `--oso-prepend-path` is specified, the path prefix applies,
- i.e. paths in the file should exact match that of N_OSO entries.
-
-.. 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:: --build-variant-suffix <suffix=buildvariant>
-
- Specify the build variant suffix used to build the executable file.
- There can be multiple variants for the binary of a product, each built
- slightly differently. The most common build variants are 'debug' and
- 'profile'. Setting the DYLD_IMAGE_SUFFIX environment variable will
- cause dyld to load the specified variant at runtime.
-
-.. option:: --codesign <identity>
-
- Code sign the dSYM bundle with the given signing identity after linking.
- Cannot be used with :option:`--flat` or :option:`--no-output`.
-
-.. option:: --disallow <path>
-
- Exclude debug map objects listed in the YAML file at <path>. Only filters
- N_OSO entries. If `--oso-prepend-path` is specified, the path prefix applies,
- i.e. paths in the file should exact match that of N_OSO entries.
-
-.. 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. No DWARF link will take place.
-
- .. option:: -D <path>
-
- Specify a directory that contain dSYM files to search for.
- This is used for mergeable libraries, so dsymutil knows where to look
- for dSYM files with debug information about symbols present in those
- libraries.
-
-.. option:: --embed-resource <src-path>=<bundle-relative-path>
-
- Copy a file or directory into the dSYM bundle's ``Contents/Resources/``
- directory. The argument is ``<source-path>=<destination-relative-to-Resources>``.
- If the source is a directory, its contents are copied recursively. This option
- can be specified multiple times.
-
-.. option:: --fat64
-
- Use a 64-bit header when emitting universal binaries.
-
-.. option:: --flat, -f
-
- 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:: --gen-reproducer
-
- Generate a reproducer consisting of the input object files. Alias for
- --reproducer=GenerateOnExit.
-
-.. option:: --help, -h
-
- Print this help output.
-
-.. option:: --include-swiftmodules-from-interface
-
- Whether or not to copy binary swiftmodules built from textual .swiftinterface
- files into the dSYM bundle. These typically come only from the SDK (since
- textual interfaces require library evolution) and thus are a waste of space to
- copy into the bundle. Turn this on if the swiftmodules are different from
- those in the SDK.
-
-.. option:: --keep-function-for-static
-
- Make a static variable keep the enclosing function even if it would have been
- omitted otherwise.
-
-.. option:: --no-object-timestamp
-
- Don't check timestamp for object files.
-
-.. 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:: --num-threads <threads>, -j <threads>
-
- Specifies the maximum number (``n``) of simultaneous threads to use when
- linking multiple architectures.
-
-.. option:: --object-prefix-map <prefix=remapped>
-
- Remap object file paths (but no source paths) before processing. Use
- this for Clang objects where the module cache location was remapped using
- ``-fdebug-prefix-map``; to help dsymutil find the Clang module cache.
-
-.. option:: --oso-prepend-path <path>
-
- Specifies a ``path`` to prepend to all debug symbol object file paths.
-
-.. option:: --out <filename>, -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:: -q, --quiet
-
- Enable quiet mode and limit output.
-
-.. option:: --remarks-drop-without-debug
-
- Drop remarks without valid debug locations. Without this flags, all remarks are kept.
-
-.. option:: --remarks-output-format <format>
-
- Specify the format to be used when serializing the linked remarks.
-
-.. option:: --remarks-prepend-path <path>
-
- Specify a directory to prepend the paths of the external remark files.
-
-.. option:: --reproducer <mode>
-
- Specify the reproducer generation mode. Valid options are 'GenerateOnExit',
- 'GenerateOnCrash', 'Use', 'Off'.
-
-.. option:: --statistics
-
- Print statistics about the contribution of each object file to the linked
- debug info. This prints a table after linking with the object file name, the
- size of the debug info in the object file (in bytes) and the size contributed
- (in bytes) to the linked dSYM. The table is sorted by the output size listing
- the object files with the largest contribution first.
-
-.. option:: -s, --symtab
-
- Dumps the symbol table found in *executable* or object file(s) and exits.
-
-.. option:: -S
-
- Output textual assembly instead of a binary dSYM companion file.
-
-.. option:: --toolchain <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:: --use-reproducer <path>
-
- Use the object files from the given reproducer path. Alias for
- --reproducer=Use.
-
-.. option:: --verbose
-
- Display verbose information when linking.
-
-.. option:: --verify
-
- Run the DWARF verifier on the linked DWARF debug info.
-
-.. option:: -v, --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
+`.dSYM` bundle with the same name as the executable.
+
+## OPTIONS
+
+:::{option} --accelerator=<accelerator type>
+Specify the desired type of accelerator table. Valid options are 'Apple',
+'Dwarf', 'Default' and 'None'.
+:::
+
+:::{option} --allow <path>
+Only process debug map objects listed in the YAML file at \<path>. Only filters
+N_OSO entries. If `--oso-prepend-path` is specified, the path prefix applies,
+i.e. paths in the file should exact match that of N_OSO entries.
+:::
+
+:::{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} --build-variant-suffix <suffix=buildvariant>
+Specify the build variant suffix used to build the executable file.
+There can be multiple variants for the binary of a product, each built
+slightly differently. The most common build variants are 'debug' and
+'profile'. Setting the DYLD_IMAGE_SUFFIX environment variable will
+cause dyld to load the specified variant at runtime.
+:::
+
+:::{option} --codesign <identity>
+Code sign the dSYM bundle with the given signing identity after linking.
+Cannot be used with {option}`--flat` or {option}`--no-output`.
+:::
+
+:::{option} --disallow <path>
+Exclude debug map objects listed in the YAML file at \<path>. Only filters
+N_OSO entries. If `--oso-prepend-path` is specified, the path prefix applies,
+i.e. paths in the file should exact match that of N_OSO entries.
+:::
+
+::::{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. No DWARF link will take place.
+
+:::{option} -D <path>
+:::
+
+Specify a directory that contain dSYM files to search for.
+This is used for mergeable libraries, so dsymutil knows where to look
+for dSYM files with debug information about symbols present in those
+libraries.
+::::
+
+:::{option} --embed-resource <src-path>=<bundle-relative-path>
+Copy a file or directory into the dSYM bundle's `Contents/Resources/`
+directory. The argument is `<source-path>=<destination-relative-to-Resources>`.
+If the source is a directory, its contents are copied recursively. This option
+can be specified multiple times.
+:::
+
+:::{option} --fat64
+Use a 64-bit header when emitting universal binaries.
+:::
+
+:::{option} --flat, -f
+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} --gen-reproducer
+Generate a reproducer consisting of the input object files. Alias for
+--reproducer=GenerateOnExit.
+:::
+
+:::{option} --help, -h
+Print this help output.
+:::
+
+:::{option} --include-swiftmodules-from-interface
+Whether or not to copy binary swiftmodules built from textual .swiftinterface
+files into the dSYM bundle. These typically come only from the SDK (since
+textual interfaces require library evolution) and thus are a waste of space to
+copy into the bundle. Turn this on if the swiftmodules are different from
+those in the SDK.
+:::
+
+:::{option} --keep-function-for-static
+Make a static variable keep the enclosing function even if it would have been
+omitted otherwise.
+:::
+
+:::{option} --no-object-timestamp
+Don't check timestamp for object files.
+:::
+
+:::{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} --num-threads <threads>, -j <threads>
+Specifies the maximum number (`n`) of simultaneous threads to use when
+linking multiple architectures.
+:::
+
+:::{option} --object-prefix-map <prefix=remapped>
+Remap object file paths (but no source paths) before processing. Use
+this for Clang objects where the module cache location was remapped using
+`-fdebug-prefix-map`; to help dsymutil find the Clang module cache.
+:::
+
+:::{option} --oso-prepend-path <path>
+Specifies a `path` to prepend to all debug symbol object file paths.
+:::
+
+:::{option} --out <filename>, -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} -q, --quiet
+Enable quiet mode and limit output.
+:::
+
+:::{option} --remarks-drop-without-debug
+Drop remarks without valid debug locations. Without this flags, all remarks are kept.
+:::
+
+:::{option} --remarks-output-format <format>
+Specify the format to be used when serializing the linked remarks.
+:::
+
+:::{option} --remarks-prepend-path <path>
+Specify a directory to prepend the paths of the external remark files.
+:::
+
+:::{option} --reproducer <mode>
+Specify the reproducer generation mode. Valid options are 'GenerateOnExit',
+'GenerateOnCrash', 'Use', 'Off'.
+:::
+
+:::{option} --statistics
+Print statistics about the contribution of each object file to the linked
+debug info. This prints a table after linking with the object file name, the
+size of the debug info in the object file (in bytes) and the size contributed
+(in bytes) to the linked dSYM. The table is sorted by the output size listing
+the object files with the largest contribution first.
+:::
+
+:::{option} -s, --symtab
+Dumps the symbol table found in *executable* or object file(s) and exits.
+:::
+
+:::{option} -S
+Output textual assembly instead of a binary dSYM companion file.
+:::
+
+:::{option} --toolchain <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} --use-reproducer <path>
+Use the object files from the given reproducer path. Alias for
+--reproducer=Use.
+:::
+
+:::{option} --verbose
+Display verbose information when linking.
+:::
+
+:::{option} --verify
+Run the DWARF verifier on the linked DWARF debug info.
+:::
+
+:::{option} -v, --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
---------
+## SEE ALSO
+
+{manpage}`llvm-dwarfdump(1)`
-:manpage:`llvm-dwarfdump(1)`
diff --git a/llvm/docs/CommandGuide/lit.md b/llvm/docs/CommandGuide/lit.md
index b52a09eb088a1..2c564791f6802 100644
--- a/llvm/docs/CommandGuide/lit.md
+++ b/llvm/docs/CommandGuide/lit.md
@@ -1,798 +1,773 @@
-lit - LLVM Integrated Tester
-============================
+# lit - LLVM Integrated Tester
+```{eval-rst}
.. program:: lit
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`lit` [*options*] [*tests*]
+{program}`lit` \[*options*\] \[*tests*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`lit` is a portable tool for executing LLVM and Clang style test
+{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
+{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`).
+{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 concurrently) 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
+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.
+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.
+{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
+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.
+{ref}`selection-options` for more information.
-:program:`lit` parses options from the environment variable ``LIT_OPTS`` after
-parsing options from the command line. ``LIT_OPTS`` is primarily useful for
-supplementing or overriding the command-line options supplied to :program:`lit`
-by ``check`` targets defined by a project's build system.
+{program}`lit` parses options from the environment variable `LIT_OPTS` after
+parsing options from the command line. `LIT_OPTS` is primarily useful for
+supplementing or overriding the command-line options supplied to {program}`lit`
+by `check` targets defined by a project's build system.
-:program:`lit` can also read options from response files which are specified as
-inputs using the ``@path/to/file.rsp`` syntax. Arguments read from a file must
+{program}`lit` can also read options from response files which are specified as
+inputs using the `@path/to/file.rsp` syntax. Arguments read from a file must
be one per line and are treated as if they were in the same place as the
original file referencing argument on the command line. A response file can
reference other response files.
-Users interested in the :program:`lit` architecture or designing a
-:program:`lit` testing implementation should see :ref:`lit-infrastructure`.
+Users interested in the {program}`lit` architecture or designing a
+{program}`lit` testing implementation should see {ref}`lit-infrastructure`.
-GENERAL OPTIONS
----------------
+## GENERAL OPTIONS
-.. option:: -h, --help
+:::{option} -h, --help
+Show the {program}`lit` help message and exit.
+:::
- Show the :program:`lit` help message and exit.
+:::{option} --version
+Show {program}`lit`'s version number and exit.
+:::
-.. option:: --version
+:::{option} -j N, --workers N
+Run `N` tests in parallel. By default, this is automatically chosen to
+match the number of detected available CPUs.
+:::
- Show :program:`lit`'s version number and exit.
+:::{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:: -j N, --workers N
+:::{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.
+:::
- Run ``N`` tests in parallel. By default, this is automatically chosen to
- match the number of detected available CPUs.
+(output-options)=
-.. option:: --config-prefix NAME
+## OUTPUT OPTIONS
- 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} -q, --quiet
+Suppress any output except for test failures.
+:::
-.. option:: -D NAME[=VALUE], --param NAME[=VALUE]
+:::{option} -s, --succinct
+Show less output, for example don't show information on tests that pass.
+Also show a progress bar, unless `--no-progress-bar` is specified.
+:::
- 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.
+:::{option} -v, --verbose
+Show more information on test failures, for example the entire test output
+instead of just the test result.
-.. _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.
- Also show a progress bar, unless ``--no-progress-bar`` is specified.
-
-.. option:: -v, --verbose
-
- Show more information on test failures, for example the entire test output
- instead of just the test result.
-
- Each command is printed before it is executed. This can be valuable for
- debugging test failures, as the last printed command is the one that failed.
- Moreover, :program:`lit` inserts ``'RUN: at line N'`` after each
- command pipeline in the output to help you locate the source line of
- the failed command.
-
-.. option:: -vv, --echo-all-commands
-
- Deprecated alias for -v.
-
-.. option:: -a, --show-all
-
- Enable -v, but for all tests not just failed tests.
-
-.. option:: -o PATH, --output PATH
-
- Write test results to the provided path.
-
-.. option:: --no-progress-bar
-
- Do not use curses based progress bar.
-
-.. option:: --min-output-interval INTERVAL
-
- Only output updates to the progress bar and status line at most once per
- INTERVAL seconds. Has no effect if the curses based progress bar is not used.
-
-.. option:: --show-excluded
-
- Show excluded tests.
-
-.. option:: --show-skipped
-
- Show skipped tests.
-
-.. option:: --show-unsupported
-
- Show unsupported tests.
-
-.. option:: --show-pass
-
- Show passed tests.
-
-.. option:: --show-flakypass
-
- Show passed with retry tests.
-
-.. option:: --show-xfail
-
- Show expectedly failed tests.
-
-.. _execution-options:
-
-EXECUTION OPTIONS
------------------
-
-.. option:: --gtest-sharding
-
- Enable sharding for GoogleTest format.
-
-.. option:: --no-gtest-sharding
-
- Disable sharding for GoogleTest format.
-
-.. option:: --path PATH
-
- Specify an additional ``PATH`` to use when searching for executables in tests.
-
-.. option:: --pass-env NAME
-
- Pass the environment variable ``NAME`` through to the test environment, in
- addition to the built-in allow-list of variables that are always passed
- through. May be specified multiple times to pass through several variables.
-
-.. 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-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:: --vg-arg ARG
-
- When :option:`--vg` is used, specify an additional argument to pass to
- :program:`valgrind` itself.
-
-.. option:: --no-execute
-
- Don't execute any tests (assume that they pass).
-
-.. option:: --xunit-xml-output XUNIT_XML_OUTPUT
-
- Write XUnit-compatible XML test reports to the specified file.
-
-.. option:: --report-failures-only
-
- Only include failures (see :ref:`test-status-results`) in the report.
-
-.. option:: --resultdb-output RESULTDB_OUTPUT
-
- Write LuCI ResultDB compatible JSON to the specified file.
-
-.. option:: --time-trace-output TIME_TRACE_OUTPUT
-
- Write Chrome tracing compatible JSON to the specified file
-
-.. option:: --timeout MAXINDIVIDUALTESTTIME
-
- Maximum time to spend running a single test (in seconds). 0 means no time
- limit. [Default: 0]
-
-.. option:: --timeout N
-
- Spend at most ``N`` seconds (approximately) running each individual test.
- ``0`` means no time limit, and ``0`` is the default. Note that this is not an
- alias for :option:`--max-time`; the two are different kinds of maximums.
-
-.. option:: --max-failures MAX_FAILURES
-
- Stop execution after the given number of failures.
-
-.. option:: --max-retries-per-test N
-
- Retry running failed tests at most ``N`` times.
- Out of the following options to rerun failed tests the
- :option:`--max-retries-per-test` is the only one that doesn't
- require a change in the test scripts or the test config:
-
- * :option:`--max-retries-per-test` lit option
- * ``config.test_retry_attempts`` test suite option
- * ``ALLOW_RETRIES:`` annotation in test script
-
- Any option in the list above overrules its predecessor.
-
-.. option:: --allow-empty-runs
-
- Do not fail the run if all tests are filtered out.
-
-.. option:: --per-test-coverage
-
- Emit the necessary test coverage data, divided per test case (involves
- setting a unique value to LLVM_PROFILE_FILE for each RUN). The coverage
- data files will be emitted in the directory specified by ``config.test_exec_root``.
-
-.. option:: --ignore-fail
-
- Exit with status zero even if some tests fail.
-
-.. option:: --skip-test-time-recording
-
- Do not track elapsed wall time for each test.
-
-.. option:: --time-tests[=N|all]
-
- Track the wall time individual tests take to execute and include the results
- in the summary output. This is useful for determining which tests in a test
- suite take the most time to execute. When enabled, lit prints a slowest-test
- list and a histogram over all timed tests. The slowest-test list defaults to
- the 20 slowest tests, but can be limited with ``=N`` or expanded to every
- timed test with ``=all``. The headings report how many tests are listed, for
- example ``Slowest Tests (N of M):`` and ``Test Times (M):``.
-
-.. _selection-options:
-
-SELECTION OPTIONS
------------------
+Each command is printed before it is executed. This can be valuable for
+debugging test failures, as the last printed command is the one that failed.
+Moreover, {program}`lit` inserts `'RUN: at line N'` after each
+command pipeline in the output to help you locate the source line of
+the failed command.
+:::
+
+:::{option} -vv, --echo-all-commands
+Deprecated alias for -v.
+:::
+
+:::{option} -a, --show-all
+Enable -v, but for all tests not just failed tests.
+:::
+
+:::{option} -o PATH, --output PATH
+Write test results to the provided path.
+:::
+
+:::{option} --no-progress-bar
+Do not use curses based progress bar.
+:::
+
+:::{option} --min-output-interval INTERVAL
+Only output updates to the progress bar and status line at most once per
+INTERVAL seconds. Has no effect if the curses based progress bar is not used.
+:::
+
+:::{option} --show-excluded
+Show excluded tests.
+:::
+
+:::{option} --show-skipped
+Show skipped tests.
+:::
+
+:::{option} --show-unsupported
+Show unsupported tests.
+:::
+
+:::{option} --show-pass
+Show passed tests.
+:::
+
+:::{option} --show-flakypass
+Show passed with retry tests.
+:::
+
+:::{option} --show-xfail
+Show expectedly failed tests.
+:::
+
+(execution-options)=
+
+## EXECUTION OPTIONS
+
+:::{option} --gtest-sharding
+Enable sharding for GoogleTest format.
+:::
+
+:::{option} --no-gtest-sharding
+Disable sharding for GoogleTest format.
+:::
+
+:::{option} --path PATH
+Specify an additional `PATH` to use when searching for executables in tests.
+:::
+
+:::{option} --pass-env NAME
+Pass the environment variable `NAME` through to the test environment, in
+addition to the built-in allow-list of variables that are always passed
+through. May be specified multiple times to pass through several variables.
+:::
+
+:::{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-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} --vg-arg ARG
+When {option}`--vg` is used, specify an additional argument to pass to
+{program}`valgrind` itself.
+:::
+
+:::{option} --no-execute
+Don't execute any tests (assume that they pass).
+:::
+
+:::{option} --xunit-xml-output XUNIT_XML_OUTPUT
+Write XUnit-compatible XML test reports to the specified file.
+:::
+
+:::{option} --report-failures-only
+Only include failures (see {ref}`test-status-results`) in the report.
+:::
+
+:::{option} --resultdb-output RESULTDB_OUTPUT
+Write LuCI ResultDB compatible JSON to the specified file.
+:::
+
+:::{option} --time-trace-output TIME_TRACE_OUTPUT
+Write Chrome tracing compatible JSON to the specified file
+:::
+
+:::{option} --timeout MAXINDIVIDUALTESTTIME
+Maximum time to spend running a single test (in seconds). 0 means no time
+limit. [Default: 0]
+:::
+
+:::{option} --timeout N
+Spend at most `N` seconds (approximately) running each individual test.
+`0` means no time limit, and `0` is the default. Note that this is not an
+alias for {option}`--max-time`; the two are different kinds of maximums.
+:::
+
+:::{option} --max-failures MAX_FAILURES
+Stop execution after the given number of failures.
+:::
+
+:::{option} --max-retries-per-test N
+Retry running failed tests at most `N` times.
+Out of the following options to rerun failed tests the
+{option}`--max-retries-per-test` is the only one that doesn't
+require a change in the test scripts or the test config:
+
+> - {option}`--max-retries-per-test` lit option
+> - `config.test_retry_attempts` test suite option
+> - `ALLOW_RETRIES:` annotation in test script
+
+Any option in the list above overrules its predecessor.
+:::
+
+:::{option} --allow-empty-runs
+Do not fail the run if all tests are filtered out.
+:::
+
+:::{option} --per-test-coverage
+Emit the necessary test coverage data, divided per test case (involves
+setting a unique value to LLVM_PROFILE_FILE for each RUN). The coverage
+data files will be emitted in the directory specified by `config.test_exec_root`.
+:::
+
+:::{option} --ignore-fail
+Exit with status zero even if some tests fail.
+:::
+
+:::{option} --skip-test-time-recording
+Do not track elapsed wall time for each test.
+:::
+
+:::{option} --time-tests[=N|all]
+Track the wall time individual tests take to execute and include the results
+in the summary output. This is useful for determining which tests in a test
+suite take the most time to execute. When enabled, lit prints a slowest-test
+list and a histogram over all timed tests. The slowest-test list defaults to
+the 20 slowest tests, but can be limited with `=N` or expanded to every
+timed test with `=all`. The headings report how many tests are listed, for
+example `Slowest Tests (N of M):` and `Test Times (M):`.
+:::
+
+(selection-options)=
+
+## SELECTION OPTIONS
By default, `lit` will run failing tests first, then run tests in descending
-execution time order to optimize concurrency. The execution order can be
-changed using the :option:`--order` option.
+execution time order to optimize concurrency. The execution order can be
+changed using the {option}`--order` option.
The timing data is stored in the `test_exec_root` in a file named
`.lit_test_times.txt`. If this file does not exist, then `lit` checks the
`test_source_root` for the file to optionally accelerate clean builds.
-.. 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.
- Note that this is not an alias for :option:`--timeout`; the two are
- different kinds of maximums.
-
-.. option:: --order {lexical,random,smart}
-
- Define the order in which tests are run. The supported values are:
-
- - lexical - tests will be run in lexical order according to the test file
- path. This option is useful when predictable test order is desired.
-
- - random - tests will be run in random order.
-
- - smart - tests that failed previously will be run first, then the remaining
- tests, all in descending execution time order. This is the default as it
- optimizes concurrency.
-
-.. option:: --shuffle
-
- Run the tests in a random order, not failing/slowest first. Deprecated,
- use :option:`--order` instead.
-
-.. option:: -i, --incremental
-
- Run failed tests first (DEPRECATED: use ``--order=smart``).
-
-.. 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.
-
-.. option:: --filter-out REGEXP
-
- Filter out those tests whose name matches the regular expression specified in
- ``REGEXP``. The environment variable ``LIT_FILTER_OUT`` can be also used in
- place of this option, which is especially useful in environments where the
- call to ``lit`` is issued indirectly.
-
-.. option:: --filter-failed
-
- Run only those tests that previously failed. Tests that have been newly added
- but not yet run are not included.
-
-.. option:: --xfail LIST
-
- Treat those tests whose name is in the semicolon separated list ``LIST`` as
- ``XFAIL``. This can be helpful when one does not want to modify the test
- suite. The environment variable ``LIT_XFAIL`` can be also used in place of
- this option, which is especially useful in environments where the call to
- ``lit`` is issued indirectly.
-
- A test name can specified as a file name relative to the test suite directory.
- For example:
-
- .. code-block:: none
-
- LIT_XFAIL="affinity/kmp-hw-subset.c;offloading/memory_manager.cpp"
-
- In this case, all of the following tests are treated as ``XFAIL``:
-
- .. code-block:: none
-
- libomp :: affinity/kmp-hw-subset.c
- libomptarget :: nvptx64-nvidia-cuda :: offloading/memory_manager.cpp
- libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp
-
- Alternatively, a test name can be specified as the full test name
- reported in LIT output. For example, we can adjust the previous
- example not to treat the ``nvptx64-nvidia-cuda`` version of
- ``offloading/memory_manager.cpp`` as XFAIL:
-
- .. code-block:: none
-
- LIT_XFAIL="affinity/kmp-hw-subset.c;libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp"
-
-.. option:: --xfail-not LIST
-
- Do not treat the specified tests as ``XFAIL``. The environment variable
- ``LIT_XFAIL_NOT`` can also be used in place of this option. The syntax is the
- same as for :option:`--xfail` and ``LIT_XFAIL``. :option:`--xfail-not` and
- ``LIT_XFAIL_NOT`` always override all other ``XFAIL`` specifications,
- including an :option:`--xfail` appearing later on the command line. The
- primary purpose is to suppress an ``XPASS`` result without modifying a test
- case that uses the ``XFAIL`` directive.
-
-.. option:: --unsupported LIST
-
- Treat those tests whose name is in the semicolon separated list ``LIST`` as
- ``UNSUPPORTED``. This can be helpful when one does not want to modify the test
- suite. The environment variable ``LIT_UNSUPPORTED`` can be also used in place
- of this option, which is especially useful in environments where the call to
- ``lit`` is issued indirectly.
-
- The syntax for specifying test names is the same as for :option:`--xfail` and
- ``LIT_XFAIL``. A test name can be specified as a file name relative to the
- test suite directory or as the full test name reported in LIT output.
-
-.. option:: --unsupported-not LIST
-
- Do not treat the specified tests as ``UNSUPPORTED``. The environment variable
- ``LIT_UNSUPPORTED_NOT`` can also be used in place of this option. The syntax
- is the same as for :option:`--unsupported` and ``LIT_UNSUPPORTED``.
- :option:`--unsupported-not` and ``LIT_UNSUPPORTED_NOT`` always override all
- other ``UNSUPPORTED`` specifications, including an :option:`--unsupported`
- appearing later on the command line.
-
-.. option:: --exclude-xfail
-
- ``XFAIL`` tests won't be run, unless they are listed in the ``--xfail-not``
- (or ``LIT_XFAIL_NOT``) lists.
-
-.. 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 partitioning 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.
-
-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.
-
-.. option:: --show-used-features
-
- Show all features used in the test suite (in ``XFAIL``, ``UNSUPPORTED`` and
- ``REQUIRES``) and exit.
-
-.. option:: --update-tests
-
- Pass failing tests to functions in the ``lit_config.test_updaters`` list to
- check whether any of them know how to update the test to make it pass.
-
-EXIT STATUS
------------
-
-:program:`lit` will exit with an exit code of 1 if there are any failures
-(see :ref:`test-status-results`) and :option:`--ignore-fail` has not been
-passed. Otherwise, it will exit with the status 0. Other exit codes are used
+:::{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.
+Note that this is not an alias for {option}`--timeout`; the two are
+different kinds of maximums.
+:::
+
+:::{option} --order {lexical,random,smart}
+Define the order in which tests are run. The supported values are:
+
+- lexical - tests will be run in lexical order according to the test file
+ path. This option is useful when predictable test order is desired.
+- random - tests will be run in random order.
+- smart - tests that failed previously will be run first, then the remaining
+ tests, all in descending execution time order. This is the default as it
+ optimizes concurrency.
+:::
+
+:::{option} --shuffle
+Run the tests in a random order, not failing/slowest first. Deprecated,
+use {option}`--order` instead.
+:::
+
+:::{option} -i, --incremental
+Run failed tests first (DEPRECATED: use `--order=smart`).
+:::
+
+:::{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.
+:::
+
+:::{option} --filter-out REGEXP
+Filter out those tests whose name matches the regular expression specified in
+`REGEXP`. The environment variable `LIT_FILTER_OUT` can be also used in
+place of this option, which is especially useful in environments where the
+call to `lit` is issued indirectly.
+:::
+
+:::{option} --filter-failed
+Run only those tests that previously failed. Tests that have been newly added
+but not yet run are not included.
+:::
+
+:::{option} --xfail LIST
+Treat those tests whose name is in the semicolon separated list `LIST` as
+`XFAIL`. This can be helpful when one does not want to modify the test
+suite. The environment variable `LIT_XFAIL` can be also used in place of
+this option, which is especially useful in environments where the call to
+`lit` is issued indirectly.
+
+A test name can specified as a file name relative to the test suite directory.
+For example:
+
+```none
+LIT_XFAIL="affinity/kmp-hw-subset.c;offloading/memory_manager.cpp"
+```
+
+In this case, all of the following tests are treated as `XFAIL`:
+
+```none
+libomp :: affinity/kmp-hw-subset.c
+libomptarget :: nvptx64-nvidia-cuda :: offloading/memory_manager.cpp
+libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp
+```
+
+Alternatively, a test name can be specified as the full test name
+reported in LIT output. For example, we can adjust the previous
+example not to treat the `nvptx64-nvidia-cuda` version of
+`offloading/memory_manager.cpp` as XFAIL:
+
+```none
+LIT_XFAIL="affinity/kmp-hw-subset.c;libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp"
+```
+:::
+
+:::{option} --xfail-not LIST
+Do not treat the specified tests as `XFAIL`. The environment variable
+`LIT_XFAIL_NOT` can also be used in place of this option. The syntax is the
+same as for {option}`--xfail` and `LIT_XFAIL`. {option}`--xfail-not` and
+`LIT_XFAIL_NOT` always override all other `XFAIL` specifications,
+including an {option}`--xfail` appearing later on the command line. The
+primary purpose is to suppress an `XPASS` result without modifying a test
+case that uses the `XFAIL` directive.
+:::
+
+:::{option} --unsupported LIST
+Treat those tests whose name is in the semicolon separated list `LIST` as
+`UNSUPPORTED`. This can be helpful when one does not want to modify the test
+suite. The environment variable `LIT_UNSUPPORTED` can be also used in place
+of this option, which is especially useful in environments where the call to
+`lit` is issued indirectly.
+
+The syntax for specifying test names is the same as for {option}`--xfail` and
+`LIT_XFAIL`. A test name can be specified as a file name relative to the
+test suite directory or as the full test name reported in LIT output.
+:::
+
+:::{option} --unsupported-not LIST
+Do not treat the specified tests as `UNSUPPORTED`. The environment variable
+`LIT_UNSUPPORTED_NOT` can also be used in place of this option. The syntax
+is the same as for {option}`--unsupported` and `LIT_UNSUPPORTED`.
+{option}`--unsupported-not` and `LIT_UNSUPPORTED_NOT` always override all
+other `UNSUPPORTED` specifications, including an {option}`--unsupported`
+appearing later on the command line.
+:::
+
+:::{option} --exclude-xfail
+`XFAIL` tests won't be run, unless they are listed in the `--xfail-not`
+(or `LIT_XFAIL_NOT`) lists.
+:::
+
+:::{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 partitioning 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.
+:::
+
+## 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.
+:::
+
+:::{option} --show-used-features
+Show all features used in the test suite (in `XFAIL`, `UNSUPPORTED` and
+`REQUIRES`) and exit.
+:::
+
+:::{option} --update-tests
+Pass failing tests to functions in the `lit_config.test_updaters` list to
+check whether any of them know how to update the test to make it pass.
+:::
+
+## EXIT STATUS
+
+{program}`lit` will exit with an exit code of 1 if there are any failures
+(see {ref}`test-status-results`) and {option}`--ignore-fail` has not been
+passed. 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)=
-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
+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
+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
+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
+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)=
-TEST STATUS RESULTS
--------------------
+## TEST STATUS RESULTS
Each test ultimately produces one of the following eight results:
**PASS**
- The test succeeded.
+> The test succeeded.
**FLAKYPASS**
- The test succeeded after being re-run more than once. This only applies to
- tests containing an ``ALLOW_RETRIES:`` annotation.
+> The test succeeded after being re-run more than once. This only applies to
+> tests containing an `ALLOW_RETRIES:` annotation.
**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.
+> 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).
+> 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.
+> 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.
+> 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.
+> The test is not supported in this environment. This is used by test formats
+> which can report unsupported tests.
**TIMEOUT**
- The test was run, but it timed out before it was able to complete.
+> The test was run, but it timed out before it was able to complete.
Unresolved (**UNRESOLVED**), timed out (**TIMEOUT**), failed (**FAIL**) and
unexpectedly passed (**XPASS**) tests are considered failures.
Depending on the test format tests may produce additional information about
-their status (generally only for failures). See the :ref:`output-options`
+their status (generally only for failures). See the {ref}`output-options`
section for more information.
-.. _lit-infrastructure:
+(lit-infrastructure)=
-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 {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
+{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
+tests. {program}`lit` itself doesn't know how to run tests, rather this logic is
defined by *test suites*.
-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
+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
+{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.
+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_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.
+> 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.
-
- **standalone_tests** When true, mark a directory with tests expected to be run
- standalone. Test discovery is disabled for that directory. *lit.suffixes* and
- *lit.excludes* must be empty when this variable is true.
-
- **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`
+> 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.
+>
+> **standalone_tests** When true, mark a directory with tests expected to be run
+> standalone. Test discovery is disabled for that directory. *lit.suffixes* and
+> *lit.excludes* must be empty when this variable is true.
+>
+> **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,
+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`).
+{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
+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)=
-LOCAL CONFIGURATION FILES
-~~~~~~~~~~~~~~~~~~~~~~~~~
+### LOCAL CONFIGURATION FILES
-When :program:`lit` loads a subdirectory in a test suite, it instantiates a
+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
+--- 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.
-SUBSTITUTIONS
-~~~~~~~~~~~~~
+### SUBSTITUTIONS
-:program:`lit` allows patterns to be substituted inside RUN commands. It also
+{program}`lit` allows patterns to be substituted inside RUN commands. It also
provides the following base set of substitutions, which are defined in
TestRunner.py:
- ======================= ==============
- 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
- %{fs-src-root} root component of file system paths pointing to the LLVM checkout
- %{fs-tmp-root} root component of file system paths pointing to the test's temporary directory
- %{fs-sep} file system path separator
- %t a path unique to the test (which may be used to make files or directories)
- %basename_t The last path component of %t but without the ``.tmp`` extension (deprecated, use ``%{t:stem}`` instead)
- %% %
- %/s %s but ``\`` is replaced by ``/``
- %/S %S but ``\`` is replaced by ``/``
- %/p %p but ``\`` is replaced by ``/``
- %/t %t but ``\`` is replaced by ``/``
- %{s:basename} The last path component of %s
- %{s:stem} The last path component of %s but with the last extension removed.
- %{t:stem} The last path component of %t but without the ``.tmp`` extension (alias for %basename_t)
- %{s:real} %s after expanding all symbolic links and substitute drives
- %{S:real} %S after expanding all symbolic links and substitute drives
- %{p:real} %p after expanding all symbolic links and substitute drives
- %{t:real} %t after expanding all symbolic links and substitute drives
- %{/s:real} %/s after expanding all symbolic links and substitute drives
- %{/S:real} %/S after expanding all symbolic links and substitute drives
- %{/p:real} %/p after expanding all symbolic links and substitute drives
- %{/t:real} %/t after expanding all symbolic links and substitute drives
- %{/s:regex_replacement} %/s but escaped for use in the replacement of a ``s@@@`` command in sed
- %{/S:regex_replacement} %/S but escaped for use in the replacement of a ``s@@@`` command in sed
- %{/p:regex_replacement} %/p but escaped for use in the replacement of a ``s@@@`` command in sed
- %{/t:regex_replacement} %/t but escaped for use in the replacement of a ``s@@@`` command in sed
- %:s On Windows, %/s but a ``:`` is removed if its the second character.
- Otherwise, %s but with a single leading ``/`` removed.
- %:S On Windows, %/S but a ``:`` is removed if its the second character.
- Otherwise, %S but with a single leading ``/`` removed.
- %:p On Windows, %/p but a ``:`` is removed if its the second character.
- Otherwise, %p but with a single leading ``/`` removed.
- %:t On Windows, %/t but a ``:`` is removed if its the second character.
- Otherwise, %t but with a single leading ``/`` removed.
- %{readfile:<filename>} Reads the file specified.
- ======================= ==============
+> | 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 |
+> | %\{fs-src-root} | root component of file system paths pointing to the LLVM checkout |
+> | %\{fs-tmp-root} | root component of file system paths pointing to the test's temporary directory |
+> | %\{fs-sep} | file system path separator |
+> | %t | a path unique to the test (which may be used to make files or directories) |
+> | %basename_t | The last path component of %t but without the `.tmp` extension (deprecated, use `%{t:stem}` instead) |
+> | %% | % |
+> | %/s | %s but `\` is replaced by `/` |
+> | %/S | %S but `\` is replaced by `/` |
+> | %/p | %p but `\` is replaced by `/` |
+> | %/t | %t but `\` is replaced by `/` |
+> | %\{s:basename} | The last path component of %s |
+> | %\{s:stem} | The last path component of %s but with the last extension removed. |
+> | %\{t:stem} | The last path component of %t but without the `.tmp` extension (alias for %basename_t) |
+> | %\{s:real} | %s after expanding all symbolic links and substitute drives |
+> | %\{S:real} | %S after expanding all symbolic links and substitute drives |
+> | %\{p:real} | %p after expanding all symbolic links and substitute drives |
+> | %\{t:real} | %t after expanding all symbolic links and substitute drives |
+> | %{/s:real} | %/s after expanding all symbolic links and substitute drives |
+> | %{/S:real} | %/S after expanding all symbolic links and substitute drives |
+> | %{/p:real} | %/p after expanding all symbolic links and substitute drives |
+> | %{/t:real} | %/t after expanding all symbolic links and substitute drives |
+> | %{/s:regex_replacement} | %/s but escaped for use in the replacement of a `s@@@` command in sed |
+> | %{/S:regex_replacement} | %/S but escaped for use in the replacement of a `s@@@` command in sed |
+> | %{/p:regex_replacement} | %/p but escaped for use in the replacement of a `s@@@` command in sed |
+> | %{/t:regex_replacement} | %/t but escaped for use in the replacement of a `s@@@` command in sed |
+> | %:s | On Windows, %/s but a `:` is removed if its the second character. Otherwise, %s but with a single leading `/` removed. |
+> | %:S | On Windows, %/S but a `:` is removed if its the second character. Otherwise, %S but with a single leading `/` removed. |
+> | %:p | On Windows, %/p but a `:` is removed if its the second character. Otherwise, %p but with a single leading `/` removed. |
+> | %:t | On Windows, %/t but a `:` is removed if its the second character. Otherwise, %t but with a single leading `/` removed. |
+> | %{readfile:\<filename>} | Reads the file specified. |
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`.
+modules {ref}`local-configuration-files`.
More detailed information on substitutions can be found in the
-:doc:`../TestingGuide`.
+{doc}`../TestingGuide`.
-TEST RUN OUTPUT FORMAT
-~~~~~~~~~~~~~~~~~~~~~~
+### TEST RUN OUTPUT FORMAT
-The :program:`lit` output for a test run conforms to the following schema, in
+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
+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>)
+```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
+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
+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.
-Should a test be allowed retries (see ``ALLOW_RETRIES:`` annotation) and it
-needed more than one attempt to succeed, then ``<progress info>`` is extended
+Should a test be allowed retries (see `ALLOW_RETRIES:` annotation) and it
+needed more than one attempt to succeed, then `<progress info>` is extended
by this information:
-.. code-block:: none
-
- , <num_attempts_made> of <max_allowed_attempts> attempts
+```none
+, <num_attempts_made> of <max_allowed_attempts> attempts
+```
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>
+```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
+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
+```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)
+```
- 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)
+### DEFAULT FEATURES
-DEFAULT FEATURES
-~~~~~~~~~~~~~~~~~
-
-For convenience :program:`lit` automatically adds **available_features** for
+For convenience {program}`lit` automatically adds **available_features** for
some common use cases.
-:program:`lit` adds a feature based on the operating system being built on, for
-example: `system-darwin`, `system-linux`, etc. :program:`lit` also
+{program}`lit` adds a feature based on the operating system being built on, for
+example: `system-darwin`, `system-linux`, etc. {program}`lit` also
automatically adds a feature based on the current architecture, for example
`target-x86_64`, `target-aarch64`, etc.
-When building with sanitizers enabled, :program:`lit` automatically adds the
+When building with sanitizers enabled, {program}`lit` automatically adds the
short name of the sanitizer, for example: `asan`, `tsan`, etc.
To see the full list of features that can be added, see
*llvm/utils/lit/lit/llvm/config.py*.
-LIT EXAMPLE TESTS
-~~~~~~~~~~~~~~~~~
+### LIT EXAMPLE TESTS
-The :program:`lit` distribution contains several example implementations of
+The {program}`lit` distribution contains several example implementations of
test suites in the *ExampleTests* directory.
-SEE ALSO
---------
+## SEE ALSO
valgrind(1)
+
diff --git a/llvm/docs/CommandGuide/llc.md b/llvm/docs/CommandGuide/llc.md
index fdd12f3fbdb89..e7ff0b4fab7fe 100644
--- a/llvm/docs/CommandGuide/llc.md
+++ b/llvm/docs/CommandGuide/llc.md
@@ -1,231 +1,225 @@
-llc - LLVM static compiler
-==========================
+# llc - LLVM static compiler
+```{eval-rst}
.. program:: llc
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llc` [*options*] [*filename*]
+{program}`llc` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llc` command compiles LLVM source inputs into assembly language
-for a specified architecture. The assembly language output can then be passed
+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
+determined from the input file, unless the {option}`-march` option is used to
override the default.
-OPTIONS
--------
+## OPTIONS
+
+If `filename` is "`-`" or omitted, {program}`llc` reads from standard input.
+Otherwise, it will read 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} -M
+Pass target-specific InstPrinter options.
+Refer to the `-M` option of {manpage}`llvm-objdump(1)`.
+:::
+
+:::{option} -o <filename>
+Use `<filename>` as the output filename. See the summary above for more
+details.
+:::
+
+:::{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:
+
+```none
+llvm-as < /dev/null | llc -march=xyz -mcpu=help
+```
+:::
+
+:::{option} -mtune=<cpuname>
+Specify a specific chip microarchitecture in the current architecture
+to tune code for. By default this is inferred from the target triple and
+autodetected to the current architecture. For a list of available tuning
+CPUs, use:
+
+```none
+llvm-as < /dev/null | llc -march=xyz -mtune=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).
-If ``filename`` is "``-``" or omitted, :program:`llc` reads from standard input.
-Otherwise, it will read from ``filename``. Inputs can be in either the LLVM
-assembly language format (``.ll``) or the LLVM bitcode format (``.bc``).
+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:
-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.
+```none
+llvm-as < /dev/null | llc -march=xyz -mattr=help
+```
+:::
-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.
+:::{option} --frame-pointer
+Specify effect of frame pointer elimination optimization (all,non-leaf,none).
+:::
-Other :program:`llc` options are described below.
+:::{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).
+:::
-End-user Options
-~~~~~~~~~~~~~~~~
+:::{option} --enable-no-infs-fp-math
+Enable optimizations that assume no Inf values.
+:::
-.. option:: -help
+:::{option} --enable-no-nans-fp-math
+Enable optimizations that assume no NAN values.
+:::
- Print a summary of command line options.
+:::{option} --enable-no-signed-zeros-fp-math
+Enable FP math optimizations that assume the sign of 0 is insignificant.
+:::
-.. option:: -M
+:::{option} --enable-no-trapping-fp-math
+Enable setting the FP exceptions build attribute not to use exceptions.
+:::
- Pass target-specific InstPrinter options.
- Refer to the ``-M`` option of :manpage:`llvm-objdump(1)`.
+:::{option} --stats
+Print statistics recorded by code-generation passes.
+:::
-.. option:: -o <filename>
+:::{option} --save-stats, --save-stats=cwd, --save-stats=obj
+Save LLVM statistics to a file in the current directory
+({option}`--save-stats`/"--save-stats=cwd") or the directory
+of the output file ("--save-stats=obj") in JSON format.
+:::
- Use ``<filename>`` as the output filename. See the summary above for more
- details.
+:::{option} --time-passes
+Record the amount of time needed for each pass and print a report to standard
+error.
+:::
-.. option:: -O=uint
+:::{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.
+:::
- Generate code at different optimization levels. These correspond to the
- ``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by
- :program:`clang`.
+:::{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.
+:::
-.. option:: -mtriple=<target triple>
+:::{option} -remarks-section
+Emit the \_\_remarks (MachO) section which contains metadata about remark
+diagnostics.
+:::
- Override the target triple specified in the input file with the specified
- string.
+### Tuning/Configuration Options
-.. option:: -march=<arch>
+:::{option} --print-after-isel
+Print generated machine code after instruction selection (useful for debugging).
+:::
- 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} --regalloc=<allocator>
+Specify the register allocator to use.
+Valid register allocators are:
-.. option:: -mcpu=<cpuname>
+*basic*
- 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:
+> Basic register allocator.
- .. code-block:: none
+*fast*
- llvm-as < /dev/null | llc -march=xyz -mcpu=help
+> Fast register allocator. It is the default for unoptimized code.
-.. option:: -mtune=<cpuname>
+*greedy*
- Specify a specific chip microarchitecture in the current architecture
- to tune code for. By default this is inferred from the target triple and
- autodetected to the current architecture. For a list of available tuning
- CPUs, use:
+> Greedy register allocator. It is the default for optimized code.
- .. code-block:: none
+*pbqp*
- llvm-as < /dev/null | llc -march=xyz -mtune=help
+> Register allocator based on 'Partitioned Boolean Quadratic Programming'.
+:::
-.. option:: -filetype=<output file type>
+:::{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:
- 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).
+*simple*
- Note that not all targets support all options.
+> Simple spiller
-.. option:: -mattr=a1,+a2,-a3,...
+*local*
- 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:
+> Local spiller
+:::
- .. code-block:: none
+### Intel IA-32-specific Options
- llvm-as < /dev/null | llc -march=xyz -mattr=help
+:::{option} --x86-asm-syntax=[att|intel]
+Specify whether to emit assembly code in AT&T syntax (the default) or Intel
+syntax.
+:::
-.. option:: --frame-pointer
+## EXIT STATUS
- 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-no-signed-zeros-fp-math
-
- Enable FP math optimizations that assume the sign of 0 is insignificant.
-
-.. option:: --enable-no-trapping-fp-math
-
- Enable setting the FP exceptions build attribute not to use exceptions.
-
-.. option:: --stats
-
- Print statistics recorded by code-generation passes.
-
-.. option:: --save-stats, --save-stats=cwd, --save-stats=obj
-
- Save LLVM statistics to a file in the current directory
- (:option:`--save-stats`/"--save-stats=cwd") or the directory
- of the output file ("--save-stats=obj") in JSON format.
-
-.. option:: --time-passes
-
- Record the amount of time needed for each pass and print a report to standard
- error.
-
-.. 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.
-
-.. option:: -remarks-section
-
- Emit the __remarks (MachO) section which contains metadata about remark
- diagnostics.
-
-Tuning/Configuration Options
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. option:: --print-after-isel
-
- Print generated machine code after instruction selection (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
+If {program}`llc` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`lli(1)`
-:manpage:`lli(1)`
diff --git a/llvm/docs/CommandGuide/lldb-tblgen.md b/llvm/docs/CommandGuide/lldb-tblgen.md
index a4a5633b47e01..1b9a8e73348ff 100644
--- a/llvm/docs/CommandGuide/lldb-tblgen.md
+++ b/llvm/docs/CommandGuide/lldb-tblgen.md
@@ -1,22 +1,21 @@
-lldb-tblgen - Description to C++ Code for LLDB
-==============================================
+# lldb-tblgen - Description to C++ Code for LLDB
+```{eval-rst}
.. program:: lldb-tblgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`lldb-tblgen` [*options*] [*filename*]
+{program}`lldb-tblgen` \[*options*\] \[*filename*\]
+## DESCRIPTION
-DESCRIPTION
------------
-
-:program:`lldb-tblgen` is a program that translates compiler-related target
-description (``.td``) files into C++ code and other output formats. Most
+{program}`lldb-tblgen` is a program that translates compiler-related target
+description (`.td`) files into C++ code and other output formats. Most
users of LLVM will not need to use this program. It is used only for writing
parts of the compiler.
-Please see :doc:`tblgen - Description to C++ Code<./tblgen>`
+Please see {doc}`tblgen - Description to C++ Code<./tblgen>`
for a description of the *filename* argument and options, including the
-options common to all :program:`*-tblgen` programs.
+options common to all {program}`*-tblgen` programs.
+
diff --git a/llvm/docs/CommandGuide/lli.md b/llvm/docs/CommandGuide/lli.md
index c69ecb0ecb66a..1cc92b8a7cdfc 100644
--- a/llvm/docs/CommandGuide/lli.md
+++ b/llvm/docs/CommandGuide/lli.md
@@ -1,209 +1,203 @@
-lli - directly execute programs from LLVM bitcode
-=================================================
+# lli - directly execute programs from LLVM bitcode
+```{eval-rst}
.. program:: lli
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`lli` [*options*] [*filename*] [*program args*]
+{program}`lli` \[*options*\] \[*filename*\] \[*program args*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`lli` directly executes programs in LLVM bitcode format. It takes a program
+{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
+{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`,
+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
+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:: -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:: -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
-
-.. 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.
+## 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} -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} -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:
+
+```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):
+
+```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
+```
+:::
+
+:::{option} -regalloc=allocator
+Register allocator to use (default=linearscan)
+
+```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:
+
+```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)
+
+```text
+=simple: simple spiller
+=local: local spiller
+```
+:::
+
+:::{option} -x86-asm-syntax=syntax
+Choose style of code to emit from X86 backend:
+
+```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
---------
+## SEE ALSO
+
+{manpage}`llc(1)`
-:manpage:`llc(1)`
diff --git a/llvm/docs/CommandGuide/llubi.md b/llvm/docs/CommandGuide/llubi.md
index 0e8ed54592e5d..3370f01e751c6 100644
--- a/llvm/docs/CommandGuide/llubi.md
+++ b/llvm/docs/CommandGuide/llubi.md
@@ -1,117 +1,114 @@
-llubi - LLVM UB-aware Interpreter
-=================================
+# llubi - LLVM UB-aware Interpreter
+```{eval-rst}
.. program:: llubi
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llubi` [*options*] [*filename*] [*program args*]
+{program}`llubi` \[*options*\] \[*filename*\] \[*program args*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llubi` directly executes programs in LLVM bitcode format and tracks values in LLVM IR semantics.
-Unlike :program:`lli`, :program:`llubi` is designed to be aware of undefined behaviors during execution.
+{program}`llubi` directly executes programs in LLVM bitcode format and tracks values in LLVM IR semantics.
+Unlike {program}`lli`, {program}`llubi` is designed to be aware of undefined behaviors during execution.
It detects immediate undefined behaviors such as integer division by zero, and respects poison generating flags
like `nsw` and `nuw`. As it captures most of the guardable undefined behaviors, it is highly suitable for
constructing an interesting-ness test for miscompilation bugs.
-If `filename` is not specified, then :program:`llubi` reads the LLVM bitcode for the
+If `filename` is not specified, then {program}`llubi` 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
----------------
+## GENERAL OPTIONS
-.. option:: -fake-argv0=executable
+:::{option} -fake-argv0=executable
+Override the `argv[0]` value passed into the executing program.
+:::
- Override the ``argv[0]`` value passed into the executing program.
+:::{option} -entry-function=function
+Specify the name of the function to execute as the program's entry point.
+By default, {program}`llubi` uses the function named `main`.
+:::
-.. option:: -entry-function=function
+:::{option} -help
+Print a summary of command line options.
+:::
- Specify the name of the function to execute as the program's entry point.
- By default, :program:`llubi` uses the function named ``main``.
+:::{option} -verbose
+Print results for each instruction executed.
+:::
-.. option:: -help
+:::{option} -version
+Print out the version of {program}`llubi` and exit without doing anything else.
+:::
- Print a summary of command line options.
+## INTERPRETER OPTIONS
-.. option:: -verbose
+:::{option} -max-mem=N
+Limit the amount of memory (in bytes) that can be allocated by the program, including
+stack, heap, and global variables. If the limit is exceeded, execution will be terminated.
+By default, there is no limit (N = 0).
+:::
- Print results for each instruction executed.
+:::{option} -max-stack-depth=N
+Limit the maximum stack depth to N. If the limit is exceeded, execution will be terminated.
+The default limit is 256. Set N to 0 to disable the limit.
+:::
-.. option:: -version
+:::{option} -max-steps=N
+Limit the number of instructions executed to N. If the limit is reached, execution will
+be terminated. By default, there is no limit (N = 0).
+:::
- Print out the version of :program:`llubi` and exit without doing anything else.
+:::{option} -vscale=N
+Set the value of `llvm.vscale` to N. The default value is 4.
+:::
-INTERPRETER OPTIONS
--------------------
+:::{option} -seed=N
+Set the seed for random number generator to N. By default, the seed is 0.
+:::
-.. option:: -max-mem=N
+:::{option} -undef-behavior=mode
+Set the behavior for undefined values (e.g., load from uninitialized memory or freeze a poison value).
+The options for `mode` are:
- Limit the amount of memory (in bytes) that can be allocated by the program, including
- stack, heap, and global variables. If the limit is exceeded, execution will be terminated.
- By default, there is no limit (N = 0).
+- `nondet`: Each load from the same uninitialized byte yields a freshly random value. This is the default behavior.
+- `zero`: Uninitialized values are treated as zero.
+:::
-.. option:: -max-stack-depth=N
+:::{option} -nan-behavior=mode
+Set the behavior for payload preserving behavior of floating-point NaN values.
+The options for `mode` are:
- Limit the maximum stack depth to N. If the limit is exceeded, execution will be terminated.
- The default limit is 256. Set N to 0 to disable the limit.
+- `nondet`: The actual behavior is randomly chosen from the modes below. This is the default behavior.
+- `preferred`: The quiet bit is set and the payload is all-zero.
+- `quieting`: The quiet bit is set and the payload is copied from any input operand that is a NaN.
+- `unchanged`: The quiet bit and payload are copied from any input operand that is a NaN.
+- `target-specific`: The quiet bit is set and the payload is picked from a known target-specific set of extra possible NaN payloads.
+:::
-.. option:: -max-steps=N
+:::{option} -deterministic
+Disable interpreter-introduced non-determinism (off by default).
+This option implies '`-undef-behavior=zero`' and '`-nan-behavior=preferred`'.
+:::
- Limit the number of instructions executed to N. If the limit is reached, execution will
- be terminated. By default, there is no limit (N = 0).
+:::{option} -fuse-fmuladd
+Treat '`llvm.fmuladd.*`' as '`llvm.fma.*`'. It is the default behavior.
+Otherwise, it is expanded into a * b + c.
+:::
-.. option:: -vscale=N
+:::{option} -disable-verify
+Disable the validation of the input LLVM IR. The user is responsible for the validity of inputs.
+The verifier is executed by default.
+:::
- Set the value of `llvm.vscale` to N. The default value is 4.
+## EXIT STATUS
-.. option:: -seed=N
-
- Set the seed for random number generator to N. By default, the seed is 0.
-
-.. option:: -undef-behavior=mode
-
- Set the behavior for undefined values (e.g., load from uninitialized memory or freeze a poison value).
- The options for `mode` are:
-
- * `nondet`: Each load from the same uninitialized byte yields a freshly random value. This is the default behavior.
- * `zero`: Uninitialized values are treated as zero.
-
-.. option:: -nan-behavior=mode
-
- Set the behavior for payload preserving behavior of floating-point NaN values.
- The options for `mode` are:
-
- * `nondet`: The actual behavior is randomly chosen from the modes below. This is the default behavior.
- * `preferred`: The quiet bit is set and the payload is all-zero.
- * `quieting`: The quiet bit is set and the payload is copied from any input operand that is a NaN.
- * `unchanged`: The quiet bit and payload are copied from any input operand that is a NaN.
- * `target-specific`: The quiet bit is set and the payload is picked from a known target-specific set of extra possible NaN payloads.
-
-.. option:: -deterministic
-
- Disable interpreter-introduced non-determinism (off by default).
- This option implies '``-undef-behavior=zero``' and '``-nan-behavior=preferred``'.
-
-.. option:: -fuse-fmuladd
-
- Treat '``llvm.fmuladd.*``' as '``llvm.fma.*``'. It is the default behavior.
- Otherwise, it is expanded into a \* b + c.
-
-.. option:: -disable-verify
-
- Disable the validation of the input LLVM IR. The user is responsible for the validity of inputs.
- The verifier is executed by default.
-
-EXIT STATUS
------------
-
-If :program:`llubi` fails to load the program, or an error occurs during execution (e.g, an immediate undefined
+If {program}`llubi` fails to load the program, or an error occurs during execution (e.g, an immediate undefined
behavior is triggered), it will exit with an exit code of 1.
If the return type of entry function is not an integer type, it will return 0.
Otherwise, it will return the exit code of the program.
+
diff --git a/llvm/docs/CommandGuide/llvm-addr2line.md b/llvm/docs/CommandGuide/llvm-addr2line.md
index 999b3e0d7e6aa..a2ee8e5947f5b 100644
--- a/llvm/docs/CommandGuide/llvm-addr2line.md
+++ b/llvm/docs/CommandGuide/llvm-addr2line.md
@@ -1,50 +1,42 @@
-llvm-addr2line - a drop-in replacement for addr2line
-====================================================
+# llvm-addr2line - a drop-in replacement for addr2line
+```{eval-rst}
.. program:: llvm-addr2line
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-addr2line` [*options*]
+{program}`llvm-addr2line` \[*options*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-addr2line` is an alias for the :manpage:`llvm-symbolizer(1)`
+{program}`llvm-addr2line` is an alias for the {manpage}`llvm-symbolizer(1)`
tool with different defaults. The goal is to make it a drop-in replacement for
-GNU's :program:`addr2line`.
+GNU's {program}`addr2line`.
Here are some of those differences:
-- ``llvm-addr2line`` interprets all addresses as hexadecimal and ignores an
- optional ``0x`` prefix, whereas ``llvm-symbolizer`` attempts to determine
- the base from the literal's prefix and defaults to decimal if there is no
- prefix.
-
-- ``llvm-addr2line`` defaults not to print function names. Use `-f`_ to enable
- that.
-
-- ``llvm-addr2line`` defaults not to demangle function names. Use `-C`_ to
- switch the demangling on.
-
-- ``llvm-addr2line`` defaults not to print inlined frames. Use `-i`_ to show
- inlined frames for a source code location in an inlined function.
-
-- ``llvm-addr2line`` uses `--output-style=GNU`_ by default.
-
-- ``llvm-addr2line`` parses options from the environment variable
- ``LLVM_ADDR2LINE_OPTS`` instead of from ``LLVM_SYMBOLIZER_OPTS``.
-
-- ``llvm-addr2line`` accepts an address with a '+' prefix, e.g. `+0x00777fff`.
- This is treated as a symbol name by ``llvm-symbolizer``.
-
-SEE ALSO
---------
-
-:manpage:`llvm-symbolizer(1)`
-
-.. _-f: llvm-symbolizer.html#llvm-symbolizer-opt-f
-.. _-C: llvm-symbolizer.html#llvm-symbolizer-opt-c
-.. _-i: llvm-symbolizer.html#llvm-symbolizer-opt-i
-.. _--output-style=GNU: llvm-symbolizer.html#llvm-symbolizer-opt-output-style
+- `llvm-addr2line` interprets all addresses as hexadecimal and ignores an
+ optional `0x` prefix, whereas `llvm-symbolizer` attempts to determine
+ the base from the literal's prefix and defaults to decimal if there is no
+ prefix.
+- `llvm-addr2line` defaults not to print function names. Use `-f` to enable
+ that.
+- `llvm-addr2line` defaults not to demangle function names. Use `-C` to
+ switch the demangling on.
+- `llvm-addr2line` defaults not to print inlined frames. Use `-i` to show
+ inlined frames for a source code location in an inlined function.
+- `llvm-addr2line` uses `--output-style=GNU` by default.
+- `llvm-addr2line` parses options from the environment variable
+ `LLVM_ADDR2LINE_OPTS` instead of from `LLVM_SYMBOLIZER_OPTS`.
+- `llvm-addr2line` accepts an address with a '+' prefix, e.g. `+0x00777fff`.
+ This is treated as a symbol name by `llvm-symbolizer`.
+
+## SEE ALSO
+
+{manpage}`llvm-symbolizer(1)`
+
+[--output-style=gnu]: llvm-symbolizer.html#llvm-symbolizer-opt-output-style
+[-c]: llvm-symbolizer.html#llvm-symbolizer-opt-c
+[-f]: llvm-symbolizer.html#llvm-symbolizer-opt-f
+[-i]: llvm-symbolizer.html#llvm-symbolizer-opt-i
diff --git a/llvm/docs/CommandGuide/llvm-ar.md b/llvm/docs/CommandGuide/llvm-ar.md
index a061dacd9207d..b108d932a0893 100644
--- a/llvm/docs/CommandGuide/llvm-ar.md
+++ b/llvm/docs/CommandGuide/llvm-ar.md
@@ -1,69 +1,67 @@
-llvm-ar - LLVM archiver
-=======================
+# llvm-ar - LLVM archiver
+```{eval-rst}
.. program:: llvm-ar
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...]
+{program}`llvm-ar` [-]\{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-ar` command is similar to the common Unix utility,
-:program:`ar`. It archives several files, such as objects and LLVM bitcode
+The {program}`llvm-ar` command is similar to the common Unix utility,
+{program}`ar`. It archives several files, such as objects and LLVM bitcode
files into a single archive library that can be linked into a program. However,
-the archive can contain any kind of file. By default, :program:`llvm-ar`
+the archive can contain any kind of file. By default, {program}`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 :program:`llvm-ar` command can be used to *read* archive files in SVR4, GNU,
+The {program}`llvm-ar` command can be used to *read* archive files in SVR4, GNU,
BSD , Big Archive, and Darwin format, and *write* in the GNU, BSD, Big Archive, and
-Darwin style archive files. If an SVR4 format archive is used with the :option:`r`
-(replace), :option:`d` (delete), :option:`m` (move) or :option:`q`
+Darwin style archive files. If an SVR4 format archive is used with the {option}`r`
+(replace), {option}`d` (delete), {option}`m` (move) or {option}`q`
(quick update) operations, the archive will be reconstructed in the format
-defined by :option:`--format`.
+defined by {option}`--format`.
-Here's where :program:`llvm-ar` departs from previous :program:`ar`
+Here's where {program}`llvm-ar` departs from previous {program}`ar`
implementations:
*The following option is not supported*
- [f] - truncate inserted filenames
+> [f] - truncate inserted filenames
*The following options are ignored for compatibility*
- --plugin=<string> - load a plugin which adds support for other file formats
-
- [l] - ignored in :program:`ar`
+> --plugin=\<string> - load a plugin which adds support for other file formats
+>
+> [l] - ignored in {program}`ar`
*Symbol Table*
- Since :program:`llvm-ar` supports bitcode files, the symbol table it creates
- includes both native and bitcode symbols.
+> Since {program}`llvm-ar` supports bitcode files, the symbol table it creates
+> includes both native and bitcode symbols.
*Deterministic Archives*
- By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs
- to write archives in a deterministic mode. This is equivalent to the
- :option:`D` modifier being enabled by default. If you wish to maintain
- compatibility with other :program:`ar` implementations, you can pass the
- :option:`U` modifier to write actual timestamps and UIDs/GIDs.
+> By default, {program}`llvm-ar` always uses zero for timestamps and UIDs/GIDs
+> to write archives in a deterministic mode. This is equivalent to the
+> {option}`D` modifier being enabled by default. If you wish to maintain
+> compatibility with other {program}`ar` implementations, you can pass the
+> {option}`U` modifier to write actual timestamps and UIDs/GIDs.
*Windows Paths*
- When on Windows :program:`llvm-ar` treats the names of archived *files* in the same
- case sensitive manner as the operating system. When on a non-Windows machine
- :program:`llvm-ar` does not consider character case.
+> When on Windows {program}`llvm-ar` treats the names of archived *files* in the same
+> case sensitive manner as the operating system. When on a non-Windows machine
+> {program}`llvm-ar` does not consider character case.
-OPTIONS
--------
+## OPTIONS
-:program:`llvm-ar` operations are compatible with other :program:`ar`
-implementations. However, there are a few modifiers (:option:`L`) that are not
-found in other :program:`ar` implementations. The options for
-:program:`llvm-ar` specify a single basic Operation to perform on the archive,
+{program}`llvm-ar` operations are compatible with other {program}`ar`
+implementations. However, there are a few modifiers ({option}`L`) that are not
+found in other {program}`ar` implementations. The options for
+{program}`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. If the *files* option is not specified, it
generally means either "none" or "all" members, depending on the operation. The
@@ -72,311 +70,307 @@ Options, 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.
-Operations
-~~~~~~~~~~
-
-.. option:: d [NT]
-
- Delete files from the ``archive``. The :option:`N` and :option:`T` modifiers
- apply 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.
-
-.. option:: m [abi]
-
- Move files from one location in the ``archive`` to another. The :option:`a`,
- :option:`b`, and :option:`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.
-
-.. option:: p [v]
-
- Print *files* to the standard output stream. If no *files* are specified, the
- entire ``archive`` is printed. With the :option:`v` modifier,
- :program:`llvm-ar` also prints out the name of the file being output. Printing
- binary files is ill-advised as they might confuse your terminal settings. The
- :option:`p` operation never modifies the archive.
-
-.. option:: q [LT]
-
- Quickly append files to the end of the ``archive`` without removing
- duplicates. If no *files* are specified, the archive is not modified. The
- behavior when appending one archive to another depends upon whether the
- :option:`L` and :option:`T` modifiers are used:
-
- * Appending a regular archive to a regular archive will append the archive
- file. If the :option:`L` modifier is specified the members will be appended
- instead.
-
- * Appending a regular archive to a thin archive requires the :option:`T`
- modifier and will append the archive file. The :option:`L` modifier is not
- supported.
-
- * Appending a thin archive to a regular archive will append the archive file.
- If the :option:`L` modifier is specified the members will be appended
- instead.
-
- * Appending a thin archive to a thin archive will always quick append its
- members.
-
-.. option:: r [abTu]
-
- Replace existing *files* or insert them at the end of the ``archive`` if
- they do not exist. The :option:`a`, :option:`b`, :option:`T` and :option:`u`
- modifiers apply to this operation. If no *files* are specified, the archive
- is not modified.
+### Operations
+
+:::{option} d [NT]
+Delete files from the `archive`. The {option}`N` and {option}`T` modifiers
+apply 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.
+:::
+
+:::{option} m [abi]
+Move files from one location in the `archive` to another. The {option}`a`,
+{option}`b`, and {option}`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.
+:::
+
+:::{option} p [v]
+Print *files* to the standard output stream. If no *files* are specified, the
+entire `archive` is printed. With the {option}`v` modifier,
+{program}`llvm-ar` also prints out the name of the file being output. Printing
+binary files is ill-advised as they might confuse your terminal settings. The
+{option}`p` operation never modifies the archive.
+:::
+
+:::{option} q [LT]
+Quickly append files to the end of the `archive` without removing
+duplicates. If no *files* are specified, the archive is not modified. The
+behavior when appending one archive to another depends upon whether the
+{option}`L` and {option}`T` modifiers are used:
+
+- Appending a regular archive to a regular archive will append the archive
+ file. If the {option}`L` modifier is specified the members will be appended
+ instead.
+- Appending a regular archive to a thin archive requires the {option}`T`
+ modifier and will append the archive file. The {option}`L` modifier is not
+ supported.
+- Appending a thin archive to a regular archive will append the archive file.
+ If the {option}`L` modifier is specified the members will be appended
+ instead.
+- Appending a thin archive to a thin archive will always quick append its
+ members.
+:::
+
+:::{option} r [abTu]
+Replace existing *files* or insert them at the end of the `archive` if
+they do not exist. The {option}`a`, {option}`b`, {option}`T` and {option}`u`
+modifiers apply to this operation. If no *files* are specified, the archive
+is not modified.
+:::
t[v]
.. option:: t [vO]
- Print the table of contents. Without any modifiers, this operation just prints
- the names of the members to the standard output stream. With the :option:`v`
- modifier, :program:`llvm-ar` also prints out the file type (B=bitcode,
- S=symbol table, blank=regular file), the permission mode, the owner and group,
- are ignored when extracting *files* and set to placeholder values when adding
- size, and the date. With the :option:`O` modifier, display member offsets. 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.
+> Print the table of contents. Without any modifiers, this operation just prints
+> the names of the members to the standard output stream. With the {option}`v`
+> modifier, {program}`llvm-ar` also prints out the file type (B=bitcode,
+> S=symbol table, blank=regular file), the permission mode, the owner and group,
+> are ignored when extracting *files* and set to placeholder values when adding
+> size, and the date. With the {option}`O` modifier, display member offsets. 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.
-.. option:: V
+:::{option} V
+A synonym for the {option}`--version` option.
+:::
- A synonym for the :option:`--version` option.
+:::{option} x [oPN]
+Extract `archive` members back to files. The {option}`o` and {option}`N`
+modifiers apply 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 extracted.
+:::
-.. option:: x [oPN]
-
- Extract ``archive`` members back to files. The :option:`o` and :option:`N`
- modifiers apply 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 extracted.
-
-Modifiers (operation specific)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Modifiers (operation specific)
The modifiers below are specific to certain operations. See the Operations
section to determine which modifiers are applicable to which operations.
-.. option:: 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``. *relpos* cannot be
- consumed without either :option:`a`, :option:`b` or :option:`i`.
-
-.. option:: 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``. *relpos* cannot
- be consumed without either :option:`a`, :option:`b` or :option:`i`. This
- modifier is identical to the :option:`i` modifier.
-
-.. option:: i
-
- A synonym for the :option:`b` option.
-
-.. option:: L
-
- When quick appending an ``archive``, instead quick append its members. This
- is a feature for :program:`llvm-ar` that is not found in gnu-ar.
-
-.. option:: N
-
- When extracting or deleting a member that shares its name with another member,
- the *count* parameter allows you to supply a positive whole number that
- selects the instance of the given name, with "1" indicating the first
- instance. If :option:`N` is not specified the first member of that name will
- be selected. If *count* is not supplied, the operation fails. *count* cannot be
- consumed without either :option:`x` or :option:`d`.
-
-.. option:: o
-
- When extracting files, use the modification times of any *files* as they
- appear in the ``archive``. By default *files* extracted from the archive
- use the time of extraction.
-
-.. option:: O
-
- Display member offsets inside the archive.
-
-.. option:: T
-
- Alias for ``--thin``. In many ar implementations ``T`` has a different
- meaning, as specified by X/Open System interface.
-
-.. option:: v
-
- When printing *files* or the ``archive`` table of contents, this modifier
- instructs :program:`llvm-ar` to include additional information in the output.
-
-Modifiers (generic)
-~~~~~~~~~~~~~~~~~~~
+:::{option} 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`. *relpos* cannot be
+consumed without either {option}`a`, {option}`b` or {option}`i`.
+:::
+
+:::{option} 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`. *relpos* cannot
+be consumed without either {option}`a`, {option}`b` or {option}`i`. This
+modifier is identical to the {option}`i` modifier.
+:::
+
+:::{option} i
+A synonym for the {option}`b` option.
+:::
+
+:::{option} L
+When quick appending an `archive`, instead quick append its members. This
+is a feature for {program}`llvm-ar` that is not found in gnu-ar.
+:::
+
+:::{option} N
+When extracting or deleting a member that shares its name with another member,
+the *count* parameter allows you to supply a positive whole number that
+selects the instance of the given name, with "1" indicating the first
+instance. If {option}`N` is not specified the first member of that name will
+be selected. If *count* is not supplied, the operation fails. *count* cannot be
+consumed without either {option}`x` or {option}`d`.
+:::
+
+:::{option} o
+When extracting files, use the modification times of any *files* as they
+appear in the `archive`. By default *files* extracted from the archive
+use the time of extraction.
+:::
+
+:::{option} O
+Display member offsets inside the archive.
+:::
+
+:::{option} T
+Alias for `--thin`. In many ar implementations `T` has a different
+meaning, as specified by X/Open System interface.
+:::
+
+:::{option} v
+When printing *files* or the `archive` table of contents, this modifier
+instructs {program}`llvm-ar` to include additional information in the output.
+:::
+
+### Modifiers (generic)
The modifiers below may be applied to any operation.
-.. option:: c
-
- For the :option:`r` (replace) and :option:`q` (quick update) operations,
- :program:`llvm-ar` will always create the archive if it doesn't exist.
- Normally, :program:`llvm-ar` will print a warning message indicating that the
- ``archive`` is being created. Using this modifier turns off
- that warning.
-
-.. option:: D
-
- Use zero for timestamps and UIDs/GIDs. This is set by default.
-
-.. option:: P
-
- Use full paths when matching member names rather than just the file name.
- This can be useful when manipulating an ``archive`` generated by another
- archiver, as some allow paths as member names. This is the default behavior
- for thin archives.
-
-.. option:: s
-
- This modifier requests that an archive index (or symbol table) be added to the
- ``archive``, as if using ranlib. The symbol table will contain all the
- externally visible functions and global variables defined by all the bitcode
- files in the archive. By default :program:`llvm-ar` generates symbol tables in
- archives. This can also be used as an operation.
-
-.. option:: S
-
- This modifier is the opposite of the :option:`s` modifier. It instructs
- :program:`llvm-ar` to not build the symbol table. If both :option:`s` and
- :option:`S` are used, the last modifier to occur in the options will prevail.
-
-.. option:: u
-
- Only update ``archive`` members with *files* that have more recent
- timestamps.
-
-.. option:: U
-
- Use actual timestamps and UIDs/GIDs.
-
-Other
-~~~~~
-
-.. option:: --format=<type>
-
- This option allows for default, gnu, darwin, bsd or coff ``<type>`` to be selected.
- When creating an ``archive`` with the default ``<type>``, :program:`llvm-ar`
- will attempt to infer it from the input files and fallback to the default
- toolchain target if unable to do so.
-
-.. option:: -h, --help
-
- Print a summary of command-line options and their meanings.
-
-.. option:: -M
-
- This option allows for MRI scripts to be read through the standard input
- stream. No other options are compatible with this option.
-
-.. option:: --output=<dir>
-
- Specify a directory where archive members should be extracted to. By default the
- current working directory is used.
-
-.. option:: --rsp-quoting=<type>
- This option selects the quoting style ``<type>`` for response files, either
- ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the
- default is ``posix``.
-
-.. option:: --thin
-
- When creating or modifying an archive, this option specifies that the
- ``archive`` will be thin. By default, archives are not created as thin archives
- and when modifying a thin archive, it will be converted to a regular archive.
-
-.. option:: --version
-
- Display the version of the :program:`llvm-ar` executable.
-
-.. option:: -X mode
-
- Specifies the type of object file :program:`llvm-ar` will recognise. The mode must be
- one of the following:
-
- 32
- Process only 32-bit object files.
- 64
- Process only 64-bit object files.
- 32_64
- Process both 32-bit and 64-bit object files.
- any
- Process all object files.
-
- The default is to process 32-bit object files (ignore 64-bit objects). The mode can also
- be set with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 causes ar to
- process any 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
- variable.
-
-.. option:: @<FILE>
-
- Read command-line options and commands from response file ``<FILE>``.
-
-MRI SCRIPTS
------------
-
-:program:`llvm-ar` understands a subset of the MRI scripting interface commonly
+:::{option} c
+For the {option}`r` (replace) and {option}`q` (quick update) operations,
+{program}`llvm-ar` will always create the archive if it doesn't exist.
+Normally, {program}`llvm-ar` will print a warning message indicating that the
+`archive` is being created. Using this modifier turns off
+that warning.
+:::
+
+:::{option} D
+Use zero for timestamps and UIDs/GIDs. This is set by default.
+:::
+
+:::{option} P
+Use full paths when matching member names rather than just the file name.
+This can be useful when manipulating an `archive` generated by another
+archiver, as some allow paths as member names. This is the default behavior
+for thin archives.
+:::
+
+:::{option} s
+This modifier requests that an archive index (or symbol table) be added to the
+`archive`, as if using ranlib. The symbol table will contain all the
+externally visible functions and global variables defined by all the bitcode
+files in the archive. By default {program}`llvm-ar` generates symbol tables in
+archives. This can also be used as an operation.
+:::
+
+:::{option} S
+This modifier is the opposite of the {option}`s` modifier. It instructs
+{program}`llvm-ar` to not build the symbol table. If both {option}`s` and
+{option}`S` are used, the last modifier to occur in the options will prevail.
+:::
+
+:::{option} u
+Only update `archive` members with *files* that have more recent
+timestamps.
+:::
+
+:::{option} U
+Use actual timestamps and UIDs/GIDs.
+:::
+
+### Other
+
+:::{option} --format=<type>
+This option allows for default, gnu, darwin, bsd or coff `<type>` to be selected.
+When creating an `archive` with the default `<type>`, {program}`llvm-ar`
+will attempt to infer it from the input files and fallback to the default
+toolchain target if unable to do so.
+:::
+
+:::{option} -h, --help
+Print a summary of command-line options and their meanings.
+:::
+
+:::{option} -M
+This option allows for MRI scripts to be read through the standard input
+stream. No other options are compatible with this option.
+:::
+
+:::{option} --output=<dir>
+Specify a directory where archive members should be extracted to. By default the
+current working directory is used.
+:::
+
+:::{option} --rsp-quoting=<type> This option selects the quoting style ``<type>`` for response files, either ``posix`` or ``windows``. The default when on Windows is ``windows``, otherwise the default is ``posix``.
+:::
+
+:::{option} --thin
+When creating or modifying an archive, this option specifies that the
+`archive` will be thin. By default, archives are not created as thin archives
+and when modifying a thin archive, it will be converted to a regular archive.
+:::
+
+:::{option} --version
+Display the version of the {program}`llvm-ar` executable.
+:::
+
+:::{option} -X mode
+Specifies the type of object file {program}`llvm-ar` will recognise. The mode must be
+one of the following:
+
+> 32
+>
+> : Process only 32-bit object files.
+>
+> 64
+>
+> : Process only 64-bit object files.
+>
+> 32_64
+>
+> : Process both 32-bit and 64-bit object files.
+>
+> any
+>
+> : Process all object files.
+
+The default is to process 32-bit object files (ignore 64-bit objects). The mode can also
+be set with the OBJECT_MODE environment variable. For example, OBJECT_MODE=64 causes ar to
+process any 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
+variable.
+:::
+
+:::{option} @<FILE>
+Read command-line options and commands from response file `<FILE>`.
+:::
+
+## MRI SCRIPTS
+
+{program}`llvm-ar` understands a subset of the MRI scripting interface commonly
supported by archivers following in the ar tradition. An MRI script contains a
-sequence of commands to be executed by the archiver. The :option:`-M` option
-allows for an MRI script to be passed to :program:`llvm-ar` through the
+sequence of commands to be executed by the archiver. The {option}`-M` option
+allows for an MRI script to be passed to {program}`llvm-ar` through the
standard input stream.
-Note that :program:`llvm-ar` has known limitations regarding the use of MRI
+Note that {program}`llvm-ar` has known limitations regarding the use of MRI
scripts:
-* Each script can only create one archive.
-* Existing archives can not be modified.
+- Each script can only create one archive.
+- Existing archives can not be modified.
-MRI Script Commands
-~~~~~~~~~~~~~~~~~~~
+### MRI Script Commands
Each command begins with the command's name and must appear on its own line.
Some commands have arguments, which must be separated from the name by
-whitespace. An MRI script should begin with either a :option:`CREATE` or
-:option:`CREATETHIN` command and will typically end with a :option:`SAVE`
-command. Any text after either '*' or ';' is treated as a comment.
-
-.. option:: CREATE archive
-
- Begin creation of a regular archive with the specified name. Subsequent
- commands act upon this ``archive``.
-
-.. option:: CREATETHIN archive
-
- Begin creation of a thin archive with the specified name. Subsequent
- commands act upon this ``archive``.
+whitespace. An MRI script should begin with either a {option}`CREATE` or
+{option}`CREATETHIN` command and will typically end with a {option}`SAVE`
+command. Any text after either '\*' or ';' is treated as a comment.
-.. option:: ADDLIB archive
+:::{option} CREATE archive
+Begin creation of a regular archive with the specified name. Subsequent
+commands act upon this `archive`.
+:::
- Append the contents of ``archive`` to the current archive.
+:::{option} CREATETHIN archive
+Begin creation of a thin archive with the specified name. Subsequent
+commands act upon this `archive`.
+:::
-.. option:: ADDMOD <file>
+:::{option} ADDLIB archive
+Append the contents of `archive` to the current archive.
+:::
- Append ``<file>`` to the current archive.
+:::{option} ADDMOD <file>
+Append `<file>` to the current archive.
+:::
-.. option:: DELETE <file>
+:::{option} DELETE <file>
+Delete the member of the current archive whose file name, excluding directory
+components, matches `<file>`.
+:::
- Delete the member of the current archive whose file name, excluding directory
- components, matches ``<file>``.
+:::{option} SAVE
+Write the current archive to the path specified in the previous
+{option}`CREATE`/{option}`CREATETHIN` command.
+:::
-.. option:: SAVE
+:::{option} END
+Ends the MRI script (optional).
+:::
- Write the current archive to the path specified in the previous
- :option:`CREATE`/:option:`CREATETHIN` command.
+## EXIT STATUS
-.. option:: END
-
- Ends the MRI script (optional).
-
-EXIT STATUS
------------
-
-If :program:`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it
+If {program}`llvm-ar` succeeds, it will exit with 0. Otherwise, if an error occurs, it
will exit with a non-zero value.
+
diff --git a/llvm/docs/CommandGuide/llvm-as.md b/llvm/docs/CommandGuide/llvm-as.md
index 97dcaf15bd054..62d86e16ffc95 100644
--- a/llvm/docs/CommandGuide/llvm-as.md
+++ b/llvm/docs/CommandGuide/llvm-as.md
@@ -1,58 +1,56 @@
-llvm-as - LLVM assembler
-========================
+# llvm-as - LLVM assembler
+```{eval-rst}
.. program:: llvm-as
+```
-SYNOPSIS
---------
+## SYNOPSIS
-**llvm-as** [*options*] [*filename*]
+**llvm-as** \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-**llvm-as** is the LLVM assembler. It reads a file containing human-readable
+**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
+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``
+- 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
--------
+## 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.
+
+: 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.
+
+: 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
------------
+: 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
+If **llvm-as** succeeds, it will exit with 0. Otherwise, if an error occurs, it
will exit with a non-zero value.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-dis(1)`, as(1)
-:manpage:`llvm-dis(1)`, as(1)
diff --git a/llvm/docs/CommandGuide/llvm-bcanalyzer.md b/llvm/docs/CommandGuide/llvm-bcanalyzer.md
index 1e0b581574a3a..7881ab50582c3 100644
--- a/llvm/docs/CommandGuide/llvm-bcanalyzer.md
+++ b/llvm/docs/CommandGuide/llvm-bcanalyzer.md
@@ -1,294 +1,291 @@
-llvm-bcanalyzer - LLVM bitcode analyzer
-=======================================
+# llvm-bcanalyzer - LLVM bitcode analyzer
+```{eval-rst}
.. program:: llvm-bcanalyzer
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-bcanalyzer` [*options*] [*filename*]
+{program}`llvm-bcanalyzer` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## 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
+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.
+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
--------
+## OPTIONS
+```{eval-rst}
.. program:: llvm-bcanalyzer
+```
-.. option:: --dump
+:::{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.
+:::
- 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} --help
+Print a summary of command line options.
+:::
-.. option:: --help
+## EXIT STATUS
- Print a summary of command line options.
-
-EXIT STATUS
------------
-
-If :program:`llvm-bcanalyzer` succeeds, it will exit with 0. Otherwise, if an
+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
---------------------------
+## 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.
+> 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.
+> The bitcode version (not LLVM version) of the file read by the analyzer.
**File Size**
- The size, in bytes, of the entire bitcode file.
+> 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
- Size.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> The total number of function definitions in the bitcode file.
**Number Of Types**
- The total number of types defined in the Global Types Pool.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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).
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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
----------------------------
+## 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.
+> The type signature of the function.
**Byte Size**
- The total number of bytes in the function's block.
+> The total number of bytes in the function's block.
**Basic Blocks**
- The number of basic blocks defined by the function.
+> The number of basic blocks defined by the function.
**Instructions**
- The number of instructions defined by the function.
+> The number of instructions defined by the function.
**Long Instructions**
- The number of instructions using the long instruction format in the function.
+> The number of instructions using the long instruction format in the function.
**Operands**
- The number of operands used by all instructions in the function.
+> The number of operands used by all instructions in the function.
**Instruction Size**
- The number of bytes consumed by instructions in the function.
+> 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).
+> 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).
+> 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.
+> 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.
+> 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.
+> 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
-SEE ALSO
---------
+{manpage}`llvm-dis(1)`, {doc}`/BitCodeFormat`
-:manpage:`llvm-dis(1)`, :doc:`/BitCodeFormat`
diff --git a/llvm/docs/CommandGuide/llvm-calc-occupancy.md b/llvm/docs/CommandGuide/llvm-calc-occupancy.md
index ae9a3a11a7113..dfbf40ce802ba 100644
--- a/llvm/docs/CommandGuide/llvm-calc-occupancy.md
+++ b/llvm/docs/CommandGuide/llvm-calc-occupancy.md
@@ -1,20 +1,19 @@
-llvm-calc-occupancy - AMDGPU occupancy calculator
-=================================================
+# llvm-calc-occupancy - AMDGPU occupancy calculator
+```{eval-rst}
.. program:: llvm-calc-occupancy
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-calc-occupancy` -mcpu=<gfxNNN> [*options*]
+{program}`llvm-calc-occupancy` -mcpu=\<gfxNNN> \[*options*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-calc-occupancy` reports the occupancy (waves per execution unit)
+{program}`llvm-calc-occupancy` reports the occupancy (waves per execution unit)
that an AMDGPU kernel would achieve for a given combination of workgroup size,
VGPR usage, SGPR usage and LDS allocation. It is a thin front-end over the same
-occupancy math the AMDGPU backend uses (``GCNSubtarget``), so the numbers match
+occupancy math the AMDGPU backend uses (`GCNSubtarget`), so the numbers match
what the compiler computes for an equivalent kernel.
Any resource that is not specified is treated as unconstrained. When the
@@ -22,88 +21,86 @@ workgroup size is left unspecified (or given as a range), the occupancy is
reported as a range as well.
The tool only supports the AMDGPU target. New callers should use the
-``amdgpu`` triple (for example ``amdgpu-amd-amdhsa``); the legacy ``amdgcn``
+`amdgpu` triple (for example `amdgpu-amd-amdhsa`); the legacy `amdgcn`
spelling is still accepted.
-EXAMPLE
--------
-
-.. code-block:: console
-
- $ llvm-calc-occupancy -mcpu=gfx90a --wg-size=512 --vgprs=50 --sgprs=30
- llvm-calc-occupancy - AMDGPU occupancy calculator
-
- Target
- Triple: amdgpu-amd-amdhsa
- GPU (-mcpu): gfx90a
- Wavefront size: 64
- Max waves/EU: 8 (waves per SIMD, hardware limit)
- SIMDs/work-group: 4
- ...
-
- Per-constraint occupancy (waves/EU)
- Workgroup + LDS: 8
- VGPRs: 8
- SGPRs: 8
-
- Result
- Occupancy: 8 waves/EU (32 waves/CU)
- Limited by: workgroup size / LDS, VGPRs, SGPRs
- Next step: already at the hardware maximum
-
-OPTIONS
--------
-
-.. option:: -mcpu=<gfxNNN>
-
- Target GPU, for example ``gfx90a``. Required.
-
-.. option:: -mtriple=<triple>
-
- Target triple. Defaults to ``amdgpu-amd-amdhsa``. Must be an AMDGPU triple
- (the ``amdgpu`` or legacy ``amdgcn`` arch).
-
-.. option:: -mattr=<features>
-
- Comma-separated list of subtarget features, for example
- ``+wavefrontsize32``.
-
-.. option:: --wg-size=<N>, --flat-workgroup-size=<N>
-
- Flat workgroup size. Accepts a single value ``N`` or a range ``MIN:MAX``.
- When omitted, the full legal range is assumed and the occupancy is reported
- as a range.
+## EXAMPLE
-.. option:: --vgprs=<N>
-
- Number of VGPRs used per lane. When omitted, VGPRs do not constrain the
- occupancy.
-
-.. option:: --sgprs=<N>
-
- Number of SGPRs used per wave. When omitted, SGPRs do not constrain the
- occupancy.
-
-.. option:: --lds=<size>
-
- LDS bytes allocated per workgroup. Accepts an optional ``k``/``kb`` or
- ``m``/``mb`` suffix (base 1024).
-
-.. option:: --dynamic-vgpr-block-size=<N>
-
- Dynamic VGPR block size. ``0`` (the default) disables dynamic VGPR mode.
-
-.. option:: --limits
-
- Print, for each occupancy level supported by the GPU, the maximum number of
- VGPRs and SGPRs that still reaches that level.
-
-.. option:: --help
-
- Print a summary of command line options and exit.
-
-EXIT STATUS
------------
+```console
+$ llvm-calc-occupancy -mcpu=gfx90a --wg-size=512 --vgprs=50 --sgprs=30
+llvm-calc-occupancy - AMDGPU occupancy calculator
-:program:`llvm-calc-occupancy` returns 0 on success and a non-zero exit code if
+Target
+ Triple: amdgpu-amd-amdhsa
+ GPU (-mcpu): gfx90a
+ Wavefront size: 64
+ Max waves/EU: 8 (waves per SIMD, hardware limit)
+ SIMDs/work-group: 4
+ ...
+
+Per-constraint occupancy (waves/EU)
+ Workgroup + LDS: 8
+ VGPRs: 8
+ SGPRs: 8
+
+Result
+ Occupancy: 8 waves/EU (32 waves/CU)
+ Limited by: workgroup size / LDS, VGPRs, SGPRs
+ Next step: already at the hardware maximum
+```
+
+## OPTIONS
+
+:::{option} -mcpu=<gfxNNN>
+Target GPU, for example `gfx90a`. Required.
+:::
+
+:::{option} -mtriple=<triple>
+Target triple. Defaults to `amdgpu-amd-amdhsa`. Must be an AMDGPU triple
+(the `amdgpu` or legacy `amdgcn` arch).
+:::
+
+:::{option} -mattr=<features>
+Comma-separated list of subtarget features, for example
+`+wavefrontsize32`.
+:::
+
+:::{option} --wg-size=<N>, --flat-workgroup-size=<N>
+Flat workgroup size. Accepts a single value `N` or a range `MIN:MAX`.
+When omitted, the full legal range is assumed and the occupancy is reported
+as a range.
+:::
+
+:::{option} --vgprs=<N>
+Number of VGPRs used per lane. When omitted, VGPRs do not constrain the
+occupancy.
+:::
+
+:::{option} --sgprs=<N>
+Number of SGPRs used per wave. When omitted, SGPRs do not constrain the
+occupancy.
+:::
+
+:::{option} --lds=<size>
+LDS bytes allocated per workgroup. Accepts an optional `k`/`kb` or
+`m`/`mb` suffix (base 1024).
+:::
+
+:::{option} --dynamic-vgpr-block-size=<N>
+Dynamic VGPR block size. `0` (the default) disables dynamic VGPR mode.
+:::
+
+:::{option} --limits
+Print, for each occupancy level supported by the GPU, the maximum number of
+VGPRs and SGPRs that still reaches that level.
+:::
+
+:::{option} --help
+Print a summary of command line options and exit.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-calc-occupancy` returns 0 on success and a non-zero exit code if
the arguments are invalid (for example a missing or non-AMDGPU target).
+
diff --git a/llvm/docs/CommandGuide/llvm-cgdata.md b/llvm/docs/CommandGuide/llvm-cgdata.md
index 0670decd087e3..e7b10c61ea327 100644
--- a/llvm/docs/CommandGuide/llvm-cgdata.md
+++ b/llvm/docs/CommandGuide/llvm-cgdata.md
@@ -1,15 +1,14 @@
-llvm-cgdata - LLVM CodeGen Data Tool
-====================================
+# llvm-cgdata - LLVM CodeGen Data Tool
+```{eval-rst}
.. program:: llvm-cgdata
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-cgdata` [**commands**] [**options**] (<binaries>|<.cgdata>)
+{program}`llvm-cgdata` \[**commands**\] \[**options**\] (\<binaries>|\<.cgdata>)
-DESCRIPTION
------------
+## DESCRIPTION
The :program:llvm-cgdata utility parses raw codegen data embedded in compiled
binary files and merges them into a single .cgdata file. It can also inspect
@@ -19,48 +18,49 @@ function outlining and function merging across modules in subsequent
compilations. The design is extensible, allowing for the incorporation of
additional codegen summaries and optimization techniques.
-COMMANDS
---------
+## COMMANDS
At least one of the following commands are required:
-.. option:: --convert
+:::{option} --convert
+Convert a .cgdata file from one format to another.
+:::
- Convert a .cgdata file from one format to another.
+:::{option} --merge
+Merge multiple raw codgen data in binaries into a single .cgdata file.
+:::
-.. option:: --merge
+:::{option} --show
+Show summary information about a .cgdata file.
+:::
- Merge multiple raw codgen data in binaries into a single .cgdata file.
+## OPTIONS
-.. option:: --show
+{program}`llvm-cgdata` supports the following options:
- Show summary information about a .cgdata file.
+:::{option} --format=[text|binary]
+Specify the format of the output .cgdata file.
+:::
-OPTIONS
--------
+:::{option} --output=<string>
+Specify the output file name.
+:::
-:program:`llvm-cgdata` supports the following options:
+:::{option} --cgdata-version
+Print the version of the llvm-cgdata tool.
+:::
-.. option:: --format=[text|binary]
+## EXAMPLES
- Specify the format of the output .cgdata file.
-
-.. option:: --output=<string>
-
- Specify the output file name.
+To convert a .cgdata file from binary to text format:
-.. option:: --cgdata-version
+: \$ llvm-cgdata --convert --format=text input.cgdata --output=output.data
- Print the version of the llvm-cgdata tool.
+To merge multiple raw codegen data in object files into a single .cgdata file:
-EXAMPLES
---------
+: \$ llvm-cgdata --merge file1.o file2.o --output=merged.cgdata
-To convert a .cgdata file from binary to text format:
- $ llvm-cgdata --convert --format=text input.cgdata --output=output.data
+To show summary information about a .cgdata file:
-To merge multiple raw codegen data in object files into a single .cgdata file:
- $ llvm-cgdata --merge file1.o file2.o --output=merged.cgdata
+: \$ llvm-cgdata --show input.cgdata
-To show summary information about a .cgdata file:
- $ llvm-cgdata --show input.cgdata
diff --git a/llvm/docs/CommandGuide/llvm-config.md b/llvm/docs/CommandGuide/llvm-config.md
index 1c5c9c7447902..1e4395cc7d1b6 100644
--- a/llvm/docs/CommandGuide/llvm-config.md
+++ b/llvm/docs/CommandGuide/llvm-config.md
@@ -1,176 +1,170 @@
-llvm-config - Print LLVM compilation options
-============================================
+# llvm-config - Print LLVM compilation options
+```{eval-rst}
.. program:: llvm-config
+```
-SYNOPSIS
---------
+## SYNOPSIS
-**llvm-config** *option* [*components*...]
+**llvm-config** *option* \[*components*...\]
-DESCRIPTION
------------
+## DESCRIPTION
-**llvm-config** makes it easier to build applications that use LLVM. It can
+**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
---------
+## EXAMPLES
To link against the JIT:
-.. code-block:: sh
+```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`
+```
- 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
--------
+## OPTIONS
**--assertion-mode**
- Print the assertion mode used when LLVM was built (ON or OFF).
+> Print the assertion mode used when LLVM was built (ON or OFF).
**--bindir**
- Print the installation directory for LLVM binaries.
+> Print the installation directory for LLVM binaries.
**--build-mode**
- Print the build mode used when LLVM was built (e.g. Debug or Release).
+> Print the build mode used when LLVM was built (e.g. Debug or Release).
**--build-system**
- Print the build system used to build LLVM (e.g. `cmake` or `gn`).
+> Print the build system used to build LLVM (e.g. `cmake` or `gn`).
**--cflags**
- Print the C compiler flags needed to use LLVM headers.
+> Print the C compiler flags needed to use LLVM headers.
**--cmakedir**
- Print the installation directory for LLVM CMake modules.
+> Print the installation directory for LLVM CMake modules.
**--components**
- Print all valid component names.
+> Print all valid component names.
**--cppflags**
- Print the C preprocessor flags needed to use LLVM headers.
+> Print the C preprocessor flags needed to use LLVM headers.
**--cxxflags**
- Print the C++ compiler flags needed to use LLVM headers.
+> Print the C++ compiler flags needed to use LLVM headers.
**--has-rtti**
- Print whether or not LLVM was built with rtti (YES or NO).
+> Print whether or not LLVM was built with rtti (YES or NO).
**--help**
- Print a summary of **llvm-config** arguments.
+> Print a summary of **llvm-config** arguments.
**--host-target**
- Print the target triple used to configure LLVM.
+> Print the target triple used to configure LLVM.
**--ignore-libllvm**
- Ignore libLLVM and link component libraries instead.
+> Ignore libLLVM and link component libraries instead.
**--includedir**
- Print the installation directory for LLVM headers.
+> Print the installation directory for LLVM headers.
**--ldflags**
- Print the flags needed to link against LLVM libraries.
+> Print the flags needed to link against LLVM libraries.
**--libdir**
- Print the installation directory for LLVM libraries.
+> Print the installation directory for LLVM libraries.
**--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.
+> 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.
**--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.
+> 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.
**--libs**
- Print all the libraries needed to link against the specified LLVM
- *components*, including any dependencies.
+> Print all the libraries needed to link against the specified LLVM
+> *components*, including any dependencies.
**--link-shared**
- Link the components as shared libraries.
+> Link the components as shared libraries.
**--link-static**
- Link the component libraries statically.
+> Link the component libraries statically.
**--obj-root**
- Print the object root used to build LLVM.
+> Print the object root used to build LLVM.
**--prefix**
- Print the installation prefix for LLVM.
+> Print the installation prefix for LLVM.
**--quote-paths**
- Quote and escape paths when needed, most notably when a quote, space, backslash
- or dollar sign characters are present in the path.
+> Quote and escape paths when needed, most notably when a quote, space, backslash
+> or dollar sign characters are present in the path.
**--shared-mode**
- Print how the provided components can be collectively linked (`shared` or `static`).
+> Print how the provided components can be collectively linked (`shared` or `static`).
**--system-libs**
- Print all the system libraries needed to link against the specified LLVM
- *components*, including any dependencies.
+> Print all the system libraries needed to link against the specified LLVM
+> *components*, including any dependencies.
**--targets-built**
- Print the component names for all targets supported by this copy of LLVM.
+> Print the component names for all targets supported by this copy of LLVM.
**--version**
- Print the version number of LLVM.
-
+> Print the version number of LLVM.
-COMPONENTS
-----------
+## 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:
+--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.
+> Includes all LLVM libraries. The default if no components are specified.
**backend**
- Includes either a native backend or the C backend.
+> Includes either a native backend or the C backend.
**engine**
- Includes either a native JIT or the bitcode interpreter.
+> Includes either a native JIT or the bitcode interpreter.
+## EXIT STATUS
-EXIT STATUS
------------
-
-If **llvm-config** succeeds, it will exit with 0. Otherwise, if an error
+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/llvm/docs/CommandGuide/llvm-cov.md b/llvm/docs/CommandGuide/llvm-cov.md
index 72414c09044b0..547781a1cbc1f 100644
--- a/llvm/docs/CommandGuide/llvm-cov.md
+++ b/llvm/docs/CommandGuide/llvm-cov.md
@@ -1,416 +1,408 @@
-llvm-cov - emit coverage information
-====================================
+# llvm-cov - emit coverage information
+```{eval-rst}
.. program:: llvm-cov
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-cov` *command* [*args...*]
+{program}`llvm-cov` *command* \[*args...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-cov` tool shows code coverage information for
+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
+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
+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
---------
+## COMMANDS
-* :ref:`gcov <llvm-cov-gcov>`
-* :ref:`show <llvm-cov-show>`
-* :ref:`report <llvm-cov-report>`
-* :ref:`export <llvm-cov-export>`
+- {ref}`gcov <llvm-cov-gcov>`
+- {ref}`show <llvm-cov-show>`
+- {ref}`report <llvm-cov-report>`
+- {ref}`export <llvm-cov-export>`
+```{eval-rst}
.. program:: llvm-cov gcov
+```
-.. _llvm-cov-gcov:
+(llvm-cov-gcov)=
-GCOV COMMAND
-------------
+## GCOV COMMAND
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-cov gcov` [*options*] *SOURCEFILE*
+{program}`llvm-cov gcov` \[*options*\] *SOURCEFILE*
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-The :program:`llvm-cov gcov` tool reads code coverage data files and displays
+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``.
+`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
+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
+`-fprofile-arcs` and `-ftest-coverage` options to add the
+instrumentation. (Alternatively, you can use the `--coverage` option, which
includes both of those other options.)
-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``
+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
+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``
+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
+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.
+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`
+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.
+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
+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
+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:: -m, --demangled-names
-
- Demangle function names.
-
-.. 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:: -r
-
- Only dump files with relative paths or absolute paths with the prefix specified
- by ``-s``.
-
-.. option:: -s <string>
-
- Source prefix to elide.
-
-.. option:: -t, --stdout
-
- Print to stdout instead of producing ``.gcov`` files.
-
-.. option:: -u, --unconditional-branches
-
- Include unconditional branches in the output for the --branch-probabilities
- option.
-
-.. option:: -version
-
- Display the version of llvm-cov.
-
-.. option:: -x, --hash-filenames
-
- Use md5 hash of file name when naming the coverage output files. The source
- file name will be suffixed by ``##`` followed by MD5 hash calculated for it.
-
-EXIT STATUS
-^^^^^^^^^^^
-
-:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
+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} -m, --demangled-names
+Demangle function names.
+:::
+
+:::{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} -r
+Only dump files with relative paths or absolute paths with the prefix specified
+by `-s`.
+:::
+
+:::{option} -s <string>
+Source prefix to elide.
+:::
+
+:::{option} -t, --stdout
+Print to stdout instead of producing `.gcov` files.
+:::
+
+:::{option} -u, --unconditional-branches
+Include unconditional branches in the output for the --branch-probabilities
+option.
+:::
+
+:::{option} -version
+Display the version of llvm-cov.
+:::
+
+:::{option} -x, --hash-filenames
+Use md5 hash of file name when naming the coverage output files. The source
+file name will be suffixed by `##` followed by MD5 hash calculated for it.
+:::
+
+### EXIT STATUS
+
+{program}`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise,
it exits with zero.
+```{eval-rst}
.. program:: llvm-cov show
+```
-.. _llvm-cov-show:
+(llvm-cov-show)=
-SHOW COMMAND
-------------
+## SHOW COMMAND
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
+{program}`llvm-cov show` \[*options*\] -instr-profile *PROFILE* \[*BIN*\] \[*-object BIN*\]... \[*-sources*\] \[*SOURCE*\]...
-DESCRIPTION
-^^^^^^^^^^^
+### 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
+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 *SOURCE*....
*BIN* may be an executable, object file, dynamic library, or archive (thin or
otherwise).
-To use :program:`llvm-cov show`, you need a program that is compiled with
+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``
+`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*
+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`
+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-branches=<VIEW>
-
- Show coverage for branch conditions in terms of either count or percentage.
- The supported views are: "count", "percent".
-
-.. option:: -show-mcdc
-
- Show modified condition/decision coverage (MC/DC) for each applicable boolean
- expression.
-
-.. option:: -show-mcdc-non-executed-vectors
-
- When showing MC/DC details, also list test vectors that were not executed (for
- example in a ``Not executed`` section after the executed vectors). By default,
- only executed test vectors are shown.
-
-.. 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:: -show-directory-coverage
-
- Generate an index file in each directory that contains at least one source
- file with a top level index showing aggregates. 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-allowlist=<FILE>
-
- Show code coverage only for functions listed in the given file. Each line in
- the file should start with `allowlist_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:: -include-filename-regex=<PATTERN>
-
- Only include 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:: -compilation-dir=<dir>
-
- Directory used as a base for relative coverage mapping paths. Only applicable
- when binaries have been compiled with one of `-fcoverage-prefix-map`
- `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
-
-.. 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. Multiple
- `-path-equivalence` arguments can be passed to specify different mappings. Each
- argument consists of a source path `<from>` and its corresponding local path `<to>`.
- The mappings are applied in the order they are specified. If multiple mappings can
- be applied to a single path, the first mapping encountered is used.
-
-.. option:: -coverage-watermark=<high>,<low>
-
- Set high and low watermarks for coverage in html format output. This allows you
- to set the high and low watermark of coverage as desired, green when
- coverage >= high, red when coverage < low, and yellow otherwise. Both high and
- low should be between 0-100 and high > low.
-
-.. option:: -debuginfod
-
- Use debuginfod to look up coverage mapping for binary IDs present in the
- profile but not in any object given on the command line. Defaults to true if
- debuginfod is compiled in and configured via the DEBUGINFOD_URLS environment
- variable.
-
-.. option:: -debug-file-directory=<dir>
-
- Provides local directories to search for objects corresponding to binary IDs in
- the profile (as with debuginfod). Defaults to system build ID directories.
-
-.. option:: -check-binary-ids
-
- Fail if an object file cannot be found for a binary ID present in the profile,
- neither on the command line nor via binary ID lookup.
-
-.. option:: -empty-profile
-
- Display the baseline coverage of the binaries with all zero execution counts.
- Mutually exclusive with -instr-profile.
-
+### OPTIONS
+
+:::{option} -show-branches=<VIEW>
+Show coverage for branch conditions in terms of either count or percentage.
+The supported views are: "count", "percent".
+:::
+
+:::{option} -show-mcdc
+Show modified condition/decision coverage (MC/DC) for each applicable boolean
+expression.
+:::
+
+:::{option} -show-mcdc-non-executed-vectors
+When showing MC/DC details, also list test vectors that were not executed (for
+example in a `Not executed` section after the executed vectors). By default,
+only executed test vectors are shown.
+:::
+
+:::{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} -show-directory-coverage
+Generate an index file in each directory that contains at least one source
+file with a top level index showing aggregates. 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-allowlist=<FILE>
+Show code coverage only for functions listed in the given file. Each line in
+the file should start with `allowlist_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} -include-filename-regex=<PATTERN>
+Only include 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} -compilation-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of `-fcoverage-prefix-map`
+`-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
+:::
+
+:::{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. Multiple
+`-path-equivalence` arguments can be passed to specify different mappings. Each
+argument consists of a source path `<from>` and its corresponding local path `<to>`.
+The mappings are applied in the order they are specified. If multiple mappings can
+be applied to a single path, the first mapping encountered is used.
+:::
+
+:::{option} -coverage-watermark=<high>,<low>
+Set high and low watermarks for coverage in html format output. This allows you
+to set the high and low watermark of coverage as desired, green when
+coverage >= high, red when coverage < low, and yellow otherwise. Both high and
+low should be between 0-100 and high > low.
+:::
+
+:::{option} -debuginfod
+Use debuginfod to look up coverage mapping for binary IDs present in the
+profile but not in any object given on the command line. Defaults to true if
+debuginfod is compiled in and configured via the DEBUGINFOD_URLS environment
+variable.
+:::
+
+:::{option} -debug-file-directory=<dir>
+Provides local directories to search for objects corresponding to binary IDs in
+the profile (as with debuginfod). Defaults to system build ID directories.
+:::
+
+:::{option} -check-binary-ids
+Fail if an object file cannot be found for a binary ID present in the profile,
+neither on the command line nor via binary ID lookup.
+:::
+
+:::{option} -empty-profile
+Display the baseline coverage of the binaries with all zero execution counts.
+Mutually exclusive with -instr-profile.
+:::
+
+```{eval-rst}
.. program:: llvm-cov report
+```
-.. _llvm-cov-report:
+(llvm-cov-report)=
-REPORT COMMAND
---------------
+## REPORT COMMAND
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
+{program}`llvm-cov report` \[*options*\] -instr-profile *PROFILE* \[*BIN*\] \[*-object BIN*\]... \[*-sources*\] \[*SOURCE*\]...
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-The :program:`llvm-cov report` command displays a summary of the coverage of
+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 *SOURCE*....
@@ -419,93 +411,91 @@ otherwise).
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.
+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-region-summary
-
- Show statistics for all regions. Defaults to true.
-
-.. option:: -show-branch-summary
-
- Show statistics for all branch conditions. Defaults to true.
-
-.. option:: -show-mcdc-summary
-
- Show MC/DC statistics. Defaults to false.
-
-.. 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.
-
-.. option:: -compilation-dir=<dir>
-
- Directory used as a base for relative coverage mapping paths. Only applicable
- when binaries have been compiled with one of `-fcoverage-prefix-map`
- `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
-
-.. option:: -debuginfod
-
- Attempt to look up coverage mapping from objects using debuginfod. This is
- attempted by default for binary IDs present in the profile but not provided on
- the command line, so long as debuginfod is compiled in and configured via
- DEBUGINFOD_URLS.
-
-.. option:: -debug-file-directory=<dir>
-
- Provides a directory to search for objects corresponding to binary IDs in the
- profile.
-
-.. option:: -check-binary-ids
-
- Fail if an object file cannot be found for a binary ID present in the profile,
- neither on the command line nor via binary ID lookup.
-
-.. option:: -empty-profile
-
- Display the baseline coverage of the binaries with all zero execution counts.
- Mutually exclusive with -instr-profile.
-
+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-region-summary
+Show statistics for all regions. Defaults to true.
+:::
+
+:::{option} -show-branch-summary
+Show statistics for all branch conditions. Defaults to true.
+:::
+
+:::{option} -show-mcdc-summary
+Show MC/DC statistics. Defaults to false.
+:::
+
+:::{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.
+:::
+
+:::{option} -compilation-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of `-fcoverage-prefix-map`
+`-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
+:::
+
+:::{option} -debuginfod
+Attempt to look up coverage mapping from objects using debuginfod. This is
+attempted by default for binary IDs present in the profile but not provided on
+the command line, so long as debuginfod is compiled in and configured via
+DEBUGINFOD_URLS.
+:::
+
+:::{option} -debug-file-directory=<dir>
+Provides a directory to search for objects corresponding to binary IDs in the
+profile.
+:::
+
+:::{option} -check-binary-ids
+Fail if an object file cannot be found for a binary ID present in the profile,
+neither on the command line nor via binary ID lookup.
+:::
+
+:::{option} -empty-profile
+Display the baseline coverage of the binaries with all zero execution counts.
+Mutually exclusive with -instr-profile.
+:::
+
+```{eval-rst}
.. program:: llvm-cov export
+```
-.. _llvm-cov-export:
+(llvm-cov-export)=
-EXPORT COMMAND
---------------
+## EXPORT COMMAND
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* [*BIN*] [*-object BIN*]... [*-sources*] [*SOURCE*]...
+{program}`llvm-cov export` \[*options*\] -instr-profile *PROFILE* \[*BIN*\] \[*-object BIN*\]... \[*-sources*\] \[*SOURCE*\]...
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-The :program:`llvm-cov export` command exports coverage data of the binaries
+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.
@@ -517,100 +507,98 @@ The exported data can optionally be filtered to only export the coverage
for the files listed in *SOURCE*....
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.
-
-.. option:: -skip-expansions
-
- Skip exporting macro expansion coverage data.
-
-.. option:: -skip-functions
-
- Skip exporting per-function coverage data.
-
-.. option:: -show-mcdc-non-executed-vectors
-
- When MC/DC data is present in the export, include test vectors that were not
- executed (for JSON, these appear with ``"executed": false`` alongside executed
- vectors). By default, only executed MC/DC test vectors are exported.
-
-.. option:: -num-threads=N, -j=N
-
- Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
- appropriate number of threads to use. This is the default.
-
-.. option:: -compilation-dir=<dir>
-
- Directory used as a base for relative coverage mapping paths. Only applicable
- when binaries have been compiled with one of `-fcoverage-prefix-map`
- `-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
-
-.. option:: -debuginfod
-
- Attempt to look up coverage mapping from objects using debuginfod. This is
- attempted by default for binary IDs present in the profile but not provided on
- the command line, so long as debuginfod is compiled in and configured via
- DEBUGINFOD_URLS.
-
-.. option:: -debug-file-directory=<dir>
-
- Provides a directory to search for objects corresponding to binary IDs in the
- profile.
-
-.. option:: -check-binary-ids
-
- Fail if an object file cannot be found for a binary ID present in the profile,
- neither on the command line nor via binary ID lookup.
-
-.. option:: -empty-profile
-
- Export the baseline coverage of the binaries with all zero execution counts.
- Mutually exclusive with -instr-profile.
-
-CONVERT-FOR-TESTING COMMAND
----------------------------
-
-.. warning::
- This command is for the LLVM developers who are working on ``llvm-cov`` only.
-
-SYNOPSIS
-^^^^^^^^
-
-:program:`llvm-cov convert-for-testing` *BIN* -o *OUT*
-
-DESCRIPTION
-^^^^^^^^^^^
-
-The :program:`llvm-cov convert-for-testing` command serves the purpose of
+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.
+:::
+
+:::{option} -skip-expansions
+Skip exporting macro expansion coverage data.
+:::
+
+:::{option} -skip-functions
+Skip exporting per-function coverage data.
+:::
+
+:::{option} -show-mcdc-non-executed-vectors
+When MC/DC data is present in the export, include test vectors that were not
+executed (for JSON, these appear with `"executed": false` alongside executed
+vectors). By default, only executed MC/DC test vectors are exported.
+:::
+
+:::{option} -num-threads=N, -j=N
+Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
+appropriate number of threads to use. This is the default.
+:::
+
+:::{option} -compilation-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of `-fcoverage-prefix-map`
+`-fcoverage-compilation-dir`, or `-ffile-compilation-dir`.
+:::
+
+:::{option} -debuginfod
+Attempt to look up coverage mapping from objects using debuginfod. This is
+attempted by default for binary IDs present in the profile but not provided on
+the command line, so long as debuginfod is compiled in and configured via
+DEBUGINFOD_URLS.
+:::
+
+:::{option} -debug-file-directory=<dir>
+Provides a directory to search for objects corresponding to binary IDs in the
+profile.
+:::
+
+:::{option} -check-binary-ids
+Fail if an object file cannot be found for a binary ID present in the profile,
+neither on the command line nor via binary ID lookup.
+:::
+
+:::{option} -empty-profile
+Export the baseline coverage of the binaries with all zero execution counts.
+Mutually exclusive with -instr-profile.
+:::
+
+## CONVERT-FOR-TESTING COMMAND
+
+:::{warning}
+This command is for the LLVM developers who are working on `llvm-cov` only.
+:::
+
+### SYNOPSIS
+
+{program}`llvm-cov convert-for-testing` *BIN* -o *OUT*
+
+### DESCRIPTION
+
+The {program}`llvm-cov convert-for-testing` command serves the purpose of
testing `llvm-cov` itself. It can extract all code coverage data from the
binary *BIN* to the file *OUT*, thereby reducing the size of test files. The
-output file typically bears the :program:`.covmapping` extension.
+output file typically bears the {program}`.covmapping` extension.
-The :program:`.covmapping` files can be read back by ``llvm-cov`` just as
+The {program}`.covmapping` files can be read back by `llvm-cov` just as
ordinary binary files.
+
diff --git a/llvm/docs/CommandGuide/llvm-cxxfilt.md b/llvm/docs/CommandGuide/llvm-cxxfilt.md
index 8e509cec6ce02..c7f39ac357d70 100644
--- a/llvm/docs/CommandGuide/llvm-cxxfilt.md
+++ b/llvm/docs/CommandGuide/llvm-cxxfilt.md
@@ -1,89 +1,85 @@
-llvm-cxxfilt - LLVM symbol name demangler
-=========================================
+# llvm-cxxfilt - LLVM symbol name demangler
+```{eval-rst}
.. program:: llvm-cxxfilt
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-cxxfilt` [*options*] [*mangled names...*]
+{program}`llvm-cxxfilt` \[*options*\] \[*mangled names...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-cxxfilt` is a symbol demangler that can be used as a replacement
-for the GNU :program:`c++filt` tool. It takes a series of symbol names and
+{program}`llvm-cxxfilt` is a symbol demangler that can be used as a replacement
+for the GNU {program}`c++filt` tool. It takes a series of symbol names and
prints their demangled form on the standard output stream. If a name cannot be
demangled, it is simply printed as is.
If no names are specified on the command-line, names are read interactively from
the standard input stream. When reading names from standard input, each input
line is split on characters that are not part of valid Itanium name manglings,
-i.e. characters that are not alphanumeric, '.', '$', or '_'. Separators between
+i.e. characters that are not alphanumeric, '.', '\$', or '\_'. Separators between
names are copied to the output as is.
-EXAMPLE
--------
+## EXAMPLE
-.. code-block:: console
+```console
+$ llvm-cxxfilt _Z3foov _Z3bari not_mangled
+foo()
+bar(int)
+not_mangled
+$ cat input.txt
+| _Z3foov *** _Z3bari *** not_mangled |
+$ llvm-cxxfilt < input.txt
+| foo() *** bar(int) *** not_mangled |
+```
- $ llvm-cxxfilt _Z3foov _Z3bari not_mangled
- foo()
- bar(int)
- not_mangled
- $ cat input.txt
- | _Z3foov *** _Z3bari *** not_mangled |
- $ llvm-cxxfilt < input.txt
- | foo() *** bar(int) *** not_mangled |
+## OPTIONS
-OPTIONS
--------
+:::{option} --format=<value>, -s
+Mangling scheme to assume. Valid values are `auto` (default, auto-detect the
+style) and `gnu` (assume GNU/Itanium style).
+:::
-.. option:: --format=<value>, -s
+:::{option} --help, -h
+Print a summary of command line options.
+:::
- Mangling scheme to assume. Valid values are ``auto`` (default, auto-detect the
- style) and ``gnu`` (assume GNU/Itanium style).
+:::{option} --no-params, -p
+Do not demangle function parameters or return types.
+:::
-.. option:: --help, -h
+:::{option} --no-strip-underscore, -n
+Do not strip a leading underscore. This is the default for all platforms.
+:::
- Print a summary of command line options.
+:::{option} --quote
+Add `"` `"` around demangled names. Do not quote already quoted names.
+:::
-.. option:: --no-params, -p
+:::{option} --strip-underscore, -_
+Strip a single leading underscore, if present, from each input name before
+demangling.
+:::
- Do not demangle function parameters or return types.
+:::{option} --types, -t
+Attempt to demangle names as type names as well as symbol names.
+:::
-.. option:: --no-strip-underscore, -n
+:::{option} --version
+Display the version of the {program}`llvm-cxxfilt` executable.
+:::
- Do not strip a leading underscore. This is the default for all platforms.
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
-.. option:: --quote
+## EXIT STATUS
- Add `"` `"` around demangled names. Do not quote already quoted names.
-
-.. option:: --strip-underscore, -_
-
- Strip a single leading underscore, if present, from each input name before
- demangling.
-
-.. option:: --types, -t
-
- Attempt to demangle names as type names as well as symbol names.
-
-.. option:: --version
-
- Display the version of the :program:`llvm-cxxfilt` executable.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-EXIT STATUS
------------
-
-:program:`llvm-cxxfilt` returns 0 unless it encounters a usage error, in which
+{program}`llvm-cxxfilt` returns 0 unless it encounters a usage error, in which
case a non-zero exit code is returned.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-nm(1)`
-:manpage:`llvm-nm(1)`
diff --git a/llvm/docs/CommandGuide/llvm-cxxmap.md b/llvm/docs/CommandGuide/llvm-cxxmap.md
index dd38f3194b17f..7a4537d694ae3 100644
--- a/llvm/docs/CommandGuide/llvm-cxxmap.md
+++ b/llvm/docs/CommandGuide/llvm-cxxmap.md
@@ -1,101 +1,101 @@
-llvm-cxxmap - Mangled name remapping tool
-=========================================
+# llvm-cxxmap - Mangled name remapping tool
+```{eval-rst}
.. program:: llvm-cxxmap
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2*
+{program}`llvm-cxxmap` \[*options*\] *symbol-file-1* *symbol-file-2*
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names,
+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
+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
+```none
+<symbol-1> <symbol-2>
+```
- <symbol-1> <symbol-2>
-
-where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is
+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
--------
+## OPTIONS
+```{eval-rst}
.. 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} -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:: -Wambiguous
+:::{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.
+:::
- Produce a warning if there are multiple equivalent (but distinct) symbols in
- *symbol-file-2*.
+:::{option} -Wambiguous
+Produce a warning if there are multiple equivalent (but distinct) symbols in
+*symbol-file-2*.
+:::
-.. option:: -Wincomplete
+:::{option} -Wincomplete
+Produce a warning if *symbol-file-1* contains a symbol for which there is no
+equivalent symbol in *symbol-file-2*.
+:::
- 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:
-
-REMAPPING FILE
---------------
+## REMAPPING FILE
The remapping file is a text file containing lines of the form
-.. code-block:: none
-
- fragmentkind fragment1 fragment2
+```none
+fragmentkind fragment1 fragment2
+```
-where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
+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,
+\<[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.
+Blank lines and lines starting with `#` are ignored.
-Unmangled C names can be expressed as an ``encoding`` that is a (length-prefixed)
-<`source-name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.source-name>`_>:
+Unmangled C names can be expressed as an `encoding` that is a (length-prefixed)
+\<[source-name](http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.source-name)>:
-.. code-block:: none
+```none
+# C function "void foo_bar()" is remapped to C++ function "void foo::bar()".
+encoding 7foo_bar _Z3foo3barv
+```
- # C function "void foo_bar()" is remapped to C++ function "void foo::bar()".
- encoding 7foo_bar _Z3foo3barv
+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 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``
+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
+```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
+# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+name St St3__1
+name St St7__cxx11
+```
-.. note::
+:::{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.
+:::
- 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/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.md b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.md
index 3023d48b144dd..5067d4793f704 100644
--- a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.md
+++ b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.md
@@ -1,16 +1,17 @@
-llvm-debuginfo-analyzer - Print a logical representation of low-level debug information.
-========================================================================================
+# llvm-debuginfo-analyzer - Print a logical representation of low-level debug information.
+```{eval-rst}
.. program:: llvm-debuginfo-analyzer
+```
-SYNOPSIS
---------
-:program:`llvm-debuginfo-analyzer` [*options*] [*filename ...*]
+## SYNOPSIS
-DESCRIPTION
------------
-:program:`llvm-debuginfo-analyzer` parses debug and text sections in
+{program}`llvm-debuginfo-analyzer` \[*options*\] \[*filename ...*\]
+
+## DESCRIPTION
+
+{program}`llvm-debuginfo-analyzer` parses debug and text sections in
binary object files or LLVM IR textual / bitcode representation and prints
their contents in a logical view, which is a human readable representation
that closely matches the structure of the original user source code.
@@ -19,7 +20,7 @@ COFF and IR (textual representation and bitcode).
The **logical view** abstracts the complexity associated with the
different low-level representations of the debugging information that
-is embedded in the object file. :program:`llvm-debuginfo-analyzer`
+is embedded in the object file. {program}`llvm-debuginfo-analyzer`
produces a canonical view of the debug information regardless of how it
is formatted. The same logical view will be seen regardless of object
file format, assuming the debug information correctly represents the
@@ -29,370 +30,370 @@ The logical view includes the following **logical elements**: *type*,
*scope*, *symbol* and *line*, which are the basic software elements used
in the C/C++ programming language. Each logical element has a set of
**attributes**, such as *types*, *classes*, *functions*, *variables*,
-*parameters*, etc. The :option:`--attribute` can be used to specify which
+*parameters*, etc. The {option}`--attribute` can be used to specify which
attributes to include when printing a logical element. A logical element
may have a **kind** that describes specific types of elements. For
instance, a *scope* could have a kind value of *function*, *class*,
*namespace*.
-:program:`llvm-debuginfo-analyzer` defaults to print a pre-defined
+{program}`llvm-debuginfo-analyzer` defaults to print a pre-defined
layout of logical elements and attributes. The command line options can
-be used to control the printed elements (:option:`--print`), using a
-specific layout (:option:`--report`), matching a given pattern
-(:option:`--select`, :option:`--select-offsets`). Also, the output can
-be limited to specified logical elements using (:option:`--select-lines`,
-:option:`--select-scopes`, :option:`--select-symbols`,
-:option:`--select-types`).
-
-:program:`llvm-debuginfo-analyzer` can also compare a set of logical
-views (:option:`--compare`), to find differences and identify possible
-debug information syntax issues (:option:`--warning`) in any object file.
-
-OPTIONS
--------
-:program:`llvm-debuginfo-analyzer` options are separated into several
-categories, each tailored to a different purpose:
-
- * :ref:`general_` - Standard LLVM options to display help, version, etc.
- * :ref:`attributes_` - Describe how to include different details when
- printing an element.
- * :ref:`print_` - Specify which elements will be included when printing
- the view.
- * :ref:`output_` - Describe the supported formats when printing the view.
- * :ref:`report_` - Describe the format layouts for view printing.
- * :ref:`select_` - Allows to use specific criteria or conditions to
- select which elements to print.
- * :ref:`compare_` - Compare logical views and print missing and/or
- added elements.
- * :ref:`warning_` - Print the warnings detected during the creation
- of the view.
- * :ref:`internal_` - Internal analysis of the logical view.
-
-.. _general_:
-
-GENERAL
-~~~~~~~
-This section describes the standard help options, used to display the
-usage, version, response files, etc.
-
-.. option:: -h, --help
-
- Show help and usage for this command. (--help-hidden for more).
+be used to control the printed elements ({option}`--print`), using a
+specific layout ({option}`--report`), matching a given pattern
+({option}`--select`, {option}`--select-offsets`). Also, the output can
+be limited to specified logical elements using ({option}`--select-lines`,
+{option}`--select-scopes`, {option}`--select-symbols`,
+{option}`--select-types`).
-.. option:: --help-list
+{program}`llvm-debuginfo-analyzer` can also compare a set of logical
+views ({option}`--compare`), to find differences and identify possible
+debug information syntax issues ({option}`--warning`) in any object file.
- Show help and usage for this command without grouping the options
- into categories (--help-list-hidden for more).
+## OPTIONS
-.. option:: --help-hidden
+{program}`llvm-debuginfo-analyzer` options are separated into several
+categories, each tailored to a different purpose:
- Display all available options.
+> - {ref}`llvm-debuginfo-analyzer-general` - Standard LLVM options to display help, version, etc.
+> - {ref}`attributes` - Describe how to include different details when
+> printing an element.
+> - {ref}`print` - Specify which elements will be included when printing
+> the view.
+> - {ref}`output` - Describe the supported formats when printing the view.
+> - {ref}`report` - Describe the format layouts for view printing.
+> - {ref}`select` - Allows to use specific criteria or conditions to
+> select which elements to print.
+> - {ref}`compare` - Compare logical views and print missing and/or
+> added elements.
+> - {ref}`warning` - Print the warnings detected during the creation
+> of the view.
+> - {ref}`internal` - Internal analysis of the logical view.
+
+(llvm-debuginfo-analyzer-general)=
+
+### GENERAL
-.. option:: --print-all-options
+This section describes the standard help options, used to display the
+usage, version, response files, etc.
- Print all option values after command line parsing.
+:::{option} -h, --help
+Show help and usage for this command. (--help-hidden for more).
+:::
-.. option:: --print-options
+:::{option} --help-list
+Show help and usage for this command without grouping the options
+into categories (--help-list-hidden for more).
+:::
- Print non-default options after command line parsing
+:::{option} --help-hidden
+Display all available options.
+:::
-.. option:: --version
+:::{option} --print-all-options
+Print all option values after command line parsing.
+:::
- Display the version of the tool.
+:::{option} --print-options
+Print non-default options after command line parsing
+:::
-.. option:: @<FILE>
+:::{option} --version
+Display the version of the tool.
+:::
- Read command-line options from `<FILE>`.
+:::{option} @<FILE>
+Read command-line options from `<FILE>`.
+:::
-If no input file is specified, :program:`llvm-debuginfo-analyzer`
+If no input file is specified, {program}`llvm-debuginfo-analyzer`
defaults to read `a.out` and return an error when no input file is found.
-If `-` is used as the input file, :program:`llvm-debuginfo-analyzer`
+If `-` is used as the input file, {program}`llvm-debuginfo-analyzer`
reads the input from its standard input stream.
-.. _attributes_:
+(attributes)=
+
+### ATTRIBUTES
-ATTRIBUTES
-~~~~~~~~~~
The following options enable attributes given for the printed elements.
The attributes are divided in categories based on the type of data being
added, such as: internal offsets in the binary file, location descriptors,
register names, user source filenames, additional element transformations,
toolchain name, binary file format, etc.
-.. option:: --attribute=<value[,value,...]>
-
- With **value** being one of the options in the following lists.
+:::{option} --attribute=<value[,value,...]>
+With **value** being one of the options in the following lists.
+
+```text
+=all: Include all the below attributes.
+=extended: Add low-level attributes.
+=standard: Add standard high-level attributes.
+```
+
+The following attributes describe the most common information for a
+logical element. They help to identify the lexical scope level; the
+element visibility across modules (global, local); the toolchain name
+and source language that produced the binary file.
+
+```text
+=global: Element referenced across Compile Units.
+=format: Object file format name.
+=language: Source language name.
+=level: Lexical scope level (File=0, Compile Unit=1).
+=local: Element referenced only in the Compile Unit.
+=producer: Toolchain identification name.
+```
+
+The following attributes describe files and directory names from the
+user source code, where the elements are declared or defined; functions
+with public visibility across modules. These options allow to map the
+elements to their user code location, for cross references purposes.
+
+```text
+=directories: Directories referenced in the debug information.
+=filename: Filename where the element is defined.
+=files: Files referenced in the debug information.
+=pathname: Pathname where the object is defined.
+=publics: Function names that are public.
+```
+
+The following attributes describe additional logical element source
+transformations, in order to display built-in types (int, bool, etc.);
+parameters and arguments used during template instantiation; parent
+name hierarchy; array dimensions information; compiler generated
+elements; type sizes and the underlying types associated with the types
+aliases.
+
+```text
+=argument: Template parameters replaced by its arguments.
+=base: Base types (int, bool, etc.).
+=generated: Compiler generated elements.
+=encoded: Template arguments encoded in the template name.
+=qualified: The element type include parents in its name.
+=reference: Element declaration and definition references.
+=size: Sizes for compound and base types.
+=subrange: Subrange encoding information for arrays.
+=typename: Template parameters.
+=underlying: Underlying type for type definitions.
+```
+
+The following attributes describe the debug location information for
+a symbol or scope. It includes the symbol percentage coverage and any
+gaps within the location layout; ranges determining the code sections
+attached to a function. When descriptors are used, the target processor
+registers are displayed.
+
+```text
+=coverage: Symbol location coverage.
+=gaps: Missing debug location (gaps).
+=location: Symbol debug location.
+=range: Debug location ranges.
+=register: Processor register names.
+```
+
+The following attributes are associated with low level details, such
+as: offsets in the binary file; discriminators added to the lines of
+inlined functions in order to distinguish specific instances; debug
+lines state machine registers; elements discarded by the compiler
+(inlining) or by the linker optimizations (dead-stripping); system
+compile units generated by the MS toolchain in PDBs.
+
+```text
+=discarded: Discarded elements by the linker.
+=discriminator: Discriminators for inlined function instances.
+=inserted: Generated inlined abstract references.
+=linkage: Object file linkage name.
+=offset: Debug information offset.
+=qualifier: Line qualifiers (Newstatement, BasicBlock, etc).
+=zero: Zero line numbers.
+```
+
+The following attribute described specific information for the **PE/COFF**
+file format. It includes MS runtime types.
+
+```text
+=system: Display PDB's MS system elements.
+```
+
+The above attributes are grouped into *standard* and *extended*
+categories that can be enabled.
+
+The *standard* group, contains those attributes that add sufficient
+information to describe a logical element and that can cover the
+normal situations while dealing with debug information.
+
+```text
+=base
+=coverage
+=directories
+=discriminator
+=filename
+=files
+=format
+=language
+=level
+=producer
+=publics
+=range
+=reference
+=zero
+```
+
+The *extended* group, contains those attributes that require a more
+extended knowledge about debug information. They are intended when a
+lower level of detail is required.
+
+```text
+=argument
+=discarded
+=encoded
+=gaps
+=generated
+=global
+=inserted
+=linkage
+=local
+=location
+=offset
+=operation
+=pathname
+=qualified
+=qualifier
+=register
+=size
+=subrange
+=system
+=typename
+```
+:::
+
+(print)=
+
+### PRINT
- .. code-block:: text
-
- =all: Include all the below attributes.
- =extended: Add low-level attributes.
- =standard: Add standard high-level attributes.
-
- The following attributes describe the most common information for a
- logical element. They help to identify the lexical scope level; the
- element visibility across modules (global, local); the toolchain name
- and source language that produced the binary file.
-
- .. code-block:: text
-
- =global: Element referenced across Compile Units.
- =format: Object file format name.
- =language: Source language name.
- =level: Lexical scope level (File=0, Compile Unit=1).
- =local: Element referenced only in the Compile Unit.
- =producer: Toolchain identification name.
-
- The following attributes describe files and directory names from the
- user source code, where the elements are declared or defined; functions
- with public visibility across modules. These options allow to map the
- elements to their user code location, for cross references purposes.
-
- .. code-block:: text
-
- =directories: Directories referenced in the debug information.
- =filename: Filename where the element is defined.
- =files: Files referenced in the debug information.
- =pathname: Pathname where the object is defined.
- =publics: Function names that are public.
-
- The following attributes describe additional logical element source
- transformations, in order to display built-in types (int, bool, etc.);
- parameters and arguments used during template instantiation; parent
- name hierarchy; array dimensions information; compiler generated
- elements; type sizes and the underlying types associated with the types
- aliases.
-
- .. code-block:: text
-
- =argument: Template parameters replaced by its arguments.
- =base: Base types (int, bool, etc.).
- =generated: Compiler generated elements.
- =encoded: Template arguments encoded in the template name.
- =qualified: The element type include parents in its name.
- =reference: Element declaration and definition references.
- =size: Sizes for compound and base types.
- =subrange: Subrange encoding information for arrays.
- =typename: Template parameters.
- =underlying: Underlying type for type definitions.
-
- The following attributes describe the debug location information for
- a symbol or scope. It includes the symbol percentage coverage and any
- gaps within the location layout; ranges determining the code sections
- attached to a function. When descriptors are used, the target processor
- registers are displayed.
-
- .. code-block:: text
-
- =coverage: Symbol location coverage.
- =gaps: Missing debug location (gaps).
- =location: Symbol debug location.
- =range: Debug location ranges.
- =register: Processor register names.
-
- The following attributes are associated with low level details, such
- as: offsets in the binary file; discriminators added to the lines of
- inlined functions in order to distinguish specific instances; debug
- lines state machine registers; elements discarded by the compiler
- (inlining) or by the linker optimizations (dead-stripping); system
- compile units generated by the MS toolchain in PDBs.
-
- .. code-block:: text
-
- =discarded: Discarded elements by the linker.
- =discriminator: Discriminators for inlined function instances.
- =inserted: Generated inlined abstract references.
- =linkage: Object file linkage name.
- =offset: Debug information offset.
- =qualifier: Line qualifiers (Newstatement, BasicBlock, etc).
- =zero: Zero line numbers.
-
- The following attribute described specific information for the **PE/COFF**
- file format. It includes MS runtime types.
-
- .. code-block:: text
-
- =system: Display PDB's MS system elements.
-
- The above attributes are grouped into *standard* and *extended*
- categories that can be enabled.
-
- The *standard* group, contains those attributes that add sufficient
- information to describe a logical element and that can cover the
- normal situations while dealing with debug information.
-
- .. code-block:: text
-
- =base
- =coverage
- =directories
- =discriminator
- =filename
- =files
- =format
- =language
- =level
- =producer
- =publics
- =range
- =reference
- =zero
-
- The *extended* group, contains those attributes that require a more
- extended knowledge about debug information. They are intended when a
- lower level of detail is required.
-
- .. code-block:: text
-
- =argument
- =discarded
- =encoded
- =gaps
- =generated
- =global
- =inserted
- =linkage
- =local
- =location
- =offset
- =operation
- =pathname
- =qualified
- =qualifier
- =register
- =size
- =subrange
- =system
- =typename
-
-.. _print_:
-
-PRINT
-~~~~~
The following options describe the elements to print. The layout used
-is determined by the :option:`--report`. In the tree layout, all the
+is determined by the {option}`--report`. In the tree layout, all the
elements have their enclosing lexical scopes printed, even when not
explicitly specified.
-.. option:: --print=<value[,value,...]>
-
- With **value** being one of the options in the following lists.
+:::{option} --print=<value[,value,...]>
+With **value** being one of the options in the following lists.
- .. code-block:: text
+```text
+=all: Include all the below attributes.
+```
- =all: Include all the below attributes.
+The following options print the requested elements; in the case of any
+given select conditions ({option}`--select`), only those elements that
+match them, will be printed. The **elements** value is a convenient
+way to specify instructions, lines, scopes, symbols and types all at
+once.
- The following options print the requested elements; in the case of any
- given select conditions (:option:`--select`), only those elements that
- match them, will be printed. The **elements** value is a convenient
- way to specify instructions, lines, scopes, symbols and types all at
- once.
+```text
+=elements: Instructions, lines, scopes, symbols and types.
+=instructions: Assembler instructions for code sections.
+=lines: Source lines referenced in the debug information.
+=scopes: Lexical blocks (function, class, namespace, etc).
+=symbols: Symbols (variable, member, parameter, etc).
+=types: Types (pointer, reference, type alias, etc).
+```
- .. code-block:: text
+The following options print information, collected during the creation
+of the elements, such as: scope contributions to the debug information;
+summary of elements created, printed or matched ({option}`--select`);
+warnings produced during the view creation.
- =elements: Instructions, lines, scopes, symbols and types.
- =instructions: Assembler instructions for code sections.
- =lines: Source lines referenced in the debug information.
- =scopes: Lexical blocks (function, class, namespace, etc).
- =symbols: Symbols (variable, member, parameter, etc).
- =types: Types (pointer, reference, type alias, etc).
+```text
+=sizes: Debug Information scopes contributions.
+=summary: Summary of elements allocated, selected or printed.
+=warnings: Warnings detected.
+```
- The following options print information, collected during the creation
- of the elements, such as: scope contributions to the debug information;
- summary of elements created, printed or matched (:option:`--select`);
- warnings produced during the view creation.
+Note: The **--print=sizes** option is ELF specific.
+:::
- .. code-block:: text
+(output)=
- =sizes: Debug Information scopes contributions.
- =summary: Summary of elements allocated, selected or printed.
- =warnings: Warnings detected.
+### OUTPUT
- Note: The **--print=sizes** option is ELF specific.
-
-.. _output_:
-
-OUTPUT
-~~~~~~
The following options describe how to control the output generated when
printing the logical elements.
-.. option:: --output-file=<path>
-
- Redirect the output to a file specified by <path>, where - is the
- standard output stream.
+:::{option} --output-file=<path>
+Redirect the output to a file specified by \<path>, where - is the
+standard output stream.
+:::
-:program:`llvm-debuginfo-analyzer` has the concept of **split view**.
+{program}`llvm-debuginfo-analyzer` has the concept of **split view**.
When redirecting the output from a complex binary format, it is
**divided** into individual files, each one containing the logical view
output for a single compilation unit.
-.. option:: --output-folder=<name>
-
- The folder to write a file per compilation unit when **--output=split**
- is specified.
-
-.. option:: --output-level=<level>
+:::{option} --output-folder=<name>
+The folder to write a file per compilation unit when **--output=split**
+is specified.
+:::
+
+:::{option} --output-level=<level>
+Only print elements up to the given **lexical level** value. The input
+file is at lexical level zero and a compilation unit is at lexical level
+one.
+:::
+
+:::{option} --output=<value[,value,...]>
+With **value** being one of the options in the following lists.
+
+```text
+=all: Include all the below outputs.
+```
+
+```text
+=json: Use JSON as the output format (Not implemented).
+=split: Split the output by Compile Units.
+=text: Use a free form text output.
+```
+:::
+
+:::{option} --output-sort=<key>
+Primary key when ordering the elements in the output (default: line).
+Sorting by logical element kind, requires be familiarity with the
+element kind selection options ({option}`--select-lines`,
+{option}`--select-scopes`, {option}`--select-symbols`,
+{option}`--select-types`), as those options describe the different
+logical element kinds.
+
+```text
+=none: Unsorted output (i.e. as read from input).
+=id: Sort by unique element ID.
+=kind: Sort by element kind.
+=line: Sort by element line number.
+=name: Sort by element name.
+=offset: Sort by element offset.
+```
+:::
+
+(report)=
+
+### REPORT
- Only print elements up to the given **lexical level** value. The input
- file is at lexical level zero and a compilation unit is at lexical level
- one.
-
-.. option:: --output=<value[,value,...]>
-
- With **value** being one of the options in the following lists.
-
- .. code-block:: text
-
- =all: Include all the below outputs.
-
- .. code-block:: text
-
- =json: Use JSON as the output format (Not implemented).
- =split: Split the output by Compile Units.
- =text: Use a free form text output.
-
-.. option:: --output-sort=<key>
-
- Primary key when ordering the elements in the output (default: line).
- Sorting by logical element kind, requires be familiarity with the
- element kind selection options (:option:`--select-lines`,
- :option:`--select-scopes`, :option:`--select-symbols`,
- :option:`--select-types`), as those options describe the different
- logical element kinds.
-
- .. code-block:: text
-
- =none: Unsorted output (i.e. as read from input).
- =id: Sort by unique element ID.
- =kind: Sort by element kind.
- =line: Sort by element line number.
- =name: Sort by element name.
- =offset: Sort by element offset.
-
-.. _report_:
-
-REPORT
-~~~~~~
Depending on the task being executed (print, compare, select), several
layouts are supported to display the elements in a more suitable way,
to make the output easier to understand.
-.. option:: --report=<value[,value,...]>
-
- With **value** being one of the options in the following list.
-
- .. code-block:: text
-
- =all: Include all the below reports.
+:::{option} --report=<value[,value,...]>
+With **value** being one of the options in the following list.
- .. code-block:: text
+```text
+=all: Include all the below reports.
+```
- =children: Elements and children are displayed in a tree format.
- =list: Elements are displayed in a tabular format.
- =parents: Elements and parents are displayed in a tree format.
- =view: Elements, parents and children are displayed in a tree format.
+```text
+=children: Elements and children are displayed in a tree format.
+=list: Elements are displayed in a tabular format.
+=parents: Elements and parents are displayed in a tree format.
+=view: Elements, parents and children are displayed in a tree format.
+```
+:::
The **list** layout presents the logical elements in a tabular form
without any parent-child relationship. This may be the preferred way to
@@ -407,187 +408,187 @@ file being the tree root (level 0) and each compilation unit being a
child (level 1).
The **children** layout includes the elements that match any given
-criteria (:option:`--select`) or (:option:`--compare`) and its children.
+criteria ({option}`--select`) or ({option}`--compare`) and its children.
The **parents** layout includes the elements that match any given
-criteria (:option:`--select`) or (:option:`--compare`) and its parents.
+criteria ({option}`--select`) or ({option}`--compare`) and its parents.
The combined **view** layout includes the elements that match any given
-criteria (:option:`--select`) or (:option:`--compare`), its parents
+criteria ({option}`--select`) or ({option}`--compare`), its parents
and children.
**Notes**:
-1. When a selection criteria (:option:`--select`) is specified with no
+1. When a selection criteria ({option}`--select`) is specified with no
report option, the **list** layout is selected.
2. The comparison mode always uses the **view** layout.
-.. _select_:
+(select)=
+
+### SELECTION
-SELECTION
-~~~~~~~~~
When printing an element, different data can be included and it varies
-(:option:`--attribute`) from data directly associated with the binary
+({option}`--attribute`) from data directly associated with the binary
file (offset) to high level details such as coverage, lexical scope
level, location. As the printed output can reach a considerable size,
several selection options, enable printing of specific elements.
-The pattern matching can ignore the case (:option:`--select-nocase`)
-and be extended to use regular expressions (:option:`--select-regex`).
-
-ELEMENTS
-^^^^^^^^
-The following options allow printing of elements that match the given
-<pattern>, offset <value> or an element <condition>.
-
-.. option:: --select=<pattern>
-
- Print all elements whose name or line number matches the given <pattern>.
+The pattern matching can ignore the case ({option}`--select-nocase`)
+and be extended to use regular expressions ({option}`--select-regex`).
-.. option:: --select-offsets=<value[,value,...]>
+#### ELEMENTS
- Print all elements whose offset matches the given values. See
- :option:`--attribute` option.
-
-.. option:: --select-elements=<condition[,condition,...]>
-
- Print all elements that satisfy the given <condition>. With **condition**
- being one of the options in the following list.
-
- .. code-block:: text
-
- =discarded: Discarded elements by the linker.
- =global: Element referenced across Compile Units.
- =optimized: Optimized inlined abstract references.
-
-.. option:: --select-nocase
-
- Pattern matching is case-insensitive when using :option:`--select`.
-
-.. option:: --select-regex
-
- Treat any <pattern> strings as regular expressions when selecting with
- :option:`--select` option. If :option:`--select-nocase` is specified,
- the regular expression becomes case-insensitive.
-
-If the <pattern> criteria is too general, a more selective option can
+The following options allow printing of elements that match the given
+\<pattern>, offset \<value> or an element \<condition>.
+
+:::{option} --select=<pattern>
+Print all elements whose name or line number matches the given \<pattern>.
+:::
+
+:::{option} --select-offsets=<value[,value,...]>
+Print all elements whose offset matches the given values. See
+{option}`--attribute` option.
+:::
+
+:::{option} --select-elements=<condition[,condition,...]>
+Print all elements that satisfy the given \<condition>. With **condition**
+being one of the options in the following list.
+
+```text
+=discarded: Discarded elements by the linker.
+=global: Element referenced across Compile Units.
+=optimized: Optimized inlined abstract references.
+```
+:::
+
+:::{option} --select-nocase
+Pattern matching is case-insensitive when using {option}`--select`.
+:::
+
+:::{option} --select-regex
+Treat any \<pattern> strings as regular expressions when selecting with
+{option}`--select` option. If {option}`--select-nocase` is specified,
+the regular expression becomes case-insensitive.
+:::
+
+If the \<pattern> criteria is too general, a more selective option can
be specified to target a particular category of elements:
-lines (:option:`--select-lines`), scopes (:option:`--select-scopes`),
-symbols (:option:`--select-symbols`) and types (:option:`--select-types`).
+lines ({option}`--select-lines`), scopes ({option}`--select-scopes`),
+symbols ({option}`--select-symbols`) and types ({option}`--select-types`).
These options require knowledge of the debug information format (DWARF,
CodeView), as the given **kind** describes a very specific type
of element.
-LINES
-^^^^^
-The following options allow printing of lines that match the given <kind>.
+#### LINES
+
+The following options allow printing of lines that match the given \<kind>.
The given criteria describes the debug line state machine registers.
-.. option:: --select-lines=<kind[,kind,...]>
-
- With **kind** being one of the options in the following list.
-
- .. code-block:: text
-
- =AlwaysStepInto: marks an always step into.
- =BasicBlock: Marks a new basic block.
- =Discriminator: Line that has a discriminator.
- =EndSequence: Marks the end in the sequence of lines.
- =EpilogueBegin: Marks the start of a function epilogue.
- =LineAssembler: Lines that correspond to disassembly text.
- =LineDebug: Lines that correspond to debug lines.
- =NeverStepInto: marks a never step into.
- =NewStatement: Marks a new statement.
- =PrologueEnd: Marks the end of a function prologue.
-
-SCOPES
-^^^^^^
-The following options allow printing of scopes that match the given <kind>.
-
-.. option:: --select-scopes=<kind[,kind,...]>
-
- With **kind** being one of the options in the following list.
-
- .. code-block:: text
-
- =Aggregate: A class, structure or union.
- =Array: An array.
- =Block: A generic block (lexical block or exception block).
- =CallSite: A call site.
- =CatchBlock: An exception block.
- =Class: A class.
- =CompileUnit: A compile unit.
- =EntryPoint: A subroutine entry point.
- =Enumeration: An enumeration.
- =Function: A function.
- =FunctionType: A function pointer.
- =InlinedFunction: An inlined function.
- =Label: A label.
- =LexicalBlock: A lexical block.
- =Module: A module.
- =Namespace: A namespace.
- =Root: The element representing the main scope.
- =Structure: A structure.
- =Subprogram: A subprogram.
- =Template: A template definition.
- =TemplateAlias: A template alias.
- =TemplatePack: A template pack.
- =TryBlock: An exception try block.
- =Union: A union.
-
-SYMBOLS
-^^^^^^^
-The following options allow printing of symbols that match the given <kind>.
-
-.. option:: --select-symbols=<kind[,kind,...]>
-
- With **kind** being one of the options in the following list.
-
- .. code-block:: text
-
- =CallSiteParameter: A call site parameter.
- =Constant: A constant symbol.
- =Inheritance: A base class.
- =Member: A member class.
- =Parameter: A parameter to function.
- =Unspecified: Unspecified parameters to function.
- =Variable: A variable.
-
-TYPES
-^^^^^
-The following options allow printing of types that match the given <kind>.
-
-.. option:: --select-types=<kind[,kind,...]>
-
- With **kind** being one of the options in the following list.
-
- .. code-block:: text
-
- =Base: Base type (integer, boolean, etc).
- =Const: Constant specifier.
- =Enumerator: Enumerator.
- =Import: Import declaration.
- =ImportDeclaration: Import declaration.
- =ImportModule: Import module.
- =Pointer: Pointer type.
- =PointerMember: Pointer to member function.
- =Reference: Reference type.
- =Restrict: Restrict specifier.
- =RvalueReference: R-value reference.
- =Subrange: Array subrange.
- =TemplateParam: Template parameter.
- =TemplateTemplateParam: Template template parameter.
- =TemplateTypeParam: Template type parameter.
- =TemplateValueParam: Template value parameter.
- =Typedef: Type definition.
- =Unspecified: Unspecified type.
- =Volatile: Volatile specifier.
-
-.. _compare_:
-
-COMPARE
-~~~~~~~
+:::{option} --select-lines=<kind[,kind,...]>
+With **kind** being one of the options in the following list.
+
+```text
+=AlwaysStepInto: marks an always step into.
+=BasicBlock: Marks a new basic block.
+=Discriminator: Line that has a discriminator.
+=EndSequence: Marks the end in the sequence of lines.
+=EpilogueBegin: Marks the start of a function epilogue.
+=LineAssembler: Lines that correspond to disassembly text.
+=LineDebug: Lines that correspond to debug lines.
+=NeverStepInto: marks a never step into.
+=NewStatement: Marks a new statement.
+=PrologueEnd: Marks the end of a function prologue.
+```
+:::
+
+#### SCOPES
+
+The following options allow printing of scopes that match the given \<kind>.
+
+:::{option} --select-scopes=<kind[,kind,...]>
+With **kind** being one of the options in the following list.
+
+```text
+=Aggregate: A class, structure or union.
+=Array: An array.
+=Block: A generic block (lexical block or exception block).
+=CallSite: A call site.
+=CatchBlock: An exception block.
+=Class: A class.
+=CompileUnit: A compile unit.
+=EntryPoint: A subroutine entry point.
+=Enumeration: An enumeration.
+=Function: A function.
+=FunctionType: A function pointer.
+=InlinedFunction: An inlined function.
+=Label: A label.
+=LexicalBlock: A lexical block.
+=Module: A module.
+=Namespace: A namespace.
+=Root: The element representing the main scope.
+=Structure: A structure.
+=Subprogram: A subprogram.
+=Template: A template definition.
+=TemplateAlias: A template alias.
+=TemplatePack: A template pack.
+=TryBlock: An exception try block.
+=Union: A union.
+```
+:::
+
+#### SYMBOLS
+
+The following options allow printing of symbols that match the given \<kind>.
+
+:::{option} --select-symbols=<kind[,kind,...]>
+With **kind** being one of the options in the following list.
+
+```text
+=CallSiteParameter: A call site parameter.
+=Constant: A constant symbol.
+=Inheritance: A base class.
+=Member: A member class.
+=Parameter: A parameter to function.
+=Unspecified: Unspecified parameters to function.
+=Variable: A variable.
+```
+:::
+
+#### TYPES
+
+The following options allow printing of types that match the given \<kind>.
+
+:::{option} --select-types=<kind[,kind,...]>
+With **kind** being one of the options in the following list.
+
+```text
+=Base: Base type (integer, boolean, etc).
+=Const: Constant specifier.
+=Enumerator: Enumerator.
+=Import: Import declaration.
+=ImportDeclaration: Import declaration.
+=ImportModule: Import module.
+=Pointer: Pointer type.
+=PointerMember: Pointer to member function.
+=Reference: Reference type.
+=Restrict: Restrict specifier.
+=RvalueReference: R-value reference.
+=Subrange: Array subrange.
+=TemplateParam: Template parameter.
+=TemplateTemplateParam: Template template parameter.
+=TemplateTypeParam: Template type parameter.
+=TemplateValueParam: Template value parameter.
+=Typedef: Type definition.
+=Unspecified: Unspecified type.
+=Volatile: Volatile specifier.
+```
+:::
+
+(compare)=
+
+### COMPARE
+
When dealing with debug information, there are situations when the
printing of the elements is not the correct approach. That is the case,
when we are interested in the effects caused by different versions of
@@ -598,7 +599,7 @@ or removed. Due to the complicated debug information format, it is very
difficult to use a regular diff tool to find those elements; even
impossible when dealing with different debug formats.
-:program:`llvm-debuginfo-analyzer` supports a logical element comparison,
+{program}`llvm-debuginfo-analyzer` supports a logical element comparison,
allowing to find semantic differences between logical views, produced by
different toolchain versions or even debug information formats.
@@ -610,253 +611,253 @@ view created from a binary file with CodeView debug information.
The following options describe the elements to compare.
-.. option:: --compare=<value[,value,...]>
-
- With **value** being one of the options in the following list.
-
- .. code-block:: text
-
- =all: Include all the below elements.
+:::{option} --compare=<value[,value,...]>
+With **value** being one of the options in the following list.
- .. code-block:: text
+```text
+=all: Include all the below elements.
+```
- =lines: Include lines.
- =scopes: Include scopes.
- =symbols: Include symbols.
- =types: Include types.
+```text
+=lines: Include lines.
+=scopes: Include scopes.
+=symbols: Include symbols.
+=types: Include types.
+```
+:::
-:program:`llvm-debuginfo-analyzer` takes the first binary file on the
+{program}`llvm-debuginfo-analyzer` takes the first binary file on the
command line as the **reference** and the second one as the **target**.
To get a more descriptive report, the comparison is done twice. The
reference and target views are swapped, in order to produce those
**missing** elements from the target view and those **added** elements
to the reference view.
-See :option:`--report` options on how to describe the comparison
+See {option}`--report` options on how to describe the comparison
reports.
-.. _warning_:
+(warning)=
-WARNING
-~~~~~~~
-When reading the input object files, :program:`llvm-debuginfo-analyzer`
+### WARNING
+
+When reading the input object files, {program}`llvm-debuginfo-analyzer`
can detect issues in the raw debug information. These may not be
considered fatal to the purpose of printing a logical view but they can
give an indication about the quality and potentially expose issues with
the generated debug information.
The following options describe the warnings to be recorded for later
-printing, if they are requested by :option:`--print`.
-
-.. option:: --warning=<value[,value,...]>
-
- With **value** being one of the options in the following list.
-
- .. code-block:: text
-
- =all: Include all the below warnings.
+printing, if they are requested by {option}`--print`.
+
+:::{option} --warning=<value[,value,...]>
+With **value** being one of the options in the following list.
+
+```text
+=all: Include all the below warnings.
+```
+
+The following options collect additional information during the creation
+of the logical view, to include invalid coverage values and locations
+for symbols; invalid code ranges; lines that are zero.
+
+```text
+=coverages: Invalid symbol coverages values.
+=lines: Debug lines that are zero.
+=locations: Invalid symbol locations.
+=ranges: Invalid code ranges.
+```
+:::
+
+(internal)=
+
+### INTERNAL
+
+> For a better understanding of the logical view, access to more detailed
+> internal information could be needed. Such data would help to identify
+> debug information processed or incorrect logical element management.
+> Typically these kind of options are available only in *debug* builds.
+>
+> {program}`llvm-debuginfo-analyzer` supports these advanced options in
+> both *release* and *debug* builds.
+
+:::{option} --internal=<value[,value,...]>
+With **value** being one of the options in the following list.
+
+```text
+=all: Include all the below options.
+```
+
+The following options allow to check the integrity of the logical view;
+collect the debug tags that are processed or not implemented; ignore the
+logical element line number, to facilitate the logical view comparison
+when using external comparison tools; print the command line options
+used to invoke {program}`llvm-debuginfo-analyzer`.
+
+```text
+=id: Print unique element ID.
+=cmdline: Print command line.
+=integrity: Check elements integrity.
+=none: Ignore element line number.
+=tag: Debug information tags.
+```
+
+**Note:** For ELF format, the collected tags represent the debug tags
+that are not processed. For PE/COFF format, they represent the tags
+that are processed.
+:::
+
+## EXAMPLES
- The following options collect additional information during the creation
- of the logical view, to include invalid coverage values and locations
- for symbols; invalid code ranges; lines that are zero.
-
- .. code-block:: text
-
- =coverages: Invalid symbol coverages values.
- =lines: Debug lines that are zero.
- =locations: Invalid symbol locations.
- =ranges: Invalid code ranges.
-
-.. _internal_:
-
-INTERNAL
-~~~~~~~~
- For a better understanding of the logical view, access to more detailed
- internal information could be needed. Such data would help to identify
- debug information processed or incorrect logical element management.
- Typically these kind of options are available only in *debug* builds.
-
- :program:`llvm-debuginfo-analyzer` supports these advanced options in
- both *release* and *debug* builds.
-
-.. option:: --internal=<value[,value,...]>
-
- With **value** being one of the options in the following list.
-
- .. code-block:: text
-
- =all: Include all the below options.
-
- The following options allow to check the integrity of the logical view;
- collect the debug tags that are processed or not implemented; ignore the
- logical element line number, to facilitate the logical view comparison
- when using external comparison tools; print the command line options
- used to invoke :program:`llvm-debuginfo-analyzer`.
-
- .. code-block:: text
-
- =id: Print unique element ID.
- =cmdline: Print command line.
- =integrity: Check elements integrity.
- =none: Ignore element line number.
- =tag: Debug information tags.
-
- **Note:** For ELF format, the collected tags represent the debug tags
- that are not processed. For PE/COFF format, they represent the tags
- that are processed.
-
-EXAMPLES
---------
This section includes some real binary files to show how to use
-:program:`llvm-debuginfo-analyzer` to print a logical view and to
+{program}`llvm-debuginfo-analyzer` to print a logical view and to
diagnose possible debug information issues.
-TEST CASE 1 - GENERAL OPTIONS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### TEST CASE 1 - GENERAL OPTIONS
+
The below example is used to show different output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for an X86
+{program}`llvm-debuginfo-analyzer`. We compiled the example for an X86
ELF target with Clang (-O0 -g):
-.. code-block:: c++
-
- 1 using INTPTR = const int *;
- 2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
- 3 if (ParamBool) {
- 4 typedef int INTEGER;
- 5 const INTEGER CONSTANT = 7;
- 6 return CONSTANT;
- 7 }
- 8 return ParamUnsigned;
- 9 }
-
-PRINTING MODE
-^^^^^^^^^^^^^
-In this mode :program:`llvm-debuginfo-analyzer` prints the *logical view*
+```c++
+1 using INTPTR = const int *;
+2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
+3 if (ParamBool) {
+4 typedef int INTEGER;
+5 const INTEGER CONSTANT = 7;
+6 return CONSTANT;
+7 }
+8 return ParamUnsigned;
+9 }
+```
+
+#### PRINTING MODE
+
+In this mode {program}`llvm-debuginfo-analyzer` prints the *logical view*
or portions of it, based on criteria patterns (including regular
expressions) to select the kind of *logical elements* to be included in
the output.
-BASIC DETAILS
-"""""""""""""
+##### BASIC DETAILS
+
The following command prints basic details for all the logical elements
sorted by the debug information internal offset; it includes its lexical
level and debug info format.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=scopes,symbols,types,lines,instructions
- test-dwarf-clang.o
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=scopes,symbols,types,lines,instructions
+ test-dwarf-clang.o
+```
or
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=elements
- test-dwarf-clang.o
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=elements
+ test-dwarf-clang.o
+```
Each row represents an element that is present within the debug
information. The first column represents the scope level, followed by
the associated line number (if any), and finally the description of
the element.
-.. code-block:: none
-
- Logical View:
- [000] {File} 'test-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'test.cpp'
- [002] 2 {Function} extern not_inlined 'foo' -> 'int'
- [003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
- [003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
- [003] 2 {Parameter} 'ParamBool' -> 'bool'
- [003] {Block}
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
- [004] 5 {Line}
- [004] {Code} 'movl $0x7, -0x1c(%rbp)'
- [004] 6 {Line}
- [004] {Code} 'movl $0x7, -0x4(%rbp)'
- [004] {Code} 'jmp 0x6'
- [004] 8 {Line}
- [004] {Code} 'movl -0x14(%rbp), %eax'
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
- [003] 2 {Line}
- [003] {Code} 'pushq %rbp'
- [003] {Code} 'movq %rsp, %rbp'
- [003] {Code} 'movb %dl, %al'
- [003] {Code} 'movq %rdi, -0x10(%rbp)'
- [003] {Code} 'movl %esi, -0x14(%rbp)'
- [003] {Code} 'andb $0x1, %al'
- [003] {Code} 'movb %al, -0x15(%rbp)'
- [003] 3 {Line}
- [003] {Code} 'testb $0x1, -0x15(%rbp)'
- [003] {Code} 'je 0x13'
- [003] 8 {Line}
- [003] {Code} 'movl %eax, -0x4(%rbp)'
- [003] 9 {Line}
- [003] {Code} 'movl -0x4(%rbp), %eax'
- [003] {Code} 'popq %rbp'
- [003] {Code} 'retq'
- [003] 9 {Line}
- [002] 1 {TypeAlias} 'INTPTR' -> '* const int'
+```none
+Logical View:
+[000] {File} 'test-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'test.cpp'
+[002] 2 {Function} extern not_inlined 'foo' -> 'int'
+[003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
+[003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
+[003] 2 {Parameter} 'ParamBool' -> 'bool'
+[003] {Block}
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+[004] 5 {Line}
+[004] {Code} 'movl $0x7, -0x1c(%rbp)'
+[004] 6 {Line}
+[004] {Code} 'movl $0x7, -0x4(%rbp)'
+[004] {Code} 'jmp 0x6'
+[004] 8 {Line}
+[004] {Code} 'movl -0x14(%rbp), %eax'
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+[003] 2 {Line}
+[003] {Code} 'pushq %rbp'
+[003] {Code} 'movq %rsp, %rbp'
+[003] {Code} 'movb %dl, %al'
+[003] {Code} 'movq %rdi, -0x10(%rbp)'
+[003] {Code} 'movl %esi, -0x14(%rbp)'
+[003] {Code} 'andb $0x1, %al'
+[003] {Code} 'movb %al, -0x15(%rbp)'
+[003] 3 {Line}
+[003] {Code} 'testb $0x1, -0x15(%rbp)'
+[003] {Code} 'je 0x13'
+[003] 8 {Line}
+[003] {Code} 'movl %eax, -0x4(%rbp)'
+[003] 9 {Line}
+[003] {Code} 'movl -0x4(%rbp), %eax'
+[003] {Code} 'popq %rbp'
+[003] {Code} 'retq'
+[003] 9 {Line}
+[002] 1 {TypeAlias} 'INTPTR' -> '* const int'
+```
On closer inspection, we can see what could be a potential debug issue:
-.. code-block:: none
-
- [003] {Block}
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
+```none
+[003] {Block}
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+```
The **'INTEGER'** definition is at level **[003]**, the same lexical
-scope as the anonymous **{Block}** ('true' branch for the 'if' statement)
+scope as the anonymous **\{Block}** ('true' branch for the 'if' statement)
whereas in the original source code the typedef statement is clearly
inside that block, so the **'INTEGER'** definition should also be at
level **[004]** inside the block.
-SELECT LOGICAL ELEMENTS
-"""""""""""""""""""""""
+##### SELECT LOGICAL ELEMENTS
+
The following prints all *instructions*, *symbols* and *types* that
contain **'inte'** or **'movl'** in their names or types, using a tab
layout and given the number of matches.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level
- --select-nocase --select-regex
- --select=INTe --select=movl
- --report=list
- --print=symbols,types,instructions,summary
- test-dwarf-clang.o
-
- Logical View:
- [000] {File} 'test-dwarf-clang.o'
-
- [001] {CompileUnit} 'test.cpp'
- [003] {Code} 'movl $0x7, -0x1c(%rbp)'
- [003] {Code} 'movl $0x7, -0x4(%rbp)'
- [003] {Code} 'movl %eax, -0x4(%rbp)'
- [003] {Code} 'movl %esi, -0x14(%rbp)'
- [003] {Code} 'movl -0x14(%rbp), %eax'
- [003] {Code} 'movl -0x4(%rbp), %eax'
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
-
- -----------------------------
- Element Total Found
- -----------------------------
- Scopes 3 0
- Symbols 4 1
- Types 2 1
- Lines 17 6
- -----------------------------
- Total 26 8
-
-COMPARISON MODE
-^^^^^^^^^^^^^^^
-In this mode :program:`llvm-debuginfo-analyzer` compares logical views
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --select-nocase --select-regex
+ --select=INTe --select=movl
+ --report=list
+ --print=symbols,types,instructions,summary
+ test-dwarf-clang.o
+
+Logical View:
+[000] {File} 'test-dwarf-clang.o'
+
+[001] {CompileUnit} 'test.cpp'
+[003] {Code} 'movl $0x7, -0x1c(%rbp)'
+[003] {Code} 'movl $0x7, -0x4(%rbp)'
+[003] {Code} 'movl %eax, -0x4(%rbp)'
+[003] {Code} 'movl %esi, -0x14(%rbp)'
+[003] {Code} 'movl -0x14(%rbp), %eax'
+[003] {Code} 'movl -0x4(%rbp), %eax'
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+
+-----------------------------
+Element Total Found
+-----------------------------
+Scopes 3 0
+Symbols 4 1
+Types 2 1
+Lines 17 6
+-----------------------------
+Total 26 8
+```
+
+#### COMPARISON MODE
+
+In this mode {program}`llvm-debuginfo-analyzer` compares logical views
to produce a report with the logical elements that are missing or added.
This a very powerful aid in finding semantic differences in the debug
information produced by different toolchain versions or even completely
@@ -871,27 +872,27 @@ INTEGER'**) by comparing against another compiler.
Using GCC to generate test-dwarf-gcc.o, we can apply a selection pattern
with the printing mode to obtain the following logical view output.
-.. code-block:: none
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --select-regex --select-nocase --select=INTe
+ --report=list
+ --print=symbols,types
+ test-dwarf-clang.o test-dwarf-gcc.o
- llvm-debuginfo-analyzer --attribute=level
- --select-regex --select-nocase --select=INTe
- --report=list
- --print=symbols,types
- test-dwarf-clang.o test-dwarf-gcc.o
+Logical View:
+[000] {File} 'test-dwarf-clang.o'
- Logical View:
- [000] {File} 'test-dwarf-clang.o'
+[001] {CompileUnit} 'test.cpp'
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
- [001] {CompileUnit} 'test.cpp'
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+Logical View:
+[000] {File} 'test-dwarf-gcc.o'
- Logical View:
- [000] {File} 'test-dwarf-gcc.o'
-
- [001] {CompileUnit} 'test.cpp'
- [004] 4 {TypeAlias} 'INTEGER' -> 'int'
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+[001] {CompileUnit} 'test.cpp'
+[004] 4 {TypeAlias} 'INTEGER' -> 'int'
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+```
The output shows that both objects contain the same elements. But the
**'typedef INTEGER'** is located at different scope level. The GCC
@@ -904,580 +905,568 @@ generated by MSVC and Clang.
There are 2 comparison methods: logical view and logical elements.
-LOGICAL VIEW
-""""""""""""
+##### LOGICAL VIEW
+
It compares the logical view as a whole unit; for a match, each compared
logical element must have the same parents and children.
-Using the :program:`llvm-debuginfo-analyzer` comparison functionality,
+Using the {program}`llvm-debuginfo-analyzer` comparison functionality,
that issue can be seen in a more global context, that can include the
logical view.
The output shows in view form the **missing (-), added (+)** elements,
giving more context by swapping the reference and target object files.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level
- --compare=types
- --report=view
- --print=symbols,types
- test-dwarf-clang.o test-dwarf-gcc.o
-
- Reference: 'test-dwarf-clang.o'
- Target: 'test-dwarf-gcc.o'
-
- Logical View:
- [000] {File} 'test-dwarf-clang.o'
-
- [001] {CompileUnit} 'test.cpp'
- [002] 1 {TypeAlias} 'INTPTR' -> '* const int'
- [002] 2 {Function} extern not_inlined 'foo' -> 'int'
- [003] {Block}
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
- +[004] 4 {TypeAlias} 'INTEGER' -> 'int'
- [003] 2 {Parameter} 'ParamBool' -> 'bool'
- [003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
- [003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
- -[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --compare=types
+ --report=view
+ --print=symbols,types
+ test-dwarf-clang.o test-dwarf-gcc.o
+
+Reference: 'test-dwarf-clang.o'
+Target: 'test-dwarf-gcc.o'
+
+Logical View:
+ [000] {File} 'test-dwarf-clang.o'
+
+ [001] {CompileUnit} 'test.cpp'
+ [002] 1 {TypeAlias} 'INTPTR' -> '* const int'
+ [002] 2 {Function} extern not_inlined 'foo' -> 'int'
+ [003] {Block}
+ [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
++[004] 4 {TypeAlias} 'INTEGER' -> 'int'
+ [003] 2 {Parameter} 'ParamBool' -> 'bool'
+ [003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
+ [003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
+-[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+```
The output shows the merging view path (reference and target) with the
missing and added elements.
-LOGICAL ELEMENTS
-""""""""""""""""
+##### LOGICAL ELEMENTS
+
It compares individual logical elements without considering if their
parents are the same. For both comparison methods, the equal criteria
includes the name, source code location, type, lexical scope level.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level
- --compare=types
- --report=list
- --print=symbols,types,summary
- test-dwarf-clang.o test-dwarf-gcc.o
-
- Reference: 'test-dwarf-clang.o'
- Target: 'test-dwarf-gcc.o'
-
- (1) Missing Types:
- -[003] 4 {TypeAlias} 'INTEGER' -> 'int'
-
- (1) Added Types:
- +[004] 4 {TypeAlias} 'INTEGER' -> 'int'
-
- ----------------------------------------
- Element Expected Missing Added
- ----------------------------------------
- Scopes 4 0 0
- Symbols 0 0 0
- Types 2 1 1
- Lines 0 0 0
- ----------------------------------------
- Total 6 1 1
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --compare=types
+ --report=list
+ --print=symbols,types,summary
+ test-dwarf-clang.o test-dwarf-gcc.o
+
+Reference: 'test-dwarf-clang.o'
+Target: 'test-dwarf-gcc.o'
+
+(1) Missing Types:
+-[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+
+(1) Added Types:
++[004] 4 {TypeAlias} 'INTEGER' -> 'int'
+
+----------------------------------------
+Element Expected Missing Added
+----------------------------------------
+Scopes 4 0 0
+Symbols 0 0 0
+Types 2 1 1
+Lines 0 0 0
+----------------------------------------
+Total 6 1 1
+```
Changing the *Reference* and *Target* order:
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level
- --compare=types
- --report=list
- --print=symbols,types,summary
- test-dwarf-gcc.o test-dwarf-clang.o
-
- Reference: 'test-dwarf-gcc.o'
- Target: 'test-dwarf-clang.o'
-
- (1) Missing Types:
- -[004] 4 {TypeAlias} 'INTEGER' -> 'int'
-
- (1) Added Types:
- +[003] 4 {TypeAlias} 'INTEGER' -> 'int'
-
- ----------------------------------------
- Element Expected Missing Added
- ----------------------------------------
- Scopes 4 0 0
- Symbols 0 0 0
- Types 2 1 1
- Lines 0 0 0
- ----------------------------------------
- Total 6 1 1
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --compare=types
+ --report=list
+ --print=symbols,types,summary
+ test-dwarf-gcc.o test-dwarf-clang.o
+
+Reference: 'test-dwarf-gcc.o'
+Target: 'test-dwarf-clang.o'
+
+(1) Missing Types:
+-[004] 4 {TypeAlias} 'INTEGER' -> 'int'
+
+(1) Added Types:
++[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+
+----------------------------------------
+Element Expected Missing Added
+----------------------------------------
+Scopes 4 0 0
+Symbols 0 0 0
+Types 2 1 1
+Lines 0 0 0
+----------------------------------------
+Total 6 1 1
+```
As the *Reference* and *Target* are switched, the *Added Types* from
the first case now are listed as *Missing Types*.
-TEST CASE 2 - ASSEMBLER INSTRUCTIONS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### TEST CASE 2 - ASSEMBLER INSTRUCTIONS
+
The below example is used to show different output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for an X86
+{program}`llvm-debuginfo-analyzer`. We compiled the example for an X86
Codeview and ELF targets with recent versions of Clang, GCC and MSVC
(-O0 -g) for Windows and Linux.
-.. code-block:: c++
-
- 1 extern int printf(const char * format, ... );
- 2
- 3 int main()
- 4 {
- 5 printf("Hello, World\n");
- 6 return 0;
- 7 }
-
-These are the logical views that :program:`llvm-debuginfo-analyzer`
+```c++
+1 extern int printf(const char * format, ... );
+2
+3 int main()
+4 {
+5 printf("Hello, World\n");
+6 return 0;
+7 }
+```
+
+These are the logical views that {program}`llvm-debuginfo-analyzer`
generates for 3 different compilers (MSVC, Clang and GCC), emitting
different debug information formats (CodeView, DWARF) on Windows and
Linux.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format,producer
- --print=lines,instructions
- hello-world-codeview-clang.o
- hello-world-codeview-msvc.o
- hello-world-dwarf-clang.o
- hello-world-dwarf-gcc.o
-
-CodeView - Clang (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'hello-world-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'hello-world.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] {Function} extern not_inlined 'main' -> 'int'
- [003] 4 {Line}
- [003] {Code} 'subq $0x28, %rsp'
- [003] {Code} 'movl $0x0, 0x24(%rsp)'
- [003] 5 {Line}
- [003] {Code} 'leaq (%rip), %rcx'
- [003] {Code} 'callq 0x0'
- [003] 6 {Line}
- [003] {Code} 'xorl %eax, %eax'
- [003] {Code} 'addq $0x28, %rsp'
- [003] {Code} 'retq'
-
-CodeView - MSVC (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'hello-world-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'hello-world.cpp'
- [002] {Producer} 'Microsoft (R) Optimizing Compiler'
- [002] {Function} extern not_inlined 'main' -> 'int'
- [003] 4 {Line}
- [003] {Code} 'pushl %ebp'
- [003] {Code} 'movl %esp, %ebp'
- [003] 5 {Line}
- [003] {Code} 'pushl $0x0'
- [003] {Code} 'calll 0x0'
- [003] {Code} 'addl $0x4, %esp'
- [003] 6 {Line}
- [003] {Code} 'xorl %eax, %eax'
- [003] 7 {Line}
- [003] {Code} 'popl %ebp'
- [003] {Code} 'retl'
-
-DWARF - Clang (Linux)
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'hello-world-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'hello-world.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] 3 {Function} extern not_inlined 'main' -> 'int'
- [003] 4 {Line}
- [003] {Code} 'pushq %rbp'
- [003] {Code} 'movq %rsp, %rbp'
- [003] {Code} 'subq $0x10, %rsp'
- [003] {Code} 'movl $0x0, -0x4(%rbp)'
- [003] 5 {Line}
- [003] {Code} 'movabsq $0x0, %rdi'
- [003] {Code} 'movb $0x0, %al'
- [003] {Code} 'callq 0x0'
- [003] 6 {Line}
- [003] {Code} 'xorl %eax, %eax'
- [003] {Code} 'addq $0x10, %rsp'
- [003] {Code} 'popq %rbp'
- [003] {Code} 'retq'
- [003] 6 {Line}
-
-DWARF - GCC (Linux)
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'hello-world-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'hello-world.cpp'
- [002] {Producer} 'GNU C++14 9.3.0'
- [002] 3 {Function} extern not_inlined 'main' -> 'int'
- [003] 4 {Line}
- [003] {Code} 'endbr64'
- [003] {Code} 'pushq %rbp'
- [003] {Code} 'movq %rsp, %rbp'
- [003] 5 {Line}
- [003] {Code} 'leaq (%rip), %rdi'
- [003] {Code} 'movl $0x0, %eax'
- [003] {Code} 'callq 0x0'
- [003] 6 {Line}
- [003] {Code} 'movl $0x0, %eax'
- [003] 7 {Line}
- [003] {Code} 'popq %rbp'
- [003] {Code} 'retq'
- [003] 7 {Line}
+```none
+llvm-debuginfo-analyzer --attribute=level,format,producer
+ --print=lines,instructions
+ hello-world-codeview-clang.o
+ hello-world-codeview-msvc.o
+ hello-world-dwarf-clang.o
+ hello-world-dwarf-gcc.o
+```
+
+#### CodeView - Clang (Windows)
+
+```none
+Logical View:
+[000] {File} 'hello-world-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'hello-world.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] {Function} extern not_inlined 'main' -> 'int'
+[003] 4 {Line}
+[003] {Code} 'subq $0x28, %rsp'
+[003] {Code} 'movl $0x0, 0x24(%rsp)'
+[003] 5 {Line}
+[003] {Code} 'leaq (%rip), %rcx'
+[003] {Code} 'callq 0x0'
+[003] 6 {Line}
+[003] {Code} 'xorl %eax, %eax'
+[003] {Code} 'addq $0x28, %rsp'
+[003] {Code} 'retq'
+```
+
+#### CodeView - MSVC (Windows)
+
+```none
+Logical View:
+[000] {File} 'hello-world-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'hello-world.cpp'
+[002] {Producer} 'Microsoft (R) Optimizing Compiler'
+[002] {Function} extern not_inlined 'main' -> 'int'
+[003] 4 {Line}
+[003] {Code} 'pushl %ebp'
+[003] {Code} 'movl %esp, %ebp'
+[003] 5 {Line}
+[003] {Code} 'pushl $0x0'
+[003] {Code} 'calll 0x0'
+[003] {Code} 'addl $0x4, %esp'
+[003] 6 {Line}
+[003] {Code} 'xorl %eax, %eax'
+[003] 7 {Line}
+[003] {Code} 'popl %ebp'
+[003] {Code} 'retl'
+```
+
+#### DWARF - Clang (Linux)
+
+```none
+Logical View:
+[000] {File} 'hello-world-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'hello-world.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] 3 {Function} extern not_inlined 'main' -> 'int'
+[003] 4 {Line}
+[003] {Code} 'pushq %rbp'
+[003] {Code} 'movq %rsp, %rbp'
+[003] {Code} 'subq $0x10, %rsp'
+[003] {Code} 'movl $0x0, -0x4(%rbp)'
+[003] 5 {Line}
+[003] {Code} 'movabsq $0x0, %rdi'
+[003] {Code} 'movb $0x0, %al'
+[003] {Code} 'callq 0x0'
+[003] 6 {Line}
+[003] {Code} 'xorl %eax, %eax'
+[003] {Code} 'addq $0x10, %rsp'
+[003] {Code} 'popq %rbp'
+[003] {Code} 'retq'
+[003] 6 {Line}
+```
+
+#### DWARF - GCC (Linux)
+
+```none
+Logical View:
+[000] {File} 'hello-world-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'hello-world.cpp'
+[002] {Producer} 'GNU C++14 9.3.0'
+[002] 3 {Function} extern not_inlined 'main' -> 'int'
+[003] 4 {Line}
+[003] {Code} 'endbr64'
+[003] {Code} 'pushq %rbp'
+[003] {Code} 'movq %rsp, %rbp'
+[003] 5 {Line}
+[003] {Code} 'leaq (%rip), %rdi'
+[003] {Code} 'movl $0x0, %eax'
+[003] {Code} 'callq 0x0'
+[003] 6 {Line}
+[003] {Code} 'movl $0x0, %eax'
+[003] 7 {Line}
+[003] {Code} 'popq %rbp'
+[003] {Code} 'retq'
+[003] 7 {Line}
+```
The logical views shows the intermixed lines and assembler instructions,
allowing to compare the code generated by the different toolchains.
-TEST CASE 3 - INCORRECT LEXICAL SCOPE FOR TYPEDEF
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### TEST CASE 3 - INCORRECT LEXICAL SCOPE FOR TYPEDEF
+
The below example is used to show different output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for an X86
+{program}`llvm-debuginfo-analyzer`. We compiled the example for an X86
Codeview and ELF targets with recent versions of Clang, GCC and MSVC
(-O0 -g).
-.. code-block:: c++
-
- 1 int bar(float Input) { return (int)Input; }
- 2
- 3 unsigned foo(char Param) {
- 4 typedef int INT; // ** Definition for INT **
- 5 INT Value = Param;
- 6 {
- 7 typedef float FLOAT; // ** Definition for FLOAT **
- 8 {
- 9 FLOAT Added = Value + Param;
- 10 Value = bar(Added);
- 11 }
- 12 }
- 13 return Value + Param;
- 14 }
+```c++
+ 1 int bar(float Input) { return (int)Input; }
+ 2
+ 3 unsigned foo(char Param) {
+ 4 typedef int INT; // ** Definition for INT **
+ 5 INT Value = Param;
+ 6 {
+ 7 typedef float FLOAT; // ** Definition for FLOAT **
+ 8 {
+ 9 FLOAT Added = Value + Param;
+10 Value = bar(Added);
+11 }
+12 }
+13 return Value + Param;
+14 }
+```
The above test is used to illustrate a scope issue found in the Clang
compiler:
-`PR44884 (Bugs LLVM) <https://bugs.llvm.org/show_bug.cgi?id=44884>`_ /
-`PR44229 (GitHub LLVM) <https://github.com/llvm/llvm-project/issues/44229>`_
+[PR44884 (Bugs LLVM)](https://bugs.llvm.org/show_bug.cgi?id=44884) /
+[PR44229 (GitHub LLVM)](https://github.com/llvm/llvm-project/issues/44229)
The lines 4 and 7 contains 2 typedefs, defined at different lexical
scopes.
-.. code-block:: c++
-
- 4 typedef int INT;
- 7 typedef float FLOAT;
+```c++
+4 typedef int INT;
+7 typedef float FLOAT;
+```
-These are the logical views that :program:`llvm-debuginfo-analyzer`
+These are the logical views that {program}`llvm-debuginfo-analyzer`
generates for 3 different compilers (MSVC, Clang and GCC), emitting
different debug information formats (CodeView, DWARF) on different
platforms.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format,producer
- --print=symbols,types,lines
- --output-sort=kind
- pr-44884-codeview-clang.o
- pr-44884-codeview-msvc.o
- pr-44884-dwarf-clang.o
- pr-44884-dwarf-gcc.o
-
-CodeView - Clang (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-44884-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-44884.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] {Function} extern not_inlined 'bar' -> 'int'
- [003] {Parameter} 'Input' -> 'float'
- [003] 1 {Line}
- [002] {Function} extern not_inlined 'foo' -> 'unsigned'
- [003] {Block}
- [004] {Variable} 'Added' -> 'float'
- [004] 9 {Line}
- [004] 10 {Line}
- [003] {Parameter} 'Param' -> 'char'
- [003] {TypeAlias} 'FLOAT' -> 'float'
- [003] {TypeAlias} 'INT' -> 'int'
- [003] {Variable} 'Value' -> 'int'
- [003] 3 {Line}
- [003] 5 {Line}
- [003] 13 {Line}
-
-CodeView - MSVC (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-44884-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-44884.cpp'
- [002] {Producer} 'Microsoft (R) Optimizing Compiler'
- [002] {Function} extern not_inlined 'bar' -> 'int'
- [003] {Variable} 'Input' -> 'float'
- [003] 1 {Line}
- [002] {Function} extern not_inlined 'foo' -> 'unsigned'
- [003] {Block}
- [004] {Block}
- [005] {Variable} 'Added' -> 'float'
- [004] {TypeAlias} 'FLOAT' -> 'float'
- [004] 9 {Line}
- [004] 10 {Line}
- [003] {TypeAlias} 'INT' -> 'int'
- [003] {Variable} 'Param' -> 'char'
- [003] {Variable} 'Value' -> 'int'
- [003] 3 {Line}
- [003] 5 {Line}
- [003] 13 {Line}
- [003] 14 {Line}
-
-DWARF - Clang (Linux)
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-44884-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-44884.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] 1 {Function} extern not_inlined 'bar' -> 'int'
- [003] 1 {Parameter} 'Input' -> 'float'
- [003] 1 {Line}
- [003] 1 {Line}
- [003] 1 {Line}
- [002] 3 {Function} extern not_inlined 'foo' -> 'unsigned int'
- [003] {Block}
- [004] 9 {Variable} 'Added' -> 'FLOAT'
- [004] 9 {Line}
- [004] 9 {Line}
- [004] 9 {Line}
- [004] 9 {Line}
- [004] 9 {Line}
- [004] 10 {Line}
- [004] 10 {Line}
- [004] 10 {Line}
- [004] 13 {Line}
- [003] 3 {Parameter} 'Param' -> 'char'
- [003] 7 {TypeAlias} 'FLOAT' -> 'float'
- [003] 4 {TypeAlias} 'INT' -> 'int'
- [003] 5 {Variable} 'Value' -> 'INT'
- [003] 3 {Line}
- [003] 5 {Line}
- [003] 5 {Line}
- [003] 13 {Line}
- [003] 13 {Line}
- [003] 13 {Line}
- [003] 13 {Line}
-
-DWARF - GCC (Linux)
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-44884-dwarf-gcc.o' -> elf32-littlearm
-
- [001] {CompileUnit} 'pr-44884.cpp'
- [002] {Producer} 'GNU C++14 10.2.1 20201103'
- [002] 1 {Function} extern not_inlined 'bar' -> 'int'
- [003] 1 {Parameter} 'Input' -> 'float'
- [003] 1 {Line}
- [003] 1 {Line}
- [003] 1 {Line}
- [002] 3 {Function} extern not_inlined 'foo' -> 'unsigned int'
- [003] {Block}
- [004] {Block}
- [005] 9 {Variable} 'Added' -> 'FLOAT'
- [005] 9 {Line}
- [005] 9 {Line}
- [005] 9 {Line}
- [005] 10 {Line}
- [005] 13 {Line}
- [004] 7 {TypeAlias} 'FLOAT' -> 'float'
- [003] 3 {Parameter} 'Param' -> 'char'
- [003] 4 {TypeAlias} 'INT' -> 'int'
- [003] 5 {Variable} 'Value' -> 'INT'
- [003] 3 {Line}
- [003] 5 {Line}
- [003] 13 {Line}
- [003] 14 {Line}
- [003] 14 {Line}
+```none
+llvm-debuginfo-analyzer --attribute=level,format,producer
+ --print=symbols,types,lines
+ --output-sort=kind
+ pr-44884-codeview-clang.o
+ pr-44884-codeview-msvc.o
+ pr-44884-dwarf-clang.o
+ pr-44884-dwarf-gcc.o
+```
+
+#### CodeView - Clang (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-44884-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-44884.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] {Function} extern not_inlined 'bar' -> 'int'
+[003] {Parameter} 'Input' -> 'float'
+[003] 1 {Line}
+[002] {Function} extern not_inlined 'foo' -> 'unsigned'
+[003] {Block}
+[004] {Variable} 'Added' -> 'float'
+[004] 9 {Line}
+[004] 10 {Line}
+[003] {Parameter} 'Param' -> 'char'
+[003] {TypeAlias} 'FLOAT' -> 'float'
+[003] {TypeAlias} 'INT' -> 'int'
+[003] {Variable} 'Value' -> 'int'
+[003] 3 {Line}
+[003] 5 {Line}
+[003] 13 {Line}
+```
+
+#### CodeView - MSVC (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-44884-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-44884.cpp'
+[002] {Producer} 'Microsoft (R) Optimizing Compiler'
+[002] {Function} extern not_inlined 'bar' -> 'int'
+[003] {Variable} 'Input' -> 'float'
+[003] 1 {Line}
+[002] {Function} extern not_inlined 'foo' -> 'unsigned'
+[003] {Block}
+[004] {Block}
+[005] {Variable} 'Added' -> 'float'
+[004] {TypeAlias} 'FLOAT' -> 'float'
+[004] 9 {Line}
+[004] 10 {Line}
+[003] {TypeAlias} 'INT' -> 'int'
+[003] {Variable} 'Param' -> 'char'
+[003] {Variable} 'Value' -> 'int'
+[003] 3 {Line}
+[003] 5 {Line}
+[003] 13 {Line}
+[003] 14 {Line}
+```
+
+#### DWARF - Clang (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-44884-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-44884.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] 1 {Function} extern not_inlined 'bar' -> 'int'
+[003] 1 {Parameter} 'Input' -> 'float'
+[003] 1 {Line}
+[003] 1 {Line}
+[003] 1 {Line}
+[002] 3 {Function} extern not_inlined 'foo' -> 'unsigned int'
+[003] {Block}
+[004] 9 {Variable} 'Added' -> 'FLOAT'
+[004] 9 {Line}
+[004] 9 {Line}
+[004] 9 {Line}
+[004] 9 {Line}
+[004] 9 {Line}
+[004] 10 {Line}
+[004] 10 {Line}
+[004] 10 {Line}
+[004] 13 {Line}
+[003] 3 {Parameter} 'Param' -> 'char'
+[003] 7 {TypeAlias} 'FLOAT' -> 'float'
+[003] 4 {TypeAlias} 'INT' -> 'int'
+[003] 5 {Variable} 'Value' -> 'INT'
+[003] 3 {Line}
+[003] 5 {Line}
+[003] 5 {Line}
+[003] 13 {Line}
+[003] 13 {Line}
+[003] 13 {Line}
+[003] 13 {Line}
+```
+
+#### DWARF - GCC (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-44884-dwarf-gcc.o' -> elf32-littlearm
+
+[001] {CompileUnit} 'pr-44884.cpp'
+[002] {Producer} 'GNU C++14 10.2.1 20201103'
+[002] 1 {Function} extern not_inlined 'bar' -> 'int'
+[003] 1 {Parameter} 'Input' -> 'float'
+[003] 1 {Line}
+[003] 1 {Line}
+[003] 1 {Line}
+[002] 3 {Function} extern not_inlined 'foo' -> 'unsigned int'
+[003] {Block}
+[004] {Block}
+[005] 9 {Variable} 'Added' -> 'FLOAT'
+[005] 9 {Line}
+[005] 9 {Line}
+[005] 9 {Line}
+[005] 10 {Line}
+[005] 13 {Line}
+[004] 7 {TypeAlias} 'FLOAT' -> 'float'
+[003] 3 {Parameter} 'Param' -> 'char'
+[003] 4 {TypeAlias} 'INT' -> 'int'
+[003] 5 {Variable} 'Value' -> 'INT'
+[003] 3 {Line}
+[003] 5 {Line}
+[003] 13 {Line}
+[003] 14 {Line}
+[003] 14 {Line}
+```
From the previous logical views, we can see that the Clang compiler
emits **both typedefs at the same lexical scope (3)**, which is wrong.
GCC and MSVC emit correct lexical scope for both typedefs.
-Using the :program:`llvm-debuginfo-analyzer` selection facilities, we
+Using the {program}`llvm-debuginfo-analyzer` selection facilities, we
can produce a simple tabular output showing just the logical types that
are **Typedef**.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=name
- --select-types=Typedef
- --report=list
- --print=types
- pr-44884-*.o
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=name
+ --select-types=Typedef
+ --report=list
+ --print=types
+ pr-44884-*.o
- Logical View:
- [000] {File} 'pr-44884-codeview-clang.o' -> COFF-x86-64
+Logical View:
+[000] {File} 'pr-44884-codeview-clang.o' -> COFF-x86-64
- [001] {CompileUnit} 'pr_44884.cpp'
- [003] {TypeAlias} 'FLOAT' -> 'float'
- [003] {TypeAlias} 'INT' -> 'int'
+[001] {CompileUnit} 'pr_44884.cpp'
+[003] {TypeAlias} 'FLOAT' -> 'float'
+[003] {TypeAlias} 'INT' -> 'int'
- Logical View:
- [000] {File} 'pr-44884-codeview-msvc.o' -> COFF-i386
+Logical View:
+[000] {File} 'pr-44884-codeview-msvc.o' -> COFF-i386
- [001] {CompileUnit} 'pr_44884.cpp'
- [004] {TypeAlias} 'FLOAT' -> 'float'
- [003] {TypeAlias} 'INT' -> 'int'
+[001] {CompileUnit} 'pr_44884.cpp'
+[004] {TypeAlias} 'FLOAT' -> 'float'
+[003] {TypeAlias} 'INT' -> 'int'
- Logical View:
- [000] {File} 'pr-44884-dwarf-clang.o' -> elf64-x86-64
+Logical View:
+[000] {File} 'pr-44884-dwarf-clang.o' -> elf64-x86-64
- [001] {CompileUnit} 'pr_44884.cpp'
- [003] 7 {TypeAlias} 'FLOAT' -> 'float'
- [003] 4 {TypeAlias} 'INT' -> 'int'
+[001] {CompileUnit} 'pr_44884.cpp'
+[003] 7 {TypeAlias} 'FLOAT' -> 'float'
+[003] 4 {TypeAlias} 'INT' -> 'int'
- Logical View:
- [000] {File} 'pr-44884-dwarf-gcc.o' -> elf32-littlearm
+Logical View:
+[000] {File} 'pr-44884-dwarf-gcc.o' -> elf32-littlearm
- [001] {CompileUnit} 'pr_44884.cpp'
- [004] 7 {TypeAlias} 'FLOAT' -> 'float'
- [003] 4 {TypeAlias} 'INT' -> 'int'
+[001] {CompileUnit} 'pr_44884.cpp'
+[004] 7 {TypeAlias} 'FLOAT' -> 'float'
+[003] 4 {TypeAlias} 'INT' -> 'int'
+```
It also shows, that the CodeView debug information does not generate
source code line numbers for the those logical types. The logical view
is sorted by the types name.
-TEST CASE 4 - MISSING NESTED ENUMERATIONS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### TEST CASE 4 - MISSING NESTED ENUMERATIONS
+
The below example is used to show different output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for an X86
+{program}`llvm-debuginfo-analyzer`. We compiled the example for an X86
Codeview and ELF targets with recent versions of Clang, GCC and MSVC
(-O0 -g).
-.. code-block:: c++
-
- 1 struct Struct {
- 2 union Union {
- 3 enum NestedEnum { RED, BLUE };
- 4 };
- 5 Union U;
- 6 };
- 7
- 8 Struct S;
- 9 int test() {
- 10 return S.U.BLUE;
- 11 }
+```c++
+ 1 struct Struct {
+ 2 union Union {
+ 3 enum NestedEnum { RED, BLUE };
+ 4 };
+ 5 Union U;
+ 6 };
+ 7
+ 8 Struct S;
+ 9 int test() {
+10 return S.U.BLUE;
+11 }
+```
The above test is used to illustrate a scope issue found in the Clang
compiler:
-`PR46466 (Bugs LLVM) <https://bugs.llvm.org/show_bug.cgi?id=46466>`_ /
-`PR45811 (GitHub LLVM) <https://github.com/llvm/llvm-project/issues/45811>`_
+[PR46466 (Bugs LLVM)](https://bugs.llvm.org/show_bug.cgi?id=46466) /
+[PR45811 (GitHub LLVM)](https://github.com/llvm/llvm-project/issues/45811)
-These are the logical views that :program:`llvm-debuginfo-analyzer`
+These are the logical views that {program}`llvm-debuginfo-analyzer`
generates for 3 different compilers (MSVC, Clang and GCC), emitting
different debug information formats (CodeView, DWARF) on different
platforms.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format,producer
- --output-sort=name
- --print=symbols,types
- pr-46466-codeview-clang.o
- pr-46466-codeview-msvc.o
- pr-46466-dwarf-clang.o
- pr-46466-dwarf-gcc.o
-
-CodeView - Clang (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] {Variable} extern 'S' -> 'Struct'
- [002] 1 {Struct} 'Struct'
- [003] {Member} public 'U' -> 'Union'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
-CodeView - MSVC (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] {Producer} 'Microsoft (R) Optimizing Compiler'
- [002] {Variable} extern 'S' -> 'Struct'
- [002] 1 {Struct} 'Struct'
- [003] {Member} public 'U' -> 'Union'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
-DWARF - Clang (Linux)
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] 8 {Variable} extern 'S' -> 'Struct'
- [002] 1 {Struct} 'Struct'
- [003] 5 {Member} public 'U' -> 'Union'
-
-DWARF - GCC (Linux)
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] {Producer} 'GNU C++14 9.3.0'
- [002] 8 {Variable} extern 'S' -> 'Struct'
- [002] 1 {Struct} 'Struct'
- [003] 5 {Member} public 'U' -> 'Union'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'unsigned int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
+```none
+llvm-debuginfo-analyzer --attribute=level,format,producer
+ --output-sort=name
+ --print=symbols,types
+ pr-46466-codeview-clang.o
+ pr-46466-codeview-msvc.o
+ pr-46466-dwarf-clang.o
+ pr-46466-dwarf-gcc.o
+```
+
+#### CodeView - Clang (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] {Variable} extern 'S' -> 'Struct'
+[002] 1 {Struct} 'Struct'
+[003] {Member} public 'U' -> 'Union'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+```
+
+#### CodeView - MSVC (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] {Producer} 'Microsoft (R) Optimizing Compiler'
+[002] {Variable} extern 'S' -> 'Struct'
+[002] 1 {Struct} 'Struct'
+[003] {Member} public 'U' -> 'Union'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+```
+
+#### DWARF - Clang (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] 8 {Variable} extern 'S' -> 'Struct'
+[002] 1 {Struct} 'Struct'
+[003] 5 {Member} public 'U' -> 'Union'
+```
+
+#### DWARF - GCC (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] {Producer} 'GNU C++14 9.3.0'
+[002] 8 {Variable} extern 'S' -> 'Struct'
+[002] 1 {Struct} 'Struct'
+[003] 5 {Member} public 'U' -> 'Union'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'unsigned int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+```
From the previous logical views, we can see that the DWARF debug
information generated by the Clang compiler does not include any
@@ -1485,301 +1474,297 @@ references to the enumerators **RED** and **BLUE**. The DWARF
generated by GCC, CodeView generated by Clang and MSVC, they do
include such references.
-Using the :program:`llvm-debuginfo-analyzer` selection facilities, we
+Using the {program}`llvm-debuginfo-analyzer` selection facilities, we
can produce a logical view showing just the logical types that are
**Enumerator** and its parents. The logical view is sorted by the types
name.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=format,level
- --output-sort=name
- --select-types=Enumerator
- --report=parents
- --print=types
- pr-46466-*.o
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] 1 {Struct} 'Struct'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
- Logical View:
- [000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] 1 {Struct} 'Struct'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [002] 1 {Struct} 'Struct'
- [003] 2 {Union} 'Union'
- [004] 3 {Enumeration} 'NestedEnum' -> 'unsigned int'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
-Using the :program:`llvm-debuginfo-analyzer` selection facilities, we
+```none
+llvm-debuginfo-analyzer --attribute=format,level
+ --output-sort=name
+ --select-types=Enumerator
+ --report=parents
+ --print=types
+ pr-46466-*.o
+```
+
+```none
+Logical View:
+[000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] 1 {Struct} 'Struct'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+
+Logical View:
+[000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] 1 {Struct} 'Struct'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+
+Logical View:
+[000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+
+Logical View:
+[000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[002] 1 {Struct} 'Struct'
+[003] 2 {Union} 'Union'
+[004] 3 {Enumeration} 'NestedEnum' -> 'unsigned int'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+```
+
+Using the {program}`llvm-debuginfo-analyzer` selection facilities, we
can produce a simple tabular output including a summary for the logical
types that are **Enumerator**. The logical view is sorted by the types
name.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=format,level
- --output-sort=name
- --select-types=Enumerator
- --print=types,summary
- pr-46466-*.o
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
- -----------------------------
- Element Total Found
- -----------------------------
- Scopes 5 0
- Symbols 2 0
- Types 6 2
- Lines 0 0
- -----------------------------
- Total 13 2
-
- Logical View:
- [000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
- -----------------------------
- Element Total Found
- -----------------------------
- Scopes 5 0
- Symbols 2 0
- Types 7 2
- Lines 0 0
- -----------------------------
- Total 14 2
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
-
- -----------------------------
- Element Total Found
- -----------------------------
- Scopes 4 0
- Symbols 0 0
- Types 0 0
- Lines 0 0
- -----------------------------
- Total 4 0
-
- Logical View:
- [000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-46466.cpp'
- [005] {Enumerator} 'BLUE' = '0x1'
- [005] {Enumerator} 'RED' = '0x0'
-
- -----------------------------
- Element Total Found
- -----------------------------
- Scopes 5 0
- Symbols 0 0
- Types 2 2
- Lines 0 0
- -----------------------------
- Total 7 2
+```none
+llvm-debuginfo-analyzer --attribute=format,level
+ --output-sort=name
+ --select-types=Enumerator
+ --print=types,summary
+ pr-46466-*.o
+```
+
+```none
+Logical View:
+[000] {File} 'pr-46466-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+
+-----------------------------
+Element Total Found
+-----------------------------
+Scopes 5 0
+Symbols 2 0
+Types 6 2
+Lines 0 0
+-----------------------------
+Total 13 2
+
+Logical View:
+[000] {File} 'pr-46466-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+
+-----------------------------
+Element Total Found
+-----------------------------
+Scopes 5 0
+Symbols 2 0
+Types 7 2
+Lines 0 0
+-----------------------------
+Total 14 2
+
+Logical View:
+[000] {File} 'pr-46466-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+
+-----------------------------
+Element Total Found
+-----------------------------
+Scopes 4 0
+Symbols 0 0
+Types 0 0
+Lines 0 0
+-----------------------------
+Total 4 0
+
+Logical View:
+[000] {File} 'pr-46466-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-46466.cpp'
+[005] {Enumerator} 'BLUE' = '0x1'
+[005] {Enumerator} 'RED' = '0x0'
+
+-----------------------------
+Element Total Found
+-----------------------------
+Scopes 5 0
+Symbols 0 0
+Types 2 2
+Lines 0 0
+-----------------------------
+Total 7 2
+```
From the values printed under the **Found** column, we can see that no
**Types** were found in the DWARF debug information generated by Clang.
-TEST CASE 5 - INCORRECT LEXICAL SCOPE FOR VARIABLE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### TEST CASE 5 - INCORRECT LEXICAL SCOPE FOR VARIABLE
+
The below example is used to show different output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for an X86
+{program}`llvm-debuginfo-analyzer`. We compiled the example for an X86
Codeview and ELF targets with recent versions of Clang, GCC and MSVC
(-O0 -g).
-.. code-block:: c++
-
- // definitions.h
- #ifdef _MSC_VER
- #define forceinline __forceinline
- #elif defined(__clang__)
- #if __has_attribute(__always_inline__)
- #define forceinline inline __attribute__((__always_inline__))
- #else
- #define forceinline inline
- #endif
- #elif defined(__GNUC__)
+```c++
+// definitions.h
+#ifdef _MSC_VER
+ #define forceinline __forceinline
+#elif defined(__clang__)
+ #if __has_attribute(__always_inline__)
#define forceinline inline __attribute__((__always_inline__))
#else
#define forceinline inline
- #error
#endif
+#elif defined(__GNUC__)
+ #define forceinline inline __attribute__((__always_inline__))
+#else
+ #define forceinline inline
+ #error
+#endif
+```
As the test is dependent on inline compiler options, the above header
file defines *forceinline*.
-.. code-block:: c++
-
- #include "definitions.h"
-
-.. code-block:: c++
-
- 1 #include "definitions.h"
- 2 forceinline int InlineFunction(int Param) {
- 3 int Var_1 = Param;
- 4 {
- 5 int Var_2 = Param + Var_1;
- 6 Var_1 = Var_2;
- 7 }
- 8 return Var_1;
- 9 }
- 10
- 11 int test(int Param_1, int Param_2) {
- 12 int A = Param_1;
- 13 A += InlineFunction(Param_2);
- 14 return A;
- 15 }
+```c++
+#include "definitions.h"
+```
+
+```c++
+ 1 #include "definitions.h"
+ 2 forceinline int InlineFunction(int Param) {
+ 3 int Var_1 = Param;
+ 4 {
+ 5 int Var_2 = Param + Var_1;
+ 6 Var_1 = Var_2;
+ 7 }
+ 8 return Var_1;
+ 9 }
+10
+11 int test(int Param_1, int Param_2) {
+12 int A = Param_1;
+13 A += InlineFunction(Param_2);
+14 return A;
+15 }
+```
The above test is used to illustrate a variable issue found in the Clang
compiler:
-`PR43860 (Bugs LLVM) <https://bugs.llvm.org/show_bug.cgi?id=43860>`_ /
-`PR43205 (GitHub) <https://github.com/llvm/llvm-project/issues/43205>`_
+[PR43860 (Bugs LLVM)](https://bugs.llvm.org/show_bug.cgi?id=43860) /
+[PR43205 (GitHub)](https://github.com/llvm/llvm-project/issues/43205)
-These are the logical views that :program:`llvm-debuginfo-analyzer`
+These are the logical views that {program}`llvm-debuginfo-analyzer`
generates for 3 different compilers (MSVC, Clang and GCC), emitting
different debug information formats (CodeView, DWARF) on different
platforms.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format,producer
- --output-sort=name
- --print=symbols
- pr-43860-codeview-clang.o
- pr-43860-codeview-msvc.o
- pr-43860-dwarf-clang.o
- pr-43860-dwarf-gcc.o
-
-CODEVIEW - Clang (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-43860-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] 2 {Function} inlined 'InlineFunction' -> 'int'
- [003] {Parameter} '' -> 'int'
- [002] {Function} extern not_inlined 'test' -> 'int'
- [003] {Variable} 'A' -> 'int'
- [003] {InlinedFunction} inlined 'InlineFunction' -> 'int'
- [004] {Parameter} 'Param' -> 'int'
- [004] {Variable} 'Var_1' -> 'int'
- [004] {Variable} 'Var_2' -> 'int'
- [003] {Parameter} 'Param_1' -> 'int'
- [003] {Parameter} 'Param_2' -> 'int'
-
-CODEVIEW - MSVC (Windows)
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-43860-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [002] {Producer} 'Microsoft (R) Optimizing Compiler'
- [002] {Function} extern not_inlined 'InlineFunction' -> 'int'
- [003] {Block}
- [004] {Variable} 'Var_2' -> 'int'
- [003] {Variable} 'Param' -> 'int'
- [003] {Variable} 'Var_1' -> 'int'
- [002] {Function} extern not_inlined 'test' -> 'int'
- [003] {Variable} 'A' -> 'int'
- [003] {Variable} 'Param_1' -> 'int'
- [003] {Variable} 'Param_2' -> 'int'
-
-DWARF - Clang (Linux)
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-43860-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [002] {Producer} 'clang version 14.0.0'
- [002] 2 {Function} extern inlined 'InlineFunction' -> 'int'
- [003] {Block}
- [004] 5 {Variable} 'Var_2' -> 'int'
- [003] 2 {Parameter} 'Param' -> 'int'
- [003] 3 {Variable} 'Var_1' -> 'int'
- [002] 11 {Function} extern not_inlined 'test' -> 'int'
- [003] 12 {Variable} 'A' -> 'int'
- [003] 13 {InlinedFunction} inlined 'InlineFunction' -> 'int'
- [004] {Block}
- [005] {Variable} 'Var_2' -> 'int'
- [004] {Parameter} 'Param' -> 'int'
- [004] {Variable} 'Var_1' -> 'int'
- [003] 11 {Parameter} 'Param_1' -> 'int'
- [003] 11 {Parameter} 'Param_2' -> 'int'
-
-DWARF - GCC (Linux)
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-43860-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [002] {Producer} 'GNU C++14 9.3.0'
- [002] 2 {Function} extern declared_inlined 'InlineFunction' -> 'int'
- [003] {Block}
- [004] 5 {Variable} 'Var_2' -> 'int'
- [003] 2 {Parameter} 'Param' -> 'int'
- [003] 3 {Variable} 'Var_1' -> 'int'
- [002] 11 {Function} extern not_inlined 'test' -> 'int'
- [003] 12 {Variable} 'A' -> 'int'
- [003] 13 {InlinedFunction} declared_inlined 'InlineFunction' -> 'int'
- [004] {Block}
- [005] {Variable} 'Var_2' -> 'int'
- [004] {Parameter} 'Param' -> 'int'
- [004] {Variable} 'Var_1' -> 'int'
- [003] 11 {Parameter} 'Param_1' -> 'int'
- [003] 11 {Parameter} 'Param_2' -> 'int'
+```none
+llvm-debuginfo-analyzer --attribute=level,format,producer
+ --output-sort=name
+ --print=symbols
+ pr-43860-codeview-clang.o
+ pr-43860-codeview-msvc.o
+ pr-43860-dwarf-clang.o
+ pr-43860-dwarf-gcc.o
+```
+
+#### CODEVIEW - Clang (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-43860-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] 2 {Function} inlined 'InlineFunction' -> 'int'
+[003] {Parameter} '' -> 'int'
+[002] {Function} extern not_inlined 'test' -> 'int'
+[003] {Variable} 'A' -> 'int'
+[003] {InlinedFunction} inlined 'InlineFunction' -> 'int'
+[004] {Parameter} 'Param' -> 'int'
+[004] {Variable} 'Var_1' -> 'int'
+[004] {Variable} 'Var_2' -> 'int'
+[003] {Parameter} 'Param_1' -> 'int'
+[003] {Parameter} 'Param_2' -> 'int'
+```
+
+#### CODEVIEW - MSVC (Windows)
+
+```none
+Logical View:
+[000] {File} 'pr-43860-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[002] {Producer} 'Microsoft (R) Optimizing Compiler'
+[002] {Function} extern not_inlined 'InlineFunction' -> 'int'
+[003] {Block}
+[004] {Variable} 'Var_2' -> 'int'
+[003] {Variable} 'Param' -> 'int'
+[003] {Variable} 'Var_1' -> 'int'
+[002] {Function} extern not_inlined 'test' -> 'int'
+[003] {Variable} 'A' -> 'int'
+[003] {Variable} 'Param_1' -> 'int'
+[003] {Variable} 'Param_2' -> 'int'
+```
+
+#### DWARF - Clang (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-43860-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[002] {Producer} 'clang version 14.0.0'
+[002] 2 {Function} extern inlined 'InlineFunction' -> 'int'
+[003] {Block}
+[004] 5 {Variable} 'Var_2' -> 'int'
+[003] 2 {Parameter} 'Param' -> 'int'
+[003] 3 {Variable} 'Var_1' -> 'int'
+[002] 11 {Function} extern not_inlined 'test' -> 'int'
+[003] 12 {Variable} 'A' -> 'int'
+[003] 13 {InlinedFunction} inlined 'InlineFunction' -> 'int'
+[004] {Block}
+[005] {Variable} 'Var_2' -> 'int'
+[004] {Parameter} 'Param' -> 'int'
+[004] {Variable} 'Var_1' -> 'int'
+[003] 11 {Parameter} 'Param_1' -> 'int'
+[003] 11 {Parameter} 'Param_2' -> 'int'
+```
+
+#### DWARF - GCC (Linux)
+
+```none
+Logical View:
+[000] {File} 'pr-43860-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[002] {Producer} 'GNU C++14 9.3.0'
+[002] 2 {Function} extern declared_inlined 'InlineFunction' -> 'int'
+[003] {Block}
+[004] 5 {Variable} 'Var_2' -> 'int'
+[003] 2 {Parameter} 'Param' -> 'int'
+[003] 3 {Variable} 'Var_1' -> 'int'
+[002] 11 {Function} extern not_inlined 'test' -> 'int'
+[003] 12 {Variable} 'A' -> 'int'
+[003] 13 {InlinedFunction} declared_inlined 'InlineFunction' -> 'int'
+[004] {Block}
+[005] {Variable} 'Var_2' -> 'int'
+[004] {Parameter} 'Param' -> 'int'
+[004] {Variable} 'Var_1' -> 'int'
+[003] 11 {Parameter} 'Param_1' -> 'int'
+[003] 11 {Parameter} 'Param_2' -> 'int'
+```
From the previous logical views, we can see that the CodeView debug
information generated by the Clang compiler shows the variables **Var_1**
@@ -1788,447 +1773,447 @@ and **Var_2** are at the same lexical scope (**4**) in the function
generated by MSVC, show those variables at the correct lexical scope:
**3** and **4** respectively.
-Using the :program:`llvm-debuginfo-analyzer` selection facilities, we
+Using the {program}`llvm-debuginfo-analyzer` selection facilities, we
can produce a simple tabular output showing just the logical elements
that have in their name the *var* pattern. The logical view is sorted
by the variables name.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=name
- --select-regex --select-nocase --select=Var
- --report=list
- --print=symbols
- pr-43860-*.o
-
-.. code-block:: none
-
- Logical View:
- [000] {File} 'pr-43860-codeview-clang.o' -> COFF-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [004] {Variable} 'Var_1' -> 'int'
- [004] {Variable} 'Var_2' -> 'int'
-
- Logical View:
- [000] {File} 'pr-43860-codeview-msvc.o' -> COFF-i386
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [003] {Variable} 'Var_1' -> 'int'
- [004] {Variable} 'Var_2' -> 'int'
-
- Logical View:
- [000] {File} 'pr-43860-dwarf-clang.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [004] {Variable} 'Var_1' -> 'int'
- [003] 3 {Variable} 'Var_1' -> 'int'
- [005] {Variable} 'Var_2' -> 'int'
- [004] 5 {Variable} 'Var_2' -> 'int'
-
- Logical View:
- [000] {File} 'pr-43860-dwarf-gcc.o' -> elf64-x86-64
-
- [001] {CompileUnit} 'pr-43860.cpp'
- [004] {Variable} 'Var_1' -> 'int'
- [003] 3 {Variable} 'Var_1' -> 'int'
- [005] {Variable} 'Var_2' -> 'int'
- [004] 5 {Variable} 'Var_2' -> 'int'
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=name
+ --select-regex --select-nocase --select=Var
+ --report=list
+ --print=symbols
+ pr-43860-*.o
+```
+
+```none
+Logical View:
+[000] {File} 'pr-43860-codeview-clang.o' -> COFF-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[004] {Variable} 'Var_1' -> 'int'
+[004] {Variable} 'Var_2' -> 'int'
+
+Logical View:
+[000] {File} 'pr-43860-codeview-msvc.o' -> COFF-i386
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[003] {Variable} 'Var_1' -> 'int'
+[004] {Variable} 'Var_2' -> 'int'
+
+Logical View:
+[000] {File} 'pr-43860-dwarf-clang.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[004] {Variable} 'Var_1' -> 'int'
+[003] 3 {Variable} 'Var_1' -> 'int'
+[005] {Variable} 'Var_2' -> 'int'
+[004] 5 {Variable} 'Var_2' -> 'int'
+
+Logical View:
+[000] {File} 'pr-43860-dwarf-gcc.o' -> elf64-x86-64
+
+[001] {CompileUnit} 'pr-43860.cpp'
+[004] {Variable} 'Var_1' -> 'int'
+[003] 3 {Variable} 'Var_1' -> 'int'
+[005] {Variable} 'Var_2' -> 'int'
+[004] 5 {Variable} 'Var_2' -> 'int'
+```
It also shows, that the CodeView debug information does not generate
source code line numbers for the those logical symbols. The logical
view is sorted by the types name.
-TEST CASE 6 - FULL LOGICAL VIEW
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For advanced users, :program:`llvm-debuginfo-analyzer` can display low
+### TEST CASE 6 - FULL LOGICAL VIEW
+
+For advanced users, {program}`llvm-debuginfo-analyzer` can display low
level information that includes offsets within the debug information
section, debug location operands, linkage names, etc.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=all
- --print=all
- test-dwarf-clang.o
-
- Logical View:
- [0x0000000000][000] {File} 'test-dwarf-clang.o' -> elf64-x86-64
-
- [0x000000000b][001] {CompileUnit} 'test.cpp'
- [0x000000000b][002] {Producer} 'clang version 12.0.0'
- {Directory} ''
- {File} 'test.cpp'
- {Public} 'foo' [0x0000000000:0x000000003a]
- [0x000000000b][002] {Range} Lines 2:9 [0x0000000000:0x000000003a]
- [0x00000000bc][002] {BaseType} 'bool'
- [0x0000000099][002] {BaseType} 'int'
- [0x00000000b5][002] {BaseType} 'unsigned int'
-
- [0x00000000a0][002] {Source} '/test.cpp'
- [0x00000000a0][002] 1 {TypeAlias} 'INTPTR' -> [0x00000000ab]'* const int'
- [0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
- [0x000000002a][003] {Range} Lines 2:9 [0x0000000000:0x000000003a]
- [0x000000002a][003] {Linkage} 0x2 '_Z3fooPKijb'
- [0x0000000071][003] {Block}
- [0x0000000071][004] {Range} Lines 5:8 [0x000000001c:0x000000002f]
- [0x000000007e][004] 5 {Variable} 'CONSTANT' -> [0x00000000c3]'const INTEGER'
- [0x000000007e][005] {Coverage} 100.00%
- [0x000000007f][005] {Location}
- [0x000000007f][006] {Entry} Stack Offset: -28 (0xffffffffffffffe4) [DW_OP_fbreg]
- [0x000000001c][004] 5 {Line} {NewStatement} '/test.cpp'
- [0x000000001c][004] {Code} 'movl $0x7, -0x1c(%rbp)'
- [0x0000000023][004] 6 {Line} {NewStatement} '/test.cpp'
- [0x0000000023][004] {Code} 'movl $0x7, -0x4(%rbp)'
- [0x000000002a][004] {Code} 'jmp 0x6'
- [0x000000002f][004] 8 {Line} {NewStatement} '/test.cpp'
- [0x000000002f][004] {Code} 'movl -0x14(%rbp), %eax'
- [0x0000000063][003] 2 {Parameter} 'ParamBool' -> [0x00000000bc]'bool'
- [0x0000000063][004] {Coverage} 100.00%
- [0x0000000064][004] {Location}
- [0x0000000064][005] {Entry} Stack Offset: -21 (0xffffffffffffffeb) [DW_OP_fbreg]
- [0x0000000047][003] 2 {Parameter} 'ParamPtr' -> [0x00000000a0]'INTPTR'
- [0x0000000047][004] {Coverage} 100.00%
- [0x0000000048][004] {Location}
- [0x0000000048][005] {Entry} Stack Offset: -16 (0xfffffffffffffff0) [DW_OP_fbreg]
- [0x0000000055][003] 2 {Parameter} 'ParamUnsigned' -> [0x00000000b5]'unsigned int'
- [0x0000000055][004] {Coverage} 100.00%
- [0x0000000056][004] {Location}
- [0x0000000056][005] {Entry} Stack Offset: -20 (0xffffffffffffffec) [DW_OP_fbreg]
- [0x000000008d][003] 4 {TypeAlias} 'INTEGER' -> [0x0000000099]'int'
- [0x0000000000][003] 2 {Line} {NewStatement} '/test.cpp'
- [0x0000000000][003] {Code} 'pushq %rbp'
- [0x0000000001][003] {Code} 'movq %rsp, %rbp'
- [0x0000000004][003] {Code} 'movb %dl, %al'
- [0x0000000006][003] {Code} 'movq %rdi, -0x10(%rbp)'
- [0x000000000a][003] {Code} 'movl %esi, -0x14(%rbp)'
- [0x000000000d][003] {Code} 'andb $0x1, %al'
- [0x000000000f][003] {Code} 'movb %al, -0x15(%rbp)'
- [0x0000000012][003] 3 {Line} {NewStatement} {PrologueEnd} '/test.cpp'
- [0x0000000012][003] {Code} 'testb $0x1, -0x15(%rbp)'
- [0x0000000016][003] {Code} 'je 0x13'
- [0x0000000032][003] 8 {Line} '/test.cpp'
- [0x0000000032][003] {Code} 'movl %eax, -0x4(%rbp)'
- [0x0000000035][003] 9 {Line} {NewStatement} '/test.cpp'
- [0x0000000035][003] {Code} 'movl -0x4(%rbp), %eax'
- [0x0000000038][003] {Code} 'popq %rbp'
- [0x0000000039][003] {Code} 'retq'
- [0x000000003a][003] 9 {Line} {NewStatement} {EndSequence} '/test.cpp'
-
- -----------------------------
- Element Total Printed
- -----------------------------
- Scopes 3 3
- Symbols 4 4
- Types 5 5
- Lines 25 25
- -----------------------------
- Total 37 37
-
- Scope Sizes:
- 189 (100.00%) : [0x000000000b][001] {CompileUnit} 'test.cpp'
- 110 ( 58.20%) : [0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
- 27 ( 14.29%) : [0x0000000071][003] {Block}
-
- Totals by lexical level:
- [001]: 189 (100.00%)
- [002]: 110 ( 58.20%)
- [003]: 27 ( 14.29%)
+```none
+llvm-debuginfo-analyzer --attribute=all
+ --print=all
+ test-dwarf-clang.o
+
+Logical View:
+[0x0000000000][000] {File} 'test-dwarf-clang.o' -> elf64-x86-64
+
+[0x000000000b][001] {CompileUnit} 'test.cpp'
+[0x000000000b][002] {Producer} 'clang version 12.0.0'
+ {Directory} ''
+ {File} 'test.cpp'
+ {Public} 'foo' [0x0000000000:0x000000003a]
+[0x000000000b][002] {Range} Lines 2:9 [0x0000000000:0x000000003a]
+[0x00000000bc][002] {BaseType} 'bool'
+[0x0000000099][002] {BaseType} 'int'
+[0x00000000b5][002] {BaseType} 'unsigned int'
+
+[0x00000000a0][002] {Source} '/test.cpp'
+[0x00000000a0][002] 1 {TypeAlias} 'INTPTR' -> [0x00000000ab]'* const int'
+[0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
+[0x000000002a][003] {Range} Lines 2:9 [0x0000000000:0x000000003a]
+[0x000000002a][003] {Linkage} 0x2 '_Z3fooPKijb'
+[0x0000000071][003] {Block}
+[0x0000000071][004] {Range} Lines 5:8 [0x000000001c:0x000000002f]
+[0x000000007e][004] 5 {Variable} 'CONSTANT' -> [0x00000000c3]'const INTEGER'
+[0x000000007e][005] {Coverage} 100.00%
+[0x000000007f][005] {Location}
+[0x000000007f][006] {Entry} Stack Offset: -28 (0xffffffffffffffe4) [DW_OP_fbreg]
+[0x000000001c][004] 5 {Line} {NewStatement} '/test.cpp'
+[0x000000001c][004] {Code} 'movl $0x7, -0x1c(%rbp)'
+[0x0000000023][004] 6 {Line} {NewStatement} '/test.cpp'
+[0x0000000023][004] {Code} 'movl $0x7, -0x4(%rbp)'
+[0x000000002a][004] {Code} 'jmp 0x6'
+[0x000000002f][004] 8 {Line} {NewStatement} '/test.cpp'
+[0x000000002f][004] {Code} 'movl -0x14(%rbp), %eax'
+[0x0000000063][003] 2 {Parameter} 'ParamBool' -> [0x00000000bc]'bool'
+[0x0000000063][004] {Coverage} 100.00%
+[0x0000000064][004] {Location}
+[0x0000000064][005] {Entry} Stack Offset: -21 (0xffffffffffffffeb) [DW_OP_fbreg]
+[0x0000000047][003] 2 {Parameter} 'ParamPtr' -> [0x00000000a0]'INTPTR'
+[0x0000000047][004] {Coverage} 100.00%
+[0x0000000048][004] {Location}
+[0x0000000048][005] {Entry} Stack Offset: -16 (0xfffffffffffffff0) [DW_OP_fbreg]
+[0x0000000055][003] 2 {Parameter} 'ParamUnsigned' -> [0x00000000b5]'unsigned int'
+[0x0000000055][004] {Coverage} 100.00%
+[0x0000000056][004] {Location}
+[0x0000000056][005] {Entry} Stack Offset: -20 (0xffffffffffffffec) [DW_OP_fbreg]
+[0x000000008d][003] 4 {TypeAlias} 'INTEGER' -> [0x0000000099]'int'
+[0x0000000000][003] 2 {Line} {NewStatement} '/test.cpp'
+[0x0000000000][003] {Code} 'pushq %rbp'
+[0x0000000001][003] {Code} 'movq %rsp, %rbp'
+[0x0000000004][003] {Code} 'movb %dl, %al'
+[0x0000000006][003] {Code} 'movq %rdi, -0x10(%rbp)'
+[0x000000000a][003] {Code} 'movl %esi, -0x14(%rbp)'
+[0x000000000d][003] {Code} 'andb $0x1, %al'
+[0x000000000f][003] {Code} 'movb %al, -0x15(%rbp)'
+[0x0000000012][003] 3 {Line} {NewStatement} {PrologueEnd} '/test.cpp'
+[0x0000000012][003] {Code} 'testb $0x1, -0x15(%rbp)'
+[0x0000000016][003] {Code} 'je 0x13'
+[0x0000000032][003] 8 {Line} '/test.cpp'
+[0x0000000032][003] {Code} 'movl %eax, -0x4(%rbp)'
+[0x0000000035][003] 9 {Line} {NewStatement} '/test.cpp'
+[0x0000000035][003] {Code} 'movl -0x4(%rbp), %eax'
+[0x0000000038][003] {Code} 'popq %rbp'
+[0x0000000039][003] {Code} 'retq'
+[0x000000003a][003] 9 {Line} {NewStatement} {EndSequence} '/test.cpp'
+
+-----------------------------
+Element Total Printed
+-----------------------------
+Scopes 3 3
+Symbols 4 4
+Types 5 5
+Lines 25 25
+-----------------------------
+Total 37 37
+
+Scope Sizes:
+ 189 (100.00%) : [0x000000000b][001] {CompileUnit} 'test.cpp'
+ 110 ( 58.20%) : [0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
+ 27 ( 14.29%) : [0x0000000071][003] {Block}
+
+Totals by lexical level:
+[001]: 189 (100.00%)
+[002]: 110 ( 58.20%)
+[003]: 27 ( 14.29%)
+```
The **Scope Sizes** table shows the contribution in bytes to the debug
information by each scope, which can be used to determine unexpected
size changes in the DWARF sections between different versions of the
same toolchain.
-.. code-block:: none
-
- [0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
- [0x000000002a][003] {Range} Lines 2:9 [0x0000000000:0x000000003a]
- [0x000000002a][003] {Linkage} 0x2 '_Z3fooPKijb'
- [0x0000000071][003] {Block}
- [0x0000000071][004] {Range} Lines 5:8 [0x000000001c:0x000000002f]
- [0x000000007e][004] 5 {Variable} 'CONSTANT' -> [0x00000000c3]'const INTEGER'
- [0x000000007e][005] {Coverage} 100.00%
- [0x000000007f][005] {Location}
- [0x000000007f][006] {Entry} Stack Offset: -28 (0xffffffffffffffe4) [DW_OP_fbreg]
-
-The **{Range}** attribute describe the line ranges for a logical scope.
+```none
+[0x000000002a][002] 2 {Function} extern not_inlined 'foo' -> [0x0000000099]'int'
+[0x000000002a][003] {Range} Lines 2:9 [0x0000000000:0x000000003a]
+[0x000000002a][003] {Linkage} 0x2 '_Z3fooPKijb'
+[0x0000000071][003] {Block}
+[0x0000000071][004] {Range} Lines 5:8 [0x000000001c:0x000000002f]
+[0x000000007e][004] 5 {Variable} 'CONSTANT' -> [0x00000000c3]'const INTEGER'
+[0x000000007e][005] {Coverage} 100.00%
+[0x000000007f][005] {Location}
+[0x000000007f][006] {Entry} Stack Offset: -28 (0xffffffffffffffe4) [DW_OP_fbreg]
+```
+
+The **\{Range}** attribute describe the line ranges for a logical scope.
For this case, the function **foo** is within the lines **2** and **9**.
-The **{Coverage}** and **{Location}** attributes describe the debug
+The **\{Coverage}** and **\{Location}** attributes describe the debug
location and coverage for logical symbols. For optimized code, the
coverage value decreases and it affects the program debuggability.
-WEBASSEMBLY SUPPORT
-~~~~~~~~~~~~~~~~~~~
+### WEBASSEMBLY SUPPORT
+
The below example is used to show the WebAssembly output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for a
+{program}`llvm-debuginfo-analyzer`. We compiled the example for a
WebAssembly 32-bit target with Clang (-O0 -g --target=wasm32):
-.. code-block:: c++
+```c++
+1 using INTPTR = const int *;
+2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
+3 if (ParamBool) {
+4 typedef int INTEGER;
+5 const INTEGER CONSTANT = 7;
+6 return CONSTANT;
+7 }
+8 return ParamUnsigned;
+9 }
+```
- 1 using INTPTR = const int *;
- 2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
- 3 if (ParamBool) {
- 4 typedef int INTEGER;
- 5 const INTEGER CONSTANT = 7;
- 6 return CONSTANT;
- 7 }
- 8 return ParamUnsigned;
- 9 }
+#### PRINT BASIC DETAILS
-PRINT BASIC DETAILS
-^^^^^^^^^^^^^^^^^^^
The following command prints basic details for all the logical elements
sorted by the debug information internal offset; it includes its lexical
level and debug info format.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=scopes,symbols,types,lines,instructions
- test-clang.o
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=scopes,symbols,types,lines,instructions
+ test-clang.o
+```
or
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=elements
- test-clang.o
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=elements
+ test-clang.o
+```
Each row represents an element that is present within the debug
information. The first column represents the scope level, followed by
the associated line number (if any), and finally the description of
the element.
-.. code-block:: none
-
- Logical View:
- [000] {File} 'test-clang.o' -> WASM
-
- [001] {CompileUnit} 'test.cpp'
- [002] 2 {Function} extern not_inlined 'foo' -> 'int'
- [003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
- [003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
- [003] 2 {Parameter} 'ParamBool' -> 'bool'
- [003] {Block}
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
- [004] 5 {Line}
- [004] {Code} 'i32.const 7'
- [004] {Code} 'local.set 10'
- [004] {Code} 'local.get 5'
- [004] {Code} 'local.get 10'
- [004] {Code} 'i32.store 12'
- [004] 6 {Line}
- [004] {Code} 'i32.const 7'
- [004] {Code} 'local.set 11'
- [004] {Code} 'local.get 5'
- [004] {Code} 'local.get 11'
- [004] {Code} 'i32.store 28'
- [004] {Code} 'br 1'
- [004] - {Line}
- [004] {Code} 'end'
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
- [003] 2 {Line}
- [003] {Code} 'nop'
- [003] {Code} 'end'
- [003] {Code} 'i64.div_s'
- [003] {Code} 'global.get 0'
- [003] {Code} 'local.set 3'
- [003] {Code} 'i32.const 32'
- [003] {Code} 'local.set 4'
- [003] {Code} 'local.get 3'
- [003] {Code} 'local.get 4'
- [003] {Code} 'i32.sub'
- [003] {Code} 'local.set 5'
- [003] {Code} 'local.get 5'
- [003] {Code} 'local.get 0'
- [003] {Code} 'i32.store 24'
- [003] {Code} 'local.get 5'
- [003] {Code} 'local.get 1'
- [003] {Code} 'i32.store 20'
- [003] {Code} 'local.get 2'
- [003] {Code} 'local.set 6'
- [003] {Code} 'local.get 5'
- [003] {Code} 'local.get 6'
- [003] {Code} 'i32.store8 19'
- [003] 3 {Line}
- [003] {Code} 'local.get 5'
- [003] {Code} 'i32.load8_u 19'
- [003] {Code} 'local.set 7'
- [003] 3 {Line}
- [003] {Code} 'i32.const 1'
- [003] {Code} 'local.set 8'
- [003] {Code} 'local.get 7'
- [003] {Code} 'local.get 8'
- [003] {Code} 'i32.and'
- [003] {Code} 'local.set 9'
- [003] {Code} 'block'
- [003] {Code} 'block'
- [003] {Code} 'local.get 9'
- [003] {Code} 'i32.eqz'
- [003] {Code} 'br_if 0'
- [003] 8 {Line}
- [003] {Code} 'local.get 5'
- [003] {Code} 'i32.load 20'
- [003] {Code} 'local.set 12'
- [003] 8 {Line}
- [003] {Code} 'local.get 5'
- [003] {Code} 'local.get 12'
- [003] {Code} 'i32.store 28'
- [003] - {Line}
- [003] {Code} 'end'
- [003] 9 {Line}
- [003] {Code} 'local.get 5'
- [003] {Code} 'i32.load 28'
- [003] {Code} 'local.set 13'
- [003] {Code} 'local.get 13'
- [003] {Code} 'return'
- [003] {Code} 'end'
- [003] 9 {Line}
- [003] {Code} 'unreachable'
- [002] 1 {TypeAlias} 'INTPTR' -> '* const int'
-
-SELECT LOGICAL ELEMENTS
-^^^^^^^^^^^^^^^^^^^^^^^
+```none
+Logical View:
+[000] {File} 'test-clang.o' -> WASM
+
+[001] {CompileUnit} 'test.cpp'
+[002] 2 {Function} extern not_inlined 'foo' -> 'int'
+[003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
+[003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
+[003] 2 {Parameter} 'ParamBool' -> 'bool'
+[003] {Block}
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+[004] 5 {Line}
+[004] {Code} 'i32.const 7'
+[004] {Code} 'local.set 10'
+[004] {Code} 'local.get 5'
+[004] {Code} 'local.get 10'
+[004] {Code} 'i32.store 12'
+[004] 6 {Line}
+[004] {Code} 'i32.const 7'
+[004] {Code} 'local.set 11'
+[004] {Code} 'local.get 5'
+[004] {Code} 'local.get 11'
+[004] {Code} 'i32.store 28'
+[004] {Code} 'br 1'
+[004] - {Line}
+[004] {Code} 'end'
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+[003] 2 {Line}
+[003] {Code} 'nop'
+[003] {Code} 'end'
+[003] {Code} 'i64.div_s'
+[003] {Code} 'global.get 0'
+[003] {Code} 'local.set 3'
+[003] {Code} 'i32.const 32'
+[003] {Code} 'local.set 4'
+[003] {Code} 'local.get 3'
+[003] {Code} 'local.get 4'
+[003] {Code} 'i32.sub'
+[003] {Code} 'local.set 5'
+[003] {Code} 'local.get 5'
+[003] {Code} 'local.get 0'
+[003] {Code} 'i32.store 24'
+[003] {Code} 'local.get 5'
+[003] {Code} 'local.get 1'
+[003] {Code} 'i32.store 20'
+[003] {Code} 'local.get 2'
+[003] {Code} 'local.set 6'
+[003] {Code} 'local.get 5'
+[003] {Code} 'local.get 6'
+[003] {Code} 'i32.store8 19'
+[003] 3 {Line}
+[003] {Code} 'local.get 5'
+[003] {Code} 'i32.load8_u 19'
+[003] {Code} 'local.set 7'
+[003] 3 {Line}
+[003] {Code} 'i32.const 1'
+[003] {Code} 'local.set 8'
+[003] {Code} 'local.get 7'
+[003] {Code} 'local.get 8'
+[003] {Code} 'i32.and'
+[003] {Code} 'local.set 9'
+[003] {Code} 'block'
+[003] {Code} 'block'
+[003] {Code} 'local.get 9'
+[003] {Code} 'i32.eqz'
+[003] {Code} 'br_if 0'
+[003] 8 {Line}
+[003] {Code} 'local.get 5'
+[003] {Code} 'i32.load 20'
+[003] {Code} 'local.set 12'
+[003] 8 {Line}
+[003] {Code} 'local.get 5'
+[003] {Code} 'local.get 12'
+[003] {Code} 'i32.store 28'
+[003] - {Line}
+[003] {Code} 'end'
+[003] 9 {Line}
+[003] {Code} 'local.get 5'
+[003] {Code} 'i32.load 28'
+[003] {Code} 'local.set 13'
+[003] {Code} 'local.get 13'
+[003] {Code} 'return'
+[003] {Code} 'end'
+[003] 9 {Line}
+[003] {Code} 'unreachable'
+[002] 1 {TypeAlias} 'INTPTR' -> '* const int'
+```
+
+#### SELECT LOGICAL ELEMENTS
+
The following prints all *instructions*, *symbols* and *types* that
contain **'block'** or **'.store'** in their names or types, using a tab
layout and given the number of matches.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level
- --select-nocase --select-regex
- --select=BLOCK --select=.store
- --report=list
- --print=symbols,types,instructions,summary
- test-clang.o
-
- Logical View:
- [000] {File} 'test-clang.o'
-
- [001] {CompileUnit} 'test.cpp'
- [003] {Code} 'block'
- [003] {Code} 'block'
- [004] {Code} 'i32.store 12'
- [003] {Code} 'i32.store 20'
- [003] {Code} 'i32.store 24'
- [004] {Code} 'i32.store 28'
- [003] {Code} 'i32.store 28'
- [003] {Code} 'i32.store8 19'
-
- -----------------------------
- Element Total Printed
- -----------------------------
- Scopes 3 0
- Symbols 4 0
- Types 2 0
- Lines 62 8
- -----------------------------
- Total 71 8
-
-LLVM IR (textual / bitcode representation) SUPPORT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```none
+llvm-debuginfo-analyzer --attribute=level
+ --select-nocase --select-regex
+ --select=BLOCK --select=.store
+ --report=list
+ --print=symbols,types,instructions,summary
+ test-clang.o
+
+Logical View:
+[000] {File} 'test-clang.o'
+
+[001] {CompileUnit} 'test.cpp'
+[003] {Code} 'block'
+[003] {Code} 'block'
+[004] {Code} 'i32.store 12'
+[003] {Code} 'i32.store 20'
+[003] {Code} 'i32.store 24'
+[004] {Code} 'i32.store 28'
+[003] {Code} 'i32.store 28'
+[003] {Code} 'i32.store8 19'
+
+-----------------------------
+Element Total Printed
+-----------------------------
+Scopes 3 0
+Symbols 4 0
+Types 2 0
+Lines 62 8
+-----------------------------
+Total 71 8
+```
+
+### LLVM IR (textual / bitcode representation) SUPPORT
+
The below example is used to show the IR output generated by
-:program:`llvm-debuginfo-analyzer`. We compiled the example for a
+{program}`llvm-debuginfo-analyzer`. We compiled the example for a
IR 64-bit target with Clang (-O0 -g --target=x86_64-linux):
-.. code-block:: c++
+```c++
+1 using INTPTR = const int *;
+2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
+3 if (ParamBool) {
+4 typedef int INTEGER;
+5 const INTEGER CONSTANT = 7;
+6 return CONSTANT;
+7 }
+8 return ParamUnsigned;
+9 }
+```
- 1 using INTPTR = const int *;
- 2 int foo(INTPTR ParamPtr, unsigned ParamUnsigned, bool ParamBool) {
- 3 if (ParamBool) {
- 4 typedef int INTEGER;
- 5 const INTEGER CONSTANT = 7;
- 6 return CONSTANT;
- 7 }
- 8 return ParamUnsigned;
- 9 }
+#### PRINT BASIC DETAILS
-PRINT BASIC DETAILS
-^^^^^^^^^^^^^^^^^^^
The following command prints basic details for all the logical elements
sorted by the debug information internal offset; it includes its lexical
level and debug info format.
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=scopes,symbols,types,lines,instructions
- test-clang.ll
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=scopes,symbols,types,lines,instructions
+ test-clang.ll
+```
or
-.. code-block:: none
-
- llvm-debuginfo-analyzer --attribute=level,format
- --output-sort=offset
- --print=elements
- test-clang.ll
+```none
+llvm-debuginfo-analyzer --attribute=level,format
+ --output-sort=offset
+ --print=elements
+ test-clang.ll
+```
Each row represents an element that is present within the debug
information. The first column represents the scope level, followed by
the associated line number (if any), and finally the description of
the element.
-.. code-block:: none
-
- Logical View:
- [000] {File} 'test-clang.ll' -> Textual IR
-
- [001] {CompileUnit} 'test.cpp'
- [002] 2 {Function} extern not_inlined 'foo' -> 'int'
- [003] {Block}
- [004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
- [004] 5 {Line}
- [004] {Code} 'store i32 7, ptr %CONSTANT, align 4, !dbg !32'
- [004] 6 {Line}
- [004] {Code} 'store i32 7, ptr %retval, align 4, !dbg !33'
- [004] 6 {Line}
- [004] {Code} 'br label %return, !dbg !33'
- [003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
- [003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
- [003] 2 {Parameter} 'ParamBool' -> 'bool'
- [003] 4 {TypeAlias} 'INTEGER' -> 'int'
- [003] 2 {Line}
- [003] {Code} '%retval = alloca i32, align 4'
- [003] {Code} '%ParamPtr.addr = alloca ptr, align 8'
- [003] {Code} '%ParamUnsigned.addr = alloca i32, align 4'
- [003] {Code} '%ParamBool.addr = alloca i8, align 1'
- [003] {Code} '%CONSTANT = alloca i32, align 4'
- [003] {Code} 'store ptr %ParamPtr, ptr %ParamPtr.addr, align 8'
- [003] {Code} 'store i32 %ParamUnsigned, ptr %ParamUnsigned.addr, align 4'
- [003] {Code} '%storedv = zext i1 %ParamBool to i8'
- [003] {Code} 'store i8 %storedv, ptr %ParamBool.addr, align 1'
- [003] 8 {Line}
- [003] {Code} '%1 = load i32, ptr %ParamUnsigned.addr, align 4, !dbg !34'
- [003] 8 {Line}
- [003] {Code} 'store i32 %1, ptr %retval, align 4, !dbg !35'
- [003] 8 {Line}
- [003] {Code} 'br label %return, !dbg !35'
- [003] 9 {Line}
- [003] {Code} '%2 = load i32, ptr %retval, align 4, !dbg !36'
- [003] 9 {Line}
- [003] {Code} 'ret i32 %2, !dbg !36'
- [003] 3 {Line}
- [003] 3 {Line}
- [003] 3 {Line}
- [003] {Code} 'br i1 %loadedv, label %if.then, label %if.end, !dbg !26'
- [002] 1 {TypeAlias} 'INTPTR' -> '* const int'
-
-EXIT STATUS
------------
-:program:`llvm-debuginfo-analyzer` returns 0 if the input files were
+```none
+Logical View:
+[000] {File} 'test-clang.ll' -> Textual IR
+
+[001] {CompileUnit} 'test.cpp'
+[002] 2 {Function} extern not_inlined 'foo' -> 'int'
+[003] {Block}
+[004] 5 {Variable} 'CONSTANT' -> 'const INTEGER'
+[004] 5 {Line}
+[004] {Code} 'store i32 7, ptr %CONSTANT, align 4, !dbg !32'
+[004] 6 {Line}
+[004] {Code} 'store i32 7, ptr %retval, align 4, !dbg !33'
+[004] 6 {Line}
+[004] {Code} 'br label %return, !dbg !33'
+[003] 2 {Parameter} 'ParamPtr' -> 'INTPTR'
+[003] 2 {Parameter} 'ParamUnsigned' -> 'unsigned int'
+[003] 2 {Parameter} 'ParamBool' -> 'bool'
+[003] 4 {TypeAlias} 'INTEGER' -> 'int'
+[003] 2 {Line}
+[003] {Code} '%retval = alloca i32, align 4'
+[003] {Code} '%ParamPtr.addr = alloca ptr, align 8'
+[003] {Code} '%ParamUnsigned.addr = alloca i32, align 4'
+[003] {Code} '%ParamBool.addr = alloca i8, align 1'
+[003] {Code} '%CONSTANT = alloca i32, align 4'
+[003] {Code} 'store ptr %ParamPtr, ptr %ParamPtr.addr, align 8'
+[003] {Code} 'store i32 %ParamUnsigned, ptr %ParamUnsigned.addr, align 4'
+[003] {Code} '%storedv = zext i1 %ParamBool to i8'
+[003] {Code} 'store i8 %storedv, ptr %ParamBool.addr, align 1'
+[003] 8 {Line}
+[003] {Code} '%1 = load i32, ptr %ParamUnsigned.addr, align 4, !dbg !34'
+[003] 8 {Line}
+[003] {Code} 'store i32 %1, ptr %retval, align 4, !dbg !35'
+[003] 8 {Line}
+[003] {Code} 'br label %return, !dbg !35'
+[003] 9 {Line}
+[003] {Code} '%2 = load i32, ptr %retval, align 4, !dbg !36'
+[003] 9 {Line}
+[003] {Code} 'ret i32 %2, !dbg !36'
+[003] 3 {Line}
+[003] 3 {Line}
+[003] 3 {Line}
+[003] {Code} 'br i1 %loadedv, label %if.then, label %if.end, !dbg !26'
+[002] 1 {TypeAlias} 'INTPTR' -> '* const int'
+```
+
+## EXIT STATUS
+
+{program}`llvm-debuginfo-analyzer` returns 0 if the input files were
parsed and printed successfully. Otherwise, it returns 1.
-LIMITATIONS AND KNOWN ISSUES
-----------------------------
-See :download:`Limitations <../../tools/llvm-debuginfo-analyzer/README.md>`.
+## LIMITATIONS AND KNOWN ISSUES
+
+See {download}`Limitations <../../tools/llvm-debuginfo-analyzer/README.md>`.
+
+## SEE ALSO
-SEE ALSO
---------
-:manpage:`llvm-dwarfdump`
+{manpage}`llvm-dwarfdump`
diff --git a/llvm/docs/CommandGuide/llvm-diff.md b/llvm/docs/CommandGuide/llvm-diff.md
index 65ed1be0d5663..fc219c6b47241 100644
--- a/llvm/docs/CommandGuide/llvm-diff.md
+++ b/llvm/docs/CommandGuide/llvm-diff.md
@@ -1,23 +1,22 @@
-llvm-diff - LLVM structural 'diff'
-==================================
+# llvm-diff - LLVM structural 'diff'
+```{eval-rst}
.. program:: llvm-diff
+```
-SYNOPSIS
---------
+## SYNOPSIS
-**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
+**llvm-diff** \[*options*\] *module 1* *module 2* \[*global name ...*\]
-DESCRIPTION
------------
+## DESCRIPTION
**llvm-diff** compares the structure of two LLVM modules, primarily
-focusing on differences in function definitions. Insignificant
+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.
+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
@@ -25,26 +24,25 @@ 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,
+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,
+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.
+passes and frontends. It does not have a stable output format.
-EXIT STATUS
------------
+## 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
+with 0 and produce no output. Otherwise it will exit with a non-zero
value.
-BUGS
-----
+## 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/llvm/docs/CommandGuide/llvm-dis.md b/llvm/docs/CommandGuide/llvm-dis.md
index 69200c6a3bd80..88856f5e1cf14 100644
--- a/llvm/docs/CommandGuide/llvm-dis.md
+++ b/llvm/docs/CommandGuide/llvm-dis.md
@@ -1,54 +1,51 @@
-llvm-dis - LLVM disassembler
-============================
+# llvm-dis - LLVM disassembler
+```{eval-rst}
.. program:: llvm-dis
+```
-SYNOPSIS
---------
+## SYNOPSIS
-**llvm-dis** [*options*] [*filename*]
+**llvm-dis** \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The **llvm-dis** command is the LLVM disassembler. It takes an LLVM
+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
+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
+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
+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
--------
+## 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.
+> 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.
+> 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.
+> Specify the output file name. If *filename* is -, then the output is sent
+> to standard output.
-EXIT STATUS
------------
+## EXIT STATUS
-If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error
+If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-as(1)`
-:manpage:`llvm-as(1)`
diff --git a/llvm/docs/CommandGuide/llvm-dwarfdump.md b/llvm/docs/CommandGuide/llvm-dwarfdump.md
index 22f2edfc30f57..60f332e997f0d 100644
--- a/llvm/docs/CommandGuide/llvm-dwarfdump.md
+++ b/llvm/docs/CommandGuide/llvm-dwarfdump.md
@@ -1,230 +1,227 @@
-llvm-dwarfdump - dump and verify DWARF debug information
-========================================================
+# llvm-dwarfdump - dump and verify DWARF debug information
+```{eval-rst}
.. program:: llvm-dwarfdump
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-dwarfdump` [*options*] [*filename ...*]
+{program}`llvm-dwarfdump` \[*options*\] \[*filename ...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-dwarfdump` parses DWARF sections in object files,
+{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.
+the section-specific options or {option}`--all` is specified.
If no input file is specified, `a.out` is used instead. If `-` is used as the
-input file, :program:`llvm-dwarfdump` reads the input from its standard input
+input file, {program}`llvm-dwarfdump` reads the input from its standard input
stream.
-OPTIONS
--------
-
-.. option:: -a, --all
-
- Dump 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 selectively printing with
- the `=<offset>` argument of :option:`--debug-info`, or options such
- as :option:`--find` or :option:`--name`.
-
-.. option:: --color
-
- Use colors in output.
-
-.. option:: --error-display=<value>
-
- Set the level of detail and summary to display when verifying.
- Implies :option:`--verify`. The supported values are:
-
- `quiet` - Only display whether errors occurred.
- `summary` - Display only a summary of the errors found.
- `details` - Display each error in detail but no summary.
- `full` - Display each error as well as a summary. [default]
-
-.. 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:: --help-list
-
- Show help and usage for this command without grouping the options
- into categories.
-
-.. option:: -i, --ignore-case
-
- Ignore case distinctions when using :option:`--name`.
-
-.. option:: -n <name>, --name=<name>
-
- Find and print all debug info entries whose name
- (`DW_AT_name`/`DW_AT_linkage_name` attribute) is <name>.
-
-.. option:: --lookup=<address>
-
- Look up <address> in the debug information and print out the file,
- function, block, and line table details.
-
-.. option:: -o <path>
-
- Redirect output to a file specified by <path>, where `-` is the
- standard output stream.
-
-.. option:: -p, --show-parents
-
- Show a debug info entry's parents when selectively printing with
- the `=<offset>` argument of :option:`--debug-info`, or options such
- as :option:`--find` or :option:`--name`.
-
-.. option:: --parent-recurse-depth=<N>
-
- When displaying debug info entry parents, only show them to a
- maximum depth of <N>.
-
-.. option:: --quiet
-
- Use with :option:`--verify` to not emit to `STDOUT`.
-
-.. option:: -r <N>, --recurse-depth=<N>
-
- When displaying debug info entries, only show children to a maximum
- depth of <N>.
-
-.. option:: --show-section-sizes
-
- Show the sizes of all debug sections, expressed in bytes.
-
-.. option:: --show-sources
-
- Print all source files mentioned in the debug information. Absolute
- paths are given whenever possible.
-
-.. option:: --statistics
-
- Collect debug info quality metrics and print the results
- as machine-readable single-line JSON output. The output
- format is described in the section below (:ref:`stats-format`).
-
-.. option:: --summarize-types
-
- Abbreviate the description of type unit entries.
-
-.. option:: -t, --filter-child-tag
-
- Only dump children whose DWARF tag is one of the specified tags.
- Example usage:
-
- .. code-block:: c
-
- llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c
-
-.. option:: -x, --regex
-
- Treat any <name> strings as regular expressions when searching
- with :option:`--name`. If :option:`--ignore-case` is also specified,
- the regular expression becomes case-insensitive.
-
-.. 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:: --verify-json=<path>
-
- Output JSON-formatted error summary to the file specified by
- <path>. Implies :option:`--verify`. The output format is described
- in the section below (:ref:`verify-json-format`).
-
-.. option:: --version
-
- Display the version of the tool.
-
-.. option:: --debug-abbrev, --debug-addr, --debug-aranges, --debug-cu-index, --debug-frame [=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-line-str, --debug-loc [=<offset>], --debug-loclists [=<offset>], --debug-macro, --debug-names, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-rnglists, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types [=<offset>], --eh-frame [=<offset>], --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.
-
- The :option:`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections.
-
- The :option:`--debug-frame` and :option:`--eh-frame` options are aliases, in cases where both sections are present one command outputs both.
-
-.. option:: --show-variable-coverage
-
- Show per-variable coverage metrics. The output format is described
- in the section below (:ref:`variable-coverage-format`).
-
-.. option:: --coverage-baseline
-
- File to use as the baseline for variable coverage statistics
- (implies :option:`--show-variable-coverage`)
-
-.. option:: --variable-coverage-bitcode-file
-
- File containing LLVM IR (bitcode or textual) used for calculating
- variable definedness in coverage statistics (implies
- :option:`--show-variable-coverage`)
-
-.. option:: --combine-inline-variable-instances
-
- Use with :option:`--show-variable-coverage` to average variable
- coverage across inlined subroutine instances instead of printing
- them separately.
-
-.. option:: @<FILE>
-
- Read command-line options from `<FILE>`.
-
-.. _stats-format:
-
-FORMAT OF STATISTICS OUTPUT
----------------------------
-
-The :option:`--statistics` option generates single-line JSON output
+## OPTIONS
+
+:::{option} -a, --all
+Dump 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 selectively printing with
+the `=<offset>` argument of {option}`--debug-info`, or options such
+as {option}`--find` or {option}`--name`.
+:::
+
+:::{option} --color
+Use colors in output.
+:::
+
+:::{option} --error-display=<value>
+Set the level of detail and summary to display when verifying.
+Implies {option}`--verify`. The supported values are:
+
+`quiet` - Only display whether errors occurred.
+`summary` - Display only a summary of the errors found.
+`details` - Display each error in detail but no summary.
+`full` - Display each error as well as a summary. [default]
+:::
+
+:::{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} --help-list
+Show help and usage for this command without grouping the options
+into categories.
+:::
+
+:::{option} -i, --ignore-case
+Ignore case distinctions when using {option}`--name`.
+:::
+
+:::{option} -n <name>, --name=<name>
+Find and print all debug info entries whose name
+(`DW_AT_name`/`DW_AT_linkage_name` attribute) is \<name>.
+:::
+
+:::{option} --lookup=<address>
+Look up \<address> in the debug information and print out the file,
+function, block, and line table details.
+:::
+
+:::{option} -o <path>
+Redirect output to a file specified by \<path>, where `-` is the
+standard output stream.
+:::
+
+:::{option} -p, --show-parents
+Show a debug info entry's parents when selectively printing with
+the `=<offset>` argument of {option}`--debug-info`, or options such
+as {option}`--find` or {option}`--name`.
+:::
+
+:::{option} --parent-recurse-depth=<N>
+When displaying debug info entry parents, only show them to a
+maximum depth of \<N>.
+:::
+
+:::{option} --quiet
+Use with {option}`--verify` to not emit to `STDOUT`.
+:::
+
+:::{option} -r <N>, --recurse-depth=<N>
+When displaying debug info entries, only show children to a maximum
+depth of \<N>.
+:::
+
+:::{option} --show-section-sizes
+Show the sizes of all debug sections, expressed in bytes.
+:::
+
+:::{option} --show-sources
+Print all source files mentioned in the debug information. Absolute
+paths are given whenever possible.
+:::
+
+:::{option} --statistics
+Collect debug info quality metrics and print the results
+as machine-readable single-line JSON output. The output
+format is described in the section below ({ref}`stats-format`).
+:::
+
+:::{option} --summarize-types
+Abbreviate the description of type unit entries.
+:::
+
+:::{option} -t, --filter-child-tag
+Only dump children whose DWARF tag is one of the specified tags.
+Example usage:
+
+```c
+llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c
+```
+:::
+
+:::{option} -x, --regex
+Treat any \<name> strings as regular expressions when searching
+with {option}`--name`. If {option}`--ignore-case` is also specified,
+the regular expression becomes case-insensitive.
+:::
+
+:::{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} --verify-json=<path>
+Output JSON-formatted error summary to the file specified by
+\<path>. Implies {option}`--verify`. The output format is described
+in the section below ({ref}`verify-json-format`).
+:::
+
+:::{option} --version
+Display the version of the tool.
+:::
+
+:::{option} --debug-abbrev, --debug-addr, --debug-aranges, --debug-cu-index, --debug-frame [=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-line-str, --debug-loc [=<offset>], --debug-loclists [=<offset>], --debug-macro, --debug-names, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-rnglists, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types [=<offset>], --eh-frame [=<offset>], --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.
+
+The {option}`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections.
+
+The {option}`--debug-frame` and {option}`--eh-frame` options are aliases, in cases where both sections are present one command outputs both.
+:::
+
+:::{option} --show-variable-coverage
+Show per-variable coverage metrics. The output format is described
+in the section below ({ref}`variable-coverage-format`).
+:::
+
+:::{option} --coverage-baseline
+File to use as the baseline for variable coverage statistics
+(implies {option}`--show-variable-coverage`)
+:::
+
+:::{option} --variable-coverage-bitcode-file
+File containing LLVM IR (bitcode or textual) used for calculating
+variable definedness in coverage statistics (implies
+{option}`--show-variable-coverage`)
+:::
+
+:::{option} --combine-inline-variable-instances
+Use with {option}`--show-variable-coverage` to average variable
+coverage across inlined subroutine instances instead of printing
+them separately.
+:::
+
+:::{option} @<FILE>
+Read command-line options from `<FILE>`.
+:::
+
+(stats-format)=
+
+## FORMAT OF STATISTICS OUTPUT
+
+The {option}`--statistics` option generates single-line JSON output
representing quality metrics of the processed debug info. These metrics are
useful to compare changes between two compilers, particularly for judging
the effect that a change to the compiler has on the debug info quality.
@@ -232,86 +229,87 @@ the effect that a change to the compiler has on the debug info quality.
The output is formatted as key-value pairs. The first pair contains a version
number. The following naming scheme is used for the keys:
- - `variables` ==> local variables and parameters
- - `local vars` ==> local variables
- - `params` ==> formal parameters
+> - `variables` ==> local variables and parameters
+> - `local vars` ==> local variables
+> - `params` ==> formal parameters
For aggregated values, the following keys are used:
- - `sum_of_all_variables(...)` ==> the sum applied to all variables
- - `#bytes` ==> the number of bytes
- - `#variables - entry values ...` ==> the number of variables excluding
- the entry values etc.
+> - `sum_of_all_variables(...)` ==> the sum applied to all variables
+> - `#bytes` ==> the number of bytes
+> - `#variables - entry values ...` ==> the number of variables excluding
+> the entry values etc.
-.. _verify-json-format:
+(verify-json-format)=
-FORMAT OF VERIFY JSON OUTPUT
-----------------------------
+## FORMAT OF VERIFY JSON OUTPUT
-The format of the JSON output created by the :option:`--verify-json` is::
+The format of the JSON output created by the {option}`--verify-json` is:
- {
- "error-categories": {
- "<first category description>": {"count": 1234},
- "<next category description>": {"count": 4321}
- },
- "error-count": 5555
- }
+```
+{
+ "error-categories": {
+ "<first category description>": {"count": 1234},
+ "<next category description>": {"count": 4321}
+ },
+ "error-count": 5555
+}
+```
-The following is generated if there are no errors reported::
+The following is generated if there are no errors reported:
- {
- "error-categories": {},
- "error-count": 0
- }
+```
+{
+ "error-categories": {},
+ "error-count": 0
+}
+```
-.. _variable-coverage-format:
+(variable-coverage-format)=
-FORMAT OF VARIABLE COVERAGE OUTPUT
-----------------------------------
+## FORMAT OF VARIABLE COVERAGE OUTPUT
-The :option:`--show-variable-coverage` option differs from
-:option:`--statistics` by printing per-variable debug info coverage metrics
+The {option}`--show-variable-coverage` option differs from
+{option}`--statistics` by printing per-variable debug info coverage metrics
based on the number of source lines covered instead of the number of
instruction bytes. Compared to counting instruction bytes, this is more stable
across compilations and better reflects the debugging experience. The output is
a tab-separated table containing the following columns:
- - `Function` ==> Name of the function the variable was found in
- - `InstanceCount` (when :option:`--combine-inline-variable-instances` is
- specified) ==> Number of instances of the function; this is 1 for
- functions that have not been inlined, and n+1 for functions that have
- been inlined n times
- - `InlChain` (when :option:`--combine-inline-variable-instances` is not
- specified) ==> Chain of call sites (file and line number) that the
- function has been inlined into; this will be empty if the function has
- not been inlined
- - `Variable` ==> Name of the variable
- - `Decl` ==> Source location (file and line number) of the variable's
- declaration
- - `LinesCovered` ==> Number of source lines covered by the variable's
- debug information in the input file
- - `Baseline` (empty if :option:`--coverage-baseline` is not specified)
- ==> Number of source lines covered by the variable's debug information
- in the baseline
- - `CoveredRatio` (empty if :option:`--coverage-baseline` is not
- specified) ==> Ratio of the coverage compared to the baseline
- (calculated as `LinesCovered/Baseline`)
- - `LinesPresent` (empty if :option:`--coverage-baseline` is not
- specified) ==> Number of source lines covered in the variable's
- baseline debug information that are also present in the input file's
- line table
- - `LinesPresentRatio` (empty if :option:`--coverage-baseline` is not
- specified) ==> Ratio of the line table coverage compared to the
- baseline (calculated as `LinesPresent/Baseline`)
-
-EXIT STATUS
------------
-
-:program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
+> - `Function` ==> Name of the function the variable was found in
+> - `InstanceCount` (when {option}`--combine-inline-variable-instances` is
+> specified) ==> Number of instances of the function; this is 1 for
+> functions that have not been inlined, and n+1 for functions that have
+> been inlined n times
+> - `InlChain` (when {option}`--combine-inline-variable-instances` is not
+> specified) ==> Chain of call sites (file and line number) that the
+> function has been inlined into; this will be empty if the function has
+> not been inlined
+> - `Variable` ==> Name of the variable
+> - `Decl` ==> Source location (file and line number) of the variable's
+> declaration
+> - `LinesCovered` ==> Number of source lines covered by the variable's
+> debug information in the input file
+> - `Baseline` (empty if {option}`--coverage-baseline` is not specified)
+> ==> Number of source lines covered by the variable's debug information
+> in the baseline
+> - `CoveredRatio` (empty if {option}`--coverage-baseline` is not
+> specified) ==> Ratio of the coverage compared to the baseline
+> (calculated as `LinesCovered/Baseline`)
+> - `LinesPresent` (empty if {option}`--coverage-baseline` is not
+> specified) ==> Number of source lines covered in the variable's
+> baseline debug information that are also present in the input file's
+> line table
+> - `LinesPresentRatio` (empty if {option}`--coverage-baseline` is not
+> specified) ==> Ratio of the line table coverage compared to the
+> baseline (calculated as `LinesPresent/Baseline`)
+
+## EXIT STATUS
+
+{program}`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
successfully. Otherwise, it returns 1.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`dsymutil(1)`
-:manpage:`dsymutil(1)`
diff --git a/llvm/docs/CommandGuide/llvm-dwarfutil.md b/llvm/docs/CommandGuide/llvm-dwarfutil.md
index 98858deccf742..b300796ea50ed 100644
--- a/llvm/docs/CommandGuide/llvm-dwarfutil.md
+++ b/llvm/docs/CommandGuide/llvm-dwarfutil.md
@@ -1,17 +1,16 @@
-llvm-dwarfutil - A tool to copy and manipulate debug info
-=========================================================
+# llvm-dwarfutil - A tool to copy and manipulate debug info
+```{eval-rst}
.. program:: llvm-dwarfutil
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-dwarfutil` [*options*] *input* *output*
+{program}`llvm-dwarfutil` \[*options*\] *input* *output*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-dwarfutil` is a tool to copy and manipulate debug info.
+{program}`llvm-dwarfutil` is a tool to copy and manipulate debug info.
In basic usage, it makes a semantic copy of the input to the output. If any
options are specified, the output may be modified along the way, e.g.
@@ -23,100 +22,94 @@ is written to the standard output stream of the program.
The tool is still in active development.
-COMMAND-LINE OPTIONS
---------------------
+## COMMAND-LINE OPTIONS
-.. option:: --garbage-collection
+:::{option} --garbage-collection
+Removes pieces of debug information related to discarded sections.
+When the linker does section garbage collection the abandoned debug info
+is left behind. Such abandoned debug info references address ranges using
+tombstone values. Thus, when this option is specified, the tool removes
+debug info which is marked with the tombstone value.
- Removes pieces of debug information related to discarded sections.
- When the linker does section garbage collection the abandoned debug info
- is left behind. Such abandoned debug info references address ranges using
- tombstone values. Thus, when this option is specified, the tool removes
- debug info which is marked with the tombstone value.
+That option is enabled by default.
+:::
- That option is enabled by default.
+:::{option} --odr-deduplication
+Remove duplicated types (if "One Definition Rule" is supported by source
+language). Keeps first type definition and removes other definitions,
+potentially significantly reducing the size of output debug info.
-.. option:: --odr-deduplication
+That option is enabled by default.
+:::
- Remove duplicated types (if "One Definition Rule" is supported by source
- language). Keeps first type definition and removes other definitions,
- potentially significantly reducing the size of output debug info.
+:::{option} --help, -h
+Print a summary of command line options.
+:::
- That option is enabled by default.
+:::{option} --no-garbage-collection
+Disable {option}`--garbage-collection`.
+:::
-.. option:: --help, -h
+:::{option} --no-odr-deduplication
+Disable {option}`--odr-deduplication`.
+:::
- Print a summary of command line options.
+:::{option} --no-separate-debug-file
+Disable {option}`--separate-debug-file`.
+:::
-.. option:: --no-garbage-collection
+:::{option} --num-threads=<n>, -j
+Specifies the maximum number (`n`) of simultaneous threads to use
+for processing.
+:::
- Disable :option:`--garbage-collection`.
+:::{option} --separate-debug-file
+Generate separate file containing output debug info. Using
+{program}`llvm-dwarfutil` with that option equals to the
+following set of commands:
+:::
-.. option:: --no-odr-deduplication
+```console
+:program:`llvm-objcopy` --only-keep-debug in-file out-file.debug
+:program:`llvm-objcopy` --strip-debug in-file out-file
+:program:`llvm-objcopy` --add-gnu-debuglink=out-file.debug out-file
+```
- Disable :option:`--odr-deduplication`.
+:::{option} --tombstone=<value>
+\<value> can be one of the following values:
-.. option:: --no-separate-debug-file
+> - `bfd`: zero for all addresses and [1,1] for DWARF v4 (or less) address ranges and exec.
+> - `maxpc`: -1 for all addresses and -2 for DWARF v4 (or less) address ranges.
+> - `universal`: both `bfd` and `maxpc`.
+> - `exec`: match with address ranges of executable sections.
+>
+> The value `universal` is used by default.
+:::
- Disable :option:`--separate-debug-file`.
+:::{option} --verbose
+Enable verbose logging. This option disables multi-thread mode.
+:::
-.. option:: --num-threads=<n>, -j
+:::{option} --verify
+Run the DWARF verifier on the output DWARF debug info.
+:::
- Specifies the maximum number (`n`) of simultaneous threads to use
- for processing.
+:::{option} --version
+Print the version of this program.
+:::
-.. option:: --separate-debug-file
+## SUPPORTED FORMATS
- Generate separate file containing output debug info. Using
- :program:`llvm-dwarfutil` with that option equals to the
- following set of commands:
-
-.. code-block:: console
-
- :program:`llvm-objcopy` --only-keep-debug in-file out-file.debug
- :program:`llvm-objcopy` --strip-debug in-file out-file
- :program:`llvm-objcopy` --add-gnu-debuglink=out-file.debug out-file
-
-.. option:: --tombstone=<value>
-
- <value> can be one of the following values:
-
- - `bfd`: zero for all addresses and [1,1] for DWARF v4 (or less) address ranges and exec.
-
- - `maxpc`: -1 for all addresses and -2 for DWARF v4 (or less) address ranges.
-
- - `universal`: both `bfd` and `maxpc`.
-
- - `exec`: match with address ranges of executable sections.
-
- The value `universal` is used by default.
-
-.. option:: --verbose
-
- Enable verbose logging. This option disables multi-thread mode.
-
-.. option:: --verify
-
- Run the DWARF verifier on the output DWARF debug info.
-
-.. option:: --version
-
- Print the version of this program.
-
-SUPPORTED FORMATS
------------------
-
-The following formats are currently supported by :program:`llvm-dwarfutil`:
+The following formats are currently supported by {program}`llvm-dwarfutil`:
ELF
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-dwarfutil` exits with a non-zero exit code if there is an error.
+{program}`llvm-dwarfutil` exits with a non-zero exit code if there is an error.
Otherwise, it exits with code 0.
-BUGS
-----
+## BUGS
+
+To report bugs, please visit \<<https://github.com/llvm/llvm-project/labels/tools:llvm-dwarfutil/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-dwarfutil/>.
diff --git a/llvm/docs/CommandGuide/llvm-exegesis.md b/llvm/docs/CommandGuide/llvm-exegesis.md
index 5996026a1deac..90017e733b181 100644
--- a/llvm/docs/CommandGuide/llvm-exegesis.md
+++ b/llvm/docs/CommandGuide/llvm-exegesis.md
@@ -1,21 +1,20 @@
-llvm-exegesis - LLVM Machine Instruction Benchmark
-==================================================
+# llvm-exegesis - LLVM Machine Instruction Benchmark
+```{eval-rst}
.. program:: llvm-exegesis
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-exegesis` [*options*]
+{program}`llvm-exegesis` \[*options*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-exegesis` is a benchmarking tool that uses information available
+{program}`llvm-exegesis` is a benchmarking tool that uses information available
in LLVM to measure host machine instruction characteristics like latency,
throughput, or port decomposition.
-Given an LLVM opcode name and a benchmarking mode, :program:`llvm-exegesis`
+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. inverse throughput/uop decomposition)
of the instruction.
@@ -27,21 +26,20 @@ 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
+{program}`llvm-exegesis` can also benchmark arbitrary user-provided code
snippets.
-SUPPORTED PLATFORMS
--------------------
+## SUPPORTED PLATFORMS
-:program:`llvm-exegesis` currently only supports X86 (64-bit only), ARM
+{program}`llvm-exegesis` currently only supports X86 (64-bit only), ARM
(AArch64 only, snippet generation is sparse), MIPS, PowerPC (PowerPC64LE
only) and RISC-V (RV64I/E and RV32I/E) on Linux for benchmarking. Not all
benchmarking functionality is guaranteed to work on every platform.
-:program:`llvm-exegesis` also has a separate analysis mode that is supported on
+{program}`llvm-exegesis` also has a separate analysis mode that is supported on
every platform that LLVM is.
To enable benchmarking in llvm-exegesis, LLVM must be configured and built with
-`LLVM_ENABLE_LIBPFM` enabled, as :program:`llvm-exegesis` depends on libpfm4
+`LLVM_ENABLE_LIBPFM` enabled, as {program}`llvm-exegesis` depends on libpfm4
for accessing performance counters. Benchmarking may fail if the target CPU is
unsupported by libpfm. This can be verified by setting `LIBPFM_VERBOSE` and
`LIBPFM_DEBUG` environment variables to enable verbose or debug mode for
@@ -49,35 +47,36 @@ libpfm. If libpfm is installed in a non-standard directory, LLVM can be
configured to locate the necessary library and header files by setting
`LIBRARY_PATH`, `C_INCLUDE_PATH`, and `CPLUS_INCLUDE_PATH` environment
variables. Additionally, `LD_LIBRARY_PATH` should be set so that
-:program:`llvm-exegesis` can locate the libpfm library during execution.
+{program}`llvm-exegesis` can locate the libpfm library during execution.
-SNIPPET ANNOTATIONS
--------------------
+## SNIPPET ANNOTATIONS
-:program:`llvm-exegesis` supports benchmarking arbitrary snippets of assembly.
+{program}`llvm-exegesis` supports benchmarking arbitrary snippets of assembly.
However, benchmarking these snippets often requires some setup so that they
-can execute properly. :program:`llvm-exegesis` has five annotations and some
+can execute properly. {program}`llvm-exegesis` has five annotations and some
additional utilities to help with setup so that snippets can be benchmarked
properly.
-* `LLVM-EXEGESIS-DEFREG <register name>` - Adding this annotation to the text
+- `LLVM-EXEGESIS-DEFREG <register name>` - Adding this annotation to the text
assembly snippet to be benchmarked marks the register as requiring a definition.
A value will automatically be provided unless a second parameter, a hex value,
is passed in. This is done with the `LLVM-EXEGESIS-DEFREG <register name> <hex value>`
format. `<hex value>` is a bit pattern used to fill the register. If it is a
value smaller than the register, it is sign extended to match the size of the
register.
-* `LLVM-EXEGESIS-LIVEIN <register name>` - This annotation allows specifying
+
+- `LLVM-EXEGESIS-LIVEIN <register name>` - This annotation allows specifying
registers that should keep their value upon starting the benchmark. Values
can be passed through registers from the benchmarking setup in some cases.
The registers and the values assigned to them that can be utilized in the
benchmarking script with a `LLVM-EXEGESIS-LIVEIN` are as follows:
- * Scratch memory register - The specific register that this value is put in
+ - Scratch memory register - The specific register that this value is put in
is platform dependent (e.g., it is the RDI register on X86 Linux). Setting
this register as a live in ensures that a pointer to a block of memory (1MB)
is placed within this register that can be used by the snippet.
-* `LLVM-EXEGESIS-MEM-DEF <value name> <size> <value>` - This annotation allows
+
+- `LLVM-EXEGESIS-MEM-DEF <value name> <size> <value>` - This annotation allows
specifying memory definitions that can later be mapped into the execution
process of a snippet with the `LLVM-EXEGESIS-MEM-MAP` annotation. Each
value is named using the `<value name>` argument so that it can be referenced
@@ -86,14 +85,16 @@ properly.
than the specified size, the value will be repeated until it fills the entire
section of memory. Using this annotation requires using the subprocess execution
mode.
-* `LLVM-EXEGESIS-MEM-MAP <value name> <address>` - This annotation allows for
+
+- `LLVM-EXEGESIS-MEM-MAP <value name> <address>` - This annotation allows for
mapping previously defined memory definitions into the execution context of a
process. The value name refers to a previously defined memory definition and
the address is a decimal number that specifies the address the memory
definition should start at. Note that a single memory definition can be
mapped multiple times. Using this annotation requires the subprocess
execution mode.
-* `LLVM-EXEGESIS-SNIPPET-ADDRESS <address>` - This annotation allows for
+
+- `LLVM-EXEGESIS-SNIPPET-ADDRESS <address>` - This annotation allows for
setting the address where the beginning of the snippet to be executed will
be mapped in at. The address is given in hexadecimal. Note that the snippet
also includes setup code, so the instruction exactly at the specified
@@ -101,74 +102,71 @@ properly.
annotation requires the subprocess execution mode. This is useful in
cases where the memory accessed by the snippet depends on the location
of the snippet, like RIP-relative addressing.
-* `LLVM-EXEGESIS-LOOP-REGISTER <register name>` - This annotation specifies
+
+- `LLVM-EXEGESIS-LOOP-REGISTER <register name>` - This annotation specifies
the loop register to use for keeping track of the current iteration when
- using the loop repetition mode. :program:`llvm-exegesis` needs to keep track
+ using the loop repetition mode. {program}`llvm-exegesis` needs to keep track
of the current loop iteration within the loop repetition mode in a performant
manner (i.e., no memory accesses), and uses a register to do this. This register
has an architecture-specific default (e.g., `R8` on X86), but this might conflict
with some snippets. This annotation allows changing the register to prevent
interference between the loop index register and the snippet.
-EXAMPLE 1: benchmarking instructions
-------------------------------------
+## 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
+```bash
+$ llvm-exegesis --mode=latency --opcode-name=ADD64rr
+```
Measuring the uop decomposition or inverse throughput of an instruction works similarly:
-.. code-block:: bash
-
- $ llvm-exegesis --mode=uops --opcode-name=ADD64rr
- $ llvm-exegesis --mode=inverse_throughput --opcode-name=ADD64rr
-
+```bash
+$ llvm-exegesis --mode=uops --opcode-name=ADD64rr
+$ llvm-exegesis --mode=inverse_throughput --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
- '
- ...
+```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
-
- $ llvm-exegesis --mode=latency --opcode-index=-1
+```bash
+$ llvm-exegesis --mode=latency --opcode-index=-1
+```
-
-EXAMPLE 2: benchmarking a custom code snippet
----------------------------------------------
+## 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=-
+```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
+{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 need to use snippet annotations to ensure setup
is performed properly.
@@ -176,314 +174,308 @@ is performed properly.
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
+```none
+# LLVM-EXEGESIS-LIVEIN RDI
+# LLVM-EXEGESIS-DEFREG XMM1 42
+vmulps (%rdi), %xmm1, %xmm2
+vhaddps %xmm2, %xmm2, %xmm3
+addq $0x10, %rdi
+```
- # LLVM-EXEGESIS-LIVEIN RDI
- # LLVM-EXEGESIS-DEFREG XMM1 42
- vmulps (%rdi), %xmm1, %xmm2
- vhaddps %xmm2, %xmm2, %xmm3
- addq $0x10, %rdi
-
-
-Example 3: benchmarking with memory annotations
------------------------------------------------
+## Example 3: benchmarking with memory annotations
Some snippets require memory setup in specific places to execute without
crashing. Setting up memory can be accomplished with the `LLVM-EXEGESIS-MEM-DEF`
and `LLVM-EXEGESIS-MEM-MAP` annotations. To execute the following snippet:
-.. code-block:: none
-
- movq $8192, %rax
- movq (%rax), %rdi
+```none
+movq $8192, %rax
+movq (%rax), %rdi
+```
We need to have at least eight bytes of memory allocated starting `0x2000`.
We can create the necessary execution environment with the following
annotations added to the snippet:
-.. code-block:: none
+```none
+# LLVM-EXEGESIS-MEM-DEF test1 4096 7fffffff
+# LLVM-EXEGESIS-MEM-MAP test1 8192
- # LLVM-EXEGESIS-MEM-DEF test1 4096 7fffffff
- # LLVM-EXEGESIS-MEM-MAP test1 8192
+movq $8192, %rax
+movq (%rax), %rdi
+```
- movq $8192, %rax
- movq (%rax), %rdi
-
-EXAMPLE 4: analysis
--------------------
+## EXAMPLE 4: 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
+```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
+```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
+```{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
+{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. Specifying `-1` will result
- in measuring every existing opcode. 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|inverse_throughput|analysis]
-
- Specify the run mode. Note that some modes have additional requirements and options.
-
- `latency` mode can be make use of either RDTSC or LBR.
- `latency[LBR]` is only available on X86 (at least `Skylake`).
- To run in `latency` mode, a positive value must be specified
- for `x86-lbr-sample-period` and `--repetition-mode=loop`.
-
- In `analysis` mode, you also need to specify at least one of the
- `-analysis-clusters-output-file=` and `-analysis-inconsistencies-output-file=`.
-
-.. option:: --benchmark-phase=[prepare-snippet|prepare-and-assemble-snippet|assemble-measured-code|measure]
-
- By default, when `-mode=` is specified, the generated snippet will be executed
- and measured, and that requires that we are running on the hardware for which
- the snippet was generated, and that supports performance measurements.
- However, it is possible to stop at some stage before measuring. Choices are:
- * ``prepare-snippet``: Only generate the minimal instruction sequence.
- * ``prepare-and-assemble-snippet``: Same as ``prepare-snippet``, but also dumps an excerpt of the sequence (hex encoded).
- * ``assemble-measured-code``: Same as ``prepare-and-assemble-snippet``. but also creates the full sequence that can be dumped to a file using ``--dump-object-to-disk``.
- * ``measure``: Same as ``assemble-measured-code``, but also runs the measurement.
-
-.. option:: --x86-lbr-sample-period=<nBranches/sample>
-
- Specify the LBR sampling period - how many branches before we take a sample.
- When a positive value is specified for this option and when the mode is `latency`,
- we will use LBRs for measuring.
- On choosing the "right" sampling period, a small value is preferred, but throttling
- could occur if the sampling is too frequent. A prime number should be used to
- avoid consistently skipping certain blocks.
-
-.. option:: --x86-disable-upper-sse-registers
-
- Using the upper xmm registers (xmm8-xmm15) forces a longer instruction encoding
- which may put greater pressure on the frontend fetch and decode stages,
- potentially reducing the rate that instructions are dispatched to the backend,
- particularly on older hardware. Comparing baseline results with this mode
- enabled can help determine the effects of the frontend and can be used to
- improve latency and throughput estimates.
-
-.. option:: --repetition-mode=[duplicate|loop|min|middle-half-duplicate|middle-half-loop]
-
- Specify the repetition mode. `duplicate` will create a large, straight line
- basic block with `min-instructions` instructions (repeating the snippet
- `min-instructions`/`snippet size` times). `loop` will, optionally, duplicate the
- snippet until the loop body contains at least `loop-body-size` instructions,
- and then wrap the result in a loop which will execute `min-instructions`
- instructions (thus, again, repeating the snippet
- `min-instructions`/`snippet size` times). The `loop` mode, especially with loop
- unrolling tends to better hide the effects of the CPU frontend on architectures
- that cache decoded instructions, but consumes a register for counting
- iterations. If performing an analysis over many opcodes, it may be best to
- instead use the `min` mode, which will run each other mode,
- and produce the minimal measured result. The middle half repetition modes
- will either duplicate or run the snippet in a loop depending upon the specific
- mode. The middle half repetition modes will run two benchmarks, one twice the
- length of the first one, and then subtract the difference between them to get
- values without overhead.
-
-.. option:: --min-instructions=<Number of instructions>
-
- Specify the target number of executed instructions. Note that the actual
- repetition count of the snippet will be `min-instructions`/`snippet size`.
- Higher values lead to more accurate measurements but lengthen the benchmark.
-
-.. option:: --loop-body-size=<Preferred loop body size>
-
- Only effective for `-repetition-mode=[loop|min]`.
- Instead of looping over the snippet directly, first duplicate it so that the
- loop body contains at least this many instructions. This potentially results
- in loop body being cached in the CPU Op Cache / Loop Cache, which allows to
- which may have higher throughput than the CPU decoders.
-
-.. option:: --max-configs-per-opcode=<value>
-
- Specify the maximum configurations that can be generated for each opcode.
- By default this is `1`, meaning that we assume that a single measurement is
- enough to characterize an opcode. This might not be true of all instructions:
- for example, the performance characteristics of the LEA instruction on X86
- depends on the value of assigned registers and immediates. Setting a value of
- `-max-configs-per-opcode` larger than `1` allows `llvm-exegesis` to explore
- more configurations to discover if some register or immediate assignments
- lead to different performance characteristics.
-
-
-.. option:: --benchmarks-file=</path/to/file>
-
- File to read (`analysis` mode) or write (`latency`/`uops`/`inverse_throughput`
- 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. By default, this analysis is not run.
-
-.. option:: --analysis-inconsistencies-output-file=</path/to/file>
-
- If non-empty, write inconsistencies found during analysis to this file. `-`
- prints to stdout. By default, this analysis is not run.
-
-.. option:: --analysis-filter=[all|reg-only|mem-only]
-
- By default, all benchmark results are analysed, but sometimes it may be useful
- to only look at those that to not involve memory, or vice versa. This option
- allows to either keep all benchmarks, or filter out (ignore) either all the
- ones that do involve memory (involve instructions that may read or write to
- memory), or the opposite, to only keep such benchmarks.
-
-.. option:: --analysis-clustering=[dbscan,naive]
-
- Specify the clustering algorithm to use. By default DBSCAN will be used.
- Naive clustering algorithm is better for doing further work on the
- `-analysis-inconsistencies-output-file=` output, it will create one cluster
- per opcode, and check that the cluster is stable (all points are neighbours).
-
-.. option:: --analysis-numpoints=<dbscan numPoints parameter>
-
- Specify the numPoints parameters to be used for DBSCAN clustering
- (`analysis` mode, DBSCAN only).
-
-.. option:: --analysis-clustering-epsilon=<dbscan epsilon parameter>
-
- Specify the epsilon parameter used for clustering of benchmark points
- (`analysis` mode).
-
-.. option:: --analysis-inconsistency-epsilon=<epsilon>
-
- Specify the epsilon parameter used for detection of when the cluster
- is different from the LLVM schedule profile values (`analysis` mode).
-
-.. option:: --analysis-display-unstable-clusters
-
- If there is more than one benchmark for an opcode, said benchmarks may end up
- not being clustered into the same cluster if the measured performance
- characteristics are different. by default all such opcodes are filtered out.
- This flag will instead show only such unstable opcodes.
-
-.. option:: --ignore-invalid-sched-class=false
-
- If set, ignore instructions that do not have a sched class (class idx = 0).
-
-.. option:: --mtriple=<triple name>
-
- Target triple. See `-version` for available targets.
-
-.. 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).
- (`-mcpu=help` for details)
-
-.. option:: --analysis-override-benchmark-triple-and-cpu
-
- By default, llvm-exegesis will analyze the benchmarks for the triple/CPU they
- were measured for, but if you want to analyze them for some other combination
- (specified via `-mtriple`/`-mcpu`), you can pass this flag.
-
-.. option:: --dump-object-to-disk=<filename>
-
- If set, llvm-exegesis will dump the generated code to a temporary file to
- enable code inspection. Disabled by default.
-
-.. option:: --use-dummy-perf-counters
-
- If set, llvm-exegesis will not read any real performance counters and
- return a dummy value instead. This can be used to ensure a snippet doesn't
- crash when hardware performance counters are unavailable and for
- debugging :program:`llvm-exegesis` itself.
-
-.. option:: --execution-mode=[inprocess,subprocess]
-
- This option specifies what execution mode to use. The `inprocess` execution
- mode is the default. The `subprocess` execution mode allows for additional
- features such as memory annotations but is currently restricted to X86-64
- on Linux.
-
-.. option:: --benchmark-repeat-count=<repeat-count>
-
- This option enables specifying the number of times to repeat the measurement
- when performing latency measurements. By default, llvm-exegesis will repeat
- a latency measurement enough times to balance run-time and noise reduction.
-
-.. option:: --validation-counter=[instructions-retired,l1d-cache-load-misses,
- l1d-cache-store-misses,l1i-cache-load-misses,data-tlb-load-misses,
- data-tld-store-misses,instruction-tlb-load-misses]
-
- This option enables the use of validation counters, which measure additional
- microarchitectural events like cache misses to validate snippet execution
- conditions. These events are measured using the perf subsystem in a group
- with the performance counter used to measure the value of interest. This
- flag can be specified multiple times to measure multiple events. The maximum
- number of validation counters is platform dependent.
-
-.. option:: --benchmark-process-cpu=<cpu id>
-
- This option specifies the number of the CPU that should be used to run the
- benchmarking subprocess. When starting the subprocess,
- :program:`llvm-exegesis` will set the affinity of the subprocess to only
- include the specified CPU. This option only works in the subprocess execution
- mode.
-
-EXIT STATUS
------------
-
-:program:`llvm-exegesis` returns 0 on success. Otherwise, an error message is
+## OPTIONS
+
+:::{option} --help
+Print a summary of command line options.
+:::
+
+:::{option} --opcode-index=<LLVM opcode index>
+Specify the opcode to measure, by index. Specifying `-1` will result
+in measuring every existing opcode. 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|inverse_throughput|analysis]
+Specify the run mode. Note that some modes have additional requirements and options.
+
+`latency` mode can be make use of either RDTSC or LBR.
+`latency[LBR]` is only available on X86 (at least `Skylake`).
+To run in `latency` mode, a positive value must be specified
+for `x86-lbr-sample-period` and `--repetition-mode=loop`.
+
+In `analysis` mode, you also need to specify at least one of the
+`-analysis-clusters-output-file=` and `-analysis-inconsistencies-output-file=`.
+:::
+
+:::{option} --benchmark-phase=[prepare-snippet|prepare-and-assemble-snippet|assemble-measured-code|measure]
+By default, when `-mode=` is specified, the generated snippet will be executed
+and measured, and that requires that we are running on the hardware for which
+the snippet was generated, and that supports performance measurements.
+However, it is possible to stop at some stage before measuring. Choices are:
+\* `prepare-snippet`: Only generate the minimal instruction sequence.
+\* `prepare-and-assemble-snippet`: Same as `prepare-snippet`, but also dumps an excerpt of the sequence (hex encoded).
+\* `assemble-measured-code`: Same as `prepare-and-assemble-snippet`. but also creates the full sequence that can be dumped to a file using `--dump-object-to-disk`.
+\* `measure`: Same as `assemble-measured-code`, but also runs the measurement.
+:::
+
+:::{option} --x86-lbr-sample-period=<nBranches/sample>
+Specify the LBR sampling period - how many branches before we take a sample.
+When a positive value is specified for this option and when the mode is `latency`,
+we will use LBRs for measuring.
+On choosing the "right" sampling period, a small value is preferred, but throttling
+could occur if the sampling is too frequent. A prime number should be used to
+avoid consistently skipping certain blocks.
+:::
+
+:::{option} --x86-disable-upper-sse-registers
+Using the upper xmm registers (xmm8-xmm15) forces a longer instruction encoding
+which may put greater pressure on the frontend fetch and decode stages,
+potentially reducing the rate that instructions are dispatched to the backend,
+particularly on older hardware. Comparing baseline results with this mode
+enabled can help determine the effects of the frontend and can be used to
+improve latency and throughput estimates.
+:::
+
+:::{option} --repetition-mode=[duplicate|loop|min|middle-half-duplicate|middle-half-loop]
+Specify the repetition mode. `duplicate` will create a large, straight line
+basic block with `min-instructions` instructions (repeating the snippet
+`min-instructions`/`snippet size` times). `loop` will, optionally, duplicate the
+snippet until the loop body contains at least `loop-body-size` instructions,
+and then wrap the result in a loop which will execute `min-instructions`
+instructions (thus, again, repeating the snippet
+`min-instructions`/`snippet size` times). The `loop` mode, especially with loop
+unrolling tends to better hide the effects of the CPU frontend on architectures
+that cache decoded instructions, but consumes a register for counting
+iterations. If performing an analysis over many opcodes, it may be best to
+instead use the `min` mode, which will run each other mode,
+and produce the minimal measured result. The middle half repetition modes
+will either duplicate or run the snippet in a loop depending upon the specific
+mode. The middle half repetition modes will run two benchmarks, one twice the
+length of the first one, and then subtract the difference between them to get
+values without overhead.
+:::
+
+:::{option} --min-instructions=<Number of instructions>
+Specify the target number of executed instructions. Note that the actual
+repetition count of the snippet will be `min-instructions`/`snippet size`.
+Higher values lead to more accurate measurements but lengthen the benchmark.
+:::
+
+:::{option} --loop-body-size=<Preferred loop body size>
+Only effective for `-repetition-mode=[loop|min]`.
+Instead of looping over the snippet directly, first duplicate it so that the
+loop body contains at least this many instructions. This potentially results
+in loop body being cached in the CPU Op Cache / Loop Cache, which allows to
+which may have higher throughput than the CPU decoders.
+:::
+
+:::{option} --max-configs-per-opcode=<value>
+Specify the maximum configurations that can be generated for each opcode.
+By default this is `1`, meaning that we assume that a single measurement is
+enough to characterize an opcode. This might not be true of all instructions:
+for example, the performance characteristics of the LEA instruction on X86
+depends on the value of assigned registers and immediates. Setting a value of
+`-max-configs-per-opcode` larger than `1` allows `llvm-exegesis` to explore
+more configurations to discover if some register or immediate assignments
+lead to different performance characteristics.
+:::
+
+:::{option} --benchmarks-file=</path/to/file>
+File to read (`analysis` mode) or write (`latency`/`uops`/`inverse_throughput`
+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. By default, this analysis is not run.
+:::
+
+:::{option} --analysis-inconsistencies-output-file=</path/to/file>
+If non-empty, write inconsistencies found during analysis to this file. `-`
+prints to stdout. By default, this analysis is not run.
+:::
+
+:::{option} --analysis-filter=[all|reg-only|mem-only]
+By default, all benchmark results are analysed, but sometimes it may be useful
+to only look at those that to not involve memory, or vice versa. This option
+allows to either keep all benchmarks, or filter out (ignore) either all the
+ones that do involve memory (involve instructions that may read or write to
+memory), or the opposite, to only keep such benchmarks.
+:::
+
+:::{option} --analysis-clustering=[dbscan,naive]
+Specify the clustering algorithm to use. By default DBSCAN will be used.
+Naive clustering algorithm is better for doing further work on the
+`-analysis-inconsistencies-output-file=` output, it will create one cluster
+per opcode, and check that the cluster is stable (all points are neighbours).
+:::
+
+:::{option} --analysis-numpoints=<dbscan numPoints parameter>
+Specify the numPoints parameters to be used for DBSCAN clustering
+(`analysis` mode, DBSCAN only).
+:::
+
+:::{option} --analysis-clustering-epsilon=<dbscan epsilon parameter>
+Specify the epsilon parameter used for clustering of benchmark points
+(`analysis` mode).
+:::
+
+:::{option} --analysis-inconsistency-epsilon=<epsilon>
+Specify the epsilon parameter used for detection of when the cluster
+is different from the LLVM schedule profile values (`analysis` mode).
+:::
+
+:::{option} --analysis-display-unstable-clusters
+If there is more than one benchmark for an opcode, said benchmarks may end up
+not being clustered into the same cluster if the measured performance
+characteristics are different. by default all such opcodes are filtered out.
+This flag will instead show only such unstable opcodes.
+:::
+
+:::{option} --ignore-invalid-sched-class=false
+If set, ignore instructions that do not have a sched class (class idx = 0).
+:::
+
+:::{option} --mtriple=<triple name>
+Target triple. See `-version` for available targets.
+:::
+
+:::{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).
+(`-mcpu=help` for details)
+:::
+
+:::{option} --analysis-override-benchmark-triple-and-cpu
+By default, llvm-exegesis will analyze the benchmarks for the triple/CPU they
+were measured for, but if you want to analyze them for some other combination
+(specified via `-mtriple`/`-mcpu`), you can pass this flag.
+:::
+
+:::{option} --dump-object-to-disk=<filename>
+If set, llvm-exegesis will dump the generated code to a temporary file to
+enable code inspection. Disabled by default.
+:::
+
+:::{option} --use-dummy-perf-counters
+If set, llvm-exegesis will not read any real performance counters and
+return a dummy value instead. This can be used to ensure a snippet doesn't
+crash when hardware performance counters are unavailable and for
+debugging {program}`llvm-exegesis` itself.
+:::
+
+:::{option} --execution-mode=[inprocess,subprocess]
+This option specifies what execution mode to use. The `inprocess` execution
+mode is the default. The `subprocess` execution mode allows for additional
+features such as memory annotations but is currently restricted to X86-64
+on Linux.
+:::
+
+:::{option} --benchmark-repeat-count=<repeat-count>
+This option enables specifying the number of times to repeat the measurement
+when performing latency measurements. By default, llvm-exegesis will repeat
+a latency measurement enough times to balance run-time and noise reduction.
+:::
+
+:::{option} --validation-counter=[instructions-retired,l1d-cache-load-misses, l1d-cache-store-misses,l1i-cache-load-misses,data-tlb-load-misses, data-tld-store-misses,instruction-tlb-load-misses]
+This option enables the use of validation counters, which measure additional
+microarchitectural events like cache misses to validate snippet execution
+conditions. These events are measured using the perf subsystem in a group
+with the performance counter used to measure the value of interest. This
+flag can be specified multiple times to measure multiple events. The maximum
+number of validation counters is platform dependent.
+:::
+
+:::{option} --benchmark-process-cpu=<cpu id>
+This option specifies the number of the CPU that should be used to run the
+benchmarking subprocess. When starting the subprocess,
+{program}`llvm-exegesis` will set the affinity of the subprocess to only
+include the specified CPU. This option only works in the subprocess execution
+mode.
+:::
+
+## 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/llvm/docs/CommandGuide/llvm-extract-bundle-entry.md b/llvm/docs/CommandGuide/llvm-extract-bundle-entry.md
index 1b31105c06817..6e25b04a49770 100644
--- a/llvm/docs/CommandGuide/llvm-extract-bundle-entry.md
+++ b/llvm/docs/CommandGuide/llvm-extract-bundle-entry.md
@@ -1,59 +1,57 @@
-llvm-extract-bundle-entry - extract an offload bundle entry
-===========================================================
+# llvm-extract-bundle-entry - extract an offload bundle entry
+```{eval-rst}
.. program:: llvm-extract-bundle-entry
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-extract-bundle-entry` [*options*] URI
+{program}`llvm-extract-bundle-entry` \[*options*\] URI
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-extract-offload-entry` is a tool thet takes a URI argument and
+{program}`llvm-extract-offload-entry` is a tool thet takes a URI argument and
generates a code object file by extracting an offload bundle entry specified
by the URI given.
The URI syntax is defined as:
-- code-block::bnf
- <code_object_uri> ::== <file_uri> | <memory_uri>
- <file_uri> ::== "file://"<extract_file><range_specifier>
- <memory_uri> ::== "memory://"<process_id><range_specifier>
- <range_specifier> ::== [ "#" | "?" ]"offset="<number>"&size="<number>
- <extract_file> ::== URI_ENCODED_OS_FILE_PATH
- <process_id> ::== DECIMAL_NUMBER
- <number> ::== DECIMAL_NUMBER
-
+
+: \<code_object_uri> ::== \<file_uri> | \<memory_uri>
+ \<file_uri> ::== "<file://>"\<extract_file>\<range_specifier>
+ \<memory_uri> ::== "memory://"\<process_id>\<range_specifier>
+ \<range_specifier> ::== [ "#" | "?" ]"offset="\<number>"&size="\<number>
+ \<extract_file> ::== URI_ENCODED_OS_FILE_PATH
+ \<process_id> ::== DECIMAL_NUMBER
+ \<number> ::== DECIMAL_NUMBER
+
The output is always written to a file, whose name is generated from the URI input given.
-OPTIONS
--------
+## OPTIONS
The following options are either agnostic of the file format or apply to
multiple file formats.
-.. option:: --help, -h
-
- Print a summary of command line options.
+:::{option} --help, -h
+Print a summary of command line options.
+:::
-.. option:: -o <file>
+:::{option} -o <file>
+Write output to \<file>. Multiple input files cannot be used in combination
+with -o.
+:::
- Write output to <file>. Multiple input files cannot be used in combination
- with -o.
+:::{option} --version, -V
+Display the version of the {program}`llvm-extract-bundle-entry` executable.
+:::
-.. option:: --version, -V
+## EXIT STATUS
- Display the version of the :program:`llvm-extract-bundle-entry` executable.
-
-EXIT STATUS
------------
-
-:program:`llvm-extract-bundle-entry` exits with a non-zero exit code if there is an error.
+{program}`llvm-extract-bundle-entry` exits with a non-zero exit code if there is an error.
Otherwise, it exits with code 0.
-BUGS
-----
+## BUGS
+
+To report bugs, please visit \<<https://github.com/llvm/llvm-project/issues?q=state%3Aopen%20label%3Allvm-extract-bundle-entry>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/issues?q=state%3Aopen%20label%3Allvm-extract-bundle-entry>.
diff --git a/llvm/docs/CommandGuide/llvm-extract.md b/llvm/docs/CommandGuide/llvm-extract.md
index 704c482a1fd5f..f5c54d520b203 100644
--- a/llvm/docs/CommandGuide/llvm-extract.md
+++ b/llvm/docs/CommandGuide/llvm-extract.md
@@ -1,110 +1,107 @@
-llvm-extract - extract a function from an LLVM module
-=====================================================
+# llvm-extract - extract a function from an LLVM module
+```{eval-rst}
.. program:: llvm-extract
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-extract` [*options*] **--func** *function-name* [*filename*]
+{program}`llvm-extract` \[*options*\] **--func** *function-name* \[*filename*\]
-DESCRIPTION
------------
+## 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
+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,
+{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
+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
--------
+## OPTIONS
**--alias** *alias-name*
- Extract the alias named *function-name* from the LLVM bitcode. May be
- specified multiple times to extract multiple alias at once.
+> Extract the alias named *function-name* from the LLVM bitcode. May be
+> specified multiple times to extract multiple alias at once.
**--ralias** *alias-regular-expr*
- Extract the alias matching *alias-regular-expr* from the LLVM bitcode.
- All alias matching the regular expression will be extracted. May be
- specified multiple times.
+> Extract the alias matching *alias-regular-expr* from the LLVM bitcode.
+> All alias matching the regular expression will be extracted. May be
+> specified multiple times.
**--bb** *basic-block-specifier*
- Extract basic blocks(s) specified in *basic-block-specifier*. May be
- specified multiple times. Each <function:bb[;bb]> specifier pair will create
- a function. If multiple basic blocks are specified in one pair, the first
- block in the sequence should dominate the rest.
+> Extract basic blocks(s) specified in *basic-block-specifier*. May be
+> specified multiple times. Each \<function:bb[;bb]> specifier pair will create
+> a function. If multiple basic blocks are specified in one pair, the first
+> block in the sequence should dominate the rest.
**--delete**
- Delete specified Globals from Module.
+> Delete specified Globals from Module.
**-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.
+> 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.
+> 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.
+> 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.
+> 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.
+> 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.
**--keep-const-init**
- Preserve the values of constant globals.
+> Preserve the values of constant globals.
**--recursive**
- Recursively extract all called functions
+> Recursively extract all called functions
**-help**
- Print a summary of command line options.
+> 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.
+> 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).
+> Write output in LLVM intermediate language (instead of bitcode).
-EXIT STATUS
------------
+## EXIT STATUS
-If :program:`llvm-extract` succeeds, it will exit with 0. Otherwise, if an error
+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
---------
+## SEE ALSO
+
+{manpage}`llvm-reduce(1)`
-:manpage:`llvm-reduce(1)`
diff --git a/llvm/docs/CommandGuide/llvm-gsymutil.md b/llvm/docs/CommandGuide/llvm-gsymutil.md
index 31ac59fd43c91..1f3a30cb78579 100644
--- a/llvm/docs/CommandGuide/llvm-gsymutil.md
+++ b/llvm/docs/CommandGuide/llvm-gsymutil.md
@@ -1,17 +1,16 @@
-llvm-gsymutil - GSYM dumping, searching and creating utility
-============================================================
+# llvm-gsymutil - GSYM dumping, searching and creating utility
+```{eval-rst}
.. program:: llvm-gsymutil
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-gsymutil` [*options*] [*gsym-files...*]
+{program}`llvm-gsymutil` \[*options*\] \[*gsym-files...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-gsymutil` is a tool for dumping, searching, and creating GSYM
+{program}`llvm-gsymutil` is a tool for dumping, searching, and creating GSYM
files.
GSYM is a compact file format for debug information, optimized for fast
@@ -19,145 +18,142 @@ lookups. It can represent address ranges, line tables, and inline info.
The tool has three main modes of operation:
-#. **Dump Mode**: If one or more GSYM files are specified as arguments without
+1. **Dump Mode**: If one or more GSYM files are specified as arguments without
any lookup options, the tool dumps all the information contained in the
specified files.
-
-#. **Lookup Mode**: If a single GSYM file is specified along with one or more
- :option:`--address` options (or :option:`--addresses-from-stdin`), the tool
+2. **Lookup Mode**: If a single GSYM file is specified along with one or more
+ {option}`--address` options (or {option}`--addresses-from-stdin`), the tool
performs lookups for the specified addresses in the GSYM file.
-
-#. **Convert Mode**: If the :option:`--convert` option is specified, the tool
+3. **Convert Mode**: If the {option}`--convert` option is specified, the tool
converts the specified ELF or Mach-O file into GSYM format.
-OPTIONS
--------
-
-.. option:: --help, -h
-
- Display information on the various flags.
-
-.. option:: --version, -v
-
- Display the version of the tool.
-
-.. option:: --verbose
-
- Enable verbose logging and encoding details.
-
-.. option:: --convert=<file>
-
- Convert the specified file to the GSYM format. Supported files include ELF and
- Mach-O files. The tool will convert their debug info (DWARF) and symbol table.
-
-.. option:: --symtab-file=<file>
-
- Specify a separate file to read the symbol table from during GSYM conversion.
- Use when the symbol table and debug info are in separate files. Matching
- architectures are selected automatically for universal binaries.
-
-.. option:: --merged-functions
-
- * When used with :option:`--convert`, encodes merged function information for
- functions in debug info that have matching address ranges. Without this
- option, one function per unique address range will be emitted.
- * When used with :option:`--address` or :option:`--addresses-from-stdin`, all
- merged functions for a particular address will be displayed. Without this
- option, only one function will be displayed.
-
-.. option:: --dwarf-callsites
-
- Load call site info from DWARF, if available. This flag only has an impact
- when converting to gsym. When using llvm-gsymutil to lookup addresses,
- any callsite information will automatically be displayed without this flag.
-
-.. option:: --arch=<arch>
-
- Process debug information for the specified CPU architecture only.
- Architectures may be specified by name or by number. This option can be
- specified multiple times, once for each desired architecture.
-
-.. option:: --out-file=<file>, -o <file>
-
- Specify the path where the converted GSYM file will be saved. When not
- specified, a '.gsym' extension will be appended to the file name specified in
- the :option:`--convert` option.
-
-.. option:: --verify
-
- Verify the generated GSYM file against the information in the file that was
- converted.
-
-.. option:: --num-threads=<n>
-
- Specify the maximum number (n) of simultaneous threads to use when converting
- files to GSYM. Defaults to the number of cores on the current machine.
-
-.. option:: --segment-size=<size>
-
- Specify the size in bytes of the size the final GSYM file should be segmented
- into. This allows GSYM files to be split across multiple files.
-
-.. option:: --quiet
-
- Do not output warnings about the debug information.
-
-.. option:: --address=<addr>
-
- Lookup an address in a GSYM file. Can be specified multiple times.
-
-.. option:: --addresses-from-stdin
-
- Lookup addresses in a GSYM file that are read from stdin. Each input line is
- expected to be of the following format: ``<addr> <gsym-path>``.
-
-.. option:: --json-summary-file=<file>
-
- Output a categorized summary of errors into the JSON file specified.
-
-.. option:: --merged-functions-filter=<regex>
-
- When used with :option:`--address` or :option:`--addresses-from-stdin` and
- :option:`--merged-functions`, filters the merged functions output to only
- show functions matching any of the specified regex patterns. Can be
- specified multiple times.
-
-.. option:: --output-version=<version>
-
- Set the GSYM output version (1 or 2). Default: 1.
-
-.. option:: --statistics[=<format>]
-
- Print the size of each section in the input GSYM file(s). Format can be
- ``text`` (default), ``json``, or ``pretty-json``. Calling this option without
- arguments is equivalent to ``--statistics=text``.
-
-EXAMPLES
---------
+## OPTIONS
+
+:::{option} --help, -h
+Display information on the various flags.
+:::
+
+:::{option} --version, -v
+Display the version of the tool.
+:::
+
+:::{option} --verbose
+Enable verbose logging and encoding details.
+:::
+
+:::{option} --convert=<file>
+Convert the specified file to the GSYM format. Supported files include ELF and
+Mach-O files. The tool will convert their debug info (DWARF) and symbol table.
+:::
+
+:::{option} --symtab-file=<file>
+Specify a separate file to read the symbol table from during GSYM conversion.
+Use when the symbol table and debug info are in separate files. Matching
+architectures are selected automatically for universal binaries.
+:::
+
+:::{option} --merged-functions
+- When used with {option}`--convert`, encodes merged function information for
+ functions in debug info that have matching address ranges. Without this
+ option, one function per unique address range will be emitted.
+- When used with {option}`--address` or {option}`--addresses-from-stdin`, all
+ merged functions for a particular address will be displayed. Without this
+ option, only one function will be displayed.
+:::
+
+:::{option} --dwarf-callsites
+Load call site info from DWARF, if available. This flag only has an impact
+when converting to gsym. When using llvm-gsymutil to lookup addresses,
+any callsite information will automatically be displayed without this flag.
+:::
+
+:::{option} --arch=<arch>
+Process debug information for the specified CPU architecture only.
+Architectures may be specified by name or by number. This option can be
+specified multiple times, once for each desired architecture.
+:::
+
+:::{option} --out-file=<file>, -o <file>
+Specify the path where the converted GSYM file will be saved. When not
+specified, a '.gsym' extension will be appended to the file name specified in
+the {option}`--convert` option.
+:::
+
+:::{option} --verify
+Verify the generated GSYM file against the information in the file that was
+converted.
+:::
+
+:::{option} --num-threads=<n>
+Specify the maximum number (n) of simultaneous threads to use when converting
+files to GSYM. Defaults to the number of cores on the current machine.
+:::
+
+:::{option} --segment-size=<size>
+Specify the size in bytes of the size the final GSYM file should be segmented
+into. This allows GSYM files to be split across multiple files.
+:::
+
+:::{option} --quiet
+Do not output warnings about the debug information.
+:::
+
+:::{option} --address=<addr>
+Lookup an address in a GSYM file. Can be specified multiple times.
+:::
+
+:::{option} --addresses-from-stdin
+Lookup addresses in a GSYM file that are read from stdin. Each input line is
+expected to be of the following format: `<addr> <gsym-path>`.
+:::
+
+:::{option} --json-summary-file=<file>
+Output a categorized summary of errors into the JSON file specified.
+:::
+
+:::{option} --merged-functions-filter=<regex>
+When used with {option}`--address` or {option}`--addresses-from-stdin` and
+{option}`--merged-functions`, filters the merged functions output to only
+show functions matching any of the specified regex patterns. Can be
+specified multiple times.
+:::
+
+:::{option} --output-version=<version>
+Set the GSYM output version (1 or 2). Default: 1.
+:::
+
+:::{option} --statistics[=<format>]
+Print the size of each section in the input GSYM file(s). Format can be
+`text` (default), `json`, or `pretty-json`. Calling this option without
+arguments is equivalent to `--statistics=text`.
+:::
+
+## EXAMPLES
Convert an ELF file with debug info to GSYM format:
-.. code-block:: console
-
- $ llvm-gsymutil --convert=input.elf -o input.gsym
+```console
+$ llvm-gsymutil --convert=input.elf -o input.gsym
+```
Lookup addresses in a GSYM file:
-.. code-block:: console
-
- $ llvm-gsymutil --address=0x400391 --address=0x4004cd input.gsym
+```console
+$ llvm-gsymutil --address=0x400391 --address=0x4004cd input.gsym
+```
Lookup addresses from standard input:
-.. code-block:: console
-
- $ cat addrs.txt
- 0x400391 input.gsym
- 0x4004cd input.gsym
- $ cat addrs.txt | llvm-gsymutil --addresses-from-stdin
+```console
+$ cat addrs.txt
+0x400391 input.gsym
+0x4004cd input.gsym
+$ cat addrs.txt | llvm-gsymutil --addresses-from-stdin
+```
Dump the contents of a GSYM file:
-.. code-block:: console
+```console
+$ llvm-gsymutil input.gsym
+```
- $ llvm-gsymutil input.gsym
diff --git a/llvm/docs/CommandGuide/llvm-ifs.md b/llvm/docs/CommandGuide/llvm-ifs.md
index e3582b365b61d..a9a45c4556ad2 100644
--- a/llvm/docs/CommandGuide/llvm-ifs.md
+++ b/llvm/docs/CommandGuide/llvm-ifs.md
@@ -1,71 +1,63 @@
-llvm-ifs - shared object stubbing tool
-======================================
+# llvm-ifs - shared object stubbing tool
+```{eval-rst}
.. program:: llvm-ifs
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-ifs` [*options*] *inputs*
+{program}`llvm-ifs` \[*options*\] *inputs*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-ifs` is a tool that jointly produces human-readable text-based
+{program}`llvm-ifs` is a tool that jointly produces human-readable text-based
stubs (.ifs files) for shared objects and linkable shared object stubs
(.so files) from either ELF shared objects or text-based stubs. The text-based
stubs is useful for monitoring ABI changes of the shared object. The linkable
shared object stubs can be used to avoid unnecessary relinks when the ABI of
shared libraries does not change.
-
-IFS FORMATS
------------
+## IFS FORMATS
Here is an example of the text representation (IFS) of a shared object produced
-by the :program:`llvm-ifs`:
-
-::
-
- --- !ifs-v1
- IFSVersion: 3.0
- SoName: libtest.so /* Optional */
- Target: x86_64-unknown-linux-gnu /* Optional, format 1, same format as llvm target triple */
- Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
- NeededLibs:
- - libc.so.6
- Symbols:
- - { Name: sym0, Type: Notype }
- - { Name: sym1, Type: Object, Size: 0 }
- - { Name: sym2, Type: Func, Weak: false }
- - { Name: sym3, Type: TLS }
- - { Name: sym4, Type: Unknown, Warning: foo }
- ...
-
-* ``IFSVersion``: Version of the IFS file for reader compatibility.
-
-* ``SoName`` (optional): Name of the shared object file that is being stubbed.
-
-* ``Target`` (optional): The architecture, endianness and bitwise information of
+by the {program}`llvm-ifs`:
+
+```
+--- !ifs-v1
+IFSVersion: 3.0
+SoName: libtest.so /* Optional */
+Target: x86_64-unknown-linux-gnu /* Optional, format 1, same format as llvm target triple */
+Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
+NeededLibs:
+ - libc.so.6
+Symbols:
+ - { Name: sym0, Type: Notype }
+ - { Name: sym1, Type: Object, Size: 0 }
+ - { Name: sym2, Type: Func, Weak: false }
+ - { Name: sym3, Type: TLS }
+ - { Name: sym4, Type: Unknown, Warning: foo }
+...
+```
+
+- `IFSVersion`: Version of the IFS file for reader compatibility.
+
+- `SoName` (optional): Name of the shared object file that is being stubbed.
+
+- `Target` (optional): The architecture, endianness and bitwise information of
this shared object. It can be either in explicit format or in implicit LLVM
triple format. It can be optional and can be overridden from command line
options.
-* ``NeededLibs``: The list of the external shared objects that this library depends on.
-
-* ``Symbols``: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.
-
- + ``Name``: Symbol name.
-
- + ``Type``: Whether the symbol is an object, function, no-type, thread local storage, or unknown. Symbol types not explicitly supported are mapped as unknown to improve signal-to-noise ratio.
-
- + ``Size``: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
-
- + ``Undefined``: Whether or not the symbol is defined in this shared object file.
+- `NeededLibs`: The list of the external shared objects that this library depends on.
- + ``Weak``: Whether or not the symbol should be treated as weak.
+- `Symbols`: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.
- + ``Warning`` (optional): Warning text to output when this symbol is linked against.
+ - `Name`: Symbol name.
+ - `Type`: Whether the symbol is an object, function, no-type, thread local storage, or unknown. Symbol types not explicitly supported are mapped as unknown to improve signal-to-noise ratio.
+ - `Size`: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
+ - `Undefined`: Whether or not the symbol is defined in this shared object file.
+ - `Weak`: Whether or not the symbol should be treated as weak.
+ - `Warning` (optional): Warning text to output when this symbol is linked against.
This YAML based text format contains everything that is needed to generate a
linkable ELF shared object as well as an Apple TAPI format file. The ordering
@@ -73,136 +65,129 @@ of symbols is sorted, so these files can be easily compared using diff tools.
If the content of the file changes, it indicates a potentially ABI breaking
change.
-
-ELF STUB FORMAT
----------------
+## ELF STUB FORMAT
A minimum ELF file that can be used by linker should have following sections properly populated:
-* ELF header.
-
-* Section headers.
-
-* Dynamic symbol table (``.dynsym`` section).
-
-* Dynamic string table (``.dynstr`` section).
-
-* Dynamic table (``.dynamic`` section).
+- ELF header.
- + ``DT_SYMTAB`` entry.
+- Section headers.
- + ``DT_STRTAB`` entry.
+- Dynamic symbol table (`.dynsym` section).
- + ``DT_STRSZ`` entry.
+- Dynamic string table (`.dynstr` section).
- + ``DT_NEEDED`` entries. (optional)
+- Dynamic table (`.dynamic` section).
- + ``DT_SONAME`` entry. (optional)
+ - `DT_SYMTAB` entry.
+ - `DT_STRTAB` entry.
+ - `DT_STRSZ` entry.
+ - `DT_NEEDED` entries. (optional)
+ - `DT_SONAME` entry. (optional)
-* Section header string table (``.shstrtab`` section)
+- Section header string table (`.shstrtab` section)
This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers.
Linkers like LLD work fine with such a minimum ELF file without errors.
-OPTIONS
--------
-
-.. option:: --input-format=[IFS|ELF|OtherObjectFileFormats]
-
- Specify input file format. Currently, only text IFS files and ELF shared
- object files are supported. This flag is optional as the input format can be
- inferred.
-
-.. option:: --output-elf=<output-filename>
-
- Specify the output file for ELF shared object stub.
-
-.. option:: --output-ifs=<output-filename>
-
- Specify the output file for text IFS.
-
-.. option:: --output-tbd=<output-filename>
-
- Specify the output file for Apple TAPI tbd.
-
-.. option:: --arch=[x86_64|AArch64|...]
-
- This flag is optional and it should only be used when reading an IFS file
- which does not define the ``Arch`` (architecture). This flag defines the
- architecture of the output file, and can be any string supported by ELF
- 'e_machine' field. If the value is conflicting with the IFS file, an error
- will be reported and the program will stop.
-
-.. option:: --endianness=[little|big]
-
- This flag is optional and it should only be used when reading an IFS file
- which does not define the ``Endianness``. This flag defines the endianness of
- the output file. If the value is conflicting with the IFS file, an error
- will be reported and the program will stop.
-
-.. option:: --bitwidth=[32|64]
-
- This flag is optional and it should only be used when reading an IFS file
- which does not define the ``BitWidth``. This flag defines the bit width of the
- output file. If the value is conflicting with the input IFS file, an error
- will be reported and the program will stop.
-
-.. option:: --target=<target triple>
-
- This flag is optional and should only be used when reading an IFS file
- which does not define any target information. This flag defines architecture,
- endianness and bit width of the output file using llvm target triple.
- This flag cannot be used simultaneously with other target related flags.
-
-.. option:: --hint-ifs-target=<target triple>
-
- This flag is optional and should only be used when reading an ELF shared
- object and generating an IFS file. by default, llvm-ifs will use '``Arch``,
- ``Endianness`` and ``BitWidth``' fields to reflect the target information from the
- input object file. Using this flag will tell llvm-ifs the expected target
- triple in the output IFS file. If the value matches the target information
- from the object file, this value will be used in the 'Target:' filed in the
- generated IFS. If it conflicts with the input object file, an error will be
- reported and the program will stop.
-
-.. option:: --hint-ifs-target
-
- This flag is optional and should only be used when outputting an IFS file.
- This flag strips the ``Arch`` field from the IFS file so it can be overridden
- later.
-
-.. option:: --strip-ifs-endianness
-
- This flag is optional and should only be used when outputting an IFS file.
- This flag strips the ``Endianness`` field from the IFS file so it can be
- overridden later.
-
-.. option:: --strip-ifs-bitwidth
-
- This flag is optional and should only be used when outputting an IFS file.
- This flag strips the ``BitWidth`` field from the IFS file so it can be overridden
- later.
-
-.. option:: --strip-ifs-target
-
- This flag is optional and should only be used when outputting an IFS file.
- This flag strips the ``Target`` field from the IFS file so it can be overridden
- later.
-
-.. option:: --write-if-changed
-
- When this flag is set, llvm-ifs will only write the output file if it does not
- already exist or the content will be different from the existing file.
-
-.. option:: --strip-size
-
- When this flag is set, llvm-ifs will remove the size field from the output ifs
- file. This is useful for shared objects that only intend to be linked against
- position independent code which doesn't need copy relocations, or where the size
- of an object is not a useful part of the abi to track.
-
-EXIT STATUS
------------
-
-If :program:`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
+## OPTIONS
+
+:::{option} --input-format=[IFS|ELF|OtherObjectFileFormats]
+Specify input file format. Currently, only text IFS files and ELF shared
+object files are supported. This flag is optional as the input format can be
+inferred.
+:::
+
+:::{option} --output-elf=<output-filename>
+Specify the output file for ELF shared object stub.
+:::
+
+:::{option} --output-ifs=<output-filename>
+Specify the output file for text IFS.
+:::
+
+:::{option} --output-tbd=<output-filename>
+Specify the output file for Apple TAPI tbd.
+:::
+
+:::{option} --arch=[x86_64|AArch64|...]
+This flag is optional and it should only be used when reading an IFS file
+which does not define the `Arch` (architecture). This flag defines the
+architecture of the output file, and can be any string supported by ELF
+'e_machine' field. If the value is conflicting with the IFS file, an error
+will be reported and the program will stop.
+:::
+
+:::{option} --endianness=[little|big]
+This flag is optional and it should only be used when reading an IFS file
+which does not define the `Endianness`. This flag defines the endianness of
+the output file. If the value is conflicting with the IFS file, an error
+will be reported and the program will stop.
+:::
+
+:::{option} --bitwidth=[32|64]
+This flag is optional and it should only be used when reading an IFS file
+which does not define the `BitWidth`. This flag defines the bit width of the
+output file. If the value is conflicting with the input IFS file, an error
+will be reported and the program will stop.
+:::
+
+:::{option} --target=<target triple>
+This flag is optional and should only be used when reading an IFS file
+which does not define any target information. This flag defines architecture,
+endianness and bit width of the output file using llvm target triple.
+This flag cannot be used simultaneously with other target related flags.
+:::
+
+:::{option} --hint-ifs-target=<target triple>
+This flag is optional and should only be used when reading an ELF shared
+object and generating an IFS file. by default, llvm-ifs will use '`Arch`,
+`Endianness` and `BitWidth`' fields to reflect the target information from the
+input object file. Using this flag will tell llvm-ifs the expected target
+triple in the output IFS file. If the value matches the target information
+from the object file, this value will be used in the 'Target:' filed in the
+generated IFS. If it conflicts with the input object file, an error will be
+reported and the program will stop.
+:::
+
+:::{option} --hint-ifs-target
+This flag is optional and should only be used when outputting an IFS file.
+This flag strips the `Arch` field from the IFS file so it can be overridden
+later.
+:::
+
+:::{option} --strip-ifs-endianness
+This flag is optional and should only be used when outputting an IFS file.
+This flag strips the `Endianness` field from the IFS file so it can be
+overridden later.
+:::
+
+:::{option} --strip-ifs-bitwidth
+This flag is optional and should only be used when outputting an IFS file.
+This flag strips the `BitWidth` field from the IFS file so it can be overridden
+later.
+:::
+
+:::{option} --strip-ifs-target
+This flag is optional and should only be used when outputting an IFS file.
+This flag strips the `Target` field from the IFS file so it can be overridden
+later.
+:::
+
+:::{option} --write-if-changed
+When this flag is set, llvm-ifs will only write the output file if it does not
+already exist or the content will be different from the existing file.
+:::
+
+:::{option} --strip-size
+When this flag is set, llvm-ifs will remove the size field from the output ifs
+file. This is useful for shared objects that only intend to be linked against
+position independent code which doesn't need copy relocations, or where the size
+of an object is not a useful part of the abi to track.
+:::
+
+## EXIT STATUS
+
+If {program}`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
error occurs, it will exit with a non-zero value.
+
diff --git a/llvm/docs/CommandGuide/llvm-install-name-tool.md b/llvm/docs/CommandGuide/llvm-install-name-tool.md
index 0997eaab18a93..29a742376dc8f 100644
--- a/llvm/docs/CommandGuide/llvm-install-name-tool.md
+++ b/llvm/docs/CommandGuide/llvm-install-name-tool.md
@@ -1,88 +1,85 @@
-llvm-install-name-tool - LLVM tool for manipulating install-names and rpaths
-============================================================================
+# llvm-install-name-tool - LLVM tool for manipulating install-names and rpaths
+```{eval-rst}
.. program:: llvm-install-name-tool
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-install-name-tool` [*options*] *input*
+{program}`llvm-install-name-tool` \[*options*\] *input*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-install-name-tool` is a tool to manipulate dynamic shared library
+{program}`llvm-install-name-tool` is a tool to manipulate dynamic shared library
install names and rpaths listed in a Mach-O binary.
For most scenarios, it works as a drop-in replacement for Apple's
-:program:`install_name_tool`.
+{program}`install_name_tool`.
+
+## OPTIONS
-OPTIONS
---------
At least one of the following options are required, and some options can be
-combined with other options. Options :option:`-add_rpath`, :option:`-delete_rpath`,
-and :option:`-rpath` can be combined in an invocation only if they do not share
+combined with other options. Options {option}`-add_rpath`, {option}`-delete_rpath`,
+and {option}`-rpath` can be combined in an invocation only if they do not share
the same `<rpath>` value.
-.. option:: -add_rpath <rpath>
-
- Add an rpath named ``<rpath>`` to the specified binary. Can be specified multiple
- times to add multiple rpaths. Throws an error if ``<rpath>`` is already listed in
- the binary.
-
-.. option:: -change <old_install_name> <new_install_name>
-
- Change an install name ``<old_install_name>`` to ``<new_install_name>`` in the
- specified binary. Can be specified multiple times to change multiple dependent shared
- library install names. Option is ignored if ``<old_install_name>`` is not listed
- in the specified binary.
-
-.. option:: -delete_rpath <rpath>
-
- Delete an rpath named ``<rpath>`` from the specified binary. Can be specified multiple
- times to delete multiple rpaths. Throws an error if ``<rpath>`` is not listed in
- the binary.
-
-.. option:: -delete_all_rpaths
-
- Deletes all rpaths from the binary.
-
-.. option:: --help, -h
-
- Print a summary of command line options.
-
-.. option:: -id <name>
-
- Change shared library's identification name under LC_ID_DYLIB to ``<name>`` in the
- specified binary. If specified multiple times, only the last :option:`-id` option is
- selected. Option is ignored if the specified Mach-O binary is not a dynamic shared library.
-
-.. option:: -o <file>, --output <file>
-
- Write the modified binary to ``<file>`` instead of updating the input file in place.
-
-.. option:: -rpath <old_rpath> <new_rpath>
-
- Change an rpath named ``<old_rpath>`` to ``<new_rpath>`` in the specified binary. Can be specified
- multiple times to change multiple rpaths. Throws an error if ``<old_rpath>`` is not listed
- in the binary or ``<new_rpath>`` is already listed in the binary.
-
-.. option:: --version, -V
-
- Display the version of the :program:`llvm-install-name-tool` executable.
-
-EXIT STATUS
------------
-
-:program:`llvm-install-name-tool` exits with a non-zero exit code if there is an error.
+:::{option} -add_rpath <rpath>
+Add an rpath named `<rpath>` to the specified binary. Can be specified multiple
+times to add multiple rpaths. Throws an error if `<rpath>` is already listed in
+the binary.
+:::
+
+:::{option} -change <old_install_name> <new_install_name>
+Change an install name `<old_install_name>` to `<new_install_name>` in the
+specified binary. Can be specified multiple times to change multiple dependent shared
+library install names. Option is ignored if `<old_install_name>` is not listed
+in the specified binary.
+:::
+
+:::{option} -delete_rpath <rpath>
+Delete an rpath named `<rpath>` from the specified binary. Can be specified multiple
+times to delete multiple rpaths. Throws an error if `<rpath>` is not listed in
+the binary.
+:::
+
+:::{option} -delete_all_rpaths
+Deletes all rpaths from the binary.
+:::
+
+:::{option} --help, -h
+Print a summary of command line options.
+:::
+
+:::{option} -id <name>
+Change shared library's identification name under LC_ID_DYLIB to `<name>` in the
+specified binary. If specified multiple times, only the last {option}`-id` option is
+selected. Option is ignored if the specified Mach-O binary is not a dynamic shared library.
+:::
+
+:::{option} -o <file>, --output <file>
+Write the modified binary to `<file>` instead of updating the input file in place.
+:::
+
+:::{option} -rpath <old_rpath> <new_rpath>
+Change an rpath named `<old_rpath>` to `<new_rpath>` in the specified binary. Can be specified
+multiple times to change multiple rpaths. Throws an error if `<old_rpath>` is not listed
+in the binary or `<new_rpath>` is already listed in the binary.
+:::
+
+:::{option} --version, -V
+Display the version of the {program}`llvm-install-name-tool` executable.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-install-name-tool` exits with a non-zero exit code if there is an error.
Otherwise, it exits with code 0.
-BUGS
-----
+## BUGS
+
+To report bugs, please visit \<<https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-objcopy(1)`
-:manpage:`llvm-objcopy(1)`
diff --git a/llvm/docs/CommandGuide/llvm-ir2vec.md b/llvm/docs/CommandGuide/llvm-ir2vec.md
index 6014df941147e..323d1d77273c7 100644
--- a/llvm/docs/CommandGuide/llvm-ir2vec.md
+++ b/llvm/docs/CommandGuide/llvm-ir2vec.md
@@ -1,54 +1,50 @@
-llvm-ir2vec - IR2Vec and MIR2Vec Embedding Generation Tool
-==========================================================
+# llvm-ir2vec - IR2Vec and MIR2Vec Embedding Generation Tool
+```{eval-rst}
.. program:: llvm-ir2vec
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-ir2vec` [*subcommand*] [*options*]
+{program}`llvm-ir2vec` \[*subcommand*\] \[*options*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-ir2vec` is a standalone command-line tool for IR2Vec and MIR2Vec.
-It generates embeddings for both LLVM IR and Machine IR (MIR) and supports
-triplet generation for vocabulary training.
+{program}`llvm-ir2vec` is a standalone command-line tool for IR2Vec and MIR2Vec.
+It generates embeddings for both LLVM IR and Machine IR (MIR) and supports
+triplet generation for vocabulary training.
The tool provides three main subcommands:
1. **triplets**: Generates numeric triplets in train2id format for vocabulary
training from LLVM IR.
-
-2. **entities**: Generates entity mapping files (entity2id.txt) for vocabulary
+2. **entities**: Generates entity mapping files (entity2id.txt) for vocabulary
training.
-
3. **embeddings**: Generates IR2Vec or MIR2Vec embeddings using a trained vocabulary
at different granularity levels (instruction, basic block, or function).
The tool supports two operation modes:
-* **LLVM IR mode** (``--mode=llvm``): Process LLVM IR bitcode files and generate
+- **LLVM IR mode** (`--mode=llvm`): Process LLVM IR bitcode files and generate
IR2Vec embeddings
-* **Machine IR mode** (``--mode=mir``): Process Machine IR (.mir) files and generate
+- **Machine IR mode** (`--mode=mir`): Process Machine IR (.mir) files and generate
MIR2Vec embeddings
The tool is designed to facilitate machine learning applications that work with
-LLVM IR or Machine IR by converting them into numerical representations that can
-be used by ML models. The `triplets` subcommand generates numeric IDs directly
+LLVM IR or Machine IR by converting them into numerical representations that can
+be used by ML models. The `triplets` subcommand generates numeric IDs directly
instead of string triplets, streamlining the training data preparation workflow.
-.. note::
+:::{note}
+For information about using IR2Vec and MIR2Vec programmatically within LLVM
+passes and the C++ API, see the [IR2Vec Embeddings](https://llvm.org/docs/MLGO.html#ir2vec-embeddings)
+section in the MLGO documentation.
+:::
- For information about using IR2Vec and MIR2Vec programmatically within LLVM
- passes and the C++ API, see the `IR2Vec Embeddings <https://llvm.org/docs/MLGO.html#ir2vec-embeddings>`_
- section in the MLGO documentation.
-
-OPERATION MODES
----------------
+## OPERATION MODES
The tool operates in two modes: **LLVM IR mode** and **Machine IR mode**. The mode
-is selected using the ``--mode`` option (default: ``llvm``).
+is selected using the `--mode` option (default: `llvm`).
Triplet Generation and Entity Mapping Modes are used for preparing
vocabulary and training data for knowledge graph embeddings. The Embedding Mode
@@ -58,17 +54,16 @@ The Seed Embedding Vocabulary of IR2Vec is trained on a large corpus of LLVM IR
by modeling the relationships between opcodes, types, and operands as a knowledge
graph. For this purpose, Triplet Generation and Entity Mapping Modes generate
triplets and entity mappings in the standard format used for knowledge graph
-embedding training (see
-<https://github.com/thunlp/OpenKE/tree/OpenKE-PyTorch?tab=readme-ov-file#data-format>
+embedding training (see
+\<<https://github.com/thunlp/OpenKE/tree/OpenKE-PyTorch?tab=readme-ov-file#data-format>>
for details).
See `llvm/utils/mlgo-utils/IR2Vec/generateTriplets.py` for more details on how
these two modes are used to generate the triplets and entity mappings.
-Triplet Generation
-~~~~~~~~~~~~~~~~~~
+### Triplet Generation
-With the `triplets` subcommand, :program:`llvm-ir2vec` analyzes LLVM IR or Machine IR
+With the `triplets` subcommand, {program}`llvm-ir2vec` analyzes LLVM IR or Machine IR
and extracts numeric triplets consisting of opcode IDs and operand IDs. These triplets
are generated in the standard format used for knowledge graph embedding training.
The tool outputs numeric IDs directly using the vocabulary mapping infrastructure,
@@ -76,20 +71,19 @@ eliminating the need for string-to-ID preprocessing.
Usage for LLVM IR:
-.. code-block:: bash
-
- llvm-ir2vec triplets --mode=llvm input.bc -o triplets_train2id.txt
+```bash
+llvm-ir2vec triplets --mode=llvm input.bc -o triplets_train2id.txt
+```
Usage for Machine IR:
-.. code-block:: bash
+```bash
+llvm-ir2vec triplets --mode=mir input.mir -o triplets_train2id.txt
+```
- llvm-ir2vec triplets --mode=mir input.mir -o triplets_train2id.txt
+### Entity Mapping Generation
-Entity Mapping Generation
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With the `entities` subcommand, :program:`llvm-ir2vec` generates the entity mappings
+With the `entities` subcommand, {program}`llvm-ir2vec` generates the entity mappings
supported by IR2Vec or MIR2Vec in the standard format used for knowledge graph embedding
training. This subcommand outputs all supported entities with their corresponding numeric IDs.
@@ -98,192 +92,187 @@ machine opcodes, common operands, and register classes (both physical and virtua
Usage for LLVM IR:
-.. code-block:: bash
-
- llvm-ir2vec entities --mode=llvm -o entity2id.txt
+```bash
+llvm-ir2vec entities --mode=llvm -o entity2id.txt
+```
Usage for Machine IR:
-.. code-block:: bash
-
- llvm-ir2vec entities --mode=mir input.mir -o entity2id.txt
-
-.. note::
+```bash
+llvm-ir2vec entities --mode=mir input.mir -o entity2id.txt
+```
- For LLVM IR mode, the entity mapping is target-independent and does not require an input file.
- For Machine IR mode, an input .mir file is required to determine the target architecture,
- as entity mappings vary by target (different architectures have different instruction sets
- and register classes).
+:::{note}
+For LLVM IR mode, the entity mapping is target-independent and does not require an input file.
+For Machine IR mode, an input .mir file is required to determine the target architecture,
+as entity mappings vary by target (different architectures have different instruction sets
+and register classes).
+:::
-Embedding Generation
-~~~~~~~~~~~~~~~~~~~~
+### Embedding Generation
-With the `embeddings` subcommand, :program:`llvm-ir2vec` uses a pre-trained vocabulary to
+With the `embeddings` subcommand, {program}`llvm-ir2vec` uses a pre-trained vocabulary to
generate numerical embeddings for LLVM IR or Machine IR at different levels of granularity.
Example Usage for LLVM IR:
-.. code-block:: bash
-
- llvm-ir2vec embeddings --mode=llvm --ir2vec-vocab-path=vocab.json --ir2vec-kind=symbolic --level=func input.bc -o embeddings.txt
+```bash
+llvm-ir2vec embeddings --mode=llvm --ir2vec-vocab-path=vocab.json --ir2vec-kind=symbolic --level=func input.bc -o embeddings.txt
+```
Example Usage for Machine IR:
-.. code-block:: bash
-
- llvm-ir2vec embeddings --mode=mir --mir2vec-vocab-path=vocab.json --level=func input.mir -o embeddings.txt
+```bash
+llvm-ir2vec embeddings --mode=mir --mir2vec-vocab-path=vocab.json --level=func input.mir -o embeddings.txt
+```
-OPTIONS
--------
+## OPTIONS
Common options (applicable to both LLVM IR and Machine IR modes):
-.. option:: --mode=<mode>
-
- Specify the operation mode. Valid values are:
-
- * ``llvm`` - Process LLVM IR bitcode files (default)
- * ``mir`` - Process Machine IR (.mir) files
+:::{option} --mode=<mode>
+Specify the operation mode. Valid values are:
-.. option:: -o <filename>
+- `llvm` - Process LLVM IR bitcode files (default)
+- `mir` - Process Machine IR (.mir) files
+:::
- Specify the output filename. Use ``-`` to write to standard output (default).
+:::{option} -o <filename>
+Specify the output filename. Use `-` to write to standard output (default).
+:::
-.. option:: --help
-
- Print a summary of command line options.
+:::{option} --help
+Print a summary of command line options.
+:::
Subcommand-specific options:
**embeddings** subcommand:
-.. option:: <input-file>
-
- The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process.
- This positional argument is required for the `embeddings` subcommand.
-
-.. option:: --level=<level>
-
- Specify the embedding generation level. Valid values are:
+:::{option} <input-file>
+The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process.
+This positional argument is required for the `embeddings` subcommand.
+:::
- * ``inst`` - Generate instruction-level embeddings
- * ``bb`` - Generate basic block-level embeddings
- * ``func`` - Generate function-level embeddings (default)
+:::{option} --level=<level>
+Specify the embedding generation level. Valid values are:
-.. option:: --function=<name>
+- `inst` - Generate instruction-level embeddings
+- `bb` - Generate basic block-level embeddings
+- `func` - Generate function-level embeddings (default)
+:::
- Process only the specified function instead of all functions in the module.
+:::{option} --function=<name>
+Process only the specified function instead of all functions in the module.
+:::
-**IR2Vec-specific options** (for ``--mode=llvm``):
+**IR2Vec-specific options** (for `--mode=llvm`):
-.. option:: --ir2vec-kind=<kind>
+:::{option} --ir2vec-kind=<kind>
+Specify the kind of IR2Vec embeddings to generate. Valid values are:
- Specify the kind of IR2Vec embeddings to generate. Valid values are:
+- `symbolic` - Generate symbolic embeddings (default)
+- `flow-aware` - Generate flow-aware embeddings
- * ``symbolic`` - Generate symbolic embeddings (default)
- * ``flow-aware`` - Generate flow-aware embeddings
+Flow-aware embeddings consider control flow relationships between instructions,
+while symbolic embeddings focus on the symbolic representation of instructions.
+:::
- Flow-aware embeddings consider control flow relationships between instructions,
- while symbolic embeddings focus on the symbolic representation of instructions.
+:::{option} --ir2vec-vocab-path=<path>
+Specify the path to the IR2Vec vocabulary file (required for LLVM IR embedding
+generation). The vocabulary file should be in JSON format and contain the trained
+vocabulary for embedding generation. See `llvm/lib/Analysis/models`
+for pre-trained vocabulary files.
+:::
-.. option:: --ir2vec-vocab-path=<path>
+:::{option} --ir2vec-opc-weight=<weight>
+Specify the weight for opcode embeddings (default: 1.0). This controls
+the relative importance of instruction opcodes in the final embedding.
+:::
- Specify the path to the IR2Vec vocabulary file (required for LLVM IR embedding
- generation). The vocabulary file should be in JSON format and contain the trained
- vocabulary for embedding generation. See `llvm/lib/Analysis/models`
- for pre-trained vocabulary files.
+:::{option} --ir2vec-type-weight=<weight>
+Specify the weight for type embeddings (default: 0.5). This controls
+the relative importance of type information in the final embedding.
+:::
-.. option:: --ir2vec-opc-weight=<weight>
+:::{option} --ir2vec-arg-weight=<weight>
+Specify the weight for argument embeddings (default: 0.2). This controls
+the relative importance of operand information in the final embedding.
+:::
- Specify the weight for opcode embeddings (default: 1.0). This controls
- the relative importance of instruction opcodes in the final embedding.
+**MIR2Vec-specific options** (for `--mode=mir`):
-.. option:: --ir2vec-type-weight=<weight>
+:::{option} --mir2vec-vocab-path=<path>
+Specify the path to the MIR2Vec vocabulary file (required for Machine IR
+embedding generation). The vocabulary file should be in JSON format and
+contain the trained vocabulary for embedding generation.
+:::
- Specify the weight for type embeddings (default: 0.5). This controls
- the relative importance of type information in the final embedding.
+:::{option} --mir2vec-kind=<kind>
+Specify the kind of MIR2Vec embeddings to generate. Valid values are:
-.. option:: --ir2vec-arg-weight=<weight>
+- `symbolic` - Generate symbolic embeddings (default)
+:::
- Specify the weight for argument embeddings (default: 0.2). This controls
- the relative importance of operand information in the final embedding.
+:::{option} --mir2vec-opc-weight=<weight>
+Specify the weight for machine opcode embeddings (default: 1.0). This controls
+the relative importance of machine instruction opcodes in the final embedding.
+:::
-**MIR2Vec-specific options** (for ``--mode=mir``):
-
-.. option:: --mir2vec-vocab-path=<path>
-
- Specify the path to the MIR2Vec vocabulary file (required for Machine IR
- embedding generation). The vocabulary file should be in JSON format and
- contain the trained vocabulary for embedding generation.
-
-.. option:: --mir2vec-kind=<kind>
-
- Specify the kind of MIR2Vec embeddings to generate. Valid values are:
-
- * ``symbolic`` - Generate symbolic embeddings (default)
-
-.. option:: --mir2vec-opc-weight=<weight>
-
- Specify the weight for machine opcode embeddings (default: 1.0). This controls
- the relative importance of machine instruction opcodes in the final embedding.
-
-.. option:: --mir2vec-common-operand-weight=<weight>
-
- Specify the weight for common operand embeddings (default: 1.0). This controls
- the relative importance of common operand types in the final embedding.
-
-.. option:: --mir2vec-reg-operand-weight=<weight>
-
- Specify the weight for register operand embeddings (default: 1.0). This controls
- the relative importance of register operands in the final embedding.
+:::{option} --mir2vec-common-operand-weight=<weight>
+Specify the weight for common operand embeddings (default: 1.0). This controls
+the relative importance of common operand types in the final embedding.
+:::
+:::{option} --mir2vec-reg-operand-weight=<weight>
+Specify the weight for register operand embeddings (default: 1.0). This controls
+the relative importance of register operands in the final embedding.
+:::
**triplets** subcommand:
-.. option:: <input-file>
-
- The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process.
- This positional argument is required for the `triplets` subcommand.
+:::{option} <input-file>
+The input LLVM IR/bitcode file (.ll/.bc) or Machine IR file (.mir) to process.
+This positional argument is required for the `triplets` subcommand.
+:::
**entities** subcommand:
-.. option:: <input-file>
+:::{option} <input-file>
+The input Machine IR file (.mir) to process. This positional argument is required
+for the `entities` subcommand when using `--mode=mir`, as the entity mappings
+are target-specific. For `--mode=llvm`, no input file is required as IR2Vec
+entity mappings are target-independent.
+:::
- The input Machine IR file (.mir) to process. This positional argument is required
- for the `entities` subcommand when using ``--mode=mir``, as the entity mappings
- are target-specific. For ``--mode=llvm``, no input file is required as IR2Vec
- entity mappings are target-independent.
+## OUTPUT FORMAT
-OUTPUT FORMAT
--------------
-
-Triplet Mode Output
-~~~~~~~~~~~~~~~~~~~
+### Triplet Mode Output
In triplet mode, the output consists of numeric triplets in train2id format with
metadata headers. The format includes:
-.. code-block:: text
-
- MAX_RELATION=<max_relation_count>
- <head_entity_id> <tail_entity_id> <relation_id>
- <head_entity_id> <tail_entity_id> <relation_id>
- ...
+```text
+MAX_RELATION=<max_relation_count>
+<head_entity_id> <tail_entity_id> <relation_id>
+<head_entity_id> <tail_entity_id> <relation_id>
+...
+```
Each line after the metadata header represents one instruction relationship,
-with numeric IDs for head entity, tail entity, and relation type. The metadata
+with numeric IDs for head entity, tail entity, and relation type. The metadata
header (MAX_RELATION) indicates the maximum relation ID used.
**Relation Types:**
For LLVM IR (IR2Vec):
- * **0** = Type relationship (instruction to its type)
- * **1** = Next relationship (sequential instructions)
- * **2+** = Argument relationships (Arg0, Arg1, Arg2, ...)
+: - **0** = Type relationship (instruction to its type)
+ - **1** = Next relationship (sequential instructions)
+ - **2+** = Argument relationships (Arg0, Arg1, Arg2, ...)
For Machine IR (MIR2Vec):
- * **0** = Next relationship (sequential instructions)
- * **1+** = Argument relationships (Arg0, Arg1, Arg2, ...)
+: - **0** = Next relationship (sequential instructions)
+ - **1+** = Argument relationships (Arg0, Arg1, Arg2, ...)
**Entity IDs:**
@@ -292,58 +281,55 @@ For LLVM IR: Entity IDs represent opcodes, types, and operands as defined by the
For Machine IR: Entity IDs represent machine opcodes, common operands (immediate, frame index, etc.),
physical register classes, and virtual register classes as defined by the MIR2Vec vocabulary. The entity layout is target-specific.
-Entity Mode Output
-~~~~~~~~~~~~~~~~~~
+### Entity Mode Output
In entity mode, the output consists of entity mappings in the format:
-.. code-block:: text
-
- <total_entities>
- <entity_string> <numeric_id>
- <entity_string> <numeric_id>
- ...
+```text
+<total_entities>
+<entity_string> <numeric_id>
+<entity_string> <numeric_id>
+...
+```
The first line contains the total number of entities, followed by one entity
mapping per line with tab-separated entity string and numeric ID.
-For LLVM IR, entities include instruction opcodes (e.g., "Add", "Ret"), types
+For LLVM IR, entities include instruction opcodes (e.g., "Add", "Ret"), types
(e.g., "INT", "PTR"), and operand kinds.
-For Machine IR, entities include machine opcodes (e.g., "COPY", "ADD"),
-common operands (e.g., "Immediate", "FrameIndex"), physical register classes
+For Machine IR, entities include machine opcodes (e.g., "COPY", "ADD"),
+common operands (e.g., "Immediate", "FrameIndex"), physical register classes
(e.g., "PhyReg_GR32"), and virtual register classes (e.g., "VirtReg_GR32").
-Embedding Mode Output
-~~~~~~~~~~~~~~~~~~~~~
+### Embedding Mode Output
In embedding mode, the output format depends on the specified level:
-* **Function Level**: One embedding vector per function
-* **Basic Block Level**: One embedding vector per basic block, grouped by function
-* **Instruction Level**: One embedding vector per instruction, grouped by basic block and function
+- **Function Level**: One embedding vector per function
+- **Basic Block Level**: One embedding vector per basic block, grouped by function
+- **Instruction Level**: One embedding vector per instruction, grouped by basic block and function
Each embedding is represented as a floating point vector.
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-ir2vec` returns 0 on success, and a non-zero value on failure.
+{program}`llvm-ir2vec` returns 0 on success, and a non-zero value on failure.
Common failure cases include:
-* Invalid or missing input file
-* Missing or invalid vocabulary file (in embedding mode)
-* Specified function not found in the module
-* Invalid command line options
+- Invalid or missing input file
+- Missing or invalid vocabulary file (in embedding mode)
+- Specified function not found in the module
+- Invalid command line options
-SEE ALSO
---------
+## SEE ALSO
-:doc:`../MLGO`
+{doc}`../MLGO`
For more information about the IR2Vec algorithm and approach, see:
-`IR2Vec: LLVM IR Based Scalable Program Embeddings <https://doi.org/10.1145/3418463>`_.
+[IR2Vec: LLVM IR Based Scalable Program Embeddings](https://doi.org/10.1145/3418463).
For more information about the MIR2Vec algorithm and approach, see:
-`RL4ReAl: Reinforcement Learning for Register Allocation <https://doi.org/10.1145/3578360.3580273>`_.
+[RL4ReAl: Reinforcement Learning for Register Allocation](https://doi.org/10.1145/3578360.3580273).
+
diff --git a/llvm/docs/CommandGuide/llvm-lib.md b/llvm/docs/CommandGuide/llvm-lib.md
index 1081fe81f7a80..1d50c8bc66e73 100644
--- a/llvm/docs/CommandGuide/llvm-lib.md
+++ b/llvm/docs/CommandGuide/llvm-lib.md
@@ -1,29 +1,28 @@
-llvm-lib - LLVM lib.exe compatible library tool
-===============================================
+# llvm-lib - LLVM lib.exe compatible library tool
+```{eval-rst}
.. program:: llvm-lib
+```
-SYNOPSIS
---------
+## SYNOPSIS
-**llvm-lib** [/libpath:<path>] [/out:<output>] [/llvmlibthin]
+**llvm-lib** [/libpath:\<path>] [/out:\<output>] [/llvmlibthin]
[/ignore] [/machine] [/nologo] [files...]
-DESCRIPTION
------------
+## 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
+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.
+- Bitcode files in symbol tables.
**llvm-lib** includes symbols from both bitcode files and regular
object files in the symbol table.
-
-* Creating thin archives.
+- 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).
+
More information about the llvm-branch-commits
mailing list