dedent code section we're keeping in fcvtfgs[.] -- nothing but dedenting

[libreriscv.git] / openpower / sv / int_fp_mv.mdwn

[[!tag standards]]

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>

# FPR-to-GPR and GPR-to-FPR

TODO special constants instruction (e, tau/N, ln 2, sqrt 2, etc.) -- exclude any constants available through fmvis

**Draft Status** under development, for submission as an RFC

Links:

* <https://bugs.libre-soc.org/show_bug.cgi?id=650>
* <https://bugs.libre-soc.org/show_bug.cgi?id=230#c71>
* <https://bugs.libre-soc.org/show_bug.cgi?id=230#c74>
* <https://bugs.libre-soc.org/show_bug.cgi?id=230#c76>
* <https://bugs.libre-soc.org/show_bug.cgi?id=887> fmvis
* <https://bugs.libre-soc.org/show_bug.cgi?id=1015> int-fp RFC
* [[int_fp_mv/appendix]]
* [[sv/rfc/ls002]] - `fmvis` and `fishmv` External RFC Formal Submission
* [[sv/rfc/ls006]] - int-fp-mv External RFC Formal Submission

Trademarks:

* Rust is a Trademark of the Rust Foundation
* Java and JavaScript are Trademarks of Oracle
* LLVM is a Trademark of the LLVM Foundation
* SPIR-V is a Trademark of the Khronos Group
* OpenCL is a Trademark of Apple, Inc.

Referring to these Trademarks within this document
is by necessity, in order to put the semantics of each language
into context, and is considered "fair use" under Trademark
Law.

Introduction:

High-performance CPU/GPU software needs to often convert between integers
and floating-point, therefore fast conversion/data-movement instructions
are needed.  Also given that initialisation of floats tends to take up
considerable space (even to just load 0.0) the inclusion of two compact
format float immediate instructions is up for consideration using 16-bit
immediates. BF16 is one of the formats: a second instruction allows a full
accuracy FP32 to be constructed.

Libre-SOC will be compliant with the
**Scalar Floating-Point Subset** (SFFS) i.e. is not implementing VMX/VSX,
and with its focus on modern 3D GPU hybrid workloads represents an
important new potential use-case for OpenPOWER.

Prior to the formation of the Compliancy Levels first introduced
in v3.0C and v3.1
the progressive historic development of the Scalar parts of the Power ISA assumed
that VSX would always be there to complement it. However With VMX/VSX 
**not available** in the newly-introduced SFFS Compliancy Level, the
existing non-VSX conversion/data-movement instructions require 
a Vector of load/store
instructions (slow and expensive) to transfer data between the FPRs and
the GPRs.  For a modern 3D GPU this kills any possibility of a
competitive edge.
Also, because SimpleV needs efficient scalar instructions in
order to generate efficient vector instructions, adding new instructions
for data-transfer/conversion between FPRs and GPRs multiplies the savings.

In addition, the vast majority of GPR <-> FPR data-transfers are as part
of a FP <-> Integer conversion sequence, therefore reducing the number
of instructions required is a priority.

Therefore, we are proposing adding:

* FPR load-immediate instructions, one equivalent to `BF16`, the
  other increasing accuracy to `FP32`
* FPR <-> GPR data-transfer instructions that just copy bits without conversion
* FPR <-> GPR combined data-transfer/conversion instructions that do
  Integer <-> FP conversions

If adding new Integer <-> FP conversion instructions, 
the opportunity may be taken to modernise the instructions and make them
well-suited for common/important conversion sequences:

* Int -> Float
    * **standard IEEE754** - used by most languages and CPUs
* Float -> Int
    * **standard OpenPOWER** - saturation with NaN
      converted to minimum valid integer
    * **Java/Saturating** - saturation with NaN converted to 0
    * **JavaScript** - modulo wrapping with Inf/NaN converted to 0

The assembly listings in the [[int_fp_mv/appendix]] show how costly
some of these language-specific conversions are: JavaScript, the
worst case, is 32 scalar instructions including seven branch instructions.
(FIXME: disagrees with ls006 and sv.mdwn)

# Proposed New Scalar Instructions

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*.

Integer operands and results being in the GPR is the key differentiator between the proposed instructions
(the entire rationale) compared to existing Scalar Power ISA.
In all existing Power ISA Scalar conversion instructions, all
operands are FPRs, even if the format of the source or destination
data is actually a scalar integer.

*(The existing Scalar instructions being FP-FP only is based on an assumption
that VSX will be implemented, and VSX is not part of the SFFS Compliancy
Level. An earlier version of the Power ISA used to have similar
FPR<->GPR instructions to these:
they were deprecated due to this incorrect assumption that VSX would
always be present).*

Note that source and destination widths can be overridden by SimpleV
SVP64, and that SVP64 also has Saturation Modes *in addition*
to those independently described here. SVP64 Overrides and Saturation
work on *both* Fixed *and* Floating Point operands and results.
 The interactions with SVP64
are explained in the  [[int_fp_mv/appendix]]

# Float load immediate  <a name="fmvis"></a>

These are like a variant of `fmvfg` and `oris`, combined.
Power ISA currently requires a large
number of instructions to get Floating Point constants into registers.
`fmvis` on its own is equivalent to BF16 to FP32/64 conversion,
but if followed up by `fishmv` an additional 16 bits of accuracy in the
mantissa may be achieved.

These instructions **always** save
resources compared to FP-load for exactly the same reason
that `li` saves resources: an L1-Data-Cache and memory read
is avoided.

*IBM may consider it worthwhile to extend these two instructions to
v3.1 Prefixed (`pfmvis` and `pfishmv`: 8RR, imm0 extended).
If so it is recommended that
`pfmvis` load a full FP32 immediate and `pfishmv` supplies the three high
missing exponent bits (numbered 8 to 10) and the lower additional
29 mantissa bits (23 to 51) needed to construct a full FP64 immediate.
Strictly speaking the sequence `fmvis fishmv pfishmv` achieves the
same effect in the same number of bytes as `pfmvis pfishmv`,
making `pfmvis` redundant.*

Just as Floating-point Load does not set FP Flags neither does fmvis or fishmv.
As fishmv is specifically intended to work in conjunction with fmvis
to provide additional accuracy, all bits other than those which
would have been set by a prior fmvis instruction are deliberately ignored.
(If these instructions involved reading from registers rather than immediates
it would be a different story).

## Load BF16 Immediate

`fmvis FRS, D`

Reinterprets `D << 16` as a 32-bit float, which is then converted to a
64-bit float and written to `FRS`.  This is equivalent to reinterpreting
`D` as a `BF16` and converting to 64-bit float.
There is no need for an Rc=1 variant because this is an immediate loading
instruction.

Example:

```
# clearing a FPR
fmvis f4, 0 # writes +0.0 to f4
# loading handy constants
fmvis f4, 0x8000 # writes -0.0 to f4
fmvis f4, 0x3F80 # writes +1.0 to f4
fmvis f4, 0xBF80 # writes -1.0 to f4
fmvis f4, 0xBFC0 # writes -1.5 to f4
fmvis f4, 0x7FC0 # writes +qNaN to f4
fmvis f4, 0x7F80 # writes +Infinity to f4
fmvis f4, 0xFF80 # writes -Infinity to f4
fmvis f4, 0x3FFF # writes +1.9921875 to f4

# clearing 128 FPRs with 2 SVP64 instructions
# by issuing 32 vec4 (subvector length 4) ops
setvli VL=MVL=32
sv.fmvis/vec4 f0, 0 # writes +0.0 to f0-f127
```
Important: If the float load immediate instruction(s) are left out,
change all [GPR to FPR conversion instructions](#GPR-to-FPR-conversions)
to instead write `+0.0` if `RA` is register `0`, at least
allowing clearing FPRs.

`fmvis` fits with DX-Form:

|  0-5   | 6-10 | 11-15 | 16-25 | 26-30 | 31  | Form    |
|--------|------|-------|-------|-------|-----|---------|
|  Major | FRS  | d1    | d0    | XO    | d2  | DX-Form |

Pseudocode:

    bf16 = d0 || d1 || d2 # create BF16 immediate
    fp32 = bf16 || [0]*16 # convert BF16 to FP32
    FRS = DOUBLE(fp32)    # convert FP32 to FP64

Special registers altered:

    None

## Float Immediate Second-Half MV <a name="fishmv"></a>

`fishmv FRS, D`

DX-Form:

|  0-5   | 6-10 | 11-15 | 16-25 | 26-30 | 31  | Form    |
|--------|------|-------|-------|-------|-----|---------|
|  Major | FRS  | d1    | d0    | XO    | d2  | DX-Form |

Strategically similar to how `oris` is used to construct
32-bit Integers, an additional 16-bits of immediate is
inserted into `FRS` to extend its accuracy to
a full FP32 (stored as usual in FP64 Format within the FPR).
If a prior `fmvis` instruction had been used to
set the upper 16-bits of an FP32 value, `fishmv` contains the
lower 16-bits.

The key difference between using `li` and `oris` to construct 32-bit
GPR Immediates and `fishmv` is that the `fmvis` will have converted
the `BF16` immediate to FP64 (Double) format.
This is taken into consideration
as can be seen in the pseudocode below.

Pseudocode:

    fp32 <- SINGLE((FRS))            # convert to FP32
    fp32[16:31] <- d0 || d1 || d2    # replace LSB half
    FRS <- DOUBLE(fp32)              # convert back to FP64

Special registers altered:

    None

**This instruction performs a Read-Modify-Write.** *FRS is read, the additional
16 bit immediate inserted, and the result also written to FRS*

Example:

```
# these two combined instructions write 0x3f808000
# into f4 as an FP32 to be converted to an FP64.
# actual contents in f4 after conversion: 0x3ff0_1000_0000_0000
# first the upper bits, happens to be +1.0
fmvis f4, 0x3F80 # writes +1.0 to f4
# now write the lower 16 bits of an FP32
fishmv f4, 0x8000 # writes +1.00390625 to f4
```

# Immediate Tables

Tables that are used by
`fmvtg[s][.]`/`fmvfg[s][.]`/`fcvttg[s][.]`/`fcvtfg[s][.]`:

## `RCS` -- `Rc` and `s`

| `RCS` | `Rc` | FP Single Mode | Assembly Alias Mnemonic |
|-------|------|----------------|-------------------------|
| 0     | 0    | Double         | `<op>`                  |
| 1     | 1    | Double         | `<op>.`                 |
| 2     | 0    | Single         | `<op>s`                 |
| 3     | 1    | Single         | `<op>s.`                |

## `IT` -- Integer Type

| `IT` | Integer Type    | Assembly Alias Mnemonic |
|------|-----------------|-------------------------|
| 0    | Signed 32-bit   | `<op>w`                 |
| 1    | Unsigned 32-bit | `<op>uw`                |
| 2    | Signed 64-bit   | `<op>d`                 |
| 3    | Unsigned 64-bit | `<op>ud`                |

## `CVM` -- Float to Integer Conversion Mode

| `CVM` | `rounding_mode` | Semantics                        |
|-------|-----------------|----------------------------------|
| 000   | from `FPSCR`    | [OpenPower semantics]            |
| 001   | Truncate        | [OpenPower semantics]            |
| 010   | from `FPSCR`    | [Java/Saturating semantics]      |
| 011   | Truncate        | [Java/Saturating semantics]      |
| 100   | from `FPSCR`    | [JavaScript semantics]           |
| 101   | Truncate        | [JavaScript semantics]           |
| rest  | --              | illegal instruction trap for now |

[OpenPower semantics]: #fp-to-int-openpower-conversion-semantics
[Java/Saturating semantics]: #fp-to-int-java-saturating-conversion-semantics
[JavaScript semantics]: #fp-to-int-javascript-conversion-semantics

# Moves

These instructions perform a straight unaltered bit-level copy from one Register
File to another.

## FPR to GPR Move

`fmvtg RT, FRB`
`fmvtg. RT, FRB`

| 0-5 | 6-10 | 11-15 | 16-20 | 21-30 | 31 | Form   |
|-----|------|-------|-------|-------|----|--------|
| PO  | RT   | 0     | FRB   | XO    | Rc | X-Form |

```
    RT <- (FRB)
```

Move a 64-bit float from a FPR to a GPR, just copying bits of the IEEE 754
representation directly. This is equivalent to `stfd` followed by `ld`.
As `fmvtg` is just copying bits, `FPSCR` is not affected in any way.

Rc=1 tests RT and sets CR0, exactly like all other Scalar Fixed-Point
operations.

Special Registers altered:

    CR0     (if Rc=1)

## FPR to GPR Move Single

`fmvtgs RT, FRB`
`fmvtgs. RT, FRB`

| 0-5 | 6-10 | 11-15 | 16-20 | 21-30 | 31 | Form   |
|-----|------|-------|-------|-------|----|--------|
| PO  | RT   | 0     | FRB   | XO    | Rc | X-Form |

```
    RT <- [0] * 32 || SINGLE((FRB))  # SINGLE since that's what stfs uses
```

Move a 32-bit float from a FPR to a GPR, just copying bits of the IEEE 754
representation directly. This is equivalent to `stfs` followed by `lwz`.
As `fmvtgs` is just copying bits, `FPSCR` is not affected in any way.

Rc=1 tests RT and sets CR0, exactly like all other Scalar Fixed-Point
operations.

Special Registers altered:

    CR0     (if Rc=1)

## GPR to FPR Move

`fmvfg FRT, RB`
`fmvfg. FRT, RB`

| 0-5 | 6-10 | 11-15 | 16-20 | 21-30 | 31 | Form   |
|-----|------|-------|-------|-------|----|--------|
| PO  | FRT  | 0     | RB    | XO    | Rc | X-Form |

```
    FRT <- (RB)
```

move a 64-bit float from a GPR to a FPR, just copying bits of the IEEE 754
representation directly. This is equivalent to `std` followed by `lfd`.
As `fmvfg` is just copying bits, `FPSCR` is not affected in any way.

Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
operations.

Special Registers altered:

    CR1     (if Rc=1)

## GPR to FPR Move Single

`fmvfgs FRT, RB`
`fmvfgs. FRT, RB`

| 0-5 | 6-10 | 11-15 | 16-20 | 21-30 | 31 | Form   |
|-----|------|-------|-------|-------|----|--------|
| PO  | FRT  | 0     | RB    | XO    | Rc | X-Form |

```
    FRT <- DOUBLE((RB)[32:63])  # DOUBLE since that's what lfs uses
```

move a 32-bit float from a GPR to a FPR, just copying bits of the IEEE 754
representation directly. This is equivalent to `stw` followed by `lfs`.
As `fmvfgs` is just copying bits, `FPSCR` is not affected in any way.

Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
operations.

Special Registers altered:

    CR1     (if Rc=1)

# Conversions

Unlike the move instructions
these instructions perform conversions between Integer and
Floating Point. Truncation can therefore occur, as well
as exceptions.

## Floating-point Convert From GPR

| 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-29 | 30-31 | Form   |
|-----|------|-------|-------|-------|-------|-------|--------|
| PO  | FRT  | IT    | 0     | RB    | XO    | RCS   | X-Form |

`fcvtfg FRT, RB, IT, RCS`

```
    if IT[0] = 0 and RCS[0] = 0 then  # 32-bit int -> 64-bit float
        # rounding never necessary, so don't touch FPSCR
        # based off xvcvsxwdp
        if IT = 0 then  # Signed 32-bit
            src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
        else  # IT = 1 -- Unsigned 32-bit
            src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
        FRT <- bfp64_CONVERT_FROM_BFP(src)
    else
        # rounding may be necessary. based off xscvuxdsp
        reset_xflags()
        switch(IT)
            case(0):  # Signed 32-bit
                src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
            case(1):  # Unsigned 32-bit
                src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
            case(2):  # Signed 64-bit
                src <- bfp_CONVERT_FROM_SI64((RB))
            default:  # Unsigned 64-bit
                src <- bfp_CONVERT_FROM_UI64((RB))
        if RCS[0] = 1 then  # Single
            rnd <- bfp_ROUND_TO_BFP32(FPSCR.RN, src)
            result32 <- bfp32_CONVERT_FROM_BFP(rnd)
            cls <- fprf_CLASS_BFP32(result32)
            result <- DOUBLE(result32)
        else
            rnd <- bfp_ROUND_TO_BFP64(FPSCR.RN, src)
            result <- bfp64_CONVERT_FROM_BFP(rnd)
            cls <- fprf_CLASS_BFP64(result)

        if xx_flag = 1 then SetFX(FPSCR.XX)

        FRT <- result
        FPSCR.FPRF <- cls
        FPSCR.FR <- inc_flag
        FPSCR.FI <- xx_flag
```
<!-- note the PowerISA spec. explicitly has empty lines before/after SetFX,
don't remove them -->

Convert from a unsigned/signed 32/64-bit integer in RB to a 32/64-bit
float in FRT, following the usual 32-bit float in 64-bit float format.
If converting from a unsigned/signed 32-bit integer to a 64-bit float,
rounding is never necessary, so `FPSCR` is unmodified and exceptions are
never raised. Otherwise, `FPSCR` is modified and exceptions are raised
as usual.

Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
operations.

Special Registers altered:

    CR1     (if Rc=1)
    FPCSR   (TODO: which bits?) (if IT[0] != 0 or RCS[0] != 0)

### Assembly Aliases

| Assembly Alias       | Full Instruction       |&nbsp;| Assembly Alias       | Full Instruction       |
|----------------------|------------------------|------|----------------------|------------------------|
| `fcvtfgw FRT, RB`    | `fcvtfg FRT, RB, 0, 0` |&nbsp;| `fcvtfgd FRT, RB`    | `fcvtfg FRT, RB, 2, 0` |
| `fcvtfgw. FRT, RB`   | `fcvtfg FRT, RB, 0, 1` |&nbsp;| `fcvtfgd. FRT, RB`   | `fcvtfg FRT, RB, 2, 1` |
| `fcvtfgws FRT, RB`   | `fcvtfg FRT, RB, 0, 2` |&nbsp;| `fcvtfgds FRT, RB`   | `fcvtfg FRT, RB, 2, 2` |
| `fcvtfgws. FRT, RB`  | `fcvtfg FRT, RB, 0, 3` |&nbsp;| `fcvtfgds. FRT, RB`  | `fcvtfg FRT, RB, 2, 3` |
| `fcvtfguw FRT, RB`   | `fcvtfg FRT, RB, 1, 0` |&nbsp;| `fcvtfgud FRT, RB`   | `fcvtfg FRT, RB, 3, 0` |
| `fcvtfguw. FRT, RB`  | `fcvtfg FRT, RB, 1, 1` |&nbsp;| `fcvtfgud. FRT, RB`  | `fcvtfg FRT, RB, 3, 1` |
| `fcvtfguws FRT, RB`  | `fcvtfg FRT, RB, 1, 2` |&nbsp;| `fcvtfguds FRT, RB`  | `fcvtfg FRT, RB, 3, 2` |
| `fcvtfguws. FRT, RB` | `fcvtfg FRT, RB, 1, 3` |&nbsp;| `fcvtfguds. FRT, RB` | `fcvtfg FRT, RB, 3, 3` |

## Floating-point Convert From GPR

| 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-29 | 30-31 | Form   |
|-----|------|-------|-------|-------|-------|-------|--------|
| PO  | FRT  | IT    | 0     | RB    | XO    | RCS   | X-Form |

`fcvtfg FRT, RB, IT, RCS`

```
    if IT[0] = 0 and RCS[0] = 0 then  # 32-bit int -> 64-bit float
        # rounding never necessary, so don't touch FPSCR
        # based off xvcvsxwdp
        if IT = 0 then  # Signed 32-bit
            src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
        else  # IT = 1 -- Unsigned 32-bit
            src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
        FRT <- bfp64_CONVERT_FROM_BFP(src)
    else
    # rounding may be necessary. based off xscvuxdsp
    reset_xflags()
    switch(IT)
        case(0):  # Signed 32-bit
            src <- bfp_CONVERT_FROM_SI32((RB)[32:63])
        case(1):  # Unsigned 32-bit
            src <- bfp_CONVERT_FROM_UI32((RB)[32:63])
        case(2):  # Signed 64-bit
            src <- bfp_CONVERT_FROM_SI64((RB))
        default:  # Unsigned 64-bit
            src <- bfp_CONVERT_FROM_UI64((RB))
    if RCS[0] = 1 then  # Single
        rnd <- bfp_ROUND_TO_BFP32(FPSCR.RN, src)
        result32 <- bfp32_CONVERT_FROM_BFP(rnd)
        cls <- fprf_CLASS_BFP32(result32)
        result <- DOUBLE(result32)
    else
        rnd <- bfp_ROUND_TO_BFP64(FPSCR.RN, src)
        result <- bfp64_CONVERT_FROM_BFP(rnd)
        cls <- fprf_CLASS_BFP64(result)

    if xx_flag = 1 then SetFX(FPSCR.XX)

    FRT <- result
    FPSCR.FPRF <- cls
    FPSCR.FR <- inc_flag
    FPSCR.FI <- xx_flag
```
<!-- note the PowerISA spec. explicitly has empty lines before/after SetFX,
don't remove them -->

Convert from a unsigned/signed 32/64-bit integer in RB to a 32/64-bit
float in FRT, following the usual 32-bit float in 64-bit float format.
If converting from a unsigned/signed 32-bit integer to a 64-bit float,
rounding is never necessary, so `FPSCR` is unmodified and exceptions are
never raised. Otherwise, `FPSCR` is modified and exceptions are raised
as usual.

Rc=1 tests FRT and sets CR1, exactly like all other Scalar Floating-Point
operations.

Special Registers altered:

    CR1     (if Rc=1)
    FPCSR   (TODO: which bits?) (if IT[0] != 0 or RCS[0] != 0)

### Assembly Aliases

| Assembly Alias       | Full Instruction       |&nbsp;| Assembly Alias       | Full Instruction       |
|----------------------|------------------------|------|----------------------|------------------------|
| `fcvtfgw FRT, RB`    | `fcvtfg FRT, RB, 0, 0` |&nbsp;| `fcvtfgd FRT, RB`    | `fcvtfg FRT, RB, 2, 0` |
| `fcvtfgw. FRT, RB`   | `fcvtfg FRT, RB, 0, 1` |&nbsp;| `fcvtfgd. FRT, RB`   | `fcvtfg FRT, RB, 2, 1` |
| `fcvtfgws FRT, RB`   | `fcvtfg FRT, RB, 0, 2` |&nbsp;| `fcvtfgds FRT, RB`   | `fcvtfg FRT, RB, 2, 2` |
| `fcvtfgws. FRT, RB`  | `fcvtfg FRT, RB, 0, 3` |&nbsp;| `fcvtfgds. FRT, RB`  | `fcvtfg FRT, RB, 2, 3` |
| `fcvtfguw FRT, RB`   | `fcvtfg FRT, RB, 1, 0` |&nbsp;| `fcvtfgud FRT, RB`   | `fcvtfg FRT, RB, 3, 0` |
| `fcvtfguw. FRT, RB`  | `fcvtfg FRT, RB, 1, 1` |&nbsp;| `fcvtfgud. FRT, RB`  | `fcvtfg FRT, RB, 3, 1` |
| `fcvtfguws FRT, RB`  | `fcvtfg FRT, RB, 1, 2` |&nbsp;| `fcvtfguds FRT, RB`  | `fcvtfg FRT, RB, 3, 2` |
| `fcvtfguws. FRT, RB` | `fcvtfg FRT, RB, 1, 3` |&nbsp;| `fcvtfguds. FRT, RB` | `fcvtfg FRT, RB, 3, 3` |

## Floating-point to Integer Conversion Overview

<div id="fpr-to-gpr-conversion-mode"></div>

IEEE 754 doesn't specify what results are obtained when converting a NaN
or out-of-range floating-point value to integer, so different programming
languages and ISAs have made different choices.  Below is an overview
of the different variants, listing the languages and hardware that
implements each variant.

For convenience, we will give those different conversion semantics names
based on which common ISA or programming language uses them, since there
may not be an established name for them:

**Standard OpenPower conversion**

This conversion performs "saturation with NaN converted to minimum
valid integer". This is also exactly the same as the x86 ISA conversion
semantics.  OpenPOWER however has instructions for both:

* rounding mode read from FPSCR
* rounding mode always set to truncate

**Java/Saturating conversion**

For the sake of simplicity, the FP -> Integer conversion semantics
generalized from those used by Java's semantics (and Rust's `as`
operator) will be referred to as [Java/Saturating conversion
semantics](#fp-to-int-java-saturating-conversion-semantics).

Those same semantics are used in some way by all of the following
languages (not necessarily for the default conversion method):

* Java's
  [FP -> Integer conversion](https://docs.oracle.com/javase/specs/jls/se16/html/jls-5.html#jls-5.1.3)
  (only for long/int results)
* Rust's FP -> Integer conversion using the
  [`as` operator](https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics)
* LLVM's
  [`llvm.fptosi.sat`](https://llvm.org/docs/LangRef.html#llvm-fptosi-sat-intrinsic) and
  [`llvm.fptoui.sat`](https://llvm.org/docs/LangRef.html#llvm-fptoui-sat-intrinsic) intrinsics
* SPIR-V's OpenCL dialect's
  [`OpConvertFToU`](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToU) and
  [`OpConvertFToS`](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#OpConvertFToS)
  instructions when decorated with
  [the `SaturatedConversion` decorator](https://www.khronos.org/registry/spir-v/specs/unified1/SPIRV.html#_a_id_decoration_a_decoration).
* WebAssembly has also introduced
 [trunc_sat_u](ttps://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-u) and
 [trunc_sat_s](https://webassembly.github.io/spec/core/exec/numerics.html#op-trunc-sat-s)

**JavaScript conversion**

For the sake of simplicity, the FP -> Integer conversion
semantics generalized from those used by JavaScripts's `ToInt32`
abstract operation will be referred to as [JavaScript conversion
semantics](#fp-to-int-javascript-conversion-semantics).

This instruction is present in ARM assembler as FJCVTZS
<https://developer.arm.com/documentation/dui0801/g/hko1477562192868>

**Rc=1 and OE=1**

All of these instructions have an Rc=1 mode which sets CR0
in the normal way for any instructions producing a GPR result.
Additionally, when OE=1, if the numerical value of the FP number
is not 100% accurately preserved (due to truncation or saturation
and including when the FP number was NaN) then this is considered
to be an integer Overflow condition, and CR0.SO, XER.SO and XER.OV
are all set as normal for any GPR instructions that overflow.

### FP to Integer Conversion Simplified Pseudo-code

Key for pseudo-code:

| term                      | result type | definition                                                                                         |
|---------------------------|-------------|----------------------------------------------------------------------------------------------------|
| `fp`                      | --          | `f32` or `f64` (or other types from SimpleV)                                                       |
| `int`                     | --          | `u32`/`u64`/`i32`/`i64` (or other types from SimpleV)                                              |
| `uint`                    | --          | the unsigned integer of the same bit-width as `int`                                                |
| `int::BITS`               | `int`       | the bit-width of `int`                                                                             |
| `uint::MIN_VALUE`         | `uint`      | the minimum value `uint` can store: `0`                   |
| `uint::MAX_VALUE`          | `uint`       | the maximum value `uint` can store: `2^int::BITS - 1`  |
| `int::MIN_VALUE`          | `int`       | the minimum value `int` can store : `-2^(int::BITS-1)`              |
| `int::MAX_VALUE`          | `int`       | the maximum value `int` can store :  `2^(int::BITS-1) - 1`  |
| `int::VALUE_COUNT`        | Integer     | the number of different values `int` can store (`2^int::BITS`). too big to fit in `int`.           |
| `rint(fp, rounding_mode)` | `fp`        | rounds the floating-point value `fp` to an integer according to rounding mode `rounding_mode`      |

<div id="fp-to-int-openpower-conversion-semantics"></div>
OpenPower conversion semantics (section A.2 page 1009 (page 1035) of
Power ISA v3.1B):

```
    def fp_to_int_open_power<fp, int>(v: fp) -> int:
        if v is NaN:
            return int::MIN_VALUE
        if v >= int::MAX_VALUE:
            return int::MAX_VALUE
        if v <= int::MIN_VALUE:
            return int::MIN_VALUE
        return (int)rint(v, rounding_mode)
```

<div id="fp-to-int-java-saturating-conversion-semantics"></div>
[Java/Saturating conversion semantics](https://docs.oracle.com/javase/specs/jls/se16/html/jls-5.html#jls-5.1.3)
(only for long/int results)/
[Rust semantics](https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics)
(with adjustment to add non-truncate rounding modes):

```
    def fp_to_int_java_saturating<fp, int>(v: fp) -> int:
        if v is NaN:
            return 0
        if v >= int::MAX_VALUE:
            return int::MAX_VALUE
        if v <= int::MIN_VALUE:
            return int::MIN_VALUE
        return (int)rint(v, rounding_mode)
```

<div id="fp-to-int-javascript-conversion-semantics"></div>
Section 7.1 of the ECMAScript / JavaScript
[conversion semantics](https://262.ecma-international.org/11.0/#sec-toint32)
(with adjustment to add non-truncate rounding modes):

```
    def fp_to_int_java_script<fp, int>(v: fp) -> int:
        if v is NaN or infinite:
            return 0
        v = rint(v, rounding_mode)  # assume no loss of precision in result
        v = v mod int::VALUE_COUNT  # 2^32 for i32, 2^64 for i64, result is non-negative
        bits = (uint)v
        return (int)bits
```

## Floating-point Convert To GPR

| 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-28 | 29     | 30 |  31    | Form    |
|-----|------|-------|-------|-------|-------|--------|----|--------|---------|
| PO  | RT   | IT    | CVM   | FRB   | XO    | RCS[0] | OE | RCS[1] | XO-Form |

`fcvttg RT, FRB, CVM, IT, RCS`
`fcvttgo RT, FRB, CVM, IT, RCS`

```
    # based on xscvdpuxws
    reset_xflags()
    if RCS[0] = 1 then  # if Single mode
        src <- bfp_CONVERT_FROM_BFP32(SINGLE((FRB)))
    else
        src <- bfp_CONVERT_FROM_BFP64((FRB))

    switch(IT)
        case(0):  # Signed 32-bit
            range_min <- bfp_CONVERT_FROM_SI32(0x8000_0000)
            range_max <- bfp_CONVERT_FROM_SI32(0x7FFF_FFFF)
            js_mask <- 0xFFFF_FFFF
        case(1):  # Unsigned 32-bit
            range_min <- bfp_CONVERT_FROM_UI32(0)
            range_max <- bfp_CONVERT_FROM_UI32(0xFFFF_FFFF)
            js_mask <- 0xFFFF_FFFF
        case(2):  # Signed 64-bit
            range_min <- bfp_CONVERT_FROM_SI64(-0x8000_0000_0000_0000)
            range_max <- bfp_CONVERT_FROM_SI64(0x7FFF_FFFF_FFFF_FFFF)
            js_mask <- 0xFFFF_FFFF_FFFF_FFFF
        default:  # Unsigned 64-bit
            range_min <- bfp_CONVERT_FROM_UI64(0)
            range_max <- bfp_CONVERT_FROM_UI64(0xFFFF_FFFF_FFFF_FFFF)
            js_mask <- 0xFFFF_FFFF_FFFF_FFFF

    if CVM[2] = 1 or FPSCR.RN = 0b01 then
        rnd <- bfp_ROUND_TO_INTEGER_TRUNC(src)
    else if FPSCR.RN = 0b00 then
        rnd <- bfp_ROUND_TO_INTEGER_NEAR_EVEN(src)
    else if FPSCR.RN = 0b10 then
        rnd <- bfp_ROUND_TO_INTEGER_CEIL(src)
    else if FPSCR.RN = 0b11 then
        rnd <- bfp_ROUND_TO_INTEGER_FLOOR(src)

    switch(CVM)
        case(0, 1):  # OpenPower semantics
            if IsNaN(rnd) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if bfp_COMPARE_GT(rnd, range_max) then
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else if bfp_COMPARE_LT(rnd, range_min) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if IT[1] = 1 then  # Unsigned 32/64-bit
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else  # Signed 32/64-bit
                result <- si64_CONVERT_FROM_BFP(range_max)
        case(2, 3):  # Java/Saturating semantics
            if IsNaN(rnd) then
                result <- [0] * 64
            else if bfp_COMPARE_GT(rnd, range_max) then
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else if bfp_COMPARE_LT(rnd, range_min) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if IT[1] = 1 then  # Unsigned 32/64-bit
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else  # Signed 32/64-bit
                result <- si64_CONVERT_FROM_BFP(range_max)
        default:  # JavaScript semantics
            # CVM = 6, 7 are illegal instructions
            # this works because the largest type we try to convert from has
            # 53 significand bits, and the largest type we try to convert to
            # has 64 bits, and the sum of those is strictly less than the 128
            # bits of the intermediate result.
            limit <- bfp_CONVERT_FROM_UI128([1] * 128)
            if IsInf(rnd) or IsNaN(rnd) then
                result <- [0] * 64
            else if bfp_COMPARE_GT(bfp_ABSOLUTE(rnd), limit) then
                result <- [0] * 64
            else
                result128 <- si128_CONVERT_FROM_BFP(rnd)
                result <- result128[64:127] & js_mask

    switch(IT)
        case(0):  # Signed 32-bit
            result <- EXTS64(result[32:63])
            result_bfp <- bfp_CONVERT_FROM_SI32(result[32:63])
        case(1):  # Unsigned 32-bit
            result <- EXTZ64(result[32:63])
            result_bfp <- bfp_CONVERT_FROM_UI32(result[32:63])
        case(2):  # Signed 64-bit
            result_bfp <- bfp_CONVERT_FROM_SI64(result)
        default:  # Unsigned 64-bit
            result_bfp <- bfp_CONVERT_FROM_UI64(result)

    if vxsnan_flag = 1 then SetFX(FPSCR.VXSNAN)
    if vxcvi_flag = 1 then SetFX(FPSCR.VXCVI)
    if xx_flag = 1 then SetFX(FPSCR.XX)

    vx_flag <- vxsnan_flag | vxcvi_flag
    vex_flag <- FPSCR.VE & vx_flag

    if vex_flag = 0 then
        RT <- result
        FPSCR.FPRF <- undefined
        FPSCR.FR <- inc_flag
        FPSCR.FI <- xx_flag
        if IsNaN(src) or not bfp_COMPARE_EQ(src, result_bfp) then
            overflow <- 1  # signals SO only when OE = 1
    else
        FPSCR.FR <- 0
        FPSCR.FI <- 0
```

Convert from 32/64-bit float in FRB to a unsigned/signed 32/64-bit integer
in RT, with the conversion overflow/rounding semantics following the
chosen `CVM` value, following the usual 32-bit float in 64-bit float
format. `FPSCR` is modified and exceptions are raised as usual.

Both of these instructions have an Rc=1 mode which sets CR0 in the normal
way for any instructions producing a GPR result.  Additionally, when OE=1,
if the numerical value of the FP number is not 100% accurately preserved
(due to truncation or saturation and including when the FP number was
NaN) then this is considered to be an integer Overflow condition, and
CR0.SO, XER.SO and XER.OV are all set as normal for any GPR instructions
that overflow.

Special Registers altered:

    CR0              (if Rc=1)
    XER SO, OV, OV32 (if OE=1)
    FPCSR   (TODO: which bits?)

### Assembly Aliases

For brevity, `[o]` is used to mean `o` is optional there.

| Assembly Alias               | Full Instruction               | Assembly Alias               | Full Instruction               |
|------------------------------|--------------------------------|------------------------------|--------------------------------|
| `fcvttgw[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 0, 0` | `fcvttgd[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 2, 0` |
| `fcvttgw[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 1` | `fcvttgd[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 1` |
| `fcvtstgw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 2` | `fcvtstgd[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 2` |
| `fcvtstgw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 0, 3` | `fcvtstgd[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 2, 3` |
| `fcvttguw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 1, 0` | `fcvttgud[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 3, 0` |
| `fcvttguw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 1` | `fcvttgud[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 1` |
| `fcvtstguw[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 2` | `fcvtstgud[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 2` |
| `fcvtstguw[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 1, 3` | `fcvtstgud[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 3, 3` |

## Floating-point Convert To GPR

| 0-5 | 6-10 | 11-12 | 13-15 | 16-20 | 21-28 | 29     | 30 |  31    | Form    |
|-----|------|-------|-------|-------|-------|--------|----|--------|---------|
| PO  | RT   | IT    | CVM   | FRB   | XO    | RCS[0] | OE | RCS[1] | XO-Form |

`fcvttg RT, FRB, CVM, IT, RCS`
`fcvttgo RT, FRB, CVM, IT, RCS`

```
    # based on xscvdpuxws
    reset_xflags()
    if RCS[0] = 1 then  # if Single mode
        src <- bfp_CONVERT_FROM_BFP32(SINGLE((FRB)))
    else
        src <- bfp_CONVERT_FROM_BFP64((FRB))

    switch(IT)
        case(0):  # Signed 32-bit
            range_min <- bfp_CONVERT_FROM_SI32(0x8000_0000)
            range_max <- bfp_CONVERT_FROM_SI32(0x7FFF_FFFF)
            js_mask <- 0xFFFF_FFFF
        case(1):  # Unsigned 32-bit
            range_min <- bfp_CONVERT_FROM_UI32(0)
            range_max <- bfp_CONVERT_FROM_UI32(0xFFFF_FFFF)
            js_mask <- 0xFFFF_FFFF
        case(2):  # Signed 64-bit
            range_min <- bfp_CONVERT_FROM_SI64(-0x8000_0000_0000_0000)
            range_max <- bfp_CONVERT_FROM_SI64(0x7FFF_FFFF_FFFF_FFFF)
            js_mask <- 0xFFFF_FFFF_FFFF_FFFF
        default:  # Unsigned 64-bit
            range_min <- bfp_CONVERT_FROM_UI64(0)
            range_max <- bfp_CONVERT_FROM_UI64(0xFFFF_FFFF_FFFF_FFFF)
            js_mask <- 0xFFFF_FFFF_FFFF_FFFF

    if CVM[2] = 1 or FPSCR.RN = 0b01 then
        rnd <- bfp_ROUND_TO_INTEGER_TRUNC(src)
    else if FPSCR.RN = 0b00 then
        rnd <- bfp_ROUND_TO_INTEGER_NEAR_EVEN(src)
    else if FPSCR.RN = 0b10 then
        rnd <- bfp_ROUND_TO_INTEGER_CEIL(src)
    else if FPSCR.RN = 0b11 then
        rnd <- bfp_ROUND_TO_INTEGER_FLOOR(src)

    switch(CVM)
        case(0, 1):  # OpenPower semantics
            if IsNaN(rnd) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if bfp_COMPARE_GT(rnd, range_max) then
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else if bfp_COMPARE_LT(rnd, range_min) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if IT[1] = 1 then  # Unsigned 32/64-bit
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else  # Signed 32/64-bit
                result <- si64_CONVERT_FROM_BFP(range_max)
        case(2, 3):  # Java/Saturating semantics
            if IsNaN(rnd) then
                result <- [0] * 64
            else if bfp_COMPARE_GT(rnd, range_max) then
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else if bfp_COMPARE_LT(rnd, range_min) then
                result <- si64_CONVERT_FROM_BFP(range_min)
            else if IT[1] = 1 then  # Unsigned 32/64-bit
                result <- ui64_CONVERT_FROM_BFP(range_max)
            else  # Signed 32/64-bit
                result <- si64_CONVERT_FROM_BFP(range_max)
        default:  # JavaScript semantics
            # CVM = 6, 7 are illegal instructions
            # this works because the largest type we try to convert from has
            # 53 significand bits, and the largest type we try to convert to
            # has 64 bits, and the sum of those is strictly less than the 128
            # bits of the intermediate result.
            limit <- bfp_CONVERT_FROM_UI128([1] * 128)
            if IsInf(rnd) or IsNaN(rnd) then
                result <- [0] * 64
            else if bfp_COMPARE_GT(bfp_ABSOLUTE(rnd), limit) then
                result <- [0] * 64
            else
                result128 <- si128_CONVERT_FROM_BFP(rnd)
                result <- result128[64:127] & js_mask

    switch(IT)
        case(0):  # Signed 32-bit
            result <- EXTS64(result[32:63])
            result_bfp <- bfp_CONVERT_FROM_SI32(result[32:63])
        case(1):  # Unsigned 32-bit
            result <- EXTZ64(result[32:63])
            result_bfp <- bfp_CONVERT_FROM_UI32(result[32:63])
        case(2):  # Signed 64-bit
            result_bfp <- bfp_CONVERT_FROM_SI64(result)
        default:  # Unsigned 64-bit
            result_bfp <- bfp_CONVERT_FROM_UI64(result)

    if vxsnan_flag = 1 then SetFX(FPSCR.VXSNAN)
    if vxcvi_flag = 1 then SetFX(FPSCR.VXCVI)
    if xx_flag = 1 then SetFX(FPSCR.XX)

    vx_flag <- vxsnan_flag | vxcvi_flag
    vex_flag <- FPSCR.VE & vx_flag

    if vex_flag = 0 then
        RT <- result
        FPSCR.FPRF <- undefined
        FPSCR.FR <- inc_flag
        FPSCR.FI <- xx_flag
        if IsNaN(src) or not bfp_COMPARE_EQ(src, result_bfp) then
            overflow <- 1  # signals SO only when OE = 1
    else
        FPSCR.FR <- 0
        FPSCR.FI <- 0
```

Convert from 32/64-bit float in FRB to a unsigned/signed 32/64-bit integer
in RT, with the conversion overflow/rounding semantics following the
chosen `CVM` value, following the usual 32-bit float in 64-bit float
format. `FPSCR` is modified and exceptions are raised as usual.

Both of these instructions have an Rc=1 mode which sets CR0 in the normal
way for any instructions producing a GPR result.  Additionally, when OE=1,
if the numerical value of the FP number is not 100% accurately preserved
(due to truncation or saturation and including when the FP number was
NaN) then this is considered to be an integer Overflow condition, and
CR0.SO, XER.SO and XER.OV are all set as normal for any GPR instructions
that overflow.

Special Registers altered:

    CR0              (if Rc=1)
    XER SO, OV, OV32 (if OE=1)
    FPCSR   (TODO: which bits?)

### Assembly Aliases

For brevity, `[o]` is used to mean `o` is optional there.

| Assembly Alias               | Full Instruction               | Assembly Alias               | Full Instruction               |
|------------------------------|--------------------------------|------------------------------|--------------------------------|
| `fcvttgw[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 0, 0` | `fcvttgd[o] RT, FRB, CVM`    | `fcvttg[o] RT, FRB, CVM, 2, 0` |
| `fcvttgw[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 1` | `fcvttgd[o]. RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 1` |
| `fcvtstgw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 0, 2` | `fcvtstgd[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 2, 2` |
| `fcvtstgw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 0, 3` | `fcvtstgd[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 2, 3` |
| `fcvttguw[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 1, 0` | `fcvttgud[o] RT, FRB, CVM`   | `fcvttg[o] RT, FRB, CVM, 3, 0` |
| `fcvttguw[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 1` | `fcvttgud[o]. RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 1` |
| `fcvtstguw[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 1, 2` | `fcvtstgud[o] RT, FRB, CVM`  | `fcvttg[o] RT, FRB, CVM, 3, 2` |
| `fcvtstguw[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 1, 3` | `fcvtstgud[o]. RT, FRB, CVM` | `fcvttg[o] RT, FRB, CVM, 3, 3` |