diff --git a/sycl/doc/extensions/README.md b/sycl/doc/extensions/README.md old mode 100755 new mode 100644 index d3d1dacf68dfd..d0fdbae6c5d5f --- a/sycl/doc/extensions/README.md +++ b/sycl/doc/extensions/README.md @@ -1,22 +1,22 @@ -# Extensions +# SYCL Extensions in DPC++ -The directory contains documents that describe DPC++ extensions to SYCL -specification. +The DPC++ compiler supports the [SYCL language][1]. In addition to the core +SYCL features, DPC++ also implements certain extensions, and this directory +contains the specifications for those extensions. These extensions are +organized into subdirectories according to their state. -DPC++ extensions status: +[1]: -| Extension | Status | Comment | -|-------------|:------------|:------------| +| Directory | Description | +|------------------|---------------------------------------------------------------| +|[supported][2] | Extensions which are fully supported | +|[experimental][3] | Extensions which are implemented but may change in the future | +|[deprecated][4] | Extensions which are supported but will be removed soon | +|[proposed][5] | Extensions which proposed but not yet implemented | +|[removed][6] | Extensions which used to be supported but are now removed | -Legend: - -| Keyword | Meaning | -|-------------|:------------| -| Proposal | A document describing an extension is published, but the extension is not supported yet | -| Supported | An extension is supported | -| Partially supported | An extension is partially supported, see comments column for more info | -| Deprecated | An extension is deprecated and can be removed in future versions | -| (API: DeviceType1, DeviceType2) | An extension is supported when specific combination of API and device types are used. If device type or API are not mentioned then an extension is supported on any device type or API. API can be OpenCL, CUDA, HOST. DeviceType can be CPU, GPU, ACCELERATOR | - - -See [User Manual](../UsersManual.md) to find information how to enable extensions. +[2]: +[3]: +[4]: +[5]: +[6]: diff --git a/sycl/doc/extensions/deprecated/README.md b/sycl/doc/extensions/deprecated/README.md new file mode 100644 index 0000000000000..5c946e3ec4405 --- /dev/null +++ b/sycl/doc/extensions/deprecated/README.md @@ -0,0 +1,6 @@ +# Deprecated Extensions + +This directory contains specifications for the SYCL extensions which are +deprecated in the DPC++ compiler. These extensions are still supported, but we +plan to remove them soon. Applications which use these extensions are +encouraged to use an alternative instead. diff --git a/sycl/doc/extensions/experimental/README.md b/sycl/doc/extensions/experimental/README.md index fcbe58d14b6b4..f13da709ad6f6 100644 --- a/sycl/doc/extensions/experimental/README.md +++ b/sycl/doc/extensions/experimental/README.md @@ -1,8 +1,10 @@ +# Experimental Extensions + This directory contains the specifications for SYCL extensions that are -considered experimental in the DPC++ implementation. The APIs in these -extensions are not stable. They may be changed or even removed in subsequent -releases of DPC++ without prior notice. As a result, they are not recommended -for use in production code. +considered experimental in the DPC++ compiler. The APIs in these extensions +are not stable. They may be changed or even removed in subsequent releases of +DPC++ without prior notice. As a result, they are not recommended for use in +production code. Experimental extensions may eventually be promoted to "supported". When this happens, a new specification is added to the "supported" directory, which may diff --git a/sycl/doc/extensions/proposed/README.md b/sycl/doc/extensions/proposed/README.md index ee44b5259eb83..6a32f001bacba 100644 --- a/sycl/doc/extensions/proposed/README.md +++ b/sycl/doc/extensions/proposed/README.md @@ -1,7 +1,9 @@ +# Proposed Extensions + 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. +proposed for the DPC++ compiler. 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 diff --git a/sycl/doc/extensions/removed/README.md b/sycl/doc/extensions/removed/README.md index 48f2688e5e570..2a6ab33c1bffc 100644 --- a/sycl/doc/extensions/removed/README.md +++ b/sycl/doc/extensions/removed/README.md @@ -1,3 +1,5 @@ +# Removed Extensions + This directory contains an archive of old DPC++ extensions which are no longer implemented. diff --git a/sycl/doc/extensions/supported/README.md b/sycl/doc/extensions/supported/README.md index fc8e36782ddbb..5ecd9b2fab1e3 100644 --- a/sycl/doc/extensions/supported/README.md +++ b/sycl/doc/extensions/supported/README.md @@ -1,7 +1,9 @@ +# Supported Extensions + This directory contains the specifications for SYCL extensions that are fully -supported by the DPC++ implementation. The APIs in these extensions are -generally stable in future releases of DPC++, retaining backward compatibility -with application code. +supported by the DPC++ compiler. The APIs in these extensions are generally +stable in future releases of DPC++, retaining backward compatibility with +application code. If support is dropped for one of these extensions, it goes through a deprecation process. The APIs in the extension are first marked "deprecated",