[clang] [Clang] Add clang::oracle_function attribute (PR #242484)

Aiden Grossman via cfe-commits cfe-commits at lists.llvm.org
Fri Nov 13 19:12:42 PST 2026


https://github.com/boomanaiden154 updated https://github.com/llvm/llvm-project/pull/242484

>From 765b34cd8ab265556a03512b894d63e1f430fc3c Mon Sep 17 00:00:00 2001
From: Aiden Grossman <aidengrossman at google.com>
Date: Fri, 13 Nov 2026 20:56:02 +0000
Subject: [PATCH 1/3] =?UTF-8?q?[=F0=9D=98=80=F0=9D=97=BD=F0=9D=97=BF]=20in?=
 =?UTF-8?q?itial=20version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created using spr 1.3.7
---
 clang/docs/LanguageExtensions.md              | 28 +++++++++++++
 clang/include/clang/Basic/Attr.td             |  7 ++++
 clang/include/clang/Basic/AttrDocs.td         |  8 ++++
 .../clang/Basic/DiagnosticSemaKinds.td        | 20 ++++++++++
 clang/lib/CodeGen/CodeGenFunction.cpp         | 10 +++++
 clang/lib/Sema/SemaDecl.cpp                   | 40 +++++++++++++++++++
 clang/test/CodeGen/oracle_function.c          | 15 +++++++
 ...a-attribute-supported-attributes-list.test |  1 +
 clang/test/Sema/attr-oracle-function.c        | 15 +++++++
 9 files changed, 144 insertions(+)
 create mode 100644 clang/test/CodeGen/oracle_function.c
 create mode 100644 clang/test/Sema/attr-oracle-function.c

diff --git a/clang/docs/LanguageExtensions.md b/clang/docs/LanguageExtensions.md
index 30018364300ad..9362de5c9e69a 100644
--- a/clang/docs/LanguageExtensions.md
+++ b/clang/docs/LanguageExtensions.md
@@ -893,6 +893,34 @@ void scatter(v8b mask, v8i val, v8i idx, int *ptr) {
 }
 ```
 
+## Speculative Loads
+
+### Oracle Functions
+
+Oracle functions must be denoted with the `[[clang::oracle_function]]` attribute:
+
+```c++
+[[clang::oracle_function]] static uint64_t oracle(uint64_t input) {
+  return input;
+}
+```
+
+Annotating a function as an oracle function implies several properties:
+
+* The function will never raise an exception.
+* The function does not synchronize with other threads.
+* The function will return.
+* The function only reads memory from its arguments.
+
+If the function violates one or more of these properties, the behavior is undefined. In addition to the above behavior requirements, there are also several more requirements on using the `[[clang::oracle_function]]` attribute:
+
+* It must be applied to a function definition.
+* The function definition must have internal linkage.
+* The function definition cannot be varidaic.
+* The function must return a 64-bit integer.
+
+Any violations of the properties immediately above will result in a compilation failure.
+
 ## Matrix Types
 
 Clang provides an extension for matrix types, which is currently being
diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index dc2bcd4cd5005..7db11d65832b7 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -5662,3 +5662,10 @@ def Personality : InheritableAttr {
   let Subjects = SubjectList<[Function]>;
   let Documentation = [PersonalityDocs];
 }
+
+def OracleFunction : InheritableAttr {
+  let Spellings = [Clang<"oracle_function">];
+  let Subjects = SubjectList<[Function], ErrorDiag>;
+  let Documentation = [OracleFunctionDocs];
+  let SimpleHandler = true;
+}
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index e04196b26765f..6681214db4724 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -10839,3 +10839,11 @@ void example2() {
 ```
   }];
 }
+
+def OracleFunctionDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+Use the `oracle_function` attribute on a function to denote that it should
+only be used as an oracle for __builtin_speculative_load.
+}];
+}
diff --git a/clang/include/clang/Basic/DiagnosticSemaKinds.td b/clang/include/clang/Basic/DiagnosticSemaKinds.td
index c3793aec1f732..9656741c6aaca 100644
--- a/clang/include/clang/Basic/DiagnosticSemaKinds.td
+++ b/clang/include/clang/Basic/DiagnosticSemaKinds.td
@@ -3997,6 +3997,26 @@ def err_attribute_selectany_non_extern_data : Error<
 def warn_attribute_hybrid_patchable_non_extern : Warning<
   "'hybrid_patchable' is ignored on functions without external linkage">,
   InGroup<IgnoredAttributes>;
+def err_oracle_function_no_external_linkage : Error<
+  "'clang::oracle_function' on a function with external linkage is not allowed">;
+def err_oracle_function_no_prototype : Error<
+  "'clang::oracle_function' on a function with no prototype is not allowed">;
+def err_oracle_function_variadic : Error<
+  "'clang::oracle_function' on a variadic function is not allowed">;
+def err_oracle_function_return_type : Error<
+  "'clang::oracle_function' can only be put on functions that return a 64-bit "
+  "integer">;
+def err_speculative_load_not_a_vector_of_integers: Error<
+  "the 1st argument to '__builtin_speculative_load' must be a pointer to a "
+  "vector of integers">;
+def err_speculative_load_third_arg_must_be_function : Error<
+  "the 3rd argument to '__builtin_speculative_load' must be a function">;
+def err_speculative_load_function_oracle_attr : Error<
+  "the oracle function passed to '__builtin_speculative_load' must have the "
+  "oracle_function attribute">;
+def err_speculative_load_arg_oracle_param_count_mismatch : Error<
+  "expected to have %0 arguments after the oracle function to match its "
+  "parameter count, but there are %1">;
 def err_declspec_thread_on_thread_variable : Error<
   "'__declspec(thread)' applied to variable that already has a "
   "thread-local storage specifier">;
diff --git a/clang/lib/CodeGen/CodeGenFunction.cpp b/clang/lib/CodeGen/CodeGenFunction.cpp
index 33434526d8632..b42c8c175a12a 100644
--- a/clang/lib/CodeGen/CodeGenFunction.cpp
+++ b/clang/lib/CodeGen/CodeGenFunction.cpp
@@ -50,6 +50,7 @@
 #include "llvm/IR/IntrinsicsPowerPC.h"
 #include "llvm/IR/MDBuilder.h"
 #include "llvm/Support/CRC.h"
+#include "llvm/Support/ModRef.h"
 #include "llvm/Support/SaveAndRestore.h"
 #include "llvm/Support/SipHash.h"
 #include "llvm/Support/xxhash.h"
@@ -1398,6 +1399,15 @@ void CodeGenFunction::StartFunction(GlobalDecl GD, QualType RetTy,
 
   if (CGM.shouldEmitConvergenceTokens())
     ConvergenceTokenStack.push_back(getOrEmitConvergenceEntryToken(CurFn));
+
+  if (D && D->hasAttr<OracleFunctionAttr>()) {
+    Fn->addFnAttr("oracle-function");
+    Fn->setDoesNotThrow();
+    Fn->setNoSync();
+    Fn->setWillReturn();
+    Fn->setMemoryEffects(
+        llvm::MemoryEffects::argMemOnly(llvm::ModRefInfo::Ref));
+  }
 }
 
 void CodeGenFunction::EmitFunctionBody(const Stmt *Body) {
diff --git a/clang/lib/Sema/SemaDecl.cpp b/clang/lib/Sema/SemaDecl.cpp
index f393d3aaf6b48..296d2370ec4c4 100644
--- a/clang/lib/Sema/SemaDecl.cpp
+++ b/clang/lib/Sema/SemaDecl.cpp
@@ -14,6 +14,7 @@
 #include "clang/AST/ASTConsumer.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/AST/ASTLambda.h"
+#include "clang/AST/Attrs.inc"
 #include "clang/AST/CXXInheritance.h"
 #include "clang/AST/CharUnits.h"
 #include "clang/AST/Decl.h"
@@ -30,6 +31,7 @@
 #include "clang/AST/StmtCXX.h"
 #include "clang/AST/Type.h"
 #include "clang/Basic/Builtins.h"
+#include "clang/Basic/DiagnosticSema.h"
 #include "clang/Basic/HLSLRuntime.h"
 #include "clang/Basic/PartialDiagnostic.h"
 #include "clang/Basic/SourceManager.h"
@@ -7335,6 +7337,43 @@ static void checkLifetimeBoundAttr(Sema &S, NamedDecl &ND) {
   }
 }
 
+static void checkOracleFunctionAttr(Sema &S, FunctionDecl &FD, const Declarator &D) {
+  auto *Attr = FD.getAttr<OracleFunctionAttr>();
+  if (!Attr)
+    return;
+
+  if (!Attr->isInherited() &&
+      D.getFunctionDefinitionKind() != FunctionDefinitionKind::Definition) {
+    S.Diag(Attr->getLocation(),
+           diag::err_attribute_no_builtin_on_non_definition)
+        << Attr;
+    return;
+  }
+
+  if (FD.isExternallyVisible()) {
+    S.Diag(Attr->getLocation(),
+            diag::err_oracle_function_no_external_linkage);
+    return;
+  }
+
+  if (!FD.hasPrototype()) {
+    S.Diag(Attr->getLocation(), diag::err_oracle_function_no_prototype);
+    return;
+  }
+
+  if (FD.isVariadic()) {
+    S.Diag(Attr->getLocation(), diag::err_oracle_function_variadic);
+    return;
+  }
+
+  QualType RetTy = FD.getReturnType();
+  if (!RetTy->isDependentType() &&
+      (!RetTy->isIntegerType() || S.Context.getIntWidth(RetTy) != 64)) {
+    S.Diag(Attr->getLocation(), diag::err_oracle_function_return_type);
+    return;
+  }
+}
+
 static void checkModularFormatAttr(Sema &S, NamedDecl &ND) {
   if (ND.hasAttr<ModularFormatAttr>() && !ND.hasAttr<FormatAttr>())
     S.Diag(ND.getLocation(), diag::err_modular_format_attribute_no_format);
@@ -11302,6 +11341,7 @@ Sema::ActOnFunctionDeclarator(Scope *S, Declarator &D, DeclContext *DC,
   ProcessPragmaWeak(S, NewFD);
   ProcessPragmaExport(NewFD);
   checkAttributesAfterMerging(*this, *NewFD);
+  checkOracleFunctionAttr(*this, *NewFD, D);
 
   AddKnownFunctionAttributes(NewFD);
   // The above can add the format attribute for known builtin/library functions
diff --git a/clang/test/CodeGen/oracle_function.c b/clang/test/CodeGen/oracle_function.c
new file mode 100644
index 0000000000000..fe99ae6b1e356
--- /dev/null
+++ b/clang/test/CodeGen/oracle_function.c
@@ -0,0 +1,15 @@
+// RUN: %clang_cc1 -disable-llvm-passes -femit-all-decls \
+// RUN:   -emit-llvm -o - %s | FileCheck %s
+
+[[clang::oracle_function]] static void oracle() {
+// CHECK: define {{.*}} void @oracle() [[ATTR1:#[0-9]+]]
+}
+
+void not_oracle() {
+// CHECK: define {{.*}} void @not_oracle() [[ATTR2:#[0-9]+]]
+}
+
+// CHECK: attributes [[ATTR1]] = {{.*}} "oracle-function"
+// CHECK: attributes [[ATTR2]] = {
+// CHECK-NOT: "oracle-function"
+// CHECK: }
diff --git a/clang/test/Misc/pragma-attribute-supported-attributes-list.test b/clang/test/Misc/pragma-attribute-supported-attributes-list.test
index 05e4e86f22f9d..cdc81335f8952 100644
--- a/clang/test/Misc/pragma-attribute-supported-attributes-list.test
+++ b/clang/test/Misc/pragma-attribute-supported-attributes-list.test
@@ -178,6 +178,7 @@
 // CHECK-NEXT: OpenCLIntelReqdSubGroupSize (SubjectMatchRule_function)
 // CHECK-NEXT: OpenCLNoSVM (SubjectMatchRule_variable)
 // CHECK-NEXT: OptimizeNone (SubjectMatchRule_function, SubjectMatchRule_objc_method)
+// CHECK-NEXT: OracleFunction (SubjectMatchRule_function)
 // CHECK-NEXT: OverflowBehavior (SubjectMatchRule_variable, SubjectMatchRule_type_alias, SubjectMatchRule_field)
 // CHECK-NEXT: Overloadable (SubjectMatchRule_function)
 // CHECK-NEXT: Owner (SubjectMatchRule_record_not_is_union)
diff --git a/clang/test/Sema/attr-oracle-function.c b/clang/test/Sema/attr-oracle-function.c
new file mode 100644
index 0000000000000..47f26937ac464
--- /dev/null
+++ b/clang/test/Sema/attr-oracle-function.c
@@ -0,0 +1,15 @@
+// RUN: %clang_cc1 -triple x86_64-unknown-linux-gnu -verify -fsyntax-only %s
+
+[[clang::oracle_function]] long a; // expected-error {{'clang::oracle_function' attribute only applies to functions}}
+
+[[clang::oracle_function]] long t1(void) {};// expected-error {{'clang::oracle_function' on a function with external linkage is not allowed}}
+
+[[clang::oracle_function(2)]] long t2(void) {} // expected-error {{'clang::oracle_function' attribute takes no arguments}}
+
+[[clang::oracle_function]] static long t3() {} // expected-error {{'clang::oracle_function' on a function with no prototype is not allowed}}
+
+[[clang::oracle_function]] static long t4(int a, ...) {} // expected-error {{'clang::oracle_function' on a variadic function is not allowed}}
+
+[[clang::oracle_function]] static void* t5(void) {} //expected-error {{'clang::oracle_function' can only be put on functions that return a 64-bit integer}}
+
+[[clang::oracle_function]] static long t6(void) {}

>From 7ca3951cb41f4a5a20166e196cc7e3d16607b60b Mon Sep 17 00:00:00 2001
From: Aiden Grossman <aidengrossman at google.com>
Date: Fri, 13 Nov 2026 23:52:02 +0000
Subject: [PATCH 2/3] fix

Created using spr 1.3.7
---
 clang/lib/Sema/SemaDecl.cpp | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/clang/lib/Sema/SemaDecl.cpp b/clang/lib/Sema/SemaDecl.cpp
index 296d2370ec4c4..fe33e18471ffa 100644
--- a/clang/lib/Sema/SemaDecl.cpp
+++ b/clang/lib/Sema/SemaDecl.cpp
@@ -14,7 +14,6 @@
 #include "clang/AST/ASTConsumer.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/AST/ASTLambda.h"
-#include "clang/AST/Attrs.inc"
 #include "clang/AST/CXXInheritance.h"
 #include "clang/AST/CharUnits.h"
 #include "clang/AST/Decl.h"
@@ -7337,7 +7336,8 @@ static void checkLifetimeBoundAttr(Sema &S, NamedDecl &ND) {
   }
 }
 
-static void checkOracleFunctionAttr(Sema &S, FunctionDecl &FD, const Declarator &D) {
+static void checkOracleFunctionAttr(Sema &S, FunctionDecl &FD,
+                                    const Declarator &D) {
   auto *Attr = FD.getAttr<OracleFunctionAttr>();
   if (!Attr)
     return;
@@ -7351,8 +7351,7 @@ static void checkOracleFunctionAttr(Sema &S, FunctionDecl &FD, const Declarator
   }
 
   if (FD.isExternallyVisible()) {
-    S.Diag(Attr->getLocation(),
-            diag::err_oracle_function_no_external_linkage);
+    S.Diag(Attr->getLocation(), diag::err_oracle_function_no_external_linkage);
     return;
   }
 

>From 4c412c2ec8996fa7fb38421bc98cb440a080e121 Mon Sep 17 00:00:00 2001
From: Aiden Grossman <aidengrossman at google.com>
Date: Sat, 14 Nov 2026 03:12:23 +0000
Subject: [PATCH 3/3] fix

Created using spr 1.3.7
---
 clang/test/CodeGen/oracle_function.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/clang/test/CodeGen/oracle_function.c b/clang/test/CodeGen/oracle_function.c
index fe99ae6b1e356..fa60040b1d4df 100644
--- a/clang/test/CodeGen/oracle_function.c
+++ b/clang/test/CodeGen/oracle_function.c
@@ -1,7 +1,7 @@
-// RUN: %clang_cc1 -disable-llvm-passes -femit-all-decls \
-// RUN:   -emit-llvm -o - %s | FileCheck %s
+// RUN: %clang_cc1 -triple x86_64-unknown-linux-gnu -disable-llvm-passes \
+// RUN:   -femit-all-decls -emit-llvm -o - %s | FileCheck %s
 
-[[clang::oracle_function]] static void oracle() {
+[[clang::oracle_function]] static long oracle(void) {
 // CHECK: define {{.*}} void @oracle() [[ATTR1:#[0-9]+]]
 }
 



More information about the cfe-commits mailing list