Need consistent and complete list of pseudoinstructions

[ThinkOpenly]

The prior RISC-V ISA Specification (20191213) had a chapter 25, "RISC-V Assembly Programmer’s Handbook" which had a table listing many/most pseudoinstructions. This is no longer present in the most recent RISC-V ISA Specification (20240411).

In many ways, though, I'm actually leaning toward closer association between the pseudoinstructions and their base instructions. This is well done for "zext.w", which is right there in the section for its base instruction "add.uw" (section 28.5.1). Something like this, done more exhaustively, would be ideal.

[nick-knight]

I don't understand. We moved the pseudoinstructions to the asm manual
https://github.com/riscv-non-isa/riscv-asm-manual/blob/main/riscv-asm.md#-a-listing-of-standard-risc-v-pseudoinstructions
I thought this was a step in the right direction. Are you wanting them moved back?

[ThinkOpenly]

@wmat said (RVI Slack) "There is no assembly programmers manual that we maintain."

Is the link you provided something official? I do now see a reference to it in the bibliography of the RISC-V ISA specification.

One issue I see is that there are plenty of references to pseudoinstructions in the RISC-V ISA specification, but no obvious comprehensive reference for them. Most of the references are thrown in off-handedly. An outlier is for "zext.w", which is well formatted.

It could be that just a simple and obvious pointer to the RISC-V Assembly Programmer's Manual is needed, like "For more information and a listing of pseudoinstructions, see ...".

But, if pseudoinstructions are in the domain of that other document, then I'm not sure why any pseudoinstructions are mentioned in the ISA? There's a fairly lengthy discussion about RDCYCLE, RDTIME, and RDINSTRET pseudoinstructions in the ISA, for example. The Assembly Programmer's Manual even says "Other assemblers might not support the same directives or pseudoinstructions", so arguably there shouldn't be any pseudoinstructions in the ISA spec. Is support for the ones mentioned in the ISA spec mandatory?

Also, I note that the RISC-V Assembly Programmer's Manual doesn't have any of the base instructions, and the ISA might sort-of document the instructions, but it doesn't describe the syntax for each of the base instructions. For example, say I wanted to know the syntax for a "load" instruction. It's not in the Assembly Programmer's Manual at all. In the ISA, I'd expect to find it in section 2.6 "Load and Store Instructions" (RV32I) or 4.3 "Load and Store Instructions" (RV64I), but it's not.

Is the separation intended to be:

• The ISA spec documents the opcodes and semantics
• The Assembly Manual documents the instructions (and semantics?)
  ?

[kasanovic]

There are multiple consumers of the specifications at different phases in the specification lifecycle, and it is not easy to remove all redundancy while retaining a readable document for all consumers.

While the ISA specs should focus on the machine instructions (i.e. actual hardware instructions and encoding),
when describing a new proposal, the pseudo instructions are often part of the rationale for the design ("this instruction can be specialized to provide these other simpler instructions as pseudo-instructions"). This should probably stay in the descriptive part of the ISA manuals to help with understanding the design, if not in the "page-per-instruction" reference manual sections.

The ISA manuals shouldn't be the assembly programming reference (not to endorse this, but some ISAs have multiple different assembler syntaxes). But I do think there should be a complete listing of all assembly instructions (native and pseudo) in the assembly programmers' manual, though probably some more mechanization is needed to help maintain these tables.

I don't think the assembly manual has to provide instruction-level semantics for native instructions but should for pseudo-instructions (and other assembler directives) that expand out into native machine instructions.

[nick-knight]

@ThinkOpenly

@wmat said (RVI Slack) "There is no assembly programmers manual that we maintain."

Is the link you provided something official?

I admit I get lost in the lasagna stack of RVI groups and committees, but I am fairly certain that the asm manual
https://github.com/riscv-non-isa/riscv-asm-manual
is maintained by (at least) one of them. I don't see that @wmat has made any contributions to that repo, so it may be that it's outside the current scope of the RVI technical writing team's charter. However, I do see evidence that the technical writers are at least aware of it (e.g., #573 (comment)).

Is the separation intended to be:
The ISA spec documents the opcodes and semantics
The Assembly Manual documents the instructions (and semantics?)

I can't speak to the original intent. I support such a separation, but I'm not available to do the refactoring work myself, nor to debate it with any who disagree.

[aswaterman]

I am fairly certain that the asm manual
https://github.com/riscv-non-isa/riscv-asm-manual
is maintained by (at least) one of them.

It most definitely is.

[aswaterman]

I agree with @kasanovic that we should continue informally describing pseudoinstructions in the ISA spec, as it elucidates the ISA design. And there is another aspect of pseudoinstructions that justifies this approach: if there are multiple ways of doing the same thing, it’s beneficial to officially recommend just one, so that implementers know which cases to optimize and software will follow suit.

This approach isn't in tension with leaving the complete definition of pseudoinstructions up to the ASM spec.

[ThinkOpenly]

"page-per-instruction" reference manual sections.

What is that?

I do think there should be a complete listing of all assembly instructions (native and pseudo) in the assembly programmers' manual

Agree.

though probably some more mechanization is needed to help maintain these tables.

One of the motivations for the Sail JSON backend I've been working on is to be able to inform uses like that. This is a bit out of date, but conveys the gist: https://github.com/ThinkOpenly/RISC-V_ISA/blob/main/src/ISA.json

And the online assembly language reference that is based on the JSON emitted by that backend: https://thinkopenly.github.io/RISC-V_ISA/. (A work in progress, pretty obviously.)

I don't think the assembly manual has to provide instruction-level semantics for native instructions but should for pseudo-instructions (and other assembler directives) that expand out into native machine instructions.

Presuming "semantics" does not include "syntax", I could agree, but I do think there should be a "one-stop shopping" reference for assembly-level programmers that certainly includes syntax and arguably should include semantics. (Currently, neither ISA nor manual are sufficient.)

[wmat]

Interesting, I was unaware of this manual. If we are to eventually include this manual within the documentation library, it will need to be converted to AsciiDoc.

[abrodkin]

I guess, it's related to #1253.