RISC-V li Pseudo-Instruction Details

Assembler pseudo-instruction

Load-integer-immediate pseudo-instruction. The assembler chooses one or more real instructions according to the constant, XLEN, and available extensions; small signed 12-bit values can use ADDI, while larger constants commonly need LUI/ADDI or more steps.

What You Write

li rd, immediate

Typical Real Expansion

addi rd, x0, imm # or: assembler-selected multi-instruction sequence such as LUI/ADDI/ADDIW/SLLI as needed

What This Pseudo Instruction Is Saving You From Writing

A single instruction encodes at most 12-bit (ADDI) or 20-bit (LUI) immediates; li auto-selects the optimal sequence for any 32/64-bit constant, making it one of the most-used pseudo-instructions.

li primarily means "Load immediate into register". It is assembler-level shorthand; when debugging, auditing, or reading machine code, reason from the real expansion and relocation semantics listed on this page.

Official Semantics Checklist

The official assembly manual treats li as an assembler-level pseudo-instruction or alias; hardware executes the expanded real instruction sequence.

The real semantics come from the ISA definitions of ADDI and the other expanded instructions, not from a separate li hardware opcode.

Toolchain And Linker Boundaries

The official assembly manual defines the assembler-level intent of li; the assembler chooses the real sequence according to the constant, XLEN, and available extensions.

Do not treat the first expansion shown here as the only machine code; disassembly may show li or real LUI/ADDI/ADDIW/SLLI-style sequences.

How To Read The Expansion

Step 1

Small immediate (-2048~2047): ADDI rd, x0, imm — single instruction.

Step 2

Medium immediate (within 20 bits on RV32): LUI rd, imm[31:12] loads upper 20 bits; ADDI rd, rd, imm[11:0] adds lower 12 bits.

Step 3

Large immediate (RV64): may require ADDIW + SLLI shift then ADDI to construct a full 64-bit value.

What You May See In objdump / Disassembly

Disassembler shows LUI+ADDI combinations as li rd,imm. Small constants are a single ADDI; large constants may be LUI+ADDI pairs.

Official References And Reading Order

This page treats pseudo-instructions as assembler-level aliases or macros: first read what real instructions they expand to, then use the official ISA manual for the behavior of those real instructions. ABI, relocation, and linker-relaxation details follow the psABI document.

RISC-V Assembly Programmer's Manual

When To Think Of It First

Initialize registers to known constants (counter seeds, base offsets)

Set system call numbers (li a7, syscall_num)

Build bitmasks, magic numbers, flag values

Load memory-mapped I/O base addresses

Pitfalls / Common Confusions

li is not one fixed encoding; constants, XLEN, and extensions can produce different sequences

Do not assume every li occupies one instruction, especially for large RV64 constants

The 12-bit ADDI immediate is signed; the assembler handles carry adjustment when splitting large constants

Disassembly may show li or the real LUI/ADDI/shift sequence

FAQ

Is li a real RISC-V instruction?

li is an assembler pseudo-instruction or alias, not a separate hardware opcode. The “Typical Real Expansion” section lists the official expansion, and behavior is defined by the expanded ISA instructions.

What is the main trap when using li?