Skip to content

fix: remove all tagging from descriptions #1138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix: remove all tagging from descriptions #1138

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
992a0cf
fix: removed the tags from descriptions
sudo-apt-abdullah Sep 26, 2025
b4cb645
do chore:update_golden_appendix
sudo-apt-abdullah Sep 29, 2025
7c34b30
removed the unnecessary when
sudo-apt-abdullah Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 6 additions & 9 deletions backends/instructions_appendix/all_instructions.golden.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -569,8 +569,6 @@ Encoding::
Description::
This instruction implements the rotation, SubBytes and Round Constant addition steps of the AES
block cipher Key Schedule.


`rnum` must be in the range `0x0..0xA`. The values `0xB..0xF` are reserved.


Expand Down Expand Up @@ -7268,7 +7266,7 @@ Encoding::
....

Description::
The xref:insts:fadd_d.adoc#udb:doc:inst:fadd_d[fadd.d] instruction is analogous to xref:insts:fadd_s.adoc#udb:doc:inst:fadd_s[fadd.s] and performs double-precision floating-point addition between
The xref:insts:fadd_d.adoc#udb:doc:inst:fadd_d[fadd.d] instruction is analogous to xref:insts:fadd_s.adoc#udb:doc:inst:fadd_s[fadd.s] and performs double-precision floating-point addition of
`fs1` and `fs2` and writes the final result to `fd`.


Expand Down Expand Up @@ -7387,7 +7385,7 @@ Encoding::
....

Description::
The xref:insts:fadd_s.adoc#udb:doc:inst:fadd_s[fadd.s] instruction performs single-precision floating-point addition of `xs1` and `xs2`
The xref:insts:fadd_s.adoc#udb:doc:inst:fadd_s[fadd.s] instruction performs single-precision floating-point addition of `fs1` and `fs2`
and writes the final result to `fd`.


Expand Down Expand Up @@ -10622,8 +10620,7 @@ Encoding::
....

Description::
The
The xref:insts:fli_q.adoc#udb:doc:inst:fli_q[fli.q] instruction loads one of 32 quad-precision floating-point constants, encoded in the `rs1`
The xref:insts:fli_q.adoc#udb:doc:inst:fli_q[fli.q] instruction loads one of 32 quad-precision floating-point constants, encoded in the `xs1`
field, into floating-point register `rd`.
xref:insts:fli_q.adoc#udb:doc:inst:fli_q[fli.q] is encoded like xref:insts:fmv_w_x.adoc#udb:doc:inst:fmv_w_x[fmv.w.x], but with _fmt_ = Q.

Expand Down Expand Up @@ -12246,7 +12243,7 @@ Included in::
== fmv.d.x

Synopsis::
Floating-Point Move from Integer Register to Double-Precision Register
Floating-Point Move Double-Precision from Integer Register

Assembly::
fmv.d.x fd, xs1
Expand Down Expand Up @@ -12365,7 +12362,7 @@ Included in::
== fmv.x.d

Synopsis::
Floating-Point Move from Double-Precision Register to Integer Register
Floating-Point Move Double-Precision to Integer Register

Assembly::
fmv.x.d xd, fs1
Expand Down Expand Up @@ -12631,7 +12628,7 @@ Encoding::
Description::
The xref:insts:fmvp_q_x.adoc#udb:doc:inst:fmvp_q_x[fmvp.q.x] instruction moves a double-precision number from a pair of integer registers into
a floating-point register.
Integer registers xs1 and xs2 supply bits 63:0 and 127:64, respectively; the result is written to
Integer registers `xs1` and `xs2` supply bits 63:0 and 127:64, respectively; the result is written to
floating-point register `fd`.
xref:insts:fmvp_q_x.adoc#udb:doc:inst:fmvp_q_x[fmvp.q.x] is encoded in the OP-FP major opcode with _funct3_=0 and _funct7_=1011011.

Expand Down
129 changes: 53 additions & 76 deletions spec/custom/non_isa/preface_demo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,12 @@ name: preface
long_name: Preface (Demo)
version: 1.0.0
ratification_date: "2025-08-08"
description:
- id: spec-preface-overview
normative: false
text: |
This Programmer's Reference Manual (PRM) provides comprehensive documentation for a generic RISC-V processor implementation. It is intended for system designers, integrators, verification engineers, and software developers working with RISC-V-based systems.
description: |
This Programmer's Reference Manual (PRM) provides comprehensive documentation for a generic RISC-V processor implementation. It is intended for system designers, integrators, verification engineers, and software developers working with RISC-V-based systems.

The manual covers the processor architecture, instruction set, control and status registers, memory management, debug and trace features, and other essential aspects. It aims to clarify both standard RISC-V features and implementation-defined options, supporting robust and portable software development.
The manual covers the processor architecture, instruction set, control and status registers, memory management, debug and trace features, and other essential aspects. It aims to clarify both standard RISC-V features and implementation-defined options, supporting robust and portable software development.

This document is suitable for public distribution and does not contain proprietary or vendor-specific content. All examples and descriptions are generic and based on open RISC-V standards.
This document is suitable for public distribution and does not contain proprietary or vendor-specific content. All examples and descriptions are generic and based on open RISC-V standards.
authors:
- name: RISC-V Community
organization:
Expand All @@ -28,85 +25,65 @@ license:
url: https://spdx.org/licenses/CC0-1.0.html
sections:
- title: About This Manual
content:
- id: sec-preface-about
normative: false
text: |
This manual is organized to guide users through the essential features of a RISC-V processor. It begins with an overview of the architecture and programming model, followed by chapters on the instruction set, privilege levels, memory subsystem, and system integration topics. Each chapter provides references to the official RISC-V specifications and highlights implementation-defined aspects where relevant.
content: |
This manual is organized to guide users through the essential features of a RISC-V processor. It begins with an overview of the architecture and programming model, followed by chapters on the instruction set, privilege levels, memory subsystem, and system integration topics. Each chapter provides references to the official RISC-V specifications and highlights implementation-defined aspects where relevant.

The manual is designed to be accessible to both new and experienced users, with clear explanations, diagrams, and practical examples. It emphasizes portability, compliance with RISC-V standards, and best practices for system design and software development.
The manual is designed to be accessible to both new and experienced users, with clear explanations, diagrams, and practical examples. It emphasizes portability, compliance with RISC-V standards, and best practices for system design and software development.
- title: Audience
content:
- id: sec-preface-audience
normative: false
text: |
This document is intended for:
content: |
This document is intended for:

* System architects and designers
* Hardware and software engineers
* Verification and validation teams
* Technical writers and educators
* System architects and designers
* Hardware and software engineers
* Verification and validation teams
* Technical writers and educators

The manual assumes a basic familiarity with computer architecture and programming concepts, but provides background information and references for further study.
- id: sec-preface-audience-conditional
normative: false
text: |
This section is only included for educational distributions.
when(): "distribution_type == 'educational'"
The manual assumes a basic familiarity with computer architecture and programming concepts, but provides background information and references for further study.

This section is only included for educational distributions.
when(): "distribution_type == 'educational'"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the previous content, this when() method applied only to the preceding line.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the previous content, this when() method applied only to the preceding line.

I'm sorry, but I couldn't get it. Can you please elaborate?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The content without the changes here is:

      - id: sec-preface-audience-conditional
        normative: false
        text: |
          This section is only included for educational distributions.
        when(): "distribution_type == 'educational'"

So, the when() conditional only applies to that single line.

With these changes, I think that the "description" is still defined as an array of "tagged_text", but that definition was renamed to "conditional_text", so I'm a bit confused how the CI tests passed. I must be missing something.

Anyway, in these changes, the when() clause is associated with all of the previous text, which is not desired.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There were some tagged description with when(): condition, especially in hstatus.yaml. So, I updated the definition from tagged_text to conditional_text after removing tags, so that it can make more sense now.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But with these latest changes (when() removed), that phrase is no longer suppressed, as it was previously. Can we get back to the original behavior, where that clause, and only that clause, is conditionally displayed?

- title: Notation and Conventions
content:
- id: sec-preface-notation
normative: false
text: |
The following conventions are used throughout this manual:
content: |
The following conventions are used throughout this manual:

* Register and field names are shown in `monospace` font.
* Bit values are indicated as 0 (read-only zero) or 1 (read-only one).
* References to RISC-V specifications are provided for standard features.
* Implementation-defined options are clearly marked and explained.
* Register and field names are shown in `monospace` font.
* Bit values are indicated as 0 (read-only zero) or 1 (read-only one).
* References to RISC-V specifications are provided for standard features.
* Implementation-defined options are clearly marked and explained.
- title: Document Organization
content:
- id: sec-preface-organization
normative: false
text: |
Chapters include:
content: |
Chapters include:

* Architecture Overview
* Instruction Set Architecture
* Privileged Architecture
* Interrupts and Exceptions
* Memory Subsystem
* Memory Management
* Reliability, Availability, and Serviceability (RAS)
* Floating Point Unit
* Debug and Trace
* Triggers and Watchpoints
* Power Management
* Performance Monitoring
* Timers and Watchdog
* Security Features
* Control and Status Registers
* Build and Configuration Options
* Acronyms and Definitions
* References
* Architecture Overview
* Instruction Set Architecture
* Privileged Architecture
* Interrupts and Exceptions
* Memory Subsystem
* Memory Management
* Reliability, Availability, and Serviceability (RAS)
* Floating Point Unit
* Debug and Trace
* Triggers and Watchpoints
* Power Management
* Performance Monitoring
* Timers and Watchdog
* Security Features
* Control and Status Registers
* Build and Configuration Options
* Acronyms and Definitions
* References

Each chapter is self-contained and provides links to related topics and external resources.
Each chapter is self-contained and provides links to related topics and external resources.
- title: Web Resources
content:
- id: sec-preface-web
normative: true
text: |
For more information on RISC-V standards and open-source resources, visit:
content: |
For more information on RISC-V standards and open-source resources, visit:

* https://riscv.org
* https://github.com/riscv/riscv-isa-manual
* https://github.com/riscv/riscv-debug-spec
* https://github.com/riscv-software-src
* https://riscv.org
* https://github.com/riscv/riscv-isa-manual
* https://github.com/riscv/riscv-debug-spec
* https://github.com/riscv-software-src

Community forums, mailing lists, and technical documentation are available to support developers and users worldwide.
Community forums, mailing lists, and technical documentation are available to support developers and users worldwide.
- title: Revision History
content:
- id: sec-preface-history
normative: true
text: |
Version 1.0.0 (2025-08-08): Initial public release of the demo Programmer's Reference Manual for RISC-V processors.
content: |
Version 1.0.0 (2025-08-08): Initial public release of the demo Programmer's Reference Manual for RISC-V processors.
13 changes: 3 additions & 10 deletions spec/schemas/schema_defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,26 +102,19 @@
{
"type": "array",
"items": {
"$ref": "#/$defs/tagged_text"
"$ref": "#/$defs/conditional_text"
}
}
]
},
"tagged_text": {
"conditional_text": {
"type": "object",
"required": ["id", "text", "normative"],
"required": ["text"],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the statement"
},
"text": {
"type": "string",
"description": "Asciidoctor source"
},
"normative": {
"type": "boolean"
},
"when()": {
"type": "string",
"description": "IDL boolean expression. When true, the text applies"
Expand Down
26 changes: 10 additions & 16 deletions spec/std/isa/csr/F/fflags.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,16 @@ name: fflags
long_name: Floating-Point Accrued Exceptions
address: 0x001
writable: true
description:
- id: csr-fflags-purpose
normative: true
text: |
The accrued exception flags indicate the exception conditions that have arisen on any floating-point arithmetic
instruction since the field was last reset by software.
- id: csr-fflags-fptrap
normative: false
text: The base RISC-V ISA does not support generating a trap on the setting of a floating-point exception flag.
- id: csr-fflags-reasoning
normative: false
text: |
As allowed by the standard, we do not support traps on floating-point exceptions in the F
extension, but instead require explicit checks of the flags in software. We considered
adding branches controlled directly by the contents of the floating-point accrued
exception flags, but ultimately chose to omit these instructions to keep the ISA simple.
description: |
The accrued exception flags indicate the exception conditions that have arisen on any floating-point arithmetic
instruction since the field was last reset by software.

The base RISC-V ISA does not support generating a trap on the setting of a floating-point exception flag.

As allowed by the standard, we do not support traps on floating-point exceptions in the F
extension, but instead require explicit checks of the flags in software. We considered
adding branches controlled directly by the contents of the floating-point accrued
exception flags, but ultimately chose to omit these instructions to keep the ISA simple.

priv_mode: U
length: 32
Expand Down
57 changes: 25 additions & 32 deletions spec/std/isa/csr/F/frm.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,39 +9,32 @@ name: frm
long_name: Floating-Point Dynamic Rounding Mode
address: 0x002
writable: true
description:
- id: csr-frm-encodings
normative: false
text: |
Rounding modes are encoded as follows:
description: |
Rounding modes are encoded as follows:

[[rm]]
.Rounding mode encoding.
[%autowidth,float="center",align="center",cols="^,^,<",options="header"]
!===
!Rounding Mode |Mnemonic |Meaning
!000 !RNE !Round to Nearest, ties to Even
!001 !RTZ !Round towards Zero
!010 !RDN !Round Down (towards latexmath:[$-\infty$])
!011 !RUP !Round Up (towards latexmath:[$+\infty$])
!100 !RMM !Round to Nearest, ties to Max Magnitude
!101 ! !_Reserved for future use._
!110 ! !_Reserved for future use._
!111 !DYN !In instruction's _rm_ field, selects dynamic rounding mode; In Rounding Mode register, _reserved_.
!===
- id: csr-frm-reserved
normative: false
text: |
The behavior of floating-point instructions that depend on rounding mode when
executed with a reserved rounding mode is _reserved_, including both static
reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).
- id: csr-frm-rmfield
normative: false
text: |
Some instructions, including widening conversions, have the _rm_ field but are
nevertheless mathematically unaffected by the rounding mode; software should set
their _rm_ field to RNE (000) but implementations must treat the _rm_ field as
usual (in particular, with regard to decoding legal vs. reserved encodings).
[[rm]]
.Rounding mode encoding.
[%autowidth,float="center",align="center",cols="^,^,<",options="header"]
!===
!Rounding Mode |Mnemonic |Meaning
!000 !RNE !Round to Nearest, ties to Even
!001 !RTZ !Round towards Zero
!010 !RDN !Round Down (towards latexmath:[$-\infty$])
!011 !RUP !Round Up (towards latexmath:[$+\infty$])
!100 !RMM !Round to Nearest, ties to Max Magnitude
!101 ! !_Reserved for future use._
!110 ! !_Reserved for future use._
!111 !DYN !In instruction's _rm_ field, selects dynamic rounding mode; In Rounding Mode register, _reserved_.
!===

The behavior of floating-point instructions that depend on rounding mode when
executed with a reserved rounding mode is _reserved_, including both static
reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).

Some instructions, including widening conversions, have the _rm_ field but are
nevertheless mathematically unaffected by the rounding mode; software should set
their _rm_ field to RNE (000) but implementations must treat the _rm_ field as
usual (in particular, with regard to decoding legal vs. reserved encodings).

priv_mode: U
length: 32
Expand Down
Loading
Loading