[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