Add instruction names

[ThinkOpenly]

I proposed some annotations to the RISC-V Sail code which added human-readable names for each mnemonic, starting with just those in the "base" set for now.

Feedback to me for that PR included that many of the proposed instruction names weren't official names already expressed in the RISC-V ISA specification.

This issue is to try to address that concern by getting agreement on names for the mnemonics (base only for now), and adding them in some form to the specification. First step is to get agreement on instruction names. Is there a process to get 'official' agreement? Should I encode the names as changes to the specification in a PR so that it can be reviewed?

Below is a table that lists:

• The base mnemonics (those found in model/riscv_insts_base.sail).
• Those names that are pretty clearly defined in the specification. (There are not many, and some of those still involve some inference.)
• My proposed names (coming out of my "Sailing Downstream" project).
• A couple of somewhat random references that have made some attempt at naming the instructions as well.

It's anecdotal, but there is reasonable agreement among the 3 ad-hoc naming attempts.

mnemonic	RISC-V ISA Specification 20240411	Sailing Downstream	MIT 6.191	risc-v.guru
lui	load upper immediate	load upper immediate	Load Upper Immediate	Load Upper Immediate
auipc	add upper immediate to pc	add upper immediate to PC		Add Upper Imm. to PC
jal	jump and link	jump and link	Jump and Link	Jump And Link
jalr	jump and link register	jump and link register	Jump and Link Register	Jump And Link Register
beq		branch if equal	Branch if =	Branch Equal
bne		branch if not equal	Branch if ≠	Branch Not Equal
blt		branch if less than	Branch if < (Signed)	Branch Less Than
bge		branch if greater than	Branch if ≥ (Signed)	Branch Greater Than
bltu		branch if less than (unsigned)	Branch if < (Unsigned)	Branch Less Than
bgeu		branch if greater than or equal to (unsigned)	Branch if ≥ (Unsigned)	Branch Greater Than
addi		add immediate	Add Immediate	ADD Immediate
slti	set less than immediate	set less than immediate	Compare < Immediate (Signed)	Set < Immediate
sltiu		set less than immediate unsigned	Compare < Immediate (Unsigned)	Set < Immediate Unsigned
xori		XOR immediate	Xor Immediate	XOR Immediate
ori		OR immediate	Or Immediate	OR Immediate
andi		AND immediate	And Immediate	AND Immediate
slli	logical left shift	shift left (logical) immediate	Shift Left Logical Immediate	Shift Left Immediate
srli	logical right shift	shift right (logical) immediate	Shift Right Logical Immediate	Shift Right Immediate
srai	arithmetic right shift	shift right (arithmetic) immediate	Shift Right Arithmetic Immediate	Shift Right Arithmetic Imm.
add	addition	add	Add Immediate	ADD
slt	signed compare	set less than	Compare < (Signed)	Set <
sltu	unsigned compare	set less than (unsigned)	Compare < (Unsigned)	Set < Unsigned
and		AND	And	AND
or		OR	Or	OR
xor		exclusive OR	Xor	XOR
sll	logical left shift	shift left (logical)	Shift Left Logical	Shift Left
srl	logical right shift	shift right (logical)	Shift Right Logical	Shift Right
sub	subtraction	subtract	Subtract	Subtract
sra	arithmetic right shift	shift right (arithmetic)	Shift Right Arithmetic	Shift Right Arithmetic
lb		load byte		Load Byte
lh		load halfword		Load Halfword
lw		load word	Load Word	Load Word
ld		load double		Load Double
lbu		load byte unsigned		Load Byte Unsigned
lhu		load halfword unsigned		Load Halfword Unsigned
lwu		load word unsigned		Load Word Unsigned
ldu		load double unsigned		Load Double Unsigned
sb		store byte		Store Byte
sh		store halfword		Store Halfword
sw		store word	Store Word	Store Word
sd		store double		Store Double
addiw		add immediate word		ADD Immediate Word
addw		add word (RV64)		ADD Word
subw		subtract word (RV64)		Subtract Word
sllw		shift left (logical) word (RV64)		Shift Left Word
srlw		shift right (logical) word (RV64)		Shift Right Word
sraw		shift right (arithmetic) word (RV64)		Shift Right Arithmetic Word
slliw		shift left (logical) immediate word (RV64)		Shift Left Immediate Word
srliw		shift right (logical) immediate word (RV64)		Shift Right Immediate Word
sraiw		shift right (arithmetic) immediate word (RV64)		Shift Right Arithmetic Imm. Word
fence		fence (memory)		Sync Thread
fence.tso		fence (total store order)
fence.i		fence (instruction)		Sync Instruction & Data
ecall	environment call	environment call
mret		machine-level return
sret		supervisor-level return
ebreak	environment breakpoint	environment breakpoint
wfi	Wait for Interrupt	wait for interrupt
sfence.vma	supervisor memory-management fence	store fence (virtual memory address)

[gfavor]

Aren't all of these instruction mnemonics the exact ones clearly used in the Unpriv spec (and hence need no discussion or agreement on making them official since they are already official and part of ratified specs)?

[ThinkOpenly]

Aren't all of these instruction mnemonics the exact ones clearly used in the Unpriv spec?

The mnemonics are all present. I want to add human-readable names to the ISA specification. So "slli" would have an associated name like "shift left logical immediate". In its current form, the ISA specification has very few clearly distinguished such names.

[ThinkOpenly]

It seems that the RISC-V Unified Database project is also busy adding instruction names, so I've added the names they chose to the table:

mnemonic	RISC-V ISA Specification 20240411	Sailing Downstream	riscv-unified-db	MIT 6.191	risc-v.guru
lui	load upper immediate	load upper immediate	Load upper immediate	Load Upper Immediate	Load Upper Immediate
auipc	add upper immediate to pc	add upper immediate to PC	Add upper immediate to pc		Add Upper Imm. to PC
jal	jump and link	jump and link	Jump and link	Jump and Link	Jump And Link
jalr	jump and link register	jump and link register	Jump and link register	Jump and Link Register	Jump And Link Register
beq		branch if equal	Branch if equal	Branch if =	Branch Equal
bne		branch if not equal	Branch if not equal	Branch if ≠	Branch Not Equal
blt		branch if less than	Branch if less than	Branch if < (Signed)	Branch Less Than
bge		branch if greater than	Branch if greater than or equal	Branch if ≥ (Signed)	Branch Greater Than
bltu		branch if less than (unsigned)	Branch if less than unsigned	Branch if < (Unsigned)	Branch Less Than
bgeu		branch if greater than or equal to (unsigned)	Branch if greater than or equal unsigned	Branch if ≥ (Unsigned)	Branch Greater Than
addi		add immediate	Add immediate	Add Immediate	ADD Immediate
slti	set less than immediate	set less than immediate	Set on less than immediate	Compare < Immediate (Signed)	Set < Immediate
sltiu		set less than immediate unsigned	Set on less than immediate unsigned	Compare < Immediate (Unsigned)	Set < Immediate Unsigned
xori		XOR immediate	Exclusive Or immediate	Xor Immediate	XOR Immediate
ori		OR immediate	Or immediate	Or Immediate	OR Immediate
andi		AND immediate	And immediate	And Immediate	AND Immediate
slli	logical left shift	shift left (logical) immediate	Shift left logical immediate	Shift Left Logical Immediate	Shift Left Immediate
srli	logical right shift	shift right (logical) immediate	Shift right logical immediate	Shift Right Logical Immediate	Shift Right Immediate
srai	arithmetic right shift	shift right (arithmetic) immediate	Shift right arithmetic immediate	Shift Right Arithmetic Immediate	Shift Right Arithmetic Imm.
add	addition	add	Integer add	Add Immediate	ADD
slt	signed compare	set less than	Set on less than	Compare < (Signed)	Set <
sltu	unsigned compare	set less than (unsigned)	Set on less than unsigned	Compare < (Unsigned)	Set < Unsigned
and		AND	And	And	AND
or		OR	Or	Or	OR
xor		exclusive OR	Exclusive Or	Xor	XOR
sll	logical left shift	shift left (logical)	Shift left logical	Shift Left Logical	Shift Left
srl	logical right shift	shift right (logical)	Shift right logical	Shift Right Logical	Shift Right
sub	subtraction	subtract	Subtract	Subtract	Subtract
sra	arithmetic right shift	shift right (arithmetic)	Shift right arithmetic	Shift Right Arithmetic	Shift Right Arithmetic
lb		load byte	Load byte		Load Byte
lh		load halfword	Load halfword		Load Halfword
lw		load word	Load word	Load Word	Load Word
ld		load doubleword	Load doubleword		Load Double
lbu		load byte unsigned	Load byte unsigned		Load Byte Unsigned
lhu		load halfword unsigned	Load halfword unsigned		Load Halfword Unsigned
lwu		load word unsigned	Load word unsigned		Load Word Unsigned
ldu		load doubleword unsigned			Load Double Unsigned
sb		store byte	Store byte		Store Byte
sh		store halfword	Store halfword		Store Halfword
sw		store word	Store word	Store Word	Store Word
sd		store doubleword	Store doubleword		Store Double
addiw		add immediate word	Add immediate word		ADD Immediate Word
addw		add word (RV64)	Add word		ADD Word
subw		subtract word (RV64)	Subtract word		Subtract Word
sllw		shift left (logical) word (RV64)	Shift left logical word		Shift Left Word
srlw		shift right (logical) word (RV64)	Shift right logical word		Shift Right Word
sraw		shift right (arithmetic) word (RV64)	Shift right arithmetic word		Shift Right Arithmetic Word
slliw		shift left (logical) immediate word (RV64)	Shift left logical immediate word		Shift Left Immediate Word
srliw		shift right (logical) immediate word (RV64)	Shift right logical immediate word		Shift Right Immediate Word
sraiw		shift right (arithmetic) immediate word (RV64)	Shift right arithmetic immediate word		Shift Right Arithmetic Imm. Word
fence		fence (memory)	Memory ordering fence		Sync Thread
fence.tso		fence (total store order)
fence.i		fence (instruction)			Sync Instruction & Data
ecall	environment call	environment call	Environment call
mret		machine-level return	Machine Exception Return
sret		supervisor-level return	Supervisor Exception Return
ebreak	environment breakpoint	environment breakpoint	Breakpoint exception
wfi	Wait for Interrupt	wait for interrupt	Wait for interrupt
sfence.vma	supervisor memory-management fence	supervisor memory-management fence (virtual memory address)	Supervisor memory-management fence