Differential D147183
[RISCV][docs] Document which revision of the specification we implement Authored by reames on Mar 29 2023, 2:02 PM.
Details This is intended to document the decision made in recent discussion, and ratified at the last risc-v sync up call two weeks ago. The wording here turned out to be a bit tricky. I ended up using the word "revision" as the specification internally defines several versioning schemes, and RVI assigns particular meaning to the words "specification version" that I really didn't want to get into. If anyone has suggestions on how to improve this, please don't hesitate to chime in.
Diff Detail
Event TimelineComment Actions I think this reflects what we (extensively) discussed and there was broad consensus for, so I'd be happy enough for it to land as-is rather than getting too bogged down over precise terminology. That said, I do think that going into the details of draft vs non-draft specifications and so on might be going into more detail than necessary, and could be confusing. It also seems like RISC-V is rather ignoring (and perhaps choosing to move away from?) the task of centralising all the extensions in a single ISA manual, so again it may make more sense to focus on ratified vs non-ratified as the thing that is easily understandable rather than trying to explain the way extension definitions are confusingly spread across different repositories. I would suggest the following, which I think expresses what we need to. If you like it or some variant along these lines, fantastic. If not, I'd rather just land your version as-is (assuming there aren't other objections) so we can get the policy we agreed documented. Thanks for putting our conclusions into writing and convening the meeting to move this forwards. There have been a number of revisions to the RISC-V specifications. LLVM aims to implement the most recent ratified version of the standard RISC-V base ISAs and ISA extensions with pragmatic variances. The most recent specification can be found at: https://github.com/riscv/riscv-isa-manual/releases/. `The official RISC-V International specification page <https://riscv.org/technical/specifications/>`_. is also worth checking, but tends to significantly lag the specifications linked above. Make sure to check the `wiki for not yet integrated extensions <https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_ and note that in addition, we sometimes carry support for extensions that have not yet been ratified (these will be marked as experimental - see below) and support various vendor-specific extensions (see below). The current known variances from the specification are: * Unconditionally allowing instructions from zifencei, zicsr, zicntr, and zihpm without gating them on the extensions being enabled. Previous revisions of the specification included these instructions in the base ISA, and we preserve this behavior to avoid breaking existing code. If a future revision of the specification reuses these opcodes for other extensions, we may need to reevaluate this choice, and thus recommend users migrate build systems so as not to rely on this. * Allowing CSRs to be named without gating on specific extensions. This applies to all CSR names, not just those in zicsr, zicntr, and zihpm. We are actively deciding not to support multiple specification revisions at this time. We acknowledge a likely future need, but actively defer the decisions making around handling this until we have a concrete example of real hardware having shipped and an incompatible change to the specification made afterwards. Comment Actions LGTM, though hopefully at least one other person can confirm they're happy with the wording. One point we clarified on the call is that the first bulletpoint under "The current known variances from the specification are:" is documenting what we do today, and the expectation is this is updated if it changes as part of moving to I 2.1 - we didn't discuss that particular point in depth. Of course anything here can be modified if we change our minds, but we did spend a bit of time discussing the second bullet (checking CSR names) and seemed to have no appetite for revisiting this in the near term. No change to the patch needed/suggested, just noting this for posterity.
| ||||||
Nit: should probably drop zihpm from this listing as it only contains CSRs and no new instructions/pseudoinstructions.