Sylpheed/tools/ppc-manual/branch/tw.md

tw — Trap Word

Category: Branch & System · Form: X · Opcode: 0x7c000008

Assembler Mnemonics

Mnemonic	XML entry	Flags	Description
tw	tw	—	Trap Word

Syntax

tw [TO], [RA], [RB]

Encoding

tw — form X

• Opcode word: 0x7c000008
• Primary opcode (bits 0–5): 31
• Extended opcode: 4
• 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
TO	tw: read	Trap-on condition mask (5 bits) — LT, GT, EQ, LGT, LLT bits.
RA	tw: read	Source GPR (r0–r31).
RB	tw: read	Source GPR.

Register Effects

tw

• Reads (always): TO, RA, RB
• Reads (conditional): none
• Writes (always): none
• Writes (conditional): none

Status-Register Effects

No condition-register or status-register effects.

Operation (pseudocode)

; No hand-written pseudocode for this instruction yet.
; The authoritative semantics are the Canary emitter snapshot under
; Implementation References; about half of Canary's emitters open
; with the PPC-style definition as a comment (`RD <- (RA) + (RB)`).
; Every side effect is also enumerated in the Register Effects and
; Status-Register Effects tables above.

C Translation Example

/* No hand-written C yet. Translate the Canary emitter snapshot   */
/* under Implementation References; its HIR maps directly:        */
/*   f.LoadGPR(n) / f.StoreGPR(n, v)  -> r[n] / r[n] = v          */
/*   f.LoadFPR / StoreFPR, f.LoadVR / StoreVR -> f[n], v[n]        */
/*   f.Load(ea, T), f.Store(ea, v) -> raw read / write; emitters   */
/*     wrap them in f.ByteSwap for the big-endian guest value      */
/*   f.UpdateCR(n, v)  -> CR field n from v's LOW 32 BITS vs 0     */
/*   f.LoadCA / f.StoreCA -> xer.CA;  f.StoreSAT -> vscr.SAT       */
/*   i.XO.RA, i.D.DS, ... -> the bit-fields listed under Operands  */
/* The Register Effects and Status-Register Effects tables above  */
/* enumerate every side effect a faithful translation must emit.  */

Implementation References

tw

• Canary XML: tools/ppc-instructions.xml — search for mnem="tw"
• Canary emitter: src/xenia/cpu/ppc/ppc_emit_control.cc:585
• Sylpheed opcode: crates/sylpheed-ppc/src/opcode.rs:292
• Sylpheed decoder: crates/sylpheed-ppc/src/decoder.rs:865

Canary emitter (frozen snapshot @ f21ebd49e9)

int InstrEmit_tw(PPCHIRBuilder& f, const InstrData& i) {
  if (cvars::ignore_trap_instructions) {
    return 0;
  }
  // a <- EXTS((RA)[32:63])
  // b <- EXTS((RB)[32:63])
  // if (a < b) & TO[0] then TRAP
  // if (a > b) & TO[1] then TRAP
  // if (a = b) & TO[2] then TRAP
  // if (a <u b) & TO[3] then TRAP
  // if (a >u b) & TO[4] then TRAP
  Value* ra =
      f.SignExtend(f.Truncate(f.LoadGPR(i.X.RA), INT32_TYPE), INT64_TYPE);
  Value* rb =
      f.SignExtend(f.Truncate(f.LoadGPR(i.X.RB), INT32_TYPE), INT64_TYPE);
  return InstrEmit_trap(f, i, ra, rb, i.X.RT);
}

Special Cases & Edge Conditions

• 32-bit comparison only. tw compares the low 32 bits of RA and RB. The high halves of the 64-bit GPRs on the Xenon are ignored. Use td for full 64-bit comparisons.

• TO mask (5 bits, MSB-first). Same encoding as the doubleword form:

  Bit	Mnemonic	Triggered when
  TO[0] (16)	LT	(int32) RA < (int32) RB
  TO[1] (8)	GT	(int32) RA > (int32) RB
  TO[2] (4)	EQ	(uint32) RA == (uint32) RB
  TO[3] (2)	LGT	(uint32) RA < (uint32) RB
  TO[4] (1)	LLT	(uint32) RA > (uint32) RB

• tw 31, 0, 0 is trap. The simplified mnemonic trap expands to tw 31, r0, r0 — all five TO bits set ⇒ unconditional trap. Compilers and the kernel use this as the assertion / debugger break primitive; it appears as 0x7FE00008 in raw bytes.

• Conditional asserts. GCC's __builtin_trap and MSVC's __assert macros emit tw variants like twge/twlt to fault on bound-check failures.

• No register effects. Side effect only: Program interrupt (0x700) with SRR1[TRAP]=1.

• Canary evaluates the condition. Canary evaluates TO properly: it compares the operands for each set bit and emits a conditional trap (TrapTrue), and TO = 0 emits nothing. tw compares the sign-extended low 32 bits of both operands, and inert markers like tw 0, r0, r0 fall through.

• Inert encoding. tw 0, r0, r0 (no TO bits set) can never trap on real hardware, and Canary emits nothing for TO = 0. It encodes as 0x7C000008 — sometimes used as a structured-NOP marker.

Related Instructions

• twi — same 32-bit comparison against a 16-bit signed immediate.
• td / tdi — 64-bit (doubleword) variants.
• sc — kernel entry via system-call exception (different vector).
• mtmsr — kernel returns from 0x700 via rfid.

Simplified Mnemonics

Simplified	Expansion	Triggered when
trap	tw 31, 0, 0	unconditional
tweq RA, RB	tw 4, RA, RB	RA == RB
twne RA, RB	tw 24, RA, RB	RA != RB
twlt RA, RB	tw 16, RA, RB	signed less than
twle RA, RB	tw 20, RA, RB	signed less or equal
twgt RA, RB	tw 8, RA, RB	signed greater than
twge RA, RB	tw 12, RA, RB	signed greater or equal
twllt RA, RB	tw 2, RA, RB	unsigned less than
twlge RA, RB	tw 5, RA, RB	unsigned greater or equal
twlgt RA, RB	tw 1, RA, RB	unsigned greater than
twlle RA, RB	tw 6, RA, RB	unsigned less or equal

IBM Reference

• AIX 7.3 — tw (Trap Word)
• AIX 7.3 — Trap simplified mnemonics
• PowerISA v2.07B, Book I §3.3.11 — fixed-point trap instructions.