[SYCL][DOC] Move proposed extension docs (#5437)

Move the proposed extensions to the "sycl/doc/extensions/proposed" directory, and add a README explaining the content of that directory. Each extension document has also been renamed to match the name of its feature-test macro. Links to these extensions have been removed from the table in "sycl/doc/extensions/README.md" because we want to avoid the possibility of that table getting out-of-date with the directory contents. Instead, users can see the list of proposed extensions by listing the content of the directory.
intel · Feb 1, 2022 · eb350ee · eb350ee
1 parent ec9d089
commit eb350ee
Show file tree

Hide file tree

Showing 13 changed files with 18 additions and 14 deletions.
diff --git a/sycl/ReleaseNotes.md b/sycl/ReleaseNotes.md
@@ -271,11 +271,11 @@ Release notes for commit range 6a49170027fb..962909fe9e78
    extension specification [edaee9b]
  - Added [initial draft](doc/extensions/supported/SYCL_EXT_ONEAPI_BACKEND_LEVEL_ZERO.md)
    for querying of free device memory in LevelZero backend extension [fa428bf]
- - Added [InvokeSIMD](doc/extensions/InvokeSIMD/InvokeSIMD.asciidoc) and
-   [Uniform](doc/extensions/Uniform/Uniform.asciidoc) extensions [72e1611]
+ - Added [InvokeSIMD](doc/extensions/proposed/SYCL_EXT_ONEAPI_INVOKE_SIMD.asciidoc) and
+   [Uniform](doc/extensions/proposed/SYCL_EXT_ONEAPI_UNIFORM.asciidoc) extensions [72e1611]
  - Added [Matrix Programming Extension for DPC++ document](doc/extensions/experimental/SYCL_EXT_ONEAPI_MATRIX.asciidoc) [ace4c733]
  - Implemented SYCL 2020 `sycl::span` [9356d53]
- - Added [device-if](doc/extensions/DeviceIf/device_if.asciidoc) extension
+ - Added [device-if](doc/extensions/proposed/SYCL_EXT_ONEAPI_DEVICE_IF.asciidoc) extension
    [4fb95fc]
  - Added a [programming guide](doc/MultiTileCardWithLevelZero.md) for
    multi-tile and multi-card under Level Zero backend [d581178a]

diff --git a/sycl/doc/CompileTimeProperties.md b/sycl/doc/CompileTimeProperties.md
@@ -40,7 +40,7 @@ One use for compile-time properties is with types that are used exclusively
 for declaring global variables.  One such example is the
 [SYCL\_EXT\_ONEAPI\_DEVICE\_GLOBAL][2] extension:
 
-[2]: <extensions/DeviceGlobal/SYCL_INTEL_device_global.asciidoc>
+[2]: <extensions/proposed/SYCL_EXT_ONEAPI_DEVICE_GLOBAL.asciidoc>
 
 ```
 namespace sycl::ext::oneapi {
@@ -270,11 +270,11 @@ the property value to a string if it is not already a string.
 ## Properties on kernel functions
 
 Compile-time properties can also be used to decorate kernel functions as with
-the [SYCL\_EXT\_ONEAPI\_KERNEL\_PROPERTIES][8] extension.  There are two ways
-the application can specify these properties.  The first is by passing a
+the [SYCL\_EXT\_ONEAPI\_PROPERTIES][8] extension.  There are two ways the
+application can specify these properties.  The first is by passing a
 `property_list` parameter to the function that submits the kernel:
 
-[8]: <https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/KernelProperties/KernelProperties.asciidoc>
+[8]: <extensions/proposed/SYCL_EXT_ONEAPI_PROPERTIES.asciidoc>
 
 ```
 namespace sycl {

diff --git a/sycl/doc/DeviceGlobal.md b/sycl/doc/DeviceGlobal.md
@@ -4,7 +4,7 @@ This document describes the implementation design for the DPC++ extension
 [SYCL\_EXT\_ONEAPI\_DEVICE\_GLOBAL][1], which allows applications to declare
 global variables in device code.
 
-[1]: <extensions/DeviceGlobal/SYCL_INTEL_device_global.asciidoc>
+[1]: <extensions/proposed/SYCL_EXT_ONEAPI_DEVICE_GLOBAL.asciidoc>
 
 
 ## Requirements

diff --git a/sycl/doc/OptionalDeviceFeatures.md b/sycl/doc/OptionalDeviceFeatures.md
@@ -266,7 +266,7 @@ non-FPGA users may want to use the `device_global` property
 [`device_image_scope`][5], which requires even non-FPGA users to have precise
 control over the way kernels are bundled into device images.
 
-[5]: <extensions/DeviceGlobal/SYCL_INTEL_device_global.asciidoc#properties-for-device-global-variables>
+[5]: <extensions/proposed/SYCL_EXT_ONEAPI_DEVICE_GLOBAL.asciidoc#properties-for-device-global-variables>
 
 The new definition of `-fsycl-device-code-split` is as follows:
 

diff --git a/sycl/doc/extensions/README.md b/sycl/doc/extensions/README.md
@@ -15,12 +15,7 @@ DPC++ extensions status:
 | [SYCL_INTEL_static_local_memory_query](StaticLocalMemoryQuery/SYCL_INTEL_static_local_memory_query.asciidoc)                | Proposal                                  | |
 | [Sub-groups for NDRange Parallelism](SubGroupNDRange/SubGroupNDRange.md)                                                    | Deprecated(OpenCL: CPU, GPU)              | |
 | [Sub-groups](SubGroup/SYCL_INTEL_sub_group.asciidoc)                                                                        | Deprecated                                | |
-| [SYCL_EXT_ONEAPI_DEVICE_IF](DeviceIf/device_if.asciidoc) | Proposal | |
-| [Invoke SIMD](InvokeSIMD/InvokeSIMD.asciidoc)                                                                               | Proposal                                  | |
-| [Uniform](Uniform/Uniform.asciidoc)                                                                                         | Proposal                                  | |
-| [SYCL_EXT_ONEAPI_DEVICE_GLOBAL](DeviceGlobal/SYCL_INTEL_device_global.asciidoc)                                             | Proposal                                  | |
 | [Property List](PropertyList/SYCL_EXT_ONEAPI_property_list.asciidoc)                                                        | Proposal                                  | |
-| [KernelProperties](KernelProperties/KernelProperties.asciidoc)                                                              | Proposal                                  | |
 | [DiscardQueueEvents](DiscardQueueEvents/SYCL_EXT_ONEAPI_DISCARD_QUEUE_EVENTS.asciidoc) | Proposal | |
 
 Legend:

diff --git a/sycl/doc/extensions/proposed/README.md b/sycl/doc/extensions/proposed/README.md
@@ -0,0 +1,9 @@
+This directory contains the specifications for SYCL extensions that are
+proposed for the DPC++ implementation.  These extensions are not implemented
+in DPC++, so they cannot be used.  These extension documents are published
+here to gather community feedback.
+
+A proposed extension may eventually be implemented, thus promoting it to
+"supported" or "experimental".  When this happens, the specification document
+is generally moved to either the "supported" or "experimental" directory, and
+there may also be some changes to its APIs.
diff --git a/...eGlobal/SYCL_INTEL_device_global.asciidoc → ...ed/SYCL_EXT_ONEAPI_DEVICE_GLOBAL.asciidoc b/...eGlobal/SYCL_INTEL_device_global.asciidoc → ...ed/SYCL_EXT_ONEAPI_DEVICE_GLOBAL.asciidoc
diff --git a/...oc/extensions/DeviceIf/device_if.asciidoc → ...oposed/SYCL_EXT_ONEAPI_DEVICE_IF.asciidoc b/...oc/extensions/DeviceIf/device_if.asciidoc → ...oposed/SYCL_EXT_ONEAPI_DEVICE_IF.asciidoc
diff --git a/...extensions/InvokeSIMD/InvokeSIMD.asciidoc → ...osed/SYCL_EXT_ONEAPI_INVOKE_SIMD.asciidoc b/...extensions/InvokeSIMD/InvokeSIMD.asciidoc → ...osed/SYCL_EXT_ONEAPI_INVOKE_SIMD.asciidoc
diff --git a/...ernelProperties/KernelProperties.asciidoc → ...YCL_EXT_ONEAPI_KERNEL_PROPERTIES.asciidoc b/...ernelProperties/KernelProperties.asciidoc → ...YCL_EXT_ONEAPI_KERNEL_PROPERTIES.asciidoc
diff --git a/..._INTEL_static_local_memory_query.asciidoc → ...EXT_ONEAPI_LOCAL_STATIC_MEM_USED.asciidoc b/..._INTEL_static_local_memory_query.asciidoc → ...EXT_ONEAPI_LOCAL_STATIC_MEM_USED.asciidoc
diff --git a/...yList/SYCL_EXT_ONEAPI_properties.asciidoc → ...posed/SYCL_EXT_ONEAPI_PROPERTIES.asciidoc b/...yList/SYCL_EXT_ONEAPI_properties.asciidoc → ...posed/SYCL_EXT_ONEAPI_PROPERTIES.asciidoc
diff --git a/sycl/doc/extensions/Uniform/Uniform.asciidoc → ...proposed/SYCL_EXT_ONEAPI_UNIFORM.asciidoc b/sycl/doc/extensions/Uniform/Uniform.asciidoc → ...proposed/SYCL_EXT_ONEAPI_UNIFORM.asciidoc