[SYCL][Doc] Adjust design for compile-time properties through add_ir_annotations_member

During implementation of the attribute and translation of annotations
on fields, the design was conflicting with existing features. This
commit makes the following design changes:

 * Change the `llvm.ptr.annotation` intrinsic call produced by
   `[[__sycl_detail__::add_ir_annotations_member()]]` to use a pointer
   to a constant global variable instead of metadata. This is done to
   adhere to the signature of the intrinsic.
 * Change the representation consumed by the translator from a new
   SPIR-V builtin to an extended version of existing decoration parsing
   using `llvm.ptr.annotation`.

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

Author: steffenlarsen

sycl/doc/design/CompileTimeProperties.md

@@ -515,12 +515,56 @@ The front-end encodes the properties from the C++ attribute
 * The third parameter is the name of the source file (as with any call to this
   intrinsic).
 * The fourth parameter is the line number (as with any call to this intrinsic).
-* The fifth parameter is a metadata tuple with information about all of the
-  properties.  The first element of the tuple is a string literal with the name
-  of the first property.  The second element is the value of the first
-  property.  The third element is a string literal with the name of the second
-  property, etc.  Since each property has exactly one value, this tuple has an
-  even number of elements.
+* The fifth parameter is a pointer to a constant global variable. The type of
+  this variable is an anonymous structure. The first field of the structure is
+  a pointer to a string literal representing the name of the first property. The
+  second field of the structure is a pointer to a string literal representing
+  the value of the first property. The third field of the structure is a pointer
+  to a string literal representing the name of the second property, etc.
+  Since each property has exactly one value, this tuple has an even number of
+  elements. Pointers to property value strings may be a null-pointer, signalling
+  a property without a value.
+
+The resulting LLVM IR for the previous example would be:
+
+```
+@.str = private unnamed_addr constant [16 x i8] c"sycl-properties\00",
+   section "llvm.metadata"
+@.str.1 = private unnamed_addr constant [9 x i8] c"file.cpp\00",
+   section "llvm.metadata"
+@.str.2 = private unnamed_addr constant [9 x i8] c"sycl-foo\00",
+   section "llvm.metadata"
+@.str.3 = private unnamed_addr constant [9 x i8] c"sycl-bar\00",
+   section "llvm.metadata"
+@.str.4 = private unnamed_addr constant [3 x i8] c"32\00",
+   section "llvm.metadata"
+
+@.args = private unnamed_addr constant { [9 x i8]*, i8*, [9 x i8]*, [3 x i8]* }
+   {
+     [9 x i8]* @.str.2,   ; Name of first property "sycl-foo"
+     i8* null,            ; Null indicates this property has no value
+     [9 x i8]* @.str.3,   ; Name of second property "sycl-bar"
+     [3 x i8]* @.str.4    ; Value of second property
+   },
+   section "llvm.metadata"
+
+define void @foo(i32* %ptr) {
+  %aptr = alloca %class.annotated_ptr
+  %ptr = getelementptr inbounds %class.annotated_ptr, %class.annotated_ptr* %aptr,
+    i32 0, i32 0
+  %1 = bitcast i32** %ptr to i8*
+
+  %2 = call i8* @llvm.ptr.annotation.p0i8(i8* nonnull %0,
+    i8* getelementptr inbounds ([16 x i8], [16 x i8]* @.str, i64 0, i64 0),
+    i8* getelementptr inbounds ([9 x i8], [9 x i8]* @.str.1, i64 0, i64 0),
+    i32 3,
+    i8* bitcast ({ [9 x i8]*, i8*, [9 x i8]*, [3 x i8]* }* @.args to i8*))
+
+  %3 = bitcast i8* %2 to i32**
+  store i32* %ptr, i32** %3
+  ret void
+}
+```
 
 **NOTE**: Calls to the `@llvm.ptr.annotation` intrinsic function are known to
 disable many clang optimizations.  As a result, properties added to a
@@ -806,26 +850,57 @@ into one (or both) of the following:
 In both cases, the decoration is a single **UserSemantic** decoration where the
 string literal is the same as the string literal in the LLVM annotation.
 
-When a SYCL structure member property needs to be represented in SPIR-V,
-however, we prefer to represent each property as an extended SPIR-V decoration
-rather than using a **UserSemantic** decoration.  There is no existing
-mechanism in the SPIR-V LLVM Translator to generate extended decorations like
-this, so we propose the following new mechanism.
+An exception to this is for a selection of FPGA-related decorations. If these
+are supported during translation from LLVM IR to SPIR-V the corresponding
+decorations will be generated, and otherwise it will fall back to creating a
+single **UserSemantic** decoration. In general these decorations occur in the
+annotation string as a series of **{X}** and **{X:Y}** where **X** is a reserved
+name and **Y** is one or more words and numbers separated by **,** or **:**,
+depending on the decoration.
+
+As such we propose an extension to this functionality with the following
+changes:
+
+* To bring it in line with the format of the metadata decorations, the parsing
+  of these decorations should allow the use of SPIR-V decoration identifiers
+  rather than reserved names. With this there need not be any agreement between
+  the translator and LLVM IR producer, as the identifiers are specified by the
+  SPIR-V specification.
+* For decorations parsed with decoration identifiers, only the **,** delimiter
+  is valid for separating decoration values.
+* In addition to words and numbers, string literals enclosed by quotation marks
+  are allowed as decoration values. No escapes are planned for this, so all
+  symbols between starting quotation mark and ending quotation mark are
+  considered part of the string literal.
 
 When a member variable property needs to be represented in SPIR-V, the
-`sycl-post-link` tool converts the `@llvm.ptr.annotation` intrinsic call into a
-call to the SPIR-V intrinsic `__spirv_AddMemberDecoration` which has a metadata
-function argument that specifies the decorations as illustrated below:
+`sycl-post-link` tool converts the `@llvm.ptr.annotation` intrinsic call
+produced by `[[__sycl_detail__::add_ir_annotations_member()]]` into another
+`@llvm.ptr.annotation` intrinsic call using this format. For example:
 
 ```
-%annotated_ptr = call i8* __spirv_AddMemberDecoration(i8* %ptr, metadata !0)
+; Contains decorations:
+;  * 7744 with no value.
+;  * 7745 with 20 and "str 1" as the values.
+@.str = private unnamed_addr constant [24 x i8] c"{7744}{7745:20,"str 1"}\00",
+  section "llvm.metadata"
+@.str.1 = private unnamed_addr constant [9 x i8] c"file.cpp\00",
+   section "llvm.metadata"
 
-!0 = !{!1, !2}            ; Each operand in this metadata represents one
-                          ;   decoration.
-!1 = !{i32 7744}          ; This is the integer value of the first decoration.
-!2 = !{i32 7745, i32 20}  ; The first operand is the integer value of the
-                          ;   second decoration.  Additional operands are
-                          ;   "extra operands" to the decoration.  These
-                          ;   operands may be either integer literals or string
-                          ;   literals.
+define void @foo(i32* %ptr) {
+  ...
+
+  ; %0 points to the annotated member field.
+  %2 = call i8* @llvm.ptr.annotation.p0i8(i8* nonnull %0,
+    i8* getelementptr inbounds ([16 x i8], [16 x i8]* @.str, i64 0, i64 0),
+    i8* getelementptr inbounds ([9 x i8], [9 x i8]* @.str.1, i64 0, i64 0),
+    i32 3,
+    i8* null)
+
+  ...
+}
 ```
+
+**NOTE**: To allow backwards compatibility with the old format, reverse
+translation of decorations will produce a decorations in the annotation string
+following the old format if the decoration had a reserved name.