[Docs] clarify that the x.with.overflow intrinsics have defined behavior for all inputs

[regehr]

Summary

I mirrored the text in the clang language extensions document as closely as possible.

[majnemer]

LGTM

[sanjoy]

docs/LangRef.rst

10864 ↗

(On Diff #56858)

I'm not sure that we need to special case "mathematically correct". Why not say something like: "the first result is the operation modulo 2^bitwidth, and the second result is 1 iff the operation overflowed."

A more pertinent bit of information here is what is defined to be an overflow: an operation overflows if for any N, "ext(A op B) to iN != (ext(A) to iN) op (ext(B) to iN)" where ext is sext for sign overflow and zext for unsigned overflow.

[regehr]

docs/LangRef.rst

10864 ↗

(On Diff #56858)

Sure. I had been aiming for wording congruent with the clang manual, if we give up on that it's possible to say things a bit better.

[regehr]

revise wording as suggested by Sanjoy

[regehr]

fix misspelling

[sanjoy]

lgtm, with an optional-to-fix nit

docs/LangRef.rst

10863 ↗

(On Diff #57004)

What I had in mind was:

Each of these intrinsics returns a two-element struct. The first
element of this struct contains the result of the corresponding
arithmetic operation modulo 2\ :sup:`n`\ , where n is the
bit width of the result.

I.e. I don't see a need to special case the overflow or no-overflow
situation -- the operation is always modulo 2^n

But I'm okay with what you have.

llvm/trunk/docs/LangRef.rst

 ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
 ``llvm.cttz(2) = 1``.
 
 .. _int_overflow:
 
 Arithmetic with Overflow Intrinsics
 -----------------------------------
 
-LLVM provides intrinsics for some arithmetic with overflow operations.
+LLVM provides intrinsics for fast arithmetic overflow checking.
+
+Each of these intrinsics returns a two-element struct. The first
+element of this struct contains the result of the corresponding
+arithmetic operation modulo 2\ :sup:`n`\ , where n is the bit width of
+the result. Therefore, for example, the first element of the struct
+returned by ``llvm.sadd.with.overflow.i32`` is always the same as the
+result of a 32-bit ``add`` instruction with the same operands, where
+the ``add`` is *not* modified by an ``nsw`` or ``nuw`` flag.
+
+The second element of the result is an ``i1`` that is 1 if the
+arithmetic operation overflowed and 0 otherwise. An operation
+overflows if, for any values of its operands ``A`` and ``B`` and for
+any ``N`` larger than the operands' width, ``ext(A op B) to iN`` is
+not equal to ``(ext(A) to iN) op (ext(B) to iN)`` where ``ext`` is
+``sext`` for signed overflow and ``zext`` for unsigned overflow, and
+``op`` is the underlying arithmetic operation.
+
+The behavior of these intrinsics is well-defined for all argument
+values.
 
 '``llvm.sadd.with.overflow.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``