transform, compiler: support LLVM 21's captures(none) attribute; add LLVM 22 build support

Written entirely by Claude (Anthropic's Claude Code), at the request of
and under the direction of dgryski, as part of an effort to get TinyGo
building against upcoming LLVM releases (this branch currently targets
LLVM 22, verified against real LLVM 22.1.8; a corresponding go-llvm
branch of the same name adds the matching binding support).

LLVM 21 replaced the boolean 'nocapture' enum attribute with the more
expressive 'captures' int attribute, where captures(none) (value 0) is
the equivalent of the old nocapture. This matters for
transform.OptimizeAllocs, which relies on reading this attribute for
its interprocedural escape analysis, and for compiler/symbol.go, which
emits it on a number of runtime/generated functions. Confirmed
empirically (via `opt -passes=function-attrs`) that the cutoff is
LLVM 20 emits/expects nocapture, LLVM 21+ emits/expects
captures(none). Since TinyGo must keep working with LLVM 20, both
sites now go through new version-gated helpers in
compiler/llvmutil (NoCaptureAttrName/IsNoCapture) rather than switching
unconditionally.

Also fixes a second, unrelated but load-bearing break found while
testing against LLVM 22: llvm.lifetime.start/end dropped their i64
size argument (confirmed via `opt -passes=verify`, the cutoff here is
one version later, at LLVM 22). compiler/llvmutil now builds the
right call signature based on version.

Adds llvm21 and llvm22 build-tag config files to the cgo package,
which parses cgo fragments via libclang and had never been updated
past LLVM 20 even though the compiler package itself already gained
LLVM 21 support previously -- a latent gap that would have caused a
version mismatch between the cgo preprocessor and the rest of the
compiler when building with -tags llvm21 or llvm22.

Finally, updates the golden-IR test comparators in
transform/transform_test.go and compiler/compiler_test.go to
normalize a few cosmetic LLVM 21/22 output differences (the
captures(none) rename/reordering, a new 'nocreateundeforpoison'
intrinsic attribute, and the lifetime intrinsic arity change) so a
single golden file continues to match output from either LLVM
version.

Verified by building a full (non-byollvm) tinygo binary against real
LLVM 22.1.8 and running a compiled Go program end-to-end (exercising
OptimizeAllocs' stack-allocation path), and by running the
transform/compiler/cgo test suites against both LLVM 20 (default) and
LLVM 22.

Not yet addressed: the byollvm embedded-clang/lld build path hits
separate, unrelated Clang C++ API breakage against LLVM 22
(DiagnosticOptions reference-to-pointer change, missing headers) --
that is a larger follow-up effort.

cgo/libclang_config_llvm20.go

@@ -1,4 +1,4 @@
-//go:build !byollvm && !llvm15 && !llvm16 && !llvm17 && !llvm18 && !llvm19
+//go:build !byollvm && !llvm15 && !llvm16 && !llvm17 && !llvm18 && !llvm19 && !llvm21 && !llvm22
 
 package cgo
 

cgo/libclang_config_llvm21.go

@@ -0,0 +1,15 @@
+//go:build !byollvm && llvm21
+
+package cgo
+
+/*
+#cgo linux        CFLAGS:  -I/usr/include/llvm-21 -I/usr/include/llvm-c-21 -I/usr/lib/llvm-21/include -I/usr/lib64/llvm21/include
+#cgo darwin,amd64 CFLAGS:  -I/usr/local/opt/llvm@21/include
+#cgo darwin,arm64 CFLAGS:  -I/opt/homebrew/opt/llvm@21/include
+#cgo freebsd      CFLAGS:  -I/usr/local/llvm21/include
+#cgo linux        LDFLAGS: -L/usr/lib/llvm-21/lib -lclang
+#cgo darwin,amd64 LDFLAGS: -L/usr/local/opt/llvm@21/lib -lclang
+#cgo darwin,arm64 LDFLAGS: -L/opt/homebrew/opt/llvm@21/lib -lclang
+#cgo freebsd      LDFLAGS: -L/usr/local/llvm21/lib -lclang
+*/
+import "C"

cgo/libclang_config_llvm22.go

@@ -0,0 +1,15 @@
+//go:build !byollvm && llvm22
+
+package cgo
+
+/*
+#cgo linux        CFLAGS:  -I/usr/include/llvm-22 -I/usr/include/llvm-c-22 -I/usr/lib/llvm-22/include -I/usr/lib64/llvm22/include
+#cgo darwin,amd64 CFLAGS:  -I/usr/local/opt/llvm@22/include
+#cgo darwin,arm64 CFLAGS:  -I/opt/homebrew/opt/llvm@22/include
+#cgo freebsd      CFLAGS:  -I/usr/local/llvm22/include
+#cgo linux        LDFLAGS: -L/usr/lib/llvm-22/lib -lclang
+#cgo darwin,amd64 LDFLAGS: -L/usr/local/opt/llvm@22/lib -lclang
+#cgo darwin,arm64 LDFLAGS: -L/opt/homebrew/opt/llvm@22/lib -lclang
+#cgo freebsd      LDFLAGS: -L/usr/local/llvm22/lib -lclang
+*/
+import "C"

compiler/compiler_test.go

@@ -4,6 +4,7 @@ import (
 	"flag"
 	"go/types"
 	"os"
+	"regexp"
 	"strconv"
 	"strings"
 	"testing"
@@ -133,6 +134,29 @@ func TestCompiler(t *testing.T) {
 // equal. That means, only relevant lines are compared (excluding comments
 // etc.).
 func fuzzyEqualIR(s1, s2 string) bool {
+	// Golden files are written using the pre-LLVM21 'nocapture' spelling,
+	// which LLVM printed before any co-occurring attribute such as
+	// 'readonly' (e.g. "ptr nocapture readonly"). LLVM 21+ prints the
+	// equivalent 'captures(none)' instead, and after such attributes (e.g.
+	// "ptr readonly captures(none)"). Normalize both name and position back
+	// to the old spelling to keep a single golden file working across LLVM
+	// versions.
+	s1 = normalizeCapturesAttr(s1)
+	s2 = normalizeCapturesAttr(s2)
+
+	// LLVM 21+ also added an explicit 'nocreateundeforpoison' attribute to
+	// certain intrinsic declarations (e.g. llvm.umin) that were implicitly
+	// assumed not to create undef/poison before. It's unrelated to the
+	// behavior under test, so ignore it for comparison.
+	s1 = strings.ReplaceAll(s1, "nocreateundeforpoison ", "")
+	s2 = strings.ReplaceAll(s2, "nocreateundeforpoison ", "")
+
+	// LLVM 22 dropped the (redundant) i64 size argument from
+	// llvm.lifetime.start/end. Normalize away that argument so golden files
+	// written against the two-argument form still match.
+	s1 = lifetimeSizeArgRe.ReplaceAllString(s1, "$1")
+	s2 = lifetimeSizeArgRe.ReplaceAllString(s2, "$1")
+
 	lines1 := filterIrrelevantIRLines(strings.Split(s1, "\n"))
 	lines2 := filterIrrelevantIRLines(strings.Split(s2, "\n"))
 	if len(lines1) != len(lines2) {
@@ -148,6 +172,25 @@ func fuzzyEqualIR(s1, s2 string) bool {
 	return true
 }
 
+// capturesNoneAttrRe matches a co-occurring attribute directly followed by
+// 'captures(none)', which is how LLVM 21+ orders these two attributes when
+// printing IR (the pre-LLVM21 'nocapture' attribute printed the other way
+// around).
+var capturesNoneAttrRe = regexp.MustCompile(`\b(readonly|readnone|writeonly|nonnull)\s+captures\(none\)`)
+
+// lifetimeSizeArgRe matches the i64 size argument of an
+// llvm.lifetime.start/end call or declaration, which LLVM 22 removed.
+var lifetimeSizeArgRe = regexp.MustCompile(`(@llvm\.lifetime\.(?:start|end)\.p0\()i64(?: immarg| \d+), `)
+
+// normalizeCapturesAttr rewrites LLVM 21+'s 'captures(none)' attribute back
+// to the pre-LLVM21 'nocapture' spelling and position, so golden IR files
+// written against LLVM <21 keep matching.
+func normalizeCapturesAttr(s string) string {
+	s = capturesNoneAttrRe.ReplaceAllString(s, "nocapture $1")
+	s = strings.ReplaceAll(s, "captures(none)", "nocapture")
+	return s
+}
+
 // filterIrrelevantIRLines removes lines from the input slice of strings that
 // are not relevant in comparing IR. For example, empty lines and comments are
 // stripped out.

compiler/llvmutil/llvm.go

@@ -44,7 +44,7 @@ func CreateTemporaryAlloca(builder llvm.Builder, mod llvm.Module, t llvm.Type, n
 	alloca = CreateEntryBlockAlloca(builder, t, name)
 	size = llvm.ConstInt(ctx.Int64Type(), targetData.TypeAllocSize(t), false)
 	fnType, fn := getLifetimeStartFunc(mod)
-	builder.CreateCall(fnType, fn, []llvm.Value{size, alloca}, "")
+	builder.CreateCall(fnType, fn, lifetimeCallArgs(size, alloca), "")
 	return
 }
 
@@ -58,14 +58,14 @@ func CreateInstructionAlloca(builder llvm.Builder, mod llvm.Module, t llvm.Type,
 	builder.SetInsertPointBefore(inst)
 	size := llvm.ConstInt(ctx.Int64Type(), targetData.TypeAllocSize(t), false)
 	fnType, fn := getLifetimeStartFunc(mod)
-	builder.CreateCall(fnType, fn, []llvm.Value{size, alloca}, "")
+	builder.CreateCall(fnType, fn, lifetimeCallArgs(size, alloca), "")
 	if next := llvm.NextInstruction(inst); !next.IsNil() {
 		builder.SetInsertPointBefore(next)
 	} else {
 		builder.SetInsertPointAtEnd(inst.InstructionParent())
 	}
 	fnType, fn = getLifetimeEndFunc(mod)
-	builder.CreateCall(fnType, fn, []llvm.Value{size, alloca}, "")
+	builder.CreateCall(fnType, fn, lifetimeCallArgs(size, alloca), "")
 	return alloca
 }
 
@@ -74,7 +74,27 @@ func CreateInstructionAlloca(builder llvm.Builder, mod llvm.Module, t llvm.Type,
 // createTemporaryAlloca.
 func EmitLifetimeEnd(builder llvm.Builder, mod llvm.Module, ptr, size llvm.Value) {
 	fnType, fn := getLifetimeEndFunc(mod)
-	builder.CreateCall(fnType, fn, []llvm.Value{size, ptr}, "")
+	builder.CreateCall(fnType, fn, lifetimeCallArgs(size, ptr), "")
+}
+
+// lifetimeCallArgs returns the arguments to pass to a call of the
+// llvm.lifetime.start/end intrinsics. LLVM 22 dropped the (redundant,
+// already required to match the alloca size) i64 size argument, so the
+// intrinsic now only takes the pointer.
+func lifetimeCallArgs(size, ptr llvm.Value) []llvm.Value {
+	if Version() >= 22 {
+		return []llvm.Value{ptr}
+	}
+	return []llvm.Value{size, ptr}
+}
+
+// lifetimeFuncType returns the function type of the llvm.lifetime.start/end
+// intrinsics, which lost their i64 size parameter in LLVM 22.
+func lifetimeFuncType(ctx llvm.Context, ptrType llvm.Type) llvm.Type {
+	if Version() >= 22 {
+		return llvm.FunctionType(ctx.VoidType(), []llvm.Type{ptrType}, false)
+	}
+	return llvm.FunctionType(ctx.VoidType(), []llvm.Type{ctx.Int64Type(), ptrType}, false)
 }
 
 // getLifetimeStartFunc returns the llvm.lifetime.start intrinsic and creates it
@@ -84,7 +104,7 @@ func getLifetimeStartFunc(mod llvm.Module) (llvm.Type, llvm.Value) {
 	fn := mod.NamedFunction(fnName)
 	ctx := mod.Context()
 	ptrType := llvm.PointerType(ctx.Int8Type(), 0)
-	fnType := llvm.FunctionType(ctx.VoidType(), []llvm.Type{ctx.Int64Type(), ptrType}, false)
+	fnType := lifetimeFuncType(ctx, ptrType)
 	if fn.IsNil() {
 		fn = llvm.AddFunction(mod, fnName, fnType)
 	}
@@ -98,7 +118,7 @@ func getLifetimeEndFunc(mod llvm.Module) (llvm.Type, llvm.Value) {
 	fn := mod.NamedFunction(fnName)
 	ctx := mod.Context()
 	ptrType := llvm.PointerType(ctx.Int8Type(), 0)
-	fnType := llvm.FunctionType(ctx.VoidType(), []llvm.Type{ctx.Int64Type(), ptrType}, false)
+	fnType := lifetimeFuncType(ctx, ptrType)
 	if fn.IsNil() {
 		fn = llvm.AddFunction(mod, fnName, fnType)
 	}
@@ -218,6 +238,36 @@ func Version() int {
 	return major
 }
 
+// NoCaptureAttrName returns the name of the LLVM attribute kind that marks a
+// pointer parameter as guaranteed not to escape by capture.
+//
+// LLVM 21 removed the old boolean 'nocapture' enum attribute in favor of the
+// more expressive 'captures' int attribute, where 'captures(none)' (encoded
+// as the value 0) is the equivalent of the old 'nocapture'. LLVM 20 supports
+// both, but its own optimizer still emits 'nocapture', so the cutoff for
+// reading/writing the new name is LLVM 21.
+func NoCaptureAttrName() string {
+	if Version() >= 21 {
+		return "captures"
+	}
+	return "nocapture"
+}
+
+// IsNoCapture reports whether attr (looked up using the kind returned by
+// NoCaptureAttrName) indicates that the pointer it is attached to does not
+// escape by capture. It returns false for a nil attribute.
+func IsNoCapture(attr llvm.Attribute) bool {
+	if attr.IsNil() {
+		return false
+	}
+	if Version() >= 21 {
+		// captures(none) is encoded as the value 0; any other value permits
+		// some form of capture.
+		return attr.GetEnumValue() == 0
+	}
+	return true
+}
+
 // ByteOrder returns the byte order for the given target triple. Most targets are little
 // endian, but for example MIPS can be big-endian.
 func ByteOrder(target string) binary.ByteOrder {

compiler/symbol.go

@@ -141,7 +141,7 @@ func (c *compilerContext) getFunction(fn *ssa.Function) (llvm.Type, llvm.Value)
 			// not.
 			// (It may be safe to add the nocapture parameter to the context
 			// parameter, but I'd like to stay on the safe side here).
-			nocapture := c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0)
+			nocapture := c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0)
 			llvmFn.AddAttributeAtIndex(i+1, nocapture)
 		}
 		if paramInfo.flags&paramIsReadonly != 0 && paramInfo.llvmType.TypeKind() == llvm.PointerTypeKind {
@@ -160,9 +160,9 @@ func (c *compilerContext) getFunction(fn *ssa.Function) (llvm.Type, llvm.Value)
 		// Mark it as noreturn so LLVM can optimize away code.
 		llvmFn.AddFunctionAttr(c.ctx.CreateEnumAttribute(llvm.AttributeKindID("noreturn"), 0))
 	case "internal/abi.NoEscape":
-		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "machine.keepAliveNoEscape", "machine.unsafeNoEscape":
-		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.alloc", "runtime.alloc_noheap", "runtime.alloc_zero":
 		// Tell the optimizer that runtime.alloc is an allocator, meaning that it
 		// returns values that are never null and never alias to an existing value.
@@ -184,44 +184,44 @@ func (c *compilerContext) getFunction(fn *ssa.Function) (llvm.Type, llvm.Value)
 	case "runtime.sliceAppend":
 		// Appending a slice will only read the to-be-appended slice, it won't
 		// be modified.
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("readonly"), 0))
 	case "runtime.stringFromBytes":
-		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("readonly"), 0))
 	case "runtime.stringFromRunes":
-		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("readonly"), 0))
 	case "runtime.hashmapSet":
 		// The key (param 2) and value (param 3) pointers are only read via
 		// memcpy/hash/equal and are never captured. The indirect calls
 		// through m.keyHash and m.keyEqual function pointers prevent LLVM's
 		// functionattrs pass from inferring this automatically.
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
-		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
+		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.hashmapGet":
 		// The key (param 2) is read-only and never captured.
 		// The value (param 3) is written to (receives the result) but never captured.
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
-		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
+		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.hashmapDelete":
 		// The key (param 2) is read-only and never captured.
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.hashmapGenericSet":
 		// Same as hashmapBinarySet: key (param 2) and value (param 3) are
 		// not captured.
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
-		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
+		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.hashmapGenericGet":
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
-		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
+		llvmFn.AddAttributeAtIndex(3, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.hashmapGenericDelete":
-		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(2, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 	case "runtime.trackPointer":
 		// This function is necessary for tracking pointers on the stack in a
 		// portable way (see gc_stack_portable.go). Indicate to the optimizer
 		// that the only thing we'll do is read the pointer.
-		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("nocapture"), 0))
+		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID(llvmutil.NoCaptureAttrName()), 0))
 		llvmFn.AddAttributeAtIndex(1, c.ctx.CreateEnumAttribute(llvm.AttributeKindID("readonly"), 0))
 	case "__mulsi3", "__divmodsi4", "__udivmodsi4":
 		if strings.Split(c.Triple, "-")[0] == "avr" {
@@ -256,7 +256,7 @@ func (c *compilerContext) getFunction(fn *ssa.Function) (llvm.Type, llvm.Value)
 
 			llvmFn.AddFunctionAttr(c.ctx.CreateStringAttribute("wasm-import-name", info.wasmName))
 		}
-		nocaptureKind := llvm.AttributeKindID("nocapture")
+		nocaptureKind := llvm.AttributeKindID(llvmutil.NoCaptureAttrName())
 		nocapture := c.ctx.CreateEnumAttribute(nocaptureKind, 0)
 		for i, typ := range paramTypes {
 			if typ.TypeKind() == llvm.PointerTypeKind {

transform/allocs.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"regexp"
 
+	"github.com/tinygo-org/tinygo/compiler/llvmutil"
 	"tinygo.org/x/go-llvm"
 )
 
@@ -260,7 +261,7 @@ func callValueEscapesAt(call, value llvm.Value, allowReturn bool, visiting map[l
 	if called.IsAFunction().IsNil() {
 		return escapeResult{escapeAt: call}
 	}
-	kindNoCapture := llvm.AttributeKindID("nocapture")
+	kindNoCapture := llvm.AttributeKindID(llvmutil.NoCaptureAttrName())
 	kindReturned := llvm.AttributeKindID("returned")
 	matched := false
 	var result escapeResult
@@ -270,7 +271,7 @@ func callValueEscapesAt(call, value llvm.Value, allowReturn bool, visiting map[l
 		}
 		matched = true
 		index := i + 1 // param attributes start at 1
-		nocapture := !called.GetEnumAttributeAtIndex(index, kindNoCapture).IsNil()
+		nocapture := llvmutil.IsNoCapture(called.GetEnumAttributeAtIndex(index, kindNoCapture))
 		returnedParam := !called.GetEnumAttributeAtIndex(index, kindReturned).IsNil()
 		if returnedParam {
 			result.returned = true

transform/transform_test.go

@@ -8,6 +8,7 @@ import (
 	"go/types"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"testing"
 
@@ -99,6 +100,29 @@ func testTransform(t *testing.T, pathPrefix string, transform func(mod llvm.Modu
 // equal. That means, only relevant lines are compared (excluding comments
 // etc.).
 func fuzzyEqualIR(s1, s2 string) bool {
+	// Golden files are written using the pre-LLVM21 'nocapture' spelling,
+	// which LLVM printed before any co-occurring attribute such as
+	// 'readonly' (e.g. "ptr nocapture readonly"). LLVM 21+ prints the
+	// equivalent 'captures(none)' instead, and after such attributes (e.g.
+	// "ptr readonly captures(none)"). Normalize both name and position back
+	// to the old spelling to keep a single golden file working across LLVM
+	// versions.
+	s1 = normalizeCapturesAttr(s1)
+	s2 = normalizeCapturesAttr(s2)
+
+	// LLVM 21+ also added an explicit 'nocreateundeforpoison' attribute to
+	// certain intrinsic declarations (e.g. llvm.umin) that were implicitly
+	// assumed not to create undef/poison before. It's unrelated to the
+	// escape-analysis behavior under test, so ignore it for comparison.
+	s1 = strings.ReplaceAll(s1, "nocreateundeforpoison ", "")
+	s2 = strings.ReplaceAll(s2, "nocreateundeforpoison ", "")
+
+	// LLVM 22 dropped the (redundant) i64 size argument from
+	// llvm.lifetime.start/end. Normalize away that argument so golden files
+	// written against the two-argument form still match.
+	s1 = lifetimeSizeArgRe.ReplaceAllString(s1, "$1")
+	s2 = lifetimeSizeArgRe.ReplaceAllString(s2, "$1")
+
 	lines1 := filterIrrelevantIRLines(strings.Split(s1, "\n"))
 	lines2 := filterIrrelevantIRLines(strings.Split(s2, "\n"))
 	if len(lines1) != len(lines2) {
@@ -114,6 +138,25 @@ func fuzzyEqualIR(s1, s2 string) bool {
 	return true
 }
 
+// capturesNoneAttrRe matches a co-occurring attribute directly followed by
+// 'captures(none)', which is how LLVM 21+ orders these two attributes when
+// printing IR (the pre-LLVM21 'nocapture' attribute printed the other way
+// around).
+var capturesNoneAttrRe = regexp.MustCompile(`\b(readonly|readnone|writeonly|nonnull)\s+captures\(none\)`)
+
+// lifetimeSizeArgRe matches the i64 size argument of an
+// llvm.lifetime.start/end call or declaration, which LLVM 22 removed.
+var lifetimeSizeArgRe = regexp.MustCompile(`(@llvm\.lifetime\.(?:start|end)\.p0\()i64(?: immarg| \d+), `)
+
+// normalizeCapturesAttr rewrites LLVM 21+'s 'captures(none)' attribute back
+// to the pre-LLVM21 'nocapture' spelling and position, so golden IR files
+// written against LLVM <21 keep matching.
+func normalizeCapturesAttr(s string) string {
+	s = capturesNoneAttrRe.ReplaceAllString(s, "nocapture $1")
+	s = strings.ReplaceAll(s, "captures(none)", "nocapture")
+	return s
+}
+
 // filterIrrelevantIRLines removes lines from the input slice of strings that
 // are not relevant in comparing IR. For example, empty lines and comments are
 // stripped out.