Organizational improvements for current (20250508) ratified unprivileged ISA spec

[L Peter Deutsch]

Appendix B is titled "Formal Memory Model," but in fact this only applies to sections B.1-B.3: sections B.4-B.13 are example code for various uses of the vector instructions. B.4-B.13 should be moved to a separate Appendix.

A larger improvement I would like to see is that while the current Table of Contents appears to simply have one Chapter per extension (or group of extensions) listed in the Chapter title, it is not consistent in this respect:

* Chapter 17 does not specify an extension or extensions at all.

* Chapters 19, 24, 29, 31, 32, and 33 cover multiple extensions, none of whose names appear in the Chapter title.

I would therefore suggest, as a minimum, the following changes to Chapter titles:

Chapter 12: put the "M" in quotation marks.

Chapter 19: change the title to '"Zicbo*" Extensions for Cache Management"'.

Chapter 24: change the title to '"Zfbf*" and "Zvfbf*" Extensions for BFloat-16 Precision Floating Point"'.

Chapter 29: change the title to '"Zba", "Zbb", "Zbc", "Zbs" Extensions for Bit Manipulation'.

Chapter 31: change the title to '"Zbk*" and "Zk*" Cryptography Extensions'.

Chapter 32: change the title to '"Zvbb", "Zvbc", and "Zvk*" Vector Cryptography Extensions'.

Chapter 33: change the title to '"Zicfilp" and "Zicfiss" Control-flow Integrity Extensions'.

I think it would be an improvement to couple the current Chapters 17 and 18 more closely, perhaps by making 18 a subsection of 17, whose title would be changed to something like "RVWMO Memory Consistency Model and "Ztso" Extension", but that is just my personal opinion.

I know I could in principle submit these changes myself through a pull request, but I'm hoping that if there's no objection to making them, they could be done by someone who is familiar with the details of adoc and the pull / update process, which I'm not.

--

L Peter Deutsch :: Aladdin Enterprises :: Healdsburg, CA & Burnaby, BC

[Bill Traynor]

Thanks Peter, may I suggest a process to move your requested changes forward?  Perhaps open issues against riscv-isa-manual for each change you'd like to see made.  The more fine grained the change the better.  That way, interested parties can comment on the issue and a decision can be made on GitHub whether to make the change or not.  Please provide your reason for each change as simply asking for a change to be made doesn't give anyone much justification for making.

If I can help in anyway, please let me know, either with issue submission or AsciiDoc formatting if you choose to make any changes yourself.

Thanks

Bill

--
You received this message because you are subscribed to the Google Groups "RISC-V ISA Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isa-dev+u...@groups.riscv.org.
To view this discussion visit https://groups.google.com/a/groups.riscv.org/d/msgid/isa-dev/20260122044249.122A0EC2D2D%40serpent.at.major2nd.com.

[L Peter Deutsch]

> Thanks Peter, may I suggest a process to move your requested changes forward?

Sorry, of course I agree that your suggestion is the right way to do this.
I'm pretty far out on the periphery of the RISC-V endeavor and just don't
have the processes ingrained.

Meanwhile, I've just learned that a large-scale reorganization of the ISA
spec will be starting soon, so rather than make scattered suggestions, I'll
wait to review the new chapters individually as they come out and then get
accustomed to the change request process you describe in the course of doing
that.

Thanks -