Sylpheed/tools/ppc-manual/alu/rlwimix.md

rlwimix — Rotate Left Word Immediate then Mask Insert

Category: Integer ALU · Form: M · Opcode: 0x50000000

Assembler Mnemonics

Mnemonic	XML entry	Flags	Description
rlwimi	rlwimix	—	Rotate Left Word Immediate then Mask Insert
rlwimi.	rlwimix	Rc=1	Rotate Left Word Immediate then Mask Insert

Syntax

rlwimi[Rc] [RA], [RS], [SH], [MB], [ME]

Encoding

rlwimix — form M

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

Bits	Field	Meaning
0–5	OPCD	primary opcode
6–10	RS	source GPR
11–15	RA	destination GPR
16–20	SH/RB	shift amount or source B
21–25	MB	mask begin
26–30	ME	mask end
31	Rc	record-form flag

Operands

Field	Role	Description
RS	rlwimix: read	Source GPR (alias for RD in some stores).
SH	rlwimix: read	Shift amount.
MB	rlwimix: read	Mask begin bit.
ME	rlwimix: read	Mask end bit.
RA	rlwimix: write	Source GPR (r0–r31).
CR	rlwimix: write (conditional)	Condition-register update. When Rc=1, CR field 0 (or CR6 for vector compares, CR1 for FPU) is updated from the result.

Register Effects

rlwimix

• Reads (always): RS, SH, MB, ME
• Reads (conditional): none
• Writes (always): RA
• Writes (conditional): CR

Status-Register Effects

• rlwimix: CR0 ← signed-compare(result, 0) with SO ← XER[SO], when Rc=1.

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

rlwimix

• Canary XML: tools/ppc-instructions.xml — search for mnem="rlwimix"
• Canary emitter: src/xenia/cpu/ppc/ppc_emit_alu.cc:1010
• Sylpheed opcode: crates/sylpheed-ppc/src/opcode.rs:210
• Sylpheed decoder: crates/sylpheed-ppc/src/decoder.rs:459

Canary emitter (frozen snapshot @ f21ebd49e9)

int InstrEmit_rlwimix(PPCHIRBuilder& f, const InstrData& i) {
  // n <- SH
  // r <- ROTL32((RS)[32:63], n)
  // m <- MASK(MB+32, ME+32)
  // RA <- r&m | (RA)&¬m
  Value* v = f.LoadGPR(i.M.RT);
  // (x||x)
  v = f.Or(f.Shl(v, 32), f.ZeroExtend(f.Truncate(v, INT32_TYPE), INT64_TYPE));
  if (i.M.SH) {
    v = f.RotateLeft(v, f.LoadConstantInt8(i.M.SH));
  }
  // Compiler sometimes masks with 0xFFFFFFFF (identity) - avoid the work here
  // as our truncation/zero-extend does it for us.
  uint64_t m = XEMASK(i.M.MB + 32, i.M.ME + 32);
  if (m != 0xFFFFFFFFFFFFFFFFull) {
    v = f.And(v, f.LoadConstantUint64(m));
  }
  v = f.Or(v, f.And(f.LoadGPR(i.M.RA), f.LoadConstantUint64(~m)));
  f.StoreGPR(i.M.RA, v);
  if (i.M.Rc) {
    f.UpdateCR(0, v);
  }
  return 0;
}

Special Cases & Edge Conditions

• RA ← (ROTL32(RS[32:63], SH) & MASK) | (RA & ~MASK). Reads the low 32 bits of RS, rotates them, then inserts under the mask. The high 32 bits of RA are implementation-defined per spec. Canary rotates a doubled word ((RS << 32) | RS[32:63]), masks it with XEMASK(MB + 32, ME + 32) and ORs back RA & ~mask — so for a contiguous mask (MB ≤ ME) RA's high 32 bits are preserved, not zeroed.
• Mask follows the standard MB..ME PPC convention. Both are 5-bit fields; the mask is contiguous when MB <= ME and wraps (a "donut" mask: bits MB..31 and 0..ME) when MB > ME. Canary computes it as XEMASK(MB + 32, ME + 32) on the 64-bit word, which gives the right low word in both cases.
• SH is 5 bits. Rotate amount is SH mod 32; values ≥ 32 are not encodable in this M-form.
• Used for bit-field insertion (insrwi RA, RS, n, b ≡ rlwimi RA, RS, 32-(b+n), b, b+n-1). Compilers emit rlwimi extensively for struct-bitfield writes.
• Rc=1 CR0 update truncates to 32 bits in Canary (f.UpdateCR(0, v)): it compares the low word only, while spec compares all 64 bits — including whatever RA kept in its high word.
• No XER effect.

Related Instructions

• rlwinmx — same mask family but zeroes outside (no read-modify-write).
• rlwnmx — register-shift variant of rlwinm.
• rldimix — 64-bit insert cousin.
• insrwi, inslwi (simplified mnemonics for common insert patterns).

IBM Reference

• AIX 7.3 — rlwimi (Rotate Left Word Immediate then Mask Insert)