Status of v1.12 privileged specification


Greg Chadwick
 

> Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Depending on how much we rely on the git repository being the source of truth you could reference the git commit SHA-1 that was used to generate the PDF along with the more human readable document version (e.g. only include the SHA1 in a footnote or a references section).

So for say the 'misa' section of the current latest ratified privileged spec (this one https://github.com/riscv/riscv-isa-manual/releases/download/Priv-v1.12/riscv-privileged-20211203.pdf)  you would say something like

Section 3.1.1 'Machine ISA Register misa' of The RISC-V Instruction Set Manual Volume II: Privileged Architecture version 20211203 SHA 9896426

Obviously you would need a shorthand for that lot.


On Wed, Jul 27, 2022 at 5:47 PM Allen Baum <allen.baum@...> wrote:
Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Andrew's suggestion is a good one - but it needs to be communicated.

A slightly different issue is that these documents that this may not take into account references to extensions that have been ratified but have not been updated in the most up-to-date ratified spec yet but are in the draft). 
Maybe that problem will go away when it's all in asciidoc and updates can be made more timely.





On Tue, Jul 26, 2022 at 11:46 PM <krste@...> wrote:

There will be an annual release of all the specs, which can be
reference as Andrew says.

But, use the extension name as a key.  If the extension doesn't have a
name, we'll give it a name.

Krste

>>>>> On Tue, 26 Jul 2022 23:14:42 -0700, "Greg Favor" <gfavor@...> said:

| On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
|     So " In general every new extension will be a separate new chapter."
|     But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
|     The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
|     in docs all over the ecosystem. 

|     I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
|     If sections change numbers, then a lot of those test questions will need to be rewritten. 
|      I'm sure that won't be the only place, and tracking them all down will be a pain.

| Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and
| section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

| If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would
| bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

| Greg


Greg Favor
 

On Wed, Jul 27, 2022 at 9:47 AM Allen Baum <allen.baum@...> wrote:
Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Andrew's suggestion is a good one - but it needs to be communicated.

I would suggest talking with Mark to see what he thinks would be a suitable way to both document and communicate this.  It's especially not clear what would be an effective way to do the former.  Although this issue maybe folds in with the overall "RISC-V Documentation" ball of wax (which certainly will need practices to be documented and communicated).

Greg


Allen Baum
 

Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Andrew's suggestion is a good one - but it needs to be communicated.

A slightly different issue is that these documents that this may not take into account references to extensions that have been ratified but have not been updated in the most up-to-date ratified spec yet but are in the draft). 
Maybe that problem will go away when it's all in asciidoc and updates can be made more timely.





On Tue, Jul 26, 2022 at 11:46 PM <krste@...> wrote:

There will be an annual release of all the specs, which can be
reference as Andrew says.

But, use the extension name as a key.  If the extension doesn't have a
name, we'll give it a name.

Krste

>>>>> On Tue, 26 Jul 2022 23:14:42 -0700, "Greg Favor" <gfavor@...> said:

| On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
|     So " In general every new extension will be a separate new chapter."
|     But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
|     The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
|     in docs all over the ecosystem. 

|     I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
|     If sections change numbers, then a lot of those test questions will need to be rewritten. 
|      I'm sure that won't be the only place, and tracking them all down will be a pain.

| Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and
| section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

| If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would
| bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

| Greg


Krste Asanovic
 

There will be an annual release of all the specs, which can be
reference as Andrew says.

But, use the extension name as a key. If the extension doesn't have a
name, we'll give it a name.

Krste

On Tue, 26 Jul 2022 23:14:42 -0700, "Greg Favor" <gfavor@...> said:
| On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
| So " In general every new extension will be a separate new chapter."
| But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
| The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
| in docs all over the ecosystem. 

| I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
| If sections change numbers, then a lot of those test questions will need to be rewritten. 
|  I'm sure that won't be the only place, and tracking them all down will be a pain.

| Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and
| section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

| If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would
| bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

| Greg

|


Andrew Waterman
 



On Tue, Jul 26, 2022 at 11:15 PM Greg Favor <gfavor@...> wrote:
On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
So " In general every new extension will be a separate new chapter."
But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
in docs all over the ecosystem. 

I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
If sections change numbers, then a lot of those test questions will need to be rewritten. 
 I'm sure that won't be the only place, and tracking them all down will be a pain.

Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

Or just point to a specific spec PDF...


Greg


Greg Favor
 

On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
So " In general every new extension will be a separate new chapter."
But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
in docs all over the ecosystem. 

I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
If sections change numbers, then a lot of those test questions will need to be rewritten. 
 I'm sure that won't be the only place, and tracking them all down will be a pain.

Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

Greg


Allen Baum
 

So " In general every new extension will be a separate new chapter."
But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
in docs all over the ecosystem. 

I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
If sections change numbers, then a lot of those test questions will need to be rewritten. 
 I'm sure that won't be the only place, and tracking them all down will be a pain.

On Tue, Jul 26, 2022 at 9:51 AM Greg Favor <gfavor@...> wrote:
On Tue, Jul 26, 2022 at 8:05 AM Greg Chadwick <gac@...> wrote:
I appreciate no guarantees are possible but is it anticipated that the final v1.12 of the RISC-V privileged specification will be the  v. 20211203 currently listed on the RISC-V website (https://riscv.org/technical/specifications/) along with copy edits and the relevant already ratified extensions integrated (Smepmp, Smstateen, Sstc) as new chapters as the Svinval, Svnapot, Svpbmt extensions already are?

From that version onwards the ratified chapters are frozen other than "typo" corrections and clarifications.  The plan is for all Priv-related ratified extensions to be integrated into the Priv document (i.e. to have them all in one document), and for the Priv (and Unpriv) documents to be converted to adoc and to the new RVI adoc format.  These are active works in progress.  In general every new extension will be a separate new chapter.
 
Am I right in my understanding that support of new extensions for a particular implementation is determined via the (as yet to be defined) structure pointed to by the mconfigptr CSR

Yes.
 
and that any instructions introduced by one of those extensions should cause an illegal instruction exception where that extension isn't supported?

The current ISA arch specs do not require that unimplemented instructions result in an Illegal Instruction trap.  That is left for an ISA Profile or a Platform to recommend or mandate.

Greg


Greg Favor
 

On Tue, Jul 26, 2022 at 8:05 AM Greg Chadwick <gac@...> wrote:
I appreciate no guarantees are possible but is it anticipated that the final v1.12 of the RISC-V privileged specification will be the  v. 20211203 currently listed on the RISC-V website (https://riscv.org/technical/specifications/) along with copy edits and the relevant already ratified extensions integrated (Smepmp, Smstateen, Sstc) as new chapters as the Svinval, Svnapot, Svpbmt extensions already are?

From that version onwards the ratified chapters are frozen other than "typo" corrections and clarifications.  The plan is for all Priv-related ratified extensions to be integrated into the Priv document (i.e. to have them all in one document), and for the Priv (and Unpriv) documents to be converted to adoc and to the new RVI adoc format.  These are active works in progress.  In general every new extension will be a separate new chapter.
 
Am I right in my understanding that support of new extensions for a particular implementation is determined via the (as yet to be defined) structure pointed to by the mconfigptr CSR

Yes.
 
and that any instructions introduced by one of those extensions should cause an illegal instruction exception where that extension isn't supported?

The current ISA arch specs do not require that unimplemented instructions result in an Illegal Instruction trap.  That is left for an ISA Profile or a Platform to recommend or mandate.

Greg


Greg Chadwick
 

Hello,

I appreciate no guarantees are possible but is it anticipated that the final v1.12 of the RISC-V privileged specification will be the  v. 20211203 currently listed on the RISC-V website (https://riscv.org/technical/specifications/) along with copy edits and the relevant already ratified extensions integrated (Smepmp, Smstateen, Sstc) as new chapters as the Svinval, Svnapot, Svpbmt extensions already are?

Am I right in my understanding that support of new extensions for a particular implementation is determined via the (as yet to be defined) structure pointed to by the mconfigptr CSR and that any instructions introduced by one of those extensions should cause an illegal instruction exception where that extension isn't supported?

Kind Regards,

Greg Chadwick
Digital Design Lead
lowRISC C.I.C