Move draft-2 specification into the official repository.

Makefile

@@ -12,14 +12,15 @@
 # This Makefile is designed to automate the process of building and packaging 
 # the Doc Template for RISC-V Extensions.
 
+SPEC=riscv-ssdtso
 DATE ?= $(shell date +%Y-%m-%d)
-VERSION ?= v0.0.0
+VERSION ?= $(shell git describe --tag --always --dirty)
 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
+PDF_RESULT := $(SPEC)-$(VERSION).pdf
 
 ASCIIDOCTOR_PDF := asciidoctor-pdf
 OPTIONS := --trace \

changes.adoc

@@ -0,0 +1,7 @@
+== Revision history
+
+Changes from v1.0-draft1 to v1.0-draft2:
+
+* Changed controlling CSR to `menvcfg`, `henvcfg`, and `senvcfg`.
+* Added clarifying language to how the `DTSO`-bit in lower priority level envcfg CSRs is partially overriden.
+* Improved language and fixed typos.

header.adoc

@@ -1,9 +1,9 @@
-= RISC-V Example Specification Document (Zexmpl)
-Authors: Author 1, Author 2
-:docgroup: RISC-V Task Group
-:description: RISC-V Example Specification Document (Zexmpl)
+= RISC-V Dynamic Switching of TSO-mode (Ssdtso) extension
+Authors: Dr. Philipp Tomsich (VRULL), Dr. Zhao Siqi (T-Head)
+:docgroup: RISC-V Fast Track
+:description: RISC-V Dynamic Switching of TSO-mode (Ssdtso) extension
 :company: RISC-V.org
-:revdate: 1/2023
+:revdate: 10/2023
 :revnumber: 1.0
 :revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details.
 :revinfo:
@@ -58,9 +58,11 @@ Copyright 2023 by RISC-V International.
 [preface]
 include::contributors.adoc[]
 
+include::changes.adoc[]
 include::intro.adoc[]
-include::chapter2.adoc[]
+include::ssdtso.adoc[]
+// include::chapter2.adoc[]
 
 // The index must precede the bibliography
-include::index.adoc[]
-include::bibliography.adoc[]
+// include::index.adoc[]
+// include::bibliography.adoc[]

intro.adoc

@@ -1,15 +1,37 @@
 [[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.
+The Sstdso extension standardises a mechanism that allows privileged system software to dynamically switch individual harts between RVWMO and RVTSO semantics for software running at lower privilege levels.
 
-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.
+This mechanism is intended for systems that:
 
-[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.
-====
+* want to provide RVTSO semantics for individual user-space processes, for a TSO-only operating system, or for a virtualized guest operating systems,
+* can dynamically switch the S/HS, U, VS, and VU execution on harts between RVWMO and RVTSO semantics,
+* natively prefer (e.g., for performance reasons) to operate with RVWMO semantics.
 
-=== Sub Section of Introduction
+In a nutshell, the Sstdso extension introduces a dynamic-RVTSO mode and allows privileged software to select the behaviour of load and store operations executing at a lower privilege level: when switched to dynamic RVTSO, all load, store, and AMO operations behave as in RVTSO.
+
+=== Interoperability between RVTSO and RVWMO
+
+RVTSO (whether statically selected or dynamically enabled) makes the following adjustments to RVWMO:
+
+* All load operations behave as if they have an acquire-RCpc annotation.
+* All store operations behave as if they have a release-RCpc annotation.
+* All AMOs operations behave as if they have both acquire-RCsc and release-RCsc annotations.
+
+This renders all rules. except those for explicit synchronization, for preserved program order (as defined in "17.1.3. Preserved Program Order" of "The RISC-V Instruction Set Manual: Volume I") redundant.
+
+For the interoperability between code (from different processes) concurrently executing under RVTSO and RVWMO rules (on separate harts), we can therefore assume correct interoperability without any special precautions if the processes use explicit synchronization primitives (and RCpc annotations for the processes executing under RVWMO semantics) as required for their respective memory consistency models.
+
+Ssdtso assumes that the privileged software controlling the dynamic-RVTSO behaviour is developed for RVWMO and will use explicit acquire-RCpc/release-RCpc annotations as required.
+
+=== Suitability for the Fast-Track Extension Process
+
+This proposed extension meets the Fast Track criteria:
+
+* it is self-contained with a programming-model consisting of bit-assignments in CSRs,
+* it provides a mechanism that will be used by privileged-level software only (i.e., has limited impact),
+* it does not modify or extend the memory model,
+* it composes with the existing RISC-V instruction set, and
+* it is not expected to be contentious.
 
-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.

ssdtso.adoc

@@ -0,0 +1,114 @@
+[[ssdtso]]
+== Dynamic switching of RVTSO
+
+The Ssdtso extension adds a 'dynamic-RVTSO' mode of operation.
+It is supported only on implementations that default to RVWMO semantics.
+
+Software executing at a higher privilege level (refer to Chapter 9.1 "Privilege Modes" in the RISC-V Provileged Architecture for the applicable definition in the presence of the H extension) can enable dynamic-RVTSO for all lower privilege levels on a per-hart granularity.
+Ssdtso does not control the memory ordering of M-mode: M-mode software always executes in RVWMO mode when the Ssdtso extension is implemented.
+
+[NOTE]
+====
+Ssdtso is intended to provide a compatibility-mode to execute binaries that require RVTSO on processors that prefer (e.g., for performance reasons) to be operated in RVWMO mode.
+====
+
+The intended use-cases for Ssdtso are
+
+. the execution of individual binaries compiled for RVTSO in user-mode or virtualized user-mode on a processor otherwise operating in RVWMO;
+. the execution of operating system images compiled for RVTSO mode in supervisor- and user-mode on a processor otherwise operating in RVWMO; and
+. the execution of guest operating system images compiled for RVTSO mode in virtualized supoervisor- and virtualized user-mode on a processors otherwise operating in RVWMO.
+
+=== Dependencies and Incompatibilities
+
+The Ssdto extension conflicts with Ztso.
+
+[NOTE]
+====
+Ztso provides RVTSO semantics across all privilege levels and harts of an implementation.
+In contrast to this, Ssdtso assumes that RVWMO is the default (at boot) mode of operation, that individual harts can be switched to RVTSO, and that the M-mode execution environment can not switched to RVTSO.
+====
+
+[NOTE]
+====
+It is strongly recommended (but not required) to implement the A extension for synchronization between software executing in RVWMO mode and RVTSO mode (such as S-mode software executing in RVWMO mode and user-space processes executing under dynamic-RVTSO).
+
+To allow the free composition of extensions for unforeseen use-cases, no formal dependency is introduced and any such mandate is delegated to ISA Profiles or Platforms definition.
+====
+
+=== State controlling whether dynamic TSO is enabled
+
+The dynamic-RVTSO behaviour is controlled by bit 8 (`DTSO`) of `menvcfg, senvcfg, henvcfg` for all lower privilege levels.
+Implementations providing Ssdtso are required to default to RVWMO semantics: the bits controlling dynamic-RVTSO behaviour are initialized to 0 on reset.
+
+If the DTSO control bit in the respective envcfg is set, all lower-privilege modes will operate in dynamic-RVTSO mode:
+[cols="^3,^2,^1,^1,^1,^1,^1",stripes=even,options="header"]
+|===
+1+|DTSO-bit |Virtualization state 5+|Controls dynamic-RVTSO in modes
+|||M|S/HS|U|VS|VU
+|menvcfg|n/a|0|1|1|1|1
+|henvcfg|n/a|0|0|0|1|1
+|senvcfg|V=0|0|0|1|0|0
+|senvcfg|V=1|0|0|0|0|1
+|===
+
+Attempt to reset the DTSO control bit at a lower priority level are ignored, if a higher-privilege mode has enabled dynamic-TSO according as follows:
+
+* menvcfg.DTSO overrides henvcfg.DTSO and senvcfg.DTSO
+* henvcfg.DTSO overrides senvcfg.DTSO for V=1
+
+=== Interpretation of memory-operations in dynamic-RVTSO
+
+While executing instructions in dynamic-RVTSO mode, all unannotated memory instructions are interpreted as if they had an acquire/release annotation.
+Entering and leaving dynamic-RVTSO mode affects memory instructions at the lower privilege levels that are encountered in program-order after the write to the CSR controlling the dynamic-RVTSO behaviour.
+
+Different harts in a system may operate in different modes.
+
+== Software considerations (informative)
+
+=== Switching to dynamic-RVTSO mode
+
+Depending on the capabilities of the software runtime environment (e.g., whether an operating system is present, and whether dynamically linked executables are supported), dynamic-RVTSO mode can be entered on processes initialisation or (programatically) during process runtime:
+
+* on process-initialisation from the ELF loader (e.g., for statically linked executables that have the *TSO* field in *e_flags* in the ELF file header set), or
+* at runtime using a system-call (e.g., if a runtime-linker resolves a DSO that has the *TSO* field in *e_flags* in the ELF file header set).
+
+Operating systems may follow various implementation strategies to enable dynamic-RVTSO in the presence of processes that require RVTSO semantics:
+
+. on-demand switching of individual harts for the duration of individual process that require RVTSO semantics for the duration of the execution on those harts
+. enabling dynamic-RVTSO across all harts as long as RVTSO processes are present in the system
+. enabling dynamic-RVTSO across all harts after encountering the first process requiring RVTSO
+
+[NOTE]
+====
+While the Ssdtso specification was written to support on-demand switching of individual harts into dynamic-RVTSO mode, it does not prescribe a specific strategy for how the operating system handles the presence of processes requiring RVTSO semantics.
+
+However, the expectation of the specification architects is that an operating system would attempt to reduce the overall time that cores would spend in dynamic-RVTSO mode.
+====
+
+=== Impact on thread/task state
+
+For operating systems that use on-demand switching of individual harts, the thread/task structures will require an additional field to track the requirement to execute in dynamic-RVTSO mode.
+
+=== Runtime linker support
+
+Support for shared objects will require runtime linker support which (roughly) follows the following process:
+
+* The capability to support Ssdtso is detected via an OS specific discovery method (e.g., `riscv_hwprobe` with `RISCV_HWPROVE_EXT_SSDTSO` key on Linux).
+* The ELF flags on each resolved shared object are evaluated to determine if RVTSO is required.  In case that RVTSO is required, but neither Ztso nor Ssdtso are available, the runtime linker is expected to invoke appropriate error handling and reporting.
+* If shared object is loaded into the process that requires RVTSO and Ssdtso in implemented, the runtime linker signals the OS to enter dynamic-TSO mode via an OS specific interface (e.g., on Linux: using a `prctl(...)` call).
+
+[NOTE]
+====
+It is recommended to only signal the need to enter dynamic-RVTSO mode once per process to reduce the number of systemcalls in consideration of performance.
+Given that entering dynamic-RVTSO is idempotent, no requirement exists to signal only.
+====
+
+=== Compatibility with RVWMO binaries and libraries
+
+RVWMO binaries and libraries can safely execute, without modification, while running under RVTSO semantics.
+Consequently, no special consideration or guidance is required for these.
+
+=== Discovery
+
+Discovery of Ssdtso is provided exclusively through Unified Discovery.
+