[SYCL][Doc] Expand device_global related PI API (#5906)

This commit changes the PI API introduced by the device_global design
document, aligning it with the corresponding OpenCL API and the rest of
PI API.

Additionally, it changes the references to relevant CUDA API functions
from referring to the CUDA runtime API to refer to the CUDA driver API,
which is the API used by the CUDA backend.

Signed-off-by: Steffen Larsen <[email protected]>

Author: steffenlarsen

sycl/doc/design/DeviceGlobal.md

@@ -563,15 +563,37 @@ instance of a device global variable in a `pi_program`.  This functionality is
 exposed as two new PI interfaces:
 
 ```
-pi_result piextCopyToDeviceVariable(pi_device Device, pi_program Program,
-  const char *name, const void *src, size_t count, size_t offset);
-
-pi_result piextCopyFromDeviceVariable(pi_device Device, pi_program Program,
-  const char *name, void *dst, size_t count, size_t offset);
+pi_result piextEnqueueDeviceVariableRead(pi_queue Queue, pi_program Program,
+                                         const char *Name, pi_bool BlockingRead,
+                                         size_t Count, size_t Offset, void *Dst,
+                                         pi_uint32 NumEventsInWaitList,
+                                         const pi_event *EventsWaitList,
+                                         pi_event *Event);
+
+pi_result piextEnqueueDeviceVariableWrite(pi_queue Queue, pi_program Program,
+                                          const char *Name,
+                                          pi_bool BlockingWrite, size_t Count,
+                                          size_t Offset, const void *Src,
+                                          pi_uint32 NumEventsInWaitList,
+                                          const pi_event *EventsWaitList,
+                                          pi_event *Event);
 ```
 
-In both cases the `name` parameter is the same as the `sycl-unique-id` string
-that is associated with the device global variable.
+The `piextEnqueueDeviceVariableRead` function reads `Count` bytes at byte-offset
+`Offset` from a device global variable in `Program` identified by the name
+`Name`. The read data is stored in `Dst`. Likewise, the
+`piextEnqueueDeviceVariableWrite` function reads `Count` bytes from `Dst` and
+stores them at byte-offset `Offset` in the device global variable in `Program`
+identified by the name `Name`.
+
+Both functions will enqueue the associated memory command on `Queue` where it
+will first wait for `NumEventsInWaitList` events in `EventsWaitList` to finish.
+`Event` will be populated with the event associated with resulting enqueued
+command. If either `BlockingRead` or `BlockingWrite` is `true` the call will
+block on the host until the enqueued command finishes execution.
+
+For `device_global` variables the `Name` parameter in calls to these functions
+is the same as the associated `sycl-unique-id` string.
 
 The Level Zero backend has existing APIs that can implement these PI
 interfaces.  The plugin first calls [`zeModuleGetGlobalPointer()`][8] to get a
@@ -616,8 +638,8 @@ depends upon implementation of that OpenCL extension.
 
 [10]: <opencl-extensions/cl_intel_global_variable_access.asciidoc>
 
-The CUDA backend has existing APIs `cudaMemcpyToSymbol()` and
-`cudaMemcpyFromSymbol()` which can be used to implement these PI interfaces.
+The CUDA backend has existing APIs `cuModuleGetGlobal()` and `cuMemcpyAsync()`
+which can be used to implement these PI interfaces.
 
 
 ## Design choices