I've been working with risc-v assembly a fair amount and sometimes I've had to resort to looking at emulators' and even compilers' code because the documentation is so lacking. Sometimes the emulators do different things in a given scenario. Sometimes real chips do different things in the same scenario. And I suspect the discrepancy is caused by lax documentation rather than implementation failure.
It doesn't have to be that way.
For example the description of exception handling is sprinkled between the CSR definitions of the CSRs involved. There's no section that just lays out the exception model.
So that's about 14 pages. This doesn't seem onerous to me, and counts as "in one place". It's about half of the entire M mode spec, which you might as well simply read in its entirety (two or three times), not try to cherry-pick.
I mean ... you don't want a solid 14 pages of description with no section heading at all, do you?
Maybe you want a single page that gives a 30,000 foot view. That would be possible, but it would inevitably have to leave out a lot and you'll need to read the detailed descriptions anyway.
Totally agree
> If you are unsure about something in the spec, there's also a multitude of RISC-V emulators out there, probably several in your favorite language already.
...but this is a problem. This means that it's not the specification saying what the standard is, but an implementation. People copying different implementations get different behaviours.
Readability is key here, as the opposite, a black box emulator, would not provide the same value.
> People copying different implementations get different behaviours
People copying black box behavior get different behaviors, necessarily.
Using English results in palpability, not specification. Major distinction. Indeed specs are intended to make an hitherto unseen vision palpable. But it's better to provide a mold, and verify implementations fit the mold.