[LangRef] Clarify codegen expectations for intrinsics with fp/integer-only overloads

[aemerson]

Summary

[LangRef] Clarify codegen expectations for intrinsics with fp/integer-only overloads.

This change is a result of discussions on list: "GlobalISel: Ambiguous intrinsic semantics problem"

[arsenm]

llvm/docs/LangRef.rst

10397–10401

I feel like this could be rephrased more generally as something along the lines of there shouldn't be a major semantic change in the operation based on the overloaded type. The integer/FP distinction is one particular example. I'm trying to come up with a definition for "major semantic change" means though.

I have a sort of counterexample though in the AMDGPU buffer intrinsics. If the return type is a struct, it changes the instruction slightly, but not in a problematic/ambiguous way like the FP/integer type.

[hfinkel]

I don't understand what this is supposed to mean to who the audience of this statement is?

[aemerson]

In D59657#1438384, @hfinkel wrote:

I don't understand what this is supposed to mean to who the audience of this statement is?

Clearly the wording isn't good enough then, but here's the motivating discussion: http://lists.llvm.org/pipermail/llvm-dev/2019-March/130903.html

The tl;dr is that we agreed that intrinsics which need different codegen based *only* on whether a intrinsic operand type is integer or fp is not supported.

call @llvm.foo(<4 x i32> %p) and call @llvm.foo(<4 x float> %p) should not be supported by the code generator, as the only thing that distinguishes them is the fp/integer type. With llvm::Instruction we have separate opcodes for fp/int operations, e.g. fadd vs add.

The audience of this are people who are defining new target intrinsics.

llvm/docs/LangRef.rst

10397–10401

Perhaps, but I think we should try to be specific.

[hfinkel]

The audience of this are people who are defining new target intrinsics.

This should be made explicitly clear. Thanks.

[aemerson]

Re-wording and making it more explicit who this is for.

[aemerson]

Ping.

[arsenm]

LGTM

llvm/docs/LangRef.rst

 ``llvm.ctpop`` function can take an integer of any width and returns an
 integer of exactly the same integer width. This leads to a family of
 functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and
 ``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
 overloaded, and only one type suffix is required. Because the argument's
 type is matched against the return type, it does not require its own
 name suffix.
 
+For target developers who are defining intrinsics for back-end code
+generation, any intrinsic overloads based solely the distinction between
+integer or floating point types should not be relied upon for correct
+code generation. In such cases, the recommended approach for target
+maintainers when defining intrinsics is to create separate integer and
+FP intrinsics rather than rely on overloading. For example, if different
+codegen is required for ``llvm.target.foo(<4 x i32>)`` and
+``llvm.target.foo(<4 x float>)`` then these should be split into
+different intrinsics.
+
 To learn how to add an intrinsic function, please see the `Extending
 LLVM Guide <ExtendingLLVM.html>`_.
 
 .. _int_varargs:
 
 Variable Argument Handling Intrinsics
 -------------------------------------