xenia-rs/migration/project-root/ppc-manual/alu/addi.md

addi — Add Immediate

Category: Integer ALU · Form: D · Opcode: 0x38000000

Assembler Mnemonics

Mnemonic	XML entry	Flags	Description
addi	addi	—	Add Immediate

Syntax

addi [RD], [RA0], [SIMM]

Encoding

addi — form D

• Opcode word: 0x38000000
• Primary opcode (bits 0–5): 14
• 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
RA0	addi: read	Source GPR; when the encoded register number is 0 the operand is the literal 64-bit zero, not r0.
SIMM	addi: read	16-bit signed immediate. Sign-extended to 64 bits before use.
RD	addi: write	Destination GPR.

Register Effects

addi

• Reads (always): RA0, SIMM
• Reads (conditional): none
• Writes (always): RD
• Writes (conditional): none

Status-Register Effects

No condition-register or status-register effects.

Operation (pseudocode)

if RA = 0 then RT <- EXTS(SIMM)
else             RT <- (RA) + EXTS(SIMM)

C Translation Example

/* addi RT, RA, SIMM   — RA=0 means literal 0                      */
uint64_t base = (insn.RA == 0) ? 0 : r[insn.RA];
r[insn.RT] = base + (uint64_t)(int64_t)(int16_t)insn.SIMM;

Implementation References

addi

• xenia-canary XML: tools/ppc-instructions.xml — search for mnem="addi"
• xenia-canary emit: src/xenia/cpu/ppc/ppc_emit_alu.cc:103
• xenia-rs opcode: crates/xenia-cpu/src/opcode.rs:8
• xenia-rs decoder: crates/xenia-cpu/src/decoder.rs:338
• xenia-rs interpreter: crates/xenia-cpu/src/interpreter.rs:114-120

xenia-rs interpreter body (frozen snapshot)

        PpcOpcode::addi => {
            // PPCBUG-001: 32-bit ABI. `li rT, -1` (= addi rT, r0, -1) must produce
            // 0x00000000_FFFFFFFF, not 0xFFFFFFFF_FFFFFFFF (sign-extended simm16).
            let ra_val = if instr.ra() == 0 { 0 } else { ctx.gpr[instr.ra()] };
            ctx.gpr[instr.rd()] = ra_val.wrapping_add(instr.simm16() as i64 as u64) as u32 as u64;
            ctx.pc += 4;
        }

Special Cases & Edge Conditions

• RA0 semantics. When the encoded RA field is 0 the operand is the literal constant 0, not the value of r0. This lets addi rT, 0, SIMM load a constant (the li rT, SIMM simplified mnemonic). To use r0's value you must use a register-register add (add RT, r0, RB through a temp) or an instruction without RA0 semantics.
• No flags written. Unlike add, addi cannot be Rc or OE — no CR or XER update. Use addic if you need XER[CA], or addicx (addic.) if you need both XER[CA] and a CR0 update.
• Immediate is 16-bit signed (SIMM, range −32768 … +32767), sign-extended to 64 bits before the add. No carry/overflow is produced regardless of the result.
• Simplified mnemonics. Assemblers recognise several aliases that all assemble to addi:
  • li RT, SIMM ≡ addi RT, 0, SIMM (load immediate; relies on RA0).
  • la RT, D(RA) ≡ addi RT, RA, D (load address; purely syntactic).
  • subi RT, RA, SIMM ≡ addi RT, RA, −SIMM.
• PC-relative idiom. addi RT, RA, D is the low-half completion of a two-instruction address load preceded by addis RT, 0, HI. The assembler emits @ha/@l relocations so the low half can be negative without corrupting the high half (add-compensation).

Related Instructions

• addis — same encoding family but the immediate is shifted left by 16 bits. Together they build any 32-bit constant or PC-relative address.
• addic, addicx — D-form adds that do set XER[CA] (and CR0 for the record form).
• addx — the register-register form.
• subfic — reverse-subtract immediate (imm − RA) with carry.
• ori, oris — the alternative D-form constant-building instructions (but these don't add, they OR).

IBM Reference

• AIX 7.3 — addi (Add Immediate)
• AIX 7.3 — li (Load Immediate, simplified mnemonic)