[LangRef] Element-wise Integral Reduction Intrinsics

[lebedev.ri]

Summary

This is the proposed wording for the [RFC] Integer Intrinsics for abs, in unsigned/signed min/max.

Link to RFC:
https://lists.llvm.org/pipermail/llvm-dev/2020-June/142257.html

Proposed alive2 implementation: https://github.com/AliveToolkit/alive2/pull/353

[nikic]

I find the naming of these intrinsics somewhat unintuitive. My first association with llvm.reduce.smax is that this is the non-experimental version of llvm.experimental.vector.reduce.smax, because reduction (to me) carries a strong vector reduction connotation. I can still see how these might be "reductions" for min/max (in which case I would expect the intrinsics to be variadic though), but not seeing the analogy at all for abs().

I would suggest to instead call these just llvm.smax, llvm.abs etc, which seems more in line with existing integer intrinsic names.

[xbolva00]

yeah, “reduce” should be dropped

[xbolva00]

llvm/docs/LangRef.rst

15365

What abouts nabs?

We pattern match it currently too.

[lebedev.ri]

Per popular demand, drop .reduce. from intrinsic names.

[spatel]

llvm/docs/LangRef.rst

15239–15245

We should avoid "reduction" vocabulary with any of these operations since that term is already used for vector ops.

abs() belongs in the "Standard C Library Intrinsics" section that starts around line 12099.
If we relax that title to "Standard C/C++ Library Intrinsics", then min/max can live there too?

15265–15266

Return the larger of a and b comparing the values as signed integers.
Vector intrinsics operate on a per-element basis. The larger element of a and b at a given index is returned for that index.

15273

I'd remove the "return type matches..." line above and work that clause in here:
"The argument types must match each other, and the return type must match the argument type."

15294

Return the smaller of a and b comparing the values as signed integers.
Vector intrinsics operate on a per-element basis. The smaller element of a and b at a given index is returned for that index.

15323–15325

Return the larger of a and b comparing the values as unsigned integers.
Vector intrinsics operate on a per-element basis. The larger element of a and b at a given index is returned for that index.

15352–15353

Return the smaller of a and b comparing the values as unsigned integers.
Vector intrinsics operate on a per-element basis. The smaller element of a and b at a given index is returned for that index.

15375–15376

Do we need to include the poison option?

The SDAG node only has:

/// Note: A value of INT_MIN will return INT_MIN, no saturation or overflow
/// is performed.

[nikic]

llvm/docs/LangRef.rst

15365

We do, but it's probably much less common than abs() and doesn't have any backend support. I think we can get away with representing it as 0 - abs(x) (or just the same way we do now).

15375–15376

The poison option is the equivalent of the sub nsw flag that was used previously. It doesn't matter for lowering, but it is used for analysis sometimes, in particular we can only assume that the llvm.abs() result is actually positive if the poison flag is set.

15393

Missing space before "if".

[lebedev.ri]

@spatel @nikic @xbolva00 thank you for taking a look!
Addressing review notes.

[lebedev.ri]

llvm/docs/LangRef.rst

15365

We do indeed have SPF_NABS, but i strongly believe that is again because we have to, not because it's useful.
Given, -(a < 0 ? -a : a), currently, we can't possibly preserve that pattern from sinking negation into it.
And as soon as it's sunk, it is no longer an ABS, and we've lost track of it.
If we have an intrinsic, that will no longer be an issue.
I currently see no need for nabs intinsic.

15375–15376

The poison option is the equivalent of the sub nsw flag that was used previously.

Precisely, yes. This intrinsic will be pretty powerless without that flag.

[simoll]

llvm/docs/LangRef.rst

15375–15376

Couldn't we add integer overflow flags to CallInsts the same way we have fast math flags? That should make this extra argument redundant.
Also, this would allow us to have nsw, nuw on VP intrinsics (https://llvm.org/docs/LangRef.html#id2355) and other integer intrinsics.

[spatel]

LGTM - see inline for grammar nits. Please remove "Reduction" from the title of this review too.

But we should wait at least a week before pushing in case there is more feedback here or on llvm-dev.

llvm/docs/LangRef.rst

12115

Remove comma after "width".

12132

Remove comma after "type".

12136

typo: a a

12143–12144

First line is a bit awkward to me. How about:
"Returns the magnitude (always positive) of the argument or each element of a vector argument."

12155

Remove comma after "width".

12172

Remove comma after "type".

12184

Remove comma after "width".

12201

Remove comma after "type".

12213

Remove comma after "width".

12230

Remove comma after "type".

12242

Remove comma after "width".

12259

Remove comma after "type".

[lebedev.ri]

@spatel thank you for taking a look!
Addressing various typo nits.

llvm/docs/LangRef.rst

15375–15376

Possibly, but that seems like a more general rework that doesn't have to block this.

[nikic]

LGTM as well.

llvm/docs/LangRef.rst

12125

nit: "returns *the* absolute value"

12143–12144

The (always positive) note seems a bit odd here, given the INT_MIN behavior.

[nhaehnle]

This LGTM, but it shouldn't be committed without an actual implementation.

[lebedev.ri]

In D81829#2100445, @nhaehnle wrote:

This LGTM,

but it shouldn't be committed without an actual implementation.

I'm going to assume that by implementation only the actual addition of the intrinsics is meant,
not any/all of the piping/teaching about the new intrinsics.

[nikic]

@lebedev.ri As we already have the corresponding SDAG nodes, I would expect the initial implementation to just add the intrinsics, the SDAG builder code, and a cursory X86 test that the intrinsics get lowered.

[nikic]

As there hasn't been any further feedback on llvm-dev, time to move forward with this?

[xbolva00]

+1, but initial implementation should be done first, as noted here:

In D81829#2100445, @nhaehnle wrote:

This LGTM, but it shouldn't be committed without an actual implementation.

llvm/docs/LangRef.rst

 to DCE), where otherwise we cannot know how large the arguments are.
 
 It is undefined behavior if this is called with a token from an
 '``llvm.call.preallocated.setup``' if another
 '``llvm.call.preallocated.setup``' has already been called or if the
 preallocated call corresponding to the '``llvm.call.preallocated.setup``'
 has already been called.
 
-Standard C Library Intrinsics
------------------------------
+Standard C/C++ Library Intrinsics
+---------------------------------
 
-LLVM provides intrinsics for a few important standard C library
+LLVM provides intrinsics for a few important standard C/C++ library
 functions. These intrinsics allow source-language front-ends to pass
 information about the alignment of the pointer arguments to the code
 generator, providing opportunity for more efficient code generation.
 
+
+'``llvm.abs.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.abs`` on any
+integer bit width, or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.abs.i32(i32 <src>, i1 <is_int_min_poison>)
+      declare <4 x i32> @llvm.abs.v4i32(<4 x i32> <src>, i1 <is_int_min_poison>)
+
+Overview:
+"""""""""
+
+The '``llvm.abs``' family of intrinsic functions returns absolute value
+of an argument.
+
+Arguments:
+""""""""""
+
+The first argument is the value for which the absolute value is to be returned.
+This argument may be of any integer type, or a vector with integer element type.
+The return type must match the first argument type.
+
+The second argument must be a constant and is a flag to indicate whether the
+result value of the '``llvm.abs``' intrinsic is a a
+:ref:`poison value <poisonvalues>` if the argument is statically or dynamically
+an ``INT_MIN`` value.
+
+Semantics:
+""""""""""
+
+The '``llvm.abs``' intrinsic negates the argument, or each element of
+the argument if it is negative. If the argument is ``INT_MIN``, then the result
+is also ``INT_MIN`` if ``is_int_min_poison == 0`` and ``poison`` otherwise.
+
+
+'``llvm.smax.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.smax`` on any
+integer bit width, or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.smax.i32(i32 %a, i32 %b)
+      declare <4 x i32> @llvm.smax.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+Overview:
+"""""""""
+
+Return the larger of ``%a`` and ``%b`` comparing the values as signed integers.
+Vector intrinsics operate on a per-element basis. The larger element of ``%a``
+and ``%b`` at a given index is returned for that index.
+
+Arguments:
+""""""""""
+
+The arguments (``%a`` and ``%b``) may be of any integer type, or a vector with
+integer element type. The argument types must match each other, and the return
+type must match the argument type.
+
+
+'``llvm.smin.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.smin`` on any
+integer bit width, or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.smin.i32(i32 %a, i32 %b)
+      declare <4 x i32> @llvm.smin.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+Overview:
+"""""""""
+
+Return the smaller of ``%a`` and ``%b`` comparing the values as signed integers.
+Vector intrinsics operate on a per-element basis. The smaller element of ``%a``
+and ``%b`` at a given index is returned for that index.
+
+Arguments:
+""""""""""
+
+The arguments (``%a`` and ``%b``) may be of any integer type, or a vector with
+integer element type. The argument types must match each other, and the return
+type must match the argument type.
+
+
+'``llvm.umax.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.umax`` on any
+integer bit width, or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.umax.i32(i32 %a, i32 %b)
+      declare <4 x i32> @llvm.umax.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+Overview:
+"""""""""
+
+Return the larger of ``%a`` and ``%b`` comparing the values as unsigned
+integers. Vector intrinsics operate on a per-element basis. The larger element
+of ``%a`` and ``%b`` at a given index is returned for that index.
+
+Arguments:
+""""""""""
+
+The arguments (``%a`` and ``%b``) may be of any integer type, or a vector with
+integer element type. The argument types must match each other, and the return
+type must match the argument type.
+
+
+'``llvm.umin.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.umin`` on any
+integer bit width, or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.umin.i32(i32 %a, i32 %b)
+      declare <4 x i32> @llvm.umin.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+Overview:
+"""""""""
+
+Return the smaller of ``%a`` and ``%b`` comparing the values as unsigned
+integers. Vector intrinsics operate on a per-element basis. The smaller element
+of ``%a`` and ``%b`` at a given index is returned for that index.
+
+Arguments:
+""""""""""
+
+The arguments (``%a`` and ``%b``) may be of any integer type, or a vector with
+integer element type. The argument types must match each other, and the return
+type must match the argument type.
+
+
 .. _int_memcpy:
 
 '``llvm.memcpy``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 

 """"""""""
 
 The '``llvm.loop.decrement.*``' intrinsics do a ``SUB`` of the loop iteration
 counter with the given loop decrement value, and return false if the loop
 should exit, this ``SUB`` is not allowed to wrap. The result is a condition
 that is used by the conditional branch controlling the loop.
 
 
 Experimental Vector Reduction Intrinsics
 ----------------------------------------
 
 Horizontal reductions of vectors can be expressed using the following
 intrinsics. Each one takes a vector operand as an input and applies its
 respective operation across all elements of the vector, returning a single
 scalar result of the same element type.
 
 
 '``llvm.experimental.vector.reduce.add.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare i32 @llvm.experimental.vector.reduce.add.v4i32(<4 x i32> %a)
       declare i64 @llvm.experimental.vector.reduce.add.v2i64(<2 x i64> %a)
 
 Overview:
 """""""""
 
 The '``llvm.experimental.vector.reduce.add.*``' intrinsics do an integer ``ADD``
 reduction of a vector, returning the result as a scalar. The return type matches
 the element-type of the vector input.
 
 Arguments:
 """"""""""
 The argument to this intrinsic must be a vector of integer values.
 
 '``llvm.experimental.vector.reduce.v2.fadd.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %a)
       declare double @llvm.experimental.vector.reduce.v2.fadd.f64.v2f64(double %start_value, <2 x double> %a)
 
 Overview:
 """""""""
 
 The '``llvm.experimental.vector.reduce.v2.fadd.*``' intrinsics do a floating-point
 ``ADD`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
 
 If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
 reduction will not preserve the associativity of an equivalent scalarized
 counterpart. Otherwise the reduction will be *ordered*, thus implying that
 the operation respects the associativity of a scalarized reduction.
 
 
 Arguments:
 """"""""""
 The first argument to this intrinsic is a scalar start value for the reduction.
 The type of the start value matches the element-type of the vector input.
 The second argument must be a vector of floating-point values.
 
 Examples:
 """""""""
 

 ::
 
       declare i32 @llvm.experimental.vector.reduce.mul.v4i32(<4 x i32> %a)
       declare i64 @llvm.experimental.vector.reduce.mul.v2i64(<2 x i64> %a)
 
 Overview:
 """""""""
 
 The '``llvm.experimental.vector.reduce.mul.*``' intrinsics do an integer ``MUL``
 reduction of a vector, returning the result as a scalar. The return type matches
 the element-type of the vector input.
 
 Arguments:
 """"""""""
 The argument to this intrinsic must be a vector of integer values.
 
 '``llvm.experimental.vector.reduce.v2.fmul.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

 
 The '``llvm.experimental.vector.reduce.v2.fmul.*``' intrinsics do a floating-point
 ``MUL`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
 
 If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
 reduction will not preserve the associativity of an equivalent scalarized
 counterpart. Otherwise the reduction will be *ordered*, thus implying that
 the operation respects the associativity of a scalarized reduction.
 
 
 Arguments:
 """"""""""
 The first argument to this intrinsic is a scalar start value for the reduction.
 The type of the start value matches the element-type of the vector input.
 The second argument must be a vector of floating-point values.
 
 Examples:
 """""""""
 
 ::
 
       %unord = call reassoc float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float 1.0, <4 x float> %input) ; unordered reduction
       %ord = call float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
 
 '``llvm.experimental.vector.reduce.and.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare i32 @llvm.experimental.vector.reduce.and.v4i32(<4 x i32> %a)
 
 Overview:
 """""""""
 
 The '``llvm.experimental.vector.reduce.and.*``' intrinsics do a bitwise ``AND``
 reduction of a vector, returning the result as a scalar. The return type matches
 the element-type of the vector input.
 
 Arguments:
 """"""""""
 The argument to this intrinsic must be a vector of integer values.
 
 '``llvm.experimental.vector.reduce.or.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare i32 @llvm.experimental.vector.reduce.or.v4i32(<4 x i32> %a)
 
 Overview:
 """""""""