How to improve the RISC-V specification
alastairreid.github.io
alastairreid.github.io
For expediency, the choice was made to not sweat it. So the document is actually called a 'Manual' but is linked as being the specification. Even so, the document needs a real editor to review it. For example, the preferred bit pattern which is to be processed by an implementation as doing nothing but incrementing the program counter ('no op') is called an 'instruction' in some sections but is clearly not in others---a dumb discrepency. A review by a good technical editor would be a great first step in improving the document.
However, the greater tragedy is that a great 'specification' for RISC-V would be an invaluable educational document. This would be a very hard document to write. No document that I could find has ever tried to specify an instruction set independent of an actual implementation. So there is no roadmap towards writing a good spec for RISC-V. This is surely one of the reasons the effort has not yet been started.
After a couple of months trying to imagine how such an effort could be undertaken, how one could argue that the effort was worth trying, and how I might convince the community of the value and need for a good spec, I gave up. The work would require a team combining very fine technical knowledge with exeedingly accurate control of technical english. The work would be a multi-person-year effort, requiring concomitant funding. It is not clear to me how this work might begin.
Also you are entirely right to think about the test suite as a central concern. Specifications are strange documents. Some specifications make requirements which can not be tested; this affects the very nature of what is being 'specified'. Others have tried to root every injunction in the test suite; that approach leads to its own difficulties. The specification will have to make its choice on the matter and the authors would benefit from being very clear with themselves about what stance they are taking on the matter.
So thanks for your argument for a better specification; it would be a wonderful addition to the open instruction set. Hopefully, somehow, such an effort finds its wings.
What do you mean by this? I'd say most ISA specifications do this (e.g. the Arm spec doesn't refer to Arm's CPU implementations and has well defined ways to discuss things that can be implementation dependent).
You're right to call me on my statement; I should have all my notes on hand to make that claim and I don't. Paah, no, I do: ARMv7-M Architeture Reference Manual ... Part A Application Level Architecture ... ...processor in Thread mode (vs. in Handler mode).
So ARM already has a lot of detail whereas the RISC-V architecture is trying to (has to?) start even more abstract, where code doesn't even have modes (no interrupts).
This all started a pandemic saturday morning, cup of coffee in hand, enthusiasm to read the "RISC-V Spec" and see what I could learn. Download. Confusion: it says "manual," did I get the right thing? ... Ok, yeah, that's what's on offer. Half an hour later, I'm actually pissed off, like actively angry. I'm reading this from the point of view of "what's the execution environment that I'll be working against?" and I'm getting hit with "unprivileged" which is just wrong. It turns out they are mixing up "the environment of general purpose programmers" with "the minimal that needs to be implemented"---it's a royal mess, they kindda give up on it in the middle. I'm angry about being asked to read this as "the product"; it's not even properly proof-edited. So I took my frustration and tried to figure out 'what would you do to make this better?'
The 'RISC-V' spec is trying to specify: [instructions], and what they do to the [architecture]. I don't know much about the details, but I have a notion that there was push back on writing this up as a 'state machine' and how each instruction might change that state. I assume Prof. Asanović had his own good reason to avoid framing things that way but he's yet to give us a good explantion of why. So probably he's right, I just don't know why.
So how could this be done?
I went to look at the history. The original x86 spec was tied to the chip they were trying to sell. PowerPC, MIPS, if I remember right, were not 'specified' in a clean way--none of them had the same challenge as RISC-V does, starting in pure execution environment mode. I went to read the infamous von Newmann writeup and got side-tracked by his virtural neurons but didn't find the right level of abstraction there either.
So, I'm sorry I can't really justify myself here, but this is all subtle and hard. From what I have found, I don't think anyone has faced the challenge that RISC-V faces, so I don't think we have a roadmap for the spec that RISC-V ought to have.
cheers
1. A p-code parser front end in C existed;
2. An alternate XML/JSON version of SLEIGH; and,
3. A way to integrate the above to document (book) generation.
For the latter I'd prefer HTML. I've found the SLEIGH spec, itself, heavy enough going that I can't tell if it supports full constraint specifications, or not.
Is that a technical term? (if so, can you explain further)
I've made SLEIGH specs for two architectures. In my experience, it can describe 95% of the semantics well enough for decompilation (it gets weird when your ISA has quirks). Not as comprehensive as SAIL appears to be
Also, SLEIGH compiles to an XML format which is what Ghidra actually uses
> It is not clear to me how this work might begin.
To me that screams for - develop interest in a US public sector (aka government) funding agency and start getting grants to do this type of work.
I assume RISC-V can reasonably be pitched to government tech & policy folks as having many directly applicable benefits to their set of problems in a way they may want to invest in. To procure RISC- systems, they’d probably want a bunch of verification done. If the community isn’t investing, maybe they would.
Caveat I’m not current on the state of RISC-V adoption in public sector systems. But I’ve done funded systems development work at start ups with DARPA/ARPA, InQTel, etc. A motivated party should be able to make this happen.
Anyone closer to RISC-V know what the state of adoption in public sector?
I disagree 100%.
(note I'm a big fan of the RISC V effort)
First, the US government can/should seed pieces of fundamental technology that the private sector may later use, but in general you really don't want the government funding direct competitors to competitive technology already in the private sector (boosting RISC V when ARM, x86 etc are widely available). On a practical level, even if you do think the USG should do such a thing it won't happen.
Look at the members of RISC V International -- they are mostly huge multinationals who could both afford and benefit from such work. In fact the author of the post works for Intel. They are they people who should be paying for it (the smaller members, like Sifive, and mostly bleeding money).
There is one hack that could work, and might even be the most feasible: get DARPA to fund the pedagogical document acuster described. That to me is similar to previous successful research-supporting projects DARPA has funded in the past, such as SPICE. But that's a special case.
And anyway, why USG? Where are China and Europe in this? The EU funding this kind of pedagogical document would be a good step towards get its chip mojo back.
Alastair Reid's article "How to improve the RISC-V specification" makes some great points: namely that the RISC-V specification needs improvement, (implicitly) that this work is worth doing, and that testing is integral to specification. These are all great points.
However, a new specification effort for RISC-V requires a much greater effort.
The core document certainly needs to be rewritten with better structure, a more formal presentation of each 'instruction,' better clarity on what it is saying, and fixes to numerous errata. The harder 'fix' requires resolving the tension between its two readerships --- the implementors who must process instructions according to the requirements of the spec versus the coders who need to know what they can expect from the environment in which their instuctions are processed. (The 'unpriviledged' element in the subtitle of the spec is the code being executed.) Problematically, this tension might not be resolvable: since the core instuction set has no side effects and no requirements can be placed on how implementations are made, the spec inherently has no way to express knowledge of whether the code has been processed correctly! Fun.
A new specification effort has a bigger task than fixing, as best as possible, the current document. Alastair Reid's article mentions needing to integrate testing more centrally into the specification. There is also the need to think of this core spec as the foundational document on which to build the whole suite of RISC-V specification documents. A new spec also needs to cater to the even wider readership, beyond 'implementors' and 'coders,' that accompanies projects with wide-spread success. For example, the spec ought to serve companies or governments in their procurement contracts, so they can express what is meant by deliverables which are conformant with the specification. Ideally, this wider readership under consideration would also include 'students,' that is smart people who have less a priori knowledge of the domain than that which the original 'manual' was able to assume.
This is all a lot of work, which would be of great benefit to the community but which no one in the community has any reason to, or really could, take on. Ideally, the RISC-V Foundation would scope out the work, take a position on what parts of the effort were worth pushing for, and then make that happen.
Specify the key formats in a json/xml file then go one by one through tools, docs, etc changing them to use the machine readable file.
The most famous example is MIX.
ARM, for example, put a tonne of effort into decoupling their ISA specification from their implementations, and guard this document.
You're seeing how the sausage is made.
To take one example it never defines what an interrupt is and more broadly never defines terminology around exceptions. Contrast to the arm ISA which precisely describes what it means by asynchronous Vs synchronous, precise Vs imprecise etc (see section D3-1 in https://developer.arm.com/documentation/ddi0487/latest/).
The original authors may see this as a virtue, the small size of the RISC-V ISA manuals Vs Arm was portrayed as a great benefit but in part that size is because it's missing lots of stuff like this that I view as highly important for a specification.
I don't think you meant D3-1 btw.
(result, -) = AddWithCarry(operand1, imm, '0');
if d == 31 then
SP[] = ZeroExtend(result, 64);
else
X[d, datasize] = result;
(result, nzcv) = AddWithCarry(operand1, operand2, carry_in);
if d == 31 then {
SP_set() = ZeroExtend(result, 64)
} else {
X_set(d, datasize) = result
}
(There surely are things that can be improved, of course - e.g. perhaps the concrete syntax for fancy types - but readability was a primary goal in the Sail design; it's really not a theorem-proving language or something that needs fancy PL knowledge.)
I think my primary criticism is the way in which the formal specification is surfaced in RISC-V as opposed to ARM rather than any issue with Sail in particular.
In ARM, the relevant portions of the pseudocode/ASL are available directly in the architecture reference manual. A snippet is either included directly underneath the relevant instruction or there is a link to it. This makes it very easy to use since only the relevant bits are presented when it is being used for reference/human spec reading purposes. This relationship to pseudocode/ASL, of course, makes sense given the history of ASL. The documentation pseudocode was originally just a nice and clearer way to explain how instructions work (free from the trappings of natural language). Later, they cleaned up the pseudocode and created an actual language specification for it so that it could be used as a formal model.
In RISC-V, we don't really get any such luxuries. If you find yourself confused about how exactly an instruction works, you have to somehow know that the Sail model is the official specification (it is not called out anywhere in the natural language spec!) and then go trawl through the entire model yourself hunting for the definition of your instruction. This isn't super hard if you know what you're doing, but there is a lot of other machinery in these models that you can trip over (it includes instruction binary encoding formats and the assembler language specification as well). I would say that I'm comfortable using the model as a reference but it's definitely not as easy to access as it is over on ARM.
I see now though that there is an effort to integrate the Sail source into the natural language specification. I hope that makes it eventually, it'll be a big quality of life improvement.
There's already a way to extract functions into asciidoc as the author noted. I've used it. It works well.
The liquid types do take some getting used to but they aren't actually used in most of the code; mostly for utility function definitions like `zero_extend`. If you look at the definition for simple instructions they can be very readable and practically pseudocode:
https://github.com/riscv/sail-riscv/blob/0aae5bc7f57df4ebedd...
A lot of instructions are more complex or course but that's what you get if you want to precisely define them.
Overall Sail is a really fantastic language and the liquid types really help avoid bugs.
The biggest actual problems are:
1. The RISC-V spec is chock full of undefined / implementation defined behaviour. How do you capture that in code, where basically everything is defined. The biggest example is probably WARL fields which can do basically anything. Another example is decomposing misaligned accesses. You can decompose them into any number of atomic memory operations and do them in any order. E.g. Spike decomposes them into single byte accesses. (This problem isn't really unique to Sail tbf).
2. The RISC-V Sail model doesn't do a good job of letting you configure it currently. E.g. you can't even set the spec version at the moment. This is just an engineering problem though. We're hoping to fix it one day using riscv-config which is a YAML file that's supposed to specify all the configurable behaviour about a RISC-V chip.
I definitely agree about the often wooly language in the spec though. It doesn't even use RFC-style MUST/SHOULD/MAY terms.
https://github.com/riscv/riscv-profiles/blob/main/rva23-prof...
If you write to a WARL field in a CSR the chip can use more or less any legalisation logic it wants. Configuring that is very difficult (though there is a decent attempt in riscv-config).
The configurability problem has several main parts.
(1) It's a Turing complete problem as the informal RISCV specification gives you so much freedom, including all those IMPDEFs. The specification of a complex, configurable ISA will always be intrinsically complex and syntax can only do so much about presenting this intrinsic complexity.
(2) Sail's lack of a clear, easy to use module system for configuration of the exact RISCV version to be emulated.
https://alasdair.github.io/#_modules
But it's very new and the RISC-V model doesn't use it yet. I think it's also just a first step rather than fully solving the problem.
As Alastair Reid says, one of the main things missing in the current RISC-V specification documents is simply that the associated Sail definitions are not yet interspersed with the prose instruction descriptions. The infrastructure to do that has been available for some time, in the Sail AsciiDoc support by Alasdair Armstrong (https://github.com/Alasdair/asciidoctor-sail/blob/master/doc...) and older LaTeX versions by Prashanth Mundkur and Alasdair (https://github.com/rems-project/riscv-isa-manual/blob/sail/r...).
Just because people are used to other ways of doing things doesn’t make those ways better. “I don’t want to learn something new“ certainly isn’t a compelling argument.
When you change the context, the perception changes. If you're a grad student who has chosen to dive head first into Chisel after already mastering functional programming and want to get more into hardware design, that's a different story.
This has been something I wish was available for ARM pseudocode. It’d be ideal to just generate an equivalent Python, SystemVerilog, etc. library from the ARM ARM instead of having to reimplement a subset of it yourself.
The authoritative description should be machine readable, but the PDF also needs to be authoritative. That means the PDF needs to be generated from the machine readable spec automatically.
I think the highest quality ISA spec in the industry at this point is ARM's ARMv8/9 ISA manual - it's a readable PDF with psuedocode in a well defined language. Every ISA rule is even given a unique identifier. But even better, it's all generated from XML source files which ARM releases, so you can parse the psuedocode out of those and run that code directly if you write an interpreter for it.
I was hoping to see ARM also release this XML for ARMv8-M but last I checked they haven't done so, sadly.
It's highly worthwhile to examine different ISA manuals to compare their relative approaches (e.g. Power, SPARC, ARMv8, Hexagon, s390x, Itanium, etc.). But I think ARMv8 is the best.
But this is not a conclusion in any sense. This is the premise of the entire RISC-V project. Because RISC-V is just an abstraction to teach and learn machine-level aspects of programming regardless of the specific processors available on the market. Donald Knuth has the same, MMIX. In addition it is difficult to say what innovations there may be in the RISС processor instruction system.
Well...
See chapter 2: https://www2.eecs.berkeley.edu/Pubs/TechRpts/2016/EECS-2016-...
I would say you're right though in that RISCV enjoys the success it's seeing due to the open specification and licensing model. People generally aren't drawn to RISCV because of technical innovation.
However RISC-V is an excellent base upon which to innovate. You can see that in things such as the Vector extension, the memory model developed by industry and academic experts world-wide, and CHERI fine-grained memory-protection.
https://codasip.com/press-release/2023/10/31/codasip-deliver...
That's largely because if you base a product on Arm or MIPS you have the choice of getting them to actively invest in and support you, or getting sued into oblivion by them.
THAT is why RISC-V is the most friendly ISA to innovation and where most future innovation will happen. Because innovation comes not only from internally inside Intel or Arm or MIPS (who have switched to RISC-V now anyway) but from a myriad of possible sources.
E.g. The ISA is modular. You can use the RV64GC set of instructions to implement a very basic Linux-capable CPU that executes one instruction at a time.
Then you can build an advanced CPU that does OOO and instruction compression and run the same binary *efficiently*.
Also the base ISA is very implementer-friendly. As in: requiring few transistors / FPGA LEs, (relatively) easy to write a compiler or emulator for, etc. But that is hardly unique.
32b and 64b flavours very similar. Oh and... modular.
That doesn't make it 'better' though. Eg. x86 has a looott of legacy cruft. But also a looott of high-quality software for it. RISC-V: many of those tools are still being written / adapted / optimized. Likewise, x86 & ARM have many high-performance, efficient and/or low-cost implementations. RISC-V is catching up quickly, but not (yet) head-to-head with those.
They unfortunately very rarely are.
And in these days of LLM's and whatnot, the human-readable version should easily be automatically derived from the machine-readable one, not the other way round.
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.
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.
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.