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

twi — Trap Word Immediate

Category: Branch & System · Form: D · Opcode: 0x0c000000

Assembler Mnemonics

Mnemonic	XML entry	Flags	Description
twi	twi	—	Trap Word Immediate

Syntax

tw [TO], [RA], [SIMM]

Encoding

twi — form D

• Opcode word: 0x0c000000
• Primary opcode (bits 0–5): 3
• Extended opcode: —
• Synchronising: no

Bits	Field	Meaning
0–5	OPCD	primary opcode
6–10	RT	destination GPR (or RS when storing)
11–15	RA	source GPR (0 ⇒ literal 0 for RA0 forms)
16–31	D/SI/UI	16-bit signed or unsigned immediate

Operands

Field	Role	Description
TO	twi: read	Trap-on condition mask (5 bits) — LT, GT, EQ, LGT, LLT bits.
RA	twi: read	Source GPR (r0–r31).
SIMM	twi: read	16-bit signed immediate. Sign-extended to 64 bits before use.

Register Effects

twi

• Reads (always): TO, RA, SIMM
• 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

twi

• Canary XML: tools/ppc-instructions.xml — search for mnem="twi"
• Canary emitter: src/xenia/cpu/ppc/ppc_emit_control.cc:603
• Sylpheed opcode: crates/sylpheed-ppc/src/opcode.rs:293
• Sylpheed decoder: crates/sylpheed-ppc/src/decoder.rs:443

Canary emitter (frozen snapshot @ f21ebd49e9)

int InstrEmit_twi(PPCHIRBuilder& f, const InstrData& i) {
  if (cvars::ignore_trap_instructions) {
    return 0;
  }
  // a <- EXTS((RA)[32:63])
  // if (a < EXTS(SI)) & TO[0] then TRAP
  // if (a > EXTS(SI)) & TO[1] then TRAP
  // if (a = EXTS(SI)) & TO[2] then TRAP
  // if (a <u EXTS(SI)) & TO[3] then TRAP
  // if (a >u EXTS(SI)) & TO[4] then TRAP
  if (i.D.RA == 0 && i.D.RT == 0x1F) {
    // This is a special trap. Probably.
    uint16_t type = (uint16_t)XEEXTS16(i.D.DS);
    f.Trap(type);
    return 0;
  }
  Value* ra =
      f.SignExtend(f.Truncate(f.LoadGPR(i.D.RA), INT32_TYPE), INT64_TYPE);
  Value* rb = f.LoadConstantInt64(XEEXTS16(i.D.DS));
  return InstrEmit_trap(f, i, ra, rb, i.D.RT);
}

Special Cases & Edge Conditions

• 32-bit comparison against sign-extended immediate. SIMM is a 16-bit signed value, sign-extended to 32 bits, then compared against the low 32 bits of RA. The high half of RA is ignored.
• TO mask. Identical to tw: bit 0 = signed LT, 1 = signed GT, 2 = EQ, 3 = unsigned LT (LGT), 4 = unsigned GT (LLT). Trap fires if any selected bit's condition is true.
• twi 31, 0, 0 is unconditional trap. All TO bits set ⇒ guaranteed trap. The simplified mnemonic family (twnei, twgei, …) is much more common in real code: bound checks, null checks, integer-divide-by-zero pre-checks.
• Compiler usage. Xbox 360 GCC emits twnei rN, -1 and similar to validate handle-style return values; the kernel handler turns the trap into an exception delivered to the title.
• No register effects. Side effect: Program interrupt → vector 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. twi 0, r0, 0 therefore falls through. One special case: twi 31, r0, <imm> (TO = 31, RA = 0) becomes an unconditional Trap carrying <imm> as its type.
• No Rc / OE. D-form trap immediates have neither.

Related Instructions

• tw — register-register 32-bit trap (X-form).
• tdi / td — 64-bit (doubleword) siblings.
• sc — alternative synchronous kernel entry.
• cmpi, cmpli — set CR for a subsequent bcx when you want a regular branch instead of a trap.

Simplified Mnemonics

Simplified	Expansion	Triggered when
tweqi RA, value	twi 4, RA, value	RA == EXTS(value)
twnei RA, value	twi 24, RA, value	RA != EXTS(value)
twlti RA, value	twi 16, RA, value	signed less than
twlei RA, value	twi 20, RA, value	signed less or equal
twgti RA, value	twi 8, RA, value	signed greater than
twgei RA, value	twi 12, RA, value	signed greater or equal
twllti RA, value	twi 2, RA, value	unsigned less than
twlgei RA, value	twi 5, RA, value	unsigned greater or equal
twlgti RA, value	twi 1, RA, value	unsigned greater than
twllei RA, value	twi 6, RA, value	unsigned less or equal

IBM Reference

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