[llvm-branch-commits] [llvm] [AMDGPU][docs] Document the <4 x i32> buffer intrinsic deprecation (PR #231302)

Krzysztof Drewniak via llvm-branch-commits llvm-branch-commits at lists.llvm.org
Mon Nov 2 12:04:42 PST 2026


https://github.com/krzysz00 updated https://github.com/llvm/llvm-project/pull/231302

>From 04215446c6c2e7428fe51c3d09a63dfe39d9c251 Mon Sep 17 00:00:00 2001
From: Krzysztof Drewniak <Krzysztof.Drewniak at amd.com>
Date: Fri, 9 Oct 2026 16:29:02 +0000
Subject: [PATCH 1/2] [AMDGPU][docs] Document the <4 x i32> buffer intrinsic
 deprecation

Flag the deprecation of <4 x i32> buffer intrinsics in the release
notes, flagging the migration path and the s.buffer.load subtleties.

AI disclosure: Claude did draft some of this, but I deleted basically
all of it and the words are mine

Co-Authored-By: Claude Opus 5 (1M context) <noreply at anthropic.com>
---
 llvm/docs/AMDGPUUsage.md  | 27 ++++++++++++++++++++++++++-
 llvm/docs/ReleaseNotes.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/llvm/docs/AMDGPUUsage.md b/llvm/docs/AMDGPUUsage.md
index fe5832b286a2b3..cd5edc590634de 100644
--- a/llvm/docs/AMDGPUUsage.md
+++ b/llvm/docs/AMDGPUUsage.md
@@ -1999,6 +1999,14 @@ supported for the `amdgcn` target.
   to make incorrect transformations (such as promotion to `s_buffer_load`,
   which requires such componentwise alignment).
 
+  The buffer intrinsics that take their resource as a `<4 x i32>` instead of
+  a `ptr addrspace(8)` are deprecated and will be removed in a future LLVM
+  release. Add `ptr` after the
+  `raw`/`struct` component of the intrinsic name for the new version.
+  However, `llvm.amdgcn.s.buffer.load` becomes
+  `llvm.amdgcn.ptr.s.buffer.load` and needs to be annotated with `!invariant.load`
+  to preserve the old merging behavior. This migration was already done in clang.
+
 **Buffer Strided Pointer**
 
 : The buffer index pointer is an experimental address space. It represents
@@ -2757,6 +2765,19 @@ The AMDGPU backend implements the following LLVM IR intrinsics.
     This intrinsic has 1 operand:
 
     - Local pointer to the LDS barrier data.
+* - llvm.amdgcn.s.buffer.load
+  - Deprecated. Takes its buffer resource as a `<4 x i32>`. Use
+    `llvm.amdgcn.ptr.s.buffer.load`, which takes a `ptr addrspace(8)`
+    produced by `llvm.amdgcn.make.buffer.rsrc`.
+    The implicit assumptions encoded by the fact that this intrinsic was
+    tagged as not reading memory are replaced by needing to tag
+    `llvm.amdgcn.ptr.s.buffer.load` with `!invariant.load` metadata.
+* - llvm.amdgcn.{raw|struct}.\*buffer.\*
+  - Deprecated. The `buffer`, `tbuffer` and `atomic.buffer.load`
+    intrinsics that take their buffer resource as a `<4 x i32>` are
+    replaced by the variants with `ptr` inserted after the `raw` or
+    `struct` component of the name, which take a `ptr addrspace(8)`
+    produced by `llvm.amdgcn.make.buffer.rsrc`.
 :::
 
 :::{todo}
@@ -3024,11 +3045,15 @@ registers. See {ref}`amdgpu-dma-operations` for full documentation.
 ```
 llvm.amdgcn.load[.async].to.lds
 llvm.amdgcn.global.load[.async].lds
-llvm.amdgcn.{raw|struct}[.ptr].buffer.load[.async].lds
+llvm.amdgcn.{raw|struct}.ptr.buffer.load[.async].lds
 llvm.amdgcn.{global|cluster}.load.async.to.lds.b{8,32,64,128}
 llvm.amdgcn.global.store.async.from.lds.b{8,32,64,128}
 ```
 
+The `llvm.amdgcn.{raw|struct}.buffer.load[.async].lds` spellings, which take
+their buffer resource as a `<4 x i32>` rather than a `ptr addrspace(8)`,
+are deprecated.
+
 #### Tensor Intrinsics
 
 Tensor intrinsics transfer data between global memory and LDS using a tensor
diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md
index 7a61e982cf38e7..6e1b83d2c181bc 100644
--- a/llvm/docs/ReleaseNotes.md
+++ b/llvm/docs/ReleaseNotes.md
@@ -308,6 +308,37 @@ Makes programs 10x faster by doing Special New Thing.
   * `llvm.amdgcn.icmp`
   * `llvm.amdgcn.fcmp`
 
+* The AMDGPU buffer intrinsics that take their buffer resource (rsrc/V#)
+  argument as a `<4 x i32>` are deprecated and will be removed in a future
+  LLVM release. Codegen now warns for their use once per module.
+
+  They all have `.ptr.` equivalents that take a `ptr addrspace(8)`, produced by
+  `llvm.amdgcn.make.buffer.rsrc`, loaded directly from memory, or, if
+  necessary, converted from an existing descriptor with
+  `bitcast <4 x i32> %rsrc to i128` followed by `inttoptr i128 %i to ptr
+  addrspace(8)`. To migrate, insert `ptr` after the `raw`/`struct` component of
+  the intrinsic name; `llvm.amdgcn.s.buffer.load` is the sole exception and
+  becomes `llvm.amdgcn.ptr.s.buffer.load`.
+
+  ```llvm
+  ; Before
+  %v = call float @llvm.amdgcn.raw.buffer.load.f32(<4 x i32> %rsrc, i32 %off, i32 0, i32 0)
+
+  ; After
+  %p = call ptr addrspace(8) @llvm.amdgcn.make.buffer.rsrc.p8.p1.i32(ptr addrspace(1) %base, i16 0, i32 %numrecords, i32 %flags)
+  %v = call float @llvm.amdgcn.raw.ptr.buffer.load.f32(ptr addrspace(8) %p, i32 %off, i32 0, i32 0)
+  ```
+
+  This migration enables future flexibility in resource size and usage and
+  allows for more accurate analysis of memory usage.
+
+  Note that when emitting `llvm.amdgcn.ptr.s.buffer.load`, you must tag the intrinsic with `!invariant.load` metadata in order to recover the merging and loop hoisting behavior that `llvm.amdgcn.s.buffer.load` had because it lied about 'not reading memory'. Explicitly tagging these buffer loads as invariant will teach LLVM's general infrastructure about the property that users of the old ``s.buffer.load`` intrinsic were already asserting.
+
+  While we do intend to autoupgrade the old intrinsics when they are removed, this upgrade will have to use `inttoptr` to convert buffer resources, losing pointer provenance. Therefore, we strongly encourage users to migrate to the new forms (which have been available for years) before this removal.
+
+  The warning can be suppressed with the
+  `amdgpu-warn-deprecated-buffer-intrinsics=0` option.
+
 ### Changes to the ARM Backend
 
 * Using the hard-float procedure call standard without floating-point registers

>From b52beaf88d9e922fbf69010c4a48f9497a8f1160 Mon Sep 17 00:00:00 2001
From: Krzysztof Drewniak <Krzysztof.Drewniak at amd.com>
Date: Mon, 2 Nov 2026 19:26:51 +0000
Subject: [PATCH 2/2] Remove mention of a warning we won't be doing

---
 llvm/docs/ReleaseNotes.md | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md
index 6e1b83d2c181bc..2721e997c13c2f 100644
--- a/llvm/docs/ReleaseNotes.md
+++ b/llvm/docs/ReleaseNotes.md
@@ -310,7 +310,7 @@ Makes programs 10x faster by doing Special New Thing.
 
 * The AMDGPU buffer intrinsics that take their buffer resource (rsrc/V#)
   argument as a `<4 x i32>` are deprecated and will be removed in a future
-  LLVM release. Codegen now warns for their use once per module.
+  LLVM release.
 
   They all have `.ptr.` equivalents that take a `ptr addrspace(8)`, produced by
   `llvm.amdgcn.make.buffer.rsrc`, loaded directly from memory, or, if
@@ -336,9 +336,6 @@ Makes programs 10x faster by doing Special New Thing.
 
   While we do intend to autoupgrade the old intrinsics when they are removed, this upgrade will have to use `inttoptr` to convert buffer resources, losing pointer provenance. Therefore, we strongly encourage users to migrate to the new forms (which have been available for years) before this removal.
 
-  The warning can be suppressed with the
-  `amdgpu-warn-deprecated-buffer-intrinsics=0` option.
-
 ### Changes to the ARM Backend
 
 * Using the hard-float procedure call standard without floating-point registers



More information about the llvm-branch-commits mailing list