s390x: document the different rounding flavors

[folkertdev]

If I remember right, these all function equivalent on the target (because the rounding mode can't be changed). At least on CE they generate the same instructions.

cc @uweigand

[rustbot]

r? @Amanieu

rustbot has assigned @Amanieu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[uweigand]

This doesn't look right. We certainly can change the default rounding mode on s390x just like on most other targets; the rint and nearbyint functions respect the current rounding mode. It is true that clang does make a default assumption (on all targets) that the default rounding mode is set to roundeven; but that assumption can be changed by using the -frounding-math command line option. (Also, even this assumption only affects potential compile-time optimizations made by LLVM; the emitted code will in any case use different instructions that will / will not respect current rounding mode at the ISA level.)

In addition, rint and nearbyint differ in whether or not they will generate the inexact floating-point exception. Again, by default clang makes the assumption that (any) floating-point exception will have no effect and can be ignored; but that assumption can be changed using the -ffp-exception-behavior= option.

Here's a full table of the various nearest-integer functions in IBM Z vector intrinsics, C23 math.h, LLVM IR, the equivalent ISO/IEC operation, and the corresponding set of vfidb instruction parameters:

Z vector intrinsic      C23 math.h  LLVM IR         ISO/IEC 60559 operation        inexact  vfidb parameters
vec_rint                rint        llvm.rint       roundToIntegralExact           yes      0, 0        
vec_roundc              nearbyint   llvm.nearbyint  n/a                            no       4, 0       
vec_floor / vec_roundm  floor       llvm.floor      roundToIntegralTowardNegative  no       4, 7       
vec_ceil / vec_roundp   ceil        llvm.ceil       roundToIntegralTowardPositive  no       4, 6       
vec_trunc / vec_roundz  trunc       llvm.trunc      roundToIntegralTowardZero      no       4, 5       
vec_round               roundeven   llvm.roundeven  roundToIntegralTiesToEven      no       4, 4       
n/a                     round       llvm.round      roundToIntegralTiesAway        no       4, 1       

[folkertdev]

Ah, right, we can't actually test for the vfidb parameters, so CI is OK with such changes.

Also, simd_round_ties_even is implemented as llvm.rint: https://github.com/sayantn/rust/blob/2ffa1dd392c1fe9c23a2f11f7b7a293a744c05ce/compiler/rustc_codegen_gcc/src/intrinsic/simd.rs#L782

I guess the name is confusing no matter what, but simd_round_ties_even not using llvm.roundeven is unexpected.

Anyway, I copied that (very helpful!) table as a comment, so hopefully there will not be any confusion in the future.

Also the rust llvm 21 update is close, so then we can resolve that TODO.