[llvm-branch-commits] [llvm] [docs] Convert remaining CommandGuide docs to Markdown (PR #220097)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Tue Sep 1 09:51:46 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/220097
>From 07177e92b26417c351fee9a8a5f787d114af74cc Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Mon, 31 Aug 2026 18:52:39 +0000
Subject: [PATCH 1/2] [docs] Convert remaining CommandGuide docs with rst2myst
---
llvm/docs/CommandGuide/llvm-libtool-darwin.md | 135 +-
llvm/docs/CommandGuide/llvm-link.md | 216 ++-
llvm/docs/CommandGuide/llvm-lipo.md | 106 +-
llvm/docs/CommandGuide/llvm-locstats.md | 154 +-
llvm/docs/CommandGuide/llvm-mc.md | 295 ++--
llvm/docs/CommandGuide/llvm-mca.md | 1317 ++++++++---------
llvm/docs/CommandGuide/llvm-nm.md | 447 +++---
llvm/docs/CommandGuide/llvm-objcopy.md | 1167 ++++++++-------
llvm/docs/CommandGuide/llvm-objdump.md | 925 ++++++------
llvm/docs/CommandGuide/llvm-offload-binary.md | 225 +--
llvm/docs/CommandGuide/llvm-opt-report.md | 154 +-
llvm/docs/CommandGuide/llvm-otool.md | 216 ++-
llvm/docs/CommandGuide/llvm-pdbutil.md | 988 ++++++-------
llvm/docs/CommandGuide/llvm-profdata.md | 799 +++++-----
llvm/docs/CommandGuide/llvm-profgen.md | 184 ++-
llvm/docs/CommandGuide/llvm-ranlib.md | 25 +-
llvm/docs/CommandGuide/llvm-readelf.md | 468 +++---
llvm/docs/CommandGuide/llvm-readobj.md | 675 +++++----
llvm/docs/CommandGuide/llvm-reduce.md | 178 ++-
llvm/docs/CommandGuide/llvm-remarkutil.md | 502 +++----
llvm/docs/CommandGuide/llvm-size.md | 373 +++--
llvm/docs/CommandGuide/llvm-stress.md | 40 +-
llvm/docs/CommandGuide/llvm-strings.md | 216 ++-
llvm/docs/CommandGuide/llvm-strip.md | 336 ++---
llvm/docs/CommandGuide/llvm-symbolizer.md | 985 ++++++------
llvm/docs/CommandGuide/llvm-tblgen.md | 23 +-
.../CommandGuide/llvm-test-mustache-spec.md | 26 +-
llvm/docs/CommandGuide/llvm-tli-checker.md | 137 +-
llvm/docs/CommandGuide/mlir-tblgen.md | 23 +-
llvm/docs/CommandGuide/opt.md | 231 ++-
llvm/docs/CommandGuide/tblgen.md | 1123 +++++++-------
31 files changed, 6288 insertions(+), 6401 deletions(-)
diff --git a/llvm/docs/CommandGuide/llvm-libtool-darwin.md b/llvm/docs/CommandGuide/llvm-libtool-darwin.md
index a786288e77477..b07e42a4b701c 100644
--- a/llvm/docs/CommandGuide/llvm-libtool-darwin.md
+++ b/llvm/docs/CommandGuide/llvm-libtool-darwin.md
@@ -1,100 +1,97 @@
-llvm-libtool-darwin - LLVM tool for creating libraries for Darwin
-=================================================================
+# llvm-libtool-darwin - LLVM tool for creating libraries for Darwin
+```{eval-rst}
.. program:: llvm-libtool-darwin
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-libtool-darwin` [*options*] *<input files>*
+{program}`llvm-libtool-darwin` \[*options*\] *\<input files>*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-libtool-darwin` is a tool for creating static and dynamic
+{program}`llvm-libtool-darwin` is a tool for creating static and dynamic
libraries for Darwin.
For most scenarios, it works as a drop-in replacement for cctools'
-:program:`libtool`.
+{program}`libtool`.
-OPTIONS
---------
-:program:`llvm-libtool-darwin` supports the following options:
+## OPTIONS
-.. option:: -arch_only <architecture>
+{program}`llvm-libtool-darwin` supports the following options:
- Build a static library only for the specified `<architecture>` and ignore all
- other architectures in the files.
+:::{option} -arch_only <architecture>
+Build a static library only for the specified `<architecture>` and ignore all
+other architectures in the files.
+:::
-.. option:: -D
+:::{option} -D
+Use zero for timestamps and UIDs/GIDs. This is set by default.
+:::
- Use zero for timestamps and UIDs/GIDs. This is set by default.
+:::{option} -filelist <listfile[,dirname]>
+Read input file names from `<listfile>`. File names are specified in `<listfile>`
+one per line, separated only by newlines. Whitespace on a line is assumed
+to be part of the filename. If the directory name, `dirname`, is also
+specified then it is prepended to each file name in the `<listfile>`.
+:::
-.. option:: -filelist <listfile[,dirname]>
+:::{option} -h, -help
+Show help and usage for this command.
+:::
- Read input file names from `<listfile>`. File names are specified in `<listfile>`
- one per line, separated only by newlines. Whitespace on a line is assumed
- to be part of the filename. If the directory name, `dirname`, is also
- specified then it is prepended to each file name in the `<listfile>`.
+:::{option} -l <x>
+Searches for the library libx.a in the library search path. If the string `<x>`
+ends with '.o', then the library 'x' is searched for without prepending 'lib'
+or appending '.a'. If the library is found, it is added to the list of input
+files. Otherwise, an error is raised.
+:::
-.. option:: -h, -help
+:::{option} -L <dir>
+Adds `<dir>` to the list of directories in which to search for libraries. The
+directories are searched in the order in which they are specified with
+{option}`-L` and before the default search path. The default search path
+includes directories `/lib`, `/usr/lib` and `/usr/local/lib`.
+:::
- Show help and usage for this command.
+:::{option} -no_warning_for_no_symbols
+Do not warn about files that have no symbols.
+:::
-.. option:: -l <x>
+:::{option} -warnings_as_errors
+Produce a non-zero exit status if any warnings are emitted.
+:::
- Searches for the library libx.a in the library search path. If the string `<x>`
- ends with '.o', then the library 'x' is searched for without prepending 'lib'
- or appending '.a'. If the library is found, it is added to the list of input
- files. Otherwise, an error is raised.
+:::{option} -o <filename>
+Specify the output file name. Must be specified exactly once.
+:::
-.. option:: -L <dir>
+:::{option} -static
+Produces a static library from the input files.
+:::
- Adds `<dir>` to the list of directories in which to search for libraries. The
- directories are searched in the order in which they are specified with
- :option:`-L` and before the default search path. The default search path
- includes directories `/lib`, `/usr/lib` and `/usr/local/lib`.
+:::{option} -U
+Use actual timestamps and UIDs/GIDs.
+:::
-.. option:: -no_warning_for_no_symbols
+:::{option} -V
+Display the version of this program and perform any operation specified.
+:::
- Do not warn about files that have no symbols.
+:::{option} -version
+Display the version of this program and exit immediately.
+:::
-.. option:: -warnings_as_errors
+## EXIT STATUS
- Produce a non-zero exit status if any warnings are emitted.
-
-.. option:: -o <filename>
-
- Specify the output file name. Must be specified exactly once.
-
-.. option:: -static
-
- Produces a static library from the input files.
-
-.. option:: -U
-
- Use actual timestamps and UIDs/GIDs.
-
-.. option:: -V
-
- Display the version of this program and perform any operation specified.
-
-.. option:: -version
-
- Display the version of this program and exit immediately.
-
-EXIT STATUS
------------
-
-:program:`llvm-libtool-darwin` exits with a non-zero exit code if there is an error.
+{program}`llvm-libtool-darwin` 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/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/issues/>.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-ar(1)`
-:manpage:`llvm-ar(1)`
diff --git a/llvm/docs/CommandGuide/llvm-link.md b/llvm/docs/CommandGuide/llvm-link.md
index ba6eee5b71be4..1e677644a5d8f 100644
--- a/llvm/docs/CommandGuide/llvm-link.md
+++ b/llvm/docs/CommandGuide/llvm-link.md
@@ -1,112 +1,110 @@
-llvm-link - LLVM bitcode linker
-===============================
+# llvm-link - LLVM bitcode linker
+```{eval-rst}
.. program:: llvm-link
-
-SYNOPSIS
---------
-
-:program:`llvm-link` [*options*] *filename ...*
-
-DESCRIPTION
------------
-
-:program:`llvm-link` takes several LLVM bitcode files and links them together
-into a single LLVM bitcode file. It writes the output file to standard output,
-unless the :option:`-o` option is used to specify a filename.
-
-OPTIONS
--------
-
-.. option:: -f
-
- Enable binary output on terminals. Normally, :program:`llvm-link` will refuse
- to write raw bitcode output if the output stream is a terminal. With this
- option, :program:`llvm-link` will write raw bitcode regardless of the output
- device.
-
-.. option:: -o filename
-
- Specify the output file name. If ``filename`` is "``-``", then
- :program:`llvm-link` will write its output to standard output.
-
-.. option:: -S
-
- Write output in LLVM intermediate language (instead of bitcode).
-
-.. option:: -d
-
- If specified, :program:`llvm-link` prints a human-readable version of the
- output bitcode file to standard error.
-
-.. option:: --help
-
- Print a summary of command line options.
-
-.. option:: -v
-
- Verbose mode. Print information about what :program:`llvm-link` is doing.
- This typically includes a message for each bitcode file linked in and for each
- library found.
-
-.. option:: --override <filename>
-
- Adds the passed-in file to the link and overrides symbols that have already
- been declared with the definitions in the file that is passed in. This flag
- can be specified multiple times to have multiple files act as overrides. If
- a symbol is declared more than twice, the definition from the file declared
- last takes precedence.
-
-.. option:: --import <function:filename>
-
- Specify a function that should be imported from the specified file for
- linking with ThinLTO. This option can be specified multiple times to import
- multiple functions.
-
-.. option:: --summary-index <filename>
-
- Specify the path to a file containing the module summary index with the
- results of an earlier ThinLTO link. This option is required when
- `--import` is used.
-
-.. option:: --internalize
-
- Maintains existing linkage for symbols defined in the first input and
- converts linkage in all other inputs to internal linkage unless they are
- referenced by `llvm*.used` or are special-cased runtime functions (e.g.
- stack protector runtime).
-
-.. option:: --disable-debug-info-type-map
-
- Disables the use of a uniquing type map for debug info.
-
-.. option:: --only-needed
-
- Link only needed symbols.
-
-.. option:: --disable-lazy-loading
-
- Disable lazy module loading.
-
-.. option:: --suppress-warnings
-
- Suppress all linker warnings.
-
-.. option:: --preserve-bc-uselistorder
-
- Preserve the use-list order when writing LLVM bitcode.
-
-.. option:: --preserve-ll-uselistorder
-
- Preserve the use-list order when writing LLVM assembly.
-
-.. option:: --ignore-non-bitcode
-
- Do not error out when a non-bitcode file is encountered while processing
- an archive.
-
-EXIT STATUS
------------
-
-If :program:`llvm-link` succeeds, it will exit with 0. Otherwise, if an error
+```
+
+## SYNOPSIS
+
+{program}`llvm-link` \[*options*\] *filename ...*
+
+## DESCRIPTION
+
+{program}`llvm-link` takes several LLVM bitcode files and links them together
+into a single LLVM bitcode file. It writes the output file to standard output,
+unless the {option}`-o` option is used to specify a filename.
+
+## OPTIONS
+
+:::{option} -f
+Enable binary output on terminals. Normally, {program}`llvm-link` will refuse
+to write raw bitcode output if the output stream is a terminal. With this
+option, {program}`llvm-link` will write raw bitcode regardless of the output
+device.
+:::
+
+:::{option} -o filename
+Specify the output file name. If `filename` is "`-`", then
+{program}`llvm-link` will write its output to standard output.
+:::
+
+:::{option} -S
+Write output in LLVM intermediate language (instead of bitcode).
+:::
+
+:::{option} -d
+If specified, {program}`llvm-link` prints a human-readable version of the
+output bitcode file to standard error.
+:::
+
+:::{option} --help
+Print a summary of command line options.
+:::
+
+:::{option} -v
+Verbose mode. Print information about what {program}`llvm-link` is doing.
+This typically includes a message for each bitcode file linked in and for each
+library found.
+:::
+
+:::{option} --override <filename>
+Adds the passed-in file to the link and overrides symbols that have already
+been declared with the definitions in the file that is passed in. This flag
+can be specified multiple times to have multiple files act as overrides. If
+a symbol is declared more than twice, the definition from the file declared
+last takes precedence.
+:::
+
+:::{option} --import <function:filename>
+Specify a function that should be imported from the specified file for
+linking with ThinLTO. This option can be specified multiple times to import
+multiple functions.
+:::
+
+:::{option} --summary-index <filename>
+Specify the path to a file containing the module summary index with the
+results of an earlier ThinLTO link. This option is required when
+`--import` is used.
+:::
+
+:::{option} --internalize
+Maintains existing linkage for symbols defined in the first input and
+converts linkage in all other inputs to internal linkage unless they are
+referenced by `llvm*.used` or are special-cased runtime functions (e.g.
+stack protector runtime).
+:::
+
+:::{option} --disable-debug-info-type-map
+Disables the use of a uniquing type map for debug info.
+:::
+
+:::{option} --only-needed
+Link only needed symbols.
+:::
+
+:::{option} --disable-lazy-loading
+Disable lazy module loading.
+:::
+
+:::{option} --suppress-warnings
+Suppress all linker warnings.
+:::
+
+:::{option} --preserve-bc-uselistorder
+Preserve the use-list order when writing LLVM bitcode.
+:::
+
+:::{option} --preserve-ll-uselistorder
+Preserve the use-list order when writing LLVM assembly.
+:::
+
+:::{option} --ignore-non-bitcode
+Do not error out when a non-bitcode file is encountered while processing
+an archive.
+:::
+
+## EXIT STATUS
+
+If {program}`llvm-link` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
+
diff --git a/llvm/docs/CommandGuide/llvm-lipo.md b/llvm/docs/CommandGuide/llvm-lipo.md
index aeaaea9d6cda6..0ec837fa9b771 100644
--- a/llvm/docs/CommandGuide/llvm-lipo.md
+++ b/llvm/docs/CommandGuide/llvm-lipo.md
@@ -1,73 +1,73 @@
-llvm-lipo - LLVM tool for manipulating universal binaries
-=========================================================
+# llvm-lipo - LLVM tool for manipulating universal binaries
+```{eval-rst}
.. program:: llvm-lipo
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-lipo` [*filenames...*] [*options*]
+{program}`llvm-lipo` \[*filenames...*\] \[*options*\]
-DESCRIPTION
------------
-:program:`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files.
+## DESCRIPTION
-COMMANDS
---------
-:program:`llvm-lipo` supports the following mutually exclusive commands:
+{program}`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files.
-.. option:: -help, -h
+## COMMANDS
- Display usage information and exit.
+{program}`llvm-lipo` supports the following mutually exclusive commands:
-.. option:: -version
+:::{option} -help, -h
+Display usage information and exit.
+:::
- Display the version of this program.
+:::{option} -version
+Display the version of this program.
+:::
-.. option:: -verify_arch <architecture 1> [<architecture 2> ...]
+:::{option} -verify_arch <architecture 1> [<architecture 2> ...]
+Take a single input file and verify the specified architectures are present in the file.
+If so then exit with a status of 0 else exit with a status of 1.
+:::
- Take a single input file and verify the specified architectures are present in the file.
- If so then exit with a status of 0 else exit with a status of 1.
+:::{option} -archs
+Take a single input file and display the architectures present in the file.
+Each architecture is separated by a single whitespace.
+Unknown architectures are displayed as unknown(CPUtype,CPUsubtype).
+:::
-.. option:: -archs
+:::{option} -info
+Take at least one input file and display the descriptions of each file.
+The descriptions include the filename and architecture types separated by whitespace.
+Universal binaries are grouped together first, followed by thin files.
+Architectures in the fat file: \<filename> are: \<architectures>
+Non-fat file: \<filename> is architecture: \<architecture>
+:::
- Take a single input file and display the architectures present in the file.
- Each architecture is separated by a single whitespace.
- Unknown architectures are displayed as unknown(CPUtype,CPUsubtype).
+:::{option} -thin
+Take a single universal binary input file and the thin flag followed by an architecture type.
+Require the output flag to be specified, and output a thin binary of the specified architecture.
+:::
-.. option:: -info
+:::{option} -create
+Take at least one input file and require the output flag to be specified.
+Output a universal binary combining the input files.
+:::
- Take at least one input file and display the descriptions of each file.
- The descriptions include the filename and architecture types separated by whitespace.
- Universal binaries are grouped together first, followed by thin files.
- Architectures in the fat file: <filename> are: <architectures>
- Non-fat file: <filename> is architecture: <architecture>
+:::{option} -replace
+Take a single universal binary input file and require the output flag to be specified.
+The replace flag is followed by an architecture type, and a thin input file.
+Output a universal binary with the specified architecture slice in the
+universal binary input replaced with the contents of the thin input file.
+:::
-.. option:: -thin
+:::{option} -segalign
+Additional flag that can be specified with create and replace.
+The segalign flag is followed by an architecture type, and an alignment.
+The alignment is a hexadecimal number that is a power of 2.
+Output a file in which the slice with the specified architecture has the specified alignment.
+:::
- Take a single universal binary input file and the thin flag followed by an architecture type.
- Require the output flag to be specified, and output a thin binary of the specified architecture.
+## BUGS
-.. option:: -create
+To report bugs, please visit \<<https://github.com/llvm/llvm-project/issues/>>.
- Take at least one input file and require the output flag to be specified.
- Output a universal binary combining the input files.
-
-.. option:: -replace
-
- Take a single universal binary input file and require the output flag to be specified.
- The replace flag is followed by an architecture type, and a thin input file.
- Output a universal binary with the specified architecture slice in the
- universal binary input replaced with the contents of the thin input file.
-
-.. option:: -segalign
-
- Additional flag that can be specified with create and replace.
- The segalign flag is followed by an architecture type, and an alignment.
- The alignment is a hexadecimal number that is a power of 2.
- Output a file in which the slice with the specified architecture has the specified alignment.
-
-BUGS
-----
-
-To report bugs, please visit <https://github.com/llvm/llvm-project/issues/>.
diff --git a/llvm/docs/CommandGuide/llvm-locstats.md b/llvm/docs/CommandGuide/llvm-locstats.md
index 7f436c1f44a7e..ca3ffa6d41308 100644
--- a/llvm/docs/CommandGuide/llvm-locstats.md
+++ b/llvm/docs/CommandGuide/llvm-locstats.md
@@ -1,118 +1,114 @@
-llvm-locstats - calculate statistics on DWARF debug location
-============================================================
+# llvm-locstats - calculate statistics on DWARF debug location
+```{eval-rst}
.. program:: llvm-locstats
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-locstats` [*options*] [*filename*]
+{program}`llvm-locstats` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-locstats` works like a wrapper around :program:`llvm-dwarfdump`.
-It parses :program:`llvm-dwarfdump` statistics regarding debug location by
+{program}`llvm-locstats` works like a wrapper around {program}`llvm-dwarfdump`.
+It parses {program}`llvm-dwarfdump` statistics regarding debug location by
pretty printing it in a more human-readable way.
The line 0% shows the number and the percentage of DIEs with no location
information, but the line 100% shows the information for DIEs where there is
location information in all code section bytes (where the variable or parameter
-is in the scope). The line [50%,60%) shows the number and the percentage of DIEs
+is in the scope). The line \[50%,60%) shows the number and the percentage of DIEs
where the location information is between 50 and 60 percentage of its scope
covered.
-OPTIONS
--------
+## OPTIONS
-.. option:: --only-variables
+:::{option} --only-variables
+calculate the location statistics only for local variables
+:::
- calculate the location statistics only for local variables
+:::{option} --only-formal-parameters
+calculate the location statistics only for formal parameters
+:::
-.. option:: --only-formal-parameters
+:::{option} --ignore-debug-entry-values
+ignore the location statistics on locations containing the
+debug entry values DWARF operation
+:::
- calculate the location statistics only for formal parameters
+:::{option} --draw-plot
+make histogram of location buckets generated (requires
+matplotlib)
+:::
-.. option:: --ignore-debug-entry-values
+:::{option} --compare
+compare the debug location coverage on two files provided, and draw
+a plot showing the difference (requires matplotlib)
+:::
- ignore the location statistics on locations containing the
- debug entry values DWARF operation
+## EXIT STATUS
-.. option:: --draw-plot
-
- make histogram of location buckets generated (requires
- matplotlib)
-
-.. option:: --compare
-
- compare the debug location coverage on two files provided, and draw
- a plot showing the difference (requires matplotlib)
-
-EXIT STATUS
------------
-
-:program:`llvm-locstats` returns 0 if the input file were parsed
+{program}`llvm-locstats` returns 0 if the input file were parsed
successfully. Otherwise, it returns 1.
-EXAMPLE 1
---------------
+## EXAMPLE 1
Pretty print the location coverage on the standard output.
-.. code-block:: none
-
- llvm-locstats a.out
-
- =================================================
- Debug Location Statistics
- =================================================
- cov% samples percentage(~)
- -------------------------------------------------
- 0% 1 16%
- (0%,10%) 0 0%
- [10%,20%) 0 0%
- [20%,30%) 0 0%
- [30%,40%) 0 0%
- [40%,50%) 0 0%
- [50%,60%) 1 16%
- [60%,70%) 0 0%
- [70%,80%) 0 0%
- [80%,90%) 1 16%
- [90%,100%) 0 0%
- 100% 3 50%
- =================================================
- -the number of debug variables processed: 6
- -PC ranges covered: 81%
- -------------------------------------------------
- -total availability: 83%
- =================================================
-
-EXAMPLE 2
---------------
+```none
+llvm-locstats a.out
+
+ =================================================
+ Debug Location Statistics
+ =================================================
+ cov% samples percentage(~)
+ -------------------------------------------------
+ 0% 1 16%
+ (0%,10%) 0 0%
+ [10%,20%) 0 0%
+ [20%,30%) 0 0%
+ [30%,40%) 0 0%
+ [40%,50%) 0 0%
+ [50%,60%) 1 16%
+ [60%,70%) 0 0%
+ [70%,80%) 0 0%
+ [80%,90%) 1 16%
+ [90%,100%) 0 0%
+ 100% 3 50%
+ =================================================
+ -the number of debug variables processed: 6
+ -PC ranges covered: 81%
+ -------------------------------------------------
+ -total availability: 83%
+ =================================================
+```
+
+## EXAMPLE 2
Generate a plot as an image file.
-.. code-block:: none
-
- llvm-locstats --draw-plot file1.out
+```none
+llvm-locstats --draw-plot file1.out
+```
-.. image:: locstats-draw-plot.png
- :align: center
+```{image} locstats-draw-plot.png
+:align: center
+```
-EXAMPLE 3
---------------
+## EXAMPLE 3
Generate a plot as an image file showing the difference in the debug location
coverage.
-.. code-block:: none
+```none
+llvm-locstats --compare file1.out file1.withentryvals.out
+```
- llvm-locstats --compare file1.out file1.withentryvals.out
+```{image} locstats-compare.png
+:align: center
+```
-.. image:: locstats-compare.png
- :align: center
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-dwarfdump(1)`
-:manpage:`llvm-dwarfdump(1)`
diff --git a/llvm/docs/CommandGuide/llvm-mc.md b/llvm/docs/CommandGuide/llvm-mc.md
index 8d6346f4f1bcc..91c0cdac68c6d 100644
--- a/llvm/docs/CommandGuide/llvm-mc.md
+++ b/llvm/docs/CommandGuide/llvm-mc.md
@@ -1,172 +1,165 @@
-llvm-mc - LLVM Machine Code Playground
-======================================
+# llvm-mc - LLVM Machine Code Playground
+```{eval-rst}
.. program:: llvm-mc
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-mc` [*options*] [*filename*]
+{program}`llvm-mc` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-mc` command takes assembly code for a specified architecture
+The {program}`llvm-mc` command takes assembly code for a specified architecture
as input and generates an object file or executable.
-:program:`llvm-mc` provides a set of tools for working with machine code,
+{program}`llvm-mc` provides a set of tools for working with machine code,
such as encoding instructions and displaying internal representations,
disassembling strings to bytes, etc.
The choice of architecture for the output assembly code is automatically
-determined from the input file, unless the :option:`--arch` option is used to
+determined from the input file, unless the {option}`--arch` option is used to
override the default.
-OPTIONS
--------
+## OPTIONS
-If the :option:`-o` option is omitted, then :program:`llvm-mc` 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
+If the {option}`-o` option is omitted, then {program}`llvm-mc` 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:`llvm-mc` creates the output filename by taking the
-input filename, removing any existing ``.s`` extension, and adding a ``.o``
+If no {option}`-o` option is specified and an input file other than "`-`" is
+specified, then {program}`llvm-mc` creates the output filename by taking the
+input filename, removing any existing `.s` extension, and adding a `.o`
suffix.
-Other :program:`llvm-mc` options are described below.
-
-End-user Options
-~~~~~~~~~~~~~~~~
-
-.. option:: --help
-
- Display available options (--help-hidden for more).
-
-.. option:: -o <filename>
-
- Use ``<filename>`` as the output filename. See the summary above for more
- details.
-
-.. option:: --arch=<string>
-
- Target arch to assemble for, see -version for available targets.
-
-.. option:: --as-lex
-
- Apply the assemblers "lexer" to break the input into tokens and print each of
- them out. This is intended to help develop and test an assembler
- implementation.
-
-.. option:: --assemble
-
- Assemble assembly file (default), and print the result to assembly. This is
- useful to design and test instruction parsers, and can be a useful tool when
- combined with other llvm-mc flags. For example, this option may be useful to
- transcode assembly from different dialects, e.g. on Intel where you can use
- -output-asm-variant=1 to translate from AT&T to Intel assembly syntax. It can
- also be combined with --show-encoding to understand how instructions are
- encoded.
-
-.. option:: --disassemble
-
- Parse a series of hex bytes, and print the result out as assembly syntax.
-
-.. option:: --mdis
-
- Marked up disassembly of string of hex bytes.
-
-.. option:: --cdis
-
- Colored disassembly of string of hex bytes.
-
-.. option:: --filetype=[asm,null,obj]
-
- Sets the output filetype. Setting this flag to `asm` will make the tool output
- text assembly. Setting this flag to `obj` will make the tool output an object
- file. Setting it to `null` causes no output to be created and can be used for
- timing purposes. The default value is `asm`.
-
-.. option:: -g
-
- Generate DWARF debugging info for assembly source files.
-
-.. option:: --hex
-
- Take raw hexadecimal bytes as input for disassembly. Whitespace is ignored.
-
-.. option:: --large-code-model
-
- Create CFI directives that assume the code might be more than 2 GB.
-
-.. option:: --main-file-name=<string>
-
- Specify the name we should consider the input file.
-
-
-.. option:: --masm-hexfloats
-
- Enable MASM-style hex float initializers (3F800000r).
-
-
-.. option:: -mattr=a1,+a2,-a3,...
- Target specific attributes (-mattr=help for details).
-
-.. option:: --mcpu=<cpu-name>
-
- Target a specific cpu type (-mcpu=help for details).
-
-.. option:: --triple=<string>
-
- Target triple to assemble for, see -version for available targets.
-
-.. option:: --split-dwarf-file=<filename>
-
- DWO output filename.
-
-.. option:: --show-inst-operands
-
- Show instructions operands as parsed.
-
-.. option:: --show-inst
-
- Show internal instruction representation.
-
-.. option:: --show-encoding
-
- Show instruction encodings.
-
-.. option:: --save-temp-labels
-
- Don't discard temporary labels.
-
-.. option:: --relax-relocations
-
- Emit R_X86_64_GOTPCRELX instead of R_X86_64_GOTPCREL.
-
-.. option:: --print-imm-hex
-
- Prefer hex format for immediate values.
-
-.. option:: --preserve-comments
-
- Preserve Comments in outputted assembly.
-
-.. option:: --output-asm-variant=<uint>
-
- Syntax variant to use for output printing. For example, on x86 targets
- --output-asm-variant=0 prints in AT&T syntax, and --output-asm-variant=1
- prints in Intel/MASM syntax.
-
-.. option:: --compress-debug-sections=[none|zlib|zstd]
-
- Choose DWARF debug sections compression.
-
-
-EXIT STATUS
------------
-
-If :program:`llvm-mc` succeeds, it will exit with 0. Otherwise, if an error
+Other {program}`llvm-mc` options are described below.
+
+### End-user Options
+
+:::{option} --help
+Display available options (--help-hidden for more).
+:::
+
+:::{option} -o <filename>
+Use `<filename>` as the output filename. See the summary above for more
+details.
+:::
+
+:::{option} --arch=<string>
+Target arch to assemble for, see -version for available targets.
+:::
+
+:::{option} --as-lex
+Apply the assemblers "lexer" to break the input into tokens and print each of
+them out. This is intended to help develop and test an assembler
+implementation.
+:::
+
+:::{option} --assemble
+Assemble assembly file (default), and print the result to assembly. This is
+useful to design and test instruction parsers, and can be a useful tool when
+combined with other llvm-mc flags. For example, this option may be useful to
+transcode assembly from different dialects, e.g. on Intel where you can use
+-output-asm-variant=1 to translate from AT&T to Intel assembly syntax. It can
+also be combined with --show-encoding to understand how instructions are
+encoded.
+:::
+
+:::{option} --disassemble
+Parse a series of hex bytes, and print the result out as assembly syntax.
+:::
+
+:::{option} --mdis
+Marked up disassembly of string of hex bytes.
+:::
+
+:::{option} --cdis
+Colored disassembly of string of hex bytes.
+:::
+
+:::{option} --filetype=[asm,null,obj]
+Sets the output filetype. Setting this flag to `asm` will make the tool output
+text assembly. Setting this flag to `obj` will make the tool output an object
+file. Setting it to `null` causes no output to be created and can be used for
+timing purposes. The default value is `asm`.
+:::
+
+:::{option} -g
+Generate DWARF debugging info for assembly source files.
+:::
+
+:::{option} --hex
+Take raw hexadecimal bytes as input for disassembly. Whitespace is ignored.
+:::
+
+:::{option} --large-code-model
+Create CFI directives that assume the code might be more than 2 GB.
+:::
+
+:::{option} --main-file-name=<string>
+Specify the name we should consider the input file.
+:::
+
+:::{option} --masm-hexfloats
+Enable MASM-style hex float initializers (3F800000r).
+:::
+
+:::{option} -mattr=a1,+a2,-a3,... Target specific attributes (-mattr=help for details).
+:::
+
+:::{option} --mcpu=<cpu-name>
+Target a specific cpu type (-mcpu=help for details).
+:::
+
+:::{option} --triple=<string>
+Target triple to assemble for, see -version for available targets.
+:::
+
+:::{option} --split-dwarf-file=<filename>
+DWO output filename.
+:::
+
+:::{option} --show-inst-operands
+Show instructions operands as parsed.
+:::
+
+:::{option} --show-inst
+Show internal instruction representation.
+:::
+
+:::{option} --show-encoding
+Show instruction encodings.
+:::
+
+:::{option} --save-temp-labels
+Don't discard temporary labels.
+:::
+
+:::{option} --relax-relocations
+Emit R_X86_64_GOTPCRELX instead of R_X86_64_GOTPCREL.
+:::
+
+:::{option} --print-imm-hex
+Prefer hex format for immediate values.
+:::
+
+:::{option} --preserve-comments
+Preserve Comments in outputted assembly.
+:::
+
+:::{option} --output-asm-variant=<uint>
+Syntax variant to use for output printing. For example, on x86 targets
+--output-asm-variant=0 prints in AT&T syntax, and --output-asm-variant=1
+prints in Intel/MASM syntax.
+:::
+
+:::{option} --compress-debug-sections=[none|zlib|zstd]
+Choose DWARF debug sections compression.
+:::
+
+## EXIT STATUS
+
+If {program}`llvm-mc` 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-mca.md b/llvm/docs/CommandGuide/llvm-mca.md
index cb8924436a26c..8adf41fa6ef94 100644
--- a/llvm/docs/CommandGuide/llvm-mca.md
+++ b/llvm/docs/CommandGuide/llvm-mca.md
@@ -1,17 +1,16 @@
-llvm-mca - LLVM Machine Code Analyzer
-=====================================
+# llvm-mca - LLVM Machine Code Analyzer
+```{eval-rst}
.. program:: llvm-mca
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-mca` [*options*] [input]
+{program}`llvm-mca` \[*options*\] [input]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-mca` is a performance analysis tool that uses information
+{program}`llvm-mca` is a performance analysis tool that uses information
available in LLVM (e.g. scheduling models) to statically measure the performance
of machine code in a specific CPU.
@@ -23,306 +22,303 @@ The main goal of this tool is not just to predict the performance of the code
when run on the target, but also help with diagnosing potential performance
issues.
-Given an assembly code sequence, :program:`llvm-mca` estimates the Instructions
+Given an assembly code sequence, {program}`llvm-mca` estimates the Instructions
Per Cycle (IPC), as well as hardware resource pressure. The analysis and
reporting style were inspired by the IACA tool from Intel.
For example, you can compile code with clang, output assembly, and pipe it
-directly into :program:`llvm-mca` for analysis:
+directly into {program}`llvm-mca` for analysis:
-.. code-block:: bash
-
- $ clang foo.c -O2 --target=x86_64 -S -o - | llvm-mca -mcpu=btver2
+```bash
+$ clang foo.c -O2 --target=x86_64 -S -o - | llvm-mca -mcpu=btver2
+```
Or for Intel syntax:
-.. code-block:: bash
-
- $ clang foo.c -O2 --target=x86_64 -masm=intel -S -o - | llvm-mca -mcpu=btver2
+```bash
+$ clang foo.c -O2 --target=x86_64 -masm=intel -S -o - | llvm-mca -mcpu=btver2
+```
-(:program:`llvm-mca` detects Intel syntax by the presence of an `.intel_syntax`
-directive at the beginning of the input. By default its output syntax matches
+({program}`llvm-mca` detects Intel syntax by the presence of an `.intel_syntax`
+directive at the beginning of the input. By default its output syntax matches
that of its input.)
Scheduling models are not just used to compute instruction latencies and
throughput, but also to understand what processor resources are available
and how to simulate them.
-By design, the quality of the analysis conducted by :program:`llvm-mca` is
+By design, the quality of the analysis conducted by {program}`llvm-mca` is
inevitably affected by the quality of the scheduling models in LLVM.
If you see that the performance report is not accurate for a processor,
-please `file a bug <https://github.com/llvm/llvm-project/issues>`_
+please [file a bug](https://github.com/llvm/llvm-project/issues)
against the appropriate backend.
-OPTIONS
--------
+## OPTIONS
-If ``input`` is "``-``" or omitted, :program:`llvm-mca` reads from standard
+If `input` is "`-`" or omitted, {program}`llvm-mca` reads from standard
input. Otherwise, it will read from the specified filename.
-If the :option:`-o` option is omitted, then :program:`llvm-mca` will send its output
-to standard output if the input is from standard input. If the :option:`-o`
-option specifies "``-``", then the output will also be sent to standard output.
-
-
-.. option:: -help
-
- Print a summary of command line options.
-
-.. option:: -o <filename>
-
- Use ``<filename>`` as the output filename. See the summary above for more
- details.
-
-.. option:: -mtriple=<target triple>
-
- Specify a target triple string.
-
-.. option:: -march=<arch>
-
- Specify the architecture for which to analyze the code. It defaults to the
- host default target.
-
-.. option:: -mcpu=<cpuname>
-
- Specify the processor for which to analyze the code. By default, the cpu name
- is autodetected from the host.
-
-.. option:: -output-asm-variant=<variant id>
-
- Specify the output assembly variant for the report generated by the tool.
- On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables
- the AT&T (vic. Intel) assembly format for the code printed out by the tool in
- the analysis report.
-
-.. option:: -print-imm-hex
-
- Prefer hex format for numeric literals in the output assembly printed as part
- of the report.
-
-.. option:: -dispatch=<width>
-
- Specify a different dispatch width for the processor. The dispatch width
- defaults to field 'IssueWidth' in the processor scheduling model. If width is
- zero, then the default dispatch width is used.
-
-.. option:: -register-file-size=<size>
-
- Specify the size of the register file. When specified, this flag limits how
- many physical registers are available for register renaming purposes. A value
- of zero for this flag means "unlimited number of physical registers".
-
-.. option:: -iterations=<number of iterations>
-
- Specify the number of iterations to run. If this flag is set to 0, then the
- tool sets the number of iterations to a default value (i.e. 100).
-
-.. option:: -noalias=<bool>
-
- If set, the tool assumes that loads and stores don't alias. This is the
- default behavior.
-
-.. option:: -lqueue=<load queue size>
-
- Specify the size of the load queue in the load/store unit emulated by the tool.
- By default, the tool assumes an unbound number of entries in the load queue.
- A value of zero for this flag is ignored, and the default load queue size is
- used instead.
-
-.. option:: -squeue=<store queue size>
-
- Specify the size of the store queue in the load/store unit emulated by the
- tool. By default, the tool assumes an unbound number of entries in the store
- queue. A value of zero for this flag is ignored, and the default store queue
- size is used instead.
-
-.. option:: -timeline
-
- Enable the timeline view.
-
-.. option:: -timeline-max-iterations=<iterations>
-
- Limit the number of iterations to print in the timeline view. By default, the
- timeline view prints information for up to 10 iterations.
-
-.. option:: -timeline-max-cycles=<cycles>
-
- Limit the number of cycles in the timeline view, or use 0 for no limit. By
- default, the number of cycles is set to 80.
-
-.. option:: -resource-pressure
-
- Enable the resource pressure view. This is enabled by default.
-
-.. option:: -register-file-stats
-
- Enable register file usage statistics.
-
-.. option:: -dispatch-stats
-
- Enable extra dispatch statistics. This view collects and analyzes instruction
- dispatch events, as well as static/dynamic dispatch stall events. This view
- is disabled by default.
-
-.. option:: -scheduler-stats
-
- Enable extra scheduler statistics. This view collects and analyzes instruction
- issue events. This view is disabled by default.
-
-.. option:: -retire-stats
-
- Enable extra retire control unit statistics. This view is disabled by default.
-
-.. option:: -instruction-info
-
- Enable the instruction info view. This is enabled by default.
-
-.. option:: -show-encoding
-
- Enable the printing of instruction encodings within the instruction info view.
-
-.. option:: -show-barriers
-
- Enable the printing of LoadBarrier and StoreBarrier flags within the
- instruction info view.
-
-.. option:: -all-stats
-
- Print all hardware statistics. This enables extra statistics related to the
- dispatch logic, the hardware schedulers, the register file(s), and the retire
- control unit. This option is disabled by default.
-
-.. option:: -all-views
-
- Enable all the view.
-
-.. option:: -instruction-tables=<level>
-
- Prints resource pressure information based on the static information
- available from the processor model. This differs from the resource pressure
- view because it doesn't require that the code is simulated. It instead prints
- the theoretical uniform distribution of resource pressure for every
- instruction in sequence.
-
- The choice of `<level>` controls number of printed information.
- `<level>` may be `none` (default), `normal`, `full`.
- Note: If the option is used without `<label>`, default is `normal` (legacy).
-
- When `<level>` is `full`, additional information are:
- - `<Bypass Latency>`: Latency when a bypass is implemented between operands
- in pipelines (see SchedReadAdvance).
- - `<LLVM Opcode Name>`: mnemonic plus operands identifier.
- - `<Resources units>`: Used resources associated with LLVM Opcode.
- - `<instruction comment>`: reports comment if any from source assembly.
-
- `<Resources units>` syntax can be:
- - <Resource Name>: ReleaseAtCycle is 1.
- - <Resource Name>[<ReleaseAtCycle>]: ReleaseAtCycle is greater than 1
- and AcquireAtCycle is 0.
- - <Resource Name>[<AcquireAtCycle>,<ReleaseAtCycle>]: ReleaseAtCycle
- is greater than 1 and AcquireAtCycle is greater than 0.
-
-.. option:: -bottleneck-analysis
-
- Print information about bottlenecks that affect the throughput. This analysis
- can be expensive, and it is disabled by default. Bottlenecks are highlighted
- in the summary view. Bottleneck analysis is currently not supported for
- processors with an in-order backend.
-
-.. option:: -json
-
- Print the requested views in valid JSON format. The instructions and the
- processor resources are printed as members of special top level JSON objects.
- The individual views refer to them by index. However, not all views are
- currently supported. For example, the report from the bottleneck analysis is
- not printed out in JSON. All the default views are currently supported.
-
-.. option:: -disable-cb
-
- Force usage of the generic CustomBehaviour and InstrPostProcess classes rather
- than using the target-specific implementation. The generic classes never
- detect any custom hazards or make any post processing modifications to
- instructions.
-
-.. option:: -disable-im
-
- Force usage of the generic InstrumentManager rather than using the target
- specific implementation. The generic class creates Instruments that provide
- no extra information, and InstrumentManager never overrides the default
- schedule class for a given instruction.
+If the {option}`-o` option is omitted, then {program}`llvm-mca` will send its output
+to standard output if the input is from standard input. If the {option}`-o`
+option specifies "`-`", then the output will also be sent to standard output.
+
+:::{option} -help
+Print a summary of command line options.
+:::
+
+:::{option} -o <filename>
+Use `<filename>` as the output filename. See the summary above for more
+details.
+:::
+
+:::{option} -mtriple=<target triple>
+Specify a target triple string.
+:::
+
+:::{option} -march=<arch>
+Specify the architecture for which to analyze the code. It defaults to the
+host default target.
+:::
+
+:::{option} -mcpu=<cpuname>
+Specify the processor for which to analyze the code. By default, the cpu name
+is autodetected from the host.
+:::
+
+:::{option} -output-asm-variant=<variant id>
+Specify the output assembly variant for the report generated by the tool.
+On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables
+the AT&T (vic. Intel) assembly format for the code printed out by the tool in
+the analysis report.
+:::
+
+:::{option} -print-imm-hex
+Prefer hex format for numeric literals in the output assembly printed as part
+of the report.
+:::
+
+:::{option} -dispatch=<width>
+Specify a different dispatch width for the processor. The dispatch width
+defaults to field 'IssueWidth' in the processor scheduling model. If width is
+zero, then the default dispatch width is used.
+:::
+
+:::{option} -register-file-size=<size>
+Specify the size of the register file. When specified, this flag limits how
+many physical registers are available for register renaming purposes. A value
+of zero for this flag means "unlimited number of physical registers".
+:::
+
+:::{option} -iterations=<number of iterations>
+Specify the number of iterations to run. If this flag is set to 0, then the
+tool sets the number of iterations to a default value (i.e. 100).
+:::
+
+:::{option} -noalias=<bool>
+If set, the tool assumes that loads and stores don't alias. This is the
+default behavior.
+:::
+
+:::{option} -lqueue=<load queue size>
+Specify the size of the load queue in the load/store unit emulated by the tool.
+By default, the tool assumes an unbound number of entries in the load queue.
+A value of zero for this flag is ignored, and the default load queue size is
+used instead.
+:::
+
+:::{option} -squeue=<store queue size>
+Specify the size of the store queue in the load/store unit emulated by the
+tool. By default, the tool assumes an unbound number of entries in the store
+queue. A value of zero for this flag is ignored, and the default store queue
+size is used instead.
+:::
+
+:::{option} -timeline
+Enable the timeline view.
+:::
+
+:::{option} -timeline-max-iterations=<iterations>
+Limit the number of iterations to print in the timeline view. By default, the
+timeline view prints information for up to 10 iterations.
+:::
+
+:::{option} -timeline-max-cycles=<cycles>
+Limit the number of cycles in the timeline view, or use 0 for no limit. By
+default, the number of cycles is set to 80.
+:::
+
+:::{option} -resource-pressure
+Enable the resource pressure view. This is enabled by default.
+:::
+
+:::{option} -register-file-stats
+Enable register file usage statistics.
+:::
+
+:::{option} -dispatch-stats
+Enable extra dispatch statistics. This view collects and analyzes instruction
+dispatch events, as well as static/dynamic dispatch stall events. This view
+is disabled by default.
+:::
+
+:::{option} -scheduler-stats
+Enable extra scheduler statistics. This view collects and analyzes instruction
+issue events. This view is disabled by default.
+:::
+
+:::{option} -retire-stats
+Enable extra retire control unit statistics. This view is disabled by default.
+:::
+
+:::{option} -instruction-info
+Enable the instruction info view. This is enabled by default.
+:::
+
+:::{option} -show-encoding
+Enable the printing of instruction encodings within the instruction info view.
+:::
+
+:::{option} -show-barriers
+Enable the printing of LoadBarrier and StoreBarrier flags within the
+instruction info view.
+:::
+
+:::{option} -all-stats
+Print all hardware statistics. This enables extra statistics related to the
+dispatch logic, the hardware schedulers, the register file(s), and the retire
+control unit. This option is disabled by default.
+:::
+
+:::{option} -all-views
+Enable all the view.
+:::
+
+:::{option} -instruction-tables=<level>
+Prints resource pressure information based on the static information
+available from the processor model. This differs from the resource pressure
+view because it doesn't require that the code is simulated. It instead prints
+the theoretical uniform distribution of resource pressure for every
+instruction in sequence.
+
+The choice of `<level>` controls number of printed information.
+`<level>` may be `none` (default), `normal`, `full`.
+Note: If the option is used without `<label>`, default is `normal` (legacy).
+
+When `<level>` is `full`, additional information are:
+\- `<Bypass Latency>`: Latency when a bypass is implemented between operands
+in pipelines (see SchedReadAdvance).
+\- `<LLVM Opcode Name>`: mnemonic plus operands identifier.
+\- `<Resources units>`: Used resources associated with LLVM Opcode.
+\- `<instruction comment>`: reports comment if any from source assembly.
+
+`<Resources units>` syntax can be:
+\- \<Resource Name>: ReleaseAtCycle is 1.
+\- \<Resource Name>\[\<ReleaseAtCycle>\]: ReleaseAtCycle is greater than 1
+and AcquireAtCycle is 0.
+\- \<Resource Name>\[\<AcquireAtCycle>,\<ReleaseAtCycle>\]: ReleaseAtCycle
+is greater than 1 and AcquireAtCycle is greater than 0.
+:::
+
+:::{option} -bottleneck-analysis
+Print information about bottlenecks that affect the throughput. This analysis
+can be expensive, and it is disabled by default. Bottlenecks are highlighted
+in the summary view. Bottleneck analysis is currently not supported for
+processors with an in-order backend.
+:::
+
+:::{option} -json
+Print the requested views in valid JSON format. The instructions and the
+processor resources are printed as members of special top level JSON objects.
+The individual views refer to them by index. However, not all views are
+currently supported. For example, the report from the bottleneck analysis is
+not printed out in JSON. All the default views are currently supported.
+:::
+
+:::{option} -disable-cb
+Force usage of the generic CustomBehaviour and InstrPostProcess classes rather
+than using the target-specific implementation. The generic classes never
+detect any custom hazards or make any post processing modifications to
+instructions.
+:::
-.. option:: -skip-unsupported-instructions=<reason>
+:::{option} -disable-im
+Force usage of the generic InstrumentManager rather than using the target
+specific implementation. The generic class creates Instruments that provide
+no extra information, and InstrumentManager never overrides the default
+schedule class for a given instruction.
+:::
- Force :program:`llvm-mca` to continue in the presence of instructions which do
- not parse or lack key scheduling information. Note that the resulting analysis
- is impacted since those unsupported instructions are ignored as-if they are
- not supplied as a part of the input.
+:::{option} -skip-unsupported-instructions=<reason>
+Force {program}`llvm-mca` to continue in the presence of instructions which do
+not parse or lack key scheduling information. Note that the resulting analysis
+is impacted since those unsupported instructions are ignored as-if they are
+not supplied as a part of the input.
- The choice of `<reason>` controls the when mca will report an error.
- `<reason>` may be `none` (default), `lack-sched`, `parse-failure`, `any`.
+The choice of `<reason>` controls the when mca will report an error.
+`<reason>` may be `none` (default), `lack-sched`, `parse-failure`, `any`.
+:::
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed
+{program}`llvm-mca` returns 0 on success. Otherwise, an error message is printed
to standard error, and the tool returns 1.
-USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS
----------------------------------------------
-:program:`llvm-mca` allows for the optional usage of special code comments to
-mark regions of the assembly code to be analyzed. A comment starting with
-substring ``LLVM-MCA-BEGIN`` marks the beginning of an analysis region. A
-comment starting with substring ``LLVM-MCA-END`` marks the end of a region.
-For example:
+## USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS
-.. code-block:: none
+{program}`llvm-mca` allows for the optional usage of special code comments to
+mark regions of the assembly code to be analyzed. A comment starting with
+substring `LLVM-MCA-BEGIN` marks the beginning of an analysis region. A
+comment starting with substring `LLVM-MCA-END` marks the end of a region.
+For example:
- # LLVM-MCA-BEGIN
- ...
- # LLVM-MCA-END
+```none
+# LLVM-MCA-BEGIN
+ ...
+# LLVM-MCA-END
+```
-If no user-defined region is specified, then :program:`llvm-mca` assumes a
-default region which contains every instruction in the input file. Every region
+If no user-defined region is specified, then {program}`llvm-mca` assumes a
+default region which contains every instruction in the input file. Every region
is analyzed in isolation, and the final performance report is the union of all
the reports generated for every analysis region.
Analysis regions can have names. For example:
-.. code-block:: none
-
- # LLVM-MCA-BEGIN A simple example
- add %eax, %eax
- # LLVM-MCA-END
+```none
+# LLVM-MCA-BEGIN A simple example
+ add %eax, %eax
+# LLVM-MCA-END
+```
The code from the example above defines a region named "A simple example" with a
single instruction in it. Note how the region name doesn't have to be repeated
-in the ``LLVM-MCA-END`` directive. In the absence of overlapping regions,
-an anonymous ``LLVM-MCA-END`` directive always ends the currently active user
+in the `LLVM-MCA-END` directive. In the absence of overlapping regions,
+an anonymous `LLVM-MCA-END` directive always ends the currently active user
defined region.
Example of nesting regions:
-.. code-block:: none
-
- # LLVM-MCA-BEGIN foo
- add %eax, %edx
- # LLVM-MCA-BEGIN bar
- sub %eax, %edx
- # LLVM-MCA-END bar
- # LLVM-MCA-END foo
+```none
+# LLVM-MCA-BEGIN foo
+ add %eax, %edx
+# LLVM-MCA-BEGIN bar
+ sub %eax, %edx
+# LLVM-MCA-END bar
+# LLVM-MCA-END foo
+```
Example of overlapping regions:
-.. code-block:: none
-
- # LLVM-MCA-BEGIN foo
- add %eax, %edx
- # LLVM-MCA-BEGIN bar
- sub %eax, %edx
- # LLVM-MCA-END foo
- add %eax, %edx
- # LLVM-MCA-END bar
+```none
+# LLVM-MCA-BEGIN foo
+ add %eax, %edx
+# LLVM-MCA-BEGIN bar
+ sub %eax, %edx
+# LLVM-MCA-END foo
+ add %eax, %edx
+# LLVM-MCA-END bar
+```
Note that multiple anonymous regions cannot overlap. Also, overlapping regions
cannot have the same name.
@@ -330,35 +326,34 @@ cannot have the same name.
There is no support for marking regions from high-level source code, like C or
C++. As a workaround, inline assembly directives may be used:
-.. code-block:: c++
-
- int foo(int a, int b) {
- __asm volatile("# LLVM-MCA-BEGIN foo":::"memory");
- a += 42;
- __asm volatile("# LLVM-MCA-END":::"memory");
- a *= b;
- return a;
- }
+```c++
+int foo(int a, int b) {
+ __asm volatile("# LLVM-MCA-BEGIN foo":::"memory");
+ a += 42;
+ __asm volatile("# LLVM-MCA-END":::"memory");
+ a *= b;
+ return a;
+}
+```
However, this interferes with optimizations like loop vectorization and may have
-an impact on the code generated. This is because the ``__asm`` statements are
+an impact on the code generated. This is because the `__asm` statements are
seen as real code having important side effects, which limits how the code
around them can be transformed. If users want to make use of inline assembly
to emit markers, then the recommendation is to always verify that the output
assembly is equivalent to the assembly generated in the absence of markers.
-The `Clang options to emit optimization reports <https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports>`_
+The [Clang options to emit optimization reports](https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports)
can also help in detecting missed optimizations.
-INSTRUMENT REGIONS
-------------------
+## INSTRUMENT REGIONS
An InstrumentRegion describes a region of assembly code guarded by
special LLVM-MCA comment directives.
-.. code-block:: none
-
- # LLVM-MCA-<INSTRUMENT_TYPE> <data>
- ... ## asm
+```none
+# LLVM-MCA-<INSTRUMENT_TYPE> <data>
+ ... ## asm
+```
where `INSTRUMENT_TYPE` is a type defined by the target and expects
to use `data`.
@@ -378,7 +373,7 @@ an InstrumentRegion does not need a comment to end the region.
Comments that are prefixed with `LLVM-MCA-` but do not correspond to
a valid `INSTRUMENT_TYPE` for the target cause an error, except for
`BEGIN` and `END`, since those correspond to AnalysisRegions. Comments
-that do not start with `LLVM-MCA-` are ignored by :program:`llvm-mca`.
+that do not start with `LLVM-MCA-` are ignored by {program}`llvm-mca`.
An instruction (a MCInst) is added to an InstrumentRegion R only
if its location is in range [R.RangeStart, R.RangeEnd].
@@ -387,11 +382,11 @@ There is one instrument that can be used on all targets to explicitly
set instruction latencies. It can be used, for example, to model the
cache misses that impact load latencies. The syntax is like
-.. code-block:: none
-
- # LLVM-MCA-LATENCY 100
- mov (%edi), %eax
- # LLVM-MCA-LATENCY
+```none
+# LLVM-MCA-LATENCY 100
+mov (%edi), %eax
+# LLVM-MCA-LATENCY
+```
It sets the latency of mov instruction to 100. LLVM-MCA-LATENCY without
argument ends the region with explicit latency, after it default target
@@ -401,9 +396,9 @@ On RISCV targets, vector instructions have different behaviour depending
on the LMUL. Code can be instrumented with a comment that takes the
following form:
-.. code-block:: none
-
- # LLVM-MCA-RISCV-LMUL <M1|M2|M4|M8|MF2|MF4|MF8>
+```none
+# LLVM-MCA-RISCV-LMUL <M1|M2|M4|M8|MF2|MF4|MF8>
+```
The RISCV InstrumentManager will override the schedule class for vector
instructions to use the scheduling behaviour of its pseudo-instruction
@@ -413,47 +408,46 @@ they can be placed anywhere in the program.
Example of program with no call to `vset{i}vl{i}`:
-.. code-block:: none
-
- # LLVM-MCA-RISCV-LMUL M2
- vadd.vv v2, v2, v2
+```none
+# LLVM-MCA-RISCV-LMUL M2
+vadd.vv v2, v2, v2
+```
Example of program with call to `vset{i}vl{i}`:
-.. code-block:: none
-
- vsetvli zero, a0, e8, m1, tu, mu
- # LLVM-MCA-RISCV-LMUL M1
- vadd.vv v2, v2, v2
+```none
+vsetvli zero, a0, e8, m1, tu, mu
+# LLVM-MCA-RISCV-LMUL M1
+vadd.vv v2, v2, v2
+```
Example of program with multiple calls to `vset{i}vl{i}`:
-.. code-block:: none
-
- vsetvli zero, a0, e8, m1, tu, mu
- # LLVM-MCA-RISCV-LMUL M1
- vadd.vv v2, v2, v2
- vsetvli zero, a0, e8, m8, tu, mu
- # LLVM-MCA-RISCV-LMUL M8
- vadd.vv v2, v2, v2
+```none
+vsetvli zero, a0, e8, m1, tu, mu
+# LLVM-MCA-RISCV-LMUL M1
+vadd.vv v2, v2, v2
+vsetvli zero, a0, e8, m8, tu, mu
+# LLVM-MCA-RISCV-LMUL M8
+vadd.vv v2, v2, v2
+```
Example of program with call to `vsetvl`:
-.. code-block:: none
-
- vsetvl rd, rs1, rs2
- # LLVM-MCA-RISCV-LMUL M1
- vadd.vv v12, v12, v12
- vsetvl rd, rs1, rs2
- # LLVM-MCA-RISCV-LMUL M4
- vadd.vv v12, v12, v12
+```none
+vsetvl rd, rs1, rs2
+# LLVM-MCA-RISCV-LMUL M1
+vadd.vv v12, v12, v12
+vsetvl rd, rs1, rs2
+# LLVM-MCA-RISCV-LMUL M4
+vadd.vv v12, v12, v12
+```
-HOW LLVM-MCA WORKS
-------------------
+## HOW LLVM-MCA WORKS
-:program:`llvm-mca` takes assembly code as input. The assembly code is parsed
+{program}`llvm-mca` takes assembly code as input. The assembly code is parsed
into a sequence of MCInst with the help of the existing LLVM target assembly
-parsers. The parsed sequence of MCInst is then analyzed by a ``Pipeline`` module
+parsers. The parsed sequence of MCInst is then analyzed by a `Pipeline` module
to generate a performance report.
The Pipeline module simulates the execution of the machine code sequence in a
@@ -463,76 +457,76 @@ pipeline generates and prints a report from the collected statistics.
Here is an example of a performance report generated by the tool for a
dot-product of two packed float vectors of four elements. The analysis is
-conducted for target x86, cpu btver2. The following result can be produced via
+conducted for target x86, cpu btver2. The following result can be produced via
the following command using the example located at
-``test/tools/llvm-mca/X86/BtVer2/dot-product.s``:
-
-.. code-block:: bash
-
- $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=300 dot-product.s
-
-.. code-block:: none
-
- Iterations: 300
- Instructions: 900
- Total Cycles: 610
- Total uOps: 900
-
- Dispatch Width: 2
- uOps Per Cycle: 1.48
- IPC: 1.48
- Block RThroughput: 2.0
-
-
- Instruction Info:
- [1]: #uOps
- [2]: Latency
- [3]: RThroughput
- [4]: MayLoad
- [5]: MayStore
- [6]: HasSideEffects (U)
-
- [1] [2] [3] [4] [5] [6] Instructions:
- 1 2 1.00 vmulps %xmm0, %xmm1, %xmm2
- 1 3 1.00 vhaddps %xmm2, %xmm2, %xmm3
- 1 3 1.00 vhaddps %xmm3, %xmm3, %xmm4
-
-
- Resources:
- [0] - JALU0
- [1] - JALU1
- [2] - JDiv
- [3] - JFPA
- [4] - JFPM
- [5] - JFPU0
- [6] - JFPU1
- [7] - JLAGU
- [8] - JMul
- [9] - JSAGU
- [10] - JSTC
- [11] - JVALU0
- [12] - JVALU1
- [13] - JVIMUL
-
-
- Resource pressure per iteration:
- [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]
- - - - 2.00 1.00 2.00 1.00 - - - - - - -
-
- Resource pressure by instruction:
- [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Instructions:
- - - - - 1.00 - 1.00 - - - - - - - vmulps %xmm0, %xmm1, %xmm2
- - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm2, %xmm2, %xmm3
- - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm3, %xmm3, %xmm4
+`test/tools/llvm-mca/X86/BtVer2/dot-product.s`:
+
+```bash
+$ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=300 dot-product.s
+```
+
+```none
+Iterations: 300
+Instructions: 900
+Total Cycles: 610
+Total uOps: 900
+
+Dispatch Width: 2
+uOps Per Cycle: 1.48
+IPC: 1.48
+Block RThroughput: 2.0
+
+
+Instruction Info:
+[1]: #uOps
+[2]: Latency
+[3]: RThroughput
+[4]: MayLoad
+[5]: MayStore
+[6]: HasSideEffects (U)
+
+[1] [2] [3] [4] [5] [6] Instructions:
+ 1 2 1.00 vmulps %xmm0, %xmm1, %xmm2
+ 1 3 1.00 vhaddps %xmm2, %xmm2, %xmm3
+ 1 3 1.00 vhaddps %xmm3, %xmm3, %xmm4
+
+
+Resources:
+[0] - JALU0
+[1] - JALU1
+[2] - JDiv
+[3] - JFPA
+[4] - JFPM
+[5] - JFPU0
+[6] - JFPU1
+[7] - JLAGU
+[8] - JMul
+[9] - JSAGU
+[10] - JSTC
+[11] - JVALU0
+[12] - JVALU1
+[13] - JVIMUL
+
+
+Resource pressure per iteration:
+[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]
+ - - - 2.00 1.00 2.00 1.00 - - - - - - -
+
+Resource pressure by instruction:
+[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Instructions:
+ - - - - 1.00 - 1.00 - - - - - - - vmulps %xmm0, %xmm1, %xmm2
+ - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm2, %xmm2, %xmm3
+ - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm3, %xmm3, %xmm4
+```
According to this report, the dot-product kernel has been executed 300 times,
for a total of 900 simulated instructions. The total number of simulated micro
opcodes (uOps) is also 900.
-The report is structured in three main sections. The first section collects a
+The report is structured in three main sections. The first section collects a
few performance numbers; the goal of this section is to give a very quick
overview of the performance throughput. Important performance indicators are
-**IPC**, **uOps Per Cycle**, and **Block RThroughput** (Block Reciprocal
+**IPC**, **uOps Per Cycle**, and **Block RThroughput** (Block Reciprocal
Throughput).
Field *DispatchWidth* is the maximum number of micro opcodes that are dispatched
@@ -565,13 +559,13 @@ because the dispatch width limits the maximum size of a dispatch group. Both IPC
and 'uOps Per Cycle' are limited by the amount of hardware parallelism. The
availability of hardware resources affects the resource pressure distribution,
and it limits the number of instructions that can be executed in parallel every
-cycle. A delta between Dispatch Width and the theoretical maximum uOps per
+cycle. A delta between Dispatch Width and the theoretical maximum uOps per
Cycle (computed by dividing the number of uOps of a single iteration by the
`Block RThroughput`) is an indicator of a performance bottleneck caused by the
lack of hardware resources.
In general, the lower the Block RThroughput, the better.
-In this example, ``uOps per iteration/Block RThroughput`` is 1.50. Since there
+In this example, `uOps per iteration/Block RThroughput` is 1.50. Since there
are no loop-carried dependencies, the observed `uOps Per Cycle` is expected to
approach 1.50 when the number of iterations tends to infinity. The delta between
the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is
@@ -588,7 +582,7 @@ Field *RThroughput* is the reciprocal of the instruction throughput. Throughput
is computed as the maximum number of instructions of a same type that can be
executed per clock cycle in the absence of operand dependencies. In this
example, the reciprocal throughput of a vector float multiply is 1
-cycles/instruction. That is because the FP multiplier JFPM is only available
+cycles/instruction. That is because the FP multiplier JFPM is only available
from pipeline JFPU1.
Instruction encodings are displayed within the instruction info view when flag
@@ -596,100 +590,100 @@ Instruction encodings are displayed within the instruction info view when flag
Below is an example of `-show-encoding` output for the dot-product kernel:
-.. code-block:: none
-
- Instruction Info:
- [1]: #uOps
- [2]: Latency
- [3]: RThroughput
- [4]: MayLoad
- [5]: MayStore
- [6]: HasSideEffects (U)
- [7]: Encoding Size
-
- [1] [2] [3] [4] [5] [6] [7] Encodings: Instructions:
- 1 2 1.00 4 c5 f0 59 d0 vmulps %xmm0, %xmm1, %xmm2
- 1 4 1.00 4 c5 eb 7c da vhaddps %xmm2, %xmm2, %xmm3
- 1 4 1.00 4 c5 e3 7c e3 vhaddps %xmm3, %xmm3, %xmm4
-
-The `Encoding Size` column shows the size in bytes of instructions. The
+```none
+Instruction Info:
+[1]: #uOps
+[2]: Latency
+[3]: RThroughput
+[4]: MayLoad
+[5]: MayStore
+[6]: HasSideEffects (U)
+[7]: Encoding Size
+
+[1] [2] [3] [4] [5] [6] [7] Encodings: Instructions:
+ 1 2 1.00 4 c5 f0 59 d0 vmulps %xmm0, %xmm1, %xmm2
+ 1 4 1.00 4 c5 eb 7c da vhaddps %xmm2, %xmm2, %xmm3
+ 1 4 1.00 4 c5 e3 7c e3 vhaddps %xmm3, %xmm3, %xmm4
+```
+
+The `Encoding Size` column shows the size in bytes of instructions. The
`Encodings` column shows the actual instruction encodings (byte sequences in
hex).
-The third section is the *Resource pressure view*. This view reports
+The third section is the *Resource pressure view*. This view reports
the average number of resource cycles consumed every iteration by instructions
-for every processor resource unit available on the target. Information is
+for every processor resource unit available on the target. Information is
structured in two tables. The first table reports the number of resource cycles
spent on average every iteration. The second table correlates the resource
cycles to the machine instruction in the sequence. For example, every iteration
of the instruction vmulps always executes on resource unit [6]
(JFPU1 - floating point pipeline #1), consuming an average of 1 resource cycle
-per iteration. Note that on AMD Jaguar, vector floating-point multiply can
+per iteration. Note that on AMD Jaguar, vector floating-point multiply can
only be issued to pipeline JFPU1, while horizontal floating-point additions can
only be issued to pipeline JFPU0.
The resource pressure view helps with identifying bottlenecks caused by high
-usage of specific hardware resources. Situations with resource pressure mainly
-concentrated on a few resources should, in general, be avoided. Ideally,
+usage of specific hardware resources. Situations with resource pressure mainly
+concentrated on a few resources should, in general, be avoided. Ideally,
pressure should be uniformly distributed between multiple resources.
-Timeline View
-^^^^^^^^^^^^^
+### Timeline View
+
The timeline view produces a detailed report of each instruction's state
-transitions through an instruction pipeline. This view is enabled by the
-command line option ``-timeline``. As instructions transition through the
+transitions through an instruction pipeline. This view is enabled by the
+command line option `-timeline`. As instructions transition through the
various stages of the pipeline, their states are depicted in the view report.
These states are represented by the following characters:
-* D : Instruction dispatched.
-* e : Instruction executing.
-* E : Instruction executed.
-* R : Instruction retired.
-* = : Instruction already dispatched, waiting to be executed.
-* \- : Instruction executed, waiting to be retired.
+- D : Instruction dispatched.
+- e : Instruction executing.
+- E : Instruction executed.
+- R : Instruction retired.
+- = : Instruction already dispatched, waiting to be executed.
+- \- : Instruction executed, waiting to be retired.
Below is the timeline view for a subset of the dot-product example located in
-``test/tools/llvm-mca/X86/BtVer2/dot-product.s`` and processed by
-:program:`llvm-mca` using the following command:
-
-.. code-block:: bash
-
- $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=3 -timeline dot-product.s
-
-.. code-block:: none
-
- Timeline view:
- 012345
- Index 0123456789
-
- [0,0] DeeER. . . vmulps %xmm0, %xmm1, %xmm2
- [0,1] D==eeeER . . vhaddps %xmm2, %xmm2, %xmm3
- [0,2] .D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
- [1,0] .DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
- [1,1] . D=eeeE---R . vhaddps %xmm2, %xmm2, %xmm3
- [1,2] . D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
- [2,0] . DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
- [2,1] . D====eeeER . vhaddps %xmm2, %xmm2, %xmm3
- [2,2] . D======eeeER vhaddps %xmm3, %xmm3, %xmm4
-
-
- Average Wait times (based on the timeline view):
- [0]: Executions
- [1]: Average time spent waiting in a scheduler's queue
- [2]: Average time spent waiting in a scheduler's queue while ready
- [3]: Average time elapsed from WB until retire stage
-
- [0] [1] [2] [3]
- 0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2
- 1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3
- 2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4
- 9 3.3 0.5 1.4 <total>
+`test/tools/llvm-mca/X86/BtVer2/dot-product.s` and processed by
+{program}`llvm-mca` using the following command:
+
+```bash
+$ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=3 -timeline dot-product.s
+```
+
+```none
+Timeline view:
+ 012345
+Index 0123456789
+
+[0,0] DeeER. . . vmulps %xmm0, %xmm1, %xmm2
+[0,1] D==eeeER . . vhaddps %xmm2, %xmm2, %xmm3
+[0,2] .D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
+[1,0] .DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
+[1,1] . D=eeeE---R . vhaddps %xmm2, %xmm2, %xmm3
+[1,2] . D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
+[2,0] . DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
+[2,1] . D====eeeER . vhaddps %xmm2, %xmm2, %xmm3
+[2,2] . D======eeeER vhaddps %xmm3, %xmm3, %xmm4
+
+
+Average Wait times (based on the timeline view):
+[0]: Executions
+[1]: Average time spent waiting in a scheduler's queue
+[2]: Average time spent waiting in a scheduler's queue while ready
+[3]: Average time elapsed from WB until retire stage
+
+ [0] [1] [2] [3]
+0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2
+1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3
+2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4
+ 9 3.3 0.5 1.4 <total>
+```
The timeline view is interesting because it shows instruction state changes
-during execution. It also gives an idea of how the tool processes instructions
+during execution. It also gives an idea of how the tool processes instructions
executed on the target, and how their timing information might be calculated.
-The timeline view is structured in two tables. The first table shows
+The timeline view is structured in two tables. The first table shows
instructions changing state over time (measured in cycles); the second table
(named *Average Wait times*) reports useful timing statistics, which should
help diagnose performance bottlenecks caused by long data dependencies and
@@ -697,8 +691,8 @@ sub-optimal usage of hardware resources.
An instruction in the timeline view is identified by a pair of indices, where
the first index identifies an iteration, and the second index is the
-instruction index (i.e., where it appears in the code sequence). Since this
-example was generated using 3 iterations: ``-iterations=3``, the iteration
+instruction index (i.e., where it appears in the code sequence). Since this
+example was generated using 3 iterations: `-iterations=3`, the iteration
indices range from 0-2 inclusively.
Excluding the first and last column, the remaining columns are in cycles.
@@ -706,15 +700,15 @@ Cycles are numbered sequentially starting from 0.
From the example output above, we know the following:
-* Instruction [1,0] was dispatched at cycle 1.
-* Instruction [1,0] started executing at cycle 2.
-* Instruction [1,0] reached the write back stage at cycle 4.
-* Instruction [1,0] was retired at cycle 10.
+- Instruction [1,0] was dispatched at cycle 1.
+- Instruction [1,0] started executing at cycle 2.
+- Instruction [1,0] reached the write back stage at cycle 4.
+- Instruction [1,0] was retired at cycle 10.
Instruction [1,0] (i.e., vmulps from iteration #1) does not have to wait in the
scheduler's queue for the operands to become available. By the time vmulps is
dispatched, operands are already available, and pipeline JFPU1 is ready to
-serve another instruction. So the instruction can be immediately issued on the
+serve another instruction. So the instruction can be immediately issued on the
JFPU1 pipeline. That is demonstrated by the fact that the instruction only
spent 1cy in the scheduler's queue.
@@ -723,74 +717,72 @@ That is because instructions must retire in program order, so [1,0] has to wait
for [0,2] to be retired first (i.e., it has to wait until cycle 10).
In the example, all instructions are in a RAW (Read After Write) dependency
-chain. Register %xmm2 written by vmulps is immediately used by the first
+chain. Register %xmm2 written by vmulps is immediately used by the first
vhaddps, and register %xmm3 written by the first vhaddps is used by the second
-vhaddps. Long data dependencies negatively impact the ILP (Instruction Level
+vhaddps. Long data dependencies negatively impact the ILP (Instruction Level
Parallelism).
In the dot-product example, there are anti-dependencies introduced by
-instructions from different iterations. However, those dependencies can be
+instructions from different iterations. However, those dependencies can be
removed at register renaming stage (at the cost of allocating register aliases,
and therefore consuming physical registers).
Table *Average Wait times* helps diagnose performance issues that are caused by
the presence of long latency instructions and potentially long data dependencies
-which may limit the ILP. Last row, ``<total>``, shows a global average over all
-instructions measured. Note that :program:`llvm-mca`, by default, assumes at
+which may limit the ILP. Last row, `<total>`, shows a global average over all
+instructions measured. Note that {program}`llvm-mca`, by default, assumes at
least 1cy between the dispatch event and the issue event.
When the performance is limited by data dependencies and/or long latency
instructions, the number of cycles spent while in the *ready* state is expected
to be very small when compared with the total number of cycles spent in the
-scheduler's queue. The difference between the two counters is a good indicator
+scheduler's queue. The difference between the two counters is a good indicator
of how large of an impact data dependencies had on the execution of the
-instructions. When performance is mostly limited by the lack of hardware
-resources, the delta between the two counters is small. However, the number of
+instructions. When performance is mostly limited by the lack of hardware
+resources, the delta between the two counters is small. However, the number of
cycles spent in the queue tends to be larger (i.e., more than 1-3cy),
especially when compared to other low latency instructions.
-Bottleneck Analysis
-^^^^^^^^^^^^^^^^^^^
-The ``-bottleneck-analysis`` command line option enables the analysis of
+### Bottleneck Analysis
+
+The `-bottleneck-analysis` command line option enables the analysis of
performance bottlenecks.
This analysis is potentially expensive. It attempts to correlate increases in
backend pressure (caused by pipeline resource pressure and data dependencies) to
dynamic dispatch stalls.
-Below is an example of ``-bottleneck-analysis`` output generated by
-:program:`llvm-mca` for 500 iterations of the dot-product example on btver2.
-
-.. code-block:: none
-
-
- Cycles with backend pressure increase [ 48.07% ]
- Throughput Bottlenecks:
- Resource Pressure [ 47.77% ]
- - JFPA [ 47.77% ]
- - JFPU0 [ 47.77% ]
- Data Dependencies: [ 0.30% ]
- - Register Dependencies [ 0.30% ]
- - Memory Dependencies [ 0.00% ]
-
- Critical sequence based on the simulation:
-
- Instruction Dependency Information
- +----< 2. vhaddps %xmm3, %xmm3, %xmm4
- |
- | < loop carried >
- |
- | 0. vmulps %xmm0, %xmm1, %xmm2
- +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ]
- +----> 2. vhaddps %xmm3, %xmm3, %xmm4 ## REGISTER dependency: %xmm3
- |
- | < loop carried >
- |
- +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ]
-
+Below is an example of `-bottleneck-analysis` output generated by
+{program}`llvm-mca` for 500 iterations of the dot-product example on btver2.
+
+```none
+Cycles with backend pressure increase [ 48.07% ]
+Throughput Bottlenecks:
+ Resource Pressure [ 47.77% ]
+ - JFPA [ 47.77% ]
+ - JFPU0 [ 47.77% ]
+ Data Dependencies: [ 0.30% ]
+ - Register Dependencies [ 0.30% ]
+ - Memory Dependencies [ 0.00% ]
+
+Critical sequence based on the simulation:
+
+ Instruction Dependency Information
+ +----< 2. vhaddps %xmm3, %xmm3, %xmm4
+ |
+ | < loop carried >
+ |
+ | 0. vmulps %xmm0, %xmm1, %xmm2
+ +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ]
+ +----> 2. vhaddps %xmm3, %xmm3, %xmm4 ## REGISTER dependency: %xmm3
+ |
+ | < loop carried >
+ |
+ +----> 1. vhaddps %xmm2, %xmm2, %xmm3 ## RESOURCE interference: JFPA [ probability: 74% ]
+```
According to the analysis, throughput is limited by resource pressure and not by
-data dependencies. The analysis observed increases in backend pressure during
+data dependencies. The analysis observed increases in backend pressure during
48.07% of the simulated run. Almost all those pressure increase events were
caused by contention on processor resources JFPA/JFPU0.
@@ -806,86 +798,86 @@ model in llvm.
Bottleneck analysis is currently not supported for processors with an in-order
backend.
-Extra Statistics to Further Diagnose Performance Issues
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``-all-stats`` command line option enables extra statistics and performance
+### Extra Statistics to Further Diagnose Performance Issues
+
+The `-all-stats` command line option enables extra statistics and performance
counters for the dispatch logic, the reorder buffer, the retire control unit,
and the register file.
-Below is an example of ``-all-stats`` output generated by :program:`llvm-mca`
+Below is an example of `-all-stats` output generated by {program}`llvm-mca`
for 300 iterations of the dot-product example discussed in the previous
sections.
-.. code-block:: none
-
- Dynamic Dispatch Stall Cycles:
- RAT - Register unavailable: 0
- RCU - Retire tokens unavailable: 0
- SCHEDQ - Scheduler full: 272 (44.6%)
- LQ - Load queue full: 0
- SQ - Store queue full: 0
- GROUP - Static restrictions on the dispatch group: 0
+```none
+Dynamic Dispatch Stall Cycles:
+RAT - Register unavailable: 0
+RCU - Retire tokens unavailable: 0
+SCHEDQ - Scheduler full: 272 (44.6%)
+LQ - Load queue full: 0
+SQ - Store queue full: 0
+GROUP - Static restrictions on the dispatch group: 0
- Dispatch Logic - number of cycles where we saw N micro opcodes dispatched:
- [# dispatched], [# cycles]
- 0, 24 (3.9%)
- 1, 272 (44.6%)
- 2, 314 (51.5%)
+Dispatch Logic - number of cycles where we saw N micro opcodes dispatched:
+[# dispatched], [# cycles]
+ 0, 24 (3.9%)
+ 1, 272 (44.6%)
+ 2, 314 (51.5%)
- Schedulers - number of cycles where we saw N micro opcodes issued:
- [# issued], [# cycles]
- 0, 7 (1.1%)
- 1, 306 (50.2%)
- 2, 297 (48.7%)
+Schedulers - number of cycles where we saw N micro opcodes issued:
+[# issued], [# cycles]
+ 0, 7 (1.1%)
+ 1, 306 (50.2%)
+ 2, 297 (48.7%)
- Scheduler's queue usage:
- [1] Resource name.
- [2] Average number of used buffer entries.
- [3] Maximum number of used buffer entries.
- [4] Total number of buffer entries.
+Scheduler's queue usage:
+[1] Resource name.
+[2] Average number of used buffer entries.
+[3] Maximum number of used buffer entries.
+[4] Total number of buffer entries.
- [1] [2] [3] [4]
- JALU01 0 0 20
- JFPU01 17 18 18
- JLSAGU 0 0 12
+ [1] [2] [3] [4]
+JALU01 0 0 20
+JFPU01 17 18 18
+JLSAGU 0 0 12
- Retire Control Unit - number of cycles where we saw N instructions retired:
- [# retired], [# cycles]
- 0, 109 (17.9%)
- 1, 102 (16.7%)
- 2, 399 (65.4%)
+Retire Control Unit - number of cycles where we saw N instructions retired:
+[# retired], [# cycles]
+ 0, 109 (17.9%)
+ 1, 102 (16.7%)
+ 2, 399 (65.4%)
- Total ROB Entries: 64
- Max Used ROB Entries: 35 ( 54.7% )
- Average Used ROB Entries per cy: 32 ( 50.0% )
+Total ROB Entries: 64
+Max Used ROB Entries: 35 ( 54.7% )
+Average Used ROB Entries per cy: 32 ( 50.0% )
- Register File statistics:
- Total number of mappings created: 900
- Max number of mappings used: 35
+Register File statistics:
+Total number of mappings created: 900
+Max number of mappings used: 35
- * Register File #1 -- JFpuPRF:
- Number of physical registers: 72
- Total number of mappings created: 900
- Max number of mappings used: 35
+* Register File #1 -- JFpuPRF:
+ Number of physical registers: 72
+ Total number of mappings created: 900
+ Max number of mappings used: 35
- * Register File #2 -- JIntegerPRF:
- Number of physical registers: 64
- Total number of mappings created: 0
- Max number of mappings used: 0
+* Register File #2 -- JIntegerPRF:
+ Number of physical registers: 64
+ Total number of mappings created: 0
+ Max number of mappings used: 0
+```
If we look at the *Dynamic Dispatch Stall Cycles* table, we see the counter for
-SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch
+SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch
logic is unable to dispatch a full group because the scheduler's queue is full.
Looking at the *Dispatch Logic* table, we see that the pipeline was only able to
-dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to
-one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The
+dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to
+one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The
dispatch statistics are displayed by either using the command option
-``-all-stats`` or ``-dispatch-stats``.
+`-all-stats` or `-dispatch-stats`.
The next table, *Schedulers*, presents a histogram displaying a count,
representing the number of micro opcodes issued on some number of cycles. In
@@ -893,134 +885,134 @@ this case, of the 610 simulated cycles, single opcodes were issued 306 times
(50.2%) and there were 7 cycles where no opcodes were issued.
The *Scheduler's queue usage* table shows that the average and maximum number of
-buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01
+buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01
reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements
three schedulers:
-* JALU01 - A scheduler for ALU instructions.
-* JFPU01 - A scheduler floating point operations.
-* JLSAGU - A scheduler for address generation.
+- JALU01 - A scheduler for ALU instructions.
+- JFPU01 - A scheduler floating point operations.
+- JLSAGU - A scheduler for address generation.
The dot-product is a kernel of three floating point instructions (a vector
-multiply followed by two horizontal adds). That explains why only the floating
+multiply followed by two horizontal adds). That explains why only the floating
point scheduler appears to be used.
A full scheduler queue is either caused by data dependency chains or by a
-sub-optimal usage of hardware resources. Sometimes, resource pressure can be
+sub-optimal usage of hardware resources. Sometimes, resource pressure can be
mitigated by rewriting the kernel using different instructions that consume
-different scheduler resources. Schedulers with a small queue are less resilient
-to bottlenecks caused by the presence of long data dependencies. The scheduler
-statistics are displayed by using the command option ``-all-stats`` or
-``-scheduler-stats``.
+different scheduler resources. Schedulers with a small queue are less resilient
+to bottlenecks caused by the presence of long data dependencies. The scheduler
+statistics are displayed by using the command option `-all-stats` or
+`-scheduler-stats`.
The next table, *Retire Control Unit*, presents a histogram displaying a count,
-representing the number of instructions retired on some number of cycles. In
+representing the number of instructions retired on some number of cycles. In
this case, of the 610 simulated cycles, two instructions were retired during the
same cycle 399 times (65.4%) and there were 109 cycles where no instructions
-were retired. The retire statistics are displayed by using the command option
-``-all-stats`` or ``-retire-stats``.
+were retired. The retire statistics are displayed by using the command option
+`-all-stats` or `-retire-stats`.
-The last table presented is *Register File statistics*. Each physical register
-file (PRF) used by the pipeline is presented in this table. In the case of AMD
+The last table presented is *Register File statistics*. Each physical register
+file (PRF) used by the pipeline is presented in this table. In the case of AMD
Jaguar, there are two register files, one for floating-point registers (JFpuPRF)
-and one for integer registers (JIntegerPRF). The table shows that of the 900
-instructions processed, there were 900 mappings created. Since this dot-product
+and one for integer registers (JIntegerPRF). The table shows that of the 900
+instructions processed, there were 900 mappings created. Since this dot-product
example utilized only floating point registers, the JFPuPRF was responsible for
-creating the 900 mappings. However, we see that the pipeline only used a
+creating the 900 mappings. However, we see that the pipeline only used a
maximum of 35 of 72 available register slots at any given time. We can conclude
that the floating point PRF was the only register file used for the example, and
-that it was never resource constrained. The register file statistics are
-displayed by using the command option ``-all-stats`` or
-``-register-file-stats``.
+that it was never resource constrained. The register file statistics are
+displayed by using the command option `-all-stats` or
+`-register-file-stats`.
In this example, we can conclude that the IPC is mostly limited by data
dependencies, and not by resource pressure.
-Instruction Flow
-^^^^^^^^^^^^^^^^
+### Instruction Flow
+
This section describes the instruction flow through the default pipeline of
-:program:`llvm-mca`, as well as the functional units involved in the process.
+{program}`llvm-mca`, as well as the functional units involved in the process.
The default pipeline implements the following sequence of stages used to
process instructions.
-* Dispatch (Instruction is dispatched to the schedulers).
-* Issue (Instruction is issued to the processor pipelines).
-* Write Back (Instruction is executed, and results are written back).
-* Retire (Instruction is retired; writes are architecturally committed).
+- Dispatch (Instruction is dispatched to the schedulers).
+- Issue (Instruction is issued to the processor pipelines).
+- Write Back (Instruction is executed, and results are written back).
+- Retire (Instruction is retired; writes are architecturally committed).
The in-order pipeline implements the following sequence of stages:
-* InOrderIssue (Instruction is issued to the processor pipelines).
-* Retire (Instruction is retired; writes are architecturally committed).
+- InOrderIssue (Instruction is issued to the processor pipelines).
+- Retire (Instruction is retired; writes are architecturally committed).
-:program:`llvm-mca` assumes that instructions have all been decoded and placed
+{program}`llvm-mca` assumes that instructions have all been decoded and placed
into a queue before the simulation start. Therefore, the instruction fetch and
decode stages are not modeled. Performance bottlenecks in the frontend are not
-diagnosed. Also, :program:`llvm-mca` does not model branch prediction.
+diagnosed. Also, {program}`llvm-mca` does not model branch prediction.
+
+#### Instruction Dispatch
-Instruction Dispatch
-""""""""""""""""""""
During the dispatch stage, instructions are picked in program order from a
queue of already decoded instructions, and dispatched in groups to the
simulated hardware schedulers.
The size of a dispatch group depends on the availability of the simulated
-hardware resources. The processor dispatch width defaults to the value
-of the ``IssueWidth`` in LLVM's scheduling model.
+hardware resources. The processor dispatch width defaults to the value
+of the `IssueWidth` in LLVM's scheduling model.
An instruction can be dispatched if:
-* The size of the dispatch group is smaller than processor's dispatch width.
-* There are enough entries in the reorder buffer.
-* There are enough physical registers to do register renaming.
-* The schedulers are not full.
+- The size of the dispatch group is smaller than processor's dispatch width.
+- There are enough entries in the reorder buffer.
+- There are enough physical registers to do register renaming.
+- The schedulers are not full.
Scheduling models can optionally specify which register files are available on
-the processor. :program:`llvm-mca` uses that information to initialize register
-file descriptors. Users can limit the number of physical registers that are
+the processor. {program}`llvm-mca` uses that information to initialize register
+file descriptors. Users can limit the number of physical registers that are
globally available for register renaming by using the command option
-``-register-file-size``. A value of zero for this option means *unbounded*. By
+`-register-file-size`. A value of zero for this option means *unbounded*. By
knowing how many registers are available for renaming, the tool can predict
dispatch stalls caused by the lack of physical registers.
The number of reorder buffer entries consumed by an instruction depends on the
number of micro-opcodes specified for that instruction by the target scheduling
-model. The reorder buffer is responsible for tracking the progress of
-instructions that are "in-flight", and retiring them in program order. The
+model. The reorder buffer is responsible for tracking the progress of
+instructions that are "in-flight", and retiring them in program order. The
number of entries in the reorder buffer defaults to the value specified by field
`MicroOpBufferSize` in the target scheduling model.
Instructions that are dispatched to the schedulers consume scheduler buffer
-entries. :program:`llvm-mca` queries the scheduling model to determine the set
-of buffered resources consumed by an instruction. Buffered resources are
+entries. {program}`llvm-mca` queries the scheduling model to determine the set
+of buffered resources consumed by an instruction. Buffered resources are
treated like scheduler resources.
-Instruction Issue
-"""""""""""""""""
-Each processor scheduler implements a buffer of instructions. An instruction
+#### Instruction Issue
+
+Each processor scheduler implements a buffer of instructions. An instruction
has to wait in the scheduler's buffer until input register operands become
-available. Only at that point, does the instruction becomes eligible for
+available. Only at that point, does the instruction becomes eligible for
execution and may be issued (potentially out-of-order) for execution.
-Instruction latencies are computed by :program:`llvm-mca` with the help of the
+Instruction latencies are computed by {program}`llvm-mca` with the help of the
scheduling model.
-:program:`llvm-mca`'s scheduler is designed to simulate multiple processor
-schedulers. The scheduler is responsible for tracking data dependencies, and
+{program}`llvm-mca`'s scheduler is designed to simulate multiple processor
+schedulers. The scheduler is responsible for tracking data dependencies, and
dynamically selecting which processor resources are consumed by instructions.
It delegates the management of processor resource units and resource groups to a
-resource manager. The resource manager is responsible for selecting resource
-units that are consumed by instructions. For example, if an instruction
+resource manager. The resource manager is responsible for selecting resource
+units that are consumed by instructions. For example, if an instruction
consumes 1cy of a resource group, the resource manager selects one of the
available units from the group; by default, the resource manager uses a
round-robin selector to guarantee that resource usage is uniformly distributed
between all units of a group.
-:program:`llvm-mca`'s scheduler internally groups instructions into three sets:
+{program}`llvm-mca`'s scheduler internally groups instructions into three sets:
-* WaitSet: a set of instructions whose operands are not ready.
-* ReadySet: a set of instructions ready to execute.
-* IssuedSet: a set of instructions executing.
+- WaitSet: a set of instructions whose operands are not ready.
+- ReadySet: a set of instructions ready to execute.
+- IssuedSet: a set of instructions executing.
Depending on the operands availability, instructions that are dispatched to the
scheduler are either placed into the WaitSet or into the ReadySet.
@@ -1030,27 +1022,27 @@ to the ReadySet, and if instructions from the ReadySet can be issued to the
underlying pipelines. The algorithm prioritizes older instructions over younger
instructions.
-Write-Back and Retire Stage
-"""""""""""""""""""""""""""
-Issued instructions are moved from the ReadySet to the IssuedSet. There,
-instructions wait until they reach the write-back stage. At that point, they
+#### Write-Back and Retire Stage
+
+Issued instructions are moved from the ReadySet to the IssuedSet. There,
+instructions wait until they reach the write-back stage. At that point, they
get removed from the queue and the retire control unit is notified.
When instructions are executed, the retire control unit flags the instruction as
"ready to retire."
-Instructions are retired in program order. The register file is notified of the
+Instructions are retired in program order. The register file is notified of the
retirement so that it can free the physical registers that were allocated for
the instruction during the register renaming stage.
-Load/Store Unit and Memory Consistency Model
-""""""""""""""""""""""""""""""""""""""""""""
-To simulate an out-of-order execution of memory operations, :program:`llvm-mca`
+#### Load/Store Unit and Memory Consistency Model
+
+To simulate an out-of-order execution of memory operations, {program}`llvm-mca`
utilizes a simulated load/store unit (LSUnit) to simulate the speculative
execution of loads and stores.
Each load (or store) consumes an entry in the load (or store) queue. Users can
-specify flags ``-lqueue`` and ``-squeue`` to limit the number of entries in the
+specify flags `-lqueue` and `-squeue` to limit the number of entries in the
load and store queues respectively. The queues are unbounded by default.
The LSUnit implements a relaxed consistency model for memory loads and stores.
@@ -1064,32 +1056,32 @@ The rules are:
4. A younger store is not allowed to pass an older load.
By default, the LSUnit optimistically assumes that loads do not alias
-(`-noalias=true`) store operations. Under this assumption, younger loads are
-always allowed to pass older stores. Essentially, the LSUnit does not attempt
+(`-noalias=true`) store operations. Under this assumption, younger loads are
+always allowed to pass older stores. Essentially, the LSUnit does not attempt
to run any alias analysis to predict when loads and stores do not alias with
each other.
Note that, in the case of write-combining memory, rule 3 could be relaxed to
-allow reordering of non-aliasing store operations. That being said, at the
-moment, there is no way to further relax the memory model (``-noalias`` is the
-only option). Essentially, there is no option to specify a different memory
+allow reordering of non-aliasing store operations. That being said, at the
+moment, there is no way to further relax the memory model (`-noalias` is the
+only option). Essentially, there is no option to specify a different memory
type (e.g., write-back, write-combining, write-through; etc.) and consequently
to weaken, or strengthen, the memory model.
Other limitations are:
-* The LSUnit does not know when store-to-load forwarding may occur.
-* The LSUnit does not know anything about cache hierarchy and memory types.
-* The LSUnit does not know how to identify serializing operations and memory
+- The LSUnit does not know when store-to-load forwarding may occur.
+- The LSUnit does not know anything about cache hierarchy and memory types.
+- The LSUnit does not know how to identify serializing operations and memory
fences.
The LSUnit does not attempt to predict if a load or store hits or misses the L1
-cache. It only knows if an instruction "MayLoad" and/or "MayStore." For
+cache. It only knows if an instruction "MayLoad" and/or "MayStore." For
loads, the scheduling model provides an "optimistic" load-to-use latency (which
usually matches the load-to-use latency for when there is a hit in the L1D).
-:program:`llvm-mca` does not (on its own) know about serializing operations or
-memory-barrier like instructions. The LSUnit used to conservatively use an
+{program}`llvm-mca` does not (on its own) know about serializing operations or
+memory-barrier like instructions. The LSUnit used to conservatively use an
instruction's "MayLoad", "MayStore", and unmodeled side effects flags to
determine whether an instruction should be treated as a memory-barrier. This was
inaccurate in general and was changed so that now each instruction has an
@@ -1099,48 +1091,48 @@ these flags set, it should be done within the target's InstrPostProcess class.
For an example, look at the `X86InstrPostProcess::postProcessInstruction` method
within `llvm/lib/Target/X86/MCA/X86CustomBehaviour.cpp`.
-A load/store barrier consumes one entry of the load/store queue. A load/store
-barrier enforces ordering of loads/stores. A younger load cannot pass a load
-barrier. Also, a younger store cannot pass a store barrier. A younger load
-has to wait for the memory/load barrier to execute. A load/store barrier is
+A load/store barrier consumes one entry of the load/store queue. A load/store
+barrier enforces ordering of loads/stores. A younger load cannot pass a load
+barrier. Also, a younger store cannot pass a store barrier. A younger load
+has to wait for the memory/load barrier to execute. A load/store barrier is
"executed" when it becomes the oldest entry in the load/store queue(s). That
also means, by construction, all of the older loads/stores have been executed.
In conclusion, the full set of load/store consistency rules are:
-#. A store may not pass a previous store.
-#. A store may not pass a previous load (regardless of ``-noalias``).
-#. A store has to wait until an older store barrier is fully executed.
-#. A load may pass a previous load.
-#. A load may not pass a previous store unless ``-noalias`` is set.
-#. A load has to wait until an older load barrier is fully executed.
+1. A store may not pass a previous store.
+2. A store may not pass a previous load (regardless of `-noalias`).
+3. A store has to wait until an older store barrier is fully executed.
+4. A load may pass a previous load.
+5. A load may not pass a previous store unless `-noalias` is set.
+6. A load has to wait until an older load barrier is fully executed.
-In-order Issue and Execute
-""""""""""""""""""""""""""""""""""""
-In-order processors are modelled as a single ``InOrderIssueStage`` stage. It
+#### In-order Issue and Execute
+
+In-order processors are modelled as a single `InOrderIssueStage` stage. It
bypasses Dispatch, Scheduler and Load/Store unit. Instructions are issued as
soon as their operand registers are available and resource requirements are
met. Multiple instructions can be issued in one cycle according to the value of
-the ``IssueWidth`` parameter in LLVM's scheduling model.
+the `IssueWidth` parameter in LLVM's scheduling model.
-Once issued, an instruction is moved to ``IssuedInst`` set until it is ready to
-retire. :program:`llvm-mca` ensures that writes are committed in-order. However,
+Once issued, an instruction is moved to `IssuedInst` set until it is ready to
+retire. {program}`llvm-mca` ensures that writes are committed in-order. However,
an instruction is allowed to commit writes and retire out-of-order if
-``RetireOOO`` property is true for at least one of its writes.
+`RetireOOO` property is true for at least one of its writes.
+
+#### Custom Behaviour
-Custom Behaviour
-""""""""""""""""""""""""""""""""""""
Due to certain instructions not being expressed perfectly within their
-scheduling model, :program:`llvm-mca` isn't always able to simulate them
+scheduling model, {program}`llvm-mca` isn't always able to simulate them
perfectly. Modifying the scheduling model isn't always a viable
option though (maybe because the instruction is modeled incorrectly on
purpose or the instruction's behaviour is quite complex). The
CustomBehaviour class can be used in these cases to enforce proper
instruction modeling (often by customizing data dependencies and detecting
-hazards that :program:`llvm-mca` has no way of knowing about).
+hazards that {program}`llvm-mca` has no way of knowing about).
-:program:`llvm-mca` comes with one generic and multiple target-specific
-CustomBehaviour classes. The generic class will be used if the ``-disable-cb``
+{program}`llvm-mca` comes with one generic and multiple target-specific
+CustomBehaviour classes. The generic class will be used if the `-disable-cb`
flag is used or if a target-specific CustomBehaviour class doesn't exist for
that target. (The generic class does nothing.) Currently, the CustomBehaviour
class is only a part of the in-order pipeline, but there are plans to add it
@@ -1158,8 +1150,8 @@ already have one, refer to an existing implementation to see how to set it
up. The classes are implemented within the target-specific backend (for
example `/llvm/lib/Target/AMDGPU/MCA/`) so that they can access backend symbols.
-Instrument Manager
-""""""""""""""""""""""""""""""""""""
+#### Instrument Manager
+
On certain architectures, scheduling information for certain instructions
do not contain all of the information required to identify the most precise
schedule class. For example, data that can have an impact on scheduling can
@@ -1180,11 +1172,11 @@ by `getSchedClassID()` to map a vector instruction and the active
LMUL to the scheduling class of the pseudo-instruction that describes
that base instruction and the active LMUL.
-Custom Views
-""""""""""""""""""""""""""""""""""""
-:program:`llvm-mca` comes with several Views such as the Timeline View and
+#### Custom Views
+
+{program}`llvm-mca` comes with several Views such as the Timeline View and
Summary View. These Views are generic and can work with most (if not all)
-targets. If you wish to add a new View to :program:`llvm-mca` and it does not
+targets. If you wish to add a new View to {program}`llvm-mca` and it does not
require any backend functionality that is not already exposed through MC layer
classes (MCSubtargetInfo, MCInstrInfo, etc.), please add it to the
`/tools/llvm-mca/View/` directory. However, if your new View is target specific
@@ -1206,3 +1198,4 @@ the `-disable-cb` flag is used.
Enabling these custom Views does not affect the non-custom (generic) Views.
Continue to use the usual command line arguments to enable / disable those
Views.
+
diff --git a/llvm/docs/CommandGuide/llvm-nm.md b/llvm/docs/CommandGuide/llvm-nm.md
index 7067bb0a29a19..80cb0df193162 100644
--- a/llvm/docs/CommandGuide/llvm-nm.md
+++ b/llvm/docs/CommandGuide/llvm-nm.md
@@ -1,23 +1,22 @@
-llvm-nm - list LLVM bitcode and object file's symbol table
-==========================================================
+# llvm-nm - list LLVM bitcode and object file's symbol table
+```{eval-rst}
.. program:: llvm-nm
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-nm` [*options*] [*filenames...*]
+{program}`llvm-nm` \[*options*\] \[*filenames...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-nm` utility lists the names of symbols from LLVM bitcode
+The {program}`llvm-nm` utility lists the names of symbols from LLVM bitcode
files, object files, and archives. Each symbol is listed along with some simple
information about its provenance. If no filename is specified, *a.out* is used
-as the input. If *-* is used as a filename, :program:`llvm-nm` will read a file
+as the input. If *-* is used as a filename, {program}`llvm-nm` will read a file
from its standard input stream.
-:program:`llvm-nm`'s default output format is the traditional BSD :program:`nm`
+{program}`llvm-nm`'s default output format is the traditional BSD {program}`nm`
output format. Each such output record consists of an (optional) 8-digit
hexadecimal address, followed by a type code character, followed by a name, for
each symbol. One record is printed per line; fields are separated by spaces.
@@ -30,298 +29,302 @@ represents a local symbol, whilst an upper-case character represents a global
a, A
- Absolute symbol.
+> Absolute symbol.
b, B
- Uninitialized data (bss) object.
+> Uninitialized data (bss) object.
C
- Common symbol. Multiple definitions link together into one definition.
+> Common symbol. Multiple definitions link together into one definition.
d, D
- Writable data object.
+> Writable data object.
i, I
- COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
+> COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
n
- ELF: local symbol from non-alloc section.
-
- COFF: debug symbol.
+> ELF: local symbol from non-alloc section.
+>
+> COFF: debug symbol.
N
- ELF: debug section symbol, or global symbol from non-alloc section.
+> ELF: debug section symbol, or global symbol from non-alloc section.
s, S
- COFF: section symbol.
-
- Mach-O: absolute symbol or symbol from a section other than __TEXT_EXEC __text,
- __TEXT __text, __DATA __data, or __DATA __bss.
+> COFF: section symbol.
+>
+> Mach-O: absolute symbol or symbol from a section other than \_\_TEXT_EXEC \_\_text,
+> \_\_TEXT \_\_text, \_\_DATA \_\_data, or \_\_DATA \_\_bss.
r, R
- Read-only data object.
+> Read-only data object.
t, T
- Code (text) object.
+> Code (text) object.
u
- ELF: GNU unique symbol.
+> ELF: GNU unique symbol.
U
- Named object is undefined in this file.
+> Named object is undefined in this file.
v
- ELF: Undefined weak object. It is not a link failure if the object is not
- defined.
+> ELF: Undefined weak object. It is not a link failure if the object is not
+> defined.
V
- ELF: Defined weak object symbol. This definition will only be used if no
- regular definitions exist in a link. If multiple weak definitions and no
- regular definitions exist, one of the weak definitions will be used.
+> ELF: Defined weak object symbol. This definition will only be used if no
+> regular definitions exist in a link. If multiple weak definitions and no
+> regular definitions exist, one of the weak definitions will be used.
w
- Undefined weak symbol other than an ELF object symbol. It is not a link failure
- if the symbol is not defined.
+> Undefined weak symbol other than an ELF object symbol. It is not a link failure
+> if the symbol is not defined.
W
- Defined weak symbol other than an ELF object symbol. This definition will only
- be used if no regular definitions exist in a link. If multiple weak definitions
- and no regular definitions exist, one of the weak definitions will be used.
+> Defined weak symbol other than an ELF object symbol. This definition will only
+> be used if no regular definitions exist in a link. If multiple weak definitions
+> and no regular definitions exist, one of the weak definitions will be used.
\-
- Mach-O: N_STAB symbol.
+> Mach-O: N_STAB symbol.
?
- Something unrecognizable.
+> Something unrecognizable.
Because LLVM bitcode files typically contain objects that are not considered to
have addresses until they are linked into an executable image or dynamically
-compiled "just-in-time", :program:`llvm-nm` does not print an address for any
+compiled "just-in-time", {program}`llvm-nm` does not print an address for any
symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
file.
-OPTIONS
--------
+## OPTIONS
+```{eval-rst}
.. program:: llvm-nm
+```
+
+:::{option} -B
+Use BSD output format. Alias for `--format=bsd`.
+:::
+
+:::{option} -X
+Specify the type of XCOFF object file, ELF object file, or IR object file input
+from command line or from archive files that llvm-nm should examine. 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 the supported object files.
+>
+> On AIX OS, the default is to process 32-bit object files only and to ignore
+> 64-bit objects. The can be changed by setting the OBJECT_MODE environment
+> variable. For example, OBJECT_MODE=64 causes {program}`llvm-nm` to process
+> 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
+> variable.
+>
+> On other operating systems, the default is to process all object files: the
+> OBJECT_MODE environment variable is not supported.
+:::
+
+:::{option} --debug-syms, -a
+Show all symbols, even those usually suppressed.
+:::
+
+:::{option} --defined-only, -U
+Print only symbols defined in this file.
+:::
+
+:::{option} --demangle, -C
+Demangle symbol names.
+:::
+
+:::{option} --dynamic, -D
+Display dynamic symbols instead of normal symbols.
+:::
+
+:::{option} --export-symbols
+Print sorted symbols with their visibility (if applicable), with duplicates
+removed.
+:::
+
+:::{option} --extern-only, -g
+Print only symbols whose definitions are external; that is, accessible from
+other files.
+:::
+
+:::{option} --format=<format>, -f
+Select an output format; *format* may be *sysv*, *posix*, *darwin*, *bsd* or
+*just-symbols*.
+The default is *bsd*.
+:::
+
+:::{option} --help, -h
+Print a summary of command-line options and their meanings.
+:::
+
+:::{option} -j
+Print just the symbol names. Alias for `` --format=just-symbols` ``.
+:::
+
+:::{option} --line-numbers, -l
+Use debugging information to print the filenames and line numbers where
+symbols are defined. Undefined symbols have the location of their first
+relocation printed instead.
+:::
+
+:::{option} -m
+Use Darwin format. Alias for `--format=darwin`.
+:::
+
+:::{option} --no-demangle
+Don't demangle symbol names. This is the default.
+:::
+
+:::{option} --no-llvm-bc
+Disable the LLVM bitcode reader.
+:::
+
+:::{option} --no-sort, -p
+Show symbols in the order encountered.
+:::
+
+:::{option} --no-weak, -W
+Don't print weak symbols.
+:::
+
+:::{option} --numeric-sort, -n, -v
+Sort symbols by address.
+:::
+
+:::{option} --portability, -P
+Use POSIX.2 output format. Alias for `--format=posix`.
+:::
+
+:::{option} --print-armap
+Print the archive symbol table, in addition to the symbols.
+:::
+
+:::{option} --print-file-name, -A, -o
+Precede each symbol with the file it came from.
+:::
+
+:::{option} --print-size, -S
+Show symbol size as well as address (not applicable for Mach-O).
+:::
+
+:::{option} --quiet
+Suppress 'no symbols' diagnostic.
+:::
-.. option:: -B
-
- Use BSD output format. Alias for ``--format=bsd``.
-
-.. option:: -X
-
- Specify the type of XCOFF object file, ELF object file, or IR object file input
- from command line or from archive files that llvm-nm should examine. 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 the supported object files.
-
- On AIX OS, the default is to process 32-bit object files only and to ignore
- 64-bit objects. The can be changed by setting the OBJECT_MODE environment
- variable. For example, OBJECT_MODE=64 causes :program:`llvm-nm` to process
- 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
- variable.
-
- On other operating systems, the default is to process all object files: the
- OBJECT_MODE environment variable is not supported.
-
-.. option:: --debug-syms, -a
-
- Show all symbols, even those usually suppressed.
-
-.. option:: --defined-only, -U
-
- Print only symbols defined in this file.
-
-.. option:: --demangle, -C
-
- Demangle symbol names.
-
-.. option:: --dynamic, -D
-
- Display dynamic symbols instead of normal symbols.
-
-.. option:: --export-symbols
-
- Print sorted symbols with their visibility (if applicable), with duplicates
- removed.
-
-.. option:: --extern-only, -g
-
- Print only symbols whose definitions are external; that is, accessible from
- other files.
-
-.. option:: --format=<format>, -f
-
- Select an output format; *format* may be *sysv*, *posix*, *darwin*, *bsd* or
- *just-symbols*.
- The default is *bsd*.
-
-.. option:: --help, -h
-
- Print a summary of command-line options and their meanings.
-
-.. option:: -j
-
- Print just the symbol names. Alias for `--format=just-symbols``.
-
-.. option:: --line-numbers, -l
-
- Use debugging information to print the filenames and line numbers where
- symbols are defined. Undefined symbols have the location of their first
- relocation printed instead.
-
-.. option:: -m
-
- Use Darwin format. Alias for ``--format=darwin``.
-
-.. option:: --no-demangle
-
- Don't demangle symbol names. This is the default.
-
-.. option:: --no-llvm-bc
-
- Disable the LLVM bitcode reader.
-
-.. option:: --no-sort, -p
-
- Show symbols in the order encountered.
-
-.. option:: --no-weak, -W
-
- Don't print weak symbols.
-
-.. option:: --numeric-sort, -n, -v
-
- Sort symbols by address.
-
-.. option:: --portability, -P
-
- Use POSIX.2 output format. Alias for ``--format=posix``.
-
-.. option:: --print-armap
-
- Print the archive symbol table, in addition to the symbols.
-
-.. option:: --print-file-name, -A, -o
-
- Precede each symbol with the file it came from.
-
-.. option:: --print-size, -S
-
- Show symbol size as well as address (not applicable for Mach-O).
-
-.. option:: --quiet
-
- Suppress 'no symbols' diagnostic.
-
-.. option:: --radix=<RADIX>, -t
-
- Specify the radix of the symbol address(es). Values accepted are *d* (decimal),
- *x* (hexadecimal) and *o* (octal).
-
-.. option:: --reverse-sort, -r
-
- Sort symbols in reverse order.
-
-.. option:: --size-sort
-
- Sort symbols by size.
-
-.. option:: --special-syms
-
- Do not filter special symbols from the output.
-
-.. option:: --undefined-only, -u
-
- Print only undefined symbols.
-
-.. option:: --version, -V
-
- Display the version of the :program:`llvm-nm` executable, then exit. Does not
- stack with other commands.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-MACH-O SPECIFIC OPTIONS
------------------------
+:::{option} --radix=<RADIX>, -t
+Specify the radix of the symbol address(es). Values accepted are *d* (decimal),
+*x* (hexadecimal) and *o* (octal).
+:::
-.. option:: --add-dyldinfo
+:::{option} --reverse-sort, -r
+Sort symbols in reverse order.
+:::
- Add symbols from the dyldinfo, if they are not already in the symbol table.
- This is the default.
+:::{option} --size-sort
+Sort symbols by size.
+:::
-.. option:: --add-inlinedinfo
+:::{option} --special-syms
+Do not filter special symbols from the output.
+:::
- Add symbols from the inlined libraries, TBD file inputs only.
+:::{option} --undefined-only, -u
+Print only undefined symbols.
+:::
-.. option:: --arch=<arch1[,arch2,...]>
+:::{option} --version, -V
+Display the version of the {program}`llvm-nm` executable, then exit. Does not
+stack with other commands.
+:::
- Dump the symbols from the specified architecture(s).
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
-.. option:: --dyldinfo-only
+## MACH-O SPECIFIC OPTIONS
- Dump only symbols from the dyldinfo.
+:::{option} --add-dyldinfo
+Add symbols from the dyldinfo, if they are not already in the symbol table.
+This is the default.
+:::
-.. option:: --no-dyldinfo
+:::{option} --add-inlinedinfo
+Add symbols from the inlined libraries, TBD file inputs only.
+:::
- Do not add any symbols from the dyldinfo.
+:::{option} --arch=<arch1[,arch2,...]>
+Dump the symbols from the specified architecture(s).
+:::
-.. option:: -s <segment> <section>
+:::{option} --dyldinfo-only
+Dump only symbols from the dyldinfo.
+:::
- Dump only symbols from this segment and section name.
+:::{option} --no-dyldinfo
+Do not add any symbols from the dyldinfo.
+:::
-.. option:: -x
+:::{option} -s <segment> <section>
+Dump only symbols from this segment and section name.
+:::
- Print symbol entry in hex.
+:::{option} -x
+Print symbol entry in hex.
+:::
-XCOFF SPECIFIC OPTIONS
-----------------------
+## XCOFF SPECIFIC OPTIONS
-.. option:: --no-rsrc
+:::{option} --no-rsrc
+Exclude resource file symbols (`__rsrc`) from export symbol list.
+:::
- Exclude resource file symbols (``__rsrc``) from export symbol list.
+## BUGS
-BUGS
-----
+> - {program}`llvm-nm` does not support the full set of arguments that GNU
+> {program}`nm` does.
- * :program:`llvm-nm` does not support the full set of arguments that GNU
- :program:`nm` does.
+## EXIT STATUS
-EXIT STATUS
------------
+{program}`llvm-nm` exits with an exit code of zero.
-:program:`llvm-nm` exits with an exit code of zero.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-ar(1)`, {manpage}`llvm-objdump(1)`, {manpage}`llvm-readelf(1)`,
+{manpage}`llvm-readobj(1)`
-:manpage:`llvm-ar(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`,
-:manpage:`llvm-readobj(1)`
diff --git a/llvm/docs/CommandGuide/llvm-objcopy.md b/llvm/docs/CommandGuide/llvm-objcopy.md
index 98735a59aa05f..9d45a8e83b587 100644
--- a/llvm/docs/CommandGuide/llvm-objcopy.md
+++ b/llvm/docs/CommandGuide/llvm-objcopy.md
@@ -1,17 +1,16 @@
-llvm-objcopy - object copying and editing tool
-==============================================
+# llvm-objcopy - object copying and editing tool
+```{eval-rst}
.. program:: llvm-objcopy
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-objcopy` [*options*] *input* [*output*]
+{program}`llvm-objcopy` \[*options*\] *input* \[*output*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic
+{program}`llvm-objcopy` is a tool to copy and manipulate objects. In basic
usage, it makes a semantic copy of the input to the output. If any options are
specified, the output may be modified along the way, e.g. by removing sections.
@@ -24,574 +23,567 @@ If the input is an archive, any requested operations will be applied to each
archive member individually.
The tool is still in active development, but in most scenarios it works as a
-drop-in replacement for GNU's :program:`objcopy`.
+drop-in replacement for GNU's {program}`objcopy`.
-GENERIC AND CROSS-PLATFORM OPTIONS
-----------------------------------
+## GENERIC AND CROSS-PLATFORM OPTIONS
The following options are either agnostic of the file format, or apply to
multiple file formats.
-.. option:: --add-gnu-debuglink <debug-file>
-
- Add a .gnu_debuglink section for ``<debug-file>`` to the output.
-
-.. option:: --add-section <section=file>
-
- Add a section named ``<section>`` with the contents of ``<file>`` to the
- output. For ELF objects the section will be of type `SHT_NOTE`, if the name
- starts with ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be
- specified multiple times to add multiple sections.
-
- For MachO objects, ``<section>`` must be formatted as
- ``<segment name>,<section name>``.
-
-.. option:: --binary-architecture <arch>, -B
-
- Ignored for compatibility.
-
-.. option:: --disable-deterministic-archives, -U
-
- Use real values for UIDs, GIDs and timestamps when updating archive member
- headers.
-
-.. option:: --discard-all, -x
-
- Remove most local symbols not referenced by relocations from the output.
- Different file formats may limit this to a subset of the local symbols. For
- example, file and section symbols in ELF objects will not be discarded.
- Additionally, remove all debug sections.
-
-.. option:: --dump-section <section>=<file>
-
- Dump the contents of section ``<section>`` into the file ``<file>``. Can be
- specified multiple times to dump multiple sections to different files.
- ``<file>`` is unrelated to the input and output files provided to
- :program:`llvm-objcopy` and as such the normal copying and editing
- operations will still be performed. No operations are performed on the sections
- prior to dumping them.
-
- For MachO objects, ``<section>`` must be formatted as
- ``<segment name>,<section name>``.
-
-.. option:: --enable-deterministic-archives, -D
-
- Enable deterministic mode when copying archives, i.e. use 0 for archive member
- header UIDs, GIDs and timestamp fields. On by default.
-
-.. option:: --extract-section <section>=<file>
-
- Extract the specified section ``<section>`` into the file ``<file>`` as a
- seperate object. Can be specified multiple times to extract multiple sections.
- ``<file>`` is unrelated to the input and output files provided to
- :program:`llvm-objcopy` and as such the normal copying and editing
- operations will still be performed. No operations are performed on the sections
- prior to dumping them.
-
-.. option:: --globalize-symbol <symbol>
-
- Mark any defined symbols named ``<symbol>`` as global symbols in the output.
- Can be specified multiple times to mark multiple symbols.
-
-.. option:: --globalize-symbols <filename>
-
- Read a list of names from the file ``<filename>`` and mark defined symbols with
- those names as global in the output. In the file, each line represents a single
- symbol, with leading and trailing whitespace ignored, as is anything following
- a '#'. Can be specified multiple times to read names from multiple files.
-
-.. option:: --help, -h
-
- Print a summary of command line options.
-
-.. option:: --keep-global-symbol <symbol>, -G
-
- Mark all symbols local in the output, except for symbols with the name
- ``<symbol>``. Can be specified multiple times to ignore multiple symbols.
-
-.. option:: --keep-global-symbols <filename>
-
- Mark all symbols local in the output, except for symbols named in the file
- ``<filename>``. In the file, each line represents a single symbol, with leading
- and trailing whitespace ignored, as is anything following a '#'. Can be
- specified multiple times to read names from multiple files.
-
-.. option:: --localize-symbol <symbol>, -L
-
- Mark any defined non-common symbol named ``<symbol>`` as a local symbol in the
- output. Can be specified multiple times to mark multiple symbols as local.
-
-.. option:: --localize-symbols <filename>
-
- Read a list of names from the file ``<filename>`` and mark defined non-common
- symbols with those names as local in the output. In the file, each line
- represents a single symbol, with leading and trailing whitespace ignored, as is
- anything following a '#'. Can be specified multiple times to read names from
- multiple files.
-
-.. option:: --only-keep-debug
-
- Produce a debug file as the output that only preserves contents of sections
- useful for debugging purposes.
-
- For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
- `SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
- possible.
-
-.. option:: --only-section <section>, -j
-
- Remove all sections from the output, except for sections named ``<section>``.
- Can be specified multiple times to keep multiple sections.
-
- For MachO objects, ``<section>`` must be formatted as
- ``<segment name>,<section name>``.
-
-.. option:: --redefine-sym <old>=<new>
-
- Rename symbols called ``<old>`` to ``<new>`` in the output. Can be specified
- multiple times to rename multiple symbols.
-
-.. option:: --redefine-syms <filename>
-
- Rename symbols in the output as described in the file ``<filename>``. In the
- file, each line represents a single symbol to rename, with the old name and new
- name separated by whitespace. Leading and trailing whitespace is ignored, as is
- anything following a '#'. Can be specified multiple times to read names from
- multiple files.
-
-.. option:: --regex
-
- If specified, symbol and section names specified by other switches are treated
- as extended POSIX regular expression patterns.
-
-.. option:: --remove-symbol-prefix <prefix>
-
- Remove ``<prefix>`` from the start of every symbol name. No-op for symbols that do
- not start with ``<prefix>``.
-
-.. option:: --remove-section <section>, -R
-
- Remove the specified section from the output. Can be specified multiple times
- to remove multiple sections simultaneously.
-
- For MachO objects, ``<section>`` must be formatted as
- ``<segment name>,<section name>``.
-
-.. option:: --set-section-alignment <section>=<align>
-
- Set the alignment of section ``<section>`` to ``<align>``. Can be specified
- multiple times to update multiple sections.
-
-.. option:: --set-section-flags <section>=<flag>[,<flag>,...]
-
- Set section properties in the output of section ``<section>`` based on the
- specified ``<flag>`` values. Can be specified multiple times to update multiple
- sections.
-
- Supported flag names are `alloc`, `load`, `noload`, `readonly`, `exclude`,
- `debug`, `code`, `data`, `rom`, `share`, `contents`, `merge`, `strings`, and
- `large`. Not all flags are meaningful for all object file formats or target
- architectures.
-
- For ELF objects, the flags have the following effects:
-
- - `alloc` = add the `SHF_ALLOC` flag.
- - `load` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
- section.
- - `readonly` = if this flag is not specified, add the `SHF_WRITE` flag.
- - `exclude` = add the `SHF_EXCLUDE` flag.
- - `code` = add the `SHF_EXECINSTR` flag.
- - `merge` = add the `SHF_MERGE` flag.
- - `strings` = add the `SHF_STRINGS` flag.
- - `contents` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
- section.
- - `large` = add the `SHF_X86_64_LARGE` on x86_64; rejected if the target
- architecture is not x86_64.
-
- For COFF objects, the flags have the following effects:
-
- - `alloc` = add the `IMAGE_SCN_CNT_UNINITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
- flags, unless the `load` flag is specified.
- - `noload` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
- - `readonly` = if this flag is not specified, add the `IMAGE_SCN_MEM_WRITE`
- flag.
- - `exclude` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
- - `debug` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA`,
- `IMAGE_SCN_MEM_DISCARDABLE` and `IMAGE_SCN_MEM_READ` flags.
- - `code` = add the `IMAGE_SCN_CNT_CODE`, `IMAGE_SCN_MEM_EXECUTE` and
- `IMAGE_SCN_MEM_READ` flags.
- - `data` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
- flags.
- - `share` = add the `IMAGE_SCN_MEM_SHARED` and `IMAGE_SCN_MEM_READ` flags.
-
-.. option:: --skip-symbol <symbol>
-
- Do not change the parameters of symbol ``<symbol>`` when executing other
- options that can change the symbol's name, binding or visibility.
-
-.. option:: --skip-symbols <filename>
-
- Do not change the parameters of symbols named in the file ``<filename>`` when
- executing other options that can change the symbol's name, binding or
- visibility. In the file, each line represents a single symbol, with leading
- and trailing whitespace ignored, as is anything following a '#'.
- Can be specified multiple times to read names from multiple files.
-
-.. option:: --strip-all-gnu
-
- Remove all symbols, debug sections and relocations from the output. This option
- is equivalent to GNU :program:`objcopy`'s ``--strip-all`` switch.
-
-.. option:: --strip-all, -S
-
- For ELF objects, remove from the output all symbols and non-alloc sections not
- within segments, except for .gnu.warning, .ARM.attribute sections and the
- section name table.
-
- For COFF and Mach-O objects, remove all symbols, debug sections, and
- relocations from the output.
-
- For WebAssembly objects, remove all custom sections except for those named
- metadata.code.*.
-
-.. option:: --strip-debug, -g
-
- Remove all debug sections from the output.
-
-.. option:: --strip-symbol <symbol>, -N
-
- Remove all symbols named ``<symbol>`` from the output. Can be specified
- multiple times to remove multiple symbols.
-
-.. option:: --strip-symbols <filename>
-
- Remove all symbols whose names appear in the file ``<filename>``, from the
- output. In the file, each line represents a single symbol name, with leading
- and trailing whitespace ignored, as is anything following a '#'. Can be
- specified multiple times to read names from multiple files.
-
-.. option:: --strip-unneeded-symbol <symbol>
-
- Remove from the output all symbols named ``<symbol>`` that are local or
- undefined and are not required by any relocation.
-
-.. option:: --strip-unneeded-symbols <filename>
-
- Remove all symbols whose names appear in the file ``<filename>``, from the
- output, if they are local or undefined and are not required by any relocation.
- In the file, each line represents a single symbol name, with leading and
- trailing whitespace ignored, as is anything following a '#'. Can be specified
- multiple times to read names from multiple files.
-
-.. option:: --strip-unneeded
-
- Remove from the output all local or undefined symbols that are not required by
- relocations. Also remove all debug sections.
-
-.. option:: --update-section <name>=<file>
-
- Replace the contents of the section ``<name>`` with contents from the file
- ``<file>``. If the section ``<name>`` is part of a segment, the new contents
- cannot be larger than the existing section.
-
-.. option:: --verbose, -v
-
- Print the paths of files that are copied.
-
-.. option:: --version, -V
-
- Display the version of the :program:`llvm-objcopy` executable.
-
-.. option:: --wildcard, -w
-
- Allow wildcard syntax for symbol-related flags. On by default for
- section-related flags. Incompatible with --regex.
-
- Wildcard syntax allows the following special symbols:
-
- ====================== ========================= ==================
- Character Meaning Equivalent
- ====================== ========================= ==================
- ``*`` Any number of characters ``.*``
- ``?`` Any single character ``.``
- ``\`` Escape the next character ``\``
- ``[a-z]`` Character class ``[a-z]``
- ``[!a-z]``, ``[^a-z]`` Negated character class ``[^a-z]``
- ====================== ========================= ==================
-
- Additionally, starting a wildcard with '!' will prevent a match, even if
- another flag matches. For example ``-w -N '*' -N '!x'`` will strip all symbols
- except for ``x``.
-
- The order of wildcards does not matter. For example, ``-w -N '*' -N '!x'`` is
- the same as ``-w -N '!x' -N '*'``.
-
-.. option:: @<FILE>
-
- Read command-line options and commands from response file `<FILE>`.
-
-ELF-SPECIFIC OPTIONS
---------------------
+:::{option} --add-gnu-debuglink <debug-file>
+Add a .gnu_debuglink section for `<debug-file>` to the output.
+:::
+
+:::{option} --add-section <section=file>
+Add a section named `<section>` with the contents of `<file>` to the
+output. For ELF objects the section will be of type `SHT_NOTE`, if the name
+starts with ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be
+specified multiple times to add multiple sections.
+
+For MachO objects, `<section>` must be formatted as
+`<segment name>,<section name>`.
+:::
+
+:::{option} --binary-architecture <arch>, -B
+Ignored for compatibility.
+:::
+
+:::{option} --disable-deterministic-archives, -U
+Use real values for UIDs, GIDs and timestamps when updating archive member
+headers.
+:::
+
+:::{option} --discard-all, -x
+Remove most local symbols not referenced by relocations from the output.
+Different file formats may limit this to a subset of the local symbols. For
+example, file and section symbols in ELF objects will not be discarded.
+Additionally, remove all debug sections.
+:::
+
+:::{option} --dump-section <section>=<file>
+Dump the contents of section `<section>` into the file `<file>`. Can be
+specified multiple times to dump multiple sections to different files.
+`<file>` is unrelated to the input and output files provided to
+{program}`llvm-objcopy` and as such the normal copying and editing
+operations will still be performed. No operations are performed on the sections
+prior to dumping them.
+
+For MachO objects, `<section>` must be formatted as
+`<segment name>,<section name>`.
+:::
+
+:::{option} --enable-deterministic-archives, -D
+Enable deterministic mode when copying archives, i.e. use 0 for archive member
+header UIDs, GIDs and timestamp fields. On by default.
+:::
+
+:::{option} --extract-section <section>=<file>
+Extract the specified section `<section>` into the file `<file>` as a
+seperate object. Can be specified multiple times to extract multiple sections.
+`<file>` is unrelated to the input and output files provided to
+{program}`llvm-objcopy` and as such the normal copying and editing
+operations will still be performed. No operations are performed on the sections
+prior to dumping them.
+:::
+
+:::{option} --globalize-symbol <symbol>
+Mark any defined symbols named `<symbol>` as global symbols in the output.
+Can be specified multiple times to mark multiple symbols.
+:::
+
+:::{option} --globalize-symbols <filename>
+Read a list of names from the file `<filename>` and mark defined symbols with
+those names as global in the output. In the file, each line represents a single
+symbol, with leading and trailing whitespace ignored, as is anything following
+a '#'. Can be specified multiple times to read names from multiple files.
+:::
+
+:::{option} --help, -h
+Print a summary of command line options.
+:::
+
+:::{option} --keep-global-symbol <symbol>, -G
+Mark all symbols local in the output, except for symbols with the name
+`<symbol>`. Can be specified multiple times to ignore multiple symbols.
+:::
+
+:::{option} --keep-global-symbols <filename>
+Mark all symbols local in the output, except for symbols named in the file
+`<filename>`. In the file, each line represents a single symbol, with leading
+and trailing whitespace ignored, as is anything following a '#'. Can be
+specified multiple times to read names from multiple files.
+:::
+
+:::{option} --localize-symbol <symbol>, -L
+Mark any defined non-common symbol named `<symbol>` as a local symbol in the
+output. Can be specified multiple times to mark multiple symbols as local.
+:::
+
+:::{option} --localize-symbols <filename>
+Read a list of names from the file `<filename>` and mark defined non-common
+symbols with those names as local in the output. In the file, each line
+represents a single symbol, with leading and trailing whitespace ignored, as is
+anything following a '#'. Can be specified multiple times to read names from
+multiple files.
+:::
+
+:::{option} --only-keep-debug
+Produce a debug file as the output that only preserves contents of sections
+useful for debugging purposes.
+
+For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
+`SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
+possible.
+:::
+
+:::{option} --only-section <section>, -j
+Remove all sections from the output, except for sections named `<section>`.
+Can be specified multiple times to keep multiple sections.
+
+For MachO objects, `<section>` must be formatted as
+`<segment name>,<section name>`.
+:::
+
+:::{option} --redefine-sym <old>=<new>
+Rename symbols called `<old>` to `<new>` in the output. Can be specified
+multiple times to rename multiple symbols.
+:::
+
+:::{option} --redefine-syms <filename>
+Rename symbols in the output as described in the file `<filename>`. In the
+file, each line represents a single symbol to rename, with the old name and new
+name separated by whitespace. Leading and trailing whitespace is ignored, as is
+anything following a '#'. Can be specified multiple times to read names from
+multiple files.
+:::
+
+:::{option} --regex
+If specified, symbol and section names specified by other switches are treated
+as extended POSIX regular expression patterns.
+:::
+
+:::{option} --remove-symbol-prefix <prefix>
+Remove `<prefix>` from the start of every symbol name. No-op for symbols that do
+not start with `<prefix>`.
+:::
+
+:::{option} --remove-section <section>, -R
+Remove the specified section from the output. Can be specified multiple times
+to remove multiple sections simultaneously.
+
+For MachO objects, `<section>` must be formatted as
+`<segment name>,<section name>`.
+:::
+
+:::{option} --set-section-alignment <section>=<align>
+Set the alignment of section `<section>` to `<align>`. Can be specified
+multiple times to update multiple sections.
+:::
+
+:::{option} --set-section-flags <section>=<flag>[,<flag>,...]
+Set section properties in the output of section `<section>` based on the
+specified `<flag>` values. Can be specified multiple times to update multiple
+sections.
+
+Supported flag names are `alloc`, `load`, `noload`, `readonly`, `exclude`,
+`debug`, `code`, `data`, `rom`, `share`, `contents`, `merge`, `strings`, and
+`large`. Not all flags are meaningful for all object file formats or target
+architectures.
+
+For ELF objects, the flags have the following effects:
+
+- `alloc` = add the `SHF_ALLOC` flag.
+- `load` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
+ section.
+- `readonly` = if this flag is not specified, add the `SHF_WRITE` flag.
+- `exclude` = add the `SHF_EXCLUDE` flag.
+- `code` = add the `SHF_EXECINSTR` flag.
+- `merge` = add the `SHF_MERGE` flag.
+- `strings` = add the `SHF_STRINGS` flag.
+- `contents` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
+ section.
+- `large` = add the `SHF_X86_64_LARGE` on x86_64; rejected if the target
+ architecture is not x86_64.
+
+For COFF objects, the flags have the following effects:
+
+- `alloc` = add the `IMAGE_SCN_CNT_UNINITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
+ flags, unless the `load` flag is specified.
+- `noload` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
+- `readonly` = if this flag is not specified, add the `IMAGE_SCN_MEM_WRITE`
+ flag.
+- `exclude` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
+- `debug` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA`,
+ `IMAGE_SCN_MEM_DISCARDABLE` and `IMAGE_SCN_MEM_READ` flags.
+- `code` = add the `IMAGE_SCN_CNT_CODE`, `IMAGE_SCN_MEM_EXECUTE` and
+ `IMAGE_SCN_MEM_READ` flags.
+- `data` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
+ flags.
+- `share` = add the `IMAGE_SCN_MEM_SHARED` and `IMAGE_SCN_MEM_READ` flags.
+:::
+
+:::{option} --skip-symbol <symbol>
+Do not change the parameters of symbol `<symbol>` when executing other
+options that can change the symbol's name, binding or visibility.
+:::
+
+:::{option} --skip-symbols <filename>
+Do not change the parameters of symbols named in the file `<filename>` when
+executing other options that can change the symbol's name, binding or
+visibility. In the file, each line represents a single symbol, with leading
+and trailing whitespace ignored, as is anything following a '#'.
+Can be specified multiple times to read names from multiple files.
+:::
+
+:::{option} --strip-all-gnu
+Remove all symbols, debug sections and relocations from the output. This option
+is equivalent to GNU {program}`objcopy`'s `--strip-all` switch.
+:::
+
+:::{option} --strip-all, -S
+For ELF objects, remove from the output all symbols and non-alloc sections not
+within segments, except for .gnu.warning, .ARM.attribute sections and the
+section name table.
+
+For COFF and Mach-O objects, remove all symbols, debug sections, and
+relocations from the output.
+
+For WebAssembly objects, remove all custom sections except for those named
+metadata.code.\*.
+:::
+
+:::{option} --strip-debug, -g
+Remove all debug sections from the output.
+:::
+
+:::{option} --strip-symbol <symbol>, -N
+Remove all symbols named `<symbol>` from the output. Can be specified
+multiple times to remove multiple symbols.
+:::
+
+:::{option} --strip-symbols <filename>
+Remove all symbols whose names appear in the file `<filename>`, from the
+output. In the file, each line represents a single symbol name, with leading
+and trailing whitespace ignored, as is anything following a '#'. Can be
+specified multiple times to read names from multiple files.
+:::
+
+:::{option} --strip-unneeded-symbol <symbol>
+Remove from the output all symbols named `<symbol>` that are local or
+undefined and are not required by any relocation.
+:::
+
+:::{option} --strip-unneeded-symbols <filename>
+Remove all symbols whose names appear in the file `<filename>`, from the
+output, if they are local or undefined and are not required by any relocation.
+In the file, each line represents a single symbol name, with leading and
+trailing whitespace ignored, as is anything following a '#'. Can be specified
+multiple times to read names from multiple files.
+:::
+
+:::{option} --strip-unneeded
+Remove from the output all local or undefined symbols that are not required by
+relocations. Also remove all debug sections.
+:::
+
+:::{option} --update-section <name>=<file>
+Replace the contents of the section `<name>` with contents from the file
+`<file>`. If the section `<name>` is part of a segment, the new contents
+cannot be larger than the existing section.
+:::
+
+:::{option} --verbose, -v
+Print the paths of files that are copied.
+:::
+
+:::{option} --version, -V
+Display the version of the {program}`llvm-objcopy` executable.
+:::
+
+:::{option} --wildcard, -w
+Allow wildcard syntax for symbol-related flags. On by default for
+section-related flags. Incompatible with --regex.
+
+Wildcard syntax allows the following special symbols:
+
+| Character | Meaning | Equivalent |
+| ------------------ | ------------------------- | ---------- |
+| `*` | Any number of characters | `.*` |
+| `?` | Any single character | `.` |
+| `\` | Escape the next character | `\` |
+| `[a-z]` | Character class | `[a-z]` |
+| `[!a-z]`, `[^a-z]` | Negated character class | `[^a-z]` |
+
+Additionally, starting a wildcard with '!' will prevent a match, even if
+another flag matches. For example `-w -N '*' -N '!x'` will strip all symbols
+except for `x`.
+
+The order of wildcards does not matter. For example, `-w -N '*' -N '!x'` is
+the same as `-w -N '!x' -N '*'`.
+:::
+
+:::{option} @<FILE>
+Read command-line options and commands from response file `<FILE>`.
+:::
+
+## ELF-SPECIFIC OPTIONS
The following options are implemented only for ELF objects. If used with other
-objects, :program:`llvm-objcopy` will either emit an error or silently ignore
+objects, {program}`llvm-objcopy` will either emit an error or silently ignore
them.
-.. option:: --add-symbol <name>=[<section>:]<value>[,<flags>]
-
- Add a new symbol called ``<name>`` to the output symbol table, in the section
- named ``<section>``, with value ``<value>``. If ``<section>`` is not specified,
- the symbol is added as an absolute symbol. The ``<flags>`` affect the symbol
- properties. Accepted values are:
-
- - `global` = the symbol will have global binding.
- - `local` = the symbol will have local binding.
- - `weak` = the symbol will have weak binding.
- - `default` = the symbol will have default visibility.
- - `hidden` = the symbol will have hidden visibility.
- - `protected` = the symbol will have protected visibility.
- - `file` = the symbol will be an `STT_FILE` symbol.
- - `section` = the symbol will be an `STT_SECTION` symbol.
- - `object` = the symbol will be an `STT_OBJECT` symbol.
- - `function` = the symbol will be an `STT_FUNC` symbol.
- - `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
-
- Additionally, the following flags are accepted but ignored: `debug`,
- `constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
-
- Can be specified multiple times to add multiple symbols.
-
-.. option:: --allow-broken-links
-
- Allow :program:`llvm-objcopy` to remove sections even if it would leave invalid
- section references. Any invalid sh_link fields will be set to zero.
-
-.. option:: --change-section-lma \*{+-}<val>
-
- Shift LMA of non-zero-sized segments by ``<val>``.
-
-.. option:: --change-section-address <section>{=+-}<val>, --adjust-section-vma
-
- Change the address of sections that match ``<section>`` pattern to the
- specified value, or apply ``+<val>``/``-<val>`` to the current value. Can be
- specified multiple times to specify multiple patterns. Each section is only
- modified by one ``--change-section-address`` argument. If a section name
- matches multiple patterns, the rightmost change applies. The object file needs
- to be of ET_REL type.
-
-.. option:: --change-start <incr>, --adjust-start
-
- Add ``<incr>`` to the program's start address. Can be specified multiple
- times, in which case the values will be applied cumulatively.
-
-.. option:: --compress-debug-sections [<format>]
-
- Compress DWARF debug sections in the output, using the specified format.
- Supported formats are ``zlib`` and ``zstd``. Use ``zlib`` if ``<format>`` is omitted.
-
-.. option:: --compress-sections <section>=<format>
-
- Compress or decompress sections matched by ``<section>`` using the specified
- format. Supported formats are ``zlib`` and ``zstd``. Specify ``none`` for
- decompression. When a section is matched by multiple options, the last one
- wins. A wildcard ``<section>`` starting with '!' is disallowed.
- Sections within a segment cannot be (de)compressed.
-
-.. option:: --decompress-debug-sections
-
- Decompress any compressed DWARF debug sections in the output.
-
-.. option:: --discard-locals, -X
-
- Remove local symbols starting with ".L" not referenced by relocations from the output.
-
-.. option:: --extract-dwo
-
- Remove all sections that are not DWARF .dwo sections from the output.
-
-.. option:: --extract-main-partition
-
- Extract the main partition from the output.
-
-.. option:: --extract-partition <name>
-
- Extract the named partition from the output.
-
-.. option:: --gap-fill <value>
-
- For binary outputs, fill the gaps between sections with ``<value>`` instead
- of zero. The value must be an unsigned 8-bit integer.
-
-.. option:: --input-target <format>, -I
-
- Read the input as the specified format. See `SUPPORTED FORMATS`_ for a list of
- valid ``<format>`` values. If unspecified, :program:`llvm-objcopy` will attempt
- to determine the format automatically.
-
-.. option:: --keep-file-symbols
-
- Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
-
-.. option:: --keep-section <section>
-
- When removing sections from the output, do not remove sections named
- ``<section>``. Can be specified multiple times to keep multiple sections.
-
-.. option:: --keep-symbol <symbol>, -K
-
- When removing symbols from the output, do not remove symbols named
- ``<symbol>``. Can be specified multiple times to keep multiple symbols.
-
-.. option:: --keep-symbols <filename>
-
- When removing symbols from the output do not remove symbols named in the file
- ``<filename>``. In the file, each line represents a single symbol, with leading
- and trailing whitespace ignored, as is anything following a '#'. Can be
- specified multiple times to read names from multiple files.
-
-.. option:: --localize-hidden
-
- Mark all symbols with hidden or internal visibility local in the output.
-
-.. option:: --new-symbol-visibility <visibility>
-
- Specify the visibility of the symbols automatically created when using binary
- input or :option:`--add-symbol`. Valid options are:
-
- - `default`
- - `hidden`
- - `internal`
- - `protected`
-
- The default is `default`.
-
-.. option:: --no-verify-note-sections
-
- When adding note sections, do not verify if the section format is valid.
-
-.. option:: --output-target <format>, -O
-
- Write the output as the specified format. See `SUPPORTED FORMATS`_ for a list
- of valid ``<format>`` values. If unspecified, the output format is assumed to
- be the same as the value specified for :option:`--input-target` or the input
- file's format if that option is also unspecified.
-
-.. option:: --pad-to <address>
-
- For binary outputs, pad the output to the load address ``<address>`` using a value
- of zero or the value specified by :option:`--gap-fill`.
-
-.. option:: --prefix-alloc-sections <prefix>
-
- Add ``<prefix>`` to the front of the names of all allocatable sections in the
- output.
-
-.. option:: --prefix-symbols <prefix>
-
- Add ``<prefix>`` to the front of every symbol name in the output.
-
-.. option:: --preserve-dates, -p
-
- Preserve access and modification timestamps in the output.
-
-.. option:: --remove-note [<name>/]<type>
-
- Remove notes of integer type ``<type>`` and name ``<name>`` from SHT_NOTE
- sections that are not in a segment. Can be specified multiple times.
-
-.. option:: --rename-section <old>=<new>[,<flag>,...]
-
- Rename sections called ``<old>`` to ``<new>`` in the output, and apply any
- specified ``<flag>`` values. See :option:`--set-section-flags` for a list of
- supported flags. Can be specified multiple times to rename multiple sections.
-
-.. option:: --set-section-type <section>=<type>
-
- Set the type of section ``<section>`` to the integer ``<type>``. Can be
- specified multiple times to update multiple sections.
-
-.. option:: --set-start <addr>
-
- Set the start address of the output to ``<addr>``. Overrides any previously
- specified :option:`--change-start` or :option:`--adjust-start` options.
-
-.. option:: --set-symbol-visibility <symbol>=<visibility>
-
- Change the visibility of a symbol to the specified value.
-
-.. option:: --set-symbols-visibility <filename>=<visibility>
-
- Read a list of symbols from <filename> and change their visibility to the
- specified value. Visibility values: default, internal, hidden, protected.
-
-.. option:: --split-dwo <dwo-file>
-
- Equivalent to running :program:`llvm-objcopy` with :option:`--extract-dwo` and
- ``<dwo-file>`` as the output file and no other options, and then with
- :option:`--strip-dwo` on the input file.
-
-.. option:: --strip-dwo
-
- Remove all DWARF .dwo sections from the output.
-
-.. option:: --strip-non-alloc
-
- Remove from the output all non-allocatable sections that are not within
- segments.
-
-.. option:: --strip-sections
-
- Remove from the output all section headers and all section data not within
- segments. Note that many tools will not be able to use an object without
- section headers.
-
-.. option:: --target <format>, -F
-
- Equivalent to :option:`--input-target` and :option:`--output-target` for the
- specified format. See `SUPPORTED FORMATS`_ for a list of valid ``<format>``
- values.
-
-.. option:: --verify-note-sections
-
- When adding note sections, verify if the section format is valid. On by
- default.
-
-.. option:: --weaken-symbol <symbol>, -W
-
- Mark global symbols named ``<symbol>`` as weak symbols in the output. Can
- be specified multiple times to mark multiple symbols as weak.
-
-.. option:: --weaken-symbols <filename>
-
- Read a list of names from the file ``<filename>`` and mark global symbols with
- those names as weak in the output. In the file, each line represents a single
- symbol, with leading and trailing whitespace ignored, as is anything following
- a '#'. Can be specified multiple times to read names from multiple files.
-
-.. option:: --weaken
-
- Mark all defined global symbols as weak in the output.
-
-MACH-O-SPECIFIC OPTIONS
------------------------
-
-.. option:: --keep-undefined
-
- Keep undefined symbols, even if they would otherwise be stripped.
-
-COFF-SPECIFIC OPTIONS
----------------------
-
-.. option:: --subsystem <name>[:<version>]
-
- Set the PE subsystem, and optionally subsystem version.
-
-SUPPORTED FORMATS
------------------
-
-The following values are currently supported by :program:`llvm-objcopy` for the
-:option:`--input-target`, :option:`--output-target`, and :option:`--target`
-options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.
+:::{option} --add-symbol <name>=[<section>:]<value>[,<flags>]
+Add a new symbol called `<name>` to the output symbol table, in the section
+named `<section>`, with value `<value>`. If `<section>` is not specified,
+the symbol is added as an absolute symbol. The `<flags>` affect the symbol
+properties. Accepted values are:
+
+- `global` = the symbol will have global binding.
+- `local` = the symbol will have local binding.
+- `weak` = the symbol will have weak binding.
+- `default` = the symbol will have default visibility.
+- `hidden` = the symbol will have hidden visibility.
+- `protected` = the symbol will have protected visibility.
+- `file` = the symbol will be an `STT_FILE` symbol.
+- `section` = the symbol will be an `STT_SECTION` symbol.
+- `object` = the symbol will be an `STT_OBJECT` symbol.
+- `function` = the symbol will be an `STT_FUNC` symbol.
+- `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
+
+Additionally, the following flags are accepted but ignored: `debug`,
+`constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
+
+Can be specified multiple times to add multiple symbols.
+:::
+
+:::{option} --allow-broken-links
+Allow {program}`llvm-objcopy` to remove sections even if it would leave invalid
+section references. Any invalid sh_link fields will be set to zero.
+:::
+
+:::{option} --change-section-lma \*{+-}<val>
+Shift LMA of non-zero-sized segments by `<val>`.
+:::
+
+:::{option} --change-section-address <section>{=+-}<val>, --adjust-section-vma
+Change the address of sections that match `<section>` pattern to the
+specified value, or apply `+<val>`/`-<val>` to the current value. Can be
+specified multiple times to specify multiple patterns. Each section is only
+modified by one `--change-section-address` argument. If a section name
+matches multiple patterns, the rightmost change applies. The object file needs
+to be of ET_REL type.
+:::
+
+:::{option} --change-start <incr>, --adjust-start
+Add `<incr>` to the program's start address. Can be specified multiple
+times, in which case the values will be applied cumulatively.
+:::
+
+:::{option} --compress-debug-sections [<format>]
+Compress DWARF debug sections in the output, using the specified format.
+Supported formats are `zlib` and `zstd`. Use `zlib` if `<format>` is omitted.
+:::
+
+:::{option} --compress-sections <section>=<format>
+Compress or decompress sections matched by `<section>` using the specified
+format. Supported formats are `zlib` and `zstd`. Specify `none` for
+decompression. When a section is matched by multiple options, the last one
+wins. A wildcard `<section>` starting with '!' is disallowed.
+Sections within a segment cannot be (de)compressed.
+:::
+
+:::{option} --decompress-debug-sections
+Decompress any compressed DWARF debug sections in the output.
+:::
+
+:::{option} --discard-locals, -X
+Remove local symbols starting with ".L" not referenced by relocations from the output.
+:::
+
+:::{option} --extract-dwo
+Remove all sections that are not DWARF .dwo sections from the output.
+:::
+
+:::{option} --extract-main-partition
+Extract the main partition from the output.
+:::
+
+:::{option} --extract-partition <name>
+Extract the named partition from the output.
+:::
+
+:::{option} --gap-fill <value>
+For binary outputs, fill the gaps between sections with `<value>` instead
+of zero. The value must be an unsigned 8-bit integer.
+:::
+
+:::{option} --input-target <format>, -I
+Read the input as the specified format. See [SUPPORTED FORMATS] for a list of
+valid `<format>` values. If unspecified, {program}`llvm-objcopy` will attempt
+to determine the format automatically.
+:::
+
+:::{option} --keep-file-symbols
+Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
+:::
+
+:::{option} --keep-section <section>
+When removing sections from the output, do not remove sections named
+`<section>`. Can be specified multiple times to keep multiple sections.
+:::
+
+:::{option} --keep-symbol <symbol>, -K
+When removing symbols from the output, do not remove symbols named
+`<symbol>`. Can be specified multiple times to keep multiple symbols.
+:::
+
+:::{option} --keep-symbols <filename>
+When removing symbols from the output do not remove symbols named in the file
+`<filename>`. In the file, each line represents a single symbol, with leading
+and trailing whitespace ignored, as is anything following a '#'. Can be
+specified multiple times to read names from multiple files.
+:::
+
+:::{option} --localize-hidden
+Mark all symbols with hidden or internal visibility local in the output.
+:::
+
+:::{option} --new-symbol-visibility <visibility>
+Specify the visibility of the symbols automatically created when using binary
+input or {option}`--add-symbol`. Valid options are:
+
+- `default`
+- `hidden`
+- `internal`
+- `protected`
+
+The default is `default`.
+:::
+
+:::{option} --no-verify-note-sections
+When adding note sections, do not verify if the section format is valid.
+:::
+
+:::{option} --output-target <format>, -O
+Write the output as the specified format. See [SUPPORTED FORMATS] for a list
+of valid `<format>` values. If unspecified, the output format is assumed to
+be the same as the value specified for {option}`--input-target` or the input
+file's format if that option is also unspecified.
+:::
+
+:::{option} --pad-to <address>
+For binary outputs, pad the output to the load address `<address>` using a value
+of zero or the value specified by {option}`--gap-fill`.
+:::
+
+:::{option} --prefix-alloc-sections <prefix>
+Add `<prefix>` to the front of the names of all allocatable sections in the
+output.
+:::
+
+:::{option} --prefix-symbols <prefix>
+Add `<prefix>` to the front of every symbol name in the output.
+:::
+
+:::{option} --preserve-dates, -p
+Preserve access and modification timestamps in the output.
+:::
+
+:::{option} --remove-note [<name>/]<type>
+Remove notes of integer type `<type>` and name `<name>` from SHT_NOTE
+sections that are not in a segment. Can be specified multiple times.
+:::
+
+:::{option} --rename-section <old>=<new>[,<flag>,...]
+Rename sections called `<old>` to `<new>` in the output, and apply any
+specified `<flag>` values. See {option}`--set-section-flags` for a list of
+supported flags. Can be specified multiple times to rename multiple sections.
+:::
+
+:::{option} --set-section-type <section>=<type>
+Set the type of section `<section>` to the integer `<type>`. Can be
+specified multiple times to update multiple sections.
+:::
+
+:::{option} --set-start <addr>
+Set the start address of the output to `<addr>`. Overrides any previously
+specified {option}`--change-start` or {option}`--adjust-start` options.
+:::
+
+:::{option} --set-symbol-visibility <symbol>=<visibility>
+Change the visibility of a symbol to the specified value.
+:::
+
+:::{option} --set-symbols-visibility <filename>=<visibility>
+Read a list of symbols from \<filename> and change their visibility to the
+specified value. Visibility values: default, internal, hidden, protected.
+:::
+
+:::{option} --split-dwo <dwo-file>
+Equivalent to running {program}`llvm-objcopy` with {option}`--extract-dwo` and
+`<dwo-file>` as the output file and no other options, and then with
+{option}`--strip-dwo` on the input file.
+:::
+
+:::{option} --strip-dwo
+Remove all DWARF .dwo sections from the output.
+:::
+
+:::{option} --strip-non-alloc
+Remove from the output all non-allocatable sections that are not within
+segments.
+:::
+
+:::{option} --strip-sections
+Remove from the output all section headers and all section data not within
+segments. Note that many tools will not be able to use an object without
+section headers.
+:::
+
+:::{option} --target <format>, -F
+Equivalent to {option}`--input-target` and {option}`--output-target` for the
+specified format. See [SUPPORTED FORMATS] for a list of valid `<format>`
+values.
+:::
+
+:::{option} --verify-note-sections
+When adding note sections, verify if the section format is valid. On by
+default.
+:::
+
+:::{option} --weaken-symbol <symbol>, -W
+Mark global symbols named `<symbol>` as weak symbols in the output. Can
+be specified multiple times to mark multiple symbols as weak.
+:::
+
+:::{option} --weaken-symbols <filename>
+Read a list of names from the file `<filename>` and mark global symbols with
+those names as weak in the output. In the file, each line represents a single
+symbol, with leading and trailing whitespace ignored, as is anything following
+a '#'. Can be specified multiple times to read names from multiple files.
+:::
+
+:::{option} --weaken
+Mark all defined global symbols as weak in the output.
+:::
+
+## MACH-O-SPECIFIC OPTIONS
+
+:::{option} --keep-undefined
+Keep undefined symbols, even if they would otherwise be stripped.
+:::
+
+## COFF-SPECIFIC OPTIONS
+
+:::{option} --subsystem <name>[:<version>]
+Set the PE subsystem, and optionally subsystem version.
+:::
+
+## SUPPORTED FORMATS
+
+The following values are currently supported by {program}`llvm-objcopy` for the
+{option}`--input-target`, {option}`--output-target`, and {option}`--target`
+options. For GNU {program}`objcopy` compatibility, the values are all bfdnames.
- `binary`
- `ihex`
@@ -623,46 +615,43 @@ options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.
- `elf64-s390`
- `elf64-amdgpu`
-The following formats are supported by :program:`llvm-objcopy` for the
-:option:`--output-target` only:
+The following formats are supported by {program}`llvm-objcopy` for the
+{option}`--output-target` only:
- `srec`
Additionally, all targets except `binary`, `ihex`, and `srec` can have
`-freebsd` as a suffix.
-BINARY INPUT AND OUTPUT
------------------------
+## BINARY INPUT AND OUTPUT
-If `binary` is used as the value for :option:`--input-target`, the input file
+If `binary` is used as the value for {option}`--input-target`, the input file
will be embedded as a data section in an ELF relocatable object, with symbols
-``_binary_<file_name>_start``, ``_binary_<file_name>_end``, and
-``_binary_<file_name>_size`` representing the start, end and size of the data,
-where ``<file_name>`` is the path of the input file as specified on the command
-line with non-alphanumeric characters converted to ``_``.
+`_binary_<file_name>_start`, `_binary_<file_name>_end`, and
+`_binary_<file_name>_size` representing the start, end and size of the data,
+where `<file_name>` is the path of the input file as specified on the command
+line with non-alphanumeric characters converted to `_`.
-If `binary` is used as the value for :option:`--output-target`, the output file
+If `binary` is used as the value for {option}`--output-target`, the output file
will be a raw binary file, containing the memory image of the input file.
Symbols and relocation information will be discarded. The image will start at
the address of the first loadable section in the output.
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-objcopy` exits with a non-zero exit code if there is an error.
+{program}`llvm-objcopy` 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/>>.
-There is a known issue with :option:`--input-target` and :option:`--target`
-causing only ``binary`` and ``ihex`` formats to have any effect. Other values
-will be ignored and :program:`llvm-objcopy` will attempt to guess the input
+There is a known issue with {option}`--input-target` and {option}`--target`
+causing only `binary` and `ihex` formats to have any effect. Other values
+will be ignored and {program}`llvm-objcopy` will attempt to guess the input
format.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-strip(1)`
-:manpage:`llvm-strip(1)`
diff --git a/llvm/docs/CommandGuide/llvm-objdump.md b/llvm/docs/CommandGuide/llvm-objdump.md
index f3cf5f67e38c5..e9290752a2bc8 100644
--- a/llvm/docs/CommandGuide/llvm-objdump.md
+++ b/llvm/docs/CommandGuide/llvm-objdump.md
@@ -1,511 +1,508 @@
-llvm-objdump - LLVM's object file dumper
-========================================
+# llvm-objdump - LLVM's object file dumper
+```{eval-rst}
.. program:: llvm-objdump
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-objdump` [*commands*] [*options*] [*filenames...*]
+{program}`llvm-objdump` \[*commands*\] \[*options*\] \[*filenames...*\]
-DESCRIPTION
------------
-The :program:`llvm-objdump` utility prints the contents of object files and
+## DESCRIPTION
+
+The {program}`llvm-objdump` utility prints the contents of object files and
final linked images named on the command line. If no file name is specified,
-:program:`llvm-objdump` will attempt to read from *a.out*. If *-* is used as a
-file name, :program:`llvm-objdump` will process a file on its standard input
+{program}`llvm-objdump` will attempt to read from *a.out*. If *-* is used as a
+file name, {program}`llvm-objdump` will process a file on its standard input
stream.
-COMMANDS
---------
+## COMMANDS
+
At least one of the following commands are required, and some commands can be
combined with other commands:
-.. option:: -a, --archive-headers
-
- Display the information contained within an archive's headers.
-
-.. option:: -d, --disassemble
-
- Disassemble all executable sections found in the input files. On some
- architectures (AArch64, PowerPC, x86), all known instructions are disassembled by
- default. On the others, :option:`--mcpu` or :option:`--mattr` is needed to
- enable some instruction sets. Disabled instructions are displayed as
- ``<unknown>``.
-
-.. option:: -D, --disassemble-all
-
- Disassemble all sections found in the input files.
-
-.. option:: --disassemble-symbols=<symbol1[,symbol2,...]>
-
-.. option:: --disassemble=symbol1 --disassemble=symbol2 ...
-
- Disassemble only the specified symbols. Takes demangled symbol names when
- :option:`--demangle` is specified, otherwise takes mangled symbol names.
- Implies :option:`--disassemble`.
-
-.. option:: --dwarf=<value>
-
- Dump the specified DWARF debug sections. The supported values are:
-
- `frames` - .debug_frame
-
-.. option:: -f, --file-headers
-
- Display the contents of the overall file header.
-
-.. option:: --fault-map-section
-
- Display the content of the fault map section.
-
-.. option:: -h, --headers, --section-headers
-
- Display summaries of the headers for each section.
-
-.. option:: --help
-
- Display usage information and exit. Does not stack with other commands.
-
-.. option:: -p, --private-headers
-
- Display format-specific file headers.
-
-.. option:: -r, --reloc
-
- Display the relocation entries in the file.
-
-.. option:: -R, --dynamic-reloc
-
- Display the dynamic relocation entries in the file.
-
-.. option:: --raw-clang-ast
-
- Dump the raw binary contents of the clang AST section.
-
-.. option:: -s, --full-contents
-
- Display the contents of each section.
-
-.. option:: -t, --syms
-
- Display the symbol table.
-
-.. option:: -T, --dynamic-syms
-
- Display the contents of the dynamic symbol table.
-
-.. option:: -u, --unwind-info
-
- Display the unwind info of the input(s).
-
- This operation is only currently supported for COFF and Mach-O object files.
-
-.. option:: -v, --version
-
- Display the version of the :program:`llvm-objdump` executable. Does not stack
- with other commands.
-
-.. option:: -x, --all-headers
-
- Display all available header information. Equivalent to specifying
- :option:`--archive-headers`, :option:`--file-headers`,
- :option:`--private-headers`, :option:`--reloc`, :option:`--section-headers`,
- and :option:`--syms`.
-
-OPTIONS
--------
-:program:`llvm-objdump` supports the following options:
-
-.. option:: --adjust-vma=<offset>
-
- Increase the displayed address in disassembly or section header printing by
- the specified offset.
-
-.. option:: --arch-name=<string>
-
- Specify the target architecture when disassembling. Use :option:`--version`
- for a list of available targets.
-
-.. option:: --build-id=<string>
-
- Look up the object using the given build ID, specified as a hexadecimal
- string. The found object is handled as if it were an input filename.
-
-.. option:: -C, --demangle
-
- Demangle symbol names in the output.
-
-.. option:: --debug-file-directory <path>
-
- Provide a path to a directory with a `.build-id` subdirectory to search for
- debug information for stripped binaries. Multiple instances of this argument
- are searched in the order given.
-
-.. option:: --debug-indent=<width>
-
- Distance to indent the source-level variable or inlined function display,
- relative to the start of the disassembly. Defaults to 52 characters.
-
-.. option:: --debug-inlined-funcs[=<format>]
-
- Print the locations of inlined functions alongside disassembly.
- ``format`` may be ``ascii``, ``limits-only``, or ``unicode``, defaulting to
- ``unicode`` if omitted.
-
-.. option:: --debug-vars[=<format>]
-
- Print the locations (in registers or memory) of source-level variables
- alongside disassembly. ``format`` may be ``ascii`` or ``unicode``, defaulting
- to ``unicode`` if omitted.
-
-.. option:: --debuginfod, --no-debuginfod
-
- Whether or not to try debuginfod lookups for debug binaries. Unless specified,
- debuginfod is only enabled if libcurl was compiled in (``LLVM_ENABLE_CURL``)
- and at least one server URL was provided by the environment variable
- ``DEBUGINFOD_URLS``.
-
-.. option:: -j, --section=<section1[,section2,...]>
-
- Perform commands on the specified sections only. For Mach-O use
- `segment,section` to specify the section name.
-
-.. option:: -l, --line-numbers
-
- When disassembling, display source line numbers. Implies
- :option:`--disassemble`.
-
-.. option:: -M, --disassembler-options=<opt1[,opt2,...]>
-
- Pass target-specific disassembler options. Available options:
-
- * ``reg-names-std``: ARM only (default). Print in ARM 's instruction set documentation, with r13/r14/r15 replaced by sp/lr/pc.
- * ``reg-names-raw``: ARM only. Use r followed by the register number.
- * ``no-aliases``: AArch64 and RISC-V only. Print raw instruction mnemonic instead of pseudo instruction mnemonic.
- * ``numeric``: RISC-V only. Print raw register names instead of ABI mnemonic. (e.g. print x1 instead of ra)
- * ``att``: x86 only (default). Print in the AT&T syntax.
- * ``intel``: x86 only. Print in the intel syntax.
-
-
-.. option:: --disassembler-color=<mode>
-
- Enable or disable disassembler color output.
-
- * ``off``: Disable disassembler color output.
- * ``on``: Enable disassembler color output.
- * ``terminal``: Enable disassembler color output if the terminal supports it (default).
-
-.. option:: --mcpu=<cpu-name>
-
- Target a specific CPU type for disassembly. Specify ``--mcpu=help`` to display
- available CPUs.
-
-.. option:: --mattr=<a1,+a2,-a3,...>
-
- Enable/disable target-specific attributes. Specify ``--mattr=help`` to display
- the available attributes.
-
-.. option:: -mllvm <arg>
-
- Specify an argument to forward to LLVM's CommandLine library.
-
-.. option:: --no-leading-addr, --no-addresses
-
- When disassembling, do not print leading addresses for instructions or inline
- relocations.
-
-.. option:: --no-print-imm-hex
-
- Do not use hex format for immediate values in disassembly output.
-
-.. option:: --no-show-raw-insn
-
- When disassembling, do not print the raw bytes of each instruction.
-
-.. option:: --offloading
-
- Display the content of the LLVM offloading sections and HIP offload bundles.
-
-.. option:: --prefix=<prefix>
-
- When disassembling with the :option:`--source` option, prepend ``prefix`` to
- absolute paths.
-
-.. option:: --prefix-strip=<level>
-
- When disassembling with the :option:`--source` option, strip out ``level``
- initial directories from absolute paths. This option has no effect without
- :option:`--prefix`.
-
-.. option:: --source-dir <dir>
-
- When disassembling with the :option:`--source` option, add ``dir`` to the
- front of the source search path when looking up source files. For each source
- file, llvm-objdump tries the path from the debug info, then each search
- directory with the full path appended, then each search directory with only
- the file name.
- This option may be specified multiple times; each ``--source-dir`` adds one
- directory. Options on the command line are searched in first to last order.
-
-.. option:: --substitute-path <from> <to>
-
- When disassembling with the :option:`--source` option, replace ``from`` with
- ``to`` at the start of the directory part of source file paths when looking up
- sources. A rule is applied only if ``from`` ends at a directory separator in
- the path. This option may be specified multiple times; rules are evaluated in
- the order given and the first matching rule is used, as in GDB
- ``set substitute-path``.
-
-.. option:: --print-imm-hex
-
- Use hex format when printing immediate values in disassembly output (default).
-
-.. option:: -S, --source
-
- When disassembling, display source interleaved with the disassembly. Implies
- :option:`--disassemble`.
-
-.. option:: --show-all-symbols
-
- Show all symbols during disassembly, even if multiple symbols are defined at
- the same location.
-
-.. option:: --show-lma
-
- Display the LMA column when dumping ELF section headers. Defaults to off
- unless any section has different VMA and LMAs.
-
-.. option:: --start-address=<address>
-
- When disassembling, only disassemble from the specified address.
-
- When printing relocations, only print the relocations patching offsets from at least ``address``.
-
- When printing symbols, only print symbols with a value of at least ``address``.
-
-.. option:: --stop-address=<address>
-
- When disassembling, only disassemble up to, but not including the specified address.
-
- When printing relocations, only print the relocations patching offsets up to ``address``.
-
- When printing symbols, only print symbols with a value up to ``address``.
-
-.. option:: --symbolize-operands, --no-symbolize-operands
-
- When disassembling, symbolize a branch target operand to print a label instead of a real address.
-
- When printing a PC-relative global symbol reference, print it as an offset from the leading symbol.
-
- When a bb-address-map section is present (i.e., the object file is built with
- ``-fbasic-block-address-map``), labels are retrieved from that section
- instead. If a pgo-analysis-map is present alongside the bb-address-map, any
- available analyses are printed after the relevant block label. By default,
- any analysis with a special representation (i.e. BlockFrequency,
- BranchProbability, etc) are printed as raw hex values.
-
- Only supported for AArch64, BPF, PowerPC, RISC-V, and X86. Enabled by default
- for BPF; use ``--no-symbolize-operands`` to disable.
-
- Example:
- A non-symbolized branch instruction with a local target and pc-relative memory access like
-
- .. code-block:: none
-
- cmp eax, dword ptr [rip + 4112]
- jge 0x20117e <_start+0x25>
-
- might become
-
- .. code-block:: none
-
- <L0>:
- cmp eax, dword ptr <g>
- jge <L0>
-
-.. option:: --pretty-pgo-analysis-map
-
- When using :option:`--symbolize-operands` with bb-address-map and
- pgo-analysis-map, print analyses using the same format as their analysis
- passes would. An example of pretty format would be printing block frequencies
- relative to the entry block, the same as BFI.
-
- Only works when :option:`--symbolize-operands` is enabled.
-
-.. option:: --triple=<string>
-
- Target triple to disassemble for, see ``--version`` for available targets.
-
-.. option:: -w, --wide
-
- Ignored for compatibility with GNU objdump.
-
-.. option:: --x86-asm-syntax=<style>
-
- Deprecated.
- When used with :option:`--disassemble`, choose style of code to emit from
- X86 backend. Supported values are:
-
- .. option:: att
-
- AT&T-style assembly
-
- .. option:: intel
-
- Intel-style assembly
-
-
- The default disassembly style is **att**.
-
-.. option:: -z, --disassemble-zeroes
-
- Do not skip blocks of zeroes when disassembling.
-
-.. option:: @<FILE>
-
- Read command-line options and commands from response file `<FILE>`.
-
-MACH-O ONLY OPTIONS AND COMMANDS
---------------------------------
-
-.. option:: --arch=<architecture>
-
- Specify the architecture to disassemble. see ``--version`` for available
- architectures.
-
-.. option:: --archive-member-offsets
-
- Print the offset to each archive member for Mach-O archives (requires
- :option:`--archive-headers`).
-
-.. option:: --bind
-
- Display binding info
-
-.. option:: --data-in-code
-
- Display the data in code table.
-
-.. option:: --dis-symname=<name>
-
- Disassemble just the specified symbol's instructions.
-
-.. option:: --chained-fixups
-
- Print chained fixup information.
-
-.. option:: --dyld-info
-
- Print bind and rebase information used by dyld to resolve external
- references in a final linked binary.
-
-.. option:: --dylibs-used
-
- Display the shared libraries used for linked files.
-
-.. option:: --dsym=<string>
-
- Use .dSYM file for debug info.
-
-.. option:: --dylib-id
-
- Display the shared library's ID for dylib files.
-
-.. option:: --exports-trie
-
- Display exported symbols.
-
-.. option:: --function-starts [=<addrs|names|both>]
-
- Print the function starts table for Mach-O objects. Either ``addrs``
- (default) to print only the addresses of functions, ``names`` to print only
- the names of the functions (when available), or ``both`` to print the
- names beside the addresses.
-
-.. option:: -g
-
- Print line information from debug info if available.
-
-.. option:: --full-leading-addr
-
- Print the full leading address when disassembling.
-
-.. option:: --indirect-symbols
+:::{option} -a, --archive-headers
+Display the information contained within an archive's headers.
+:::
- Display the indirect symbol table.
+:::{option} -d, --disassemble
+Disassemble all executable sections found in the input files. On some
+architectures (AArch64, PowerPC, x86), all known instructions are disassembled by
+default. On the others, {option}`--mcpu` or {option}`--mattr` is needed to
+enable some instruction sets. Disabled instructions are displayed as
+`<unknown>`.
+:::
-.. option:: --info-plist
+:::{option} -D, --disassemble-all
+Disassemble all sections found in the input files.
+:::
- Display the info plist section as strings.
+:::{option} --disassemble-symbols=<symbol1[,symbol2,...]>
+:::
+
+:::{option} --disassemble=symbol1 --disassemble=symbol2 ...
+Disassemble only the specified symbols. Takes demangled symbol names when
+{option}`--demangle` is specified, otherwise takes mangled symbol names.
+Implies {option}`--disassemble`.
+:::
+
+:::{option} --dwarf=<value>
+Dump the specified DWARF debug sections. The supported values are:
+
+`frames` - .debug_frame
+:::
+
+:::{option} -f, --file-headers
+Display the contents of the overall file header.
+:::
+
+:::{option} --fault-map-section
+Display the content of the fault map section.
+:::
+
+:::{option} -h, --headers, --section-headers
+Display summaries of the headers for each section.
+:::
+
+:::{option} --help
+Display usage information and exit. Does not stack with other commands.
+:::
+
+:::{option} -p, --private-headers
+Display format-specific file headers.
+:::
+
+:::{option} -r, --reloc
+Display the relocation entries in the file.
+:::
+
+:::{option} -R, --dynamic-reloc
+Display the dynamic relocation entries in the file.
+:::
+
+:::{option} --raw-clang-ast
+Dump the raw binary contents of the clang AST section.
+:::
+
+:::{option} -s, --full-contents
+Display the contents of each section.
+:::
+
+:::{option} -t, --syms
+Display the symbol table.
+:::
+
+:::{option} -T, --dynamic-syms
+Display the contents of the dynamic symbol table.
+:::
+
+:::{option} -u, --unwind-info
+Display the unwind info of the input(s).
+
+This operation is only currently supported for COFF and Mach-O object files.
+:::
+
+:::{option} -v, --version
+Display the version of the {program}`llvm-objdump` executable. Does not stack
+with other commands.
+:::
+
+:::{option} -x, --all-headers
+Display all available header information. Equivalent to specifying
+{option}`--archive-headers`, {option}`--file-headers`,
+{option}`--private-headers`, {option}`--reloc`, {option}`--section-headers`,
+and {option}`--syms`.
+:::
+
+## OPTIONS
+
+{program}`llvm-objdump` supports the following options:
+
+:::{option} --adjust-vma=<offset>
+Increase the displayed address in disassembly or section header printing by
+the specified offset.
+:::
+
+:::{option} --arch-name=<string>
+Specify the target architecture when disassembling. Use {option}`--version`
+for a list of available targets.
+:::
+
+:::{option} --build-id=<string>
+Look up the object using the given build ID, specified as a hexadecimal
+string. The found object is handled as if it were an input filename.
+:::
+
+:::{option} -C, --demangle
+Demangle symbol names in the output.
+:::
+
+:::{option} --debug-file-directory <path>
+Provide a path to a directory with a `.build-id` subdirectory to search for
+debug information for stripped binaries. Multiple instances of this argument
+are searched in the order given.
+:::
+
+:::{option} --debug-indent=<width>
+Distance to indent the source-level variable or inlined function display,
+relative to the start of the disassembly. Defaults to 52 characters.
+:::
+
+:::{option} --debug-inlined-funcs[=<format>]
+Print the locations of inlined functions alongside disassembly.
+`format` may be `ascii`, `limits-only`, or `unicode`, defaulting to
+`unicode` if omitted.
+:::
+
+:::{option} --debug-vars[=<format>]
+Print the locations (in registers or memory) of source-level variables
+alongside disassembly. `format` may be `ascii` or `unicode`, defaulting
+to `unicode` if omitted.
+:::
+
+:::{option} --debuginfod, --no-debuginfod
+Whether or not to try debuginfod lookups for debug binaries. Unless specified,
+debuginfod is only enabled if libcurl was compiled in (`LLVM_ENABLE_CURL`)
+and at least one server URL was provided by the environment variable
+`DEBUGINFOD_URLS`.
+:::
+
+:::{option} -j, --section=<section1[,section2,...]>
+Perform commands on the specified sections only. For Mach-O use
+`segment,section` to specify the section name.
+:::
+
+:::{option} -l, --line-numbers
+When disassembling, display source line numbers. Implies
+{option}`--disassemble`.
+:::
+
+:::{option} -M, --disassembler-options=<opt1[,opt2,...]>
+Pass target-specific disassembler options. Available options:
+
+- `reg-names-std`: ARM only (default). Print in ARM 's instruction set documentation, with r13/r14/r15 replaced by sp/lr/pc.
+- `reg-names-raw`: ARM only. Use r followed by the register number.
+- `no-aliases`: AArch64 and RISC-V only. Print raw instruction mnemonic instead of pseudo instruction mnemonic.
+- `numeric`: RISC-V only. Print raw register names instead of ABI mnemonic. (e.g. print x1 instead of ra)
+- `att`: x86 only (default). Print in the AT&T syntax.
+- `intel`: x86 only. Print in the intel syntax.
+:::
+
+:::{option} --disassembler-color=<mode>
+Enable or disable disassembler color output.
+
+- `off`: Disable disassembler color output.
+- `on`: Enable disassembler color output.
+- `terminal`: Enable disassembler color output if the terminal supports it (default).
+:::
+
+:::{option} --mcpu=<cpu-name>
+Target a specific CPU type for disassembly. Specify `--mcpu=help` to display
+available CPUs.
+:::
+
+:::{option} --mattr=<a1,+a2,-a3,...>
+Enable/disable target-specific attributes. Specify `--mattr=help` to display
+the available attributes.
+:::
+
+:::{option} -mllvm <arg>
+Specify an argument to forward to LLVM's CommandLine library.
+:::
+
+:::{option} --no-leading-addr, --no-addresses
+When disassembling, do not print leading addresses for instructions or inline
+relocations.
+:::
+
+:::{option} --no-print-imm-hex
+Do not use hex format for immediate values in disassembly output.
+:::
+
+:::{option} --no-show-raw-insn
+When disassembling, do not print the raw bytes of each instruction.
+:::
+
+:::{option} --offloading
+Display the content of the LLVM offloading sections and HIP offload bundles.
+:::
+
+:::{option} --prefix=<prefix>
+When disassembling with the {option}`--source` option, prepend `prefix` to
+absolute paths.
+:::
+
+:::{option} --prefix-strip=<level>
+When disassembling with the {option}`--source` option, strip out `level`
+initial directories from absolute paths. This option has no effect without
+{option}`--prefix`.
+:::
+
+:::{option} --source-dir <dir>
+When disassembling with the {option}`--source` option, add `dir` to the
+front of the source search path when looking up source files. For each source
+file, llvm-objdump tries the path from the debug info, then each search
+directory with the full path appended, then each search directory with only
+the file name.
+This option may be specified multiple times; each `--source-dir` adds one
+directory. Options on the command line are searched in first to last order.
+:::
+
+:::{option} --substitute-path <from> <to>
+When disassembling with the {option}`--source` option, replace `from` with
+`to` at the start of the directory part of source file paths when looking up
+sources. A rule is applied only if `from` ends at a directory separator in
+the path. This option may be specified multiple times; rules are evaluated in
+the order given and the first matching rule is used, as in GDB
+`set substitute-path`.
+:::
+
+:::{option} --print-imm-hex
+Use hex format when printing immediate values in disassembly output (default).
+:::
+
+:::{option} -S, --source
+When disassembling, display source interleaved with the disassembly. Implies
+{option}`--disassemble`.
+:::
+
+:::{option} --show-all-symbols
+Show all symbols during disassembly, even if multiple symbols are defined at
+the same location.
+:::
+
+:::{option} --show-lma
+Display the LMA column when dumping ELF section headers. Defaults to off
+unless any section has different VMA and LMAs.
+:::
+
+:::{option} --start-address=<address>
+When disassembling, only disassemble from the specified address.
+
+When printing relocations, only print the relocations patching offsets from at least `address`.
+
+When printing symbols, only print symbols with a value of at least `address`.
+:::
+
+:::{option} --stop-address=<address>
+When disassembling, only disassemble up to, but not including the specified address.
+
+When printing relocations, only print the relocations patching offsets up to `address`.
+
+When printing symbols, only print symbols with a value up to `address`.
+:::
+
+:::{option} --symbolize-operands, --no-symbolize-operands
+When disassembling, symbolize a branch target operand to print a label instead of a real address.
+
+When printing a PC-relative global symbol reference, print it as an offset from the leading symbol.
+
+When a bb-address-map section is present (i.e., the object file is built with
+`-fbasic-block-address-map`), labels are retrieved from that section
+instead. If a pgo-analysis-map is present alongside the bb-address-map, any
+available analyses are printed after the relevant block label. By default,
+any analysis with a special representation (i.e. BlockFrequency,
+BranchProbability, etc) are printed as raw hex values.
+
+Only supported for AArch64, BPF, PowerPC, RISC-V, and X86. Enabled by default
+for BPF; use `--no-symbolize-operands` to disable.
+
+Example:
+
+: A non-symbolized branch instruction with a local target and pc-relative memory access like
+
+```none
+cmp eax, dword ptr [rip + 4112]
+jge 0x20117e <_start+0x25>
+```
+
+might become
+
+```none
+<L0>:
+ cmp eax, dword ptr <g>
+ jge <L0>
+```
+:::
+
+:::{option} --pretty-pgo-analysis-map
+When using {option}`--symbolize-operands` with bb-address-map and
+pgo-analysis-map, print analyses using the same format as their analysis
+passes would. An example of pretty format would be printing block frequencies
+relative to the entry block, the same as BFI.
+
+Only works when {option}`--symbolize-operands` is enabled.
+:::
+
+:::{option} --triple=<string>
+Target triple to disassemble for, see `--version` for available targets.
+:::
+
+:::{option} -w, --wide
+Ignored for compatibility with GNU objdump.
+:::
+
+::::{option} --x86-asm-syntax=<style>
+Deprecated.
+When used with {option}`--disassemble`, choose style of code to emit from
+X86 backend. Supported values are:
+
+> :::{option} att
+> AT&T-style assembly
+> :::
+>
+> :::{option} intel
+> Intel-style assembly
+> :::
-.. option:: --lazy-bind
+The default disassembly style is **att**.
+::::
+
+:::{option} -z, --disassemble-zeroes
+Do not skip blocks of zeroes when disassembling.
+:::
+
+:::{option} @<FILE>
+Read command-line options and commands from response file `<FILE>`.
+:::
- Display lazy binding info.
+## MACH-O ONLY OPTIONS AND COMMANDS
-.. option:: --link-opt-hints
+:::{option} --arch=<architecture>
+Specify the architecture to disassemble. see `--version` for available
+architectures.
+:::
- Display the linker optimization hints.
+:::{option} --archive-member-offsets
+Print the offset to each archive member for Mach-O archives (requires
+{option}`--archive-headers`).
+:::
-.. option:: -m, --macho
+:::{option} --bind
+Display binding info
+:::
+
+:::{option} --data-in-code
+Display the data in code table.
+:::
+
+:::{option} --dis-symname=<name>
+Disassemble just the specified symbol's instructions.
+:::
+
+:::{option} --chained-fixups
+Print chained fixup information.
+:::
+
+:::{option} --dyld-info
+Print bind and rebase information used by dyld to resolve external
+references in a final linked binary.
+:::
+
+:::{option} --dylibs-used
+Display the shared libraries used for linked files.
+:::
- Use Mach-O specific object file parser. Commands and other options may behave
- differently when used with ``--macho``.
+:::{option} --dsym=<string>
+Use .dSYM file for debug info.
+:::
-.. option:: --no-leading-headers
+:::{option} --dylib-id
+Display the shared library's ID for dylib files.
+:::
- Do not print any leading headers.
+:::{option} --exports-trie
+Display exported symbols.
+:::
-.. option:: --no-symbolic-operands
+:::{option} --function-starts [=<addrs|names|both>]
+Print the function starts table for Mach-O objects. Either `addrs`
+(default) to print only the addresses of functions, `names` to print only
+the names of the functions (when available), or `both` to print the
+names beside the addresses.
+:::
- Do not print symbolic operands when disassembling.
+:::{option} -g
+Print line information from debug info if available.
+:::
-.. option:: --non-verbose
+:::{option} --full-leading-addr
+Print the full leading address when disassembling.
+:::
- Display the information for Mach-O objects in non-verbose or numeric form.
+:::{option} --indirect-symbols
+Display the indirect symbol table.
+:::
-.. option:: --objc-meta-data
+:::{option} --info-plist
+Display the info plist section as strings.
+:::
- Display the Objective-C runtime meta data.
+:::{option} --lazy-bind
+Display lazy binding info.
+:::
-.. option:: --private-header
+:::{option} --link-opt-hints
+Display the linker optimization hints.
+:::
- Display only the first format specific file header.
+:::{option} -m, --macho
+Use Mach-O specific object file parser. Commands and other options may behave
+differently when used with `--macho`.
+:::
-.. option:: --rebase
+:::{option} --no-leading-headers
+Do not print any leading headers.
+:::
- Display rebasing information.
+:::{option} --no-symbolic-operands
+Do not print symbolic operands when disassembling.
+:::
-.. option:: --rpaths
+:::{option} --non-verbose
+Display the information for Mach-O objects in non-verbose or numeric form.
+:::
- Display runtime search paths for the binary.
+:::{option} --objc-meta-data
+Display the Objective-C runtime meta data.
+:::
-.. option:: --universal-headers
+:::{option} --private-header
+Display only the first format specific file header.
+:::
- Display universal headers.
+:::{option} --rebase
+Display rebasing information.
+:::
-.. option:: --weak-bind
+:::{option} --rpaths
+Display runtime search paths for the binary.
+:::
- Display weak binding information.
+:::{option} --universal-headers
+Display universal headers.
+:::
-XCOFF ONLY OPTIONS AND COMMANDS
----------------------------------
+:::{option} --weak-bind
+Display weak binding information.
+:::
-.. option:: --symbol-description
+## XCOFF ONLY OPTIONS AND COMMANDS
- Add symbol description to disassembly output.
+:::{option} --symbol-description
+Add symbol description to disassembly output.
+:::
-.. option:: --traceback-table
+:::{option} --traceback-table
+Decode traceback table in disassembly output. Implies {option}`--disassemble`.
+:::
- Decode traceback table in disassembly output. Implies :option:`--disassemble`.
+## BUGS
-BUGS
-----
+To report bugs, please visit \<<https://github.com/llvm/llvm-project/labels/tools:llvm-objdump/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objdump/>.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-nm(1)`, {manpage}`llvm-otool(1)`, {manpage}`llvm-readelf(1)`,
+{manpage}`llvm-readobj(1)`
-:manpage:`llvm-nm(1)`, :manpage:`llvm-otool(1)`, :manpage:`llvm-readelf(1)`,
-:manpage:`llvm-readobj(1)`
diff --git a/llvm/docs/CommandGuide/llvm-offload-binary.md b/llvm/docs/CommandGuide/llvm-offload-binary.md
index 59ee472d8c3ee..3b10816ceeecd 100644
--- a/llvm/docs/CommandGuide/llvm-offload-binary.md
+++ b/llvm/docs/CommandGuide/llvm-offload-binary.md
@@ -1,118 +1,115 @@
-llvm-offload-binary - LLVM Offload Binary Packager
-==================================================
+# llvm-offload-binary - LLVM Offload Binary Packager
+```{eval-rst}
.. program:: llvm-offload-binary
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-offload-binary` [*options*] [*input files...*]
+{program}`llvm-offload-binary` \[*options*\] \[*input files...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-offload-binary` is a utility for bundling multiple device object
+{program}`llvm-offload-binary` is a utility for bundling multiple device object
files into a single binary container. The resulting binary can then be embedded
into the host section table to form a fat binary containing offloading code for
different targets. Conversely, it can also extract previously bundled device
images from offload binaries.
-When extracting images, if no :option:`--image` filters are specified, all
+When extracting images, if no {option}`--image` filters are specified, all
offload images are automatically extracted with descriptive filenames. When
-:option:`--image` filters are provided, only matching images are extracted.
+{option}`--image` filters are provided, only matching images are extracted.
The tool supports nested OffloadBinary format, where device images can be wrapped
in an inner OffloadBinary container. When extracting, the tool automatically
detects and unwraps nested OffloadBinary images, making the format transparent
to users.
-The binary format begins with the magic bytes ``0x10FF10AD``, followed by a
+The binary format begins with the magic bytes `0x10FF10AD`, followed by a
version and size. Each binary contains its own header, allowing tools to locate
offloading sections even when merged by a linker. Each offload entry includes
metadata such as the device image kind, producer kind, and key-value string
metadata. Multiple offloading images are concatenated to form a fat binary.
-EXAMPLE
--------
+## EXAMPLE
-.. code-block:: console
+```console
+# Package multiple device images into a fat binary:
+$ llvm-offload-binary -o out.bin \
+ --image=file=input.o,triple=nvptx64,arch=sm_70
- # Package multiple device images into a fat binary:
- $ llvm-offload-binary -o out.bin \
- --image=file=input.o,triple=nvptx64,arch=sm_70
+# Extract all offload images from an executable (no filters):
+$ llvm-offload-binary in.bin
+# Output:
+# Extracted: in-nvptx64-nvidia-cuda-sm_70.0.bc
+# Extracted: in-spirv64-intel-unknown.0.spv
- # Extract all offload images from an executable (no filters):
- $ llvm-offload-binary in.bin
- # Output:
- # Extracted: in-nvptx64-nvidia-cuda-sm_70.0.bc
- # Extracted: in-spirv64-intel-unknown.0.spv
+# Extract only SPIR-V images using filters:
+$ llvm-offload-binary in.bin --image=triple=spirv64-intel
+# Output:
+# Extracted: in-spirv64-intel-unknown.0.spv
- # Extract only SPIR-V images using filters:
- $ llvm-offload-binary in.bin --image=triple=spirv64-intel
- # Output:
- # Extracted: in-spirv64-intel-unknown.0.spv
+# Extract filtered images to a specific file:
+$ llvm-offload-binary in.bin --image=file=output.bc,arch=sm_70
- # Extract filtered images to a specific file:
- $ llvm-offload-binary in.bin --image=file=output.bc,arch=sm_70
+# Extract filtered images to an archive:
+$ llvm-offload-binary in.bin --image=file=output.a,triple=nvptx64 --archive
+```
- # Extract filtered images to an archive:
- $ llvm-offload-binary in.bin --image=file=output.a,triple=nvptx64 --archive
+## OPTIONS
-OPTIONS
--------
+:::{option} --archive
+When extracting from an input binary, write all extracted images into a static
+archive instead of separate files.
+:::
-.. option:: --archive
+:::{option} --image=<<key>=<value>,...>
+Specify a set of arbitrary key-value arguments describing an image.
+Commonly used optional keys include `arch` (e.g. `sm_70` for CUDA) and
+`triple` (e.g. nvptx64-nvidia-cuda).
- When extracting from an input binary, write all extracted images into a static
- archive instead of separate files.
+When bundling, this option specifies images to include in the output binary.
+When extracting, this option acts as a filter: only images matching the
+specified keys are extracted. If no {option}`--image` options are provided
+during extraction, all images are automatically extracted with descriptive
+filenames.
-.. option:: --image=<<key>=<value>,...>
+When extracting from a static archive, the `member` key restricts the output
+to a single archive member for cases when `--archive` is insufficient.
+, e.g.
+`--image=member=foo.o,triple=nvptx64,arch=sm_70,file=out.o`.
+:::
- Specify a set of arbitrary key-value arguments describing an image.
- Commonly used optional keys include ``arch`` (e.g. ``sm_70`` for CUDA) and
- ``triple`` (e.g. nvptx64-nvidia-cuda).
+:::{option} -o <file>
+Write output to \<file>. When bundling, this specifies the fat binary filename.
+When extracting, this specifies the archive or output file destination.
+:::
- When bundling, this option specifies images to include in the output binary.
- When extracting, this option acts as a filter: only images matching the
- specified keys are extracted. If no :option:`--image` options are provided
- during extraction, all images are automatically extracted with descriptive
- filenames.
+:::{option} --help, -h
+Display available options. Use `--help-hidden` to show hidden options.
+:::
- When extracting from a static archive, the ``member`` key restricts the output
- to a single archive member for cases when `--archive` is insufficient.
- , e.g.
- ``--image=member=foo.o,triple=nvptx64,arch=sm_70,file=out.o``.
+:::{option} --help-list
+Display a list of all options. Use `--help-list-hidden` to show hidden ones.
+:::
-.. option:: -o <file>
+:::{option} --version
+Display the version of the {program}`llvm-offload-binary` executable.
+:::
- Write output to <file>. When bundling, this specifies the fat binary filename.
- When extracting, this specifies the archive or output file destination.
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
-.. option:: --help, -h
+## BINARY FORMAT
- Display available options. Use ``--help-hidden`` to show hidden options.
-
-.. option:: --help-list
-
- Display a list of all options. Use ``--help-list-hidden`` to show hidden ones.
-
-.. option:: --version
-
- Display the version of the :program:`llvm-offload-binary` executable.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-BINARY FORMAT
--------------
-
-The binary format is marked by the magic bytes ``0x10FF10AD``, followed by a
+The binary format is marked by the magic bytes `0x10FF10AD`, followed by a
version number. Each created binary contains its own header. This allows tools
to locate offloading sections even after linker operations such as relocatable
linking. Conceptually, this binary format is a serialization of a string map and
an image buffer.
+```{eval-rst}
.. table:: Offloading Binary Header
:name: table-binary_header
@@ -129,9 +126,11 @@ an image buffer.
+----------+--------------+----------------------------------------------------+
| uint64_t | entry size | Size of the offload entries in bytes |
+----------+--------------+----------------------------------------------------+
+```
Each offload entry describes a bundled image along with its associated metadata.
+```{eval-rst}
.. table:: Offloading Entry Table
:name: table-binary_entry
@@ -152,10 +151,12 @@ Each offload entry describes a bundled image along with its associated metadata.
+----------+---------------+----------------------------------------------------+
| uint64_t | image size | Size of the device image in bytes |
+----------+---------------+----------------------------------------------------+
+```
The entry table refers to both a string table and the raw device image itself.
The string table provides arbitrary key-value metadata.
+```{eval-rst}
.. table:: Offloading String Entry
:name: table-binary_string
@@ -166,13 +167,15 @@ The string table provides arbitrary key-value metadata.
+----------+--------------+-------------------------------------------------------+
| uint64_t | value offset | Absolute byte offset of the value in the string table |
+----------+--------------+-------------------------------------------------------+
+```
The string table is a collection of null-terminated strings stored in the image.
Offsets allow string entries to be interpreted as key-value pairs, enabling
flexible metadata such as architecture or target triple.
-The enumerated values for ``image kind`` and ``offload kind`` are:
+The enumerated values for `image kind` and `offload kind` are:
+```{eval-rst}
.. table:: Image Kind
:name: table-image_kind
@@ -191,7 +194,9 @@ The enumerated values for ``image kind`` and ``offload kind`` are:
+---------------+-------+---------------------------------------+
| IMG_PTX | 0x05 | The image is a CUDA PTX file |
+---------------+-------+---------------------------------------+
+```
+```{eval-rst}
.. table:: Offload Kind
:name: table-offload_kind
@@ -208,76 +213,76 @@ The enumerated values for ``image kind`` and ``offload kind`` are:
+------------+-------+---------------------------------------+
| OFK_SYCL | 0x04 | The producer was SYCL |
+------------+-------+---------------------------------------+
+```
-COMMON WORKFLOWS
-----------------
+## COMMON WORKFLOWS
**Workflow 1: Explore Executable Contents**
Extract all embedded offload images to see what's inside:
-.. code-block:: console
-
- $ clang++ -fopenmp -fopenmp-targets=nvptx64,spirv64-intel app.cpp -o myapp
- $ llvm-offload-binary myapp
- # Output:
- # Extracted: myapp-nvptx64-nvidia-cuda-sm_70.0.bc
- # Extracted: myapp-spirv64-intel-unknown.1.spv
+```console
+$ clang++ -fopenmp -fopenmp-targets=nvptx64,spirv64-intel app.cpp -o myapp
+$ llvm-offload-binary myapp
+# Output:
+# Extracted: myapp-nvptx64-nvidia-cuda-sm_70.0.bc
+# Extracted: myapp-spirv64-intel-unknown.1.spv
+```
**Workflow 2: Extract Specific Target**
Extract only images for a specific target:
-.. code-block:: console
-
- $ llvm-offload-binary myapp --image=triple=spirv64-intel
- # Output:
- # Extracted: myapp-spirv64-intel-unknown.0.spv
+```console
+$ llvm-offload-binary myapp --image=triple=spirv64-intel
+# Output:
+# Extracted: myapp-spirv64-intel-unknown.0.spv
+```
**Workflow 3: Create Device Image Archive**
Extract filtered images into a static archive:
-.. code-block:: console
-
- $ llvm-offload-binary myapp --image=file=nvptx.a,triple=nvptx64 --archive
- $ ar t nvptx.a
- # Shows extracted CUDA images
+```console
+$ llvm-offload-binary myapp --image=file=nvptx.a,triple=nvptx64 --archive
+$ ar t nvptx.a
+# Shows extracted CUDA images
+```
**Workflow 4: Validate SPIR-V**
Extract and validate SPIR-V binaries:
-.. code-block:: console
-
- $ llvm-offload-binary myapp --image=triple=spirv64-intel
- $ spirv-val myapp-spirv64-intel-unknown.0.spv
- $ spirv-dis myapp-spirv64-intel-unknown.0.spv -o kernel.spvasm
+```console
+$ llvm-offload-binary myapp --image=triple=spirv64-intel
+$ spirv-val myapp-spirv64-intel-unknown.0.spv
+$ spirv-dis myapp-spirv64-intel-unknown.0.spv -o kernel.spvasm
+```
**Workflow 5: Bundle Multiple Targets**
Create a fat binary from multiple device images:
-.. code-block:: console
-
- $ clang++ -fopenmp -fopenmp-targets=nvptx64 --offload-device-only kernel.cpp -o kernel_nvptx.bc
- $ clang++ -fopenmp -fopenmp-targets=spirv64-intel --offload-device-only kernel.cpp -o kernel_spirv.bc
- $ llvm-offload-binary -o bundle.bin \
- --image=file=kernel_nvptx.bc,triple=nvptx64,arch=sm_70 \
- --image=file=kernel_spirv.bc,triple=spirv64-intel
+```console
+$ clang++ -fopenmp -fopenmp-targets=nvptx64 --offload-device-only kernel.cpp -o kernel_nvptx.bc
+$ clang++ -fopenmp -fopenmp-targets=spirv64-intel --offload-device-only kernel.cpp -o kernel_spirv.bc
+$ llvm-offload-binary -o bundle.bin \
+ --image=file=kernel_nvptx.bc,triple=nvptx64,arch=sm_70 \
+ --image=file=kernel_spirv.bc,triple=spirv64-intel
+```
**Workflow 6: Extract and Rebundle**
Extract images from one binary and rebundle with modifications:
-.. code-block:: console
+```console
+$ llvm-offload-binary old_app
+$ llvm-offload-binary -o new_bundle.bin \
+ --image=file=old_app-nvptx64-nvidia-cuda-sm_70.0.bc,triple=nvptx64,arch=sm_70 \
+ --image=file=new_kernel.bc,triple=nvptx64,arch=sm_80
+```
- $ llvm-offload-binary old_app
- $ llvm-offload-binary -o new_bundle.bin \
- --image=file=old_app-nvptx64-nvidia-cuda-sm_70.0.bc,triple=nvptx64,arch=sm_70 \
- --image=file=new_kernel.bc,triple=nvptx64,arch=sm_80
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`clang(1)`, {manpage}`llvm-objdump(1)`, {manpage}`spirv-val(1)`, {manpage}`spirv-dis(1)`
-:manpage:`clang(1)`, :manpage:`llvm-objdump(1)`, :manpage:`spirv-val(1)`, :manpage:`spirv-dis(1)`
diff --git a/llvm/docs/CommandGuide/llvm-opt-report.md b/llvm/docs/CommandGuide/llvm-opt-report.md
index ba10ba34578aa..1ada35d8d3ae0 100644
--- a/llvm/docs/CommandGuide/llvm-opt-report.md
+++ b/llvm/docs/CommandGuide/llvm-opt-report.md
@@ -1,60 +1,58 @@
-llvm-opt-report - generate optimization report from YAML
-========================================================
+# llvm-opt-report - generate optimization report from YAML
+```{eval-rst}
.. program:: llvm-opt-report
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-opt-report` [*options*] [input]
+{program}`llvm-opt-report` \[*options*\] [input]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-opt-report` is a tool to generate an optimization report from YAML optimization record files.
+{program}`llvm-opt-report` is a tool to generate an optimization report from YAML optimization record files.
-You need to create an input YAML optimization record file before running :program:`llvm-opt-report`.
+You need to create an input YAML optimization record file before running {program}`llvm-opt-report`.
It provides information on the execution time, memory usage, and other details of each optimization pass.
+```console
+$ clang -c foo.c -o foo.o -O3 -fsave-optimization-record
+```
-.. code-block:: console
+Then, you create a report using the {program}`llvm-opt-report` command with the YAML optimization record file {file}`foo.opt.yaml` as input.
- $ clang -c foo.c -o foo.o -O3 -fsave-optimization-record
-
-Then, you create a report using the :program:`llvm-opt-report` command with the YAML optimization record file :file:`foo.opt.yaml` as input.
-
-.. code-block:: console
-
- $ llvm-opt-report foo.opt.yaml -o foo.lst
+```console
+$ llvm-opt-report foo.opt.yaml -o foo.lst
+```
foo.lst is the generated optimization report.
-.. code-block::
-
- < foo.c
- 1 | void bar();
- 2 | void foo() { bar(); }
- 3 |
- 4 | void Test(int *res, int *c, int *d, int *p, int n) {
- 5 | int i;
- 6 |
- 7 | #pragma clang loop vectorize(assume_safety)
- 8 V4,1 | for (i = 0; i < 1600; i++) {
- 9 | res[i] = (p[i] == 0) ? res[i] : res[i] + d[i];
- 10 | }
- 11 |
- 12 U16 | for (i = 0; i < 16; i++) {
- 13 | res[i] = (p[i] == 0) ? res[i] : res[i] + d[i];
- 14 | }
- 15 |
- 16 I | foo();
- 17 |
- 18 | foo(); bar(); foo();
- I | ^
- I | ^
- 19 | }
- 20 |
+```
+< foo.c
+ 1 | void bar();
+ 2 | void foo() { bar(); }
+ 3 |
+ 4 | void Test(int *res, int *c, int *d, int *p, int n) {
+ 5 | int i;
+ 6 |
+ 7 | #pragma clang loop vectorize(assume_safety)
+ 8 V4,1 | for (i = 0; i < 1600; i++) {
+ 9 | res[i] = (p[i] == 0) ? res[i] : res[i] + d[i];
+10 | }
+11 |
+12 U16 | for (i = 0; i < 16; i++) {
+13 | res[i] = (p[i] == 0) ? res[i] : res[i] + d[i];
+14 | }
+15 |
+16 I | foo();
+17 |
+18 | foo(); bar(); foo();
+ I | ^
+ I | ^
+19 | }
+20 |
+```
Symbols printed on the left side of the program indicate what kind of optimization was performed.
The meanings of the symbols are as follows:
@@ -63,58 +61,54 @@ The meanings of the symbols are as follows:
- U: The loop is unrolled. The following number indicates the unroll factor.
- V: The loop is vectorized. The following numbers indicate the vector length and the interleave factor.
-.. note::
-
- If a specific line of code is output twice, it means that the same optimization pass was applied to that
- line of code twice, and the pass was able to further optimize the code on the second iteration.
+:::{note}
+If a specific line of code is output twice, it means that the same optimization pass was applied to that
+line of code twice, and the pass was able to further optimize the code on the second iteration.
+:::
+## OPTIONS
-OPTIONS
--------
-
-If ``input`` is "``-``" or omitted, :program:`llvm-opt-report` reads from standard
+If `input` is "`-`" or omitted, {program}`llvm-opt-report` reads from standard
input. Otherwise, it will read from the specified filename.
-If the :option:`-o` option is omitted, then :program:`llvm-opt-report` will send its output
-to standard output. If the :option:`-o` option specifies "``-``", then the output will also
+If the {option}`-o` option is omitted, then {program}`llvm-opt-report` will send its output
+to standard output. If the {option}`-o` option specifies "`-`", then the output will also
be sent to standard output.
+:::{option} --help
+Display available options.
+:::
-.. option:: --help
-
- Display available options.
-
-.. option:: --version
-
- Display the version of this program.
-
-.. option:: --format=<string>
-
- The format of the optimization record file.
- The Argument is one of the following:
-
- - yaml
- - bitstream
-
-.. option:: --no-demangle
-
- Do not demangle function names.
+:::{option} --version
+Display the version of this program.
+:::
-.. option:: -o=<string>
+:::{option} --format=<string>
+The format of the optimization record file.
+The Argument is one of the following:
- Output file.
+- yaml
+- bitstream
+:::
-.. option:: -r=<string>
+:::{option} --no-demangle
+Do not demangle function names.
+:::
- Root for relative input paths.
+:::{option} -o=<string>
+Output file.
+:::
-.. option:: -s
+:::{option} -r=<string>
+Root for relative input paths.
+:::
- Do not include vectorization factors, etc.
+:::{option} -s
+Do not include vectorization factors, etc.
+:::
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-opt-report` returns 0 on success. Otherwise, an error message is printed
+{program}`llvm-opt-report` returns 0 on success. Otherwise, an error message is printed
to standard error, and the tool returns 1.
diff --git a/llvm/docs/CommandGuide/llvm-otool.md b/llvm/docs/CommandGuide/llvm-otool.md
index 17aa9089b3875..3a9e8e4f29b3a 100644
--- a/llvm/docs/CommandGuide/llvm-otool.md
+++ b/llvm/docs/CommandGuide/llvm-otool.md
@@ -1,156 +1,152 @@
-llvm-otool - Mach-O dumping tool
-================================
+# llvm-otool - Mach-O dumping tool
+```{eval-rst}
.. program:: llvm-otool
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-otool` [*option...*] *[file...]*
+{program}`llvm-otool` \[*option...*\] *[file...]*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-otool` is a tool for dumping Mach-O files.
+{program}`llvm-otool` is a tool for dumping Mach-O files.
It attempts to be command-line-compatible and output-compatible with macOS's
-:program:`otool`.
+{program}`otool`.
-OPTIONS
--------
+## OPTIONS
-.. option:: -a
+:::{option} -a
+Print archive header.
+:::
- Print archive header.
+:::{option} -arch <value>
+Select slice of universal Mach-O file.
+:::
-.. option:: -arch <value>
+:::{option} -chained_fixups
+Print chained fixup information.
+:::
- Select slice of universal Mach-O file.
+:::{option} -C
+Print linker optimization hints.
+:::
-.. option:: -chained_fixups
+:::{option} -dyld_info
+Print bind and rebase information.
+:::
- Print chained fixup information.
+:::{option} -D
+Print shared library id.
+:::
-.. option:: -C
+:::{option} -d
+Print data section.
+:::
- Print linker optimization hints.
+:::{option} -f
+Print universal headers.
+:::
-.. option:: -dyld_info
+:::{option} -G
+Print data-in-code table.
+:::
- Print bind and rebase information.
+:::{option} --help-hidden
+Print help for hidden flags.
+:::
-.. option:: -D
+:::{option} --help
+Print help.
+:::
- Print shared library id.
+:::{option} -h
+Print mach header.
+:::
-.. option:: -d
+:::{option} -I
+Print indirect symbol table.
+:::
- Print data section.
+:::{option} -j
+Print opcode bytes.
+:::
-.. option:: -f
+:::{option} -L
+Print used shared libraries.
+:::
- Print universal headers.
+:::{option} -l
+Print load commands.
+:::
-.. option:: -G
+:::{option} -m
+Don't use archive(member) syntax.
+:::
- Print data-in-code table.
+:::{option} -mcpu=<value>
+Select cpu for disassembly.
+:::
-.. option:: --help-hidden
+:::{option} -o
+Print Objective-C segment.
+:::
- Print help for hidden flags.
+:::{option} -P
+Print \_\_TEXT,\_\_info_plist section as strings.
+:::
-.. option:: --help
+:::{option} -p <function name>
+Start disassembly at \<function name>.
+:::
- Print help.
+:::{option} -r
+Print relocation entries.
+:::
-.. option:: -h
+:::{option} -s <segname> <sectname>
+Print contents of section.
+:::
- Print mach header.
+:::{option} -t
+Print text section.
+:::
-.. option:: -I
+:::{option} --version
+Print version.
+:::
- Print indirect symbol table.
+:::{option} -V
+Symbolize disassembled operands (implies {option}`-v`).
+:::
-.. option:: -j
+:::{option} -v
+Verbose output / disassemble when printing text sections.
+:::
- Print opcode bytes.
+:::{option} -X
+Omit leading addresses or headers.
+:::
-.. option:: -L
+:::{option} -x
+Print all text sections.
+:::
- Print used shared libraries.
+:::{option} @<FILE>
+Read command-line options and commands from response file `<FILE>`.
+:::
-.. option:: -l
+## EXIT STATUS
- Print load commands.
-
-.. option:: -m
-
- Don't use archive(member) syntax.
-
-.. option:: -mcpu=<value>
-
- Select cpu for disassembly.
-
-.. option:: -o
-
- Print Objective-C segment.
-
-.. option:: -P
-
- Print __TEXT,__info_plist section as strings.
-
-.. option:: -p <function name>
-
- Start disassembly at <function name>.
-
-.. option:: -r
-
- Print relocation entries.
-
-.. option:: -s <segname> <sectname>
-
- Print contents of section.
-
-.. option:: -t
-
- Print text section.
-
-.. option:: --version
-
- Print version.
-
-.. option:: -V
-
- Symbolize disassembled operands (implies :option:`-v`).
-
-.. option:: -v
-
- Verbose output / disassemble when printing text sections.
-
-.. option:: -X
-
- Omit leading addresses or headers.
-
-.. option:: -x
-
- Print all text sections.
-
-.. option:: @<FILE>
-
- Read command-line options and commands from response file `<FILE>`.
-
-EXIT STATUS
------------
-
-:program:`llvm-otool` exits with a non-zero exit code if there is an error.
+{program}`llvm-otool` 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-objdump/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objdump/>.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-nm(1)`, {manpage}`llvm-objdump(1)`
-:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`
diff --git a/llvm/docs/CommandGuide/llvm-pdbutil.md b/llvm/docs/CommandGuide/llvm-pdbutil.md
index ff00d87e890f1..1f02743a609d0 100644
--- a/llvm/docs/CommandGuide/llvm-pdbutil.md
+++ b/llvm/docs/CommandGuide/llvm-pdbutil.md
@@ -1,656 +1,646 @@
-llvm-pdbutil - PDB File forensics and diagnostics
-=================================================
+# llvm-pdbutil - PDB File forensics and diagnostics
+```{eval-rst}
.. program:: llvm-pdbutil
+```
-Synopsis
---------
+## Synopsis
-:program:`llvm-pdbutil` [*subcommand*] [*options*]
+{program}`llvm-pdbutil` \[*subcommand*\] \[*options*\]
-Description
------------
+## Description
Display types, symbols, CodeView records, and other information from a
-PDB file, as well as manipulate and create PDB files. :program:`llvm-pdbutil`
+PDB file, as well as manipulate and create PDB files. {program}`llvm-pdbutil`
is normally used by FileCheck-based tests to test LLVM's PDB reading and
writing functionality, but can also be used for general PDB file investigation
and forensics, or as a replacement for cvdump.
-Subcommands
------------
+## Subcommands
-:program:`llvm-pdbutil` is separated into several subcommands each tailored to
-a different purpose. A brief summary of each command follows, with more detail
+{program}`llvm-pdbutil` is separated into several subcommands each tailored to
+a different purpose. A brief summary of each command follows, with more detail
in the sections that follow.
- * :ref:`pretty_subcommand` - Dump symbol and type information in a format that
- tries to look as much like the original source code as possible.
- * :ref:`dump_subcommand` - Dump low level types and structures from the PDB
- file, including CodeView records, hash tables, PDB streams, etc.
- * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,
- types, symbols, etc as raw bytes.
- * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
- a valid PDB file that matches that description.
- * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
- description of some or all of the file in a way that the PDB can be
- reconstructed.
- * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the
- result of merging the two input PDBs.
- * :ref:`export_subcommand` - Write the contents of a PDB stream to a file.
-
-.. _pretty_subcommand:
-
-pretty
-~~~~~~
-
+> - {ref}`pretty_subcommand` - Dump symbol and type information in a format that
+> tries to look as much like the original source code as possible.
+> - {ref}`dump_subcommand` - Dump low level types and structures from the PDB
+> file, including CodeView records, hash tables, PDB streams, etc.
+> - {ref}`bytes_subcommand` - Dump data from the PDB file's streams, records,
+> types, symbols, etc as raw bytes.
+> - {ref}`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
+> a valid PDB file that matches that description.
+> - {ref}`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
+> description of some or all of the file in a way that the PDB can be
+> reconstructed.
+> - {ref}`merge_subcommand` - Given two PDBs, produce a third PDB that is the
+> result of merging the two input PDBs.
+> - {ref}`export_subcommand` - Write the contents of a PDB stream to a file.
+
+(pretty-subcommand)=
+
+### pretty
+
+```{eval-rst}
.. program:: llvm-pdbutil pretty
+```
-.. important::
- The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
- supported on non-Windows platforms.
+:::{important}
+The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
+supported on non-Windows platforms.
+:::
-USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file>
+USAGE: {program}`llvm-pdbutil` pretty \[*options*\] \<input PDB file>
-Summary
-^^^^^^^^^^^
+#### Summary
The *pretty* subcommand displays a very high level representation of your
-program's debug info. Since it is built on the Windows DIA SDK which is the
+program's debug info. Since it is built on the Windows DIA SDK which is the
standard API that Windows tools and debuggers query debug information, it
presents a more authoritative view of how a debugger is going to interpret your
debug information than a mode which displays low-level CodeView records.
-Options
-^^^^^^^
-
-Filtering and Sorting Options
-+++++++++++++++++++++++++++++
-
-.. note::
- *exclude* filters take priority over *include* filters. So if a filter
- matches both an include and an exclude rule, then it is excluded.
-
-.. option:: -exclude-compilands=<string>
-
- When dumping compilands, compiland source-file contributions, or per-compiland
- symbols, this option instructs **llvm-pdbutil** to omit any compilands that
- match the specified regular expression.
-
-.. option:: -exclude-symbols=<string>
-
- When dumping global, public, or per-compiland symbols, this option instructs
- **llvm-pdbutil** to omit any symbols that match the specified regular
- expression.
-
-.. option:: -exclude-types=<string>
-
- When dumping types, this option instructs **llvm-pdbutil** to omit any types
- that match the specified regular expression.
-
-.. option:: -include-compilands=<string>
-
- When dumping compilands, compiland source-file contributions, or per-compiland
- symbols, limit the initial search to only those compilands that match the
- specified regular expression.
-
-.. option:: -include-symbols=<string>
-
- When dumping global, public, or per-compiland symbols, limit the initial
- search to only those symbols that match the specified regular expression.
-
-.. option:: -include-types=<string>
-
- When dumping types, limit the initial search to only those types that match
- the specified regular expression.
-
-.. option:: -min-class-padding=<uint>
-
- Only display types that have at least the specified amount of alignment
- padding, accounting for padding in base classes and aggregate field members.
-
-.. option:: -min-class-padding-imm=<uint>
-
- Only display types that have at least the specified amount of alignment
- padding, ignoring padding in base classes and aggregate field members.
-
-.. option:: -min-type-size=<uint>
-
- Only display types T where sizeof(T) is greater than or equal to the specified
- amount.
-
-.. option:: -no-compiler-generated
-
- Don't show compiler generated types and symbols
-
-.. option:: -no-enum-definitions
-
- When dumping an enum, don't show the full enum (e.g. the individual enumerator
- values).
-
-.. option:: -no-system-libs
-
- Don't show symbols from system libraries
-
-Symbol Type Options
-+++++++++++++++++++
-.. option:: -all
-
- Implies all other options in this category.
-
-.. option:: -class-definitions=<format>
-
- Displays class definitions in the specified format.
-
- .. code-block:: text
-
- =all - Display all class members including data, constants, typedefs, functions, etc (default)
- =layout - Only display members that contribute to class size.
- =none - Don't display class definitions (e.g. only display the name and base list)
-
-.. option:: -class-order
-
- Displays classes in the specified order.
-
- .. code-block:: text
-
- =none - Undefined / no particular sort order (default)
- =name - Sort classes by name
- =size - Sort classes by size
- =padding - Sort classes by amount of padding
- =padding-pct - Sort classes by percentage of space consumed by padding
- =padding-imm - Sort classes by amount of immediate padding
- =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
-
-.. option:: -class-recurse-depth=<uint>
-
- When dumping class definitions, stop after recursing the specified number of times. The
- default is 0, which is no limit.
-
-.. option:: -classes
-
- Display classes
-
-.. option:: -compilands
-
- Display compilands (e.g. object files)
-
-.. option:: -enums
-
- Display enums
-
-.. option:: -externals
-
- Dump external (e.g. exported) symbols
-
-.. option:: -globals
-
- Dump global symbols
-
-.. option:: -lines
-
- Dump the mappings between source lines and code addresses.
-
-.. option:: -module-syms
-
- Display symbols (variables, functions, etc) for each compiland
-
-.. option:: -sym-types=<types>
-
- Type of symbols to dump when -globals, -externals, or -module-syms is
- specified. (default all)
-
- .. code-block:: text
-
- =thunks - Display thunk symbols
- =data - Display data symbols
- =funcs - Display function symbols
- =all - Display all symbols (default)
-
-.. option:: -symbol-order=<order>
-
- For symbols dumped via the -module-syms, -globals, or -externals options, sort
- the results in specified order.
-
- .. code-block:: text
-
- =none - Undefined / no particular sort order
- =name - Sort symbols by name
- =size - Sort symbols by size
-
-.. option:: -typedefs
-
- Display typedef types
-
-.. option:: -types
-
- Display all types (implies -classes, -enums, -typedefs)
-
-Other Options
-+++++++++++++
-
-.. option:: -color-output
-
- Force color output on or off. By default, color if used if outputting to a
- terminal.
-
-.. option:: -load-address=<uint>
-
- When displaying relative virtual addresses, assume the process is loaded at the
- given address and display what would be the absolute address.
-
-.. _dump_subcommand:
-
-dump
-~~~~
-
-USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file>
-
+#### Options
+
+##### Filtering and Sorting Options
+
+:::{note}
+*exclude* filters take priority over *include* filters. So if a filter
+matches both an include and an exclude rule, then it is excluded.
+:::
+
+:::{option} -exclude-compilands=<string>
+When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, this option instructs **llvm-pdbutil** to omit any compilands that
+match the specified regular expression.
+:::
+
+:::{option} -exclude-symbols=<string>
+When dumping global, public, or per-compiland symbols, this option instructs
+**llvm-pdbutil** to omit any symbols that match the specified regular
+expression.
+:::
+
+:::{option} -exclude-types=<string>
+When dumping types, this option instructs **llvm-pdbutil** to omit any types
+that match the specified regular expression.
+:::
+
+:::{option} -include-compilands=<string>
+When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, limit the initial search to only those compilands that match the
+specified regular expression.
+:::
+
+:::{option} -include-symbols=<string>
+When dumping global, public, or per-compiland symbols, limit the initial
+search to only those symbols that match the specified regular expression.
+:::
+
+:::{option} -include-types=<string>
+When dumping types, limit the initial search to only those types that match
+the specified regular expression.
+:::
+
+:::{option} -min-class-padding=<uint>
+Only display types that have at least the specified amount of alignment
+padding, accounting for padding in base classes and aggregate field members.
+:::
+
+:::{option} -min-class-padding-imm=<uint>
+Only display types that have at least the specified amount of alignment
+padding, ignoring padding in base classes and aggregate field members.
+:::
+
+:::{option} -min-type-size=<uint>
+Only display types T where sizeof(T) is greater than or equal to the specified
+amount.
+:::
+
+:::{option} -no-compiler-generated
+Don't show compiler generated types and symbols
+:::
+
+:::{option} -no-enum-definitions
+When dumping an enum, don't show the full enum (e.g. the individual enumerator
+values).
+:::
+
+:::{option} -no-system-libs
+Don't show symbols from system libraries
+:::
+
+##### Symbol Type Options
+
+:::{option} -all
+Implies all other options in this category.
+:::
+
+:::{option} -class-definitions=<format>
+Displays class definitions in the specified format.
+
+```text
+=all - Display all class members including data, constants, typedefs, functions, etc (default)
+=layout - Only display members that contribute to class size.
+=none - Don't display class definitions (e.g. only display the name and base list)
+```
+:::
+
+:::{option} -class-order
+Displays classes in the specified order.
+
+```text
+=none - Undefined / no particular sort order (default)
+=name - Sort classes by name
+=size - Sort classes by size
+=padding - Sort classes by amount of padding
+=padding-pct - Sort classes by percentage of space consumed by padding
+=padding-imm - Sort classes by amount of immediate padding
+=padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
+```
+:::
+
+:::{option} -class-recurse-depth=<uint>
+When dumping class definitions, stop after recursing the specified number of times. The
+default is 0, which is no limit.
+:::
+
+:::{option} -classes
+Display classes
+:::
+
+:::{option} -compilands
+Display compilands (e.g. object files)
+:::
+
+:::{option} -enums
+Display enums
+:::
+
+:::{option} -externals
+Dump external (e.g. exported) symbols
+:::
+
+:::{option} -globals
+Dump global symbols
+:::
+
+:::{option} -lines
+Dump the mappings between source lines and code addresses.
+:::
+
+:::{option} -module-syms
+Display symbols (variables, functions, etc) for each compiland
+:::
+
+:::{option} -sym-types=<types>
+Type of symbols to dump when -globals, -externals, or -module-syms is
+specified. (default all)
+
+```text
+=thunks - Display thunk symbols
+=data - Display data symbols
+=funcs - Display function symbols
+=all - Display all symbols (default)
+```
+:::
+
+:::{option} -symbol-order=<order>
+For symbols dumped via the -module-syms, -globals, or -externals options, sort
+the results in specified order.
+
+```text
+=none - Undefined / no particular sort order
+=name - Sort symbols by name
+=size - Sort symbols by size
+```
+:::
+
+:::{option} -typedefs
+Display typedef types
+:::
+
+:::{option} -types
+Display all types (implies -classes, -enums, -typedefs)
+:::
+
+##### Other Options
+
+:::{option} -color-output
+Force color output on or off. By default, color if used if outputting to a
+terminal.
+:::
+
+:::{option} -load-address=<uint>
+When displaying relative virtual addresses, assume the process is loaded at the
+given address and display what would be the absolute address.
+:::
+
+(dump-subcommand)=
+
+### dump
+
+USAGE: {program}`llvm-pdbutil` dump \[*options*\] \<input PDB file>
+
+```{eval-rst}
.. program:: llvm-pdbutil dump
+```
-Summary
-^^^^^^^^^^^
+#### Summary
The **dump** subcommand displays low level information about the structure of a
-PDB file. It is used heavily by LLVM's testing infrastructure, but can also be
-used for PDB forensics. It serves a role similar to that of Microsoft's
+PDB file. It is used heavily by LLVM's testing infrastructure, but can also be
+used for PDB forensics. It serves a role similar to that of Microsoft's
`cvdump` tool.
-.. note::
- The **dump** subcommand exposes internal details of the file format. As
- such, the reader should be familiar with :doc:`/PDB/index` before using this
- command.
-
-Options
-^^^^^^^
-
-MSF Container Options
-+++++++++++++++++++++
-
-.. option:: -streams
-
- dump a summary of all of the streams in the PDB file.
-
-.. option:: -stream-blocks
-
- In conjunction with :option:`-streams`, add information to the output about
- what blocks the specified stream occupies.
-
-.. option:: -summary
-
- Dump MSF and PDB header information.
-
-Module & File Options
-+++++++++++++++++++++
-
-.. option:: -modi=<uint>
-
- For all options that dump information from each module/compiland, limit to
- the specified module.
-
-.. option:: -files
-
- Dump the source files that contribute to each displayed module.
-
-.. option:: -il
-
- Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
-
-.. option:: -l
-
- Dump line information (DEBUG_S_LINES CodeView subsection)
-
-.. option:: -modules
-
- Dump compiland information
-
-.. option:: -xme
-
- Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
-
-.. option:: -xmi
-
- Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
-
-Symbol Options
-++++++++++++++
-
-.. option:: -globals
-
- dump global symbol records
+:::{note}
+The **dump** subcommand exposes internal details of the file format. As
+such, the reader should be familiar with {doc}`/PDB/index` before using this
+command.
+:::
-.. option:: -global-extras
+#### Options
- dump additional information about the globals, such as hash buckets and hash
- values.
+##### MSF Container Options
-.. option:: -publics
+:::{option} -streams
+dump a summary of all of the streams in the PDB file.
+:::
- dump public symbol records
+:::{option} -stream-blocks
+In conjunction with {option}`-streams`, add information to the output about
+what blocks the specified stream occupies.
+:::
-.. option:: -public-extras
+:::{option} -summary
+Dump MSF and PDB header information.
+:::
- dump additional information about the publics, such as hash buckets and hash
- values.
+##### Module & File Options
-.. option:: -symbols
+:::{option} -modi=<uint>
+For all options that dump information from each module/compiland, limit to
+the specified module.
+:::
- dump symbols (functions, variables, etc) for each module dumped.
+:::{option} -files
+Dump the source files that contribute to each displayed module.
+:::
-.. option:: -sym-data
+:::{option} -il
+Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
+:::
- For each symbol record dumped as a result of the :option:`-symbols` option,
- display the full bytes of the record in binary as well.
+:::{option} -l
+Dump line information (DEBUG_S_LINES CodeView subsection)
+:::
-Type Record Options
-+++++++++++++++++++
+:::{option} -modules
+Dump compiland information
+:::
-.. option:: -types
+:::{option} -xme
+Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
+:::
- Dump CodeView type records from TPI stream
+:::{option} -xmi
+Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
+:::
-.. option:: -type-extras
+##### Symbol Options
+
+:::{option} -globals
+dump global symbol records
+:::
+
+:::{option} -global-extras
+dump additional information about the globals, such as hash buckets and hash
+values.
+:::
- Dump additional information from the TPI stream, such as hashes and the type
- index offsets array.
+:::{option} -publics
+dump public symbol records
+:::
-.. option:: -type-data
+:::{option} -public-extras
+dump additional information about the publics, such as hash buckets and hash
+values.
+:::
- For each type record dumped, display the full bytes of the record in binary as
- well.
+:::{option} -symbols
+dump symbols (functions, variables, etc) for each module dumped.
+:::
-.. option:: -type-index=<uint>
+:::{option} -sym-data
+For each symbol record dumped as a result of the {option}`-symbols` option,
+display the full bytes of the record in binary as well.
+:::
- Only dump types with the specified type index.
+##### Type Record Options
-.. option:: -ids
+:::{option} -types
+Dump CodeView type records from TPI stream
+:::
- Dump CodeView type records from IPI stream.
+:::{option} -type-extras
+Dump additional information from the TPI stream, such as hashes and the type
+index offsets array.
+:::
-.. option:: -id-extras
+:::{option} -type-data
+For each type record dumped, display the full bytes of the record in binary as
+well.
+:::
- Dump additional information from the IPI stream, such as hashes and the type
- index offsets array.
+:::{option} -type-index=<uint>
+Only dump types with the specified type index.
+:::
-.. option:: -id-data
+:::{option} -ids
+Dump CodeView type records from IPI stream.
+:::
- For each ID record dumped, display the full bytes of the record in binary as
- well.
+:::{option} -id-extras
+Dump additional information from the IPI stream, such as hashes and the type
+index offsets array.
+:::
-.. option:: -id-index=<uint>
+:::{option} -id-data
+For each ID record dumped, display the full bytes of the record in binary as
+well.
+:::
- only dump ID records with the specified hexadecimal type index.
+:::{option} -id-index=<uint>
+only dump ID records with the specified hexadecimal type index.
+:::
-.. option:: -dependents
+:::{option} -dependents
+When used in conjunction with {option}`-type-index` or {option}`-id-index`,
+dumps the entire dependency graph for the specified index instead of just the
+single record with the specified index. For example, if type index 0x4000 is
+a function whose return type has index 0x3000, and you specify
+`-dependents=0x4000`, then this would dump both records (as well as any other
+dependents in the tree).
+:::
- When used in conjunction with :option:`-type-index` or :option:`-id-index`,
- dumps the entire dependency graph for the specified index instead of just the
- single record with the specified index. For example, if type index 0x4000 is
- a function whose return type has index 0x3000, and you specify
- `-dependents=0x4000`, then this would dump both records (as well as any other
- dependents in the tree).
+##### Miscellaneous Options
-Miscellaneous Options
-+++++++++++++++++++++
+:::{option} -all
+Implies most other options.
+:::
-.. option:: -all
+:::{option} -section-contribs
+Dump section contributions.
+:::
- Implies most other options.
+:::{option} -section-headers
+Dump image section headers.
+:::
-.. option:: -section-contribs
+:::{option} -dxcontainer
+Dump a summary of the DXContainer stored in the PDB file's DXContainer stream.
+Shader companion PDB files produced by the DirectX backend store debug-related
+container parts in this stream. For example:
- Dump section contributions.
+```
+llvm-pdbutil dump --dxcontainer shader.pdb
+```
+:::
-.. option:: -section-headers
+:::{option} -section-map
+Dump section map.
+:::
+
+:::{option} -string-table
+Dump PDB string table.
+:::
+
+(bytes-subcommand)=
- Dump image section headers.
-
-.. option:: -dxcontainer
-
- Dump a summary of the DXContainer stored in the PDB file's DXContainer stream.
- Shader companion PDB files produced by the DirectX backend store debug-related
- container parts in this stream. For example::
-
- llvm-pdbutil dump --dxcontainer shader.pdb
-
-.. option:: -section-map
-
- Dump section map.
-
-.. option:: -string-table
-
- Dump PDB string table.
-
-.. _bytes_subcommand:
-
-bytes
-~~~~~
-
-USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file>
+### bytes
+
+USAGE: {program}`llvm-pdbutil` bytes \[*options*\] \<input PDB file>
+```{eval-rst}
.. program:: llvm-pdbutil bytes
+```
-Summary
-^^^^^^^
+#### Summary
Like the **dump** subcommand, the **bytes** subcommand displays low level
information about the structure of a PDB file, but it is used for even deeper
-forensics. The **bytes** subcommand finds various structures in a PDB file
-based on the command line options specified, and dumps them in hex. Someone
+forensics. The **bytes** subcommand finds various structures in a PDB file
+based on the command line options specified, and dumps them in hex. Someone
working on support for emitting PDBs would use this heavily, for example, to
-compare one PDB against another PDB to ensure byte-for-byte compatibility. It
+compare one PDB against another PDB to ensure byte-for-byte compatibility. It
is not enough to simply compare the bytes of an entire file, or an entire stream
because it's perfectly fine for the same structure to exist at different
locations in two different PDBs, and "finding" the structure is half the battle.
-Options
-^^^^^^^
-
-MSF File Options
-++++++++++++++++
-
-.. option:: -block-range=<start[-end]>
-
- Dump binary data from specified range of MSF file blocks.
-
-.. option:: -byte-range=<start[-end]>
-
- Dump binary data from specified range of bytes in the file.
-
-.. option:: -fpm
-
- Dump the MSF free page map.
+#### Options
-.. option:: -stream-data=<string>
+##### MSF File Options
- Dump binary data from the specified streams. Format is SN[:Start][@Size].
- For example, `-stream-data=7:3 at 12` dumps 12 bytes from stream 7, starting
- at offset 3 in the stream.
+:::{option} -block-range=<start[-end]>
+Dump binary data from specified range of MSF file blocks.
+:::
-PDB Stream Options
-++++++++++++++++++
+:::{option} -byte-range=<start[-end]>
+Dump binary data from specified range of bytes in the file.
+:::
-.. option:: -name-map
+:::{option} -fpm
+Dump the MSF free page map.
+:::
- Dump bytes of PDB Name Map
+:::{option} -stream-data=<string>
+Dump binary data from the specified streams. Format is SN[:Start][@Size].
+For example, `-stream-data=7:3 at 12` dumps 12 bytes from stream 7, starting
+at offset 3 in the stream.
+:::
-DBI Stream Options
-++++++++++++++++++
+##### PDB Stream Options
-.. option:: -ec
+:::{option} -name-map
+Dump bytes of PDB Name Map
+:::
- Dump the edit and continue map substream of the DBI stream.
+##### DBI Stream Options
-.. option:: -files
+:::{option} -ec
+Dump the edit and continue map substream of the DBI stream.
+:::
- Dump the file info substream of the DBI stream.
+:::{option} -files
+Dump the file info substream of the DBI stream.
+:::
-.. option:: -modi
+:::{option} -modi
+Dump the modi substream of the DBI stream.
+:::
- Dump the modi substream of the DBI stream.
+:::{option} -sc
+Dump section contributions substream of the DBI stream.
+:::
-.. option:: -sc
+:::{option} -sm
+Dump the section map from the DBI stream.
+:::
- Dump section contributions substream of the DBI stream.
+:::{option} -type-server
+Dump the type server map from the DBI stream.
+:::
-.. option:: -sm
+##### Module Options
- Dump the section map from the DBI stream.
+:::{option} -mod=<uint>
+Limit all options in this category to the specified module index. By default,
+options in this category will dump bytes from all modules.
+:::
-.. option:: -type-server
+:::{option} -chunks
+Dump the bytes of each module's C13 debug subsection.
+:::
- Dump the type server map from the DBI stream.
+:::{option} -split-chunks
+When specified with {option}`-chunks`, split the C13 debug subsection into a
+separate chunk for each subsection type, and dump them separately.
+:::
-Module Options
-++++++++++++++
+:::{option} -syms
+Dump the symbol record substream from each module.
+:::
-.. option:: -mod=<uint>
+##### Type Record Options
- Limit all options in this category to the specified module index. By default,
- options in this category will dump bytes from all modules.
+:::{option} -id=<uint>
+Dump the record from the IPI stream with the given type index.
+:::
-.. option:: -chunks
+:::{option} -type=<uint>
+Dump the record from the TPI stream with the given type index.
+:::
- Dump the bytes of each module's C13 debug subsection.
+(pdb2yaml-subcommand)=
-.. option:: -split-chunks
+### pdb2yaml
- When specified with :option:`-chunks`, split the C13 debug subsection into a
- separate chunk for each subsection type, and dump them separately.
-
-.. option:: -syms
-
- Dump the symbol record substream from each module.
-
-Type Record Options
-+++++++++++++++++++
-
-.. option:: -id=<uint>
-
- Dump the record from the IPI stream with the given type index.
-
-.. option:: -type=<uint>
-
- Dump the record from the TPI stream with the given type index.
-
-.. _pdb2yaml_subcommand:
-
-pdb2yaml
-~~~~~~~~
-
-USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file>
+USAGE: {program}`llvm-pdbutil` pdb2yaml \[*options*\] \<input PDB file>
+```{eval-rst}
.. program:: llvm-pdbutil pdb2yaml
+```
-Summary
-^^^^^^^
+#### Summary
Produce a YAML description of some or all of a PDB file's contents.
-Options
-^^^^^^^
-
-.. option:: -all
-
- Implies most other options in this category.
+#### Options
-.. option:: -dxcontainer
+:::{option} -all
+Implies most other options in this category.
+:::
- Dump the DXContainer stored in the PDB file's DXContainer stream to YAML.
- For example::
+:::{option} -dxcontainer
+Dump the DXContainer stored in the PDB file's DXContainer stream to YAML.
+For example:
- llvm-pdbutil pdb2yaml --dxcontainer shader.pdb
+```
+llvm-pdbutil pdb2yaml --dxcontainer shader.pdb
+```
+:::
-.. _yaml2pdb_subcommand:
+(yaml2pdb-subcommand)=
-yaml2pdb
-~~~~~~~~
+### yaml2pdb
-USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file>
+USAGE: {program}`llvm-pdbutil` yaml2pdb \[*options*\] \<input YAML file>
+```{eval-rst}
.. program:: llvm-pdbutil yaml2pdb
+```
-Summary
-^^^^^^^
+#### Summary
-Generate a PDB file from a YAML description. The YAML syntax is not described
-here. Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and
+Generate a PDB file from a YAML description. The YAML syntax is not described
+here. Instead, use {ref}`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and
examine the output for an example starting point.
-Options
-^^^^^^^
+#### Options
-.. option:: -pdb=<file-name>
+:::{option} -pdb=<file-name>
+:::
Write the resulting PDB to the specified file.
-.. _export_subcommand:
+(export-subcommand)=
-export
-~~~~~~
+### export
-USAGE: :program:`llvm-pdbutil` export --out=<file> [*options*] <input PDB file>
+USAGE: {program}`llvm-pdbutil` export --out=\<file> \[*options*\] \<input PDB file>
+```{eval-rst}
.. program:: llvm-pdbutil export
+```
-Summary
-^^^^^^^
+#### Summary
Write the binary contents of a PDB stream to a file.
-DirectX Shader PDBs
-^^^^^^^^^^^^^^^^^^^
+#### DirectX Shader PDBs
When a DirectX shader is compiled with debug information and a companion PDB
file is requested, the PDB contains a DXContainer stream with debug-related
parts such as ILDB, ILDN, SRCI, and VERS. To extract that container as a
-standalone DXContainer file::
+standalone DXContainer file:
- llvm-pdbutil export --dxcontainer --out=shader.dxbc shader.pdb
+```
+llvm-pdbutil export --dxcontainer --out=shader.dxbc shader.pdb
+```
The resulting file can be inspected with the same DXContainer tooling used for
-the main shader output, such as :program:`obj2yaml` and
-:program:`llvm-objcopy`. See :doc:`../DirectX/DXContainer` for part format
+the main shader output, such as {program}`obj2yaml` and
+{program}`llvm-objcopy`. See {doc}`../DirectX/DXContainer` for part format
details. To inspect the embedded container without extracting it, use
-:ref:`llvm-pdbutil dump <dump_subcommand>` or
-:ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>`.
+{ref}`llvm-pdbutil dump <dump_subcommand>` or
+{ref}`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>`.
-Options
-^^^^^^^
+#### Options
-.. option:: --out=<file>
+:::{option} --out=<file>
+The file to write the exported stream data to.
+:::
- The file to write the exported stream data to.
+:::{option} --dxcontainer
+A synonym for the {option}`--stream=5` option.
+Export the DXContainer stored in the PDB file's DXContainer stream. This is
+the usual way to recover the debug-related container parts from a shader
+companion PDB file.
+:::
-.. option:: --dxcontainer
+:::{option} --stream=<index-or-name>
+Export the contents of the specified PDB stream.
+:::
- A synonym for the :option:`--stream=5` option.
- Export the DXContainer stored in the PDB file's DXContainer stream. This is
- the usual way to recover the debug-related container parts from a shader
- companion PDB file.
+(merge-subcommand)=
-.. option:: --stream=<index-or-name>
+### merge
- Export the contents of the specified PDB stream.
-
-.. _merge_subcommand:
-
-merge
-~~~~~
-
-USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2>
+USAGE: {program}`llvm-pdbutil` merge \[*options*\] \<input PDB file 1> \<input PDB file 2>
+```{eval-rst}
.. program:: llvm-pdbutil merge
+```
-Summary
-^^^^^^^
+#### Summary
Merge two PDB files into a single file.
-Options
-^^^^^^^
+#### Options
-.. option:: -pdb=<file-name>
+:::{option} -pdb=<file-name>
+:::
Write the resulting PDB to the specified file.
+
diff --git a/llvm/docs/CommandGuide/llvm-profdata.md b/llvm/docs/CommandGuide/llvm-profdata.md
index 0b1cd02e2230f..49361d33edfab 100644
--- a/llvm/docs/CommandGuide/llvm-profdata.md
+++ b/llvm/docs/CommandGuide/llvm-profdata.md
@@ -1,43 +1,40 @@
-llvm-profdata - Profile data tool
-=================================
+# llvm-profdata - Profile data tool
+```{eval-rst}
.. program:: llvm-profdata
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-profdata` *command* [*args...*]
+{program}`llvm-profdata` *command* \[*args...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-profdata` tool is a small utility for working with profile
+The {program}`llvm-profdata` tool is a small utility for working with profile
data files.
-COMMANDS
---------
+## COMMANDS
-* :ref:`merge <profdata-merge>`
-* :ref:`show <profdata-show>`
-* :ref:`overlap <profdata-overlap>`
-* :ref:`order <profdata-order>`
+- {ref}`merge <profdata-merge>`
+- {ref}`show <profdata-show>`
+- {ref}`overlap <profdata-overlap>`
+- {ref}`order <profdata-order>`
+```{eval-rst}
.. program:: llvm-profdata merge
+```
-.. _profdata-merge:
+(profdata-merge)=
-MERGE
------
+## MERGE
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-profdata merge` [*options*] [*filename...*]
+{program}`llvm-profdata merge` \[*options*\] \[*filename...*\]
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-:program:`llvm-profdata merge` takes several profile data files
+{program}`llvm-profdata merge` takes several profile data files
generated by PGO instrumentation and merges them together into a single
indexed profile data file.
@@ -46,372 +43,371 @@ relative importance of each input file is proportional to the number of samples
or counts it contains. In general, the input from a longer training run will be
interpreted as relatively more important than a shorter run. Depending on the
nature of the training runs it may be useful to adjust the weight given to each
-input file by using the ``-weighted-input`` option.
+input file by using the `-weighted-input` option.
-Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
+Profiles passed in via `-weighted-input`, `-input-files`, or via positional
arguments are processed once for each time they are seen.
+### OPTIONS
+
+:::{option} --help
+Print a summary of command line options.
+:::
+
+:::{option} --output=<output>, -o
+Specify the output file name. *Output* cannot be `-` as the resulting
+indexed profile data can't be written to standard output.
+:::
+
+:::{option} --weighted-input=<weight,filename>
+Specify an input file name along with a weight. The profile counts of the
+supplied `filename` will be scaled (multiplied) by the supplied
+`weight`, where `weight` is a decimal integer >= 1.
+Input files specified without using this option are assigned a default
+weight of 1. Examples are shown below.
+:::
+
+:::{option} --input-files=<path>, -f
+Specify a file which contains a list of files to merge. The entries in this
+file are newline-separated. Lines starting with '#' are skipped. Entries may
+be of the form \<filename> or \<weight>,\<filename>.
+:::
+
+:::{option} --remapping-file=<path>, -r
+Specify a file which contains a remapping from symbol names in the input
+profile to the symbol names that should be used in the output profile. The
+file should consist of lines of the form `<input-symbol> <output-symbol>`.
+Blank lines and lines starting with `#` are skipped.
+
+The {doc}`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
+remapping file.
+:::
+
+:::{option} --instr (default)
+Specify that the input profile is an instrumentation-based profile.
+:::
+
+::::{option} --sample
+Specify that the input profile is a sample-based profile.
+
+The format of the generated file can be generated in one of three ways:
+
+:::{option} --binary (default)
+:::
+
+Emit the profile using a binary encoding. For instrumentation-based profile
+the output format is the indexed binary format.
+
+:::{option} --extbinary
+:::
+
+Emit the profile using an extensible binary encoding. This option can only
+be used with sample-based profile. The extensible binary encoding can be
+more compact with compression enabled and can be loaded faster than the
+default binary encoding.
+
+:::{option} --text
+:::
+
+Emit the profile in text mode. This option can also be used with both
+sample-based and instrumentation-based profile. When this option is used
+the profile will be dumped in the text format that is parsable by the profile
+reader.
+
+:::{option} --gcc
+:::
+
+Emit the profile using GCC's gcov format (Not yet supported).
+::::
+
+:::{option} --sparse[=true|false]
+Do not emit function records with 0 execution count. Can only be used in
+conjunction with -instr. Defaults to false, since it can inhibit compiler
+optimization during PGO.
+:::
+
+:::{option} --num-threads=<N>, -j
+Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
+an appropriate number of threads to use. This is the default.
+:::
+
+:::{option} --failure-mode=[any|all]
+Set the failure mode. There are two options: 'any' causes the merge command to
+fail if any profiles are invalid, and 'all' causes the merge command to fail
+only if all profiles are invalid. If 'all' is set, information from any
+invalid profiles is excluded from the final merged product. The default
+failure mode is 'any'.
+:::
+
+:::{option} --prof-sym-list=<path>
+Specify a file which contains a list of symbols to generate profile symbol
+list in the profile. This option can only be used with sample-based profile
+in extbinary format. The entries in this file are newline-separated.
+:::
+
+:::{option} --compress-all-sections=[true|false]
+Compress all sections when writing the profile. This option can only be used
+with sample-based profile in extbinary format.
+:::
+
+:::{option} --use-md5=[true|false]
+Use MD5 to represent string in name table when writing the profile.
+This option can only be used with sample-based profile in extbinary format.
+:::
+
+:::{option} --gen-partial-profile=[true|false]
+Mark the profile to be a partial profile which only provides partial profile
+coverage for the optimized target. This option can only be used with
+sample-based profile in extbinary format.
+:::
+
+:::{option} --split-layout=[true|false]
+Split the profile data section to two with one containing sample profiles with
+inlined functions and the other not. This option can only be used with
+sample-based profile in extbinary format.
+:::
+
+:::{option} --convert-sample-profile-layout=[nest|flat]
+Convert the merged profile into a profile with a new layout. Supported
+layout are `nest` (Nested profile, the input should be CS flat profile) and
+`flat` (Profile with nested inlinees flattened out).
+:::
+
+:::{option} --supplement-instr-with-sample=<file>
+Supplement an instrumentation profile with sample profile. The sample profile
+is the input of the flag. Output will be in instrumentation format (only works
+with -instr).
+:::
+
+:::{option} --zero-counter-threshold=<float>
+For the function which is cold in instr profile but hot in sample profile, if
+the ratio of the number of zero counters divided by the total number of
+counters is above the threshold, the profile of the function will be regarded
+as being harmful for performance and will be dropped.
+:::
+
+:::{option} --instr-prof-cold-threshold=<int>
+User specified cold threshold for instr profile which will override the cold
+threshold got from profile summary.
+:::
+
+:::{option} --suppl-min-size-threshold=<int>
+If the size of a function is smaller than the threshold, assume it can be
+inlined by PGO early inliner and it will not be adjusted based on sample
+profile.
+:::
+
+:::{option} --debug-info=<path>
+Specify the executable or `.dSYM` that contains debug info for the raw profile.
+When `--debug-info-correlate` or `--profile-correlate=debug-info` was used
+for instrumentation, use this option to correlate the raw profile.
+:::
+
+:::{option} --binary-file=<path>
+Specify the executable that contains profile data and profile name sections for
+the raw profile. When `-profile-correlate=binary` was used for
+instrumentation, use this option to correlate the raw profile.
+:::
+
+:::{option} --debuginfod
+Use debuginfod to find the associated executables that contain profile data and
+name sections for the raw profiles to correlate them.
+When -profile-correlate=binary was used for instrumentation, this option can be
+used for correlation.
+:::
+
+:::{option} --debug-file-directory=<dir>
+Use provided local directories to search for executables that contain profile
+data and name sections for the raw profiles to correlate them.
+When -profile-correlate=binary was used for instrumentation, this option can be
+used for correlation.
+:::
+
+:::{option} --correlate=<kind>
+Specify the correlation kind (debug_info or binary) to use when -debuginfod or
+-debug-file-directory=\<dir> option is provided.
+:::
+
+:::{option} --temporal-profile-trace-reservoir-size
+The maximum number of temporal profile traces to be stored in the output
+profile. If more traces are added, we will use reservoir sampling to select
+which traces to keep. Note that changing this value between different merge
+invocations on the same indexed profile could result in sample bias. The
+default value is 100.
+:::
+
+:::{option} --temporal-profile-max-trace-length
+The maximum number of functions in a single temporal profile trace. Longer
+traces will be truncated. The default value is 1000.
+:::
+
+:::{option} --function=<string>
+Only keep functions matching the regex in the output, all others are erased
+from the profile.
+:::
+
+:::{option} --no-function=<string>
+Remove functions matching the regex from the profile. If both --function and
+--no-function are specified and a function matches both, it is removed.
+:::
+
+### EXAMPLES
+
+#### Basic Usage
-OPTIONS
-^^^^^^^
-
-.. option:: --help
-
- Print a summary of command line options.
-
-.. option:: --output=<output>, -o
-
- Specify the output file name. *Output* cannot be ``-`` as the resulting
- indexed profile data can't be written to standard output.
-
-.. option:: --weighted-input=<weight,filename>
-
- Specify an input file name along with a weight. The profile counts of the
- supplied ``filename`` will be scaled (multiplied) by the supplied
- ``weight``, where ``weight`` is a decimal integer >= 1.
- Input files specified without using this option are assigned a default
- weight of 1. Examples are shown below.
-
-.. option:: --input-files=<path>, -f
-
- Specify a file which contains a list of files to merge. The entries in this
- file are newline-separated. Lines starting with '#' are skipped. Entries may
- be of the form <filename> or <weight>,<filename>.
-
-.. option:: --remapping-file=<path>, -r
-
- Specify a file which contains a remapping from symbol names in the input
- profile to the symbol names that should be used in the output profile. The
- file should consist of lines of the form ``<input-symbol> <output-symbol>``.
- Blank lines and lines starting with ``#`` are skipped.
-
- The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
- remapping file.
-
-.. option:: --instr (default)
-
- Specify that the input profile is an instrumentation-based profile.
-
-.. option:: --sample
-
- Specify that the input profile is a sample-based profile.
-
- The format of the generated file can be generated in one of three ways:
-
- .. option:: --binary (default)
-
- Emit the profile using a binary encoding. For instrumentation-based profile
- the output format is the indexed binary format.
-
- .. option:: --extbinary
-
- Emit the profile using an extensible binary encoding. This option can only
- be used with sample-based profile. The extensible binary encoding can be
- more compact with compression enabled and can be loaded faster than the
- default binary encoding.
-
- .. option:: --text
-
- Emit the profile in text mode. This option can also be used with both
- sample-based and instrumentation-based profile. When this option is used
- the profile will be dumped in the text format that is parsable by the profile
- reader.
-
- .. option:: --gcc
-
- Emit the profile using GCC's gcov format (Not yet supported).
-
-.. option:: --sparse[=true|false]
-
- Do not emit function records with 0 execution count. Can only be used in
- conjunction with -instr. Defaults to false, since it can inhibit compiler
- optimization during PGO.
-
-.. option:: --num-threads=<N>, -j
-
- Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
- an appropriate number of threads to use. This is the default.
-
-.. option:: --failure-mode=[any|all]
-
- Set the failure mode. There are two options: 'any' causes the merge command to
- fail if any profiles are invalid, and 'all' causes the merge command to fail
- only if all profiles are invalid. If 'all' is set, information from any
- invalid profiles is excluded from the final merged product. The default
- failure mode is 'any'.
-
-.. option:: --prof-sym-list=<path>
-
- Specify a file which contains a list of symbols to generate profile symbol
- list in the profile. This option can only be used with sample-based profile
- in extbinary format. The entries in this file are newline-separated.
-
-.. option:: --compress-all-sections=[true|false]
-
- Compress all sections when writing the profile. This option can only be used
- with sample-based profile in extbinary format.
-
-.. option:: --use-md5=[true|false]
-
- Use MD5 to represent string in name table when writing the profile.
- This option can only be used with sample-based profile in extbinary format.
-
-.. option:: --gen-partial-profile=[true|false]
-
- Mark the profile to be a partial profile which only provides partial profile
- coverage for the optimized target. This option can only be used with
- sample-based profile in extbinary format.
-
-.. option:: --split-layout=[true|false]
-
- Split the profile data section to two with one containing sample profiles with
- inlined functions and the other not. This option can only be used with
- sample-based profile in extbinary format.
-
-.. option:: --convert-sample-profile-layout=[nest|flat]
-
- Convert the merged profile into a profile with a new layout. Supported
- layout are ``nest`` (Nested profile, the input should be CS flat profile) and
- ``flat`` (Profile with nested inlinees flattened out).
-
-.. option:: --supplement-instr-with-sample=<file>
-
- Supplement an instrumentation profile with sample profile. The sample profile
- is the input of the flag. Output will be in instrumentation format (only works
- with -instr).
-
-.. option:: --zero-counter-threshold=<float>
-
- For the function which is cold in instr profile but hot in sample profile, if
- the ratio of the number of zero counters divided by the total number of
- counters is above the threshold, the profile of the function will be regarded
- as being harmful for performance and will be dropped.
-
-.. option:: --instr-prof-cold-threshold=<int>
-
- User specified cold threshold for instr profile which will override the cold
- threshold got from profile summary.
-
-.. option:: --suppl-min-size-threshold=<int>
-
- If the size of a function is smaller than the threshold, assume it can be
- inlined by PGO early inliner and it will not be adjusted based on sample
- profile.
-
-.. option:: --debug-info=<path>
-
- Specify the executable or ``.dSYM`` that contains debug info for the raw profile.
- When ``--debug-info-correlate`` or ``--profile-correlate=debug-info`` was used
- for instrumentation, use this option to correlate the raw profile.
-
-.. option:: --binary-file=<path>
-
- Specify the executable that contains profile data and profile name sections for
- the raw profile. When ``-profile-correlate=binary`` was used for
- instrumentation, use this option to correlate the raw profile.
-
-.. option:: --debuginfod
-
- Use debuginfod to find the associated executables that contain profile data and
- name sections for the raw profiles to correlate them.
- When -profile-correlate=binary was used for instrumentation, this option can be
- used for correlation.
-
-.. option:: --debug-file-directory=<dir>
-
- Use provided local directories to search for executables that contain profile
- data and name sections for the raw profiles to correlate them.
- When -profile-correlate=binary was used for instrumentation, this option can be
- used for correlation.
-
-.. option:: --correlate=<kind>
-
- Specify the correlation kind (debug_info or binary) to use when -debuginfod or
- -debug-file-directory=<dir> option is provided.
-
-.. option:: --temporal-profile-trace-reservoir-size
-
- The maximum number of temporal profile traces to be stored in the output
- profile. If more traces are added, we will use reservoir sampling to select
- which traces to keep. Note that changing this value between different merge
- invocations on the same indexed profile could result in sample bias. The
- default value is 100.
-
-.. option:: --temporal-profile-max-trace-length
-
- The maximum number of functions in a single temporal profile trace. Longer
- traces will be truncated. The default value is 1000.
-
-.. option:: --function=<string>
-
- Only keep functions matching the regex in the output, all others are erased
- from the profile.
-
-.. option:: --no-function=<string>
-
- Remove functions matching the regex from the profile. If both --function and
- --no-function are specified and a function matches both, it is removed.
-
-EXAMPLES
-^^^^^^^^
-Basic Usage
-+++++++++++
Merge three profiles:
-::
-
- llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
+```
+llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
+```
-Weighted Input
-++++++++++++++
-The input file ``foo.profdata`` is especially important, multiply its counts by 10:
+#### Weighted Input
-::
+The input file `foo.profdata` is especially important, multiply its counts by 10:
- llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
+```
+llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
+```
Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
-::
-
- llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
+```
+llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
+```
+```{eval-rst}
.. program:: llvm-profdata show
+```
-.. _profdata-show:
+(profdata-show)=
-SHOW
-----
+## SHOW
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-profdata show` [*options*] [*filename*]
+{program}`llvm-profdata show` \[*options*\] \[*filename*\]
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-:program:`llvm-profdata show` takes a profile data file and displays the
+{program}`llvm-profdata show` takes a profile data file and displays the
information about the profile counters for this file and
for any of the specified function(s).
-If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
+If *filename* is omitted or is `-`, then **llvm-profdata show** reads its
input from standard input.
-OPTIONS
-^^^^^^^
-
-.. option:: --all-functions
-
- Print details for every function.
-
-.. option:: --binary-ids
-
- Print embedded binary ids in a profile.
-
-.. option:: --counts
-
- Print the counter values for the displayed functions.
-
-.. option:: --show-format=<text|json|yaml>
-
- Emit output in the selected format if supported by the provided profile type.
-
-.. option:: --function=<string>
-
- Print details for a function if the function's name contains the given string.
-
-.. option:: --help
-
- Print a summary of command line options.
-
-.. option:: --output=<output>, -o
-
- Specify the output file name. If *output* is ``-`` or it isn't specified,
- then the output is sent to standard output.
-
-.. option:: --instr (default)
-
- Specify that the input profile is an instrumentation-based profile.
-
-.. option:: --text
-
- Instruct the profile dumper to show profile counts in the text format of the
- instrumentation-based profile data representation. By default, the profile
- information is dumped in a more human-readable form (also in text) with
- annotations.
-
-.. option:: --topn=<n>
-
- Instruct the profile dumper to show the top ``n`` functions with the
- hottest basic blocks in the summary section. By default, the topn functions
- are not dumped.
-
-.. option:: --sample
-
- Specify that the input profile is a sample-based profile.
-
-.. option:: --memop-sizes
-
- Show the profiled sizes of the memory intrinsic calls for shown functions.
-
-.. option:: --value-cutoff=<n>
-
- Show only those functions whose max count values are greater or equal to ``n``.
- By default, the value-cutoff is set to 0.
-
-.. option:: --list-below-cutoff
-
- Only output names of functions whose max count value are below the cutoff
- value.
-
-.. option:: --profile-version
-
- Print profile version.
-
-.. option:: --showcs
-
- Only show context sensitive profile counts. The default is to filter all
- context sensitive profile counts.
-
-.. option:: --show-prof-sym-list=[true|false]
-
- Show profile symbol list if it exists in the profile. This option is only
- meaningful for sample-based profile in extbinary format.
-
-.. option:: --show-sec-info-only=[true|false]
-
- Show basic information about each section in the profile. This option is
- only meaningful for sample-based profile in extbinary format.
-
-.. option:: --debug-info=<path>
-
- Specify the executable or ``.dSYM`` that contains debug info for the raw profile.
- When ``--debug-info-correlate`` or ``--profile-correlate=debug-info`` was used
- for instrumentation, use this option to show the correlated functions from the
- raw profile.
-
-.. option:: --covered
-
- Show only the functions that have been executed, i.e., functions with non-zero
- counts.
-
+### OPTIONS
+
+:::{option} --all-functions
+Print details for every function.
+:::
+
+:::{option} --binary-ids
+Print embedded binary ids in a profile.
+:::
+
+:::{option} --counts
+Print the counter values for the displayed functions.
+:::
+
+:::{option} --show-format=<text|json|yaml>
+Emit output in the selected format if supported by the provided profile type.
+:::
+
+:::{option} --function=<string>
+Print details for a function if the function's name contains the given string.
+:::
+
+:::{option} --help
+Print a summary of command line options.
+:::
+
+:::{option} --output=<output>, -o
+Specify the output file name. If *output* is `-` or it isn't specified,
+then the output is sent to standard output.
+:::
+
+:::{option} --instr (default)
+Specify that the input profile is an instrumentation-based profile.
+:::
+
+:::{option} --text
+Instruct the profile dumper to show profile counts in the text format of the
+instrumentation-based profile data representation. By default, the profile
+information is dumped in a more human-readable form (also in text) with
+annotations.
+:::
+
+:::{option} --topn=<n>
+Instruct the profile dumper to show the top `n` functions with the
+hottest basic blocks in the summary section. By default, the topn functions
+are not dumped.
+:::
+
+:::{option} --sample
+Specify that the input profile is a sample-based profile.
+:::
+
+:::{option} --memop-sizes
+Show the profiled sizes of the memory intrinsic calls for shown functions.
+:::
+
+:::{option} --value-cutoff=<n>
+Show only those functions whose max count values are greater or equal to `n`.
+By default, the value-cutoff is set to 0.
+:::
+
+:::{option} --list-below-cutoff
+Only output names of functions whose max count value are below the cutoff
+value.
+:::
+
+:::{option} --profile-version
+Print profile version.
+:::
+
+:::{option} --showcs
+Only show context sensitive profile counts. The default is to filter all
+context sensitive profile counts.
+:::
+
+:::{option} --show-prof-sym-list=[true|false]
+Show profile symbol list if it exists in the profile. This option is only
+meaningful for sample-based profile in extbinary format.
+:::
+
+:::{option} --show-sec-info-only=[true|false]
+Show basic information about each section in the profile. This option is
+only meaningful for sample-based profile in extbinary format.
+:::
+
+:::{option} --debug-info=<path>
+Specify the executable or `.dSYM` that contains debug info for the raw profile.
+When `--debug-info-correlate` or `--profile-correlate=debug-info` was used
+for instrumentation, use this option to show the correlated functions from the
+raw profile.
+:::
+
+:::{option} --covered
+Show only the functions that have been executed, i.e., functions with non-zero
+counts.
+:::
+
+```{eval-rst}
.. program:: llvm-profdata overlap
+```
-.. _profdata-overlap:
+(profdata-overlap)=
-OVERLAP
--------
+## OVERLAP
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*]
+{program}`llvm-profdata overlap` \[*options*\] \[*base profile file*\] \[*test profile file*\]
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-:program:`llvm-profdata overlap` takes two profile data files and displays the
+{program}`llvm-profdata overlap` takes two profile data files and displays the
*overlap* of counter distribution between the whole files and between any of the
specified functions.
@@ -420,13 +416,13 @@ Suppose *base profile file* has the following counts:
{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
and *test profile file* has
{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
-Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
+Here c{1|2}\_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
*base profile file* and *test profile file*, respectively.
-Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and
+Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and
sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
-+ min(c1_n/sum_1, c2_n/sum_2).
+\+ min(c1_n/sum_1, c2_n/sum_2).
The result overlap distribution is a percentage number, ranging from 0.0% to
100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
@@ -435,68 +431,65 @@ overlap.
Here is an example, if *base profile file* has counts of {400, 600}, and
*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%.
-OPTIONS
-^^^^^^^
-
-.. option:: --function=<string>
+### OPTIONS
- Print details for a function if the function's name contains the given string.
+:::{option} --function=<string>
+Print details for a function if the function's name contains the given string.
+:::
-.. option:: --help
+:::{option} --help
+Print a summary of command line options.
+:::
- Print a summary of command line options.
+:::{option} --output=<output>, -o
+Specify the output file name. If *output* is `-` or it isn't specified,
+then the output is sent to standard output.
+:::
-.. option:: --output=<output>, -o
+:::{option} --value-cutoff=<n>
+Show only those functions whose max count values are greater or equal to `n`.
+By default, the value-cutoff is set to max of unsigned long long.
+:::
- Specify the output file name. If *output* is ``-`` or it isn't specified,
- then the output is sent to standard output.
-
-.. option:: --value-cutoff=<n>
-
- Show only those functions whose max count values are greater or equal to ``n``.
- By default, the value-cutoff is set to max of unsigned long long.
-
-.. option:: --cs
-
- Only show overlap for the context sensitive profile counts. The default is to show
- non-context sensitive profile counts.
+:::{option} --cs
+Only show overlap for the context sensitive profile counts. The default is to show
+non-context sensitive profile counts.
+:::
+```{eval-rst}
.. program:: llvm-profdata order
+```
-.. _profdata-order:
+(profdata-order)=
-ORDER
--------
+## ORDER
-SYNOPSIS
-^^^^^^^^
+### SYNOPSIS
-:program:`llvm-profdata order` [*options*] [*filename*]
+{program}`llvm-profdata order` \[*options*\] \[*filename*\]
-DESCRIPTION
-^^^^^^^^^^^
+### DESCRIPTION
-:program:`llvm-profdata order` uses temporal profiling traces from a profile and
+{program}`llvm-profdata order` uses temporal profiling traces from a profile and
finds a function order that reduces the number of page faults for those traces.
-This output can be directly passed to ``lld`` via ``--symbol-ordering-file=``
-for ELF or ``-order-file`` for Mach-O. If the traces found in the profile are
+This output can be directly passed to `lld` via `--symbol-ordering-file=`
+for ELF or `-order-file` for Mach-O. If the traces found in the profile are
representative of the real world, then this order should improve startup
performance.
-OPTIONS
-^^^^^^^
+### OPTIONS
-.. option:: --help
+:::{option} --help
+Print a summary of command line options.
+:::
- Print a summary of command line options.
+:::{option} --output=<output>, -o
+Specify the output file name. If *output* is `-` or it isn't specified,
+then the output is sent to standard output.
+:::
-.. option:: --output=<output>, -o
+## EXIT STATUS
- Specify the output file name. If *output* is ``-`` or it isn't specified,
- then the output is sent to standard output.
-
-EXIT STATUS
------------
-
-:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
+{program}`llvm-profdata` returns 1 if the command is omitted or is invalid,
if it cannot read input files, or if there is a mismatch between their data.
+
diff --git a/llvm/docs/CommandGuide/llvm-profgen.md b/llvm/docs/CommandGuide/llvm-profgen.md
index 006cdfecf4f88..f47a36ae05f59 100644
--- a/llvm/docs/CommandGuide/llvm-profgen.md
+++ b/llvm/docs/CommandGuide/llvm-profgen.md
@@ -1,105 +1,103 @@
-llvm-profgen - LLVM SPGO profile generation tool
-================================================
+# llvm-profgen - LLVM SPGO profile generation tool
+```{eval-rst}
.. program:: llvm-profgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-profgen` [*commands*] [*options*]
+{program}`llvm-profgen` \[*commands*\] \[*options*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-profgen` utility generates a profile data file
+The {program}`llvm-profgen` utility generates a profile data file
from given perf script data files for sample-based profile guided
optimization(SPGO).
-COMMANDS
---------
-At least one of the following commands are required:
-
-.. option:: --perfscript=<string[,string,...]>
-
- Path of perf-script trace created by Linux perf tool with `script`
- command(the raw perf.data should be profiled with -b).
-
-.. option:: --etm=<string>
-
- Path of the ETM trace file created by ARM CoreSight trace tools.
- Requires the OpenCSD library version 1.5.4 or higher to be enabled during the build.
-
-.. option:: --perfdata=<perfdata>, --pd
-
- Path of raw perf data created by Linux perf tool (it should be profiled
- with -b).
-
-.. option:: --unsymbolized-profile=<unsymbolized profile>, --up
-
- Path of the unsymbolized profile created by ``llvm-profgen`` with
- ``--skip-symbolization``.
-
-.. option:: --llvm-sample-profile=<llvm sample profile>
-
- Path of the LLVM sample profile.
-
-.. note::
-
- Only one of ``--perfscript``, ``--perfdata``, ``--unsymbolized-profile``,
- ``--llvm-sample-profile``, or ``--etm`` may be specified at a time.
-
-.. option:: --binary=<string[,string,...]>
-
- Path of the input profiled binary files.
-
-.. option:: --output=<string>
-
- Path of the output profile file.
-
+## COMMANDS
-OPTIONS
--------
-:program:`llvm-profgen` supports the following options:
-
-.. option:: --format=[text|binary|extbinary|compbinary|gcc]
-
- Specify the format of the generated profile. Supported <format> are `text`,
- `binary`, `extbinary`, `compbinary`, `gcc`, see `llvm-profdata` for more
- descriptions of the format.
-
-.. option:: --show-mmap-events
-
- Print mmap events.
-
-.. option:: --show-disassembly
-
- Print disassembled code.
-
-.. option:: --x86-asm-syntax=[att|intel]
-
- Specify whether to print assembly code in AT&T syntax (the default) or Intel
- syntax.
-
-.. option:: --debug-binary=<debug-binary>
-
- Path of debug info binary. ``llvm-profgen`` will load the DWARF info from
- it instead of the executable binary.
-
-.. option:: --target-triple=<triple>
-
- Override the target triple for the binary. This is useful for ETM trace
- decoding to specify the correct Arm M-profile target.
-
-.. option:: --pid
-
- Process Id for the profiled executable binary.
-
-.. option:: --output=<output>
-
- Path of the output profile file.
-
-.. option:: --data-access-perftrace=<data-access-perftrace>
+At least one of the following commands are required:
- File path of a Linux perf raw trace (generated by ``perf report -D``)
- consisting of memory access events.
+:::{option} --perfscript=<string[,string,...]>
+Path of perf-script trace created by Linux perf tool with `script`
+command(the raw perf.data should be profiled with -b).
+:::
+
+:::{option} --etm=<string>
+Path of the ETM trace file created by ARM CoreSight trace tools.
+Requires the OpenCSD library version 1.5.4 or higher to be enabled during the build.
+:::
+
+:::{option} --perfdata=<perfdata>, --pd
+Path of raw perf data created by Linux perf tool (it should be profiled
+with -b).
+:::
+
+:::{option} --unsymbolized-profile=<unsymbolized profile>, --up
+Path of the unsymbolized profile created by `llvm-profgen` with
+`--skip-symbolization`.
+:::
+
+:::{option} --llvm-sample-profile=<llvm sample profile>
+Path of the LLVM sample profile.
+:::
+
+:::{note}
+Only one of `--perfscript`, `--perfdata`, `--unsymbolized-profile`,
+`--llvm-sample-profile`, or `--etm` may be specified at a time.
+:::
+
+:::{option} --binary=<string[,string,...]>
+Path of the input profiled binary files.
+:::
+
+:::{option} --output=<string>
+Path of the output profile file.
+:::
+
+## OPTIONS
+
+{program}`llvm-profgen` supports the following options:
+
+:::{option} --format=[text|binary|extbinary|compbinary|gcc]
+Specify the format of the generated profile. Supported \<format> are `text`,
+`binary`, `extbinary`, `compbinary`, `gcc`, see `llvm-profdata` for more
+descriptions of the format.
+:::
+
+:::{option} --show-mmap-events
+Print mmap events.
+:::
+
+:::{option} --show-disassembly
+Print disassembled code.
+:::
+
+:::{option} --x86-asm-syntax=[att|intel]
+Specify whether to print assembly code in AT&T syntax (the default) or Intel
+syntax.
+:::
+
+:::{option} --debug-binary=<debug-binary>
+Path of debug info binary. `llvm-profgen` will load the DWARF info from
+it instead of the executable binary.
+:::
+
+:::{option} --target-triple=<triple>
+Override the target triple for the binary. This is useful for ETM trace
+decoding to specify the correct Arm M-profile target.
+:::
+
+:::{option} --pid
+Process Id for the profiled executable binary.
+:::
+
+:::{option} --output=<output>
+Path of the output profile file.
+:::
+
+:::{option} --data-access-perftrace=<data-access-perftrace>
+File path of a Linux perf raw trace (generated by `perf report -D`)
+consisting of memory access events.
+:::
diff --git a/llvm/docs/CommandGuide/llvm-ranlib.md b/llvm/docs/CommandGuide/llvm-ranlib.md
index 5cc5a6a839d1c..f8568d0e8a9bf 100644
--- a/llvm/docs/CommandGuide/llvm-ranlib.md
+++ b/llvm/docs/CommandGuide/llvm-ranlib.md
@@ -1,23 +1,22 @@
-llvm-ranlib - generates an archive index
-========================================
+# llvm-ranlib - generates an archive index
+```{eval-rst}
.. program:: llvm-ranlib
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-ranlib` [*options*] *archive...*
+{program}`llvm-ranlib` \[*options*\] *archive...*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-ranlib` is an alias for the :doc:`llvm-ar <llvm-ar>` tool that
+{program}`llvm-ranlib` is an alias for the {doc}`llvm-ar <llvm-ar>` tool that
generates an index for one or more archives. It can be used as a replacement for GNU's
-:program:`ranlib` tool.
+{program}`ranlib` tool.
-Running :program:`llvm-ranlib` is equivalent to running ``llvm-ar s``.
+Running {program}`llvm-ranlib` is equivalent to running `llvm-ar s`.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-ar(1)`
-:manpage:`llvm-ar(1)`
diff --git a/llvm/docs/CommandGuide/llvm-readelf.md b/llvm/docs/CommandGuide/llvm-readelf.md
index 4269a52c13731..d24db896a23c2 100644
--- a/llvm/docs/CommandGuide/llvm-readelf.md
+++ b/llvm/docs/CommandGuide/llvm-readelf.md
@@ -1,246 +1,244 @@
-llvm-readelf - GNU-style LLVM Object Reader
-===========================================
+# llvm-readelf - GNU-style LLVM Object Reader
+```{eval-rst}
.. program:: llvm-readelf
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-readelf` [*options*] [*input...*]
+{program}`llvm-readelf` \[*options*\] \[*input...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-readelf` tool displays low-level format-specific information
+The {program}`llvm-readelf` tool displays low-level format-specific information
about one or more object files.
-If ``input`` is "``-``", :program:`llvm-readelf` reads from standard
-input. Otherwise, it will read from the specified ``filenames``.
-
-OPTIONS
--------
-
-.. option:: --addrsig
-
- Display the address-significance table.
-
- .. option:: --all, -a
-
- Equivalent to specifying all the main display options relevant to the file
- format.
-
-.. option:: --arch-specific, -A
-
- Display architecture-specific information, e.g. the ARM attributes section on ARM.
-
-.. option:: --bb-addr-map
-
- Display the contents of the basic block address map section(s), which contain the
- address of each function, along with the relative offset of each basic block.
-
-.. option:: --call-graph-info
-
- Display the call graph section entries i.e. for each function
- its identifying information, each of its direct callees' information
- and for each indirect callee a 64-bit number representing the callee's
- function signature. This information can be used to reconstruct
- the program call graph.
-
-.. option:: --cg-profile
-
- Display the callgraph profile section.
-
-.. option:: --decompress, -z
-
- Dump decompressed section content when used with ``-x`` or ``-p``.
- If the section(s) are not compressed, they are displayed as is.
-
-.. option:: --demangle, -C
-
- Display demangled symbol names in the output.
-
-.. option:: --dependent-libraries
-
- Display the dependent libraries section.
-
-.. option:: --dynamic-table, --dynamic, -d
-
- Display the dynamic table.
-
-.. option:: --dyn-relocations
-
- Display the dynamic relocation entries.
-
-.. option:: --dyn-symbols, --dyn-syms
-
- Display the dynamic symbol table.
-
-.. option:: --elf-linker-options
-
- Display the linker options section.
-
-.. option:: --elf-output-style=<value>
-
- Format ELF information in the specified style. Valid options are ``LLVM``,
- ``GNU``, and ``JSON``. ``LLVM`` output is an expanded and structured format.
- ``GNU`` (the default) output mimics the equivalent GNU :program:`readelf`
- output. ``JSON`` is JSON formatted output intended for machine consumption.
-
-.. option:: --extra-sym-info
-
- Display extra information (section name) when showing symbols.
-
-.. option:: --expand-relocs
-
- When used with :option:`--relocations`, display each relocation in an expanded
- multi-line format.
-
-.. option:: --file-header, -h
-
- Display file headers.
-
-.. option:: --gnu-hash-table
-
- Display the GNU hash table for dynamic symbols.
-
-.. option:: --hash-symbols
-
- Display the expanded hash table with dynamic symbol data.
-
-.. option:: --hash-table
-
- Display the hash table for dynamic symbols.
-
-.. option:: --headers, -e
-
- Equivalent to setting: :option:`--file-header`, :option:`--program-headers`,
- and :option:`--sections`.
-
-.. option:: --help
-
- Display a summary of command line options.
-
-.. option:: --hex-dump=<section[,section,...]>, -x
-
- Display the specified section(s) as hexadecimal bytes. ``section`` may be a
- section index or section name.
-
-.. option:: --histogram, -I
-
- Display a bucket list histogram for dynamic symbol hash tables.
-
-.. option:: --memtag
-
- Display information about memory tagging present in the binary. This includes
- various memtag-specific dynamic entries, decoded global descriptor sections,
- and decoded Android-specific ELF notes.
-
-.. option:: --needed-libs
-
- Display the needed libraries.
-
-.. option:: --no-demangle
-
- Do not display demangled symbol names in the output. On by default.
-
-.. option:: --notes, -n
-
- Display all notes.
-
-.. option:: --offloading
-
- Display list of HIP offload bundles.
-
-.. option:: --pretty-print
-
- When used with :option:`--elf-output-style`, JSON output will be formatted in
- a more readable format.
-
-.. option:: --program-headers, --segments, -l
-
- Display the program headers.
-
-.. option:: --relocations, --relocs, -r
-
- Display the relocation entries in the file.
-
-.. option:: --section-data
-
- When used with :option:`--sections`, display section data for each section
- shown. This option has no effect for GNU style output.
-
-.. option:: --section-details, -t
-
- Display all section details. Used as an alternative to :option:`--sections`.
-
-.. option:: --section-groups, -g
-
- Display section groups.
-
-.. option:: --section-mapping
-
- Display the section to segment mapping.
-
-.. option:: --section-relocations
-
- When used with :option:`--sections`, display relocations for each section
- shown. This option has no effect for GNU style output.
-
-.. option:: --sections, --section-headers, -S
-
- Display all sections.
-
-.. option:: --section-symbols
-
- When used with :option:`--sections`, display symbols for each section shown.
- This option has no effect for GNU style output.
-
-.. option:: --stackmap
-
- Display contents of the stackmap section.
-
-.. option:: --stack-sizes
-
- Display the contents of the stack sizes section(s), i.e. pairs of function
- names and the size of their stack frames. Currently only implemented for GNU
- style output.
-
-.. option:: --string-dump=<section[,section,...]>, -p
-
- Display the specified section(s) as a list of strings. ``section`` may be a
- section index or section name.
-
-.. option:: --symbols, --syms, -s
-
- Display the symbol table. Also display the dynamic symbol table when using GNU output style for ELF.
-
-.. option:: --unwind, -u
-
- Display unwind information.
-
-.. option:: --version
-
- Display the version of the :program:`llvm-readelf` executable.
-
-.. option:: --version-info, -V
-
- Display version sections.
-
-.. option:: --wide, -W
-
- Ignored for GNU readelf compatibility. The output is already similar to when using -W with GNU readelf.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-EXIT STATUS
------------
-
-:program:`llvm-readelf` returns 0 under normal operation. It returns a non-zero
+If `input` is "`-`", {program}`llvm-readelf` reads from standard
+input. Otherwise, it will read from the specified `filenames`.
+
+## OPTIONS
+
+::::{option} --addrsig
+Display the address-significance table.
+
+:::{option} --all, -a
+:::
+
+Equivalent to specifying all the main display options relevant to the file
+format.
+::::
+
+:::{option} --arch-specific, -A
+Display architecture-specific information, e.g. the ARM attributes section on ARM.
+:::
+
+:::{option} --bb-addr-map
+Display the contents of the basic block address map section(s), which contain the
+address of each function, along with the relative offset of each basic block.
+:::
+
+:::{option} --call-graph-info
+Display the call graph section entries i.e. for each function
+its identifying information, each of its direct callees' information
+and for each indirect callee a 64-bit number representing the callee's
+function signature. This information can be used to reconstruct
+the program call graph.
+:::
+
+:::{option} --cg-profile
+Display the callgraph profile section.
+:::
+
+:::{option} --decompress, -z
+Dump decompressed section content when used with `-x` or `-p`.
+If the section(s) are not compressed, they are displayed as is.
+:::
+
+:::{option} --demangle, -C
+Display demangled symbol names in the output.
+:::
+
+:::{option} --dependent-libraries
+Display the dependent libraries section.
+:::
+
+:::{option} --dynamic-table, --dynamic, -d
+Display the dynamic table.
+:::
+
+:::{option} --dyn-relocations
+Display the dynamic relocation entries.
+:::
+
+:::{option} --dyn-symbols, --dyn-syms
+Display the dynamic symbol table.
+:::
+
+:::{option} --elf-linker-options
+Display the linker options section.
+:::
+
+:::{option} --elf-output-style=<value>
+Format ELF information in the specified style. Valid options are `LLVM`,
+`GNU`, and `JSON`. `LLVM` output is an expanded and structured format.
+`GNU` (the default) output mimics the equivalent GNU {program}`readelf`
+output. `JSON` is JSON formatted output intended for machine consumption.
+:::
+
+:::{option} --extra-sym-info
+Display extra information (section name) when showing symbols.
+:::
+
+:::{option} --expand-relocs
+When used with {option}`--relocations`, display each relocation in an expanded
+multi-line format.
+:::
+
+:::{option} --file-header, -h
+Display file headers.
+:::
+
+:::{option} --gnu-hash-table
+Display the GNU hash table for dynamic symbols.
+:::
+
+:::{option} --hash-symbols
+Display the expanded hash table with dynamic symbol data.
+:::
+
+:::{option} --hash-table
+Display the hash table for dynamic symbols.
+:::
+
+:::{option} --headers, -e
+Equivalent to setting: {option}`--file-header`, {option}`--program-headers`,
+and {option}`--sections`.
+:::
+
+:::{option} --help
+Display a summary of command line options.
+:::
+
+:::{option} --hex-dump=<section[,section,...]>, -x
+Display the specified section(s) as hexadecimal bytes. `section` may be a
+section index or section name.
+:::
+
+:::{option} --histogram, -I
+Display a bucket list histogram for dynamic symbol hash tables.
+:::
+
+:::{option} --memtag
+Display information about memory tagging present in the binary. This includes
+various memtag-specific dynamic entries, decoded global descriptor sections,
+and decoded Android-specific ELF notes.
+:::
+
+:::{option} --needed-libs
+Display the needed libraries.
+:::
+
+:::{option} --no-demangle
+Do not display demangled symbol names in the output. On by default.
+:::
+
+:::{option} --notes, -n
+Display all notes.
+:::
+
+:::{option} --offloading
+Display list of HIP offload bundles.
+:::
+
+:::{option} --pretty-print
+When used with {option}`--elf-output-style`, JSON output will be formatted in
+a more readable format.
+:::
+
+:::{option} --program-headers, --segments, -l
+Display the program headers.
+:::
+
+:::{option} --relocations, --relocs, -r
+Display the relocation entries in the file.
+:::
+
+:::{option} --section-data
+When used with {option}`--sections`, display section data for each section
+shown. This option has no effect for GNU style output.
+:::
+
+:::{option} --section-details, -t
+Display all section details. Used as an alternative to {option}`--sections`.
+:::
+
+:::{option} --section-groups, -g
+Display section groups.
+:::
+
+:::{option} --section-mapping
+Display the section to segment mapping.
+:::
+
+:::{option} --section-relocations
+When used with {option}`--sections`, display relocations for each section
+shown. This option has no effect for GNU style output.
+:::
+
+:::{option} --sections, --section-headers, -S
+Display all sections.
+:::
+
+:::{option} --section-symbols
+When used with {option}`--sections`, display symbols for each section shown.
+This option has no effect for GNU style output.
+:::
+
+:::{option} --stackmap
+Display contents of the stackmap section.
+:::
+
+:::{option} --stack-sizes
+Display the contents of the stack sizes section(s), i.e. pairs of function
+names and the size of their stack frames. Currently only implemented for GNU
+style output.
+:::
+
+:::{option} --string-dump=<section[,section,...]>, -p
+Display the specified section(s) as a list of strings. `section` may be a
+section index or section name.
+:::
+
+:::{option} --symbols, --syms, -s
+Display the symbol table. Also display the dynamic symbol table when using GNU output style for ELF.
+:::
+
+:::{option} --unwind, -u
+Display unwind information.
+:::
+
+:::{option} --version
+Display the version of the {program}`llvm-readelf` executable.
+:::
+
+:::{option} --version-info, -V
+Display version sections.
+:::
+
+:::{option} --wide, -W
+Ignored for GNU readelf compatibility. The output is already similar to when using -W with GNU readelf.
+:::
+
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-readelf` returns 0 under normal operation. It returns a non-zero
exit code if there were any errors.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-nm(1)`, {manpage}`llvm-objdump(1)`, {manpage}`llvm-readobj(1)`
-:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readobj(1)`
diff --git a/llvm/docs/CommandGuide/llvm-readobj.md b/llvm/docs/CommandGuide/llvm-readobj.md
index 463f4d4f2fe12..0237a5d007c17 100644
--- a/llvm/docs/CommandGuide/llvm-readobj.md
+++ b/llvm/docs/CommandGuide/llvm-readobj.md
@@ -1,398 +1,391 @@
-llvm-readobj - LLVM Object Reader
-=================================
+# llvm-readobj - LLVM Object Reader
+```{eval-rst}
.. program:: llvm-readobj
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-readobj` [*options*] [*input...*]
+{program}`llvm-readobj` \[*options*\] \[*input...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-readobj` tool displays low-level format-specific information
+The {program}`llvm-readobj` tool displays low-level format-specific information
about one or more object files.
-If ``input`` is "``-``", :program:`llvm-readobj` reads from standard
-input. Otherwise, it will read from the specified ``filenames``.
+If `input` is "`-`", {program}`llvm-readobj` reads from standard
+input. Otherwise, it will read from the specified `filenames`.
-DIFFERENCES TO LLVM-READELF
----------------------------
+## DIFFERENCES TO LLVM-READELF
-:program:`llvm-readelf` is an alias for the :manpage:`llvm-readobj` tool with a
+{program}`llvm-readelf` is an alias for the {manpage}`llvm-readobj` tool with a
slightly different command-line interface and output that is GNU compatible.
-Following is a list of differences between :program:`llvm-readelf` and
-:program:`llvm-readobj`:
-
-- :program:`llvm-readelf` uses `GNU` for the :option:`--elf-output-style` option
- by default. :program:`llvm-readobj` uses `LLVM`.
-- :program:`llvm-readelf` allows single-letter grouped flags (e.g.
- ``llvm-readelf -SW`` is the same as ``llvm-readelf -S -W``).
- :program:`llvm-readobj` does not allow grouping.
-- :program:`llvm-readelf` provides :option:`-s` as an alias for
- :option:`--symbols`, for GNU :program:`readelf` compatibility, whereas it is
- an alias for :option:`--section-headers` in :program:`llvm-readobj`.
-- :program:`llvm-readobj` provides ``-t`` as an alias for :option:`--symbols`.
- :program:`llvm-readelf` does not.
-- :program:`llvm-readobj` provides ``--sr``, ``--sd``, ``--st`` and ``--dt`` as
- aliases for :option:`--section-relocations`, :option:`--section-data`,
- :option:`--section-symbols` and :option:`--dyn-symbols` respectively.
- :program:`llvm-readelf` does not provide these aliases, to avoid conflicting
+Following is a list of differences between {program}`llvm-readelf` and
+{program}`llvm-readobj`:
+
+- {program}`llvm-readelf` uses `GNU` for the {option}`--elf-output-style` option
+ by default. {program}`llvm-readobj` uses `LLVM`.
+- {program}`llvm-readelf` allows single-letter grouped flags (e.g.
+ `llvm-readelf -SW` is the same as `llvm-readelf -S -W`).
+ {program}`llvm-readobj` does not allow grouping.
+- {program}`llvm-readelf` provides {option}`-s` as an alias for
+ {option}`--symbols`, for GNU {program}`readelf` compatibility, whereas it is
+ an alias for {option}`--section-headers` in {program}`llvm-readobj`.
+- {program}`llvm-readobj` provides `-t` as an alias for {option}`--symbols`.
+ {program}`llvm-readelf` does not.
+- {program}`llvm-readobj` provides `--sr`, `--sd`, `--st` and `--dt` as
+ aliases for {option}`--section-relocations`, {option}`--section-data`,
+ {option}`--section-symbols` and {option}`--dyn-symbols` respectively.
+ {program}`llvm-readelf` does not provide these aliases, to avoid conflicting
with grouped flags.
-GENERAL AND MULTI-FORMAT OPTIONS
---------------------------------
+## GENERAL AND MULTI-FORMAT OPTIONS
These options are applicable to more than one file format, or are unrelated to
file formats.
-.. option:: --addrsig
-
- Display the address-significance table.
-
-.. option:: --all
-
- Equivalent to specifying all the main display options relevant to the file
- format.
-
-.. option:: --decompress, -z
-
- Dump decompressed section content when used with ``-x`` or ``-p``.
- If the section(s) are not compressed, they are displayed as is.
-
-.. option:: --demangle, -C
-
- Display demangled symbol names in the output. This option is only for ELF and
- XCOFF file formats.
-
-.. option:: --expand-relocs
-
- When used with :option:`--relocs`, display each relocation in an expanded
- multi-line format.
-
-.. option:: --file-header, -h
-
- Display file headers.
-
-.. option:: --headers, -e
-
- Equivalent to setting: :option:`--file-header`, :option:`--program-headers`,
- and :option:`--sections`.
-
-.. option:: --help
-
- Display a summary of command line options.
-
-.. option:: --hex-dump=<section[,section,...]>, -x
-
- Display the specified section(s) as hexadecimal bytes. ``section`` may be a
- section index or section name.
-
-.. option:: --needed-libs
-
- Display the needed libraries.
-
-.. option:: --no-demangle
-
- Do not demangle symbol names in the output. This option is only for ELF and
- XCOFF file formats. The option is enabled by default.
-
-.. option:: --offloading
-
- Display list of HIP offload bundles.
-
-.. option:: --relocations, --relocs, -r
-
- Display the relocation entries in the file.
-
-.. option:: --section-data, --sd
-
- When used with :option:`--sections`, display section data for each section
- shown. This option has no effect for GNU style output.
-
-.. option:: --section-relocations, --sr
-
- When used with :option:`--sections`, display relocations for each section
- shown. This option has no effect for GNU style output.
-
-.. option:: --sections, --section-headers, -S
-
- Display all sections.
-
-.. option:: --section-symbols, --st
-
- When used with :option:`--sections`, display symbols for each section shown.
- This option has no effect for GNU style output.
-
-.. option:: --sort-symbols=<sort_key[,sort_key]>
-
- Specify the keys to sort symbols before displaying symtab.
- Valid values for sort_key are ``name`` and ``type``.
-.. option:: --stackmap
-
- Display contents of the stackmap section.
-
-.. option:: --string-dump=<section[,section,...]>, -p
-
- Display the specified section(s) as a list of strings. ``section`` may be a
- section index or section name.
-
-.. option:: --string-table
-
- Display contents of the string table.
-
-.. option:: --symbols, --syms, -s
-
- Display the symbol table.
-
-.. option:: --unwind, -u
-
- Display unwind information.
-
-.. option:: --version
-
- Display the version of the :program:`llvm-readobj` executable.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-ELF SPECIFIC OPTIONS
---------------------
+:::{option} --addrsig
+Display the address-significance table.
+:::
+
+:::{option} --all
+Equivalent to specifying all the main display options relevant to the file
+format.
+:::
+
+:::{option} --decompress, -z
+Dump decompressed section content when used with `-x` or `-p`.
+If the section(s) are not compressed, they are displayed as is.
+:::
+
+:::{option} --demangle, -C
+Display demangled symbol names in the output. This option is only for ELF and
+XCOFF file formats.
+:::
+
+:::{option} --expand-relocs
+When used with {option}`--relocs`, display each relocation in an expanded
+multi-line format.
+:::
+
+:::{option} --file-header, -h
+Display file headers.
+:::
+
+:::{option} --headers, -e
+Equivalent to setting: {option}`--file-header`, {option}`--program-headers`,
+and {option}`--sections`.
+:::
+
+:::{option} --help
+Display a summary of command line options.
+:::
+
+:::{option} --hex-dump=<section[,section,...]>, -x
+Display the specified section(s) as hexadecimal bytes. `section` may be a
+section index or section name.
+:::
+
+:::{option} --needed-libs
+Display the needed libraries.
+:::
+
+:::{option} --no-demangle
+Do not demangle symbol names in the output. This option is only for ELF and
+XCOFF file formats. The option is enabled by default.
+:::
+
+:::{option} --offloading
+Display list of HIP offload bundles.
+:::
+
+:::{option} --relocations, --relocs, -r
+Display the relocation entries in the file.
+:::
+
+:::{option} --section-data, --sd
+When used with {option}`--sections`, display section data for each section
+shown. This option has no effect for GNU style output.
+:::
+
+:::{option} --section-relocations, --sr
+When used with {option}`--sections`, display relocations for each section
+shown. This option has no effect for GNU style output.
+:::
+
+:::{option} --sections, --section-headers, -S
+Display all sections.
+:::
+
+:::{option} --section-symbols, --st
+When used with {option}`--sections`, display symbols for each section shown.
+This option has no effect for GNU style output.
+:::
+
+:::{option} --sort-symbols=<sort_key[,sort_key]>
+Specify the keys to sort symbols before displaying symtab.
+Valid values for sort_key are `name` and `type`.
+:::
+
+:::{option} --stackmap
+Display contents of the stackmap section.
+:::
+
+:::{option} --string-dump=<section[,section,...]>, -p
+Display the specified section(s) as a list of strings. `section` may be a
+section index or section name.
+:::
+
+:::{option} --string-table
+Display contents of the string table.
+:::
+
+:::{option} --symbols, --syms, -s
+Display the symbol table.
+:::
+
+:::{option} --unwind, -u
+Display unwind information.
+:::
+
+:::{option} --version
+Display the version of the {program}`llvm-readobj` executable.
+:::
+
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
+
+## ELF SPECIFIC OPTIONS
The following options are implemented only for the ELF file format.
-.. option:: --arch-specific, -A
-
- Display architecture-specific information, e.g. the ARM attributes section on ARM.
-
-.. option:: --bb-addr-map
-
- Display the contents of the basic block address map section(s), which contain the
- address of each function, along with the relative offset of each basic block.
-
- When pgo analysis maps are present, all analyses are printed as their raw
- value.
-
-.. option:: --call-graph-info
-
- Display the call graph section entries i.e. for each function
- its identifying information, each of its direct callees' information
- and for each indirect callee a 64-bit number representing the callee's
- function signature. This information can be used to reconstruct
- the program call graph.
-
-.. option:: --cg-profile
-
- Display the callgraph profile section.
-
-.. option:: --dependent-libraries
-
- Display the dependent libraries section.
-
-.. option:: --dynamic-table, --dynamic, -d
-
- Display the dynamic table.
-
-.. option:: --dyn-relocations
-
- Display the dynamic relocation entries.
-
-.. option:: --dyn-symbols, --dyn-syms, --dt
-
- Display the dynamic symbol table.
-
-.. option:: --elf-linker-options
-
- Display the linker options section.
-
-.. option:: --elf-output-style=<value>
-
- Format ELF information in the specified style. Valid options are ``LLVM``,
- ``GNU``, and ``JSON``. ``LLVM`` output (the default) is an expanded and
- structured format. ``GNU`` output mimics the equivalent GNU :program:`readelf`
- output. ``JSON`` is JSON formatted output intended for machine consumption.
-
-.. option:: --gnu-hash-table
-
- Display the GNU hash table for dynamic symbols.
-
-.. option:: --hash-symbols
-
- Display the expanded hash table with dynamic symbol data.
-
-.. option:: --hash-table
-
- Display the hash table for dynamic symbols.
-
-.. option:: --histogram, -I
-
- Display a bucket list histogram for dynamic symbol hash tables.
-
-.. option:: --memtag
-
- Display information about memory tagging present in the binary. This includes
- various dynamic entries, decoded global descriptor sections, and decoded
- Android-specific ELF notes.
-
-.. option:: --notes, -n
-
- Display all notes.
-
-.. option:: --pretty-pgo-analysis-map
-
- When pgo analysis maps are present in the basic block address map section(s),
- analyses with special formats (i.e. BlockFrequency, BranchProbability, etc)
- are printed using the same format as their respective analysis pass.
-
- Requires :option:`--bb-addr-map` to have an effect.
-
-.. option:: --pretty-print
-
- When used with :option:`--elf-output-style`, JSON output will be formatted in
- a more readable format.
-
-.. option:: --program-headers, --segments, -l
-
- Display the program headers.
-
-.. option:: --section-groups, -g
-
- Display section groups.
-
-.. option:: --section-mapping
-
- Display the section to segment mapping.
-
-.. option:: --stack-sizes
-
- Display the contents of the stack sizes section(s), i.e. pairs of function
- names and the size of their stack frames. Currently only implemented for GNU
- style output.
-
-.. option:: --version-info, -V
-
- Display version sections.
-
-MACH-O SPECIFIC OPTIONS
------------------------
+:::{option} --arch-specific, -A
+Display architecture-specific information, e.g. the ARM attributes section on ARM.
+:::
+
+:::{option} --bb-addr-map
+Display the contents of the basic block address map section(s), which contain the
+address of each function, along with the relative offset of each basic block.
+
+When pgo analysis maps are present, all analyses are printed as their raw
+value.
+:::
+
+:::{option} --call-graph-info
+Display the call graph section entries i.e. for each function
+its identifying information, each of its direct callees' information
+and for each indirect callee a 64-bit number representing the callee's
+function signature. This information can be used to reconstruct
+the program call graph.
+:::
+
+:::{option} --cg-profile
+Display the callgraph profile section.
+:::
+
+:::{option} --dependent-libraries
+Display the dependent libraries section.
+:::
+
+:::{option} --dynamic-table, --dynamic, -d
+Display the dynamic table.
+:::
+
+:::{option} --dyn-relocations
+Display the dynamic relocation entries.
+:::
+
+:::{option} --dyn-symbols, --dyn-syms, --dt
+Display the dynamic symbol table.
+:::
+
+:::{option} --elf-linker-options
+Display the linker options section.
+:::
+
+:::{option} --elf-output-style=<value>
+Format ELF information in the specified style. Valid options are `LLVM`,
+`GNU`, and `JSON`. `LLVM` output (the default) is an expanded and
+structured format. `GNU` output mimics the equivalent GNU {program}`readelf`
+output. `JSON` is JSON formatted output intended for machine consumption.
+:::
+
+:::{option} --gnu-hash-table
+Display the GNU hash table for dynamic symbols.
+:::
+
+:::{option} --hash-symbols
+Display the expanded hash table with dynamic symbol data.
+:::
+
+:::{option} --hash-table
+Display the hash table for dynamic symbols.
+:::
+
+:::{option} --histogram, -I
+Display a bucket list histogram for dynamic symbol hash tables.
+:::
+
+:::{option} --memtag
+Display information about memory tagging present in the binary. This includes
+various dynamic entries, decoded global descriptor sections, and decoded
+Android-specific ELF notes.
+:::
+
+:::{option} --notes, -n
+Display all notes.
+:::
+
+:::{option} --pretty-pgo-analysis-map
+When pgo analysis maps are present in the basic block address map section(s),
+analyses with special formats (i.e. BlockFrequency, BranchProbability, etc)
+are printed using the same format as their respective analysis pass.
+
+Requires {option}`--bb-addr-map` to have an effect.
+:::
+
+:::{option} --pretty-print
+When used with {option}`--elf-output-style`, JSON output will be formatted in
+a more readable format.
+:::
+
+:::{option} --program-headers, --segments, -l
+Display the program headers.
+:::
+
+:::{option} --section-groups, -g
+Display section groups.
+:::
+
+:::{option} --section-mapping
+Display the section to segment mapping.
+:::
+
+:::{option} --stack-sizes
+Display the contents of the stack sizes section(s), i.e. pairs of function
+names and the size of their stack frames. Currently only implemented for GNU
+style output.
+:::
+
+:::{option} --version-info, -V
+Display version sections.
+:::
+
+## MACH-O SPECIFIC OPTIONS
The following options are implemented only for the Mach-O file format.
-.. option:: --macho-data-in-code
-
- Display the Data in Code command.
-
-.. option:: --macho-dsymtab
-
- Display the Dsymtab command.
+:::{option} --macho-data-in-code
+Display the Data in Code command.
+:::
-.. option:: --macho-indirect-symbols
+:::{option} --macho-dsymtab
+Display the Dsymtab command.
+:::
- Display indirect symbols.
+:::{option} --macho-indirect-symbols
+Display indirect symbols.
+:::
-.. option:: --macho-linker-options
+:::{option} --macho-linker-options
+Display the Mach-O-specific linker options.
+:::
- Display the Mach-O-specific linker options.
+:::{option} --macho-segment
+Display the Segment command.
+:::
-.. option:: --macho-segment
+:::{option} --macho-target-triple
+Display the target triple command.
+:::
- Display the Segment command.
+:::{option} --macho-version-min
+Display the version min command.
+:::
-.. option:: --macho-target-triple
-
- Display the target triple command.
-
-.. option:: --macho-version-min
-
- Display the version min command.
-
-PE/COFF SPECIFIC OPTIONS
-------------------------
+## PE/COFF SPECIFIC OPTIONS
The following options are implemented only for the PE/COFF file format.
-.. option:: --codeview
-
- Display CodeView debug information.
-
-.. option:: --codeview-ghash
-
- Enable global hashing for CodeView type stream de-duplication.
+:::{option} --codeview
+Display CodeView debug information.
+:::
-.. option:: --codeview-merged-types
+:::{option} --codeview-ghash
+Enable global hashing for CodeView type stream de-duplication.
+:::
- Display the merged CodeView type stream.
+:::{option} --codeview-merged-types
+Display the merged CodeView type stream.
+:::
-.. option:: --codeview-subsection-bytes
+:::{option} --codeview-subsection-bytes
+Dump raw contents of CodeView debug sections and records.
+:::
- Dump raw contents of CodeView debug sections and records.
+:::{option} --coff-basereloc
+Display the .reloc section.
+:::
-.. option:: --coff-basereloc
+:::{option} --coff-debug-directory
+Display the debug directory.
+:::
- Display the .reloc section.
+:::{option} --coff-directives
+Display the .drectve section.
+:::
-.. option:: --coff-debug-directory
+:::{option} --coff-exports
+Display the export table.
+:::
- Display the debug directory.
+:::{option} --coff-imports
+Display the import table.
+:::
-.. option:: --coff-directives
+:::{option} --coff-load-config
+Display the load config.
+:::
- Display the .drectve section.
+:::{option} --coff-resources
+Display the .rsrc section.
+:::
-.. option:: --coff-exports
+:::{option} --coff-tls-directory
+Display the TLS directory.
+:::
- Display the export table.
-
-.. option:: --coff-imports
-
- Display the import table.
-
-.. option:: --coff-load-config
-
- Display the load config.
-
-.. option:: --coff-resources
-
- Display the .rsrc section.
-
-.. option:: --coff-tls-directory
-
- Display the TLS directory.
-
-XCOFF SPECIFIC OPTIONS
-----------------------
+## XCOFF SPECIFIC OPTIONS
The following options are implemented only for the XCOFF file format.
-.. option:: --auxiliary-header
-
- Display XCOFF Auxiliary header.
-
-.. option:: --exception-section
-
- Display XCOFF exception section entries.
+:::{option} --auxiliary-header
+Display XCOFF Auxiliary header.
+:::
-.. option:: --loader-section-header
+:::{option} --exception-section
+Display XCOFF exception section entries.
+:::
- Display XCOFF loader section header.
+:::{option} --loader-section-header
+Display XCOFF loader section header.
+:::
-.. option:: --loader-section-relocations
+:::{option} --loader-section-relocations
+Display relocation entries of loader section.
+:::
- Display relocation entries of loader section.
+:::{option} --loader-section-symbols
+Display symbol table of loader section.
+:::
-.. option:: --loader-section-symbols
+## EXIT STATUS
- Display symbol table of loader section.
-
-EXIT STATUS
------------
-
-:program:`llvm-readobj` returns 0 under normal operation. It returns a non-zero
+{program}`llvm-readobj` returns 0 under normal operation. It returns a non-zero
exit code if there were any errors.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-nm(1)`, {manpage}`llvm-objdump(1)`, {manpage}`llvm-readelf(1)`
-:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`
diff --git a/llvm/docs/CommandGuide/llvm-reduce.md b/llvm/docs/CommandGuide/llvm-reduce.md
index 1bba9020bc62e..dc1329efb3dfe 100644
--- a/llvm/docs/CommandGuide/llvm-reduce.md
+++ b/llvm/docs/CommandGuide/llvm-reduce.md
@@ -1,127 +1,122 @@
-llvm-reduce - LLVM automatic testcase reducer.
-==============================================
+# llvm-reduce - LLVM automatic testcase reducer.
+```{eval-rst}
.. program:: llvm-reduce
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-reduce` [*options*] [*input...*]
+{program}`llvm-reduce` \[*options*\] \[*input...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-reduce` tool project that can be used for reducing the size of LLVM test cases.
+The {program}`llvm-reduce` tool project that can be used for reducing the size of LLVM test cases.
It works by removing redundant or unnecessary code from LLVM test cases while still preserving
their ability to detect bugs.
-If ``input`` is "``-``", :program:`llvm-reduce` reads from standard
-input. Otherwise, it will read from the specified ``filenames``.
+If `input` is "`-`", {program}`llvm-reduce` reads from standard
+input. Otherwise, it will read from the specified `filenames`.
LLVM-Reduce is a useful tool for reducing the size and
complexity of LLVM test cases, making it easier to identify and debug issues in
the LLVM compiler infrastructure.
-GENERIC OPTIONS
----------------
+## GENERIC OPTIONS
+:::{option} --help
+Display available options (--help-hidden for more).
+:::
-.. option:: --help
+:::{option} --abort-on-invalid-reduction
+Abort if any reduction results in invalid IR
+:::
- Display available options (--help-hidden for more).
+:::{option} --delta-passes=<string>
+A comma-separated list of delta passes to run. By default, {program}`llvm-reduce`
+runs all available delta passes for the input format (IR or MIR). When specified,
+only the listed passes will be executed, in the given order.
-.. option:: --abort-on-invalid-reduction
+Available delta passes can be listed using {option}`--print-delta-passes`.
+Specific passes can also be excluded using {option}`--skip-delta-passes`.
+If an unrecognized pass name is specified, {program}`llvm-reduce` will report an
+error and exit.
+:::
- Abort if any reduction results in invalid IR
+:::{option} --in-place
+WARNING: This option will replace your input file with the reduced version!
+:::
-.. option:: --delta-passes=<string>
+:::{option} --ir-passes=<string>
+A textual description of the pass pipeline, same as what's passed to `opt -passes`.
+:::
- A comma-separated list of delta passes to run. By default, :program:`llvm-reduce`
- runs all available delta passes for the input format (IR or MIR). When specified,
- only the listed passes will be executed, in the given order.
+:::{option} -j <uint>
+Maximum number of threads to use to process chunks. Set to 1 to disable parallelism.
+:::
- Available delta passes can be listed using :option:`--print-delta-passes`.
- Specific passes can also be excluded using :option:`--skip-delta-passes`.
- If an unrecognized pass name is specified, :program:`llvm-reduce` will report an
- error and exit.
+:::{option} --max-pass-iterations=<int>
+Maximum number of times to run the full set of delta passes (default=5).
+:::
-.. option:: --in-place
+:::{option} --mtriple=<string>
+Set the target triple.
+:::
- WARNING: This option will replace your input file with the reduced version!
+:::{option} --preserve-debug-environment
+Don't disable features used for crash debugging (crash reports, llvm-symbolizer and core dumps)
+:::
-.. option:: --ir-passes=<string>
+:::{option} --print-delta-passes
+Print list of delta passes, passable to {option}`--delta-passes` as a comma-separated list.
+:::
- A textual description of the pass pipeline, same as what's passed to `opt -passes`.
+:::{option} --skip-delta-passes=<string>
+Delta passes to not run, separated by commas. By default, run all delta passes.
+:::
-.. option:: -j <uint>
+:::{option} --skip-verify-interesting-after-counting-chunks
+Do not validate testcase is interesting after counting chunks. This
+will save time by avoiding extra executions of the interestingness
+test, but a warning will no longer be printed on flaky reproducers.
+:::
- Maximum number of threads to use to process chunks. Set to 1 to disable parallelism.
+:::{option} --starting-granularity-level=<uint>
+Number of times to divide chunks prior to first test.
-.. option:: --max-pass-iterations=<int>
+Note : Granularity refers to the level of detail at which the reduction process operates.
+A lower granularity means that the reduction process operates at a more coarse-grained level,
+while a higher granularity means that it operates at a more fine-grained level.
+:::
- Maximum number of times to run the full set of delta passes (default=5).
+:::{option} --test=<string>
+Name of the interesting-ness test to be run.
+:::
-.. option:: --mtriple=<string>
+:::{option} --test-arg=<string>
+Arguments passed onto the interesting-ness test.
+:::
- Set the target triple.
+:::{option} --verbose
+Print extra debugging information.
+:::
-.. option:: --preserve-debug-environment
+:::{option} --write-tmp-files-as-bitcode
+Always write temporary files as bitcode instead of textual IR.
+:::
- Don't disable features used for crash debugging (crash reports, llvm-symbolizer and core dumps)
+:::{option} -x={ir|mir}
+Input language as ir or mir.
+:::
-.. option:: --print-delta-passes
+## EXIT STATUS
- Print list of delta passes, passable to :option:`--delta-passes` as a comma-separated list.
-
-.. option:: --skip-delta-passes=<string>
-
- Delta passes to not run, separated by commas. By default, run all delta passes.
-
-.. option:: --skip-verify-interesting-after-counting-chunks
-
- Do not validate testcase is interesting after counting chunks. This
- will save time by avoiding extra executions of the interestingness
- test, but a warning will no longer be printed on flaky reproducers.
-
-.. option:: --starting-granularity-level=<uint>
-
- Number of times to divide chunks prior to first test.
-
- Note : Granularity refers to the level of detail at which the reduction process operates.
- A lower granularity means that the reduction process operates at a more coarse-grained level,
- while a higher granularity means that it operates at a more fine-grained level.
-
-.. option:: --test=<string>
-
- Name of the interesting-ness test to be run.
-
-.. option:: --test-arg=<string>
-
- Arguments passed onto the interesting-ness test.
-
-.. option:: --verbose
-
- Print extra debugging information.
-
-.. option:: --write-tmp-files-as-bitcode
-
- Always write temporary files as bitcode instead of textual IR.
-
-.. option:: -x={ir|mir}
-
- Input language as ir or mir.
-
-EXIT STATUS
-------------
-
-:program:`llvm-reduce` returns 0 under normal operation. It returns a
+{program}`llvm-reduce` returns 0 under normal operation. It returns a
non-zero exit code if there were any errors. Returns 2 if the
interestingness test reported the initial input was not interesting.
-EXAMPLE
--------
+## EXAMPLE
-:program:`llvm-reduce` can be used to simplify a test that causes a
+{program}`llvm-reduce` can be used to simplify a test that causes a
compiler crash.
For example, let's assume that `opt` is crashing on the IR file
@@ -131,20 +126,21 @@ WhateverFile.cpp`, when running at `-O2`.
The test case of `test.ll` can be reduced by invoking the following
command:
-.. code-block:: bash
-
- $(LLVM_BUILD_FOLDER)/bin/llvm-reduce --test=script.sh <path to>/test.ll
+```bash
+$(LLVM_BUILD_FOLDER)/bin/llvm-reduce --test=script.sh <path to>/test.ll
+```
The shell script passed to the option `test` consists of the
following:
-.. code-block:: bash
-
- $(LLVM_BUILD_FOLDER)/bin/opt -O2 -disable-output $1 \
- |& grep "Assertion failed at line 1234 of WhateverFile.cpp"
+```bash
+$(LLVM_BUILD_FOLDER)/bin/opt -O2 -disable-output $1 \
+ |& grep "Assertion failed at line 1234 of WhateverFile.cpp"
+```
(In this script, `grep` exits with 0 if it finds the string and that
becomes the whole script's status.)
This example can be generalized to other tools that process IR files,
for example `llc`.
+
diff --git a/llvm/docs/CommandGuide/llvm-remarkutil.md b/llvm/docs/CommandGuide/llvm-remarkutil.md
index af7d8eb31c018..5326f1815272c 100644
--- a/llvm/docs/CommandGuide/llvm-remarkutil.md
+++ b/llvm/docs/CommandGuide/llvm-remarkutil.md
@@ -1,68 +1,66 @@
-llvm-remarkutil - Remark utility
-================================
+# llvm-remarkutil - Remark utility
+```{eval-rst}
.. program:: llvm-remarkutil
+```
-Synopsis
---------
+## Synopsis
-:program:`llvm-remarkutil` [*subcommmand*] [*options*]
+{program}`llvm-remarkutil` \[*subcommmand*\] \[*options*\]
-Description
------------
+## Description
Utility for displaying information from, and converting between different
-`remark <https://llvm.org/docs/Remarks.html>`_ formats.
+[remark](https://llvm.org/docs/Remarks.html) formats.
-Subcommands
------------
+## Subcommands
- * :ref:`bitstream2yaml_subcommand` - Reserialize bitstream remarks to YAML.
- * :ref:`yaml2bitstream_subcommand` - Reserialize YAML remarks to bitstream.
- * :ref:`instruction-count_subcommand` - Output function instruction counts.
- * :ref:`annotation-count_subcommand` - Output remark type count from annotation remarks.
- * :ref:`size-diff_subcommand` - Compute diff in size remarks.
+> - {ref}`bitstream2yaml_subcommand` - Reserialize bitstream remarks to YAML.
+> - {ref}`yaml2bitstream_subcommand` - Reserialize YAML remarks to bitstream.
+> - {ref}`instruction-count_subcommand` - Output function instruction counts.
+> - {ref}`annotation-count_subcommand` - Output remark type count from annotation remarks.
+> - {ref}`size-diff_subcommand` - Compute diff in size remarks.
-.. _bitstream2yaml_subcommand:
+(bitstream2yaml-subcommand)=
-bitstream2yaml
-~~~~~~~~~~~~~~
+### bitstream2yaml
+```{eval-rst}
.. program:: llvm-remarkutil bitstream2yaml
+```
-USAGE: :program:`llvm-remarkutil` bitstream2yaml <input file> -o <output file>
+USAGE: {program}`llvm-remarkutil` bitstream2yaml \<input file> -o \<output file>
-Summary
-^^^^^^^
+#### Summary
Takes a bitstream remark file as input, and reserializes that file as YAML.
-.. _yaml2bitstream_subcommand:
+(yaml2bitstream-subcommand)=
-yaml2bitstream
-~~~~~~~~~~~~~~
+### yaml2bitstream
+```{eval-rst}
.. program:: llvm-remarkutil yaml2bitstream
+```
-USAGE: :program:`llvm-remarkutil` yaml2bitstream <input file> -o <output file>
+USAGE: {program}`llvm-remarkutil` yaml2bitstream \<input file> -o \<output file>
-Summary
-^^^^^^^
+#### Summary
Takes a YAML remark file as input, and reserializes that file in the bitstream
format.
-.. _instruction-count_subcommand:
+(instruction-count-subcommand)=
-instruction-count
-~~~~~~~~~~~~~~~~~
+### instruction-count
+```{eval-rst}
.. program:: llvm-remarkutil instruction-count
+```
-USAGE: :program:`llvm-remarkutil` instruction-count <input file> --parser=<bitstream|yaml> [--use-debug-loc] -o <output file>
+USAGE: {program}`llvm-remarkutil` instruction-count \<input file> --parser=\<bitstream|yaml> [--use-debug-loc] -o \<output file>
-Summary
-^^^^^^^
+#### Summary
Outputs instruction count remarks for every function. Instruction count remarks
encode the number of instructions in a function at assembly printing time.
@@ -71,29 +69,29 @@ Instruction count remarks require asm-printer remarks.
CSV format is as follows:
-::
-
- Function,InstructionCount
- foo,123
+```
+Function,InstructionCount
+foo,123
+```
if `--use-debug-loc` is passed then the CSV will include the source path, line number and column.
-::
-
- Source,Function,InstructionCount
- path:line:column,foo,3
+```
+Source,Function,InstructionCount
+path:line:column,foo,3
+```
-.. _annotation-count_subcommand:
+(annotation-count-subcommand)=
-annotation-count
-~~~~~~~~~~~~~~~~~
+### annotation-count
+```{eval-rst}
.. program:: llvm-remarkutil annotation-count
+```
-USAGE: :program:`llvm-remarkutil` annotation-count <input file> --parser=<bitstream|yaml> --annotation-type=<type> [--use-debug-loc] -o <output file>
+USAGE: {program}`llvm-remarkutil` annotation-count \<input file> --parser=\<bitstream|yaml> --annotation-type=\<type> [--use-debug-loc] -o \<output file>
-Summary
-^^^^^^^
+#### Summary
Outputs a count for annotation-type `<type>` remark for every function. The count expresses
the number of remark checks inserted at the function.
@@ -102,326 +100,334 @@ Annotation count remarks require AnnotationRemarksPass remarks.
CSV format is as follows:
-::
-
- Function,Count
- foo,123
+```
+Function,Count
+foo,123
+```
if `--use-debug-loc` is passed then the CSV will include the source path, line number and column.
-::
-
- Source,Function,Count
- path:line:column,foo,3
+```
+Source,Function,Count
+path:line:column,foo,3
+```
-.. _count_subcommand:
+(count-subcommand)=
-count
-~~~~~
+### count
+```{eval-rst}
.. program:: llvm-remarkutil count
+```
-USAGE: :program:`llvm-remarkutil` count [*options*] <input file>
+USAGE: {program}`llvm-remarkutil` count \[*options*\] \<input file>
-Summary
-^^^^^^^
+#### Summary
-:program:`llvm-remarkutil count` counts `remarks <https://llvm.org/docs/Remarks.html>`_ based on specified properties.
+{program}`llvm-remarkutil count` counts [remarks](https://llvm.org/docs/Remarks.html) based on specified properties.
By default the tool counts remarks based on how many occur in a source file or function or total for the generated remark file.
The tool also supports collecting count based on specific remark arguments. The specified arguments should have an integer value to be able to report a count.
The tool contains utilities to filter the remark count based on remark name, pass name, argument value and remark type.
-Options
-^^^^^^^
-
-.. option:: --parser=<yaml|bitstream>
-
- Select the type of input remark parser. Required.
-
- * ``yaml`` : The tool will parse YAML remarks.
- * ``bitstream`` : The tool will parse bitstream remarks.
-
-.. option:: --count-by=<value>
-
- Select option to collect remarks by.
+#### Options
- * ``remark-name`` : count how many individual remarks exist.
- * ``arg`` : count remarks based on specified arguments passed by --(r)args. The argument value must be a number.
-
-.. option:: --group-by=<value>
-
- group count of remarks by property.
-
- * ``source`` : Count will be collected per source path. Remarks with no debug location will not be counted.
- * ``function`` : Count is collected per function.
- * ``function-with-loc`` : Count is collected per function per source. Remarks with no debug location will not be counted.
- * ``Total`` : Report a count for the provided remark file.
-
-.. option:: --args[=arguments]
-
- If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments represented as a comma separated string.
- The arguments must have a numeral value to be able to count remarks by
-
-.. option:: --rargs[=arguments]
+:::{option} --parser=<yaml|bitstream>
+Select the type of input remark parser. Required.
- If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments using regular expression.
- The arguments must have a numeral value to be able to count remarks by
+- `yaml` : The tool will parse YAML remarks.
+- `bitstream` : The tool will parse bitstream remarks.
+:::
-.. option:: --pass-name[=<string>]
+:::{option} --count-by=<value>
+Select option to collect remarks by.
- Filter count by pass name.
+- `remark-name` : count how many individual remarks exist.
+- `arg` : count remarks based on specified arguments passed by --(r)args. The argument value must be a number.
+:::
-.. option:: --rpass-name[=<string>]
+:::{option} --group-by=<value>
+group count of remarks by property.
- Filter count by pass name using regular expressions.
+- `source` : Count will be collected per source path. Remarks with no debug location will not be counted.
+- `function` : Count is collected per function.
+- `function-with-loc` : Count is collected per function per source. Remarks with no debug location will not be counted.
+- `Total` : Report a count for the provided remark file.
+:::
-.. option:: --remark-name[=<string>]
+:::{option} --args[=arguments]
+If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments represented as a comma separated string.
+The arguments must have a numeral value to be able to count remarks by
+:::
- Filter count by remark name.
+:::{option} --rargs[=arguments]
+If `count-by` is set to `arg` this flag can be used to collect from specified remark arguments using regular expression.
+The arguments must have a numeral value to be able to count remarks by
+:::
-.. option:: --rremark-name[=<string>]
+:::{option} --pass-name[=<string>]
+Filter count by pass name.
+:::
- Filter count by remark name using regular expressions.
+:::{option} --rpass-name[=<string>]
+Filter count by pass name using regular expressions.
+:::
-.. option:: --filter-arg-by[=<string>]
+:::{option} --remark-name[=<string>]
+Filter count by remark name.
+:::
- Filter count by argument value.
+:::{option} --rremark-name[=<string>]
+Filter count by remark name using regular expressions.
+:::
-.. option:: --rfilter-arg-by[=<string>]
+:::{option} --filter-arg-by[=<string>]
+Filter count by argument value.
+:::
- Filter count by argument value using regular expressions.
+:::{option} --rfilter-arg-by[=<string>]
+Filter count by argument value using regular expressions.
+:::
-.. option:: --remark-type=<value>
+:::{option} --remark-type=<value>
+Filter remarks by type with the following options.
- Filter remarks by type with the following options.
+- `unknown`
+- `passed`
+- `missed`
+- `analysis`
+- `analysis-fp-commute`
+- `analysis-aliasing`
+- `failure`
+:::
- * ``unknown``
- * ``passed``
- * ``missed``
- * ``analysis``
- * ``analysis-fp-commute``
- * ``analysis-aliasing``
- * ``failure``
+(size-diff-subcommand)=
-.. _size-diff_subcommand:
+### size-diff
-size-diff
-~~~~~~~~~
+```{eval-rst}
.. program:: llvm-remarkutil size-diff
+```
-USAGE: :program:`llvm-remarkutil` size-diff [*options*] *file_a* *file_b* **--parser** *parser*
+USAGE: {program}`llvm-remarkutil` size-diff \[*options*\] *file_a* *file_b* **--parser** *parser*
-Summary
-^^^^^^^
+#### Summary
-:program:`llvm-remarkutil size-diff` diffs size `remarks <https://llvm.org/docs/Remarks.html>`_ in two remark files: ``file_a``
-and ``file_b``.
+{program}`llvm-remarkutil size-diff` diffs size [remarks](https://llvm.org/docs/Remarks.html) in two remark files: `file_a`
+and `file_b`.
-:program:`llvm-remarkutil size-diff` can be used to gain insight into which
+{program}`llvm-remarkutil size-diff` can be used to gain insight into which
functions were impacted the most by code generation changes.
-In most common use-cases ``file_a`` and ``file_b`` will be remarks output by
+In most common use-cases `file_a` and `file_b` will be remarks output by
compiling a **fixed source** with **differing compilers** or
**differing optimization settings**.
-:program:`llvm-remarkutil size-diff` handles both
-`YAML <https://llvm.org/docs/Remarks.html#yaml-remarks>`_ and
-`bitstream <https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks>`_
+{program}`llvm-remarkutil size-diff` handles both
+[YAML](https://llvm.org/docs/Remarks.html#yaml-remarks) and
+[bitstream](https://llvm.org/docs/Remarks.html#llvm-bitstream-remarks)
remarks.
-Options
-^^^^^^^
+#### Options
-.. option:: --parser=<yaml|bitstream>
+:::{option} --parser=<yaml|bitstream>
+:::
Select the type of input remark parser. Required.
-* ``yaml`` : The tool will parse YAML remarks.
-* ``bitstream`` : The tool will parse bitstream remarks.
-
-.. option:: --report-style=<human|json>
+- `yaml` : The tool will parse YAML remarks.
+- `bitstream` : The tool will parse bitstream remarks.
- Output style.
+:::{option} --report-style=<human|json>
+Output style.
- * ``human`` : Human-readable textual report. Default option.
- * ``json`` : JSON report.
+- `human` : Human-readable textual report. Default option.
+- `json` : JSON report.
+:::
-.. option:: --pretty
+:::{option} --pretty
+Pretty-print JSON output. Optional.
- Pretty-print JSON output. Optional.
+If output is not set to JSON, this does nothing.
+:::
- If output is not set to JSON, this does nothing.
+:::{option} -o=<file>
+Output file for the report. Outputs to stdout by default.
+:::
-.. option:: -o=<file>
+#### Human-Readable Output
- Output file for the report. Outputs to stdout by default.
-
-Human-Readable Output
-^^^^^^^^^^^^^^^^^^^^^
-
-The human-readable format for :program:`llvm-remarkutil size-diff` is composed of
+The human-readable format for {program}`llvm-remarkutil size-diff` is composed of
two sections:
-* Per-function changes.
-* A high-level summary of all changes.
+- Per-function changes.
+- A high-level summary of all changes.
-Changed Function Section
-^^^^^^^^^^^^^^^^^^^^^^^^
+#### Changed Function Section
Suppose you are comparing two remark files OLD and NEW.
For each function with a **changed instruction count** in OLD and NEW,
-:program:`llvm-remarkutil size-diff` will emit a line like below:
+{program}`llvm-remarkutil size-diff` will emit a line like below:
-::
-
- (++|--|==) (>|<) function_name, N instrs, M stack B
+```
+(++|--|==) (>|<) function_name, N instrs, M stack B
+```
A breakdown of the format is below:
-``(++|--|==)``
- Which of OLD and NEW the ``function_name`` is present in.
+`(++|--|==)`
+
+: Which of OLD and NEW the `function_name` is present in.
- * ``++``: Only in NEW. ("Added")
- * ``--``: Only in OLD. ("Removed")
- * ``==``: In both.
+ - `++`: Only in NEW. ("Added")
+ - `--`: Only in OLD. ("Removed")
+ - `==`: In both.
-``(>|<)``
- Denotes if ``function_name`` has more instructions or fewer instructions in
+`(>|<)`
+
+: Denotes if `function_name` has more instructions or fewer instructions in
the second file.
- * ``>``: More instructions in second file than first file.
- * ``<``: Fewer instructions in second file than in first file.
+ - `>`: More instructions in second file than first file.
+ - `<`: Fewer instructions in second file than in first file.
+
+`function_name`
+
+: The name of the changed function.
+
+`N instrs`
-``function_name``
- The name of the changed function.
+: Second file instruction count - first file instruction count.
-``N instrs``
- Second file instruction count - first file instruction count.
+`M stack B`
-``M stack B``
- Second file stack byte count - first file stack byte count.
+: Second file stack byte count - first file stack byte count.
-Summary Section
-^^^^^^^^^^^^^^^
+#### Summary Section
-:program:`llvm-remarkutil size-diff` will output a high-level summary after
+{program}`llvm-remarkutil size-diff` will output a high-level summary after
printing all changed functions.
-::
+```
+instruction count: N (inst_pct_change%)
+stack byte usage: M (sb_pct_change%)
+```
- instruction count: N (inst_pct_change%)
- stack byte usage: M (sb_pct_change%)
+`N`
-``N``
- Sum of all instruction count changes between the second and first file.
+: Sum of all instruction count changes between the second and first file.
-``inst_pct_change%``
- Percent increase or decrease in instruction count between the second and first
+`inst_pct_change%`
+
+: Percent increase or decrease in instruction count between the second and first
file.
-``M``
- Sum of all stack byte count changes between the second and first file.
+`M`
+
+: Sum of all stack byte count changes between the second and first file.
-``sb_pct_change%``
- Percent increase or decrease in stack byte usage between the second and first
+`sb_pct_change%`
+
+: Percent increase or decrease in stack byte usage between the second and first
file.
-JSON OUTPUT
-^^^^^^^^^^^^
+#### JSON OUTPUT
-High-Level view
-^^^^^^^^^^^^^^^
+#### High-Level view
Suppose we are comparing two files, OLD and NEW.
-:program:`llvm-remarkutil size-diff` will output JSON as follows.
+{program}`llvm-remarkutil size-diff` will output JSON as follows.
+
+```
+"Files": [
+ "A": "path/to/OLD",
+ "B": "path/to/NEW"
+]
-::
+"InBoth": [
+ ...
+],
- "Files": [
- "A": "path/to/OLD",
- "B": "path/to/NEW"
- ]
+"OnlyInA": [
+ ...
+],
- "InBoth": [
- ...
- ],
+"OnlyInB": [
+ ...
+]
+```
- "OnlyInA": [
- ...
- ],
+`Files`
- "OnlyInB": [
- ...
- ]
+: Original paths to remark files.
+ - `A`: Path to the first file.
+ - `B`: Path to the second file.
-``Files``
- Original paths to remark files.
+`InBoth`
- * ``A``: Path to the first file.
- * ``B``: Path to the second file.
+: Functions present in both files.
-``InBoth``
- Functions present in both files.
+`OnlyInA`
-``OnlyInA``
- Functions only present in the first file.
+: Functions only present in the first file.
-``OnlyInB``
- Functions only present in the second file.
+`OnlyInB`
-Function JSON
-^^^^^^^^^^^^^
+: Functions only present in the second file.
-The ``InBoth``, ``OnlyInA``, and ``OnlyInB`` sections contain size information
+#### Function JSON
+
+The `InBoth`, `OnlyInA`, and `OnlyInB` sections contain size information
for each function in the input remark files.
-::
+```
+{
+ "FunctionName" : "function_name"
+ "InstCount": [
+ INST_COUNT_A,
+ INST_COUNT_B
+ ],
+ "StackSize": [
+ STACK_BYTES_A,
+ STACK_BYTES_B
+ ],
+}
+```
+
+`FunctionName`
- {
- "FunctionName" : "function_name"
- "InstCount": [
- INST_COUNT_A,
- INST_COUNT_B
- ],
- "StackSize": [
- STACK_BYTES_A,
- STACK_BYTES_B
- ],
- }
+: Name of the function.
-``FunctionName``
- Name of the function.
+`InstCount`
-``InstCount``
- Instruction counts for the function.
+: Instruction counts for the function.
- * ``INST_COUNT_A``: Instruction count in OLD.
- * ``INST_COUNT_B``: Instruction count in NEW.
+ - `INST_COUNT_A`: Instruction count in OLD.
+ - `INST_COUNT_B`: Instruction count in NEW.
-``StackSize``
- Stack byte counts for the function.
+`StackSize`
- * ``STACK_BYTES_A``: Stack bytes in OLD.
- * ``STACK_BYTES_B``: Stack bytes in NEW.
+: Stack byte counts for the function.
-Computing Diffs From Function JSON
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ - `STACK_BYTES_A`: Stack bytes in OLD.
+ - `STACK_BYTES_B`: Stack bytes in NEW.
+
+#### Computing Diffs From Function JSON
Function JSON does not contain the diffs. Tools consuming JSON output from
-:program:`llvm-remarkutil size-diff` are responsible for computing the diffs
+{program}`llvm-remarkutil size-diff` are responsible for computing the diffs
separately.
**To compute the diffs:**
-* Instruction count diff: ``INST_COUNT_B - INST_COUNT_A``
-* Stack byte count diff: ``STACK_BYTES_B - STACK_BYTES_A``
+- Instruction count diff: `INST_COUNT_B - INST_COUNT_A`
+- Stack byte count diff: `STACK_BYTES_B - STACK_BYTES_A`
-EXIT STATUS
-^^^^^^^^^^^
+#### EXIT STATUS
-:program:`llvm-remarkutil size-diff` returns 0 on success, and a non-zero value
+{program}`llvm-remarkutil size-diff` returns 0 on success, and a non-zero value
otherwise.
+
diff --git a/llvm/docs/CommandGuide/llvm-size.md b/llvm/docs/CommandGuide/llvm-size.md
index 12e7c58c5776d..940a48bf2be28 100644
--- a/llvm/docs/CommandGuide/llvm-size.md
+++ b/llvm/docs/CommandGuide/llvm-size.md
@@ -1,201 +1,198 @@
-llvm-size - print size information
-==================================
+# llvm-size - print size information
+```{eval-rst}
.. program:: llvm-size
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-size` [*options*] [*input...*]
+{program}`llvm-size` \[*options*\] \[*input...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-size` is a tool that prints size information for binary files.
-It is intended to be a drop-in replacement for GNU's :program:`size`.
+{program}`llvm-size` is a tool that prints size information for binary files.
+It is intended to be a drop-in replacement for GNU's {program}`size`.
-The tool prints size information for each ``input`` specified. If no input is
-specified, the program prints size information for ``a.out``. If "``-``" is
-specified as an input file, :program:`llvm-size` reads a file from the standard
+The tool prints size information for each `input` specified. If no input is
+specified, the program prints size information for `a.out`. If "`-`" is
+specified as an input file, {program}`llvm-size` reads a file from the standard
input stream. If an input is an archive, size information will be displayed for
all its members.
-OPTIONS
--------
-
-.. option:: -A
-
- Equivalent to :option:`--format` with a value of ``sysv``.
-
-.. option:: --arch=<arch>
-
- Architecture(s) from Mach-O universal binaries to display information for.
-
-.. option:: -B
-
- Equivalent to :option:`--format` with a value of ``berkeley``.
-
-.. option:: --common
-
- Include ELF common symbol sizes in bss size for ``berkeley`` output format, or
- as a separate section entry for ``sysv`` output. If not specified, these
- symbols are ignored.
-
-.. option:: --exclude-pagezero
-
- Do not include the ``__PAGEZERO`` segment when calculating size information
- for Mach-O files. The ``__PAGEZERO`` segment is a virtual memory region used
- for memory protection that does not contribute to actual size, and excluding
- can provide a better representation of actual size.
-
-.. option:: -d
-
- Equivalent to :option:`--radix` with a value of ``10``.
-
-.. option:: -l
-
- Display verbose address and offset information for segments and sections in
- Mach-O files in ``darwin`` format.
-
-.. option:: --format=<format>
-
- Set the output format to the ``<format>`` specified. Available ``<format>``
- options are ``berkeley`` (the default), ``sysv`` and ``darwin``.
-
- Berkeley output summarises text, data and bss sizes in each file, as shown
- below for a typical pair of ELF files:
-
- .. code-block:: console
-
- $ llvm-size --format=berkeley test.o test2.o
- text data bss dec hex filename
- 182 16 5 203 cb test.elf
- 82 8 1 91 5b test2.o
-
- For Mach-O files, the output format is slightly different:
-
- .. code-block:: console
-
- $ llvm-size --format=berkeley macho.obj macho2.obj
- __TEXT __DATA __OBJC others dec hex
- 4 8 0 0 12 c macho.obj
- 16 32 0 0 48 30 macho2.obj
-
- Sysv output displays size and address information for most sections, with each
- file being listed separately:
-
- .. code-block:: console
-
- $ llvm-size --format=sysv test.elf test2.o
- test.elf :
- section size addr
- .eh_frame 92 2097496
- .text 90 2101248
- .data 16 2105344
- .bss 5 2105360
- .comment 209 0
- Total 412
-
- test2.o :
- section size addr
- .text 26 0
- .data 8 0
- .bss 1 0
- .comment 106 0
- .note.GNU-stack 0 0
- .eh_frame 56 0
- .llvm_addrsig 2 0
- Total 199
-
- ``darwin`` format only affects Mach-O input files. If an input of a different
- file format is specified, :program:`llvm-size` falls back to ``berkeley``
- format. When producing ``darwin`` format, the tool displays information about
- segments and sections:
-
- .. code-block:: console
-
- $ llvm-size --format=darwin macho.obj macho2.obj
- macho.obj:
- Segment : 12
- Section (__TEXT, __text): 4
- Section (__DATA, __data): 8
- total 12
- total 12
- macho2.obj:
- Segment : 48
- Section (__TEXT, __text): 16
- Section (__DATA, __data): 32
- total 48
- total 48
-
-.. option:: --help, -h
-
- Display a summary of command line options.
-
-.. option:: -m
-
- Equivalent to :option:`--format` with a value of ``darwin``.
-
-.. option:: -o
-
- Equivalent to :option:`--radix` with a value of ``8``.
-
-.. option:: --radix=<value>
-
- Display size information in the specified radix. Permitted values are ``8``,
- ``10`` (the default) and ``16`` for octal, decimal and hexadecimal output
- respectively.
-
- Example:
-
- .. code-block:: console
-
- $ llvm-size --radix=8 test.o
- text data bss oct hex filename
- 0152 04 04 162 72 test.o
-
- $ llvm-size --radix=10 test.o
- text data bss dec hex filename
- 106 4 4 114 72 test.o
-
- $ llvm-size --radix=16 test.o
- text data bss dec hex filename
- 0x6a 0x4 0x4 114 72 test.o
-
-.. option:: --totals, -t
-
- Applies only to ``berkeley`` output format. Display the totals for all listed
- fields, in addition to the individual file listings.
-
- Example:
-
- .. code-block:: console
-
- $ llvm-size --totals test.elf test2.o
- text data bss dec hex filename
- 182 16 5 203 cb test.elf
- 82 8 1 91 5b test2.o
- 264 24 6 294 126 (TOTALS)
-
-.. option:: --version
-
- Display the version of the :program:`llvm-size` executable.
-
-.. option:: -x
-
- Equivalent to :option:`--radix` with a value of ``16``.
-
-.. option:: @<FILE>
-
- Read command-line options from response file ``<FILE>``.
-
-EXIT STATUS
------------
-
-:program:`llvm-size` exits with a non-zero exit code if there is an error.
+## OPTIONS
+
+:::{option} -A
+Equivalent to {option}`--format` with a value of `sysv`.
+:::
+
+:::{option} --arch=<arch>
+Architecture(s) from Mach-O universal binaries to display information for.
+:::
+
+:::{option} -B
+Equivalent to {option}`--format` with a value of `berkeley`.
+:::
+
+:::{option} --common
+Include ELF common symbol sizes in bss size for `berkeley` output format, or
+as a separate section entry for `sysv` output. If not specified, these
+symbols are ignored.
+:::
+
+:::{option} --exclude-pagezero
+Do not include the `__PAGEZERO` segment when calculating size information
+for Mach-O files. The `__PAGEZERO` segment is a virtual memory region used
+for memory protection that does not contribute to actual size, and excluding
+can provide a better representation of actual size.
+:::
+
+:::{option} -d
+Equivalent to {option}`--radix` with a value of `10`.
+:::
+
+:::{option} -l
+Display verbose address and offset information for segments and sections in
+Mach-O files in `darwin` format.
+:::
+
+:::{option} --format=<format>
+Set the output format to the `<format>` specified. Available `<format>`
+options are `berkeley` (the default), `sysv` and `darwin`.
+
+Berkeley output summarises text, data and bss sizes in each file, as shown
+below for a typical pair of ELF files:
+
+```console
+$ llvm-size --format=berkeley test.o test2.o
+ text data bss dec hex filename
+ 182 16 5 203 cb test.elf
+ 82 8 1 91 5b test2.o
+```
+
+For Mach-O files, the output format is slightly different:
+
+```console
+$ llvm-size --format=berkeley macho.obj macho2.obj
+__TEXT __DATA __OBJC others dec hex
+4 8 0 0 12 c macho.obj
+16 32 0 0 48 30 macho2.obj
+```
+
+Sysv output displays size and address information for most sections, with each
+file being listed separately:
+
+```console
+$ llvm-size --format=sysv test.elf test2.o
+ test.elf :
+ section size addr
+ .eh_frame 92 2097496
+ .text 90 2101248
+ .data 16 2105344
+ .bss 5 2105360
+ .comment 209 0
+ Total 412
+
+ test2.o :
+ section size addr
+ .text 26 0
+ .data 8 0
+ .bss 1 0
+ .comment 106 0
+ .note.GNU-stack 0 0
+ .eh_frame 56 0
+ .llvm_addrsig 2 0
+ Total 199
+```
+
+`darwin` format only affects Mach-O input files. If an input of a different
+file format is specified, {program}`llvm-size` falls back to `berkeley`
+format. When producing `darwin` format, the tool displays information about
+segments and sections:
+
+```console
+$ llvm-size --format=darwin macho.obj macho2.obj
+ macho.obj:
+ Segment : 12
+ Section (__TEXT, __text): 4
+ Section (__DATA, __data): 8
+ total 12
+ total 12
+ macho2.obj:
+ Segment : 48
+ Section (__TEXT, __text): 16
+ Section (__DATA, __data): 32
+ total 48
+ total 48
+```
+:::
+
+:::{option} --help, -h
+Display a summary of command line options.
+:::
+
+:::{option} -m
+Equivalent to {option}`--format` with a value of `darwin`.
+:::
+
+:::{option} -o
+Equivalent to {option}`--radix` with a value of `8`.
+:::
+
+:::{option} --radix=<value>
+Display size information in the specified radix. Permitted values are `8`,
+`10` (the default) and `16` for octal, decimal and hexadecimal output
+respectively.
+
+Example:
+
+```console
+$ llvm-size --radix=8 test.o
+ text data bss oct hex filename
+ 0152 04 04 162 72 test.o
+
+$ llvm-size --radix=10 test.o
+ text data bss dec hex filename
+ 106 4 4 114 72 test.o
+
+$ llvm-size --radix=16 test.o
+ text data bss dec hex filename
+ 0x6a 0x4 0x4 114 72 test.o
+```
+:::
+
+:::{option} --totals, -t
+Applies only to `berkeley` output format. Display the totals for all listed
+fields, in addition to the individual file listings.
+
+Example:
+
+```console
+$ llvm-size --totals test.elf test2.o
+ text data bss dec hex filename
+ 182 16 5 203 cb test.elf
+ 82 8 1 91 5b test2.o
+ 264 24 6 294 126 (TOTALS)
+```
+:::
+
+:::{option} --version
+Display the version of the {program}`llvm-size` executable.
+:::
+
+:::{option} -x
+Equivalent to {option}`--radix` with a value of `16`.
+:::
+
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-size` 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-size/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-size/>.
diff --git a/llvm/docs/CommandGuide/llvm-stress.md b/llvm/docs/CommandGuide/llvm-stress.md
index 4daea62cdde30..2606eae47a621 100644
--- a/llvm/docs/CommandGuide/llvm-stress.md
+++ b/llvm/docs/CommandGuide/llvm-stress.md
@@ -1,35 +1,33 @@
-llvm-stress - generate random .ll files
-=======================================
+# llvm-stress - generate random .ll files
+```{eval-rst}
.. program:: llvm-stress
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile]
+{program}`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`llvm-stress` tool is used to generate random ``.ll`` files that
+The {program}`llvm-stress` tool is used to generate random `.ll` files that
can be used to test different components of LLVM.
-OPTIONS
--------
+## OPTIONS
-.. option:: -o filename
+:::{option} -o filename
+Specify the output filename.
+:::
- Specify the output filename.
+:::{option} -size size
+Specify the size of the generated `.ll` file.
+:::
-.. option:: -size size
+:::{option} -seed seed
+Specify the seed to be used for the randomly generated instructions.
+:::
- Specify the size of the generated ``.ll`` file.
+## EXIT STATUS
-.. option:: -seed seed
+{program}`llvm-stress` returns 0.
- Specify the seed to be used for the randomly generated instructions.
-
-EXIT STATUS
------------
-
-:program:`llvm-stress` returns 0.
diff --git a/llvm/docs/CommandGuide/llvm-strings.md b/llvm/docs/CommandGuide/llvm-strings.md
index 0a9ab5dca0c1f..1e3a0fa3f1ee7 100644
--- a/llvm/docs/CommandGuide/llvm-strings.md
+++ b/llvm/docs/CommandGuide/llvm-strings.md
@@ -1,126 +1,122 @@
-llvm-strings - print strings
-============================
+# llvm-strings - print strings
+```{eval-rst}
.. program:: llvm-strings
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-strings` [*options*] [*input...*]
+{program}`llvm-strings` \[*options*\] \[*input...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-strings` is a tool intended as a drop-in replacement for GNU's
-:program:`strings`, which looks for printable strings in files and writes them
+{program}`llvm-strings` is a tool intended as a drop-in replacement for GNU's
+{program}`strings`, which looks for printable strings in files and writes them
to the standard output stream. A printable string is any sequence of four (by
default) or more printable ASCII characters. The end of the file, or any other
byte, terminates the current sequence.
-:program:`llvm-strings` looks for strings in each ``input`` file specified.
-Unlike GNU :program:`strings` it looks in the entire input file, regardless of
+{program}`llvm-strings` looks for strings in each `input` file specified.
+Unlike GNU {program}`strings` it looks in the entire input file, regardless of
file format, rather than restricting the search to certain sections of object
-files. If "``-``" is specified as an ``input``, or no ``input`` is specified,
+files. If "`-`" is specified as an `input`, or no `input` is specified,
the program reads from the standard input stream.
-EXAMPLE
--------
-
-.. code-block:: console
-
- $ cat input.txt
- bars
- foo
- wibble blob
- $ llvm-strings input.txt
- bars
- wibble blob
-
-OPTIONS
--------
-
-.. option:: --all, -a
-
- Silently ignored. Present for GNU :program:`strings` compatibility.
-
-.. option:: --bytes=<length>, -n
-
- Set the minimum number of printable ASCII characters required for a sequence of
- bytes to be considered a string. The default value is 4.
-
-.. option:: --help, -h
-
- Display a summary of command line options.
-
-.. option:: --print-file-name, -f
-
- Display the name of the containing file before each string.
-
- Example:
-
- .. code-block:: console
-
- $ llvm-strings --print-file-name test.o test.elf
- test.o: _Z5hellov
- test.o: some_bss
- test.o: test.cpp
- test.o: main
- test.elf: test.cpp
- test.elf: test2.cpp
- test.elf: _Z5hellov
- test.elf: main
- test.elf: some_bss
-
-.. option:: --radix=<radix>, -t
-
- Display the offset within the file of each string, before the string and using
- the specified radix. Valid ``<radix>`` values are ``o``, ``d`` and ``x`` for
- octal, decimal and hexadecimal respectively.
-
- Example:
-
- .. code-block:: console
-
- $ llvm-strings --radix=o test.o
- 1054 _Z5hellov
- 1066 .rela.text
- 1101 .comment
- 1112 some_bss
- 1123 .bss
- 1130 test.cpp
- 1141 main
- $ llvm-strings --radix=d test.o
- 556 _Z5hellov
- 566 .rela.text
- 577 .comment
- 586 some_bss
- 595 .bss
- 600 test.cpp
- 609 main
- $ llvm-strings -t x test.o
- 22c _Z5hellov
- 236 .rela.text
- 241 .comment
- 24a some_bss
- 253 .bss
- 258 test.cpp
- 261 main
-
-.. option:: --version
-
- Display the version of the :program:`llvm-strings` executable.
-
-.. option:: @<FILE>
-
- Read command-line options from response file ``<FILE>``.
-
-EXIT STATUS
------------
-
-:program:`llvm-strings` exits with a non-zero exit code if there is an error.
+## EXAMPLE
+
+```console
+$ cat input.txt
+bars
+foo
+wibble blob
+$ llvm-strings input.txt
+bars
+wibble blob
+```
+
+## OPTIONS
+
+:::{option} --all, -a
+Silently ignored. Present for GNU {program}`strings` compatibility.
+:::
+
+:::{option} --bytes=<length>, -n
+Set the minimum number of printable ASCII characters required for a sequence of
+bytes to be considered a string. The default value is 4.
+:::
+
+:::{option} --help, -h
+Display a summary of command line options.
+:::
+
+:::{option} --print-file-name, -f
+Display the name of the containing file before each string.
+
+Example:
+
+```console
+$ llvm-strings --print-file-name test.o test.elf
+test.o: _Z5hellov
+test.o: some_bss
+test.o: test.cpp
+test.o: main
+test.elf: test.cpp
+test.elf: test2.cpp
+test.elf: _Z5hellov
+test.elf: main
+test.elf: some_bss
+```
+:::
+
+:::{option} --radix=<radix>, -t
+Display the offset within the file of each string, before the string and using
+the specified radix. Valid `<radix>` values are `o`, `d` and `x` for
+octal, decimal and hexadecimal respectively.
+
+Example:
+
+```console
+$ llvm-strings --radix=o test.o
+ 1054 _Z5hellov
+ 1066 .rela.text
+ 1101 .comment
+ 1112 some_bss
+ 1123 .bss
+ 1130 test.cpp
+ 1141 main
+$ llvm-strings --radix=d test.o
+ 556 _Z5hellov
+ 566 .rela.text
+ 577 .comment
+ 586 some_bss
+ 595 .bss
+ 600 test.cpp
+ 609 main
+$ llvm-strings -t x test.o
+ 22c _Z5hellov
+ 236 .rela.text
+ 241 .comment
+ 24a some_bss
+ 253 .bss
+ 258 test.cpp
+ 261 main
+```
+:::
+
+:::{option} --version
+Display the version of the {program}`llvm-strings` executable.
+:::
+
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-strings` 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-strings/>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-strings/>.
diff --git a/llvm/docs/CommandGuide/llvm-strip.md b/llvm/docs/CommandGuide/llvm-strip.md
index d6f4ab1d37461..2a0be6678dce8 100644
--- a/llvm/docs/CommandGuide/llvm-strip.md
+++ b/llvm/docs/CommandGuide/llvm-strip.md
@@ -1,18 +1,17 @@
-llvm-strip - object stripping tool
-==================================
+# llvm-strip - object stripping tool
+```{eval-rst}
.. program:: llvm-strip
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-strip` [*options*] *inputs...*
+{program}`llvm-strip` \[*options*\] *inputs...*
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-strip` is a tool to strip sections and symbols from object files.
-If no other stripping or remove options are specified, :option:`--strip-all`
+{program}`llvm-strip` is a tool to strip sections and symbols from object files.
+If no other stripping or remove options are specified, {option}`--strip-all`
will be enabled.
By default, the input files are modified in-place. If "-" is specified for the
@@ -22,193 +21,186 @@ If the input is an archive, any requested operations will be applied to each
archive member individually.
The tool is still in active development, but in most scenarios it works as a
-drop-in replacement for GNU's :program:`strip`.
+drop-in replacement for GNU's {program}`strip`.
-GENERIC AND CROSS-PLATFORM OPTIONS
-----------------------------------
+## GENERIC AND CROSS-PLATFORM OPTIONS
The following options are either agnostic of the file format, or apply to
multiple file formats.
-.. option:: --disable-deterministic-archives, -U
-
- Use real values for UIDs, GIDs and timestamps when updating archive member
- headers.
-
-.. option:: --discard-all, -x
-
- Remove most local symbols not referenced by relocations from the output.
- Different file formats may limit this to a subset of the local symbols. For
- example, file and section symbols in ELF objects will not be discarded.
- Additionally, remove all debug sections.
-
-.. option:: --enable-deterministic-archives, -D
-
- Enable deterministic mode when stripping archives, i.e. use 0 for archive member
- header UIDs, GIDs and timestamp fields. On by default.
-
-.. option:: --help, -h
-
- Print a summary of command line options.
-
-.. option:: --no-strip-all
-
- Disable :option:`--strip-all`.
-
-.. option:: -o <file>
-
- Write output to <file>. Multiple input files cannot be used in combination
- with -o.
-
-.. option:: --only-keep-debug
-
- Produce a debug file as the output that only preserves contents of sections
- useful for debugging purposes.
-
- For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
- `SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
- possible.
-
-.. option:: --regex
-
- If specified, symbol and section names specified by other switches are treated
- as extended POSIX regular expression patterns.
-
-.. option:: --remove-section <section>, -R
-
- Remove the specified section from the output. Can be specified multiple times
- to remove multiple sections simultaneously.
-
-.. option:: --strip-all-gnu
-
- Remove all symbols, debug sections and relocations from the output. This option
- is equivalent to GNU :program:`strip`'s ``--strip-all`` switch.
-
-.. option:: --strip-all, -s
-
- For ELF objects, remove from the output all symbols and non-alloc sections not
- within segments, except for .gnu.warning, .ARM.attribute sections and the
- section name table.
-
- For COFF and Mach-O objects, remove all symbols, debug sections, and
- relocations from the output.
-
- For WebAssembly objects, remove all custom sections except for those named
- metadata.code.*.
-
-.. option:: --strip-debug, -d, -g, -S
-
- Remove all debug sections from the output.
-
-.. option:: --strip-symbol <symbol>, -N
-
- Remove all symbols named ``<symbol>`` from the output. Can be specified
- multiple times to remove multiple symbols.
-
-.. option:: --strip-unneeded
-
- Remove from the output all local or undefined symbols that are not required by
- relocations. Also remove all debug sections.
-
-.. option:: --verbose, -v
-
- Print the paths of files that are copied.
-
-.. option:: --version, -V
-
- Display the version of the :program:`llvm-strip` executable.
-
-.. option:: --wildcard, -w
-
- Allow wildcard syntax for symbol-related flags. On by default for
- section-related flags. Incompatible with --regex.
-
- Wildcard syntax allows the following special symbols:
-
- ====================== ========================= ==================
- Character Meaning Equivalent
- ====================== ========================= ==================
- ``*`` Any number of characters ``.*``
- ``?`` Any single character ``.``
- ``\`` Escape the next character ``\``
- ``[a-z]`` Character class ``[a-z]``
- ``[!a-z]``, ``[^a-z]`` Negated character class ``[^a-z]``
- ====================== ========================= ==================
-
- Additionally, starting a wildcard with '!' will prevent a match, even if
- another flag matches. For example ``-w -N '*' -N '!x'`` will strip all symbols
- except for ``x``.
-
- The order of wildcards does not matter. For example, ``-w -N '*' -N '!x'`` is
- the same as ``-w -N '!x' -N '*'``.
-
-.. option:: @<FILE>
-
- Read command-line options and commands from response file `<FILE>`.
-
-ELF-SPECIFIC OPTIONS
---------------------
+:::{option} --disable-deterministic-archives, -U
+Use real values for UIDs, GIDs and timestamps when updating archive member
+headers.
+:::
+
+:::{option} --discard-all, -x
+Remove most local symbols not referenced by relocations from the output.
+Different file formats may limit this to a subset of the local symbols. For
+example, file and section symbols in ELF objects will not be discarded.
+Additionally, remove all debug sections.
+:::
+
+:::{option} --enable-deterministic-archives, -D
+Enable deterministic mode when stripping archives, i.e. use 0 for archive member
+header UIDs, GIDs and timestamp fields. On by default.
+:::
+
+:::{option} --help, -h
+Print a summary of command line options.
+:::
+
+:::{option} --no-strip-all
+Disable {option}`--strip-all`.
+:::
+
+:::{option} -o <file>
+Write output to \<file>. Multiple input files cannot be used in combination
+with -o.
+:::
+
+:::{option} --only-keep-debug
+Produce a debug file as the output that only preserves contents of sections
+useful for debugging purposes.
+
+For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
+`SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
+possible.
+:::
+
+:::{option} --regex
+If specified, symbol and section names specified by other switches are treated
+as extended POSIX regular expression patterns.
+:::
+
+:::{option} --remove-section <section>, -R
+Remove the specified section from the output. Can be specified multiple times
+to remove multiple sections simultaneously.
+:::
+
+:::{option} --strip-all-gnu
+Remove all symbols, debug sections and relocations from the output. This option
+is equivalent to GNU {program}`strip`'s `--strip-all` switch.
+:::
+
+:::{option} --strip-all, -s
+For ELF objects, remove from the output all symbols and non-alloc sections not
+within segments, except for .gnu.warning, .ARM.attribute sections and the
+section name table.
+
+For COFF and Mach-O objects, remove all symbols, debug sections, and
+relocations from the output.
+
+For WebAssembly objects, remove all custom sections except for those named
+metadata.code.\*.
+:::
+
+:::{option} --strip-debug, -d, -g, -S
+Remove all debug sections from the output.
+:::
+
+:::{option} --strip-symbol <symbol>, -N
+Remove all symbols named `<symbol>` from the output. Can be specified
+multiple times to remove multiple symbols.
+:::
+
+:::{option} --strip-unneeded
+Remove from the output all local or undefined symbols that are not required by
+relocations. Also remove all debug sections.
+:::
+
+:::{option} --verbose, -v
+Print the paths of files that are copied.
+:::
+
+:::{option} --version, -V
+Display the version of the {program}`llvm-strip` executable.
+:::
+
+:::{option} --wildcard, -w
+Allow wildcard syntax for symbol-related flags. On by default for
+section-related flags. Incompatible with --regex.
+
+Wildcard syntax allows the following special symbols:
+
+| Character | Meaning | Equivalent |
+| ------------------ | ------------------------- | ---------- |
+| `*` | Any number of characters | `.*` |
+| `?` | Any single character | `.` |
+| `\` | Escape the next character | `\` |
+| `[a-z]` | Character class | `[a-z]` |
+| `[!a-z]`, `[^a-z]` | Negated character class | `[^a-z]` |
+
+Additionally, starting a wildcard with '!' will prevent a match, even if
+another flag matches. For example `-w -N '*' -N '!x'` will strip all symbols
+except for `x`.
+
+The order of wildcards does not matter. For example, `-w -N '*' -N '!x'` is
+the same as `-w -N '!x' -N '*'`.
+:::
+
+:::{option} @<FILE>
+Read command-line options and commands from response file `<FILE>`.
+:::
+
+## ELF-SPECIFIC OPTIONS
The following options are implemented only for ELF objects. If used with other
-objects, :program:`llvm-strip` will either emit an error or silently ignore
+objects, {program}`llvm-strip` will either emit an error or silently ignore
them.
-.. option:: --allow-broken-links
-
- Allow :program:`llvm-strip` to remove sections even if it would leave invalid
- section references. Any invalid sh_link fields will be set to zero.
-
-.. option:: --discard-locals, -X
-
- Remove local symbols starting with ".L" not referenced by relocations from the output.
+:::{option} --allow-broken-links
+Allow {program}`llvm-strip` to remove sections even if it would leave invalid
+section references. Any invalid sh_link fields will be set to zero.
+:::
-.. option:: --keep-file-symbols
+:::{option} --discard-locals, -X
+Remove local symbols starting with ".L" not referenced by relocations from the output.
+:::
- Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
+:::{option} --keep-file-symbols
+Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
+:::
-.. option:: --keep-section <section>
+:::{option} --keep-section <section>
+When removing sections from the output, do not remove sections named
+`<section>`. Can be specified multiple times to keep multiple sections.
+:::
- When removing sections from the output, do not remove sections named
- ``<section>``. Can be specified multiple times to keep multiple sections.
+:::{option} --keep-symbol <symbol>, -K
+When removing symbols from the output, do not remove symbols named
+`<symbol>`. Can be specified multiple times to keep multiple symbols.
+:::
-.. option:: --keep-symbol <symbol>, -K
+:::{option} --preserve-dates, -p
+Preserve access and modification timestamps in the output.
+:::
- When removing symbols from the output, do not remove symbols named
- ``<symbol>``. Can be specified multiple times to keep multiple symbols.
+:::{option} --strip-sections
+Remove from the output all section headers and all section data not within
+segments. Note that many tools will not be able to use an object without
+section headers.
+:::
-.. option:: --preserve-dates, -p
-
- Preserve access and modification timestamps in the output.
-
-.. option:: --strip-sections
-
- Remove from the output all section headers and all section data not within
- segments. Note that many tools will not be able to use an object without
- section headers.
-
-MACH-O-SPECIFIC OPTIONS
------------------------
+## MACH-O-SPECIFIC OPTIONS
The following options are implemented only for Mach-O objects. If used with other
-objects, :program:`llvm-strip` will either emit an error or silently ignore
+objects, {program}`llvm-strip` will either emit an error or silently ignore
them.
-.. option:: -T
-
- Remove Swift symbols.
+:::{option} -T
+Remove Swift symbols.
+:::
-EXIT STATUS
------------
+## EXIT STATUS
-:program:`llvm-strip` exits with a non-zero exit code if there is an error.
+{program}`llvm-strip` 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%2Fstrip>>.
-To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy%2Fstrip>.
+## SEE ALSO
-SEE ALSO
---------
+{manpage}`llvm-objcopy(1)`
-:manpage:`llvm-objcopy(1)`
diff --git a/llvm/docs/CommandGuide/llvm-symbolizer.md b/llvm/docs/CommandGuide/llvm-symbolizer.md
index e56a7f209d196..916173f6f6cc6 100644
--- a/llvm/docs/CommandGuide/llvm-symbolizer.md
+++ b/llvm/docs/CommandGuide/llvm-symbolizer.md
@@ -1,20 +1,19 @@
-llvm-symbolizer - convert addresses into source code locations
-==============================================================
+# llvm-symbolizer - convert addresses into source code locations
+```{eval-rst}
.. program:: llvm-symbolizer
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-symbolizer` [*options*] [*addresses...*]
+{program}`llvm-symbolizer` \[*options*\] \[*addresses...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-symbolizer` reads input names and addresses from the command-line
+{program}`llvm-symbolizer` reads input names and addresses from the command-line
and prints corresponding source code locations to standard output. It can also
-symbolize logs containing :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` via
-:option:`--filter-markup`. Addresses may be specified as numbers or symbol names.
+symbolize logs containing {doc}`Symbolizer Markup </SymbolizerMarkupFormat>` via
+{option}`--filter-markup`. Addresses may be specified as numbers or symbol names.
If no address is specified on the command-line, it reads the addresses from
standard input. If no input name is specified on the command-line, but addresses
@@ -24,155 +23,154 @@ recognized, it reports that source information is not found.
Input names can be specified together with the addresses either on standard
input or as positional arguments on the command-line. By default, input names
are interpreted as object file paths. However, prefixing a name with
-``BUILDID:`` states that it is a hex build ID rather than a path. This will look
+`BUILDID:` states that it is a hex build ID rather than a path. This will look
up the corresponding debug binary. For consistency, prefixing a name with
-``FILE:`` explicitly states that it is an object file path (the default).
+`FILE:` explicitly states that it is an object file path (the default).
A positional argument or standard input value can be preceded by "DATA" or
"CODE" to indicate that the address should be symbolized as data or executable
code respectively. If neither is specified, "CODE" is assumed. DATA is
symbolized as address and symbol size rather than line number.
-:program:`llvm-symbolizer` parses options from the environment variable
-``LLVM_SYMBOLIZER_OPTS`` after parsing options from the command line.
-``LLVM_SYMBOLIZER_OPTS`` is primarily useful for supplementing the command-line
-options when :program:`llvm-symbolizer` is invoked by another program or
+{program}`llvm-symbolizer` parses options from the environment variable
+`LLVM_SYMBOLIZER_OPTS` after parsing options from the command line.
+`LLVM_SYMBOLIZER_OPTS` is primarily useful for supplementing the command-line
+options when {program}`llvm-symbolizer` is invoked by another program or
runtime.
-EXAMPLES
---------
+## EXAMPLES
All of the following examples use the following two source files as input. They
use a mixture of C-style and C++-style linkage to illustrate how these names are
-printed differently (see :option:`--demangle`).
-
-.. code-block:: c
-
- // test.h
- extern "C" inline int foz() {
- return 1234;
- }
-
-.. code-block:: c
-
- // test.cpp
- #include "test.h"
- int bar=42;
-
- int foo() {
- return bar;
- }
-
- int baz() {
- volatile int k = 42;
- return foz() + k;
- }
-
- int main() {
- return foo() + baz();
- }
+printed differently (see {option}`--demangle`).
+
+```c
+// test.h
+extern "C" inline int foz() {
+ return 1234;
+}
+```
+
+```c
+// test.cpp
+#include "test.h"
+int bar=42;
+
+int foo() {
+ return bar;
+}
+
+int baz() {
+ volatile int k = 42;
+ return foz() + k;
+}
+
+int main() {
+ return foo() + baz();
+}
+```
These files are built as follows:
-.. code-block:: console
-
- $ clang -g test.cpp -o test.elf
- $ clang -g -O2 test.cpp -o inlined.elf
+```console
+$ clang -g test.cpp -o test.elf
+$ clang -g -O2 test.cpp -o inlined.elf
+```
Example 1 - addresses and object on command-line:
-.. code-block:: console
+```console
+$ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
+foz
+/tmp/test.h:1:0
- $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
- foz
- /tmp/test.h:1:0
-
- baz()
- /tmp/test.cpp:11:0
+baz()
+/tmp/test.cpp:11:0
+```
Example 2 - addresses on standard input:
-.. code-block:: console
-
- $ cat addr.txt
- 0x4004a0
- 0x400490
- 0x4004d0
- $ llvm-symbolizer --obj=test.elf < addr.txt
- main
- /tmp/test.cpp:15:0
+```console
+$ cat addr.txt
+0x4004a0
+0x400490
+0x4004d0
+$ llvm-symbolizer --obj=test.elf < addr.txt
+main
+/tmp/test.cpp:15:0
- baz()
- /tmp/test.cpp:11:0
+baz()
+/tmp/test.cpp:11:0
- foz
- /tmp/./test.h:1:0
+foz
+/tmp/./test.h:1:0
+```
Example 3 - object specified with address:
-.. code-block:: console
+```console
+$ llvm-symbolizer "test.elf 0x400490" "FILE:inlined.elf 0x400480"
+baz()
+/tmp/test.cpp:11:0
- $ llvm-symbolizer "test.elf 0x400490" "FILE:inlined.elf 0x400480"
- baz()
- /tmp/test.cpp:11:0
+foo()
+/tmp/test.cpp:8:10
- foo()
- /tmp/test.cpp:8:10
+$ cat addr2.txt
+FILE:test.elf 0x4004a0
+inlined.elf 0x400480
- $ cat addr2.txt
- FILE:test.elf 0x4004a0
- inlined.elf 0x400480
+$ llvm-symbolizer < addr2.txt
+main
+/tmp/test.cpp:15:0
- $ llvm-symbolizer < addr2.txt
- main
- /tmp/test.cpp:15:0
-
- foo()
- /tmp/test.cpp:8:10
+foo()
+/tmp/test.cpp:8:10
+```
Example 4 - BUILDID and FILE prefixes:
-.. code-block:: console
-
- $ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"
- baz()
- /tmp/test.cpp:11:0
+```console
+$ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"
+baz()
+/tmp/test.cpp:11:0
- bar
- 6295592 4
+bar
+6295592 4
- $ cat addr3.txt
- FILE:test.elf 0x400490
- DATA BUILDID:123456789abcdef 0x601028
+$ cat addr3.txt
+FILE:test.elf 0x400490
+DATA BUILDID:123456789abcdef 0x601028
- $ llvm-symbolizer < addr3.txt
- baz()
- /tmp/test.cpp:11:0
+$ llvm-symbolizer < addr3.txt
+baz()
+/tmp/test.cpp:11:0
- bar
- 6295592 4
+bar
+6295592 4
+```
Example 5 - CODE and DATA prefixes:
-.. code-block:: console
+```console
+$ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
+baz()
+/tmp/test.cpp:11:0
- $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
- baz()
- /tmp/test.cpp:11:0
+bar
+6295592 4
- bar
- 6295592 4
+$ cat addr4.txt
+CODE test.elf 0x4004a0
+DATA inlined.elf 0x601028
- $ cat addr4.txt
- CODE test.elf 0x4004a0
- DATA inlined.elf 0x601028
+$ llvm-symbolizer < addr4.txt
+main
+/tmp/test.cpp:15:0
- $ llvm-symbolizer < addr4.txt
- main
- /tmp/test.cpp:15:0
-
- bar
- 6295592 4
+bar
+6295592 4
+```
Example 6 - path-style options:
@@ -181,406 +179,399 @@ full path is /tmp/foo/test.cpp and is compiled as follows. The first case
shows the default absolute path, the second --basenames, and the third
shows --relativenames.
-.. code-block:: console
-
- $ pwd
- /tmp
- $ clang -g foo/test.cpp -o test.elf
- $ llvm-symbolizer --obj=test.elf 0x4004a0
- main
- /tmp/foo/test.cpp:15:0
- $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
- main
- test.cpp:15:0
- $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
- main
- foo/test.cpp:15:0
+```console
+$ pwd
+/tmp
+$ clang -g foo/test.cpp -o test.elf
+$ llvm-symbolizer --obj=test.elf 0x4004a0
+main
+/tmp/foo/test.cpp:15:0
+$ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
+main
+test.cpp:15:0
+$ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
+main
+foo/test.cpp:15:0
+```
Example 7 - Addresses as symbol names:
-.. code-block:: console
-
- $ llvm-symbolizer --obj=test.elf main
- main
- /tmp/test.cpp:14:0
- $ llvm-symbolizer --obj=test.elf "CODE foz"
- foz
- /tmp/test.h:1:0
-
-Example 8 - :option:`--skip-line-zero` output for an address with no line correspondence (an address associated with line zero):
-
-.. code-block:: c
-
- // test.c
- int foo = 0;
- int x = 1234;
- int main() {
- if (x)
- return foo;
- else
- return x;
- }
+```console
+$ llvm-symbolizer --obj=test.elf main
+main
+/tmp/test.cpp:14:0
+$ llvm-symbolizer --obj=test.elf "CODE foz"
+foz
+/tmp/test.h:1:0
+```
+
+Example 8 - {option}`--skip-line-zero` output for an address with no line correspondence (an address associated with line zero):
+
+```c
+// test.c
+int foo = 0;
+int x = 1234;
+int main() {
+ if (x)
+ return foo;
+ else
+ return x;
+}
+```
These files are built as follows:
-.. code-block:: console
-
- $ clang -g -O2 -S test.c -o test.s
- $ llvm-mc -filetype=obj -triple=x86_64-unknown-linux test.s -o test.o
-
-.. code-block:: console
-
- $ llvm-symbolizer --obj=test.o --skip-line-zero 0xa
- main
- /tmp/test.c:5:7 (approximate)
-
-OPTIONS
--------
-
-.. option:: --adjust-vma <offset>
-
- Add the specified offset to object file addresses when performing lookups.
- This can be used to perform lookups as if the object were relocated by the
- offset.
-
-.. option:: --skip-line-zero
-
- If an address does not have an associated line number, use the last line
- number from the current sequence in the line-table. Such lines are labeled
- as "approximate" in the output as they may be misleading.
-
-.. option:: --basenames, -s
-
- Print just the file's name without any directories, instead of the
- absolute path.
-
-.. option:: --build-id
-
- Look up the object using the given build ID, specified as a hexadecimal
- string. Mutually exclusive with :option:`--obj`.
-
-.. option:: --color [=<always|auto|never>]
-
- Specify whether to use color in :option:`--filter-markup` mode. Defaults to
- ``auto``, which detects whether standard output supports color. Specifying
- ``--color`` alone is equivalent to ``--color=always``.
-
-.. option:: --debug-file-directory <path>
-
- Provide a path to a directory with a `.build-id` subdirectory to search for
- debug information for stripped binaries. Multiple instances of this argument
- are searched in the order given.
-
-.. option:: --debuginfod, --no-debuginfod
-
- Whether or not to try debuginfod lookups for debug binaries. Unless specified,
- debuginfod is only enabled if libcurl was compiled in (``LLVM_ENABLE_CURL``)
- and at least one server URL was provided by the environment variable
- ``DEBUGINFOD_URLS``.
-
-.. _llvm-symbolizer-opt-C:
-
-.. option:: --demangle, -C
-
- Print demangled function names, if the names are mangled (e.g. the mangled
- name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
- as is). Defaults to true.
-
-.. option:: --dwp <path>
-
- Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
- debug data.
-
-.. option:: --fallback-debug-path <path>
-
- When a separate file contains debug data, and is referenced by a GNU debug
- link section, use the specified path as a basis for locating the debug data if
- it cannot be found relative to the object.
-
-.. option:: --filter-markup
-
- Reads from standard input, converts contained
- :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable form,
- and prints the results to standard output. The following markup elements are
- not yet supported:
-
- * ``{{{hexdict}}}``
- * ``{{{dumpfile}}}``
-
- The ``{{{bt}}}`` backtrace element reports frames using the following syntax:
-
- ``#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)``
-
- ``<inline>`` provides frame numbers for calls inlined into the caller
- corresponding to ``<number>``. The inlined call numbers start at 1 and increase
- from callee to caller.
-
- ``<address>`` is an address inside the call instruction to the function. The
- address may not be the start of the instruction. ``<relative address>`` is
- the corresponding virtual offset in the ``<module>`` loaded at that address.
-
-
-.. _llvm-symbolizer-opt-f:
-
-.. option:: --functions [=<none|short|linkage>], -f
-
- Specify the way function names are printed (omit function name, print short
- function name, or print full linkage name, respectively). Defaults to
- ``linkage``.
-
-.. option:: --help, -h
-
- Show help and usage for this command.
-
-.. _llvm-symbolizer-opt-i:
-
-.. option:: --inlining, --inlines, -i
-
- If a source code location is in an inlined function, prints all the inlined
- frames. This is the default.
+```console
+$ clang -g -O2 -S test.c -o test.s
+$ llvm-mc -filetype=obj -triple=x86_64-unknown-linux test.s -o test.o
+```
+
+```console
+$ llvm-symbolizer --obj=test.o --skip-line-zero 0xa
+main
+/tmp/test.c:5:7 (approximate)
+```
+
+## OPTIONS
+
+:::{option} --adjust-vma <offset>
+Add the specified offset to object file addresses when performing lookups.
+This can be used to perform lookups as if the object were relocated by the
+offset.
+:::
+
+:::{option} --skip-line-zero
+If an address does not have an associated line number, use the last line
+number from the current sequence in the line-table. Such lines are labeled
+as "approximate" in the output as they may be misleading.
+:::
+
+:::{option} --basenames, -s
+Print just the file's name without any directories, instead of the
+absolute path.
+:::
+
+:::{option} --build-id
+Look up the object using the given build ID, specified as a hexadecimal
+string. Mutually exclusive with {option}`--obj`.
+:::
+
+:::{option} --color [=<always|auto|never>]
+Specify whether to use color in {option}`--filter-markup` mode. Defaults to
+`auto`, which detects whether standard output supports color. Specifying
+`--color` alone is equivalent to `--color=always`.
+:::
+
+:::{option} --debug-file-directory <path>
+Provide a path to a directory with a `.build-id` subdirectory to search for
+debug information for stripped binaries. Multiple instances of this argument
+are searched in the order given.
+:::
+
+:::{option} --debuginfod, --no-debuginfod
+Whether or not to try debuginfod lookups for debug binaries. Unless specified,
+debuginfod is only enabled if libcurl was compiled in (`LLVM_ENABLE_CURL`)
+and at least one server URL was provided by the environment variable
+`DEBUGINFOD_URLS`.
+:::
+
+(llvm-symbolizer-opt-c)=
+
+:::{option} --demangle, -C
+Print demangled function names, if the names are mangled (e.g. the mangled
+name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
+as is). Defaults to true.
+:::
+
+:::{option} --dwp <path>
+Use the specified DWP file at `<path>` for any CUs that have split DWARF
+debug data.
+:::
+
+:::{option} --fallback-debug-path <path>
+When a separate file contains debug data, and is referenced by a GNU debug
+link section, use the specified path as a basis for locating the debug data if
+it cannot be found relative to the object.
+:::
+
+:::{option} --filter-markup
+Reads from standard input, converts contained
+{doc}`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable form,
+and prints the results to standard output. The following markup elements are
+not yet supported:
+
+- `{{{hexdict}}}`
+- `{{{dumpfile}}}`
+
+The `{{{bt}}}` backtrace element reports frames using the following syntax:
+
+`#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)`
+
+`<inline>` provides frame numbers for calls inlined into the caller
+corresponding to `<number>`. The inlined call numbers start at 1 and increase
+from callee to caller.
+
+`<address>` is an address inside the call instruction to the function. The
+address may not be the start of the instruction. `<relative address>` is
+the corresponding virtual offset in the `<module>` loaded at that address.
+:::
+
+(llvm-symbolizer-opt-f)=
+
+:::{option} --functions [=<none|short|linkage>], -f
+Specify the way function names are printed (omit function name, print short
+function name, or print full linkage name, respectively). Defaults to
+`linkage`.
+:::
+
+:::{option} --help, -h
+Show help and usage for this command.
+:::
+
+(llvm-symbolizer-opt-i)=
+
+:::{option} --inlining, --inlines, -i
+If a source code location is in an inlined function, prints all the inlined
+frames. This is the default.
+:::
+
+:::{option} --no-inlines
+Don't print inlined frames.
+:::
+
+:::{option} --no-demangle
+Don't print demangled function names.
+:::
+
+:::{option} --obj <path>, --exe, -e
+Path to object file to be symbolized. If `-` is specified, read the object
+directly from the standard input stream. Mutually exclusive with
+{option}`--build-id`.
+:::
+
+(llvm-symbolizer-opt-output-style)=
+
+:::{option} --output-style <LLVM|GNU|JSON>
+Specify the preferred output style. Defaults to `LLVM`. When the output
+style is set to `GNU`, the tool follows the style of GNU's **addr2line**.
+The differences from the `LLVM` style are:
+
+- Does not print the column of a source code location.
+- Does not add an empty line after the report for an address.
+- Does not replace the name of an inlined function with the name of the
+ topmost caller when inlined frames are not shown.
+- Prints an address's debug-data discriminator when it is non-zero. One way to
+ produce discriminators is to compile with clang's -fdebug-info-for-profiling.
+
+`JSON` style provides a machine-readable output in JSON. If addresses are
+
+: supplied via stdin, the output JSON will be a series of individual objects.
+ Otherwise, all results will be contained in a single array.
-.. option:: --no-inlines
+```console
+$ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
+baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
- Don't print inlined frames.
+foo() at /tmp/test.cpp:6:3
-.. option:: --no-demangle
+$ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
+main at /tmp/test.cpp:11:18
+
+foo() at /tmp/test.cpp:6:3
- Don't print demangled function names.
+$ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
+baz() at /tmp/test.cpp:11
+foo() at /tmp/test.cpp:6
-.. option:: --obj <path>, --exe, -e
+$ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
+$ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
+main at /tmp/test.cpp:15 (discriminator 2)
- Path to object file to be symbolized. If ``-`` is specified, read the object
- directly from the standard input stream. Mutually exclusive with
- :option:`--build-id`.
-
-.. _llvm-symbolizer-opt-output-style:
-
-.. option:: --output-style <LLVM|GNU|JSON>
-
- Specify the preferred output style. Defaults to ``LLVM``. When the output
- style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
- The differences from the ``LLVM`` style are:
-
- * Does not print the column of a source code location.
-
- * Does not add an empty line after the report for an address.
-
- * Does not replace the name of an inlined function with the name of the
- topmost caller when inlined frames are not shown.
-
- * Prints an address's debug-data discriminator when it is non-zero. One way to
- produce discriminators is to compile with clang's -fdebug-info-for-profiling.
-
- ``JSON`` style provides a machine-readable output in JSON. If addresses are
- supplied via stdin, the output JSON will be a series of individual objects.
- Otherwise, all results will be contained in a single array.
-
- .. code-block:: console
-
- $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
- baz() at /tmp/test.cpp:11:18
- (inlined by) main at /tmp/test.cpp:15:0
-
- foo() at /tmp/test.cpp:6:3
-
- $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
- main at /tmp/test.cpp:11:18
-
- foo() at /tmp/test.cpp:6:3
-
- $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
- baz() at /tmp/test.cpp:11
- foo() at /tmp/test.cpp:6
-
- $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
- $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
- main at /tmp/test.cpp:15 (discriminator 2)
-
- $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
- [
+$ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
+[
+ {
+ "Address": "0x4004be",
+ "ModuleName": "inlined.elf",
+ "Symbol": [
{
- "Address": "0x4004be",
- "ModuleName": "inlined.elf",
- "Symbol": [
- {
- "Column": 18,
- "Discriminator": 0,
- "FileName": "/tmp/test.cpp",
- "FunctionName": "baz()",
- "Line": 11,
- "StartAddress": "0x4004be",
- "StartFileName": "/tmp/test.cpp",
- "StartLine": 9
- },
- {
- "Column": 0,
- "Discriminator": 0,
- "FileName": "/tmp/test.cpp",
- "FunctionName": "main",
- "Line": 15,
- "StartAddress": "0x4004be",
- "StartFileName": "/tmp/test.cpp",
- "StartLine": 14
- }
- ]
+ "Column": 18,
+ "Discriminator": 0,
+ "FileName": "/tmp/test.cpp",
+ "FunctionName": "baz()",
+ "Line": 11,
+ "StartAddress": "0x4004be",
+ "StartFileName": "/tmp/test.cpp",
+ "StartLine": 9
},
{
- "Address": "0x400486",
- "ModuleName": "inlined.elf",
- "Symbol": [
- {
- "Column": 3,
- "Discriminator": 0,
- "FileName": "/tmp/test.cpp",
- "FunctionName": "foo()",
- "Line": 6,
- "StartAddress": "0x400486",
- "StartFileName": "/tmp/test.cpp",
- "StartLine": 5
- }
- ]
+ "Column": 0,
+ "Discriminator": 0,
+ "FileName": "/tmp/test.cpp",
+ "FunctionName": "main",
+ "Line": 15,
+ "StartAddress": "0x4004be",
+ "StartFileName": "/tmp/test.cpp",
+ "StartLine": 14
}
]
-
-.. option:: --pdb <path>
-
- Use the specified PDB file at ``<path>``, overriding the PDB info
- contained in the COFF object.
-
-.. option:: --pretty-print, -p
-
- Print human-readable output. If :option:`--inlining` is specified, the
- enclosing scope is prefixed by (inlined by).
- For JSON output, the option will cause JSON to be indented and split over
- new lines. Otherwise, the JSON output will be printed in a compact form.
-
- .. code-block:: console
-
- $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
- baz() at /tmp/test.cpp:11:18
- (inlined by) main at /tmp/test.cpp:15:0
-
-.. option:: --print-address, --addresses, -a
-
- Print address before the source code location. Defaults to false.
-
- .. code-block:: console
-
- $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
- 0x4004be
- baz()
- /tmp/test.cpp:11:18
- main
- /tmp/test.cpp:15:0
-
- $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
- 0x4004be: baz() at /tmp/test.cpp:11:18
- (inlined by) main at /tmp/test.cpp:15:0
-
-.. option:: --print-source-context-lines <N>
-
- Print ``N`` lines of source context for each symbolized address.
-
- .. code-block:: console
-
- $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
- baz()
- /tmp/test.cpp:11:0
- 10 : volatile int k = 42;
- 11 >: return foz() + k;
- 12 : }
-
-.. option:: --relativenames
-
- Print the file's path relative to the compilation directory, instead
- of the absolute path. If the command-line to the compiler included
- the full path, this will be the same as the default.
-
-.. option:: --verbose
-
- Print verbose address, line and column information.
-
- .. code-block:: console
-
- $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
- baz()
- Filename: /tmp/test.cpp
- Function start filename: /tmp/test.cpp
- Function start line: 9
- Function start address: 0x4004b6
- Line: 11
- Column: 18
- main
- Filename: /tmp/test.cpp
- Function start filename: /tmp/test.cpp
- Function start line: 14
- Function start address: 0x4004b0
- Line: 15
- Column: 18
-
-.. option:: --version, -v
-
- Print version information for the tool.
-
-.. option:: @<FILE>
-
- Read command-line options from response file `<FILE>`.
-
-WINDOWS/PDB SPECIFIC OPTIONS
------------------------------
-
-.. option:: --dia
-
- Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
- llvm-symbolizer will fall back to the native implementation.
-
-MACH-O SPECIFIC OPTIONS
------------------------
-
-.. option:: --default-arch <arch>
-
- If a binary contains object files for multiple architectures (e.g. it is a
- Mach-O universal binary or an archive with architecture variants),
- symbolize the object file for a given architecture. You can also specify
- the architecture by writing ``binary_name:arch_name`` in the input (see
- example below). For archives, the format ``archive.a(member.o):arch``
- is also supported. If the architecture is not specified,
- the address will not be symbolized. Defaults to empty string.
-
- .. code-block:: console
-
- $ cat addr.txt
- /tmp/mach_universal_binary:i386 0x1f84
- /tmp/mach_universal_binary:x86_64 0x100000f24
- /tmp/archive.a(member.o):ppc 0x1000
- /tmp/archive.a(member.o):ppc64 0x2000
-
- $ llvm-symbolizer < addr.txt
- _main
- /tmp/source_i386.cc:8
-
- _main
- /tmp/source_x86_64.cc:8
-
- _foo
- /tmp/source_ppc.cc:12
-
- _foo
- /tmp/source_ppc64.cc:12
-
-.. option:: --dsym-hint <path/to/file.dSYM>
-
- If the debug info for a binary isn't present in the default location, look for
- the debug info at the .dSYM path provided via this option. This flag can be
- used multiple times.
-
-EXIT STATUS
------------
-
-:program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
+ },
+ {
+ "Address": "0x400486",
+ "ModuleName": "inlined.elf",
+ "Symbol": [
+ {
+ "Column": 3,
+ "Discriminator": 0,
+ "FileName": "/tmp/test.cpp",
+ "FunctionName": "foo()",
+ "Line": 6,
+ "StartAddress": "0x400486",
+ "StartFileName": "/tmp/test.cpp",
+ "StartLine": 5
+ }
+ ]
+ }
+]
+```
+:::
+
+:::{option} --pdb <path>
+Use the specified PDB file at `<path>`, overriding the PDB info
+contained in the COFF object.
+:::
+
+:::{option} --pretty-print, -p
+Print human-readable output. If {option}`--inlining` is specified, the
+enclosing scope is prefixed by (inlined by).
+For JSON output, the option will cause JSON to be indented and split over
+new lines. Otherwise, the JSON output will be printed in a compact form.
+
+```console
+$ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
+baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+```
+:::
+
+:::{option} --print-address, --addresses, -a
+Print address before the source code location. Defaults to false.
+
+```console
+$ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
+0x4004be
+baz()
+/tmp/test.cpp:11:18
+main
+/tmp/test.cpp:15:0
+
+$ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
+0x4004be: baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+```
+:::
+
+:::{option} --print-source-context-lines <N>
+Print `N` lines of source context for each symbolized address.
+
+```console
+$ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
+baz()
+/tmp/test.cpp:11:0
+10 : volatile int k = 42;
+11 >: return foz() + k;
+12 : }
+```
+:::
+
+:::{option} --relativenames
+Print the file's path relative to the compilation directory, instead
+of the absolute path. If the command-line to the compiler included
+the full path, this will be the same as the default.
+:::
+
+:::{option} --verbose
+Print verbose address, line and column information.
+
+```console
+$ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
+baz()
+ Filename: /tmp/test.cpp
+ Function start filename: /tmp/test.cpp
+ Function start line: 9
+ Function start address: 0x4004b6
+ Line: 11
+ Column: 18
+main
+ Filename: /tmp/test.cpp
+ Function start filename: /tmp/test.cpp
+ Function start line: 14
+ Function start address: 0x4004b0
+ Line: 15
+ Column: 18
+```
+:::
+
+:::{option} --version, -v
+Print version information for the tool.
+:::
+
+:::{option} @<FILE>
+Read command-line options from response file `<FILE>`.
+:::
+
+## WINDOWS/PDB SPECIFIC OPTIONS
+
+:::{option} --dia
+Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
+llvm-symbolizer will fall back to the native implementation.
+:::
+
+## MACH-O SPECIFIC OPTIONS
+
+:::{option} --default-arch <arch>
+If a binary contains object files for multiple architectures (e.g. it is a
+Mach-O universal binary or an archive with architecture variants),
+symbolize the object file for a given architecture. You can also specify
+the architecture by writing `binary_name:arch_name` in the input (see
+example below). For archives, the format `archive.a(member.o):arch`
+is also supported. If the architecture is not specified,
+the address will not be symbolized. Defaults to empty string.
+
+```console
+$ cat addr.txt
+/tmp/mach_universal_binary:i386 0x1f84
+/tmp/mach_universal_binary:x86_64 0x100000f24
+/tmp/archive.a(member.o):ppc 0x1000
+/tmp/archive.a(member.o):ppc64 0x2000
+
+$ llvm-symbolizer < addr.txt
+_main
+/tmp/source_i386.cc:8
+
+_main
+/tmp/source_x86_64.cc:8
+
+_foo
+/tmp/source_ppc.cc:12
+
+_foo
+/tmp/source_ppc64.cc:12
+```
+:::
+
+:::{option} --dsym-hint <path/to/file.dSYM>
+If the debug info for a binary isn't present in the default location, look for
+the debug info at the .dSYM path provided via this option. This flag can be
+used multiple times.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-symbolizer` returns 0. Other exit codes imply an internal program
error.
-SEE ALSO
---------
+## SEE ALSO
+
+{manpage}`llvm-addr2line(1)`
-:manpage:`llvm-addr2line(1)`
diff --git a/llvm/docs/CommandGuide/llvm-tblgen.md b/llvm/docs/CommandGuide/llvm-tblgen.md
index 1e8ff8bf6e3e2..12b590065f731 100644
--- a/llvm/docs/CommandGuide/llvm-tblgen.md
+++ b/llvm/docs/CommandGuide/llvm-tblgen.md
@@ -1,22 +1,21 @@
-llvm-tblgen - Target Description to C++ Code for LLVM
-=====================================================
+# llvm-tblgen - Target Description to C++ Code for LLVM
+```{eval-rst}
.. program:: llvm-tblgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-tblgen` [*options*] [*filename*]
+{program}`llvm-tblgen` \[*options*\] \[*filename*\]
+## DESCRIPTION
-DESCRIPTION
------------
-
-:program:`llvm-tblgen` is a program that translates compiler-related target
-description (``.td``) files into C++ code and other output formats. Most
+{program}`llvm-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/llvm-test-mustache-spec.md b/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
index 8cd5a349e7e49..0cd42042a471a 100644
--- a/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
+++ b/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
@@ -1,18 +1,17 @@
-llvm-test-mustache-spec - LLVM tool to test Mustache library compliance
-=======================================================================
+# llvm-test-mustache-spec - LLVM tool to test Mustache library compliance
+```{eval-rst}
.. program:: llvm-test-mustache-spec
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-test-mustache-spec` [*inputs...*]
+{program}`llvm-test-mustache-spec` \[*inputs...*\]
-Description
------------
+## Description
-``llvm-test-mustache-spec`` tests the mustache spec conformance of the LLVM
-mustache library. The spec can be found here: https://github.com/mustache/spec
+`llvm-test-mustache-spec` tests the mustache spec conformance of the LLVM
+mustache library. The spec can be found here: <https://github.com/mustache/spec>
To test against the spec, simply download the spec and pass the test JSON files
to the driver. Each spec file should have a list of tests for compliance with
@@ -28,10 +27,9 @@ marked as XFail and are removed from the XFail list as they are fixed.
The tool prints the number of test failures and successes in each of the test
files to standard output.
-EXAMPLE
--------
+## EXAMPLE
-.. code-block:: console
-
- $ llvm-test-mustache-spec path/to/specs/\*.json
+```console
+$ llvm-test-mustache-spec path/to/specs/\*.json
+```
diff --git a/llvm/docs/CommandGuide/llvm-tli-checker.md b/llvm/docs/CommandGuide/llvm-tli-checker.md
index bbd2bf29f46b9..e983e689b1a70 100644
--- a/llvm/docs/CommandGuide/llvm-tli-checker.md
+++ b/llvm/docs/CommandGuide/llvm-tli-checker.md
@@ -1,17 +1,16 @@
-llvm-tli-checker - TargetLibraryInfo vs library checker
-=======================================================
+# llvm-tli-checker - TargetLibraryInfo vs library checker
+```{eval-rst}
.. program:: llvm-tli-checker
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`llvm-tli-checker` [*options*] [*library-file...*]
+{program}`llvm-tli-checker` \[*options*\] \[*library-file...*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`llvm-tli-checker` compares TargetLibraryInfo's opinion of the
+{program}`llvm-tli-checker` compares TargetLibraryInfo's opinion of the
availability of library functions against the set of functions exported
by the specified library files, reporting any disagreements between TLI's
opinion and whether the function is actually present. This is primarily
@@ -19,67 +18,65 @@ useful for vendors to ensure the TLI for their target is correct, and
the compiler will not "optimize" some code sequence into a library call
that is not actually available.
-EXAMPLE
--------
-
-.. code-block:: console
-
- $ llvm-tli-checker --triple x86_64-scei-ps4 example.so
- TLI knows 466 symbols, 235 available for 'x86_64-scei-ps4'
-
- Looking for symbols in 'example.so'
- Found 235 global function symbols in 'example.so'
- Found a grand total of 235 library symbols
- << TLI yes SDK no: '_ZdaPv' aka operator delete[](void*)
- >> TLI no SDK yes: '_ZdaPvj' aka operator delete[](void*, unsigned int)
- << Total TLI yes SDK no: 1
- >> Total TLI no SDK yes: 1
- == Total TLI yes SDK yes: 234
- FAIL: LLVM TLI doesn't match SDK libraries.
-
-OPTIONS
--------
-
-.. option:: --dump-tli
-
- Print "available"/"not available" for each library function, according to
- TargetLibraryInfo's information for the specified triple, and exit. This
- option does not read any input files.
-
-.. option:: --help, -h
-
- Print a summary of command line options and exit.
-
-.. option:: --libdir=<directory>
-
- A base directory to prepend to each library file path. This is handy
- when there are a number of library files all in the same directory, or
- a list of input filenames are kept in a response file.
-
-.. option:: --report=<level>
-
- The amount of information to report. <level> can be summary, discrepancy,
- or full. A summary report gives only the count of matching and mis-matching
- symbols; discrepancy lists the mis-matching symbols; and full lists all
- symbols known to TLI, matching or mis-matching. The default is discrepancy.
-
-.. option:: --separate
-
- Read and report a summary for each library file separately. This can be
- useful to identify library files that don't contribute anything that TLI
- knows about. Implies --report=summary (can be overridden).
-
-.. option:: --triple=<triple>
-
- The triple to use for initializing TargetLibraryInfo.
-
-.. option:: @<FILE>
-
- Read command-line options and/or library names from response file `<FILE>`.
-
-EXIT STATUS
------------
-
-:program:`llvm-tli-checker` returns 0 even if there are mismatches. It returns a
+## EXAMPLE
+
+```console
+$ llvm-tli-checker --triple x86_64-scei-ps4 example.so
+TLI knows 466 symbols, 235 available for 'x86_64-scei-ps4'
+
+Looking for symbols in 'example.so'
+Found 235 global function symbols in 'example.so'
+Found a grand total of 235 library symbols
+<< TLI yes SDK no: '_ZdaPv' aka operator delete[](void*)
+>> TLI no SDK yes: '_ZdaPvj' aka operator delete[](void*, unsigned int)
+<< Total TLI yes SDK no: 1
+>> Total TLI no SDK yes: 1
+== Total TLI yes SDK yes: 234
+FAIL: LLVM TLI doesn't match SDK libraries.
+```
+
+## OPTIONS
+
+:::{option} --dump-tli
+Print "available"/"not available" for each library function, according to
+TargetLibraryInfo's information for the specified triple, and exit. This
+option does not read any input files.
+:::
+
+:::{option} --help, -h
+Print a summary of command line options and exit.
+:::
+
+:::{option} --libdir=<directory>
+A base directory to prepend to each library file path. This is handy
+when there are a number of library files all in the same directory, or
+a list of input filenames are kept in a response file.
+:::
+
+:::{option} --report=<level>
+The amount of information to report. \<level> can be summary, discrepancy,
+or full. A summary report gives only the count of matching and mis-matching
+symbols; discrepancy lists the mis-matching symbols; and full lists all
+symbols known to TLI, matching or mis-matching. The default is discrepancy.
+:::
+
+:::{option} --separate
+Read and report a summary for each library file separately. This can be
+useful to identify library files that don't contribute anything that TLI
+knows about. Implies --report=summary (can be overridden).
+:::
+
+:::{option} --triple=<triple>
+The triple to use for initializing TargetLibraryInfo.
+:::
+
+:::{option} @<FILE>
+Read command-line options and/or library names from response file `<FILE>`.
+:::
+
+## EXIT STATUS
+
+{program}`llvm-tli-checker` returns 0 even if there are mismatches. It returns a
non-zero exit code if there is an unrecognized option, or no input files are
provided.
+
diff --git a/llvm/docs/CommandGuide/mlir-tblgen.md b/llvm/docs/CommandGuide/mlir-tblgen.md
index e4cb2f3bfaf02..761fdb44ab0cf 100644
--- a/llvm/docs/CommandGuide/mlir-tblgen.md
+++ b/llvm/docs/CommandGuide/mlir-tblgen.md
@@ -1,22 +1,21 @@
-mlir-tblgen - Description to C++ Code for MLIR
-==============================================
+# mlir-tblgen - Description to C++ Code for MLIR
+```{eval-rst}
.. program:: mlir-tblgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`mlir-tblgen` [*options*] [*filename*]
+{program}`mlir-tblgen` \[*options*\] \[*filename*\]
+## DESCRIPTION
-DESCRIPTION
------------
-
-:program:`mlir-tblgen` is a program that translates compiler-related target
-description (``.td``) files into C++ code and other output formats. Most
+{program}`mlir-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/opt.md b/llvm/docs/CommandGuide/opt.md
index bda749f902a16..3368af13f1f3a 100644
--- a/llvm/docs/CommandGuide/opt.md
+++ b/llvm/docs/CommandGuide/opt.md
@@ -1,126 +1,123 @@
-opt - LLVM optimizer
-====================
+# opt - LLVM optimizer
+```{eval-rst}
.. program:: opt
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`opt` [*options*] [*filename*]
+{program}`opt` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-The :program:`opt` command is the modular LLVM optimizer and analyzer. It takes
+The {program}`opt` command is the modular LLVM optimizer and analyzer. It takes
LLVM source files as input, runs the specified optimizations or analyses on it,
and then outputs the optimized file. The optimizations available via
-:program:`opt` depend upon what libraries were linked into it as well as any
-additional libraries that have been loaded with the :option:`-load` option. Use
-the :option:`-help` option to determine what optimizations you can use.
-
-If ``filename`` is omitted from the command line or is "``-``", :program:`opt`
-reads its input from standard input. Inputs can be in either the LLVM assembly
-language format (``.ll``) or the LLVM bitcode format (``.bc``).
-
-If an output filename is not specified with the :option:`-o` option,
-:program:`opt` writes its output to the standard output.
-
-OPTIONS
--------
-
-.. option:: -f
-
- Enable binary output on terminals. Normally, :program:`opt` will refuse to
- write raw bitcode output if the output stream is a terminal. With this option,
- :program:`opt` will write raw bitcode regardless of the output device.
-
-.. option:: -help
-
- Print a summary of command line options.
-
-.. option:: -o <filename>
-
- Specify the output filename.
-
-.. option:: -S
-
- Write output in LLVM intermediate language (instead of bitcode).
-
-.. option:: -passes=<string>
-
- A textual (comma-separated) description of the pass pipeline,
- e.g., ``-passes="sroa,instcombine"``. See
- `invoking opt <../NewPassManager.html#invoking-opt>`_ for more details on the
- pass pipeline syntax.
-
-.. option:: -mtriple=<target triple>
-
- Override the target triple specified in the input file with the specified
- string.
-
-.. 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:
-
- .. code-block:: none
-
- llvm-as < /dev/null | opt -march=xyz -mtune=help
-
-.. option:: -strip-debug
-
- This option causes opt to strip debug information from the module before
- applying other optimizations. It is essentially the same as `-strip`
- but it ensures that stripping of debug information is done first.
-
-.. option:: -verify-each
-
- This option causes opt to add a verify pass after every pass otherwise
- specified on the command line (including `-verify`). This is useful
- for cases where it is suspected that a pass is creating an invalid module but
- it is not clear which pass is doing it.
-
-.. option:: -stats
-
- Print statistics.
-
-.. option:: --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 it to standard
- error.
-
-.. option:: -debug
-
- If this is a debug build, this option will enable debug printouts from passes
- which use the ``LLVM_DEBUG()`` macro. See the `LLVM Programmer's Manual
- <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information.
-
-.. option:: -load=<plugin>
-
- Load the dynamic object ``plugin``. This object should register new
- optimization or analysis passes. Once loaded, the object will add new command
- line options to enable various optimizations or analyses. To see the new
- complete list of optimizations, use the :option:`-help` and :option:`-load`
- options together. For example:
-
- .. code-block:: sh
-
- opt -load=plugin.so -help
-
-.. option:: -print-passes
-
- Print all available passes and exit.
-
-EXIT STATUS
------------
-
-If :program:`opt` succeeds, it will exit with 0. Otherwise, if an error
+{program}`opt` depend upon what libraries were linked into it as well as any
+additional libraries that have been loaded with the {option}`-load` option. Use
+the {option}`-help` option to determine what optimizations you can use.
+
+If `filename` is omitted from the command line or is "`-`", {program}`opt`
+reads its input from standard input. Inputs can be in either the LLVM assembly
+language format (`.ll`) or the LLVM bitcode format (`.bc`).
+
+If an output filename is not specified with the {option}`-o` option,
+{program}`opt` writes its output to the standard output.
+
+## OPTIONS
+
+:::{option} -f
+Enable binary output on terminals. Normally, {program}`opt` will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+{program}`opt` will write raw bitcode regardless of the output device.
+:::
+
+:::{option} -help
+Print a summary of command line options.
+:::
+
+:::{option} -o <filename>
+Specify the output filename.
+:::
+
+:::{option} -S
+Write output in LLVM intermediate language (instead of bitcode).
+:::
+
+:::{option} -passes=<string>
+A textual (comma-separated) description of the pass pipeline,
+e.g., `-passes="sroa,instcombine"`. See
+[invoking opt](../NewPassManager.html#invoking-opt) for more details on the
+pass pipeline syntax.
+:::
+
+:::{option} -mtriple=<target triple>
+Override the target triple specified in the input file with the specified
+string.
+:::
+
+:::{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 | opt -march=xyz -mtune=help
+```
+:::
+
+:::{option} -strip-debug
+This option causes opt to strip debug information from the module before
+applying other optimizations. It is essentially the same as `-strip`
+but it ensures that stripping of debug information is done first.
+:::
+
+:::{option} -verify-each
+This option causes opt to add a verify pass after every pass otherwise
+specified on the command line (including `-verify`). This is useful
+for cases where it is suspected that a pass is creating an invalid module but
+it is not clear which pass is doing it.
+:::
+
+:::{option} -stats
+Print statistics.
+:::
+
+:::{option} --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 it to standard
+error.
+:::
+
+:::{option} -debug
+If this is a debug build, this option will enable debug printouts from passes
+which use the `LLVM_DEBUG()` macro. See the [LLVM Programmer's Manual](../ProgrammersManual.html), section `#DEBUG` for more information.
+:::
+
+:::{option} -load=<plugin>
+Load the dynamic object `plugin`. This object should register new
+optimization or analysis passes. Once loaded, the object will add new command
+line options to enable various optimizations or analyses. To see the new
+complete list of optimizations, use the {option}`-help` and {option}`-load`
+options together. For example:
+
+```sh
+opt -load=plugin.so -help
+```
+:::
+
+:::{option} -print-passes
+Print all available passes and exit.
+:::
+
+## EXIT STATUS
+
+If {program}`opt` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
+
diff --git a/llvm/docs/CommandGuide/tblgen.md b/llvm/docs/CommandGuide/tblgen.md
index 92186579e682d..391b2034c628b 100644
--- a/llvm/docs/CommandGuide/tblgen.md
+++ b/llvm/docs/CommandGuide/tblgen.md
@@ -1,751 +1,740 @@
-tblgen - Description to C++ Code
-================================
+# tblgen - Description to C++ Code
+```{eval-rst}
.. program:: tblgen
+```
-SYNOPSIS
---------
+## SYNOPSIS
-:program:`clang-tblgen` [*options*] [*filename*]
+{program}`clang-tblgen` \[*options*\] \[*filename*\]
-:program:`lldb-tblgen` [*options*] [*filename*]
+{program}`lldb-tblgen` \[*options*\] \[*filename*\]
-:program:`llvm-tblgen` [*options*] [*filename*]
+{program}`llvm-tblgen` \[*options*\] \[*filename*\]
-:program:`mlir-tblgen` [*options*] [*filename*]
+{program}`mlir-tblgen` \[*options*\] \[*filename*\]
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`*-tblgen` is a family of programs that translates target
-description (``.td``) files into C++ code and other output formats. Most
+{program}`*-tblgen` is a family of programs that translates 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, debugger, and LLVM target backends.
-The details of the input and output of the :program:`*-tblgen` programs is
-beyond the scope of this short introduction; please see the :doc:`TableGen
+The details of the input and output of the {program}`*-tblgen` programs is
+beyond the scope of this short introduction; please see the {doc}`TableGen
Overview <../TableGen/index>` for an introduction and for references to
additional TableGen documents.
-The *filename* argument specifies the name of the Target Description (``.td``)
+The *filename* argument specifies the name of the Target Description (`.td`)
file that TableGen processes.
-OPTIONS
--------
+## OPTIONS
-General Options
-~~~~~~~~~~~~~~~
+### General Options
-.. option:: -help
+:::{option} -help
+Print a description of the command line options.
+:::
- Print a description of the command line options.
+:::{option} -help-list
+Print a description of the command line options in a simple list format.
+:::
-.. option:: -help-list
+:::{option} -D=macroname
+Specify the name of a macro to be defined. The name is defined, but it
+has no particular value.
+:::
- Print a description of the command line options in a simple list format.
+:::{option} -d=filename
+Specify the name of the dependency filename.
+:::
-.. option:: -D=macroname
+:::{option} -debug
+Enable debug output.
+:::
- Specify the name of a macro to be defined. The name is defined, but it
- has no particular value.
+:::{option} -dump-json
+Print a JSON representation of all records, suitable for further
+automated processing.
+:::
-.. option:: -d=filename
+:::{option} -I directory
+Specify where to find other target description files for inclusion. The
+`directory` value should be a full or partial path to a directory that
+contains target description files.
+:::
- Specify the name of the dependency filename.
+:::{option} -null-backend
+Parse the source files and build the records, but do not run any
+backend. This is useful for timing the frontend.
+:::
-.. option:: -debug
+:::{option} -o filename
+Specify the output file name. If `filename` is `-`, then
+{program}`*-tblgen` sends its output to standard output.
+:::
- Enable debug output.
+:::{option} -print-records
+Print all classes and records to standard output (default backend option).
+:::
-.. option:: -dump-json
+:::{option} -print-detailed-records
+Print a detailed report of all global variables, classes, and records
+to standard output.
+:::
- Print a JSON representation of all records, suitable for further
- automated processing.
+:::{option} -stats
+Print a report with any statistics collected by the backend.
+:::
-.. option:: -I directory
+:::{option} -time-phases
+Time the parser and backend phases and print a report.
+:::
- Specify where to find other target description files for inclusion. The
- ``directory`` value should be a full or partial path to a directory that
- contains target description files.
+:::{option} -version
+Show the version number of the program.
+:::
-.. option:: -null-backend
+:::{option} -write-if-changed
+Write the output file only if it is new or has changed.
+:::
- Parse the source files and build the records, but do not run any
- backend. This is useful for timing the frontend.
+### clang-tblgen Options
-.. option:: -o filename
+:::{option} -gen-clang-attr-classes
+Generate Clang attribute classes.
+:::
- Specify the output file name. If ``filename`` is ``-``, then
- :program:`*-tblgen` sends its output to standard output.
+:::{option} -gen-clang-attr-parser-string-switches
+Generate all parser-related attribute string switches.
+:::
-.. option:: -print-records
+:::{option} -gen-clang-attr-subject-match-rules-parser-string-switches
+Generate all parser-related attribute subject match rule string switches.
+:::
- Print all classes and records to standard output (default backend option).
+:::{option} -gen-clang-attr-impl
+Generate Clang attribute implementations.
+:::
-.. option:: -print-detailed-records
+:::{option} -gen-clang-attr-list"
+Generate a Clang attribute list.
+:::
- Print a detailed report of all global variables, classes, and records
- to standard output.
+:::{option} -gen-clang-attr-subject-match-rule-list
+Generate a Clang attribute subject match rule list.
+:::
-.. option:: -stats
+:::{option} -gen-clang-attr-pch-read
+Generate Clang PCH attribute reader.
+:::
+
+:::{option} -gen-clang-attr-pch-write
+Generate Clang PCH attribute writer.
+:::
+
+:::{option} -gen-clang-attr-has-attribute-impl
+Generate a Clang attribute spelling list.
+:::
+
+:::{option} -gen-clang-attr-spelling-index
+Generate a Clang attribute spelling index.
+:::
+
+:::{option} -gen-clang-attr-ast-visitor
+Generate a recursive AST visitor for Clang attributes.
+:::
+
+:::{option} -gen-clang-attr-template-instantiate
+Generate a Clang template instantiate code.
+:::
+
+:::{option} -gen-clang-attr-parsed-attr-list
+Generate a Clang parsed attribute list.
+:::
+
+:::{option} -gen-clang-attr-parsed-attr-impl
+Generate the Clang parsed attribute helpers.
+:::
+
+:::{option} -gen-clang-attr-parsed-attr-kinds
+Generate a Clang parsed attribute kinds.
+:::
+
+:::{option} -gen-clang-attr-text-node-dump
+Generate Clang attribute text node dumper.
+:::
+
+:::{option} -gen-clang-attr-node-traverse
+Generate Clang attribute traverser.
+:::
- Print a report with any statistics collected by the backend.
+:::{option} -gen-clang-diags-defs
+Generate Clang diagnostics definitions.
+:::
-.. option:: -time-phases
+:::{option} -clang-component component
+Only use warnings from specified component.
+:::
- Time the parser and backend phases and print a report.
+:::{option} -gen-clang-diag-groups
+Generate Clang diagnostic groups.
+:::
-.. option:: -version
+:::{option} -gen-clang-diags-index-name
+Generate Clang diagnostic name index.
+:::
- Show the version number of the program.
+:::{option} -gen-clang-basic-reader
+Generate Clang BasicReader classes.
+:::
-.. option:: -write-if-changed
+:::{option} -gen-clang-basic-writer
+Generate Clang BasicWriter classes.
+:::
- Write the output file only if it is new or has changed.
+:::{option} -gen-clang-comment-nodes
+Generate Clang AST comment nodes.
+:::
+:::{option} -gen-clang-decl-nodes
+Generate Clang AST declaration nodes.
+:::
-clang-tblgen Options
-~~~~~~~~~~~~~~~~~~~~
+:::{option} -gen-clang-stmt-nodes
+Generate Clang AST statement nodes.
+:::
-.. option:: -gen-clang-attr-classes
+:::{option} -gen-clang-type-nodes
+Generate Clang AST type nodes.
+:::
- Generate Clang attribute classes.
+:::{option} -gen-clang-type-reader
+Generate Clang AbstractTypeReader class.
+:::
-.. option:: -gen-clang-attr-parser-string-switches
+:::{option} -gen-clang-type-writer
+Generate Clang AbstractTypeWriter class.
+:::
- Generate all parser-related attribute string switches.
+:::{option} -gen-clang-opcodes
+Generate Clang constexpr interpreter opcodes.
+:::
-.. option:: -gen-clang-attr-subject-match-rules-parser-string-switches
+:::{option} -gen-clang-sa-checkers
+Generate Clang static analyzer checkers.
+:::
- Generate all parser-related attribute subject match rule string switches.
+:::{option} -gen-clang-comment-html-tags
+Generate efficient matchers for HTML tag names that are used in
+documentation comments.
+:::
-.. option:: -gen-clang-attr-impl
+:::{option} -gen-clang-comment-html-tags-properties
+Generate efficient matchers for HTML tag properties.
+:::
- Generate Clang attribute implementations.
+:::{option} -gen-clang-comment-html-named-character-references
+Generate function to translate named character references to UTF-8 sequences.
+:::
-.. option:: -gen-clang-attr-list"
+:::{option} -gen-clang-comment-command-info
+Generate command properties for commands that are used in documentation comments.
+:::
- Generate a Clang attribute list.
+:::{option} -gen-clang-comment-command-list
+Generate list of commands that are used in documentation comments.
+:::
-.. option:: -gen-clang-attr-subject-match-rule-list
+:::{option} -gen-clang-opencl-builtins
+Generate OpenCL builtin declaration handlers.
+:::
- Generate a Clang attribute subject match rule list.
+:::{option} -gen-arm-neon
+Generate `arm_neon.h` for Clang.
+:::
-.. option:: -gen-clang-attr-pch-read
+:::{option} -gen-arm-fp16
+Generate `arm_fp16.h` for Clang.
+:::
- Generate Clang PCH attribute reader.
+:::{option} -gen-arm-bf16
+Generate `arm_bf16.h` for Clang.
+:::
-.. option:: -gen-clang-attr-pch-write
+:::{option} -gen-arm-neon-sema
+Generate ARM NEON sema support for Clang.
+:::
- Generate Clang PCH attribute writer.
+:::{option} -gen-arm-neon-test
+Generate ARM NEON tests for Clang.
+:::
-.. option:: -gen-clang-attr-has-attribute-impl
+:::{option} -gen-arm-immcheck-types
+Generate `arm_immcheck_types.inc` for Clang.
+:::
+
+:::{option} -gen-arm-sve-header
+Generate `arm_sve.h` for Clang.
+:::
- Generate a Clang attribute spelling list.
+:::{option} -gen-arm-sve-builtins
+Generate `arm_sve_builtins.inc` for Clang.
+:::
-.. option:: -gen-clang-attr-spelling-index
+:::{option} -gen-arm-sve-builtin-codegen
+Generate `arm_sve_builtin_cg_map.inc` for Clang.
+:::
- Generate a Clang attribute spelling index.
+:::{option} -gen-arm-sve-typeflags
+Generate `arm_sve_typeflags.inc` for Clang.
+:::
-.. option:: -gen-clang-attr-ast-visitor
+:::{option} -gen-arm-sve-sema-rangechecks
+Generate `arm_sve_sema_rangechecks.inc` for Clang.
+:::
- Generate a recursive AST visitor for Clang attributes.
+:::{option} -gen-arm-mve-header
+Generate `arm_mve.h` for Clang.
+:::
-.. option:: -gen-clang-attr-template-instantiate
+:::{option} -gen-arm-mve-builtin-def
+Generate ARM MVE builtin definitions for Clang.
+:::
- Generate a Clang template instantiate code.
+:::{option} -gen-arm-mve-builtin-sema
+Generate ARM MVE builtin sema checks for Clang.
+:::
-.. option:: -gen-clang-attr-parsed-attr-list
+:::{option} -gen-arm-mve-builtin-codegen
+Generate ARM MVE builtin code-generator for Clang.
+:::
- Generate a Clang parsed attribute list.
+:::{option} -gen-arm-mve-builtin-aliases
+Generate list of valid ARM MVE builtin aliases for Clang.
+:::
-.. option:: -gen-clang-attr-parsed-attr-impl
+:::{option} -gen-arm-cde-header
+Generate `arm_cde.h` for Clang.
+:::
- Generate the Clang parsed attribute helpers.
+:::{option} -gen-arm-cde-builtin-def
+Generate ARM CDE builtin definitions for Clang.
+:::
-.. option:: -gen-clang-attr-parsed-attr-kinds
+:::{option} -gen-arm-cde-builtin-sema
+Generate ARM CDE builtin sema checks for Clang.
+:::
- Generate a Clang parsed attribute kinds.
+:::{option} -gen-arm-cde-builtin-codegen
+Generate ARM CDE builtin code-generator for Clang.
+:::
-.. option:: -gen-clang-attr-text-node-dump
+:::{option} -gen-arm-cde-builtin-aliases
+Generate list of valid ARM CDE builtin aliases for Clang.
+:::
- Generate Clang attribute text node dumper.
+:::{option} -gen-riscv-vector-header
+Generate `riscv_vector.h` for Clang.
+:::
-.. option:: -gen-clang-attr-node-traverse
+:::{option} -gen-riscv-vector-builtins
+Generate `riscv_vector_builtins.inc` for Clang.
+:::
- Generate Clang attribute traverser.
+:::{option} -gen-riscv-vector-builtin-codegen
+Generate `riscv_vector_builtin_cg.inc` for Clang.
+:::
-.. option:: -gen-clang-diags-defs
+:::{option} -gen-riscv-sifive-vector-builtins
+Generate `riscv_sifive_vector_builtins.inc` for Clang.
+:::
- Generate Clang diagnostics definitions.
+:::{option} -gen-riscv-sifive-vector-builtin-codegen
+Generate `riscv_sifive_vector_builtin_cg.inc` for Clang.
+:::
-.. option:: -clang-component component
+:::{option} -gen-attr-docs
+Generate attribute documentation.
+:::
- Only use warnings from specified component.
+:::{option} -gen-diag-docs
+Generate diagnostic documentation.
+:::
-.. option:: -gen-clang-diag-groups
+:::{option} -gen-opt-docs
+Generate option documentation.
+:::
- Generate Clang diagnostic groups.
+:::{option} -gen-clang-data-collectors
+Generate data collectors for AST nodes.
+:::
-.. option:: -gen-clang-diags-index-name
+:::{option} -gen-clang-test-pragma-attribute-supported-attributes
+Generate a list of attributes supported by `#pragma` Clang attribute for
+testing purposes.
+:::
- Generate Clang diagnostic name index.
+### lldb-tblgen Options
-.. option:: -gen-clang-basic-reader
+:::{option} gen-lldb-option-defs
+Generate lldb OptionDefinition values.
+:::
- Generate Clang BasicReader classes.
+:::{option} gen-lldb-property-defs
+Generate lldb PropertyDefinition values.
+:::
-.. option:: -gen-clang-basic-writer
+:::{option} gen-lldb-property-enum-defs
+Generate lldb PropertyDefinition enum values.
+:::
- Generate Clang BasicWriter classes.
+### llvm-tblgen Options
-.. option:: -gen-clang-comment-nodes
+:::{option} -gen-asm-matcher
+Generate assembly instruction matcher.
+:::
- Generate Clang AST comment nodes.
+:::{option} -match-prefix=prefix
+Make -gen-asm-matcher match only instructions with the given *prefix*.
+:::
-.. option:: -gen-clang-decl-nodes
+:::{option} -gen-asm-parser
+Generate assembly instruction parser.
+:::
- Generate Clang AST declaration nodes.
+:::{option} -asmparsernum=n
+Make -gen-asm-parser emit assembly parser number *n*.
+:::
-.. option:: -gen-clang-stmt-nodes
+:::{option} -gen-asm-writer
+Generate assembly writer.
+:::
- Generate Clang AST statement nodes.
+:::{option} -asmwriternum=n
+Make -gen-asm-writer emit assembly writer number *n*.
+:::
-.. option:: -gen-clang-type-nodes
+:::{option} -gen-attrs
+Generate attributes.
+:::
- Generate Clang AST type nodes.
+:::{option} -gen-automata
+Generate generic automata.
+:::
-.. option:: -gen-clang-type-reader
+:::{option} -gen-callingconv
+Generate calling convention descriptions.
+:::
- Generate Clang AbstractTypeReader class.
+:::{option} -gen-compress-inst-emitter
+Generate RISC-V compressed instructions.
+:::
-.. option:: -gen-clang-type-writer
+:::{option} -gen-ctags
+Generate ctags-compatible index.
+:::
- Generate Clang AbstractTypeWriter class.
+:::{option} -gen-dag-isel
+Generate a DAG (directed acyclic graph) instruction selector.
+:::
-.. option:: -gen-clang-opcodes
+:::{option} -instrument-coverage
+Make -gen-dag-isel generate tables to help identify the patterns matched.
+:::
- Generate Clang constexpr interpreter opcodes.
+:::{option} -omit-comments
+Make -gen-dag-isel omit comments. The default is false.
+:::
-.. option:: -gen-clang-sa-checkers
+:::{option} -gen-dfa-packetizer
+Generate DFA Packetizer for VLIW targets.
+:::
- Generate Clang static analyzer checkers.
+:::{option} -gen-directive-decl
+Generate directive related declaration code (header file).
+:::
-.. option:: -gen-clang-comment-html-tags
+:::{option} -gen-directive-gen
+Generate directive related implementation code part.
+:::
- Generate efficient matchers for HTML tag names that are used in
- documentation comments.
+:::{option} -gen-directive-impl
+Generate directive related implementation code.
+:::
-.. option:: -gen-clang-comment-html-tags-properties
+:::{option} -gen-disassembler
+Generate disassembler.
+:::
- Generate efficient matchers for HTML tag properties.
+:::{option} -gen-emitter
+Generate machine code emitter.
+:::
-.. option:: -gen-clang-comment-html-named-character-references
+:::{option} -gen-exegesis
+Generate llvm-exegesis tables.
+:::
- Generate function to translate named character references to UTF-8 sequences.
+:::{option} -gen-fast-isel
+Generate a "fast" instruction selector.
+:::
-.. option:: -gen-clang-comment-command-info
+:::{option} -gen-global-isel
+Generate GlobalISel selector.
+:::
- Generate command properties for commands that are used in documentation comments.
+:::{option} -gisel-coverage-file=filename
+Specify the file from which to retrieve coverage information.
+:::
-.. option:: -gen-clang-comment-command-list
+:::{option} -instrument-gisel-coverage
+Make -gen-global-isel generate coverage instrumentation.
+:::
- Generate list of commands that are used in documentation comments.
+:::{option} -optimize-match-table
+Make -gen-global-isel generate an optimized version of the match table.
+:::
-.. option:: -gen-clang-opencl-builtins
+:::{option} -warn-on-skipped-patterns
+Make -gen-global-isel explain why a pattern was skipped for inclusion.
+:::
- Generate OpenCL builtin declaration handlers.
+:::{option} -gen-global-isel-combiner
+Generate GlobalISel combiner.
+:::
-.. option:: -gen-arm-neon
+:::{option} -combiners=list
+Make -gen-global-isel-combiner emit the specified combiners.
+:::
- Generate ``arm_neon.h`` for Clang.
+:::{option} -gicombiner-debug-cxxpreds
+Add debug comments to all C++ predicates emitted by -gen-global-isel-combiner
+:::
-.. option:: -gen-arm-fp16
+:::{option} -gicombiner-stop-after-parse
+Make -gen-global-isel-combiner stop processing after parsing rules and dump state.
+:::
- Generate ``arm_fp16.h`` for Clang.
+:::{option} -gen-instr-info
+Generate instruction descriptions.
+:::
-.. option:: -gen-arm-bf16
+:::{option} -gen-instr-docs
+Generate instruction documentation.
+:::
- Generate ``arm_bf16.h`` for Clang.
+:::{option} -gen-intrinsic-enums
+Generate intrinsic enums.
+:::
-.. option:: -gen-arm-neon-sema
+:::{option} -intrinsic-prefix=prefix
+Make -gen-intrinsic-enums generate intrinsics with this target *prefix*.
+:::
- Generate ARM NEON sema support for Clang.
+:::{option} -gen-intrinsic-impl
+Generate intrinsic information.
+:::
-.. option:: -gen-arm-neon-test
+:::{option} -gen-opt-parser-defs
+Generate options definitions.
+:::
- Generate ARM NEON tests for Clang.
+:::{option} -gen-opt-rst
+Generate option RST.
+:::
-.. option:: -gen-arm-immcheck-types
+:::{option} -gen-pseudo-lowering
+Generate pseudo instruction lowering.
+:::
- Generate ``arm_immcheck_types.inc`` for Clang.
+:::{option} -gen-register-bank
+Generate register bank descriptions.
+:::
-.. option:: -gen-arm-sve-header
+:::{option} -gen-register-info
+Generate registers and register classes info.
+:::
- Generate ``arm_sve.h`` for Clang.
+:::{option} -register-info-debug
+Make -gen-register-info dump register information for debugging.
+:::
-.. option:: -gen-arm-sve-builtins
+:::{option} -gen-searchable-tables
+Generate generic searchable tables. See {doc}`TableGen BackEnds <../TableGen/BackEnds>`
+for a detailed description.
+:::
- Generate ``arm_sve_builtins.inc`` for Clang.
+:::{option} -gen-subtarget
+Generate subtarget enumerations.
+:::
-.. option:: -gen-arm-sve-builtin-codegen
+:::{option} -gen-x86-EVEX2VEX-tables
+Generate X86 EVEX to VEX compress tables.
+:::
- Generate ``arm_sve_builtin_cg_map.inc`` for Clang.
+:::{option} -gen-x86-fold-tables
+Generate X86 fold tables.
+:::
-.. option:: -gen-arm-sve-typeflags
+:::{option} -long-string-literals
+When emitting large string tables, prefer string literals over
+comma-separated char literals. This can be a readability and
+compile-time performance win, but upsets some compilers.
+:::
- Generate ``arm_sve_typeflags.inc`` for Clang.
+:::{option} -print-enums
+Print enumeration values for a class.
+:::
-.. option:: -gen-arm-sve-sema-rangechecks
+:::{option} -class=classname
+Make -print-enums print the enumeration list for the specified class.
+:::
- Generate ``arm_sve_sema_rangechecks.inc`` for Clang.
+:::{option} -print-sets
+Print expanded sets for testing DAG exprs.
+:::
-.. option:: -gen-arm-mve-header
+### mlir-tblgen Options
- Generate ``arm_mve.h`` for Clang.
+:::{option} -gen-avail-interface-decls
+Generate availability interface declarations.
+:::
-.. option:: -gen-arm-mve-builtin-def
+:::{option} -gen-avail-interface-defs
+Generate op interface definitions.
+:::
- Generate ARM MVE builtin definitions for Clang.
+:::{option} -gen-dialect-doc
+Generate dialect documentation.
+:::
-.. option:: -gen-arm-mve-builtin-sema
+:::{option} -dialect
+The dialect to generate.
+:::
- Generate ARM MVE builtin sema checks for Clang.
+:::{option} -gen-directive-decl
+Generate declarations for directives (OpenMP, etc.).
+:::
-.. option:: -gen-arm-mve-builtin-codegen
+:::{option} -gen-enum-decls
+Generate enum utility declarations.
+:::
- Generate ARM MVE builtin code-generator for Clang.
+:::{option} -gen-enum-defs
+Generate enum utility definitions.
+:::
-.. option:: -gen-arm-mve-builtin-aliases
+:::{option} -gen-enum-from-llvmir-conversions
+Generate conversions of EnumAttrs from LLVM IR.
+:::
- Generate list of valid ARM MVE builtin aliases for Clang.
+:::{option} -gen-enum-to-llvmir-conversions
+Generate conversions of EnumAttrs to LLVM IR.
+:::
-.. option:: -gen-arm-cde-header
+:::{option} -gen-llvmir-conversions
+Generate LLVM IR conversions.
+:::
- Generate ``arm_cde.h`` for Clang.
+:::{option} -gen-llvmir-intrinsics
+Generate LLVM IR intrinsics.
+:::
-.. option:: -gen-arm-cde-builtin-def
+:::{option} -llvmir-intrinsics-filter
+Only keep the intrinsics with the specified substring in their record name.
+:::
- Generate ARM CDE builtin definitions for Clang.
+:::{option} -dialect-opclass-base
+The base class for the ops in the dialect we are to emit.
+:::
-.. option:: -gen-arm-cde-builtin-sema
+:::{option} -gen-op-decls
+Generate operation declarations.
+:::
- Generate ARM CDE builtin sema checks for Clang.
+:::{option} -gen-op-defs
+Generate operation definitions.
+:::
-.. option:: -gen-arm-cde-builtin-codegen
+:::{option} -asmformat-error-is-fatal
+Emit a fatal error if format parsing fails.
+:::
- Generate ARM CDE builtin code-generator for Clang.
+:::{option} -op-exclude-regex
+Regular expression of name of ops to exclude (no filter if empty).
+:::
-.. option:: -gen-arm-cde-builtin-aliases
+:::{option} -op-include-regex
+Regular expression of name of ops to include (no filter if empty).
+:::
- Generate list of valid ARM CDE builtin aliases for Clang.
+:::{option} -gen-op-doc
+Generate operation documentation.
+:::
-.. option:: -gen-riscv-vector-header
+:::{option} -gen-pass-decls
+Generate operation documentation.
+:::
- Generate ``riscv_vector.h`` for Clang.
+:::{option} -name namestring
+The name of this group of passes.
+:::
-.. option:: -gen-riscv-vector-builtins
+:::{option} -gen-pass-doc
+Generate pass documentation.
+:::
- Generate ``riscv_vector_builtins.inc`` for Clang.
+:::{option} -gen-rewriters
+Generate pattern rewriters.
+:::
-.. option:: -gen-riscv-vector-builtin-codegen
+:::{option} -gen-spirv-avail-impls
+Generate SPIR-V operation utility definitions.
+:::
- Generate ``riscv_vector_builtin_cg.inc`` for Clang.
+:::{option} -gen-spirv-capability-implication
+Generate utility function to return implied capabilities for a given capability.
+:::
-.. option:: -gen-riscv-sifive-vector-builtins
+:::{option} -gen-spirv-enum-avail-decls
+Generate SPIR-V enum availability declarations.
+:::
- Generate ``riscv_sifive_vector_builtins.inc`` for Clang.
+:::{option} -gen-spirv-enum-avail-defs
+Generate SPIR-V enum availability definitions.
+:::
-.. option:: -gen-riscv-sifive-vector-builtin-codegen
+:::{option} -gen-spirv-op-utils
+Generate SPIR-V operation utility definitions.
+:::
- Generate ``riscv_sifive_vector_builtin_cg.inc`` for Clang.
+:::{option} -gen-spirv-serialization
+Generate SPIR-V (de)serialization utilities and functions.
+:::
-.. option:: -gen-attr-docs
+:::{option} -gen-struct-attr-decls
+Generate struct utility declarations.
+:::
- Generate attribute documentation.
+:::{option} -gen-struct-attr-defs
+Generate struct utility definitions.
+:::
-.. option:: -gen-diag-docs
+:::{option} -gen-typedef-decls
+Generate TypeDef declarations.
+:::
- Generate diagnostic documentation.
+:::{option} -gen-typedef-defs
+Generate TypeDef definitions.
+:::
-.. option:: -gen-opt-docs
+:::{option} -typedefs-dialect name
+Generate types for this dialect.
+:::
- Generate option documentation.
+## EXIT STATUS
-.. option:: -gen-clang-data-collectors
-
- Generate data collectors for AST nodes.
-
-.. option:: -gen-clang-test-pragma-attribute-supported-attributes
-
- Generate a list of attributes supported by ``#pragma`` Clang attribute for
- testing purposes.
-
-
-lldb-tblgen Options
-~~~~~~~~~~~~~~~~~~~
-
-.. option:: gen-lldb-option-defs
-
- Generate lldb OptionDefinition values.
-
-.. option:: gen-lldb-property-defs
-
- Generate lldb PropertyDefinition values.
-
-.. option:: gen-lldb-property-enum-defs
-
- Generate lldb PropertyDefinition enum values.
-
-
-llvm-tblgen Options
-~~~~~~~~~~~~~~~~~~~
-
-.. option:: -gen-asm-matcher
-
- Generate assembly instruction matcher.
-
-.. option:: -match-prefix=prefix
-
- Make -gen-asm-matcher match only instructions with the given *prefix*.
-
-.. option:: -gen-asm-parser
-
- Generate assembly instruction parser.
-
-.. option:: -asmparsernum=n
-
- Make -gen-asm-parser emit assembly parser number *n*.
-
-.. option:: -gen-asm-writer
-
- Generate assembly writer.
-
-.. option:: -asmwriternum=n
-
- Make -gen-asm-writer emit assembly writer number *n*.
-
-.. option:: -gen-attrs
-
- Generate attributes.
-
-.. option:: -gen-automata
-
- Generate generic automata.
-
-.. option:: -gen-callingconv
-
- Generate calling convention descriptions.
-
-.. option:: -gen-compress-inst-emitter
-
- Generate RISC-V compressed instructions.
-
-.. option:: -gen-ctags
-
- Generate ctags-compatible index.
-
-.. option:: -gen-dag-isel
-
- Generate a DAG (directed acyclic graph) instruction selector.
-
-.. option:: -instrument-coverage
-
- Make -gen-dag-isel generate tables to help identify the patterns matched.
-
-.. option:: -omit-comments
-
- Make -gen-dag-isel omit comments. The default is false.
-
-.. option:: -gen-dfa-packetizer
-
- Generate DFA Packetizer for VLIW targets.
-
-.. option:: -gen-directive-decl
-
- Generate directive related declaration code (header file).
-
-.. option:: -gen-directive-gen
-
- Generate directive related implementation code part.
-
-.. option:: -gen-directive-impl
-
- Generate directive related implementation code.
-
-.. option:: -gen-disassembler
-
- Generate disassembler.
-
-.. option:: -gen-emitter
-
- Generate machine code emitter.
-
-.. option:: -gen-exegesis
-
- Generate llvm-exegesis tables.
-
-.. option:: -gen-fast-isel
-
- Generate a "fast" instruction selector.
-
-.. option:: -gen-global-isel
-
- Generate GlobalISel selector.
-
-.. option:: -gisel-coverage-file=filename
-
- Specify the file from which to retrieve coverage information.
-
-.. option:: -instrument-gisel-coverage
-
- Make -gen-global-isel generate coverage instrumentation.
-
-.. option:: -optimize-match-table
-
- Make -gen-global-isel generate an optimized version of the match table.
-
-.. option:: -warn-on-skipped-patterns
-
- Make -gen-global-isel explain why a pattern was skipped for inclusion.
-
-.. option:: -gen-global-isel-combiner
-
- Generate GlobalISel combiner.
-
-.. option:: -combiners=list
-
- Make -gen-global-isel-combiner emit the specified combiners.
-
-.. option:: -gicombiner-debug-cxxpreds
-
- Add debug comments to all C++ predicates emitted by -gen-global-isel-combiner
-
-.. option:: -gicombiner-stop-after-parse
-
- Make -gen-global-isel-combiner stop processing after parsing rules and dump state.
-
-.. option:: -gen-instr-info
-
- Generate instruction descriptions.
-
-.. option:: -gen-instr-docs
-
- Generate instruction documentation.
-
-.. option:: -gen-intrinsic-enums
-
- Generate intrinsic enums.
-
-.. option:: -intrinsic-prefix=prefix
-
- Make -gen-intrinsic-enums generate intrinsics with this target *prefix*.
-
-.. option:: -gen-intrinsic-impl
-
- Generate intrinsic information.
-
-.. option:: -gen-opt-parser-defs
-
- Generate options definitions.
-
-.. option:: -gen-opt-rst
-
- Generate option RST.
-
-.. option:: -gen-pseudo-lowering
-
- Generate pseudo instruction lowering.
-
-.. option:: -gen-register-bank
-
- Generate register bank descriptions.
-
-.. option:: -gen-register-info
-
- Generate registers and register classes info.
-
-.. option:: -register-info-debug
-
- Make -gen-register-info dump register information for debugging.
-
-.. option:: -gen-searchable-tables
-
- Generate generic searchable tables. See :doc:`TableGen BackEnds <../TableGen/BackEnds>`
- for a detailed description.
-
-.. option:: -gen-subtarget
-
- Generate subtarget enumerations.
-
-.. option:: -gen-x86-EVEX2VEX-tables
-
- Generate X86 EVEX to VEX compress tables.
-
-.. option:: -gen-x86-fold-tables
-
- Generate X86 fold tables.
-
-.. option:: -long-string-literals
-
- When emitting large string tables, prefer string literals over
- comma-separated char literals. This can be a readability and
- compile-time performance win, but upsets some compilers.
-
-.. option:: -print-enums
-
- Print enumeration values for a class.
-
-.. option:: -class=classname
-
- Make -print-enums print the enumeration list for the specified class.
-
-.. option:: -print-sets
-
- Print expanded sets for testing DAG exprs.
-
-
-mlir-tblgen Options
-~~~~~~~~~~~~~~~~~~~
-
-.. option:: -gen-avail-interface-decls
-
- Generate availability interface declarations.
-
-.. option:: -gen-avail-interface-defs
-
- Generate op interface definitions.
-
-.. option:: -gen-dialect-doc
-
- Generate dialect documentation.
-
-.. option:: -dialect
-
- The dialect to generate.
-
-.. option:: -gen-directive-decl
-
- Generate declarations for directives (OpenMP, etc.).
-
-.. option:: -gen-enum-decls
-
- Generate enum utility declarations.
-
-.. option:: -gen-enum-defs
-
- Generate enum utility definitions.
-
-.. option:: -gen-enum-from-llvmir-conversions
-
- Generate conversions of EnumAttrs from LLVM IR.
-
-.. option:: -gen-enum-to-llvmir-conversions
-
- Generate conversions of EnumAttrs to LLVM IR.
-
-.. option:: -gen-llvmir-conversions
-
- Generate LLVM IR conversions.
-
-.. option:: -gen-llvmir-intrinsics
-
- Generate LLVM IR intrinsics.
-
-.. option:: -llvmir-intrinsics-filter
-
- Only keep the intrinsics with the specified substring in their record name.
-
-.. option:: -dialect-opclass-base
-
- The base class for the ops in the dialect we are to emit.
-
-.. option:: -gen-op-decls
-
- Generate operation declarations.
-
-.. option:: -gen-op-defs
-
- Generate operation definitions.
-
-.. option:: -asmformat-error-is-fatal
-
- Emit a fatal error if format parsing fails.
-
-.. option:: -op-exclude-regex
-
- Regular expression of name of ops to exclude (no filter if empty).
-
-.. option:: -op-include-regex
-
- Regular expression of name of ops to include (no filter if empty).
-
-.. option:: -gen-op-doc
-
- Generate operation documentation.
-
-.. option:: -gen-pass-decls
-
- Generate operation documentation.
-
-.. option:: -name namestring
-
- The name of this group of passes.
-
-.. option:: -gen-pass-doc
-
- Generate pass documentation.
-
-.. option:: -gen-rewriters
-
- Generate pattern rewriters.
-
-.. option:: -gen-spirv-avail-impls
-
- Generate SPIR-V operation utility definitions.
-
-.. option:: -gen-spirv-capability-implication
-
- Generate utility function to return implied capabilities for a given capability.
-
-.. option:: -gen-spirv-enum-avail-decls
-
- Generate SPIR-V enum availability declarations.
-
-.. option:: -gen-spirv-enum-avail-defs
-
- Generate SPIR-V enum availability definitions.
-
-.. option:: -gen-spirv-op-utils
-
- Generate SPIR-V operation utility definitions.
-
-.. option:: -gen-spirv-serialization
-
- Generate SPIR-V (de)serialization utilities and functions.
-
-.. option:: -gen-struct-attr-decls
-
- Generate struct utility declarations.
-
-.. option:: -gen-struct-attr-defs
-
- Generate struct utility definitions.
-
-.. option:: -gen-typedef-decls
-
- Generate TypeDef declarations.
-
-.. option:: -gen-typedef-defs
-
- Generate TypeDef definitions.
-
-.. option:: -typedefs-dialect name
-
- Generate types for this dialect.
-
-EXIT STATUS
------------
-
-If :program:`*-tblgen` succeeds, it will exit with 0. Otherwise, if an error
+If {program}`*-tblgen` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
+
>From efc1b658c927576e88fa3c3c26496462e6ce02d3 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Mon, 31 Aug 2026 18:53:21 +0000
Subject: [PATCH 2/2] [docs] Finish MyST migration for remaining CommandGuide
docs
---
llvm/docs/CommandGuide/llvm-libtool-darwin.md | 5 +-
llvm/docs/CommandGuide/llvm-link.md | 5 +-
llvm/docs/CommandGuide/llvm-lipo.md | 5 +-
llvm/docs/CommandGuide/llvm-locstats.md | 5 +-
llvm/docs/CommandGuide/llvm-mc.md | 5 +-
llvm/docs/CommandGuide/llvm-mca.md | 5 +-
llvm/docs/CommandGuide/llvm-nm.md | 153 ++++++++---------
llvm/docs/CommandGuide/llvm-objcopy.md | 5 +-
llvm/docs/CommandGuide/llvm-objdump.md | 20 +--
llvm/docs/CommandGuide/llvm-offload-binary.md | 156 +++++++-----------
llvm/docs/CommandGuide/llvm-opt-report.md | 5 +-
llvm/docs/CommandGuide/llvm-otool.md | 5 +-
llvm/docs/CommandGuide/llvm-pdbutil.md | 75 ++++-----
llvm/docs/CommandGuide/llvm-profdata.md | 25 ++-
llvm/docs/CommandGuide/llvm-profgen.md | 5 +-
llvm/docs/CommandGuide/llvm-ranlib.md | 5 +-
llvm/docs/CommandGuide/llvm-readelf.md | 5 +-
llvm/docs/CommandGuide/llvm-readobj.md | 5 +-
llvm/docs/CommandGuide/llvm-reduce.md | 5 +-
llvm/docs/CommandGuide/llvm-remarkutil.md | 45 +++--
llvm/docs/CommandGuide/llvm-size.md | 5 +-
llvm/docs/CommandGuide/llvm-stress.md | 5 +-
llvm/docs/CommandGuide/llvm-strings.md | 5 +-
llvm/docs/CommandGuide/llvm-strip.md | 5 +-
llvm/docs/CommandGuide/llvm-symbolizer.md | 5 +-
llvm/docs/CommandGuide/llvm-tblgen.md | 5 +-
.../CommandGuide/llvm-test-mustache-spec.md | 8 +-
llvm/docs/CommandGuide/llvm-tli-checker.md | 5 +-
llvm/docs/CommandGuide/mlir-tblgen.md | 5 +-
llvm/docs/CommandGuide/opt.md | 12 +-
llvm/docs/CommandGuide/tblgen.md | 5 +-
llvm/docs/ProgrammersManual.md | 2 +-
32 files changed, 262 insertions(+), 349 deletions(-)
diff --git a/llvm/docs/CommandGuide/llvm-libtool-darwin.md b/llvm/docs/CommandGuide/llvm-libtool-darwin.md
index b07e42a4b701c..72c0280802c29 100644
--- a/llvm/docs/CommandGuide/llvm-libtool-darwin.md
+++ b/llvm/docs/CommandGuide/llvm-libtool-darwin.md
@@ -1,8 +1,7 @@
# llvm-libtool-darwin - LLVM tool for creating libraries for Darwin
-```{eval-rst}
-.. program:: llvm-libtool-darwin
-```
+:::{program} llvm-libtool-darwin
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-link.md b/llvm/docs/CommandGuide/llvm-link.md
index 1e677644a5d8f..dd6978d3bce71 100644
--- a/llvm/docs/CommandGuide/llvm-link.md
+++ b/llvm/docs/CommandGuide/llvm-link.md
@@ -1,8 +1,7 @@
# llvm-link - LLVM bitcode linker
-```{eval-rst}
-.. program:: llvm-link
-```
+:::{program} llvm-link
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-lipo.md b/llvm/docs/CommandGuide/llvm-lipo.md
index 0ec837fa9b771..8a24be4b3cfab 100644
--- a/llvm/docs/CommandGuide/llvm-lipo.md
+++ b/llvm/docs/CommandGuide/llvm-lipo.md
@@ -1,8 +1,7 @@
# llvm-lipo - LLVM tool for manipulating universal binaries
-```{eval-rst}
-.. program:: llvm-lipo
-```
+:::{program} llvm-lipo
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-locstats.md b/llvm/docs/CommandGuide/llvm-locstats.md
index ca3ffa6d41308..b4cae4a676c4b 100644
--- a/llvm/docs/CommandGuide/llvm-locstats.md
+++ b/llvm/docs/CommandGuide/llvm-locstats.md
@@ -1,8 +1,7 @@
# llvm-locstats - calculate statistics on DWARF debug location
-```{eval-rst}
-.. program:: llvm-locstats
-```
+:::{program} llvm-locstats
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-mc.md b/llvm/docs/CommandGuide/llvm-mc.md
index 91c0cdac68c6d..4fdde854cdecc 100644
--- a/llvm/docs/CommandGuide/llvm-mc.md
+++ b/llvm/docs/CommandGuide/llvm-mc.md
@@ -1,8 +1,7 @@
# llvm-mc - LLVM Machine Code Playground
-```{eval-rst}
-.. program:: llvm-mc
-```
+:::{program} llvm-mc
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-mca.md b/llvm/docs/CommandGuide/llvm-mca.md
index 8adf41fa6ef94..43cead1afddcd 100644
--- a/llvm/docs/CommandGuide/llvm-mca.md
+++ b/llvm/docs/CommandGuide/llvm-mca.md
@@ -1,8 +1,7 @@
# llvm-mca - LLVM Machine Code Analyzer
-```{eval-rst}
-.. program:: llvm-mca
-```
+:::{program} llvm-mca
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-nm.md b/llvm/docs/CommandGuide/llvm-nm.md
index 80cb0df193162..fae264c6f7729 100644
--- a/llvm/docs/CommandGuide/llvm-nm.md
+++ b/llvm/docs/CommandGuide/llvm-nm.md
@@ -1,8 +1,7 @@
# llvm-nm - list LLVM bitcode and object file's symbol table
-```{eval-rst}
-.. program:: llvm-nm
-```
+:::{program} llvm-nm
+:::
## SYNOPSIS
@@ -27,88 +26,88 @@ upper-case characters are listed for the same meaning, a lower-case character
represents a local symbol, whilst an upper-case character represents a global
(external) symbol:
-a, A
+`a`, `A`
+
+: Absolute symbol.
+
+`b`, `B`
-> Absolute symbol.
+: Uninitialized data (bss) object.
-b, B
+`C`
-> Uninitialized data (bss) object.
+: Common symbol. Multiple definitions link together into one definition.
-C
+`d`, `D`
-> Common symbol. Multiple definitions link together into one definition.
+: Writable data object.
-d, D
+`i`, `I`
-> Writable data object.
+: COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
-i, I
+`n`
-> COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
+: ELF: local symbol from non-alloc section.
-n
+ COFF: debug symbol.
-> ELF: local symbol from non-alloc section.
->
-> COFF: debug symbol.
+`N`
-N
+: ELF: debug section symbol, or global symbol from non-alloc section.
-> ELF: debug section symbol, or global symbol from non-alloc section.
+`s`, `S`
-s, S
+: COFF: section symbol.
-> COFF: section symbol.
->
-> Mach-O: absolute symbol or symbol from a section other than \_\_TEXT_EXEC \_\_text,
-> \_\_TEXT \_\_text, \_\_DATA \_\_data, or \_\_DATA \_\_bss.
+ Mach-O: absolute symbol or symbol from a section other than \_\_TEXT_EXEC \_\_text,
+ \_\_TEXT \_\_text, \_\_DATA \_\_data, or \_\_DATA \_\_bss.
-r, R
+`r`, `R`
-> Read-only data object.
+: Read-only data object.
-t, T
+`t`, `T`
-> Code (text) object.
+: Code (text) object.
-u
+`u`
-> ELF: GNU unique symbol.
+: ELF: GNU unique symbol.
-U
+`U`
-> Named object is undefined in this file.
+: Named object is undefined in this file.
-v
+`v`
-> ELF: Undefined weak object. It is not a link failure if the object is not
-> defined.
+: ELF: Undefined weak object. It is not a link failure if the object is not
+ defined.
-V
+`V`
-> ELF: Defined weak object symbol. This definition will only be used if no
-> regular definitions exist in a link. If multiple weak definitions and no
-> regular definitions exist, one of the weak definitions will be used.
+: ELF: Defined weak object symbol. This definition will only be used if no
+ regular definitions exist in a link. If multiple weak definitions and no
+ regular definitions exist, one of the weak definitions will be used.
-w
+`w`
-> Undefined weak symbol other than an ELF object symbol. It is not a link failure
-> if the symbol is not defined.
+: Undefined weak symbol other than an ELF object symbol. It is not a link failure
+ if the symbol is not defined.
-W
+`W`
-> Defined weak symbol other than an ELF object symbol. This definition will only
-> be used if no regular definitions exist in a link. If multiple weak definitions
-> and no regular definitions exist, one of the weak definitions will be used.
+: Defined weak symbol other than an ELF object symbol. This definition will only
+ be used if no regular definitions exist in a link. If multiple weak definitions
+ and no regular definitions exist, one of the weak definitions will be used.
-\-
+`-`
-> Mach-O: N_STAB symbol.
+: Mach-O: N_STAB symbol.
-?
+`?`
-> Something unrecognizable.
+: Something unrecognizable.
Because LLVM bitcode files typically contain objects that are not considered to
have addresses until they are linked into an executable image or dynamically
@@ -118,9 +117,8 @@ file.
## OPTIONS
-```{eval-rst}
-.. program:: llvm-nm
-```
+:::{program} llvm-nm
+:::
:::{option} -B
Use BSD output format. Alias for `--format=bsd`.
@@ -131,30 +129,26 @@ Specify the type of XCOFF object file, ELF object file, or IR object file input
from command line or from archive files that llvm-nm should examine. 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 the supported object files.
->
-> On AIX OS, the default is to process 32-bit object files only and to ignore
-> 64-bit objects. The can be changed by setting the OBJECT_MODE environment
-> variable. For example, OBJECT_MODE=64 causes {program}`llvm-nm` to process
-> 64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
-> variable.
->
-> On other operating systems, the default is to process all object files: the
-> OBJECT_MODE environment variable is not supported.
+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 the supported object files.
+
+On AIX OS, the default is to process 32-bit object files only and to ignore
+64-bit objects. The can be changed by setting the OBJECT_MODE environment
+variable. For example, OBJECT_MODE=64 causes {program}`llvm-nm` to process
+64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
+variable.
+
+On other operating systems, the default is to process all object files: the
+OBJECT_MODE environment variable is not supported.
:::
:::{option} --debug-syms, -a
@@ -316,8 +310,8 @@ Exclude resource file symbols (`__rsrc`) from export symbol list.
## BUGS
-> - {program}`llvm-nm` does not support the full set of arguments that GNU
-> {program}`nm` does.
+- {program}`llvm-nm` does not support the full set of arguments that GNU
+ {program}`nm` does.
## EXIT STATUS
@@ -327,4 +321,3 @@ Exclude resource file symbols (`__rsrc`) from export symbol list.
{manpage}`llvm-ar(1)`, {manpage}`llvm-objdump(1)`, {manpage}`llvm-readelf(1)`,
{manpage}`llvm-readobj(1)`
-
diff --git a/llvm/docs/CommandGuide/llvm-objcopy.md b/llvm/docs/CommandGuide/llvm-objcopy.md
index 9d45a8e83b587..c26cd1e9be883 100644
--- a/llvm/docs/CommandGuide/llvm-objcopy.md
+++ b/llvm/docs/CommandGuide/llvm-objcopy.md
@@ -1,8 +1,7 @@
# llvm-objcopy - object copying and editing tool
-```{eval-rst}
-.. program:: llvm-objcopy
-```
+:::{program} llvm-objcopy
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-objdump.md b/llvm/docs/CommandGuide/llvm-objdump.md
index e9290752a2bc8..0e4e5c7181f93 100644
--- a/llvm/docs/CommandGuide/llvm-objdump.md
+++ b/llvm/docs/CommandGuide/llvm-objdump.md
@@ -1,8 +1,7 @@
# llvm-objdump - LLVM's object file dumper
-```{eval-rst}
-.. program:: llvm-objdump
-```
+:::{program} llvm-objdump
+:::
## SYNOPSIS
@@ -347,13 +346,13 @@ Deprecated.
When used with {option}`--disassemble`, choose style of code to emit from
X86 backend. Supported values are:
-> :::{option} att
-> AT&T-style assembly
-> :::
->
-> :::{option} intel
-> Intel-style assembly
-> :::
+:::{option} att
+AT&T-style assembly
+:::
+
+:::{option} intel
+Intel-style assembly
+:::
The default disassembly style is **att**.
::::
@@ -505,4 +504,3 @@ To report bugs, please visit \<<https://github.com/llvm/llvm-project/labels/tool
{manpage}`llvm-nm(1)`, {manpage}`llvm-otool(1)`, {manpage}`llvm-readelf(1)`,
{manpage}`llvm-readobj(1)`
-
diff --git a/llvm/docs/CommandGuide/llvm-offload-binary.md b/llvm/docs/CommandGuide/llvm-offload-binary.md
index 3b10816ceeecd..b3ac0386ebe1b 100644
--- a/llvm/docs/CommandGuide/llvm-offload-binary.md
+++ b/llvm/docs/CommandGuide/llvm-offload-binary.md
@@ -1,8 +1,7 @@
# llvm-offload-binary - LLVM Offload Binary Packager
-```{eval-rst}
-.. program:: llvm-offload-binary
-```
+:::{program} llvm-offload-binary
+:::
## SYNOPSIS
@@ -109,65 +108,48 @@ to locate offloading sections even after linker operations such as relocatable
linking. Conceptually, this binary format is a serialization of a string map and
an image buffer.
-```{eval-rst}
-.. table:: Offloading Binary Header
- :name: table-binary_header
-
- +----------+--------------+----------------------------------------------------+
- | Type | Identifier | Description |
- +==========+==============+====================================================+
- | uint8_t | magic | The magic bytes for the binary format (0x10FF10AD) |
- +----------+--------------+----------------------------------------------------+
- | uint32_t | version | Version of this format (currently version 1) |
- +----------+--------------+----------------------------------------------------+
- | uint64_t | size | Size of this binary in bytes |
- +----------+--------------+----------------------------------------------------+
- | uint64_t | entry offset | Absolute offset of the offload entries in bytes |
- +----------+--------------+----------------------------------------------------+
- | uint64_t | entry size | Size of the offload entries in bytes |
- +----------+--------------+----------------------------------------------------+
-```
+:::{table} Offloading Binary Header
+:name: table-binary_header
+:widths: auto
+
+| Type | Identifier | Description |
+| -------- | ------------ | -------------------------------------------------- |
+| uint8_t | magic | The magic bytes for the binary format (0x10FF10AD) |
+| uint32_t | version | Version of this format (currently version 1) |
+| uint64_t | size | Size of this binary in bytes |
+| uint64_t | entry offset | Absolute offset of the offload entries in bytes |
+| uint64_t | entry size | Size of the offload entries in bytes |
+:::
Each offload entry describes a bundled image along with its associated metadata.
-```{eval-rst}
-.. table:: Offloading Entry Table
- :name: table-binary_entry
-
- +----------+---------------+----------------------------------------------------+
- | Type | Identifier | Description |
- +==========+===============+====================================================+
- | uint16_t | image kind | The kind of the device image (e.g. bc, cubin) |
- +----------+---------------+----------------------------------------------------+
- | uint16_t | offload kind | The producer of the image (e.g. openmp, cuda) |
- +----------+---------------+----------------------------------------------------+
- | uint32_t | flags | Generic flags for the image |
- +----------+---------------+----------------------------------------------------+
- | uint64_t | string offset | Absolute offset of the string metadata table |
- +----------+---------------+----------------------------------------------------+
- | uint64_t | num strings | Number of string entries in the table |
- +----------+---------------+----------------------------------------------------+
- | uint64_t | image offset | Absolute offset of the device image in bytes |
- +----------+---------------+----------------------------------------------------+
- | uint64_t | image size | Size of the device image in bytes |
- +----------+---------------+----------------------------------------------------+
-```
+:::{table} Offloading Entry Table
+:name: table-binary_entry
+:widths: auto
+
+| Type | Identifier | Description |
+| -------- | ------------- | ----------------------------------------------- |
+| uint16_t | image kind | The kind of the device image (e.g. bc, cubin) |
+| uint16_t | offload kind | The producer of the image (e.g. openmp, cuda) |
+| uint32_t | flags | Generic flags for the image |
+| uint64_t | string offset | Absolute offset of the string metadata table |
+| uint64_t | num strings | Number of string entries in the table |
+| uint64_t | image offset | Absolute offset of the device image in bytes |
+| uint64_t | image size | Size of the device image in bytes |
+:::
The entry table refers to both a string table and the raw device image itself.
The string table provides arbitrary key-value metadata.
-```{eval-rst}
-.. table:: Offloading String Entry
- :name: table-binary_string
-
- +----------+--------------+-------------------------------------------------------+
- | Type | Identifier | Description |
- +==========+==============+=======================================================+
- | uint64_t | key offset | Absolute byte offset of the key in the string table |
- +----------+--------------+-------------------------------------------------------+
- | uint64_t | value offset | Absolute byte offset of the value in the string table |
- +----------+--------------+-------------------------------------------------------+
-```
+:::{table} Offloading String Entry
+:name: table-binary_string
+:widths: auto
+
+| Type | Identifier | Description |
+| -------- | ------------ | ----------------------------------------------------- |
+| uint64_t | key offset | Absolute byte offset of the key in the string table |
+| uint64_t | value offset | Absolute byte offset of the value in the string table |
+:::
The string table is a collection of null-terminated strings stored in the image.
Offsets allow string entries to be interpreted as key-value pairs, enabling
@@ -175,45 +157,32 @@ flexible metadata such as architecture or target triple.
The enumerated values for `image kind` and `offload kind` are:
-```{eval-rst}
-.. table:: Image Kind
- :name: table-image_kind
-
- +---------------+-------+---------------------------------------+
- | Name | Value | Description |
- +===============+=======+=======================================+
- | IMG_None | 0x00 | No image information provided |
- +---------------+-------+---------------------------------------+
- | IMG_Object | 0x01 | The image is a generic object file |
- +---------------+-------+---------------------------------------+
- | IMG_Bitcode | 0x02 | The image is an LLVM-IR bitcode file |
- +---------------+-------+---------------------------------------+
- | IMG_Cubin | 0x03 | The image is a CUDA object file |
- +---------------+-------+---------------------------------------+
- | IMG_Fatbinary | 0x04 | The image is a CUDA fatbinary file |
- +---------------+-------+---------------------------------------+
- | IMG_PTX | 0x05 | The image is a CUDA PTX file |
- +---------------+-------+---------------------------------------+
-```
+:::{table} Image Kind
+:name: table-image_kind
+:widths: auto
+
+| Name | Value | Description |
+| ------------- | ------ | -------------------------------------- |
+| IMG_None | 0x00 | No image information provided |
+| IMG_Object | 0x01 | The image is a generic object file |
+| IMG_Bitcode | 0x02 | The image is an LLVM-IR bitcode file |
+| IMG_Cubin | 0x03 | The image is a CUDA object file |
+| IMG_Fatbinary | 0x04 | The image is a CUDA fatbinary file |
+| IMG_PTX | 0x05 | The image is a CUDA PTX file |
+:::
-```{eval-rst}
-.. table:: Offload Kind
- :name: table-offload_kind
-
- +------------+-------+---------------------------------------+
- | Name | Value | Description |
- +============+=======+=======================================+
- | OFK_None | 0x00 | No offloading information provided |
- +------------+-------+---------------------------------------+
- | OFK_OpenMP | 0x01 | The producer was OpenMP offloading |
- +------------+-------+---------------------------------------+
- | OFK_CUDA | 0x02 | The producer was CUDA |
- +------------+-------+---------------------------------------+
- | OFK_HIP | 0x03 | The producer was HIP |
- +------------+-------+---------------------------------------+
- | OFK_SYCL | 0x04 | The producer was SYCL |
- +------------+-------+---------------------------------------+
-```
+:::{table} Offload Kind
+:name: table-offload_kind
+:widths: auto
+
+| Name | Value | Description |
+| ---------- | ----- | ---------------------------------- |
+| OFK_None | 0x00 | No offloading information provided |
+| OFK_OpenMP | 0x01 | The producer was OpenMP offloading |
+| OFK_CUDA | 0x02 | The producer was CUDA |
+| OFK_HIP | 0x03 | The producer was HIP |
+| OFK_SYCL | 0x04 | The producer was SYCL |
+:::
## COMMON WORKFLOWS
@@ -285,4 +254,3 @@ $ llvm-offload-binary -o new_bundle.bin \
## SEE ALSO
{manpage}`clang(1)`, {manpage}`llvm-objdump(1)`, {manpage}`spirv-val(1)`, {manpage}`spirv-dis(1)`
-
diff --git a/llvm/docs/CommandGuide/llvm-opt-report.md b/llvm/docs/CommandGuide/llvm-opt-report.md
index 1ada35d8d3ae0..bd8596cafedb5 100644
--- a/llvm/docs/CommandGuide/llvm-opt-report.md
+++ b/llvm/docs/CommandGuide/llvm-opt-report.md
@@ -1,8 +1,7 @@
# llvm-opt-report - generate optimization report from YAML
-```{eval-rst}
-.. program:: llvm-opt-report
-```
+:::{program} llvm-opt-report
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-otool.md b/llvm/docs/CommandGuide/llvm-otool.md
index 3a9e8e4f29b3a..aa46347d3d603 100644
--- a/llvm/docs/CommandGuide/llvm-otool.md
+++ b/llvm/docs/CommandGuide/llvm-otool.md
@@ -1,8 +1,7 @@
# llvm-otool - Mach-O dumping tool
-```{eval-rst}
-.. program:: llvm-otool
-```
+:::{program} llvm-otool
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-pdbutil.md b/llvm/docs/CommandGuide/llvm-pdbutil.md
index 1f02743a609d0..8c6b9158f2b6c 100644
--- a/llvm/docs/CommandGuide/llvm-pdbutil.md
+++ b/llvm/docs/CommandGuide/llvm-pdbutil.md
@@ -1,9 +1,7 @@
# llvm-pdbutil - PDB File forensics and diagnostics
-```{eval-rst}
-.. program:: llvm-pdbutil
-
-```
+:::{program} llvm-pdbutil
+:::
## Synopsis
@@ -23,28 +21,27 @@ and forensics, or as a replacement for cvdump.
a different purpose. A brief summary of each command follows, with more detail
in the sections that follow.
-> - {ref}`pretty_subcommand` - Dump symbol and type information in a format that
-> tries to look as much like the original source code as possible.
-> - {ref}`dump_subcommand` - Dump low level types and structures from the PDB
-> file, including CodeView records, hash tables, PDB streams, etc.
-> - {ref}`bytes_subcommand` - Dump data from the PDB file's streams, records,
-> types, symbols, etc as raw bytes.
-> - {ref}`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
-> a valid PDB file that matches that description.
-> - {ref}`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
-> description of some or all of the file in a way that the PDB can be
-> reconstructed.
-> - {ref}`merge_subcommand` - Given two PDBs, produce a third PDB that is the
-> result of merging the two input PDBs.
-> - {ref}`export_subcommand` - Write the contents of a PDB stream to a file.
+- {ref}`pretty-subcommand` - Dump symbol and type information in a format that
+ tries to look as much like the original source code as possible.
+- {ref}`dump-subcommand` - Dump low level types and structures from the PDB
+ file, including CodeView records, hash tables, PDB streams, etc.
+- {ref}`bytes-subcommand` - Dump data from the PDB file's streams, records,
+ types, symbols, etc as raw bytes.
+- {ref}`yaml2pdb-subcommand` - Given a yaml description of a PDB file, produce
+ a valid PDB file that matches that description.
+- {ref}`pdb2yaml-subcommand` - For a given PDB file, produce a YAML
+ description of some or all of the file in a way that the PDB can be
+ reconstructed.
+- {ref}`merge-subcommand` - Given two PDBs, produce a third PDB that is the
+ result of merging the two input PDBs.
+- {ref}`export-subcommand` - Write the contents of a PDB stream to a file.
(pretty-subcommand)=
### pretty
-```{eval-rst}
-.. program:: llvm-pdbutil pretty
-```
+:::{program} llvm-pdbutil pretty
+:::
:::{important}
The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
@@ -243,9 +240,8 @@ given address and display what would be the absolute address.
USAGE: {program}`llvm-pdbutil` dump \[*options*\] \<input PDB file>
-```{eval-rst}
-.. program:: llvm-pdbutil dump
-```
+:::{program} llvm-pdbutil dump
+:::
#### Summary
@@ -422,9 +418,8 @@ Dump PDB string table.
USAGE: {program}`llvm-pdbutil` bytes \[*options*\] \<input PDB file>
-```{eval-rst}
-.. program:: llvm-pdbutil bytes
-```
+:::{program} llvm-pdbutil bytes
+:::
#### Summary
@@ -528,9 +523,8 @@ Dump the record from the TPI stream with the given type index.
USAGE: {program}`llvm-pdbutil` pdb2yaml \[*options*\] \<input PDB file>
-```{eval-rst}
-.. program:: llvm-pdbutil pdb2yaml
-```
+:::{program} llvm-pdbutil pdb2yaml
+:::
#### Summary
@@ -557,14 +551,13 @@ llvm-pdbutil pdb2yaml --dxcontainer shader.pdb
USAGE: {program}`llvm-pdbutil` yaml2pdb \[*options*\] \<input YAML file>
-```{eval-rst}
-.. program:: llvm-pdbutil yaml2pdb
-```
+:::{program} llvm-pdbutil yaml2pdb
+:::
#### Summary
Generate a PDB file from a YAML description. The YAML syntax is not described
-here. Instead, use {ref}`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and
+here. Instead, use {ref}`llvm-pdbutil pdb2yaml <pdb2yaml-subcommand>` and
examine the output for an example starting point.
#### Options
@@ -580,9 +573,8 @@ Write the resulting PDB to the specified file.
USAGE: {program}`llvm-pdbutil` export --out=\<file> \[*options*\] \<input PDB file>
-```{eval-rst}
-.. program:: llvm-pdbutil export
-```
+:::{program} llvm-pdbutil export
+:::
#### Summary
@@ -603,8 +595,8 @@ The resulting file can be inspected with the same DXContainer tooling used for
the main shader output, such as {program}`obj2yaml` and
{program}`llvm-objcopy`. See {doc}`../DirectX/DXContainer` for part format
details. To inspect the embedded container without extracting it, use
-{ref}`llvm-pdbutil dump <dump_subcommand>` or
-{ref}`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>`.
+{ref}`llvm-pdbutil dump <dump-subcommand>` or
+{ref}`llvm-pdbutil pdb2yaml <pdb2yaml-subcommand>`.
#### Options
@@ -629,9 +621,8 @@ Export the contents of the specified PDB stream.
USAGE: {program}`llvm-pdbutil` merge \[*options*\] \<input PDB file 1> \<input PDB file 2>
-```{eval-rst}
-.. program:: llvm-pdbutil merge
-```
+:::{program} llvm-pdbutil merge
+:::
#### Summary
diff --git a/llvm/docs/CommandGuide/llvm-profdata.md b/llvm/docs/CommandGuide/llvm-profdata.md
index 49361d33edfab..60e3e957913b4 100644
--- a/llvm/docs/CommandGuide/llvm-profdata.md
+++ b/llvm/docs/CommandGuide/llvm-profdata.md
@@ -1,8 +1,7 @@
# llvm-profdata - Profile data tool
-```{eval-rst}
-.. program:: llvm-profdata
-```
+:::{program} llvm-profdata
+:::
## SYNOPSIS
@@ -20,9 +19,8 @@ data files.
- {ref}`overlap <profdata-overlap>`
- {ref}`order <profdata-order>`
-```{eval-rst}
-.. program:: llvm-profdata merge
-```
+:::{program} llvm-profdata merge
+:::
(profdata-merge)=
@@ -275,9 +273,8 @@ Exactly equivalent to the previous invocation (explicit form; useful for program
llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
```
-```{eval-rst}
-.. program:: llvm-profdata show
-```
+:::{program} llvm-profdata show
+:::
(profdata-show)=
@@ -393,9 +390,8 @@ Show only the functions that have been executed, i.e., functions with non-zero
counts.
:::
-```{eval-rst}
-.. program:: llvm-profdata overlap
-```
+:::{program} llvm-profdata overlap
+:::
(profdata-overlap)=
@@ -456,9 +452,8 @@ Only show overlap for the context sensitive profile counts. The default is to sh
non-context sensitive profile counts.
:::
-```{eval-rst}
-.. program:: llvm-profdata order
-```
+:::{program} llvm-profdata order
+:::
(profdata-order)=
diff --git a/llvm/docs/CommandGuide/llvm-profgen.md b/llvm/docs/CommandGuide/llvm-profgen.md
index f47a36ae05f59..cd73711a4502f 100644
--- a/llvm/docs/CommandGuide/llvm-profgen.md
+++ b/llvm/docs/CommandGuide/llvm-profgen.md
@@ -1,8 +1,7 @@
# llvm-profgen - LLVM SPGO profile generation tool
-```{eval-rst}
-.. program:: llvm-profgen
-```
+:::{program} llvm-profgen
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-ranlib.md b/llvm/docs/CommandGuide/llvm-ranlib.md
index f8568d0e8a9bf..f1f5956edca16 100644
--- a/llvm/docs/CommandGuide/llvm-ranlib.md
+++ b/llvm/docs/CommandGuide/llvm-ranlib.md
@@ -1,8 +1,7 @@
# llvm-ranlib - generates an archive index
-```{eval-rst}
-.. program:: llvm-ranlib
-```
+:::{program} llvm-ranlib
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-readelf.md b/llvm/docs/CommandGuide/llvm-readelf.md
index d24db896a23c2..68d0a168f682a 100644
--- a/llvm/docs/CommandGuide/llvm-readelf.md
+++ b/llvm/docs/CommandGuide/llvm-readelf.md
@@ -1,8 +1,7 @@
# llvm-readelf - GNU-style LLVM Object Reader
-```{eval-rst}
-.. program:: llvm-readelf
-```
+:::{program} llvm-readelf
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-readobj.md b/llvm/docs/CommandGuide/llvm-readobj.md
index 0237a5d007c17..e5362e11933ca 100644
--- a/llvm/docs/CommandGuide/llvm-readobj.md
+++ b/llvm/docs/CommandGuide/llvm-readobj.md
@@ -1,8 +1,7 @@
# llvm-readobj - LLVM Object Reader
-```{eval-rst}
-.. program:: llvm-readobj
-```
+:::{program} llvm-readobj
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-reduce.md b/llvm/docs/CommandGuide/llvm-reduce.md
index dc1329efb3dfe..5ebd3425d3146 100644
--- a/llvm/docs/CommandGuide/llvm-reduce.md
+++ b/llvm/docs/CommandGuide/llvm-reduce.md
@@ -1,8 +1,7 @@
# llvm-reduce - LLVM automatic testcase reducer.
-```{eval-rst}
-.. program:: llvm-reduce
-```
+:::{program} llvm-reduce
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-remarkutil.md b/llvm/docs/CommandGuide/llvm-remarkutil.md
index 5326f1815272c..5b0f150300d15 100644
--- a/llvm/docs/CommandGuide/llvm-remarkutil.md
+++ b/llvm/docs/CommandGuide/llvm-remarkutil.md
@@ -1,8 +1,7 @@
# llvm-remarkutil - Remark utility
-```{eval-rst}
-.. program:: llvm-remarkutil
-```
+:::{program} llvm-remarkutil
+:::
## Synopsis
@@ -15,19 +14,18 @@ Utility for displaying information from, and converting between different
## Subcommands
-> - {ref}`bitstream2yaml_subcommand` - Reserialize bitstream remarks to YAML.
-> - {ref}`yaml2bitstream_subcommand` - Reserialize YAML remarks to bitstream.
-> - {ref}`instruction-count_subcommand` - Output function instruction counts.
-> - {ref}`annotation-count_subcommand` - Output remark type count from annotation remarks.
-> - {ref}`size-diff_subcommand` - Compute diff in size remarks.
+- {ref}`bitstream2yaml-subcommand` - Reserialize bitstream remarks to YAML.
+- {ref}`yaml2bitstream-subcommand` - Reserialize YAML remarks to bitstream.
+- {ref}`instruction-count-subcommand` - Output function instruction counts.
+- {ref}`annotation-count-subcommand` - Output remark type count from annotation remarks.
+- {ref}`size-diff-subcommand` - Compute diff in size remarks.
(bitstream2yaml-subcommand)=
### bitstream2yaml
-```{eval-rst}
-.. program:: llvm-remarkutil bitstream2yaml
-```
+:::{program} llvm-remarkutil bitstream2yaml
+:::
USAGE: {program}`llvm-remarkutil` bitstream2yaml \<input file> -o \<output file>
@@ -39,9 +37,8 @@ Takes a bitstream remark file as input, and reserializes that file as YAML.
### yaml2bitstream
-```{eval-rst}
-.. program:: llvm-remarkutil yaml2bitstream
-```
+:::{program} llvm-remarkutil yaml2bitstream
+:::
USAGE: {program}`llvm-remarkutil` yaml2bitstream \<input file> -o \<output file>
@@ -54,9 +51,8 @@ format.
### instruction-count
-```{eval-rst}
-.. program:: llvm-remarkutil instruction-count
-```
+:::{program} llvm-remarkutil instruction-count
+:::
USAGE: {program}`llvm-remarkutil` instruction-count \<input file> --parser=\<bitstream|yaml> [--use-debug-loc] -o \<output file>
@@ -85,9 +81,8 @@ path:line:column,foo,3
### annotation-count
-```{eval-rst}
-.. program:: llvm-remarkutil annotation-count
-```
+:::{program} llvm-remarkutil annotation-count
+:::
USAGE: {program}`llvm-remarkutil` annotation-count \<input file> --parser=\<bitstream|yaml> --annotation-type=\<type> [--use-debug-loc] -o \<output file>
@@ -116,9 +111,8 @@ path:line:column,foo,3
### count
-```{eval-rst}
-.. program:: llvm-remarkutil count
-```
+:::{program} llvm-remarkutil count
+:::
USAGE: {program}`llvm-remarkutil` count \[*options*\] \<input file>
@@ -205,9 +199,8 @@ Filter remarks by type with the following options.
### size-diff
-```{eval-rst}
-.. program:: llvm-remarkutil size-diff
-```
+:::{program} llvm-remarkutil size-diff
+:::
USAGE: {program}`llvm-remarkutil` size-diff \[*options*\] *file_a* *file_b* **--parser** *parser*
diff --git a/llvm/docs/CommandGuide/llvm-size.md b/llvm/docs/CommandGuide/llvm-size.md
index 940a48bf2be28..f44192b1375f5 100644
--- a/llvm/docs/CommandGuide/llvm-size.md
+++ b/llvm/docs/CommandGuide/llvm-size.md
@@ -1,8 +1,7 @@
# llvm-size - print size information
-```{eval-rst}
-.. program:: llvm-size
-```
+:::{program} llvm-size
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-stress.md b/llvm/docs/CommandGuide/llvm-stress.md
index 2606eae47a621..727c6b4ca82ab 100644
--- a/llvm/docs/CommandGuide/llvm-stress.md
+++ b/llvm/docs/CommandGuide/llvm-stress.md
@@ -1,8 +1,7 @@
# llvm-stress - generate random .ll files
-```{eval-rst}
-.. program:: llvm-stress
-```
+:::{program} llvm-stress
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-strings.md b/llvm/docs/CommandGuide/llvm-strings.md
index 1e3a0fa3f1ee7..da9d0a03d9fd5 100644
--- a/llvm/docs/CommandGuide/llvm-strings.md
+++ b/llvm/docs/CommandGuide/llvm-strings.md
@@ -1,8 +1,7 @@
# llvm-strings - print strings
-```{eval-rst}
-.. program:: llvm-strings
-```
+:::{program} llvm-strings
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-strip.md b/llvm/docs/CommandGuide/llvm-strip.md
index 2a0be6678dce8..f2a14ad91b931 100644
--- a/llvm/docs/CommandGuide/llvm-strip.md
+++ b/llvm/docs/CommandGuide/llvm-strip.md
@@ -1,8 +1,7 @@
# llvm-strip - object stripping tool
-```{eval-rst}
-.. program:: llvm-strip
-```
+:::{program} llvm-strip
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-symbolizer.md b/llvm/docs/CommandGuide/llvm-symbolizer.md
index 916173f6f6cc6..a3068491b93bd 100644
--- a/llvm/docs/CommandGuide/llvm-symbolizer.md
+++ b/llvm/docs/CommandGuide/llvm-symbolizer.md
@@ -1,8 +1,7 @@
# llvm-symbolizer - convert addresses into source code locations
-```{eval-rst}
-.. program:: llvm-symbolizer
-```
+:::{program} llvm-symbolizer
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-tblgen.md b/llvm/docs/CommandGuide/llvm-tblgen.md
index 12b590065f731..054a80a3182b0 100644
--- a/llvm/docs/CommandGuide/llvm-tblgen.md
+++ b/llvm/docs/CommandGuide/llvm-tblgen.md
@@ -1,8 +1,7 @@
# llvm-tblgen - Target Description to C++ Code for LLVM
-```{eval-rst}
-.. program:: llvm-tblgen
-```
+:::{program} llvm-tblgen
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/llvm-test-mustache-spec.md b/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
index 0cd42042a471a..52406f56639bf 100644
--- a/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
+++ b/llvm/docs/CommandGuide/llvm-test-mustache-spec.md
@@ -1,8 +1,7 @@
# llvm-test-mustache-spec - LLVM tool to test Mustache library compliance
-```{eval-rst}
-.. program:: llvm-test-mustache-spec
-```
+:::{program} llvm-test-mustache-spec
+:::
## SYNOPSIS
@@ -30,6 +29,5 @@ files to standard output.
## EXAMPLE
```console
-$ llvm-test-mustache-spec path/to/specs/\*.json
+$ llvm-test-mustache-spec path/to/specs/*.json
```
-
diff --git a/llvm/docs/CommandGuide/llvm-tli-checker.md b/llvm/docs/CommandGuide/llvm-tli-checker.md
index e983e689b1a70..082d58d9775bc 100644
--- a/llvm/docs/CommandGuide/llvm-tli-checker.md
+++ b/llvm/docs/CommandGuide/llvm-tli-checker.md
@@ -1,8 +1,7 @@
# llvm-tli-checker - TargetLibraryInfo vs library checker
-```{eval-rst}
-.. program:: llvm-tli-checker
-```
+:::{program} llvm-tli-checker
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/mlir-tblgen.md b/llvm/docs/CommandGuide/mlir-tblgen.md
index 761fdb44ab0cf..6d415ab6de4c9 100644
--- a/llvm/docs/CommandGuide/mlir-tblgen.md
+++ b/llvm/docs/CommandGuide/mlir-tblgen.md
@@ -1,8 +1,7 @@
# mlir-tblgen - Description to C++ Code for MLIR
-```{eval-rst}
-.. program:: mlir-tblgen
-```
+:::{program} mlir-tblgen
+:::
## SYNOPSIS
diff --git a/llvm/docs/CommandGuide/opt.md b/llvm/docs/CommandGuide/opt.md
index 3368af13f1f3a..ab41ea398462d 100644
--- a/llvm/docs/CommandGuide/opt.md
+++ b/llvm/docs/CommandGuide/opt.md
@@ -1,8 +1,7 @@
# opt - LLVM optimizer
-```{eval-rst}
-.. program:: opt
-```
+:::{program} opt
+:::
## SYNOPSIS
@@ -47,7 +46,7 @@ Write output in LLVM intermediate language (instead of bitcode).
:::{option} -passes=<string>
A textual (comma-separated) description of the pass pipeline,
e.g., `-passes="sroa,instcombine"`. See
-[invoking opt](../NewPassManager.html#invoking-opt) for more details on the
+[invoking opt](../NewPassManager.md#invoking-opt) for more details on the
pass pipeline syntax.
:::
@@ -97,7 +96,9 @@ error.
:::{option} -debug
If this is a debug build, this option will enable debug printouts from passes
-which use the `LLVM_DEBUG()` macro. See the [LLVM Programmer's Manual](../ProgrammersManual.html), section `#DEBUG` for more information.
+which use the `LLVM_DEBUG()` macro. See {ref}`the LDBG and LLVM_DEBUG() macros
+and -debug option <debug>` for more
+information.
:::
:::{option} -load=<plugin>
@@ -120,4 +121,3 @@ Print all available passes and exit.
If {program}`opt` succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
-
diff --git a/llvm/docs/CommandGuide/tblgen.md b/llvm/docs/CommandGuide/tblgen.md
index 391b2034c628b..f941652f0408e 100644
--- a/llvm/docs/CommandGuide/tblgen.md
+++ b/llvm/docs/CommandGuide/tblgen.md
@@ -1,8 +1,7 @@
# tblgen - Description to C++ Code
-```{eval-rst}
-.. program:: tblgen
-```
+:::{program} tblgen
+:::
## SYNOPSIS
diff --git a/llvm/docs/ProgrammersManual.md b/llvm/docs/ProgrammersManual.md
index e4c07a389891a..9dc27fd48669f 100644
--- a/llvm/docs/ProgrammersManual.md
+++ b/llvm/docs/ProgrammersManual.md
@@ -1065,7 +1065,7 @@ the external storage will not be freed). If you need this ability, consider
using `std::function`. `function_ref` is small enough that it should always
be passed by value.
-(DEBUG)=
+(debug)=
### The `LDBG` and `LLVM_DEBUG()` macros and `-debug` option
More information about the llvm-branch-commits
mailing list