Merge pull request #1 from riscv/jscheid/initial-adoc

Initial adoc from the older gdoc source.

.github/workflows/build-pdf.yml

@@ -0,0 +1,56 @@
+# This workflow installs dependencies for PDF generation, generates the PDF,
+# and uploads the PDF as an artifact.
+
+name: Build Document PDF
+
+on:
+  push:
+    branches: [ $default-branch, "jscheid/**" ]
+  pull_request:
+    branches: [ $default-branch ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    env:
+      APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt
+      BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile
+      BUNDLE_BIN: ${{ github.workspace }}/bin
+      NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies
+      PDF_RESULT: autogenerated/Sstc.pdf
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install Ubuntu packages
+      run: |
+        sudo apt-get update
+        grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends
+    # Ruby for asciidoctor
+    - name: Setup Ruby and Gemfile content
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "2.6"
+        bundler-cache: true
+    # Node.js for wavedrom
+    - uses: actions/cache@v2
+      with:
+        path: ~/.npm
+        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+        restore-keys: |
+          ${{ runner.os }}-node-
+    - name: Setup Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '14'
+    - name: Install Node.js dependencies
+      run: npm install ${NPM_PACKAGE_FOLDER}
+    - name: Generate PDF
+      run: |
+        PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \
+        make ${PDF_RESULT}
+    - name: Archive PDF result
+      uses: actions/upload-artifact@v2
+      with:
+        name: pdf
+        path: ${{ env.PDF_RESULT }}
+        retention-days: 7

.gitignore

@@ -0,0 +1 @@
+autogenerated/

Makefile

@@ -0,0 +1,57 @@
+SPEC=Sstc
+VERSION=0.5.4
+STAGE=frozen
+
+COMMITDATE=$(shell git show -s --format=%ci | cut -d ' ' -f 1)
+GITVERSION=$(shell git describe --tags --always --dirty)
+
+GENDIR=autogenerated
+
+SPEC_PDF=$(GENDIR)/$(SPEC).pdf
+
+all: $(SPEC_PDF)
+
+REVISION_SRC=$(GENDIR)/revision.adoc
+
+HEADER_SRC=book_header.adoc
+
+COMMON_SRCS= \
+	bibliography.adoc \
+	colophon.adoc \
+	index.adoc \
+	$(HEADER_SRC) \
+	$(REVISION_SRC)
+
+SPEC_SRCS=content.adoc
+
+$(GENDIR):
+	-mkdir $@
+
+# Always perform this, but the rule is implemented so as to not touch the
+# output if it needn't change.
+.PHONY: $(REVISION_SRC)
+$(REVISION_SRC): Makefile $(GENDIR)
+	echo ":revdate: ${COMMITDATE}" > $@-tmp
+	echo ":revnumber: ${VERSION}-${GITVERSION}" >> $@-tmp
+	echo ":revremark: ${STAGE}" >> $@-tmp
+	diff $@ $@-tmp || mv $@-tmp $@
+
+# In order to remove the PHONY, this needs dependencies on all the input data,
+# adocs, images/, resources/, etc.
+.PHONY: $(SPEC_PDF)
+$(SPEC_PDF): $(COMMON_SRCS) $(SPEC_SRCS) $(GENDIR)
+	asciidoctor-pdf \
+		--attribute=mathematical-format=svg \
+		--attribute=pdf-fontsdir=resources/fonts \
+		--attribute=pdf-style=resources/themes/risc-v_spec-pdf.yml \
+		--failure-level=ERROR \
+		--out-file=$@ \
+		--require=asciidoctor-bibtex \
+		--require=asciidoctor-diagram \
+		--require=asciidoctor-mathematical \
+		--trace \
+		--verbose \
+		$(HEADER_SRC)
+
+clean:
+	$(RM) -r $(GENDIR)

bibliography.adoc

@@ -0,0 +1,2 @@
+[bibliography]
+== Bibliography

book_header.adoc

@@ -0,0 +1,51 @@
+[[riscv-doc-template]]
+= RISC-V "stimecmp / vstimecmp" Extension: Sstc
+:description: "stimecmp / vsstimecmp"
+:company: RISC-V.org
+include::autogenerated/revision.adoc[]
+:url-riscv: http://riscv.org
+:doctype: book
+//:doctype: report
+:preface-title: Preamble
+:colophon:
+:appendix-caption: Appendix
+:imagesdir: images
+:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center]
+//:page-background-image: image:draft.svg[opacity=20%]
+//:title-page-background-image: none
+:back-cover-image: image:backpage.png[opacity=25%]
+// Settings:
+:experimental:
+:reproducible:
+:imagesoutdir: images
+:bibtex-file: resources/riscv-spec.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::[]
+:table-caption: Table
+:figure-caption: Figure
+:xrefstyle: full
+:chapter-refsig: Chapter
+:section-refsig: Section
+:appendix-refsig: Appendix
+:data-uri:
+:hide-uri-scheme:
+:stem: latexmath
+:footnote:
+
+This document is released under a Creative Commons Attribution 4.0 International License.
+
+include::colophon.adoc[]
+include::content.adoc[]
+include::index.adoc[]
+include::bibliography.adoc[]
+

colophon.adoc

@@ -0,0 +1,9 @@
+[colophon]
+
+[NOTE]
+.Document Source Information
+****
+See link:https://github.com/riscv/riscv-time-compare[]
+for document source.  The document version includes the source control tag or
+commit hash used to produce this document.
+****

content.adoc

@@ -0,0 +1,187 @@
+[Sstc]
+== Introduction
+
+The current Privileged arch specification only defines a hardware mechanism for
+generating machine-mode timer interrupts (based on the mtime and mtimecmp
+registers). With the resultant requirement that timer services for
+S-mode/HS-mode (and for VS-mode) have to all be provided by M-mode - via SBI
+calls from S/HS-mode up to M-mode (or VS-mode calls to HS-mode and then to
+M-mode). M-mode software then multiplexes these multiple logical timers onto
+its one physical M-mode timer facility, and the M-mode timer interrupt handler
+passes timer interrupts back down to the appropriate lower privilege mode.
+
+This extension serves to provide supervisor mode with its own CSR-based timer
+interrupt facility that it can directly manage to provide its own timer service
+(in the form of having its own stimecmp register) - thus eliminating the large
+overheads for emulating S/HS-mode timers and timer interrupt generation up in
+M-mode. Further, this extension adds a similar facility to the Hypervisor
+extension for VS-mode.
+
+To make it easy to understand the deltas from the current Priv 1.11/1.12 specs,
+this is written as the actual exact changes to be made to existing paragraphs
+of Priv spec text (or additional paragraphs within the existing text).
+
+The extension name is "Sstc" ('Ss' for Privileged arch and Supervisor-level
+extensions, and 'tc' for timecmp). This extension adds the S-level stimecmp CSR
+and the VS-level vstimecmp CSR.
+
+== Machine and Supervisor Level Additions
+
+=== *Supervisor Timer Register (stimecmp)*
+
+This extension adds this new CSR.
+
+The stimecmp CSR is a 64-bit register and has 64-bit precision on all RV32 and
+RV64 systems. In RV32 only, accesses to the stimecmp CSR access the low 32
+bits, while accesses to the stimecmph CSR access the high 32 bits of stimecmp.
+
+The CSR numbers for stimecmp / stimecmph are 0x14D / 0x15D (within the
+Supervisor Trap Setup block of CSRs).
+
+A supervisor timer interrupt becomes pending - as reflected in the STIP bit in
+the mip and sip registers - whenever time contains a value greater than or
+equal to stimecmp, treating the values as unsigned integers. Writes to stimecmp
+are guaranteed to be reflected in STIP eventually, but not necessarily
+immediately. The interrupt remains posted until stimecmp becomes greater than
+time - typically as a result of writing stimecmp. The interrupt will be taken
+based on the standard interrupt enable and delegation rules.
+
+[NOTE]
+.Non-normative
+****
+A spurious timer interrupt might occur if an interrupt handler advances
+stimecmp then immediately returns, because STIP might not yet have fallen in
+the interim. All software should be written to assume this event is possible,
+but most software should assume this event is extremely unlikely. It is almost
+always more performant to incur an occasional spurious timer interrupt than to
+poll STIP until it falls.
+****
+
+[NOTE]
+.Non-normative
+****
+In systems in which a supervisor execution environment (SEE) provides timer
+facilities via an SBI function call, this SBI call will continue to support
+requests to schedule a timer interrupt. The SEE will simply make use of
+stimecmp, changing its value as appropriate. This ensures compatibility with
+existing S-mode software that uses this SEE facility, while new S-mode software
+takes advantage of stimecmp directly.)
+****
+
+=== Machine Interrupt Registers (mip and mie)
+
+This extension modifies the description of the STIP/STIE bits in these
+registers as follows:
+
+If supervisor mode is implemented, its mip.STIP and mie.STIE are the
+interrupt-pending and interrupt-enable bits for supervisor-level timer
+interrupts. If the stimecmp register is not implemented, STIP is writable in
+mip, and may be written by M-mode software to deliver timer interrupts to
+S-mode. If the stimecmp (supervisor-mode timer compare) register is
+implemented, STIP is read-only in mip and reflects the supervisor-level timer
+interrupt signal resulting from stimecmp. This timer interrupt signal is
+cleared by writing stimecmp with a value greater than the current time value.
+
+=== Supervisor Interrupt Registers (sip and sie)
+
+This extension modifies the description of the STIP/STIE bits in these
+registers as follows:
+
+Bits sip.STIP and sie.STIE are the interrupt-pending and interrupt-enable bits
+for supervisor level timer interrupts. If implemented, STIP is read-only in
+sip, and is either set and cleared by the execution environment (if stimecmp is
+not implemented), or reflects the timer interrupt signal resulting from
+stimecmp (if stimecmp is implemented). The sip.STIP bit, in response to timer
+interrupts generated by stimecmp, is set and cleared by writing stimecmp with a
+value that respectively is less than or equal to, or greater than, the current
+time value.
+
+=== Machine Counter-Enable Register (mcounteren)
+
+This extension adds to the description of the TM bit in this register as
+follows:
+
+In addition, when the TM bit in the mcounteren register is clear, attempts to
+access the stimecmp register while executing in S-mode will cause an illegal
+instruction exception. When this bit is set, access to the stimecmp register
+(if implemented) is permitted in S-mode.
+
+== Hypervisor Extension Additions
+
+=== *Virtual Supervisor Timer Register (vstimecmp)*
+
+This extension adds this new CSR.
+
+The vstimecmp CSR is a 64-bit register and has 64-bit precision on all RV32 and
+RV64 systems. In RV32 only, accesses to the vstimecmp CSR access the low 32
+bits, while accesses to the vstimecmph CSR access the high 32 bits of
+vstimecmp.
+
+The proposed CSR numbers for vstimecmp / vstimecmph are 0x24D / 0x25D (within
+the Virtual Supervisor Registers block of CSRs, and mirroring the CSR numbers
+for stimecmp/stimecmph).
+
+A virtual supervisor timer interrupt becomes pending - as reflected in the
+VSTIP bit in the hip register - whenever (time + htimedelta), truncated to 64
+bits, contains a value greater than or equal to vstimecmp, treating the values
+as unsigned integers. Writes to vstimecmp and htimedelta are guaranteed to be
+reflected in VSTIP eventually, but not necessarily immediately. The interrupt
+remains posted until vstimecmp becomes greater than (time + htimedelta) -
+typically as a result of writing vstimecmp. The interrupt will be taken based
+on the standard interrupt enable and delegation rules while V=1.
+
+[NOTE]
+.Non-normative
+****
+In systems in which a supervisor execution environment (SEE) implemented by an
+HS-mode hypervisor provides timer facilities via an SBI function call, this SBI
+call will continue to support requests to schedule a timer interrupt. The SEE
+will simply make use of vstimecmp, changing its value as appropriate. This
+ensures compatibility with existing guest VS-mode software that uses this SEE
+facility, while new VS-mode software takes advantage of vstimecmp directly.)
+****
+
+=== Hypervisor Interrupt Registers (hvip, hip, and hie)
+
+This extension modifies the description of the VSTIP/VSTIE bits in the hip/hie
+registers as follows:
+
+Bits hip.VSTIP and hie.VSTIE are the interrupt-pending and interrupt-enable
+bits for VS-level timer interrupts. VSTIP is read-only in hip, and is the
+logical-OR of hvip.VSTIP and the timer interrupt signal resulting from
+vstimecmp (if vstimecmp is implemented). The hip.VSTIP bit, in response to
+timer interrupts generated by vstimecmp, is set and cleared by writing
+vstimecmp with a value that respectively is less than or equal to, or greater
+than, the current (time + htimedelta) value. The hip.VSTIP bit remains defined
+while V=0 as well as V=1.
+
+=== Hypervisor Counter-Enable Register (hcounteren)
+
+This extension adds to the description of the TM bit in this register as
+follows:
+
+In addition, when the TM bit in the hcounteren register is clear, attempts to
+access the vstimecmp register (via stimecmp) while executing in VS-mode will
+cause a virtual instruction exception if the same bit in mcounteren is 1. When
+this bit is set, access to the vstimecmp register (if implemented) is permitted
+in VS-mode.
+
+== Environment Config (menvcfg/henvcfg) Support
+
+Enable/disable bits for this extension are provided in the new menvcfg /
+henvcfg CSRs.
+
+Bit 63 of menvcfg (or bit 31 of menvcfgh) - named STCE (STimecmp Enable) -
+enables stimecmp for S-mode when set to one, and the same bit of henvcfg
+enables vstimecmp for VS-mode. These STCE bits are WARL and are hard-wired to 0
+when this extension is not implemented.
+
+When STCE in menvcfg is zero, an attempt to access stimecmp or vstimecmp in a
+mode other than M-mode raises an illegal instruction exception, STCE in henvcfg
+is read-only zero, and STIP in mip and sip reverts to its defined behavior as
+if this extension is not implemented.
+
+When STCE in menvcfg is one but STCE in henvcfg is zero, an attempt to access
+stimecmp (really vstimecmp) when V = 1 raises a virtual instruction exception,
+and VSTIP in hip reverts to its defined behavior as if this extension is not
+implemented.

dependencies/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+gem 'asciidoctor'
+gem 'asciidoctor-bibtex'
+gem 'asciidoctor-diagram'
+gem 'asciidoctor-mathematical'
+gem 'asciidoctor-pdf'
+gem 'citeproc-ruby'
+gem 'coderay'
+gem 'csl-styles'
+gem 'json'
+gem 'pygments.rb'
+gem 'rghost'
+gem 'rouge'
+gem 'ruby_dev'

dependencies/README.md

@@ -0,0 +1,3 @@
+Dependencies for the build environment for various package managers.  Used in
+`.github/workflows/`.
+