[llvm-branch-commits] [llvm] [docs] Finish MyST migration for selected LLVM docs (PR #214618)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Aug 7 11:51:14 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/214618
>From 22219cd0b8dbe47e2e544987064cf1de62d53ccf Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Fri, 7 Aug 2026 02:17:29 +0000
Subject: [PATCH 1/3] [docs] Convert selected rst docs with rst2myst
---
llvm/docs/Benchmarking.md | 95 ++-
llvm/docs/CMakePrimer.md | 460 +++++-----
llvm/docs/CodeOfConduct.md | 168 ++--
llvm/docs/DirectXUsage.md | 77 +-
llvm/docs/FatLTO.md | 140 ++-
llvm/docs/HowToUseAttributes.md | 84 +-
llvm/docs/LFI.md | 303 ++++---
llvm/docs/MisExpect.md | 65 +-
llvm/docs/OpaquePointers.md | 229 +++--
llvm/docs/OptBisect.md | 219 +++--
llvm/docs/PDB/index.md | 231 +++--
llvm/docs/RISCV/RISCVVCIX.md | 350 ++++----
llvm/docs/RISCV/RISCVVectorExtension.md | 433 +++++-----
llvm/docs/RISCVUsage.md | 1045 ++++++++++++-----------
llvm/docs/ReportingGuide.md | 112 ++-
llvm/docs/ResponseGuide.md | 234 +++--
llvm/docs/SymbolizerMarkupFormat.md | 596 ++++++-------
llvm/docs/TableGenFundamentals.md | 10 +-
llvm/docs/Telemetry.md | 367 ++++----
llvm/docs/yaml2obj.md | 513 +++++------
20 files changed, 2829 insertions(+), 2902 deletions(-)
diff --git a/llvm/docs/Benchmarking.md b/llvm/docs/Benchmarking.md
index d168965114459..4edf5ada2f47b 100644
--- a/llvm/docs/Benchmarking.md
+++ b/llvm/docs/Benchmarking.md
@@ -1,87 +1,94 @@
-==================================
-Benchmarking tips
-==================================
+# Benchmarking tips
-
-Introduction
-============
+## Introduction
For benchmarking a patch we want to reduce all possible sources of
noise as much as possible. How to do that is very OS dependent.
Note that low noise is required, but not sufficient. It does not
exclude measurement bias.
-See `"Producing Wrong Data Without Doing Anything Obviously Wrong!" by Mytkowicz, Diwan, Hauswith and Sweeney (ASPLOS 2009) <https://users.cs.northwestern.edu/~robby/courses/322-2013-spring/mytkowicz-wrong-data.pdf>`_
+See ["Producing Wrong Data Without Doing Anything Obviously Wrong!" by Mytkowicz, Diwan, Hauswith and Sweeney (ASPLOS 2009)](https://users.cs.northwestern.edu/~robby/courses/322-2013-spring/mytkowicz-wrong-data.pdf)
for example.
-General
-================================
+## General
-* Use a high-resolution timer, e.g., perf under Linux.
+- Use a high-resolution timer, e.g., perf under Linux.
-* Run the benchmark multiple times to be able to recognize noise.
+- Run the benchmark multiple times to be able to recognize noise.
-* Disable as many processes or services as possible on the target system.
+- Disable as many processes or services as possible on the target system.
-* Disable frequency scaling, Turbo Boost and address space
+- Disable frequency scaling, Turbo Boost and address space
randomization (see OS-specific section).
-* Use static linking if the OS supports it. That avoids any variation that
+- Use static linking if the OS supports it. That avoids any variation that
might be introduced by loading dynamic libraries. This can be done
- by passing ``-DLLVM_BUILD_STATIC=ON`` to CMake.
+ by passing `-DLLVM_BUILD_STATIC=ON` to CMake.
-* Try to avoid storage. On some systems, you can use tmpfs. Putting the
+- Try to avoid storage. On some systems, you can use tmpfs. Putting the
program, inputs and outputs on tmpfs avoids touching a real storage
system, which can have a pretty big variability.
- To mount it (on Linux and FreeBSD at least)::
+ To mount it (on Linux and FreeBSD at least):
- mount -t tmpfs -o size=<XX>g none dir_to_mount
+ ```
+ mount -t tmpfs -o size=<XX>g none dir_to_mount
+ ```
-Linux
-=====
+## Linux
-* Disable address space randomization::
+- Disable address space randomization:
- echo 0 > /proc/sys/kernel/randomize_va_space
+ ```
+ echo 0 > /proc/sys/kernel/randomize_va_space
+ ```
-* Set scaling_governor to performance::
+- Set scaling_governor to performance:
- for i in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
- do
- echo performance > $i
- done
+ ```
+ for i in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+ do
+ echo performance > $i
+ done
+ ```
-* Use https://github.com/lpechacek/cpuset to reserve CPU cores for just the
+- Use <https://github.com/lpechacek/cpuset> to reserve CPU cores for just the
program you are benchmarking. If using perf, leave at least 2 cores
- so that perf runs in one and your program in another::
+ so that perf runs in one and your program in another:
- cset shield -c N1,N2 -k on
+ ```
+ cset shield -c N1,N2 -k on
+ ```
- This will move all threads out of N1 and N2. The ``-k on`` means
+ This will move all threads out of N1 and N2. The `-k on` means
that even kernel threads are moved out.
-* Disable the SMT pair of the cpus you will use for the benchmark. The
+- Disable the SMT pair of the cpus you will use for the benchmark. The
pair of cpu N can be found in
- ``/sys/devices/system/cpu/cpuN/topology/thread_siblings_list`` and
- disabled with::
-
- echo 0 > /sys/devices/system/cpu/cpuX/online
+ `/sys/devices/system/cpu/cpuN/topology/thread_siblings_list` and
+ disabled with:
+ ```
+ echo 0 > /sys/devices/system/cpu/cpuX/online
+ ```
-* Run the program with::
+- Run the program with:
- cset shield --exec -- perf stat -r 10 <cmd>
+ ```
+ cset shield --exec -- perf stat -r 10 <cmd>
+ ```
- This will run the command after ``--`` in the isolated CPU cores. The
- particular perf command runs the ``<cmd>`` 10 times and reports
+ This will run the command after `--` in the isolated CPU cores. The
+ particular perf command runs the `<cmd>` 10 times and reports
statistics.
With these in place you can expect perf variations of less than 0.1%.
-Linux Intel
------------
+### Linux Intel
+
+- Disable Turbo Boost:
-* Disable Turbo Boost::
+ ```
+ echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo
+ ```
- echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo
diff --git a/llvm/docs/CMakePrimer.md b/llvm/docs/CMakePrimer.md
index ce4604b0d5d5a..1dd95b0bd2296 100644
--- a/llvm/docs/CMakePrimer.md
+++ b/llvm/docs/CMakePrimer.md
@@ -1,28 +1,22 @@
-============
-CMake Primer
-============
+# CMake Primer
+:::{warning}
+Disclaimer: This documentation is written by LLVM project contributors `not`
+anyone affiliated with the CMake project. This document may contain
+inaccurate terminology, phrasing, or technical details. It is provided with
+the best intentions.
+:::
-.. warning::
- Disclaimer: This documentation is written by LLVM project contributors `not`
- anyone affiliated with the CMake project. This document may contain
- inaccurate terminology, phrasing, or technical details. It is provided with
- the best intentions.
-
-
-Introduction
-============
+## Introduction
The LLVM project and many of the core projects built on LLVM build using CMake.
This document aims to provide a brief overview of CMake for developers modifying
LLVM projects or building their own projects on top of LLVM.
The official CMake language reference is available in the cmake-language
-manpage and `cmake-language online documentation
-<https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html>`_.
+manpage and [cmake-language online documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html).
-10,000 ft View
-==============
+## 10,000 ft View
CMake is a tool that reads script files in its own language that describe how a
software project builds. As CMake evaluates the scripts, it constructs an
@@ -38,11 +32,10 @@ because it allows the build system to skip long-running checks during
incremental development. CMake caching also has some drawbacks, but that will be
discussed later.
-Scripting Overview
-==================
+## Scripting Overview
CMake's scripting language has a very simple grammar. Every language construct
-is a command that matches the pattern _name_(_args_). Commands come in three
+is a command that matches the pattern \_name\_(\_args\_). Commands come in three
primary types: language-defined (commands implemented in C++ in CMake), defined
functions, and defined macros. The CMake distribution also contains a suite of
CMake modules that contain definitions for useful functionality.
@@ -50,33 +43,31 @@ CMake modules that contain definitions for useful functionality.
The example below is the full CMake build for building a C++ "Hello World"
program. The example uses only CMake language-defined functions.
-.. code-block:: cmake
+```cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(HelloWorld)
+add_executable(HelloWorld HelloWorld.cpp)
+```
- cmake_minimum_required(VERSION 3.20.0)
- project(HelloWorld)
- add_executable(HelloWorld HelloWorld.cpp)
-
-The CMake language provides control flow constructs in the form of ``foreach`` loops
-and ``if`` blocks. To make the example above more complicated you could add an if
+The CMake language provides control flow constructs in the form of `foreach` loops
+and `if` blocks. To make the example above more complicated you could add an if
block to define "APPLE" when targeting Apple platforms:
-.. code-block:: cmake
-
- cmake_minimum_required(VERSION 3.20.0)
- project(HelloWorld)
- add_executable(HelloWorld HelloWorld.cpp)
- if(APPLE)
- target_compile_definitions(HelloWorld PUBLIC APPLE)
- endif()
+```cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(HelloWorld)
+add_executable(HelloWorld HelloWorld.cpp)
+if(APPLE)
+ target_compile_definitions(HelloWorld PUBLIC APPLE)
+endif()
+```
-Variables, Types, and Scope
-===========================
+## Variables, Types, and Scope
-Dereferencing
--------------
+### Dereferencing
In CMake, variables are "stringly" typed. All variables are represented as
-strings throughout evaluation. Wrapping a variable in ``${}`` dereferences it
+strings throughout evaluation. Wrapping a variable in `${}` dereferences it
and results in a literal substitution of the name for the value. CMake refers to
this as "variable evaluation" in their documentation. Dereferences are performed
*before* the command being called receives the arguments. This means
@@ -86,11 +77,11 @@ command.
Variable dereferences can be nested and be used to model complex data. For
example:
-.. code-block:: cmake
-
- set(var_name var1)
- set(${var_name} foo) # same as "set(var1 foo)"
- set(${${var_name}}_var bar) # same as "set(foo_var bar)"
+```cmake
+set(var_name var1)
+set(${var_name} foo) # same as "set(var1 foo)"
+set(${${var_name}}_var bar) # same as "set(foo_var bar)"
+```
Dereferencing an unset variable results in an empty expansion. It is a common
pattern in CMake to conditionally set variables knowing that it will be used in
@@ -99,79 +90,74 @@ the LLVM CMake build system.
An example of variable empty expansion is:
-.. code-block:: cmake
-
- if(APPLE)
- set(extra_sources Apple.cpp)
- endif()
- add_executable(HelloWorld HelloWorld.cpp ${extra_sources})
+```cmake
+if(APPLE)
+ set(extra_sources Apple.cpp)
+endif()
+add_executable(HelloWorld HelloWorld.cpp ${extra_sources})
+```
-In this example the ``extra_sources`` variable is only defined if you're
-targeting an Apple platform. For all other targets the ``extra_sources`` will be
+In this example the `extra_sources` variable is only defined if you're
+targeting an Apple platform. For all other targets the `extra_sources` will be
evaluated as empty before add_executable is given its arguments.
-Lists
------
+### Lists
In CMake, lists are semicolon-delimited strings, and it is strongly advised that
you avoid using semicolons in lists; it doesn't go smoothly. A few examples of
defining lists:
-.. code-block:: cmake
+```cmake
+# Creates a list with members a, b, c, and d
+set(my_list a b c d)
+set(my_list "a;b;c;d")
- # Creates a list with members a, b, c, and d
- set(my_list a b c d)
- set(my_list "a;b;c;d")
+# Creates a string "a b c d"
+set(my_string "a b c d")
+```
- # Creates a string "a b c d"
- set(my_string "a b c d")
-
-Lists of Lists
---------------
+### Lists of Lists
One of the more complicated patterns in CMake is lists of lists. Because a list
cannot contain an element with a semicolon to construct a list of lists you
make a list of variable names that refer to other lists. For example:
-.. code-block:: cmake
-
- set(list_of_lists a b c)
- set(a 1 2 3)
- set(b 4 5 6)
- set(c 7 8 9)
+```cmake
+set(list_of_lists a b c)
+set(a 1 2 3)
+set(b 4 5 6)
+set(c 7 8 9)
+```
With this layout you can iterate through the list of lists printing each value
with the following code:
-.. code-block:: cmake
-
- foreach(list_name IN LISTS list_of_lists)
- foreach(value IN LISTS ${list_name})
- message(${value})
- endforeach()
- endforeach()
+```cmake
+foreach(list_name IN LISTS list_of_lists)
+ foreach(value IN LISTS ${list_name})
+ message(${value})
+ endforeach()
+endforeach()
+```
You'll notice that the inner foreach loop's list is doubly dereferenced. This is
-because the first dereference turns ``list_name`` into the name of the sub-list
+because the first dereference turns `list_name` into the name of the sub-list
(a, b, or c in the example), then the second dereference is to get the value of
the list.
This pattern is used throughout CMake, the most common example is the compiler
flags options, which CMake refers to using the following variable expansions:
-``CMAKE_${LANGUAGE}_FLAGS`` and ``CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}``.
+`CMAKE_${LANGUAGE}_FLAGS` and `CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}`.
-Other Types
------------
+### Other Types
Variables that are cached or specified on the command line can have types
associated with them. The variable's type is used by CMake's UI tool to display
the right input field. A variable's type generally doesn't impact evaluation;
-however, CMake does have special handling for some variables such as ``PATH``.
-You can read more about the special handling in `CMake's set documentation
-<https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry>`_.
+however, CMake does have special handling for some variables such as `PATH`.
+You can read more about the special handling in [CMake's set documentation](https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry).
-Scope
------
+### Scope
CMake inherently has a directory-based scoping. Setting a variable in a
CMakeLists file, will set the variable for that file, and all subdirectories.
@@ -181,135 +167,132 @@ set in the scope they are included from, and all subdirectories.
When a variable that is already set is set again in a subdirectory it overrides
the value in that scope and any deeper subdirectories.
-The CMake set command provides two scope-related options. ``PARENT_SCOPE`` sets a
-variable into the parent scope, and not the current scope. The ``CACHE`` option sets
+The CMake set command provides two scope-related options. `PARENT_SCOPE` sets a
+variable into the parent scope, and not the current scope. The `CACHE` option sets
the variable in the CMakeCache, which results in it being set in all scopes. The
-``CACHE`` option will not set a variable that already exists in the ``CACHE`` unless the
-``FORCE`` option is specified.
+`CACHE` option will not set a variable that already exists in the `CACHE` unless the
+`FORCE` option is specified.
In addition to directory-based scope, CMake functions also have their own scope.
This means variables set inside functions do not bleed into the parent scope.
This is not true of macros, and it is for this reason LLVM prefers functions
over macros whenever reasonable.
-.. note::
- Unlike C-based languages, CMake's loop and control flow blocks do not have
- their own scopes.
+:::{note}
+Unlike C-based languages, CMake's loop and control flow blocks do not have
+their own scopes.
+:::
-Control Flow
-============
+## Control Flow
CMake features the same basic control flow constructs you would expect in any
scripting language, but there are a few quirks because, as with everything in
CMake, control flow constructs are commands.
-If, ElseIf, Else
-----------------
+### If, ElseIf, Else
-.. note::
- For the full documentation on the CMake if command go
- `here <https://cmake.org/cmake/help/v3.4/command/if.html>`_. That resource is
- far more complete.
+:::{note}
+For the full documentation on the CMake if command go
+[here](https://cmake.org/cmake/help/v3.4/command/if.html). That resource is
+far more complete.
+:::
-In general, CMake ``if`` blocks work the way you'd expect:
+In general, CMake `if` blocks work the way you'd expect:
-.. code-block:: cmake
+```cmake
+if(<condition>)
+ message("do stuff")
+elseif(<condition>)
+ message("do other stuff")
+else()
+ message("do other other stuff")
+endif()
+```
- if(<condition>)
- message("do stuff")
- elseif(<condition>)
- message("do other stuff")
- else()
- message("do other other stuff")
- endif()
-
-The single most important thing to know about CMake's ``if`` blocks coming from a C
+The single most important thing to know about CMake's `if` blocks coming from a C
background is that they do not have their own scope. Variables set inside
-conditional blocks persist after the ``endif()``.
-
-Loops
------
+conditional blocks persist after the `endif()`.
-The most common form of the CMake ``foreach`` block is:
+### Loops
-.. code-block:: cmake
+The most common form of the CMake `foreach` block is:
- foreach(var ...)
- message("do stuff")
- endforeach()
+```cmake
+foreach(var ...)
+ message("do stuff")
+endforeach()
+```
-The variable argument portion of the ``foreach`` block can contain dereferenced
+The variable argument portion of the `foreach` block can contain dereferenced
lists, values to iterate, or a mix of both:
-.. code-block:: cmake
-
- foreach(var foo bar baz)
- message(${var})
- endforeach()
- # prints:
- # foo
- # bar
- # baz
-
- set(my_list 1 2 3)
- foreach(var ${my_list})
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
-
- foreach(var ${my_list} out_of_bounds)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
- # out_of_bounds
+```cmake
+foreach(var foo bar baz)
+ message(${var})
+endforeach()
+# prints:
+# foo
+# bar
+# baz
+
+set(my_list 1 2 3)
+foreach(var ${my_list})
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+
+foreach(var ${my_list} out_of_bounds)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+# out_of_bounds
+```
There is also a more modern CMake foreach syntax. The code below is equivalent
to the code above:
-.. code-block:: cmake
-
- foreach(var IN ITEMS foo bar baz)
- message(${var})
- endforeach()
- # prints:
- # foo
- # bar
- # baz
-
- set(my_list 1 2 3)
- foreach(var IN LISTS my_list)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
-
- foreach(var IN LISTS my_list ITEMS out_of_bounds)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
- # out_of_bounds
+```cmake
+foreach(var IN ITEMS foo bar baz)
+ message(${var})
+endforeach()
+# prints:
+# foo
+# bar
+# baz
+
+set(my_list 1 2 3)
+foreach(var IN LISTS my_list)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+
+foreach(var IN LISTS my_list ITEMS out_of_bounds)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+# out_of_bounds
+```
Similar to the conditional statements, these generally behave how you would
expect, and they do not have their own scope.
-CMake also supports ``while`` loops, although they are not widely used in LLVM.
+CMake also supports `while` loops, although they are not widely used in LLVM.
-Modules, Functions and Macros
-=============================
+## Modules, Functions and Macros
-Modules
--------
+### Modules
Modules are CMake's vehicle for enabling code reuse. CMake modules are just
CMake script files. They can contain code to execute on include as well as
@@ -324,46 +307,44 @@ modules are the fundamental pieces needed to build LLVM-based projects with
CMake. We also rely on modules as a way of organizing the build system's
functionality for maintainability and reuse within LLVM projects.
-Argument Handling
------------------
+### Argument Handling
When defining a CMake command handling arguments is very useful. The examples
-in this section will all use the CMake ``function`` block, but this also applies
-to the ``macro`` block as well.
+in this section will all use the CMake `function` block, but this also applies
+to the `macro` block as well.
CMake commands can have named arguments that are required at every call site. In
addition, all commands will implicitly accept a variable number of extra
arguments (In C parlance, all commands are varargs functions). When a command is
invoked with extra arguments (beyond the named ones) CMake will store the full
-list of arguments (both named and unnamed) in a list named ``ARGV``, and the
-sublist of unnamed arguments in ``ARGN``. Below is a trivial example of
-providing a wrapper function for CMake's built in function ``add_dependencies``.
-
-.. code-block:: cmake
+list of arguments (both named and unnamed) in a list named `ARGV`, and the
+sublist of unnamed arguments in `ARGN`. Below is a trivial example of
+providing a wrapper function for CMake's built in function `add_dependencies`.
- function(add_deps target)
- add_dependencies(${target} ${ARGN})
- endfunction()
+```cmake
+function(add_deps target)
+ add_dependencies(${target} ${ARGN})
+endfunction()
+```
-This example defines a new macro named ``add_deps`` which takes a required first
+This example defines a new macro named `add_deps` which takes a required first
argument, and just calls another function passing through the first argument and
all trailing arguments.
-CMake provides a module ``CMakeParseArguments`` which provides an implementation
+CMake provides a module `CMakeParseArguments` which provides an implementation
of advanced argument parsing. We use this all over LLVM, and it is recommended
for any function that has complex argument-based behaviors or optional
arguments. CMake's official documentation for the module is in the
-``cmake-modules`` manpage, and is also available at the
-`cmake-modules online documentation
-<https://cmake.org/cmake/help/v3.4/module/CMakeParseArguments.html>`_.
+`cmake-modules` manpage, and is also available at the
+[cmake-modules online documentation](https://cmake.org/cmake/help/v3.4/module/CMakeParseArguments.html).
-.. note::
- As of CMake 3.5 the cmake_parse_arguments command has become a native command
- and the CMakeParseArguments module is empty and only left around for
- compatibility.
+:::{note}
+As of CMake 3.5 the cmake_parse_arguments command has become a native command
+and the CMakeParseArguments module is empty and only left around for
+compatibility.
+:::
-Functions Vs Macros
--------------------
+### Functions Vs Macros
Functions and Macros look very similar in how they are used, but there is one
fundamental difference between the two. Functions have their own scope, and
@@ -376,62 +357,61 @@ passed. Arguments to macros are not set as variables, instead dereferences to
the parameters are resolved across the macro before executing it. This can
result in some unexpected behavior if using unreferenced variables. For example:
-.. code-block:: cmake
-
- macro(print_list my_list)
- foreach(var IN LISTS my_list)
- message("${var}")
- endforeach()
- endmacro()
-
- set(my_list a b c d)
- set(my_list_of_numbers 1 2 3 4)
- print_list(my_list_of_numbers)
- # prints:
- # a
- # b
- # c
- # d
+```cmake
+macro(print_list my_list)
+ foreach(var IN LISTS my_list)
+ message("${var}")
+ endforeach()
+endmacro()
+
+set(my_list a b c d)
+set(my_list_of_numbers 1 2 3 4)
+print_list(my_list_of_numbers)
+# prints:
+# a
+# b
+# c
+# d
+```
Generally speaking, this issue is uncommon because it requires using
non-dereferenced variables with names that overlap in the parent scope, but it
is important to be aware of because it can lead to subtle bugs.
-LLVM Project Wrappers
-=====================
+## LLVM Project Wrappers
LLVM projects provide lots of wrappers around critical CMake built-in commands.
We use these wrappers to provide consistent behaviors across LLVM components
and to reduce code duplication.
We generally (but not always) follow the convention that commands prefaced with
-``llvm_`` are intended to be used only as building blocks for other commands.
+`llvm_` are intended to be used only as building blocks for other commands.
Wrapper commands that are intended for direct use are generally named following
-with the project in the middle of the command name (i.e. ``add_llvm_executable``
-is the wrapper for ``add_executable``). The LLVM ``add_*`` wrapper functions are
-all defined in ``AddLLVM.cmake`` which is installed as part of the LLVM
+with the project in the middle of the command name (i.e. `add_llvm_executable`
+is the wrapper for `add_executable`). The LLVM `add_*` wrapper functions are
+all defined in `AddLLVM.cmake` which is installed as part of the LLVM
distribution. It can be included and used by any LLVM sub-project that requires
LLVM.
-.. note::
+:::{note}
+Not all LLVM projects require LLVM for all use cases. For example compiler-rt
+can be built without LLVM, and the compiler-rt sanitizer libraries are used
+with GCC.
+:::
- Not all LLVM projects require LLVM for all use cases. For example compiler-rt
- can be built without LLVM, and the compiler-rt sanitizer libraries are used
- with GCC.
-
-Useful Built-in Commands
-========================
+## Useful Built-in Commands
CMake has a collection of useful built-in commands. This document isn't going to
go into details about them because The CMake project has excellent
documentation. To highlight a few useful functions see:
-* `add_custom_command <https://cmake.org/cmake/help/v3.4/command/add_custom_command.html>`_
-* `add_custom_target <https://cmake.org/cmake/help/v3.4/command/add_custom_target.html>`_
-* `file <https://cmake.org/cmake/help/v3.4/command/file.html>`_
-* `list <https://cmake.org/cmake/help/v3.4/command/list.html>`_
-* `math <https://cmake.org/cmake/help/v3.4/command/math.html>`_
-* `string <https://cmake.org/cmake/help/v3.4/command/string.html>`_
+- [add_custom_command](https://cmake.org/cmake/help/v3.4/command/add_custom_command.html)
+- [add_custom_target](https://cmake.org/cmake/help/v3.4/command/add_custom_target.html)
+- [file](https://cmake.org/cmake/help/v3.4/command/file.html)
+- [list](https://cmake.org/cmake/help/v3.4/command/list.html)
+- [math](https://cmake.org/cmake/help/v3.4/command/math.html)
+- [string](https://cmake.org/cmake/help/v3.4/command/string.html)
+
+The full documentation for CMake commands is in the `cmake-commands` manpage
+and available on [CMake's website](https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html)
-The full documentation for CMake commands is in the ``cmake-commands`` manpage
-and available on `CMake's website <https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html>`_
diff --git a/llvm/docs/CodeOfConduct.md b/llvm/docs/CodeOfConduct.md
index 995d32bb388df..4f380b603018a 100644
--- a/llvm/docs/CodeOfConduct.md
+++ b/llvm/docs/CodeOfConduct.md
@@ -1,23 +1,20 @@
-..
- This work is licensed under a Creative Commons Attribution 3.0 Unported License.
- SPDX-License-Identifier: CC-BY-3.0
+% This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+% SPDX-License-Identifier: CC-BY-3.0
-.. _LLVM Community Code of Conduct:
+(llvm-community-code-of-conduct)=
-==============================
-LLVM Community Code of Conduct
-==============================
+# LLVM Community Code of Conduct
The LLVM community has always worked to be a welcoming and respectful
community, and we want to ensure that doesn't change as we grow and evolve. To
that end, we have a few ground rules that we ask people to adhere to:
-* `be friendly and patient`_,
-* `be welcoming`_,
-* `be considerate`_,
-* `be respectful`_,
-* `be careful in the words that you choose and be kind to others`_, and
-* `when we disagree, try to understand why`_.
+- [be friendly and patient],
+- [be welcoming],
+- [be considerate],
+- [be respectful],
+- [be careful in the words that you choose and be kind to others], and
+- [when we disagree, try to understand why].
This isn't an exhaustive list of things that you can't do. Rather, take it in
the spirit in which it's intended - a guide to make it easier to communicate
@@ -31,15 +28,15 @@ all of your communication and conduct in these spaces, including emails, chats,
things you say, slides, videos, posters, signs, or even t-shirts you display in
these spaces.
-In rare cases, violations of this code outside of these spaces may affect a
-person’s ability to participate within these spaces. Important examples
-include `sexual and gender-based violence`_, `hate crimes`_, and `hate speech`_.
-We do not conduct proactive research, but we have an obligation to respond
-to any reported concerns. We are not interested in evaluating severity,
-responding punitively, or holding people accountable. Both the relevance
-and our response is instead focused on how a person’s continued participation
-impacts the community’s safety, wellbeing, and inclusivity. We specifically
-prioritize remaining a welcoming community to victims as well as groups
+In rare cases, violations of this code outside of these spaces may affect a
+person’s ability to participate within these spaces. Important examples
+include [sexual and gender-based violence][sexual and gender-based violence], [hate crimes][hate crimes], and [hate speech][hate speech].
+We do not conduct proactive research, but we have an obligation to respond
+to any reported concerns. We are not interested in evaluating severity,
+responding punitively, or holding people accountable. Both the relevance
+and our response is instead focused on how a person’s continued participation
+impacts the community’s safety, wellbeing, and inclusivity. We specifically
+prioritize remaining a welcoming community to victims as well as groups
subjected to systemic marginalization or underrepresentation.
In addition, violations of this code outside these spaces may, in rare
@@ -47,33 +44,33 @@ cases, affect a person's ability to participate within them, when the conduct
amounts to an egregious violation of this code.
If you believe someone is violating the code of conduct, we ask that you report
-it by emailing conduct at llvm.org. For more details please see the
-:doc:`Reporting Guide <ReportingGuide>`.
+it by emailing <mailto:conduct at llvm.org>. For more details please see the
+{doc}`Reporting Guide <ReportingGuide>`.
-.. _be friendly and patient:
+(be-friendly-and-patient)=
-* **Be friendly and patient.**
+- **Be friendly and patient.**
-.. _be welcoming:
+(be-welcoming)=
-* **Be welcoming.** We strive to be a community that welcomes and supports
+- **Be welcoming.** We strive to be a community that welcomes and supports
people of all backgrounds and identities. This includes, but is not limited
to members of any race, ethnicity, culture, national origin, colour,
immigration status, social and economic class, educational level, sex, sexual
orientation, gender identity and expression, age, size, family status,
political belief, religion or lack thereof, and mental and physical ability.
-.. _be considerate:
+(be-considerate)=
-* **Be considerate.** Your work will be used by other people, and you in turn
+- **Be considerate.** Your work will be used by other people, and you in turn
will depend on the work of others. Any decision you take will affect users
and colleagues, and you should take those consequences into account. Remember
that we're a world-wide community, so you might not be communicating in
someone else's primary language.
-.. _be respectful:
+(be-respectful)=
-* **Be respectful.** Not all of us will agree all the time, but disagreement is
+- **Be respectful.** Not all of us will agree all the time, but disagreement is
no excuse for poor behavior and poor manners. We might all experience some
frustration now and then, but we cannot allow that frustration to turn into
a personal attack. It's important to remember that a community where people
@@ -81,27 +78,27 @@ it by emailing conduct at llvm.org. For more details please see the
community should be respectful when dealing with other members as well as
with people outside the LLVM community.
-.. _be careful in the words that you choose and be kind to others:
+(be-careful-in-the-words-that-you-choose-and-be-kind-to-others)=
-* **Be careful in the words that you choose and be kind to others.** Do not
+- **Be careful in the words that you choose and be kind to others.** Do not
insult or put down other participants. Harassment and other exclusionary
behavior aren't acceptable. This includes, but is not limited to:
- * Violent threats or language directed against another person.
- * Discriminatory jokes and language.
- * Posting sexually explicit or violent material.
- * Posting (or threatening to post) other people's personally identifying
+ - Violent threats or language directed against another person.
+ - Discriminatory jokes and language.
+ - Posting sexually explicit or violent material.
+ - Posting (or threatening to post) other people's personally identifying
information ("doxing").
- * Personal insults, especially those using racist or sexist terms.
- * Unwelcome sexual attention.
- * Advocating for, or encouraging, any of the above behavior.
+ - Personal insults, especially those using racist or sexist terms.
+ - Unwelcome sexual attention.
+ - Advocating for, or encouraging, any of the above behavior.
In general, if someone asks you to stop, then stop. Persisting in such
behavior after being asked to stop is considered harassment.
-.. _when we disagree, try to understand why:
+(when-we-disagree-try-to-understand-why)=
-* **When we disagree, try to understand why.** Disagreements, both social and
+- **When we disagree, try to understand why.** Disagreements, both social and
technical, happen all the time and LLVM is no exception. It is important that
we resolve disagreements and differing views constructively. Remember that
we're different. The strength of LLVM comes from its varied community, people
@@ -111,14 +108,13 @@ it by emailing conduct at llvm.org. For more details please see the
err and blaming each other doesn't get us anywhere. Instead, focus on helping
to resolve issues and learning from mistakes.
-Reporting
-=========
+## Reporting
If you believe someone is violating the code of conduct you can always report
it to the LLVM Foundation Code of Conduct Committee by emailing
-conduct at llvm.org. All reports will be kept confidential. This isn't a public
+<mailto:conduct at llvm.org>. All reports will be kept confidential. This isn't a public
list and only members of the advisory committee will receive the report. For
-details on what to include in the report, please see the :doc:`Reporting Guide
+details on what to include in the report, please see the {doc}`Reporting Guide
<ReportingGuide>`.
If you believe anyone is in physical danger, please notify appropriate law
@@ -133,73 +129,67 @@ able to help. If you cannot find one of the organizers, the venue staff can
locate one for you. We will also post detailed contact information for specific
events as part of each events' information. In person reports will still be
kept confidential exactly as above, but also feel free to (anonymously if
-needed) email conduct at llvm.org.
+needed) email <mailto:conduct at llvm.org>.
-Bans
-====
+## Bans
The code of conduct committee may decide to ban an individual from the
community for violating the code of conduct. The goal of a ban is to protect
community members from having to interact with people who are consistently not
respecting the code of conduct. Please refer to the
-:doc:`Developer Policy<DeveloperPolicy>` section on Bans for how to handle
+{doc}`Developer Policy<DeveloperPolicy>` section on Bans for how to handle
interactions with former community members. If you need further guidance,
-please contact conduct at llvm.org.
+please contact <mailto:conduct at llvm.org>.
-Code of Conduct Committee
-=========================
+## Code of Conduct Committee
The committee will consist of a minimum of 5 members and members are asked to
serve at least a 1 year term. New committee members will be selected by the
current committee and the LLVM Foundation Board of Directors.
When responding to a Code of Conduct report, the committee follows the
-following
-:doc:`Response Guide<ResponseGuide>`.
+following
+{doc}`Response Guide<ResponseGuide>`.
The current committee members are:
-* Aaron Ballman (aaron.ballman\@llvm.org)
-* Kristof Beyls (kristof.beyls\@llvm.org)
-* David Blaikie (dblaikie\@llvm.org)
-* Jonas Devlieghere (jdevlieghere\@llvm.org)
-* Cyndy Ishida (cishida\@llvm.org)
-* Tanya Lattner (tanyalattner\@llvm.org)
-* Stella Stamenova (sstamenova\@llvm.org)
+- Aaron Ballman (aaron.ballman at llvm.org)
+- Kristof Beyls (kristof.beyls at llvm.org)
+- David Blaikie (dblaikie at llvm.org)
+- Jonas Devlieghere (jdevlieghere at llvm.org)
+- Cyndy Ishida (cishida at llvm.org)
+- Tanya Lattner (tanyalattner at llvm.org)
+- Stella Stamenova (sstamenova at llvm.org)
+## Transparency Reports
-Transparency Reports
-====================
+- [July 15, 2025](https://discourse.llvm.org/t/llvm-code-of-conduct-transparency-report-july-15-2024-july-15-2025/88622)
+- [July 15, 2024](https://discourse.llvm.org/t/llvm-code-of-conduct-transparency-report-july-15-2023-july-15-2024/82687)
+- [July 15, 2023](https://llvm.org/coc-reports/2023-07-15-report.html)
+- [July 15, 2022](https://llvm.org/coc-reports/2022-07-15-report.html)
+- [April 28, 2022](https://llvm.org/coc-reports/2022-04-28-report.html)
-* `July 15, 2025 <https://discourse.llvm.org/t/llvm-code-of-conduct-transparency-report-july-15-2024-july-15-2025/88622>`_
-* `July 15, 2024 <https://discourse.llvm.org/t/llvm-code-of-conduct-transparency-report-july-15-2023-july-15-2024/82687>`_
-* `July 15, 2023 <https://llvm.org/coc-reports/2023-07-15-report.html>`_
-* `July 15, 2022 <https://llvm.org/coc-reports/2022-07-15-report.html>`_
-* `April 28, 2022 <https://llvm.org/coc-reports/2022-04-28-report.html>`_
+For details about what a Transparency Report is and what it contains, please see the {doc}`Response Guide<ResponseGuide>`.
-For details about what a Transparency Report is and what it contains, please see the :doc:`Response Guide<ResponseGuide>`.
-
-Questions?
-==========
+## Questions?
If you have questions, please feel free to contact the LLVM Foundation Code of
-Conduct Committee by emailing conduct at llvm.org.
+Conduct Committee by emailing <mailto:conduct at llvm.org>.
+
+## Thanks!
-Thanks!
-=======
+This text is based on the [Django Project][django project] Code of Conduct, which is in turn
+based on wording from the [Speak Up! project][speak up! project].
-This text is based on the `Django Project`_ Code of Conduct, which is in turn
-based on wording from the `Speak Up! project`_.
+## License
-License
-=======
+All content on this page is licensed under a [Creative Commons Attribution 3.0
+Unported License][creative commons attribution 3.0 unported license].
-All content on this page is licensed under a `Creative Commons Attribution 3.0
-Unported License`_.
+[creative commons attribution 3.0 unported license]: http://creativecommons.org/licenses/by/3.0/
+[django project]: https://www.djangoproject.com/conduct/
+[hate crimes]: https://hatecrime.osce.org
+[hate speech]: https://www.un.org/en/genocideprevention/documents/UN%20Strategy%20and%20Plan%20of%20Action%20on%20Hate%20Speech%2018%20June%20SYNOPSIS.pdf
+[sexual and gender-based violence]: https://hr.un.org/sites/hr.un.org/files/SEA%20Glossary%20%20%5BSecond%20Edition%20-%202017%5D%20-%20English_0.pdf
+[speak up! project]: http://speakup.io/coc.html
-.. _Django Project: https://www.djangoproject.com/conduct/
-.. _Speak Up! project: http://speakup.io/coc.html
-.. _sexual and gender-based violence: https://hr.un.org/sites/hr.un.org/files/SEA%20Glossary%20%20%5BSecond%20Edition%20-%202017%5D%20-%20English_0.pdf
-.. _hate crimes: https://hatecrime.osce.org
-.. _hate speech: https://www.un.org/en/genocideprevention/documents/UN%20Strategy%20and%20Plan%20of%20Action%20on%20Hate%20Speech%2018%20June%20SYNOPSIS.pdf
-.. _Creative Commons Attribution 3.0 Unported License: http://creativecommons.org/licenses/by/3.0/
diff --git a/llvm/docs/DirectXUsage.md b/llvm/docs/DirectXUsage.md
index dc795cd7f53df..dca6588f88a67 100644
--- a/llvm/docs/DirectXUsage.md
+++ b/llvm/docs/DirectXUsage.md
@@ -1,53 +1,51 @@
-=================================
-User Guide for the DirectX Target
-=================================
+# User Guide for the DirectX Target
-.. warning::
- Disclaimer: The DirectX backend is experimental and under active development.
- It is not yet feature complete or ready to be used outside of experimental or
- demonstration contexts.
+:::{warning}
+Disclaimer: The DirectX backend is experimental and under active development.
+It is not yet feature complete or ready to be used outside of experimental or
+demonstration contexts.
+:::
+```{toctree}
+:hidden: true
-.. toctree::
- :hidden:
+DirectX/DXContainer
+DirectX/DXILArchitecture
+DirectX/DXILOpTableGenDesign
+DirectX/DXILResources
+DirectX/RootSignatures
+DirectX/SemanticSignatures
+```
- DirectX/DXContainer
- DirectX/DXILArchitecture
- DirectX/DXILOpTableGenDesign
- DirectX/DXILResources
- DirectX/RootSignatures
- DirectX/SemanticSignatures
-
-Introduction
-============
+## Introduction
The DirectX target implements the DirectX programmability interfaces. These
-interfaces are documented in the `DirectX Specifications. <https://github.com/Microsoft/DirectX-Specs>`_
+interfaces are documented in the [DirectX Specifications.](https://github.com/Microsoft/DirectX-Specs)
Initially the backend is aimed at supporting DirectX 12, and support for DirectX
11 is planned at a later date.
The DirectX backend is currently experimental and is not shipped with any
release builds of LLVM tools. To build the DirectX backend locally, add
-``DirectX`` to the ``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD`` CMake option. For more
-information on building LLVM see the :doc:`CMake` documentation.
+`DirectX` to the `LLVM_EXPERIMENTAL_TARGETS_TO_BUILD` CMake option. For more
+information on building LLVM see the {doc}`CMake` documentation.
-.. _dx-target-triples:
+(dx-target-triples)=
-Target Triples
-==============
+## Target Triples
-At present, the DirectX target only supports the ``dxil`` architecture, which
+At present, the DirectX target only supports the `dxil` architecture, which
generates code for the
-`DirectX Intermediate Language. <https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst>`_
+[DirectX Intermediate Language.](https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst)
In addition to target architecture, the DirectX backend also needs to know the
target runtime version and pipeline stage. These are expressed using the OS and
Environment triple component.
-Presently, the DirectX backend requires targeting the ``shadermodel`` OS, and
+Presently, the DirectX backend requires targeting the `shadermodel` OS, and
supports versions 6.0+ (as of writing, the latest announced version is 6.7).
+```{eval-rst}
.. table:: DirectX Environments
================== ========================================================
@@ -69,28 +67,29 @@ supports versions 6.0+ (as of writing, the latest announced version is 6.7).
``mesh`` Mesh shader
``amplification`` Amplification shader
================== ========================================================
+```
-Output Binaries
-===============
+## Output Binaries
The DirectX runtime APIs read a file format based on the
-`DirectX Specification. <https://github.com/Microsoft/DirectX-Specs>`_. In
+[DirectX Specification.](https://github.com/Microsoft/DirectX-Specs). In
different codebases the file format is referred to by different names
-(specifically ``DXBC`` and ``DXILContainer``). Since the format is used to store
-both ``DXBC`` and ``DXIL`` outputs, and the ultimate goal is to support both as
+(specifically `DXBC` and `DXILContainer`). Since the format is used to store
+both `DXBC` and `DXIL` outputs, and the ultimate goal is to support both as
code generation targets in LLVM, the LLVM codebase uses a more neutral name,
-``DXContainer``.
+`DXContainer`.
-The ``DXContainer`` format is sparsely documented in the functional
+The `DXContainer` format is sparsely documented in the functional
specification, but a reference implementation exists in the
-`DirectXShaderCompiler. <https://github.com/microsoft/DirectXShaderCompiler>`_.
+[DirectXShaderCompiler.](https://github.com/microsoft/DirectXShaderCompiler).
The format is documented in the LLVM project docs as well (see
-:doc:`DirectX/DXContainer`).
+{doc}`DirectX/DXContainer`).
-Support for generating ``DXContainer`` files in LLVM, is being added to the LLVM
+Support for generating `DXContainer` files in LLVM, is being added to the LLVM
MC layer for object streamers and writers, and to the Object and ObjectYAML
libraries for testing and object file tooling.
-For ``dxil`` targeting, bitcode emission into ``DXContainer`` files follows a
-similar model to the ``-fembed-bitcode`` flag supported by clang for other
+For `dxil` targeting, bitcode emission into `DXContainer` files follows a
+similar model to the `-fembed-bitcode` flag supported by clang for other
targets.
+
diff --git a/llvm/docs/FatLTO.md b/llvm/docs/FatLTO.md
index d5c2e773d8eda..63c6348e48e30 100644
--- a/llvm/docs/FatLTO.md
+++ b/llvm/docs/FatLTO.md
@@ -1,112 +1,104 @@
-===================
-FatLTO
-===================
+# FatLTO
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+```
-Introduction
-============
+## Introduction
-FatLTO objects are a special type of `fat object file
-<https://en.wikipedia.org/wiki/Fat_binary>`_ that contain LTO compatible IR in
+FatLTO objects are a special type of [fat object file](https://en.wikipedia.org/wiki/Fat_binary) that contain LTO compatible IR in
addition to generated object code, instead of containing object code for
multiple target architectures. This allows users to defer the choice of whether
to use LTO or not to link-time, and has been a feature available in other
-compilers, like `GCC
-<https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html>`_, for some time.
+compilers, like [GCC](https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html), for some time.
Under FatLTO the compiler can emit standard object files which contain both the
-machine code in the ``.text`` section and LLVM bitcode in the ``.llvm.lto``
+machine code in the `.text` section and LLVM bitcode in the `.llvm.lto`
section.
-Overview
-========
+## Overview
-Within LLVM, FatLTO is supported by choosing the ``FatLTODefaultPipeline``.
+Within LLVM, FatLTO is supported by choosing the `FatLTODefaultPipeline`.
This pipeline will:
-#) Run the pre-link (Thin)LTO pipeline on the current module.
-#) Embed the pre-link bitcode in a special ``.llvm.lto`` section.
-#) Finish optimizing the module using the ModuleOptimization pipeline.
-#) Emit the object file, including the new ``.llvm.lto`` section.
-
-.. NOTE
-
- Previously, we conservatively ran independent pipelines on separate copies
- of the LLVM module to generate the bitcode section and the object code,
- which happened to be identical to those used outside of FatLTO. While that
- resulted in compiled artifacts that were identical to those produced by the
- default and (Thin)LTO pipelines, module cloning led to some cases of
- miscompilation, and we have moved away from trying to keep bitcode
- generation and optimization completely disjoint.
-
- Bit-for-bit compatibility is not (and never was) a guarantee, and we reserve
- the right to change this at any time. Explicitly, users should not rely on
- the produced bitcode or object code to match their non-LTO counterparts
- precisely. They will exhibit similar performance characteristics, but may
- not be bit-for-bit the same.
-
-Internally, the ``.llvm.lto`` section is created by running the
-``EmbedBitcodePass`` after the ``ThinLTOPreLinkDefaultPipeline``. This pass is
-responsible for emitting the ``.llvm.lto`` section. Afterwards, the
-``ThinLTODefaultPipeline`` runs and the compiler can emit the fat object file.
-
-Limitations
-===========
-
-Linkers
--------
+1. Run the pre-link (Thin)LTO pipeline on the current module.
+2. Embed the pre-link bitcode in a special `.llvm.lto` section.
+3. Finish optimizing the module using the ModuleOptimization pipeline.
+4. Emit the object file, including the new `.llvm.lto` section.
+
+% NOTE
+%
+% Previously, we conservatively ran independent pipelines on separate copies
+% of the LLVM module to generate the bitcode section and the object code,
+% which happened to be identical to those used outside of FatLTO. While that
+% resulted in compiled artifacts that were identical to those produced by the
+% default and (Thin)LTO pipelines, module cloning led to some cases of
+% miscompilation, and we have moved away from trying to keep bitcode
+% generation and optimization completely disjoint.
+%
+% Bit-for-bit compatibility is not (and never was) a guarantee, and we reserve
+% the right to change this at any time. Explicitly, users should not rely on
+% the produced bitcode or object code to match their non-LTO counterparts
+% precisely. They will exhibit similar performance characteristics, but may
+% not be bit-for-bit the same.
+
+Internally, the `.llvm.lto` section is created by running the
+`EmbedBitcodePass` after the `ThinLTOPreLinkDefaultPipeline`. This pass is
+responsible for emitting the `.llvm.lto` section. Afterwards, the
+`ThinLTODefaultPipeline` runs and the compiler can emit the fat object file.
+
+## Limitations
+
+### Linkers
Currently, using LTO with LLVM fat lto objects is supported by LLD and by the
-GNU linkers via :doc:`GoldPlugin`. This may change in the future, but
+GNU linkers via {doc}`GoldPlugin`. This may change in the future, but
extending support to other linkers isn't planned for now.
-.. NOTE
- For standard linking the fat object files should be usable by any
- linker capable of using ELF objects, since the ``.llvm.lto`` section is
- marked ``SHF_EXCLUDE``.
+% NOTE
+% For standard linking the fat object files should be usable by any
+% linker capable of using ELF objects, since the ``.llvm.lto`` section is
+% marked ``SHF_EXCLUDE``.
-Supported File Formats
-----------------------
+### Supported File Formats
The current implementation only supports ELF files. At time of writing, it is
-unclear if it will be useful to support other object file formats like ``COFF``
-or ``Mach-O``.
+unclear if it will be useful to support other object file formats like `COFF`
+or `Mach-O`.
-Usage
-=====
+## Usage
-Clang users can specify ``-ffat-lto-objects`` with ``-flto`` or ``-flto=thin``.
-Without the ``-flto`` option, ``-ffat-lto-objects`` has no effect.
+Clang users can specify `-ffat-lto-objects` with `-flto` or `-flto=thin`.
+Without the `-flto` option, `-ffat-lto-objects` has no effect.
Compile an object file using FatLTO:
-.. code-block:: console
-
- $ clang -flto -ffat-lto-objects example.c -c -o example.o
+```console
+$ clang -flto -ffat-lto-objects example.c -c -o example.o
+```
Link using the object code from the fat object without LTO. This turns
-``-ffat-lto-objects`` into a no-op, when ``-fno-lto`` is specified:
-
-.. code-block:: console
+`-ffat-lto-objects` into a no-op, when `-fno-lto` is specified:
- $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.o
+```console
+$ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.o
+```
Alternatively, you can omit any references to LTO with fat objects and retain standard linker behavior:
-.. code-block:: console
-
- $ clang -fuse-ld=lld example.o
+```console
+$ clang -fuse-ld=lld example.o
+```
Link using the LLVM bitcode from the fat object with Full LTO:
-.. code-block:: console
-
- $ clang -flto -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=full --fat-lto-objects to ld.lld
+```console
+$ clang -flto -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=full --fat-lto-objects to ld.lld
+```
Link using the LLVM bitcode from the fat object with Thin LTO:
-.. code-block:: console
+```console
+$ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=thin --fat-lto-objects to ld.lld
+```
- $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=thin --fat-lto-objects to ld.lld
diff --git a/llvm/docs/HowToUseAttributes.md b/llvm/docs/HowToUseAttributes.md
index cf26c956414e0..28f2014d20275 100644
--- a/llvm/docs/HowToUseAttributes.md
+++ b/llvm/docs/HowToUseAttributes.md
@@ -1,76 +1,70 @@
-=====================
-How To Use Attributes
-=====================
+# How To Use Attributes
+## Introduction
-Introduction
-============
-
-Attributes in LLVM have changed in some fundamental ways. It was necessary to
+Attributes in LLVM have changed in some fundamental ways. It was necessary to
do this to support expanding the attributes to encompass more than a handful of
-attributes --- e.g. command line options. The old way of handling attributes
-consisted of representing them as a bit mask of values. This bit mask was
-stored in a "list" structure that was reference counted. The advantage of this
-was that attributes could be manipulated with 'or's and 'and's. The
+attributes --- e.g. command line options. The old way of handling attributes
+consisted of representing them as a bit mask of values. This bit mask was
+stored in a "list" structure that was reference counted. The advantage of this
+was that attributes could be manipulated with 'or's and 'and's. The
disadvantage of this was that there was limited room for expansion, and
virtually no support for attribute-value pairs other than alignment.
-In the new scheme, an ``Attribute`` object represents a single attribute that's
-uniqued. You use the ``Attribute::get`` methods to create a new ``Attribute``
-object. An attribute can be a single "enum" value (the enum being the
-``Attribute::AttrKind`` enum), a string representing a target-dependent
-attribute, or an attribute-value pair. Some examples:
+In the new scheme, an `Attribute` object represents a single attribute that's
+uniqued. You use the `Attribute::get` methods to create a new `Attribute`
+object. An attribute can be a single "enum" value (the enum being the
+`Attribute::AttrKind` enum), a string representing a target-dependent
+attribute, or an attribute-value pair. Some examples:
-* Target-independent: ``noinline``, ``zext``
-* Target-dependent: ``"no-sse"``, ``"thumb2"``
-* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``
+- Target-independent: `noinline`, `zext`
+- Target-dependent: `"no-sse"`, `"thumb2"`
+- Attribute-value pair: `"cpu" = "cortex-a8"`, `align = 4`
Note: for an attribute value pair, we expect a target-dependent attribute to
have a string for the value.
-``Attribute``
-=============
-An ``Attribute`` object is designed to be passed around by value.
+## `Attribute`
+
+An `Attribute` object is designed to be passed around by value.
Because attributes are no longer represented as a bit mask, you will need to
convert any code which does treat them as a bit mask to use the new query
methods on the Attribute class.
-``AttributeList``
-=================
+## `AttributeList`
-The ``AttributeList`` stores a collection of Attribute objects for each kind of
+The `AttributeList` stores a collection of Attribute objects for each kind of
object that may have an attribute associated with it: the function as a whole,
-the return type, or the function's parameters. A function's attributes are at
-index ``AttributeList::FunctionIndex``; the return type's attributes are at
-index ``AttributeList::ReturnIndex``; and the function's parameters' attributes
-are at indices 1, ..., n (where 'n' is the number of parameters). Most methods
-on the ``AttributeList`` class take an index parameter.
+the return type, or the function's parameters. A function's attributes are at
+index `AttributeList::FunctionIndex`; the return type's attributes are at
+index `AttributeList::ReturnIndex`; and the function's parameters' attributes
+are at indices 1, ..., n (where 'n' is the number of parameters). Most methods
+on the `AttributeList` class take an index parameter.
-An ``AttributeList`` is also a uniqued and immutable object. You create an
-``AttributeList`` through the ``AttributeList::get`` methods. You can add and
-remove attributes, which result in the creation of a new ``AttributeList``.
+An `AttributeList` is also a uniqued and immutable object. You create an
+`AttributeList` through the `AttributeList::get` methods. You can add and
+remove attributes, which result in the creation of a new `AttributeList`.
-An ``AttributeList`` object is designed to be passed around by value.
+An `AttributeList` object is designed to be passed around by value.
-Note: It is advised that you do *not* use the ``AttributeList`` "introspection"
-methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break
+Note: It is advised that you do *not* use the `AttributeList` "introspection"
+methods (e.g. `Raw`, `getRawPointer`, etc.). These methods break
encapsulation, and may be removed in a future release.
-``AttrBuilder``
-===============
+## `AttrBuilder`
-Lastly, we have a "builder" class to help create the ``AttributeList`` object
+Lastly, we have a "builder" class to help create the `AttributeList` object
without having to create several different intermediate uniqued
-``AttributeList`` objects. The ``AttrBuilder`` class allows you to add and
-remove attributes at will. The attributes won't be uniqued until you call the
-appropriate ``AttributeList::get`` method.
+`AttributeList` objects. The `AttrBuilder` class allows you to add and
+remove attributes at will. The attributes won't be uniqued until you call the
+appropriate `AttributeList::get` method.
-An ``AttrBuilder`` object is *not* designed to be passed around by value. It
+An `AttrBuilder` object is *not* designed to be passed around by value. It
should be passed by reference.
-Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``
-method or the ``AttrBuilder(uint64_t Val)`` constructor. These are for
+Note: It is advised that you do *not* use the `AttrBuilder::addRawValue()`
+method or the `AttrBuilder(uint64_t Val)` constructor. These are for
backwards compatibility and may be removed in a future release.
And that's basically it! A lot of functionality is hidden behind these classes,
diff --git a/llvm/docs/LFI.md b/llvm/docs/LFI.md
index 928079dd047de..4aa13babee917 100644
--- a/llvm/docs/LFI.md
+++ b/llvm/docs/LFI.md
@@ -1,10 +1,6 @@
-=========================================
-Lightweight Fault Isolation (LFI) in LLVM
-=========================================
+# Lightweight Fault Isolation (LFI) in LLVM
-
-Introduction
-++++++++++++
+## Introduction
Lightweight Fault Isolation (LFI) is a compiler-based sandboxing technology for
native code. Like WebAssembly and Native Client, LFI isolates sandboxed code in-process
@@ -15,14 +11,14 @@ libraries (including assembly code) and device drivers.
LFI aims for the following goals:
-* Compatibility: LFI can be used to sandbox nearly all existing C/C++/assembly
+- Compatibility: LFI can be used to sandbox nearly all existing C/C++/assembly
libraries unmodified (they just need to be recompiled). Sandboxed libraries
work with existing system call interfaces, and are compatible with existing
development tools such as profilers, debuggers, and sanitizers.
-* Performance: LFI aims for minimal overhead vs. unsandboxed code.
-* Security: The LFI runtime and compiler elements aim to be simple and
+- Performance: LFI aims for minimal overhead vs. unsandboxed code.
+- Security: The LFI runtime and compiler elements aim to be simple and
verifiable when possible.
-* Usability: LFI aims to make it as easy as possible to retrofit sandboxing,
+- Usability: LFI aims to make it as easy as possible to retrofit sandboxing,
i.e., to migrate from unsandboxed to sandboxed libraries with minimal effort.
When building a program for the LFI target the compiler is designed to ensure
@@ -40,14 +36,13 @@ technique of Software-Based Fault Isolation (SFI). LLVM currently supports LFI
for the AArch64 and X86-64 platforms. The AArch64 version is designed to
support the Armv8.1 AArch64 architecture.
-See `https://github.com/lfi-project <https://github.com/lfi-project/>`__ for
+See [https://github.com/lfi-project](https://github.com/lfi-project/) for
details about the LFI project and additional software needed to run LFI
programs.
-Compiler Requirements
-+++++++++++++++++++++
+## Compiler Requirements
-When building for an LFI target (``aarch64_lfi`` or ``x86_64_lfi``), the
+When building for an LFI target (`aarch64_lfi` or `x86_64_lfi`), the
compiler must restrict use of the instruction set to a subset of instructions,
which are known to be safe from a sandboxing perspective. To do this, we apply a
set of simple rewrites at the assembly language level to transform standard
@@ -57,13 +52,13 @@ These rewrites (also called "expansions") are applied at the very end of the
LLVM compilation pipeline (during the assembler step). This allows the rewrites
to be applied to hand-written assembly, including inline assembly.
-Context Register
-++++++++++++++++
+## Context Register
Both architectures designate a context register that points to a block of
-thread-local memory managed by the LFI runtime. The context register is ``x25``
-on AArch64 and ``r15`` on X86-64. The layout is as follows:
+thread-local memory managed by the LFI runtime. The context register is `x25`
+on AArch64 and `r15` on X86-64. The layout is as follows:
+```{eval-rst}
+--------+--------+----------------------------------------------+
| Offset | Size | Description |
+--------+--------+----------------------------------------------+
@@ -73,78 +68,72 @@ on AArch64 and ``r15`` on X86-64. The layout is as follows:
+--------+--------+----------------------------------------------+
| 16 | 8 | Virtual thread pointer (used for TP access). |
+--------+--------+----------------------------------------------+
+```
-Linker Support
-++++++++++++++
+## Linker Support
In the initial version, LFI only supports static linking, and only supports
-creating ``static-pie`` binaries. There is nothing that fundamentally precludes
+creating `static-pie` binaries. There is nothing that fundamentally precludes
support for dynamic linking on the LFI target, but such support would require
that the code generated by the linker for PLT entries be slightly modified in
order to conform to the LFI architecture subset.
-Assembler Directives
-++++++++++++++++++++
+## Assembler Directives
The following directives are supported for controlling the rewriter.
-``.lfi_rewrite_disable``
-========================
+### `.lfi_rewrite_disable`
Disables LFI assembly rewrites for all subsequent instructions, until
-``.lfi_rewrite_enable`` is used. This can be useful for hand-written assembly
+`.lfi_rewrite_enable` is used. This can be useful for hand-written assembly
that is already safe and should not be modified by the rewriter.
-``.lfi_rewrite_enable``
-=======================
+### `.lfi_rewrite_enable`
-Re-enables LFI assembly rewrites after a previous ``.lfi_rewrite_disable``.
+Re-enables LFI assembly rewrites after a previous `.lfi_rewrite_disable`.
Example:
-.. code-block:: gas
-
- .lfi_rewrite_disable
- // No rewrites applied here.
- ldr x0, [x27, w1, uxtw]
- .lfi_rewrite_enable
+```gas
+.lfi_rewrite_disable
+// No rewrites applied here.
+ldr x0, [x27, w1, uxtw]
+.lfi_rewrite_enable
+```
-Compiler Options
-++++++++++++++++
+## Compiler Options
-The LFI target has several configuration options, specified via ``-mattr=``:
+The LFI target has several configuration options, specified via `-mattr=`:
-* ``+no-lfi-loads``: Disable sandboxing for load instructions (stores-only mode).
-* ``+no-lfi-stores``: Disable sandboxing for store instructions.
+- `+no-lfi-loads`: Disable sandboxing for load instructions (stores-only mode).
+- `+no-lfi-stores`: Disable sandboxing for store instructions.
-Use ``+no-lfi-loads`` to create a "stores-only" sandbox that may read, but not
+Use `+no-lfi-loads` to create a "stores-only" sandbox that may read, but not
write, outside the sandbox region.
-Use ``+no-lfi-loads,+no-lfi-stores`` to create a "jumps-only" sandbox that may
+Use `+no-lfi-loads,+no-lfi-stores` to create a "jumps-only" sandbox that may
read/write outside the sandbox region but may not transfer control outside
(e.g., may not execute system calls directly). This is primarily useful in
combination with some other form of memory sandboxing, such as Intel MPK.
-AArch64
-+++++++
+## AArch64
-The AArch64 LFI target is ``aarch64_lfi``. This is the first part of a target
-triple that can be used with ``--triple=aarch64_lfi-<rest of triple>``.
+The AArch64 LFI target is `aarch64_lfi`. This is the first part of a target
+triple that can be used with `--triple=aarch64_lfi-<rest of triple>`.
-Reserved Registers
-==================
+### Reserved Registers
The AArch64 LFI target uses a custom ABI that reserves additional registers for
the platform. The registers are listed below, along with the security invariant
that must be maintained.
-* ``x27``: always holds the sandbox base address (must be aligned to the size
+- `x27`: always holds the sandbox base address (must be aligned to the size
of the sandbox).
-* ``x28``: always holds an address within the sandbox.
-* ``sp``: always holds an address within the sandbox.
-* ``x30``: always holds an address within the sandbox.
-* ``x26``: scratch register.
-* ``x25``: context register (see `Context Register`_).
+- `x28`: always holds an address within the sandbox.
+- `sp`: always holds an address within the sandbox.
+- `x30`: always holds an address within the sandbox.
+- `x26`: scratch register.
+- `x25`: context register (see [Context Register]).
The current design only supports 4GiB sandboxes, which requires the sandbox
base address to be 4GiB-aligned. This is because LFI's ABI stores pointers as
@@ -152,28 +141,26 @@ their full 64-bit values, rather than just 32-bit offsets from the base. This
enables stores-only mode, where loads are not sandboxed but stores are, and
allows the host to directly pass pointers to the sandbox.
-Assembly Rewrites
-=================
+### Assembly Rewrites
-Terminology
-~~~~~~~~~~~
+#### Terminology
In the following assembly rewrites, some shorthand is used.
-* ``xN`` or ``wN``: refers to any general-purpose non-reserved register.
-* ``{a,b,c}``: matches any of ``a``, ``b``, or ``c``.
-* ``LDSTr``: a load/store instruction that supports register-register addressing modes, with one source/destination register.
-* ``LDSTx``: a load/store instruction not matched by ``LDSTr``. This covers load/store pairs (``ldp``/``stp``), SIMD load/stores (``ld1``, ``st1``, ...), atomics, exclusives, load/store-release, and unscaled (``ldur``/``stur``) forms. These instructions have a more limited set of addressing modes than ``LDSTr``.
+- `xN` or `wN`: refers to any general-purpose non-reserved register.
+- `{a,b,c}`: matches any of `a`, `b`, or `c`.
+- `LDSTr`: a load/store instruction that supports register-register addressing modes, with one source/destination register.
+- `LDSTx`: a load/store instruction not matched by `LDSTr`. This covers load/store pairs (`ldp`/`stp`), SIMD load/stores (`ld1`, `st1`, ...), atomics, exclusives, load/store-release, and unscaled (`ldur`/`stur`) forms. These instructions have a more limited set of addressing modes than `LDSTr`.
-Control flow
-~~~~~~~~~~~~
+#### Control flow
-Indirect branches get rewritten to branch through register ``x28``, which must
-always contain an address within the sandbox. An ``add`` is used to safely
-update ``x28`` with the destination address. Since ``ret`` uses ``x30`` by
+Indirect branches get rewritten to branch through register `x28`, which must
+always contain an address within the sandbox. An `add` is used to safely
+update `x28` with the destination address. Since `ret` uses `x30` by
default, which already must contain an address within the sandbox, it does not
require any rewrite.
+```{eval-rst}
+--------------------+---------------------------+
| Original | Rewritten |
+--------------------+---------------------------+
@@ -188,15 +175,16 @@ require any rewrite.
| ret | ret |
| | |
+--------------------+---------------------------+
+```
-Memory accesses
-~~~~~~~~~~~~~~~
+#### Memory accesses
-Memory accesses are rewritten to use the ``[x27, wM, uxtw]`` addressing mode if
+Memory accesses are rewritten to use the `[x27, wM, uxtw]` addressing mode if
it is available, which is automatically safe. Otherwise, rewrites fall back to
-using ``x28`` along with an instruction to safely load it with the target
+using `x28` along with an instruction to safely load it with the target
address.
+```{eval-rst}
+---------------------------------+-------------------------------+
| Original | Rewritten |
+---------------------------------+-------------------------------+
@@ -268,13 +256,14 @@ address.
| | add xM1, xM1, xM2 |
| | |
+---------------------------------+-------------------------------+
+```
-Stack pointer modification
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Stack pointer modification
When the stack pointer is modified, we write the modified value to a temporary,
-before moving it back into ``sp`` with a safe ``add``.
+before moving it back into `sp` with a safe `add`.
+```{eval-rst}
+------------------------------+-------------------------------+
| Original | Rewritten |
+------------------------------+-------------------------------+
@@ -289,18 +278,19 @@ before moving it back into ``sp`` with a safe ``add``.
| | add sp, x27, w26, uxtw |
| | |
+------------------------------+-------------------------------+
+```
-Link register modification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Link register modification
When the link register is modified, it is guarded back into the sandbox with a
-safe ``add x30, x27, w30, uxtw``. This guard is deferred until the next
+safe `add x30, x27, w30, uxtw`. This guard is deferred until the next
control-flow instruction rather than emitted immediately after the
modification. Deferral keeps a signed return address intact so that a following
-authentication instruction (such as ``autiasp``) can run before the guard,
+authentication instruction (such as `autiasp`) can run before the guard,
which would otherwise destroy the pointer authentication signature. See
-`Pointer Authentication Code (PAC) support`_.
+[Pointer Authentication Code (PAC) support].
+```{eval-rst}
+---------------------------+-------------------------------+
| Original | Rewritten |
+---------------------------+-------------------------------+
@@ -318,28 +308,29 @@ which would otherwise destroy the pointer authentication signature. See
| | ret |
| | |
+---------------------------+-------------------------------+
+```
-Pointer Authentication Code (PAC) support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Pointer Authentication Code (PAC) support
LFI is compatible with Arm Pointer Authentication Code (PAC) instructions,
-which are used to sign and authenticate ``x30`` to protect against control-flow
+which are used to sign and authenticate `x30` to protect against control-flow
hijacking.
-The typical use is ``-mbranch-protection=pac-ret``, which signs only the return
-address in ``x30`` using the hint-space ``paciasp`` and ``autiasp``
+The typical use is `-mbranch-protection=pac-ret`, which signs only the return
+address in `x30` using the hint-space `paciasp` and `autiasp`
instructions. The combined authenticate-and-branch and authenticate-and-return
instructions covered below require Armv8.3-a and are not produced by
-``-mbranch-protection``. They can appear in hand-written assembly or from
+`-mbranch-protection`. They can appear in hand-written assembly or from
environments that sign all code pointers, so the rewriter still sandboxes them
rather than passing them through unmodified.
To gain the security benefit of PAC under LFI, the hardware must implement
-``FEAT_FPAC``, so that authentication failures fault immediately. Without
-``FEAT_FPAC``, a failed authentication produces a poisoned pointer, which LFI
+`FEAT_FPAC`, so that authentication failures fault immediately. Without
+`FEAT_FPAC`, a failed authentication produces a poisoned pointer, which LFI
still keeps confined to the sandbox by masking it, but the mask overwrites the
poison caused by the authentication failure.
+```{eval-rst}
+-------------------+------------------------------+
| Original | Rewritten |
+-------------------+------------------------------+
@@ -355,10 +346,12 @@ poison caused by the authentication failure.
| | ret |
| | |
+-------------------+------------------------------+
+```
-Authenticated returns (``retaa``/``retab``) combine authentication with return,
+Authenticated returns (`retaa`/`retab`) combine authentication with return,
and must be expanded during rewriting.
+```{eval-rst}
+-----------------+-------------------------------+
| Original | Rewritten |
+-----------------+-------------------------------+
@@ -376,12 +369,14 @@ and must be expanded during rewriting.
| | ret |
| | |
+-----------------+-------------------------------+
+```
-Authenticated branches (``braa``/``brab``/``braaz``/``brabz``) and calls
-(``blraa``/``blrab``/``blraaz``/``blrabz``) combine authentication with an
+Authenticated branches (`braa`/`brab`/`braaz`/`brabz`) and calls
+(`blraa`/`blrab`/`blraaz`/`blrabz`) combine authentication with an
indirect branch or call. They are expanded by first authenticating the target
register in place, then performing a normal sandboxed branch or call.
+```{eval-rst}
+-------------------+-------------------------------+
| Original | Rewritten |
+-------------------+-------------------------------+
@@ -406,19 +401,20 @@ register in place, then performing a normal sandboxed branch or call.
| | blr x28 |
| | |
+-------------------+-------------------------------+
+```
-Authenticated exception returns (``eret``/``eretaa``/``eretab``) are privileged
+Authenticated exception returns (`eret`/`eretaa`/`eretab`) are privileged
and are not supported: the rewriter reports an error for them.
-System instructions
-~~~~~~~~~~~~~~~~~~~
+#### System instructions
System calls are rewritten into a sequence that loads the address of the first
runtime call entrypoint and jumps to it. The runtime call entrypoint table is
stored at a negative offset from the sandbox base, so it can be referenced by
-``x27``. The rewrite also saves and restores the link register, since it is
+`x27`. The rewrite also saves and restores the link register, since it is
used for branching into the runtime.
+```{eval-rst}
+-----------------+------------------------------+
| Original | Rewritten |
+-----------------+------------------------------+
@@ -430,14 +426,15 @@ used for branching into the runtime.
| | add x30, x27, w26, uxtw |
| | |
+-----------------+------------------------------+
+```
-Thread pointer (TP)
-~~~~~~~~~~~~~~~~~~~
+#### Thread pointer (TP)
TP accesses are rewritten into loads/stores from the context register
-(``x25``), which holds the virtual thread pointer at offset 16 (see
-`Context Register`_).
+(`x25`), which holds the virtual thread pointer at offset 16 (see
+[Context Register]).
+```{eval-rst}
+----------------------+-------------------------+
| Original | Rewritten |
+----------------------+-------------------------+
@@ -451,17 +448,17 @@ TP accesses are rewritten into loads/stores from the context register
| msr tpidr_el0, xN | str xN, [x25, #16] |
| | |
+----------------------+-------------------------+
+```
-Optimizations
-=============
+### Optimizations
-Basic guard elimination
-~~~~~~~~~~~~~~~~~~~~~~~
+#### Basic guard elimination
If a register is guarded multiple times in the same basic block without any
modifications to it during the intervening instructions, then subsequent guards
can be removed.
+```{eval-rst}
+---------------------------+---------------------------+
| Original | Rewritten |
+---------------------------+---------------------------+
@@ -475,18 +472,19 @@ can be removed.
| ldur xN, [x28, #16] | |
| | |
+---------------------------+---------------------------+
+```
-Address generation
-~~~~~~~~~~~~~~~~~~
+#### Address generation
**Note**: not yet implemented.
Addresses to global symbols in position-independent executables are frequently
-generated via ``adrp`` followed by ``ldr``. Since the address generated by
-``adrp`` can be statically guaranteed to be within the sandbox, it is safe to
-directly target ``x28`` for these sequences. This allows the omission of a
-guard instruction before the ``ldr``.
+generated via `adrp` followed by `ldr`. Since the address generated by
+`adrp` can be statically guaranteed to be within the sandbox, it is safe to
+directly target `x28` for these sequences. This allows the omission of a
+guard instruction before the `ldr`.
+```{eval-rst}
+----------------------+-----------------------+
| Original | Rewritten |
+----------------------+-----------------------+
@@ -496,9 +494,9 @@ guard instruction before the ``ldr``.
| ldr xN, [xN, imm] | ldr xN, [x28, imm] |
| | |
+----------------------+-----------------------+
+```
-Stack guard elimination
-~~~~~~~~~~~~~~~~~~~~~~~
+#### Stack guard elimination
**Note**: not yet implemented.
@@ -508,6 +506,7 @@ the guard on the stack pointer modification can be removed. This is because the
load/store is guaranteed to trap if the stack pointer has been moved outside of
the sandbox region.
+```{eval-rst}
+---------------------------+---------------------------+
| Original | Rewritten |
+---------------------------+---------------------------+
@@ -519,14 +518,15 @@ the sandbox region.
| ldr xN, [sp] | |
| | |
+---------------------------+---------------------------+
+```
-Guard hoisting
-~~~~~~~~~~~~~~
+#### Guard hoisting
**Note**: not yet implemented.
In certain cases, guards may be hoisted outside of loops.
+```{eval-rst}
+-----------------------+-------------------------------+
| Original | Rewritten |
+-----------------------+-------------------------------+
@@ -543,65 +543,58 @@ In certain cases, guards may be hoisted outside of loops.
| | .end: |
| | |
+-----------------------+-------------------------------+
+```
-X86-64
-++++++
+## X86-64
-The X86-64 LFI target is ``x86_64_lfi``.
+The X86-64 LFI target is `x86_64_lfi`.
-Reserved Registers
-==================
+### Reserved Registers
The X86-64 LFI target reserves the following registers:
-* ``r14``: always holds the sandbox base address. Also used as the runtime call
+- `r14`: always holds the sandbox base address. Also used as the runtime call
table pointer (the runtime call table is stored at the sandbox base).
-* ``gs``: always holds the sandbox base address (used as a segment register for
+- `gs`: always holds the sandbox base address (used as a segment register for
memory access sandboxing).
-* ``rsp``: always holds an address within the sandbox.
-* ``r15``: context register (see `Context Register`_).
-* ``r11``: scratch register.
+- `rsp`: always holds an address within the sandbox.
+- `r15`: context register (see [Context Register]).
+- `r11`: scratch register.
-Assembly Rewrites
-=================
+### Assembly Rewrites
-Terminology
-~~~~~~~~~~~
+#### Terminology
In the following assembly rewrites, some shorthand is used.
-* ``%rN`` or ``%eN``: refers to any general-purpose non-reserved register.
-* ``{a,b,c}``: matches any of ``a``, ``b``, or ``c``.
+- `%rN` or `%eN`: refers to any general-purpose non-reserved register.
+- `{a,b,c}`: matches any of `a`, `b`, or `c`.
-Control flow
-~~~~~~~~~~~~
+#### Control flow
**Note**: these rewrites have not been implemented.
-Memory accesses
-~~~~~~~~~~~~~~~
+#### Memory accesses
**Note**: these rewrites have not been implemented.
-String instructions
-~~~~~~~~~~~~~~~~~~~
+#### String instructions
**Note**: these rewrites have not been implemented.
-Stack modification
-~~~~~~~~~~~~~~~~~~
+#### Stack modification
**Note**: these rewrites have not been implemented.
-System instructions
-~~~~~~~~~~~~~~~~~~~
+#### System instructions
System calls are rewritten into a sequence that loads the return address into
the scratch register and jumps to the runtime call handler. The runtime call
-handler table is stored at the address pointed to by ``r14``. The ``r11``
-register stores the return address (marked by the label ``.Ltmp`` in the
+handler table is stored at the address pointed to by `r14`. The `r11`
+register stores the return address (marked by the label `.Ltmp` in the
block below).
+```{eval-rst}
+-------------------+-------------------------------+
| Original | Rewritten |
+-------------------+-------------------------------+
@@ -612,15 +605,16 @@ block below).
| | .Ltmp: |
| | |
+-------------------+-------------------------------+
+```
-Thread pointer
-~~~~~~~~~~~~~~
+#### Thread pointer
-Thread pointer accesses via the ``%fs`` segment (used for TLS) are rewritten to
-use the virtual thread pointer from the context register (``r15``) at offset 16
-(see `Context Register`_). The rewrite handles any load or store instruction
-with an ``%fs``-segment memory operand. ``Op`` represents any such instruction.
+Thread pointer accesses via the `%fs` segment (used for TLS) are rewritten to
+use the virtual thread pointer from the context register (`r15`) at offset 16
+(see [Context Register]). The rewrite handles any load or store instruction
+with an `%fs`-segment memory operand. `Op` represents any such instruction.
+```{eval-rst}
+--------------------------------------+----------------------------------------+
| Original | Rewritten |
+--------------------------------------+----------------------------------------+
@@ -655,18 +649,19 @@ with an ``%fs``-segment memory operand. ``Op`` represents any such instruction.
| | Op %rS, N(%r11, %rY, S) |
| | |
+--------------------------------------+----------------------------------------+
+```
-References
-++++++++++
+## References
For more information, please see the following resources:
-* `LFI project page <https://github.com/lfi-project/>`__
-* `LFI RFC <https://discourse.llvm.org/t/rfc-lightweight-fault-isolation-lfi-efficient-native-code-sandboxing-upstream-lfi-target-and-compiler-changes/88380>`__
-* `LFI paper <https://zyedidia.github.io/papers/lfi_asplos24.pdf>`__
+- [LFI project page](https://github.com/lfi-project/)
+- [LFI RFC](https://discourse.llvm.org/t/rfc-lightweight-fault-isolation-lfi-efficient-native-code-sandboxing-upstream-lfi-target-and-compiler-changes/88380)
+- [LFI paper](https://zyedidia.github.io/papers/lfi_asplos24.pdf)
Contact info:
-* Zachary Yedidia - zyedidia at cs.stanford.edu
-* Tal Garfinkel - tgarfinkel at google.com
-* Sharjeel Khan - sharjeelkhan at google.com
+- Zachary Yedidia - <mailto:zyedidia at cs.stanford.edu>
+- Tal Garfinkel - <mailto:tgarfinkel at google.com>
+- Sharjeel Khan - <mailto:sharjeelkhan at google.com>
+
diff --git a/llvm/docs/MisExpect.md b/llvm/docs/MisExpect.md
index b0637ea46530d..5c0c7feb3ae81 100644
--- a/llvm/docs/MisExpect.md
+++ b/llvm/docs/MisExpect.md
@@ -1,25 +1,24 @@
-===================
-Misexpect
-===================
+# Misexpect
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+```
-When developers use ``llvm.expect`` intrinsics, i.e., through use of
-``__builtin_expect(...)``, they are trying to communicate how their code is
+When developers use `llvm.expect` intrinsics, i.e., through use of
+`__builtin_expect(...)`, they are trying to communicate how their code is
expected to behave at runtime to the optimizer. These annotations, however, can
be incorrect for a variety of reasons: changes to the code base invalidate them
-silently, the developer mis-annotated them (e.g., using ``LIKELY`` instead of
-``UNLIKELY``), or perhaps they assumed something incorrectly when they wrote
+silently, the developer mis-annotated them (e.g., using `LIKELY` instead of
+`UNLIKELY`), or perhaps they assumed something incorrectly when they wrote
the annotation. Regardless of why, it is useful to detect these situations so
that the optimizer can make more useful decisions about the code. MisExpect
diagnostics are intended to help developers identify and address these
-situations, by comparing the use of the ``llvm.expect`` intrinsic to the ground
+situations, by comparing the use of the `llvm.expect` intrinsic to the ground
truth provided by a profiling input.
The MisExpect checks in the LLVM backend follow a simple procedure: if there is
a mismatch between the branch weights collected during profiling and those
-supplied by an ``llvm.expect`` intrinsic, then it will emit a diagnostic
+supplied by an `llvm.expect` intrinsic, then it will emit a diagnostic
message to the user.
The most natural place to perform the verification is just prior to when
@@ -28,45 +27,39 @@ branch weight metadata.
There are 3 key places in the LLVM backend where branch weights are
created and assigned based on profiling information or the use of the
-``llvm.expect`` intrinsic, and our implementation focuses on these
+`llvm.expect` intrinsic, and our implementation focuses on these
places to perform the verification.
We calculate the threshold for emitting MisExpect related diagnostics
-based on the values the compiler assigns to ``llvm.expect`` intrinsics,
-which can be set through the ``-likely-branch-weight`` and
-``-unlikely-branch-weight`` LLVM options. During verification, if the
+based on the values the compiler assigns to `llvm.expect` intrinsics,
+which can be set through the `-likely-branch-weight` and
+`-unlikely-branch-weight` LLVM options. During verification, if the
profile weights mismatch the calculated threshold, then we will emit a
remark or warning detailing a potential performance regression. The
diagnostic also reports the percentage of the time the annotation was
correct during profiling to help developers reason about how to proceed.
The diagnostics are also available in the form of optimization remarks,
-which can be serialized and processed through the ``opt-viewer.py``
+which can be serialized and processed through the `opt-viewer.py`
scripts in LLVM.
-.. option:: -pass-remarks=misexpect
+:::{option} -pass-remarks=misexpect
+Enables optimization remarks for misexpect when profiling data conflicts with
+use of `llvm.expect` intrinsics.
+:::
- Enables optimization remarks for misexpect when profiling data conflicts with
- use of ``llvm.expect`` intrinsics.
-
-
-.. option:: -pgo-warn-misexpect
-
- Enables misexpect warnings when profiling data conflicts with use of
- ``llvm.expect`` intrinsics.
+:::{option} -pgo-warn-misexpect
+Enables misexpect warnings when profiling data conflicts with use of
+`llvm.expect` intrinsics.
+:::
LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and
Sampling. MisExpect Diagnostics are compatible with all Profiling formats.
-+----------------+--------------------------------------------------------------------------------------+
-| Profile Type | Description |
-+================+======================================================================================+
-| Frontend | Profiling instrumentation added during compilation by the frontend, i.e. ``clang`` |
-+----------------+--------------------------------------------------------------------------------------+
-| IR | Profiling instrumentation added during by the LLVM backend |
-+----------------+--------------------------------------------------------------------------------------+
-| CS-IR | Context Sensitive IR based profiles |
-+----------------+--------------------------------------------------------------------------------------+
-| Sampling | Profiles collected through sampling with external tools, such as ``perf`` on Linux |
-+----------------+--------------------------------------------------------------------------------------+
+| Profile Type | Description |
+| ------------ | -------------------------------------------------------------------------------- |
+| Frontend | Profiling instrumentation added during compilation by the frontend, i.e. `clang` |
+| IR | Profiling instrumentation added during by the LLVM backend |
+| CS-IR | Context Sensitive IR based profiles |
+| Sampling | Profiles collected through sampling with external tools, such as `perf` on Linux |
diff --git a/llvm/docs/OpaquePointers.md b/llvm/docs/OpaquePointers.md
index 533d56c9459dc..4319de96f8582 100644
--- a/llvm/docs/OpaquePointers.md
+++ b/llvm/docs/OpaquePointers.md
@@ -1,18 +1,15 @@
-===============
-Opaque Pointers
-===============
+# Opaque Pointers
-The Opaque Pointer Type
-=======================
+## The Opaque Pointer Type
Traditionally, LLVM IR pointer types have contained a pointee type. For example,
-``i32*`` is a pointer that points to an ``i32`` somewhere in memory. However,
+`i32*` is a pointer that points to an `i32` somewhere in memory. However,
due to a lack of pointee type semantics and various issues with having pointee
types, there is a desire to remove pointee types from pointers.
The opaque pointer type project aims to replace all pointer types containing
pointee types in LLVM with an opaque pointer type. The new pointer type is
-represented textually as ``ptr``.
+represented textually as `ptr`.
Some instructions still need to know what type to treat the memory pointed to by
the pointer as. For example, a load needs to know how many bytes to load from
@@ -20,28 +17,27 @@ memory and what type to treat the resulting value as. In these cases,
instructions themselves contain a type argument. For example the load
instruction from older versions of LLVM
-.. code-block:: llvm
-
- load i64* %p
+```llvm
+load i64* %p
+```
becomes
-.. code-block:: llvm
-
- load i64, ptr %p
+```llvm
+load i64, ptr %p
+```
Address spaces are still used to distinguish between different kinds of pointers
where the distinction is relevant for lowering (e.g. data vs function pointers
have different sizes on some architectures). Opaque pointers are not changing
anything related to address spaces and lowering. For more information, see
-`DataLayout <LangRef.html#langref-datalayout>`_. Opaque pointers in non-default
-address space are spelled ``ptr addrspace(N)``.
+[DataLayout](LangRef.html#langref-datalayout). Opaque pointers in non-default
+address space are spelled `ptr addrspace(N)`.
This was proposed all the way back in
-`2015 <https://lists.llvm.org/pipermail/llvm-dev/2015-February/081822.html>`_.
+[2015](https://lists.llvm.org/pipermail/llvm-dev/2015-February/081822.html).
-Issues with explicit pointee types
-==================================
+## Issues with explicit pointee types
LLVM IR pointers can be cast back and forth between pointers with different
pointee types. The pointee type does not necessarily represent the actual
@@ -55,16 +51,14 @@ languages like C++ adopted LLVM, the community realized that pointee types were
more of a hindrance for LLVM development and that the extra type checking with
some frontends wasn't worth it.
-LLVM's type system was `originally designed
-<https://llvm.org/pubs/2003-05-01-GCCSummit2003.html>`_ to support high-level
+LLVM's type system was [originally designed](https://llvm.org/pubs/2003-05-01-GCCSummit2003.html) to support high-level
optimization. However, years of LLVM implementation experience have demonstrated
that the pointee type system design does not effectively support
optimization. Memory optimization algorithms, such as SROA, GVN, and AA,
generally need to look through LLVM's struct types and reason about the
underlying memory offsets. The community realized that pointee types hinder LLVM
development, rather than helping it. Some of the initially proposed high-level
-optimizations have evolved into `TBAA
-<https://llvm.org/docs/LangRef.html#tbaa-metadata>`_ due to limitations with
+optimizations have evolved into [TBAA](https://llvm.org/docs/LangRef.html#tbaa-metadata) due to limitations with
representing higher-level language information directly via SSA values.
Pointee types provide some value to frontends because the IR verifier uses types
@@ -75,7 +69,7 @@ outweigh the benefits, and that they should be removed.
Many operations do not actually care about the underlying type. These
operations, typically intrinsics, usually end up taking an arbitrary pointer
-type ``i8*`` and sometimes a size. This causes lots of redundant no-op bitcasts
+type `i8*` and sometimes a size. This causes lots of redundant no-op bitcasts
in the IR to and from a pointer with a different pointee type.
No-op bitcasts take up memory/disk space and also take up compile time to look
@@ -100,43 +94,41 @@ integer types and ran into similar issues of no-op casts. The transition from
manifesting signedness in types to instructions happened early on in LLVM's
timeline to make LLVM easier to work with.
-Opaque Pointers Mode
-====================
+## Opaque Pointers Mode
During the transition phase, LLVM can be used in two modes: In typed pointer
mode all pointer types have a pointee type and opaque pointers cannot be used.
In opaque pointers mode (the default), all pointers are opaque. The opaque
-pointer mode can be disabled using ``-opaque-pointers=0`` in
-LLVM tools like ``opt``, or ``-Xclang -no-opaque-pointers`` in clang.
+pointer mode can be disabled using `-opaque-pointers=0` in
+LLVM tools like `opt`, or `-Xclang -no-opaque-pointers` in clang.
Additionally, opaque pointer mode is automatically disabled for IR and bitcode
-files that explicitly mention ``i8*`` style typed pointers.
+files that explicitly mention `i8*` style typed pointers.
In opaque pointer mode, all typed pointers used in IR, bitcode, or created
-using ``PointerType::get()`` and similar APIs are automatically converted into
+using `PointerType::get()` and similar APIs are automatically converted into
opaque pointers. This simplifies migration and allows testing existing IR with
opaque pointers.
-.. code-block:: llvm
-
- define i8* @test(i8* %p) {
- %p2 = getelementptr i8, i8* %p, i64 1
- ret i8* %p2
- }
+```llvm
+define i8* @test(i8* %p) {
+ %p2 = getelementptr i8, i8* %p, i64 1
+ ret i8* %p2
+}
- ; Is automatically converted into the following if -opaque-pointers
- ; is enabled:
+; Is automatically converted into the following if -opaque-pointers
+; is enabled:
- define ptr @test(ptr %p) {
- %p2 = getelementptr i8, ptr %p, i64 1
- ret ptr %p2
- }
+define ptr @test(ptr %p) {
+ %p2 = getelementptr i8, ptr %p, i64 1
+ ret ptr %p2
+}
+```
-Migration Instructions
-======================
+## Migration Instructions
In order to support opaque pointers, two types of changes tend to be necessary.
-The first is the removal of all calls to ``PointerType::getElementType()`` and
-``Type::getPointerElementType()``.
+The first is the removal of all calls to `PointerType::getElementType()` and
+`Type::getPointerElementType()`.
In the LLVM middle-end and backend, this is usually accomplished by inspecting
the type of relevant operations instead. For example, memory access related
@@ -145,35 +137,35 @@ instructions instead of querying the pointer type.
Here are some common ways to avoid pointer element type accesses:
-* For loads, use ``getType()``.
-* For stores, use ``getValueOperand()->getType()``.
-* Use ``getLoadStoreType()`` to handle both of the above in one call.
-* For getelementptr instructions, use ``getSourceElementType()``.
-* For calls, use ``getFunctionType()``.
-* For allocas, use ``getAllocatedType()``.
-* For globals, use ``getValueType()``.
-* For consistency assertions, use
- ``PointerType::isOpaqueOrPointeeTypeEquals()``.
-* To create a pointer type in a different address space, use
- ``PointerType::getWithSamePointeeType()``.
-* To check that two pointers have the same element type, use
- ``PointerType::hasSameElementTypeAs()``.
-* While it is preferred to write code in a way that accepts both typed and
- opaque pointers, ``Type::isOpaquePointerTy()`` and
- ``PointerType::isOpaque()`` can be used to handle opaque pointers specially.
- ``PointerType::getNonOpaquePointerElementType()`` can be used as a marker in
+- For loads, use `getType()`.
+- For stores, use `getValueOperand()->getType()`.
+- Use `getLoadStoreType()` to handle both of the above in one call.
+- For getelementptr instructions, use `getSourceElementType()`.
+- For calls, use `getFunctionType()`.
+- For allocas, use `getAllocatedType()`.
+- For globals, use `getValueType()`.
+- For consistency assertions, use
+ `PointerType::isOpaqueOrPointeeTypeEquals()`.
+- To create a pointer type in a different address space, use
+ `PointerType::getWithSamePointeeType()`.
+- To check that two pointers have the same element type, use
+ `PointerType::hasSameElementTypeAs()`.
+- While it is preferred to write code in a way that accepts both typed and
+ opaque pointers, `Type::isOpaquePointerTy()` and
+ `PointerType::isOpaque()` can be used to handle opaque pointers specially.
+ `PointerType::getNonOpaquePointerElementType()` can be used as a marker in
code-paths where opaque pointers have been explicitly excluded.
-* To get the type of a byval argument, use ``getParamByValType()``. Similar
+- To get the type of a byval argument, use `getParamByValType()`. Similar
method exists for other ABI-affecting attributes that need to know the
element type, such as byref, sret, inalloca and preallocated.
-* Some intrinsics require an ``elementtype`` attribute, which can be retrieved
- using ``getParamElementType()``. This attribute is required in cases where
+- Some intrinsics require an `elementtype` attribute, which can be retrieved
+ using `getParamElementType()`. This attribute is required in cases where
the intrinsic does not naturally encode a needed element type. This is also
used for inline assembly.
Note that some of the methods mentioned above only exist to support both typed
and opaque pointers at the same time, and will be dropped once the migration
-has completed. For example, ``isOpaqueOrPointeeTypeEquals()`` becomes
+has completed. For example, `isOpaqueOrPointeeTypeEquals()` becomes
meaningless once all pointers are opaque.
While direct usage of pointer element types is immediately apparent in code,
@@ -182,20 +174,20 @@ of code assumes that pointer equality also implies that the used load/store
type or GEP source element type is the same. Consider the following examples
with typed and opaque pointers:
-.. code-block:: llvm
-
- define i32 @test(i32* %p) {
- store i32 0, i32* %p
- %bc = bitcast i32* %p to i64*
- %v = load i64, i64* %bc
- ret i64 %v
- }
-
- define i32 @test(ptr %p) {
- store i32 0, ptr %p
- %v = load i64, ptr %p
- ret i64 %v
- }
+```llvm
+define i32 @test(i32* %p) {
+ store i32 0, i32* %p
+ %bc = bitcast i32* %p to i64*
+ %v = load i64, i64* %bc
+ ret i64 %v
+}
+
+define i32 @test(ptr %p) {
+ store i32 0, ptr %p
+ %v = load i64, ptr %p
+ ret i64 %v
+}
+```
Without opaque pointers, a check that the pointer operand of the load and
store are the same also ensures that the accessed type is the same. Using a
@@ -206,61 +198,60 @@ With opaque pointers, the bitcast is not present, and this check is no longer
sufficient. In the above example, it could result in store to load forwarding
of an incorrect type. Code making such assumptions needs to be adjusted to
check the accessed type explicitly:
-``LI->getType() == SI->getValueOperand()->getType()``.
+`LI->getType() == SI->getValueOperand()->getType()`.
-Frontends
----------
+### Frontends
Frontends need to be adjusted to track pointee types independently of LLVM,
insofar as they are necessary for lowering. For example, clang now tracks the
-pointee type in the ``Address`` structure.
+pointee type in the `Address` structure.
Frontends using the C API through an FFI interface should be aware that a
number of C API functions are deprecated and will be removed as part of the
-opaque pointer transition::
-
- LLVMBuildLoad -> LLVMBuildLoad2
- LLVMBuildCall -> LLVMBuildCall2
- LLVMBuildInvoke -> LLVMBuildInvoke2
- LLVMBuildGEP -> LLVMBuildGEP2
- LLVMBuildInBoundsGEP -> LLVMBuildInBoundsGEP2
- LLVMBuildStructGEP -> LLVMBuildStructGEP2
- LLVMBuildPtrDiff -> LLVMBuildPtrDiff2
- LLVMConstGEP -> LLVMConstGEP2
- LLVMConstInBoundsGEP -> LLVMConstInBoundsGEP2
- LLVMAddAlias -> LLVMAddAlias2
-
-Additionally, it will no longer be possible to call ``LLVMGetElementType()``
+opaque pointer transition:
+
+```
+LLVMBuildLoad -> LLVMBuildLoad2
+LLVMBuildCall -> LLVMBuildCall2
+LLVMBuildInvoke -> LLVMBuildInvoke2
+LLVMBuildGEP -> LLVMBuildGEP2
+LLVMBuildInBoundsGEP -> LLVMBuildInBoundsGEP2
+LLVMBuildStructGEP -> LLVMBuildStructGEP2
+LLVMBuildPtrDiff -> LLVMBuildPtrDiff2
+LLVMConstGEP -> LLVMConstGEP2
+LLVMConstInBoundsGEP -> LLVMConstInBoundsGEP2
+LLVMAddAlias -> LLVMAddAlias2
+```
+
+Additionally, it will no longer be possible to call `LLVMGetElementType()`
on a pointer type.
It is possible to control whether opaque pointers are used (if you want to
-override the default) using ``LLVMContext::setOpaquePointers``.
+override the default) using `LLVMContext::setOpaquePointers`.
-Temporarily disabling opaque pointers
-=====================================
+## Temporarily disabling opaque pointers
In LLVM 15, opaque pointers are enabled by default, but it it still possible to
use typed pointers using a number of opt-in flags.
For users of the clang driver interface, it is possible to temporarily restore
-the old default using the ``-DCLANG_ENABLE_OPAQUE_POINTERS=OFF`` cmake option,
-or by passing ``-Xclang -no-opaque-pointers`` to a single clang invocation.
+the old default using the `-DCLANG_ENABLE_OPAQUE_POINTERS=OFF` cmake option,
+or by passing `-Xclang -no-opaque-pointers` to a single clang invocation.
-For users of the clang cc1 interface, ``-no-opaque-pointers`` can be passed.
-Note that the ``CLANG_ENABLE_OPAQUE_POINTERS`` cmake option has no effect on
+For users of the clang cc1 interface, `-no-opaque-pointers` can be passed.
+Note that the `CLANG_ENABLE_OPAQUE_POINTERS` cmake option has no effect on
the cc1 interface.
-Usage for LTO can be disabled by passing ``-Wl,-plugin-opt=no-opaque-pointers``
+Usage for LTO can be disabled by passing `-Wl,-plugin-opt=no-opaque-pointers`
to the clang driver.
For users of LLVM as a library, opaque pointers can be disabled by calling
-``setOpaquePointers(false)`` on the ``LLVMContext``.
+`setOpaquePointers(false)` on the `LLVMContext`.
For users of LLVM tools like opt, opaque pointers can be disabled by passing
-``-opaque-pointers=0``.
+`-opaque-pointers=0`.
-Version Support
-===============
+## Version Support
**LLVM 14:** Supports all necessary APIs for migrating to opaque pointers and deprecates/removes incompatible APIs. However, using opaque pointers in the optimization pipeline is **not** fully supported. This release can be used to make out-of-tree code compatible with opaque pointers, but opaque pointers should **not** be enabled in production.
@@ -273,22 +264,22 @@ supported on a best-effort basis only and not tested.
**LLVM 17:** Only opaque pointers are supported. Typed pointers are not
supported.
-Transition State
-================
+## Transition State
As of July 2023:
-Typed pointers are **not** supported on the ``main`` branch.
+Typed pointers are **not** supported on the `main` branch.
The following typed pointer functionality has been removed:
-* The ``CLANG_ENABLE_OPAQUE_POINTERS`` cmake flag is no longer supported.
-* The ``-no-opaque-pointers`` cc1 clang flag is no longer supported.
-* The ``-opaque-pointers`` opt flag is no longer supported.
-* The ``-plugin-opt=no-opaque-pointers`` LTO flag is no longer supported.
-* C APIs that do not support opaque pointers (like ``LLVMBuildLoad``) are no
+- The `CLANG_ENABLE_OPAQUE_POINTERS` cmake flag is no longer supported.
+- The `-no-opaque-pointers` cc1 clang flag is no longer supported.
+- The `-opaque-pointers` opt flag is no longer supported.
+- The `-plugin-opt=no-opaque-pointers` LTO flag is no longer supported.
+- C APIs that do not support opaque pointers (like `LLVMBuildLoad`) are no
longer supported.
The following typed pointer functionality is still to be removed:
-* Various APIs that are no longer relevant with opaque pointers.
+- Various APIs that are no longer relevant with opaque pointers.
+
diff --git a/llvm/docs/OptBisect.md b/llvm/docs/OptBisect.md
index 7eee52ff1c0d6..26c79ac917dd2 100644
--- a/llvm/docs/OptBisect.md
+++ b/llvm/docs/OptBisect.md
@@ -1,85 +1,79 @@
-====================================================
-Using -opt-bisect-limit to debug optimization errors
-====================================================
+# Using -opt-bisect-limit to debug optimization errors
-Introduction
-============
+## Introduction
-The ``-opt-bisect-limit`` option provides a way to disable all optimization passes
+The `-opt-bisect-limit` option provides a way to disable all optimization passes
above a specified limit without modifying the way in which the Pass Managers
-are populated. The intention of this option is to assist in tracking down
+are populated. The intention of this option is to assist in tracking down
problems where incorrect transformations during optimization result in incorrect
run-time behavior.
-This feature is implemented on an opt-in basis. Passes which can be safely
+This feature is implemented on an opt-in basis. Passes which can be safely
skipped while still allowing correct code generation call a function to
-check the opt-bisect limit before performing optimizations. Passes which
+check the opt-bisect limit before performing optimizations. Passes which
either must be run or do not modify the IR do not perform this check and are
-therefore never skipped. Generally, this means analysis passes, passes
-that are run at ``CodeGenOptLevel::None`` and passes which are required for register
+therefore never skipped. Generally, this means analysis passes, passes
+that are run at `CodeGenOptLevel::None` and passes which are required for register
allocation.
-The ``-opt-bisect-limit`` option can be used with any tool, including front ends
+The `-opt-bisect-limit` option can be used with any tool, including front ends
such as clang, that uses the core LLVM library for optimization and code
-generation. The exact syntax for invoking the option is discussed below. This
-makes ``-opt-bisect-limit`` easy to use in situations that require complex
+generation. The exact syntax for invoking the option is discussed below. This
+makes `-opt-bisect-limit` easy to use in situations that require complex
build infrastructure or when a full pass pipeline is needed that is difficult
to replace in opt or llc.
+## Getting Started
-Getting Started
-===============
+The `-opt-bisect-limit` command-line option can be passed directly to tools such
+as opt, llc and lli. The syntax is as follows:
-The ``-opt-bisect-limit`` command-line option can be passed directly to tools such
-as opt, llc and lli. The syntax is as follows:
-
-::
-
- <tool name> [other options] -opt-bisect-limit=<limit>
+```
+<tool name> [other options] -opt-bisect-limit=<limit>
+```
If a value of -1 is used the tool will perform all optimizations but a message
will be printed to stderr for each optimization that could be skipped
-indicating the index value that is associated with that optimization. To skip
+indicating the index value that is associated with that optimization. To skip
optimizations, pass the value of the last optimization to be performed as the
-opt-bisect-limit. All optimizations with a higher index value will be skipped.
+opt-bisect-limit. All optimizations with a higher index value will be skipped.
-In order to use the ``-opt-bisect-limit`` option with a driver that provides a
+In order to use the `-opt-bisect-limit` option with a driver that provides a
wrapper around the LLVM core library, an additional prefix option may be
-required, as defined by the driver. For example, to use this option with
-clang, the ``-mllvm`` prefix must be used. A typical clang invocation would look
+required, as defined by the driver. For example, to use this option with
+clang, the `-mllvm` prefix must be used. A typical clang invocation would look
like this:
-::
+```
+clang -O2 -mllvm -opt-bisect-limit=256 my_file.c
+```
- clang -O2 -mllvm -opt-bisect-limit=256 my_file.c
-
-The ``-opt-bisect-limit`` option may also be applied to link-time optimizations by
+The `-opt-bisect-limit` option may also be applied to link-time optimizations by
using a prefix to indicate that this is a plug-in option for the linker. The
following syntax will set a bisect limit for LTO transformations:
-::
-
- # When using lld, or ld64 (macOS)
- clang -flto -Wl,-mllvm,-opt-bisect-limit=256 my_file.o my_other_file.o
- # When using Gold
- clang -flto -Wl,-plugin-opt,-opt-bisect-limit=256 my_file.o my_other_file.o
+```
+# When using lld, or ld64 (macOS)
+clang -flto -Wl,-mllvm,-opt-bisect-limit=256 my_file.o my_other_file.o
+# When using Gold
+clang -flto -Wl,-plugin-opt,-opt-bisect-limit=256 my_file.o my_other_file.o
+```
LTO passes are run by a library instance invoked by the linker. Therefore any
passes run in the primary driver compilation phase are not affected by options
-passed via ``-Wl,-plugin-opt`` and LTO passes are not affected by options
-passed to the driver-invoked LLVM invocation via ``-mllvm``.
+passed via `-Wl,-plugin-opt` and LTO passes are not affected by options
+passed to the driver-invoked LLVM invocation via `-mllvm`.
-Passing ``-opt-bisect-print-ir-path=path/foo.ll`` will dump the IR to
-``path/foo.ll`` when ``-opt-bisect-limit`` starts skipping passes.
+Passing `-opt-bisect-print-ir-path=path/foo.ll` will dump the IR to
+`path/foo.ll` when `-opt-bisect-limit` starts skipping passes.
-Bisection Index Values
-======================
+## Bisection Index Values
The granularity of the optimizations associated with a single index value is
-variable. Depending on how the optimization pass has been instrumented the
+variable. Depending on how the optimization pass has been instrumented the
value may be associated with as much as all transformations that would have
been performed by an optimization pass on an IR unit for which it is invoked
-(for instance, during a single call of ``runOnFunction`` for a ``FunctionPass``) or as
+(for instance, during a single call of `runOnFunction` for a `FunctionPass`) or as
little as a single transformation. The index values may also be nested so that
if an invocation of the pass is not skipped individual transformations within
that invocation may still be skipped.
@@ -93,7 +87,7 @@ is not a problem.
When an opt-bisect index value refers to an entire invocation of the run
function for a pass, the pass will query whether or not it should be skipped
each time it is invoked and each invocation will be assigned a unique value.
-For example, if a ``FunctionPass`` is used with a module containing three functions
+For example, if a `FunctionPass` is used with a module containing three functions
a different index value will be assigned to the pass for each of the functions
as the pass is run. The pass may be run on two functions but skipped for the
third.
@@ -102,86 +96,81 @@ If the pass internally performs operations on a smaller IR unit the pass must be
specifically instrumented to enable bisection at this finer level of granularity
(see below for details).
-
-Example Usage
-=============
-
-.. code-block:: console
-
- $ opt -O2 -o test-opt.bc -opt-bisect-limit=16 test.ll
-
- BISECT: running pass (1) Simplify the CFG on function (g)
- BISECT: running pass (2) SROA on function (g)
- BISECT: running pass (3) Early CSE on function (g)
- BISECT: running pass (4) Infer set function attributes on module (test.ll)
- BISECT: running pass (5) Interprocedural Sparse Conditional Constant Propagation on module (test.ll)
- BISECT: running pass (6) Global Variable Optimizer on module (test.ll)
- BISECT: running pass (7) Promote Memory to Register on function (g)
- BISECT: running pass (8) Dead Argument Elimination on module (test.ll)
- BISECT: running pass (9) Combine redundant instructions on function (g)
- BISECT: running pass (10) Simplify the CFG on function (g)
- BISECT: running pass (11) Remove unused exception handling info on SCC (<<null function>>)
- BISECT: running pass (12) Function Integration/Inlining on SCC (<<null function>>)
- BISECT: running pass (13) Deduce function attributes on SCC (<<null function>>)
- BISECT: running pass (14) Remove unused exception handling info on SCC (f)
- BISECT: running pass (15) Function Integration/Inlining on SCC (f)
- BISECT: running pass (16) Deduce function attributes on SCC (f)
- BISECT: NOT running pass (17) Remove unused exception handling info on SCC (g)
- BISECT: NOT running pass (18) Function Integration/Inlining on SCC (g)
- BISECT: NOT running pass (19) Deduce function attributes on SCC (g)
- BISECT: NOT running pass (20) SROA on function (g)
- BISECT: NOT running pass (21) Early CSE on function (g)
- BISECT: NOT running pass (22) Speculatively execute instructions if target has divergent branches on function (g)
- ... etc. ...
-
-
-Pass Skipping Implementation
-============================
-
-The ``-opt-bisect-limit`` implementation depends on individual passes opting in to
-the opt-bisect process. The ``OptBisect`` object that manages the process is
-entirely passive and has no knowledge of how any pass is implemented. When a
-pass is run if the pass may be skipped, it should call the ``OptBisect`` object to
+## Example Usage
+
+```console
+$ opt -O2 -o test-opt.bc -opt-bisect-limit=16 test.ll
+
+BISECT: running pass (1) Simplify the CFG on function (g)
+BISECT: running pass (2) SROA on function (g)
+BISECT: running pass (3) Early CSE on function (g)
+BISECT: running pass (4) Infer set function attributes on module (test.ll)
+BISECT: running pass (5) Interprocedural Sparse Conditional Constant Propagation on module (test.ll)
+BISECT: running pass (6) Global Variable Optimizer on module (test.ll)
+BISECT: running pass (7) Promote Memory to Register on function (g)
+BISECT: running pass (8) Dead Argument Elimination on module (test.ll)
+BISECT: running pass (9) Combine redundant instructions on function (g)
+BISECT: running pass (10) Simplify the CFG on function (g)
+BISECT: running pass (11) Remove unused exception handling info on SCC (<<null function>>)
+BISECT: running pass (12) Function Integration/Inlining on SCC (<<null function>>)
+BISECT: running pass (13) Deduce function attributes on SCC (<<null function>>)
+BISECT: running pass (14) Remove unused exception handling info on SCC (f)
+BISECT: running pass (15) Function Integration/Inlining on SCC (f)
+BISECT: running pass (16) Deduce function attributes on SCC (f)
+BISECT: NOT running pass (17) Remove unused exception handling info on SCC (g)
+BISECT: NOT running pass (18) Function Integration/Inlining on SCC (g)
+BISECT: NOT running pass (19) Deduce function attributes on SCC (g)
+BISECT: NOT running pass (20) SROA on function (g)
+BISECT: NOT running pass (21) Early CSE on function (g)
+BISECT: NOT running pass (22) Speculatively execute instructions if target has divergent branches on function (g)
+... etc. ...
+```
+
+## Pass Skipping Implementation
+
+The `-opt-bisect-limit` implementation depends on individual passes opting in to
+the opt-bisect process. The `OptBisect` object that manages the process is
+entirely passive and has no knowledge of how any pass is implemented. When a
+pass is run if the pass may be skipped, it should call the `OptBisect` object to
see if it should be skipped.
-The ``OptBisect`` object is intended to be accessed through ``LLVMContext`` and each
+The `OptBisect` object is intended to be accessed through `LLVMContext` and each
Pass base class contains a helper function that abstracts the details in order
-to make this check uniform across all passes. These helper functions are:
-
-.. code-block:: c++
-
- bool ModulePass::skipModule(Module &M);
- bool FunctionPass::skipFunction(const Function &F);
- bool LoopPass::skipLoop(const Loop *L);
-
-A ``MachineFunctionPass`` should use ``FunctionPass::skipFunction()`` as such:
-
-.. code-block:: c++
-
- bool MyMachineFunctionPass::runOnMachineFunction(Function &MF) {
- if (skipFunction(*MF.getFunction())
- return false;
- // Otherwise, run the pass normally.
- }
-
-In addition to checking with the ``OptBisect`` class to see if the pass should be
-skipped, the ``skipFunction()``, ``skipLoop()`` and ``skipBasicBlock()`` helper functions
-also look for the presence of the ``optnone`` function attribute. The calling
+to make this check uniform across all passes. These helper functions are:
+
+```c++
+bool ModulePass::skipModule(Module &M);
+bool FunctionPass::skipFunction(const Function &F);
+bool LoopPass::skipLoop(const Loop *L);
+```
+
+A `MachineFunctionPass` should use `FunctionPass::skipFunction()` as such:
+
+```c++
+bool MyMachineFunctionPass::runOnMachineFunction(Function &MF) {
+ if (skipFunction(*MF.getFunction())
+ return false;
+ // Otherwise, run the pass normally.
+}
+```
+
+In addition to checking with the `OptBisect` class to see if the pass should be
+skipped, the `skipFunction()`, `skipLoop()` and `skipBasicBlock()` helper functions
+also look for the presence of the `optnone` function attribute. The calling
pass will be unable to determine whether it is being skipped because the
-``optnone`` attribute is present or because the ``opt-bisect-limit`` has been
-reached. This is desirable because the behavior should be the same in either
+`optnone` attribute is present or because the `opt-bisect-limit` has been
+reached. This is desirable because the behavior should be the same in either
case.
The majority of LLVM passes which can be skipped have already been instrumented
-in the manner described above. If you are adding a new pass or believe you
+in the manner described above. If you are adding a new pass or believe you
have found a pass which is not being included in the opt-bisect process but
should be, you can add it as described above.
-
-Adding Finer Granularity
-========================
+## Adding Finer Granularity
Once the pass in which an incorrect transformation is performed has been
determined, it may be useful to perform further analysis in order to determine
-which specific transformation is causing the problem. Debug counters
+which specific transformation is causing the problem. Debug counters
can be used for this purpose.
+
diff --git a/llvm/docs/PDB/index.md b/llvm/docs/PDB/index.md
index 0be9363bdd16a..8f83867f4edcb 100644
--- a/llvm/docs/PDB/index.md
+++ b/llvm/docs/PDB/index.md
@@ -1,170 +1,155 @@
-=====================================
-The PDB File Format
-=====================================
+# The PDB File Format
+(pdb-intro)=
-.. _pdb_intro:
-
-Introduction
-============
+## Introduction
PDB (Program Database) is a file format invented by Microsoft and which contains
-debug information that can be consumed by debuggers and other tools. Since
+debug information that can be consumed by debuggers and other tools. Since
officially supported APIs exist on Windows for querying debug information from
PDBs even without the user understanding the internals of the file format, a
-large ecosystem of tools has been built for Windows to consume this format. In
+large ecosystem of tools has been built for Windows to consume this format. In
order for Clang to be able to generate programs that can interoperate with these
tools, it is necessary for us to generate PDB files ourselves.
At the same time, LLVM has a long history of being able to cross-compile from
-any platform to any platform, and we wish for the same to be true here. So it
+any platform to any platform, and we wish for the same to be true here. So it
is necessary for us to understand the PDB file format at the byte-level so that
we can generate PDB files entirely on our own.
-This manual describes what we know about the PDB file format today. The layout
+This manual describes what we know about the PDB file format today. The layout
of the file, the various streams contained within, the format of individual
records within, and more.
We would like to extend our heartfelt gratitude to Microsoft, without whom we
-would not be where we are today. Much of the knowledge contained within this
-manual was learned through reading code published by Microsoft on their `GitHub
-repo <https://github.com/Microsoft/microsoft-pdb>`__.
-
-For more documentation, see Microsoft's `pdb-rs GitHub repo
-<https://github.com/microsoft/pdb-rs/blob/main/docs/index.md>`__.
-
-.. _pdb_layout:
-
-File Layout
-===========
-
-.. important::
- Unless otherwise specified, all numeric values are encoded in little endian.
- If you see a type such as ``uint16_t`` or ``uint64_t`` going forward, always
- assume it is little endian!
-
-.. toctree::
- :hidden:
-
- MsfFile
- PdbStream
- TpiStream
- DbiStream
- ModiStream
- PublicStream
- GlobalStream
- HashTable
- CodeViewSymbols
- CodeViewTypes
-
-.. _msf:
-
-The MSF Container
------------------
-A PDB file is an MSF (Multi-Stream Format) file. An MSF file is a "file system
-within a file". It contains multiple streams (aka files) which can represent
+would not be where we are today. Much of the knowledge contained within this
+manual was learned through reading code published by Microsoft on their [GitHub
+repo](https://github.com/Microsoft/microsoft-pdb).
+
+For more documentation, see Microsoft's [pdb-rs GitHub repo](https://github.com/microsoft/pdb-rs/blob/main/docs/index.md).
+
+(pdb-layout)=
+
+## File Layout
+
+:::{important}
+Unless otherwise specified, all numeric values are encoded in little endian.
+If you see a type such as `uint16_t` or `uint64_t` going forward, always
+assume it is little endian!
+:::
+
+```{toctree}
+:hidden: true
+
+MsfFile
+PdbStream
+TpiStream
+DbiStream
+ModiStream
+PublicStream
+GlobalStream
+HashTable
+CodeViewSymbols
+CodeViewTypes
+```
+
+(msf)=
+
+### The MSF Container
+
+A PDB file is an MSF (Multi-Stream Format) file. An MSF file is a "file system
+within a file". It contains multiple streams (aka files) which can represent
arbitrary data, and these streams are divided into blocks which may not
necessarily be contiguously laid out within the MSF container file.
Additionally, the MSF contains a stream directory (aka MFT) which describes how
the streams (files) are laid out within the MSF.
For more information about the MSF container format, stream directory, and
-block layout, see :doc:`MsfFile`.
+block layout, see {doc}`MsfFile`.
-.. _streams:
+(streams)=
+
+### Streams
-Streams
--------
The PDB format contains a number of streams which describe various information
such as the types, symbols, source files, and compilands (e.g. object files)
of a program, as well as some additional streams containing hash tables that are
used by debuggers and other tools to provide fast lookup of records and types
by name, and various other information about how the program was compiled such
-as the specific toolchain used, and more. A summary of streams contained in a
+as the specific toolchain used, and more. A summary of streams contained in a
PDB file is as follows:
-+--------------------+------------------------------+-------------------------------------------+
-| Name | Stream Index | Contents |
-+====================+==============================+===========================================+
-| Old Directory | - Fixed Stream Index 0 | - Previous MSF Stream Directory |
-+--------------------+------------------------------+-------------------------------------------+
-| PDB Stream | - Fixed Stream Index 1 | - Basic File Information |
-| | | - Fields to match EXE to this PDB |
-| | | - Map of named streams to stream indices |
-+--------------------+------------------------------+-------------------------------------------+
-| TPI Stream | - Fixed Stream Index 2 | - CodeView Type Records |
-| | | - Index of TPI Hash Stream |
-+--------------------+------------------------------+-------------------------------------------+
-| DBI Stream | - Fixed Stream Index 3 | - Module/Compiland Information |
-| | | - Indices of individual module streams |
-| | | - Indices of public / global streams |
-| | | - Section Contribution Information |
-| | | - Source File Information |
-| | | - References to streams containing |
-| | | FPO / PGO Data |
-+--------------------+------------------------------+-------------------------------------------+
-| IPI Stream | - Fixed Stream Index 4 | - CodeView Type Records |
-| | | - Index of IPI Hash Stream |
-+--------------------+------------------------------+-------------------------------------------+
-| /LinkInfo | - Contained in PDB Stream | - Unknown |
-| | Named Stream map | |
-+--------------------+------------------------------+-------------------------------------------+
-| /src/headerblock | - Contained in PDB Stream | - Summary of embedded source file content |
-| | Named Stream map | (e.g. natvis files) |
-+--------------------+------------------------------+-------------------------------------------+
-| /names | - Contained in PDB Stream | - PDB-wide global string table used for |
-| | Named Stream map | string de-duplication |
-+--------------------+------------------------------+-------------------------------------------+
-| Module Info Stream | - Contained in DBI Stream | - CodeView Symbol Records for this module |
-| | - One for each compiland | - Line Number Information |
-+--------------------+------------------------------+-------------------------------------------+
-| Public Stream | - Contained in DBI Stream | - Public (Exported) Symbol Records |
-| | | - Index of Public Hash Stream |
-+--------------------+------------------------------+-------------------------------------------+
-| Global Stream | - Contained in DBI Stream | - Single combined symbol-table |
-| | | - Index of Global Hash Stream |
-+--------------------+------------------------------+-------------------------------------------+
-| TPI Hash Stream | - Contained in TPI Stream | - Hash table for looking up TPI records |
-| | | by name |
-+--------------------+------------------------------+-------------------------------------------+
-| IPI Hash Stream | - Contained in IPI Stream | - Hash table for looking up IPI records |
-| | | by name |
-+--------------------+------------------------------+-------------------------------------------+
+| Name | Stream Index | Contents |
+| ------------------ | ------------------------------------------ | ------------------------------------------------------------- |
+| Old Directory | - Fixed Stream Index 0 | - Previous MSF Stream Directory |
+| PDB Stream | - Fixed Stream Index 1 | - Basic File Information
+- Fields to match EXE to this PDB
+- Map of named streams to stream indices |
+| TPI Stream | - Fixed Stream Index 2 | - CodeView Type Records
+- Index of TPI Hash Stream |
+| DBI Stream | - Fixed Stream Index 3 | - Module/Compiland Information
+- Indices of individual module streams
+- Indices of public / global streams
+- Section Contribution Information
+- Source File Information
+- References to streams containing FPO / PGO Data |
+| IPI Stream | - Fixed Stream Index 4 | - CodeView Type Records
+- Index of IPI Hash Stream |
+| /LinkInfo | - Contained in PDB Stream Named Stream map | - Unknown |
+| /src/headerblock | - Contained in PDB Stream Named Stream map | - Summary of embedded source file content (e.g. natvis files) |
+| /names | - Contained in PDB Stream Named Stream map | - PDB-wide global string table used for string de-duplication |
+| Module Info Stream | - Contained in DBI Stream
+- One for each compiland | - CodeView Symbol Records for this module
+- Line Number Information |
+| Public Stream | - Contained in DBI Stream | - Public (Exported) Symbol Records
+- Index of Public Hash Stream |
+| Global Stream | - Contained in DBI Stream | - Single combined symbol-table
+- Index of Global Hash Stream |
+| TPI Hash Stream | - Contained in TPI Stream | - Hash table for looking up TPI records by name |
+| IPI Hash Stream | - Contained in IPI Stream | - Hash table for looking up IPI records by name |
More information about the structure of each of these can be found on the
following pages:
-:doc:`PdbStream`
- Information about the PDB Info Stream and how it is used to match PDBs to EXEs.
+{doc}`PdbStream`
+
+: Information about the PDB Info Stream and how it is used to match PDBs to EXEs.
+
+{doc}`TpiStream`
+
+: Information about the TPI stream and the CodeView records contained within.
+
+{doc}`DbiStream`
-:doc:`TpiStream`
- Information about the TPI stream and the CodeView records contained within.
+: Information about the DBI stream and relevant substreams including the
+ Module Substreams, source file information, and CodeView symbol records
+ contained within.
-:doc:`DbiStream`
- Information about the DBI stream and relevant substreams including the
- Module Substreams, source file information, and CodeView symbol records
- contained within.
+{doc}`ModiStream`
-:doc:`ModiStream`
- Information about the Module Information Stream, of which there is one for
- each compilation unit and the format of symbols contained within.
+: Information about the Module Information Stream, of which there is one for
+ each compilation unit and the format of symbols contained within.
-:doc:`PublicStream`
- Information about the Public Symbol Stream.
+{doc}`PublicStream`
-:doc:`GlobalStream`
- Information about the Global Symbol Stream.
+: Information about the Public Symbol Stream.
-:doc:`HashTable`
- Information about the serialized hash table format used internally to
- represent things such as the Named Stream Map and the Hash Adjusters in the
- :doc:`TPI/IPI Stream <TpiStream>`.
+{doc}`GlobalStream`
-CodeView
-========
-CodeView is another format which comes into the picture. While MSF defines
+: Information about the Global Symbol Stream.
+
+{doc}`HashTable`
+
+: Information about the serialized hash table format used internally to
+ represent things such as the Named Stream Map and the Hash Adjusters in the
+ {doc}`TPI/IPI Stream <TpiStream>`.
+
+## CodeView
+
+CodeView is another format which comes into the picture. While MSF defines
the structure of the overall file, and PDB defines the set of streams that
appear within the MSF file and the format of those streams, CodeView defines
the format of **symbol and type records** that appear within specific streams.
-Refer to the pages on :doc:`CodeViewSymbols` and :doc:`CodeViewTypes` for
+Refer to the pages on {doc}`CodeViewSymbols` and {doc}`CodeViewTypes` for
more information about the CodeView format.
+
diff --git a/llvm/docs/RISCV/RISCVVCIX.md b/llvm/docs/RISCV/RISCVVCIX.md
index 26e7b6eb5cc84..98e1dbf401acf 100644
--- a/llvm/docs/RISCV/RISCVVCIX.md
+++ b/llvm/docs/RISCV/RISCVVCIX.md
@@ -1,256 +1,250 @@
-===================================================
-Scheduling Information for RISC-V VCIX Instructions
-===================================================
+# Scheduling Information for RISC-V VCIX Instructions
+## Summary
-Summary
--------
-The purpose of this document is to outline how the scheduling information for RISC-V's ``XSfvcp`` extension -- SiFive Vector Coprocessor Interface (VCIX) -- in LLVM works, why it works the way it does, and how one may modify the code to support their VCIX needs.
+The purpose of this document is to outline how the scheduling information for RISC-V's `XSfvcp` extension -- SiFive Vector Coprocessor Interface (VCIX) -- in LLVM works, why it works the way it does, and how one may modify the code to support their VCIX needs.
SiFive makes no guarantee that modifying the upstream code to describe their VCIX implementations will lead to performance improvements over the default implementation.
-Introduction
-------------
-LLVM uses scheduler models to describe the behavior of processor latencies and resources. The scheduler models are attached to a processor definition (i.e. ``-mcpu=``) or tunings (i.e. ``-mtune=``). The challenge with VCIX is that the same processor definition could be used with different coprocessors that have very different latencies or processor resource usage for a given instruction. As a result, a default implementation is provided, and one may use this document to customize the existing implementation to their needs.
+## Introduction
-Understanding the VCIX Scheduling Model Information
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+LLVM uses scheduler models to describe the behavior of processor latencies and resources. The scheduler models are attached to a processor definition (i.e. `-mcpu=`) or tunings (i.e. `-mtune=`). The challenge with VCIX is that the same processor definition could be used with different coprocessors that have very different latencies or processor resource usage for a given instruction. As a result, a default implementation is provided, and one may use this document to customize the existing implementation to their needs.
-Supported Scheduling Models
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Understanding the VCIX Scheduling Model Information
-VCIX is supported in the SiFive 7 family scheduling models, for instance ``SiFive7VLEN512Model`` and ``SiFive7VLEN1024X300Model``. These models share a large portion of scheduling information, including those for VCIX instructions. Therefore, when it comes to customizing VCIX scheduling info, which we will walk you through in later sections, you only need to modify a single place.
+#### Supported Scheduling Models
+
+VCIX is supported in the SiFive 7 family scheduling models, for instance `SiFive7VLEN512Model` and `SiFive7VLEN1024X300Model`. These models share a large portion of scheduling information, including those for VCIX instructions. Therefore, when it comes to customizing VCIX scheduling info, which we will walk you through in later sections, you only need to modify a single place.
The SiFive 7 scheduling models are used in the following (tuning) processors:
-* ``-mtune=sifive7-series``
-* ``-mcpu=sifive-x390``
-* ``-mcpu=sifive-x280``
-* ``-mcpu=sifive-e76``
-* ``-mcpu=sifive-s76``
-* ``-mcpu=sifive-u74``
+- `-mtune=sifive7-series`
+- `-mcpu=sifive-x390`
+- `-mcpu=sifive-x280`
+- `-mcpu=sifive-e76`
+- `-mcpu=sifive-s76`
+- `-mcpu=sifive-u74`
-Understanding the Default Implementation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Understanding the Default Implementation
-To read the default implementation, please open ``llvm/lib/Target/RISCV/RISCVSchedSiFive7.td`` and navigate to the line that says ``// VCIX``. The line can be found on GitHub `here <https://github.com/llvm/llvm-project/blob/a00278632dfed7b856a0ac11a58423cb6b14a8c1/llvm/lib/Target/RISCV/RISCVSchedSiFive7.td#L1161>`__.
+To read the default implementation, please open `llvm/lib/Target/RISCV/RISCVSchedSiFive7.td` and navigate to the line that says `// VCIX`. The line can be found on GitHub [here](https://github.com/llvm/llvm-project/blob/a00278632dfed7b856a0ac11a58423cb6b14a8c1/llvm/lib/Target/RISCV/RISCVSchedSiFive7.td#L1161).
-To understand the code here, we first provide a brief overview. VCIX Pseudo-instructions are defined in ``llvm/lib/Target/RISCV/RISCVInstrInfoXSf.td`` which can be found on GitHub `here <https://github.com/llvm/llvm-project/blob/main/llvm/lib/Target/RISCV/RISCVInstrInfoXSf.td>`__.
+To understand the code here, we first provide a brief overview. VCIX Pseudo-instructions are defined in `llvm/lib/Target/RISCV/RISCVInstrInfoXSf.td` which can be found on GitHub [here](https://github.com/llvm/llvm-project/blob/main/llvm/lib/Target/RISCV/RISCVInstrInfoXSf.td).
For example:
-.. code-block::
-
- multiclass VPseudoVC_X<LMULInfo m, DAGOperand RS1Class,
- Operand OpClass = payload2> {
- let VLMul = m.value in {
- let Defs = [SF_VCIX_STATE], Uses = [SF_VCIX_STATE] in {
- def "PseudoVC_" # NAME # "_SE_" # m.MX
- : VPseudoVC_X<OpClass, RS1Class>,
- Sched<[!cast<SchedWrite>("WriteVC_" # NAME # "_" # m.MX)]>;
- def "PseudoVC_V_" # NAME # "_SE_" # m.MX
- : VPseudoVC_V_X<OpClass, m.vrclass, RS1Class>,
- Sched<[!cast<SchedWrite>("WriteVC_V_" # NAME # "_" # m.MX)]>;
- }
- def "PseudoVC_V_" # NAME # "_" # m.MX
+```
+multiclass VPseudoVC_X<LMULInfo m, DAGOperand RS1Class,
+ Operand OpClass = payload2> {
+ let VLMul = m.value in {
+ let Defs = [SF_VCIX_STATE], Uses = [SF_VCIX_STATE] in {
+ def "PseudoVC_" # NAME # "_SE_" # m.MX
+ : VPseudoVC_X<OpClass, RS1Class>,
+ Sched<[!cast<SchedWrite>("WriteVC_" # NAME # "_" # m.MX)]>;
+ def "PseudoVC_V_" # NAME # "_SE_" # m.MX
: VPseudoVC_V_X<OpClass, m.vrclass, RS1Class>,
Sched<[!cast<SchedWrite>("WriteVC_V_" # NAME # "_" # m.MX)]>;
}
+ def "PseudoVC_V_" # NAME # "_" # m.MX
+ : VPseudoVC_V_X<OpClass, m.vrclass, RS1Class>,
+ Sched<[!cast<SchedWrite>("WriteVC_V_" # NAME # "_" # m.MX)]>;
}
+}
- // snip
-
- let Predicates = [HasVendorXSfvcp] in {
- foreach m = MxList in {
- defm X : VPseudoVC_X<m, GPR>;
+// snip
- // snip
+let Predicates = [HasVendorXSfvcp] in {
+ foreach m = MxList in {
+ defm X : VPseudoVC_X<m, GPR>;
-In this example, for each LMUL ``m.MX``, there are three pseudos defined:
+// snip
+```
-1. ``PseudoVC_X_SE_ # m.MX``
-2. ``PseudoVC_V_X_SE_ # m.MX``
-3. ``PseudoVC_V_X_ # m.MX``
+In this example, for each LMUL `m.MX`, there are three pseudos defined:
-Note that ``#`` concatenates the first string with the LMUL ``m.MX``. When ``m.MX`` is ``M2`` for example, the three pseudos would be defined:
+1. `PseudoVC_X_SE_ # m.MX`
+2. `PseudoVC_V_X_SE_ # m.MX`
+3. `PseudoVC_V_X_ # m.MX`
-1. ``PseudoVC_X_SE_M2``
-2. ``PseudoVC_V_X_SE_M2``
-3. ``PseudoVC_V_X_M2``
+Note that `#` concatenates the first string with the LMUL `m.MX`. When `m.MX` is `M2` for example, the three pseudos would be defined:
-Note that for each of these definitions, there is a ``Sched`` list attached. The ``Sched`` list takes ``SchedWrite`` and ``SchedRead`` objects, which define the behavior of the operands that are written and and read. In the snippet above, the singular write is attached to the pseudo-instruction. It is up to the scheduler model to describe the behavior of each ``SchedWrite``.
+1. `PseudoVC_X_SE_M2`
+2. `PseudoVC_V_X_SE_M2`
+3. `PseudoVC_V_X_M2`
-Switching back to the scheduling model linked at the start of this section, we explain how behavior is assigned to the VCIX ``SchedWrite`` objects. Let’s take a look at an example:
+Note that for each of these definitions, there is a `Sched` list attached. The `Sched` list takes `SchedWrite` and `SchedRead` objects, which define the behavior of the operands that are written and and read. In the snippet above, the singular write is attached to the pseudo-instruction. It is up to the scheduler model to describe the behavior of each `SchedWrite`.
-.. code-block::
+Switching back to the scheduling model linked at the start of this section, we explain how behavior is assigned to the VCIX `SchedWrite` objects. Let’s take a look at an example:
- // snip
+```
+// snip
- defvar Cycles = SiFive7GetCyclesDefault<mx>.c;
- defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
- let Latency = Cycles,
- AcquireAtCycles = [0, 1],
- ReleaseAtCycles = [1, !add(1, Cycles)] in {
- defm "" : LMULWriteResMX<"WriteVC_V_I", [VCQ, VA1], mx, IsWorstCase>;
+defvar Cycles = SiFive7GetCyclesDefault<mx>.c;
+defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
+let Latency = Cycles,
+ AcquireAtCycles = [0, 1],
+ ReleaseAtCycles = [1, !add(1, Cycles)] in {
+ defm "" : LMULWriteResMX<"WriteVC_V_I", [VCQ, VA1], mx, IsWorstCase>;
- // snip
+// snip
+```
-Here, the ``LMULWriteResMX`` creates a ``WriteRes`` for each supported LMULs, which is represented by ``mx`` above. A ``WriteRes`` associates processor resources, processor resource usage, and latency with each ``SchedWrite``. In this example, the ``SchedWrite`` named ``WriteVC_V_I # mx`` is being said to use the ``VCQ`` (vector command queue) and ``VA1`` (vector arithmetic sequencer) processor resources.
-``AcquireAtCycles[i]`` defines a cycle, relative to instruction issue, that processor resource ``i`` in the ``LMULWriteResMX`` below is acquired at. Similarly, ``ReleaseAtCycles[i]`` defines a cycle, relative to instruction issue, that processor resource ``i`` in the ``LMULWriteResMX`` below is released at. For this ``LMULWriteResMX``, we’re saying that the vector command queue is acquired at cycle 0 and released at cycle 1 and the vector arithmetic sequencer is acquired at cycle 1 and released at cycle 1+Cycles. ``Cycles`` gets its value from a function that describes the default behavior. Looking at the entire VCIX default implementation, you can see that all instructions are given this behavior.
+Here, the `LMULWriteResMX` creates a `WriteRes` for each supported LMULs, which is represented by `mx` above. A `WriteRes` associates processor resources, processor resource usage, and latency with each `SchedWrite`. In this example, the `SchedWrite` named `WriteVC_V_I # mx` is being said to use the `VCQ` (vector command queue) and `VA1` (vector arithmetic sequencer) processor resources.
+`AcquireAtCycles[i]` defines a cycle, relative to instruction issue, that processor resource `i` in the `LMULWriteResMX` below is acquired at. Similarly, `ReleaseAtCycles[i]` defines a cycle, relative to instruction issue, that processor resource `i` in the `LMULWriteResMX` below is released at. For this `LMULWriteResMX`, we’re saying that the vector command queue is acquired at cycle 0 and released at cycle 1 and the vector arithmetic sequencer is acquired at cycle 1 and released at cycle 1+Cycles. `Cycles` gets its value from a function that describes the default behavior. Looking at the entire VCIX default implementation, you can see that all instructions are given this behavior.
From here, you should have enough background on how the default implementation works.
-Basic Scheduling Info Customization
------------------------------------
-The default implementation sets the ``Latency``, ``AcquireAtCycles`` and ``ReleaseAtCycles`` the same way for all VCIX instructions. Let’s walk through an example where we *customize* the default implementation for our needs.
+## Basic Scheduling Info Customization
-Let’s assume that ``WriteVC_V_I`` behaves differently from the default implementation, and all the other VCIX instructions behave the same as the default implementation. We might write something like this:
+The default implementation sets the `Latency`, `AcquireAtCycles` and `ReleaseAtCycles` the same way for all VCIX instructions. Let’s walk through an example where we *customize* the default implementation for our needs.
-.. code-block::
+Let’s assume that `WriteVC_V_I` behaves differently from the default implementation, and all the other VCIX instructions behave the same as the default implementation. We might write something like this:
- defvar CustomCycles = SiFive7GetCustomCycles<mx>.c;
- defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
- let Latency = CustomCycles,
- AcquireAtCycles = [0, 1],
- ReleaseAtCycles = [1, !add(1, CustomCycles)] in
- defm "" : LMULWriteResMX<"WriteVC_V_I", [VCQ, VA1], mx, IsWorstCase>;
-
- // snip rest
+```
+defvar CustomCycles = SiFive7GetCustomCycles<mx>.c;
+defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
+let Latency = CustomCycles,
+ AcquireAtCycles = [0, 1],
+ ReleaseAtCycles = [1, !add(1, CustomCycles)] in
+ defm "" : LMULWriteResMX<"WriteVC_V_I", [VCQ, VA1], mx, IsWorstCase>;
-In this example, we wrote a new function ``SiFive7GetCustomCycles`` which takes an argument ``mx`` which describes the LMUL we are scheduling for. It is up to you to determine the number of cycles that should be returned, based on the behavior of your implementation. You can read the implementation of ``SiFive7GetCyclesDefault`` to help you write a custom one.
+ // snip rest
+```
-We set ``Latency`` using the result of our new custom function. Then we left ``AcquireAtCycles[0]`` and ``ReleaseAtCycles[0]`` the same because we assume that the ``VCQ`` has the same behavior: it takes one cycle to get dequeued. Then, we use the result of our new custom function to describe how long the arithmetic sequencer is used. In this case, we made the ``Latency`` and occupancy of the arithmetic sequencer the same, but we could have easily written two custom functions instead.
+In this example, we wrote a new function `SiFive7GetCustomCycles` which takes an argument `mx` which describes the LMUL we are scheduling for. It is up to you to determine the number of cycles that should be returned, based on the behavior of your implementation. You can read the implementation of `SiFive7GetCyclesDefault` to help you write a custom one.
-Another thing that can be customized is the processor resources that are used by a VCIX instruction. Currently, these instructions all use the vector command queue and the vector arithmetic sequencer. However, you can add another ``ProcResource`` to the list, and describe when it is acquired and released in ``AcquireAtCycles`` and ``ReleaseAtCycles``.
+We set `Latency` using the result of our new custom function. Then we left `AcquireAtCycles[0]` and `ReleaseAtCycles[0]` the same because we assume that the `VCQ` has the same behavior: it takes one cycle to get dequeued. Then, we use the result of our new custom function to describe how long the arithmetic sequencer is used. In this case, we made the `Latency` and occupancy of the arithmetic sequencer the same, but we could have easily written two custom functions instead.
-To do so, first let’s look at the existing ``ProcResource`` we used before, namely ``VCQ`` and ``VA1``. These two instances are actually parameters passed to the enclosing structure, ``SiFive7WriteResBase``. Their actual definitions are placed `here <https://github.com/llvm/llvm-project/blob/e087d428823e1d1d4c00c895bc3b637989764104/llvm/lib/Target/RISCV/RISCVSchedSiFive7.td#L273>`__:
+Another thing that can be customized is the processor resources that are used by a VCIX instruction. Currently, these instructions all use the vector command queue and the vector arithmetic sequencer. However, you can add another `ProcResource` to the list, and describe when it is acquired and released in `AcquireAtCycles` and `ReleaseAtCycles`.
-.. code-block::
+To do so, first let’s look at the existing `ProcResource` we used before, namely `VCQ` and `VA1`. These two instances are actually parameters passed to the enclosing structure, `SiFive7WriteResBase`. Their actual definitions are placed [here](https://github.com/llvm/llvm-project/blob/e087d428823e1d1d4c00c895bc3b637989764104/llvm/lib/Target/RISCV/RISCVSchedSiFive7.td#L273):
- def PipeA : ProcResource<1>;
- def PipeB : ProcResource<1>;
- def IDiv : ProcResource<1>; // Int Division
- def FDiv : ProcResource<1>; // FP Division/Sqrt
+```
+def PipeA : ProcResource<1>;
+def PipeB : ProcResource<1>;
+def IDiv : ProcResource<1>; // Int Division
+def FDiv : ProcResource<1>; // FP Division/Sqrt
- // Arithmetic sequencer(s)
- // VA1 can handle any vector airthmetic instruction.
- def VA1 : ProcResource<1>;
- if dualVALU then {
- // VA2 generally can only handle simple vector arithmetic.
- def VA2 : ProcResource<1>;
- }
+// Arithmetic sequencer(s)
+// VA1 can handle any vector airthmetic instruction.
+def VA1 : ProcResource<1>;
+if dualVALU then {
+ // VA2 generally can only handle simple vector arithmetic.
+ def VA2 : ProcResource<1>;
+}
- def VL : ProcResource<1>; // Load sequencer
- def VS : ProcResource<1>; // Store sequencer
- def VCQ : ProcResource<1>; // Vector Command Queue
+def VL : ProcResource<1>; // Load sequencer
+def VS : ProcResource<1>; // Store sequencer
+def VCQ : ProcResource<1>; // Vector Command Queue
+```
-These ``ProcResources`` are instantiated in another class, ``SiFive7SchedResources``, where we also create an alias for each of them (through ``defvar``) so that it's easier to use later:
+These `ProcResources` are instantiated in another class, `SiFive7SchedResources`, where we also create an alias for each of them (through `defvar`) so that it's easier to use later:
-.. code-block::
+```
+defvar SiFive7PipeA = !cast<ProcResource>(NAME # "SiFive7PipeA");
+defvar SiFive7PipeB = !cast<ProcResource>(NAME # "SiFive7PipeB");
+defvar SiFive7PipeAB = !cast<ProcResGroup>(NAME # "SiFive7PipeAB");
+defvar SiFive7IDiv = !cast<ProcResource>(NAME # "SiFive7IDiv");
+defvar SiFive7FDiv = !cast<ProcResource>(NAME # "SiFive7FDiv");
- defvar SiFive7PipeA = !cast<ProcResource>(NAME # "SiFive7PipeA");
- defvar SiFive7PipeB = !cast<ProcResource>(NAME # "SiFive7PipeB");
- defvar SiFive7PipeAB = !cast<ProcResGroup>(NAME # "SiFive7PipeAB");
- defvar SiFive7IDiv = !cast<ProcResource>(NAME # "SiFive7IDiv");
- defvar SiFive7FDiv = !cast<ProcResource>(NAME # "SiFive7FDiv");
+defvar SiFive7VA1 = !cast<ProcResource>(NAME # "SiFive7VA1");
- defvar SiFive7VA1 = !cast<ProcResource>(NAME # "SiFive7VA1");
+defvar SiFive7VA1OrVA2 = !if (dualVALU,
+ !cast<ProcResGroup>(NAME # "SiFive7VA1OrVA2"),
+ !cast<ProcResource>(NAME # "SiFive7VA1"));
+```
- defvar SiFive7VA1OrVA2 = !if (dualVALU,
- !cast<ProcResGroup>(NAME # "SiFive7VA1OrVA2"),
- !cast<ProcResource>(NAME # "SiFive7VA1"));
-
-Specifically, ``SiFive7VA1`` here is the alias for ``VA1`` mentioned previously, which is also the instance we’ll eventually pass as a parameter to ``SiFive7WriteResBase`` mentioned earlier.
+Specifically, `SiFive7VA1` here is the alias for `VA1` mentioned previously, which is also the instance we’ll eventually pass as a parameter to `SiFive7WriteResBase` mentioned earlier.
So if you want to add your own, that might look something like this:
-.. code-block::
+```
+// Step 1: create a new ProcResource
+def CustomVCIX : ProcResource<1>;
- // Step 1: create a new ProcResource
- def CustomVCIX : ProcResource<1>;
+// Step 2: add a new parameter to SiFive7WriteResBase
+multiclass SiFive7WriteResBase<int VLEN,
+ ProcResourceKind PipeA, ProcResourceKind PipeB, ProcResourceKind PipeAB,
+ ...
+ ProcResourceKind VCQ, ProcResourceKind CustomVCIX,
+ ...>
- // Step 2: add a new parameter to SiFive7WriteResBase
- multiclass SiFive7WriteResBase<int VLEN,
- ProcResourceKind PipeA, ProcResourceKind PipeB, ProcResourceKind PipeAB,
- ...
- ProcResourceKind VCQ, ProcResourceKind CustomVCIX,
- ...>
+// Step 3: update SiFive7SchedResources
+defvar SiFive7CustomVCIX = !cast<ProcResource>(NAME # SiFive7CustomVCIX);
- // Step 3: update SiFive7SchedResources
- defvar SiFive7CustomVCIX = !cast<ProcResource>(NAME # SiFive7CustomVCIX);
+defm SiFive7
+ : SiFive7WriteResBase<vlen, SiFive7PipeA, SiFive7PipeB, SiFive7PipeAB,
+ ...
+ SiFive7VCQ, SiFive7CustomVCIX, ...>;
- defm SiFive7
- : SiFive7WriteResBase<vlen, SiFive7PipeA, SiFive7PipeB, SiFive7PipeAB,
- ...
- SiFive7VCQ, SiFive7CustomVCIX, ...>;
+// Final Step: update scheduling info entry
- // Final Step: update scheduling info entry
+defvar CustomCycles = SiFive7GetCustomCycles<mx>.c;
+defvar VCIXCycles = SiFive7GetCustomCyclesVCIX<mx>.c;
+defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
+let Latency = CustomCycles,
+ AcquireAtCycles = [0, 1, CustomCycles],
+ ReleaseAtCycles = [1, !add(1, CustomCycles), !add(1, VCIXCycles) ] in
+ defm "" : LMULWriteResMX<"WriteVC_V_I", [SiFive7VCQ, VA, CustomVCIX], mx, ...>;
+```
- defvar CustomCycles = SiFive7GetCustomCycles<mx>.c;
- defvar VCIXCycles = SiFive7GetCustomCyclesVCIX<mx>.c;
- defvar IsWorstCase = SiFive7IsWorstCaseMX<mx, SchedMxList>.c;
- let Latency = CustomCycles,
- AcquireAtCycles = [0, 1, CustomCycles],
- ReleaseAtCycles = [1, !add(1, CustomCycles), !add(1, VCIXCycles) ] in
- defm "" : LMULWriteResMX<"WriteVC_V_I", [SiFive7VCQ, VA, CustomVCIX], mx, ...>;
+## Advanced Scheduling Info Customization
-Advanced Scheduling Info Customization
---------------------------------------
Another scenario you may be interested in handling is changing scheduling information based on the *value* of the immediate in the first operand of the pseudo-instruction, since it is considered part of the opcode. In order to model this there are a few steps:
-1. Define ``WriteRes`` objects for all pseudo + opcode combinations.
-2. Define ``MCSchedPredicate`` objects for all opcode combinations
-3. Define ``SchedVar`` objects to tie ``MCSchedPredicate`` objects to ``WriteRes`` objects
-4. Define ``SchedWriteVariant`` to aggregate all ``SchedVar`` objects together
-5. Define a ``SchedAlias`` object to tie the behavior of the original ``WriteRes`` name with the ``SchedWriteVariant``
-
-There is an existing helper class, ``LMULWriteResMXVariant``, which can be found on GitHub `here <https://github.com/llvm/llvm-project/blob/36b339b84a98afe7bdf470747a776d0d5f348b64/llvm/lib/Target/RISCV/RISCVScheduleV.td#L74>`__ that implements this process for the case when there is a single predicate.
-
-.. code-block::
+1. Define `WriteRes` objects for all pseudo + opcode combinations.
+2. Define `MCSchedPredicate` objects for all opcode combinations
+3. Define `SchedVar` objects to tie `MCSchedPredicate` objects to `WriteRes` objects
+4. Define `SchedWriteVariant` to aggregate all `SchedVar` objects together
+5. Define a `SchedAlias` object to tie the behavior of the original `WriteRes` name with the `SchedWriteVariant`
- def IsOp0ImmEq2 : MCSchedPredicate<CheckImmOperand<0, 2>>; // true when operand 0 is 2
+There is an existing helper class, `LMULWriteResMXVariant`, which can be found on GitHub [here](https://github.com/llvm/llvm-project/blob/36b339b84a98afe7bdf470747a776d0d5f348b64/llvm/lib/Target/RISCV/RISCVScheduleV.td#L74) that implements this process for the case when there is a single predicate.
- defm : LMULWriteResMXVariant<"WriteVC_V_I", IsOp0ImmEq2,
- // When IsOp0ImmEq2 is true
- [VCQ, VA1], 20, [0, 1], [1, 22],
- // Other cases
- [VCQ, VA1], 3, [0, 1], [1, 4],
- mx, ...>;
+```
+def IsOp0ImmEq2 : MCSchedPredicate<CheckImmOperand<0, 2>>; // true when operand 0 is 2
-In the above example, ``WriteVC_V_I`` will be assigned a latency of 20 cycles and hold ``VA1`` for 22 cycles if its first (immediate) operand has a value of 2. Otherwise, the latency would be 3 cycles with an occupancy of 4 cycles on ``VA1``.
+defm : LMULWriteResMXVariant<"WriteVC_V_I", IsOp0ImmEq2,
+ // When IsOp0ImmEq2 is true
+ [VCQ, VA1], 20, [0, 1], [1, 22],
+ // Other cases
+ [VCQ, VA1], 3, [0, 1], [1, 4],
+ mx, ...>;
+```
-To extend it to handle multiple opcodes, you would add add additional ``WriteRes`` definitions for each pseudo + opcode combinations, define additional ``MCSchedPredicate`` objects for each opcode, define additional ``SchedVar`` objects to tie these new objects together, and add these ``SchedVar`` objects to the ``SchedWriteVariant``.
+In the above example, `WriteVC_V_I` will be assigned a latency of 20 cycles and hold `VA1` for 22 cycles if its first (immediate) operand has a value of 2. Otherwise, the latency would be 3 cycles with an occupancy of 4 cycles on `VA1`.
-To define a predicate that checks an opcode immediate is 0 or 1 for example, you might write something like this for the ``WriteVC_V_I`` pseudo for LMUL ``mx``:
+To extend it to handle multiple opcodes, you would add add additional `WriteRes` definitions for each pseudo + opcode combinations, define additional `MCSchedPredicate` objects for each opcode, define additional `SchedVar` objects to tie these new objects together, and add these `SchedVar` objects to the `SchedWriteVariant`.
-.. code-block::
+To define a predicate that checks an opcode immediate is 0 or 1 for example, you might write something like this for the `WriteVC_V_I` pseudo for LMUL `mx`:
- // Define WriteRes objects for all pseudo + opcode combinations
- let Latency = 3, AcquireAtCycles = [0, 1], ReleaseAtCycles = [1, 4] in
- def "WriteVC_V_I_" # mx # "_Opc0" : SchedWriteRes<[VCQ, VA1]>
- let Latency = 10, AcquireAtCycles = [0, 1], ReleaseAtCycles = [1, 11] in
- def "WriteVC_V_I_" # mx # "_Opc1" : SchedWriteRes<[VCQ, VA1]>
+```
+// Define WriteRes objects for all pseudo + opcode combinations
+let Latency = 3, AcquireAtCycles = [0, 1], ReleaseAtCycles = [1, 4] in
+def "WriteVC_V_I_" # mx # "_Opc0" : SchedWriteRes<[VCQ, VA1]>
+let Latency = 10, AcquireAtCycles = [0, 1], ReleaseAtCycles = [1, 11] in
+def "WriteVC_V_I_" # mx # "_Opc1" : SchedWriteRes<[VCQ, VA1]>
- // Define MCSchedPredicate objects for all opcode combinations. This toy example shows how to
- // do this with made up opcodes. Please refer to the VCIX manual for opcodes you will want to
- // support.
- def IsOp0ImmEq0 : MCSchedPredicate<CheckImmOperand<0, 0>>; // true when operand 0 is 0
- def IsOp0ImmEq1 : MCSchedPredicate<CheckImmOperand<0, 1>>; // true when operand 0 is 1
+// Define MCSchedPredicate objects for all opcode combinations. This toy example shows how to
+// do this with made up opcodes. Please refer to the VCIX manual for opcodes you will want to
+// support.
+def IsOp0ImmEq0 : MCSchedPredicate<CheckImmOperand<0, 0>>; // true when operand 0 is 0
+def IsOp0ImmEq1 : MCSchedPredicate<CheckImmOperand<0, 1>>; // true when operand 0 is 1
- // Define SchedVar objects to tie MCSchedPredicate objects to WriteRes objects
- def "WriteVC_V_I_" # mx # "_Opc0SchedVar"
- : SchedVar<IsOp0ImmEq0, [!cast<SchedWriteRes>("WriteVC_V_I_" # mx # "_Opc0")]>;
- def "WriteVC_V_I_" # mx # "_Opc1SchedVar"
- : SchedVar<IsOp0ImmEq0, [!cast<SchedWriteRes>("WriteVC_V_I_" # mx # "_Opc1")]>;
+// Define SchedVar objects to tie MCSchedPredicate objects to WriteRes objects
+def "WriteVC_V_I_" # mx # "_Opc0SchedVar"
+ : SchedVar<IsOp0ImmEq0, [!cast<SchedWriteRes>("WriteVC_V_I_" # mx # "_Opc0")]>;
+def "WriteVC_V_I_" # mx # "_Opc1SchedVar"
+ : SchedVar<IsOp0ImmEq0, [!cast<SchedWriteRes>("WriteVC_V_I_" # mx # "_Opc1")]>;
- // Define SchedWriteVariant to aggregate all SchedVar objects together
- def "WriteVC_V_I_" # mx # "Variant"
- : SchedWriteVariant<["WriteVC_V_I_" # mx # "_Opc0SchedVar",
- "WriteVC_V_I_" # mx # "_Opc1SchedVar"]>;
-
- // Define a SchedAlias object to tie the behavior of the original WriteRes name with the SchedWriteVariant
- def : SchedAlias<!cast<SchedReadWrite>("WriteVC_V_I_" # mx),
- !cast<SchedReadWrite>("WriteVC_V_I_" # mx # "Variant")>;
+// Define SchedWriteVariant to aggregate all SchedVar objects together
+def "WriteVC_V_I_" # mx # "Variant"
+ : SchedWriteVariant<["WriteVC_V_I_" # mx # "_Opc0SchedVar",
+ "WriteVC_V_I_" # mx # "_Opc1SchedVar"]>;
+// Define a SchedAlias object to tie the behavior of the original WriteRes name with the SchedWriteVariant
+def : SchedAlias<!cast<SchedReadWrite>("WriteVC_V_I_" # mx),
+ !cast<SchedReadWrite>("WriteVC_V_I_" # mx # "Variant")>;
+```
From here, you should have a strong understanding of how to modify the default implementation of VCIX scheduling in LLVM.
+
diff --git a/llvm/docs/RISCV/RISCVVectorExtension.md b/llvm/docs/RISCV/RISCVVectorExtension.md
index aa6d6e8f961dc..b57eb9baf7ea2 100644
--- a/llvm/docs/RISCV/RISCVVectorExtension.md
+++ b/llvm/docs/RISCV/RISCVVectorExtension.md
@@ -1,350 +1,321 @@
-=========================
- RISC-V Vector Extension
-=========================
+# RISC-V Vector Extension
-
-The RISC-V target supports the 1.0 version of the `RISC-V Vector Extension (RVV) <https://github.com/riscv/riscv-v-spec/blob/v1.0/v-spec.adoc>`_.
+The RISC-V target supports the 1.0 version of the [RISC-V Vector Extension (RVV)](https://github.com/riscv/riscv-v-spec/blob/v1.0/v-spec.adoc).
This guide gives an overview of how it's modelled in LLVM IR and how the backend generates code for it.
-Mapping to LLVM IR types
-========================
+## Mapping to LLVM IR types
-RVV adds 32 VLEN sized registers, where VLEN is an unknown constant to the compiler. To be able to represent VLEN sized values, the RISC-V backend takes the same approach as AArch64's SVE and uses `scalable vector types <https://llvm.org/docs/LangRef.html#t-vector>`_.
+RVV adds 32 VLEN sized registers, where VLEN is an unknown constant to the compiler. To be able to represent VLEN sized values, the RISC-V backend takes the same approach as AArch64's SVE and uses [scalable vector types](https://llvm.org/docs/LangRef.html#t-vector).
-Scalable vector types are of the form ``<vscale x n x ty>``, which indicates a vector with a multiple of ``n`` elements of type ``ty``.
-On RISC-V ``n`` and ``ty`` control LMUL and SEW respectively.
+Scalable vector types are of the form `<vscale x n x ty>`, which indicates a vector with a multiple of `n` elements of type `ty`.
+On RISC-V `n` and `ty` control LMUL and SEW respectively.
-LLVM only supports ELEN=32 or ELEN=64, so ``vscale`` is defined as VLEN/64 (see ``RISCV::RVVBitsPerBlock``).
+LLVM only supports ELEN=32 or ELEN=64, so `vscale` is defined as VLEN/64 (see `RISCV::RVVBitsPerBlock`).
Note this means that VLEN must be at least 64, so VLEN=32 isn't currently supported.
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| | LMUL=⅛ | LMUL=¼ | LMUL=½ | LMUL=1 | LMUL=2 | LMUL=4 | LMUL=8 |
-+===================+===============+==================+==================+===================+===================+===================+===================+
-| i64 (ELEN=64) | N/A | N/A | N/A | <v x 1 x i64> | <v x 2 x i64> | <v x 4 x i64> | <v x 8 x i64> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| i32 | N/A | N/A | <v x 1 x i32> | <v x 2 x i32> | <v x 4 x i32> | <v x 8 x i32> | <v x 16 x i32> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| i16 | N/A | <v x 1 x i16> | <v x 2 x i16> | <v x 4 x i16> | <v x 8 x i16> | <v x 16 x i16> | <v x 32 x i16> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| i8 | <v x 1 x i8> | <v x 2 x i8> | <v x 4 x i8> | <v x 8 x i8> | <v x 16 x i8> | <v x 32 x i8> | <v x 64 x i8> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| double (ELEN=64) | N/A | N/A | N/A | <v x 1 x double> | <v x 2 x double> | <v x 4 x double> | <v x 8 x double> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| float | N/A | N/A | <v x 1 x float> | <v x 2 x float> | <v x 4 x float> | <v x 8 x float> | <v x 16 x float> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| half | N/A | <v x 1 x half> | <v x 2 x half> | <v x 4 x half> | <v x 8 x half> | <v x 16 x half> | <v x 32 x half> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-| bfloat | N/A | <v x 1 x bfloat> | <v x 2 x bfloat> | <v x 4 x bfloat> | <v x 8 x bfloat> | <v x 16 x bfloat> | <v x 32 x bfloat> |
-+-------------------+---------------+------------------+------------------+-------------------+-------------------+-------------------+-------------------+
-
-(Read ``<v x k x ty>`` as ``<vscale x k x ty>``)
-
-
-Mask vector types
------------------
+| | LMUL=⅛ | LMUL=¼ | LMUL=½ | LMUL=1 | LMUL=2 | LMUL=4 | LMUL=8 |
+| ---------------- | ------------- | ----------------- | ----------------- | ----------------- | ----------------- | ------------------ | ------------------ |
+| i64 (ELEN=64) | N/A | N/A | N/A | \<v x 1 x i64> | \<v x 2 x i64> | \<v x 4 x i64> | \<v x 8 x i64> |
+| i32 | N/A | N/A | \<v x 1 x i32> | \<v x 2 x i32> | \<v x 4 x i32> | \<v x 8 x i32> | \<v x 16 x i32> |
+| i16 | N/A | \<v x 1 x i16> | \<v x 2 x i16> | \<v x 4 x i16> | \<v x 8 x i16> | \<v x 16 x i16> | \<v x 32 x i16> |
+| i8 | \<v x 1 x i8> | \<v x 2 x i8> | \<v x 4 x i8> | \<v x 8 x i8> | \<v x 16 x i8> | \<v x 32 x i8> | \<v x 64 x i8> |
+| double (ELEN=64) | N/A | N/A | N/A | \<v x 1 x double> | \<v x 2 x double> | \<v x 4 x double> | \<v x 8 x double> |
+| float | N/A | N/A | \<v x 1 x float> | \<v x 2 x float> | \<v x 4 x float> | \<v x 8 x float> | \<v x 16 x float> |
+| half | N/A | \<v x 1 x half> | \<v x 2 x half> | \<v x 4 x half> | \<v x 8 x half> | \<v x 16 x half> | \<v x 32 x half> |
+| bfloat | N/A | \<v x 1 x bfloat> | \<v x 2 x bfloat> | \<v x 4 x bfloat> | \<v x 8 x bfloat> | \<v x 16 x bfloat> | \<v x 32 x bfloat> |
+
+(Read `<v x k x ty>` as `<vscale x k x ty>`)
+
+### Mask vector types
Mask vectors are physically represented using a layout of densely packed bits in a vector register.
They are mapped to the following LLVM IR types:
-- ``<vscale x 1 x i1>``
-- ``<vscale x 2 x i1>``
-- ``<vscale x 4 x i1>``
-- ``<vscale x 8 x i1>``
-- ``<vscale x 16 x i1>``
-- ``<vscale x 32 x i1>``
-- ``<vscale x 64 x i1>``
+- `<vscale x 1 x i1>`
+- `<vscale x 2 x i1>`
+- `<vscale x 4 x i1>`
+- `<vscale x 8 x i1>`
+- `<vscale x 16 x i1>`
+- `<vscale x 32 x i1>`
+- `<vscale x 64 x i1>`
Two types with the same SEW/LMUL ratio will have the same related mask type.
-For instance, two different comparisons one under SEW=64, LMUL=2 and the other under SEW=32, LMUL=1 will both generate a mask ``<vscale x 2 x i1>``.
+For instance, two different comparisons one under SEW=64, LMUL=2 and the other under SEW=32, LMUL=1 will both generate a mask `<vscale x 2 x i1>`.
-Representation in LLVM IR
-=========================
+## Representation in LLVM IR
Vector instructions can be represented in two main ways in LLVM IR:
1. Regular instructions on both scalable and fixed-length vector types
- .. code-block:: llvm
-
- %c = add <vscale x 4 x i32> %a, %b
- %f = add <4 x i32> %d, %e
+ ```llvm
+ %c = add <vscale x 4 x i32> %a, %b
+ %f = add <4 x i32> %d, %e
+ ```
-2. RISC-V vector intrinsics, which mirror the `C intrinsics specification <https://github.com/riscv-non-isa/rvv-intrinsic-doc>`_
+2. RISC-V vector intrinsics, which mirror the [C intrinsics specification](https://github.com/riscv-non-isa/rvv-intrinsic-doc)
These come in unmasked variants:
- .. code-block:: llvm
-
- %c = call @llvm.riscv.vadd.nxv4i32.nxv4i32(
- <vscale x 4 x i32> %passthru,
- <vscale x 4 x i32> %a,
- <vscale x 4 x i32> %b,
- i64 %avl
- )
+ ```llvm
+ %c = call @llvm.riscv.vadd.nxv4i32.nxv4i32(
+ <vscale x 4 x i32> %passthru,
+ <vscale x 4 x i32> %a,
+ <vscale x 4 x i32> %b,
+ i64 %avl
+ )
+ ```
As well as masked variants:
- .. code-block:: llvm
-
- %c = call @llvm.riscv.vadd.mask.nxv4i32.nxv4i32(
- <vscale x 4 x i32> %passthru,
- <vscale x 4 x i32> %a,
- <vscale x 4 x i32> %b,
- <vscale x 4 x i1> %mask,
- i64 %avl,
- i64 0 ; policy (must be an immediate)
- )
+ ```llvm
+ %c = call @llvm.riscv.vadd.mask.nxv4i32.nxv4i32(
+ <vscale x 4 x i32> %passthru,
+ <vscale x 4 x i32> %a,
+ <vscale x 4 x i32> %b,
+ <vscale x 4 x i1> %mask,
+ i64 %avl,
+ i64 0 ; policy (must be an immediate)
+ )
+ ```
- Both allow setting the AVL as well as controlling the inactive/tail elements via the passthru operand, but the masked variant also provides operands for the mask and ``vta``/``vma`` policy bits.
+ Both allow setting the AVL as well as controlling the inactive/tail elements via the passthru operand, but the masked variant also provides operands for the mask and `vta`/`vma` policy bits.
The only valid types are scalable vector types.
-For operations that access memory, trap or otherwise have behaviour which depends on what elements are enabled, the target agnostic :ref:`llvm.masked.* <int_mload_mstore>` and :ref:`llvm.vp.* <int_vp>` intrinsics can be used to control the mask and AVL respectively.
-
-.. note::
+For operations that access memory, trap or otherwise have behaviour which depends on what elements are enabled, the target agnostic {ref}`llvm.masked.* <int_mload_mstore>` and {ref}`llvm.vp.* <int_vp>` intrinsics can be used to control the mask and AVL respectively.
- Middle-end passes typically do not need to worry about controlling the AVL for most instructions, as :ref:`RISCVVLOptimizer` will automatically take care of reducing the AVL to avoid vsetvli toggles. Using regular LLVM IR instructions allows more generic combines and optimisations to be taken advantage of. For instructions that may access memory or trap etc., passes should use the ``llvm.vp.*`` intrinsics to set the AVL where required.
+:::{note}
+Middle-end passes typically do not need to worry about controlling the AVL for most instructions, as {ref}`RISCVVLOptimizer` will automatically take care of reducing the AVL to avoid vsetvli toggles. Using regular LLVM IR instructions allows more generic combines and optimisations to be taken advantage of. For instructions that may access memory or trap etc., passes should use the `llvm.vp.*` intrinsics to set the AVL where required.
+:::
-SelectionDAG lowering
-=====================
+## SelectionDAG lowering
For most regular **scalable** vector LLVM IR instructions, their corresponding SelectionDAG nodes are legal on RISC-V and don't require any custom lowering.
-.. code-block::
-
- t5: nxv4i32 = add t2, t4
+```
+t5: nxv4i32 = add t2, t4
+```
RISC-V vector intrinsics also don't require any custom lowering.
-.. code-block::
-
- t12: nxv4i32 = llvm.riscv.vadd TargetConstant:i64<10056>, undef:nxv4i32, t2, t4, t6
+```
+t12: nxv4i32 = llvm.riscv.vadd TargetConstant:i64<10056>, undef:nxv4i32, t2, t4, t6
+```
-Fixed-length vectors
---------------------
+### Fixed-length vectors
Because there are no fixed-length vector patterns, fixed-length vectors need to be custom lowered and performed in a scalable "container" type:
-1. The fixed-length vector operands are inserted into scalable containers with ``insert_subvector`` nodes. The container type is chosen such that its minimum size will fit the fixed-length vector (see ``getContainerForFixedLengthVector``).
-2. The operation is then performed on the container type via a **VL (vector length) node**. These are custom nodes defined in ``RISCVInstrInfoVVLPatterns.td`` that mirror target agnostic SelectionDAG nodes, as well as some RVV instructions. They contain an AVL operand, which is set to the number of elements in the fixed-length vector.
- Some nodes also have a passthru or mask operand, which will usually be set to ``undef`` and all ones when lowering fixed-length vectors.
-3. The result is put back into a fixed-length vector via ``extract_subvector``.
-
-.. code-block::
+1. The fixed-length vector operands are inserted into scalable containers with `insert_subvector` nodes. The container type is chosen such that its minimum size will fit the fixed-length vector (see `getContainerForFixedLengthVector`).
+2. The operation is then performed on the container type via a **VL (vector length) node**. These are custom nodes defined in `RISCVInstrInfoVVLPatterns.td` that mirror target agnostic SelectionDAG nodes, as well as some RVV instructions. They contain an AVL operand, which is set to the number of elements in the fixed-length vector.
+ Some nodes also have a passthru or mask operand, which will usually be set to `undef` and all ones when lowering fixed-length vectors.
+3. The result is put back into a fixed-length vector via `extract_subvector`.
- t2: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %0
- t6: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %1
- t4: v4i32 = extract_subvector t2, Constant:i64<0>
- t7: v4i32 = extract_subvector t6, Constant:i64<0>
- t8: v4i32 = add t4, t7
+```
+ t2: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %0
+ t6: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %1
+ t4: v4i32 = extract_subvector t2, Constant:i64<0>
+ t7: v4i32 = extract_subvector t6, Constant:i64<0>
+t8: v4i32 = add t4, t7
- // is custom lowered to:
+// is custom lowered to:
- t2: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %0
- t6: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %1
- t15: nxv2i1 = RISCVISD::VMSET_VL Constant:i64<4>
- t16: nxv2i32 = RISCVISD::ADD_VL t2, t6, undef:nxv2i32, t15, Constant:i64<4>
- t17: v4i32 = extract_subvector t16, Constant:i64<0>
+ t2: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %0
+ t6: nxv2i32,ch = CopyFromReg t0, Register:nxv2i32 %1
+ t15: nxv2i1 = RISCVISD::VMSET_VL Constant:i64<4>
+ t16: nxv2i32 = RISCVISD::ADD_VL t2, t6, undef:nxv2i32, t15, Constant:i64<4>
+t17: v4i32 = extract_subvector t16, Constant:i64<0>
+```
-VL nodes often have a passthru or mask operand, which are usually set to ``undef`` and all ones for fixed-length vectors.
+VL nodes often have a passthru or mask operand, which are usually set to `undef` and all ones for fixed-length vectors.
-The ``insert_subvector`` and ``extract_subvector`` nodes responsible for wrapping and unwrapping will get combined away, and eventually we will lower all fixed-length vector types to scalable. Note that fixed-length vectors at the interface of a function are passed in a scalable vector container.
+The `insert_subvector` and `extract_subvector` nodes responsible for wrapping and unwrapping will get combined away, and eventually we will lower all fixed-length vector types to scalable. Note that fixed-length vectors at the interface of a function are passed in a scalable vector container.
-.. note::
+:::{note}
+The only `insert_subvector` and `extract_subvector` nodes that make it through lowering are those that can be performed as an exact subregister insert or extract. This means that any fixed-length vector `insert_subvector` and `extract_subvector` nodes that aren't legalized must lie on a register group boundary, so the exact VLEN must be known at compile time (i.e., compiled with `-mrvv-vector-bits=zvl` or `-mllvm -riscv-v-vector-bits-max=VLEN`, or have an exact `vscale_range` attribute).
+:::
- The only ``insert_subvector`` and ``extract_subvector`` nodes that make it through lowering are those that can be performed as an exact subregister insert or extract. This means that any fixed-length vector ``insert_subvector`` and ``extract_subvector`` nodes that aren't legalized must lie on a register group boundary, so the exact VLEN must be known at compile time (i.e., compiled with ``-mrvv-vector-bits=zvl`` or ``-mllvm -riscv-v-vector-bits-max=VLEN``, or have an exact ``vscale_range`` attribute).
-
-Vector predication intrinsics
------------------------------
+### Vector predication intrinsics
VP intrinsics also get custom lowered via VL nodes.
-.. code-block::
-
- t12: nxv2i32 = vp_add t2, t4, t6, Constant:i64<8>
-
- // is custom lowered to:
+```
+t12: nxv2i32 = vp_add t2, t4, t6, Constant:i64<8>
- t18: nxv2i32 = RISCVISD::ADD_VL t2, t4, undef:nxv2i32, t6, Constant:i64<8>
+// is custom lowered to:
-The VP EVL and mask are used for the VL node's AVL and mask respectively, whilst the passthru is set to ``undef``.
+t18: nxv2i32 = RISCVISD::ADD_VL t2, t4, undef:nxv2i32, t6, Constant:i64<8>
+```
-Instruction selection
-=====================
+The VP EVL and mask are used for the VL node's AVL and mask respectively, whilst the passthru is set to `undef`.
-``vl`` and ``vtype`` need to be configured correctly, so we can't just directly select the underlying vector ``MachineInstr``. Instead pseudo instructions are selected, which carry the extra information needed to emit the necessary ``vsetvli``\s later.
+## Instruction selection
-.. code-block::
+`vl` and `vtype` need to be configured correctly, so we can't just directly select the underlying vector `MachineInstr`. Instead pseudo instructions are selected, which carry the extra information needed to emit the necessary `vsetvli`s later.
- %c:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %a:vrm2, %b:vrm2, %vl:gpr, 5 /*sew*/, 3 /*policy*/
+```
+%c:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %a:vrm2, %b:vrm2, %vl:gpr, 5 /*sew*/, 3 /*policy*/
+```
-Each vector instruction has multiple pseudo instructions defined in ``RISCVInstrInfoVPseudos.td``.
-There is a variant of each pseudo for each possible LMUL, as well as a masked variant. So a typical instruction like ``vadd.vv`` would have the following pseudos:
+Each vector instruction has multiple pseudo instructions defined in `RISCVInstrInfoVPseudos.td`.
+There is a variant of each pseudo for each possible LMUL, as well as a masked variant. So a typical instruction like `vadd.vv` would have the following pseudos:
-.. code-block::
-
- %rd:vr = PseudoVADD_VV_MF8 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_MF4 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_MF2 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_M1 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
- %rd:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %avl:gpr, sew:imm, policy:imm
- %rd:vrm4 = PseudoVADD_VV_M4 %passthru:vrm4(tied-def 0), %rs2:vrm4, %rs1:vrm4, %avl:gpr, sew:imm, policy:imm
- %rd:vrm8 = PseudoVADD_VV_M8 %passthru:vrm8(tied-def 0), %rs2:vrm8, %rs1:vrm8, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_MF8_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_MF4_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_MF2_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vr = PseudoVADD_VV_M1_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vrm2 = PseudoVADD_VV_M2_MASK %passthru:vrm2(tied-def 0), %rs2:vrm2, %%rs1:vrm2, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vrm4 = PseudoVADD_VV_M4_MASK %passthru:vrm4(tied-def 0), %rs2:vrm4, %rs1:vrm4, mask:$v0, %avl:gpr, sew:imm, policy:imm
- %rd:vrm8 = PseudoVADD_VV_M8_MASK %passthru:vrm8(tied-def 0), %rs2:vrm8, %rs1:vrm8, mask:$v0, %avl:gpr, sew:imm, policy:imm
-
-.. note::
-
- Whilst the SEW can be encoded in an operand, we need to use separate pseudos for each LMUL since different register groups will require different register classes: see :ref:`rvv_register_allocation`.
+```
+%rd:vr = PseudoVADD_VV_MF8 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_MF4 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_MF2 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_M1 %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, %avl:gpr, sew:imm, policy:imm
+%rd:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %avl:gpr, sew:imm, policy:imm
+%rd:vrm4 = PseudoVADD_VV_M4 %passthru:vrm4(tied-def 0), %rs2:vrm4, %rs1:vrm4, %avl:gpr, sew:imm, policy:imm
+%rd:vrm8 = PseudoVADD_VV_M8 %passthru:vrm8(tied-def 0), %rs2:vrm8, %rs1:vrm8, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_MF8_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_MF4_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_MF2_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vr = PseudoVADD_VV_M1_MASK %passthru:vr(tied-def 0), %rs2:vr, %rs1:vr, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vrm2 = PseudoVADD_VV_M2_MASK %passthru:vrm2(tied-def 0), %rs2:vrm2, %%rs1:vrm2, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vrm4 = PseudoVADD_VV_M4_MASK %passthru:vrm4(tied-def 0), %rs2:vrm4, %rs1:vrm4, mask:$v0, %avl:gpr, sew:imm, policy:imm
+%rd:vrm8 = PseudoVADD_VV_M8_MASK %passthru:vrm8(tied-def 0), %rs2:vrm8, %rs1:vrm8, mask:$v0, %avl:gpr, sew:imm, policy:imm
+```
+:::{note}
+Whilst the SEW can be encoded in an operand, we need to use separate pseudos for each LMUL since different register groups will require different register classes: see {ref}`rvv_register_allocation`.
+:::
Pseudos have operands for the AVL and SEW (encoded as a power of 2), as well as potentially the mask, policy or rounding mode if applicable.
The passthru operand is tied to the destination register which will determine the inactive/tail elements.
-For scalable vectors that should use VLMAX, the AVL is set to a sentinel value of ``-1``.
+For scalable vectors that should use VLMAX, the AVL is set to a sentinel value of `-1`.
-There are patterns for target agnostic SelectionDAG nodes in ``RISCVInstrInfoVSDPatterns.td``, VL nodes in ``RISCVInstrInfoVVLPatterns.td`` and RVV intrinsics in ``RISCVInstrInfoVPseudos.td``.
+There are patterns for target agnostic SelectionDAG nodes in `RISCVInstrInfoVSDPatterns.td`, VL nodes in `RISCVInstrInfoVVLPatterns.td` and RVV intrinsics in `RISCVInstrInfoVPseudos.td`.
Instructions that operate only on masks like VMAND or VMSBF uses pseudo instructions suffixed with B1, B2, B4, B8, B16, B32, or B64 where the number is SEW/LMUL representing
the ratio between SEW and LMUL needed in vtype. These instructions always operate as if EEW=1 and always use a value of 0 as their SEW operand.
-Mask patterns
--------------
-
-The patterns in ``RISCVInstrInfoVVLPatterns.td`` only match masked pseudos to reduce the size of the match table, even if the node's mask is all ones and could be an unmasked pseudo.
-``RISCVVectorPeephole::convertToUnmasked`` will detect if the mask is all ones and convert it into its unmasked form.
-
-.. code-block::
-
- %mask:vmv0 = PseudoVMSET_M_B16 -1, 32
- %rd:vrm2 = PseudoVADD_VV_M2_MASK %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %mask:vmv0, %avl:gpr, sew:imm, policy:imm
-
- // gets optimized to:
+### Mask patterns
- %rd:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %avl:gpr, sew:imm, policy:imm
+The patterns in `RISCVInstrInfoVVLPatterns.td` only match masked pseudos to reduce the size of the match table, even if the node's mask is all ones and could be an unmasked pseudo.
+`RISCVVectorPeephole::convertToUnmasked` will detect if the mask is all ones and convert it into its unmasked form.
-.. note::
+```
+%mask:vmv0 = PseudoVMSET_M_B16 -1, 32
+%rd:vrm2 = PseudoVADD_VV_M2_MASK %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %mask:vmv0, %avl:gpr, sew:imm, policy:imm
- Any ``vmset.m`` can be treated as an all ones mask since the tail elements past AVL are ``undef`` and can be replaced with ones.
+// gets optimized to:
-.. _RISCVVLOptimizer:
+%rd:vrm2 = PseudoVADD_VV_M2 %passthru:vrm2(tied-def 0), %rs2:vrm2, %rs1:vrm2, %avl:gpr, sew:imm, policy:imm
+```
-RISCVVLOptimizer
-================
+:::{note}
+Any `vmset.m` can be treated as an all ones mask since the tail elements past AVL are `undef` and can be replaced with ones.
+:::
-After instruction selection, ``RISCVVLOptimizer.cpp`` will reduce the AVL of vector pseudos to only what is demanded from its users. This helps performance on microarchitectures which have performance characteristics dependent on ``vl``, and also avoids unnecessary ``vsetvli`` toggles.
+(riscvvloptimizer)=
-.. code-block::
+## RISCVVLOptimizer
- %x:vr = PseudoVADD_VV_M1 undef, %a:vr, %b:vr, -1 /*avl*/, 5 /*sew*/, 3 /*policy*/
- %y:vr = PseudoVADD_VV_M1 undef, %%y:vr, %x:vr, -1 /*avl*/, 5 /*sew*/, 3 /*policy*/
- PseudoVSE32_V_M1 %y, %addr, 4 /*avl*/, 5 /*sew*/
+After instruction selection, `RISCVVLOptimizer.cpp` will reduce the AVL of vector pseudos to only what is demanded from its users. This helps performance on microarchitectures which have performance characteristics dependent on `vl`, and also avoids unnecessary `vsetvli` toggles.
- // gets optimized to:
+```
+%x:vr = PseudoVADD_VV_M1 undef, %a:vr, %b:vr, -1 /*avl*/, 5 /*sew*/, 3 /*policy*/
+%y:vr = PseudoVADD_VV_M1 undef, %%y:vr, %x:vr, -1 /*avl*/, 5 /*sew*/, 3 /*policy*/
+PseudoVSE32_V_M1 %y, %addr, 4 /*avl*/, 5 /*sew*/
- %x:vr = PseudoVADD_VV_M1 undef, %a:vr, %b:vr, 5 /*avl*/, 5 /*sew*/, 3 /*policy*/
- %y:vr = PseudoVADD_VV_M1 undef, %%y:vr, %x:vr, 5 /*avl*/, 5 /*sew*/, 3 /*policy*/
- PseudoVSE32_V_M1 %y, %addr, 4 /*avl*/, 5 /*sew*/
+// gets optimized to:
-For a vector pseudo to be considered for AVL optimisation, its underlying instruction must specify that its output doesn't depend on ``vl`` in the ``ElementsDependOn`` TSFlag. The default for this flag is conservatively set to depending on ``vl``, so AVL optimisation will be off by default.
+%x:vr = PseudoVADD_VV_M1 undef, %a:vr, %b:vr, 5 /*avl*/, 5 /*sew*/, 3 /*policy*/
+%y:vr = PseudoVADD_VV_M1 undef, %%y:vr, %x:vr, 5 /*avl*/, 5 /*sew*/, 3 /*policy*/
+PseudoVSE32_V_M1 %y, %addr, 4 /*avl*/, 5 /*sew*/
+```
-VMV0 elimination
-=================
+For a vector pseudo to be considered for AVL optimisation, its underlying instruction must specify that its output doesn't depend on `vl` in the `ElementsDependOn` TSFlag. The default for this flag is conservatively set to depending on `vl`, so AVL optimisation will be off by default.
-Because masked instructions must have the mask register in ``v0``, a specific register class ``vmv0`` is used that contains only one register, ``v0``.
+## VMV0 elimination
-However register coalescing may end up coalescing copies into ``vmv0``, resulting in instructions with multiple uses of ``vmv0`` that the register allocator can't allocate:
+Because masked instructions must have the mask register in `v0`, a specific register class `vmv0` is used that contains only one register, `v0`.
-.. code-block::
+However register coalescing may end up coalescing copies into `vmv0`, resulting in instructions with multiple uses of `vmv0` that the register allocator can't allocate:
- %x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vmv0, %3:vmv0, ...
+```
+%x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vmv0, %3:vmv0, ...
+```
-To avoid this, ``RISCVVMV0Elimination`` replaces any uses of ``vmv0`` with physical copies to ``v0`` before register coalescing and allocation:
+To avoid this, `RISCVVMV0Elimination` replaces any uses of `vmv0` with physical copies to `v0` before register coalescing and allocation:
-.. code-block::
-
- %x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vr, %3:vmv0, ...
+```
+%x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vr, %3:vmv0, ...
- // vmv0 gets eliminated to:
+// vmv0 gets eliminated to:
- $v0 = COPY %3:vr
- %x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vr, $v0, ...
+$v0 = COPY %3:vr
+%x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vr, $v0, ...
+```
-.. _rvv_register_allocation:
+(rvv-register-allocation)=
-Register allocation
-===================
+## Register allocation
Register allocation is split between vector and scalar registers, with vector allocation running first:
-.. code-block::
+```
+$v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, %vl:gpr, 5, 3
+```
- $v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, %vl:gpr, 5, 3
+:::{note}
+Register allocation is split so that {ref}`RISCVInsertVSETVLI` can run after vector register allocation, but before scalar register allocation. It needs to be run before scalar register allocation as it may need to create a new virtual register to set the AVL to VLMAX.
-.. note::
-
- Register allocation is split so that :ref:`RISCVInsertVSETVLI` can run after vector register allocation, but before scalar register allocation. It needs to be run before scalar register allocation as it may need to create a new virtual register to set the AVL to VLMAX.
-
- Performing ``RISCVInsertVSETVLI`` after vector register allocation imposes fewer constraints on the machine scheduler since it cannot schedule instructions past ``vsetvli``\s, and it allows us to emit further vector pseudos during spilling or constant rematerialization.
+Performing `RISCVInsertVSETVLI` after vector register allocation imposes fewer constraints on the machine scheduler since it cannot schedule instructions past `vsetvli`s, and it allows us to emit further vector pseudos during spilling or constant rematerialization.
+:::
There are four register classes for vectors:
-- ``VR`` for vector registers (``v0``, ``v1,``, ..., ``v31``). Used when :math:`\text{LMUL} \leq 1` and mask registers.
-- ``VRM2`` for vector groups of length 2 i.e., :math:`\text{LMUL}=2` (``v0m2``, ``v2m2``, ..., ``v30m2``)
-- ``VRM4`` for vector groups of length 4 i.e., :math:`\text{LMUL}=4` (``v0m4``, ``v4m4``, ..., ``v28m4``)
-- ``VRM8`` for vector groups of length 8 i.e., :math:`\text{LMUL}=8` (``v0m8``, ``v8m8``, ..., ``v24m8``)
-
-:math:`\text{LMUL} \lt 1` types and mask types do not benefit from having a dedicated class, so ``VR`` is used in their case.
+- `VR` for vector registers (`v0`, `v1,`, ..., `v31`). Used when $\text{LMUL} \leq 1$ and mask registers.
+- `VRM2` for vector groups of length 2 i.e., $\text{LMUL}=2$ (`v0m2`, `v2m2`, ..., `v30m2`)
+- `VRM4` for vector groups of length 4 i.e., $\text{LMUL}=4$ (`v0m4`, `v4m4`, ..., `v28m4`)
+- `VRM8` for vector groups of length 8 i.e., $\text{LMUL}=8$ (`v0m8`, `v8m8`, ..., `v24m8`)
-Some instructions have a constraint that a register operand cannot be ``V0`` or overlap with ``V0``, so for these cases we also have ``VRNoV0`` variants.
+$\text{LMUL} \lt 1$ types and mask types do not benefit from having a dedicated class, so `VR` is used in their case.
-.. _RISCVInsertVSETVLI:
+Some instructions have a constraint that a register operand cannot be `V0` or overlap with `V0`, so for these cases we also have `VRNoV0` variants.
-RISCVInsertVSETVLI
-==================
+(riscvinsertvsetvli)=
-After vector registers are allocated, the ``RISCVInsertVSETVLI`` pass will insert the necessary ``vsetvli``\s for the pseudos.
+## RISCVInsertVSETVLI
-.. code-block::
+After vector registers are allocated, the `RISCVInsertVSETVLI` pass will insert the necessary `vsetvli`s for the pseudos.
- dead $x0 = PseudoVSETVLI %vl:gpr, 209, implicit-def $vl, implicit-def $vtype
- $v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, $noreg, 5, implicit $vl, implicit $vtype
+```
+dead $x0 = PseudoVSETVLI %vl:gpr, 209, implicit-def $vl, implicit-def $vtype
+$v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, $noreg, 5, implicit $vl, implicit $vtype
+```
-The physical ``$vl`` and ``$vtype`` registers are implicitly defined by the ``PseudoVSETVLI``, and are implicitly used by the ``PseudoVADD``.
-The ``vtype`` operand (``209`` in this example) is encoded as per the specification via ``RISCVVType::encodeVTYPE``.
+The physical `$vl` and `$vtype` registers are implicitly defined by the `PseudoVSETVLI`, and are implicitly used by the `PseudoVADD`.
+The `vtype` operand (`209` in this example) is encoded as per the specification via `RISCVVType::encodeVTYPE`.
-``RISCVInsertVSETVLI`` performs dataflow analysis to emit as few ``vsetvli``\s as possible. It will also try to minimize the number of ``vsetvli``\s that set VL, i.e., it will emit ``vsetvli x0, x0`` if only ``vtype`` needs changed but ``vl`` doesn't.
+`RISCVInsertVSETVLI` performs dataflow analysis to emit as few `vsetvli`s as possible. It will also try to minimize the number of `vsetvli`s that set VL, i.e., it will emit `vsetvli x0, x0` if only `vtype` needs changed but `vl` doesn't.
-Pseudo expansion and printing
-=============================
+## Pseudo expansion and printing
-After scalar register allocation, the ``RISCVExpandPseudoInsts.cpp`` pass expands the ``PseudoVSETVLI`` instructions.
+After scalar register allocation, the `RISCVExpandPseudoInsts.cpp` pass expands the `PseudoVSETVLI` instructions.
-.. code-block::
-
- dead $x0 = VSETVLI $x1, 209, implicit-def $vtype, implicit-def $vl
- renamable $v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, $noreg, 5, implicit $vl, implicit $vtype
+```
+dead $x0 = VSETVLI $x1, 209, implicit-def $vtype, implicit-def $vl
+renamable $v8m2 = PseudoVADD_VV_M2 $v8m2(tied-def 0), $v8m2, $v10m2, $noreg, 5, implicit $vl, implicit $vtype
+```
Note that the vector pseudo remains as it's needed to encode the register class for the LMUL. Its AVL and SEW operands are no longer used.
-``RISCVAsmPrinter`` will then lower the pseudo instructions into real ``MCInst``\s.
-
-.. code-block:: nasm
-
- vsetvli a0, zero, e32, m2, ta, ma
- vadd.vv v8, v8, v10
+`RISCVAsmPrinter` will then lower the pseudo instructions into real `MCInst`s.
+```nasm
+vsetvli a0, zero, e32, m2, ta, ma
+vadd.vv v8, v8, v10
+```
+## See also
-See also
-========
+- [[llvm-dev] [RFC] Code generation for RISC-V V-extension](https://lists.llvm.org/pipermail/llvm-dev/2020-October/145850.html)
+- [2023 LLVM Dev Mtg - Vector codegen in the RISC-V backend](https://youtu.be/-ox8iJmbp0c?feature=shared)
+- [2023 LLVM Dev Mtg - How to add an C intrinsic and code-gen it, using the RISC-V vector C intrinsics](https://youtu.be/t17O_bU1jks?feature=shared)
+- [2021 LLVM Dev Mtg “Optimizing code for scalable vector architectures”](https://youtu.be/daWLCyhwrZ8?feature=shared)
-- `[llvm-dev] [RFC] Code generation for RISC-V V-extension <https://lists.llvm.org/pipermail/llvm-dev/2020-October/145850.html>`_
-- `2023 LLVM Dev Mtg - Vector codegen in the RISC-V backend <https://youtu.be/-ox8iJmbp0c?feature=shared>`_
-- `2023 LLVM Dev Mtg - How to add an C intrinsic and code-gen it, using the RISC-V vector C intrinsics <https://youtu.be/t17O_bU1jks?feature=shared>`_
-- `2021 LLVM Dev Mtg “Optimizing code for scalable vector architectures” <https://youtu.be/daWLCyhwrZ8?feature=shared>`_
diff --git a/llvm/docs/RISCVUsage.md b/llvm/docs/RISCVUsage.md
index 8fbe60c55d64c..3ce33c2d51afb 100644
--- a/llvm/docs/RISCVUsage.md
+++ b/llvm/docs/RISCVUsage.md
@@ -1,45 +1,38 @@
-=============================
-User Guide for RISC-V Target
-=============================
+# User Guide for RISC-V Target
-
-Introduction
-============
+## Introduction
The RISC-V target provides code generation for processors implementing
-supported variations of the RISC-V specification. It lives in the
-``llvm/lib/Target/RISCV`` directory.
+supported variations of the RISC-V specification. It lives in the
+`llvm/lib/Target/RISCV` directory.
-Specification Documents
-=======================
+## Specification Documents
There have been a number of revisions to the RISC-V specifications. LLVM aims
to implement the most recent ratified version of the standard RISC-V base ISAs
and ISA extensions with pragmatic variances. The most recent specification can
-be found at: https://github.com/riscv/riscv-isa-manual/releases/.
+be found at: <https://github.com/riscv/riscv-isa-manual/releases/>.
-`The official RISC-V International specification page
-<https://riscv.org/technical/specifications/>`__. is also worth checking, but
+[The official RISC-V International specification page](https://riscv.org/technical/specifications/). is also worth checking, but
tends to significantly lag the specifications linked above. Make sure to check
-the `wiki for not yet integrated extensions
-<https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`__ and note
+the [wiki for not yet integrated extensions](https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions) and note
that in addition, we sometimes carry support for extensions that have not yet
been ratified (these will be marked as experimental - see below) and support
various vendor-specific extensions (see below).
The current known variances from the specification are:
-* Unconditionally allowing instructions from zifencei, zicsr, zicntr, and
- zihpm without gating them on the extensions being enabled. Previous
+- Unconditionally allowing instructions from zifencei, zicsr, zicntr, and
+ zihpm without gating them on the extensions being enabled. Previous
revisions of the specification included these instructions in the base
- ISA, and we preserve this behavior to avoid breaking existing code. If
+ ISA, and we preserve this behavior to avoid breaking existing code. If
a future revision of the specification reuses these opcodes for other
extensions, we may need to reevaluate this choice, and thus recommend
users migrate build systems so as not to rely on this.
-* Allowing CSRs to be named without gating on specific extensions. This
+- Allowing CSRs to be named without gating on specific extensions. This
applies to all CSR names, not just those in zicsr, zicntr, and zihpm.
-* The ordering of ``z*``, ``s*``, and ``x*`` prefixed extension names is not
- enforced in user-specified ISA naming strings (e.g. ``-march``).
+- The ordering of `z*`, `s*`, and `x*` prefixed extension names is not
+ enforced in user-specified ISA naming strings (e.g. `-march`).
We are actively deciding not to support multiple specification revisions
at this time. We acknowledge a likely future need, but actively defer the
@@ -47,675 +40,763 @@ decisions making around handling this until we have a concrete example of
real hardware having shipped and an incompatible change to the
specification made afterwards.
-Base ISAs
-=========
+## Base ISAs
The specification defines five base instruction sets: RV32I, RV32E, RV64I,
-RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I. RV32E and
-RV64E are supported by the assembly-based tools only. RV128I is not supported.
+RV64E, and RV128I. Currently, LLVM fully supports RV32I, and RV64I. RV32E and
+RV64E are supported by the assembly-based tools only. RV128I is not supported.
To specify the target triple:
- .. table:: RISC-V Architectures
-
- ============ ==============================================================
- Architecture Description
- ============ ==============================================================
- ``riscv32`` RISC-V with XLEN=32 (i.e. RV32I or RV32E)
- ``riscv64`` RISC-V with XLEN=64 (i.e. RV64I or RV64E)
- ============ ==============================================================
+> ```{eval-rst}
+> .. table:: RISC-V Architectures
+>
+> ============ ==============================================================
+> Architecture Description
+> ============ ==============================================================
+> ``riscv32`` RISC-V with XLEN=32 (i.e. RV32I or RV32E)
+> ``riscv64`` RISC-V with XLEN=64 (i.e. RV64I or RV64E)
+> ============ ==============================================================
+> ```
To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
-architecture string (e.g. ``riscv32``) with the extension ``e``.
+architecture string (e.g. `riscv32`) with the extension `e`.
-Profiles
-========
+## Profiles
-Supported profile names can be passed using ``-march`` instead of a standard
+Supported profile names can be passed using `-march` instead of a standard
ISA naming string. Currently supported profiles:
-* ``rvi20u32``
-* ``rvi20u64``
-* ``rva20u64``
-* ``rva20s64``
-* ``rva22u64``
-* ``rva22s64``
-* ``rva23u64``
-* ``rva23s64``
-* ``rvb23u64``
-* ``rvb23s64``
+- `rvi20u32`
+- `rvi20u64`
+- `rva20u64`
+- `rva20s64`
+- `rva22u64`
+- `rva22s64`
+- `rva23u64`
+- `rva23s64`
+- `rvb23u64`
+- `rvb23s64`
Note that you can also append additional extension names to be enabled, e.g.
-``rva20u64_zicond`` will enable the ``zicond`` extension in addition to those
-in the ``rva20u64`` profile.
+`rva20u64_zicond` will enable the `zicond` extension in addition to those
+in the `rva20u64` profile.
Profiles that are not yet ratified cannot be used unless
-``-menable-experimental-extensions`` (or equivalent for other tools) is
+`-menable-experimental-extensions` (or equivalent for other tools) is
specified. This applies to the following profiles:
-* ``rvm23u32``
+- `rvm23u32`
-.. _riscv-extensions:
+(riscv-extensions)=
-Extensions
-==========
+## Extensions
The following table provides a status summary for extensions which have been
-ratified and thus have finalized specifications. When relevant, detailed notes
+ratified and thus have finalized specifications. When relevant, detailed notes
on support follow.
- .. table:: Ratified Extensions by Status
-
- ================ =================================================================
- Extension Status
- ================ =================================================================
- ``A`` Supported
- ``B`` Supported
- ``C`` Supported
- ``D`` Supported
- ``F`` Supported
- ``E`` Supported (`See note <#riscv-rve-note>`__)
- ``H`` Assembly Support
- ``M`` Supported
- ``Q`` Assembly Support
- ``Sdext`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
- ``Sdtrig`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
- ``Sha`` Supported
- ``Shcounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Shgatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Shlcofideleg`` Supported
- ``Shtvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Shvsatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Shvstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Shvstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Smaia`` Supported
- ``Smcdeleg`` Supported
- ``Smcntrpmf`` Supported
- ``Smcsrind`` Supported
- ``Smctr`` Assembly Support
- ``Smdbltrp`` Supported
- ``Smepmp`` Supported
- ``Smmpm`` Supported
- ``Smnpm`` Supported
- ``Smrnmi`` Supported
- ``Smstateen`` Assembly Support
- ``Ssaia`` Supported
- ``Ssccfg`` Supported
- ``Ssccptr`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Sscofpmf`` Assembly Support
- ``Sscounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Sscsrind`` Supported
- ``Ssctr`` Assembly Support
- ``Ssdbltrp`` Supported
- ``Ssnpm`` Supported
- ``Sspm`` Supported
- ``Ssqosid`` Assembly Support
- ``Ssstateen`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Ssstrict`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Sstc`` Assembly Support
- ``Sstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Sstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Ssu64xl`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Supm`` Supported
- ``Svade`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Svadu`` Assembly Support
- ``Svbare`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
- ``Svinval`` Assembly Support
- ``Svnapot`` Assembly Support
- ``Svpbmt`` Supported
- ``Svrsw60t59b`` Supported
- ``Svvptc`` Supported
- ``V`` Supported
- ``Za128rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Za64rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Zaamo`` Assembly Support
- ``Zabha`` Supported
- ``Zacas`` Supported (`See note <#riscv-zacas-note>`__)
- ``Zalasr`` Supported
- ``Zalrsc`` Assembly Support
- ``Zama16b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Zawrs`` Assembly Support
- ``Zba`` Supported
- ``Zbb`` Supported
- ``Zbc`` Supported
- ``Zbkb`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
- ``Zbkc`` Supported
- ``Zbkx`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
- ``Zbs`` Supported
- ``Zca`` Supported
- ``Zcb`` Supported
- ``Zcd`` Supported
- ``Zcf`` Supported
- ``Zclsd`` Assembly Support
- ``Zcmop`` Supported
- ``Zcmp`` Supported
- ``Zcmt`` Assembly Support
- ``Zdinx`` Supported
- ``Zfa`` Supported
- ``Zfbfmin`` Supported
- ``Zfh`` Supported
- ``Zfhmin`` Supported
- ``Zfinx`` Supported
- ``Zhinx`` Supported
- ``Zhinxmin`` Supported
- ``Zic64b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Zicbom`` Assembly Support
- ``Zicbop`` Supported
- ``Zicboz`` Assembly Support
- ``Ziccamoa`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Ziccamoc`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Ziccid`` Supported
- ``Ziccif`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Zicclsm`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Ziccrse`` Supported (`See note <#riscv-profiles-extensions-note>`__)
- ``Zicntr`` (`See Note <#riscv-i2p1-note>`__)
- ``Zicond`` Supported
- ``Zicsr`` (`See Note <#riscv-i2p1-note>`__)
- ``Zifencei`` (`See Note <#riscv-i2p1-note>`__)
- ``Zihintntl`` Supported
- ``Zihintpause`` Assembly Support
- ``Zihpm`` (`See Note <#riscv-i2p1-note>`__)
- ``Zilsd`` Supported
- ``Zimop`` Supported
- ``Zkn`` Supported
- ``Zknd`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
- ``Zkne`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
- ``Zknh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
- ``Zksed`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
- ``Zksh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
- ``Zk`` Supported
- ``Zkr`` Supported
- ``Zks`` Supported
- ``Zkt`` Supported
- ``Zmmul`` Supported
- ``Ztso`` Supported
- ``Zvbb`` Supported
- ``Zvbc`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zve32x`` (`Partially <#riscv-vlen-32-note>`__) Supported
- ``Zve32f`` (`Partially <#riscv-vlen-32-note>`__) Supported
- ``Zve64x`` Supported
- ``Zve64f`` Supported
- ``Zve64d`` Supported
- ``Zvfbfa`` Assembly Support
- ``Zvfbfmin`` Supported
- ``Zvfbfwma`` Supported
- ``Zvfh`` Supported
- ``Zvfhmin`` Supported
- ``Zvfofp8min`` Assembly Support
- ``Zvkb`` Supported
- ``Zvkg`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvkn`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvknc`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvkned`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvkng`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvknha`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvknhb`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvks`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvksc`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvksed`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvksg`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvksh`` Supported (`See note <#riscv-vector-crypto-note>`__)
- ``Zvkt`` Supported
- ``Zvvfmm`` Assembly Support
- ``Zvvmm`` Assembly Support
- ``Zvvmtls`` Assembly Support
- ``Zvvmttls`` Assembly Support
- ``Zvl32b`` (`Partially <#riscv-vlen-32-note>`__) Supported
- ``Zvl64b`` Supported
- ``Zvl128b`` Supported
- ``Zvl256b`` Supported
- ``Zvl512b`` Supported
- ``Zvl1024b`` Supported
- ``Zvl2048b`` Supported
- ``Zvl4096b`` Supported
- ``Zvl8192b`` Supported
- ``Zvl16384b`` Supported
- ``Zvl32768b`` Supported
- ``Zvl65536b`` Supported
- ================ =================================================================
+> ```{eval-rst}
+> .. table:: Ratified Extensions by Status
+>
+> ================ =================================================================
+> Extension Status
+> ================ =================================================================
+> ``A`` Supported
+> ``B`` Supported
+> ``C`` Supported
+> ``D`` Supported
+> ``F`` Supported
+> ``E`` Supported (`See note <#riscv-rve-note>`__)
+> ``H`` Assembly Support
+> ``M`` Supported
+> ``Q`` Assembly Support
+> ``Sdext`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
+> ``Sdtrig`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
+> ``Sha`` Supported
+> ``Shcounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Shgatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Shlcofideleg`` Supported
+> ``Shtvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Shvsatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Shvstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Shvstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Smaia`` Supported
+> ``Smcdeleg`` Supported
+> ``Smcntrpmf`` Supported
+> ``Smcsrind`` Supported
+> ``Smctr`` Assembly Support
+> ``Smdbltrp`` Supported
+> ``Smepmp`` Supported
+> ``Smmpm`` Supported
+> ``Smnpm`` Supported
+> ``Smrnmi`` Supported
+> ``Smstateen`` Assembly Support
+> ``Ssaia`` Supported
+> ``Ssccfg`` Supported
+> ``Ssccptr`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Sscofpmf`` Assembly Support
+> ``Sscounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Sscsrind`` Supported
+> ``Ssctr`` Assembly Support
+> ``Ssdbltrp`` Supported
+> ``Ssnpm`` Supported
+> ``Sspm`` Supported
+> ``Ssqosid`` Assembly Support
+> ``Ssstateen`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Ssstrict`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Sstc`` Assembly Support
+> ``Sstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Sstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Ssu64xl`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Supm`` Supported
+> ``Svade`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Svadu`` Assembly Support
+> ``Svbare`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
+> ``Svinval`` Assembly Support
+> ``Svnapot`` Assembly Support
+> ``Svpbmt`` Supported
+> ``Svrsw60t59b`` Supported
+> ``Svvptc`` Supported
+> ``V`` Supported
+> ``Za128rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Za64rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Zaamo`` Assembly Support
+> ``Zabha`` Supported
+> ``Zacas`` Supported (`See note <#riscv-zacas-note>`__)
+> ``Zalasr`` Supported
+> ``Zalrsc`` Assembly Support
+> ``Zama16b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Zawrs`` Assembly Support
+> ``Zba`` Supported
+> ``Zbb`` Supported
+> ``Zbc`` Supported
+> ``Zbkb`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
+> ``Zbkc`` Supported
+> ``Zbkx`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
+> ``Zbs`` Supported
+> ``Zca`` Supported
+> ``Zcb`` Supported
+> ``Zcd`` Supported
+> ``Zcf`` Supported
+> ``Zclsd`` Assembly Support
+> ``Zcmop`` Supported
+> ``Zcmp`` Supported
+> ``Zcmt`` Assembly Support
+> ``Zdinx`` Supported
+> ``Zfa`` Supported
+> ``Zfbfmin`` Supported
+> ``Zfh`` Supported
+> ``Zfhmin`` Supported
+> ``Zfinx`` Supported
+> ``Zhinx`` Supported
+> ``Zhinxmin`` Supported
+> ``Zic64b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Zicbom`` Assembly Support
+> ``Zicbop`` Supported
+> ``Zicboz`` Assembly Support
+> ``Ziccamoa`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Ziccamoc`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Ziccid`` Supported
+> ``Ziccif`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Zicclsm`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Ziccrse`` Supported (`See note <#riscv-profiles-extensions-note>`__)
+> ``Zicntr`` (`See Note <#riscv-i2p1-note>`__)
+> ``Zicond`` Supported
+> ``Zicsr`` (`See Note <#riscv-i2p1-note>`__)
+> ``Zifencei`` (`See Note <#riscv-i2p1-note>`__)
+> ``Zihintntl`` Supported
+> ``Zihintpause`` Assembly Support
+> ``Zihpm`` (`See Note <#riscv-i2p1-note>`__)
+> ``Zilsd`` Supported
+> ``Zimop`` Supported
+> ``Zkn`` Supported
+> ``Zknd`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
+> ``Zkne`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
+> ``Zknh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
+> ``Zksed`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
+> ``Zksh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
+> ``Zk`` Supported
+> ``Zkr`` Supported
+> ``Zks`` Supported
+> ``Zkt`` Supported
+> ``Zmmul`` Supported
+> ``Ztso`` Supported
+> ``Zvbb`` Supported
+> ``Zvbc`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zve32x`` (`Partially <#riscv-vlen-32-note>`__) Supported
+> ``Zve32f`` (`Partially <#riscv-vlen-32-note>`__) Supported
+> ``Zve64x`` Supported
+> ``Zve64f`` Supported
+> ``Zve64d`` Supported
+> ``Zvfbfa`` Assembly Support
+> ``Zvfbfmin`` Supported
+> ``Zvfbfwma`` Supported
+> ``Zvfh`` Supported
+> ``Zvfhmin`` Supported
+> ``Zvfofp8min`` Assembly Support
+> ``Zvkb`` Supported
+> ``Zvkg`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvkn`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvknc`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvkned`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvkng`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvknha`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvknhb`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvks`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvksc`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvksed`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvksg`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvksh`` Supported (`See note <#riscv-vector-crypto-note>`__)
+> ``Zvkt`` Supported
+> ``Zvvfmm`` Assembly Support
+> ``Zvvmm`` Assembly Support
+> ``Zvvmtls`` Assembly Support
+> ``Zvvmttls`` Assembly Support
+> ``Zvl32b`` (`Partially <#riscv-vlen-32-note>`__) Supported
+> ``Zvl64b`` Supported
+> ``Zvl128b`` Supported
+> ``Zvl256b`` Supported
+> ``Zvl512b`` Supported
+> ``Zvl1024b`` Supported
+> ``Zvl2048b`` Supported
+> ``Zvl4096b`` Supported
+> ``Zvl8192b`` Supported
+> ``Zvl16384b`` Supported
+> ``Zvl32768b`` Supported
+> ``Zvl65536b`` Supported
+> ================ =================================================================
+> ```
Assembly Support
- LLVM supports the associated instructions in assembly. All assembly related tools (e.g. assembler, disassembler, llvm-objdump, etc..) are supported. Compiler and linker will accept extension names, and linked binaries will contain appropriate ELF flags and attributes to reflect use of named extension.
+
+: LLVM supports the associated instructions in assembly. All assembly related tools (e.g. assembler, disassembler, llvm-objdump, etc..) are supported. Compiler and linker will accept extension names, and linked binaries will contain appropriate ELF flags and attributes to reflect use of named extension.
Supported
- Fully supported by the compiler. This includes everything in Assembly Support, along with - if relevant - C language intrinsics for the instructions and pattern matching by the compiler to recognize idiomatic patterns which can be lowered to the associated instructions.
-.. _riscv-rve-note:
+: Fully supported by the compiler. This includes everything in Assembly Support, along with - if relevant - C language intrinsics for the instructions and pattern matching by the compiler to recognize idiomatic patterns which can be lowered to the associated instructions.
+
+(riscv-rve-note)=
+
+`E`
+
+: Support of RV32E/RV64E and ilp32e/lp64e ABIs are experimental. To be compatible with the implementation of ilp32e in GCC, we don't use aligned registers to pass variadic arguments. Furthermore, we set the stack alignment to 4 bytes for types with length of 2\*XLEN.
+
+(riscv-scalar-crypto-note1)=
-``E``
- Support of RV32E/RV64E and ilp32e/lp64e ABIs are experimental. To be compatible with the implementation of ilp32e in GCC, we don't use aligned registers to pass variadic arguments. Furthermore, we set the stack alignment to 4 bytes for types with length of 2*XLEN.
+`Zbkb`, `Zbkx`
-.. _riscv-scalar-crypto-note1:
+: Pattern matching support for these instructions is incomplete.
-``Zbkb``, ``Zbkx``
- Pattern matching support for these instructions is incomplete.
+(riscv-scalar-crypto-note2)=
-.. _riscv-scalar-crypto-note2:
+`Zknd`, `Zkne`, `Zknh`, `Zksed`, `Zksh`
-``Zknd``, ``Zkne``, ``Zknh``, ``Zksed``, ``Zksh``
- No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls.
+: No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls.
-.. _riscv-vector-crypto-note:
+(riscv-vector-crypto-note)=
-``Zvbc``, ``Zvkg``, ``Zvkn``, ``Zvknc``, ``Zvkned``, ``Zvkng``, ``Zvknha``, ``Zvknhb``, ``Zvks``, ``Zvks``, ``Zvks``, ``Zvksc``, ``Zvksed``, ``Zvksg``, ``Zvksh``.
- No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls.
+`Zvbc`, `Zvkg`, `Zvkn`, `Zvknc`, `Zvkned`, `Zvkng`, `Zvknha`, `Zvknhb`, `Zvks`, `Zvks`, `Zvks`, `Zvksc`, `Zvksed`, `Zvksg`, `Zvksh`.
-.. _riscv-vlen-32-note:
+: No pattern matching exists. As a result, these instructions can only be used from assembler or via intrinsic calls.
-``Zve32x``, ``Zve32f``, ``Zvl32b``
- LLVM currently assumes a minimum VLEN (vector register width) of 64 bits during compilation, and as a result ``Zve32x`` and ``Zve32f`` are supported only for VLEN>=64. Assembly support doesn't have this restriction.
+(riscv-vlen-32-note)=
-.. _riscv-i2p1-note:
+`Zve32x`, `Zve32f`, `Zvl32b`
-``Zicntr``, ``Zicsr``, ``Zifencei``, ``Zihpm``
- Between versions 2.0 and 2.1 of the base I specification, a backwards incompatible change was made to remove selected instructions and CSRs from the base ISA. These instructions were grouped into a set of new extensions, but were no longer required by the base ISA. This change is partially described in "Preface to Document Version 20190608-Base-Ratified" from the specification document (the ``zicntr`` and ``zihpm`` bits are not mentioned). LLVM currently implements version 2.1 of the base specification. To maintain compatibility, instructions from these extensions are accepted without being in the ``-march`` string. LLVM also allows the explicit specification of the extensions in an ``-march`` string.
+: LLVM currently assumes a minimum VLEN (vector register width) of 64 bits during compilation, and as a result `Zve32x` and `Zve32f` are supported only for VLEN>=64. Assembly support doesn't have this restriction.
-.. _riscv-profiles-extensions-note:
+(riscv-i2p1-note)=
-``Za128rs``, ``Za64rs``, ``Zama16b``, ``Zic64b``, ``Ziccamoa``, ``Ziccamoc``, ``Ziccif``, ``Zicclsm``, ``Ziccrse``, ``Shcounterenvw``, ``Shgatpa``, ``Shtvala``, ``Shvsatpa``, ``Shvstvala``, ``Shvstvecd``, ``Ssccptr``, ``Sscounterenw``, ``Ssstateen``, ``Ssstrict``, ``Sstvala``, ``Sstvecd``, ``Ssu64xl``, ``Svade``, ``Svbare``
- These extensions are defined as part of the `RISC-V Profiles specification <https://github.com/riscv/riscv-profiles/releases/tag/v1.0>`__. They do not introduce any new features themselves, but instead describe existing hardware features.
+`Zicntr`, `Zicsr`, `Zifencei`, `Zihpm`
-.. _riscv-debug-specification-note:
+: Between versions 2.0 and 2.1 of the base I specification, a backwards incompatible change was made to remove selected instructions and CSRs from the base ISA. These instructions were grouped into a set of new extensions, but were no longer required by the base ISA. This change is partially described in "Preface to Document Version 20190608-Base-Ratified" from the specification document (the `zicntr` and `zihpm` bits are not mentioned). LLVM currently implements version 2.1 of the base specification. To maintain compatibility, instructions from these extensions are accepted without being in the `-march` string. LLVM also allows the explicit specification of the extensions in an `-march` string.
-``Sdext``, ``Sdtrig`` `The RISC-V Debug Specification <https://github.com/riscv/riscv-debug-spec/releases/download/1.0/riscv-debug-specification.pdf>`__.
+(riscv-profiles-extensions-note)=
-.. _riscv-zacas-note:
+`Za128rs`, `Za64rs`, `Zama16b`, `Zic64b`, `Ziccamoa`, `Ziccamoc`, `Ziccif`, `Zicclsm`, `Ziccrse`, `Shcounterenvw`, `Shgatpa`, `Shtvala`, `Shvsatpa`, `Shvstvala`, `Shvstvecd`, `Ssccptr`, `Sscounterenw`, `Ssstateen`, `Ssstrict`, `Sstvala`, `Sstvecd`, `Ssu64xl`, `Svade`, `Svbare`
-``Zacas``
- The compiler will not generate amocas.d on RV32 or amocas.q on RV64 due to ABI compatibility. These can only be used in the assembler.
+: These extensions are defined as part of the [RISC-V Profiles specification](https://github.com/riscv/riscv-profiles/releases/tag/v1.0). They do not introduce any new features themselves, but instead describe existing hardware features.
-Atomics ABIs
-============
+(riscv-debug-specification-note)=
-At the time of writing there are three atomics mappings (ABIs) `defined for RISC-V <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#tag_riscv_atomic_abi-14-uleb128version>`__. As of LLVM 19, LLVM defaults to "A6S", which is compatible with both the original "A6" and the future "A7" ABI. See `the psABI atomics document <https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-atomic.adoc>`__ for more information on these mappings.
+`Sdext`, `Sdtrig` [The RISC-V Debug Specification](https://github.com/riscv/riscv-debug-spec/releases/download/1.0/riscv-debug-specification.pdf).
+
+(riscv-zacas-note)=
+
+`Zacas`
+
+: The compiler will not generate amocas.d on RV32 or amocas.q on RV64 due to ABI compatibility. These can only be used in the assembler.
+
+## Atomics ABIs
+
+At the time of writing there are three atomics mappings (ABIs) [defined for RISC-V](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-elf.adoc#tag_riscv_atomic_abi-14-uleb128version). As of LLVM 19, LLVM defaults to "A6S", which is compatible with both the original "A6" and the future "A7" ABI. See [the psABI atomics document](https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-atomic.adoc) for more information on these mappings.
Note that although the "A6S" mapping is used, the ELF attribute recording the mapping isn't currently emitted by default due to a bug causing a crash in older versions of binutils when processing files containing this attribute.
-Experimental Extensions
-=======================
+## Experimental Extensions
+
+LLVM supports (to various degrees) a number of experimental extensions. All experimental extensions have `experimental-` as a prefix. There is explicitly no compatibility promised between versions of the toolchain, and regular users are strongly advised *not* to make use of experimental extensions before they reach ratification.
+
+The primary goal of experimental support is to assist in the process of ratification by providing an existence proof of an implementation, and simplifying efforts to validate the value of a proposed extension against large code bases. Experimental extensions are expected to either transition to ratified status, or be eventually removed. The decision on whether to accept an experimental extension is currently done on an entirely case by case basis; if you want to propose one, attending the bi-weekly RISC-V sync-up call is strongly advised.
+
+`experimental-p`
+
+: LLVM implements the [0.21 draft specification](https://github.com/riscv/riscv-p-spec/blob/master/P-ext-proposal.adoc).
+
+`experimental-zibi`
+
+: LLVM implements the [0.1 release specification](https://github.com/riscv/zibi/releases/tag/v0.1.0).
+
+`experimental-zicfilp`, `experimental-zicfiss`
+
+: LLVM implements the [1.0 release specification](https://github.com/riscv/riscv-cfi/releases/tag/v1.0).
+
+`experimental-smcsps`, `experimental-sscsps`, `experimental-smijt`, `experimental-ssijt`, `experimental-smehv`, `experimental-ssehv`
+
+: LLVM implements the [0.19 release specification](https://github.com/riscv/riscv-fast-interrupt/releases/tag/v0.19).
+
+`experimental-zvbc32e`, `experimental-zvkgs`
+
+: LLVM implements the [0.7 release specification](https://github.com/user-attachments/files/16450464/riscv-crypto-spec-vector-extra_v0.0.7.pdf).
+
+`experimental-svukte`
-LLVM supports (to various degrees) a number of experimental extensions. All experimental extensions have ``experimental-`` as a prefix. There is explicitly no compatibility promised between versions of the toolchain, and regular users are strongly advised *not* to make use of experimental extensions before they reach ratification.
+: LLVM implements the [1.0 draft specification](https://github.com/riscv/riscv-isa-manual/pull/1564).
-The primary goal of experimental support is to assist in the process of ratification by providing an existence proof of an implementation, and simplifying efforts to validate the value of a proposed extension against large code bases. Experimental extensions are expected to either transition to ratified status, or be eventually removed. The decision on whether to accept an experimental extension is currently done on an entirely case by case basis; if you want to propose one, attending the bi-weekly RISC-V sync-up call is strongly advised.
+`experimental-zvdot4a8i`
-``experimental-p``
- LLVM implements the `0.21 draft specification <https://github.com/riscv/riscv-p-spec/blob/master/P-ext-proposal.adoc>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/riscv-isa-manual/pull/2576).
-``experimental-zibi``
- LLVM implements the `0.1 release specification <https://github.com/riscv/zibi/releases/tag/v0.1.0>`__.
+`experimental-zvqwdota8i`, `experimental-zvqwdota16i`, `experimental-zvfwdota16bf`, `experimental-zvfqwdota8f`
-``experimental-zicfilp``, ``experimental-zicfiss``
- LLVM implements the `1.0 release specification <https://github.com/riscv/riscv-cfi/releases/tag/v1.0>`__.
+: LLVM implements the [0.2 draft specification](https://github.com/aswaterman/riscv-misc/blob/main/isa/ldot-bdot/ldot-bdot.adoc).
-``experimental-smcsps``, ``experimental-sscsps``, ``experimental-smijt``, ``experimental-ssijt``, ``experimental-smehv``, ``experimental-ssehv``
- LLVM implements the `0.19 release specification <https://github.com/riscv/riscv-fast-interrupt/releases/tag/v0.19>`__.
+`experimental-smpmpmt`
-``experimental-zvbc32e``, ``experimental-zvkgs``
- LLVM implements the `0.7 release specification <https://github.com/user-attachments/files/16450464/riscv-crypto-spec-vector-extra_v0.0.7.pdf>`__.
+: LLVM implements the [0.6 draft specification](https://github.com/riscv/riscv-isa-manual/blob/smpmpmt/src/smpmpmt.adoc).
-``experimental-svukte``
- LLVM implements the `1.0 draft specification <https://github.com/riscv/riscv-isa-manual/pull/1564>`__.
+`experimental-zvabd`
-``experimental-zvdot4a8i``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/riscv-isa-manual/pull/2576>`__.
+: LLVM implements the [0.7 draft specification](https://github.com/riscv/integer-vector-absolute-difference/releases/tag/v0.7).
-``experimental-zvqwdota8i``, ``experimental-zvqwdota16i``, ``experimental-zvfwdota16bf``, ``experimental-zvfqwdota8f``
- LLVM implements the `0.2 draft specification <https://github.com/aswaterman/riscv-misc/blob/main/isa/ldot-bdot/ldot-bdot.adoc>`__.
+`experimental-zvzip`
-``experimental-smpmpmt``
- LLVM implements the `0.6 draft specification <https://github.com/riscv/riscv-isa-manual/blob/smpmpmt/src/smpmpmt.adoc>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/ved-rivos/riscv-isa-manual/blob/zvzip/src/zvzip.adoc).
-``experimental-zvabd``
- LLVM implements the `0.7 draft specification <https://github.com/riscv/integer-vector-absolute-difference/releases/tag/v0.7>`__.
+`experimental-zvvfmm`
-``experimental-zvzip``
- LLVM implements the `0.1 draft specification <https://github.com/ved-rivos/riscv-isa-manual/blob/zvzip/src/zvzip.adoc>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17).
-``experimental-zvvfmm``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17>`__.
+`experimental-zvvmm`
-``experimental-zvvmm``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17).
-``experimental-zvvmtls``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17>`__.
+`experimental-zvvmtls`
-``experimental-zvvmttls``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17).
-``experimental-zvqwbdota8i``, ``experimental-zvqwbdota16i``, ``experimental-zvfqwbdota8f``, ``experimental-zvfwbdota16bf``, ``experimental-zvfbdota32f``
- LLVM implements the `0.2 draft specification <https://github.com/aswaterman/riscv-misc/blob/main/isa/ldot-bdot/ldot-bdot.adoc>`__.
+`experimental-zvvmttls`
-``experimental-zilx``
- LLVM implements the `0.1 draft specification <https://github.com/riscv/riscv-zilx>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/integrated-matrix-extension/releases/tag/riscv-isa-release-71c48b9-2026-05-17).
-To use an experimental extension from `clang`, you must add `-menable-experimental-extensions` to the command line, and specify the exact version of the experimental extension you are using. To use an experimental extension with LLVM's internal developer tools (e.g. `llc`, `llvm-objdump`, `llvm-mc`), you must prefix the extension name with `experimental-`. Note that you don't need to specify the version with internal tools, and shouldn't include the `experimental-` prefix with `clang`.
+`experimental-zvqwbdota8i`, `experimental-zvqwbdota16i`, `experimental-zvfqwbdota8f`, `experimental-zvfwbdota16bf`, `experimental-zvfbdota32f`
-Vendor Extensions
-=================
+: LLVM implements the [0.2 draft specification](https://github.com/aswaterman/riscv-misc/blob/main/isa/ldot-bdot/ldot-bdot.adoc).
-Vendor extensions are extensions which are not standardized by RISC-V International, and are instead defined by a hardware vendor. The term vendor extension roughly parallels the definition of a `non-standard` extension from Section 1.3 of the Volume I: RISC-V Unprivileged ISA specification. In particular, we expect to eventually accept both `custom` extensions and `non-conforming` extensions.
+`experimental-zilx`
-Inclusion of a vendor extension will be considered on a case by case basis. All proposals should be brought to the bi-weekly RISC-V sync calls for discussion. For a general idea of the factors likely to be considered, please see the `Clang documentation <https://clang.llvm.org/get_involved.html>`__.
+: LLVM implements the [0.1 draft specification](https://github.com/riscv/riscv-zilx).
-It is our intention to follow the naming conventions described in `riscv-non-isa/riscv-toolchain-conventions <https://github.com/riscv-non-isa/riscv-toolchain-conventions#conventions-for-vendor-extensions>`__. Exceptions to this naming will need to be strongly motivated.
+To use an experimental extension from `clang`, you must add `-menable-experimental-extensions` to the command line, and specify the exact version of the experimental extension you are using. To use an experimental extension with LLVM's internal developer tools (e.g. `llc`, `llvm-objdump`, `llvm-mc`), you must prefix the extension name with `experimental-`. Note that you don't need to specify the version with internal tools, and shouldn't include the `experimental-` prefix with `clang`.
+
+## Vendor Extensions
+
+Vendor extensions are extensions which are not standardized by RISC-V International, and are instead defined by a hardware vendor. The term vendor extension roughly parallels the definition of a `non-standard` extension from Section 1.3 of the Volume I: RISC-V Unprivileged ISA specification. In particular, we expect to eventually accept both `custom` extensions and `non-conforming` extensions.
+
+Inclusion of a vendor extension will be considered on a case by case basis. All proposals should be brought to the bi-weekly RISC-V sync calls for discussion. For a general idea of the factors likely to be considered, please see the [Clang documentation](https://clang.llvm.org/get_involved.html).
+
+It is our intention to follow the naming conventions described in [riscv-non-isa/riscv-toolchain-conventions](https://github.com/riscv-non-isa/riscv-toolchain-conventions#conventions-for-vendor-extensions). Exceptions to this naming will need to be strongly motivated.
The current vendor extensions supported are:
-``XAIFET``
- LLVM implements `the AIFET (AI Foundry's ET) vendor-defined instructions specified in <https://github.com/aifoundry-org/et-man/blob/main/ET%20Programmer's%20Reference%20Manual.pdf>`__ originally defined by Esperanto Technologies (and now under the AI Foundry non-profit). Instructions are prefixed with `aif.` as described in the specification.
+`XAIFET`
+
+: LLVM implements [the AIFET (AI Foundry's ET) vendor-defined instructions specified in](https://github.com/aifoundry-org/et-man/blob/main/ET%20Programmer's%20Reference%20Manual.pdf) originally defined by Esperanto Technologies (and now under the AI Foundry non-profit). Instructions are prefixed with `aif.` as described in the specification.
+
+`XTHeadBa`
+
+: LLVM implements [the THeadBa (address-generation) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadBb`
+
+: LLVM implements [the THeadBb (basic bit-manipulation) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadBs`
+
+: LLVM implements [the THeadBs (single-bit operations) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadCondMov`
+
+: LLVM implements [the THeadCondMov (conditional move) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadCmo`
+
+: LLVM implements [the THeadCmo (cache management operations) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadFMemIdx`
+
+: LLVM implements [the THeadFMemIdx (indexed memory operations for floating point) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTheadMac`
+
+: LLVM implements [the XTheadMac (multiply-accumulate instructions) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadMemIdx`
+
+: LLVM implements [the THeadMemIdx (indexed memory operations) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadMemPair`
+
+: LLVM implements [the THeadMemPair (two-GPR memory operations) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+
+`XTHeadSync`
+
+: LLVM implements [the THeadSync (multi-core synchronization instructions) vendor-defined instructions specified in](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf) by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
-``XTHeadBa``
- LLVM implements `the THeadBa (address-generation) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+`XTHeadVdot`
-``XTHeadBb``
- LLVM implements `the THeadBb (basic bit-manipulation) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+: LLVM implements [version 1.0.0 of the THeadV-family custom instructions specification](https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.0/xthead-2022-12-04-2.2.0.pdf) by T-HEAD of Alibaba. All instructions are prefixed with `th.` as described in the specification, and the riscv-toolchain-convention document linked above.
-``XTHeadBs``
- LLVM implements `the THeadBs (single-bit operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+`XVentanaCondOps`
-``XTHeadCondMov``
- LLVM implements `the THeadCondMov (conditional move) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+: LLVM implements [version 1.0.0 of the VTx-family custom instructions specification](https://github.com/ventanamicro/ventana-custom-extensions/releases/download/v1.0.0/ventana-custom-extensions-v1.0.0.pdf) by Ventana Micro Systems. All instructions are prefixed with `vt.` as described in the specification, and the riscv-toolchain-convention document linked above. These instructions are only available for riscv64 at this time.
-``XTHeadCmo``
- LLVM implements `the THeadCmo (cache management operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+`Xsfmm*`
-``XTHeadFMemIdx``
- LLVM implements `the THeadFMemIdx (indexed memory operations for floating point) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+: LLVM implements [version 0.6 of the Xsfmm Family of Attached Matrix Extensions Specification](https://www.sifive.com/document-file/xsfmm-matrix-extensions-specification) by SiFive. All instructions are prefixed with `sf.` as described in the specification.
-``XTheadMac``
- LLVM implements `the XTheadMac (multiply-accumulate instructions) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+`XSfvcp`
-``XTHeadMemIdx``
- LLVM implements `the THeadMemIdx (indexed memory operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+: LLVM implements [version 1.1.0 of the SiFive Vector Coprocessor Interface (VCIX) Software Specification](https://sifive.cdn.prismic.io/sifive/Zn3m1R5LeNNTwnLS_vcix-spec-software-v1p1.pdf) by SiFive. All instructions are prefixed with `sf.vc.` as described in the specification, and the riscv-toolchain-convention document linked above.
-``XTHeadMemPair``
- LLVM implements `the THeadMemPair (two-GPR memory operations) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+`Xsfvfexp16e`, `Xsfvfbfexp16e`, and `Xsfvfexp32e`
-``XTHeadSync``
- LLVM implements `the THeadSync (multi-core synchronization instructions) vendor-defined instructions specified in <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.2/xthead-2023-01-30-2.2.2.pdf>`__ by T-HEAD of Alibaba. Instructions are prefixed with `th.` as described in the specification.
+: LLVM implements [version 0.5 of the Vector Exponential Extension Specification](https://www.sifive.com/document-file/exponential-function-instruction-xsfvfexp32e-xsfvf) by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
-``XTHeadVdot``
- LLVM implements `version 1.0.0 of the THeadV-family custom instructions specification <https://github.com/T-head-Semi/thead-extension-spec/releases/download/2.2.0/xthead-2022-12-04-2.2.0.pdf>`__ by T-HEAD of Alibaba. All instructions are prefixed with `th.` as described in the specification, and the riscv-toolchain-convention document linked above.
+`Xsfvfexpa` and `Xsfvfexpa64e`
-``XVentanaCondOps``
- LLVM implements `version 1.0.0 of the VTx-family custom instructions specification <https://github.com/ventanamicro/ventana-custom-extensions/releases/download/v1.0.0/ventana-custom-extensions-v1.0.0.pdf>`__ by Ventana Micro Systems. All instructions are prefixed with `vt.` as described in the specification, and the riscv-toolchain-convention document linked above. These instructions are only available for riscv64 at this time.
+: LLVM implements [version 0.2 of the Vector Exponential Approximation Extension Specification](https://www.sifive.com/document-file/exponential-approximation-instruction-xsfvfexpa-ex) by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
-``Xsfmm*``
- LLVM implements `version 0.6 of the Xsfmm Family of Attached Matrix Extensions Specification <https://www.sifive.com/document-file/xsfmm-matrix-extensions-specification>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification.
+`XSfvqmaccdod`, `XSfvqmaccqoq`
-``XSfvcp``
- LLVM implements `version 1.1.0 of the SiFive Vector Coprocessor Interface (VCIX) Software Specification <https://sifive.cdn.prismic.io/sifive/Zn3m1R5LeNNTwnLS_vcix-spec-software-v1p1.pdf>`__ by SiFive. All instructions are prefixed with `sf.vc.` as described in the specification, and the riscv-toolchain-convention document linked above.
+: LLVM implements [version 1.1.0 of the SiFive Int8 Matrix Multiplication Extensions Specification](https://sifive.cdn.prismic.io/sifive/1a2ad85b-d818-49f7-ba83-f51f1731edbe_int8-matmul-spec.pdf) by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
-``Xsfvfexp16e``, ``Xsfvfbfexp16e``, and ``Xsfvfexp32e``
- LLVM implements `version 0.5 of the Vector Exponential Extension Specification <https://www.sifive.com/document-file/exponential-function-instruction-xsfvfexp32e-xsfvf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
+`Xsfvfnrclipxfqf`
-``Xsfvfexpa`` and ``Xsfvfexpa64e``
- LLVM implements `version 0.2 of the Vector Exponential Approximation Extension Specification <https://www.sifive.com/document-file/exponential-approximation-instruction-xsfvfexpa-ex>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
+: LLVM implements [version 1.0.0 of the FP32-to-int8 Ranged Clip Instructions Extension Specification](https://sifive.cdn.prismic.io/sifive/0aacff47-f530-43dc-8446-5caa2260ece0_xsfvfnrclipxfqf-spec.pdf) by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
-``XSfvqmaccdod``, ``XSfvqmaccqoq``
- LLVM implements `version 1.1.0 of the SiFive Int8 Matrix Multiplication Extensions Specification <https://sifive.cdn.prismic.io/sifive/1a2ad85b-d818-49f7-ba83-f51f1731edbe_int8-matmul-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
+`Xsfvfwmaccqqq`
-``Xsfvfnrclipxfqf``
- LLVM implements `version 1.0.0 of the FP32-to-int8 Ranged Clip Instructions Extension Specification <https://sifive.cdn.prismic.io/sifive/0aacff47-f530-43dc-8446-5caa2260ece0_xsfvfnrclipxfqf-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
+: LLVM implements [version 1.0.0 of the Matrix Multiply Accumulate Instruction Extension Specification](https://sifive.cdn.prismic.io/sifive/c391d53e-ffcf-4091-82f6-c37bf3e883ed_xsfvfwmaccqqq-spec.pdf) by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
-``Xsfvfwmaccqqq``
- LLVM implements `version 1.0.0 of the Matrix Multiply Accumulate Instruction Extension Specification <https://sifive.cdn.prismic.io/sifive/c391d53e-ffcf-4091-82f6-c37bf3e883ed_xsfvfwmaccqqq-spec.pdf>`__ by SiFive. All instructions are prefixed with `sf.` as described in the specification linked above.
+`XCVbitmanip`
-``XCVbitmanip``
- LLVM implements `version 1.0.0 of the CORE-V Bit Manipulation custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/62bec66b36182215e18c9cf10f723567e23878e9/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification.
+: LLVM implements [version 1.0.0 of the CORE-V Bit Manipulation custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/62bec66b36182215e18c9cf10f723567e23878e9/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification.
-``XCVelw``
- LLVM implements `version 1.0.0 of the CORE-V Event load custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
+`XCVelw`
-``XCVmac``
- LLVM implements `version 1.0.0 of the CORE-V Multiply-Accumulate (MAC) custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.mac` as described in the specification. These instructions are only available for riscv32 at this time.
+: LLVM implements [version 1.0.0 of the CORE-V Event load custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
-``XCVmem``
- LLVM implements `version 1.0.0 of the CORE-V Post-Increment load and stores custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
+`XCVmac`
-``XCValu``
- LLVM implements `version 1.0.0 of the Core-V ALU custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst>`__ by Core-V. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
+: LLVM implements [version 1.0.0 of the CORE-V Multiply-Accumulate (MAC) custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.mac` as described in the specification. These instructions are only available for riscv32 at this time.
-``XCVsimd``
- LLVM implements `version 1.0.0 of the CORE-V SIMD custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification.
+`XCVmem`
-``XCVbi``
- LLVM implements `version 1.0.0 of the CORE-V immediate branching custom instructions specification <https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst>`__ by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
+: LLVM implements [version 1.0.0 of the CORE-V Post-Increment load and stores custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/master/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
-``XSiFivecdiscarddlone``
- LLVM implements `the SiFive sf.cdiscard.d.l1 instruction <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`__ by SiFive.
+`XCValu`
-``XSiFivecflushdlone``
- LLVM implements `the SiFive sf.cflush.d.l1 instruction <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`__ by SiFive.
+: LLVM implements [version 1.0.0 of the Core-V ALU custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/4f024fe4b15a68b76615b0630c07a6745c620da7/docs/source/instruction_set_extensions.rst) by Core-V. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
-``XSfcease``
- LLVM implements `the SiFive sf.cease instruction <https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf>`__ by SiFive.
+`XCVsimd`
-``Xwchc``
- LLVM implements `the custom compressed opcodes present in some QingKe cores` by WCH / Nanjing Qinheng Microelectronics. The vendor refers to these opcodes by the name "XW".
+: LLVM implements [version 1.0.0 of the CORE-V SIMD custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification.
-``Xqccmp``
- LLVM implements `version 0.3 of the 16-bit Push/Pop instructions and double-moves extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqccmp_extension-0.3.0>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification.
+`XCVbi`
-``experimental-Xqccmt``
- LLVM implements `version 0.1 of the Qualcomm 16-bit Table Jump extension specification <https://github.com/riscv/riscv-unified-db/pull/1788>`__ by Qualcomm. All instructions are prefixed with ``qc.`` as described in the specification.
+: LLVM implements [version 1.0.0 of the CORE-V immediate branching custom instructions specification](https://github.com/openhwgroup/cv32e40p/blob/cv32e40p_v1.3.2/docs/source/instruction_set_extensions.rst) by OpenHW Group. All instructions are prefixed with `cv.` as described in the specification. These instructions are only available for riscv32 at this time.
-``Xqci``
- LLVM implements `version 0.13 of the Qualcomm uC extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`XSiFivecdiscarddlone`
-``Xqcia``
- LLVM implements `version 0.7 of the Qualcomm uC Arithmetic extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [the SiFive sf.cdiscard.d.l1 instruction](https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf) by SiFive.
-``Xqciac``
- LLVM implements `version 0.3 of the Qualcomm uC Load-Store Address Calculation extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`XSiFivecflushdlone`
-``Xqcibi``
- LLVM implements `version 0.2 of the Qualcomm uC Branch Immediate extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [the SiFive sf.cflush.d.l1 instruction](https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf) by SiFive.
-``Xqcibm``
- LLVM implements `version 0.8 of the Qualcomm uC Bit Manipulation extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`XSfcease`
-``Xqcicli``
- LLVM implements `version 0.3 of the Qualcomm uC Conditional Load Immediate extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [the SiFive sf.cease instruction](https://sifive.cdn.prismic.io/sifive/767804da-53b2-4893-97d5-b7c030ae0a94_s76mc_core_complex_manual_21G3.pdf) by SiFive.
-``Xqcicm``
- LLVM implements `version 0.2 of the Qualcomm uC Conditional Move extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xwchc`
-``Xqcics``
- LLVM implements `version 0.2 of the Qualcomm uC Conditional Select extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements `the custom compressed opcodes present in some QingKe cores` by WCH / Nanjing Qinheng Microelectronics. The vendor refers to these opcodes by the name "XW".
-``Xqcicsr``
- LLVM implements `version 0.4 of the Qualcomm uC CSR extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xqccmp`
-``Xqciint``
- LLVM implements `version 0.10 of the Qualcomm uC Interrupts extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [version 0.3 of the 16-bit Push/Pop instructions and double-moves extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqccmp_extension-0.3.0) by Qualcomm. All instructions are prefixed with `qc.` as described in the specification.
-``Xqciio``
- LLVM implements `version 0.1 of the Qualcomm uC External Input Output extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`experimental-Xqccmt`
-``Xqcilb``
- LLVM implements `version 0.2 of the Qualcomm uC Long Branch extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [version 0.1 of the Qualcomm 16-bit Table Jump extension specification](https://github.com/riscv/riscv-unified-db/pull/1788) by Qualcomm. All instructions are prefixed with `qc.` as described in the specification.
-``Xqcili``
- LLVM implements `version 0.2 of the Qualcomm uC Load Large Immediate extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xqci`
-``Xqcilia``
- LLVM implements `version 0.2 of the Qualcomm uC Large Immediate Arithmetic extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [version 0.13 of the Qualcomm uC extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``Xqcilo``
- LLVM implements `version 0.3 of the Qualcomm uC Large Offset Load Store extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xqcia`
-``Xqcilsm``
- LLVM implements `version 0.6 of the Qualcomm uC Load Store Multiple extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [version 0.7 of the Qualcomm uC Arithmetic extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``Xqcisim``
- LLVM implements `version 0.2 of the Qualcomm uC Simulation Hint extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xqciac`
-``Xqcisls``
- LLVM implements `version 0.2 of the Qualcomm uC Scaled Load Store extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+: LLVM implements [version 0.3 of the Qualcomm uC Load-Store Address Calculation extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``Xqcisync``
- LLVM implements `version 0.3 of the Qualcomm uC Sync Delay extension specification <https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0>`__ by Qualcomm. These instructions are only available for riscv32.
+`Xqcibi`
-``Xmipscbop``
- LLVM implements MIPS prefetch extension `p8700 processor <https://mips.com/products/hardware/p8700/>`__ by MIPS.
+: LLVM implements [version 0.2 of the Qualcomm uC Branch Immediate extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``Xmipscmov``
- LLVM implements conditional move for the `p8700 processor <https://mips.com/products/hardware/p8700/>`__ by MIPS.
+`Xqcibm`
-``Xmipslsp``
- LLVM implements load/store pair instructions for the `p8700 processor <https://mips.com/products/hardware/p8700/>`__ by MIPS.
+: LLVM implements [version 0.8 of the Qualcomm uC Bit Manipulation extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``XAndesPerf``
- LLVM implements `version 5.0.0 of the Andes Performance Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+`Xqcicli`
-``XAndesBFHCvt``
- LLVM implements `version 5.0.0 of the Andes Scalar BFLOAT16 Conversion Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+: LLVM implements [version 0.3 of the Qualcomm uC Conditional Load Immediate extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``XAndesVBFHCvt``
- LLVM implements `version 5.0.0 of the Andes Vector BFLOAT16 Conversion Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+`Xqcicm`
-``XAndesVSINTH``
- LLVM implements `version 5.0.0 of the Andes Vector Small Int Handling Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+: LLVM implements [version 0.2 of the Qualcomm uC Conditional Move extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``XAndesVSINTLoad``
- LLVM implements `version 5.0.0 of the Andes Vector INT4 Load Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+`Xqcics`
-``XAndesVPackFPH``
- LLVM implements `version 5.0.0 of the Andes Vector Packed FP16 Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+: LLVM implements [version 0.2 of the Qualcomm uC Conditional Select extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``XAndesVDot``
- LLVM implements `version 5.0.0 of the Andes Vector Dot Product Extension specification <https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf>`__ by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+`Xqcicsr`
-``XSMTVDot``
- SpacemiT defines `Integrated Matrix Extension (IME) specification <https://github.com/spacemit-com/riscv-ime-extension-spec/releases/tag/v1.0>`__.
- LLVM implements the hardware-adapted subset for SpacemiT X60, defined in the `feature document <https://developer.spacemit.com/documentation?token=BWbGwbx7liGW21kq9lucSA6Vnpb#2.1>`__ by SpacemiT. All instructions are prefixed with `smt.` as described in the implementation guide. Note that this implemented subset is `version 1.0.0 of the SpacemiT Vector Dot Product Extension specification`, which is strictly a subset of the full IME specification to reflect the capabilities of SpacemiT X60 hardware correctly.
+: LLVM implements [version 0.4 of the Qualcomm uC CSR extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
-``XSMTVDotII``
- SpacemiT defines the `Integrated Matrix Extension (IME) specification <https://github.com/spacemit-com/docs-ai/blob/main/en/architecture/ime_extension.md>`__
+`Xqciint`
+
+: LLVM implements [version 0.10 of the Qualcomm uC Interrupts extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqciio`
+
+: LLVM implements [version 0.1 of the Qualcomm uC External Input Output extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcilb`
+
+: LLVM implements [version 0.2 of the Qualcomm uC Long Branch extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcili`
+
+: LLVM implements [version 0.2 of the Qualcomm uC Load Large Immediate extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcilia`
+
+: LLVM implements [version 0.2 of the Qualcomm uC Large Immediate Arithmetic extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcilo`
+
+: LLVM implements [version 0.3 of the Qualcomm uC Large Offset Load Store extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcilsm`
+
+: LLVM implements [version 0.6 of the Qualcomm uC Load Store Multiple extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcisim`
+
+: LLVM implements [version 0.2 of the Qualcomm uC Simulation Hint extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcisls`
+
+: LLVM implements [version 0.2 of the Qualcomm uC Scaled Load Store extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xqcisync`
+
+: LLVM implements [version 0.3 of the Qualcomm uC Sync Delay extension specification](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0) by Qualcomm. These instructions are only available for riscv32.
+
+`Xmipscbop`
+
+: LLVM implements MIPS prefetch extension [p8700 processor](https://mips.com/products/hardware/p8700/) by MIPS.
+
+`Xmipscmov`
+
+: LLVM implements conditional move for the [p8700 processor](https://mips.com/products/hardware/p8700/) by MIPS.
+
+`Xmipslsp`
+
+: LLVM implements load/store pair instructions for the [p8700 processor](https://mips.com/products/hardware/p8700/) by MIPS.
+
+`XAndesPerf`
+
+: LLVM implements [version 5.0.0 of the Andes Performance Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesBFHCvt`
+
+: LLVM implements [version 5.0.0 of the Andes Scalar BFLOAT16 Conversion Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesVBFHCvt`
+
+: LLVM implements [version 5.0.0 of the Andes Vector BFLOAT16 Conversion Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesVSINTH`
+
+: LLVM implements [version 5.0.0 of the Andes Vector Small Int Handling Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesVSINTLoad`
+
+: LLVM implements [version 5.0.0 of the Andes Vector INT4 Load Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesVPackFPH`
+
+: LLVM implements [version 5.0.0 of the Andes Vector Packed FP16 Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XAndesVDot`
+
+: LLVM implements [version 5.0.0 of the Andes Vector Dot Product Extension specification](https://github.com/andestech/andes-v5-isa/releases/download/ast-v5_4_0-release/AndeStar_V5_ISA_Spec_UM165-v1.5.08-20250317.pdf) by Andes Technology. All instructions are prefixed with `nds.` as described in the specification.
+
+`XSMTVDot`
+
+: SpacemiT defines [Integrated Matrix Extension (IME) specification](https://github.com/spacemit-com/riscv-ime-extension-spec/releases/tag/v1.0).
+ LLVM implements the hardware-adapted subset for SpacemiT X60, defined in the [feature document](https://developer.spacemit.com/documentation?token=BWbGwbx7liGW21kq9lucSA6Vnpb#2.1) by SpacemiT. All instructions are prefixed with `smt.` as described in the implementation guide. Note that this implemented subset is `version 1.0.0 of the SpacemiT Vector Dot Product Extension specification`, which is strictly a subset of the full IME specification to reflect the capabilities of SpacemiT X60 hardware correctly.
+
+`XSMTVDotII`
+
+: SpacemiT defines the [Integrated Matrix Extension (IME) specification](https://github.com/spacemit-com/docs-ai/blob/main/en/architecture/ime_extension.md)
LLVM implements the hardware-adapted subset for SpacemiT A100
-Experimental C Intrinsics
-=========================
+## Experimental C Intrinsics
In some cases an extension is non-experimental but the C intrinsics for that
-extension are still experimental. To use C intrinsics for such an extension
+extension are still experimental. To use C intrinsics for such an extension
from `clang`, you must add `-menable-experimental-extensions` to the command
-line. This currently applies to the following extensions:
+line. This currently applies to the following extensions:
No extensions have experimental intrinsics.
-Long (>32-bit) Instruction Support
-==================================
+## Long (>32-bit) Instruction Support
RISC-V is a variable-length ISA, but the standard currently only defines 16- and 32-bit instructions. The specification describes longer instruction encodings, but these are not ratified.
The LLVM disassembler, `llvm-objdump`, does use the longer instruction encodings described in the specification to guess the instruction length (up to 176 bits) and will group the disassembly view of encoding bytes correspondingly.
-The LLVM integrated assembler for RISC-V supports two different kinds of ``.insn`` directive, for assembling instructions that LLVM does not yet support:
+The LLVM integrated assembler for RISC-V supports two different kinds of `.insn` directive, for assembling instructions that LLVM does not yet support:
-* ``.insn type, args*`` which takes a known instruction type, and a list of fields. You are strongly recommended to use this variant of the directive if your instruction fits an existing instruction type.
-* ``.insn [ length , ] encoding`` which takes an (optional) explicit length (in bytes) and a raw encoding for the instruction. When given an explicit length, this variant can encode instructions up to 64 bits long. The encoding part of the directive must be given all bits for the instruction, none are filled in for the user. When used without the optional length, this variant of the directive will use the LSBs of the raw encoding to work out if an instruction is 16 or 32 bits long. LLVM does not infer that an instruction might be longer than 32 bits - in this case, the user must give the length explicitly.
+- `.insn type, args*` which takes a known instruction type, and a list of fields. You are strongly recommended to use this variant of the directive if your instruction fits an existing instruction type.
+- `.insn [ length , ] encoding` which takes an (optional) explicit length (in bytes) and a raw encoding for the instruction. When given an explicit length, this variant can encode instructions up to 64 bits long. The encoding part of the directive must be given all bits for the instruction, none are filled in for the user. When used without the optional length, this variant of the directive will use the LSBs of the raw encoding to work out if an instruction is 16 or 32 bits long. LLVM does not infer that an instruction might be longer than 32 bits - in this case, the user must give the length explicitly.
-It is strongly recommended to use the ``.insn`` directive for assembling unsupported instructions instead of ``.word`` or ``.hword``, because it will produce the correct mapping symbols to mark the word as an instruction, not data.
+It is strongly recommended to use the `.insn` directive for assembling unsupported instructions instead of `.word` or `.hword`, because it will produce the correct mapping symbols to mark the word as an instruction, not data.
-Global Pointer (GP) Relaxation and the Small Data Limit
-=======================================================
+## Global Pointer (GP) Relaxation and the Small Data Limit
-Some of the RISC-V psABI variants reserve ``gp`` (``x3``) for use as a "Global Pointer", to make generating data addresses more efficient.
+Some of the RISC-V psABI variants reserve `gp` (`x3`) for use as a "Global Pointer", to make generating data addresses more efficient.
To use this functionality, you need to be doing all of the following:
-* Use the ``medlow`` (aka ``small``) code model;
-* Not use the ``gp`` register for any other uses (some platforms use it for the shadow stack and others as a temporary -- as denoted by the ``Tag_RISCV_x3_reg_usage`` build attribute);
-* Compile your objects with Clang's ``-mrelax`` option, to enable relaxation annotations on relocatable objects (this is the default, but ``-mno-relax`` disables these relaxation annotations);
-* Compile for a position-dependent static executable (not a shared library, and ``-fno-PIC`` / ``-fno-pic`` / ``-fno-pie``); and
-* Use LLD's ``--relax-gp`` option.
+- Use the `medlow` (aka `small`) code model;
+- Not use the `gp` register for any other uses (some platforms use it for the shadow stack and others as a temporary -- as denoted by the `Tag_RISCV_x3_reg_usage` build attribute);
+- Compile your objects with Clang's `-mrelax` option, to enable relaxation annotations on relocatable objects (this is the default, but `-mno-relax` disables these relaxation annotations);
+- Compile for a position-dependent static executable (not a shared library, and `-fno-PIC` / `-fno-pic` / `-fno-pie`); and
+- Use LLD's `--relax-gp` option.
-LLD will relax (rewrite) any code sequences that materialize an address within 2048 bytes of ``__global_pointer$`` (which will be defined if it is used and does not already exist) to instead generate the address using ``gp`` and the correct (signed) 12-bit immediate. This usually saves at least one instruction compared to materialising a full 32-bit address value.
+LLD will relax (rewrite) any code sequences that materialize an address within 2048 bytes of `__global_pointer$` (which will be defined if it is used and does not already exist) to instead generate the address using `gp` and the correct (signed) 12-bit immediate. This usually saves at least one instruction compared to materialising a full 32-bit address value.
-There can only be one ``gp`` value in a process (as ``gp`` is not changed when calling into a function in a shared library), so the symbol is only defined and this relaxation is only done for executables, and not for shared libraries. The linker expects executable startup code to put the value of ``__global_pointer$`` (from the executable) into ``gp`` before any user code is run.
+There can only be one `gp` value in a process (as `gp` is not changed when calling into a function in a shared library), so the symbol is only defined and this relaxation is only done for executables, and not for shared libraries. The linker expects executable startup code to put the value of `__global_pointer$` (from the executable) into `gp` before any user code is run.
Arguably, the most efficient use for this addressing mode is for smaller global variables, as larger global variables likely need many more loads or stores when they are being accessed anyway, so the cost of materializing the upper bits can be shared.
-Therefore the compiler can place smaller global variables into sections with names starting with ``.sdata`` or ``.sbss`` (matching sections with names starting with ``.data`` and ``.bss`` respectively). LLD knows to define the ``global_pointer$`` symbol close to these sections, and to lay these sections out adjacent to the ``.data`` section.
+Therefore the compiler can place smaller global variables into sections with names starting with `.sdata` or `.sbss` (matching sections with names starting with `.data` and `.bss` respectively). LLD knows to define the `global_pointer$` symbol close to these sections, and to lay these sections out adjacent to the `.data` section.
-Clang's ``-msmall-data-limit=`` option controls what the threshold size is (in bytes) for a global variable to be considered small. ``-msmall-data-limit=0`` disables the use of sections starting ``.sdata`` and ``.sbss``. The ``-msmall-data-limit=`` option will not move global variables that have an explicit data section, and will keep globals in separate sections if you are using ``-fdata-sections``.
+Clang's `-msmall-data-limit=` option controls what the threshold size is (in bytes) for a global variable to be considered small. `-msmall-data-limit=0` disables the use of sections starting `.sdata` and `.sbss`. The `-msmall-data-limit=` option will not move global variables that have an explicit data section, and will keep globals in separate sections if you are using `-fdata-sections`.
-The small data limit threshold is also used to separate small constants into sections with names starting with ``.srodata``. LLD does not place these with the ``.sdata`` and ``.sbss`` sections as ``.srodata`` sections are read only and the other two are writable. Instead the ``.srodata`` sections are placed adjacent to ``.rodata``.
+The small data limit threshold is also used to separate small constants into sections with names starting with `.srodata`. LLD does not place these with the `.sdata` and `.sbss` sections as `.srodata` sections are read only and the other two are writable. Instead the `.srodata` sections are placed adjacent to `.rodata`.
Data suggests that these options can produce significant improvements across a range of benchmarks.
-Sanitizers
-==========
+## Sanitizers
-.. note::
- This is a summary of the current state of sanitizers, and not an official support statement.
+:::{note}
+This is a summary of the current state of sanitizers, and not an official support statement.
+:::
-* UBSan is not platform-specific, and should work out of the box.
+- UBSan is not platform-specific, and should work out of the box.
-* ASan and TSan already have shadow mappings defined for Linux on RISC-V, and are likely to work.
+- ASan and TSan already have shadow mappings defined for Linux on RISC-V, and are likely to work.
-* HWASan is also likely to work, though RISC-V Pointer Masking (very new) is needed as well to make it run efficiently.
+- HWASan is also likely to work, though RISC-V Pointer Masking (very new) is needed as well to make it run efficiently.
-* Memtag: N/A - there is currently no ratified RISC-V memory tagging spec.
+- Memtag: N/A - there is currently no ratified RISC-V memory tagging spec.
-* MSan is unlikely to work: there are currently no RISC-V-specific shadow mappings (this is probably easy to fix; perhaps the default Linux 64-bit mapping will work) and MSan does not explicitly handle any of the `@llvm.riscv.*` intrinsics (this is significantly more work to fix).
+- MSan is unlikely to work: there are currently no RISC-V-specific shadow mappings (this is probably easy to fix; perhaps the default Linux 64-bit mapping will work) and MSan does not explicitly handle any of the `@llvm.riscv.*` intrinsics (this is significantly more work to fix).
Some intrinsics will be handled correctly anyway, if the RISC-V intrinsic is auto-upgraded into cross-platform LLVM intrinsics. Some others will be "heuristically" handled (possibly incorrectly). The rest will default to the "strict" handler, which checks that all the parameters are fully initialized.
MSan intrinsics support is only required if code (including dependencies) manually calls the intrinsic.
-Scheduling Model and Tuning
-===========================
+## Scheduling Model and Tuning
RISC-V is highly configurable, meaning its scheduling models could be highly diversified as well. Yet we still believe it is helpful to provide a "generic" tuning processor / scheduling model that represents the "lowest common denominator" RISC-V implementation at the time. The idea is that it could serve as a "good-enough" baseline model for performance tuning purposes on some of the most common use cases.
-Though details of this generic scheduling model might evolve over time, we always have some _expectations_ on the kind of processors it is used for.
+Though details of this generic scheduling model might evolve over time, we always have some \_expectations\_ on the kind of processors it is used for.
-For example, the ``generic`` tuning processor is expected to target in-order, superscalar application processors designed for general-purpose computing. It is usually RVA22U64- or RVA23U64-capable intended to run Linux. The ``generic-ooo`` has a similar set of expectations, except it is targeting out-of-order application processors.
+For example, the `generic` tuning processor is expected to target in-order, superscalar application processors designed for general-purpose computing. It is usually RVA22U64- or RVA23U64-capable intended to run Linux. The `generic-ooo` has a similar set of expectations, except it is targeting out-of-order application processors.
-Right now, we simply assign a scheduling model that is widely used by the community to ``generic``. But in the future, we can create a standalone scheduling model for ``generic``, or even create a generic model for each of the individual sectors. For example, a ``generic-embedded`` for embedded processors and a ``generic-server`` for server workloads.
+Right now, we simply assign a scheduling model that is widely used by the community to `generic`. But in the future, we can create a standalone scheduling model for `generic`, or even create a generic model for each of the individual sectors. For example, a `generic-embedded` for embedded processors and a `generic-server` for server workloads.
-These future generic models could even serve as the "base" model for other scheduling models to derive from: it's not uncommon for multiple processors to share a similar set of instruction scheduling info except a few key instructions, and this is especially true for RISC-V given its highly configurable nature. If we could design the base model in a way that it can be _parameterized_ by subtarget tuning features, we can substitue the traditional way of creating individual scheduling models with a combination of base scheduling model + different subtarget features.
+These future generic models could even serve as the "base" model for other scheduling models to derive from: it's not uncommon for multiple processors to share a similar set of instruction scheduling info except a few key instructions, and this is especially true for RISC-V given its highly configurable nature. If we could design the base model in a way that it can be \_parameterized\_ by subtarget tuning features, we can substitue the traditional way of creating individual scheduling models with a combination of base scheduling model + different subtarget features.
-Processor-Specific Tuning Feature String
-========================================
-Due to RISC-V's highly configurable nature, it is often desirable to share a single scheduling model across multiple similar RISC-V processors that only differ in a small number of (uArch) tuning features. An example of such tuning feature could be whether the latency of vector operations depend on VL or not. This could be extended to tuning features that are not directly connected to scheduling model but other parts of the RISC-V backend, like the cost of ``vrgather.vv`` instruction.
+## Processor-Specific Tuning Feature String
-To that end, RISC-V LLVM supports a tuning feature string format, through frontend flags like ``-mtune`` in Clang, to help users building a performance model by "configuring" an existing tune CPU, along with its scheduling model. For example, this flag
+Due to RISC-V's highly configurable nature, it is often desirable to share a single scheduling model across multiple similar RISC-V processors that only differ in a small number of (uArch) tuning features. An example of such tuning feature could be whether the latency of vector operations depend on VL or not. This could be extended to tuning features that are not directly connected to scheduling model but other parts of the RISC-V backend, like the cost of `vrgather.vv` instruction.
+
+To that end, RISC-V LLVM supports a tuning feature string format, through frontend flags like `-mtune` in Clang, to help users building a performance model by "configuring" an existing tune CPU, along with its scheduling model. For example, this flag
::
- -mtune=sifive-x280:single-element-vec-fp64
-takes ``sifive-x280`` as the "base" tune CPU and configured it with ``single-element-vec-fp64``. This gives us a performance model that looks exactly like that of ``sifive-x280``, except some of the 64-bit vector floating point instructions now produce only a single element per cycle due to ``single-element-vec-fp64``.
+: -mtune=sifive-x280:single-element-vec-fp64
+
+takes `sifive-x280` as the "base" tune CPU and configured it with `single-element-vec-fp64`. This gives us a performance model that looks exactly like that of `sifive-x280`, except some of the 64-bit vector floating point instructions now produce only a single element per cycle due to `single-element-vec-fp64`.
More formally speaking, each tuning feature string has the following format:
::
- <tune-cpu>[":"<tune-features>]?
+
+: \<tune-cpu>[":"\<tune-features>]?
where
::
- tune-cpu ::= 'tuning CPU name in lower case'
- directive ::= "[a-zA-Z0-9\_-]+"
- tune-features ::= directive ["," directive]*
-A *directive* can and can only _enable_ or _disable_ a certain tuning feature from the tuning CPU. A **positive directive**, like the ``single-element-vec-fp64`` we just saw, enables an additional tuning feature in the associated tuning model. A **negative directive**, on the other hand, removes a certain tuning feature. For example, ``sifive-x390`` already has the ``single-element-vec-fp64`` feature, and we can use
+: tune-cpu ::= 'tuning CPU name in lower case'
+ directive ::= "[a-zA-Z0-9\_-]+"
+ tune-features ::= directive ["," directive]\*
+
+A *directive* can and can only \_enable\_ or \_disable\_ a certain tuning feature from the tuning CPU. A **positive directive**, like the `single-element-vec-fp64` we just saw, enables an additional tuning feature in the associated tuning model. A **negative directive**, on the other hand, removes a certain tuning feature. For example, `sifive-x390` already has the `single-element-vec-fp64` feature, and we can use
::
- "sifive-x390:full-vec-fp64"
-to create a new performance model that looks nearly the same as ``sifive-x390`` except ``single-element-vec-fp64`` being cut out. In this case, ``full-vec-fp64`` is a negative directive.
+: "sifive-x390:full-vec-fp64"
+
+to create a new performance model that looks nearly the same as `sifive-x390` except `single-element-vec-fp64` being cut out. In this case, `full-vec-fp64` is a negative directive.
There are some rules for the list of directives, though:
1. The same directive cannot appear more than once.
-
2. The positive and negative directives that belong to the same feature cannot appear at the same time.
+3. If a feature implies other features -- for example, `short-forward-branch-imul` implies `short-forward-branch-ialu` -- then the \_implied\_ features are subject to the previous two rules, too. For example, we cannot write \_"short-forward-branch-imul,no-short-forward-branch-ialu"\_, because the feature implied by `short-forward-branch-imul` violates rule 2.
-3. If a feature implies other features -- for example, ``short-forward-branch-imul`` implies ``short-forward-branch-ialu`` -- then the _implied_ features are subject to the previous two rules, too. For example, we cannot write _"short-forward-branch-imul,no-short-forward-branch-ialu"_, because the feature implied by ``short-forward-branch-imul`` violates rule 2.
+In addition to the rules listed above, right now, this string only accepts directives that are explicitly supported by the tune CPU. For example, \_"sifive-x280:prefer-w-inst"\_ is not a valid string as `prefer-w-inst` is not supported by `sifive-x280` at this moment. Vendors of these processors are expected to maintain the compatibility of their supported directives across different versions. There have been lots of discussions on having "generic" features that are universally supported by all RISC-V CPUs, yet many concerns -- including the difficulty to maintain compatibility across \_all\_ CPU targets and versions -- make us decide to table this issue until we find a reliable process to select such features.
-In addition to the rules listed above, right now, this string only accepts directives that are explicitly supported by the tune CPU. For example, _"sifive-x280:prefer-w-inst"_ is not a valid string as ``prefer-w-inst`` is not supported by ``sifive-x280`` at this moment. Vendors of these processors are expected to maintain the compatibility of their supported directives across different versions. There have been lots of discussions on having "generic" features that are universally supported by all RISC-V CPUs, yet many concerns -- including the difficulty to maintain compatibility across _all_ CPU targets and versions -- make us decide to table this issue until we find a reliable process to select such features.
diff --git a/llvm/docs/ReportingGuide.md b/llvm/docs/ReportingGuide.md
index 9332534a144a8..05ed77786e708 100644
--- a/llvm/docs/ReportingGuide.md
+++ b/llvm/docs/ReportingGuide.md
@@ -1,18 +1,15 @@
-..
- This work is licensed under a Creative Commons Attribution 3.0 Unported License.
- SPDX-License-Identifier: CC-BY-3.0
+% This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+% SPDX-License-Identifier: CC-BY-3.0
-=================================
-LLVM CoC Incident Reporting Guide
-=================================
+# LLVM CoC Incident Reporting Guide
First of all, please do not feel like you may be a burden to us by reporting
incidents. We consider reports an opportunity for us to act: by knowing about
an incident, we can act on it if appropriate, and reduce continuation of
-problematic behavior. If we don't know, we can't learn or take any appropriate
+problematic behavior. If we don't know, we can't learn or take any appropriate
actions.
-If you are not sure the situation being reported was a :doc:`Code of
+If you are not sure the situation being reported was a {doc}`Code of
Conduct<CodeOfConduct>` violation, we encourage you to still report it. We
would much rather have reports where we decide to take no action, rather than
miss a report of an actual violation. There is no harm in reporting an incident
@@ -20,61 +17,55 @@ which is later determined not to be a violation, and knowing about incidents
that are not violations can also help us to improve the Code of Conduct or the
processes surrounding it.
-Reporting and Contact Information
-=================================
-
-* For any incident involving an online platform (e.g., mailing lists, forums,
- irc/discord/slack, etc) we ask that you make any reports by emailing
- conduct at llvm.org. This is received by all members of the CoC Committee.
-
-* For LLVM Developers' Meetings, please file a report with the on-site Code
- of Conduct team. Their names and contact details are listed on the event
- webpage. You can also approach any other staff member, who can be
- identified by special badges and often found at the registration desk,
- to help you locate a member of the Code of Conduct team. All incidents
- reported in-person at a LLVM Developers' Meeting will be emailed to the
- Code of Conduct Committee.
-
-* For meetups, please report the incident to the local meetup organizers first
- and then email conduct at llvm.org with your report. Each meetup will have a
- contact listed on the associated meetup page. If you feel the incident was
+## Reporting and Contact Information
+
+- For any incident involving an online platform (e.g., mailing lists, forums,
+ irc/discord/slack, etc) we ask that you make any reports by emailing
+ <mailto:conduct at llvm.org>. This is received by all members of the CoC Committee.
+- For LLVM Developers' Meetings, please file a report with the on-site Code
+ of Conduct team. Their names and contact details are listed on the event
+ webpage. You can also approach any other staff member, who can be
+ identified by special badges and often found at the registration desk,
+ to help you locate a member of the Code of Conduct team. All incidents
+ reported in-person at a LLVM Developers' Meeting will be emailed to the
+ Code of Conduct Committee.
+- For meetups, please report the incident to the local meetup organizers first
+ and then email <mailto:conduct at llvm.org> with your report. Each meetup will have a
+ contact listed on the associated meetup page. If you feel the incident was
not well handled by the local organizers, please include this information in
- your email to conduct at llvm.org. All meetup organizers who receive an
- in-person report are also asked to email conduct at llvm.org with the
+ your email to <mailto:conduct at llvm.org>. All meetup organizers who receive an
+ in-person report are also asked to email <mailto:conduct at llvm.org> with the
incident information.
-
If you believe anyone is in physical danger, please notify appropriate law
enforcement first. If you are unsure what law enforcement agency is
appropriate, please include this in your report and we will attempt to notify
them.
-Guidelines for Reporting Incidents
-==================================
+## Guidelines for Reporting Incidents
-Please email conduct at llvm.org with the following details (if possible):
+Please email <mailto:conduct at llvm.org> with the following details (if possible):
-* Your contact info (so we can get in touch with you). Include email and
+- Your contact info (so we can get in touch with you). Include email and
optionally a phone number.
-* Names or descriptions of anyone who was involved or who witnessed the
+- Names or descriptions of anyone who was involved or who witnessed the
incident.
-* When and where the incident occurred. Please be as specific as possible.
-* Your account of what occurred. If there is a written record (e.g. emails,
+- When and where the incident occurred. Please be as specific as possible.
+- Your account of what occurred. If there is a written record (e.g. emails,
forum links, tweets, Slack, or Discord messages) please include screenshots,
as well as any available link.
-* Any extra context you believe existed for the incident.
-* If you believe this incident is ongoing.
-* If you have concerns about retaliation or your personal safety, please note
+- Any extra context you believe existed for the incident.
+- If you believe this incident is ongoing.
+- If you have concerns about retaliation or your personal safety, please note
those concerns in your report.
-* Any other information you believe we should have.
+- Any other information you believe we should have.
If you are unable to provide all of this information, please still make the
report and include as much information as you have.
-When handling a report, we follow our :doc:`Response Guide <ResponseGuide>`.
+When handling a report, we follow our {doc}`Response Guide <ResponseGuide>`.
-Confidentiality
-===============
+## Confidentiality
All reports will be kept confidential with details shared only with the Code of
Conduct committee members. In the case that a CoC committee member is involved
@@ -89,34 +80,29 @@ you have concerns about retaliation or your personal safety, please note those
concerns in your report. You are still encouraged to report the incident so
that we can support you while keeping our community members safe. In some
cases, we can compile several anonymized reports into a pattern of behavior,
-and take action on that pattern.
+and take action on that pattern.
Transparency reports will be published but will retain confidentiality. See the
-:doc:`Response Guide <ResponseGuide>`. for details on this.
+{doc}`Response Guide <ResponseGuide>`. for details on this.
-Following Up With Reporter(s)
-=============================
+## Following Up With Reporter(s)
Once a report is filed, the Code of Conduct committee will handle the review
-and follow up according to the procedures in the :doc:`Response Guide
-<ResponseGuide>`.
-
-
-Thanks!
-=======
+and follow up according to the procedures in the {doc}`Response Guide
+<ResponseGuide>`.
-This guide was created and inspired by the following: the `Django Project`_,
-`Carpentries Response Guide`_, and the `Write The Docs Response Guide`_.
+## Thanks!
-License
-=======
+This guide was created and inspired by the following: the [Django Project][django project],
+[Carpentries Response Guide][carpentries response guide], and the [Write The Docs Response Guide][write the docs response guide].
-All content on this page is licensed under a `Creative Commons Attribution 3.0
-Unported License`_.
+## License
+All content on this page is licensed under a [Creative Commons Attribution 3.0
+Unported License][creative commons attribution 3.0 unported license].
-.. _Django Project: https://www.djangoproject.com/conduct/
-.. _Carpentries Response Guide: https://docs.carpentries.org/topic_folders/policies/enforcement-guidelines.html
-.. _Write The Docs Response Guide: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
-.. _Creative Commons Attribution 3.0 Unported License: http://creativecommons.org/licenses/by/3.0/
+[carpentries response guide]: https://docs.carpentries.org/topic_folders/policies/enforcement-guidelines.html
+[creative commons attribution 3.0 unported license]: http://creativecommons.org/licenses/by/3.0/
+[django project]: https://www.djangoproject.com/conduct/
+[write the docs response guide]: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
diff --git a/llvm/docs/ResponseGuide.md b/llvm/docs/ResponseGuide.md
index 779684a275a81..7d32eafe02658 100644
--- a/llvm/docs/ResponseGuide.md
+++ b/llvm/docs/ResponseGuide.md
@@ -1,58 +1,50 @@
-..
- This work is licensed under a Creative Commons Attribution 3.0 Unported License.
- SPDX-License-Identifier: CC-BY-3.0
+% This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+% SPDX-License-Identifier: CC-BY-3.0
-===============
-Response Guide
-===============
+# Response Guide
-This is a :doc:`Code of Conduct<CodeOfConduct>` (CoC) incident response guide
+This is a {doc}`Code of Conduct<CodeOfConduct>` (CoC) incident response guide
used by the Code of Conduct Committee and LLVM event organizers.
-Code of Conduct Committee
-=========================
+## Code of Conduct Committee
All responses to Code of Conduct reports will be managed by a Code of Conduct
-Committee.
+Committee.
-Additional Code of Conduct Response Teams
-=========================================
+## Additional Code of Conduct Response Teams
In-person events will have an additional response team to immediately respond
to an incident. For example:
-* Each LLVM Developers' Meeting has a Code of Conduct response team.
-* For LLVM meetups, the local organizers will be the first point of contact.
-* Any other event funded by the LLVM Foundation or listed on the LLVM website,
- will have a code of conduct response team or point of contact for CoC
+- Each LLVM Developers' Meeting has a Code of Conduct response team.
+- For LLVM meetups, the local organizers will be the first point of contact.
+- Any other event funded by the LLVM Foundation or listed on the LLVM website,
+ will have a code of conduct response team or point of contact for CoC
reports.
-These teams should determine if an :ref:`immediate response<Immediate Response
+These teams should determine if an {ref}`immediate response<Immediate Response
Checklist>` is needed before sending the report to the Code of Conduct
committee.
-.. _Receiving a report:
+(receiving-a-report)=
-Receiving a Report
-==================
+## Receiving a Report
-Reports are typically received by email (conduct at llvm.org) or in person from
+Reports are typically received by email (<mailto:conduct at llvm.org>) or in person from
the reporter or event CoC response team.
When receiving a report by email, the CoC Committee should acknowledge receipt
-within 24 hours. The acknowledgment should be understanding and compassionate
+within 24 hours. The acknowledgment should be understanding and compassionate
but no commitment should be made on whether this is a violation or which action
will be taken. Specific guidance is in the checklist below.
For in-person events that have a violation reported, the report should be sent
to the Code of Conduct committee within 24 hours by the on-site CoC response
-team.
+team.
+(immediate-response-checklist)=
-.. _Immediate Response Checklist:
-
-Immediate Response Checklist
-============================
+## Immediate Response Checklist
The CoC committee generally works, decides, and communicates together. If the
report indicates that an immediate response is required and other committee
@@ -60,120 +52,113 @@ members are not available, any committee member may take the immediate action
they think is necessary. In-person Code of Conduct response teams should use
this checklist to determine if an immediate response is needed.
-* If the incident involves physical danger, contact the appropriate law
+- If the incident involves physical danger, contact the appropriate law
enforcement or event security immediately. Ensure the reporter feels safe and
stay with them if possible until help arrives.
-* If the act is ongoing and involves harassment or threats against someone in
+- If the act is ongoing and involves harassment or threats against someone in
any space (online or physical), any appropriate response (e.g., ban, physical
removal, or moderation) may be used to immediately stop it.
-* For events that include talks, organizers should end talks early if the
+- For events that include talks, organizers should end talks early if the
violations include harassment or violent threats. There may be talks where
- other types of code of conduct violations occur and organizers should do
- their best to determine if a talk should be ended early or not.
+ other types of code of conduct violations occur and organizers should do
+ their best to determine if a talk should be ended early or not.
When undertaking an immediate response, document the action and notify the
-committee within 24 hours.
-
+committee within 24 hours.
-Response Procedure
-==================
+## Response Procedure
The following is a summary of the steps the committee takes when responding to
-a reported incident.
+a reported incident.
-1. Determine if there is a need for an :ref:`immediate response<Immediate
+1. Determine if there is a need for an {ref}`immediate response<Immediate
Response Checklist>`.
-
-2. :ref:`Acknowledge the report<Receiving a report>` within 24 hours.
-
-3. :ref:`Discuss the incident report<Incident Response Assessment>`, gather
- more information, and determine a :ref:`resolution<Resolutions>`.
-
-4. During this process, the :ref:`reporter will be informed of the
+2. {ref}`Acknowledge the report<Receiving a report>` within 24 hours.
+3. {ref}`Discuss the incident report<Incident Response Assessment>`, gather
+ more information, and determine a {ref}`resolution<Resolutions>`.
+4. During this process, the {ref}`reporter will be informed of the
resolution<Following Up With the Reportee>` and feedback is requested. This
feedback may or may not be used to re-evaluate the resolution.
-
5. Inform the reportee of the resolution. The reportee is provided options to
- :ref:`appeal<Appeal Process>`.
-
-6. The :ref:`resolution<Resolutions>` is implemented.
-
+ {ref}`appeal<Appeal Process>`.
+6. The {ref}`resolution<Resolutions>` is implemented.
7. All reports, data, notes, and resolutions are logged in a private location
(e.g., Google Drive or other database).
The committee will never make public statements about a resolution and will
-only publish :ref:`transparency reports<Transparency Reports>`. If a public
+only publish {ref}`transparency reports<Transparency Reports>`. If a public
statement is necessary and requested by the committee, it will be given by the
LLVM Foundation Board of Directors.
-Report Acknowledgement
-======================
+## Report Acknowledgement
When a report is received, the committee will reply to the reporter to confirm
-receipt within 24 hours of the incident being reported.
+receipt within 24 hours of the incident being reported.
This acknowledgement will contain:
-* Acknowledgement of the incident report
-* Next steps of the committee for responding to the incident
-* Reminder of confidentiality policy regarding the report and parties involved
+- Acknowledgement of the incident report
+- Next steps of the committee for responding to the incident
+- Reminder of confidentiality policy regarding the report and parties involved
All incident reports should be assessed if they require immediate response and
acted on accordingly.
-.. _Incident Response Assessment:
+(incident-response-assessment)=
-Incident Response Assessment
-============================
+## Incident Response Assessment
The committee will assess the incident and determine an appropriate response.
The assessment will be documented and retained in records. Here are some
guidelines for the process:
-* Review report documentation to determine the content and context of the
+- Review report documentation to determine the content and context of the
incident.
- * Request additional information if needed from the reporter.
+ - Request additional information if needed from the reporter.
-* Determine if it occurred within the scope of the CoC.
-* Determine if it violated the CoC and specifically which part.
-* Consult documentation of past incidents for patterns of behavior (if
+- Determine if it occurred within the scope of the CoC.
+
+- Determine if it violated the CoC and specifically which part.
+
+- Consult documentation of past incidents for patterns of behavior (if
available and applicable).
-* Follow up with the reportee to get their view or any other additional
+
+- Follow up with the reportee to get their view or any other additional
information.
-* Determine appropriate resolutions to the incident when all information has
+
+- Determine appropriate resolutions to the incident when all information has
been gathered.
-* Notify the reporter of the resolution and request feedback. This may or may
+
+- Notify the reporter of the resolution and request feedback. This may or may
not be used to reevaluate the resolution.
The committee will aim to have a resolution agreed upon within two weeks of
receipt of the incident report. In the event that a resolution cannot be
determined within that time, the CoC committee will respond to the reporter(s)
-with an updated and projected timeline for resolution.
+with an updated and projected timeline for resolution.
-.. _Following Up With the Reportee:
+(following-up-with-the-reportee)=
-Following Up With the Reportee
-==============================
+## Following Up With the Reportee
When following up with the reportee, the committee will:
-* Explain that an incident was reported that involves the reportee.
-* In this explanation, the focus will be on the impact of their behavior, not
+- Explain that an incident was reported that involves the reportee.
+- In this explanation, the focus will be on the impact of their behavior, not
their intent.
-* Reiterate the Code of Conduct and that their behavior may be deemed
+- Reiterate the Code of Conduct and that their behavior may be deemed
inappropriate.
-* Give them the opportunity to state their view of the incident.
-* Explain the possible resolutions that may be enforced should the CoC
+- Give them the opportunity to state their view of the incident.
+- Explain the possible resolutions that may be enforced should the CoC
committee determine there is a breach.
The reportee will be given a week to respond with the option to request
additional time if needed and subject to approval of the CoC Committee.
-.. _Resolutions:
+(resolutions)=
-Resolutions
-===========
+## Resolutions
The committee should agree unanimously on a resolution. In the event that the
committee cannot reach a unanimous resolution, the LLVM Foundation Board of
@@ -185,25 +170,25 @@ appropriate way, while also looking to prevent or reduce the risk of continuing
harm in the future. Any action deemed necessary by the committee will be
taken, but below is a list of possible resolutions:
-* Taking no further action as the incident was determined not to be a
+- Taking no further action as the incident was determined not to be a
violation.
-* A private verbal warning and/or reprimand from the committee to the
+- A private verbal warning and/or reprimand from the committee to the
individual(s) involved and request to stop this behavior. This conversation
may happen in person, email, by phone, video chat, or Discord.
-* Request that the reportee avoid any interaction with, and physical proximity
+- Request that the reportee avoid any interaction with, and physical proximity
to, another person for the remainder of the event.
-* Refusal of alcoholic beverage purchases by the reportee at LLVM events.
-* Ending a talk/tutorial/etc at an LLVM event early. See immediate response
+- Refusal of alcoholic beverage purchases by the reportee at LLVM events.
+- Ending a talk/tutorial/etc at an LLVM event early. See immediate response
checklist for further clarification.
-* Not publishing the video or slides of a talk.
-* Not allowing a speaker to give (further) talks at LLVM events for a specified
+- Not publishing the video or slides of a talk.
+- Not allowing a speaker to give (further) talks at LLVM events for a specified
amount of time or ever.
-* Requiring that the reportee immediately leave an event and not return.
-* Immediately ending any volunteer responsibilities and privileges the reportee
+- Requiring that the reportee immediately leave an event and not return.
+- Immediately ending any volunteer responsibilities and privileges the reportee
holds.
-* An imposed suspension (e.g., asking someone to "take a week off" from mailing
- lists, bug tracker, Discord, repositories, or other communication forms).
-* A permanent or temporary ban from some or all LLVM Project spaces (online or
+- An imposed suspension (e.g., asking someone to "take a week off" from mailing
+ lists, bug tracker, Discord, repositories, or other communication forms).
+- A permanent or temporary ban from some or all LLVM Project spaces (online or
in person).
Once a resolution is agreed upon, but before it is enacted, the committee will
@@ -212,30 +197,27 @@ resolution. They will ask if this resolution is acceptable and must note
feedback for the record. However, the committee is not required to act on this
feedback.
-.. _Appeal Process:
+(appeal-process)=
-Appeal Process
-===============
+## Appeal Process
Any individual(s) determined to have violated the CoC have the right to appeal
-a resolution decision. An appeal can be made directly to the committee by sending an
-email to conduct at llvm.org with subject line Code of Conduct Incident Appeal.
+a resolution decision. An appeal can be made directly to the committee by sending an
+email to <mailto:conduct at llvm.org> with subject line Code of Conduct Incident Appeal.
-This process is intended to consider new or different evidence from the
-initial incident investigation. The email should include documentation related
-to the incident to support the appeal. The said documentation may include,
+This process is intended to consider new or different evidence from the
+initial incident investigation. The email should include documentation related
+to the incident to support the appeal. The said documentation may include,
but does not have to be limited to:
-* Information from the reportee justifying reasoning for the appeal.
-* Statements from other individuals involved in the incident to support the
+- Information from the reportee justifying reasoning for the appeal.
+- Statements from other individuals involved in the incident to support the
appeal.
Appeals can be requested up to 30 days after a resolution has been communicated
-to the individual(s). The committee will aim to evaluate appeals within two weeks of receipt. In the event that appeal can not be evaluated within that time, the CoC committee will respond with an updated and projected timeline.
-
+to the individual(s). The committee will aim to evaluate appeals within two weeks of receipt. In the event that appeal can not be evaluated within that time, the CoC committee will respond with an updated and projected timeline.
-Conflicts of Interest
-=====================
+## Conflicts of Interest
Committee members should declare any conflicts of interest as soon as possible
and before any official committee meetings. This can mean being friends with
@@ -258,27 +240,25 @@ will not share more information than they would have with a non-member. If a
member of the committee is found to have violated the CoC, they may no longer
be able to keep serving on the committee.
-Confidentiality
-===============
+## Confidentiality
All reports will be kept confidential with details shared only with the Code of
Conduct committee members. However, the Code of Conduct Committee will always
comply with law enforcement when directed. In the case that a CoC committee
member is involved in a report, the member will be asked to recuse themselves
from ongoing conversations, and they will not have access to reports after the
-enforcement decision has been made.
+enforcement decision has been made.
In the event of a temporary suspension or ban, the appropriate people must be
notified of the ban in order to restrict access to infrastructure or events.
These individuals will only be notified of the person's name and the
restrictions imposed. They will be under a confidentiality clause and not
allowed to respond to questions regarding the ban and should direct all
-questions to the CoC committee.
+questions to the CoC committee.
-.. _Transparency Reports:
+(transparency-reports)=
-Transparency Reports
-====================
+## Transparency Reports
Lack of transparency in the outcomes of our Code of Conduct incidents leaves
our community without an understanding of how or if the organizers worked to
@@ -287,28 +267,24 @@ reports, if reports are received, at least 2 times in a calendar year.
A transparency report consists of 2 parts:
-* An overview of the reports received, and resolutions.
-* A more detailed summary of each reported incident and the resolution while
+- An overview of the reports received, and resolutions.
+- A more detailed summary of each reported incident and the resolution while
maintaining confidentiality.
These reports will be published on the LLVM website.
-Thanks!
-=======
-
-
-This guide was created and inspired by the following: the `Django Project`_,
-`Carpentries Response Guide`_, and the `Write The Docs Response Guide`_.
+## Thanks!
-License
-=======
+This guide was created and inspired by the following: the [Django Project][django project],
+[Carpentries Response Guide][carpentries response guide], and the [Write The Docs Response Guide][write the docs response guide].
-All content on this page is licensed under a `Creative Commons Attribution 3.0
-Unported License`_.
+## License
+All content on this page is licensed under a [Creative Commons Attribution 3.0
+Unported License][creative commons attribution 3.0 unported license].
-.. _Django Project: https://www.djangoproject.com/conduct/
-.. _Carpentries Response Guide: https://docs.carpentries.org/topic_folders/policies/enforcement-guidelines.html
-.. _Write The Docs Response Guide: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
-.. _Creative Commons Attribution 3.0 Unported License: http://creativecommons.org/licenses/by/3.0/
+[carpentries response guide]: https://docs.carpentries.org/topic_folders/policies/enforcement-guidelines.html
+[creative commons attribution 3.0 unported license]: http://creativecommons.org/licenses/by/3.0/
+[django project]: https://www.djangoproject.com/conduct/
+[write the docs response guide]: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
diff --git a/llvm/docs/SymbolizerMarkupFormat.md b/llvm/docs/SymbolizerMarkupFormat.md
index 5ae6fa769f330..2b9fa8df867dc 100644
--- a/llvm/docs/SymbolizerMarkupFormat.md
+++ b/llvm/docs/SymbolizerMarkupFormat.md
@@ -1,10 +1,6 @@
-==========================
-Symbolizer Markup Format
-==========================
+# Symbolizer Markup Format
-
-Overview
-========
+## Overview
This document defines a text format for log messages that can be processed by a
symbolizing filter. The basic idea is that logging code emits text that contains
@@ -28,15 +24,14 @@ distinctive. It's simple enough to be matched and parsed with straightforward
code. It's distinctive enough that character sequences that look like the start
or end of a markup element should rarely if ever appear incidentally in logging
text. It's specifically intended not to require sanitizing plain text, such as
-the HTML/XML requirement to replace ``<`` with ``<`` and the like.
+the HTML/XML requirement to replace `<` with `<` and the like.
-:doc:`llvm-symbolizer <CommandGuide/llvm-symbolizer>` includes a symbolizing
-filter via its ``--filter-markup`` option. Also, LLVM utilites emit stack
-traces as markup when the ``LLVM_ENABLE_SYMBOLIZER_MARKUP`` environment
+{doc}`llvm-symbolizer <CommandGuide/llvm-symbolizer>` includes a symbolizing
+filter via its `--filter-markup` option. Also, LLVM utilites emit stack
+traces as markup when the `LLVM_ENABLE_SYMBOLIZER_MARKUP` environment
variable is set.
-Scope and assumptions
-=====================
+## Scope and assumptions
A symbolizing filter implementation will be independent both of the target
operating system and machine architecture where the logs are generated and of
@@ -61,16 +56,15 @@ disjoint address regions in most operating systems, a single user process
address space plus the kernel address space can be treated as a single address
space for symbolization purposes if desired.
-Dependence on Build IDs
-=======================
+## Dependence on Build IDs
The symbolizer markup scheme relies on contextual information about runtime
memory address layout to make it possible to convert markup elements into useful
symbolic form. This relies on having an unmistakable identification of which
binary was loaded at each address.
-An ELF Build ID is the payload of an ELF note with name ``"GNU"`` and type
-``NT_GNU_BUILD_ID``, a unique byte sequence that identifies a particular binary
+An ELF Build ID is the payload of an ELF note with name `"GNU"` and type
+`NT_GNU_BUILD_ID`, a unique byte sequence that identifies a particular binary
(executable, shared library, loadable module, or driver module). The linker
generates this automatically based on a hash that includes the complete symbol
table and debugging information, even if this is later stripped from the binary.
@@ -81,20 +75,18 @@ Build ID. The symbolizing filter must have some means of mapping a Build ID back
to the original ELF binary (either the whole unstripped binary, or a stripped
binary paired with a separate debug file).
-Colorization
-============
+## Colorization
The markup format supports a restricted subset of ANSI X3.64 SGR (Select Graphic
Rendition) control sequences. These are unlike other markup elements:
-* They specify presentation details (bold or colors) rather than semantic
+- They specify presentation details (bold or colors) rather than semantic
information. The association of semantic meaning with color (e.g. red for
errors) is chosen by the code doing the logging, rather than by the UI
presentation of the symbolizing filter. This is a concession to existing code
(e.g. LLVM sanitizer runtimes) that use specific colors and would require
substantial changes to generate semantic markup instead.
-
-* A single control sequence changes "the state", rather than being an
+- A single control sequence changes "the state", rather than being an
hierarchical structure that surrounds affected text.
The filter processes ANSI SGR control sequences only within a single line. If a
@@ -108,36 +100,35 @@ However, other markup elements may appear between SGR control sequences and the
color/bold state is expected to apply to the symbolic output that replaces the
markup element in the filter's output.
-The accepted SGR control sequences all have the form ``"\033[%um"`` (expressed here
-using C string syntax), where ``%u`` is one of these:
-
-==== ============================ ===============================================
-Code Effect Notes
-==== ============================ ===============================================
-0 Reset to default formatting.
-1 Bold text Combines with color states, doesn't reset them.
-30 Black foreground
-31 Red foreground
-32 Green foreground
-33 Yellow foreground
-34 Blue foreground
-35 Magenta foreground
-36 Cyan foreground
-37 White foreground
-==== ============================ ===============================================
-
-Common markup element syntax
-============================
+The accepted SGR control sequences all have the form `"\033[%um"` (expressed here
+using C string syntax), where `%u` is one of these:
+
+| Code | Effect | Notes |
+| ---- | ---------------------------- | ----------------------------------------------- |
+| 0 | Reset to default formatting. | |
+| 1 | Bold text | Combines with color states, doesn't reset them. |
+| 30 | Black foreground | |
+| 31 | Red foreground | |
+| 32 | Green foreground | |
+| 33 | Yellow foreground | |
+| 34 | Blue foreground | |
+| 35 | Magenta foreground | |
+| 36 | Cyan foreground | |
+| 37 | White foreground | |
+
+## Common markup element syntax
All the markup elements share a common syntactic structure to facilitate simple
-matching and parsing code. Each element has the form::
+matching and parsing code. Each element has the form:
- {{{tag:fields}}}
+```
+{{{tag:fields}}}
+```
-``tag`` identifies one of the element types described below, and is always a
+`tag` identifies one of the element types described below, and is always a
short alphabetic string that must be in lower case. The rest of the element
-consists of one or more fields. Fields are separated by ``:`` and cannot contain
-any ``:`` or ``}`` characters. How many fields must be or may be present and
+consists of one or more fields. Fields are separated by `:` and cannot contain
+any `:` or `}` characters. How many fields must be or may be present and
what they contain is specified for each element type.
No markup elements or ANSI SGR control sequences are interpreted inside the
@@ -148,203 +139,218 @@ adding new fields to backwards-compatibly extend elements. Implementations need
not ignore them silently, but the element should behave otherwise as if the
fields were removed.
-In the descriptions of each element type, ``printf``-style placeholders indicate
+In the descriptions of each element type, `printf`-style placeholders indicate
field contents:
-``%s``
- A string of printable characters, not including ``:`` or ``}``.
+`%s`
+
+: A string of printable characters, not including `:` or `}`.
-``%p``
- An address value represented by ``0x`` followed by an even number of
- hexadecimal digits (using either lower-case or upper-case for ``A``–``F``).
- If the digits are all ``0`` then the ``0x`` prefix may be omitted. No more
+`%p`
+
+: An address value represented by `0x` followed by an even number of
+ hexadecimal digits (using either lower-case or upper-case for `A`–`F`).
+ If the digits are all `0` then the `0x` prefix may be omitted. No more
than 16 hexadecimal digits are expected to appear in a single value (64 bits).
-``%u``
- A nonnegative decimal integer.
+`%u`
+
+: A nonnegative decimal integer.
+
+`%i`
+
+: A nonnegative integer. The digits are hexadecimal if prefixed by `0x`, octal
+ if prefixed by `0`, or decimal otherwise.
-``%i``
- A nonnegative integer. The digits are hexadecimal if prefixed by ``0x``, octal
- if prefixed by ``0``, or decimal otherwise.
+`%x`
-``%x``
- A sequence of an even number of hexadecimal digits (using either lower-case or
- upper-case for ``A``–``F``), with no ``0x`` prefix. This represents an
+: A sequence of an even number of hexadecimal digits (using either lower-case or
+ upper-case for `A`–`F`), with no `0x` prefix. This represents an
arbitrary sequence of bytes, such as an ELF Build ID.
-Presentation elements
-=====================
+## Presentation elements
These are elements that convey a specific program entity to be displayed in
human-readable symbolic form.
-``{{{symbol:%s}}}``
- Here ``%s`` is the linkage name for a symbol or type. It may require
+`{{{symbol:%s}}}`
+
+: Here `%s` is the linkage name for a symbol or type. It may require
demangling according to language ABI rules. Even for unmangled names, it's
recommended that this markup element be used to identify a symbol name so that
it can be presented distinctively.
- Examples::
-
- {{{symbol:_ZN7Mangled4NameEv}}}
- {{{symbol:foobar}}}
-
-``{{{pc:%p}}}``, ``{{{pc:%p:ra}}}``, ``{{{pc:%p:pc}}}``
-
- Here ``%p`` is the memory address of a code location. It might be presented as a
- function name and source location. The second two forms distinguish the kind of
- code location, as described in detail for bt elements below.
-
- Examples::
-
- {{{pc:0x12345678}}}
- {{{pc:0xffffffff9abcdef0}}}
-
-``{{{data:%p}}}``
-
- Here ``%p`` is the memory address of a data location. It might be presented as
- the name of a global variable at that location.
-
- Examples::
-
- {{{data:0x12345678}}}
- {{{data:0xffffffff9abcdef0}}}
-
-``{{{bt:%u:%p}}}``, ``{{{bt:%u:%p:ra}}}``, ``{{{bt:%u:%p:pc}}}``
-
- This represents one frame in a backtrace. It usually appears on a line by
- itself (surrounded only by whitespace), in a sequence of such lines with
- ascending frame numbers. So the human-readable output might be formatted
- assuming that, such that it looks good for a sequence of bt elements each
- alone on its line with uniform indentation of each line. But it can appear
- anywhere, so the filter should not remove any non-whitespace text surrounding
- the element.
-
- Here ``%u`` is the frame number, which starts at zero for the location of the
- fault being identified, increments to one for the caller of frame zero's call
- frame, to two for the caller of frame one, etc. ``%p`` is the memory address
- of a code location.
-
- Code locations in a backtrace come from two distinct sources. Most backtrace
- frames describe a return address code location, i.e. the instruction
- immediately after a call instruction. This is the location of code that has
- yet to run, since the function called there has not yet returned. Hence the
- code location of actual interest is usually the call site itself rather than
- the return address, i.e. one instruction earlier. When presenting the source
- location for a return address frame, the symbolizing filter will subtract one
- byte or one instruction length from the actual return address for the call
- site, with the intent that the address logged can be translated directly to a
- source location for the call site and not for the apparent return site
- thereafter (which can be confusing). When inlined functions are involved, the
- call site and the return site can appear to be in different functions at
- entirely unrelated source locations rather than just a line away, making the
- confusion of showing the return site rather the call site quite severe.
-
- Often the first frame in a backtrace ("frame zero") identifies the precise
- code location of a fault, trap, or asynchronous interrupt rather than a return
- address. At other times, even the first frame is actually a return address
- (for example, backtraces collected at the time of an object allocation and
- reported later when the allocated object is used or misused). When a system
- supports in-thread trap handling, there may also be frames after the first
- that represent a precise interrupted code location rather than a return
- address, presented as the "caller" of a trap handler function (for example,
- signal handlers in POSIX systems).
-
- Return address frames are identified by the ``:ra`` suffix. Precise code
- location frames are identified by the ``:pc`` suffix.
-
- Traditional practice has often been to collect backtraces as simple address
- lists, losing the distinction between return address code locations and
- precise code locations. Some such code applies the "subtract one" adjustment
- described above to the address values before reporting them, and it's not
- always clear or consistent whether this adjustment has been applied or not.
- These ambiguous cases are supported by the ``bt`` and ``pc`` forms with no
- ``:ra`` or ``:pc`` suffix, which indicate it's unclear which sort of code
- location this is. However, it's highly recommended that all emitters use the
- suffixed forms and deliver address values with no adjustments applied. When
- traditional practice has been ambiguous, the majority of cases seem to have
- been of printing addresses that are return address code locations and printing
- them without adjustment. So the symbolizing filter will usually apply the
- "subtract one byte" adjustment to an address printed without a disambiguating
- suffix. Assuming that a call instruction is longer than one byte on all
- supported machines, applying the "subtract one byte" adjustment a second time
- still results in an address somewhere in the call instruction, so a little
- sloppiness here often does little or no harm.
-
- Examples::
-
- {{{bt:0:0x12345678:pc}}}
- {{{bt:1:0xffffffff9abcdef0:ra}}}
-
-``{{{hexdict:...}}}`` [#not_yet_implemented]_
-
- This element can span multiple lines. Here ``...`` is a sequence of key-value
- pairs where a single ``:`` separates each key from its value, and arbitrary
- whitespace separates the pairs. The value (right-hand side) of each pair
- either is one or more ``0`` digits, or is ``0x`` followed by hexadecimal
- digits. Each value might be a memory address or might be some other integer
- (including an integer that looks like a likely memory address but actually has
- an unrelated purpose). When the contextual information about the memory layout
- suggests that a given value could be a code location or a global variable data
- address, it might be presented as a source location or variable name or with
- active UI that makes such interpretation optionally visible.
-
- The intended use is for things like register dumps, where the emitter doesn't
- know which values might have a symbolic interpretation but a presentation that
- makes plausible symbolic interpretations available might be very useful to
- someone reading the log. At the same time, a flat text presentation should
- usually avoid interfering too much with the original contents and formatting
- of the dump. For example, it might use footnotes with source locations for
- values that appear to be code locations. An active UI presentation might show
- the dump text as is, but highlight values with symbolic information available
- and pop up a presentation of symbolic details when a value is selected.
-
- Example::
-
- {{{hexdict:
- CS: 0 RIP: 0x6ee17076fb80 EFL: 0x10246 CR2: 0
- RAX: 0xc53d0acbcf0 RBX: 0x1e659ea7e0d0 RCX: 0 RDX: 0x6ee1708300cc
- RSI: 0 RDI: 0x6ee170830040 RBP: 0x3b13734898e0 RSP: 0x3b13734898d8
- R8: 0x3b1373489860 R9: 0x2776ff4f R10: 0x2749d3e9a940 R11: 0x246
- R12: 0x1e659ea7e0f0 R13: 0xd7231230fd6ff2e7 R14: 0x1e659ea7e108 R15: 0xc53d0acbcf0
- }}}
-
-Trigger elements
-================
+ Examples:
+
+ ```
+ {{{symbol:_ZN7Mangled4NameEv}}}
+ {{{symbol:foobar}}}
+ ```
+
+`{{{pc:%p}}}`, `{{{pc:%p:ra}}}`, `{{{pc:%p:pc}}}`
+
+> Here `%p` is the memory address of a code location. It might be presented as a
+> function name and source location. The second two forms distinguish the kind of
+> code location, as described in detail for bt elements below.
+>
+> Examples:
+>
+> ```
+> {{{pc:0x12345678}}}
+> {{{pc:0xffffffff9abcdef0}}}
+> ```
+
+`{{{data:%p}}}`
+
+> Here `%p` is the memory address of a data location. It might be presented as
+> the name of a global variable at that location.
+>
+> Examples:
+>
+> ```
+> {{{data:0x12345678}}}
+> {{{data:0xffffffff9abcdef0}}}
+> ```
+
+`{{{bt:%u:%p}}}`, `{{{bt:%u:%p:ra}}}`, `{{{bt:%u:%p:pc}}}`
+
+> This represents one frame in a backtrace. It usually appears on a line by
+> itself (surrounded only by whitespace), in a sequence of such lines with
+> ascending frame numbers. So the human-readable output might be formatted
+> assuming that, such that it looks good for a sequence of bt elements each
+> alone on its line with uniform indentation of each line. But it can appear
+> anywhere, so the filter should not remove any non-whitespace text surrounding
+> the element.
+>
+> Here `%u` is the frame number, which starts at zero for the location of the
+> fault being identified, increments to one for the caller of frame zero's call
+> frame, to two for the caller of frame one, etc. `%p` is the memory address
+> of a code location.
+>
+> Code locations in a backtrace come from two distinct sources. Most backtrace
+> frames describe a return address code location, i.e. the instruction
+> immediately after a call instruction. This is the location of code that has
+> yet to run, since the function called there has not yet returned. Hence the
+> code location of actual interest is usually the call site itself rather than
+> the return address, i.e. one instruction earlier. When presenting the source
+> location for a return address frame, the symbolizing filter will subtract one
+> byte or one instruction length from the actual return address for the call
+> site, with the intent that the address logged can be translated directly to a
+> source location for the call site and not for the apparent return site
+> thereafter (which can be confusing). When inlined functions are involved, the
+> call site and the return site can appear to be in different functions at
+> entirely unrelated source locations rather than just a line away, making the
+> confusion of showing the return site rather the call site quite severe.
+>
+> Often the first frame in a backtrace ("frame zero") identifies the precise
+> code location of a fault, trap, or asynchronous interrupt rather than a return
+> address. At other times, even the first frame is actually a return address
+> (for example, backtraces collected at the time of an object allocation and
+> reported later when the allocated object is used or misused). When a system
+> supports in-thread trap handling, there may also be frames after the first
+> that represent a precise interrupted code location rather than a return
+> address, presented as the "caller" of a trap handler function (for example,
+> signal handlers in POSIX systems).
+>
+> Return address frames are identified by the `:ra` suffix. Precise code
+> location frames are identified by the `:pc` suffix.
+>
+> Traditional practice has often been to collect backtraces as simple address
+> lists, losing the distinction between return address code locations and
+> precise code locations. Some such code applies the "subtract one" adjustment
+> described above to the address values before reporting them, and it's not
+> always clear or consistent whether this adjustment has been applied or not.
+> These ambiguous cases are supported by the `bt` and `pc` forms with no
+> `:ra` or `:pc` suffix, which indicate it's unclear which sort of code
+> location this is. However, it's highly recommended that all emitters use the
+> suffixed forms and deliver address values with no adjustments applied. When
+> traditional practice has been ambiguous, the majority of cases seem to have
+> been of printing addresses that are return address code locations and printing
+> them without adjustment. So the symbolizing filter will usually apply the
+> "subtract one byte" adjustment to an address printed without a disambiguating
+> suffix. Assuming that a call instruction is longer than one byte on all
+> supported machines, applying the "subtract one byte" adjustment a second time
+> still results in an address somewhere in the call instruction, so a little
+> sloppiness here often does little or no harm.
+>
+> Examples:
+>
+> ```
+> {{{bt:0:0x12345678:pc}}}
+> {{{bt:1:0xffffffff9abcdef0:ra}}}
+> ```
+
+`{{{hexdict:...}}}` [^not-yet-implemented]
+
+> This element can span multiple lines. Here `...` is a sequence of key-value
+> pairs where a single `:` separates each key from its value, and arbitrary
+> whitespace separates the pairs. The value (right-hand side) of each pair
+> either is one or more `0` digits, or is `0x` followed by hexadecimal
+> digits. Each value might be a memory address or might be some other integer
+> (including an integer that looks like a likely memory address but actually has
+> an unrelated purpose). When the contextual information about the memory layout
+> suggests that a given value could be a code location or a global variable data
+> address, it might be presented as a source location or variable name or with
+> active UI that makes such interpretation optionally visible.
+>
+> The intended use is for things like register dumps, where the emitter doesn't
+> know which values might have a symbolic interpretation but a presentation that
+> makes plausible symbolic interpretations available might be very useful to
+> someone reading the log. At the same time, a flat text presentation should
+> usually avoid interfering too much with the original contents and formatting
+> of the dump. For example, it might use footnotes with source locations for
+> values that appear to be code locations. An active UI presentation might show
+> the dump text as is, but highlight values with symbolic information available
+> and pop up a presentation of symbolic details when a value is selected.
+>
+> Example:
+>
+> ```
+> {{{hexdict:
+> CS: 0 RIP: 0x6ee17076fb80 EFL: 0x10246 CR2: 0
+> RAX: 0xc53d0acbcf0 RBX: 0x1e659ea7e0d0 RCX: 0 RDX: 0x6ee1708300cc
+> RSI: 0 RDI: 0x6ee170830040 RBP: 0x3b13734898e0 RSP: 0x3b13734898d8
+> R8: 0x3b1373489860 R9: 0x2776ff4f R10: 0x2749d3e9a940 R11: 0x246
+> R12: 0x1e659ea7e0f0 R13: 0xd7231230fd6ff2e7 R14: 0x1e659ea7e108 R15: 0xc53d0acbcf0
+> }}}
+> ```
+
+## Trigger elements
These elements cause an external action and will be presented to the user in a
human-readable form. Generally they trigger an external action to occur that
results in a linkable page. The link or some other informative information about
the external action can then be presented to the user.
-``{{{dumpfile:%s:%s}}}`` [#not_yet_implemented]_
-
- Here the first ``%s`` is an identifier for a type of dump and the second
- ``%s`` is an identifier for a particular dump that's just been published. The
- types of dumps, the exact meaning of "published", and the nature of the
- identifier are outside the scope of the markup format per se. In general it
- might correspond to writing a file by that name or something similar.
-
- This element may trigger additional post-processing work beyond symbolizing
- the markup. It indicates that a dump file of some sort has been published.
- Some logic attached to the symbolizing filter may understand certain types of
- dump file and trigger additional post-processing of the dump file upon
- encountering this element (e.g. generating visualizations, symbolization). The
- expectation is that the information collected from contextual elements
- (described below) in the logging stream may be necessary to decode the content
- of the dump. So if the symbolizing filter triggers other processing, it may
- need to feed some distilled form of the contextual information to those
- processes.
-
- An example of a type identifier is ``sancov``, for dumps from LLVM
- `SanitizerCoverage <https://clang.llvm.org/docs/SanitizerCoverage.html>`_.
-
- Example::
-
- {{{dumpfile:sancov:sancov.8675}}}
-
-Contextual elements
-===================
+`{{{dumpfile:%s:%s}}}` [^not-yet-implemented]
+
+> Here the first `%s` is an identifier for a type of dump and the second
+> `%s` is an identifier for a particular dump that's just been published. The
+> types of dumps, the exact meaning of "published", and the nature of the
+> identifier are outside the scope of the markup format per se. In general it
+> might correspond to writing a file by that name or something similar.
+>
+> This element may trigger additional post-processing work beyond symbolizing
+> the markup. It indicates that a dump file of some sort has been published.
+> Some logic attached to the symbolizing filter may understand certain types of
+> dump file and trigger additional post-processing of the dump file upon
+> encountering this element (e.g. generating visualizations, symbolization). The
+> expectation is that the information collected from contextual elements
+> (described below) in the logging stream may be necessary to decode the content
+> of the dump. So if the symbolizing filter triggers other processing, it may
+> need to feed some distilled form of the contextual information to those
+> processes.
+>
+> An example of a type identifier is `sancov`, for dumps from LLVM
+> [SanitizerCoverage](https://clang.llvm.org/docs/SanitizerCoverage.html).
+>
+> Example:
+>
+> ```
+> {{{dumpfile:sancov:sancov.8675}}}
+> ```
+
+## Contextual elements
These are elements that supply information necessary to convert presentation
elements to symbolic form. Unlike presentation elements, they are not directly
@@ -365,75 +371,81 @@ elements should have appeared somewhere earlier in the logging stream. It should
always be possible for the symbolizing filter to be implemented as a single pass
over the raw logging stream, accumulating context and massaging text as it goes.
-``{{{reset}}}``
-
- This should be output before any other contextual element. The need for this
- contextual element is to support implementations that handle logs coming from
- multiple processes. Such implementations might not know when a new process
- starts or ends. Because some identifying information (like process IDs) might
- be the same between old and new processes, a way is needed to distinguish two
- processes with such identical identifying information. This element informs
- such implementations to reset the state of a filter so that information from a
- previous process's contextual elements is not assumed for new process that
- just happens have the same identifying information.
-
-``{{{module:%i:%s:%s:...}}}``
-
- This element represents a so-called "module". A "module" is a single linked
- binary, such as a loaded ELF file. Usually each module occupies a contiguous
- range of memory.
-
- Here ``%i`` is the module ID which is used by other contextual elements to
- refer to this module. The first ``%s`` is a human-readable identifier for the
- module, such as an ELF ``DT_SONAME`` string or a file name; but it might be
- empty. It's only for casual information. Only the module ID is used to refer
- to this module in other contextual elements, never the ``%s`` string. The
- ``module`` element defining a module ID must always be emitted before any
- other elements that refer to that module ID, so that a filter never needs to
- keep track of dangling references. The second ``%s`` is the module type and it
- determines what the remaining fields are. The following module types are
- supported:
-
- * ``elf:%x``
-
- Here ``%x`` encodes an ELF Build ID. The Build ID should refer to a single
- linked binary. The Build ID string is the sole way to identify the binary from
- which this module was loaded.
-
- Example::
-
- {{{module:1:libc.so:elf:83238ab56ba10497}}}
-
-``{{{mmap:%p:%i:...}}}``
-
- This contextual element is used to give information about a particular region
- in memory. ``%p`` is the starting address and ``%i`` gives the size in hex of the
- region of memory. The ``...`` part can take different forms to give different
- information about the specified region of memory. The allowed forms are the
- following:
-
- * ``load:%i:%s:%p``
-
- This subelement informs the filter that a segment was loaded from a module.
- The module is identified by its module ID ``%i``. The ``%s`` is one or more of
- the letters 'r', 'w', and 'x' (in that order and in either upper or lower
- case) to indicate this segment of memory is readable, writable, and/or
- executable. The symbolizing filter can use this information to guess whether
- an address is a likely code address or a likely data address in the given
- module. The remaining ``%p`` gives the module relative address. For ELF files
- the module relative address will be the ``p_vaddr`` of the associated program
- header. For example if your module's executable segment has
- ``p_vaddr=0x1000``, ``p_memsz=0x1234``, and was loaded at ``0x7acba69d5000``
- then you need to subtract ``0x7acba69d4000`` from any address between
- ``0x7acba69d5000`` and ``0x7acba69d6234`` to get the module relative address.
- The starting address will usually have been rounded down to the active page
- size, and the size rounded up.
-
- Example::
-
- {{{mmap:0x7acba69d5000:0x5a000:load:1:rx:0x1000}}}
-
-.. rubric:: Footnotes
-
-.. [#not_yet_implemented] This markup element is not yet implemented in
- :doc:`llvm-symbolizer <CommandGuide/llvm-symbolizer>`.
+`{{{reset}}}`
+
+> This should be output before any other contextual element. The need for this
+> contextual element is to support implementations that handle logs coming from
+> multiple processes. Such implementations might not know when a new process
+> starts or ends. Because some identifying information (like process IDs) might
+> be the same between old and new processes, a way is needed to distinguish two
+> processes with such identical identifying information. This element informs
+> such implementations to reset the state of a filter so that information from a
+> previous process's contextual elements is not assumed for new process that
+> just happens have the same identifying information.
+
+`{{{module:%i:%s:%s:...}}}`
+
+> This element represents a so-called "module". A "module" is a single linked
+> binary, such as a loaded ELF file. Usually each module occupies a contiguous
+> range of memory.
+>
+> Here `%i` is the module ID which is used by other contextual elements to
+> refer to this module. The first `%s` is a human-readable identifier for the
+> module, such as an ELF `DT_SONAME` string or a file name; but it might be
+> empty. It's only for casual information. Only the module ID is used to refer
+> to this module in other contextual elements, never the `%s` string. The
+> `module` element defining a module ID must always be emitted before any
+> other elements that refer to that module ID, so that a filter never needs to
+> keep track of dangling references. The second `%s` is the module type and it
+> determines what the remaining fields are. The following module types are
+> supported:
+>
+> - `elf:%x`
+>
+> Here `%x` encodes an ELF Build ID. The Build ID should refer to a single
+> linked binary. The Build ID string is the sole way to identify the binary from
+> which this module was loaded.
+>
+> Example:
+>
+> ```
+> {{{module:1:libc.so:elf:83238ab56ba10497}}}
+> ```
+
+`{{{mmap:%p:%i:...}}}`
+
+> This contextual element is used to give information about a particular region
+> in memory. `%p` is the starting address and `%i` gives the size in hex of the
+> region of memory. The `...` part can take different forms to give different
+> information about the specified region of memory. The allowed forms are the
+> following:
+>
+> - `load:%i:%s:%p`
+>
+> This subelement informs the filter that a segment was loaded from a module.
+> The module is identified by its module ID `%i`. The `%s` is one or more of
+> the letters 'r', 'w', and 'x' (in that order and in either upper or lower
+> case) to indicate this segment of memory is readable, writable, and/or
+> executable. The symbolizing filter can use this information to guess whether
+> an address is a likely code address or a likely data address in the given
+> module. The remaining `%p` gives the module relative address. For ELF files
+> the module relative address will be the `p_vaddr` of the associated program
+> header. For example if your module's executable segment has
+> `p_vaddr=0x1000`, `p_memsz=0x1234`, and was loaded at `0x7acba69d5000`
+> then you need to subtract `0x7acba69d4000` from any address between
+> `0x7acba69d5000` and `0x7acba69d6234` to get the module relative address.
+> The starting address will usually have been rounded down to the active page
+> size, and the size rounded up.
+>
+> Example:
+>
+> ```
+> {{{mmap:0x7acba69d5000:0x5a000:load:1:rx:0x1000}}}
+> ```
+
+```{rubric} Footnotes
+```
+
+[^not-yet-implemented]: This markup element is not yet implemented in
+ {doc}`llvm-symbolizer <CommandGuide/llvm-symbolizer>`.
+
diff --git a/llvm/docs/TableGenFundamentals.md b/llvm/docs/TableGenFundamentals.md
index 75e82ae2c7a5b..9ff2e2f77e429 100644
--- a/llvm/docs/TableGenFundamentals.md
+++ b/llvm/docs/TableGenFundamentals.md
@@ -1,10 +1,8 @@
-=====================
-TableGen Fundamentals
-=====================
+# TableGen Fundamentals
-Moved
-=====
+## Moved
The TableGen fundamentals documentation has moved to a directory on its own
-and is now available at :doc:`TableGen/index`. Please, change your links to
+and is now available at {doc}`TableGen/index`. Please, change your links to
that page.
+
diff --git a/llvm/docs/Telemetry.md b/llvm/docs/Telemetry.md
index 08493681605f6..52e4a6af2b17e 100644
--- a/llvm/docs/Telemetry.md
+++ b/llvm/docs/Telemetry.md
@@ -1,33 +1,29 @@
-===========================
-Telemetry framework in LLVM
-===========================
+# Telemetry framework in LLVM
+```{toctree}
+:hidden: true
+```
-.. toctree::
- :hidden:
-
-Objective
-=========
+## Objective
Provides a common framework in LLVM for collecting various usage and performance
metrics.
-It is located at ``llvm/Telemetry/Telemetry.h``.
+It is located at `llvm/Telemetry/Telemetry.h`.
+
+### Characteristics
-Characteristics
----------------
-* Configurable and extensible by:
+- Configurable and extensible by:
- * Tools: any tool that wants to use Telemetry can extend and customize it.
- * Vendors: Toolchain vendors can also provide custom implementation of the
+ - Tools: any tool that wants to use Telemetry can extend and customize it.
+ - Vendors: Toolchain vendors can also provide custom implementation of the
library, which could either override or extend the given tool's upstream
implementation, to best fit their organization's usage and privacy models.
- * End users of such tool can also configure Telemetry (as allowed by their
+ - End users of such tool can also configure Telemetry (as allowed by their
vendor).
-Important notes
----------------
+### Important notes
-* There is no concrete implementation of a Telemetry library in upstream LLVM.
+- There is no concrete implementation of a Telemetry library in upstream LLVM.
We only provide the abstract API here. Any tool that wants telemetry will
implement one.
@@ -37,219 +33,216 @@ Important notes
However, in the future, if we see enough common pattern, we can extract them
into a shared place. This is TBD - contributions are welcome.
-* No implementation of Telemetry in upstream LLVM shall store any of the
+- No implementation of Telemetry in upstream LLVM shall store any of the
collected data due to privacy and security reasons:
- * Different organizations have different privacy models:
+ - Different organizations have different privacy models:
- * Which data is sensitive, which is not?
- * Whether it is acceptable for instrumented data to be stored anywhere?
+ - Which data is sensitive, which is not?
+ - Whether it is acceptable for instrumented data to be stored anywhere?
(to a local file, what not?)
- * Data ownership and data collection consents are hard to accommodate from
+ - Data ownership and data collection consents are hard to accommodate from
LLVM developers' point of view:
- * E.g., data collected by Telemetry is not necessarily owned by the user
+ - E.g., data collected by Telemetry is not necessarily owned by the user
of an LLVM tool with Telemetry enabled, hence the user's consent to data
collection is not meaningful. On the other hand, LLVM developers have no
reasonable ways to request consent from the "real" owners.
+## High-level design
-High-level design
-=================
-
-Key components
---------------
+### Key components
The framework consists of four important classes:
-* ``llvm::telemetry::Manager``: The class responsible for collecting and
+- `llvm::telemetry::Manager`: The class responsible for collecting and
transmitting telemetry data. This is the main point of interaction between the
framework and any tool that wants to enable telemetry.
-* ``llvm::telemetry::TelemetryInfo``: Data courier
-* ``llvm::telemetry::Destination``: Data sink to which the Telemetry framework
+- `llvm::telemetry::TelemetryInfo`: Data courier
+- `llvm::telemetry::Destination`: Data sink to which the Telemetry framework
sends data.
Its implementation is transparent to the framework.
It is up to the vendor to decide which pieces of data to forward and where
to forward them to for their final storage.
-* ``llvm::telemetry::Config``: Configurations for the ``Manager``.
-
-.. image:: llvm_telemetry_design.png
-
-How to implement and interact with the API
-------------------------------------------
-
-To use Telemetry in your tool, you need to provide a concrete implementation of the ``Manager`` class and ``Destination``.
-
-1) Define a custom ``Serializer``, ``Manager``, ``Destination`` and optionally a subclass of ``TelemetryInfo``
-
-.. code-block:: c++
-
- class JsonSerializer : public Serializer {
- public:
- json::Object *getOutputObject() { return Out.get(); }
-
- Error init() override {
- if (Started)
- return createStringError("Serializer already in use");
- started = true;
- Out = std::make_unique<json::Object>();
- return Error::success();
- }
-
- // Serialize the given value.
- void write(StringRef KeyName, bool Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, int Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, long Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, long long Value ) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, unsigned int Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, unsigned long Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, unsigned long long Value) override {
- writeHelper(KeyName, Value);
- }
-
- void write(StringRef KeyName, StringRef Value) override {
- writeHelper(KeyName, Value);
- }
-
- void beginObject(StringRef KeyName) override {
- Children.push_back(json::Object());
- ChildrenNames.push_back(KeyName.str());
- }
-
- void endObject() override {
- assert(!Children.empty() && !ChildrenNames.empty());
- json::Value Val = json::Value(std::move(Children.back()));
- std::string Name = ChildrenNames.back();
-
- Children.pop_back();
- ChildrenNames.pop_back();
- writeHelper(Name, std::move(Val));
- }
-
- Error finalize() override {
- if (!Started)
- return createStringError("Serializer not currently in use");
- Started = false;
- return Error::success();
- }
-
- private:
- template <typename T> void writeHelper(StringRef Name, T Value) {
- assert(Started && "serializer not started");
- if (Children.empty())
- Out->try_emplace(Name, Value);
- else
- Children.back().try_emplace(Name, Value);
- }
- bool Started = false;
- std::unique_ptr<json::Object> Out;
- std::vector<json::Object> Children;
- std::vector<std::string> ChildrenNames;
- };
-
- class MyManager : public telemetry::Manager {
- public:
- static std::unique_ptr<MyManager> createInstance(telemetry::Config *Config) {
- // If Telemetry is not enabled, then just return null;
- if (!Config->EnableTelemetry)
- return nullptr;
- return std::make_unique<MyManager>();
- }
- MyManager() = default;
+- `llvm::telemetry::Config`: Configurations for the `Manager`.
+
+```{image} llvm_telemetry_design.png
+```
+
+### How to implement and interact with the API
+
+To use Telemetry in your tool, you need to provide a concrete implementation of the `Manager` class and `Destination`.
+
+1. Define a custom `Serializer`, `Manager`, `Destination` and optionally a subclass of `TelemetryInfo`
- Error preDispatch(TelemetryInfo *Entry) override {
- Entry->SessionId = SessionId;
+```c++
+class JsonSerializer : public Serializer {
+public:
+ json::Object *getOutputObject() { return Out.get(); }
+
+ Error init() override {
+ if (Started)
+ return createStringError("Serializer already in use");
+ started = true;
+ Out = std::make_unique<json::Object>();
return Error::success();
}
- // You can also define additional instrumentation points.
- void logStartup(TelemetryInfo *Entry) {
- // Add some additional data to entry.
- Entry->Msg = "Some message";
- dispatch(Entry);
+ // Serialize the given value.
+ void write(StringRef KeyName, bool Value) override {
+ writeHelper(KeyName, Value);
}
- void logAdditionalPoint(TelemetryInfo *Entry) {
- // .... code here
+ void write(StringRef KeyName, int Value) override {
+ writeHelper(KeyName, Value);
}
- private:
- const std::string SessionId;
- };
+ void write(StringRef KeyName, long Value) override {
+ writeHelper(KeyName, Value);
+ }
- class MyDestination : public telemetry::Destination {
- public:
- Error receiveEntry(const TelemetryInfo *Entry) override {
- if (Error Err = Serializer.init())
- return Err;
+ void write(StringRef KeyName, long long Value ) override {
+ writeHelper(KeyName, Value);
+ }
- Entry->serialize(Serializer);
- if (Error Err = Serializer.finalize())
- return Err;
+ void write(StringRef KeyName, unsigned int Value) override {
+ writeHelper(KeyName, Value);
+ }
- json::Object Copied = *Serializer.getOutputObject();
- // Send the `Copied` object to wherever.
- return Error::success();
- }
+ void write(StringRef KeyName, unsigned long Value) override {
+ writeHelper(KeyName, Value);
+ }
- private:
- JsonSerializer Serializer;
- };
+ void write(StringRef KeyName, unsigned long long Value) override {
+ writeHelper(KeyName, Value);
+ }
- // This defines a custom TelemetryInfo that has an additional Msg field.
- struct MyTelemetryInfo : public telemetry::TelemetryInfo {
- std::string Msg;
+ void write(StringRef KeyName, StringRef Value) override {
+ writeHelper(KeyName, Value);
+ }
- Error serialize(Serializer &Serializer) const override {
- TelemetryInfo::serialize(serializer);
- Serializer.writeString("MyMsg", Msg);
- }
+ void beginObject(StringRef KeyName) override {
+ Children.push_back(json::Object());
+ ChildrenNames.push_back(KeyName.str());
+ }
- // Note: implement getKind() and classof() to support dyn_cast operations.
- };
+ void endObject() override {
+ assert(!Children.empty() && !ChildrenNames.empty());
+ json::Value Val = json::Value(std::move(Children.back()));
+ std::string Name = ChildrenNames.back();
+ Children.pop_back();
+ ChildrenNames.pop_back();
+ writeHelper(Name, std::move(Val));
+ }
-2) Use the library in your tool.
+ Error finalize() override {
+ if (!Started)
+ return createStringError("Serializer not currently in use");
+ Started = false;
+ return Error::success();
+ }
-Logging the tool init-process:
+private:
+ template <typename T> void writeHelper(StringRef Name, T Value) {
+ assert(Started && "serializer not started");
+ if (Children.empty())
+ Out->try_emplace(Name, Value);
+ else
+ Children.back().try_emplace(Name, Value);
+ }
+ bool Started = false;
+ std::unique_ptr<json::Object> Out;
+ std::vector<json::Object> Children;
+ std::vector<std::string> ChildrenNames;
+};
+
+class MyManager : public telemetry::Manager {
+public:
+static std::unique_ptr<MyManager> createInstance(telemetry::Config *Config) {
+ // If Telemetry is not enabled, then just return null;
+ if (!Config->EnableTelemetry)
+ return nullptr;
+ return std::make_unique<MyManager>();
+}
+MyManager() = default;
+
+Error preDispatch(TelemetryInfo *Entry) override {
+ Entry->SessionId = SessionId;
+ return Error::success();
+}
+
+// You can also define additional instrumentation points.
+void logStartup(TelemetryInfo *Entry) {
+ // Add some additional data to entry.
+ Entry->Msg = "Some message";
+ dispatch(Entry);
+}
+
+void logAdditionalPoint(TelemetryInfo *Entry) {
+ // .... code here
+}
+
+private:
+ const std::string SessionId;
+};
+
+class MyDestination : public telemetry::Destination {
+public:
+ Error receiveEntry(const TelemetryInfo *Entry) override {
+ if (Error Err = Serializer.init())
+ return Err;
+
+ Entry->serialize(Serializer);
+ if (Error Err = Serializer.finalize())
+ return Err;
+
+ json::Object Copied = *Serializer.getOutputObject();
+ // Send the `Copied` object to wherever.
+ return Error::success();
+ }
-.. code-block:: c++
+private:
+ JsonSerializer Serializer;
+};
- // In tool's initialization code.
- auto StartTime = std::chrono::time_point<std::chrono::steady_clock>::now();
- telemetry::Config MyConfig = makeConfig(); // Build up the appropriate Config struct here.
- auto Manager = MyManager::createInstance(&MyConfig);
+// This defines a custom TelemetryInfo that has an additional Msg field.
+struct MyTelemetryInfo : public telemetry::TelemetryInfo {
+ std::string Msg;
+ Error serialize(Serializer &Serializer) const override {
+ TelemetryInfo::serialize(serializer);
+ Serializer.writeString("MyMsg", Msg);
+ }
- // Any other tool's init code can go here.
- // ...
+ // Note: implement getKind() and classof() to support dyn_cast operations.
+};
+```
- // Finally, take a snapshot of the time now so we know how long it took the
- // init process to finish.
- auto EndTime = std::chrono::time_point<std::chrono::steady_clock>::now();
- MyTelemetryInfo Entry;
+2. Use the library in your tool.
- Entry.Start = StartTime;
- Entry.End = EndTime;
- Manager->logStartup(&Entry);
+Logging the tool init-process:
+
+```c++
+// In tool's initialization code.
+auto StartTime = std::chrono::time_point<std::chrono::steady_clock>::now();
+telemetry::Config MyConfig = makeConfig(); // Build up the appropriate Config struct here.
+auto Manager = MyManager::createInstance(&MyConfig);
+
+
+// Any other tool's init code can go here.
+// ...
+
+// Finally, take a snapshot of the time now so we know how long it took the
+// init process to finish.
+auto EndTime = std::chrono::time_point<std::chrono::steady_clock>::now();
+MyTelemetryInfo Entry;
+
+Entry.Start = StartTime;
+Entry.End = EndTime;
+Manager->logStartup(&Entry);
+```
Similar code can be used for logging the tool's exit.
+
diff --git a/llvm/docs/yaml2obj.md b/llvm/docs/yaml2obj.md
index f58fdd4f398ea..cc2f6fae1a5a5 100644
--- a/llvm/docs/yaml2obj.md
+++ b/llvm/docs/yaml2obj.md
@@ -1,276 +1,277 @@
-yaml2obj
-========
+# yaml2obj
yaml2obj takes a YAML description of an object file and converts it to a binary
file.
- $ yaml2obj input-file
+> \$ yaml2obj input-file
+```{eval-rst}
.. program:: yaml2obj
+```
Outputs the binary to stdout.
-COFF Syntax
------------
+## COFF Syntax
Here's a sample COFF file.
-.. code-block:: yaml
+```yaml
+header:
+ Machine: IMAGE_FILE_MACHINE_I386 # (0x14C)
- header:
- Machine: IMAGE_FILE_MACHINE_I386 # (0x14C)
+sections:
+ - Name: .text
+ Characteristics: [ IMAGE_SCN_CNT_CODE
+ , IMAGE_SCN_ALIGN_16BYTES
+ , IMAGE_SCN_MEM_EXECUTE
+ , IMAGE_SCN_MEM_READ
+ ] # 0x60500020
+ SectionData:
+ "\x83\xEC\x0C\xC7\x44\x24\x08\x00\x00\x00\x00\xC7\x04\x24\x00\x00\x00\x00\xE8\x00\x00\x00\x00\xE8\x00\x00\x00\x00\x8B\x44\x24\x08\x83\xC4\x0C\xC3" # |....D$.......$...............D$.....|
+ - Name: .rdata
+ Characteristics: [ IMAGE_SCN_CNT_INITIALIZED_DATA, IMAGE_SCN_MEM_READ ]
+ StructuredData:
+ - Binary: {type: str}
+ - UInt32: {type: int}
+ - LoadConfig:
+ Size: {type: int}
+ TimeDateStamp: {type: int}
+ MajorVersion: {type: int}
+ MinorVersion: {type: int}
+ GlobalFlagsClear: {type: int}
+ GlobalFlagsSet: {type: int}
+ CriticalSectionDefaultTimeout: {type: int}
+ DeCommitFreeBlockThreshold: {type: int}
+ DeCommitTotalFreeThreshold: {type: int}
+ LockPrefixTable: {type: int}
+ MaximumAllocationSize: {type: int}
+ VirtualMemoryThreshold: {type: int}
+ ProcessAffinityMask: {type: int}
+ ProcessHeapFlags: {type: int}
+ CSDVersion: {type: int}
+ DependentLoadFlags: {type: int}
+ EditList: {type: int}
+ SecurityCookie: {type: int}
+ SEHandlerTable: {type: int}
+ SEHandlerCount: {type: int}
+ GuardCFCheckFunction: {type: int}
+ GuardCFCheckDispatch: {type: int}
+ GuardCFFunctionTable: {type: int}
+ GuardCFFunctionCount: {type: int}
+ GuardFlags: {type: int}
+ CodeIntegrity:
+ Flags: {type: int}
+ Catalog: {type: int}
+ CatalogOffset: {type: int}
+ GuardAddressTakenIatEntryTable: {type: int}
+ GuardAddressTakenIatEntryCount: {type: int}
+ GuardLongJumpTargetTable: {type: int}
+ GuardLongJumpTargetCount: {type: int}
+ DynamicValueRelocTable: {type: int}
+ CHPEMetadataPointer: {type: int}
+ GuardRFFailureRoutine: {type: int}
+ GuardRFFailureRoutineFunctionPointer: {type: int}
+ DynamicValueRelocTableOffset: {type: int}
+ DynamicValueRelocTableSection: {type: int}
+ GuardRFVerifyStackPointerFunctionPointer: {type: int}
+ HotPatchTableOffset: {type: int}
+ EnclaveConfigurationPointer: {type: int}
+ VolatileMetadataPointer: {type: int}
+ GuardEHContinuationTable: {type: int}
+ GuardEHContinuationCount: {type: int}
+ GuardXFGCheckFunctionPointer: {type: int}
+ GuardXFGDispatchFunctionPointer: {type: int}
+ GuardXFGTableDispatchFunctionPointer: {type: int}
+ CastGuardOsDeterminedFailureMode: {type: int}
- sections:
- - Name: .text
- Characteristics: [ IMAGE_SCN_CNT_CODE
- , IMAGE_SCN_ALIGN_16BYTES
- , IMAGE_SCN_MEM_EXECUTE
- , IMAGE_SCN_MEM_READ
- ] # 0x60500020
- SectionData:
- "\x83\xEC\x0C\xC7\x44\x24\x08\x00\x00\x00\x00\xC7\x04\x24\x00\x00\x00\x00\xE8\x00\x00\x00\x00\xE8\x00\x00\x00\x00\x8B\x44\x24\x08\x83\xC4\x0C\xC3" # |....D$.......$...............D$.....|
- - Name: .rdata
- Characteristics: [ IMAGE_SCN_CNT_INITIALIZED_DATA, IMAGE_SCN_MEM_READ ]
- StructuredData:
- - Binary: {type: str}
- - UInt32: {type: int}
- - LoadConfig:
- Size: {type: int}
- TimeDateStamp: {type: int}
- MajorVersion: {type: int}
- MinorVersion: {type: int}
- GlobalFlagsClear: {type: int}
- GlobalFlagsSet: {type: int}
- CriticalSectionDefaultTimeout: {type: int}
- DeCommitFreeBlockThreshold: {type: int}
- DeCommitTotalFreeThreshold: {type: int}
- LockPrefixTable: {type: int}
- MaximumAllocationSize: {type: int}
- VirtualMemoryThreshold: {type: int}
- ProcessAffinityMask: {type: int}
- ProcessHeapFlags: {type: int}
- CSDVersion: {type: int}
- DependentLoadFlags: {type: int}
- EditList: {type: int}
- SecurityCookie: {type: int}
- SEHandlerTable: {type: int}
- SEHandlerCount: {type: int}
- GuardCFCheckFunction: {type: int}
- GuardCFCheckDispatch: {type: int}
- GuardCFFunctionTable: {type: int}
- GuardCFFunctionCount: {type: int}
- GuardFlags: {type: int}
- CodeIntegrity:
- Flags: {type: int}
- Catalog: {type: int}
- CatalogOffset: {type: int}
- GuardAddressTakenIatEntryTable: {type: int}
- GuardAddressTakenIatEntryCount: {type: int}
- GuardLongJumpTargetTable: {type: int}
- GuardLongJumpTargetCount: {type: int}
- DynamicValueRelocTable: {type: int}
- CHPEMetadataPointer: {type: int}
- GuardRFFailureRoutine: {type: int}
- GuardRFFailureRoutineFunctionPointer: {type: int}
- DynamicValueRelocTableOffset: {type: int}
- DynamicValueRelocTableSection: {type: int}
- GuardRFVerifyStackPointerFunctionPointer: {type: int}
- HotPatchTableOffset: {type: int}
- EnclaveConfigurationPointer: {type: int}
- VolatileMetadataPointer: {type: int}
- GuardEHContinuationTable: {type: int}
- GuardEHContinuationCount: {type: int}
- GuardXFGCheckFunctionPointer: {type: int}
- GuardXFGDispatchFunctionPointer: {type: int}
- GuardXFGTableDispatchFunctionPointer: {type: int}
- CastGuardOsDeterminedFailureMode: {type: int}
+symbols:
+ - Name: .text
+ Value: 0
+ SectionNumber: 1
+ SimpleType: IMAGE_SYM_TYPE_NULL # (0)
+ ComplexType: IMAGE_SYM_DTYPE_NULL # (0)
+ StorageClass: IMAGE_SYM_CLASS_STATIC # (3)
+ NumberOfAuxSymbols: 1
+ AuxiliaryData:
+ "\x24\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00" # |$.................|
- symbols:
- - Name: .text
- Value: 0
- SectionNumber: 1
- SimpleType: IMAGE_SYM_TYPE_NULL # (0)
- ComplexType: IMAGE_SYM_DTYPE_NULL # (0)
- StorageClass: IMAGE_SYM_CLASS_STATIC # (3)
- NumberOfAuxSymbols: 1
- AuxiliaryData:
- "\x24\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00" # |$.................|
+ - Name: _main
+ Value: 0
+ SectionNumber: 1
+ SimpleType: IMAGE_SYM_TYPE_NULL # (0)
+ ComplexType: IMAGE_SYM_DTYPE_NULL # (0)
+ StorageClass: IMAGE_SYM_CLASS_EXTERNAL # (2)
+```
- - Name: _main
- Value: 0
- SectionNumber: 1
- SimpleType: IMAGE_SYM_TYPE_NULL # (0)
- ComplexType: IMAGE_SYM_DTYPE_NULL # (0)
- StorageClass: IMAGE_SYM_CLASS_EXTERNAL # (2)
+Here's a simplified [Kwalify][kwalify] schema with an extension to allow alternate types.
-Here's a simplified Kwalify_ schema with an extension to allow alternate types.
-
-.. _Kwalify: http://www.kuwata-lab.com/kwalify/ruby/users-guide.html
-
-.. code-block:: yaml
-
- type: map
- mapping:
- header:
- type: map
- mapping:
- Machine: [ {type: str, enum:
- [ IMAGE_FILE_MACHINE_UNKNOWN
- , IMAGE_FILE_MACHINE_AM33
- , IMAGE_FILE_MACHINE_AMD64
- , IMAGE_FILE_MACHINE_ARM
- , IMAGE_FILE_MACHINE_ARMNT
- , IMAGE_FILE_MACHINE_ARM64
- , IMAGE_FILE_MACHINE_EBC
- , IMAGE_FILE_MACHINE_I386
- , IMAGE_FILE_MACHINE_IA64
- , IMAGE_FILE_MACHINE_M32R
- , IMAGE_FILE_MACHINE_MIPS16
- , IMAGE_FILE_MACHINE_MIPSFPU
- , IMAGE_FILE_MACHINE_MIPSFPU16
- , IMAGE_FILE_MACHINE_POWERPC
- , IMAGE_FILE_MACHINE_POWERPCFP
- , IMAGE_FILE_MACHINE_R4000
- , IMAGE_FILE_MACHINE_SH3
- , IMAGE_FILE_MACHINE_SH3DSP
- , IMAGE_FILE_MACHINE_SH4
- , IMAGE_FILE_MACHINE_SH5
- , IMAGE_FILE_MACHINE_THUMB
- , IMAGE_FILE_MACHINE_WCEMIPSV2
- ]}
- , {type: int}
- ]
- Characteristics:
- - type: seq
- sequence:
- - type: str
- enum: [ IMAGE_FILE_RELOCS_STRIPPED
- , IMAGE_FILE_EXECUTABLE_IMAGE
- , IMAGE_FILE_LINE_NUMS_STRIPPED
- , IMAGE_FILE_LOCAL_SYMS_STRIPPED
- , IMAGE_FILE_AGGRESSIVE_WS_TRIM
- , IMAGE_FILE_LARGE_ADDRESS_AWARE
- , IMAGE_FILE_BYTES_REVERSED_LO
- , IMAGE_FILE_32BIT_MACHINE
- , IMAGE_FILE_DEBUG_STRIPPED
- , IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP
- , IMAGE_FILE_NET_RUN_FROM_SWAP
- , IMAGE_FILE_SYSTEM
- , IMAGE_FILE_DLL
- , IMAGE_FILE_UP_SYSTEM_ONLY
- , IMAGE_FILE_BYTES_REVERSED_HI
+```yaml
+type: map
+ mapping:
+ header:
+ type: map
+ mapping:
+ Machine: [ {type: str, enum:
+ [ IMAGE_FILE_MACHINE_UNKNOWN
+ , IMAGE_FILE_MACHINE_AM33
+ , IMAGE_FILE_MACHINE_AMD64
+ , IMAGE_FILE_MACHINE_ARM
+ , IMAGE_FILE_MACHINE_ARMNT
+ , IMAGE_FILE_MACHINE_ARM64
+ , IMAGE_FILE_MACHINE_EBC
+ , IMAGE_FILE_MACHINE_I386
+ , IMAGE_FILE_MACHINE_IA64
+ , IMAGE_FILE_MACHINE_M32R
+ , IMAGE_FILE_MACHINE_MIPS16
+ , IMAGE_FILE_MACHINE_MIPSFPU
+ , IMAGE_FILE_MACHINE_MIPSFPU16
+ , IMAGE_FILE_MACHINE_POWERPC
+ , IMAGE_FILE_MACHINE_POWERPCFP
+ , IMAGE_FILE_MACHINE_R4000
+ , IMAGE_FILE_MACHINE_SH3
+ , IMAGE_FILE_MACHINE_SH3DSP
+ , IMAGE_FILE_MACHINE_SH4
+ , IMAGE_FILE_MACHINE_SH5
+ , IMAGE_FILE_MACHINE_THUMB
+ , IMAGE_FILE_MACHINE_WCEMIPSV2
+ ]}
+ , {type: int}
+ ]
+ Characteristics:
+ - type: seq
+ sequence:
+ - type: str
+ enum: [ IMAGE_FILE_RELOCS_STRIPPED
+ , IMAGE_FILE_EXECUTABLE_IMAGE
+ , IMAGE_FILE_LINE_NUMS_STRIPPED
+ , IMAGE_FILE_LOCAL_SYMS_STRIPPED
+ , IMAGE_FILE_AGGRESSIVE_WS_TRIM
+ , IMAGE_FILE_LARGE_ADDRESS_AWARE
+ , IMAGE_FILE_BYTES_REVERSED_LO
+ , IMAGE_FILE_32BIT_MACHINE
+ , IMAGE_FILE_DEBUG_STRIPPED
+ , IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP
+ , IMAGE_FILE_NET_RUN_FROM_SWAP
+ , IMAGE_FILE_SYSTEM
+ , IMAGE_FILE_DLL
+ , IMAGE_FILE_UP_SYSTEM_ONLY
+ , IMAGE_FILE_BYTES_REVERSED_HI
+ ]
+ - type: int
+ sections:
+ type: seq
+ sequence:
+ - type: map
+ mapping:
+ Name: {type: str}
+ Characteristics:
+ - type: seq
+ sequence:
+ - type: str
+ enum: [ IMAGE_SCN_TYPE_NO_PAD
+ , IMAGE_SCN_CNT_CODE
+ , IMAGE_SCN_CNT_INITIALIZED_DATA
+ , IMAGE_SCN_CNT_UNINITIALIZED_DATA
+ , IMAGE_SCN_LNK_OTHER
+ , IMAGE_SCN_LNK_INFO
+ , IMAGE_SCN_LNK_REMOVE
+ , IMAGE_SCN_LNK_COMDAT
+ , IMAGE_SCN_GPREL
+ , IMAGE_SCN_MEM_PURGEABLE
+ , IMAGE_SCN_MEM_16BIT
+ , IMAGE_SCN_MEM_LOCKED
+ , IMAGE_SCN_MEM_PRELOAD
+ , IMAGE_SCN_ALIGN_1BYTES
+ , IMAGE_SCN_ALIGN_2BYTES
+ , IMAGE_SCN_ALIGN_4BYTES
+ , IMAGE_SCN_ALIGN_8BYTES
+ , IMAGE_SCN_ALIGN_16BYTES
+ , IMAGE_SCN_ALIGN_32BYTES
+ , IMAGE_SCN_ALIGN_64BYTES
+ , IMAGE_SCN_ALIGN_128BYTES
+ , IMAGE_SCN_ALIGN_256BYTES
+ , IMAGE_SCN_ALIGN_512BYTES
+ , IMAGE_SCN_ALIGN_1024BYTES
+ , IMAGE_SCN_ALIGN_2048BYTES
+ , IMAGE_SCN_ALIGN_4096BYTES
+ , IMAGE_SCN_ALIGN_8192BYTES
+ , IMAGE_SCN_LNK_NRELOC_OVFL
+ , IMAGE_SCN_MEM_DISCARDABLE
+ , IMAGE_SCN_MEM_NOT_CACHED
+ , IMAGE_SCN_MEM_NOT_PAGED
+ , IMAGE_SCN_MEM_SHARED
+ , IMAGE_SCN_MEM_EXECUTE
+ , IMAGE_SCN_MEM_READ
+ , IMAGE_SCN_MEM_WRITE
+ ]
+ - type: int
+ SectionData: {type: str}
+ symbols:
+ type: seq
+ sequence:
+ - type: map
+ mapping:
+ Name: {type: str}
+ Value: {type: int}
+ SectionNumber: {type: int}
+ SimpleType: [ {type: str, enum: [ IMAGE_SYM_TYPE_NULL
+ , IMAGE_SYM_TYPE_VOID
+ , IMAGE_SYM_TYPE_CHAR
+ , IMAGE_SYM_TYPE_SHORT
+ , IMAGE_SYM_TYPE_INT
+ , IMAGE_SYM_TYPE_LONG
+ , IMAGE_SYM_TYPE_FLOAT
+ , IMAGE_SYM_TYPE_DOUBLE
+ , IMAGE_SYM_TYPE_STRUCT
+ , IMAGE_SYM_TYPE_UNION
+ , IMAGE_SYM_TYPE_ENUM
+ , IMAGE_SYM_TYPE_MOE
+ , IMAGE_SYM_TYPE_BYTE
+ , IMAGE_SYM_TYPE_WORD
+ , IMAGE_SYM_TYPE_UINT
+ , IMAGE_SYM_TYPE_DWORD
+ ]}
+ , {type: int}
]
- - type: int
- sections:
- type: seq
- sequence:
- - type: map
- mapping:
- Name: {type: str}
- Characteristics:
- - type: seq
- sequence:
- - type: str
- enum: [ IMAGE_SCN_TYPE_NO_PAD
- , IMAGE_SCN_CNT_CODE
- , IMAGE_SCN_CNT_INITIALIZED_DATA
- , IMAGE_SCN_CNT_UNINITIALIZED_DATA
- , IMAGE_SCN_LNK_OTHER
- , IMAGE_SCN_LNK_INFO
- , IMAGE_SCN_LNK_REMOVE
- , IMAGE_SCN_LNK_COMDAT
- , IMAGE_SCN_GPREL
- , IMAGE_SCN_MEM_PURGEABLE
- , IMAGE_SCN_MEM_16BIT
- , IMAGE_SCN_MEM_LOCKED
- , IMAGE_SCN_MEM_PRELOAD
- , IMAGE_SCN_ALIGN_1BYTES
- , IMAGE_SCN_ALIGN_2BYTES
- , IMAGE_SCN_ALIGN_4BYTES
- , IMAGE_SCN_ALIGN_8BYTES
- , IMAGE_SCN_ALIGN_16BYTES
- , IMAGE_SCN_ALIGN_32BYTES
- , IMAGE_SCN_ALIGN_64BYTES
- , IMAGE_SCN_ALIGN_128BYTES
- , IMAGE_SCN_ALIGN_256BYTES
- , IMAGE_SCN_ALIGN_512BYTES
- , IMAGE_SCN_ALIGN_1024BYTES
- , IMAGE_SCN_ALIGN_2048BYTES
- , IMAGE_SCN_ALIGN_4096BYTES
- , IMAGE_SCN_ALIGN_8192BYTES
- , IMAGE_SCN_LNK_NRELOC_OVFL
- , IMAGE_SCN_MEM_DISCARDABLE
- , IMAGE_SCN_MEM_NOT_CACHED
- , IMAGE_SCN_MEM_NOT_PAGED
- , IMAGE_SCN_MEM_SHARED
- , IMAGE_SCN_MEM_EXECUTE
- , IMAGE_SCN_MEM_READ
- , IMAGE_SCN_MEM_WRITE
- ]
- - type: int
- SectionData: {type: str}
- symbols:
- type: seq
- sequence:
- - type: map
- mapping:
- Name: {type: str}
- Value: {type: int}
- SectionNumber: {type: int}
- SimpleType: [ {type: str, enum: [ IMAGE_SYM_TYPE_NULL
- , IMAGE_SYM_TYPE_VOID
- , IMAGE_SYM_TYPE_CHAR
- , IMAGE_SYM_TYPE_SHORT
- , IMAGE_SYM_TYPE_INT
- , IMAGE_SYM_TYPE_LONG
- , IMAGE_SYM_TYPE_FLOAT
- , IMAGE_SYM_TYPE_DOUBLE
- , IMAGE_SYM_TYPE_STRUCT
- , IMAGE_SYM_TYPE_UNION
- , IMAGE_SYM_TYPE_ENUM
- , IMAGE_SYM_TYPE_MOE
- , IMAGE_SYM_TYPE_BYTE
- , IMAGE_SYM_TYPE_WORD
- , IMAGE_SYM_TYPE_UINT
- , IMAGE_SYM_TYPE_DWORD
- ]}
+ ComplexType: [ {type: str, enum: [ IMAGE_SYM_DTYPE_NULL
+ , IMAGE_SYM_DTYPE_POINTER
+ , IMAGE_SYM_DTYPE_FUNCTION
+ , IMAGE_SYM_DTYPE_ARRAY
+ ]}
+ , {type: int}
+ ]
+ StorageClass: [ {type: str, enum:
+ [ IMAGE_SYM_CLASS_END_OF_FUNCTION
+ , IMAGE_SYM_CLASS_NULL
+ , IMAGE_SYM_CLASS_AUTOMATIC
+ , IMAGE_SYM_CLASS_EXTERNAL
+ , IMAGE_SYM_CLASS_STATIC
+ , IMAGE_SYM_CLASS_REGISTER
+ , IMAGE_SYM_CLASS_EXTERNAL_DEF
+ , IMAGE_SYM_CLASS_LABEL
+ , IMAGE_SYM_CLASS_UNDEFINED_LABEL
+ , IMAGE_SYM_CLASS_MEMBER_OF_STRUCT
+ , IMAGE_SYM_CLASS_ARGUMENT
+ , IMAGE_SYM_CLASS_STRUCT_TAG
+ , IMAGE_SYM_CLASS_MEMBER_OF_UNION
+ , IMAGE_SYM_CLASS_UNION_TAG
+ , IMAGE_SYM_CLASS_TYPE_DEFINITION
+ , IMAGE_SYM_CLASS_UNDEFINED_STATIC
+ , IMAGE_SYM_CLASS_ENUM_TAG
+ , IMAGE_SYM_CLASS_MEMBER_OF_ENUM
+ , IMAGE_SYM_CLASS_REGISTER_PARAM
+ , IMAGE_SYM_CLASS_BIT_FIELD
+ , IMAGE_SYM_CLASS_BLOCK
+ , IMAGE_SYM_CLASS_FUNCTION
+ , IMAGE_SYM_CLASS_END_OF_STRUCT
+ , IMAGE_SYM_CLASS_FILE
+ , IMAGE_SYM_CLASS_SECTION
+ , IMAGE_SYM_CLASS_WEAK_EXTERNAL
+ , IMAGE_SYM_CLASS_CLR_TOKEN
+ ]}
, {type: int}
]
- ComplexType: [ {type: str, enum: [ IMAGE_SYM_DTYPE_NULL
- , IMAGE_SYM_DTYPE_POINTER
- , IMAGE_SYM_DTYPE_FUNCTION
- , IMAGE_SYM_DTYPE_ARRAY
- ]}
- , {type: int}
- ]
- StorageClass: [ {type: str, enum:
- [ IMAGE_SYM_CLASS_END_OF_FUNCTION
- , IMAGE_SYM_CLASS_NULL
- , IMAGE_SYM_CLASS_AUTOMATIC
- , IMAGE_SYM_CLASS_EXTERNAL
- , IMAGE_SYM_CLASS_STATIC
- , IMAGE_SYM_CLASS_REGISTER
- , IMAGE_SYM_CLASS_EXTERNAL_DEF
- , IMAGE_SYM_CLASS_LABEL
- , IMAGE_SYM_CLASS_UNDEFINED_LABEL
- , IMAGE_SYM_CLASS_MEMBER_OF_STRUCT
- , IMAGE_SYM_CLASS_ARGUMENT
- , IMAGE_SYM_CLASS_STRUCT_TAG
- , IMAGE_SYM_CLASS_MEMBER_OF_UNION
- , IMAGE_SYM_CLASS_UNION_TAG
- , IMAGE_SYM_CLASS_TYPE_DEFINITION
- , IMAGE_SYM_CLASS_UNDEFINED_STATIC
- , IMAGE_SYM_CLASS_ENUM_TAG
- , IMAGE_SYM_CLASS_MEMBER_OF_ENUM
- , IMAGE_SYM_CLASS_REGISTER_PARAM
- , IMAGE_SYM_CLASS_BIT_FIELD
- , IMAGE_SYM_CLASS_BLOCK
- , IMAGE_SYM_CLASS_FUNCTION
- , IMAGE_SYM_CLASS_END_OF_STRUCT
- , IMAGE_SYM_CLASS_FILE
- , IMAGE_SYM_CLASS_SECTION
- , IMAGE_SYM_CLASS_WEAK_EXTERNAL
- , IMAGE_SYM_CLASS_CLR_TOKEN
- ]}
- , {type: int}
- ]
+```
+
+[kwalify]: http://www.kuwata-lab.com/kwalify/ruby/users-guide.html
+
>From b4c01310789a4cf7c8bcf9dff316f0cf67281254 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Fri, 7 Aug 2026 02:18:07 +0000
Subject: [PATCH 2/3] [docs] Finish MyST migration for selected docs
---
llvm/docs/CMakePrimer.md | 5 +-
llvm/docs/CodeOfConduct.md | 13 +-
llvm/docs/DirectXUsage.md | 45 +-
llvm/docs/FatLTO.md | 5 -
llvm/docs/LFI.md | 734 +++++++++++++-----------
llvm/docs/MisExpect.md | 5 -
llvm/docs/PDB/index.md | 124 ++--
llvm/docs/RISCV/RISCVVectorExtension.md | 29 +-
llvm/docs/RISCVUsage.md | 394 +++++++------
llvm/docs/SymbolizerMarkupFormat.md | 412 +++++++------
llvm/docs/Telemetry.md | 7 +-
llvm/docs/yaml2obj.md | 7 +-
12 files changed, 917 insertions(+), 863 deletions(-)
diff --git a/llvm/docs/CMakePrimer.md b/llvm/docs/CMakePrimer.md
index 1dd95b0bd2296..6f954967441c5 100644
--- a/llvm/docs/CMakePrimer.md
+++ b/llvm/docs/CMakePrimer.md
@@ -1,7 +1,7 @@
# CMake Primer
:::{warning}
-Disclaimer: This documentation is written by LLVM project contributors `not`
+Disclaimer: This documentation is written by LLVM project contributors *not*
anyone affiliated with the CMake project. This document may contain
inaccurate terminology, phrasing, or technical details. It is provided with
the best intentions.
@@ -35,7 +35,7 @@ discussed later.
## Scripting Overview
CMake's scripting language has a very simple grammar. Every language construct
-is a command that matches the pattern \_name\_(\_args\_). Commands come in three
+is a command that matches the pattern `_name_(_args_)`. Commands come in three
primary types: language-defined (commands implemented in C++ in CMake), defined
functions, and defined macros. The CMake distribution also contains a suite of
CMake modules that contain definitions for useful functionality.
@@ -414,4 +414,3 @@ documentation. To highlight a few useful functions see:
The full documentation for CMake commands is in the `cmake-commands` manpage
and available on [CMake's website](https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html)
-
diff --git a/llvm/docs/CodeOfConduct.md b/llvm/docs/CodeOfConduct.md
index 4f380b603018a..9dab7304be11c 100644
--- a/llvm/docs/CodeOfConduct.md
+++ b/llvm/docs/CodeOfConduct.md
@@ -9,12 +9,12 @@ The LLVM community has always worked to be a welcoming and respectful
community, and we want to ensure that doesn't change as we grow and evolve. To
that end, we have a few ground rules that we ask people to adhere to:
-- [be friendly and patient],
-- [be welcoming],
-- [be considerate],
-- [be respectful],
-- [be careful in the words that you choose and be kind to others], and
-- [when we disagree, try to understand why].
+- [be friendly and patient](#be-friendly-and-patient),
+- [be welcoming](#be-welcoming),
+- [be considerate](#be-considerate),
+- [be respectful](#be-respectful),
+- [be careful in the words that you choose and be kind to others](#be-careful-in-the-words-that-you-choose-and-be-kind-to-others), and
+- [when we disagree, try to understand why](#when-we-disagree-try-to-understand-why).
This isn't an exhaustive list of things that you can't do. Rather, take it in
the spirit in which it's intended - a guide to make it easier to communicate
@@ -192,4 +192,3 @@ Unported License][creative commons attribution 3.0 unported license].
[hate speech]: https://www.un.org/en/genocideprevention/documents/UN%20Strategy%20and%20Plan%20of%20Action%20on%20Hate%20Speech%2018%20June%20SYNOPSIS.pdf
[sexual and gender-based violence]: https://hr.un.org/sites/hr.un.org/files/SEA%20Glossary%20%20%5BSecond%20Edition%20-%202017%5D%20-%20English_0.pdf
[speak up! project]: http://speakup.io/coc.html
-
diff --git a/llvm/docs/DirectXUsage.md b/llvm/docs/DirectXUsage.md
index dca6588f88a67..73c823b55cf04 100644
--- a/llvm/docs/DirectXUsage.md
+++ b/llvm/docs/DirectXUsage.md
@@ -7,7 +7,7 @@ demonstration contexts.
:::
```{toctree}
-:hidden: true
+:hidden:
DirectX/DXContainer
DirectX/DXILArchitecture
@@ -45,29 +45,25 @@ Environment triple component.
Presently, the DirectX backend requires targeting the `shadermodel` OS, and
supports versions 6.0+ (as of writing, the latest announced version is 6.7).
-```{eval-rst}
-.. table:: DirectX Environments
-
- ================== ========================================================
- Environment Description
- ================== ========================================================
- ``pixel`` Pixel shader
- ``vertex`` Vertex shader
- ``geometry`` Geometry shader
- ``hull`` Hull shader (tesselation)
- ``domain`` Domain shader (tesselation)
- ``compute`` Compute kernel
- ``library`` Linkable ``dxil`` library
- ``raygeneration`` Ray generation (ray tracing)
- ``intersection`` Ray intersection (ray tracing)
- ``anyhit`` Ray any collision (ray tracing)
- ``closesthit`` Ray closest collision (ray tracing)
- ``miss`` Ray miss (ray tracing)
- ``callable`` Callable shader (ray tracing)
- ``mesh`` Mesh shader
- ``amplification`` Amplification shader
- ================== ========================================================
-```
+:::{table} DirectX Environments
+| Environment | Description |
+| --- | --- |
+| `pixel` | Pixel shader |
+| `vertex` | Vertex shader |
+| `geometry` | Geometry shader |
+| `hull` | Hull shader (tesselation) |
+| `domain` | Domain shader (tesselation) |
+| `compute` | Compute kernel |
+| `library` | Linkable `dxil` library |
+| `raygeneration` | Ray generation (ray tracing) |
+| `intersection` | Ray intersection (ray tracing) |
+| `anyhit` | Ray any collision (ray tracing) |
+| `closesthit` | Ray closest collision (ray tracing) |
+| `miss` | Ray miss (ray tracing) |
+| `callable` | Callable shader (ray tracing) |
+| `mesh` | Mesh shader |
+| `amplification` | Amplification shader |
+:::
## Output Binaries
@@ -92,4 +88,3 @@ libraries for testing and object file tooling.
For `dxil` targeting, bitcode emission into `DXContainer` files follows a
similar model to the `-fembed-bitcode` flag supported by clang for other
targets.
-
diff --git a/llvm/docs/FatLTO.md b/llvm/docs/FatLTO.md
index 63c6348e48e30..c74ea1e4e6262 100644
--- a/llvm/docs/FatLTO.md
+++ b/llvm/docs/FatLTO.md
@@ -1,9 +1,5 @@
# FatLTO
-```{toctree}
-:maxdepth: 1
-```
-
## Introduction
FatLTO objects are a special type of [fat object file](https://en.wikipedia.org/wiki/Fat_binary) that contain LTO compatible IR in
@@ -101,4 +97,3 @@ Link using the LLVM bitcode from the fat object with Thin LTO:
```console
$ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=thin --fat-lto-objects to ld.lld
```
-
diff --git a/llvm/docs/LFI.md b/llvm/docs/LFI.md
index 4aa13babee917..4cf2ac2a03107 100644
--- a/llvm/docs/LFI.md
+++ b/llvm/docs/LFI.md
@@ -58,17 +58,11 @@ Both architectures designate a context register that points to a block of
thread-local memory managed by the LFI runtime. The context register is `x25`
on AArch64 and `r15` on X86-64. The layout is as follows:
-```{eval-rst}
-+--------+--------+----------------------------------------------+
-| Offset | Size | Description |
-+--------+--------+----------------------------------------------+
-| 0 | 8 | Reserved for future use. |
-+--------+--------+----------------------------------------------+
-| 8 | 8 | Reserved for use by the LFI runtime. |
-+--------+--------+----------------------------------------------+
-| 16 | 8 | Virtual thread pointer (used for TP access). |
-+--------+--------+----------------------------------------------+
-```
+| Offset | Size | Description |
+| --- | --- | --- |
+| 0 | 8 | Reserved for future use. |
+| 8 | 8 | Reserved for use by the LFI runtime. |
+| 16 | 8 | Virtual thread pointer (used for TP access). |
## Linker Support
@@ -133,7 +127,7 @@ that must be maintained.
- `sp`: always holds an address within the sandbox.
- `x30`: always holds an address within the sandbox.
- `x26`: scratch register.
-- `x25`: context register (see [Context Register]).
+- `x25`: context register (see [Context Register](#context-register)).
The current design only supports 4GiB sandboxes, which requires the sandbox
base address to be 4GiB-aligned. This is because LFI's ABI stores pointers as
@@ -160,22 +154,25 @@ update `x28` with the destination address. Since `ret` uses `x30` by
default, which already must contain an address within the sandbox, it does not
require any rewrite.
-```{eval-rst}
-+--------------------+---------------------------+
-| Original | Rewritten |
-+--------------------+---------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| {br,blr,ret} xN | add x28, x27, wN, uxtw |
-| | {br,blr,ret} x28 |
-| | |
-+--------------------+---------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ret | ret |
-| | |
-+--------------------+---------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ {br,blr,ret} xN
+ ```
+ - ```gas
+ add x28, x27, wN, uxtw
+ {br,blr,ret} x28
+ ```
+* - ```gas
+ ret
+ ```
+ - ```gas
+ ret
+ ```
+:::
#### Memory accesses
@@ -184,101 +181,116 @@ it is available, which is automatically safe. Otherwise, rewrites fall back to
using `x28` along with an instruction to safely load it with the target
address.
-```{eval-rst}
-+---------------------------------+-------------------------------+
-| Original | Rewritten |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM] | LDSTr xN, [x27, wM, uxtw] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM, #I] | add x28, x27, wM, uxtw |
-| | LDSTr xN, [x28, #I] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM, #I]! | add xM, xM, #I |
-| | LDSTr xN, [x27, wM, uxtw] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM], #I | LDSTr xN, [x27, wM, uxtw] |
-| | add xM, xM, #I |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM1, xM2] | add x26, xM1, xM2 |
-| | LDSTr xN, [x27, w26, uxtw] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTr xN, [xM1, xM2, MOD #I] | add x26, xM1, xM2, MOD #I |
-| | LDSTr xN, [x27, w26, uxtw] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTx ..., [xM] | add x28, x27, wM, uxtw |
-| | LDSTx ..., [x28] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTx ..., [xM, #I] | add x28, x27, wM, uxtw |
-| | LDSTx ..., [x28, #I] |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTx ..., [xM, #I]! | add x28, x27, wM, uxtw |
-| | LDSTx ..., [x28, #I] |
-| | add xM, xM, #I |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTx ..., [xM], #I | add x28, x27, wM, uxtw |
-| | LDSTx ..., [x28] |
-| | add xM, xM, #I |
-| | |
-+---------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| LDSTx ..., [xM1], xM2 | add x28, x27, wM1, uxtw |
-| | LDSTx ..., [x28] |
-| | add xM1, xM1, xM2 |
-| | |
-+---------------------------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ LDSTr xN, [xM]
+ ```
+ - ```gas
+ LDSTr xN, [x27, wM, uxtw]
+ ```
+* - ```gas
+ LDSTr xN, [xM, #I]
+ ```
+ - ```gas
+ add x28, x27, wM, uxtw
+ LDSTr xN, [x28, #I]
+ ```
+* - ```gas
+ LDSTr xN, [xM, #I]!
+ ```
+ - ```gas
+ add xM, xM, #I
+ LDSTr xN, [x27, wM, uxtw]
+ ```
+* - ```gas
+ LDSTr xN, [xM], #I
+ ```
+ - ```gas
+ LDSTr xN, [x27, wM, uxtw]
+ add xM, xM, #I
+ ```
+* - ```gas
+ LDSTr xN, [xM1, xM2]
+ ```
+ - ```gas
+ add x26, xM1, xM2
+ LDSTr xN, [x27, w26, uxtw]
+ ```
+* - ```gas
+ LDSTr xN, [xM1, xM2, MOD #I]
+ ```
+ - ```gas
+ add x26, xM1, xM2, MOD #I
+ LDSTr xN, [x27, w26, uxtw]
+ ```
+* - ```gas
+ LDSTx ..., [xM]
+ ```
+ - ```gas
+ add x28, x27, wM, uxtw
+ LDSTx ..., [x28]
+ ```
+* - ```gas
+ LDSTx ..., [xM, #I]
+ ```
+ - ```gas
+ add x28, x27, wM, uxtw
+ LDSTx ..., [x28, #I]
+ ```
+* - ```gas
+ LDSTx ..., [xM, #I]!
+ ```
+ - ```gas
+ add x28, x27, wM, uxtw
+ LDSTx ..., [x28, #I]
+ add xM, xM, #I
+ ```
+* - ```gas
+ LDSTx ..., [xM], #I
+ ```
+ - ```gas
+ add x28, x27, wM, uxtw
+ LDSTx ..., [x28]
+ add xM, xM, #I
+ ```
+* - ```gas
+ LDSTx ..., [xM1], xM2
+ ```
+ - ```gas
+ add x28, x27, wM1, uxtw
+ LDSTx ..., [x28]
+ add xM1, xM1, xM2
+ ```
+:::
#### Stack pointer modification
When the stack pointer is modified, we write the modified value to a temporary,
before moving it back into `sp` with a safe `add`.
-```{eval-rst}
-+------------------------------+-------------------------------+
-| Original | Rewritten |
-+------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| mov sp, xN | add sp, x27, wN, uxtw |
-| | |
-+------------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| {add,sub} sp, sp, {#I,xN} | {add,sub} x26, sp, {#I,xN} |
-| | add sp, x27, w26, uxtw |
-| | |
-+------------------------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ mov sp, xN
+ ```
+ - ```gas
+ add sp, x27, wN, uxtw
+ ```
+* - ```gas
+ {add,sub} sp, sp, {#I,xN}
+ ```
+ - ```gas
+ {add,sub} x26, sp, {#I,xN}
+ add sp, x27, w26, uxtw
+ ```
+:::
#### Link register modification
@@ -288,27 +300,32 @@ control-flow instruction rather than emitted immediately after the
modification. Deferral keeps a signed return address intact so that a following
authentication instruction (such as `autiasp`) can run before the guard,
which would otherwise destroy the pointer authentication signature. See
-[Pointer Authentication Code (PAC) support].
-
-```{eval-rst}
-+---------------------------+-------------------------------+
-| Original | Rewritten |
-+---------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ldr x30, [...] | ldr x30, [...] |
-| ret | add x30, x27, w30, uxtw |
-| | ret |
-| | |
-+---------------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| ldp xN, x30, [...] | ldp xN, x30, [...] |
-| ret | add x30, x27, w30, uxtw |
-| | ret |
-| | |
-+---------------------------+-------------------------------+
-```
+[Pointer Authentication Code (PAC) support](#pointer-authentication-code-pac-support).
+
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ ldr x30, [...]
+ ret
+ ```
+ - ```gas
+ ldr x30, [...]
+ add x30, x27, w30, uxtw
+ ret
+ ```
+* - ```gas
+ ldp xN, x30, [...]
+ ret
+ ```
+ - ```gas
+ ldp xN, x30, [...]
+ add x30, x27, w30, uxtw
+ ret
+ ```
+:::
#### Pointer Authentication Code (PAC) support
@@ -330,78 +347,89 @@ To gain the security benefit of PAC under LFI, the hardware must implement
still keeps confined to the sandbox by masking it, but the mask overwrites the
poison caused by the authentication failure.
-```{eval-rst}
-+-------------------+------------------------------+
-| Original | Rewritten |
-+-------------------+------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| paciasp | paciasp |
-| | |
-+-------------------+------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| autiasp | autiasp |
-| ret | add x30, x27, w30, uxtw |
-| | ret |
-| | |
-+-------------------+------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ paciasp
+ ```
+ - ```gas
+ paciasp
+ ```
+* - ```gas
+ autiasp
+ ret
+ ```
+ - ```gas
+ autiasp
+ add x30, x27, w30, uxtw
+ ret
+ ```
+:::
Authenticated returns (`retaa`/`retab`) combine authentication with return,
and must be expanded during rewriting.
-```{eval-rst}
-+-----------------+-------------------------------+
-| Original | Rewritten |
-+-----------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| retaa | autiasp |
-| | add x30, x27, w30, uxtw |
-| | ret |
-| | |
-+-----------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| retab | autibsp |
-| | add x30, x27, w30, uxtw |
-| | ret |
-| | |
-+-----------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ retaa
+ ```
+ - ```gas
+ autiasp
+ add x30, x27, w30, uxtw
+ ret
+ ```
+* - ```gas
+ retab
+ ```
+ - ```gas
+ autibsp
+ add x30, x27, w30, uxtw
+ ret
+ ```
+:::
Authenticated branches (`braa`/`brab`/`braaz`/`brabz`) and calls
(`blraa`/`blrab`/`blraaz`/`blrabz`) combine authentication with an
indirect branch or call. They are expanded by first authenticating the target
register in place, then performing a normal sandboxed branch or call.
-```{eval-rst}
-+-------------------+-------------------------------+
-| Original | Rewritten |
-+-------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| braa xN, xM | autia xN, xM |
-| | add x28, x27, wN, uxtw |
-| | br x28 |
-| | |
-+-------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| braaz xN | autiza xN |
-| | add x28, x27, wN, uxtw |
-| | br x28 |
-| | |
-+-------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| blraa xN, xM | autia xN, xM |
-| | add x28, x27, wN, uxtw |
-| | blr x28 |
-| | |
-+-------------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ braa xN, xM
+ ```
+ - ```gas
+ autia xN, xM
+ add x28, x27, wN, uxtw
+ br x28
+ ```
+* - ```gas
+ braaz xN
+ ```
+ - ```gas
+ autiza xN
+ add x28, x27, wN, uxtw
+ br x28
+ ```
+* - ```gas
+ blraa xN, xM
+ ```
+ - ```gas
+ autia xN, xM
+ add x28, x27, wN, uxtw
+ blr x28
+ ```
+:::
Authenticated exception returns (`eret`/`eretaa`/`eretab`) are privileged
and are not supported: the rewriter reports an error for them.
@@ -414,41 +442,38 @@ stored at a negative offset from the sandbox base, so it can be referenced by
`x27`. The rewrite also saves and restores the link register, since it is
used for branching into the runtime.
-```{eval-rst}
-+-----------------+------------------------------+
-| Original | Rewritten |
-+-----------------+------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| svc #0 | mov x26, x30 |
-| | ldur x30, [x27, #-8] |
-| | blr x30 |
-| | add x30, x27, w26, uxtw |
-| | |
-+-----------------+------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ svc #0
+ ```
+ - ```gas
+ mov x26, x30
+ ldur x30, [x27, #-8]
+ blr x30
+ add x30, x27, w26, uxtw
+ ```
+:::
#### Thread pointer (TP)
TP accesses are rewritten into loads/stores from the context register
(`x25`), which holds the virtual thread pointer at offset 16 (see
-[Context Register]).
-
-```{eval-rst}
-+----------------------+-------------------------+
-| Original | Rewritten |
-+----------------------+-------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| mrs xN, tpidr_el0 | ldr xN, [x25, #16] |
-| | |
-+----------------------+-------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| msr tpidr_el0, xN | str xN, [x25, #16] |
-| | |
-+----------------------+-------------------------+
-```
+[Context Register](#context-register)).
+
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - `mrs xN, tpidr_el0`
+ - `ldr xN, [x25, #16]`
+* - `msr tpidr_el0, xN`
+ - `str xN, [x25, #16]`
+:::
### Optimizations
@@ -458,21 +483,26 @@ If a register is guarded multiple times in the same basic block without any
modifications to it during the intervening instructions, then subsequent guards
can be removed.
-```{eval-rst}
-+---------------------------+---------------------------+
-| Original | Rewritten |
-+---------------------------+---------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| add x28, x27, wN, uxtw | add x28, x27, wN, uxtw |
-| ldur xN, [x28] | ldur xN, [x28] |
-| add x28, x27, wN, uxtw | ldur xN, [x28, #8] |
-| ldur xN, [x28, #8] | ldur xN, [x28, #16] |
-| add x28, x27, wN, uxtw | |
-| ldur xN, [x28, #16] | |
-| | |
-+---------------------------+---------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ add x28, x27, wN, uxtw
+ ldur xN, [x28]
+ add x28, x27, wN, uxtw
+ ldur xN, [x28, #8]
+ add x28, x27, wN, uxtw
+ ldur xN, [x28, #16]
+ ```
+ - ```gas
+ add x28, x27, wN, uxtw
+ ldur xN, [x28]
+ ldur xN, [x28, #8]
+ ldur xN, [x28, #16]
+ ```
+:::
#### Address generation
@@ -484,17 +514,20 @@ generated via `adrp` followed by `ldr`. Since the address generated by
directly target `x28` for these sequences. This allows the omission of a
guard instruction before the `ldr`.
-```{eval-rst}
-+----------------------+-----------------------+
-| Original | Rewritten |
-+----------------------+-----------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| adrp xN, target | adrp x28, target |
-| ldr xN, [xN, imm] | ldr xN, [x28, imm] |
-| | |
-+----------------------+-----------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ adrp xN, target
+ ldr xN, [xN, imm]
+ ```
+ - ```gas
+ adrp x28, target
+ ldr xN, [x28, imm]
+ ```
+:::
#### Stack guard elimination
@@ -506,19 +539,23 @@ the guard on the stack pointer modification can be removed. This is because the
load/store is guaranteed to trap if the stack pointer has been moved outside of
the sandbox region.
-```{eval-rst}
-+---------------------------+---------------------------+
-| Original | Rewritten |
-+---------------------------+---------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| add x26, sp, #8 | add sp, sp, #8 |
-| add sp, x27, w26, uxtw | ... (same basic block) |
-| ... (same basic block) | ldr xN, [sp] |
-| ldr xN, [sp] | |
-| | |
-+---------------------------+---------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ add x26, sp, #8
+ add sp, x27, w26, uxtw
+ ... (same basic block)
+ ldr xN, [sp]
+ ```
+ - ```gas
+ add sp, sp, #8
+ ... (same basic block)
+ ldr xN, [sp]
+ ```
+:::
#### Guard hoisting
@@ -526,24 +563,33 @@ the sandbox region.
In certain cases, guards may be hoisted outside of loops.
-```{eval-rst}
-+-----------------------+-------------------------------+
-| Original | Rewritten |
-+-----------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| mov w8, #10 | mov w8, #10 |
-| mov w9, #0 | mov w9, #0 |
-| .loop: | add x28, x27, wM, uxtw |
-| add w9, w9, #1 | .loop: |
-| ldr xN, [xM] | add w9, w9, #1 |
-| cmp w9, w8 | ldr xN, [x28] |
-| b.lt .loop | cmp w9, w8 |
-| .end: | b.lt .loop |
-| | .end: |
-| | |
-+-----------------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ mov w8, #10
+ mov w9, #0
+ .loop:
+ add w9, w9, #1
+ ldr xN, [xM]
+ cmp w9, w8
+ b.lt .loop
+ .end:
+ ```
+ - ```gas
+ mov w8, #10
+ mov w9, #0
+ add x28, x27, wM, uxtw
+ .loop:
+ add w9, w9, #1
+ ldr xN, [x28]
+ cmp w9, w8
+ b.lt .loop
+ .end:
+ ```
+:::
## X86-64
@@ -558,7 +604,7 @@ The X86-64 LFI target reserves the following registers:
- `gs`: always holds the sandbox base address (used as a segment register for
memory access sandboxing).
- `rsp`: always holds an address within the sandbox.
-- `r15`: context register (see [Context Register]).
+- `r15`: context register (see [Context Register](#context-register)).
- `r11`: scratch register.
### Assembly Rewrites
@@ -594,62 +640,71 @@ handler table is stored at the address pointed to by `r14`. The `r11`
register stores the return address (marked by the label `.Ltmp` in the
block below).
-```{eval-rst}
-+-------------------+-------------------------------+
-| Original | Rewritten |
-+-------------------+-------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| syscall | leaq .Ltmp(%rip), %r11 |
-| | jmpq *-8(%r14) |
-| | .Ltmp: |
-| | |
-+-------------------+-------------------------------+
-```
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ syscall
+ ```
+ - ```gas
+ leaq .Ltmp(%rip), %r11
+ jmpq *-8(%r14)
+ .Ltmp:
+ ```
+:::
#### Thread pointer
Thread pointer accesses via the `%fs` segment (used for TLS) are rewritten to
use the virtual thread pointer from the context register (`r15`) at offset 16
-(see [Context Register]). The rewrite handles any load or store instruction
-with an `%fs`-segment memory operand. `Op` represents any such instruction.
-
-```{eval-rst}
-+--------------------------------------+----------------------------------------+
-| Original | Rewritten |
-+--------------------------------------+----------------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| Op %fs:0, %rD | Op 16(%r15), %rD |
-| | |
-+--------------------------------------+----------------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| Op %fs:(%rX), %rD | movq 16(%r15), %rD |
-| | Op (%rD, %rX), %rD |
-| | |
-+--------------------------------------+----------------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| Op %rS, %fs:(%rX) | movq 16(%r15), %r11 |
-| | Op %rS, (%r11, %rX) |
-| | |
-+--------------------------------------+----------------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| Op %fs:N(%rX, %rY, S), %rD | movq 16(%r15), %r11 |
-| | leaq (%r11, %rX), %r11 |
-| | Op N(%r11, %rY, S), %rD |
-| | |
-+--------------------------------------+----------------------------------------+
-| .. code-block:: | .. code-block:: |
-| | |
-| Op %rS, %fs:N(%rX, %rY, S) | movq 16(%r15), %r11 |
-| | leaq (%r11, %rX), %r11 |
-| | Op %rS, N(%r11, %rY, S) |
-| | |
-+--------------------------------------+----------------------------------------+
-```
+(see [Context Register](#context-register)). The rewrite handles any load or
+store instruction with an `%fs`-segment memory operand. `Op` represents any
+such instruction.
+
+:::{list-table}
+:header-rows: 1
+
+* - Original
+ - Rewritten
+* - ```gas
+ Op %fs:0, %rD
+ ```
+ - ```gas
+ Op 16(%r15), %rD
+ ```
+* - ```gas
+ Op %fs:(%rX), %rD
+ ```
+ - ```gas
+ movq 16(%r15), %rD
+ Op (%rD, %rX), %rD
+ ```
+* - ```gas
+ Op %rS, %fs:(%rX)
+ ```
+ - ```gas
+ movq 16(%r15), %r11
+ Op %rS, (%r11, %rX)
+ ```
+* - ```gas
+ Op %fs:N(%rX, %rY, S), %rD
+ ```
+ - ```gas
+ movq 16(%r15), %r11
+ leaq (%r11, %rX), %r11
+ Op N(%r11, %rY, S), %rD
+ ```
+* - ```gas
+ Op %rS, %fs:N(%rX, %rY, S)
+ ```
+ - ```gas
+ movq 16(%r15), %r11
+ leaq (%r11, %rX), %r11
+ Op %rS, N(%r11, %rY, S)
+ ```
+:::
## References
@@ -664,4 +719,3 @@ Contact info:
- Zachary Yedidia - <mailto:zyedidia at cs.stanford.edu>
- Tal Garfinkel - <mailto:tgarfinkel at google.com>
- Sharjeel Khan - <mailto:sharjeelkhan at google.com>
-
diff --git a/llvm/docs/MisExpect.md b/llvm/docs/MisExpect.md
index 5c0c7feb3ae81..41e199941eb3f 100644
--- a/llvm/docs/MisExpect.md
+++ b/llvm/docs/MisExpect.md
@@ -1,9 +1,5 @@
# Misexpect
-```{toctree}
-:maxdepth: 1
-```
-
When developers use `llvm.expect` intrinsics, i.e., through use of
`__builtin_expect(...)`, they are trying to communicate how their code is
expected to behave at runtime to the optimizer. These annotations, however, can
@@ -62,4 +58,3 @@ Sampling. MisExpect Diagnostics are compatible with all Profiling formats.
| IR | Profiling instrumentation added during by the LLVM backend |
| CS-IR | Context Sensitive IR based profiles |
| Sampling | Profiles collected through sampling with external tools, such as `perf` on Linux |
-
diff --git a/llvm/docs/PDB/index.md b/llvm/docs/PDB/index.md
index 8f83867f4edcb..d2a5c31cafe1e 100644
--- a/llvm/docs/PDB/index.md
+++ b/llvm/docs/PDB/index.md
@@ -39,7 +39,7 @@ assume it is little endian!
:::
```{toctree}
-:hidden: true
+:hidden:
MsfFile
PdbStream
@@ -79,67 +79,104 @@ by name, and various other information about how the program was compiled such
as the specific toolchain used, and more. A summary of streams contained in a
PDB file is as follows:
-| Name | Stream Index | Contents |
-| ------------------ | ------------------------------------------ | ------------------------------------------------------------- |
-| Old Directory | - Fixed Stream Index 0 | - Previous MSF Stream Directory |
-| PDB Stream | - Fixed Stream Index 1 | - Basic File Information
-- Fields to match EXE to this PDB
-- Map of named streams to stream indices |
-| TPI Stream | - Fixed Stream Index 2 | - CodeView Type Records
-- Index of TPI Hash Stream |
-| DBI Stream | - Fixed Stream Index 3 | - Module/Compiland Information
-- Indices of individual module streams
-- Indices of public / global streams
-- Section Contribution Information
-- Source File Information
-- References to streams containing FPO / PGO Data |
-| IPI Stream | - Fixed Stream Index 4 | - CodeView Type Records
-- Index of IPI Hash Stream |
-| /LinkInfo | - Contained in PDB Stream Named Stream map | - Unknown |
-| /src/headerblock | - Contained in PDB Stream Named Stream map | - Summary of embedded source file content (e.g. natvis files) |
-| /names | - Contained in PDB Stream Named Stream map | - PDB-wide global string table used for string de-duplication |
-| Module Info Stream | - Contained in DBI Stream
-- One for each compiland | - CodeView Symbol Records for this module
-- Line Number Information |
-| Public Stream | - Contained in DBI Stream | - Public (Exported) Symbol Records
-- Index of Public Hash Stream |
-| Global Stream | - Contained in DBI Stream | - Single combined symbol-table
-- Index of Global Hash Stream |
-| TPI Hash Stream | - Contained in TPI Stream | - Hash table for looking up TPI records by name |
-| IPI Hash Stream | - Contained in IPI Stream | - Hash table for looking up IPI records by name |
+:::{list-table}
+:header-rows: 1
+
+* - Name
+ - Stream Index
+ - Contents
+* - Old Directory
+ - Fixed Stream Index 0
+ - Previous MSF Stream Directory
+* - PDB Stream
+ - Fixed Stream Index 1
+ - Basic File Information
+
+ Fields to match EXE to this PDB
+
+ Map of named streams to stream indices
+* - TPI Stream
+ - Fixed Stream Index 2
+ - CodeView Type Records
+
+ Index of TPI Hash Stream
+* - DBI Stream
+ - Fixed Stream Index 3
+ - Module/Compiland Information
+
+ Indices of individual module streams
+
+ Indices of public / global streams
+
+ Section Contribution Information
+
+ Source File Information
+
+ References to streams containing FPO / PGO Data
+* - IPI Stream
+ - Fixed Stream Index 4
+ - CodeView Type Records
+
+ Index of IPI Hash Stream
+* - /LinkInfo
+ - Contained in PDB Stream Named Stream map
+ - Unknown
+* - /src/headerblock
+ - Contained in PDB Stream Named Stream map
+ - Summary of embedded source file content (e.g. natvis files)
+* - /names
+ - Contained in PDB Stream Named Stream map
+ - PDB-wide global string table used for string de-duplication
+* - Module Info Stream
+ - Contained in DBI Stream
+
+ One for each compiland
+ - CodeView Symbol Records for this module
+
+ Line Number Information
+* - Public Stream
+ - Contained in DBI Stream
+ - Public (Exported) Symbol Records
+
+ Index of Public Hash Stream
+* - Global Stream
+ - Contained in DBI Stream
+ - Single combined symbol-table
+
+ Index of Global Hash Stream
+* - TPI Hash Stream
+ - Contained in TPI Stream
+ - Hash table for looking up TPI records by name
+* - IPI Hash Stream
+ - Contained in IPI Stream
+ - Hash table for looking up IPI records by name
+:::
More information about the structure of each of these can be found on the
following pages:
-{doc}`PdbStream`
-
+{doc}`PdbStream <PdbStream>`
: Information about the PDB Info Stream and how it is used to match PDBs to EXEs.
-{doc}`TpiStream`
-
+{doc}`TpiStream <TpiStream>`
: Information about the TPI stream and the CodeView records contained within.
-{doc}`DbiStream`
-
+{doc}`DbiStream <DbiStream>`
: Information about the DBI stream and relevant substreams including the
Module Substreams, source file information, and CodeView symbol records
contained within.
-{doc}`ModiStream`
-
+{doc}`ModiStream <ModiStream>`
: Information about the Module Information Stream, of which there is one for
each compilation unit and the format of symbols contained within.
-{doc}`PublicStream`
-
+{doc}`PublicStream <PublicStream>`
: Information about the Public Symbol Stream.
-{doc}`GlobalStream`
-
+{doc}`GlobalStream <GlobalStream>`
: Information about the Global Symbol Stream.
-{doc}`HashTable`
-
+{doc}`HashTable <HashTable>`
: Information about the serialized hash table format used internally to
represent things such as the Named Stream Map and the Hash Adjusters in the
{doc}`TPI/IPI Stream <TpiStream>`.
@@ -152,4 +189,3 @@ appear within the MSF file and the format of those streams, CodeView defines
the format of **symbol and type records** that appear within specific streams.
Refer to the pages on {doc}`CodeViewSymbols` and {doc}`CodeViewTypes` for
more information about the CodeView format.
-
diff --git a/llvm/docs/RISCV/RISCVVectorExtension.md b/llvm/docs/RISCV/RISCVVectorExtension.md
index b57eb9baf7ea2..9cdf1a7ce929d 100644
--- a/llvm/docs/RISCV/RISCVVectorExtension.md
+++ b/llvm/docs/RISCV/RISCVVectorExtension.md
@@ -15,14 +15,14 @@ Note this means that VLEN must be at least 64, so VLEN=32 isn't currently suppor
| | LMUL=⅛ | LMUL=¼ | LMUL=½ | LMUL=1 | LMUL=2 | LMUL=4 | LMUL=8 |
| ---------------- | ------------- | ----------------- | ----------------- | ----------------- | ----------------- | ------------------ | ------------------ |
-| i64 (ELEN=64) | N/A | N/A | N/A | \<v x 1 x i64> | \<v x 2 x i64> | \<v x 4 x i64> | \<v x 8 x i64> |
-| i32 | N/A | N/A | \<v x 1 x i32> | \<v x 2 x i32> | \<v x 4 x i32> | \<v x 8 x i32> | \<v x 16 x i32> |
-| i16 | N/A | \<v x 1 x i16> | \<v x 2 x i16> | \<v x 4 x i16> | \<v x 8 x i16> | \<v x 16 x i16> | \<v x 32 x i16> |
-| i8 | \<v x 1 x i8> | \<v x 2 x i8> | \<v x 4 x i8> | \<v x 8 x i8> | \<v x 16 x i8> | \<v x 32 x i8> | \<v x 64 x i8> |
-| double (ELEN=64) | N/A | N/A | N/A | \<v x 1 x double> | \<v x 2 x double> | \<v x 4 x double> | \<v x 8 x double> |
-| float | N/A | N/A | \<v x 1 x float> | \<v x 2 x float> | \<v x 4 x float> | \<v x 8 x float> | \<v x 16 x float> |
-| half | N/A | \<v x 1 x half> | \<v x 2 x half> | \<v x 4 x half> | \<v x 8 x half> | \<v x 16 x half> | \<v x 32 x half> |
-| bfloat | N/A | \<v x 1 x bfloat> | \<v x 2 x bfloat> | \<v x 4 x bfloat> | \<v x 8 x bfloat> | \<v x 16 x bfloat> | \<v x 32 x bfloat> |
+| i64 (ELEN=64) | N/A | N/A | N/A | `<v x 1 x i64>` | `<v x 2 x i64>` | `<v x 4 x i64>` | `<v x 8 x i64>` |
+| i32 | N/A | N/A | `<v x 1 x i32>` | `<v x 2 x i32>` | `<v x 4 x i32>` | `<v x 8 x i32>` | `<v x 16 x i32>` |
+| i16 | N/A | `<v x 1 x i16>` | `<v x 2 x i16>` | `<v x 4 x i16>` | `<v x 8 x i16>` | `<v x 16 x i16>` | `<v x 32 x i16>` |
+| i8 | `<v x 1 x i8>` | `<v x 2 x i8>` | `<v x 4 x i8>` | `<v x 8 x i8>` | `<v x 16 x i8>` | `<v x 32 x i8>` | `<v x 64 x i8>` |
+| double (ELEN=64) | N/A | N/A | N/A | `<v x 1 x double>` | `<v x 2 x double>` | `<v x 4 x double>` | `<v x 8 x double>` |
+| float | N/A | N/A | `<v x 1 x float>` | `<v x 2 x float>` | `<v x 4 x float>` | `<v x 8 x float>` | `<v x 16 x float>` |
+| half | N/A | `<v x 1 x half>` | `<v x 2 x half>` | `<v x 4 x half>` | `<v x 8 x half>` | `<v x 16 x half>` | `<v x 32 x half>` |
+| bfloat | N/A | `<v x 1 x bfloat>` | `<v x 2 x bfloat>` | `<v x 4 x bfloat>` | `<v x 8 x bfloat>` | `<v x 16 x bfloat>` | `<v x 32 x bfloat>` |
(Read `<v x k x ty>` as `<vscale x k x ty>`)
@@ -251,7 +251,7 @@ $v0 = COPY %3:vr
%x:vrnov0 = PseudoVADD_VV_M1_MASK %0:vrnov0, %1:vr, %2:vr, $v0, ...
```
-(rvv-register-allocation)=
+(rvv_register_allocation)=
## Register allocation
@@ -269,12 +269,12 @@ Performing `RISCVInsertVSETVLI` after vector register allocation imposes fewer c
There are four register classes for vectors:
-- `VR` for vector registers (`v0`, `v1,`, ..., `v31`). Used when $\text{LMUL} \leq 1$ and mask registers.
-- `VRM2` for vector groups of length 2 i.e., $\text{LMUL}=2$ (`v0m2`, `v2m2`, ..., `v30m2`)
-- `VRM4` for vector groups of length 4 i.e., $\text{LMUL}=4$ (`v0m4`, `v4m4`, ..., `v28m4`)
-- `VRM8` for vector groups of length 8 i.e., $\text{LMUL}=8$ (`v0m8`, `v8m8`, ..., `v24m8`)
+- `VR` for vector registers (`v0`, `v1,`, ..., `v31`). Used when {math}`\text{LMUL} \leq 1` and mask registers.
+- `VRM2` for vector groups of length 2 i.e., {math}`\text{LMUL}=2` (`v0m2`, `v2m2`, ..., `v30m2`)
+- `VRM4` for vector groups of length 4 i.e., {math}`\text{LMUL}=4` (`v0m4`, `v4m4`, ..., `v28m4`)
+- `VRM8` for vector groups of length 8 i.e., {math}`\text{LMUL}=8` (`v0m8`, `v8m8`, ..., `v24m8`)
-$\text{LMUL} \lt 1$ types and mask types do not benefit from having a dedicated class, so `VR` is used in their case.
+{math}`\text{LMUL} \lt 1` types and mask types do not benefit from having a dedicated class, so `VR` is used in their case.
Some instructions have a constraint that a register operand cannot be `V0` or overlap with `V0`, so for these cases we also have `VRNoV0` variants.
@@ -318,4 +318,3 @@ vadd.vv v8, v8, v10
- [2023 LLVM Dev Mtg - Vector codegen in the RISC-V backend](https://youtu.be/-ox8iJmbp0c?feature=shared)
- [2023 LLVM Dev Mtg - How to add an C intrinsic and code-gen it, using the RISC-V vector C intrinsics](https://youtu.be/t17O_bU1jks?feature=shared)
- [2021 LLVM Dev Mtg “Optimizing code for scalable vector architectures”](https://youtu.be/daWLCyhwrZ8?feature=shared)
-
diff --git a/llvm/docs/RISCVUsage.md b/llvm/docs/RISCVUsage.md
index 3ce33c2d51afb..43a8dd4a68712 100644
--- a/llvm/docs/RISCVUsage.md
+++ b/llvm/docs/RISCVUsage.md
@@ -48,16 +48,10 @@ RV64E are supported by the assembly-based tools only. RV128I is not supported.
To specify the target triple:
-> ```{eval-rst}
-> .. table:: RISC-V Architectures
->
-> ============ ==============================================================
-> Architecture Description
-> ============ ==============================================================
-> ``riscv32`` RISC-V with XLEN=32 (i.e. RV32I or RV32E)
-> ``riscv64`` RISC-V with XLEN=64 (i.e. RV64I or RV64E)
-> ============ ==============================================================
-> ```
+| Architecture | Description |
+| ------------ | ----------- |
+| `riscv32` | RISC-V with XLEN=32 (i.e. RV32I or RV32E) |
+| `riscv64` | RISC-V with XLEN=64 (i.e. RV64I or RV64E) |
To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
architecture string (e.g. `riscv32`) with the extension `e`.
@@ -96,177 +90,174 @@ The following table provides a status summary for extensions which have been
ratified and thus have finalized specifications. When relevant, detailed notes
on support follow.
-> ```{eval-rst}
-> .. table:: Ratified Extensions by Status
->
-> ================ =================================================================
-> Extension Status
-> ================ =================================================================
-> ``A`` Supported
-> ``B`` Supported
-> ``C`` Supported
-> ``D`` Supported
-> ``F`` Supported
-> ``E`` Supported (`See note <#riscv-rve-note>`__)
-> ``H`` Assembly Support
-> ``M`` Supported
-> ``Q`` Assembly Support
-> ``Sdext`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
-> ``Sdtrig`` Assembly Support (`See note <#riscv-debug-specification-note>`__)
-> ``Sha`` Supported
-> ``Shcounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Shgatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Shlcofideleg`` Supported
-> ``Shtvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Shvsatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Shvstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Shvstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Smaia`` Supported
-> ``Smcdeleg`` Supported
-> ``Smcntrpmf`` Supported
-> ``Smcsrind`` Supported
-> ``Smctr`` Assembly Support
-> ``Smdbltrp`` Supported
-> ``Smepmp`` Supported
-> ``Smmpm`` Supported
-> ``Smnpm`` Supported
-> ``Smrnmi`` Supported
-> ``Smstateen`` Assembly Support
-> ``Ssaia`` Supported
-> ``Ssccfg`` Supported
-> ``Ssccptr`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Sscofpmf`` Assembly Support
-> ``Sscounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Sscsrind`` Supported
-> ``Ssctr`` Assembly Support
-> ``Ssdbltrp`` Supported
-> ``Ssnpm`` Supported
-> ``Sspm`` Supported
-> ``Ssqosid`` Assembly Support
-> ``Ssstateen`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Ssstrict`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Sstc`` Assembly Support
-> ``Sstvala`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Sstvecd`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Ssu64xl`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Supm`` Supported
-> ``Svade`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Svadu`` Assembly Support
-> ``Svbare`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__)
-> ``Svinval`` Assembly Support
-> ``Svnapot`` Assembly Support
-> ``Svpbmt`` Supported
-> ``Svrsw60t59b`` Supported
-> ``Svvptc`` Supported
-> ``V`` Supported
-> ``Za128rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Za64rs`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Zaamo`` Assembly Support
-> ``Zabha`` Supported
-> ``Zacas`` Supported (`See note <#riscv-zacas-note>`__)
-> ``Zalasr`` Supported
-> ``Zalrsc`` Assembly Support
-> ``Zama16b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Zawrs`` Assembly Support
-> ``Zba`` Supported
-> ``Zbb`` Supported
-> ``Zbc`` Supported
-> ``Zbkb`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
-> ``Zbkc`` Supported
-> ``Zbkx`` Supported (`See note <#riscv-scalar-crypto-note1>`__)
-> ``Zbs`` Supported
-> ``Zca`` Supported
-> ``Zcb`` Supported
-> ``Zcd`` Supported
-> ``Zcf`` Supported
-> ``Zclsd`` Assembly Support
-> ``Zcmop`` Supported
-> ``Zcmp`` Supported
-> ``Zcmt`` Assembly Support
-> ``Zdinx`` Supported
-> ``Zfa`` Supported
-> ``Zfbfmin`` Supported
-> ``Zfh`` Supported
-> ``Zfhmin`` Supported
-> ``Zfinx`` Supported
-> ``Zhinx`` Supported
-> ``Zhinxmin`` Supported
-> ``Zic64b`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Zicbom`` Assembly Support
-> ``Zicbop`` Supported
-> ``Zicboz`` Assembly Support
-> ``Ziccamoa`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Ziccamoc`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Ziccid`` Supported
-> ``Ziccif`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Zicclsm`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Ziccrse`` Supported (`See note <#riscv-profiles-extensions-note>`__)
-> ``Zicntr`` (`See Note <#riscv-i2p1-note>`__)
-> ``Zicond`` Supported
-> ``Zicsr`` (`See Note <#riscv-i2p1-note>`__)
-> ``Zifencei`` (`See Note <#riscv-i2p1-note>`__)
-> ``Zihintntl`` Supported
-> ``Zihintpause`` Assembly Support
-> ``Zihpm`` (`See Note <#riscv-i2p1-note>`__)
-> ``Zilsd`` Supported
-> ``Zimop`` Supported
-> ``Zkn`` Supported
-> ``Zknd`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
-> ``Zkne`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
-> ``Zknh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
-> ``Zksed`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
-> ``Zksh`` Supported (`See note <#riscv-scalar-crypto-note2>`__)
-> ``Zk`` Supported
-> ``Zkr`` Supported
-> ``Zks`` Supported
-> ``Zkt`` Supported
-> ``Zmmul`` Supported
-> ``Ztso`` Supported
-> ``Zvbb`` Supported
-> ``Zvbc`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zve32x`` (`Partially <#riscv-vlen-32-note>`__) Supported
-> ``Zve32f`` (`Partially <#riscv-vlen-32-note>`__) Supported
-> ``Zve64x`` Supported
-> ``Zve64f`` Supported
-> ``Zve64d`` Supported
-> ``Zvfbfa`` Assembly Support
-> ``Zvfbfmin`` Supported
-> ``Zvfbfwma`` Supported
-> ``Zvfh`` Supported
-> ``Zvfhmin`` Supported
-> ``Zvfofp8min`` Assembly Support
-> ``Zvkb`` Supported
-> ``Zvkg`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvkn`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvknc`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvkned`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvkng`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvknha`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvknhb`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvks`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvksc`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvksed`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvksg`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvksh`` Supported (`See note <#riscv-vector-crypto-note>`__)
-> ``Zvkt`` Supported
-> ``Zvvfmm`` Assembly Support
-> ``Zvvmm`` Assembly Support
-> ``Zvvmtls`` Assembly Support
-> ``Zvvmttls`` Assembly Support
-> ``Zvl32b`` (`Partially <#riscv-vlen-32-note>`__) Supported
-> ``Zvl64b`` Supported
-> ``Zvl128b`` Supported
-> ``Zvl256b`` Supported
-> ``Zvl512b`` Supported
-> ``Zvl1024b`` Supported
-> ``Zvl2048b`` Supported
-> ``Zvl4096b`` Supported
-> ``Zvl8192b`` Supported
-> ``Zvl16384b`` Supported
-> ``Zvl32768b`` Supported
-> ``Zvl65536b`` Supported
-> ================ =================================================================
-> ```
+:::{table} Ratified Extensions by Status
+| Extension | Status |
+| --- | --- |
+| `A` | Supported |
+| `B` | Supported |
+| `C` | Supported |
+| `D` | Supported |
+| `F` | Supported |
+| `E` | Supported ([See note](#riscv-rve-note)) |
+| `H` | Assembly Support |
+| `M` | Supported |
+| `Q` | Assembly Support |
+| `Sdext` | Assembly Support ([See note](#riscv-debug-specification-note)) |
+| `Sdtrig` | Assembly Support ([See note](#riscv-debug-specification-note)) |
+| `Sha` | Supported |
+| `Shcounterenw` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Shgatpa` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Shlcofideleg` | Supported |
+| `Shtvala` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Shvsatpa` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Shvstvala` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Shvstvecd` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Smaia` | Supported |
+| `Smcdeleg` | Supported |
+| `Smcntrpmf` | Supported |
+| `Smcsrind` | Supported |
+| `Smctr` | Assembly Support |
+| `Smdbltrp` | Supported |
+| `Smepmp` | Supported |
+| `Smmpm` | Supported |
+| `Smnpm` | Supported |
+| `Smrnmi` | Supported |
+| `Smstateen` | Assembly Support |
+| `Ssaia` | Supported |
+| `Ssccfg` | Supported |
+| `Ssccptr` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Sscofpmf` | Assembly Support |
+| `Sscounterenw` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Sscsrind` | Supported |
+| `Ssctr` | Assembly Support |
+| `Ssdbltrp` | Supported |
+| `Ssnpm` | Supported |
+| `Sspm` | Supported |
+| `Ssqosid` | Assembly Support |
+| `Ssstateen` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Ssstrict` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Sstc` | Assembly Support |
+| `Sstvala` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Sstvecd` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Ssu64xl` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Supm` | Supported |
+| `Svade` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Svadu` | Assembly Support |
+| `Svbare` | Assembly Support ([See note](#riscv-profiles-extensions-note)) |
+| `Svinval` | Assembly Support |
+| `Svnapot` | Assembly Support |
+| `Svpbmt` | Supported |
+| `Svrsw60t59b` | Supported |
+| `Svvptc` | Supported |
+| `V` | Supported |
+| `Za128rs` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Za64rs` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Zaamo` | Assembly Support |
+| `Zabha` | Supported |
+| `Zacas` | Supported ([See note](#riscv-zacas-note)) |
+| `Zalasr` | Supported |
+| `Zalrsc` | Assembly Support |
+| `Zama16b` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Zawrs` | Assembly Support |
+| `Zba` | Supported |
+| `Zbb` | Supported |
+| `Zbc` | Supported |
+| `Zbkb` | Supported ([See note](#riscv-scalar-crypto-note1)) |
+| `Zbkc` | Supported |
+| `Zbkx` | Supported ([See note](#riscv-scalar-crypto-note1)) |
+| `Zbs` | Supported |
+| `Zca` | Supported |
+| `Zcb` | Supported |
+| `Zcd` | Supported |
+| `Zcf` | Supported |
+| `Zclsd` | Assembly Support |
+| `Zcmop` | Supported |
+| `Zcmp` | Supported |
+| `Zcmt` | Assembly Support |
+| `Zdinx` | Supported |
+| `Zfa` | Supported |
+| `Zfbfmin` | Supported |
+| `Zfh` | Supported |
+| `Zfhmin` | Supported |
+| `Zfinx` | Supported |
+| `Zhinx` | Supported |
+| `Zhinxmin` | Supported |
+| `Zic64b` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Zicbom` | Assembly Support |
+| `Zicbop` | Supported |
+| `Zicboz` | Assembly Support |
+| `Ziccamoa` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Ziccamoc` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Ziccid` | Supported |
+| `Ziccif` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Zicclsm` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Ziccrse` | Supported ([See note](#riscv-profiles-extensions-note)) |
+| `Zicntr` | ([See Note](#riscv-i2p1-note)) |
+| `Zicond` | Supported |
+| `Zicsr` | ([See Note](#riscv-i2p1-note)) |
+| `Zifencei` | ([See Note](#riscv-i2p1-note)) |
+| `Zihintntl` | Supported |
+| `Zihintpause` | Assembly Support |
+| `Zihpm` | ([See Note](#riscv-i2p1-note)) |
+| `Zilsd` | Supported |
+| `Zimop` | Supported |
+| `Zkn` | Supported |
+| `Zknd` | Supported ([See note](#riscv-scalar-crypto-note2)) |
+| `Zkne` | Supported ([See note](#riscv-scalar-crypto-note2)) |
+| `Zknh` | Supported ([See note](#riscv-scalar-crypto-note2)) |
+| `Zksed` | Supported ([See note](#riscv-scalar-crypto-note2)) |
+| `Zksh` | Supported ([See note](#riscv-scalar-crypto-note2)) |
+| `Zk` | Supported |
+| `Zkr` | Supported |
+| `Zks` | Supported |
+| `Zkt` | Supported |
+| `Zmmul` | Supported |
+| `Ztso` | Supported |
+| `Zvbb` | Supported |
+| `Zvbc` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zve32x` | ([Partially](#riscv-vlen-32-note)) Supported |
+| `Zve32f` | ([Partially](#riscv-vlen-32-note)) Supported |
+| `Zve64x` | Supported |
+| `Zve64f` | Supported |
+| `Zve64d` | Supported |
+| `Zvfbfa` | Assembly Support |
+| `Zvfbfmin` | Supported |
+| `Zvfbfwma` | Supported |
+| `Zvfh` | Supported |
+| `Zvfhmin` | Supported |
+| `Zvfofp8min` | Assembly Support |
+| `Zvkb` | Supported |
+| `Zvkg` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvkn` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvknc` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvkned` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvkng` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvknha` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvknhb` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvks` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvksc` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvksed` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvksg` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvksh` | Supported ([See note](#riscv-vector-crypto-note)) |
+| `Zvkt` | Supported |
+| `Zvvfmm` | Assembly Support |
+| `Zvvmm` | Assembly Support |
+| `Zvvmtls` | Assembly Support |
+| `Zvvmttls` | Assembly Support |
+| `Zvl32b` | ([Partially](#riscv-vlen-32-note)) Supported |
+| `Zvl64b` | Supported |
+| `Zvl128b` | Supported |
+| `Zvl256b` | Supported |
+| `Zvl512b` | Supported |
+| `Zvl1024b` | Supported |
+| `Zvl2048b` | Supported |
+| `Zvl4096b` | Supported |
+| `Zvl8192b` | Supported |
+| `Zvl16384b` | Supported |
+| `Zvl32768b` | Supported |
+| `Zvl65536b` | Supported |
+
+:::
Assembly Support
@@ -280,7 +271,7 @@ Supported
`E`
-: Support of RV32E/RV64E and ilp32e/lp64e ABIs are experimental. To be compatible with the implementation of ilp32e in GCC, we don't use aligned registers to pass variadic arguments. Furthermore, we set the stack alignment to 4 bytes for types with length of 2\*XLEN.
+: Support of RV32E/RV64E and ilp32e/lp64e ABIs are experimental. To be compatible with the implementation of ilp32e in GCC, we don't use aligned registers to pass variadic arguments. Furthermore, we set the stack alignment to 4 bytes for types with length of 2*XLEN.
(riscv-scalar-crypto-note1)=
@@ -750,13 +741,13 @@ This is a summary of the current state of sanitizers, and not an official suppor
RISC-V is highly configurable, meaning its scheduling models could be highly diversified as well. Yet we still believe it is helpful to provide a "generic" tuning processor / scheduling model that represents the "lowest common denominator" RISC-V implementation at the time. The idea is that it could serve as a "good-enough" baseline model for performance tuning purposes on some of the most common use cases.
-Though details of this generic scheduling model might evolve over time, we always have some \_expectations\_ on the kind of processors it is used for.
+Though details of this generic scheduling model might evolve over time, we always have some _expectations_ on the kind of processors it is used for.
For example, the `generic` tuning processor is expected to target in-order, superscalar application processors designed for general-purpose computing. It is usually RVA22U64- or RVA23U64-capable intended to run Linux. The `generic-ooo` has a similar set of expectations, except it is targeting out-of-order application processors.
Right now, we simply assign a scheduling model that is widely used by the community to `generic`. But in the future, we can create a standalone scheduling model for `generic`, or even create a generic model for each of the individual sectors. For example, a `generic-embedded` for embedded processors and a `generic-server` for server workloads.
-These future generic models could even serve as the "base" model for other scheduling models to derive from: it's not uncommon for multiple processors to share a similar set of instruction scheduling info except a few key instructions, and this is especially true for RISC-V given its highly configurable nature. If we could design the base model in a way that it can be \_parameterized\_ by subtarget tuning features, we can substitue the traditional way of creating individual scheduling models with a combination of base scheduling model + different subtarget features.
+These future generic models could even serve as the "base" model for other scheduling models to derive from: it's not uncommon for multiple processors to share a similar set of instruction scheduling info except a few key instructions, and this is especially true for RISC-V given its highly configurable nature. If we could design the base model in a way that it can be _parameterized_ by subtarget tuning features, we can substitue the traditional way of creating individual scheduling models with a combination of base scheduling model + different subtarget features.
## Processor-Specific Tuning Feature String
@@ -764,31 +755,31 @@ Due to RISC-V's highly configurable nature, it is often desirable to share a sin
To that end, RISC-V LLVM supports a tuning feature string format, through frontend flags like `-mtune` in Clang, to help users building a performance model by "configuring" an existing tune CPU, along with its scheduling model. For example, this flag
-::
-
-: -mtune=sifive-x280:single-element-vec-fp64
+```text
+-mtune=sifive-x280:single-element-vec-fp64
+```
takes `sifive-x280` as the "base" tune CPU and configured it with `single-element-vec-fp64`. This gives us a performance model that looks exactly like that of `sifive-x280`, except some of the 64-bit vector floating point instructions now produce only a single element per cycle due to `single-element-vec-fp64`.
More formally speaking, each tuning feature string has the following format:
-::
-
-: \<tune-cpu>[":"\<tune-features>]?
+```text
+<tune-cpu>[":"<tune-features>]?
+```
where
-::
+```text
+tune-cpu ::= 'tuning CPU name in lower case'
+directive ::= "[a-zA-Z0-9\_-]+"
+tune-features ::= directive ["," directive]*
+```
-: tune-cpu ::= 'tuning CPU name in lower case'
- directive ::= "[a-zA-Z0-9\_-]+"
- tune-features ::= directive ["," directive]\*
+A *directive* can and can only _enable_ or _disable_ a certain tuning feature from the tuning CPU. A **positive directive**, like the `single-element-vec-fp64` we just saw, enables an additional tuning feature in the associated tuning model. A **negative directive**, on the other hand, removes a certain tuning feature. For example, `sifive-x390` already has the `single-element-vec-fp64` feature, and we can use
-A *directive* can and can only \_enable\_ or \_disable\_ a certain tuning feature from the tuning CPU. A **positive directive**, like the `single-element-vec-fp64` we just saw, enables an additional tuning feature in the associated tuning model. A **negative directive**, on the other hand, removes a certain tuning feature. For example, `sifive-x390` already has the `single-element-vec-fp64` feature, and we can use
-
-::
-
-: "sifive-x390:full-vec-fp64"
+```text
+"sifive-x390:full-vec-fp64"
+```
to create a new performance model that looks nearly the same as `sifive-x390` except `single-element-vec-fp64` being cut out. In this case, `full-vec-fp64` is a negative directive.
@@ -796,7 +787,6 @@ There are some rules for the list of directives, though:
1. The same directive cannot appear more than once.
2. The positive and negative directives that belong to the same feature cannot appear at the same time.
-3. If a feature implies other features -- for example, `short-forward-branch-imul` implies `short-forward-branch-ialu` -- then the \_implied\_ features are subject to the previous two rules, too. For example, we cannot write \_"short-forward-branch-imul,no-short-forward-branch-ialu"\_, because the feature implied by `short-forward-branch-imul` violates rule 2.
-
-In addition to the rules listed above, right now, this string only accepts directives that are explicitly supported by the tune CPU. For example, \_"sifive-x280:prefer-w-inst"\_ is not a valid string as `prefer-w-inst` is not supported by `sifive-x280` at this moment. Vendors of these processors are expected to maintain the compatibility of their supported directives across different versions. There have been lots of discussions on having "generic" features that are universally supported by all RISC-V CPUs, yet many concerns -- including the difficulty to maintain compatibility across \_all\_ CPU targets and versions -- make us decide to table this issue until we find a reliable process to select such features.
+3. If a feature implies other features -- for example, `short-forward-branch-imul` implies `short-forward-branch-ialu` -- then the _implied_ features are subject to the previous two rules, too. For example, we cannot write _"short-forward-branch-imul,no-short-forward-branch-ialu"_, because the feature implied by `short-forward-branch-imul` violates rule 2.
+In addition to the rules listed above, right now, this string only accepts directives that are explicitly supported by the tune CPU. For example, _"sifive-x280:prefer-w-inst"_ is not a valid string as `prefer-w-inst` is not supported by `sifive-x280` at this moment. Vendors of these processors are expected to maintain the compatibility of their supported directives across different versions. There have been lots of discussions on having "generic" features that are universally supported by all RISC-V CPUs, yet many concerns -- including the difficulty to maintain compatibility across _all_ CPU targets and versions -- make us decide to table this issue until we find a reliable process to select such features.
diff --git a/llvm/docs/SymbolizerMarkupFormat.md b/llvm/docs/SymbolizerMarkupFormat.md
index 2b9fa8df867dc..45ff11ca58c8e 100644
--- a/llvm/docs/SymbolizerMarkupFormat.md
+++ b/llvm/docs/SymbolizerMarkupFormat.md
@@ -189,131 +189,131 @@ human-readable symbolic form.
`{{{pc:%p}}}`, `{{{pc:%p:ra}}}`, `{{{pc:%p:pc}}}`
-> Here `%p` is the memory address of a code location. It might be presented as a
-> function name and source location. The second two forms distinguish the kind of
-> code location, as described in detail for bt elements below.
->
-> Examples:
->
-> ```
-> {{{pc:0x12345678}}}
-> {{{pc:0xffffffff9abcdef0}}}
-> ```
+: Here `%p` is the memory address of a code location. It might be presented as a
+ function name and source location. The second two forms distinguish the kind of
+ code location, as described in detail for bt elements below.
+
+ Examples:
+
+ ```
+ {{{pc:0x12345678}}}
+ {{{pc:0xffffffff9abcdef0}}}
+ ```
`{{{data:%p}}}`
-> Here `%p` is the memory address of a data location. It might be presented as
-> the name of a global variable at that location.
->
-> Examples:
->
-> ```
-> {{{data:0x12345678}}}
-> {{{data:0xffffffff9abcdef0}}}
-> ```
+: Here `%p` is the memory address of a data location. It might be presented as
+ the name of a global variable at that location.
+
+ Examples:
+
+ ```
+ {{{data:0x12345678}}}
+ {{{data:0xffffffff9abcdef0}}}
+ ```
`{{{bt:%u:%p}}}`, `{{{bt:%u:%p:ra}}}`, `{{{bt:%u:%p:pc}}}`
-> This represents one frame in a backtrace. It usually appears on a line by
-> itself (surrounded only by whitespace), in a sequence of such lines with
-> ascending frame numbers. So the human-readable output might be formatted
-> assuming that, such that it looks good for a sequence of bt elements each
-> alone on its line with uniform indentation of each line. But it can appear
-> anywhere, so the filter should not remove any non-whitespace text surrounding
-> the element.
->
-> Here `%u` is the frame number, which starts at zero for the location of the
-> fault being identified, increments to one for the caller of frame zero's call
-> frame, to two for the caller of frame one, etc. `%p` is the memory address
-> of a code location.
->
-> Code locations in a backtrace come from two distinct sources. Most backtrace
-> frames describe a return address code location, i.e. the instruction
-> immediately after a call instruction. This is the location of code that has
-> yet to run, since the function called there has not yet returned. Hence the
-> code location of actual interest is usually the call site itself rather than
-> the return address, i.e. one instruction earlier. When presenting the source
-> location for a return address frame, the symbolizing filter will subtract one
-> byte or one instruction length from the actual return address for the call
-> site, with the intent that the address logged can be translated directly to a
-> source location for the call site and not for the apparent return site
-> thereafter (which can be confusing). When inlined functions are involved, the
-> call site and the return site can appear to be in different functions at
-> entirely unrelated source locations rather than just a line away, making the
-> confusion of showing the return site rather the call site quite severe.
->
-> Often the first frame in a backtrace ("frame zero") identifies the precise
-> code location of a fault, trap, or asynchronous interrupt rather than a return
-> address. At other times, even the first frame is actually a return address
-> (for example, backtraces collected at the time of an object allocation and
-> reported later when the allocated object is used or misused). When a system
-> supports in-thread trap handling, there may also be frames after the first
-> that represent a precise interrupted code location rather than a return
-> address, presented as the "caller" of a trap handler function (for example,
-> signal handlers in POSIX systems).
->
-> Return address frames are identified by the `:ra` suffix. Precise code
-> location frames are identified by the `:pc` suffix.
->
-> Traditional practice has often been to collect backtraces as simple address
-> lists, losing the distinction between return address code locations and
-> precise code locations. Some such code applies the "subtract one" adjustment
-> described above to the address values before reporting them, and it's not
-> always clear or consistent whether this adjustment has been applied or not.
-> These ambiguous cases are supported by the `bt` and `pc` forms with no
-> `:ra` or `:pc` suffix, which indicate it's unclear which sort of code
-> location this is. However, it's highly recommended that all emitters use the
-> suffixed forms and deliver address values with no adjustments applied. When
-> traditional practice has been ambiguous, the majority of cases seem to have
-> been of printing addresses that are return address code locations and printing
-> them without adjustment. So the symbolizing filter will usually apply the
-> "subtract one byte" adjustment to an address printed without a disambiguating
-> suffix. Assuming that a call instruction is longer than one byte on all
-> supported machines, applying the "subtract one byte" adjustment a second time
-> still results in an address somewhere in the call instruction, so a little
-> sloppiness here often does little or no harm.
->
-> Examples:
->
-> ```
-> {{{bt:0:0x12345678:pc}}}
-> {{{bt:1:0xffffffff9abcdef0:ra}}}
-> ```
+: This represents one frame in a backtrace. It usually appears on a line by
+ itself (surrounded only by whitespace), in a sequence of such lines with
+ ascending frame numbers. So the human-readable output might be formatted
+ assuming that, such that it looks good for a sequence of bt elements each
+ alone on its line with uniform indentation of each line. But it can appear
+ anywhere, so the filter should not remove any non-whitespace text surrounding
+ the element.
+
+ Here `%u` is the frame number, which starts at zero for the location of the
+ fault being identified, increments to one for the caller of frame zero's call
+ frame, to two for the caller of frame one, etc. `%p` is the memory address
+ of a code location.
+
+ Code locations in a backtrace come from two distinct sources. Most backtrace
+ frames describe a return address code location, i.e. the instruction
+ immediately after a call instruction. This is the location of code that has
+ yet to run, since the function called there has not yet returned. Hence the
+ code location of actual interest is usually the call site itself rather than
+ the return address, i.e. one instruction earlier. When presenting the source
+ location for a return address frame, the symbolizing filter will subtract one
+ byte or one instruction length from the actual return address for the call
+ site, with the intent that the address logged can be translated directly to a
+ source location for the call site and not for the apparent return site
+ thereafter (which can be confusing). When inlined functions are involved, the
+ call site and the return site can appear to be in different functions at
+ entirely unrelated source locations rather than just a line away, making the
+ confusion of showing the return site rather the call site quite severe.
+
+ Often the first frame in a backtrace ("frame zero") identifies the precise
+ code location of a fault, trap, or asynchronous interrupt rather than a return
+ address. At other times, even the first frame is actually a return address
+ (for example, backtraces collected at the time of an object allocation and
+ reported later when the allocated object is used or misused). When a system
+ supports in-thread trap handling, there may also be frames after the first
+ that represent a precise interrupted code location rather than a return
+ address, presented as the "caller" of a trap handler function (for example,
+ signal handlers in POSIX systems).
+
+ Return address frames are identified by the `:ra` suffix. Precise code
+ location frames are identified by the `:pc` suffix.
+
+ Traditional practice has often been to collect backtraces as simple address
+ lists, losing the distinction between return address code locations and
+ precise code locations. Some such code applies the "subtract one" adjustment
+ described above to the address values before reporting them, and it's not
+ always clear or consistent whether this adjustment has been applied or not.
+ These ambiguous cases are supported by the `bt` and `pc` forms with no
+ `:ra` or `:pc` suffix, which indicate it's unclear which sort of code
+ location this is. However, it's highly recommended that all emitters use the
+ suffixed forms and deliver address values with no adjustments applied. When
+ traditional practice has been ambiguous, the majority of cases seem to have
+ been of printing addresses that are return address code locations and printing
+ them without adjustment. So the symbolizing filter will usually apply the
+ "subtract one byte" adjustment to an address printed without a disambiguating
+ suffix. Assuming that a call instruction is longer than one byte on all
+ supported machines, applying the "subtract one byte" adjustment a second time
+ still results in an address somewhere in the call instruction, so a little
+ sloppiness here often does little or no harm.
+
+ Examples:
+
+ ```
+ {{{bt:0:0x12345678:pc}}}
+ {{{bt:1:0xffffffff9abcdef0:ra}}}
+ ```
`{{{hexdict:...}}}` [^not-yet-implemented]
-> This element can span multiple lines. Here `...` is a sequence of key-value
-> pairs where a single `:` separates each key from its value, and arbitrary
-> whitespace separates the pairs. The value (right-hand side) of each pair
-> either is one or more `0` digits, or is `0x` followed by hexadecimal
-> digits. Each value might be a memory address or might be some other integer
-> (including an integer that looks like a likely memory address but actually has
-> an unrelated purpose). When the contextual information about the memory layout
-> suggests that a given value could be a code location or a global variable data
-> address, it might be presented as a source location or variable name or with
-> active UI that makes such interpretation optionally visible.
->
-> The intended use is for things like register dumps, where the emitter doesn't
-> know which values might have a symbolic interpretation but a presentation that
-> makes plausible symbolic interpretations available might be very useful to
-> someone reading the log. At the same time, a flat text presentation should
-> usually avoid interfering too much with the original contents and formatting
-> of the dump. For example, it might use footnotes with source locations for
-> values that appear to be code locations. An active UI presentation might show
-> the dump text as is, but highlight values with symbolic information available
-> and pop up a presentation of symbolic details when a value is selected.
->
-> Example:
->
-> ```
-> {{{hexdict:
-> CS: 0 RIP: 0x6ee17076fb80 EFL: 0x10246 CR2: 0
-> RAX: 0xc53d0acbcf0 RBX: 0x1e659ea7e0d0 RCX: 0 RDX: 0x6ee1708300cc
-> RSI: 0 RDI: 0x6ee170830040 RBP: 0x3b13734898e0 RSP: 0x3b13734898d8
-> R8: 0x3b1373489860 R9: 0x2776ff4f R10: 0x2749d3e9a940 R11: 0x246
-> R12: 0x1e659ea7e0f0 R13: 0xd7231230fd6ff2e7 R14: 0x1e659ea7e108 R15: 0xc53d0acbcf0
-> }}}
-> ```
+: This element can span multiple lines. Here `...` is a sequence of key-value
+ pairs where a single `:` separates each key from its value, and arbitrary
+ whitespace separates the pairs. The value (right-hand side) of each pair
+ either is one or more `0` digits, or is `0x` followed by hexadecimal
+ digits. Each value might be a memory address or might be some other integer
+ (including an integer that looks like a likely memory address but actually has
+ an unrelated purpose). When the contextual information about the memory layout
+ suggests that a given value could be a code location or a global variable data
+ address, it might be presented as a source location or variable name or with
+ active UI that makes such interpretation optionally visible.
+
+ The intended use is for things like register dumps, where the emitter doesn't
+ know which values might have a symbolic interpretation but a presentation that
+ makes plausible symbolic interpretations available might be very useful to
+ someone reading the log. At the same time, a flat text presentation should
+ usually avoid interfering too much with the original contents and formatting
+ of the dump. For example, it might use footnotes with source locations for
+ values that appear to be code locations. An active UI presentation might show
+ the dump text as is, but highlight values with symbolic information available
+ and pop up a presentation of symbolic details when a value is selected.
+
+ Example:
+
+ ```
+ {{{hexdict:
+ CS: 0 RIP: 0x6ee17076fb80 EFL: 0x10246 CR2: 0
+ RAX: 0xc53d0acbcf0 RBX: 0x1e659ea7e0d0 RCX: 0 RDX: 0x6ee1708300cc
+ RSI: 0 RDI: 0x6ee170830040 RBP: 0x3b13734898e0 RSP: 0x3b13734898d8
+ R8: 0x3b1373489860 R9: 0x2776ff4f R10: 0x2749d3e9a940 R11: 0x246
+ R12: 0x1e659ea7e0f0 R13: 0xd7231230fd6ff2e7 R14: 0x1e659ea7e108 R15: 0xc53d0acbcf0
+ }}}
+ ```
## Trigger elements
@@ -324,31 +324,31 @@ the external action can then be presented to the user.
`{{{dumpfile:%s:%s}}}` [^not-yet-implemented]
-> Here the first `%s` is an identifier for a type of dump and the second
-> `%s` is an identifier for a particular dump that's just been published. The
-> types of dumps, the exact meaning of "published", and the nature of the
-> identifier are outside the scope of the markup format per se. In general it
-> might correspond to writing a file by that name or something similar.
->
-> This element may trigger additional post-processing work beyond symbolizing
-> the markup. It indicates that a dump file of some sort has been published.
-> Some logic attached to the symbolizing filter may understand certain types of
-> dump file and trigger additional post-processing of the dump file upon
-> encountering this element (e.g. generating visualizations, symbolization). The
-> expectation is that the information collected from contextual elements
-> (described below) in the logging stream may be necessary to decode the content
-> of the dump. So if the symbolizing filter triggers other processing, it may
-> need to feed some distilled form of the contextual information to those
-> processes.
->
-> An example of a type identifier is `sancov`, for dumps from LLVM
-> [SanitizerCoverage](https://clang.llvm.org/docs/SanitizerCoverage.html).
->
-> Example:
->
-> ```
-> {{{dumpfile:sancov:sancov.8675}}}
-> ```
+: Here the first `%s` is an identifier for a type of dump and the second
+ `%s` is an identifier for a particular dump that's just been published. The
+ types of dumps, the exact meaning of "published", and the nature of the
+ identifier are outside the scope of the markup format per se. In general it
+ might correspond to writing a file by that name or something similar.
+
+ This element may trigger additional post-processing work beyond symbolizing
+ the markup. It indicates that a dump file of some sort has been published.
+ Some logic attached to the symbolizing filter may understand certain types of
+ dump file and trigger additional post-processing of the dump file upon
+ encountering this element (e.g. generating visualizations, symbolization). The
+ expectation is that the information collected from contextual elements
+ (described below) in the logging stream may be necessary to decode the content
+ of the dump. So if the symbolizing filter triggers other processing, it may
+ need to feed some distilled form of the contextual information to those
+ processes.
+
+ An example of a type identifier is `sancov`, for dumps from LLVM
+ [SanitizerCoverage](https://clang.llvm.org/docs/SanitizerCoverage.html).
+
+ Example:
+
+ ```
+ {{{dumpfile:sancov:sancov.8675}}}
+ ```
## Contextual elements
@@ -373,79 +373,75 @@ over the raw logging stream, accumulating context and massaging text as it goes.
`{{{reset}}}`
-> This should be output before any other contextual element. The need for this
-> contextual element is to support implementations that handle logs coming from
-> multiple processes. Such implementations might not know when a new process
-> starts or ends. Because some identifying information (like process IDs) might
-> be the same between old and new processes, a way is needed to distinguish two
-> processes with such identical identifying information. This element informs
-> such implementations to reset the state of a filter so that information from a
-> previous process's contextual elements is not assumed for new process that
-> just happens have the same identifying information.
+: This should be output before any other contextual element. The need for this
+ contextual element is to support implementations that handle logs coming from
+ multiple processes. Such implementations might not know when a new process
+ starts or ends. Because some identifying information (like process IDs) might
+ be the same between old and new processes, a way is needed to distinguish two
+ processes with such identical identifying information. This element informs
+ such implementations to reset the state of a filter so that information from a
+ previous process's contextual elements is not assumed for new process that
+ just happens have the same identifying information.
`{{{module:%i:%s:%s:...}}}`
-> This element represents a so-called "module". A "module" is a single linked
-> binary, such as a loaded ELF file. Usually each module occupies a contiguous
-> range of memory.
->
-> Here `%i` is the module ID which is used by other contextual elements to
-> refer to this module. The first `%s` is a human-readable identifier for the
-> module, such as an ELF `DT_SONAME` string or a file name; but it might be
-> empty. It's only for casual information. Only the module ID is used to refer
-> to this module in other contextual elements, never the `%s` string. The
-> `module` element defining a module ID must always be emitted before any
-> other elements that refer to that module ID, so that a filter never needs to
-> keep track of dangling references. The second `%s` is the module type and it
-> determines what the remaining fields are. The following module types are
-> supported:
->
-> - `elf:%x`
->
-> Here `%x` encodes an ELF Build ID. The Build ID should refer to a single
-> linked binary. The Build ID string is the sole way to identify the binary from
-> which this module was loaded.
->
-> Example:
->
-> ```
-> {{{module:1:libc.so:elf:83238ab56ba10497}}}
-> ```
+: This element represents a so-called "module". A "module" is a single linked
+ binary, such as a loaded ELF file. Usually each module occupies a contiguous
+ range of memory.
+
+ Here `%i` is the module ID which is used by other contextual elements to
+ refer to this module. The first `%s` is a human-readable identifier for the
+ module, such as an ELF `DT_SONAME` string or a file name; but it might be
+ empty. It's only for casual information. Only the module ID is used to refer
+ to this module in other contextual elements, never the `%s` string. The
+ `module` element defining a module ID must always be emitted before any
+ other elements that refer to that module ID, so that a filter never needs to
+ keep track of dangling references. The second `%s` is the module type and it
+ determines what the remaining fields are. The following module types are
+ supported:
+
+ - `elf:%x`
+
+ Here `%x` encodes an ELF Build ID. The Build ID should refer to a single
+ linked binary. The Build ID string is the sole way to identify the binary from
+ which this module was loaded.
+
+ Example:
+
+ ```
+ {{{module:1:libc.so:elf:83238ab56ba10497}}}
+ ```
`{{{mmap:%p:%i:...}}}`
-> This contextual element is used to give information about a particular region
-> in memory. `%p` is the starting address and `%i` gives the size in hex of the
-> region of memory. The `...` part can take different forms to give different
-> information about the specified region of memory. The allowed forms are the
-> following:
->
-> - `load:%i:%s:%p`
->
-> This subelement informs the filter that a segment was loaded from a module.
-> The module is identified by its module ID `%i`. The `%s` is one or more of
-> the letters 'r', 'w', and 'x' (in that order and in either upper or lower
-> case) to indicate this segment of memory is readable, writable, and/or
-> executable. The symbolizing filter can use this information to guess whether
-> an address is a likely code address or a likely data address in the given
-> module. The remaining `%p` gives the module relative address. For ELF files
-> the module relative address will be the `p_vaddr` of the associated program
-> header. For example if your module's executable segment has
-> `p_vaddr=0x1000`, `p_memsz=0x1234`, and was loaded at `0x7acba69d5000`
-> then you need to subtract `0x7acba69d4000` from any address between
-> `0x7acba69d5000` and `0x7acba69d6234` to get the module relative address.
-> The starting address will usually have been rounded down to the active page
-> size, and the size rounded up.
->
-> Example:
->
-> ```
-> {{{mmap:0x7acba69d5000:0x5a000:load:1:rx:0x1000}}}
-> ```
-
-```{rubric} Footnotes
-```
+: This contextual element is used to give information about a particular region
+ in memory. `%p` is the starting address and `%i` gives the size in hex of the
+ region of memory. The `...` part can take different forms to give different
+ information about the specified region of memory. The allowed forms are the
+ following:
+
+ - `load:%i:%s:%p`
+
+ This subelement informs the filter that a segment was loaded from a module.
+ The module is identified by its module ID `%i`. The `%s` is one or more of
+ the letters 'r', 'w', and 'x' (in that order and in either upper or lower
+ case) to indicate this segment of memory is readable, writable, and/or
+ executable. The symbolizing filter can use this information to guess whether
+ an address is a likely code address or a likely data address in the given
+ module. The remaining `%p` gives the module relative address. For ELF files
+ the module relative address will be the `p_vaddr` of the associated program
+ header. For example if your module's executable segment has
+ `p_vaddr=0x1000`, `p_memsz=0x1234`, and was loaded at `0x7acba69d5000`
+ then you need to subtract `0x7acba69d4000` from any address between
+ `0x7acba69d5000` and `0x7acba69d6234` to get the module relative address.
+ The starting address will usually have been rounded down to the active page
+ size, and the size rounded up.
+
+ Example:
+
+ ```
+ {{{mmap:0x7acba69d5000:0x5a000:load:1:rx:0x1000}}}
+ ```
[^not-yet-implemented]: This markup element is not yet implemented in
{doc}`llvm-symbolizer <CommandGuide/llvm-symbolizer>`.
-
diff --git a/llvm/docs/Telemetry.md b/llvm/docs/Telemetry.md
index 52e4a6af2b17e..27481e2a9e7ab 100644
--- a/llvm/docs/Telemetry.md
+++ b/llvm/docs/Telemetry.md
@@ -1,8 +1,8 @@
# Telemetry framework in LLVM
-```{toctree}
-:hidden: true
-```
+:::{toctree}
+:hidden:
+:::
## Objective
@@ -245,4 +245,3 @@ Manager->logStartup(&Entry);
```
Similar code can be used for logging the tool's exit.
-
diff --git a/llvm/docs/yaml2obj.md b/llvm/docs/yaml2obj.md
index cc2f6fae1a5a5..d64c3c46de4e5 100644
--- a/llvm/docs/yaml2obj.md
+++ b/llvm/docs/yaml2obj.md
@@ -3,10 +3,8 @@
yaml2obj takes a YAML description of an object file and converts it to a binary
file.
-> \$ yaml2obj input-file
-
-```{eval-rst}
-.. program:: yaml2obj
+```console
+$ yaml2obj input-file
```
Outputs the binary to stdout.
@@ -274,4 +272,3 @@ type: map
```
[kwalify]: http://www.kuwata-lab.com/kwalify/ruby/users-guide.html
-
>From be9c54c96ea3e7431b5d55623fa383bc6999e327 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Fri, 7 Aug 2026 18:39:15 +0000
Subject: [PATCH 3/3] [docs] Fix LLVM markdown migration defects
---
llvm/docs/CodeOfConduct.md | 11 ++++++-----
llvm/docs/LFI.md | 6 +++---
llvm/docs/OpaquePointers.md | 3 +--
llvm/docs/PDB/index.md | 14 +++++++-------
llvm/docs/RISCVUsage.md | 3 +++
llvm/docs/ReportingGuide.md | 11 +++++------
llvm/docs/ResponseGuide.md | 31 +++++++++++++++----------------
7 files changed, 40 insertions(+), 39 deletions(-)
diff --git a/llvm/docs/CodeOfConduct.md b/llvm/docs/CodeOfConduct.md
index 9dab7304be11c..bb02888b82174 100644
--- a/llvm/docs/CodeOfConduct.md
+++ b/llvm/docs/CodeOfConduct.md
@@ -2,6 +2,7 @@
% SPDX-License-Identifier: CC-BY-3.0
(llvm-community-code-of-conduct)=
+(llvm community code of conduct)=
# LLVM Community Code of Conduct
@@ -44,7 +45,7 @@ cases, affect a person's ability to participate within them, when the conduct
amounts to an egregious violation of this code.
If you believe someone is violating the code of conduct, we ask that you report
-it by emailing <mailto:conduct at llvm.org>. For more details please see the
+it by emailing [conduct at llvm.org](mailto:conduct at llvm.org). For more details please see the
{doc}`Reporting Guide <ReportingGuide>`.
(be-friendly-and-patient)=
@@ -112,7 +113,7 @@ it by emailing <mailto:conduct at llvm.org>. For more details please see the
If you believe someone is violating the code of conduct you can always report
it to the LLVM Foundation Code of Conduct Committee by emailing
-<mailto:conduct at llvm.org>. All reports will be kept confidential. This isn't a public
+[conduct at llvm.org](mailto:conduct at llvm.org). All reports will be kept confidential. This isn't a public
list and only members of the advisory committee will receive the report. For
details on what to include in the report, please see the {doc}`Reporting Guide
<ReportingGuide>`.
@@ -129,7 +130,7 @@ able to help. If you cannot find one of the organizers, the venue staff can
locate one for you. We will also post detailed contact information for specific
events as part of each events' information. In person reports will still be
kept confidential exactly as above, but also feel free to (anonymously if
-needed) email <mailto:conduct at llvm.org>.
+needed) email [conduct at llvm.org](mailto:conduct at llvm.org).
## Bans
@@ -139,7 +140,7 @@ community members from having to interact with people who are consistently not
respecting the code of conduct. Please refer to the
{doc}`Developer Policy<DeveloperPolicy>` section on Bans for how to handle
interactions with former community members. If you need further guidance,
-please contact <mailto:conduct at llvm.org>.
+please contact [conduct at llvm.org](mailto:conduct at llvm.org).
## Code of Conduct Committee
@@ -174,7 +175,7 @@ For details about what a Transparency Report is and what it contains, please see
## Questions?
If you have questions, please feel free to contact the LLVM Foundation Code of
-Conduct Committee by emailing <mailto:conduct at llvm.org>.
+Conduct Committee by emailing [conduct at llvm.org](mailto:conduct at llvm.org).
## Thanks!
diff --git a/llvm/docs/LFI.md b/llvm/docs/LFI.md
index 4cf2ac2a03107..9f920981fa04d 100644
--- a/llvm/docs/LFI.md
+++ b/llvm/docs/LFI.md
@@ -716,6 +716,6 @@ For more information, please see the following resources:
Contact info:
-- Zachary Yedidia - <mailto:zyedidia at cs.stanford.edu>
-- Tal Garfinkel - <mailto:tgarfinkel at google.com>
-- Sharjeel Khan - <mailto:sharjeelkhan at google.com>
+- Zachary Yedidia - [zyedidia at cs.stanford.edu](mailto:zyedidia at cs.stanford.edu)
+- Tal Garfinkel - [tgarfinkel at google.com](mailto:tgarfinkel at google.com)
+- Sharjeel Khan - [sharjeelkhan at google.com](mailto:sharjeelkhan at google.com)
diff --git a/llvm/docs/OpaquePointers.md b/llvm/docs/OpaquePointers.md
index 4319de96f8582..f455806dfde02 100644
--- a/llvm/docs/OpaquePointers.md
+++ b/llvm/docs/OpaquePointers.md
@@ -31,7 +31,7 @@ Address spaces are still used to distinguish between different kinds of pointers
where the distinction is relevant for lowering (e.g. data vs function pointers
have different sizes on some architectures). Opaque pointers are not changing
anything related to address spaces and lowering. For more information, see
-[DataLayout](LangRef.html#langref-datalayout). Opaque pointers in non-default
+{ref}`DataLayout <langref_datalayout>`. Opaque pointers in non-default
address space are spelled `ptr addrspace(N)`.
This was proposed all the way back in
@@ -282,4 +282,3 @@ The following typed pointer functionality has been removed:
The following typed pointer functionality is still to be removed:
- Various APIs that are no longer relevant with opaque pointers.
-
diff --git a/llvm/docs/PDB/index.md b/llvm/docs/PDB/index.md
index d2a5c31cafe1e..e1355a22e41d0 100644
--- a/llvm/docs/PDB/index.md
+++ b/llvm/docs/PDB/index.md
@@ -155,28 +155,28 @@ PDB file is as follows:
More information about the structure of each of these can be found on the
following pages:
-{doc}`PdbStream <PdbStream>`
+{doc}`PdbStream`
: Information about the PDB Info Stream and how it is used to match PDBs to EXEs.
-{doc}`TpiStream <TpiStream>`
+{doc}`TpiStream`
: Information about the TPI stream and the CodeView records contained within.
-{doc}`DbiStream <DbiStream>`
+{doc}`DbiStream`
: Information about the DBI stream and relevant substreams including the
Module Substreams, source file information, and CodeView symbol records
contained within.
-{doc}`ModiStream <ModiStream>`
+{doc}`ModiStream`
: Information about the Module Information Stream, of which there is one for
each compilation unit and the format of symbols contained within.
-{doc}`PublicStream <PublicStream>`
+{doc}`PublicStream`
: Information about the Public Symbol Stream.
-{doc}`GlobalStream <GlobalStream>`
+{doc}`GlobalStream`
: Information about the Global Symbol Stream.
-{doc}`HashTable <HashTable>`
+{doc}`HashTable`
: Information about the serialized hash table format used internally to
represent things such as the Named Stream Map and the Hash Adjusters in the
{doc}`TPI/IPI Stream <TpiStream>`.
diff --git a/llvm/docs/RISCVUsage.md b/llvm/docs/RISCVUsage.md
index 43a8dd4a68712..54974f1c90a28 100644
--- a/llvm/docs/RISCVUsage.md
+++ b/llvm/docs/RISCVUsage.md
@@ -48,11 +48,14 @@ RV64E are supported by the assembly-based tools only. RV128I is not supported.
To specify the target triple:
+:::{table} RISC-V Architectures
| Architecture | Description |
| ------------ | ----------- |
| `riscv32` | RISC-V with XLEN=32 (i.e. RV32I or RV32E) |
| `riscv64` | RISC-V with XLEN=64 (i.e. RV64I or RV64E) |
+:::
+
To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
architecture string (e.g. `riscv32`) with the extension `e`.
diff --git a/llvm/docs/ReportingGuide.md b/llvm/docs/ReportingGuide.md
index 05ed77786e708..bd8e42408fc3b 100644
--- a/llvm/docs/ReportingGuide.md
+++ b/llvm/docs/ReportingGuide.md
@@ -21,7 +21,7 @@ processes surrounding it.
- For any incident involving an online platform (e.g., mailing lists, forums,
irc/discord/slack, etc) we ask that you make any reports by emailing
- <mailto:conduct at llvm.org>. This is received by all members of the CoC Committee.
+ [conduct at llvm.org](mailto:conduct at llvm.org). This is received by all members of the CoC Committee.
- For LLVM Developers' Meetings, please file a report with the on-site Code
of Conduct team. Their names and contact details are listed on the event
webpage. You can also approach any other staff member, who can be
@@ -30,11 +30,11 @@ processes surrounding it.
reported in-person at a LLVM Developers' Meeting will be emailed to the
Code of Conduct Committee.
- For meetups, please report the incident to the local meetup organizers first
- and then email <mailto:conduct at llvm.org> with your report. Each meetup will have a
+ and then email [conduct at llvm.org](mailto:conduct at llvm.org) with your report. Each meetup will have a
contact listed on the associated meetup page. If you feel the incident was
not well handled by the local organizers, please include this information in
- your email to <mailto:conduct at llvm.org>. All meetup organizers who receive an
- in-person report are also asked to email <mailto:conduct at llvm.org> with the
+ your email to [conduct at llvm.org](mailto:conduct at llvm.org). All meetup organizers who receive an
+ in-person report are also asked to email [conduct at llvm.org](mailto:conduct at llvm.org) with the
incident information.
If you believe anyone is in physical danger, please notify appropriate law
@@ -44,7 +44,7 @@ them.
## Guidelines for Reporting Incidents
-Please email <mailto:conduct at llvm.org> with the following details (if possible):
+Please email [conduct at llvm.org](mailto:conduct at llvm.org) with the following details (if possible):
- Your contact info (so we can get in touch with you). Include email and
optionally a phone number.
@@ -105,4 +105,3 @@ Unported License][creative commons attribution 3.0 unported license].
[creative commons attribution 3.0 unported license]: http://creativecommons.org/licenses/by/3.0/
[django project]: https://www.djangoproject.com/conduct/
[write the docs response guide]: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
-
diff --git a/llvm/docs/ResponseGuide.md b/llvm/docs/ResponseGuide.md
index 7d32eafe02658..0292db41b5c27 100644
--- a/llvm/docs/ResponseGuide.md
+++ b/llvm/docs/ResponseGuide.md
@@ -22,15 +22,15 @@ to an incident. For example:
will have a code of conduct response team or point of contact for CoC
reports.
-These teams should determine if an {ref}`immediate response<Immediate Response
-Checklist>` is needed before sending the report to the Code of Conduct
+These teams should determine if an {ref}`immediate response <immediate-response-checklist>`
+is needed before sending the report to the Code of Conduct
committee.
(receiving-a-report)=
## Receiving a Report
-Reports are typically received by email (<mailto:conduct at llvm.org>) or in person from
+Reports are typically received by email ([conduct at llvm.org](mailto:conduct at llvm.org)) or in person from
the reporter or event CoC response team.
When receiving a report by email, the CoC Committee should acknowledge receipt
@@ -71,22 +71,21 @@ committee within 24 hours.
The following is a summary of the steps the committee takes when responding to
a reported incident.
-1. Determine if there is a need for an {ref}`immediate response<Immediate
- Response Checklist>`.
-2. {ref}`Acknowledge the report<Receiving a report>` within 24 hours.
-3. {ref}`Discuss the incident report<Incident Response Assessment>`, gather
- more information, and determine a {ref}`resolution<Resolutions>`.
+1. Determine if there is a need for an {ref}`immediate response <immediate-response-checklist>`.
+2. {ref}`Acknowledge the report <receiving-a-report>` within 24 hours.
+3. {ref}`Discuss the incident report <incident-response-assessment>`, gather
+ more information, and determine a {ref}`resolution <resolutions>`.
4. During this process, the {ref}`reporter will be informed of the
- resolution<Following Up With the Reportee>` and feedback is requested. This
+ resolution <following-up-with-the-reportee>` and feedback is requested. This
feedback may or may not be used to re-evaluate the resolution.
5. Inform the reportee of the resolution. The reportee is provided options to
- {ref}`appeal<Appeal Process>`.
-6. The {ref}`resolution<Resolutions>` is implemented.
+ {ref}`appeal <appeal-process>`.
+6. The {ref}`resolution <resolutions>` is implemented.
7. All reports, data, notes, and resolutions are logged in a private location
(e.g., Google Drive or other database).
The committee will never make public statements about a resolution and will
-only publish {ref}`transparency reports<Transparency Reports>`. If a public
+only publish {ref}`transparency reports <transparency-reports>`. If a public
statement is necessary and requested by the committee, it will be given by the
LLVM Foundation Board of Directors.
@@ -178,8 +177,9 @@ taken, but below is a list of possible resolutions:
- Request that the reportee avoid any interaction with, and physical proximity
to, another person for the remainder of the event.
- Refusal of alcoholic beverage purchases by the reportee at LLVM events.
-- Ending a talk/tutorial/etc at an LLVM event early. See immediate response
- checklist for further clarification.
+- Ending a talk/tutorial/etc at an LLVM event early. See
+ [immediate response checklist](#immediate-response-checklist) for further
+ clarification.
- Not publishing the video or slides of a talk.
- Not allowing a speaker to give (further) talks at LLVM events for a specified
amount of time or ever.
@@ -203,7 +203,7 @@ feedback.
Any individual(s) determined to have violated the CoC have the right to appeal
a resolution decision. An appeal can be made directly to the committee by sending an
-email to <mailto:conduct at llvm.org> with subject line Code of Conduct Incident Appeal.
+email to [conduct at llvm.org](mailto:conduct at llvm.org) with subject line Code of Conduct Incident Appeal.
This process is intended to consider new or different evidence from the
initial incident investigation. The email should include documentation related
@@ -287,4 +287,3 @@ Unported License][creative commons attribution 3.0 unported license].
[creative commons attribution 3.0 unported license]: http://creativecommons.org/licenses/by/3.0/
[django project]: https://www.djangoproject.com/conduct/
[write the docs response guide]: https://www.writethedocs.org/code-of-conduct/#guidelines-for-reporting-incidents
-
More information about the llvm-branch-commits
mailing list