Skip to content

Commit 7b46b20

Browse files
YixingZhang007yixing.zhang
andauthored
[SYCL][Doc] Update --device-compiler option and remove FPGA support from OffloadDesign.md (#21037)
This PR modifies the backend compiler options passed to clang-linker-wrapper and removes FPGA descriptions from OffloadDesign.md. Detailed explanations are below: 1. In PR #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`. 2. As described in #16929 and PR #16864, we are removing support for FPGA features and their related options from DPC++. We update OffloadDesign.md to remove any FPGA-related descriptions. --------- Co-authored-by: yixing.zhang <yixingzh@smtp.igk.intel.com>
1 parent 217f6b9 commit 7b46b20

1 file changed

Lines changed: 19 additions & 62 deletions

File tree

sycl/doc/design/OffloadDesign.md

Lines changed: 19 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ to be taken.
107107
For example, when an embedded device binary is of the `OFK_SYCL` kind and of
108108
the `spir64_gen` architecture triple, the resulting extracted binary is linked,
109109
post-link processed and converted to SPIR-V before being passed to `ocloc` to
110-
generate the final device binary. Options passed via `--gpu-tool-arg=` will
110+
generate the final device binary. Options passed via `--device-compiler=sycl:spir64_gen-unknown-unknown=<arg>` will
111111
be applied to the `ocloc` step as well.
112112

113113
Binaries generated during the offload compilation will be 'bundled' together
@@ -233,25 +233,32 @@ to create the image.
233233

234234
To support the needed option passing triggered by use of the
235235
`-Xsycl-target-backend` option and implied options based on the optional
236-
device behaviors for AOT compilations for GPU new command line interfaces
236+
device behaviors for AOT compilations for GPU and CPU, new command line interfaces
237237
are needed to pass along this information.
238238

239-
| Target | Triple | Offline Tool | Option for Additional Args |
240-
|--------|---------------|----------------|----------------------------|
241-
| CPU | spir64_x86_64 | opencl-aot | `--cpu-tool-arg=<arg>` |
242-
| GPU | spir64_gen | ocloc | `--gpu-tool-arg=<arg>` |
243-
| FPGA | spir64_fpga | aoc/opencl-aot | `--fpga-tool-arg=<arg>` |
239+
| Target | Triple | Offline Tool | Option for Additional Args |
240+
|--------|---------------|----------------|------------------------------------------------------------------|
241+
| CPU | spir64_x86_64 | opencl-aot | `--device-compiler=sycl:spir64_x86_64-unknown-unknown=<arg>` |
242+
| GPU | spir64_gen | ocloc | `--device-compiler=sycl:spir64_gen-unknown-unknown=<arg>` |
244243

245244
*Table: Ahead of Time Info*
246245

246+
#### Format of the --device-compiler Option
247+
The `--device-compiler` option uses the format `--device-compiler=[<kind>:][<triple>=]<value>` where:
248+
- `<kind>` : specifies the offloading kind (e.g., sycl, hip, openmp) and is optional.
249+
- `<triple>` : specifies the target triple (e.g., `spir64_gen-unknown-unknown`, `spir64_x86_64-unknown-unknown`) and is optional.
250+
- `<value>` : contains the arguments to be passed to the backend compiler.
251+
252+
In clang-linker-wrapper, the `<kind>` and `<triple>` are matched against the current compilation target. Only arguments that match both the offloading kind and target triple will be passed to the backend compiler. If `<kind>` is not specified, the arguments will match any offloading kind; if `<triple>` is not specified, the arguments will match any target triple; and if neither is specified, the arguments will be applied to all targets.
253+
254+
#### Other Supported Options
247255
To complete the support needed for the various targets using the
248256
`clang-linker-wrapper` as the main interface, a few additional options will
249257
be needed to communicate from the driver to the tool. Further details of usage
250258
are given further below.
251259

252260
| Option Name | Purpose |
253261
|------------------------------|----------------------------------------------|
254-
| `--fpga-link-type=<arg>` | Tells the link step to perform 'early' or 'image' processing to create archives for FPGA |
255262
| `--parallel-link-sycl=<arg>` | Provide the number of parallel jobs that will be used when processing split jobs |
256263

257264
*Table: Additional Options for clang-linker-wrapper*
@@ -282,8 +289,8 @@ list to be passed along.
282289

283290
*Example: spir64_gen enabling options*
284291

285-
> --gpu-tool-arg="-device pvc -options extraopt_pvc"
286-
--gpu-tool-arg="-options -extraopt_skl"
292+
> "--device-compiler=sycl:spir64_gen-unknown-unknown=-device pvc -options extraopt_pvc"
293+
"--device-compiler=sycl:spir64_gen-unknown-unknown=-options -extraopt_skl"
287294

288295
*Example: clang-linker-wrapper options*
289296

@@ -292,7 +299,7 @@ individually wrapped and linked into the final executable.
292299

293300
Additionally, the syntax can be expanded to enable the ability to pass specific
294301
options to a specific device GPU target for spir64_gen. The syntax will
295-
resemble `--gpu-tool-arg=<arch> <arg>`. This corresponds to the existing
302+
resemble `--device-compiler=sycl:spir64_gen-unknown-unknown=<arch> <arg>`. This corresponds to the existing
296303
option syntax of `-fsycl-targets=intel_gpu_arch` where `arch` can be a fixed
297304
set of targets.
298305

@@ -418,64 +425,14 @@ lists the accepted values.
418425
| GCN GFX12 (RDNA 4) architecture | gfx1200 |
419426
| GCN GFX12 (RDNA 4) architecture | gfx1201 |
420427

421-
#### spir64_fpga support
422-
423-
Compilation behaviors involving AOT for FPGA involve an additional call to
424-
either `aoc` (for Hardware/Simulation) or `opencl-aot` (for Emulation). This
425-
call occurs after the post-link step performed by `sycl-post-link` and the
426-
SPIR-V translation step performed by `llvm-spirv`. Additional options passed
427-
by the user via the `-Xsycl-target-backend=spir64_fpga <opts>` command will be
428-
processed by a new options to the wrapper,
429-
`--fpga-tool-arg=<arg>`
430-
431-
The FPGA target also has support for additional generated binaries that
432-
contain intermediate files specific for FPGA. These binaries (aoco, aocr and
433-
aocx) can reside in archives and are treated differently than traditional
434-
device binaries.
435-
436-
Generation of the AOCR and AOCX type binary is triggered by the command line
437-
option `-fsycl-link`, where `-fsycl-link=image` creates AOCX archives and
438-
`-fsycl-link=early` generates AOCR archives. The files generated by these
439-
options are handled in a specific manner when encountered.
440-
441-
Any archive with an AOCR type device binary will have the AOCR binary
442-
extracted and passed to `aoc` to produce an AOCX final image. This final
443-
image is wrapped and added to the final binary during the host link. The use
444-
of `-fsycl-link=image` with an AOCR binary will create an AOCX based archive
445-
instead of completing the host link. Any archive with an AOCX type device
446-
binary skips the `aoc` step and is wrapped and added to the final binary during
447-
the host link. Archives with any AOCO device binaries are extracted and passed
448-
through to `aoc -library-list=<listfile>`
449-
450-
As the `clang-linker-wrapper` is responsible for understanding the archives
451-
that are added on the command line, it will need to know when to look for
452-
these unique device binaries based on the expected compilation targets. The
453-
behavior of creating the AOCX/AOCR type archive will be triggered via an
454-
additional command line option specified by the driver when `-fsycl-link`
455-
options are used. The `--fpga-link=<type>` option will tell the wrapper when
456-
these handlings need to occur.
457-
458-
When using the `-fintelfpga` option to enable AOT for FPGA, there are
459-
additional expectations during the compilation. Use of the option will enable
460-
debug generation and also generate dependency information. The dependency
461-
generation should be packaged along with the device binary for use during
462-
the link phase. It is expected that the full fat object, containing host,
463-
device and dependency file is generated before being passed to the link phase.
464-
The dependency information is only used when compiling for hardware.
465-
466-
The `clang-linker-wrapper` tool will be responsible to determine which FPGA
467-
tool is being used during the AOT device compilation phase. The use of
468-
`-simulation` or `-hardware` as passed in by `--fpga-tool-arg` signifies
469-
which tool is used.
470-
471428
#### spir64_x86_64 support
472429

473430
Compilation behaviors involving AOT for CPU involve an additional call to
474431
`opencl-aot`. This call occurs after the post-link step performed by
475432
`sycl-post-link` and the SPIR-V translation step performed by `llvm-spirv`.
476433
Additional options passed by the user via the
477434
`-Xsycl-target-backend=spir64_x86_64 <opts>` command will be processed by a new
478-
option to the wrapper, `--cpu-tool-arg=<arg>`
435+
option to the wrapper, `--device-compiler=sycl:spir64_x86_64-unknown-unknown=<arg>`
479436

480437
Similar to SYCL offloading to Intel GPUs using `--offload-arch`, SYCL AOT for Intel CPUs
481438
will also leverage the `--offload-arch` option.

0 commit comments

Comments
 (0)