Skip to content

Instruction descriptions name operands their instruction does not declare #2458

Description

The problem

Some instruction descriptions name an operand the instruction never declares. vadd.vx reads:

Adds elements from vector register vs2 to scalar register rs1 according to mask vm...

but its encoding declares xs1, and its assembly is vd, vs2, xs1, vm. There is no rs1 in that file. The clearest case is c.sw, which uses both spellings for the same operand three words apart:

Stores a 32-bit value in register xs2 ... It expands to sw **rs2**, offset(xs1).

This is not a convention problem. Both spellings are legitimate in tree, and a file that declares rs1 and says rs1 is consistent. Counting declared encoding variable names across the 1,544 instruction files on main:

declared files declared files
xs1 878 rs1 116
xs2 389 rs2 53
xd 485 rd 101

The defect is only the mismatch: description says one, encoding declares the other.

The sweep

Parsing every instruction YAML under spec/std/isa/inst and spec/custom, and comparing tokens in description against the names in encoding.variables, 33 files reference an operand they do not declare. They are not one class:

count disposition
description names rsN/rd, file declares xsN/xd 18 mechanical, fixed in the PR
rs2 naming the encoding field, not an operand 3 correct, left alone
already fixed in #2419 1 c.sdsp
.vf scalar is a float register 5 needs a decision
.vs form has no scalar integer operand at all 5 needs a decision
manual quote of another instruction 1 needs a decision

Correct, and deliberately untouched

Three files use rs2 to name the encoding field at bits 24-20 rather than an operand, which is standard, and each match string agrees with what it claims:

file says bits 24-20 of its match
fround.q encoded like fcvt.q.s, but with rs2=4 00100 = 4 (fcvt.q.s is 00000)
froundnx.q encoded like fround.q but with rs2=5 00101 = 5
fround.s encoded like FCVT.S.D, but with rs2=4 00100 = 4

Nothing to fix in these.

Needs a decision, not a rename

Five .vf instructions say the scalar comes from rs1, but the .vf form takes a floating-point scalar. vfadd.vf declares fs1 and its assembly is vd, vs2, fs1, vm. fs1 looks right, but this is a different fix from the mechanical one: vfadd.vf, vfdiv.vf, vfmul.vf, vfsub.vf, vfwmaccbf16.vf.

Five .vs instructions say "using scalar register rs1" but declare only vs2 and vd, with assembly vd, vs2. There is no scalar integer operand. The .vv sibling reads identically except "using vector register vs1", so the .vs text looks like it was derived from it by substitution: vaesdf.vs, vaesdm.vs, vaesef.vs, vaesem.vs, vsm4r.vs.

fcvt.s.wu contains "initialized to ... using fcvt.s.w rd, x0", a quote of the manual describing a different instruction. Arguably fine as a quotation.

A separate finding in one of the same files

vsub.vx describes the wrong direction. It reads "Subtracts elements of vs2 from scalar rs1", which is x[rs1] - vs2[i]. That is what vrsub.vx does, and vrsub.vx exists separately, described as "reverse subtraction on elements from scalar register xs1 and vector register vs2". vsub.vx should be vs2[i] - x[rs1].

I have not fixed this, because it is a semantic correction rather than a naming one and vsub.vx has an empty operation() body, so nothing in the tree contradicts the prose. Happy to send it separately if wanted.

Scope of the PR

Descriptions only, 18 files, 19 lines. Every token was confirmed to occur the same number of times in the whole file as in its description before editing, so no encoding variable, assembly string or operation() body is touched. All 18 still validate against inst_schema.json. c.addi4spn keeps its RVC prime and gains the prefix, rd' to xd', matching c.beqz, c.bnez, c.not and c.mul, which already use xs1', xd' and xs2'.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions