xenia-rs/migration/project-root/ppc-manual/fpu/fcmpo.md

# `fcmpo` — Floating Compare Ordered

> **Category:** [Floating-Point](../categories/fpu.md) · **Form:** [X](../forms/X.md) · **Opcode:** `0xfc000040`

<!-- GENERATED: BEGIN -->

## Assembler Mnemonics

| Mnemonic | XML entry | Flags | Description |
| --- | --- | --- | --- |
| `fcmpo` | `fcmpo` | — | Floating Compare Ordered |

## Syntax

```asm
fcmpo [CRFD], [FA], [FB]
```

## Encoding

### `fcmpo` — form `X`

- **Opcode word:** `0xfc000040`
- **Primary opcode (bits 0–5):** `63`
- **Extended opcode:** `32`
- **Synchronising:** no

| Bits | Field | Meaning |
| --- | --- | --- |
| 0–5 | `OPCD` | primary opcode |
| 6–10 | `RT/FRT/VRT` | destination |
| 11–15 | `RA/FRA/VRA` | source A |
| 16–20 | `RB/FRB/VRB` | source B |
| 21–30 | `XO` | extended opcode (10 bits) |
| 31 | `Rc` | record-form flag |

## Operands

| Field | Role | Description |
| --- | --- | --- |
| `FA` | fcmpo: read | Source A floating-point register (`fr0`–`fr31`). |
| `FB` | fcmpo: read | Source B floating-point register. |
| `CRFD` | fcmpo: write | CR destination field (`crf`, 0–7). |
| `FPSCR` | fcmpo: write | Floating-Point Status and Control Register. |

## Register Effects

### `fcmpo`

- **Reads (always):** `FA`, `FB`
- **Reads (conditional):** _none_
- **Writes (always):** `CRFD`, `FPSCR`
- **Writes (conditional):** _none_

## Status-Register Effects

- `fcmpo`: **FPSCR** updated per IEEE-754 flags (FX, FEX, FPRF, FR, FI, exceptions).

## Operation (pseudocode)

```
; Pseudocode derives directly from the xenia-rs interpreter
; arm (see Implementation References). Operation semantics:
;   - Read source operands from the fields listed under Operands.
;   - Apply the arithmetic / logical / memory action described
;     in the Description field above.
;   - Write results to the destination register(s); update any
;     status bits enumerated under Status-Register Effects.
; Consult the IBM AIX reference link under IBM Reference for
; canonical PPC-style pseudocode where xenia's expression is
; terse.
```

## C Translation Example

```c
/* C translation: the xenia-rs interpreter arm below in           */
/* Implementation References is the authoritative semantic        */
/* snapshot. Translate it line-by-line:                            */
/*   - ctx.gpr[N]  -> r[N]       (or f[]/v[] for FPRs/VRs)        */
/*   - mem.read_u*/write_u* -> mem_read_u*_be / mem_write_u*_be   */
/*   - ctx.update_cr_signed(fld, v) -> update_cr_signed(fld, v)   */
/*   - ctx.xer_ca / xer_ov / xer_so -> xer.CA / xer.OV / xer.SO   */
/* The Register Effects and Status-Register Effects tables above  */
/* enumerate every side effect a faithful translation must emit.  */
```

## Implementation References

**`fcmpo`**
- xenia-canary XML: [`tools/ppc-instructions.xml` — search for `mnem="fcmpo"`](../../xenia-canary/tools/ppc-instructions.xml)
- xenia-canary emit: [`src/xenia/cpu/ppc/ppc_emit_fpu.cc:362`](../../xenia-canary/src/xenia/cpu/ppc/ppc_emit_fpu.cc#L362)
- xenia-rs opcode: [`crates/xenia-cpu/src/opcode.rs:27`](../../xenia-rs/crates/xenia-cpu/src/opcode.rs#L27)
- xenia-rs decoder: [`crates/xenia-cpu/src/decoder.rs:901`](../../xenia-rs/crates/xenia-cpu/src/decoder.rs#L901)
- xenia-rs interpreter: [`crates/xenia-cpu/src/interpreter.rs:3002-3032`](../../xenia-rs/crates/xenia-cpu/src/interpreter.rs#L3002-L3032)
<details><summary>xenia-rs interpreter body (frozen snapshot)</summary>

```rust
        PpcOpcode::fcmpo => {
            // Ordered compare: like fcmpu but also sets VXVC on QNaN (or VXSNAN on SNaN).
            let fra = ctx.fpr[instr.ra()];
            let frb = ctx.fpr[instr.rb()];
            let crfd = instr.crfd();
            if fra.is_nan() || frb.is_nan() {
                ctx.cr[crfd] = crate::context::CrField { lt: false, gt: false, eq: false, so: true };
                if fpscr::is_snan(fra) || fpscr::is_snan(frb) {
                    fpscr::set_exception(ctx, fpscr::VXSNAN | fpscr::VXVC);
                } else {
                    fpscr::set_exception(ctx, fpscr::VXVC);
                }
            } else if fra < frb {
                ctx.cr[crfd] = crate::context::CrField { lt: true, gt: false, eq: false, so: false };
            } else if fra > frb {
                ctx.cr[crfd] = crate::context::CrField { lt: false, gt: true, eq: false, so: false };
            } else {
                ctx.cr[crfd] = crate::context::CrField { lt: false, gt: false, eq: true, so: false };
            }
            let fprf = if fra.is_nan() || frb.is_nan() {
                0b0_0001
            } else if fra < frb {
                0b0_1000
            } else if fra > frb {
                0b0_0100
            } else {
                0b0_0010
            };
            fpscr::set_fprf(ctx, fprf);
            ctx.pc += 4;
        }
```
</details>

<!-- GENERATED: END -->

## Special Cases & Edge Conditions

- **Ordered compare.** Same CR-field semantics as `fcmpu` (`LT/GT/EQ/SO`), but NaN inputs raise additional FPSCR exceptions:
  - Either operand NaN → `FPSCR[VXVC] = 1` (invalid-operation: compare on QNaN/SNaN).
  - Either operand signalling NaN → also `FPSCR[VXSNAN] = 1`.
  - All NaN cases also set `FX = 1` and `VX = 1`.
- **xenia quirk.** xenia-rs's `fcmpo` body is identical to `fcmpu` — the FPSCR exception bits are not modelled. The xenia source comment explicitly notes "Same as fcmpu but sets FPSCR exception bits for QNaN (not modeled yet)". Title code that polls FPSCR for compare-class invalid-operation will not observe it.
- **CR field bits.**
  - `LT` (bit 0) — `FRA < FRB`
  - `GT` (bit 1) — `FRA > FRB`
  - `EQ` (bit 2) — `FRA == FRB`
  - `SO` (bit 3) — unordered (NaN involved)
- **`+0` and `-0` compare equal.**
- **No `Rc` bit.**
- **FPSCR side effects.** Hardware updates `FPSCR[FPCC]`, `FX`, `VX`, and (on NaN) `VXVC`/`VXSNAN`. xenia-rs only updates the CR field.
- **Use case.** Ordered compares are required by C/C++ semantics for `<`, `>`, `<=`, `>=` (which must signal on NaN per IEEE-754). `fcmpu` corresponds to the C `==`/`!=` semantics (which do not signal).
- **Encoding.** X-form, primary 63, XO 32.

## Related Instructions

- [`fcmpux`](fcmpu.md) — unordered compare; identical CR result, no `VXVC`.
- `mcrf`, `mcrfs`, `mfcr` — fan-out CR fields after compare.
- `bc`, `bclr`, `bcctr` — conditional branches consume `LT/GT/EQ/SO`.
- [`fselx`](fselx.md) — branch-free alternative for single-key compares.
- [`mcrfs`](mcrfs.md), [`mffsx`](mffsx.md) — move FPSCR/CR.

## IBM Reference

- [AIX 7.3 — `fcmpo` (Floating Compare Ordered)](https://www.ibm.com/docs/en/aix/7.3.0?topic=set-fcmpo-floating-compare-ordered-instruction)
- [PowerISA v2.07B, Book I, Chapter 4 — Floating-Point Processor](https://openpowerfoundation.org/specifications/isa/) (`fcmpo` raises `VXVC` on QNaN; both raise `VXSNAN` on SNaN).