Add SPV_INTEL_vector_compute extension preview

sycl/doc/extensions/SPIRV/SPV_INTEL_vector_compute.asciidoc

@@ -0,0 +1,233 @@
+SPV_INTEL_vector_compute
+========================
+
+Name Strings
+------------
+
+SPV_INTEL_vector_compute
+
+Contact
+-------
+
+To report problems or to provide input on this extension, please open a new issue at:
+https://github.com/intel/llvm/issues
+
+Contributors
+------------
+
+- Gang Chen, Intel
+- Aleksandr Bezzubikov, Intel
+- Aleksander Us, Intel
+- Nikita Rudenko, Intel
+- Konstantin Vladimirov, Intel
+- Alexey Sachkov, Intel
+- Mariusz Merecki, Intel
+
+
+Notice
+------
+
+Copyright (c) 2020-2022 Intel Corporation. All rights reserved.
+
+Status
+------
+
+Working Draft
+
+This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension.
+
+Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products. If you are interested in using this feature in your software product, please let us know!
+
+
+Version
+-------
+
+[width="40%",cols="25,25"]
+|========================================
+| Last Modified Date | 2022-03-31
+| Revision           | 15
+|========================================
+
+Dependencies
+------------
+
+This extension is written against the SPIR-V Specification,
+Version 1.5, Revision 2, Unified
+
+This extension requires SPIR-V 1.0.
+
+Overview
+--------
+
+This extension adds new capability, execution mode and decorations
+to support INTEL vector compute specific features in SPIR-V.
+
+
+Extension Name
+--------------
+
+To use this extension within a SPIR-V module, the following
+*OpExtension* must be present in the module:
+
+----
+OpExtension "SPV_INTEL_vector_compute"
+----
+
+Modifications to the SPIR-V Specification, Version 1.5, Revision 2, Unified
+---------------------------------------------------------------------------
+
+Modify Section 2.2.2, Types, add *OpTypeBufferSurfaceINTEL* to the list of _Opaque Types_
+
+Modify Section 3.6, Execution Mode, add the following rows to the Execution Mode table:
+
+--
+[cols="1,20,10,10",options="header",width = "80%"]
+|====
+  2+^| Execution Mode  | Enabling Capabilities | Extra Operands
+| 5618 | *SharedLocalMemorySizeINTEL* +
+Specifies the size of shared memory required by kernel, in bytes.
+
+'Size' is an unsigned 32-bit integer.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _Size_
+| 6417 | *NamedBarrierCountINTEL* +
+Specifies the number of named barriers used by kernel. _Barrier Count_ is an unsigned 32-bit integer.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _Barrier Count_
+|====
+--
+Modify Section 3.7, Storage Class: +
+Add *VectorComputeINTEL* to the list of enabling capabilities for the *Private* storage class.
+
+Modify Section 3.20, Decoration, add the following rows to the Decoration table:
+
+--
+[cols="1,20,10,10",options="header",width = "80%"]
+|====
+2+^| Decoration  | Enabling Capabilities | Extra Operands
+| 5599 | *SIMTCallINTEL* +
+Apply to a function definition to specify that this function must be vectorized to width specified in 'N'.
+
+'N' is an unsigned 32-bit integer.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _N_
+| 5624 | *VectorComputeVariableINTEL* +
+Apply to a variable to specify that the variable is a vector compute variable.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* |
+| 5625 | *FuncParamIOKindINTEL* +
+Apply to a function parameter to specify properties of the register file corresponding to the parameter.
+
+'Kind' is an unsigned 32-bit integer.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _Kind_
+| 5626 | *VectorComputeFunctionINTEL* +
+Apply to a function definition to specify that the function is a vector compute function.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* |
+| 5627 | *StackCallINTEL* +
+Apply to a function definition to specify that this function is a stack call function.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* |
+| 5628 | *GlobalVariableOffsetINTEL* +
+Apply to a variable to specify byte offset in general register file.
+
+'Offset' is an unsigned 32-bit integer.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _Offset_
+| 6085 | *SingleElementVectorINTEL* +
+Apply to a global variable, a function or a function parameter to indicate that the global variable or function's return value or the function parameter is a single-element vector or a pointer to a single-element vector in the high-level language. +
+
+Only valid on *OpVariable* or *OpFunction* or *OpFunctionParameter* whose type is <<Scalar,scalar type>> or <<Pointer,pointer type>>.
+
+'Levels' is an unsigned 32-bit integer. 'Levels' specifies the number of levels of indirection of the vector element in the high-level language if the type of the decorated instruction is a pointer-to-pointer type.
+
+See the client API specification for more detail.
+| *VectorComputeINTEL* | <<Literal, 'Literal'>> _Levels_
+|====
+
+Modify the description of *Volatile* decoration, add the following text: +
+If the *VectorComputeINTEL* capability is declared *Volatile* may be applied to memory object declarations or members of a structure type in *Private* or *Workgroup* storage class.
+
+--
+
+Modify Section 3.18, Access Qualifier: +
+Add *OpTypeBufferSurfaceINTEL* to the list of instructions that use Access Qualifier.
+
+Modify Section 3.19, Function Parameter Attribute, add the following rows to the 'Function Parameter Attribute' table:
+
+--
+[cols="1,20,10",options="header",width = "80%"]
+|====
+2+^| Decoration  | Enabling Capabilities
+| 6140 | *MediaBlockIOINTEL* +
+The image is only used in *OpSubgroupImageMediaBlockReadINTEL* or *OpSubgroupImageMediaBlockWriteINTEL*.
+Only valid for image parameters. Not valid on return values.
+| *VectorComputeINTEL*
+|====
+--
+
+Modify Section 3.31, Capability, add the following rows to the 'Capability' table:
+--
+[cols="1,20,10,10",options="header",width = "80%"]
+|====
+  2+^| Capability      |     Implicitly Declares    | Enabled by Extension
+| 5617 | *VectorComputeINTEL* +
+Enables the use of *Private* storage class, *SharedLocalMemorySizeINTEL* execution mode and *VectorComputeFunctionINTEL*, *VectorComputeVariableINTEL*, *StackCallINTEL*, *SIMTCallINTEL*, *FuncParamIOKindINTEL*, *GlobalVariableOffsetINTEL*
+*SingleElementVectorINTEL* decorations and *OpTypeBufferSurfaceINTEL* type.
+|*VectorAnyINTEL* | *SPV_INTEL_vector_compute*
+| 5619 | *VectorAnyINTEL* +
+Uses OpTypeVector to declare vectors with any number of components greater or equal to 2.
+|| *SPV_INTEL_vector_compute*
+|====
+--
+
+Modify Section 3.36.6. Type-Declaration Instructions, add to the end of type instructions list:
+--
+[cols="1,1,1,1",width="60%"]
+|=====
+3+|*OpTypeBufferSurfaceINTEL* +
+ +
+Delare a buffer surface type. This type is opaque: values of this type have no defined physical size or bit pattern.
+ +
+ 'Access Qualifier' is an image <<Access_Qualifier, Access Qualifier>>.
+|Capability: +
+*VectorComputeINTEL*
+| 2+ | 6086 | 'Result <id>' | Optional <<Access_Qualifier, 'Access Qualifier'>>
+|=====
+--
+
+Issues
+------
+
+
+Revision History
+----------------
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-04-17|Mariusz Merecki|Initial revision
+|2|2020-04-24|Mariusz Merecki|Assigned token number to *VectorComputeFunctionINTEL*
+|3|2020-05-06|Mariusz Merecki|Removed *VectorComputeKernelINTEL*, *KernelArgumentTypeINTEL* and *KernelArgumentDescINTEL*. Added *VectorComputeFunctionINTEL*.
+|4|2020-06-03|Mariusz Merecki|Added *VectorAnyINTEL*, *VectorComputeVariableINTEL*, *FuncParamIOKindINTEL* and *GlobalVariableOffsetINTEL*. Added updates for the *Volatile* decoration and *Private* storage class descriptions.
+|5|2020-07-09|Mariusz Merecki|Added *SIMTCallINTEL* decoration.
+|6|2020-08-13|Mariusz Merecki|Added *OpTypeBufferSurfaceINTEL* type and *SingleElementVectorINTEL* decoration.
+|7|2020-09-03|Mariusz Merecki|Added *Access Qualifier* operand to *OpTypeBufferSurfaceINTEL*
+|8|2020-10-07|Mariusz Merecki|Added *VectorComputeCallableFunctionINTEL*
+|9|2020-10-07|Mariusz Merecki|Added Change the description of *SingleElementVectorINTEL* to allow the decoration to be applied to function and function parameters of scalar or pointer type only.
+|10|2020-11-24|Mariusz Merecki|Added *VectorComputeFastCompositeKernelINTEL*, execution mode. Decorations sorted wrt their assigned token.
+|11|2020-12-03|Mariusz Merecki|Fix token number of *VectorComputeFastCompositeKernelINTEL*
+|12|2020-12-16|Mariusz Merecki|Remove *VectorComputeFastCompositeKernelINTEL* and *VectorComputeCallableFunctionINTEL*, moved to SPV_INTEL_fast_composition
+|13|2020-08-19|Mariusz Merecki|Allow *SingleElementVectorINTEL* on global variables, add extra operand to *SingleElementVectorINTEL* to specify the number of levels of indirection for single-element vectors of pointers, clarify that with *VectorAnyINTEL* the number of vector components must be grater or equal to 2
+|14|2020-11-17|Mariusz Merecki|Add *MediaBlockIOINTEL* Function Parameter Attribute
+|15|2022-03-31|Mariusz Merecki|Add *NamedBarrierCountINTEL* Execution Mode
+|========================================