Mandatory operands for vsetvli, vsetivli could be better explained

[ThinkOpenly]

Looking at the lastest GitHub released spec, under "Vector Tail Agnostic and Vector Mask Agnostic vta and vma" there is this text:

The assembly syntax adds two mandatory flags to the `vsetvli` instruction

...followed by a table of the valid vta and vtm flags.

A first suggestion is to change "adds ... to" in the text above to "has ... in", as it's not apparent what is being added to.

A second suggestion is to add vsetivli to the sentence, presuming these flags are also mandatory for it.

Accompanying the above table is a note:

Prior to v0.9, when these flags were not specified on a vsetvli, they defaulted to mask-undisturbed/tail-undisturbed. The use of vsetvli without these flags is deprecated, however, and specifying a flag setting is now mandatory. The default should perhaps be tail-agnostic/mask-agnostic, so software has to specify when it cares about the non-participating elements, but given the historical meaning of the instruction prior to introduction of these flags, it was decided to always require them in future assembly code.

Are references to pre-ratified specifications of value in the ratified spec? Presuming not, a third suggestion is to remove this note.

Regardless, this note further confirms that the vta and vtm flags are required.

Unfortunately, some later examples of the use of vsetvli/vsetivli do not obviously include the mandatory flags. In (33.6):

 vsetvli rd, rs1, vtypei   # rd = new vl, rs1 = AVL, vtypei = new vtype setting
 vsetivli rd, uimm, vtypei # rd = new vl, uimm = AVL, vtypei = new vtype setting
 vsetvl  rd, rs1, rs2      # rd = new vl, rs1 = AVL, rs2 = new vtype value

Thus, a final suggestion is to add some indication or immediate explanation that vtypei is a series of flags (not one operand as shown), including some mandatory flags. This explanation comes in a subsection about a page later after content about encodings and the vtype register layout.

[nick-knight]

I support the proposed changes.

I haven't checked how broadly various tools have deprecated the old assembly syntax. I generally use LLVM's (integrated) assembler, modern versions of which error on the old syntax. So I'm OK with deleting the note.

Over time, I'm hoping that such details of assembly language syntax will be migrated to https://github.com/riscv-non-isa/riscv-asm-manual/blob/main/riscv-asm.md . But that is a broader issue.

[ThinkOpenly]

I support the proposed changes.

Thanks, @nick-knight!

Over time, I'm hoping that such details of assembly language syntax will be migrated to https://github.com/riscv-non-isa/riscv-asm-manual/blob/main/riscv-asm.md . But that is a broader issue.

In the quest for "one source of truth", I certainly hope the RISC-V Sail specification informs the content of the RISC-V Assembly Programmer's Manual, if it is not generated (or partly generated) from it. The Sail specification needs to retain its role as the canonical reference.