openpower/sv/int_fp_mv/cvt_fp_to_int_overview.mdwn

   1 ## Floating-point to Integer Conversion Overview
   2
   3 <div id="fpr-to-gpr-conversion-mode"></div>
   4
   5 IEEE 754 doesn't specify what results are obtained when converting a NaN
   6 or out-of-range floating-point value to integer, so different programming
   7 languages and ISAs have made different choices.  The different conversion
   8 modes supported by the `cffpr` instruction are as follows:
   9
  10 * P-Type: <div id="fpr-to-gpr-conversion-p-type"></div>
  11     Used by most other PowerISA instructions,
  12     as well as commonly used floating-point to integer conversions on x86.
  13
  14 * S-Type: <div id="fpr-to-gpr-conversion-s-type"></div>
  15     Used for WebAssembly's `trunc_sat_u`[^trunc_sat_u] and
  16     `trunc_sat_s`[^trunc_sat_s] instructions, as well as several notable
  17     programming languages:
  18
  19     * Java's conversion from `float`/`double` to `long`/`int`[^java_fp_to_int]
  20     * Rust's `as` operator[^rust_as_operator]
  21     * LLVM's `llvm.fptosi.sat`[^llvm_fptosi_sat] and
  22         `llvm.fptoui.sat`[^llvm_fptoui_sat] intrinsics
  23     * SPIR-V's OpenCL dialect's `OpConvertFToU`[^SPIRV_OpConvertFToU] and
  24         `OpConvertFToS`[^SPIRV_OpConvertFToS] instructions when decorated with
  25         the `SaturatedConversion`[^SPIRV_SaturatedConversion] decorator.
  26
  27 * E-Type: <div id="fpr-to-gpr-conversion-e-type"></div>
  28     Used for ECMAScript's `ToInt32` abstract operation[^ECMAScript_ToInt32].
  29     Also implemented in ARMv8.3A as the `FJCVTZS` instruction[^ARM_FJCVTZS].
  30
  31 [^trunc_sat_u]: WASM's `trunc_sat_u`:
  32     <https://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-u>
  33 [^trunc_sat_s]: WASM's `trunc_sat_s`:
  34     <https://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-s>
  35 [^java_fp_to_int]: Java `float`/`double` to `long`/`int` conversion:
  36     <https://docs.oracle.com/javase/specs/jls/se16/html/jls-5.html#jls-5.1.3>
  37 [^rust_as_operator]: Rust's `as` operator:
  38     <https://doc.rust-lang.org/1.70.0/reference/expressions/operator-expr.html#numeric-cast>
  39 [^llvm_fptosi_sat]: LLVM's `llvm.fptosi.sat` intrinsic:
  40     <https://llvm.org/docs/LangRef.html#llvm-fptosi-sat-intrinsic>
  41 [^llvm_fptoui_sat]: LLVM's `llvm.fptoui.sat` intrinsic:
  42     <https://llvm.org/docs/LangRef.html#llvm-fptoui-sat-intrinsic>
  43 [^SPIRV_OpConvertFToU]: SPIR-V's `OpConvertFToU` instruction:
  44     <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToU>
  45 [^SPIRV_OpConvertFToS]: SPIR-V's `OpConvertFToS` instruction:
  46     <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToS>
  47 [^SPIRV_SaturatedConversion]: SPIR-V's `SaturatedConversion` decorator:<br/>
  48     <https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_decoration_a_decoration>
  49 [^ECMAScript_ToInt32]: ECMAScript's `ToInt32` abstract operation:
  50     <https://262.ecma-international.org/14.0/#sec-toint32>
  51 [^ARM_FJCVTZS]: ARM's `FJCVTZS` instruction:
  52     <https://developer.arm.com/documentation/dui0801/g/hko1477562192868>
  53
  54 ### Floating-point to Integer Conversion Semantics Summary
  55
  56 Let `rounded` be the result of `bfp_ROUND_TO_INTEGER(rmode, input)`.
  57 Let `w` be the number of bits in the result's type.
  58 The result of Floating-point to Integer conversion is as follows:
  59
  60 ```
  61 +--------+------------+-----------------------------------------------------------------------+
  62 | Type   | Result's   | Category of rounded                                                   |
  63 |        | Signedness +-----------+-----------+-----------+-----------+-----------+-----------+
  64 |        |            | NaN       | +Infinity | -Infinity | > Maximum | < Minimum | Otherwise |
  65 |        |            |           |           |           | Possible  | Possible  |           |
  66 |        |            |           |           |           | Result    | Result    |           |
  67 +--------+------------+-----------+-----------+-----------+-----------+-----------+-----------+
  68 | P-Type | Unsigned   | 0         | 2^w - 1   | 0         | 2^w - 1   | 0         | rounded   |
  69 |        +------------+-----------+-----------+-----------+-----------+-----------+-----------+
  70 |        | Signed     | -2^(w-1)  | 2^(w-1)-1 | -2^(w-1)  | 2^(w-1)-1 | -2^(w-1)  | rounded   |
  71 +--------+------------+-----------+-----------+-----------+-----------+-----------+-----------+
  72 | S-Type | Unsigned   | 0         | 2^w - 1   | 0         | 2^w - 1   | 0         | rounded   |
  73 |        +------------+-----------+-----------+-----------+-----------+-----------+-----------+
  74 |        | Signed     | 0         | 2^(w-1)-1 | -2^(w-1)  | 2^(w-1)-1 | -2^(w-1)  | rounded   |
  75 +--------+------------+-----------+-----------+-----------+-----------+-----------+-----------+
  76 | E-Type | Either     | 0                                 | rounded & (2^w - 1)               |
  77 +--------+------------+-----------------------------------+-----------------------------------+
  78 ```