[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

15528

What abouts nabs?

We pattern match it currently too.

[lebedev.ri]

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

[spatel]

llvm/docs/LangRef.rst

15402–15408

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?

15428–15429

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.

15436

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."

15457

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.

15486–15488

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.

15515–15516

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.

15538–15539

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

15528

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).

15538–15539

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.

15556

Missing space before "if".

[lebedev.ri]

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

[lebedev.ri]

llvm/docs/LangRef.rst

15528

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.

15538–15539

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

15538–15539

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

12277

Remove comma after "width".

12294

Remove comma after "type".

12298

typo: a a

12305–12306

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."

12317

Remove comma after "width".

12334

Remove comma after "type".

12346

Remove comma after "width".

12363

Remove comma after "type".

12375

Remove comma after "width".

12392

Remove comma after "type".

12404

Remove comma after "width".

12421

Remove comma after "type".

[lebedev.ri]

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

llvm/docs/LangRef.rst

15538–15539

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

[nikic]

LGTM as well.

llvm/docs/LangRef.rst

12287

nit: "returns *the* absolute value"

12305–12306

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

conta:
         ret void
     contb:
         %s = catchswitch within none [label %catch] unwind to caller
     catch:
         %p = catchpad within %s []
         call void @llvm.call.preallocated.teardown(token %cs)
         ret void
 
-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 the 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
+:ref:`poison value <poisonvalues>` if the argument is statically or dynamically
+an ``INT_MIN`` value.
+
+Semantics:
+""""""""""
+
+The '``llvm.abs``' intrinsic returns the magnitude (always positive) of the
+argument or each element of a vector argument.". 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. That is, the
 reduction begins with the start value and performs an fadd operation with consecutively
 increasing vector element indices. See the following pseudocode:
 
 ::
 
     float ordered_fadd(start_value, input_vector)
       result = start_value
       for i = 0 to length(input_vector)
         result = result + input_vector[i]
       return result
 
::
       %unord = call reassoc float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float 0.0, <4 x float> %input) ; unordered reduction
       %ord = call float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
 
 
 '``llvm.experimental.vector.reduce.mul.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       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``

 Syntax:
 """""""
 
 ::
 
       declare float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %a)
       declare double @llvm.experimental.vector.reduce.v2.fmul.f64.v2f64(double %start_value, <2 x double> %a)
 
 Overview:
 """""""""
 
 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. That is, the
 reduction begins with the start value and performs an fmul operation with consecutively
 increasing vector element indices. See the following pseudocode:
 
 ::
 
     float ordered_fmul(start_value, input_vector)
       result = start_value
       for i = 0 to length(input_vector)
         result = result * input_vector[i]
       return result
 
 
 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:
 """""""""