From 0331576d6022ae2cd5674a80621ff0c753a009df Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 15 Feb 2022 13:04:12 -0500 Subject: [PATCH 1/2] [SYCL][DOC] Move SPIR-V and OpenCL extensions The SPIR-V and OpenCL extensions are not SYCL extensions, rather they are extensions to underlying components used by DPC++. Therefore, we consider them part of the design, so move them to "doc/design". Our policy is to remove SPIR-V and OpenCL extension specifications from this repo once they are added to the Khronos registry. The "SPV_INTEL_arbitrary_precision_int" extension was already added there, so remove it from this repo. --- sycl/ReleaseNotes.md | 2 +- sycl/doc/DeviceGlobal.md | 4 +- sycl/doc/design/opencl-extensions/README.md | 8 ++ .../cl_intel_global_variable_access.asciidoc | 0 sycl/doc/design/spirv-extensions/README.md | 8 ++ .../SPV_INTEL_bfloat16_conversion.asciidoc | 0 .../SPV_INTEL_debug_module.asciidoc | 0 .../SPV_INTEL_function_pointers.asciidoc | 0 ...INTEL_global_variable_decorations.asciidoc | 0 .../SPV_INTEL_inline_assembly.asciidoc | 0 .../SPV_INTEL_joint_matrix.asciidoc | 0 ...TEL_non_constant_addrspace_printf.asciidoc | 0 .../SPV_INTEL_optnone.asciidoc | 0 ..._INTEL_uniform_group_instructions.asciidoc | 0 .../SPV_INTEL_usm_storage_classes.asciidoc | 0 .../SPV_INTEL_variable_length_array.asciidoc | 0 sycl/doc/extensions/README.md | 2 - ...SPV_INTEL_arbitrary_precision_int.asciidoc | 95 ------------------- 18 files changed, 19 insertions(+), 100 deletions(-) create mode 100644 sycl/doc/design/opencl-extensions/README.md rename sycl/doc/{extensions/DeviceGlobal => design/opencl-extensions}/cl_intel_global_variable_access.asciidoc (100%) create mode 100644 sycl/doc/design/spirv-extensions/README.md rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_bfloat16_conversion.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_debug_module.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_function_pointers.asciidoc (100%) rename sycl/doc/{extensions/DeviceGlobal => design/spirv-extensions}/SPV_INTEL_global_variable_decorations.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_inline_assembly.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_joint_matrix.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_non_constant_addrspace_printf.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_optnone.asciidoc (100%) mode change 100755 => 100644 rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_uniform_group_instructions.asciidoc (100%) mode change 100755 => 100644 rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_usm_storage_classes.asciidoc (100%) rename sycl/doc/{extensions/SPIRV => design/spirv-extensions}/SPV_INTEL_variable_length_array.asciidoc (100%) delete mode 100644 sycl/doc/extensions/SPIRV/SPV_INTEL_arbitrary_precision_int.asciidoc diff --git a/sycl/ReleaseNotes.md b/sycl/ReleaseNotes.md index b1419b07fd7a9..23c7cd38087f4 100644 --- a/sycl/ReleaseNotes.md +++ b/sycl/ReleaseNotes.md @@ -1185,7 +1185,7 @@ Release notes for commit range 5976ff0..1fc0e4f [c4c3494] ### Documentation - - Added documentation for [`SPV_INTEL_usm_storage_classes`](doc/extensions/SPIRV/SPV_INTEL_usm_storage_classes.asciidoc) + - Added documentation for [`SPV_INTEL_usm_storage_classes`](doc/design/spirv-extensions/SPV_INTEL_usm_storage_classes.asciidoc) and [SYCL_INTEL_usm_address_spaces](doc/extensions/supported/SYCL_EXT_INTEL_USM_ADDRESS_SPACES.asciidoc) [781fbfc] - Fixed SPIR-V format name spelling [6e9bf3b] - Added extension [LocalMemory](doc/extensions/supported/SYCL_EXT_ONEAPI_LOCAL_MEMORY.asciidoc) draft specification [4b5308a] diff --git a/sycl/doc/DeviceGlobal.md b/sycl/doc/DeviceGlobal.md index 3d3f1a7baf4f8..6c156bf737b34 100644 --- a/sycl/doc/DeviceGlobal.md +++ b/sycl/doc/DeviceGlobal.md @@ -403,7 +403,7 @@ has the `implement_in_csr` property). See the [SPV\_INTEL\_global\_variable\_decorations][6] SPIR-V extension for details about all of these decorations. -[6]: +[6]: The `sycl-post-link` tool also create a "SYCL/device globals" property set for each device code module that contains at least one device global variable. @@ -614,7 +614,7 @@ The OpenCL backend has a proposed extension which can be easily used to implement these PI interfaces. This DPC++ design depends upon implementation of that OpenCL extension. -[10]: +[10]: The CUDA backend has existing APIs `cudaMemcpyToSymbol()` and `cudaMemcpyFromSymbol()` which can be used to implement these PI interfaces. diff --git a/sycl/doc/design/opencl-extensions/README.md b/sycl/doc/design/opencl-extensions/README.md new file mode 100644 index 0000000000000..33e4737f9a785 --- /dev/null +++ b/sycl/doc/design/opencl-extensions/README.md @@ -0,0 +1,8 @@ +# Draft OpenCL Extensions + +This directory contains draft OpenCL extensions that are used as part of the +DPC++ design. Once these extensions become fully mature, they are moved to the +[Khronos OpenCL Registry][1]. Therefore, look there also for OpenCL extensions +that are used by DPC++. + +[1]: diff --git a/sycl/doc/extensions/DeviceGlobal/cl_intel_global_variable_access.asciidoc b/sycl/doc/design/opencl-extensions/cl_intel_global_variable_access.asciidoc similarity index 100% rename from sycl/doc/extensions/DeviceGlobal/cl_intel_global_variable_access.asciidoc rename to sycl/doc/design/opencl-extensions/cl_intel_global_variable_access.asciidoc diff --git a/sycl/doc/design/spirv-extensions/README.md b/sycl/doc/design/spirv-extensions/README.md new file mode 100644 index 0000000000000..12552c9b51ec8 --- /dev/null +++ b/sycl/doc/design/spirv-extensions/README.md @@ -0,0 +1,8 @@ +# Draft SPIR-V Extensions + +This directory contains draft SPIR-V extensions that are used as part of the +DPC++ design. Once these extensions become fully mature, they are moved to the +[Khronos SPIR-V Registry][1]. Therefore, look there also for SPIR-V extensions +that are used by DPC++. + +[1]: diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_bfloat16_conversion.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_bfloat16_conversion.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_bfloat16_conversion.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_bfloat16_conversion.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_debug_module.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_debug_module.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_function_pointers.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_function_pointers.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_function_pointers.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_function_pointers.asciidoc diff --git a/sycl/doc/extensions/DeviceGlobal/SPV_INTEL_global_variable_decorations.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_global_variable_decorations.asciidoc similarity index 100% rename from sycl/doc/extensions/DeviceGlobal/SPV_INTEL_global_variable_decorations.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_global_variable_decorations.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_inline_assembly.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_inline_assembly.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_inline_assembly.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_inline_assembly.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_joint_matrix.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_joint_matrix.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_joint_matrix.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_joint_matrix.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_non_constant_addrspace_printf.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_non_constant_addrspace_printf.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_non_constant_addrspace_printf.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_non_constant_addrspace_printf.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_optnone.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_optnone.asciidoc old mode 100755 new mode 100644 similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_optnone.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_optnone.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_uniform_group_instructions.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_uniform_group_instructions.asciidoc old mode 100755 new mode 100644 similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_uniform_group_instructions.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_uniform_group_instructions.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_usm_storage_classes.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_usm_storage_classes.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_usm_storage_classes.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_usm_storage_classes.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_variable_length_array.asciidoc b/sycl/doc/design/spirv-extensions/SPV_INTEL_variable_length_array.asciidoc similarity index 100% rename from sycl/doc/extensions/SPIRV/SPV_INTEL_variable_length_array.asciidoc rename to sycl/doc/design/spirv-extensions/SPV_INTEL_variable_length_array.asciidoc diff --git a/sycl/doc/extensions/README.md b/sycl/doc/extensions/README.md index 6e57f87535afb..d3d1dacf68dfd 100755 --- a/sycl/doc/extensions/README.md +++ b/sycl/doc/extensions/README.md @@ -7,8 +7,6 @@ DPC++ extensions status: | Extension | Status | Comment | |-------------|:------------|:------------| -| [SPV_INTEL_function_pointers](SPIRV/SPV_INTEL_function_pointers.asciidoc) | Supported(OpenCL: CPU, GPU; HOST) | | -| [SPV_INTEL_inline_assembly](SPIRV/SPV_INTEL_inline_assembly.asciidoc) | Supported(OpenCL: GPU) | | Legend: diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_arbitrary_precision_int.asciidoc b/sycl/doc/extensions/SPIRV/SPV_INTEL_arbitrary_precision_int.asciidoc deleted file mode 100644 index 2bef48671823e..0000000000000 --- a/sycl/doc/extensions/SPIRV/SPV_INTEL_arbitrary_precision_int.asciidoc +++ /dev/null @@ -1,95 +0,0 @@ -= SPV_INTEL_arbitrary_precision_integers - -== Name Strings - -SPV_INTEL_arbitrary_precision_integers - -== Contact - -To report problems with this extension, please open a new issue at: - -https://github.com/KhronosGroup/SPIRV-Headers - -== Contributors - -* Ajaykumar Kannan, Intel -* Joe Garvey, Intel - -== Notice - -Copyright (c) 2020 Intel Corporation - -== Status - -Final draft - -=== Version - -[width="40%",cols="25,25"] -|======================================== -| Last Modified Date | {docdate} -| Revision | 1 -|======================================== - -== Dependencies - -This extension is written against the SPIR-V Specification Version 1.5, Revision 2. - -== Overview - -This extension relaxes the restriction that `OpTypeInt` must have a width of 32 bits. -Ints of arbitrary bit widths can be beneficial on targets that can exploit narrower widths such as FPGAs. - -== Extension Name - -To use this extension within a SPIR-V module, the following *OpExtension* must be present in the module: - ----- -OpExtension "SPV_INTEL_arbitrary_precision_integers" ----- - -== New Capabilities - -This extension introduces a new capability: - ----- -ArbitraryPrecisionIntegersINTEL ----- - -== Token Number Assignments -[width="40%"] -[cols="70%,30%"] -[grid="rows"] -|==== -|`ArbitraryPrecisionIntegersINTEL` | 5844 -|==== - -== Modifications to the SPIR-V Specification Version 1.5 - -=== Capability -Modify Section 3.31, *Capability*, adding a row to the Capability table: -[options="header"] -|==== -2+^| Capability ^| Implicitly Declares -| 5844 | *ArbitraryPrecisionIntegersINTEL* + - -Allows the use of the *OpTypeInt* to declare integers of any arbitrary width. -The minimum requirement is that all bitwidths up to 32-bits must be supported, but implementations can extend the support beyond 32-bits. -| Int8, Int16 -|==== - -=== Validation Rules - -None. - -== Issues - -None. - -== Revision History - -[cols="^,<,<,<",options="header",] -|================================================ -|Rev |Date |Author |Changes -|1 |2020-03-27 |Ajaykumar Kannan |*Initial public release* -|================================================ From 94c02111767a1ad04772bcca8a6452176461e6e4 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Wed, 16 Feb 2022 05:26:47 -0800 Subject: [PATCH 2/2] Do not generate Sphinx doc for OpenCL/SPV exts Do not generate Sphinx documentation for the OpenCL or SPIR-V extensions because they are written in AsciiDoc, which Spinx does not support well. Instead, link to their GitHub location, and readers can read GitHub's rendering of the AsciiDoc documents. This is the same thing we do already for the SYCL extension specifications. --- sycl/doc/conf.py | 8 ++++++-- sycl/doc/index.rst | 2 ++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/sycl/doc/conf.py b/sycl/doc/conf.py index c976900bda320..e4185328399a1 100644 --- a/sycl/doc/conf.py +++ b/sycl/doc/conf.py @@ -46,8 +46,12 @@ # The suffix of source filenames. source_suffix = ['.rst', '.md'] -# Extensions are mostly in asciidoc which has poor support in Sphinx -exclude_patterns = ['extensions/*'] +exclude_patterns = [ + # Extensions are mostly in asciidoc which has poor support in Sphinx. + 'extensions/*', + 'design/opencl-extensions/*', + 'design/spirv-extensions/*' +] suppress_warnings = [ 'misc.highlighting_failure' ] diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index 844e0c1c3be7b..1beb6bddc6745 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -42,6 +42,8 @@ Developing oneAPI DPC++ Compiler ITTAnnotations DeviceGlobal CompileTimeProperties + New OpenCL Extensions + New SPIR-V Extensions Development BKMs ~~~~~~~~~~~~~~~~