summaryrefslogtreecommitdiff
path: root/llvm/docs
diff options
context:
space:
mode:
Diffstat (limited to 'llvm/docs')
-rw-r--r--llvm/docs/DirectX/DXILResources.rst199
-rw-r--r--llvm/docs/GettingStarted.rst14
-rw-r--r--llvm/docs/ProgrammersManual.rst6
-rw-r--r--llvm/docs/RISCVUsage.rst12
-rw-r--r--llvm/docs/ReleaseNotes.md8
-rw-r--r--llvm/docs/TableGen/BackEnds.rst2
6 files changed, 191 insertions, 50 deletions
diff --git a/llvm/docs/DirectX/DXILResources.rst b/llvm/docs/DirectX/DXILResources.rst
index 3971d3788b8a..857d29e48363 100644
--- a/llvm/docs/DirectX/DXILResources.rst
+++ b/llvm/docs/DirectX/DXILResources.rst
@@ -274,39 +274,87 @@ Examples:
@llvm.dx.handle.fromHeap.tdx.RawBuffer_v4f32_1_0(
i32 2, i1 false)
-16-byte Loads, Samples, and Gathers
------------------------------------
-
-*relevant types: TypedBuffer, CBuffer, and Textures*
-
-TypedBuffer, CBuffer, and Texture loads, as well as samples and gathers, can
-return 1 to 4 elements from the given resource, to a maximum of 16 bytes of
-data. DXIL's modeling of this is influenced by DirectX and DXBC's history and
-it generally treats these operations as returning 4 32-bit values. For 16-bit
-elements the values are 16-bit values, and for 64-bit values the operations
-return 4 32-bit integers and emit further code to construct the double.
-
-In DXIL, these operations return `ResRet`_ and `CBufRet`_ values, are structs
-containing 4 elements of the same type, and in the case of `ResRet` a 5th
-element that is used by the `CheckAccessFullyMapped`_ operation.
-
-In LLVM IR the intrinsics will return the contained type of the resource
-instead. That is, ``llvm.dx.resource.load.typedbuffer`` from a
-``Buffer<float>`` would return a single float, from ``Buffer<float4>`` a vector
-of 4 floats, and from ``Buffer<double2>`` a vector of two doubles, etc. The
-operations are then expanded out to match DXIL's format during lowering.
-
-In cases where we need ``CheckAccessFullyMapped``, we have a second intrinsic
-that returns an anonymous struct with element-0 being the contained type, and
-element-1 being the ``i1`` result of a ``CheckAccessFullyMapped`` call. We
-don't have a separate call to ``CheckAccessFullyMapped`` at all, since that's
-the only operation that can possibly be done on this value. In practice this
-may mean we insert a DXIL operation for the check when this was missing in the
-HLSL source, but this actually matches DXC's behaviour in practice.
+Accessing Resources as Memory
+-----------------------------
+
+*relevant types: Buffers, CBuffer, and Textures*
+
+Loading and storing from resources is generally represented in LLVM using
+operations on memory that is only accessible via a handle object. Given a
+handle, `llvm.dx.resource.getpointer` gives a pointer that can be used to read
+and (depending on type) write to the resource.
+
+Accesses using `llvm.dx.resource.getpointer` are replaced with direct load and
+store operations in the `DXILResourceAccess` pass. These direct loads and
+stores are described later in this document.
+
+.. note:: Currently the pointers returned by `dx.resource.getpointer` are in
+ the default address space, but that will likely change in the future.
+
+.. list-table:: ``@llvm.dx.resource.getpointer``
+ :header-rows: 1
+
+ * - Argument
+ -
+ - Type
+ - Description
+ * - Return value
+ -
+ - Pointer
+ - A pointer to an object in the buffer
+ * - ``%buffer``
+ - 0
+ - ``target(dx.TypedBuffer, ...)``
+ - The buffer to access
+ * - ``%index``
+ - 1
+ - ``i32``
+ - Index into the buffer
+
+Examples:
+
+.. code-block:: llvm
+
+ %ptr = call ptr @llvm.dx.resource.getpointer.p0.tdx.TypedBuffer_v4f32_0_0_0t(
+ target("dx.TypedBuffer", <4 x float>, 0, 0, 0) %buffer, i32 %index)
+
+Loads, Samples, and Gathers
+---------------------------
+
+*relevant types: Buffers, CBuffers, and Textures*
+
+All load, sample, and gather operations in DXIL return a `ResRet`_ type, and
+CBuffer loads return a similar `CBufRet`_ type. These types are structs
+containing 4 elements of some basic type, and in the case of `ResRet` a 5th
+element that is used by the `CheckAccessFullyMapped`_ operation. Some of these
+operations, like `RawBufferLoad`_ include a mask and/or alignment that tell us
+some information about how to interpret those four values.
+
+In the LLVM IR representations of these operations we instead return scalars or
+vectors, but we keep the requirement that we only return up to 4 elements of a
+basic type. This avoids some unnecessary casting and structure manipulation in
+the intermediate format while also keeping lowering to DXIL straightforward.
+
+LLVM intrinsics that map to operations returning `ResRet` return an anonymous
+struct with element-0 being the scalar or vector type, and element-1 being the
+``i1`` result of a ``CheckAccessFullyMapped`` call. We don't have a separate
+call to ``CheckAccessFullyMapped`` at all, since that's the only operation that
+can possibly be done on this value. In practice this may mean we insert a DXIL
+operation for the check when this was missing in the HLSL source, but this
+actually matches DXC's behaviour in practice.
+
+For TypedBuffer and Texture, we map directly from the contained type of the
+resource to the return value of the intrinsic. Since these resources are
+constrained to contain only scalars and vectors of up to 4 elements, the
+lowering to DXIL ops is generally straightforward. The one exception we have
+here is that `double` types in the elements are special - these are allowed in
+the LLVM intrinsics, but are lowered to pairs of `i32` followed by
+``MakeDouble`` operations for DXIL.
.. _ResRet: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#resource-operation-return-types
.. _CBufRet: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#cbufferloadlegacy
.. _CheckAccessFullyMapped: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/checkaccessfullymapped
+.. _RawBufferLoad: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#rawbufferload
.. list-table:: ``@llvm.dx.resource.load.typedbuffer``
:header-rows: 1
@@ -317,8 +365,8 @@ HLSL source, but this actually matches DXC's behaviour in practice.
- Description
* - Return value
-
- - The contained type of the buffer
- - The data loaded from the buffer
+ - A structure of the contained type and the check bit
+ - The data loaded from the buffer and the check bit
* - ``%buffer``
- 0
- ``target(dx.TypedBuffer, ...)``
@@ -332,23 +380,32 @@ Examples:
.. code-block:: llvm
- %ret = call <4 x float>
+ %ret = call {<4 x float>, i1}
@llvm.dx.resource.load.typedbuffer.v4f32.tdx.TypedBuffer_v4f32_0_0_0t(
target("dx.TypedBuffer", <4 x float>, 0, 0, 0) %buffer, i32 %index)
- %ret = call float
+ %ret = call {float, i1}
@llvm.dx.resource.load.typedbuffer.f32.tdx.TypedBuffer_f32_0_0_0t(
target("dx.TypedBuffer", float, 0, 0, 0) %buffer, i32 %index)
- %ret = call <4 x i32>
+ %ret = call {<4 x i32>, i1}
@llvm.dx.resource.load.typedbuffer.v4i32.tdx.TypedBuffer_v4i32_0_0_0t(
target("dx.TypedBuffer", <4 x i32>, 0, 0, 0) %buffer, i32 %index)
- %ret = call <4 x half>
+ %ret = call {<4 x half>, i1}
@llvm.dx.resource.load.typedbuffer.v4f16.tdx.TypedBuffer_v4f16_0_0_0t(
target("dx.TypedBuffer", <4 x half>, 0, 0, 0) %buffer, i32 %index)
- %ret = call <2 x double>
+ %ret = call {<2 x double>, i1}
@llvm.dx.resource.load.typedbuffer.v2f64.tdx.TypedBuffer_v2f64_0_0t(
target("dx.TypedBuffer", <2 x double>, 0, 0, 0) %buffer, i32 %index)
-.. list-table:: ``@llvm.dx.resource.loadchecked.typedbuffer``
+For RawBuffer, an HLSL load operation may return an arbitrarily sized result,
+but we still constrain the LLVM intrinsic to return only up to 4 elements of a
+basic type. This means that larger loads are represented as a series of loads,
+which matches DXIL. Unlike in the `RawBufferLoad`_ operation, we do not need
+arguments for the mask/type size and alignment, since we can calculate these
+from the return type of the load during lowering.
+
+.. _RawBufferLoad: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#rawbufferload
+
+.. list-table:: ``@llvm.dx.resource.load.rawbuffer``
:header-rows: 1
* - Argument
@@ -357,22 +414,82 @@ Examples:
- Description
* - Return value
-
- - A structure of the contained type and the check bit
+ - A structure of a scalar or vector and the check bit
- The data loaded from the buffer and the check bit
* - ``%buffer``
- 0
- - ``target(dx.TypedBuffer, ...)``
+ - ``target(dx.RawBuffer, ...)``
- The buffer to load from
* - ``%index``
- 1
- ``i32``
- Index into the buffer
+ * - ``%offset``
+ - 2
+ - ``i32``
+ - Offset into the structure at the given index
+
+Examples:
.. code-block:: llvm
+ ; float
+ %ret = call {float, i1}
+ @llvm.dx.resource.load.rawbuffer.f32.tdx.RawBuffer_f32_0_0_0t(
+ target("dx.RawBuffer", float, 0, 0, 0) %buffer,
+ i32 %index,
+ i32 0)
+ %ret = call {float, i1}
+ @llvm.dx.resource.load.rawbuffer.f32.tdx.RawBuffer_i8_0_0_0t(
+ target("dx.RawBuffer", i8, 0, 0, 0) %buffer,
+ i32 %byte_offset,
+ i32 0)
+
+ ; float4
%ret = call {<4 x float>, i1}
- @llvm.dx.resource.loadchecked.typedbuffer.v4f32.tdx.TypedBuffer_v4f32_0_0_0t(
- target("dx.TypedBuffer", <4 x float>, 0, 0, 0) %buffer, i32 %index)
+ @llvm.dx.resource.load.rawbuffer.v4f32.tdx.RawBuffer_v4f32_0_0_0t(
+ target("dx.RawBuffer", float, 0, 0, 0) %buffer,
+ i32 %index,
+ i32 0)
+ %ret = call {float, i1}
+ @llvm.dx.resource.load.rawbuffer.v4f32.tdx.RawBuffer_i8_0_0_0t(
+ target("dx.RawBuffer", i8, 0, 0, 0) %buffer,
+ i32 %byte_offset,
+ i32 0)
+
+ ; struct S0 { float4 f; int4 i; };
+ %ret = call {<4 x float>, i1}
+ @llvm.dx.resource.load.rawbuffer.v4f32.tdx.RawBuffer_sl_v4f32v4i32s_0_0t(
+ target("dx.RawBuffer", {<4 x float>, <4 x i32>}, 0, 0, 0) %buffer,
+ i32 %index,
+ i32 0)
+ %ret = call {<4 x i32>, i1}
+ @llvm.dx.resource.load.rawbuffer.v4i32.tdx.RawBuffer_sl_v4f32v4i32s_0_0t(
+ target("dx.RawBuffer", {<4 x float>, <4 x i32>}, 0, 0, 0) %buffer,
+ i32 %index,
+ i32 1)
+
+ ; struct Q { float4 f; int3 i; }
+ ; struct R { int z; S x; }
+ %ret = call {i32, i1}
+ @llvm.dx.resource.load.rawbuffer.i32(
+ target("dx.RawBuffer", {i32, {<4 x float>, <3 x i32>}}, 0, 0, 0)
+ %buffer, i32 %index, i32 0)
+ %ret = call {<4 x float>, i1}
+ @llvm.dx.resource.load.rawbuffer.i32(
+ target("dx.RawBuffer", {i32, {<4 x float>, <3 x i32>}}, 0, 0, 0)
+ %buffer, i32 %index, i32 4)
+ %ret = call {<3 x i32>, i1}
+ @llvm.dx.resource.load.rawbuffer.i32(
+ target("dx.RawBuffer", {i32, {<4 x float>, <3 x i32>}}, 0, 0, 0)
+ %buffer, i32 %index, i32 20)
+
+ ; byteaddressbuf.Load<int64_t4>
+ %ret = call {<4 x i64>, i1}
+ @llvm.dx.resource.load.rawbuffer.v4i64.tdx.RawBuffer_i8_0_0t(
+ target("dx.RawBuffer", i8, 0, 0, 0) %buffer,
+ i32 %byte_offset,
+ i32 0)
Texture and Typed Buffer Stores
-------------------------------
diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index 7f4b62f63957..7f73b61e11dd 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -233,12 +233,13 @@ Hardware
LLVM is known to work on the following host platforms:
-================== ===================== =============
+================== ===================== ==============================
OS Arch Compilers
-================== ===================== =============
+================== ===================== ==============================
Linux x86\ :sup:`1` GCC, Clang
Linux amd64 GCC, Clang
Linux ARM GCC, Clang
+Linux AArch64 GCC, Clang
Linux Mips GCC, Clang
Linux PowerPC GCC, Clang
Linux SystemZ GCC, Clang
@@ -246,16 +247,19 @@ Solaris V9 (Ultrasparc) GCC
DragonFlyBSD amd64 GCC, Clang
FreeBSD x86\ :sup:`1` GCC, Clang
FreeBSD amd64 GCC, Clang
+FreeBSD AArch64 GCC, Clang
NetBSD x86\ :sup:`1` GCC, Clang
NetBSD amd64 GCC, Clang
OpenBSD x86\ :sup:`1` GCC, Clang
OpenBSD amd64 GCC, Clang
macOS\ :sup:`2` PowerPC GCC
macOS x86 GCC, Clang
+macOS arm64 Clang
Cygwin/Win32 x86\ :sup:`1, 3` GCC
Windows x86\ :sup:`1` Visual Studio
-Windows x64 x86-64 Visual Studio
-================== ===================== =============
+Windows x64 x86-64 Visual Studio, Clang\ :sup:`4`
+Windows on Arm ARM64 Visual Studio, Clang\ :sup:`4`
+================== ===================== ==============================
.. note::
@@ -263,6 +267,8 @@ Windows x64 x86-64 Visual Studio
#. Code generation supported for 32-bit ABI only
#. To use LLVM modules on Win32-based system, you may configure LLVM
with ``-DBUILD_SHARED_LIBS=On``.
+ #. Visual Studio alone can compile LLVM. When using Clang, you
+ must also have Visual Studio installed.
Note that Debug builds require a lot of time and disk space. An LLVM-only build
will need about 1-3 GB of space. A full build of LLVM and Clang will need around
diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst
index 98803ddffd08..e2829eb5a884 100644
--- a/llvm/docs/ProgrammersManual.rst
+++ b/llvm/docs/ProgrammersManual.rst
@@ -3358,15 +3358,15 @@ the ``PassManager.h`` system, and there is a more detailed introduction to it
by Sean Parent in several of his talks and papers:
#. `Inheritance Is The Base Class of Evil
- <http://channel9.msdn.com/Events/GoingNative/2013/Inheritance-Is-The-Base-Class-of-Evil>`_
+ <https://learn.microsoft.com/en-us/shows/goingnative-2013/inheritance-base-class-of-evil>`_
- The GoingNative 2013 talk describing this technique, and probably the best
place to start.
#. `Value Semantics and Concepts-based Polymorphism
<http://www.youtube.com/watch?v=_BpMYeUFXv8>`_ - The C++Now! 2012 talk
describing this technique in more detail.
#. `Sean Parent's Papers and Presentations
- <http://github.com/sean-parent/sean-parent.github.com/wiki/Papers-and-Presentations>`_
- - A GitHub project full of links to slides, video, and sometimes code.
+ <https://sean-parent.stlab.cc/papers-and-presentations>`_
+ - Links to slides, videos, and sometimes code.
When deciding between creating a type hierarchy (with either tagged or virtual
dispatch) and using templates or concepts-based polymorphism, consider whether
diff --git a/llvm/docs/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst
index f6a0dd4bf238..0dc63f34806b 100644
--- a/llvm/docs/RISCVUsage.rst
+++ b/llvm/docs/RISCVUsage.rst
@@ -326,6 +326,9 @@ The primary goal of experimental support is to assist in the process of ratifica
``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-sdext``, ``experimental-sdtrig``
+ LLVM implements the `1.0-rc4 specification <https://github.com/riscv/riscv-debug-spec/releases/download/1.0.0-rc4/riscv-debug-specification.pdf>`__.
+
``experimental-smctr``, ``experimental-ssctr``
LLVM implements the `1.0-rc3 specification <https://github.com/riscv/riscv-control-transfer-records/releases/tag/v1.0_rc3>`__.
@@ -429,6 +432,15 @@ The current vendor extensions supported are:
``experimental-Xqcia``
LLVM implements `version 0.2 of the Qualcomm uC Arithmetic extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32.
+``experimental-Xqciac``
+ LLVM implements `version 0.2 of the Qualcomm uC Load-Store Address Calculation extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32.
+
+``experimental-Xqcicli``
+ LLVM implements `version 0.2 of the Qualcomm uC Conditional Load Immediate extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32.
+
+``experimental-Xqcicm``
+ LLVM implements `version 0.2 of the Qualcomm uC Conditional Move extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32.
+
``experimental-Xqcics``
LLVM implements `version 0.2 of the Qualcomm uC Conditional Select extension specification <https://github.com/quic/riscv-unified-db/releases/latest>`__ by Qualcomm. All instructions are prefixed with `qc.` as described in the specification. These instructions are only available for riscv32.
diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md
index 5999f78f7e06..3463dc8339fd 100644
--- a/llvm/docs/ReleaseNotes.md
+++ b/llvm/docs/ReleaseNotes.md
@@ -198,6 +198,7 @@ Changes to the RISC-V Backend
* `-mcpu=syntacore-scr7` was added.
* `-mcpu=tt-ascalon-d8` was added.
* `-mcpu=mips-p8700` was added.
+* `-mcpu=sifive-p550` was added.
* The `Zacas` extension is no longer marked as experimental.
* Added Smdbltrp, Ssdbltrp extensions to -march.
* The `Smmpm`, `Smnpm`, `Ssnpm`, `Supm`, and `Sspm` pointer masking extensions
@@ -224,10 +225,17 @@ Changes to the RISC-V Backend
extension.
* Adds experimental assembler support for the Qualcomm uC 'Xqcia` (Arithmetic)
extension.
+* Adds experimental assembler support for the Qualcomm uC 'Xqciac` (Load-Store Address Calculation)
+ extension.
* Adds experimental assembler support for the Qualcomm uC 'Xqcics` (Conditonal Select)
extension.
* Adds experimental assembler support for the Qualcomm uC 'Xqcilsm` (Load Store Multiple)
extension.
+* Adds experimental assembler support for the Qualcomm uC 'Xqcicli` (Conditional Load Immediate)
+ extension.
+* Adds experimental assembler support for the Qualcomm uC 'Xqcicm` (Conditonal Move)
+ extension.
+* Added ``Sdext`` and ``Sdtrig`` extensions.
Changes to the WebAssembly Backend
----------------------------------
diff --git a/llvm/docs/TableGen/BackEnds.rst b/llvm/docs/TableGen/BackEnds.rst
index f73269e71718..94af2e4ab8f5 100644
--- a/llvm/docs/TableGen/BackEnds.rst
+++ b/llvm/docs/TableGen/BackEnds.rst
@@ -1071,8 +1071,6 @@ function. This class provides three fields.
* ``bit EarlyOut``. See the third example in `Generic Tables`_.
-* ``bit ReturnRange``. See the second example in `Generic Tables`_.
-
Here is an example of a secondary key added to the ``CTable`` above. The
generated function looks up entries based on the ``Name`` and ``Kind`` fields.
generated by cgit v1.2.3 (git 2.25.1) at 2026-05-31 16:36:57 +0000