Merge pull request #22 from riscv/jhauser-2022-stable

Stable version, with preface.

doc/src/AdvPLIC.tex

@@ -5,9 +5,8 @@ \chapter{Advanced Platform-Level Interrupt Controller (APLIC)}
 \chaptermark{APLIC}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/CSRs.tex

@@ -5,9 +5,8 @@ \chapter{Control and Status Registers (CSRs) Added to Harts}
 \chaptermark{CSRs Added to Harts}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/DuoPLIC.tex

@@ -5,8 +5,10 @@ \chapter{Duo-PLIC}
 
 \textbf{%
 Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is only a draft, and might change significantly before 
+being accepted as standard by the {\RISCV} International Association.
+It remains possible that the Duo-PLIC specification
+will never become a ratified standard.%
 }
 \bigskip
 

doc/src/IMSIC.tex

@@ -5,9 +5,8 @@ \chapter{Incoming MSI Controller (IMSIC)}
 \chaptermark{IMSIC}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/IOMMU.tex

@@ -5,8 +5,8 @@ \chapter{IOMMU Support for MSIs to Virtual Machines}
 
 \textbf{%
 Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is only a draft, and might change significantly before
+being ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/IPIs.tex

@@ -4,9 +4,8 @@ \chapter{Interprocessor Interrupts (IPIs)}
 \label{ch:IPIs}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/MSLevel.tex

@@ -4,9 +4,8 @@ \chapter{Interrupts for Machine and Supervisor Levels}
 \label{ch:MSLevel}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/VSLevel.tex

@@ -4,9 +4,8 @@ \chapter{Interrupts for Virtual Machines (VS Level)}
 \label{ch:VSLevel}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 

doc/src/intro.tex

@@ -4,9 +4,8 @@ \chapter{Introduction}
 \label{ch:intro}
 
 \textbf{%
-Warning!
-This draft specification is likely to change before being accepted as
-standard by the {\RISCV} International Association.%
+This chapter is considered stable but could still change before being
+ratified as standard by the {\RISCV} International Association.%
 }
 \bigskip
 
@@ -489,3 +488,44 @@ \section{Selection of harts to receive an interrupt}
 multiple harts.
 \end{commentary}
 
+%-----------------------------------------------------------------------
+\section{ISA extensions Smaia and Ssaia}
+
+The Advanced Interrupt Architecture (AIA) defines two names for
+extensions to the {\RISCV} instruction set architecture (ISA),
+one for machine-level execution environments,
+and another for supervisor-level environments.
+For a machine-level environment, extension \textbf{Smaia} encompasses
+all added CSRs and all modifications to interrupt response behavior
+that the AIA specifies for a hart, over all privilege levels.
+For a supervisor-level environment, extension \textbf{Ssaia} is
+essentially the same as Smaia except excluding the machine-level
+CSRs and behavior not directly visible to supervisor level.
+
+Extensions Smaia and Ssaia cover only
+those AIA features that impact the ISA at a hart.
+Although the following are described or discussed
+in this document as part of the AIA, they are not implied by
+Smaia or Ssaia because the components are categorized as non-ISA:
+APLICs, Duo-PLICs, IOMMUs, and any mechanisms for initiating
+interprocessor interrupts apart from writing to IMSICs.
+
+As revealed in subsequent chapters, the exact set
+of CSRs and behavior added by the AIA, and hence
+implied by Smaia or Ssaia, depends on some other factors:
+the base ISA's XLEN (RV32 or RV64), whether \mbox{S-mode}
+and the hypervisor extension are implemented,
+and whether the hart has an IMSIC.
+But individual AIA extension names are not
+provided for each possible valid subset.
+Rather, the different combinations are inferable
+from the intersection of features indicated (such as
+RV64I + \mbox{S-mode} + Smaia, but without the hypervisor extension).
+
+Software development tools like compilers and assemblers need not
+be concerned about whether an IMSIC exists but should just
+allow attempts to access the IMSIC CSRs (described in Chapters
+\ref{ch:CSRs} and~\ref{ch:IMSIC}) if Smaia or Ssaia is indicated.
+Without an actual IMSIC, such attempts may trap,
+but that is not a problem for the development tools.
+

doc/src/preface.tex

@@ -0,0 +1,59 @@
+
+%=======================================================================
+\chapter{Preface}
+
+This document describes an Advanced Interrupt Architecture
+being proposed for {\RISCV} systems.
+
+No part of this document has yet been ratified
+by the {\RISCV} International Association.
+The table below shows the current status of each chapter,
+and also indicates which chapters specify extensions to the
+{\RISCV} ISA (instruction set architecture) and which are non-ISA.
+
+{
+\begin{table}[hbt]
+\centering
+\begin{tabular}{|l|c|c|}
+\hline
+Chapter                                                  & ISA? & Status \\
+\hline
+\hline
+1.\ Introduction                                         & ---  & Stable \\
+2.\ Control and Status Registers (CSRs) Added to Harts   & Yes  & Stable \\
+3.\ Incoming MSI Controller (IMSIC)                      & Yes  & Stable \\
+4.\ Advanced Platform-Level Interrupt Controller (APLIC) & No   & Stable \\
+5.\ Duo-PLIC                                             & No   & Draft \\
+6.\ Interrupts for Machine and Supervisor Levels         & Yes  & Stable \\
+7.\ Interrupts for Virtual Machines (VS Level)           & Yes  & Stable \\
+8.\ Interprocessor Interrupts (IPIs)                     & No   & Stable \\
+9.\ IOMMU Support for MSIs to Virtual Machines           & No   & Draft \\
+\hline
+\end{tabular}
+\end{table}
+}
+
+The chapters marked in the table as \emph{Stable} are not expected
+to change significantly before being put up for ratification,
+but changes of all kinds are still possible nonetheless.
+The chapters marked \emph{Draft} are very much
+at risk of changing before ratification.
+An implementation adhering to the current document might not conform
+to an eventual ratified Advanced Interrupt Architecture for {\RISCV}.
+
+Concerning the two chapters that remain in draft state:
+\begin{itemize}
+
+\item
+The authors are not aware that any implementation of
+a Duo-PLIC yet exists, even one just for simulation.
+So long as that remains true, the Duo-PLIC specification of
+Chapter~\ref{ch:DuoPLIC} will not advance beyond draft status.
+
+\item
+A separate standard is being developed for IOMMUs in {\RISCV} systems.
+Chapter~\ref{ch:IOMMU} about an IOMMU's support for MSIs
+(message-signaled interrupts) is expected to be finalized
+only in conjunction with the full {\RISCV} IOMMU specification.  
+\end{itemize}
+

doc/src/riscv-interrupts.tex

@@ -69,6 +69,8 @@
 
 \frontmatter
 
+\input{preface.tex}
+
 {\hypersetup{linktoc=all,hidelinks}
 \tableofcontents
 }