From 4393af7e12d7e689c533f57c7b46febc16b2192f Mon Sep 17 00:00:00 2001 From: beeman Date: Mon, 14 Aug 2023 16:41:02 -0700 Subject: [PATCH] convert from gdoc --- Makefile | 128 ++++++++++----------- body.adoc | 280 ++++++++++++++++++++++++++++++++++++++++++++++ contributors.adoc | 16 +-- header.adoc | 128 +++++++++++---------- intro.adoc | 56 +++++++--- readme.adoc | 218 ++++++++++++++++++------------------ 6 files changed, 565 insertions(+), 261 deletions(-) create mode 100644 body.adoc diff --git a/Makefile b/Makefile index ad48dfe..73cbcdb 100644 --- a/Makefile +++ b/Makefile @@ -1,65 +1,65 @@ -# Makefile for RISC-V Doc Template -# -# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 -# International License. To view a copy of this license, visit -# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to -# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. -# -# SPDX-License-Identifier: CC-BY-SA-4.0 -# -# Description: -# -# This Makefile is designed to automate the process of building and packaging -# the Doc Template for RISC-V Extensions. - -DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= v0.0.0 -REVMARK ?= Draft -DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ -riscvintl/riscv-docs-base-container-image:latest - -HEADER_SOURCE := header.adoc -PDF_RESULT := spec-sample.pdf - -ASCIIDOCTOR_PDF := asciidoctor-pdf -OPTIONS := --trace \ - -a compress \ - -a mathematical-format=svg \ - -a revnumber=${VERSION} \ - -a revremark=${REVMARK} \ - -a revdate=${DATE} \ - -a pdf-fontsdir=docs-resources/fonts \ - -a pdf-style=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR -REQUIRES := --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical - -.PHONY: all build clean build-container build-no-container - -all: build - -build: - @echo "Checking if Docker is available..." - @if command -v docker &> /dev/null ; then \ - echo "Docker is available, building inside Docker container..."; \ - $(MAKE) build-container; \ - else \ - echo "Docker is not available, building without Docker..."; \ - $(MAKE) build-no-container; \ - fi - -build-container: - @echo "Starting build inside Docker container..." - $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" - @echo "Build completed successfully inside Docker container." - -build-no-container: - @echo "Starting build..." - $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) - @echo "Build completed successfully." - -clean: - @echo "Cleaning up generated files..." - rm -f $(PDF_RESULT) +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. + +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v1.0.0 +REVMARK ?= Stable +DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ +riscvintl/riscv-docs-base-container-image:latest + +HEADER_SOURCE := header.adoc +PDF_RESULT := riscv-indirect-csr-access.pdf + +ASCIIDOCTOR_PDF := asciidoctor-pdf +OPTIONS := --trace \ + -a compress \ + -a mathematical-format=svg \ + -a revnumber=${VERSION} \ + -a revremark=${REVMARK} \ + -a revdate=${DATE} \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-style=docs-resources/themes/riscv-pdf.yml \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical + +.PHONY: all build clean build-container build-no-container + +all: build + +build: + @echo "Checking if Docker is available..." + @if command -v docker &> /dev/null ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) + @echo "Build completed successfully." + +clean: + @echo "Cleaning up generated files..." + rm -f $(PDF_RESULT) @echo "Cleanup completed." \ No newline at end of file diff --git a/body.adoc b/body.adoc new file mode 100644 index 0000000..87ffbab --- /dev/null +++ b/body.adoc @@ -0,0 +1,280 @@ +== Machine-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x350 |MRW |XLEN |miselect |Machine indirect register select +|0x351 |MRW |XLEN |mireg |Machine indirect register alias +|0x352 |MRW |XLEN |mireg2 |Machine indirect register alias 2 +|0x353 |MRW |XLEN |mireg3 |Machine indirect register alias 3 +|0x355 |MRW |XLEN |mireg4 |Machine indirect register alias 4 +|0x356 |MRW |XLEN |mireg5 |Machine indirect register alias 5 +|0x357 |MRW |XLEN |mireg6 |Machine indirect register alias 6 +|=== + +[NOTE] +==== +_The mireg* CSR numbers are not consecutive because miph is CSR number +0x354._ +==== + +The CSRs listed in the table above provide a window for accessing +register state indirectly. The value of miselect determines which +registers are currently accessible through the machine indirect alias +CSRs (mireg*). miselect value ranges are allocated to dependent +extensions, which specify the register state accessible via each +mireg__i__ register, for each miselect value. miselect is a WARL +register. + +The miselect register implements at least enough bits to support all +implemented miselect values (corresponding to the implemented extensions +that utilize miselect/mireg* to indirectly access register state). The +miselect register may be read-only zero If there are no extensions +implemented that utilize it. + +Values of miselect with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom +registers through the alias CSRs. Values of miselect with the +most-significant bit clear are designated only for standard use and are +reserved until allocated to a standard architecture extension. If XLEN +is changed, the most-significant bit of miselect moves to the new +position, retaining its value from before. + +[NOTE] +==== +_An implementation is not required to support any custom values for +miselect._ +==== + +The behavior upon accessing mireg* from M-mode, while miselect holds a +value that is reserved, or is standard but not implemented, is +UNSPECIFIED. + +[NOTE] +==== +_It is expected that implementations will typically raise an illegal +instruction exception for such accesses, so that, for example, they can +be identified as software bugs. Platform specs, profile specs, and/or +the Privileged ISA spec may place more restrictions on behavior for such +accesses._ +==== + +Attempts to access mireg* while miselect holds a number in an allocated +and implemented range results in a specific behavior that, for each +combination of miselect and mireg__i__, is defined by the extension to +which the miselect value is allocated. + +[NOTE] +==== +__Ordinarily, each mireg__i _will access register state, access +read-only 0 state, or raise an illegal instruction exception._ + +_For RV32, if an extension defines an indirectly accessed register as 64 +bits wide, it is recommended that the lower 32 bits of the register are +accessed through one of mireg, mireg2, or mireg3, while the upper 32 +bits are accessed through mireg4, mireg5, or mireg6, respectively._ +==== + +== Supervisor-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x150 |SRW |XLEN |siselect |Supervisor indirect register select +|0x151 |SRW |XLEN |sireg |Supervisor indirect register alias +|0x152 |SRW |XLEN |sireg2 |Supervisor indirect register alias 2 +|0x153 |SRW |XLEN |sireg3 |Supervisor indirect register alias 3 +|0x155 |SRW |XLEN |sireg4 |Supervisor indirect register alias 4 +|0x156 |SRW |XLEN |sireg5 |Supervisor indirect register alias 5 +|0x157 |SRW |XLEN |sireg6 |Supervisor indirect register alias 6 +|=== + +The CSRs in the table above are required if S-mode is implemented. + +The siselect register will support the value range 0..0xFFF at a +minimum. A future extension may define a value range outside of this +minimum range. Only if such an extension is implemented will siselect be +required to support larger values. + +[NOTE] +==== +_Requiring a range of 0–0xFFF for siselect, even though most or +all of the space may be reserved or inaccessible, permits M-mode to +emulate indirectly accessed registers in this implemented range, +including registers that may be standardized in the future._ +==== + +Values of siselect with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom registers through the alias +CSRs. Values of siselect with the most-significant bit clear are +designated only for standard use and are reserved until allocated to a +standard architecture extension. If XLEN is changed, the +most-significant bit of siselect moves to the new position, retaining +its value from before. + +The behavior upon accessing sireg* from M-mode or S-mode, while siselect +holds a value that is reserved, or is standard but not implemented at +supervisor level, is UNSPECIFIED. + +[NOTE] +==== +_It is recommended that implementations raise an illegal instruction +exception for such accesses, to facilitate possible emulation (by +M-mode) of these accesses._ +==== +[NOTE] +==== +_An extension is considered not to be implemented at supervisor level if +machine level has disabled the extension for S-mode, such as by the +settings of certain fields in CSR menvcfg, for example._ +==== + +Otherwise, attempts to access sireg* from M-mode or S-mode while +siselect holds a number in a standard-defined and implemented range +result in specific behavior that, for each combination of siselect and +sireg__i__, is defined by the extension to which the siselect value is +allocated. + +[NOTE] +==== +__Ordinarily, each sireg__i _will access register state, access +read-only 0 state, or, unless executing in a virtual machine (covered in +the next section), raise an illegal instruction exception._ +==== + +Note that the widths of siselect and sireg* are always the +current XLEN rather than SXLEN. Hence, for example, if MXLEN = 64 and +SXLEN = 32, then these registers are 64 bits when the current privilege +mode is M (running RV64 code) but 32 bits when the privilege mode is S +(RV32 code). + +== Virtual Supervisor-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x250 |HRW |XLEN |vsiselect |Virtual supervisor indirect register +select + +|0x251 |HRW |XLEN |vsireg |Virtual supervisor indirect register alias + +|0x252 |HRW |XLEN |vsireg2 |Virtual supervisor indirect register alias 2 + +|0x253 |HRW |XLEN |vsireg3 |Virtual supervisor indirect register alias 3 + +|0x255 |HRW |XLEN |vsireg4 |Virtual supervisor indirect register alias 4 + +|0x256 |HRW |XLEN |vsireg5 |Virtual supervisor indirect register alias 5 + +|0x257 |HRW |XLEN |vsireg6 |Virtual supervisor indirect register alias 6 +|=== + +The CSRs in the table above are required if the hypervisor extension is +implemented. These VS CSRs all match supervisor CSRs, and substitute for +those supervisor CSRs when executing in a virtual machine (in VS-mode or +VU-mode). + +The vsiselect register will support the value range 0..0xFFF at a +minimum. A future extension may define a value range outside of this +minimum range. Only if such an extension is implemented will vsiselect +be required to support larger values. + +[NOTE] +==== +_Requiring a range of 0–0xFFF for vsiselect, even though most or all of +the space may be reserved or inaccessible, permits a hypervisor to +emulate indirectly accessed registers in this implemented range, +including registers that may be standardized in the future._ + +_More generally it is recommended that vsiselect and siselect be +implemented with the same number of bits. This also avoids creation of a +virtualization hole due to observable differences between vsiselect and +siselect widths._ +==== + +Values of vsiselect with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom registers through the alias +CSRs. Values of vsiselect with the most-significant bit clear are +designated only for standard use and are reserved until allocated to a +standard architecture extension. If XLEN is changed, the +most-significant bit of vsiselect moves to the new position, retaining +its value from before. + +For alias CSRs sireg* and vsireg*, the hypervisor extension’s usual +rules for when to raise a virtual instruction exception (based on +whether an instruction is HS-qualified) are not applicable. The +rules given in this section for sireg and vsireg apply instead, unless +overridden by the requirements specified in the section below, which +take precedence over this section when extension Smstateen is also +implemented. + +A virtual instruction exception is raised for attempts from VS-mode or +VU-mode to directly access vsiselect or vsireg*, or attempts from +VU-mode to access siselect or sireg*. + +The behavior upon accessing vsireg* from M-mode or HS-mode, or accessing +sireg* (really vsireg*) from VS-mode, while vsiselect holds a value that +is reserved, or is standard but not implemented at HS level, is +UNSPECIFIED. + +[NOTE] +==== +_It is recommended that implementations raise an illegal instruction +exception for such accesses, to facilitate possible emulation (by M-mode +or HS-mode) of these accesses._ +==== + +Otherwise, while vsiselect holds a number in a standard-defined and +implemented range, attempts to access vsireg* from a sufficiently +privileged mode, or to access sireg* (really vsireg*) from VS-mode, +result in specific behavior that, for each combination of vsiselect and +vsireg__i__, is defined by the extension to which the vsiselect value is +allocated. + +[NOTE] +==== +__Ordinarily, each vsireg__i _will access register state, access +read-only 0 state, or raise an exception (either an illegal instruction +exception or, for select accesses from VS-mode or VU-mode, a virtual +instruction exception)._ +==== + +Like siselect and sireg*, the widths of vsiselect and vsireg* are always +the current XLEN rather than VSXLEN. Hence, for example, if HSXLEN = 64 +and VSXLEN = 32, then these registers are 64 bits when accessed by a +hypervisor in HS-mode (running RV64 code) but 32 bits for a guest OS in +VS-mode (RV32 code). + +== Access control by the state-enable CSRs + +If extension Smstateen is implemented together with Smcsrind, bit 60 of +state-enable register mstateen0 controls access to siselect, sireg*, +vsiselect, and vsireg*. When mstateen0[60]=0, an attempt to access one +of these CSRs from a privilege mode less privileged than M-mode results +in an illegal instruction exception. As always, the state-enable CSRs do +not affect the accessibility of any state when in M-mode, only in less +privileged modes. For more explanation, see the documentation for +extension +https://github.com/riscv/riscv-state-enable/releases/download/v1.0.0/Smstateen.pdf[[.underline]#Smstateen#]. + +Other extensions may specify that certain mstateen bits control access +to registers accessed indirectly through siselect + sireg*, and/or +vsiselect + vsireg*. However, regardless of any other mstateen bits, if +mstateen0[60] = 1, a virtual instruction exception is raised as +described in the previous section for all attempts from VS-mode or +VU-mode to directly access vsiselect or vsireg*, and for all attempts +from VU-mode to access siselect or sireg*. + +If the hypervisor extension is implemented, the same bit is defined also +in hypervisor CSR hstateen0, but concerns only siselect and sireg* +(really vsiselect and vsireg*), which is the state potentially +accessible to a virtual machine executing in VS or VU-mode. When +hstateen0[60]=0 and mstateen0[60]=1, all attempts from VS or VU-mode to +access siselect or sireg* raise a virtual instruction exception, not an +illegal instruction exception, regardless of the value of vsiselect or +any other mstateen bit. + +Extension Ssstateen is defined as the supervisor-level view of +Smstateen. Therefore, the combination of Sscsrind and Ssstateen +incorporates the bit defined above for hstateen0 but not that for +mstateen0, since machine-level CSRs are not visible to supervisor level. diff --git a/contributors.adoc b/contributors.adoc index 13fd776..0cca6c1 100644 --- a/contributors.adoc +++ b/contributors.adoc @@ -1,7 +1,9 @@ -== Contributors - -This RISC-V specification has been contributed to directly or indirectly by: - -[%hardbreaks] -* Author1 -* Author2 +== Contributors + +This RISC-V specification has been contributed to directly or indirectly by: + +[%hardbreaks] +* Beeman Strong +* John Hauser +* Greg Favor +* Krste Asanovic diff --git a/header.adoc b/header.adoc index 5fb1282..e33e42d 100644 --- a/header.adoc +++ b/header.adoc @@ -1,66 +1,64 @@ -= RISC-V Example Specification Document (Zexmpl) -Authors: Author 1, Author 2 -:docgroup: RISC-V Task Group -:description: RISC-V Example Specification Document (Zexmpl) -:company: RISC-V.org -:revdate: 1/2023 -:revnumber: 1.0 -:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. -:revinfo: -:url-riscv: http://riscv.org -:doctype: book -:preface-title: Preamble -:colophon: -:appendix-caption: Appendix -:imagesdir: docs-resources/images -:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] -// Settings: -:experimental: -:reproducible: -//:WaveDromEditorApp: app/wavedrom-editor.app -:imagesoutdir: docs-resources/images -:bibtex-file: example.bib -:bibtex-order: alphabetical -:bibtex-style: apa -:icons: font -:lang: en -:listing-caption: Listing -:sectnums: -:toc: left -:toclevels: 4 -:source-highlighter: pygments -ifdef::backend-pdf[] -:source-highlighter: coderay -endif::[] -:data-uri: -:hide-uri-scheme: -:stem: latexmath -:footnote: -:xrefstyle: short - -[WARNING] -.This document is in the link:http://riscv.org/spec-state[Development state] -==== -Expect potential changes. This draft specification is likely to evolve before -it is accepted as a standard. Implementations based on this draft -may not conform to the future standard. -==== - -[preface] -== Copyright and license information -This specification is licensed under the Creative Commons -Attribution 4.0 International License (CC-BY 4.0). The full -license text is available at -https://creativecommons.org/licenses/by/4.0/. - -Copyright 2022 by RISC-V International. - -[preface] -include::contributors.adoc[] - -include::intro.adoc[] -include::chapter2.adoc[] - -// The index must precede the bibliography -include::index.adoc[] += RISC-V Indirect CSR Access (Smcsrind/Sscsrind) +Authors: Beeman Strong, John Hauser +:docgroup: RISC-V Privileged ISA IC +:description: RISC-V Indirect CSR Access (Smcsrind/Sscsrind) +:company: RISC-V.org +:revdate: 8/2023 +:revnumber: 1.0.0-rc1 +:revremark: This document is in Stable state. Assume anything could still change, but limited change should be expected. Visit http://riscv.org/spec-state for further details. +:revinfo: +:url-riscv: http://riscv.org +:doctype: book +:preface-title: Preamble +:colophon: +:appendix-caption: Appendix +:imagesdir: docs-resources/images +:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] +// Settings: +:experimental: +:reproducible: +//:WaveDromEditorApp: app/wavedrom-editor.app +:imagesoutdir: docs-resources/images +:bibtex-file: example.bib +:bibtex-order: alphabetical +:bibtex-style: apa +:icons: font +:lang: en +:listing-caption: Listing +:sectnums: +:toc: left +:toclevels: 4 +:source-highlighter: pygments +ifdef::backend-pdf[] +:source-highlighter: coderay +endif::[] +:data-uri: +:hide-uri-scheme: +:stem: latexmath +:footnote: +:xrefstyle: short + +[WARNING] +.This document is in the link:http://riscv.org/spec-state[Stable state] +==== +Assume anything could still change, but limited change should be expected. +==== + +[preface] +== Copyright and license information +This specification is licensed under the Creative Commons +Attribution 4.0 International License (CC-BY 4.0). The full +license text is available at +https://creativecommons.org/licenses/by/4.0/. + +Copyright 2022 by RISC-V International. + +[preface] +include::contributors.adoc[] + +include::intro.adoc[] +include::body.adoc[] + +// The index must precede the bibliography +include::index.adoc[] include::bibliography.adoc[] \ No newline at end of file diff --git a/intro.adoc b/intro.adoc index 0d62327..012fb3e 100644 --- a/intro.adoc +++ b/intro.adoc @@ -1,15 +1,41 @@ -[[intro]] -== Introduction - -Lorem ipsum indexterm:[Lorem ipsum] dolor sit amet, consectetur adipiscing elit, sed do *eiusmod tempor* incididunt ut labore et dolore magna aliqua. Felis imperdiet proin fermentum leo vel orci porta. Volutpat lacus laoreet non curabitur indexterm:[curabitur] gravida indexterm:[gravida]. Posuere urna nec tincidunt praesent semper feugiat nibh. Elit ``ullamcorper`` dignissim cras tincidunt lobortis. Malesuada fames ac turpis egestas integer eget. Tristique sollicitudin nibh sit amet commodo. Sed felis eget velit aliquet. Sit amet aliquam id diam maecenas ultricies mi. Consectetur purus ut faucibus pulvinar. Lectus urna duis convallis convallis tellus id. Fermentum iaculis eu non diam. Feugiat in fermentum posuere urna nec tincidunt praesent semper feugiat. Urna nec tincidunt praesent semper feugiat nibh. - -Commodo viverra maecenas accumsan lacus. Vulputate odio ut enim blandit indexterm:[blandit] volutpat maecenas volutpat blandit. Urna porttitor rhoncus dolor purus non. Tellus mauris a diam maecenas sed. Vitae auctor eu augue ut lectus. Ridiculus mus mauris vitae ultricies leo integer. Consequat semper viverra nam *libero* justo laoreet sit amet. Pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus et. Ac placerat vestibulum lectus mauris ``ultrices`` eros in cursus turpis. Accumsan in nisl nisi scelerisque eu ultrices vitae. Cras ornare arcu dui vivamus. Vitae congue mauris rhoncus aenean. Consequat mauris nunc congue nisi vitae suscipit tellus. Tempus egestas sed sed risus pretium quam vulputate dignissim. Quis varius quam quisque id diam vel. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Amet mauris commodo quis imperdiet massa tincidunt nunc. - -[NOTE] -==== -The name RISC-V indexterm:[RISC-V] was chosen to represent the fifth major RISC ISA design from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first four). We also pun on the use of the Roman numeral "V" to signify "variations" and "vectors", as support for a range of architecture research, including various data-parallel accelerators, is an explicit goal of the ISA design. -==== - -=== Sub Section of Introduction - -Pellentesque habitant morbi *tristique* senectus et netus et. Aliquam purus sit amet luctus. Odio eu ``feugiat`` pretium nibh ipsum consequat nisl vel. Euismod lacinia at quis risus sed vulputate odio ut. Eu sem integer vitae justo eget. Cursus euismod quis viverra nibh. Tempus egestas sed sed risus. Quis imperdiet massa tincidunt nunc pulvinar. Id venenatis a condimentum vitae sapien pellentesque habitant. +[[intro]] +== Introduction + +Smcsrind/Sscsrind is an ISA extension that extends the indirect CSR +access mechanism originally defined as part of the +https://github.com/riscv/riscv-aia[[.underline]#Smaia/Ssaia +extensions#], in order to make it available for use by other extensions +without creating an unnecessary dependence on Smaia/Ssaia. + +This extension confers two benefits: + + +. It provides a means to access an array of registers via CSRs without +requiring allocation of large chunks of the limited CSR address space. + +. It enables software to access each of an array of registers by index, +without requiring a switch statement with a case for each register. + +[NOTE] +==== +_CSRs are accessed indirectly via this extension using select values, in +contrast to being accessed directly using standard CSR numbers. A CSR +accessible via one method may or may not be accessible via the other +method. Select values are a separate address space from CSR numbers, and +from tselect values in the Sdtrig extension. If a CSR is both directly +and indirectly accessible, the CSR's select value is unrelated to its +CSR number._ + +_Further, Machine-level and Supervisor-level select values are separate +address spaces from each other. Although Machine-level and +Supervisor-level CSRs with the same select value may be defined by an +extension as partial or full aliases with respect to each other. This +typically would be done for CSRs that can be delegated from +Machine-level to Supervisor-level._ +==== + +The machine-level extension *Smcsrind* encompasses all added CSRs and +all behavior modifications for a hart, over all privilege levels. For a +supervisor-level environment, extension *Sscsrind* is essentially the +same as Smcsrind except excluding the machine-level CSRs and behavior +not directly visible to supervisor level. \ No newline at end of file diff --git a/readme.adoc b/readme.adoc index dbc4538..d3bd33c 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,110 +1,108 @@ -= RISC-V Specification Template - -This repository serves as a blueprint for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. The template aims to facilitate and standardize the process of specification development. - -NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository. - -== License - -This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. - -== Contributors - -The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file. - -For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. - -== Building the Document - -=== Prerequisites - -To build the document, you'll need the following tools installed on your system: - -* Make -* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical -* Docker - -=== Cloning the Repository - -`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` - -=== Versioning, Customization and Makefile Variables - -This section provides an overview of the environment variables used in our Makefile. These variables include DATE, VERSION, and REVMARK. - -* `DATE`: Represents the current date. The default value is generated using the date command on Unix-based systems, formatted as "YYYY-MM-DD". -* `VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification. -* `REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release' or 'Stable'. -* `PDF_RESULT`: Specifies the name of the output PDF file. -* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. - -==== Versioning Strategy - -In a nutshell, the versioning strategy is as follows: - -```bash -[Start] - | - V -1.0.0-draft[#] --> (Revisions) --> 1.0.0-draft[#] (last draft) - | - V -1.0.0-rc[#] --> (Revisions) --> 1.0.0-rc[#] (last release candidate) - | - V -[Approval] - | - V -1.0.0 (Approved/Ratified) - | - V -(Minor changes, Fixes, Compatible extensions) --> 1.1.0 - | - V -(Corrections, Editorial changes) --> 1.1.1 - | - V -(Incompatible changes, Major new features) --> 2.0.0 -``` - -link:https://docs.google.com/document/d/1ZO3clTdgbm-t6r8GMDQ7CypWl68_3ZeYuHl4e-cS280/edit[RISC-V International has a policy for versioning] -. The purpose of this policy is to ensure consistency and clarity in the versioning of RISC-V artifacts, which can be comprehended by both the RISC-V community and external parties. This policy adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). - -The first ratified version of any artifact is expected to be 1.0.0. The policy outlines specific versioning conventions for different stages of specification development: 1.0.0-draft1 for drafts, 1.0.0-rc1 for release candidates, and 1.0.0 for approved and ratified specifications. Furthermore, the use of build-date metadata is encouraged for non-release versions. - -The MAJOR.MINOR.PATCH paradigm is explained as: PATCH for corrections or editorial changes, MINOR for fixes and compatible extensions with limited new functionality, and MAJOR for incompatible changes or significant new features. The policy is effective immediately upon approval. - -Examples: - -* Specification Development - Suppose a new RISC-V specification is being developed. Its version might start as 1.0.0-draft1 for the first draft, then proceed to 1.0.0-rc1 when it reaches the release candidate stage (1.0.0-rc2, 1.0.0-rc3, etc...), and finally settle at 1.0.0 when it's approved and ratified. - -* Update Types - If the ratified specification undergoes a minor update, incorporating fixes or compatible extensions with limited new functionality, it would change to 1.1.0. If there are only corrections or editorial modifications, the version would move to 1.0.1. For incompatible changes or major new features, the version would leap to 2.0.0. - -* Metadata Tagging - Non-release versions of the specification can be tagged with the build date. For example, if a draft version is prepared on June 29, 2023, it could be tagged as 1.0.0-draft1+20230629. - -==== Setting Environment Variables - -These variables can be overridden by setting environment variables on your system. Here's how you can do it in Linux and MacOS: - -```bash -export VERSION=v1.2.3 -export REVMARK=Release -export PDF_RESULT=spec.pdf -``` - -=== Building the Documentation - -To start the build process, run `cd ./docs-spec-template && make build`. - -The Makefile script will check the availability of Docker on your system: - -* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. -* If Docker is not available, the documentation will be built directly on your system using the installed tools. - -The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. - -The build process utilizes several options, including theming and font settings, and generates a PDF document as output. - -=== Cleaning up - -To clean up the generated files, run `make clean`. This will remove the generated PDF file. += RISC-V Indirect CSR Access Extension Specification + +This repository holds the specification for the RISC-V Indirect CSR Access (Smcsrind/Sscsrind) Extension. + +== License + +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. + +== Contributors + +The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file. + +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. + +== Building the Document + +=== Prerequisites + +To build the document, you'll need the following tools installed on your system: + +* Make +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical +* Docker + +=== Cloning the Repository + +`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` + +=== Versioning, Customization and Makefile Variables + +This section provides an overview of the environment variables used in our Makefile. These variables include DATE, VERSION, and REVMARK. + +* `DATE`: Represents the current date. The default value is generated using the date command on Unix-based systems, formatted as "YYYY-MM-DD". +* `VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification. +* `REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release' or 'Stable'. +* `PDF_RESULT`: Specifies the name of the output PDF file. +* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. + +==== Versioning Strategy + +In a nutshell, the versioning strategy is as follows: + +```bash +[Start] + | + V +1.0.0-draft[#] --> (Revisions) --> 1.0.0-draft[#] (last draft) + | + V +1.0.0-rc[#] --> (Revisions) --> 1.0.0-rc[#] (last release candidate) + | + V +[Approval] + | + V +1.0.0 (Approved/Ratified) + | + V +(Minor changes, Fixes, Compatible extensions) --> 1.1.0 + | + V +(Corrections, Editorial changes) --> 1.1.1 + | + V +(Incompatible changes, Major new features) --> 2.0.0 +``` + +link:https://docs.google.com/document/d/1ZO3clTdgbm-t6r8GMDQ7CypWl68_3ZeYuHl4e-cS280/edit[RISC-V International has a policy for versioning] +. The purpose of this policy is to ensure consistency and clarity in the versioning of RISC-V artifacts, which can be comprehended by both the RISC-V community and external parties. This policy adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). + +The first ratified version of any artifact is expected to be 1.0.0. The policy outlines specific versioning conventions for different stages of specification development: 1.0.0-draft1 for drafts, 1.0.0-rc1 for release candidates, and 1.0.0 for approved and ratified specifications. Furthermore, the use of build-date metadata is encouraged for non-release versions. + +The MAJOR.MINOR.PATCH paradigm is explained as: PATCH for corrections or editorial changes, MINOR for fixes and compatible extensions with limited new functionality, and MAJOR for incompatible changes or significant new features. The policy is effective immediately upon approval. + +Examples: + +* Specification Development - Suppose a new RISC-V specification is being developed. Its version might start as 1.0.0-draft1 for the first draft, then proceed to 1.0.0-rc1 when it reaches the release candidate stage (1.0.0-rc2, 1.0.0-rc3, etc...), and finally settle at 1.0.0 when it's approved and ratified. + +* Update Types - If the ratified specification undergoes a minor update, incorporating fixes or compatible extensions with limited new functionality, it would change to 1.1.0. If there are only corrections or editorial modifications, the version would move to 1.0.1. For incompatible changes or major new features, the version would leap to 2.0.0. + +* Metadata Tagging - Non-release versions of the specification can be tagged with the build date. For example, if a draft version is prepared on June 29, 2023, it could be tagged as 1.0.0-draft1+20230629. + +==== Setting Environment Variables + +These variables can be overridden by setting environment variables on your system. Here's how you can do it in Linux and MacOS: + +```bash +export VERSION=v1.2.3 +export REVMARK=Release +export PDF_RESULT=spec.pdf +``` + +=== Building the Documentation + +To start the build process, run `cd ./docs-spec-template && make build`. + +The Makefile script will check the availability of Docker on your system: + +* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. +* If Docker is not available, the documentation will be built directly on your system using the installed tools. + +The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. + +The build process utilizes several options, including theming and font settings, and generates a PDF document as output. + +=== Cleaning up + +To clean up the generated files, run `make clean`. This will remove the generated PDF file.