After analyzing the RISC-V manual and consulting many online forums I found out that instructions are one of the parts of this manual that I believe have the most room for improvement. Taking the conditional branches as an example there is only one paragraph and one diagram for all the branch types.
Branch instructions compare two registers. BEQ and BNE take the branch
if registers rs1 and rs2 are equal or unequal respectively. BLT and
BLTU take the branch if rs1 is less than rs2, using signed and
unsigned comparison respectively. BGE and BGEU take the branch if rs1
is greater than or equal to rs2, using signed and unsigned comparison
respectively. Note, BGT, BGTU, BLE, and BLEU can be synthesized by
reversing the operands to BLT, BLTU, BGE, and BGEU, respectively.
This summarized text approach on part of the documentation makes it difficult on readers (as mentioned in issue #1396 ) and harder to maintain for the community, while also creating a lack of consistency throughout the manual. This problem is even more noticeable when considering all the extensions in the manual and the different maintainers supporting them. It seems that some extensions already follow a different approach like the ("B" Extension for Bit Manipulation), which is much clearer, and it's also much more in line with the industry standard. My proposal is to migrate this approach to all the base instructions as well. I believe that the "standard" should include:
Function Name
Function Synopsis
Mnemonic
Instruction Encoding
Description
Operation (SAIL format)
This standardized way of describing each instruction, which is common on ISA manuals from other vendors, would also create a great index on the "Table of Contents" for developers trying to quickly find specific instructions description (example below from ARM A64 manual).
Finally, I believe that in addition to this type of standardized approach there could be a way to create the intrusction asciidoc file format in an automated way that would take all the standard fields as input and then proceed to generate the aligned and formalized output, instead of having the need to do it step by step as currently is happening in all the extensions that are already addopting this kind of standard (such as in https://github.com/riscv/riscv-isa-manual/blob/77fd4fc3457efceff641def9f50df7592ec49bdb/src/b-st-ext.adoc?plain=1#L999). This would not only make it easier on writers, but would also tremendously improve the consistency throughout all the instructions. I know that this last section has already been discussed in #541 , but it seems like it was stalled or forgotten.
AFOliveira
commented
3 months ago
After analyzing the RISC-V manual and consulting many online forums I found out that instructions are one of the parts of this manual that I believe have the most room for improvement. Taking the conditional branches as an example there is only one paragraph and one diagram for all the branch types.
This summarized text approach on part of the documentation makes it difficult on readers (as mentioned in issue #1396 ) and harder to maintain for the community, while also creating a lack of consistency throughout the manual. This problem is even more noticeable when considering all the extensions in the manual and the different maintainers supporting them. It seems that some extensions already follow a different approach like the ("B" Extension for Bit Manipulation), which is much clearer, and it's also much more in line with the industry standard. My proposal is to migrate this approach to all the base instructions as well. I believe that the "standard" should include:
This standardized way of describing each instruction, which is common on ISA manuals from other vendors, would also create a great index on the "Table of Contents" for developers trying to quickly find specific instructions description (example below from ARM A64 manual).
Finally, I believe that in addition to this type of standardized approach there could be a way to create the intrusction asciidoc file format in an automated way that would take all the standard fields as input and then proceed to generate the aligned and formalized output, instead of having the need to do it step by step as currently is happening in all the extensions that are already addopting this kind of standard (such as in https://github.com/riscv/riscv-isa-manual/blob/77fd4fc3457efceff641def9f50df7592ec49bdb/src/b-st-ext.adoc?plain=1#L999). This would not only make it easier on writers, but would also tremendously improve the consistency throughout all the instructions. I know that this last section has already been discussed in #541 , but it seems like it was stalled or forgotten.