From 14e2cac42f50891a9314189cf29addf6e8cca45e Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Fri, 3 Oct 2025 19:41:18 +0200 Subject: [PATCH 1/7] [SYCL][Doc] RFC draft for SYCLBIN format Not to be merged to `sycl` branch. Created for discussion and feedback. --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 325 ++++++++++++++++++++ 1 file changed, 325 insertions(+) create mode 100644 sycl/doc/design/RFC_drafts/SYCLBINDesign.md diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md new file mode 100644 index 0000000000000..a25d8dc7a9735 --- /dev/null +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -0,0 +1,325 @@ +# [RFC] SYCLBIN - A format for SYCL device code + +## Summary + +This RFC proposes the addition of SYCLBIN, a new binary format for storing SYCL device code. The format provides a lightweight, extensible wrapper around device modules and their corresponding SYCL-specific metadata to be produced/consumed by tools/SYCL runtime. + +## Purpose of this RFC + +This RFC seeks community feedback on the proposed SYCLBIN binary format design, including: + +- The binary format specification and layout +- Toolchain integration approach and new compiler flags + +Community input is particularly valuable regarding potential integration challenges with existing LLVM offloading implementations. + +## Motivation and alternatives considered + +### Metadata unique for SYCL programming model + +- [ ] This section needs re-writing... + +LLVM offloading infrastructure supports the following binary formats: Object, Bitcode, Cubin, Fatbinary, PTX and SPIRV which could be placed into OffloadBinary format. None of it satisfies the needs of SYCL programming model. + +- [ ] Steffen, I need to discuss with you, why other existing formats did not satisfy our needs. I think we need to provide short summary why each format doesn't work for us somewhere in this section. + +Specifically, SYCL needs to keep the following metadata necessary for SYCL runtime, which is not supported by any of existing formats: + +1. Device target triple (e.g. spirv64_unknown_unknown). +2. Compiler and linker options to pass to JIT compiler in case of JITing. +3. List of entry points exposed by an image +4. Arrays of property sets. + +While #1 and #2 can be saved to StringData of OffloadBinary, #3 requires additional handling, since StringData serialization infrastructure assumes that value is a single null-terminated string, so to restore multiple null-terminated strings from StringData format, they need to be concatenated with split symbol and then split during deserialization. + +[Property sets](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/PropertySets.md) (#4) would be even more complicated. + +### Abstraction: simplify support in offloading tools + +Another motivation to add SYCLBIN format is to encapsulate SYCL-specific logic to SYCL-specific parts of toolchain (clang-sycl-linker, SYCL runtime) and hide SYCL specifics from offloading tools intended to support multiple programming models. Without this format, we would need to use the following workflow to pass metadata (#1 - #4) from compiler to runtime: + +1. clang-sycl-linker would use OffloadingImage’s StringData to save metadata #1-#4. +Problem: OffloadingImage’s StringData is not intended for composite objects like arrays or property sets. +2. clang-linker-wrapper would open OffloadingImages prepared by clang-sycl-linker and generate device image binary descriptor for each image in some format that SYCL runtime could read. +Problem: clang-linker-wrapper needs to maintain SYCL-specific formats necessary for SYCL runtime, which means unnecessary duplication. +3. Then SYCL runtime would use this format to decode metadata. + +If SYCLBIN is accepted, then the scheme could be simplified, resolving problems highlighted above: + +1. clang-sycl-linker would prepare SYCLBIN with all metadata encoded put it inside OffloadingImage as image. +2. clang-linker-wrapper would generate only host register and unregister calls, but would know nothing about what’s inside SYCLBIN. +3. SYCL runtime would work with SYCLBIN directly. + +### Enable modular dynamic loading of device binaries at runtime + +Some applications may want to dynamically load device binaries at runtime, e.g. for modularity and to avoid having to recompile the entire application. To facilitate that SYCLBIN format defines the interface between +the compiler-produced binaries and the runtime's handling of it. + +## Detailed Design + +### SYCLBIN binary format + +The SYCLBIN format consists of: + +- A [file header](#file-header) with magic number (0x53594249 "SYBI") and version information +- Three lists of headers: the [abstract module header](#abstract-module-header) list, the +[IR module header](#ir-module-header) list and +[native device code image header](#native-device-code-image-header) list, +containing information about the [abstract modules](#abstract-module), +[IR modules](#ir-module) and +[native device code images](#native-device-code-image) respectively. +- Two byte tables containing metadata and binary data + +#### File Structure + +| | +| --------------------------------------------------------------------- | +| [File header](#file-header) | +| [Abstract module header](#abstract-module-header) 1 | +| ... | +| [Abstract module header](#abstract-module-header) N | +| [IR module header](#ir-module-header) 1 | +| ... | +| [IR module header](#ir-module-header) M | +| [Native device code image header](#native-device-code-image-header) 1 | +| ... | +| [Native device code image header](#native-device-code-image-header) L | +| Metadata byte table | +| Binary byte table | + +The headers and each byte table are all aligned to 8 bytes. The fields in the +headers use C/C++ type notation, including the fixed-size integer types defined +in the `` header, and will have the same size and alignment. For +consistency, all these types use little endian layout. + +#### Component Details + +- [ ] Do we want to provide that level of details in the RFC, or it is better to clean it up to +keep only key info and for details provide reference to design document? + +##### File header + +| Type | Description | +| ---------- | ----------------------------------------------------------------------------- | +| `uint32_t` | Magic number. (0x53594249) | +| `uint32_t` | SYCLBIN version number. | +| `uint32_t` | Number of abstract modules. | +| `uint32_t` | Number of IR modules. | +| `uint32_t` | Number of native device code images. | +| `uint64_t` | Byte size of the metadata byte table. | +| `uint64_t` | Byte size of the binary byte table. | +| `uint64_t` | Byte offset of the global metadata from the start of the metadata byte table. | +| `uint64_t` | Byte size of the global metadata. | + +##### Global metadata + +The global metadata entry contains a single property set with the identifying +name "SYCLBIN/global metadata", as described in the +[PropertySets.md](PropertySets.md#syclbinglobal-metadata) design document. + +##### Abstract module + +An abstract module is a collection of device binaries that share properties, +including, but not limited to: kernel names, imported symbols, exported symbols, +aspect requirements, and specialization constants. + +The device binaries contained inside an abstract module must either be an IR +module or a native device code image. IR modules contain device binaries in some +known intermediate representation, such as SPIR-V, while the native device code +images can be an architecture-specific binary format. There is no requirement +that all device binaries in an abstract module are usable on the same device or +are specific to a single vendor. + +##### Abstract module header + +A abstract module header contains the following fields in the stated order: + +| Type | Description | +| ---------- | ------------------------------------------------------------------------------------------ | +| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | +| `uint64_t` | Byte size of the metadata in the metadata byte table. | +| `uint32_t` | Number of IR modules. | +| `uint32_t` | Index of the first IR module header in the IR module header array. | +| `uint32_t` | Number of native device code images. | +| `uint32_t` | Index of the first native device code images header native device code image header array. | + +##### Abstract module metadata + +An abstract module metadata entry contains any number of property sets, as +described in [PropertySets.md](PropertySets.md), excluding: + +- ["SYCLBIN/global metadata"](PropertySets.md#syclbinglobal-metadata) +- ["SYCLBIN/ir module metadata"](PropertySets.md#syclbinir-module-metadata) +- ["SYCLBIN/native device code image module metadata"](PropertySets.md#syclbinnative-device-code-image-metadata) + +##### IR module + +An IR module contains the binary data for the corresponding module compiled to a +given IR representation, identified by the IR type field. + +##### IR module header + +A IR module header contains the following fields in the stated order: + +| Type | Description | +| ---------- | ------------------------------------------------------------------------ | +| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | +| `uint64_t` | Byte size of the metadata in the metadata byte table. | +| `uint64_t` | Byte offset of the raw IR bytes from the start of the binary byte table. | +| `uint64_t` | Byte size of the raw IR bytes in the binary byte table. | + +##### IR module metadata + +An IR module metadata entry contains a single property set with the identifying +name "SYCLBIN/ir module metadata", as described in the +[PropertySets.md](PropertySets.md#syclbinir-module-metadata) design document. + +##### Native device code image + +An native device code image contains the binary data for the corresponding +module AOT compiled for a specific device, identified by the architecture +string. The runtime library will attempt to map these to the architecture +enumerators in the +[sycl_ext_oneapi_device_architecture](../extensions/experimental/sycl_ext_oneapi_device_architecture.asciidoc) +extension. + +##### Native device code image header + +A native device code image header contains the following fields in the stated +order: + +| Type | Description | +| ---------- | ----------------------------------------------------------------------------------- | +| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | +| `uint64_t` | Byte size of the metadata in the metadata byte table. | +| `uint64_t` | Byte offset of the device code image bytes from the start of the binary byte table. | +| `uint64_t` | Byte size of the device code image bytes in the binary byte table. | + +##### Native device code image metadata + +A native device code image metadata entry contains a single property set with +the identifying name "SYCLBIN/native device code image module metadata", as +described in the +[PropertySets.md](PropertySets.md#syclbinnative-device-code-image-metadata) +design document. + +##### Byte tables + +A byte table contains dynamic data, such as metadata and binary blobs. The +contents of it is generally referenced by an offset specified in the headers. + +## Toolchain integration + +The content of the SYCLBIN may be contained as an image in the [offload binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/tree/main/clang/tools/clang-sycl-linker). + +### Clang driver changes + +- [ ] This needs to be rewritten... + +The clang driver needs to accept the following new flags: + + + + + + + + + + + + + + +
OptionDescription
`-fsyclbin` +If this option is set, the output of the invocation is a SYCLBIN file with the +.syclbin file extension. This skips the host-compilation invocation of the +typical `-fsycl` pipeline, instead passing the output of the +clang-offload-packager invocation to clang-linker-wrapper together with the new +`--syclbin` flag. + +Setting this option will override `-fsycl`. Passing`-fsycl-device-only` with +`-fsyclbin` will cause `-fsyclbin` to be considered unused. + +The behavior is dependent on using the clang-linker-wrapper. +
`--offload-rdc`This is an alias of `-fgpu-rdc`.
+ +Additionally, `-fsycl-link` should work with .syclbin files. Semantics of how +SYCLBIN files are linked together is yet to be specified. + +### clang-sycl-linker changes + +- [ ] to be updated... + +The clang-linker-wrapper is responsible for doing module-splitting, metadata +extraction and linking of device binaries, as described in +[OffloadDesign.md](OffloadDesign.md). However, to support SYCLBIN files, the +clang-linker-wrapper must be able to unpack an offload binary (as described in +[ClangOffloadPackager.rst](https://github.com/intel/llvm/blob/sycl/clang/docs/ClangOffloadPackager.rst)) +directly, instead of extracting it from a host binary. This should be done when +a new flag, `--syclbin`, is passed. In this case, the clang-linker-wrapper is +responsible to package the resulting device binaries and produced metadata into +the format described in [SYCLBIN binary format section](#syclbin-binary-format). + +### clang-linker-wrapper changes + +- [ ] to be updated... + +Additionally, in this case the clang-linker-wrapper will skip the wrapping of +the device code and the host code linking stage, as there is no host code to +wrap the device code in and link. + +### SYCL runtime library changes + +- [ ] do we want to provide details in RFC or limit it to basic info? + +Using the interfaces from the +[sycl_ext_oneapi_syclbin](../extensions/proposed/sycl_ext_oneapi_syclbin.asciidoc) +extension, the runtime must be able to parse the SYCLBIN format, as described in +the [SYCLBIN binary format section](#syclbin-binary-format). To avoid large +amounts of code duplication, the runtime uses the implementation of SYCLBIN +reading and writing implemented in LLVM. + +When creating a `kernel_bundle` from a SYCLBIN file, the runtime reads the +contents of the SYCLBIN file and creates the corresponding data structure from +it. + +- [ ] this part below needs to be rewritten I think.... + +In order for the SYCL runtime library's existing logic to use the binaries, +the runtime then creates a collection of `sycl_device_binary_struct` objects and +its constituents, pointing to the data in the parsed SYCLBIN object. Passing +these objects to the runtime library's `ProgramManager` allows it to reuse the +logic for compiling, linking and building SYCL binaries. + +In the other direction, users can request the "contents" of a `kernel_bundle`. +When this is done, the runtime library must ensure that a SYCLBIN file is +available for the contents of the `kernel_bundle` and must then write the +SYCLBIN object to the corresponding binary representation in the format +described in the [SYCLBIN binary format section](#syclbin-binary-format). In cases +where the `kernel_bundle` was created with a SYCLBIN file, the SYCLBIN +representation is immediately available and can be serialized directly. In other +cases, the runtime library creates a new SYCLBIN object from the binaries +associated with the `kernel_bundle`, then serializes it and returns the result. + +## Versioning and Extensibility + +The SYCLBIN format is subject to change, but any such changes must come with an +increment to the version number in the header. +Additionally, any changes to the property set structure that affects the way the +runtime has to parse the contained property sets will require an increase in the +SYCLBIN version. Adding new property set names or new predefined properties only +require a SYCLBIN version change if the the SYCLBIN consumer cannot safely +ignore the property. + +## Upstreaming Plan + +- Phase 1: Upstream SYCLBIN format specification, including parsing/writing +- Phase 2: Add clang driver, sycl-linker and linker-wrapper support +- Phase 3: Integrate SYCLBIN support into SYCL runtime + +## Opens, common todos + +- [ ] Do we want to extend SYCL spec with SYCLBIN format? Do we want to somehow mention it in the RFC? Is it relevant? +- [ ] Need to add/update links in this RFC +- [ ] Polish formatting, fix typos, etc... From 0e2ae1846f8f04a615ecfedce8b049b68531a901 Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Tue, 7 Oct 2025 02:22:51 +0200 Subject: [PATCH 2/7] Requirements: SYCL-Specific metadata and modules hierarchy --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 27 ++++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index a25d8dc7a9735..0886ab191aa67 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -15,27 +15,30 @@ Community input is particularly valuable regarding potential integration challen ## Motivation and alternatives considered -### Metadata unique for SYCL programming model +### Requirements: SYCL-Specific metadata and modules hierarchy -- [ ] This section needs re-writing... - -LLVM offloading infrastructure supports the following binary formats: Object, Bitcode, Cubin, Fatbinary, PTX and SPIRV which could be placed into OffloadBinary format. None of it satisfies the needs of SYCL programming model. +The SYCL programming model requires device images to be accompanied by specific metadata necessary for SYCL runtime operation: -- [ ] Steffen, I need to discuss with you, why other existing formats did not satisfy our needs. I think we need to provide short summary why each format doesn't work for us somewhere in this section. +1. Device target triple (e.g. ``spirv64_unknown_unknown``). +2. Compiler and linker options for JIT compilation scenarios +3. List of entry points exposed by each image +4. Arrays of [property sets](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/PropertySets.md). -Specifically, SYCL needs to keep the following metadata necessary for SYCL runtime, which is not supported by any of existing formats: +When a binary contains multiple images, some may share common metadata. Therefore, we require a hierarchical structure that enables metadata sharing while allowing specification of image-specific metadata. -1. Device target triple (e.g. spirv64_unknown_unknown). -2. Compiler and linker options to pass to JIT compiler in case of JITing. -3. List of entry points exposed by an image -4. Arrays of property sets. +#### Existing Format Limitations: -While #1 and #2 can be saved to StringData of OffloadBinary, #3 requires additional handling, since StringData serialization infrastructure assumes that value is a single null-terminated string, so to restore multiple null-terminated strings from StringData format, they need to be concatenated with split symbol and then split during deserialization. +LLVM's offloading infrastructure supports several binary formats that can be embedded within the OffloadBinary format. However, these formats have various limitations that make them unsuitable for SYCL: -[Property sets](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/PropertySets.md) (#4) would be even more complicated. +- **Single-module design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules +- **Missing SYCL metadata support**: None provide native support for SYCL-specific metadata requirements +- **Vendor constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach +- **Limited container capabilities**: OffloadBinary is not designed for multiple device images or hierarchical organization, with StringData insufficient for complex metadata structures (like #3 and #4 above). ### Abstraction: simplify support in offloading tools +- [ ] This section needs re-writing... + Another motivation to add SYCLBIN format is to encapsulate SYCL-specific logic to SYCL-specific parts of toolchain (clang-sycl-linker, SYCL runtime) and hide SYCL specifics from offloading tools intended to support multiple programming models. Without this format, we would need to use the following workflow to pass metadata (#1 - #4) from compiler to runtime: 1. clang-sycl-linker would use OffloadingImage’s StringData to save metadata #1-#4. From 65522c2273d5dea5a2f36f8d0447853497163099 Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Tue, 7 Oct 2025 03:58:01 +0200 Subject: [PATCH 3/7] progress --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 185 ++++---------------- 1 file changed, 30 insertions(+), 155 deletions(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index 0886ab191aa67..a3bc26b3c7099 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -35,30 +35,34 @@ LLVM's offloading infrastructure supports several binary formats that can be emb - **Vendor constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach - **Limited container capabilities**: OffloadBinary is not designed for multiple device images or hierarchical organization, with StringData insufficient for complex metadata structures (like #3 and #4 above). -### Abstraction: simplify support in offloading tools +### Abstraction: Simplifying Support in Offloading Tools -- [ ] This section needs re-writing... +Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific logic within SYCL-specific toolchain components (clang-sycl-linker, SYCL runtime) and isolate SYCL implementation details from general offloading tools designed to support multiple programming models. -Another motivation to add SYCLBIN format is to encapsulate SYCL-specific logic to SYCL-specific parts of toolchain (clang-sycl-linker, SYCL runtime) and hide SYCL specifics from offloading tools intended to support multiple programming models. Without this format, we would need to use the following workflow to pass metadata (#1 - #4) from compiler to runtime: +#### Current Workflow Without SYCLBIN: -1. clang-sycl-linker would use OffloadingImage’s StringData to save metadata #1-#4. -Problem: OffloadingImage’s StringData is not intended for composite objects like arrays or property sets. -2. clang-linker-wrapper would open OffloadingImages prepared by clang-sycl-linker and generate device image binary descriptor for each image in some format that SYCL runtime could read. -Problem: clang-linker-wrapper needs to maintain SYCL-specific formats necessary for SYCL runtime, which means unnecessary duplication. -3. Then SYCL runtime would use this format to decode metadata. +Without this format, metadata transfer from compiler to runtime requires the following complex workflow: -If SYCLBIN is accepted, then the scheme could be simplified, resolving problems highlighted above: +1. **clang-sycl-linker** uses OffloadingImage's StringData (with workarounds) to store metadata items #1-#4 +2. **clang-linker-wrapper** opens OffloadingImage files from clang-sycl-linker and generates device image binary descriptors in a format readable by SYCL runtime +- Problem: This requires clang-linker-wrapper to maintain SYCL-specific format knowledge, creating unnecessary code duplication +3. **SYCL runtime** decodes metadata using this intermediate format -1. clang-sycl-linker would prepare SYCLBIN with all metadata encoded put it inside OffloadingImage as image. -2. clang-linker-wrapper would generate only host register and unregister calls, but would know nothing about what’s inside SYCLBIN. -3. SYCL runtime would work with SYCLBIN directly. +#### Simplified Workflow With SYCLBIN: + +The SYCLBIN format enables a cleaner separation of concerns: + +1. **clang-sycl-linker** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within OffloadingImage +2. **clang-linker-wrapper** generates only host register/unregister calls without needing knowledge of SYCLBIN internals +3. **SYCL runtime** works directly with SYCLBIN format + +This approach eliminates the need for clang-linker-wrapper to understand SYCL-specific formats, reducing maintenance burden and improving toolchain modularity. ### Enable modular dynamic loading of device binaries at runtime -Some applications may want to dynamically load device binaries at runtime, e.g. for modularity and to avoid having to recompile the entire application. To facilitate that SYCLBIN format defines the interface between -the compiler-produced binaries and the runtime's handling of it. +Some applications require dynamic loading of device binaries at runtime to achieve modularity and avoid recompiling the entire application when device code changes. The SYCLBIN format provides a standardized interface between compiler-produced binaries and runtime handling, enabling efficient dynamic loading scenarios. -## Detailed Design +## Design ### SYCLBIN binary format @@ -90,165 +94,36 @@ containing information about the [abstract modules](#abstract-module), | Metadata byte table | | Binary byte table | -The headers and each byte table are all aligned to 8 bytes. The fields in the -headers use C/C++ type notation, including the fixed-size integer types defined -in the `` header, and will have the same size and alignment. For -consistency, all these types use little endian layout. - -#### Component Details - -- [ ] Do we want to provide that level of details in the RFC, or it is better to clean it up to -keep only key info and for details provide reference to design document? - -##### File header - -| Type | Description | -| ---------- | ----------------------------------------------------------------------------- | -| `uint32_t` | Magic number. (0x53594249) | -| `uint32_t` | SYCLBIN version number. | -| `uint32_t` | Number of abstract modules. | -| `uint32_t` | Number of IR modules. | -| `uint32_t` | Number of native device code images. | -| `uint64_t` | Byte size of the metadata byte table. | -| `uint64_t` | Byte size of the binary byte table. | -| `uint64_t` | Byte offset of the global metadata from the start of the metadata byte table. | -| `uint64_t` | Byte size of the global metadata. | - -##### Global metadata +#### Key Components -The global metadata entry contains a single property set with the identifying -name "SYCLBIN/global metadata", as described in the -[PropertySets.md](PropertySets.md#syclbinglobal-metadata) design document. - -##### Abstract module - -An abstract module is a collection of device binaries that share properties, +**Abstract Modules:** collection of device binaries that share properties, including, but not limited to: kernel names, imported symbols, exported symbols, -aspect requirements, and specialization constants. - -The device binaries contained inside an abstract module must either be an IR +aspect requirements, and specialization constants. The device binaries contained inside an abstract module must either be an IR module or a native device code image. IR modules contain device binaries in some known intermediate representation, such as SPIR-V, while the native device code images can be an architecture-specific binary format. There is no requirement that all device binaries in an abstract module are usable on the same device or are specific to a single vendor. -##### Abstract module header - -A abstract module header contains the following fields in the stated order: - -| Type | Description | -| ---------- | ------------------------------------------------------------------------------------------ | -| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | -| `uint64_t` | Byte size of the metadata in the metadata byte table. | -| `uint32_t` | Number of IR modules. | -| `uint32_t` | Index of the first IR module header in the IR module header array. | -| `uint32_t` | Number of native device code images. | -| `uint32_t` | Index of the first native device code images header native device code image header array. | - -##### Abstract module metadata - -An abstract module metadata entry contains any number of property sets, as -described in [PropertySets.md](PropertySets.md), excluding: - -- ["SYCLBIN/global metadata"](PropertySets.md#syclbinglobal-metadata) -- ["SYCLBIN/ir module metadata"](PropertySets.md#syclbinir-module-metadata) -- ["SYCLBIN/native device code image module metadata"](PropertySets.md#syclbinnative-device-code-image-metadata) - -##### IR module - -An IR module contains the binary data for the corresponding module compiled to a +**IR modules:** binary data for the corresponding module compiled to a given IR representation, identified by the IR type field. -##### IR module header - -A IR module header contains the following fields in the stated order: - -| Type | Description | -| ---------- | ------------------------------------------------------------------------ | -| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | -| `uint64_t` | Byte size of the metadata in the metadata byte table. | -| `uint64_t` | Byte offset of the raw IR bytes from the start of the binary byte table. | -| `uint64_t` | Byte size of the raw IR bytes in the binary byte table. | - -##### IR module metadata - -An IR module metadata entry contains a single property set with the identifying -name "SYCLBIN/ir module metadata", as described in the -[PropertySets.md](PropertySets.md#syclbinir-module-metadata) design document. - -##### Native device code image - -An native device code image contains the binary data for the corresponding +**Native device code images:** binary data for the corresponding module AOT compiled for a specific device, identified by the architecture -string. The runtime library will attempt to map these to the architecture -enumerators in the -[sycl_ext_oneapi_device_architecture](../extensions/experimental/sycl_ext_oneapi_device_architecture.asciidoc) -extension. +string. -##### Native device code image header - -A native device code image header contains the following fields in the stated -order: - -| Type | Description | -| ---------- | ----------------------------------------------------------------------------------- | -| `uint64_t` | Byte offset of the metadata from the start of the metadata byte table. | -| `uint64_t` | Byte size of the metadata in the metadata byte table. | -| `uint64_t` | Byte offset of the device code image bytes from the start of the binary byte table. | -| `uint64_t` | Byte size of the device code image bytes in the binary byte table. | - -##### Native device code image metadata - -A native device code image metadata entry contains a single property set with -the identifying name "SYCLBIN/native device code image module metadata", as -described in the -[PropertySets.md](PropertySets.md#syclbinnative-device-code-image-metadata) -design document. - -##### Byte tables - -A byte table contains dynamic data, such as metadata and binary blobs. The +**Byte tables:** A byte table contains dynamic data, such as metadata and binary blobs. The contents of it is generally referenced by an offset specified in the headers. +Detailed design can be found [here](https://intel.github.io/llvm/design/SYCLBINDesign.html) + ## Toolchain integration -The content of the SYCLBIN may be contained as an image in the [offload binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/tree/main/clang/tools/clang-sycl-linker). +The SYCLBIN content is embedded as an image within the [offload binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/tree/main/clang/tools/clang-sycl-linker). ### Clang driver changes -- [ ] This needs to be rewritten... - -The clang driver needs to accept the following new flags: - - - - - - - - - - - - - - -
OptionDescription
`-fsyclbin` -If this option is set, the output of the invocation is a SYCLBIN file with the -.syclbin file extension. This skips the host-compilation invocation of the -typical `-fsycl` pipeline, instead passing the output of the -clang-offload-packager invocation to clang-linker-wrapper together with the new -`--syclbin` flag. - -Setting this option will override `-fsycl`. Passing`-fsycl-device-only` with -`-fsyclbin` will cause `-fsyclbin` to be considered unused. - -The behavior is dependent on using the clang-linker-wrapper. -
`--offload-rdc`This is an alias of `-fgpu-rdc`.
- -Additionally, `-fsycl-link` should work with .syclbin files. Semantics of how -SYCLBIN files are linked together is yet to be specified. +- ``--sycl-link`` would trigger use of a SYCLBIN format in toolchain ### clang-sycl-linker changes From 460ecce36746de4beda76c438e5188e525c49c18 Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Thu, 9 Oct 2025 01:23:19 +0200 Subject: [PATCH 4/7] update --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 168 ++++++-------------- 1 file changed, 53 insertions(+), 115 deletions(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index a3bc26b3c7099..ca600820a270f 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -6,12 +6,7 @@ This RFC proposes the addition of SYCLBIN, a new binary format for storing SYCL ## Purpose of this RFC -This RFC seeks community feedback on the proposed SYCLBIN binary format design, including: - -- The binary format specification and layout -- Toolchain integration approach and new compiler flags - -Community input is particularly valuable regarding potential integration challenges with existing LLVM offloading implementations. +This RFC seeks community feedback on the proposed SYCLBIN binary format, including toolchain integration approach. Community input is particularly valuable regarding potential integration challenges with existing LLVM offloading implementations. ## Motivation and alternatives considered @@ -26,41 +21,41 @@ The SYCL programming model requires device images to be accompanied by specific When a binary contains multiple images, some may share common metadata. Therefore, we require a hierarchical structure that enables metadata sharing while allowing specification of image-specific metadata. -#### Existing Format Limitations: +#### Existing Formats Limitations -LLVM's offloading infrastructure supports several binary formats that can be embedded within the OffloadBinary format. However, these formats have various limitations that make them unsuitable for SYCL: +LLVM's offloading infrastructure supports several binary formats that can be embedded within the [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) format. However, these formats have various limitations that make them unsuitable for SYCL: -- **Single-module design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules -- **Missing SYCL metadata support**: None provide native support for SYCL-specific metadata requirements -- **Vendor constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach -- **Limited container capabilities**: OffloadBinary is not designed for multiple device images or hierarchical organization, with StringData insufficient for complex metadata structures (like #3 and #4 above). +- **Single-module design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules. +- **Missing SYCL metadata support**: None provide native support for SYCL-specific metadata requirements. +- **Vendor constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach. +- **Limited container capabilities**: [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) is not designed for multiple device images or hierarchical organization, with ``StringData`` insufficient for complex metadata structures (like #3 and #4 above). ### Abstraction: Simplifying Support in Offloading Tools -Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific logic within SYCL-specific toolchain components (clang-sycl-linker, SYCL runtime) and isolate SYCL implementation details from general offloading tools designed to support multiple programming models. +Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific logic within SYCL-specific toolchain components ([clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst), SYCL runtime) and isolate SYCL implementation details from general offloading tools designed to support multiple programming models. -#### Current Workflow Without SYCLBIN: +#### Current Workflow Without SYCLBIN -Without this format, metadata transfer from compiler to runtime requires the following complex workflow: +Without this format, metadata transfer from compiler to runtime requires the following complicated workflow: -1. **clang-sycl-linker** uses OffloadingImage's StringData (with workarounds) to store metadata items #1-#4 -2. **clang-linker-wrapper** opens OffloadingImage files from clang-sycl-linker and generates device image binary descriptors in a format readable by SYCL runtime -- Problem: This requires clang-linker-wrapper to maintain SYCL-specific format knowledge, creating unnecessary code duplication +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata items #1-#4 +2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime + - Problem: This requires [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to maintain SYCL-specific format knowledge, creating unnecessary code duplication 3. **SYCL runtime** decodes metadata using this intermediate format -#### Simplified Workflow With SYCLBIN: +#### Simplified Workflow With SYCLBIN The SYCLBIN format enables a cleaner separation of concerns: -1. **clang-sycl-linker** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within OffloadingImage -2. **clang-linker-wrapper** generates only host register/unregister calls without needing knowledge of SYCLBIN internals +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) +2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** generates only host register/unregister calls without needing knowledge of SYCLBIN internals 3. **SYCL runtime** works directly with SYCLBIN format -This approach eliminates the need for clang-linker-wrapper to understand SYCL-specific formats, reducing maintenance burden and improving toolchain modularity. +This approach eliminates the need for [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to understand SYCL-specific formats, reducing maintenance burden and improving toolchain modularity. ### Enable modular dynamic loading of device binaries at runtime -Some applications require dynamic loading of device binaries at runtime to achieve modularity and avoid recompiling the entire application when device code changes. The SYCLBIN format provides a standardized interface between compiler-produced binaries and runtime handling, enabling efficient dynamic loading scenarios. +Some applications require dynamic loading of device binaries at runtime to achieve modularity and avoid recompiling the entire application when device code changes. The SYCLBIN format provides a standardized interface between compiler-produced SYCLBIN binaries and runtime handling, enabling efficient dynamic loading scenarios. ## Design @@ -68,117 +63,66 @@ Some applications require dynamic loading of device binaries at runtime to achie The SYCLBIN format consists of: -- A [file header](#file-header) with magic number (0x53594249 "SYBI") and version information -- Three lists of headers: the [abstract module header](#abstract-module-header) list, the -[IR module header](#ir-module-header) list and -[native device code image header](#native-device-code-image-header) list, -containing information about the [abstract modules](#abstract-module), -[IR modules](#ir-module) and -[native device code images](#native-device-code-image) respectively. +- A file header with magic number and version information +- Three lists of headers: the abstract module header list, the IR module header list and native device code image header list, +containing information about the abstract modules, IR modules and native device code images respectively. - Two byte tables containing metadata and binary data #### File Structure -| | -| --------------------------------------------------------------------- | -| [File header](#file-header) | -| [Abstract module header](#abstract-module-header) 1 | -| ... | -| [Abstract module header](#abstract-module-header) N | -| [IR module header](#ir-module-header) 1 | -| ... | -| [IR module header](#ir-module-header) M | -| [Native device code image header](#native-device-code-image-header) 1 | -| ... | -| [Native device code image header](#native-device-code-image-header) L | -| Metadata byte table | -| Binary byte table | +| | +| --------------------------------- | +| File header | +| Abstract module header 1 | +| ... | +| Abstract module header N | +| IR module header 1 | +| ... | +| IR module header M | +| Native device code image header 1 | +| ... | +| Native device code image header L | +| Metadata byte table | +| Binary byte table | #### Key Components -**Abstract Modules:** collection of device binaries that share properties, -including, but not limited to: kernel names, imported symbols, exported symbols, -aspect requirements, and specialization constants. The device binaries contained inside an abstract module must either be an IR -module or a native device code image. IR modules contain device binaries in some -known intermediate representation, such as SPIR-V, while the native device code -images can be an architecture-specific binary format. There is no requirement -that all device binaries in an abstract module are usable on the same device or -are specific to a single vendor. +**Abstract Modules:** collection of device binaries that share properties, including, but not limited to: exported symbols, [aspect requirements](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/OptionalDeviceFeatures.md), and [specialization constants](https://github.khronos.org/SYCL_Reference/iface/specialization-constants.html). The device binaries contained inside an abstract module must either be an IR module or a native device code image. IR modules contain device binaries in some known intermediate representation, such as SPIR-V, while the native device code images can be an architecture-specific binary format. There is no requirement that all device binaries in an abstract module are usable on the same device or are specific to a single vendor. -**IR modules:** binary data for the corresponding module compiled to a -given IR representation, identified by the IR type field. +**IR modules:** binary data for the corresponding module compiled to a given IR representation, identified by the IR type field. -**Native device code images:** binary data for the corresponding -module AOT compiled for a specific device, identified by the architecture +**Native device code images:** binary data for the corresponding module AOT compiled for a specific device, identified by the architecture string. -**Byte tables:** A byte table contains dynamic data, such as metadata and binary blobs. The -contents of it is generally referenced by an offset specified in the headers. +**Byte tables:** A byte table contains dynamic data, such as metadata and binary blobs. The contents of it is generally referenced by an offset specified in the headers. Detailed design can be found [here](https://intel.github.io/llvm/design/SYCLBINDesign.html) ## Toolchain integration -The SYCLBIN content is embedded as an image within the [offload binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/tree/main/clang/tools/clang-sycl-linker). - -### Clang driver changes +The SYCLBIN content can either be embedded as an image within the [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) or outputted directly as standalone SYCLBIN files. -- ``--sycl-link`` would trigger use of a SYCLBIN format in toolchain +This integration approach allows SYCLBIN to leverage the existing [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) infrastructure while maintaining its specialized format for SYCL-specific requirements. -### clang-sycl-linker changes +### [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) changes -- [ ] to be updated... +The [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) is responsible for module-splitting, metadata extraction (symbol tables, property sets, etc.) and linking of device binaries. To support SYCLBIN, it must be able to: -The clang-linker-wrapper is responsible for doing module-splitting, metadata -extraction and linking of device binaries, as described in -[OffloadDesign.md](OffloadDesign.md). However, to support SYCLBIN files, the -clang-linker-wrapper must be able to unpack an offload binary (as described in -[ClangOffloadPackager.rst](https://github.com/intel/llvm/blob/sycl/clang/docs/ClangOffloadPackager.rst)) -directly, instead of extracting it from a host binary. This should be done when -a new flag, `--syclbin`, is passed. In this case, the clang-linker-wrapper is -responsible to package the resulting device binaries and produced metadata into -the format described in [SYCLBIN binary format section](#syclbin-binary-format). +- Pack device binaries and extracted metadata into the SYCLBIN format +- Embed the resulting SYCLBIN into an OffloadBinary container or output standalone SYCLBIN files +- Support linking multiple SYCLBIN binaries together -### clang-linker-wrapper changes +### [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) changes -- [ ] to be updated... +The [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) shall support two operational modes: -Additionally, in this case the clang-linker-wrapper will skip the wrapping of -the device code and the host code linking stage, as there is no host code to -wrap the device code in and link. +- **Standalone SYCLBIN output:** Output SYCLBIN binaries directly, skipping device code wrapping and host code linking stages. +- **Host linking:** Generate host register/unregister calls for SYCL runtime access to SYCLBIN binaries and link with host code. ### SYCL runtime library changes -- [ ] do we want to provide details in RFC or limit it to basic info? - -Using the interfaces from the -[sycl_ext_oneapi_syclbin](../extensions/proposed/sycl_ext_oneapi_syclbin.asciidoc) -extension, the runtime must be able to parse the SYCLBIN format, as described in -the [SYCLBIN binary format section](#syclbin-binary-format). To avoid large -amounts of code duplication, the runtime uses the implementation of SYCLBIN -reading and writing implemented in LLVM. - -When creating a `kernel_bundle` from a SYCLBIN file, the runtime reads the -contents of the SYCLBIN file and creates the corresponding data structure from -it. - -- [ ] this part below needs to be rewritten I think.... - -In order for the SYCL runtime library's existing logic to use the binaries, -the runtime then creates a collection of `sycl_device_binary_struct` objects and -its constituents, pointing to the data in the parsed SYCLBIN object. Passing -these objects to the runtime library's `ProgramManager` allows it to reuse the -logic for compiling, linking and building SYCL binaries. - -In the other direction, users can request the "contents" of a `kernel_bundle`. -When this is done, the runtime library must ensure that a SYCLBIN file is -available for the contents of the `kernel_bundle` and must then write the -SYCLBIN object to the corresponding binary representation in the format -described in the [SYCLBIN binary format section](#syclbin-binary-format). In cases -where the `kernel_bundle` was created with a SYCLBIN file, the SYCLBIN -representation is immediately available and can be serialized directly. In other -cases, the runtime library creates a new SYCLBIN object from the binaries -associated with the `kernel_bundle`, then serializes it and returns the result. +The runtime must be able to parse the SYCLBIN format, using the implementation of SYCLBIN +reading and writing functionality. ## Versioning and Extensibility @@ -193,11 +137,5 @@ ignore the property. ## Upstreaming Plan - Phase 1: Upstream SYCLBIN format specification, including parsing/writing -- Phase 2: Add clang driver, sycl-linker and linker-wrapper support +- Phase 2: Add clang driver, [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) support - Phase 3: Integrate SYCLBIN support into SYCL runtime - -## Opens, common todos - -- [ ] Do we want to extend SYCL spec with SYCLBIN format? Do we want to somehow mention it in the RFC? Is it relevant? -- [ ] Need to add/update links in this RFC -- [ ] Polish formatting, fix typos, etc... From 18a7eb6b63307f63e3e54401315486a14e734b71 Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Mon, 13 Oct 2025 22:49:04 +0200 Subject: [PATCH 5/7] addressed feedback --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 92 ++++++++++----------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index ca600820a270f..cbee4e1d76b0b 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -1,4 +1,4 @@ -# [RFC] SYCLBIN - A format for SYCL device code +# [RFC] SYCLBIN - A Format for SYCL Device Code ## Summary @@ -8,27 +8,28 @@ This RFC proposes the addition of SYCLBIN, a new binary format for storing SYCL This RFC seeks community feedback on the proposed SYCLBIN binary format, including toolchain integration approach. Community input is particularly valuable regarding potential integration challenges with existing LLVM offloading implementations. -## Motivation and alternatives considered +## Motivation and Alternatives Considered -### Requirements: SYCL-Specific metadata and modules hierarchy +### Requirements: SYCL-Specific Metadata and Modules Hierarchy -The SYCL programming model requires device images to be accompanied by specific metadata necessary for SYCL runtime operation: - -1. Device target triple (e.g. ``spirv64_unknown_unknown``). -2. Compiler and linker options for JIT compilation scenarios -3. List of entry points exposed by each image -4. Arrays of [property sets](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/PropertySets.md). - -When a binary contains multiple images, some may share common metadata. Therefore, we require a hierarchical structure that enables metadata sharing while allowing specification of image-specific metadata. +1. The SYCL programming model requires device images to be accompanied by specific metadata necessary for SYCL runtime operation: + 1. Device target triple. + 2. Compiler and linker options for JIT compilation scenarios. + 3. List of entry points exposed by each image. + 4. [Property sets](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/PropertySets.md). +2. When a binary contains multiple images, some may share common metadata. Therefore, we require a hierarchical structure that enables metadata sharing while allowing specification of image-specific metadata. +3. Multiple images can exist for a single device, and images for different devices can expose different entry points. #### Existing Formats Limitations -LLVM's offloading infrastructure supports several binary formats that can be embedded within the [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) format. However, these formats have various limitations that make them unsuitable for SYCL: +LLVM's offloading infrastructure supports several binary formats that can be embedded within the [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) format. However, these formats have various limitations that make them unsuitable for SYCL: + +- **Single-Module Design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules. +- **Missing SYCL Metadata Support**: None provide native support for SYCL-specific metadata requirements. +- **Vendor Constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach. +- **Limited Container Capabilities**: [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) is not designed for multiple device images or hierarchical organization, with ``StringData`` insufficient for complex metadata structures (like #1.3 and #1.4 above). -- **Single-module design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules. -- **Missing SYCL metadata support**: None provide native support for SYCL-specific metadata requirements. -- **Vendor constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach. -- **Limited container capabilities**: [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) is not designed for multiple device images or hierarchical organization, with ``StringData`` insufficient for complex metadata structures (like #3 and #4 above). +The [OffloadingDesign](https://clang.llvm.org/docs/OffloadingDesign.html) describes a [target binary descriptor](https://clang.llvm.org/docs/OffloadingDesign.html#table-target-binary-descriptor) that stores multiple binary images (one per device type) with all images sharing the same entries list. This structure doesn't satisfy requirement #3 above. ### Abstraction: Simplifying Support in Offloading Tools @@ -38,35 +39,37 @@ Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific Without this format, metadata transfer from compiler to runtime requires the following complicated workflow: -1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata items #1-#4 -2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime - - Problem: This requires [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to maintain SYCL-specific format knowledge, creating unnecessary code duplication -3. **SYCL runtime** decodes metadata using this intermediate format +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata items #1-#4. +2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime. + - Problem: This requires [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to maintain SYCL-specific format knowledge, creating unnecessary code duplication. +3. **SYCL runtime** decodes metadata using this intermediate format. #### Simplified Workflow With SYCLBIN The SYCLBIN format enables a cleaner separation of concerns: -1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) -2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** generates only host register/unregister calls without needing knowledge of SYCLBIN internals -3. **SYCL runtime** works directly with SYCLBIN format +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h). +2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** generates only host register/unregister calls and a trivial wrapper without needing knowledge of SYCLBIN internals. +3. **SYCL runtime** works directly with SYCLBIN format. This approach eliminates the need for [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to understand SYCL-specific formats, reducing maintenance burden and improving toolchain modularity. -### Enable modular dynamic loading of device binaries at runtime +### Enable Modular Dynamic Loading of Device Binaries at Runtime Some applications require dynamic loading of device binaries at runtime to achieve modularity and avoid recompiling the entire application when device code changes. The SYCLBIN format provides a standardized interface between compiler-produced SYCLBIN binaries and runtime handling, enabling efficient dynamic loading scenarios. +SYCLBIN serves as SYCL's analog to CUDA's FATBIN format. Just as nvcc provides compiler options to generate ".fatbin" files, SYCL compiler could offer options to generate ".syclbin" files. Similarly, we intend to add SYCL runtime functions to load and manipulate ".syclbin" files, mirroring CUDA's runtime functions for ".fatbin" files. + ## Design -### SYCLBIN binary format +### SYCLBIN Binary Format The SYCLBIN format consists of: -- A file header with magic number and version information +- A file header with magic number and version information. - Three lists of headers: the abstract module header list, the IR module header list and native device code image header list, containing information about the abstract modules, IR modules and native device code images respectively. -- Two byte tables containing metadata and binary data +- Two byte tables containing metadata and binary data. #### File Structure @@ -89,37 +92,34 @@ containing information about the abstract modules, IR modules and native device **Abstract Modules:** collection of device binaries that share properties, including, but not limited to: exported symbols, [aspect requirements](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/OptionalDeviceFeatures.md), and [specialization constants](https://github.khronos.org/SYCL_Reference/iface/specialization-constants.html). The device binaries contained inside an abstract module must either be an IR module or a native device code image. IR modules contain device binaries in some known intermediate representation, such as SPIR-V, while the native device code images can be an architecture-specific binary format. There is no requirement that all device binaries in an abstract module are usable on the same device or are specific to a single vendor. -**IR modules:** binary data for the corresponding module compiled to a given IR representation, identified by the IR type field. - -**Native device code images:** binary data for the corresponding module AOT compiled for a specific device, identified by the architecture -string. +**IR Modules:** metadata and binary data for the corresponding module compiled to a given IR representation. -**Byte tables:** A byte table contains dynamic data, such as metadata and binary blobs. The contents of it is generally referenced by an offset specified in the headers. +**Native Device Code Images:** metadata and binary data for the corresponding module AOT compiled for a specific device. -Detailed design can be found [here](https://intel.github.io/llvm/design/SYCLBINDesign.html) +[Detailed design](https://intel.github.io/llvm/design/SYCLBINDesign.html). -## Toolchain integration +## Toolchain Integration -The SYCLBIN content can either be embedded as an image within the [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) or outputted directly as standalone SYCLBIN files. +The SYCLBIN content can either be embedded as an image within the [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) or outputted directly as standalone SYCLBIN files. -This integration approach allows SYCLBIN to leverage the existing [Offload Binary](https://github.com/llvm/llvm-project/blame/main/llvm/include/llvm/Object/OffloadBinary.h) infrastructure while maintaining its specialized format for SYCL-specific requirements. +This integration approach allows SYCLBIN to leverage the existing [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) infrastructure while maintaining its specialized format for SYCL-specific requirements. ### [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) changes The [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) is responsible for module-splitting, metadata extraction (symbol tables, property sets, etc.) and linking of device binaries. To support SYCLBIN, it must be able to: -- Pack device binaries and extracted metadata into the SYCLBIN format -- Embed the resulting SYCLBIN into an OffloadBinary container or output standalone SYCLBIN files -- Support linking multiple SYCLBIN binaries together +- Pack device binaries and extracted metadata into the SYCLBIN format. +- Embed the resulting SYCLBIN into an [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) container or output standalone SYCLBIN files. +- Support linking multiple SYCLBIN binaries together. ### [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) changes The [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) shall support two operational modes: -- **Standalone SYCLBIN output:** Output SYCLBIN binaries directly, skipping device code wrapping and host code linking stages. -- **Host linking:** Generate host register/unregister calls for SYCL runtime access to SYCLBIN binaries and link with host code. +- **Standalone SYCLBIN Output:** Output SYCLBIN binaries directly, skipping device code wrapping and host code linking stages. +- **Host Linking:** Generate host register/unregister calls and a trivial wrapper for SYCL runtime access to SYCLBIN binaries and link with host code. -### SYCL runtime library changes +### SYCL Runtime Library Changes The runtime must be able to parse the SYCLBIN format, using the implementation of SYCLBIN reading and writing functionality. @@ -131,11 +131,11 @@ increment to the version number in the header. Additionally, any changes to the property set structure that affects the way the runtime has to parse the contained property sets will require an increase in the SYCLBIN version. Adding new property set names or new predefined properties only -require a SYCLBIN version change if the the SYCLBIN consumer cannot safely +require a SYCLBIN version change if the SYCLBIN consumer cannot safely ignore the property. ## Upstreaming Plan -- Phase 1: Upstream SYCLBIN format specification, including parsing/writing -- Phase 2: Add clang driver, [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) support -- Phase 3: Integrate SYCLBIN support into SYCL runtime +- Phase 1: Upstream SYCLBIN format specification, including parsing/writing. +- Phase 2: Add clang driver, [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) support. +- Phase 3: Integrate SYCLBIN support into SYCL runtime. From 748edc120c66f1f6cdb2f67615aa918ac64376fe Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Mon, 13 Oct 2025 22:52:53 +0200 Subject: [PATCH 6/7] fixed leftover --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index cbee4e1d76b0b..8dc991a55ba77 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -39,7 +39,7 @@ Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific Without this format, metadata transfer from compiler to runtime requires the following complicated workflow: -1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata items #1-#4. +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata (#1 above). 2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime. - Problem: This requires [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to maintain SYCL-specific format knowledge, creating unnecessary code duplication. 3. **SYCL runtime** decodes metadata using this intermediate format. From e57814d4483013e75d3f932e036c3894003e4061 Mon Sep 17 00:00:00 2001 From: "Plyakhin, Yury" Date: Wed, 15 Oct 2025 01:49:24 +0200 Subject: [PATCH 7/7] comments resolved --- sycl/doc/design/RFC_drafts/SYCLBINDesign.md | 30 ++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md index 8dc991a55ba77..95218bec90aa6 100644 --- a/sycl/doc/design/RFC_drafts/SYCLBINDesign.md +++ b/sycl/doc/design/RFC_drafts/SYCLBINDesign.md @@ -22,33 +22,33 @@ This RFC seeks community feedback on the proposed SYCLBIN binary format, includi #### Existing Formats Limitations -LLVM's offloading infrastructure supports several binary formats that can be embedded within the [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) format. However, these formats have various limitations that make them unsuitable for SYCL: +LLVM's offloading infrastructure supports several binary formats that can be embedded within the [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) format. However, these formats have various limitations that make them unsuitable for SYCL: - **Single-Module Design**: Formats like Object, Bitcode, CUBIN, PTX, and SPIRV are designed for single binary or single-module IR representation, lacking hierarchical structuring capabilities for multiple images/modules. - **Missing SYCL Metadata Support**: None provide native support for SYCL-specific metadata requirements. - **Vendor Constraints**: Fatbinary is NVIDIA proprietary and incompatible with SYCL's vendor-neutral approach. -- **Limited Container Capabilities**: [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) is not designed for multiple device images or hierarchical organization, with ``StringData`` insufficient for complex metadata structures (like #1.3 and #1.4 above). +- **Limited Container Capabilities**: [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) is not designed for multiple device images or hierarchical organization, with ``StringData`` insufficient for complex metadata structures (like #1.3 and #1.4 above). The [OffloadingDesign](https://clang.llvm.org/docs/OffloadingDesign.html) describes a [target binary descriptor](https://clang.llvm.org/docs/OffloadingDesign.html#table-target-binary-descriptor) that stores multiple binary images (one per device type) with all images sharing the same entries list. This structure doesn't satisfy requirement #3 above. ### Abstraction: Simplifying Support in Offloading Tools -Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific logic within SYCL-specific toolchain components ([clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst), SYCL runtime) and isolate SYCL implementation details from general offloading tools designed to support multiple programming models. +Another motivation for adding the SYCLBIN format is to encapsulate SYCL-specific logic within SYCL-specific toolchain components ([clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst), SYCL runtime) and isolate SYCL implementation details from general offloading tools designed to support multiple programming models. -#### Current Workflow Without SYCLBIN +#### Current Workflow without SYCLBIN Without this format, metadata transfer from compiler to runtime requires the following complicated workflow: -1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata (#1 above). -2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime. +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst)** uses [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h)'s ``StringData`` (with workarounds) to store metadata (#1 above). +2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** opens [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) files produced by [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst) and generates [device image binary descriptors](https://github.com/llvm/llvm-project/blob/139a6bf0e448ebd7ef9bd1c26aa92018d90f8add/llvm/lib/Frontend/Offloading/OffloadWrapper.cpp#L675) in a format readable by SYCL runtime. - Problem: This requires [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) to maintain SYCL-specific format knowledge, creating unnecessary code duplication. 3. **SYCL runtime** decodes metadata using this intermediate format. -#### Simplified Workflow With SYCLBIN +#### Simplified Workflow with SYCLBIN The SYCLBIN format enables a cleaner separation of concerns: -1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst)** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h). +1. **[clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst)** prepares a complete SYCLBIN containing all metadata and multiple images, embedding it as a single image within [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h). 2. **[clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst)** generates only host register/unregister calls and a trivial wrapper without needing knowledge of SYCLBIN internals. 3. **SYCL runtime** works directly with SYCLBIN format. @@ -100,19 +100,19 @@ containing information about the abstract modules, IR modules and native device ## Toolchain Integration -The SYCLBIN content can either be embedded as an image within the [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) or outputted directly as standalone SYCLBIN files. +The SYCLBIN content can either be embedded as an image within the [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) produced by the [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst) or outputted directly as standalone SYCLBIN files. -This integration approach allows SYCLBIN to leverage the existing [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) infrastructure while maintaining its specialized format for SYCL-specific requirements. +This integration approach allows SYCLBIN to leverage the existing [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) infrastructure while maintaining its specialized format for SYCL-specific requirements. -### [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) changes +### [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst) Changes -The [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) is responsible for module-splitting, metadata extraction (symbol tables, property sets, etc.) and linking of device binaries. To support SYCLBIN, it must be able to: +The [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst) is responsible for module-splitting, metadata extraction (symbol tables, property sets, etc.) and linking of device binaries. To support SYCLBIN, it must be able to: - Pack device binaries and extracted metadata into the SYCLBIN format. -- Embed the resulting SYCLBIN into an [Offload Binary](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Object/OffloadBinary.h) container or output standalone SYCLBIN files. +- Embed the resulting SYCLBIN into an [Offload Binary](https://github.com/llvm/llvm-project/blob/3e5fc80dfe7536f8fcbd50fc58f7cc66e0bf8f16/llvm/include/llvm/Object/OffloadBinary.h) container or output standalone SYCLBIN files. - Support linking multiple SYCLBIN binaries together. -### [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) changes +### [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) Changes The [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) shall support two operational modes: @@ -137,5 +137,5 @@ ignore the property. ## Upstreaming Plan - Phase 1: Upstream SYCLBIN format specification, including parsing/writing. -- Phase 2: Add clang driver, [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangSYCLLinker.rst) and [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) support. +- Phase 2: Add clang driver, [clang-sycl-linker](https://github.com/llvm/llvm-project/blob/3984d19826cbe724a006971266d15eabc4d59287/clang/docs/ClangSYCLLinker.rst) and [clang-linker-wrapper](https://github.com/llvm/llvm-project/blob/c083fa1597f1a34fcab4c2910158a288defc72f6/clang/docs/ClangLinkerWrapper.rst) support. - Phase 3: Integrate SYCLBIN support into SYCL runtime.