RISC-V Specifications page is confusing/incorrect?
TommyMurphyTM1234 opened this issue · 7 comments
TommyMurphyTM1234 commented
Apologies if this is not the correct place to log this but I can't see anywhere else to log an issue against this page:
That page says (italicised emphasis is mine):
ISA Specifications (Ratified)
The specifications shown below represent the current, ratified and published releases.
But, for example. the version of Volume 1 linked contains this:
31.1. Introduction
This document is version 1.1-draft of the RISC-V vector extension.
So it contains includes draft and is presumably not fully ratified?
Am I missing something here?
If there is a better way/place to log this issue please let me know as I couldn't fine one.
Thanks.
wmat commented
Hi Tommy,
Thanks for pointing this out. I'll verify the Vector version today and
update the spec. There was mention in the Vector discussions of moving the
ratified version to 2.0, so want to confirm whether that is still the
case. However, rest assured the version in the Unpriv spec is ratified.
…On Mon, May 13, 2024 at 7:20 AM Tommy Murphy ***@***.***> wrote:
Apologies if this is not the correct place to log this but I can't see
anywhere else to log an issue against this page:
- https://riscv.org/technical/specifications/
That page says (*italicised emphasis* is mine):
*ISA Specifications (Ratified)*
The specifications shown below represent the current, *ratified* and
published releases.
- Volume 1, Unprivileged Specification version 20240411 [PDF
<https://drive.google.com/file/d/1uviu1nH-tScFfgrovvFCrj7Omv8tFtkp/view?usp=drive_link>
][GitHub
<https://github.com/riscv/riscv-isa-manual/releases/tag/20240411>]
- Volume 2, Privileged Specification version 20240411 [PDF
<https://drive.google.com/file/d/17GeetSnT5wW3xNuAHI95-SI1gPGd5sJ_/view?usp=drive_link>
][GitHub
<https://github.com/riscv/riscv-isa-manual/releases/tag/20240411>]
But, for example. the version of Volume 1 linked contains this:
*31.1. Introduction*
This document is version 1.1-*draft* of the RISC-V vector extension.
So it contains draft and not ratified info.
Am I missing something here?
If there is a better way/place to log this issue please let me know as I
couldn't fine one.
Thanks.
—
Reply to this email directly, view it on GitHub
<#1400>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAN6ZHBTQ3YTJAL4W5AQSDZCCOWJAVCNFSM6AAAAABHUAFBAGVHI2DSMVQWIX3LMV43ASLTON2WKOZSGI4TENJSG4ZTAMY>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
TommyMurphyTM1234 commented
Hi Bill
Thanks a lot for your reply.
I'll verify the Vector version today
Just to be clear, my questions on this issue are twofold:
1. Was the Vector extension 1.0 actually ratified (in November 2021?) or not - and if it was then where can the "standalone" spec for that particular version of the extension be found?
2. Where is the authoritative place to get info about the ongoing 1.1 (or maybe 2.0?) Vector extension specification (used to be the GitHub repo but that's now archived but with no clear redirection hint that I can see) and does a "standalone" draft spec exist or just the version of the Unpivileged spec that integrates draft Vector extension 1.1 (2.0?) text?
However, rest assured the version in the Unpriv spec is ratified.
Yes - but the version linked from the RISC-V International Specifications page is described as ratified but contains draft Vector (and other?) extension text so, de factor, cannot be a ratified version.
It's not totally clear to me from this where to find the (latest?) ratified versions of the Unprivileged and Privileged Specs:
https://github.com/riscv/riscv-isa-manual/releases
Something here perhaps?
https://github.com/riscv/riscv-isa-manual/releases?q=ratified&expanded=true
To summarise - I may well be missing some key guidance info here but it seems to me to be quite difficult to identify/find/track authoritative ratified and work in progress specification documents/info.
I'm open to correction and elucidation. :-)
Thanks again
Regards
Tommy
wmat commented
On Tue, May 14, 2024 at 9:15 AM Tommy Murphy ***@***.***> wrote:
Hi Bill
Thanks a lot for your reply.
> I'll verify the Vector version today
Just to be clear, my questions on this issue are twofold:
1. Was the Vector extension 1.0 actually ratified (in November 2021?) or
not - and if it was then where can the "standalone" spec for that
particular version of the extension be found?
Yes, it was. It can be found here: https://github.com/riscv/riscv-v-spec
However, the Vector chapter in the Unprivileged spec should be the single
point of reference for all things Vector going forward.
2. Where is the authoritative place to get info about the ongoing 1.1 (or
maybe 2.0?) Vector extension specification (used to be the GitHub repo but
that's now archived but with no clear redirection hint that I can see) and
does a "standalone" draft spec exist or just the version of the Unpivileged
spec that integrates draft Vector extension 1.1 (2.0?) text?
The authoritative place is the Vector chapter of the Unprivileged spec.
Any issues/discussions should be filed against the riscv-isa-manual as
there is no longer a standalone Vector spec in development.
> However, rest assured the version in the Unpriv spec is ratified.
Yes - but the version linked from the RISC-V International Specifications
page is described as ratified but contains draft Vector (and other?)
extension text so, de factor, cannot be a ratified version.
That's an error and the word draft will be removed.
It's not totally clear to me from this where to find the (latest?)
ratified versions of the Unprivileged and Privileged Specs:
https://github.com/riscv/riscv-isa-manual/releases
The PDFs are linked from https://riscv.org/technical/specifications/
Or on GitHub here:
https://github.com/riscv/riscv-isa-manual/releases/tag/20240411
Something here perhaps?
https://github.com/riscv/riscv-isa-manual/releases?q=ratified&expanded=true
To summarise - I may well be missing some key guidance info here but it
seems to me to be quite difficult to identify/find/track authoritative
ratified and work in progress specification documents/info.
The two links provided above are the ratified Unprivileged and Privileged
specs. Any work in progress on ISA specifications is done in a stand alone
repository for individual extensions and then upon their ratification, they
are integrated into the Unprivileged or Privileged specs as a chapter.
… I'm open to correction and elucidation. :-)
Thanks again
Regards
Tommy
—
Reply to this email directly, view it on GitHub
<#1400 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAN6ZABFRRMCTXRCMYCHPLZCIE7ZAVCNFSM6AAAAABHUAFBAGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMJQGIYTIMBQGE>
.
You are receiving this because you commented.Message ID:
***@***.***>
wmat commented
In looking closer at Vector, the introduction of the chapter indicates the
following
"This document is version 1.1-draft of the RISC-V vector extension.
NOTE: This version holds updates gathered after the start of the
public review. The spec will have a final update to version 2.0 at
time of ratification."
Therefore, that chapter is technically 1.0 + updates gathered after the
start of the public review. I'm going to open an issue to clarify it's
version.
…On Tue, May 14, 2024 at 9:28 AM Bill Traynor ***@***.***> wrote:
On Tue, May 14, 2024 at 9:15 AM Tommy Murphy ***@***.***>
wrote:
> Hi Bill
>
> Thanks a lot for your reply.
>
> > I'll verify the Vector version today
>
> Just to be clear, my questions on this issue are twofold:
>
> 1. Was the Vector extension 1.0 actually ratified (in November 2021?) or
> not - and if it was then where can the "standalone" spec for that
> particular version of the extension be found?
>
Yes, it was. It can be found here: https://github.com/riscv/riscv-v-spec
However, the Vector chapter in the Unprivileged spec should be the single
point of reference for all things Vector going forward.
2. Where is the authoritative place to get info about the ongoing 1.1 (or
> maybe 2.0?) Vector extension specification (used to be the GitHub repo but
> that's now archived but with no clear redirection hint that I can see) and
> does a "standalone" draft spec exist or just the version of the Unpivileged
> spec that integrates draft Vector extension 1.1 (2.0?) text?
>
The authoritative place is the Vector chapter of the Unprivileged spec.
Any issues/discussions should be filed against the riscv-isa-manual as
there is no longer a standalone Vector spec in development.
> > However, rest assured the version in the Unpriv spec is ratified.
>
> Yes - but the version linked from the RISC-V International Specifications
> page is described as ratified but contains draft Vector (and other?)
> extension text so, de factor, cannot be a ratified version.
>
That's an error and the word draft will be removed.
> It's not totally clear to me from this where to find the (latest?)
> ratified versions of the Unprivileged and Privileged Specs:
>
> https://github.com/riscv/riscv-isa-manual/releases
The PDFs are linked from https://riscv.org/technical/specifications/
Or on GitHub here:
https://github.com/riscv/riscv-isa-manual/releases/tag/20240411
>
> Something here perhaps?
>
>
> https://github.com/riscv/riscv-isa-manual/releases?q=ratified&expanded=true
>
> To summarise - I may well be missing some key guidance info here but it
> seems to me to be quite difficult to identify/find/track authoritative
> ratified and work in progress specification documents/info.
>
The two links provided above are the ratified Unprivileged and Privileged
specs. Any work in progress on ISA specifications is done in a stand alone
repository for individual extensions and then upon their ratification, they
are integrated into the Unprivileged or Privileged specs as a chapter.
> I'm open to correction and elucidation. :-)
> Thanks again
>
> Regards
> Tommy
>
> —
> Reply to this email directly, view it on GitHub
> <#1400 (comment)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAAN6ZABFRRMCTXRCMYCHPLZCIE7ZAVCNFSM6AAAAABHUAFBAGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMJQGIYTIMBQGE>
> .
> You are receiving this because you commented.Message ID:
> ***@***.***>
>
TommyMurphyTM1234 commented
Hi Bill
Thanks for your replies and attempts to clarify.
Unfortunately I remain confused on several points in terms of what exactly is ratified versus frozen versus draft and where to find the relevant authoritative info/specs.
In my opinion the RVI Specifications page really needs to be clearer on such issues assuming that it is the first port of call for many/most people who go looking for specs.
I would suggest changes if I could but unfortunately I remain too confused to suggest anything constructive right now.
Regards
Tommy
wmat commented
Hi Tommy, thanks for your feedback. Let me see if I can add some clarity
to the current landscape:
1. The two published (20240411) primary ISA specifications, Volume I:
Unprivileged and Volume II: Privileged include (as chapters) ALL ratified
specifications up to that publication date of 20240411. Fundamentally, the
technical content of these specifications is ratified and will not change.
Non-substantive changes may occur, such as fixes to typos or clean up of
any content that may not have been updated correctly at time of
ratification. An example of the latter is the updating of wording around
version as it may sometimes get missed. These specifications are linked
from the Specifications Page <https://riscv.org/technical/specifications/> on
riscv.org.
I will caveat #1 by saying that we will be making one last update to the
published ISA specs in the coming week as there was some content that was
causing confusion, namely the versioning of the vector chapter and some
wording around a possible new version of the vector chapter that was not
needed.
2. Frozen vs. Draft. These are defined in the RISC-V Lifecycle Guide
<https://docs.google.com/document/d/1Au3veNdNJQKPq-oiQRKTzdgmM72FDaqZOKeH7sOnG04/edit?usp=sharing>
.
3. Work on non-ratified ISA specifications will occur on Branches of the
riscv-isa-manual on GitHub. Extension authors are now encouraged to branch
the main repository, document their extension specification (in Draft) for
consideration and review following the Lifecycle, and finally issue a Pull
Request upon ratification. Therefore, the top-of-tree of the
riscv-isa-manual will continue to move forward with new chapters as new
extensions are ratified. At a future date, after a period of time
accumulating new contributions at top-of-tree, a new published version of
the manuals will be generated and replace those previously linked to from
the Specifications Page on riscv.org.
I hope this provides some clarity. Please feel free to reach back out with
any questions you may have.
…On Tue, May 14, 2024 at 6:03 PM Tommy Murphy ***@***.***> wrote:
Hi Bill
Thanks for your replies and attempts to clarify.
Unfortunately I remain confused on several points in terms of what exactly
is ratified versus frozen versus draft and where to find the relevant
authoritative info/specs.
In my opinion the RVI Specifications page really needs to be clearer on
such issues assuming that it is the first port of call for many/most people
who go looking for specs.
I would suggest changes if I could but unfortunately I remain too confused
to suggest anything constructive right now.
Regards
Tommy
—
Reply to this email directly, view it on GitHub
<#1400 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAN6ZGVKKDMQ5UOM3ELHVDZCKC3PAVCNFSM6AAAAABHUAFBAGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMJRGIYTAOBRGQ>
.
You are receiving this because you commented.Message ID:
***@***.***>
kasanovic commented
Just to add one minor point to Bill's explanation - we will also be archiving older versions of the published spec on the Specifications page, but in a way that ensures folks first are pointed at the most current one.