[SYCL][Doc] Update --device-compiler option and remove FPGA support from OffloadDesign.md by YixingZhang007 · Pull Request #21037 · intel/llvm

YixingZhang007 · 2026-01-12T18:07:30Z

This PR modifies the backend compiler options passed to clang-linker-wrapper and removes FPGA descriptions from OffloadDesign.md. Detailed explanations are below:

In PR [NewOffloadModel] Pass link-time options through device-compiler and device-linker argument for ClangLinkerWrapper #20691, we modified the link-time compiler option to be passed through --device-compiler instead of through --cpu-tool-arg and --gpu-tool-arg. We update OffloadDesign.md to include the usage and format of --device-compiler.
As described in Remove FPGA features from DPC++ #16929 and PR [SYCL][Driver][FPGA] Remove support for FPGA related options #16864, we are removing support for FPGA features and their related options from DPC++. We update OffloadDesign.md to remove any FPGA-related descriptions.

YixingZhang007 · 2026-01-13T23:09:08Z

sycl/doc/design/OffloadDesign.md

-resemble `--gpu-tool-arg=<arch> <arg>`.  This corresponds to the existing
+resemble `--device-compiler=sycl:spir64_gen-unknown-unknown==<arch> <arg>`.  This corresponds to the existing
 option syntax of `-fsycl-targets=intel_gpu_arch` where `arch` can be a fixed
 set of targets.


I am not sure if this is still what we want to support, because currently, the backend compiler arguments for all architectures are passed together through a single --device-compiler= argument. For the example shown earlier in this file, if we have the following:

clang++ -fsycl -fsycl-targets=intel_gpu_skl,spir64_gen \ -Xsycl-target-backend=spir64_gen "-device pvc -options -extraopt_pvc" \ -Xsycl-target-backend=intel_gpu_skl "-options -extraopt_skl"

the clang-linker-wrapper command right now looks like:

clang-linker-wrapper ... \ --device-compiler=sycl:spir64_gen-unknown-unknown \ =-device pvc -options -extraopt_pvc -options -extraopt_skl ...

Then in clang-linker-wrapper, it will execute ocloc with both -device pvc -options -extraopt_pvc and -options -extraopt_skl for both PVC and SKL.

If we still want to keep the original proposed solution of separating the arguments for different architectures in clang-linker-wrapper, this will be something we need to implement next.

Interesting, should not we call ocloc specifying both pvc and skl as -device options?
What does old offloading model do for this scenario?
@mdtoguchi , I believe, original design came from you, could you please comment?

I think we need to retain this capability to allow for passing along specific values for each potential arch target. Each individual target arch provided performs a separate ocloc call.

But does it make sense to you that we are calling ocloc with such options? -device pvc -options -extraopt_pvc -options -extraopt_skl
should not it be something like: -device pvc -options -extraopt_pvc -device skl -options -extraopt_skl?
or maybe 2 calls to ocloc?

in other words, it looks like we are calling ocloc to compile for pvc target, while inital clang++ command line asks to compile for 2 targets: pvc and skl.

I tried modifying the clang-linker-wrapper with two separate --device-compiler options, one for each architecture, as shown below (right now the arguments for both arch are passed through a single --device-compiler option) :

clang-linker-wrapper ... \ "--device-compiler=sycl:spir64_gen-unknown-unknown=-device pvc -options -extraopt_pvc" \ "--device-compiler=sycl:spir64_gen-unknown-unknown=-device skl -options -extraopt_skl"

The ocloc commands got called is shown below.

ocloc ... -device skl -device_options pvc -device pvc -options -extraopt_pvc -device skl -options -extraopt_skl ... ocloc ... -device pvc -device_options pvc -device pvc -options -extraopt_pvc -device skl -options -extraopt_skl ...

I think we may still need to implement filtering logic in clang-linker-wrapper so that each --device-compiler option is only applied to its corresponding architecture @YuriPlyakhin

yes, as we discussed on the meeting, we also need to do more experiments to better understand implemented behavior for old offloading model as well.

I have looked into the behavior of the old offloading model for multiple devices. The argument passing into the ocloc command is different for old and new offloading models.

For example, we run the following clang command with the old offloading model:

clang++ ... -fsycl-targets=intel_gpu_dg1,spir64_gen -Xsycl-target-backend=spir64_gen "-device pvc -options -extraopt_pvc" -Xsycl-target-backend=intel_gpu_dg1 "-options -extraopt_dg1" ...

The ocloc commands run for the old offloading model are:

ocloc ... -device dg1 -device_options pvc ... -options -extraopt_dg1 ... ocloc ... -device_options pvc -device pvc ... -options -extraopt_pvc -options -extraopt_dg1 ...

@YuriPlyakhin @mdtoguchi I don't think the ocloc commands are correct for the old offloading model, because the backend option that was passed for dg1 is also passed to pvc as well (however, the options passed to ocloc for dg1 is correct).

hmm, how is -device_options pvc correct for dg1?
If the old offloading model is broken, I guess we can just make new offloading model to work correctly then. And we should not break any old-offloading model scenarios. So, could we implement something like what I proposed in #21037 (comment)?
and yes, for that solution additional filtering will be needed in clang-linker-wrapper based on -device ... value

Looking at the behaviors with when mixing -fsycl-targets=spir64_gen and -fsycl-targets=intel_gpu_dg1 in your example, the driver doesn't seem to differentiate things that when assigned to spir64_gen should only go to spir64_gen explicit targets and is applying to all spir64_gen targets. Underlying triple target with intel_gpu_dg1 is spir64_gen so the driver looks to be generalizing the options at that point and passing the -Xsycl-target-backend=spir64_gen to all of the related ocloc calls.

Due to the fact that spir64_gen is more of a 'generic' value it's not clear to me if what we are doing is correct or if we should be more explicit in option passing management.

mdtoguchi · 2026-01-13T23:37:01Z

sycl/doc/design/OffloadDesign.md

 the `spir64_gen` architecture triple, the resulting extracted binary is linked,
 post-link processed and converted to SPIR-V before being passed to `ocloc` to
-generate the final device binary.  Options passed via `--gpu-tool-arg=` will
+generate the final device binary.  Options passed via `--device-compiler=` will


The --device-compiler usage here should be extended to include the spir64_gen target as it is specific for options to ocloc

Thanks for the suggestion! I have update this to be --device-compiler=sycl:spir64_gen-unknown-unknown=<arg>

mdtoguchi · 2026-01-13T23:40:35Z

sycl/doc/design/OffloadDesign.md

-> --gpu-tool-arg="-device pvc -options extraopt_pvc"
--gpu-tool-arg="-options -extraopt_skl"
+> "--device-compiler=sycl:spir64_gen-unknown-unknown=-device pvc -options extraopt_pvc"
+"--device-compiler=sycl:spir64_gen-unknown-unknown=-options -extraopt_skl"


It looks like the syntax of the options passed is slightly different (quotes around the entire option as opposed to just the arg). Was the original usage of --gpu-tool-arg not correct here?

Yes, I think the documentation of --gpu-tool-arg here is different from what it generates when I do clang++ ... -v. Without the recent changes for --device-compiler, I see the clang-linker-wrapper command that got generated when we do clang++ ... -v is clang-linker-wrapper ... "--gpu-tool-arg=-device pvc -options -extraopt_pvc -options -extraopt_skl" ... which the quotation mark is wrapped around the whole --gpu-tool-arg option.

Thanks - as long as the clang-linker-wrapper is parsing the information correctly how it is represented here is inconsequential.

mdtoguchi · 2026-01-13T23:42:33Z

sycl/doc/design/OffloadDesign.md

-resemble `--gpu-tool-arg=<arch> <arg>`.  This corresponds to the existing
+resemble `--device-compiler=sycl:spir64_gen-unknown-unknown==<arch> <arg>`.  This corresponds to the existing
 option syntax of `-fsycl-targets=intel_gpu_arch` where `arch` can be a fixed
 set of targets.


I think we need to retain this capability to allow for passing along specific values for each potential arch target. Each individual target arch provided performs a separate ocloc call.

YixingZhang007 · 2026-04-07T20:18:42Z

Currently, support for clang-linker-wrapper to pass backend options for a specific device or for multiple device architectures is still under discussion (see CMPLRLLVM-73054). Once the discussion is complete, a separate PR will be needed to update OffloadDesign.md.

This PR will focus solely on two changes: replacing --cpu-tool-arg and --gpu-tool-arg with --device-compiler, and removing the documentation related to FPGA.

YixingZhang007 commented Jan 13, 2026

View reviewed changes

YixingZhang007 marked this pull request as ready for review January 13, 2026 23:13

YixingZhang007 requested a review from a team as a code owner January 13, 2026 23:13

YixingZhang007 requested review from YuriPlyakhin, maksimsab, mdtoguchi and slawekptak January 13, 2026 23:13

mdtoguchi reviewed Jan 13, 2026

View reviewed changes

YixingZhang007 requested a review from mdtoguchi January 14, 2026 17:10

YixingZhang007 and others added 6 commits February 9, 2026 01:11

Add initial draft of change

108dd3a

update the description for AOT compilation

2fb7eec

code clean up

79be1c1

code clean up

ece55ed

resolve comment

9314eb9

update the description for --device-compiler

008d3a2

YixingZhang007 force-pushed the update_documentation branch from eea246b to 008d3a2 Compare February 9, 2026 00:37

YixingZhang007 mentioned this pull request Feb 20, 2026

[NewOffloadModel] Add support for passing backend options for multiple device architectures #21140

Open

yixing.zhang added 2 commits April 7, 2026 22:01

remove the doc update for passing for multiple device architecture

f27d7c5

fix bug

bb81be6

Conversation

YixingZhang007 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

YixingZhang007 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YixingZhang007 Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YixingZhang007 Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YixingZhang007 commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

YixingZhang007 commented Jan 12, 2026 •

edited

Loading

YixingZhang007 Jan 13, 2026 •

edited

Loading

YixingZhang007 Jan 15, 2026 •

edited

Loading

YixingZhang007 Jan 16, 2026 •

edited

Loading