openpower/sv/int_fp_mv.mdwn

   1 [[!tag standards]]
   2
   3 Note on considered alternative naming schemes: we decided to switch to using the reduced mnemonic naming scheme (over some people's objections) since it would be 5 instructions instead of dozens, though we did consider trying to match PowerISA's existing naming scheme for the instructions rather than only for the instruction aliases. <https://bugs.libre-soc.org/show_bug.cgi?id=1015#c7>
   4
   5 # FPR-to-GPR and GPR-to-FPR
   6
   7 TODO special constants instruction (e, tau/N, ln 2, sqrt 2, etc.) -- exclude any constants available through fmvis
   8
   9 **Draft Status** under development, for submission as an RFC
  10
  11 Links:
  12
  13 * <https://bugs.libre-soc.org/show_bug.cgi?id=650>
  14 * <https://bugs.libre-soc.org/show_bug.cgi?id=230#c71>
  15 * <https://bugs.libre-soc.org/show_bug.cgi?id=230#c74>
  16 * <https://bugs.libre-soc.org/show_bug.cgi?id=230#c76>
  17 * <https://bugs.libre-soc.org/show_bug.cgi?id=887> fmvis
  18 * <https://bugs.libre-soc.org/show_bug.cgi?id=1015> int-fp RFC
  19 * [[int_fp_mv/appendix]]
  20 * [[sv/rfc/ls002]] - `fmvis` and `fishmv` External RFC Formal Submission
  21 * [[sv/rfc/ls006]] - int-fp-mv External RFC Formal Submission
  22
  23 Trademarks:
  24
  25 * Rust is a Trademark of the Rust Foundation
  26 * Java and Javascript are Trademarks of Oracle
  27 * LLVM is a Trademark of the LLVM Foundation
  28 * SPIR-V is a Trademark of the Khronos Group
  29 * OpenCL is a Trademark of Apple, Inc.
  30
  31 Referring to these Trademarks within this document
  32 is by necessity, in order to put the semantics of each language
  33 into context, and is considered "fair use" under Trademark
  34 Law.
  35
  36 Introduction:
  37
  38 High-performance CPU/GPU software needs to often convert between integers
  39 and floating-point, therefore fast conversion/data-movement instructions
  40 are needed.  Also given that initialisation of floats tends to take up
  41 considerable space (even to just load 0.0) the inclusion of two compact
  42 format float immediate instructions is up for consideration using 16-bit
  43 immediates. BF16 is one of the formats: a second instruction allows a full
  44 accuracy FP32 to be constructed.
  45
  46 Libre-SOC will be compliant with the
  47 **Scalar Floating-Point Subset** (SFFS) i.e. is not implementing VMX/VSX,
  48 and with its focus on modern 3D GPU hybrid workloads represents an
  49 important new potential use-case for OpenPOWER.
  50
  51 Prior to the formation of the Compliancy Levels first introduced
  52 in v3.0C and v3.1
  53 the progressive historic development of the Scalar parts of the Power ISA assumed
  54 that VSX would always be there to complement it. However With VMX/VSX
  55 **not available** in the newly-introduced SFFS Compliancy Level, the
  56 existing non-VSX conversion/data-movement instructions require
  57 a Vector of load/store
  58 instructions (slow and expensive) to transfer data between the FPRs and
  59 the GPRs.  For a modern 3D GPU this kills any possibility of a
  60 competitive edge.
  61 Also, because SimpleV needs efficient scalar instructions in
  62 order to generate efficient vector instructions, adding new instructions
  63 for data-transfer/conversion between FPRs and GPRs multiplies the savings.
  64
  65 In addition, the vast majority of GPR <-> FPR data-transfers are as part
  66 of a FP <-> Integer conversion sequence, therefore reducing the number
  67 of instructions required is a priority.
  68
  69 Therefore, we are proposing adding:
  70
  71 * FPR load-immediate instructions, one equivalent to `BF16`, the
  72   other increasing accuracy to `FP32`
  73 * FPR <-> GPR data-transfer instructions that just copy bits without conversion
  74 * FPR <-> GPR combined data-transfer/conversion instructions that do
  75   Integer <-> FP conversions
  76
  77 If adding new Integer <-> FP conversion instructions,
  78 the opportunity may be taken to modernise the instructions and make them
  79 well-suited for common/important conversion sequences:
  80
  81 * Int -> Float
  82     * **standard IEEE754** - used by most languages and CPUs
  83 * Float -> Int
  84     * **standard OpenPOWER** - saturation with NaN
  85       converted to minimum valid integer
  86     * **Java/Saturating** - saturation with NaN converted to 0
  87     * **JavaScript** - modulo wrapping with Inf/NaN converted to 0
  88
  89 The assembly listings in the [[int_fp_mv/appendix]] show how costly
  90 some of these language-specific conversions are: Javascript, the
  91 worst case, is 32 scalar instructions including seven branch instructions.
  92
  93 # Proposed New Scalar Instructions
  94
  95 All of the following instructions use the standard OpenPower conversion to/from 64-bit float format when reading/writing a 32-bit float from/to a FPR.  All integers however are sourced/stored in the *GPR*.
  96
  97 Integer operands and results being in the GPR is the key differentiator between the proposed instructions
  98 (the entire rationale) compared to existing Scalar Power ISA.
  99 In all existing Power ISA Scalar conversion instructions, all
 100 operands are FPRs, even if the format of the source or destination
 101 data is actually a scalar integer.
 102
 103 *(The existing Scalar instructions being FP-FP only is based on an assumption
 104 that VSX will be implemented, and VSX is not part of the SFFS Compliancy
 105 Level. An earlier version of the Power ISA used to have similar
 106 FPR<->GPR instructions to these:
 107 they were deprecated due to this incorrect assumption that VSX would
 108 always be present).*
 109
 110 Note that source and destination widths can be overridden by SimpleV
 111 SVP64, and that SVP64 also has Saturation Modes *in addition*
 112 to those independently described here. SVP64 Overrides and Saturation
 113 work on *both* Fixed *and* Floating Point operands and results.
 114  The interactions with SVP64
 115 are explained in the  [[int_fp_mv/appendix]]
 116
 117 # Float load immediate  <a name="fmvis"></a>
 118
 119 These are like a variant of `fmvfg` and `oris`, combined.
 120 Power ISA currently requires a large
 121 number of instructions to get Floating Point constants into registers.
 122 `fmvis` on its own is equivalent to BF16 to FP32/64 conversion,
 123 but if followed up by `fishmv` an additional 16 bits of accuracy in the
 124 mantissa may be achieved.
 125
 126 These instructions **always** save
 127 resources compared to FP-load for exactly the same reason
 128 that `li` saves resources: an L1-Data-Cache and memory read
 129 is avoided.
 130
 131 *IBM may consider it worthwhile to extend these two instructions to
 132 v3.1 Prefixed (`pfmvis` and `pfishmv`: 8RR, imm0 extended).
 133 If so it is recommended that
 134 `pfmvis` load a full FP32 immediate and `pfishmv` supplies the three high
 135 missing exponent bits (numbered 8 to 10) and the lower additional
 136 29 mantissa bits (23 to 51) needed to construct a full FP64 immediate.
 137 Strictly speaking the sequence `fmvis fishmv pfishmv` achieves the
 138 same effect in the same number of bytes as `pfmvis pfishmv`,
 139 making `pfmvis` redundant.*
 140
 141 Just as Floating-point Load does not set FP Flags neither does fmvis or fishmv.
 142 As fishmv is specifically intended to work in conjunction with fmvis
 143 to provide additional accuracy, all bits other than those which
 144 would have been set by a prior fmvis instruction are deliberately ignored.
 145 (If these instructions involved reading from registers rather than immediates
 146 it would be a different story).
 147
 148 ## Load BF16 Immediate
 149
 150 `fmvis FRS, D`
 151
 152 Reinterprets `D << 16` as a 32-bit float, which is then converted to a
 153 64-bit float and written to `FRS`.  This is equivalent to reinterpreting
 154 `D` as a `BF16` and converting to 64-bit float.
 155 There is no need for an Rc=1 variant because this is an immediate loading
 156 instruction.
 157
 158 Example:
 159
 160 ```
 161 # clearing a FPR
 162 fmvis f4, 0 # writes +0.0 to f4
 163 # loading handy constants
 164 fmvis f4, 0x8000 # writes -0.0 to f4
 165 fmvis f4, 0x3F80 # writes +1.0 to f4
 166 fmvis f4, 0xBF80 # writes -1.0 to f4
 167 fmvis f4, 0xBFC0 # writes -1.5 to f4
 168 fmvis f4, 0x7FC0 # writes +qNaN to f4
 169 fmvis f4, 0x7F80 # writes +Infinity to f4
 170 fmvis f4, 0xFF80 # writes -Infinity to f4
 171 fmvis f4, 0x3FFF # writes +1.9921875 to f4
 172
 173 # clearing 128 FPRs with 2 SVP64 instructions
 174 # by issuing 32 vec4 (subvector length 4) ops
 175 setvli VL=MVL=32
 176 sv.fmvis/vec4 f0, 0 # writes +0.0 to f0-f127
 177 ```
 178 Important: If the float load immediate instruction(s) are left out,
 179 change all [GPR to FPR conversion instructions](#GPR-to-FPR-conversions)
 180 to instead write `+0.0` if `RA` is register `0`, at least
 181 allowing clearing FPRs.
 182
 183 `fmvis` fits with DX-Form:
 184
 185 |  0-5   | 6-10 | 11-15 | 16-25 | 26-30 | 31  | Form    |
 186 |--------|------|-------|-------|-------|-----|---------|
 187 |  Major | FRS  | d1    | d0    | XO    | d2  | DX-Form |
 188
 189 Pseudocode:
 190
 191     bf16 = d0 || d1 || d2 # create BF16 immediate
 192     fp32 = bf16 || [0]*16 # convert BF16 to FP32
 193     FRS = DOUBLE(fp32)    # convert FP32 to FP64
 194
 195 Special registers altered:
 196
 197     None
 198
 199 ## Float Immediate Second-Half MV <a name="fishmv"></a>
 200
 201 `fishmv FRS, D`
 202
 203 DX-Form:
 204
 205 |  0-5   | 6-10 | 11-15 | 16-25 | 26-30 | 31  | Form    |
 206 |--------|------|-------|-------|-------|-----|---------|
 207 |  Major | FRS  | d1    | d0    | XO    | d2  | DX-Form |
 208
 209 Strategically similar to how `oris` is used to construct
 210 32-bit Integers, an additional 16-bits of immediate is
 211 inserted into `FRS` to extend its accuracy to
 212 a full FP32 (stored as usual in FP64 Format within the FPR).
 213 If a prior `fmvis` instruction had been used to
 214 set the upper 16-bits of an FP32 value, `fishmv` contains the
 215 lower 16-bits.
 216
 217 The key difference between using `li` and `oris` to construct 32-bit
 218 GPR Immediates and `fishmv` is that the `fmvis` will have converted
 219 the `BF16` immediate to FP64 (Double) format.
 220 This is taken into consideration
 221 as can be seen in the pseudocode below.
 222
 223 Pseudocode:
 224
 225     fp32 <- SINGLE((FRS))            # convert to FP32
 226     fp32[16:31] <- d0 || d1 || d2    # replace LSB half
 227     FRS <- DOUBLE(fp32)              # convert back to FP64
 228
 229 Special registers altered:
 230
 231     None
 232
 233 **This instruction performs a Read-Modify-Write.** *FRS is read, the additional
 234 16 bit immediate inserted, and the result also written to FRS*
 235
 236 Example:
 237
 238 ```
 239 # these two combined instructions write 0x3f808000
 240 # into f4 as an FP32 to be converted to an FP64.
 241 # actual contents in f4 after conversion: 0x3ff0_1000_0000_0000
 242 # first the upper bits, happens to be +1.0
 243 fmvis f4, 0x3F80 # writes +1.0 to f4
 244 # now write the lower 16 bits of an FP32
 245 fishmv f4, 0x8000 # writes +1.00390625 to f4
 246 ```
 247
 248 # Immediate Tables
 249
 250 Tables that are used by `fmvtg`/`fmvfg`/`fcvttg`/`fcvtfg`:
 251
 252 ## `RCS` -- `Rc` and `s`
 253
 254 | `RCS` | `Rc` | FP Single Mode | Assembly Alias Mnemonic |
 255 |-------|------|----------------|-------------------------|
 256 | 0     | 0    | Double         | `<op>`                  |
 257 | 1     | 1    | Double         | `<op>.`                 |
 258 | 2     | 0    | Single         | `<op>s`                 |
 259 | 3     | 1    | Single         | `<op>s.`                |
 260
 261 ## `IT` -- Integer Type
 262
 263 | `IT` | Integer Type    | Assembly Alias Mnemonic |
 264 |------|-----------------|-------------------------|
 265 | 0    | Signed 32-bit   | `<op>w`                 |
 266 | 1    | Unsigned 32-bit | `<op>uw`                |
 267 | 2    | Signed 64-bit   | `<op>d`                 |
 268 | 3    | Unsigned 64-bit | `<op>ud`                |
 269
 270 ## `CVM` -- Float to Integer Conversion Mode
 271
 272 | `CVM` | `rounding_mode` | Semantics                        |
 273 |-------|-----------------|----------------------------------|
 274 | 000   | from `FPSCR`    | [OpenPower semantics]            |
 275 | 001   | Truncate        | [OpenPower semantics]            |
 276 | 010   | from `FPSCR`    | [Java/Saturating semantics]      |
 277 | 011   | Truncate        | [Java/Saturating semantics]      |
 278 | 100   | from `FPSCR`    | [JavaScript semantics]           |
 279 | 101   | Truncate        | [JavaScript semantics]           |
 280 | rest  | --              | illegal instruction trap for now |
 281
 282 [OpenPower semantics]: #fp-to-int-openpower-conversion-semantics
 283 [Java/Saturating semantics]: #fp-to-int-java-saturating-conversion-semantics
 284 [JavaScript semantics]: #fp-to-int-javascript-conversion-semantics
 285
 286 # Moves
 287
 288 These instructions perform a straight unaltered bit-level copy from one Register
 289 File to another.
 290
 291 ## FPR to GPR move
 292
 293 `fmvtg RT, FRB, RCS`
 294
 295 | 0-5 | 6-10 | 11-15 | 16-20 | 21-29 | 30-31 | Form   |
 296 |-----|------|-------|-------|-------|-------|--------|
 297 | PO  | RT   | 0     | FRB   | XO    | RCS   | X-Form |
 298
 299 ```
 300     if RCS[0] = 1 then  # if Single mode
 301         RT <- [0] * 32 || SINGLE((FRB))  # SINGLE since that's what stfs uses
 302     else
 303         RT <- (FRB)
 304 ```
 305
 306 Move a 32/64-bit float from a FPR to a GPR, just copying bits of the
 307 IEEE 754 representation directly. This is equivalent to `stfs` followed
 308 by `lwz` or equivalent to `stfd` followed by `ld`.  As `fmvtg` is just
 309 copying bits, `FPSCR` is not affected in any way.
 310
 311 Rc=1 tests RT and sets CR0, exactly like all other Scalar Fixed-Point
 312 operations.
 313
 314 Special Registers altered:
 315
 316     CR1     (if Rc=1)
 317
 318 ### Assembly Aliases
 319
 320 | Assembly Alias    | Full Instruction   |
 321 |-------------------|--------------------|
 322 | `fmvtg RT, FRB`   | `fmvtg RT, FRB, 0` |
 323 | `fmvtg. RT, FRB`  | `fmvtg RT, FRB, 1` |
 324 | `fmvtgs RT, FRB`  | `fmvtg RT, FRB, 2` |
 325 | `fmvtgs. RT, FRB` | `fmvtg RT, FRB, 3` |
 326
 327 ## GPR to FPR move
 328
 329 `fmvfg FRT, RB, RCS`
 330
 331 | 0-5 | 6-10 | 11-15 | 16-20 | 21-29 | 30-31 | Form   |
 332 |-----|------|-------|-------|-------|-------|--------|
 333 | PO  | FRT  | 0     | RB    | XO    | RCS   | X-Form |
 334
 335 ```
 336     if RCS[0] = 1 then  # if Single mode
 337         FRT <- DOUBLE((RB)[32:63])  # DOUBLE since that's what lfs uses
 338     else
 339         FRT <- (RB)
 340 ```
 341
 342 move a 32/64-bit float from a GPR to a FPR, just copying bits of the IEEE
 343 754 representation directly. This is equivalent to `stw` followed by `lfs`
 344 or equivalent to `std` followed by `lfd`. As `fmvfg` is just copying bits,
 345 `FPSCR` is not affected in any way.
 346
 347 Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
 348 operations.
 349
 350 Special Registers altered:
 351
 352     CR1     (if Rc=1)
 353
 354 ### Assembly Aliases
 355
 356 | Assembly Alias    | Full Instruction   |
 357 |-------------------|--------------------|
 358 | `fmvfg FRT, RB`   | `fmvfg FRT, RB, 0` |
 359 | `fmvfg. FRT, RB`  | `fmvfg FRT, RB, 1` |
 360 | `fmvfgs FRT, RB`  | `fmvfg FRT, RB, 2` |
 361 | `fmvfgs. FRT, RB` | `fmvfg FRT, RB, 3` |
 362
 363 # Conversions
 364
 365 Unlike the move instructions
 366 these instructions perform conversions between Integer and
 367 Floating Point. Truncation can therefore occur, as well
 368 as exceptions.
 369
 370 ## Floating-point Convert From GPR
 371
 372 | 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-29 | 30-31 | Form   |
 373 |-----|------|-------|-------|-------|-------|-------|--------|
 374 | PO  | FRT  | IT    | 0     | RB    | XO    | RCS   | X-Form |
 375
 376 `fcvtfg FRT, RB, IT, RCS`
 377
 378 ```
 379     if IT[0] = 0 and RCS[0] = 0 then  # 32-bit int -> 64-bit float
 380         # rounding never necessary, so don't touch FPSCR
 381         # based off xvcvsxwdp
 382         if IT = 0 then  # Signed 32-bit
 383             src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
 384         else  # IT = 1 -- Unsigned 32-bit
 385             src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
 386         FRT <- bfp64_CONVERT_FROM_BFP(src)
 387     else
 388         # rounding may be necessary. based off xscvuxdsp
 389         reset_xflags()
 390         switch(IT)
 391             case(0):  # Signed 32-bit
 392                 src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
 393             case(1):  # Unsigned 32-bit
 394                 src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
 395             case(2):  # Signed 64-bit
 396                 src <- bfp_CONVERT_FROM_SI64((RB))
 397             default:  # Unsigned 64-bit
 398                 src <- bfp_CONVERT_FROM_UI64((RB))
 399         if RCS[0] = 1 then  # Single
 400             rnd <- bfp_ROUND_TO_BFP32(FPSCR.RN, src)
 401             result32 <- bfp32_CONVERT_FROM_BFP(rnd)
 402             cls <- fprf_CLASS_BFP32(result32)
 403             result <- DOUBLE(result32)
 404         else
 405             rnd <- bfp_ROUND_TO_BFP64(FPSCR.RN, src)
 406             result <- bfp64_CONVERT_FROM_BFP(rnd)
 407             cls <- fprf_CLASS_BFP64(result)
 408
 409         if xx_flag = 1 then SetFX(FPSCR.XX)
 410
 411         FRT <- result
 412         FPSCR.FPRF <- cls
 413         FPSCR.FR <- inc_flag
 414         FPSCR.FI <- xx_flag
 415 ```
 416 <!-- note the PowerISA spec. explicitly has empty lines before/after SetFX,
 417 don't remove them -->
 418
 419 Convert from a unsigned/signed 32/64-bit integer in RB to a 32/64-bit
 420 float in FRT, following the usual 32-bit float in 64-bit float format.
 421 If converting from a unsigned/signed 32-bit integer to a 64-bit float,
 422 rounding is never necessary, so `FPSCR` is unmodified and exceptions are
 423 never raised. Otherwise, `FPSCR` is modified and exceptions are raised
 424 as usual.
 425
 426 Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
 427 operations.
 428
 429 Special Registers altered:
 430
 431     CR1     (if Rc=1)
 432     FPCSR   (TODO: which bits?) (if IT[0] != 0 or RCS[0] != 0)
 433
 434 ### Assembly Aliases
 435
 436 | Assembly Alias       | Full Instruction       |&nbsp;| Assembly Alias       | Full Instruction       |
 437 |----------------------|------------------------|------|----------------------|------------------------|
 438 | `fcvtfgw FRT, RB`    | `fcvtfg FRT, RB, 0, 0` |&nbsp;| `fcvtfgd FRT, RB`    | `fcvtfg FRT, RB, 2, 0` |
 439 | `fcvtfgw. FRT, RB`   | `fcvtfg FRT, RB, 0, 1` |&nbsp;| `fcvtfgd. FRT, RB`   | `fcvtfg FRT, RB, 2, 1` |
 440 | `fcvtfgws FRT, RB`   | `fcvtfg FRT, RB, 0, 2` |&nbsp;| `fcvtfgds FRT, RB`   | `fcvtfg FRT, RB, 2, 2` |
 441 | `fcvtfgws. FRT, RB`  | `fcvtfg FRT, RB, 0, 3` |&nbsp;| `fcvtfgds. FRT, RB`  | `fcvtfg FRT, RB, 2, 3` |
 442 | `fcvtfguw FRT, RB`   | `fcvtfg FRT, RB, 1, 0` |&nbsp;| `fcvtfgud FRT, RB`   | `fcvtfg FRT, RB, 3, 0` |
 443 | `fcvtfguw. FRT, RB`  | `fcvtfg FRT, RB, 1, 1` |&nbsp;| `fcvtfgud. FRT, RB`  | `fcvtfg FRT, RB, 3, 1` |
 444 | `fcvtfguws FRT, RB`  | `fcvtfg FRT, RB, 1, 2` |&nbsp;| `fcvtfguds FRT, RB`  | `fcvtfg FRT, RB, 3, 2` |
 445 | `fcvtfguws. FRT, RB` | `fcvtfg FRT, RB, 1, 3` |&nbsp;| `fcvtfguds. FRT, RB` | `fcvtfg FRT, RB, 3, 3` |
 446
 447 ## Floating-point to Integer Conversion Overview
 448
 449 <div id="fpr-to-gpr-conversion-mode"></div>
 450
 451 IEEE 754 doesn't specify what results are obtained when converting a NaN
 452 or out-of-range floating-point value to integer, so different programming
 453 languages and ISAs have made different choices.  Below is an overview
 454 of the different variants, listing the languages and hardware that
 455 implements each variant.
 456
 457 For convenience, we will give those different conversion semantics names
 458 based on which common ISA or programming language uses them, since there
 459 may not be an established name for them:
 460
 461 **Standard OpenPower conversion**
 462
 463 This conversion performs "saturation with NaN converted to minimum
 464 valid integer". This is also exactly the same as the x86 ISA conversion
 465 semantics.  OpenPOWER however has instructions for both:
 466
 467 * rounding mode read from FPSCR
 468 * rounding mode always set to truncate
 469
 470 **Java/Saturating conversion**
 471
 472 For the sake of simplicity, the FP -> Integer conversion semantics
 473 generalized from those used by Java's semantics (and Rust's `as`
 474 operator) will be referred to as [Java/Saturating conversion
 475 semantics](#fp-to-int-java-saturating-conversion-semantics).
 476
 477 Those same semantics are used in some way by all of the following
 478 languages (not necessarily for the default conversion method):
 479
 480 * Java's
 481   [FP -> Integer conversion](https://docs.oracle.com/javase/specs/jls/se16/html/jls-5.html#jls-5.1.3)
 482   (only for long/int results)
 483 * Rust's FP -> Integer conversion using the
 484   [`as` operator](https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics)
 485 * LLVM's
 486   [`llvm.fptosi.sat`](https://llvm.org/docs/LangRef.html#llvm-fptosi-sat-intrinsic) and
 487   [`llvm.fptoui.sat`](https://llvm.org/docs/LangRef.html#llvm-fptoui-sat-intrinsic) intrinsics
 488 * SPIR-V's OpenCL dialect's
 489   [`OpConvertFToU`](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToU) and
 490   [`OpConvertFToS`](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToS)
 491   instructions when decorated with
 492   [the `SaturatedConversion` decorator](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_decoration_a_decoration).
 493 * WebAssembly has also introduced
 494  [trunc_sat_u](ttps://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-u) and
 495  [trunc_sat_s](https://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-s)
 496
 497 **JavaScript conversion**
 498
 499 For the sake of simplicity, the FP -> Integer conversion
 500 semantics generalized from those used by JavaScripts's `ToInt32`
 501 abstract operation will be referred to as [JavaScript conversion
 502 semantics](#fp-to-int-javascript-conversion-semantics).
 503
 504 This instruction is present in ARM assembler as FJCVTZS
 505 <https://developer.arm.com/documentation/dui0801/g/hko1477562192868>
 506
 507 **Rc=1 and OE=1**
 508
 509 All of these instructions have an Rc=1 mode which sets CR0
 510 in the normal way for any instructions producing a GPR result.
 511 Additionally, when OE=1, if the numerical value of the FP number
 512 is not 100% accurately preserved (due to truncation or saturation
 513 and including when the FP number was NaN) then this is considered
 514 to be an integer Overflow condition, and CR0.SO, XER.SO and XER.OV
 515 are all set as normal for any GPR instructions that overflow.
 516
 517 ### FP to Integer Conversion Simplified Pseudo-code
 518
 519 Key for pseudo-code:
 520
 521 | term                      | result type | definition                                                                                         |
 522 |---------------------------|-------------|----------------------------------------------------------------------------------------------------|
 523 | `fp`                      | --          | `f32` or `f64` (or other types from SimpleV)                                                       |
 524 | `int`                     | --          | `u32`/`u64`/`i32`/`i64` (or other types from SimpleV)                                              |
 525 | `uint`                    | --          | the unsigned integer of the same bit-width as `int`                                                |
 526 | `int::BITS`               | `int`       | the bit-width of `int`                                                                             |
 527 | `uint::MIN_VALUE`         | `uint`      | the minimum value `uint` can store: `0`                   |
 528 | `uint::MAX_VALUE`          | `uint`       | the maximum value `uint` can store: `2^int::BITS - 1`  |
 529 | `int::MIN_VALUE`          | `int`       | the minimum value `int` can store : `-2^(int::BITS-1)`              |
 530 | `int::MAX_VALUE`          | `int`       | the maximum value `int` can store :  `2^(int::BITS-1) - 1`  |
 531 | `int::VALUE_COUNT`        | Integer     | the number of different values `int` can store (`2^int::BITS`). too big to fit in `int`.           |
 532 | `rint(fp, rounding_mode)` | `fp`        | rounds the floating-point value `fp` to an integer according to rounding mode `rounding_mode`      |
 533
 534 <div id="fp-to-int-openpower-conversion-semantics"></div>
 535 OpenPower conversion semantics (section A.2 page 1009 (page 1035) of
 536 Power ISA v3.1B):
 537
 538 ```
 539     def fp_to_int_open_power<fp, int>(v: fp) -> int:
 540         if v is NaN:
 541             return int::MIN_VALUE
 542         if v >= int::MAX_VALUE:
 543             return int::MAX_VALUE
 544         if v <= int::MIN_VALUE:
 545             return int::MIN_VALUE
 546         return (int)rint(v, rounding_mode)
 547 ```
 548
 549 <div id="fp-to-int-java-saturating-conversion-semantics"></div>
 550 [Java/Saturating conversion semantics](https://docs.oracle.com/javase/specs/jls/se16/html/jls-5.html#jls-5.1.3)
 551 (only for long/int results)/
 552 [Rust semantics](https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics)
 553 (with adjustment to add non-truncate rounding modes):
 554
 555 ```
 556     def fp_to_int_java_saturating<fp, int>(v: fp) -> int:
 557         if v is NaN:
 558             return 0
 559         if v >= int::MAX_VALUE:
 560             return int::MAX_VALUE
 561         if v <= int::MIN_VALUE:
 562             return int::MIN_VALUE
 563         return (int)rint(v, rounding_mode)
 564 ```
 565
 566 <div id="fp-to-int-javascript-conversion-semantics"></div>
 567 Section 7.1 of the ECMAScript / JavaScript
 568 [conversion semantics](https://262.ecma-international.org/11.0/#sec-toint32)
 569 (with adjustment to add non-truncate rounding modes):
 570
 571 ```
 572     def fp_to_int_java_script<fp, int>(v: fp) -> int:
 573         if v is NaN or infinite:
 574             return 0
 575         v = rint(v, rounding_mode)  # assume no loss of precision in result
 576         v = v mod int::VALUE_COUNT  # 2^32 for i32, 2^64 for i64, result is non-negative
 577         bits = (uint)v
 578         return (int)bits
 579 ```
 580
 581 ## Floating-point Convert To GPR
 582
 583 | 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-28 | 29     | 30 |  31    | Form    |
 584 |-----|------|-------|-------|-------|-------|--------|----|--------|---------|
 585 | PO  | RT   | IT    | CVM   | FRB   | XO    | RCS[0] | OE | RCS[1] | XO-Form |
 586
 587 `fcvttg RT, FRB, CVM, IT, RCS`
 588 `fcvttgo RT, FRB, CVM, IT, RCS`
 589
 590 ```
 591     # based on xscvdpuxws
 592     reset_xflags()
 593     if RCS[0] = 1 then  # if Single mode
 594         src <- bfp_CONVERT_FROM_BFP32(SINGLE((FRB)))
 595     else
 596         src <- bfp_CONVERT_FROM_BFP64((FRB))
 597
 598     switch(IT)
 599         case(0):  # Signed 32-bit
 600             range_min <- bfp_CONVERT_FROM_SI32(0x8000_0000)
 601             range_max <- bfp_CONVERT_FROM_SI32(0x7FFF_FFFF)
 602             js_mask <- 0xFFFF_FFFF
 603         case(1):  # Unsigned 32-bit
 604             range_min <- bfp_CONVERT_FROM_UI32(0)
 605             range_max <- bfp_CONVERT_FROM_UI32(0xFFFF_FFFF)
 606             js_mask <- 0xFFFF_FFFF
 607         case(2):  # Signed 64-bit
 608             range_min <- bfp_CONVERT_FROM_SI64(-0x8000_0000_0000_0000)
 609             range_max <- bfp_CONVERT_FROM_SI64(0x7FFF_FFFF_FFFF_FFFF)
 610             js_mask <- 0xFFFF_FFFF_FFFF_FFFF
 611         default:  # Unsigned 64-bit
 612             range_min <- bfp_CONVERT_FROM_UI64(0)
 613             range_max <- bfp_CONVERT_FROM_UI64(0xFFFF_FFFF_FFFF_FFFF)
 614             js_mask <- 0xFFFF_FFFF_FFFF_FFFF
 615
 616     if CVM[2] = 1 or FPSCR.RN = 0b01 then
 617         rnd <- bfp_ROUND_TO_INTEGER_TRUNC(src)
 618     else if FPSCR.RN = 0b00 then
 619         rnd <- bfp_ROUND_TO_INTEGER_NEAR_EVEN(src)
 620     else if FPSCR.RN = 0b10 then
 621         rnd <- bfp_ROUND_TO_INTEGER_CEIL(src)
 622     else if FPSCR.RN = 0b11 then
 623         rnd <- bfp_ROUND_TO_INTEGER_FLOOR(src)
 624
 625     switch(CVM)
 626         case(0, 1):  # OpenPower semantics
 627             if IsNaN(rnd) then
 628                 result <- si64_CONVERT_FROM_BFP(range_min)
 629             else if bfp_COMPARE_GT(rnd, range_max) then
 630                 result <- ui64_CONVERT_FROM_BFP(range_max)
 631             else if bfp_COMPARE_LT(rnd, range_min) then
 632                 result <- si64_CONVERT_FROM_BFP(range_min)
 633             else if IT[1] = 1 then  # Unsigned 32/64-bit
 634                 result <- ui64_CONVERT_FROM_BFP(range_max)
 635             else  # Signed 32/64-bit
 636                 result <- si64_CONVERT_FROM_BFP(range_max)
 637         case(2, 3):  # Java/Saturating semantics
 638             if IsNaN(rnd) then
 639                 result <- [0] * 64
 640             else if bfp_COMPARE_GT(rnd, range_max) then
 641                 result <- ui64_CONVERT_FROM_BFP(range_max)
 642             else if bfp_COMPARE_LT(rnd, range_min) then
 643                 result <- si64_CONVERT_FROM_BFP(range_min)
 644             else if IT[1] = 1 then  # Unsigned 32/64-bit
 645                 result <- ui64_CONVERT_FROM_BFP(range_max)
 646             else  # Signed 32/64-bit
 647                 result <- si64_CONVERT_FROM_BFP(range_max)
 648         default:  # JavaScript semantics
 649             # CVM = 6, 7 are illegal instructions
 650             # this works because the largest type we try to convert from has
 651             # 53 significand bits, and the largest type we try to convert to
 652             # has 64 bits, and the sum of those is strictly less than the 128
 653             # bits of the intermediate result.
 654             limit <- bfp_CONVERT_FROM_UI128([1] * 128)
 655             if IsInf(rnd) or IsNaN(rnd) then
 656                 result <- [0] * 64
 657             else if bfp_COMPARE_GT(bfp_ABSOLUTE(rnd), limit) then
 658                 result <- [0] * 64
 659             else
 660                 result128 <- si128_CONVERT_FROM_BFP(rnd)
 661                 result <- result128[64:127] & js_mask
 662
 663     switch(IT)
 664         case(0):  # Signed 32-bit
 665             result <- EXTS64(result[32:63])
 666             result_bfp <- bfp_CONVERT_FROM_SI32(result[32:63])
 667         case(1):  # Unsigned 32-bit
 668             result <- EXTZ64(result[32:63])
 669             result_bfp <- bfp_CONVERT_FROM_UI32(result[32:63])
 670         case(2):  # Signed 64-bit
 671             result_bfp <- bfp_CONVERT_FROM_SI64(result)
 672         default:  # Unsigned 64-bit
 673             result_bfp <- bfp_CONVERT_FROM_UI64(result)
 674
 675     if vxsnan_flag = 1 then SetFX(FPSCR.VXSNAN)
 676     if vxcvi_flag = 1 then SetFX(FPSCR.VXCVI)
 677     if xx_flag = 1 then SetFX(FPSCR.XX)
 678
 679     vx_flag <- vxsnan_flag | vxcvi_flag
 680     vex_flag <- FPSCR.VE & vx_flag
 681
 682     if vex_flag = 0 then
 683         RT <- result
 684         FPSCR.FPRF <- undefined
 685         FPSCR.FR <- inc_flag
 686         FPSCR.FI <- xx_flag
 687         if IsNaN(src) or not bfp_COMPARE_EQ(src, result_bfp) then
 688             overflow <- 1  # signals SO only when OE = 1
 689     else
 690         FPSCR.FR <- 0
 691         FPSCR.FI <- 0
 692 ```
 693
 694 Convert from 32/64-bit float in FRB to a unsigned/signed 32/64-bit integer
 695 in RT, with the conversion overflow/rounding semantics following the
 696 chosen `CVM` value, following the usual 32-bit float in 64-bit float
 697 format. `FPSCR` is modified and exceptions are raised as usual.
 698
 699 Both of these instructions have an Rc=1 mode which sets CR0 in the normal
 700 way for any instructions producing a GPR result.  Additionally, when OE=1,
 701 if the numerical value of the FP number is not 100% accurately preserved
 702 (due to truncation or saturation and including when the FP number was
 703 NaN) then this is considered to be an integer Overflow condition, and
 704 CR0.SO, XER.SO and XER.OV are all set as normal for any GPR instructions
 705 that overflow.
 706
 707 Special Registers altered:
 708
 709     CR0              (if Rc=1)
 710     XER SO, OV, OV32 (if OE=1)
 711     FPCSR   (TODO: which bits?)
 712
 713 ### Assembly Aliases
 714
 715 For brevity, `[o]` is used to mean `o` is optional there.
 716
 717 | Assembly Alias               | Full Instruction               | Assembly Alias               | Full Instruction               |
 718 |------------------------------|--------------------------------|------------------------------|--------------------------------|
 719 | `fcvttgw[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 0, 0` | `fcvttgd[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 2, 0` |
 720 | `fcvttgw[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 1` | `fcvttgd[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 1` |
 721 | `fcvtstgw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 2` | `fcvtstgd[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 2` |
 722 | `fcvtstgw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 0, 3` | `fcvtstgd[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 2, 3` |
 723 | `fcvttguw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 1, 0` | `fcvttgud[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 3, 0` |
 724 | `fcvttguw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 1` | `fcvttgud[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 1` |
 725 | `fcvtstguw[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 2` | `fcvtstgud[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 2` |
 726 | `fcvtstguw[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 1, 3` | `fcvtstgud[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 3, 3` |