[SYCL] Add property set fields to the binary image descriptor, bump PI version.

This change breaks backward binary compatibility of device binary image descriptors.

Signed-off-by: Konstantin S Bobrovsky <[email protected]>

Author: kbobrovs

sycl/include/CL/sycl/detail/pi.h

@@ -27,8 +27,16 @@
 // maintained there should be a (+1) change to the major version in
 // addition to the increase of the minor.
 //
+// PI version changes log:
+// -- Version 1.2:
+// 1. (Binary backward compatibility breaks) Two fields added to the
+// pi_device_binary_struct structure:
+//   pi_device_binary_property_set PropertySetsBegin;
+//   pi_device_binary_property_set PropertySetsEnd;
+// 2. A number of types needed to define pi_device_binary_property_set added.
+//
 #define _PI_H_VERSION_MAJOR 1
-#define _PI_H_VERSION_MINOR 1
+#define _PI_H_VERSION_MINOR 2
 
 #define _PI_STRING_HELPER(a) #a
 #define _PI_CONCAT(a, b) _PI_STRING_HELPER(a.b)
@@ -531,6 +539,35 @@ struct _pi_offload_entry_struct {
 
 using _pi_offload_entry = _pi_offload_entry_struct *;
 
+// A type of a binary image property.
+typedef enum {
+  PI_PROP_TYPE_UNKNOWN,
+  PI_PROP_TYPE_UINT32, // 32-bit integer
+  PI_PROP_TYPE_STRING  // null-terminated string
+} _pi_property_type;
+
+// Device binary image property.
+// If the type size of the property value is fixed and is no greater than
+// 64 bits, then ValAddr is 0 and the value is stored in the ValSize field.
+// Example - PI_PROP_TYPE_UINT32, which is 32-bit
+struct _pi_device_binary_property_struct {
+  char *Name;       // null-terminated property name
+  void *ValAddr;    // address of property value
+  uint32_t Type;    // _pi_property_type
+  uint64_t ValSize; // size of property value in bytes
+};
+
+typedef _pi_device_binary_property_struct *pi_device_binary_property;
+
+// Named array of properties.
+struct _pi_device_binary_property_set_struct {
+  char *Name;                                // the name
+  pi_device_binary_property PropertiesBegin; // array start
+  pi_device_binary_property PropertiesEnd;   // array end
+};
+
+typedef _pi_device_binary_property_set_struct *pi_device_binary_property_set;
+
 /// Types of device binary.
 using pi_device_binary_type = uint8_t;
 // format is not determined
@@ -566,10 +603,15 @@ static const uint8_t PI_DEVICE_BINARY_OFFLOAD_KIND_SYCL = 4;
 #define PI_DEVICE_BINARY_TARGET_SPIRV64_X86_64 "spir64_x86_64"
 #define PI_DEVICE_BINARY_TARGET_SPIRV64_GEN "spir64_gen"
 #define PI_DEVICE_BINARY_TARGET_SPIRV64_FPGA "spir64_fpga"
-
 /// PTX 64-bit image <-> "nvptx64", 64-bit NVIDIA PTX device
 #define PI_DEVICE_BINARY_TARGET_NVPTX64 "nvptx64"
 
+/// Device binary image property set names recognized by the SYCL runtime.
+/// Name must be consistent with
+/// PropertySetRegistry::SYCL_SPECIALIZATION_CONSTANTS defined in
+/// PropertySetIO.h
+#define PI_PROPERTY_SET_SPEC_CONST_MAP "SYCL/specialization constants"
+
 /// This struct is a record of the device binary information. If the Kind field
 /// denotes a portable binary type (SPIR-V or LLVM IR), the DeviceTargetSpec
 /// field can still be specific and denote e.g. FPGA target. It must match the
@@ -610,6 +652,13 @@ struct pi_device_binary_struct {
   /// the offload entry table
   _pi_offload_entry EntriesBegin;
   _pi_offload_entry EntriesEnd;
+  // Array of preperty sets; e.g. specialization constants symbol-int ID map is
+  // propagated to runtime with this mechanism.
+  pi_device_binary_property_set PropertySetsBegin;
+  pi_device_binary_property_set PropertySetsEnd;
+  // TODO Other fields like entries, link options can be propagated using
+  // the property set infrastructure. This will improve binary compatibility and
+  // add flexibility.
 };
 using pi_device_binary = pi_device_binary_struct *;