Update SPV and OCL specs w.r.t. variable name

We decided that we need some alternate way for the host to reference a
global variable in the kernel other than using the exported SPIR-V
name.  Extend the `HostAccessINTEL` decoration to take a new `Name`
parameter.  This allows the host to access even a non-exported
`OpVariable`.

Changes are still needed to the "DeviceGlobal.md" spec to explain how
this new field will be set by the compiler.  Those changes will be made
in a separate commit.

Author: gmlueck

sycl/doc/extensions/DeviceGlobal/SPV_INTEL_global_variable_decorations.asciidoc

@@ -61,8 +61,8 @@ This extension requires SPIR-V 1.0.
 == Overview
 
 This extension adds decorations that can be applied to global (module scope)
-variables.  These decorations are intended to help code generation for FPGA
-devices, but they must be recognized by any consumer that supports this
+variables.  These decorations are mostly intended to help code generation for
+FPGA devices, but they must be recognized by any consumer that supports this
 extension.
 
 == Extension Name
@@ -103,7 +103,7 @@ Modify Section 3.20, Decoration, adding these rows to the Decoration table:
 --
 [options="header"]
 |====
-2+^| Decoration | Extra Operands | Enabling Capabilities
+2+^| Decoration 2+^| Extra Operands | Enabling Capabilities
 
 // --- ROW BREAK ---
 | 6147
@@ -113,8 +113,10 @@ Only valid on global (module scope) *OpVariable*.
 
 The client API's execution environment may provide a way to access a global
 variable's value from the host system.  If it does, this decoration provides
-an assertion by the producer about the types of these accesses.  This may allow
-the consumer to perform certain optimizations, especially for FPGA devices.
+two pieces of information.  _Access_ is an assertion by the producer about the
+types of these accesses, which may allow the consumer to perform certain
+optimizations, especially for FPGA devices.  _Name_ is a name which the client
+API's execution environment may use to identify this variable.
 
 Legal values of _Access_:
 
@@ -135,6 +137,8 @@ If a global *OpVariable* is not decorated with *HostAccessINTEL*, the default
 behavior is [Read/Write].
 | Literal Number +
 _Access_
+| Literal String +
+_Name_
 | *GlobalVariableDecorationsINTEL*
 
 // --- ROW BREAK ---
@@ -154,7 +158,7 @@ Legal values of _Trigger_:
 * 1 [init on device reset] - Initialization is performed when a reset signal is
   sent to the device.
 
-| Literal Number +
+2+| Literal Number +
 _Trigger_
 | *GlobalVariableDecorationsINTEL*
 
@@ -174,7 +178,7 @@ Legal values of _Value_:
 * 1 [True] - Access to this memory is through a CSR interface shared with the
   kernel arguments.
 
-| Literal Number +
+2+| Literal Number +
 _Value_
 | *GlobalVariableDecorationsINTEL*
 

sycl/doc/extensions/DeviceGlobal/cl_intel_global_variable_pointers.asciidoc

@@ -96,7 +96,26 @@ cl_int clGetDeviceGlobalVariablePointerINTEL(
     void **global_variable_pointer_ret );
 ----
 is used to retrieve a pointer to a user-defined global variable
-_global_variable_name_ which exists in built _program_.
+_global_variable_name_ which exists in built _program_.  The interpretation of
+_global_variable_name_ depends on how the _program_ was created:
+
+* If the _program_ was created with *clCreateProgramWithSource* from OpenCL C
+  sources, *TODO* (see Issues section below).
+
+* If the _program_ was created with *clCreateProgramWithIL* from SPIR-V, there
+  are two cases:
+
+  - If the SPIR-V module declares the *GlobalVariableDecorationsINTEL*
+    capability, the implementation looks first for an *OpVariable* that is
+    decorated with *HostAccessINTEL* where the _Name_ operand is the same as
+    _global_variable_name_.
+
+  - The implementation next looks for an *OpVariable* that is decorated with
+    *LinkageAttributes* where the _Linkage Type_ is *Export* and the _Name_
+    operand is the same as _global_variable_name_.
+
+* If the _program_ was created in any other way, the interpretation of
+  _global_variable_name_ is implementation-defined.
 
 The returned pointer is a Unified Shared Memory pointer to the requested global
 variable and is specific to given _device_.
@@ -150,21 +169,12 @@ cl_intel_global_variable_pointers ...
 
 == Issues
 
-. Can this extension be used to query the address of any global variable in the program?
+. Exactly what is the interpretation of _global_variable_name_ for a _program_
+  that was created from OpenCL C sources?  Must the variable be declared
+  "extern"?  Are "constant" variables allowed?
 +
 --
 *UNRESOLVED*
-
-It is not possible to obtain address of *any* arbitrary global variable using
-`clGetDeviceGlobalVariablePointerINTEL`, and the mechanism to identify that the
-global variable may have it's address taken is dependent on how program object
-is created:
-
-* for programs created from source, *TODO* (extern?)
-
-* for programs created from SPIR-V IL, *TODO* (global variable needs to have *export* linkage?)
-
-* for programs created from a binary, the mechanism is implementation defined.
 --
 
 . Can a queried global variable pointer be used by a kernel from another program object?
@@ -185,4 +195,5 @@ Currently this is disallowed.
 |Rev|Date|Author|Changes
 |0.9.0|2019-09-14|Jaroslaw Chodor|*Initial revision*
 |0.9.0|2021-09-22|Ben Ashbaugh|Added preview disclaimer, general cleanup.
+|0.9.0|2021-10-18|Greg Lueck|Clarify variable name for SPIR-V case.
 |========================================