diff options
-rw-r--r-- | build/Makefile | 114 | ||||
-rw-r--r-- | src/cmo.adoc | 24 | ||||
-rw-r--r-- | src/hypervisor.adoc | 6 | ||||
-rw-r--r-- | src/indirect-csr.adoc | 4 | ||||
-rw-r--r-- | src/priv-preface.adoc | 89 | ||||
-rw-r--r-- | src/riscv-privileged.adoc | 2 | ||||
-rw-r--r-- | src/smcdeleg.adoc | 2 | ||||
-rw-r--r-- | src/smcntrpmf.adoc | 2 | ||||
-rw-r--r-- | src/smepmp.adoc | 2 | ||||
-rw-r--r-- | src/smstateen.adoc | 2 | ||||
-rw-r--r-- | src/sscofpmf.adoc | 2 | ||||
-rw-r--r-- | src/sstc.adoc | 2 |
12 files changed, 119 insertions, 132 deletions
diff --git a/build/Makefile b/build/Makefile index 0eb6a38..db2c1c1 100644 --- a/build/Makefile +++ b/build/Makefile @@ -12,23 +12,43 @@ # This Makefile is designed to automate the process of building and packaging # the documentation for RISC-V ISA Manuals. It supports multiple build targets # for generating documentation in various formats (PDF, HTML). +# +# Building with a preinstalled docker container is recommended. +# Install by running: +# +# docker pull riscvintl/riscv-docs-base-container-image:latest +# # Build Targets -TARGETS_PDF := priv-pdf unpriv-pdf -TARGETS_HTML := priv-html unpriv-html -TARGETS_EPUB := priv-epub unpriv-epub +TARGETS_PDF := riscv-privileged.pdf riscv-unprivileged.pdf +TARGETS_HTML := riscv-privileged.html riscv-unprivileged.html +TARGETS_EPUB := riscv-privileged.epub riscv-unprivileged.epub TARGETS := $(TARGETS_PDF) $(TARGETS_HTML) $(TARGETS_EPUB) +SHORT_TARGETS := priv-pdf unpriv-pdf priv-html unpriv-html priv-epub unpriv-epub + # Declare phony targets -.PHONY: all $(TARGETS) clean +.PHONY: all docker clean $(SHORT_TARGETS) # Default target builds all all: $(TARGETS) -# Build with preinstalled docker container; first install it with: -# docker pull riscvintl/riscv-docs-base-container-image:latest +define run_with_docker + cd .. && docker run -it -v `pwd`:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'export LANG=C.utf8; cd ./build; $(1)' +endef + +# Run natively if command exists, otherwise run with docker +define maybe_run_with_docker + @if command -v $(1) &> /dev/null; \ + then \ + $(1) $(2); \ + else \ + $(call run_with_docker, $(1) $(2)); \ + fi +endef + docker: - cd .. && docker run -it -v `pwd`:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'export LANG=C.utf8; cd ./build; make -$(MAKEFLAGS) $(TARGETS)' + $(call run_with_docker, make -$(MAKEFLAGS) all) # Asciidoctor options ASCIIDOCTOR_OPTS := -a compress \ @@ -42,75 +62,57 @@ ASCIIDOCTOR_OPTS := -a compress \ # Source directory SRCDIR := ../src -# Temporary files to clean up for LaTeX build -JUNK := *.pdf *.aux *.log *.bbl *.blg *.toc *.out *.fdb_latexmk *.fls *.synctex.gz - # Privileged ISA build -priv-pdf: priv-isa-asciidoc.pdf +priv-pdf: riscv-privileged.pdf -priv-isa-asciidoc.pdf: $(SRCDIR)/riscv-privileged.adoc $(SRCDIR)/*.adoc +riscv-privileged.pdf: $(SRCDIR)/riscv-privileged.adoc $(SRCDIR)/*.adoc @echo "Building Privileged ISA" - rm -f $@.tmp - asciidoctor-pdf $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $< - mv $@.tmp $@ + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor-pdf, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ # Unprivileged ISA build -unpriv-pdf: unpriv-isa-asciidoc.pdf +unpriv-pdf: riscv-unprivileged.pdf -unpriv-isa-asciidoc.pdf: $(SRCDIR)/riscv-unprivileged.adoc $(SRCDIR)/*.adoc +riscv-unprivileged.pdf: $(SRCDIR)/riscv-unprivileged.adoc $(SRCDIR)/*.adoc @echo "Building Unprivileged ISA" - rm -f $@.tmp - asciidoctor-pdf $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $< - mv $@.tmp $@ + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor-pdf, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ # Privileged ISA HTML build -priv-html: priv-isa-asciidoc.html +priv-html: riscv-privileged.html -priv-isa-asciidoc.html: $(SRCDIR)/riscv-privileged.adoc +riscv-privileged.html: $(SRCDIR)/riscv-privileged.adoc @echo "Building Privileged ISA HTML" - asciidoctor $(ASCIIDOCTOR_OPTS) --out-file=$@ $< + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ # Unprivileged ISA HTML build -unpriv-html: unpriv-isa-asciidoc.html +unpriv-html: riscv-unprivileged.html -unpriv-isa-asciidoc.html: $(SRCDIR)/riscv-unprivileged.adoc +riscv-unprivileged.html: $(SRCDIR)/riscv-unprivileged.adoc @echo "Building Unprivileged ISA HTML" - asciidoctor $(ASCIIDOCTOR_OPTS) --out-file=$@ $< + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ -priv-epub: priv-isa-asciidoc.epub +priv-epub: riscv-privileged.epub -priv-isa-asciidoc.epub: $(SRCDIR)/riscv-privileged.adoc +riscv-privileged.epub: $(SRCDIR)/riscv-privileged.adoc @echo "Building Privileged ISA EPUB" - asciidoctor-epub3 $(ASCIIDOCTOR_OPTS) --out-file=$@ $< + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor-epub3, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ -unpriv-epub: unpriv-isa-asciidoc.epub +unpriv-epub: riscv-unprivileged.epub -unpriv-isa-asciidoc.epub: $(SRCDIR)/riscv-unprivileged.adoc +riscv-unprivileged.epub: $(SRCDIR)/riscv-unprivileged.adoc @echo "Building Unprivileged ISA EPUB" - asciidoctor-epub3 $(ASCIIDOCTOR_OPTS) --out-file=$@ $< + @rm -f $@.tmp + $(call maybe_run_with_docker, asciidoctor-epub3, $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<) + @mv $@.tmp $@ clean: - @if [ -f priv-isa-asciidoc.pdf ]; then \ - echo "Removing priv-isa-asciidoc.pdf"; \ - rm -f priv-isa-asciidoc.pdf; \ - fi - @if [ -f unpriv-isa-asciidoc.pdf ]; then \ - echo "Removing unpriv-isa-asciidoc.pdf"; \ - rm -f unpriv-isa-asciidoc.pdf; \ - fi - @if [ -f priv-isa-asciidoc.html ]; then \ - echo "Removing priv-isa-asciidoc.html"; \ - rm -f priv-isa-asciidoc.html; \ - fi - @if [ -f unpriv-isa-asciidoc.html ]; then \ - echo "Removing unpriv-isa-asciidoc.html"; \ - rm -f unpriv-isa-asciidoc.html; \ - fi - @if [ -f priv-isa-asciidoc.epub ]; then \ - echo "Removing priv-isa-asciidoc.epub"; \ - rm -f priv-isa-asciidoc.epub; \ - fi - @if [ -f unpriv-isa-asciidoc.epub ]; then \ - echo "Removing unpriv-isa-asciidoc.epub"; \ - rm -f unpriv-isa-asciidoc.epub; \ - fi + rm -f $(TARGETS) $(addsuffix .tmp,$(TARGETS)) diff --git a/src/cmo.adoc b/src/cmo.adoc index 5f7087e..42941bb 100644 --- a/src/cmo.adoc +++ b/src/cmo.adoc @@ -337,6 +337,9 @@ _This specification assumes that the above constraints will typically be met for main memory regions and may be met for certain I/O regions._ ==== +Additionally, for the purposes of PMP and PMA checks, the access size of a CMO +instruction equals the size of the cache block accessed by the instruction. + The Zicboz extension introduces an additional supported access type PMA for cache-block zero instructions. Main memory regions are required to support accesses by cache-block zero instructions; however, I/O regions may specify @@ -381,7 +384,9 @@ exceptions and shall not access any caches or memory. During address translation, the instruction does _not_ check the accessed and dirty bits and neither raises an exception nor sets the bits. -When a page fault, guest-page fault, or access fault exception is taken, the relevant *tval CSR is written with the faulting effective address (i.e. the same faulting address value as for other causes of these exceptions). +When a page fault, guest-page fault, or access fault exception is taken, the +relevant *tval CSR is written with the faulting effective address (i.e. the same +faulting address value as for other causes of these exceptions). [NOTE] ==== @@ -888,6 +893,14 @@ be omitted; otherwise, any expression that computes the offset shall evaluate to zero. The instruction operates on the set of coherent caches accessed by the agent executing the instruction. +[NOTE] +==== +_When executing a *cbo.clean* instruction, an implementation may instead perform +a flush operation, since the result of that operation is indistinguishable from +the sequence of performing a clean operation just before deallocating all cached +copies in the set of coherent caches._ +==== + Operation:: [source,sail] -- @@ -960,6 +973,14 @@ accessed by the agent executing the instruction. Depending on CSR programming, the instruction may perform a flush operation instead of an invalidate operation. +[NOTE] +==== +_When executing a *cbo.inval* instruction, an implementation may instead perform +a flush operation, since the result of that operation is indistinguishable from +the sequence of performing a write transfer to memory just before performing an +invalidate operation._ +==== + Operation:: [source,sail] -- @@ -1129,4 +1150,3 @@ Operation:: -- TODO -- - diff --git a/src/hypervisor.adoc b/src/hypervisor.adoc index 56761a7..1e8f0b8 100644 --- a/src/hypervisor.adoc +++ b/src/hypervisor.adoc @@ -1061,14 +1061,14 @@ include::images/bytefield/vsipreg-standard.edn[] .Standard portion (bits 15:0) of `vsie`. include::images/bytefield/vsiereg-standard.edn[] +Extension Shlcofideleg supports delegating LCOFI interrupts to VS-mode. +If the Shlcofideleg extension is implemented, `hideleg` bit 13 is +writable; otherwise, it is read-only zero. When bit 13 of `hideleg` is zero, `vsip`.LCOFIP and `vsie`.LCOFIE are read-only zeros. Else, `vsip`.LCOFIP and `vsie`.LCOFIE are aliases of `sip`.LCOFIP and `sie`.LCOFIE. -NOTE: The `vsip`.LCOFIP and `vsie`.LCOFIE bits were added in Version 1.13 of -the Privileged Architecture. - When bit 10 of `hideleg` is zero, `vsip`.SEIP and `vsie`.SEIE are read-only zeros. Else, `vsip`.SEIP and `vsie`.SEIE are aliases of `hip`.VSEIP and `hie`.VSEIE. diff --git a/src/indirect-csr.adoc b/src/indirect-csr.adoc index cb63a23..52a3340 100644 --- a/src/indirect-csr.adoc +++ b/src/indirect-csr.adoc @@ -1,5 +1,5 @@ [[indirect-csr]] -== "Smcsrind/Sscsrind" Indirect CSR Access, Version 1.0.0 +== "Smcsrind/Sscsrind" Indirect CSR Access, Version 1.0 [[intro]] === Introduction @@ -331,4 +331,4 @@ incorporates the bit defined above for `hstateen0` but not that for [NOTE] ==== CSR address space is reserved for a possible future "Sucsrind" extension that extends indirect CSR access to user mode. -====
\ No newline at end of file +==== diff --git a/src/priv-preface.adoc b/src/priv-preface.adoc index ba36ebb..936409c 100644 --- a/src/priv-preface.adoc +++ b/src/priv-preface.adoc @@ -1,10 +1,10 @@ [colophon] = Preface -[.big]*_Preface to Version 20240326_* +[.big]*_Preface to Version 20240528_* This document describes the RISC-V privileged architecture. This -release, version 20240213, contains the following versions of the RISC-V ISA +release, version 20240528, contains the following versions of the RISC-V ISA modules: [%autowidth,float="center",align="center",cols="^,<,^",options="header",] @@ -25,24 +25,26 @@ _Supervisor ISA_ + *Svadu Extension* + *Sstc* + *Sscofpmf* + -*Hypervisor ISA* +*Hypervisor ISA* + +_Shlcofideleg_ |_1.13_ + -*1.0.0* + -*1.0.0* + -*1.0.0* + -*1.0.0* + -*1.0.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + _1.13_ + -*1.0.0* + -_0.1_ + *1.0* + *1.0* + *1.0* + *1.0* + *1.0* + *1.0* + -*1.0* +*1.0* + +*1.0* + +_0.1_ |_Draft_ + *Ratified* + @@ -50,7 +52,6 @@ _0.1_ + *Ratified* + *Ratified* + *Ratified* + -_Draft_ + *Ratified* + _Draft_ + *Ratified* + @@ -59,63 +60,21 @@ _Draft_ + *Ratified* + *Ratified* + *Ratified* + -*Ratified* -|=== - -The changes in this version of the document include: - -* The inclusion of all ratified extensions through March 2024. -* The concept of vacant memory regions has been superseded by inaccessible memory or I/O regions. - -[.big]*_Preface to Version 20240213_* - -This document describes the RISC-V privileged architecture. This -release, version 20240213, contains the following versions of the RISC-V ISA -modules: - -[%autowidth,float="center",align="center",cols="^,<,^",options="header",] -|=== -|Module |Version |Status -|_Machine ISA_ + -_Supervisor ISA_ + -_Smrnmi Extension_ + -*Svade Extension* + -*Svnapot Extension* + -*Svpbmt Extension* + -*Svinval Extension* + -*Svadu Extension* + -*Hypervisor ISA* -|_1.13_ + -_1.13_ + -_0.1_ + -*1.0* + -*1.0* + -*1.0* + -*1.0* + -*1.0* + -*1.0* -|_Draft_ + -_Draft_ + -_Draft_ + -*Ratified* + -*Ratified* + -*Ratified* + *Ratified* + *Ratified* + -*Ratified* +_Draft_ |=== -The following changes have been made since version 1.12, which, while -not strictly backwards compatible, are not anticipated to cause software -portability problems in practice: +The following changes have been made since version 1.12 of the Machine and +Supervisor ISAs, which, while not strictly backwards compatible, are not +anticipated to cause software portability problems in practice: * Redefined `misa`.MXL to be read-only, making MXLEN a constant. * Added the constraint that SXLEN≥UXLEN. -Additionally, the following compatible changes have been made to the Machine ISA since -version 1.12: +Additionally, the following compatible changes have been +made to the Machine and Supervisor ISAs since version 1.12: -* Transliterated the document from LaTeX into AsciiDoc. * Defined the `misa`.V field to reflect that the V extension has been implemented. * Defined the RV32-only `medelegh` and `hedelegh` CSRs. @@ -125,7 +84,13 @@ implemented. * Defined hardware error and software check exception codes. * Specified synchronization requirements when changing the PBMTE fields in `menvcfg` and `henvcfg`. -* Incorporated Svade and Svadu extension specifications. +* Exposed count-overflow interrups to VS-mode via the Shlcofideleg extension. + +Finally, the following clarifications and document improvments have been made +since the last document release: + +* Transliterated the document from LaTeX into AsciiDoc. +* Included all ratified extensions through March 2024. * Clarified that "platform- or custom-use" interrupts are actually "platform-use interrupts", where the platform can choose to make some custom. * Clarified semantics of explicit accesses to CSRs wider than XLEN bits. @@ -138,7 +103,7 @@ in `menvcfg` and `henvcfg`. be set to a nonzero value but sometimes not. * Clarified exception behavior of unimplemented or inaccessible CSRs. * Clarified that Svpbmt allows implementations to override additional PMAs. -* Exposed count-overflow interrups to VS-mode. +* Replaced the concept of vacant memory regions with inaccessible memory or I/O regions. [.big]*_Preface to Version 20211203_* diff --git a/src/riscv-privileged.adoc b/src/riscv-privileged.adoc index 484f907..caff79a 100644 --- a/src/riscv-privileged.adoc +++ b/src/riscv-privileged.adoc @@ -2,7 +2,7 @@ = The RISC-V Instruction Set Manual: Volume II: Privileged Architecture :description: Volume II - Privileged Architecture :company: RISC-V.org -:revnumber: 20240411 +:revnumber: 20240528 //:revremark: Pre-release version //development: assume everything can change //stable: assume everything could change diff --git a/src/smcdeleg.adoc b/src/smcdeleg.adoc index 0530f56..fd0be2a 100644 --- a/src/smcdeleg.adoc +++ b/src/smcdeleg.adoc @@ -1,5 +1,5 @@ [[smcdeleg]] -== "Smcdeleg" Counter Delegation Extension, Version 1.0.0 +== "Smcdeleg" Counter Delegation Extension, Version 1.0 In modern “Rich OS” environments, hardware performance monitoring resources are managed by the kernel, kernel driver, and/or hypervisor. diff --git a/src/smcntrpmf.adoc b/src/smcntrpmf.adoc index 4130002..94e6314 100644 --- a/src/smcntrpmf.adoc +++ b/src/smcntrpmf.adoc @@ -1,5 +1,5 @@ [[smcntrpmf]] -== "Smcntrpmf" Cycle and Instret Privilege Mode Filtering, Version 1.0.0 +== "Smcntrpmf" Cycle and Instret Privilege Mode Filtering, Version 1.0 [[intro]] === Introduction diff --git a/src/smepmp.adoc b/src/smepmp.adoc index a0b89e6..0f602c5 100644 --- a/src/smepmp.adoc +++ b/src/smepmp.adoc @@ -1,5 +1,5 @@ [[smepmp]] -== "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode, Version 1.0.0 +== "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode, Version 1.0 === Introduction Being able to access the memory of a process running at a high privileged execution mode, such as the Supervisor or Machine mode, from a lower privileged mode such as the User mode, introduces an obvious attack vector since it allows for an attacker to perform privilege escalation, and tamper with the code and/or data of that process. A less obvious attack vector exists when the reverse happens, in which case an attacker instead of tampering with code and/or data that belong to a high-privileged process, can tamper with the memory of an unprivileged / less-privileged process and trick the high-privileged process to use or execute it. diff --git a/src/smstateen.adoc b/src/smstateen.adoc index e037720..299b93a 100644 --- a/src/smstateen.adoc +++ b/src/smstateen.adoc @@ -1,5 +1,5 @@ [[smstateen]] -== "Smstateen/Ssstateen" Extensions, Version 1.0.0 +== "Smstateen/Ssstateen" Extensions, Version 1.0 The implementation of optional RISC-V extensions has the potential to open covert channels between separate user threads, or between separate guest OSes diff --git a/src/sscofpmf.adoc b/src/sscofpmf.adoc index 58f1bde..7e67a25 100644 --- a/src/sscofpmf.adoc +++ b/src/sscofpmf.adoc @@ -1,5 +1,5 @@ [[Sscofpmf]] -== "Sscofpmf" Extension for Count Overflow and Mode-Based Filtering, Version 1.0.0 +== "Sscofpmf" Extension for Count Overflow and Mode-Based Filtering, Version 1.0 The current Privileged specification defines mhpmevent CSRs to select and control event counting by the associated hpmcounter CSRs, but provides no diff --git a/src/sstc.adoc b/src/sstc.adoc index 3b4a9b8..8198349 100644 --- a/src/sstc.adoc +++ b/src/sstc.adoc @@ -1,5 +1,5 @@ [[Sstc]] -== "Sstc" Extension for Supervisor-mode Timer Interrupts, Version 1.0.0 +== "Sstc" Extension for Supervisor-mode Timer Interrupts, Version 1.0 The current Privileged arch specification only defines a hardware mechanism for generating machine-mode timer interrupts (based on the mtime and mtimecmp |