[NFC] update LangRef for D88645

[Tyker]

Summary

reflect IR change in the LangRef after addition on a new parameter to llvm.ptr.annotation.* and llvm.var.annotation in d3205bbca3e0002d76282878986993e7e7994779.

[jdoerfert]

The text needs an update too. It talks about each argument but not the new one. Also, " and the last argument is the line number." is now clearly wrong.

[Tyker]

addressed comment

[andrew.w.kaylor]

llvm/docs/LangRef.rst

19804–19805

This 'and' becomes redundant with the additional text.

19805

Can you add some information about what the additional arguments are? What exactly does this point to?

[Tyker]

fixed the sentence.

[jdoerfert]

Can you add some information about what the additional arguments are? What exactly does this point to?

This is not clear from the description.

[Tyker]

added more details about the storage of additional arguments.

[andrew.w.kaylor]

I'm not trying to be difficult, but I genuinely still don't understand the additional arguments pointer. Is it intended to allow proprietary extensions? Is there an example somewhere?

If these intrinsics are meant as a general mechanism to enable arbitrary communication between custom front ends and custom optimization passes, that's fine. I'd just like to see something explicitly explaining that.

[lebedev.ri]

This patch is missing a description.

[Tyker]

In D96646#2594843, @andrew.w.kaylor wrote:

I'm not trying to be difficult, but I genuinely still don't understand the additional arguments pointer. Is it intended to allow proprietary extensions? Is there an example somewhere?

If these intrinsics are meant as a general mechanism to enable arbitrary communication between custom front ends and custom optimization passes, that's fine. I'd just like to see something explicitly explaining that.

the pointer is to a global struct containing the the provided arguments. I use it to communicate from source code to custom passes. but the front-end doesn't need to be custom. since the code to generate theses extra arguments is in clang trunk.
here is a basic example: https://godbolt.org/z/Tavcv9.
how the passes use this information is not defined it can be used for many things.
the major benefit I see is that it can pass arbitrary information and works well with template and constexpr programing. but the front-end does not do any semantic checking on the meaning of the information.

[andrew.w.kaylor]

In D96646#2611589, @Tyker wrote:

In D96646#2594843, @andrew.w.kaylor wrote:

I'm not trying to be difficult, but I genuinely still don't understand the additional arguments pointer. Is it intended to allow proprietary extensions? Is there an example somewhere?

If these intrinsics are meant as a general mechanism to enable arbitrary communication between custom front ends and custom optimization passes, that's fine. I'd just like to see something explicitly explaining that.

the pointer is to a global struct containing the the provided arguments. I use it to communicate from source code to custom passes. but the front-end doesn't need to be custom. since the code to generate theses extra arguments is in clang trunk.
here is a basic example: https://godbolt.org/z/Tavcv9.
how the passes use this information is not defined it can be used for many things.
the major benefit I see is that it can pass arbitrary information and works well with template and constexpr programing. but the front-end does not do any semantic checking on the meaning of the information.

I was reminded today that this never landed and the LangRef is still wrong. Can you incorporate the explanation above about how this is used into the LangRef documentation?

[arichardson]

I was just looking at llvm.ptr.annotation and noticed that the LangRef did not match the actual arguments since D88645. Could you please fix this?

llvm/docs/LangRef.rst

19804

19844

[lebedev.ri]

This review may be stuck/dead, consider abandoning if no longer relevant.
Removing myself as reviewer in attempt to clean dashboard.

llvm/docs/LangRef.rst

 '``llvm.var.annotation``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
-      declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>, i8* <args>)
 
 Overview:
 """""""""
 
 The '``llvm.var.annotation``' intrinsic.
 
 Arguments:
 """"""""""
 
 The first argument is a pointer to a value, the second is a pointer to a
 global string, the third is a pointer to a global string which is the
-source file name, and the last argument is the line number.
+source file name, the forth argument is the line number and the last argument
+is a pointer to a global struct containing additional arguments.
 
 Semantics:
 """"""""""
 
 This intrinsic allows annotation of local variables with arbitrary
 strings. This can be useful for special purpose optimizations that want
 to look for these annotations. These have no other defined use; they are
 ignored by code generation and optimization.
 
 '``llvm.ptr.annotation.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
 pointer to an integer of any width. *NOTE* you must specify an address space for
 the pointer. The identifier for the default address space is the integer
 '``0``'.
 
 ::
 
-      declare i8*   @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
-      declare i16*  @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32  <int>)
-      declare i32*  @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32  <int>)
-      declare i64*  @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32  <int>)
-      declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32  <int>)
+      declare i8*   @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32  <int>, i8* <args>)
+      declare i16*  @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32  <int>, i8* <args>)
+      declare i32*  @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32  <int>, i8* <args>)
+      declare i64*  @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32  <int>, i8* <args>)
+      declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32  <int>, i8* <args>)
 
 Overview:
 """""""""
 
 The '``llvm.ptr.annotation``' intrinsic.
 
 Arguments:
 """"""""""
 
 The first argument is a pointer to an integer value of arbitrary bitwidth
 (result of some expression), the second is a pointer to a global string, the
-third is a pointer to a global string which is the source file name, and the
-last argument is the line number. It returns the value of the first argument.
+third is a pointer to a global string which is the source file name, the forth
+is the line number and the last is a pointer to a global struct containing
+additional arguments. It returns the value of the first argument.
 
 Semantics:
 """"""""""
 
 This intrinsic allows annotation of a pointer to an integer with arbitrary
 strings. This can be useful for special purpose optimizations that want to look
 for these annotations. These have no other defined use; they are ignored by code
 generation and optimization.