[SYCL][Driver] Update -fsycl-dump-device-code option name. (#18908)

srividya-sundaram · bader · web-flow · commit 4b62aeaef6fa · 2025-06-18T10:31:46.000-07:00
This PR deprecates the usage of `-fsycl-dump-device-code` option, making
this option backend-agnostic, extending its functionality beyond just
SYCL to include OpenMP and other offloading models in the future, with
the new option name: `-save-offload-code=/path/to/offload/code/`(Linux)
and `-(or)/Qsave-offload-code=/path/to/offload/code/` (Windows)



A diagnostic warning is emitted when `-fsycl-dump-device-code` option is
passed to the Clang driver.
Example:
```
clang++ -fsycl -fsycl-dump-device-code= syclfile.cpp
clang++: warning: option '-fsycl-dump-device-code=' is deprecated and will be removed in a future release, use '-save-offload-code=' instead [-Wdeprecated]
```

---------

Co-authored-by: Alexey Bader &lt;alexey.bader@intel.com&gt;
diff --git a/clang/include/clang/Driver/Driver.h b/clang/include/clang/Driver/Driver.h
@@ -101,7 +101,7 @@ class Driver {
 
   IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS;
 
-  bool DumpDeviceCode;
+  bool SaveOffloadCode;
 
   enum DriverMode {
     GCCMode,
@@ -453,7 +453,7 @@ class Driver {
     return ClangExecutable.c_str();
   }
 
-  bool isDumpDeviceCodeEnabled() const { return DumpDeviceCode; }
+  bool isSaveOffloadCodeEnabled() const { return SaveOffloadCode; }
 
   bool isSaveTempsEnabled() const { return SaveTemps != SaveTempsNone; }
   bool isSaveTempsObj() const { return SaveTemps == SaveTempsObj; }
diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
@@ -7348,9 +7348,14 @@ defm sycl_allow_device_image_dependencies: BoolOptionWithoutMarshalling<"f", "sy
   PosFlag<SetTrue, [], [ClangOption], "Allow dependencies between device code images">,
   NegFlag<SetFalse, [], [ClangOption], "Do not allow dependencies between device code images (default)">>;
 
-def fsycl_dump_device_code_EQ : Joined<["-"], "fsycl-dump-device-code=">,
+def save_offload_code_EQ : Joined<["-"], "save-offload-code=">,
   Flags<[NoXarchOption]>,
-  HelpText<"Dump device code into the user provided directory.">;
+  Visibility<[ClangOption]>,
+  HelpText<"Save offload code generated during compilation into the user provided directory.">;
+def fsycl_dump_device_code_EQ : Joined<["-"], "fsycl-dump-device-code=">,
+  Alias<save_offload_code_EQ>,
+  Flags<[NoXarchOption, Deprecated]>,
+  HelpText<"Dump device code into the user provided directory. (deprecated)">;
 def fsyclbin_EQ : Joined<["-"], "fsyclbin=">, Values<"executable,object,input">,
   HelpText<"Output in the SYCLBIN binary format in the state specified by <arg> (input, object or executable (default))">;
 def fsyclbin : Flag<["-"], "fsyclbin">, Alias<fsyclbin_EQ>,
@@ -9586,6 +9591,8 @@ def : Separate<["-"], "Xmicrosoft-windows-sdk-version">,
     Alias<_SLASH_winsdkversion>;
 def : Separate<["-"], "Xmicrosoft-windows-sys-root">,
     Alias<_SLASH_winsysroot>;
+def _SLASH_Qsave_offload_code : CLJoined<"Qsave-offload-code=">, Alias<save_offload_code_EQ>,
+  HelpText<"Save offload code generated during compilation into the user provided directory.">;
 
 // Ignored:
 
diff --git a/clang/lib/Driver/Compilation.cpp b/clang/lib/Driver/Compilation.cpp
@@ -182,12 +182,12 @@ bool Compilation::CleanupFile(const char *File, bool IssueErrors) const {
   // able to remove), or non-regular files. Underlying tools may have
   // intentionally not overwritten them.
 
-  // Save the device code files if -fsycl-dump-device-code option is enabled.
-  if (TheDriver.isDumpDeviceCodeEnabled()) {
-    Arg *DumpDeviceCodeArg =
-        getArgs().getLastArg(options::OPT_fsycl_dump_device_code_EQ);
+  // Save the device code files if -save-offload-code option is enabled.
+  if (TheDriver.isSaveOffloadCodeEnabled()) {
+    Arg *SaveOffloadCodeArg =
+        getArgs().getLastArg(options::OPT_save_offload_code_EQ);
     std::string ExpectedDir =
-        DumpDeviceCodeArg ? DumpDeviceCodeArg->getValue() : "";
+        SaveOffloadCodeArg ? SaveOffloadCodeArg->getValue() : "";
     std::string ActualFile(File);
 
     if (ActualFile.find(ExpectedDir) != std::string::npos) {
diff --git a/clang/lib/Driver/Driver.cpp b/clang/lib/Driver/Driver.cpp
@@ -245,7 +245,7 @@ std::string CUIDOptions::getCUID(StringRef InputFile,
 Driver::Driver(StringRef ClangExecutable, StringRef TargetTriple,
                DiagnosticsEngine &Diags, std::string Title,
                IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS)
-    : Diags(Diags), VFS(std::move(VFS)), DumpDeviceCode(false), Mode(GCCMode),
+    : Diags(Diags), VFS(std::move(VFS)), SaveOffloadCode(false), Mode(GCCMode),
       SaveTemps(SaveTempsNone), BitcodeEmbed(EmbedNone),
       Offload(OffloadHostDevice), CXX20HeaderType(HeaderMode_None),
       ModulesModeCXX20(false), LTOMode(LTOK_None), OffloadLTOMode(LTOK_None),
@@ -2099,8 +2099,8 @@ Compilation *Driver::BuildCompilation(ArrayRef<const char *> ArgList) {
                     .Default(SaveTempsCwd);
   }
 
-  if (Args.getLastArg(options::OPT_fsycl_dump_device_code_EQ))
-    DumpDeviceCode = true;
+  if (Args.getLastArg(options::OPT_save_offload_code_EQ))
+    SaveOffloadCode = true;
 
   if (const Arg *A = Args.getLastArg(
           options::OPT_offload_host_only, options::OPT_offload_device_only,
diff --git a/clang/lib/Driver/ToolChains/Clang.cpp b/clang/lib/Driver/ToolChains/Clang.cpp
@@ -10755,15 +10755,15 @@ void SPIRVTranslator::ConstructJob(Compilation &C, const JobAction &JA,
         TCArgs.MakeArgString("--out-file-list=" + OutputFileName));
     ForeachArgs.push_back(
         TCArgs.MakeArgString("--out-replace=" + OutputFileName));
-    // If fsycl-dump-device-code is passed, put the output files from llvm-spirv
-    // into the path provided in fsycl-dump-device-code.
-    if (C.getDriver().isDumpDeviceCodeEnabled()) {
+    // If save-offload-code is passed, put the output files from llvm-spirv
+    // into the path provided in save-offload-code.
+    if (C.getDriver().isSaveOffloadCodeEnabled()) {
       SmallString<128> OutputDir;
 
-      Arg *DumpDeviceCodeArg =
-          C.getArgs().getLastArg(options::OPT_fsycl_dump_device_code_EQ);
+      Arg *SaveOffloadCodeArg =
+          C.getArgs().getLastArg(options::OPT_save_offload_code_EQ);
 
-      OutputDir = (DumpDeviceCodeArg ? DumpDeviceCodeArg->getValue() : "");
+      OutputDir = (SaveOffloadCodeArg ? SaveOffloadCodeArg->getValue() : "");
 
       // If the output directory path is empty, put the llvm-spirv output in the
       // current directory.
@@ -11417,9 +11417,9 @@ void LinkerWrapper::ConstructJob(Compilation &C, const JobAction &JA,
     CmdArgs.push_back(Args.MakeArgString(
         Twine("-sycl-device-library-location=") + DeviceLibDir));
 
-    if (C.getDriver().isDumpDeviceCodeEnabled()) {
+    if (C.getDriver().isSaveOffloadCodeEnabled()) {
       SmallString<128> DumpDir;
-      Arg *A = C.getArgs().getLastArg(options::OPT_fsycl_dump_device_code_EQ);
+      Arg *A = C.getArgs().getLastArg(options::OPT_save_offload_code_EQ);
       DumpDir = A ? A->getValue() : "";
       CmdArgs.push_back(
           Args.MakeArgString(Twine("-sycl-dump-device-code=") + DumpDir));
diff --git a/clang/lib/Driver/ToolChains/SYCL.cpp b/clang/lib/Driver/ToolChains/SYCL.cpp
@@ -248,16 +248,16 @@ void SYCL::constructLLVMForeachCommand(Compilation &C, const JobAction &JA,
         C.getArgs().MakeArgString("--out-dir=" + OutputDirName));
   }
 
-  // If fsycl-dump-device-code is passed, put the PTX files
-  // into the path provided in fsycl-dump-device-code.
+  // If save-offload-code is passed, put the PTX files
+  // into the path provided in save-offload-code.
   if (T->getToolChain().getTriple().isNVPTX() &&
-      C.getDriver().isDumpDeviceCodeEnabled() && Ext == "s") {
+      C.getDriver().isSaveOffloadCodeEnabled() && Ext == "s") {
     SmallString<128> OutputDir;
 
-    Arg *DumpDeviceCodeArg =
-        C.getArgs().getLastArg(options::OPT_fsycl_dump_device_code_EQ);
+    Arg *SaveOffloadCodeArg =
+        C.getArgs().getLastArg(options::OPT_save_offload_code_EQ);
 
-    OutputDir = (DumpDeviceCodeArg ? DumpDeviceCodeArg->getValue() : "");
+    OutputDir = (SaveOffloadCodeArg ? SaveOffloadCodeArg->getValue() : "");
 
     // If the output directory path is empty, put the PTX files in the
     // current directory.
diff --git a/clang/test/Driver/save-ptx-files.cpp b/clang/test/Driver/save-ptx-files.cpp
@@ -1,17 +1,17 @@
-// Save PTX files during PTX target processing using -fsycl-dump-device-code option.
+// Save PTX files during PTX target processing using -save-offload-code option.
 
-// Verify that -fsycl-dump-device-code saves PTX files in the user provided directory
+// Verify that -save-offload-code saves PTX files in the user provided directory
 // while targeting CUDA enabled GPUs.
 
 // Linux
-// RUN: %clang -### -fsycl -fsycl-targets=nvptx64-nvidia-cuda,spir64-unknown-unknown -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -fsycl-dump-device-code=/user/input/path %s 2>&1 \
+// RUN: %clang -### -fsycl -fsycl-targets=nvptx64-nvidia-cuda,spir64-unknown-unknown -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -save-offload-code=/user/input/path %s 2>&1 \
 // RUN: | FileCheck %s --check-prefixes=CHECK-PTX-FILES,CHECK-SPIRV-FILES
 
 // clang --driver-mode=g++
-// RUN: %clangxx -### -fsycl  -fsycl-targets=nvptx64-nvidia-cuda -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -fsycl-dump-device-code=/user/input/path %s 2>&1 \
+// RUN: %clangxx -### -fsycl  -fsycl-targets=nvptx64-nvidia-cuda -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -save-offload-code=/user/input/path %s 2>&1 \
 // RUN: | FileCheck %s --check-prefixes=CHECK-PTX-FILES
 
-// RUN: %clang -### -fsycl -fsycl-targets=nvptx64-nvidia-cuda,spir64-unknown-unknown -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -fsycl-dump-device-code= %s 2>&1 \
+// RUN: %clang -### -fsycl -fsycl-targets=nvptx64-nvidia-cuda,spir64-unknown-unknown -target x86_64-unknown-linux-gnu --cuda-path=%S/Inputs/CUDA/usr/local/cuda -save-offload-code= %s 2>&1 \
 // RUN: | FileCheck %s --check-prefixes=CHECK-PTX-FILES-CWD,CHECK-SPIRV-FILES-CWD
 
 // CHECK-PTX-FILES: llvm-foreach{{.*}} "--out-ext=s"{{.*}} "--out-dir=/user/input/path{{(/|\\\\)}}" "--" "{{.*}}clang{{.*}}" {{.*}} "-fsycl-is-device" {{.*}}.s{{.*}}
@@ -22,20 +22,20 @@
 // Windows - Check if PTX files are saved in the user provided path.
 // RUN: %clang_cl -### -fsycl \
 // RUN: -fsycl-targets=nvptx64-nvidia-cuda --cuda-path=%S/Inputs/CUDA/usr/local/cuda \
-// RUN: -fsycl-dump-device-code=/user/input/path %s 2>&1 \
+// RUN: -Qsave-offload-code=/user/input/path %s 2>&1 \
 // RUN: | FileCheck -check-prefix=CHECK-PTX-WIN %s
 
 // Windows - Check if PTX and SPV files are saved in user provided path.
 // RUN: %clang_cl -### -fsycl \
 // RUN: -fsycl-targets=nvptx64-nvidia-cuda,spir64-unknown-unknown --cuda-path=%S/Inputs/CUDA/usr/local/cuda \
-// RUN: -fsycl-dump-device-code=/user/input/path %s 2>&1 \
+// RUN: -Qsave-offload-code=/user/input/path %s 2>&1 \
 // RUN: | FileCheck -check-prefixes=CHECK-PTX-WIN,CHECK-SPV-WIN %s
 
-// Windows - Check PTX files saved in current working directory when -fsycl-dump-device-code
+// Windows - Check PTX files saved in current working directory when -save-offload-code
 // is empty. 
 // RUN: %clang_cl -### -fsycl \
 // RUN: -fsycl-targets=nvptx64-nvidia-cuda --cuda-path=%S/Inputs/CUDA/usr/local/cuda \
-// RUN: -fsycl-dump-device-code= %s 2>&1 \
+// RUN: -Qsave-offload-code= %s 2>&1 \
 // RUN: | FileCheck -check-prefix=CHECK-PTX-WIN-CWD %s
 
 // CHECK-PTX-WIN: llvm-foreach{{.*}} "--out-ext=s"{{.*}} "--out-dir=/user/input/path{{(/|\\\\)}}" "--" "{{.*}}clang{{.*}}" {{.*}} "-fsycl-is-device" {{.*}}.asm{{.*}}
diff --git a/clang/test/Driver/sycl-deprecated.cpp b/clang/test/Driver/sycl-deprecated.cpp
@@ -10,4 +10,5 @@
 // RUN: %clangxx -fsycl -fno-sycl-use-bitcode %s -### 2>&1 \
 // RUN: | FileCheck %s --check-prefix=CHECK_REPLACE -DOPTION=-fno-sycl-use-bitcode -DOPTION_REPLACE=-fsycl-device-obj=spirv
 // RUN: %clangxx -fsycl -fsycl-fp32-prec-sqrt %s -### 2>&1 | FileCheck %s --check-prefix=CHECK_REPLACE -DOPTION=-fsycl-fp32-prec-sqrt -DOPTION_REPLACE=-foffload-fp32-prec-sqrt
+// RUN: %clangxx -fsycl -fsycl-dump-device-code=/path/to/spv/ %s -### 2>&1 | FileCheck %s --check-prefix=CHECK_REPLACE -DOPTION=-fsycl-dump-device-code=/path/to/spv/ -DOPTION_REPLACE=-save-offload-code=/path/to/spv/
 // CHECK_REPLACE: option '[[OPTION]]' is deprecated and will be removed in a future release, use '[[OPTION_REPLACE]]' instead
diff --git a/clang/test/Driver/sycl-dump-device-code-old-model.cpp b/clang/test/Driver/sycl-dump-device-code-old-model.cpp
diff --git a/clang/test/Driver/sycl-dump-device-code.cpp b/clang/test/Driver/sycl-dump-device-code.cpp
diff --git a/clang/test/Driver/sycl-save-offload-code-old-model.cpp b/clang/test/Driver/sycl-save-offload-code-old-model.cpp
@@ -0,0 +1,35 @@
+// SYCL offloading tests using -save-offload-code
+
+// Verify that -save-offload-code puts the device code (.spv files)
+// in the user provided directory.
+
+// Linux
+// clang -fsycl --no-offload-new-driver -target x86_64-unknown-linux-gnu
+// RUN: %clang -fsycl --no-offload-new-driver -fno-sycl-instrument-device-code -fno-sycl-device-lib=all -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code
+
+// clang -fsycl --no-offload-new-driver -fsycl-targets=spir64-unknown-unknown
+// RUN: %clang -fsycl --no-offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code
+
+// clang --driver-mode=g++
+// RUN: %clangxx -fsycl --no-offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code
+
+// Windows
+// RUN: %clang_cl -fsycl --no-offload-new-driver -Qsave-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-WIN
+
+// CHK-save-offload-code: llvm-foreach{{.*}} "--out-dir=/user/input/path{{(/|\\\\)}}" "--" "{{.*}}llvm-spirv"
+// CHK-save-offload-code-WIN: llvm-foreach{{.*}} "--out-dir=/user/input/path{{(/|\\\\)}}" "--" "{{.*}}llvm-spirv"
+
+// Linux
+// RUN: %clang -fsycl --no-offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code= %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-CWD
+
+// Windows
+// RUN: %clang_cl -fsycl --no-offload-new-driver -Qsave-offload-code= %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-WIN-CWD
+
+// CHK-save-offload-code-CWD: llvm-foreach{{.*}} "--out-dir=.{{(/|\\\\)}}" "--" "{{.*}}llvm-spirv"
+// CHK-save-offload-code-WIN-CWD: llvm-foreach{{.*}} "--out-dir=.{{(/|\\\\)}}" "--" "{{.*}}llvm-spirv"
diff --git a/clang/test/Driver/sycl-save-offload-code.cpp b/clang/test/Driver/sycl-save-offload-code.cpp
@@ -0,0 +1,34 @@
+// SYCL offloading tests using -save-offload-code
+
+// Verify that -save-offload-code passes the option to
+// clang-linker-wrapper in the new offload model.
+
+// clang -fsycl --offload-new-driver -target x86_64-unknown-linux-gnu
+// RUN: %clang -fsycl --offload-new-driver -fno-sycl-instrument-device-code -fno-sycl-device-lib=all -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-NEW-OFFLOAD
+
+// clang -fsycl --offload-new-driver -fsycl-targets=spir64-unknown-unknown
+// RUN: %clang -fsycl --offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-NEW-OFFLOAD
+
+// clang --driver-mode=g++
+// RUN: %clangxx -fsycl --offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-NEW-OFFLOAD
+
+// Windows
+// RUN: %clang_cl -fsycl --offload-new-driver -Qsave-offload-code=/user/input/path %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-WIN-NEW-OFFLOAD
+
+// CHK-save-offload-code-NEW-OFFLOAD: clang-linker-wrapper{{.*}} "-sycl-dump-device-code=/user/input/path"
+// CHK-save-offload-code-WIN-NEW-OFFLOAD: clang-linker-wrapper{{.*}} "-sycl-dump-device-code=/user/input/path"
+
+// Linux
+// RUN: %clang -fsycl --offload-new-driver  -fsycl-targets=spir64-unknown-unknown -target x86_64-unknown-linux-gnu -save-offload-code= %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-CWD-NEW-OFFLOAD
+
+// Windows
+// RUN: %clang_cl -fsycl --offload-new-driver -Qsave-offload-code= %s -### 2>&1 \
+// RUN: | FileCheck %s --check-prefixes=CHK-save-offload-code-WIN-CWD-NEW-OFFLOAD
+
+// CHK-save-offload-code-CWD-NEW-OFFLOAD: clang-linker-wrapper{{.*}} "-sycl-dump-device-code="
+// CHK-save-offload-code-WIN-CWD-NEW-OFFLOAD: clang-linker-wrapper{{.*}} "-sycl-dump-device-code="
diff --git a/sycl/doc/UsersManual.md b/sycl/doc/UsersManual.md
diff --git a/sycl/test-e2e/LLVMIntrinsicLowering/bitreverse.cpp b/sycl/test-e2e/LLVMIntrinsicLowering/bitreverse.cpp
diff --git a/sycl/test-e2e/LLVMIntrinsicLowering/sub_byte_bitreverse.cpp b/sycl/test-e2e/LLVMIntrinsicLowering/sub_byte_bitreverse.cpp
