xenia-rs/migration/project-root/ppc-manual/control/mftb.md

# `mftb` — Move from Time Base

> **Category:** [Control / CR / SPR](../categories/control.md) · **Form:** [XFX](../forms/XFX.md) · **Opcode:** `0x7c0002e6`

<!-- GENERATED: BEGIN -->

## Assembler Mnemonics

| Mnemonic | XML entry | Flags | Description |
| --- | --- | --- | --- |
| `mftb` | `mftb` | — | Move from Time Base |

## Syntax

```asm
mftb [RD], [TBR]
```

## Encoding

### `mftb` — form `XFX`

- **Opcode word:** `0x7c0002e6`
- **Primary opcode (bits 0–5):** `31`
- **Extended opcode:** `371`
- **Synchronising:** no

| Bits | Field | Meaning |
| --- | --- | --- |
| 0–5 | `OPCD` | primary opcode (31) |
| 6–10 | `RT` | destination / source GPR |
| 11–20 | `spr/tbr/FXM` | SPR/TBR number (byte-swapped halves) or CR field mask |
| 21–30 | `XO` | extended opcode |
| 31 | `—` | reserved |

## Operands

| Field | Role | Description |
| --- | --- | --- |
| `TBR` | mftb: read | Time-Base Register selector for `mftb`. |
| `RD` | mftb: write | Destination GPR. |

## Register Effects

### `mftb`

- **Reads (always):** `TBR`
- **Reads (conditional):** _none_
- **Writes (always):** `RD`
- **Writes (conditional):** _none_

## Status-Register Effects

_No condition-register or status-register effects._

## 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

**`mftb`**
- xenia-canary XML: [`tools/ppc-instructions.xml` — search for `mnem="mftb"`](../../xenia-canary/tools/ppc-instructions.xml)
- xenia-canary emit: [`src/xenia/cpu/ppc/ppc_emit_control.cc:719`](../../xenia-canary/src/xenia/cpu/ppc/ppc_emit_control.cc#L719)
- xenia-rs opcode: [`crates/xenia-cpu/src/opcode.rs:53`](../../xenia-rs/crates/xenia-cpu/src/opcode.rs#L53)
- xenia-rs decoder: [`crates/xenia-cpu/src/decoder.rs:803`](../../xenia-rs/crates/xenia-cpu/src/decoder.rs#L803)
- xenia-rs interpreter: [`crates/xenia-cpu/src/interpreter.rs:1664-1672`](../../xenia-rs/crates/xenia-cpu/src/interpreter.rs#L1664-L1672)
<details><summary>xenia-rs interpreter body (frozen snapshot)</summary>

```rust
        PpcOpcode::mftb => {
            let tbr = instr.spr();
            ctx.gpr[instr.rd()] = match tbr {
                268 => ctx.timebase & 0xFFFF_FFFF,
                269 => ctx.timebase >> 32,
                _ => 0,
            };
            ctx.pc += 4;
        }
```
</details>

<!-- GENERATED: END -->

## Special Cases & Edge Conditions

- **Time-base register selectors.** The 10-bit `tbr` field encodes the same way as `mfspr`'s `spr` field (two halves swapped). The two values defined for the Xenon:

  | Decoded | Name | Meaning                                         |
  | ---     | ---  | ---                                             |
  | 268     | TBL  | Time Base, lower 32 bits                        |
  | 269     | TBU  | Time Base, upper 32 bits                        |

  Other selectors return 0 in xenia and are not used by titles.
- **Atomic 64-bit read pattern.** Because `mftb` reads only 32 bits at a time, software performs the canonical retry loop to avoid TBL→TBU rollover skew:
  ```asm
  retry:
      mftbu rH        ; read upper
      mftb  rL        ; read lower (TBR=268)
      mftbu rH2       ; read upper again
      cmpw  rH, rH2
      bne   retry
  ```
- **Xenon clock rate.** Real hardware ticks the time base at ~3.2 GHz (one tick per CPU clock divided by the architectural ratio). The PVR signature the kernel exposes (`0x00710800`) and the kernel-reported tick rate jointly let titles convert TB ticks to seconds.
- **xenia behaviour.** xenia-rs stores `ctx.timebase` as a `u64` and **increments it once per interpreted instruction**, not per real-time wall clock. This guarantees deterministic replay (same trace ⇒ same TB readings) at the cost of decoupling guest time from host time. Games that rely on TB for real-time sync will run faster or slower depending on host throughput.
- **`mftb RT` (no operand)** is the simplified mnemonic for `mftb RT, 268` — read the lower half. `mftbu RT` ≡ `mftb RT, 269`.
- **Deprecated alternative.** `mfspr RT, 268`/`269` works on the Xenon (xenia accepts both) but post-PowerISA v2.06 deprecated reading TB through `mfspr`. Prefer `mftb`.

## Related Instructions

- [`mfspr`](mfspr.md) — generic SPR read; can also read TBL/TBU on Xenon (deprecated).
- [`mtspr`](mtspr.md) — TBL/TBU writes are privileged; not user-accessible.
- [`isync`](mtmsr.md) — context-synchronising fence sometimes paired with `mftb` for tight measurement loops.

### Simplified Mnemonics

| Simplified | Expansion          | Notes |
| ---        | ---                | --- |
| `mftb  RT` | `mftb RT, 268`     | read TBL |
| `mftbu RT` | `mftb RT, 269`     | read TBU |

## IBM Reference

- [AIX 7.3 — `mftb` (Move from Time Base)](https://www.ibm.com/docs/en/aix/7.3.0?topic=set-mftb-move-from-time-base-instruction)
- PowerISA v2.07B, Book II §6.1 — Time Base description and the canonical 64-bit read sequence.