From bd675fedb671855edc3e51c673695c9b6d80bb0b Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Tue, 4 Feb 2025 09:21:04 -0800 Subject: [PATCH 1/3] [SYCL][DOC] Describe process of prototyping KHR extensions --- sycl/doc/developer/KHRExtensions.md | 46 +++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 sycl/doc/developer/KHRExtensions.md diff --git a/sycl/doc/developer/KHRExtensions.md b/sycl/doc/developer/KHRExtensions.md new file mode 100644 index 0000000000000..248b050c1c68d --- /dev/null +++ b/sycl/doc/developer/KHRExtensions.md @@ -0,0 +1,46 @@ +# Considerations for working on KHR extensions + +SYCL specification evolves through embedding extensions developed by various +vendors, including Khronos Group itself (`khr` extensions). + +In order for a KHR extension to be accepted, there must be CTS tests for it and +at least one implementation which passes them. + +Considering that KHR extensions are being developed in public, we can start +prototyping them as soon as corresponding PR for an extension is published at +KhronosGroup/SYCL-Docs. + +However, we shouldn't be exposing those extensions to end users until the +extension if finalised, ratified and published by Khronos - due to risk of an +extension changing during that process and lack of the officially published +version of it. + +So, we can have a PR but can't merge it. Keeping PRs opened for a long time is a +bad practice, because they tend to get stale: there are merge conflicts, +potential functional issues due to the codebase changes, etc. + +In order for us to avoid stale PRs, all functionality which is a public +interface of an "in-progress" KHR extension, must be hidden under +`__DPCPP_ENABLE_UNFINISHED_KHR_EXTENSIONS` macro. That way we can merge a PR to +avoid constantly maintaining it in a good shape, start automatically testing it +but at the same time avoid exposing incomplete and/or undocumented feature to +end users just yet. + +"in-progress" KHR extension term used above is defined as: +- KHR extension proposed to Khronos Group which has not been published in a + released revision of the SYCL specification (of any version). + + Note: merge of an extension proposal PR into KhronosGroup/SYCL-Docs repo is + **not** considered to be a publishing event. The extension specification has + to be available on the Khronos SYCL Registry website: + https://registry.khronos.org/SYCL/ + +- Published KHR extension, which hasn't been fully implemented by us + +The macro is **not** intended to be used by end users and its purpose is to +simplify our development process by allowing us to merge implementation (full +or partial) of the aforementioned extensions earlier to simplify maintenance and +enable automated testing. + +Due to this reason, we are not providing a separate macro for each "in-progress" +KHR extension we may (partially) support, but just a single guard. From e3b9805781fe743b52615e81a217f176afb3ba45 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Thu, 6 Feb 2025 04:00:09 -0800 Subject: [PATCH 2/3] Add new document into top-level TOC --- sycl/doc/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index cc4961dd7f438..f5e5ce5574215 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -66,3 +66,4 @@ Developer Documentation developer/DockerBKMs developer/ABIPolicyGuide developer/ContributeToDPCPP + developer/KHRExtensions From 0588f7f3c8489296eeaa0d6771d4cfd18635e659 Mon Sep 17 00:00:00 2001 From: Alexey Sachkov Date: Mon, 10 Feb 2025 03:51:13 -0800 Subject: [PATCH 3/3] Apply comments --- sycl/doc/developer/KHRExtensions.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/sycl/doc/developer/KHRExtensions.md b/sycl/doc/developer/KHRExtensions.md index 248b050c1c68d..7890eb6707b85 100644 --- a/sycl/doc/developer/KHRExtensions.md +++ b/sycl/doc/developer/KHRExtensions.md @@ -27,15 +27,17 @@ but at the same time avoid exposing incomplete and/or undocumented feature to end users just yet. "in-progress" KHR extension term used above is defined as: -- KHR extension proposed to Khronos Group which has not been published in a - released revision of the SYCL specification (of any version). +- PR proposing a KHR extension has not been merged/cherry-picked to `sycl-2020` + branch of KhronosGroup/SYCL-Docs. - Note: merge of an extension proposal PR into KhronosGroup/SYCL-Docs repo is - **not** considered to be a publishing event. The extension specification has - to be available on the Khronos SYCL Registry website: - https://registry.khronos.org/SYCL/ + That only happens after all formal processes on Khronos Group side are + completed so an extension can be considered good and stable to be released by + us. -- Published KHR extension, which hasn't been fully implemented by us + Note: merge of an extension proposal PR into `main` branch of + KhronosGroup/SYCL-Docs repo is **not** enough. +- Published (i.e. the above bullet complete) KHR extension, which hasn't been + fully implemented by us The macro is **not** intended to be used by end users and its purpose is to simplify our development process by allowing us to merge implementation (full