[llvm][docs] LangRef for IR attribute `vector-function-abi-variant`.

[jdoerfert]

What are instruction attributes? How would that look like? Is there a list discussion?

[fpetrogalli]

In D72798#1822598, @jdoerfert wrote:

What are instruction attributes? How would that look like? Is there a list discussion?

Hi @jdoerfert,

I thought we all agreed on this attribute by the fact we have implemented it - right now we have read/write functions for such attribute: https://reviews.llvm.org/D69976, and it is used in https://reviews.llvm.org/D72734

I couldn't find a section in the LangRef to describe it (it is not a function attribute) and decided to start a new one. I am happy to discuss to fall back on llvm-dev if you think I did something wrong.

Francesco

[andwar]

@fpetrogalli Thank you for working on this - just a few nits from me!

@jdoerfert I also assume that we have already agreed on this. Happy to fall back to llvm-dev if you feel otherwise.

llvm/docs/LangRef.rst

1876

function -> functions?

1877

scalar function -> scalar function that would otherwise we invoked by the call instruction? Maybe that's too verbose.

1883

correspondent -> corresponding ?

1889

the optional -> the optional name?

1890

Why would one provide a custom name? Perhaps it's worth expanding here.

1892

Declaration is a _necessary_ condition, definition is a _sufficient_ condition. Wouldn't declaration cover both?

1903

This is a bit confusing - with `<isa> = __LLVM__, which token specification one should use? The one for X86 or Arm? Could you clarify what <isa> == __LLVM__` means in practical terms?

[jdoerfert]

llvm/docs/LangRef.rst

1868

My problem/confusion was with the term Instruction here. These are (only) Call Site Attributes, correct?

[fpetrogalli]

Update text according to review.

llvm/docs/LangRef.rst

1868

Yes, the attribute I am describing here is an attribute that can be attached to a CallInst. I didn't know how to title the section, I am happy to suggestions.

1877

Hum, I am not convinced by this change. What's behind your suggestion?

[andwar]

llvm/docs/LangRef.rst

1877

You refer to the scalar function, but no scalar function is introduced beforehand. I know what scalar function you mean, but IMO it's not obvious from the context. But I'm a non-native speaker, so maybe just me :)

1912

For all targets (x86, Arm and Internal LLVM) - x86, Arm, internal LLVM are not all targets. Did you mean all targets for which this attribute is currently supported?

[andwar]

llvm/docs/LangRef.rst

1904

reconducible?

[fpetrogalli]

1. I have changed the title of the section from Instruction Attributes to Call Site Attributes, as suggested by @jdoerfert.
2. I have addressed the comments from @andwar.

[fpetrogalli]

llvm/docs/LangRef.rst

1904

bha, I made up an English word. I replaced it with associated.

[fpetrogalli]

I have rephrased the first paragraph to avoid mentioning the the term scalar function.

[andwar]

llvm/docs/LangRef.rst

1889

When present, the optional token `(<vector_redirection>) informs the compiler that a custom name is provided instead of the standard one _ZGV<isa><mask><vlen><parameters>_<scalar_name>`

This sounds a bit odd:

• a custom name is provided instead of the standard one -> a custom name is provided in addition to the standard one? As far as the attribute is concerned, the custom name is something that's additional/optional, right. AFAIK, it's not there _instead_ of the standard name (but indeed, later will be used _instead_ of the standard name). Maybe worth claryfying?
• the standard one _ZGV<isa><mask><vlen><parameters>_<scalar_name> -> here you repeat the definition of the standard name, which was already specified in the previous sentence. Maybe just remove `_ZGV<isa><mask><vlen><parameters>_<scalar_name>`?

[fpetrogalli]

Update last round of review from @andwar.

[fpetrogalli]

Adding some text here to convince phabricator to mark a comment as done. :)

[jdoerfert]

Sorry for my absence on this.

llvm/docs/LangRef.rst

1871

I'd word it something like this:

In addition to function attributes the following call site only attributes are supported:

1878

1. Only CallInst or call site?
2. Do we have a mangling doc entry that we could link to?
3. Do the { and ( belong to the token stream? Maybe [ is better to indicate optional things?

[fpetrogalli]

Address review from @jdoerfert.

llvm/docs/LangRef.rst

1878

Only CallInst or call site?

I am not sure what the distinction is. For now we are in need of it only for CallInst. What would be a call site?

Do we have a mangling doc entry that we could link to?

The aarch64 and x86 ones are linked below. For LLVM, this piece of docs is to be considered the mangling doc.

Do the { and ( belong to the token stream? Maybe [ is better to indicate optional things?

I'll use [ for optional instead of {.

[jdoerfert]

llvm/docs/LangRef.rst

1878

Call site is a term (and for now a class llvm::CallSite) that describes CallInst, InvokeInst, CallBr (I think), and later potentially other call like instructions. If these attributes can be placed on an InvokeInst which I was expecting, we need to say call site or also mention InvokeInst. If they cannot, we should mention that explicitly I think.

Also, if you refer to CallInst we need the ticks and a link to the definition in the lang ref.

[fpetrogalli]

1. Make sure that the attribute can be specified only for CallInst.
2. Use [ and ] instead of { and } for optional tokens in the syntax of the attribute.

[fpetrogalli]

llvm/docs/LangRef.rst

1878

My understanding of the callbr and invoke instructions is that they cannot be vectorized, as they both have the following sentence in the description: [...] [the instruction] causes control to transfer to a specified function [...].

I don't think this is compatible with the concept of concurrent execution of the functions on the lanes of the vector that is implied by a vector function.

For this reason, I have modified the text to make sure it applies only to CallInst.

[jdoerfert]

I'm fine with this but I want to make sure ppl see this before it goes in.

[fpetrogalli]

Fix a typo in the name of the attribute (remove trailing s).

[fpetrogalli]

In D72798#1834636, @jdoerfert wrote:

I'm fine with this but I want to make sure ppl see this before it goes in.

Sure! Thank you for looking into this. Francesco

[simoll]

Nit: You might want to add that list order does not imply preference (it's logically a set) and that the compiler is free to pick any listed vector function of its choosing.
Question: how does this interact with vector function metadata attached to a function declaration (if at all), eg does the call site list override that of the function?
Otw, LGTM.

[fpetrogalli]

Specify that the order of the list in the attribute is not important.

[fpetrogalli]

In D72798#1838110, @simoll wrote:

Nit: You might want to add that list order does not imply preference (it's logically a set) and that the compiler is free to pick any listed vector function of its choosing.

Done

Question: how does this interact with vector function metadata attached to a function declaration (if at all), eg does the call site list override that of the function?

Hum - I haven't really thought about that. I think that more than "override", the local list should extend the one attached to the function. At the end, what we need to prevent is that the call sites don't mix up their respective list (as they may come from different compilation unit being merged).

My preference would be to forbid the attribute at all for functions, and leave it only for callinst, as vectorization is instantiated only when a call is seen. Any concerns on this approach?

Otw, LGTM.

Thanks for your review, Simon!

[andwar]

LGTM

[jdoerfert]

LGTM

[simoll]

Thx!

llvm/docs/LangRef.rst

``nocf_check``
     is target independent and currently appertains to a function or function
     pointer.
 ``shadowcallstack``
     This attribute indicates that the ShadowCallStack checks are enabled for
     the function. The instrumentation checks that the return address for the
     function has not changed between the function prolog and eiplog. It is
     currently x86_64-specific.
 
+Call Site Attributes
+----------------------
+
+In addition to function attributes the following call site only
+attributes are supported:
+
+``vector-function-abi-variant``
+    This attribute can be attached to a :ref:`call <i_call>` to list
+    the vector functions associated to the function. Notice that the
+    attribute cannot be attached to a :ref:`invoke <i_invoke>` or a
+    :ref:`callbr <i_callbr>` instruction. The attribute consists of a
+    comma separated list of mangled names. The order of the list does
+    not imply preference (it is logically a set). The compiler is free
+    to pick any listed vector function of its choosing.
+
+    The syntax for the mangled names is as follows:
+
+        _ZGV<isa><mask><vlen><parameters>_<scalar_name>[(<vector_redirection>)]
+
+    When present, the attribute informs the compiler that the function
+    ``<scalar_name>`` has a corresponding vector variant that can be
+    used to perform the concurrent invocation of ``<scalar_name>`` on
+    vectors. The shape of the vector function is described by the
+    tokens between the prefix ``_ZGV`` and the ``<scalar_name>``
+    token. The standard name of the vector function is
+    ``_ZGV<isa><mask><vlen><parameters>_<scalar_name>``. When present,
+    the optional token ``(<vector_redirection>)`` informs the compiler
+    that a custom name is provided in addition to the standard one
+    (custom names can be provided for example via the use of ``declare
+    variant`` in OpenMP 5.0). The declaration of the variant must be
+    present in the IR Module. The signature of the vector variant is
+    determined by the rules of the Vector Function ABI (VFABI)
+    specifications of the target. For Arm and X86, the VFABI can be
+    found at https://github.com/ARM-software/software-standards and
+    https://software.intel.com/en-us/articles/vector-simd-function-abi,
+    respectively.
+
+    For X86 and Arm targets, the values of the tokens in the standard
+    name are those that are defined in the VFABI. LLVM has an internal
+    ``<isa>`` token that can be used to create scalar-to-vector
+    mappings for functions that are not directly associated to any of
+    the target ISAs (for example, some of the mappings stored in the
+    TargetLibraryInfo). Valid values for the ``<isa>`` token are:
+
+    <isa>:= b | c | d | e  -> X86 SSE, AVX, AVX2, AVX512
+          | n | s          -> Armv8 Advanced SIMD, SVE
+          | __LLVM__       -> Internal LLVM Vector ISA
+
+    For all targets currently supported (x86, Arm and Internal LLVM),
+    the remaining tokens can have the following values:
+
+    <mask>:= M | N         -> mask | no mask
+
+    <vlen>:= number        -> number of lanes
+           | x             -> VLA (Vector Length Agnostic)
+
+    <parameters>:= v              -> vector
+                 | l | l <number> -> linear
+                 | R | R <number> -> linear with ref modifier
+                 | L | L <number> -> linear with val modifier
+                 | U | U <number> -> linear with uval modifier
+                 | ls <pos>       -> runtime linear
+                 | Rs <pos>       -> runtime linear with ref modifier
+                 | Ls <pos>       -> runtime linear with val modifier
+                 | Us <pos>       -> runtime linear with uval modifier
+                 | u              -> uniform
+
+    <scalar_name>:= name of the scalar function
+
+    <vector_redirection>:= optional, custom name of the vector function
+
 .. _glattrs:
 
 Global Attributes
 -----------------
 
 Attributes may be set to communicate additional information about a global variable.
 Unlike :ref:`function attributes <fnattrs>`, attributes on a global variable
 are grouped into a single :ref:`attribute group <attrgrp>`.