This is an archive of the discontinued LLVM Phabricator instance.

Differential D96646

[NFC] update LangRef for D88645
Needs RevisionPublic

Authored by Tyker on Feb 13 2021, 4:28 AM.

Details

Reviewers
jdoerfert
arichardson
lebedev.ri
Summary

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

Diff Detail

Event Timeline

Tyker requested review of this revision.Feb 13 2021, 4:28 AM
Tyker created this revision.
Herald added a project: Restricted Project. · View Herald TranscriptFeb 13 2021, 4:28 AM
Herald added a subscriber: llvm-commits. · View Herald Transcript
Tyker mentioned this in D88645: [Annotation] Allows annotation to carry some additional constant arguments..Feb 13 2021, 4:29 AM
Harbormaster completed remote builds in B89106: Diff 323546.Feb 13 2021, 5:29 AM
jdoerfert added a comment.Feb 13 2021, 2:32 PM

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 updated this revision to Diff 323788.Feb 15 2021, 10:14 AM

addressed comment

Harbormaster completed remote builds in B89258: Diff 323788.Feb 15 2021, 11:30 AM
andrew.w.kaylor added a subscriber: andrew.w.kaylor.Feb 16 2021, 10:49 AM
andrew.w.kaylor added inline comments.
llvm/docs/LangRef.rst
19804

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?

andrew.w.kaylor mentioned this in D95993: Add auto-upgrade support for annotation intrinsics.Feb 22 2021, 1:06 PM
Tyker updated this revision to Diff 325715.Feb 23 2021, 1:55 AM

fixed the sentence.

Harbormaster completed remote builds in B90360: Diff 325715.Feb 23 2021, 2:59 AM
jdoerfert added a comment.Feb 23 2021, 8:22 AM

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

This is not clear from the description.

tstellar added a subscriber: tstellar.Feb 23 2021, 11:14 AM
Tyker updated this revision to Diff 327088.Mar 1 2021, 5:52 AM

added more details about the storage of additional arguments.

Harbormaster completed remote builds in B91319: Diff 327088.Mar 1 2021, 7:02 AM
andrew.w.kaylor added a comment.Mar 1 2021, 10:38 AM

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 requested changes to this revision.Mar 1 2021, 10:43 AM
lebedev.ri added a subscriber: lebedev.ri.

This patch is missing a description.

This revision now requires changes to proceed.Mar 1 2021, 10:43 AM
Tyker edited the summary of this revision. (Show Details)EditedMar 8 2021, 9:39 AM
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 added a comment.Dec 3 2021, 12:13 PM
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 requested changes to this revision.Nov 19 2022, 3:42 AM
arichardson added a subscriber: 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
Herald added a project: Restricted Project. · View Herald TranscriptNov 19 2022, 3:42 AM
lebedev.ri resigned from this revision.Jan 12 2023, 4:59 PM

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

Herald added a subscriber: StephenFan. · View Herald TranscriptJan 12 2023, 4:59 PM

Revision Contents

PathSize
llvm/
docs/
12 lines

Diff 323546

llvm/docs/LangRef.rst

  • This file is larger than 256 KB, so syntax highlighting is disabled by default.
Show First 20 Lines • Show All 19,783 Lines • ▼ Show 20 Lines
'``llvm.var.annotation``' Intrinsic '``llvm.var.annotation``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax: 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: Overview:
""""""""" """""""""
The '``llvm.var.annotation``' intrinsic. The '``llvm.var.annotation``' intrinsic.
Arguments: Arguments:
"""""""""" """"""""""
The first argument is a pointer to a value, the second is a pointer to a 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 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, and the last argument is the line number.
andrew.w.kaylorUnsubmitted
Not Done
ReplyInline Actions

This 'and' becomes redundant with the additional text.

andrew.w.kaylor: This 'and' becomes redundant with the additional text.
arichardsonUnsubmitted
Not Done
ReplyInline Actions
global string, the third is a pointer to a global string which is the
- source file name, the forth argument is the line number and the last argument
+ source file name, the fourth argument is the line number and the last argument
is a pointer to a global struct containing additional arguments.
arichardson:
andrew.w.kaylorUnsubmitted
Not Done
ReplyInline Actions

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

andrew.w.kaylor: Can you add some information about what the additional arguments are? What exactly does this…
Semantics: Semantics:
"""""""""" """"""""""
This intrinsic allows annotation of local variables with arbitrary This intrinsic allows annotation of local variables with arbitrary
strings. This can be useful for special purpose optimizations that want strings. This can be useful for special purpose optimizations that want
to look for these annotations. These have no other defined use; they are to look for these annotations. These have no other defined use; they are
ignored by code generation and optimization. ignored by code generation and optimization.
'``llvm.ptr.annotation.*``' Intrinsic '``llvm.ptr.annotation.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax: Syntax:
""""""" """""""
This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a 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 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 the pointer. The identifier for the default address space is the integer
'``0``'. '``0``'.
:: ::
declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <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>) 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>) 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>) 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>) declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>, i8* <args>)
Overview: Overview:
""""""""" """""""""
The '``llvm.ptr.annotation``' intrinsic. The '``llvm.ptr.annotation``' intrinsic.
Arguments: Arguments:
"""""""""" """"""""""
The first argument is a pointer to an integer value of arbitrary bitwidth 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 (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 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. last argument is the line number. It returns the value of the first argument.
arichardsonUnsubmitted
Not Done
ReplyInline Actions
(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, the forth
+ third is a pointer to a global string which is the source file name, the fourth
is the line number and the last is a pointer to a global struct containing
arichardson:
Semantics: Semantics:
"""""""""" """"""""""
This intrinsic allows annotation of a pointer to an integer with arbitrary 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 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 for these annotations. These have no other defined use; they are ignored by code
generation and optimization. generation and optimization.
▲ Show 20 Lines • Show All 1,551 Lines • Show Last 20 Lines