Re: [PATCH] Provide a simple introduction


atishp@...
 

On Tue, 2021-01-12 at 15:19 -0700, Al Stone wrote:
Provide a simple introduction the platform spec, and a brief
description of the overall structure.  This is essentially v3
of the proposal as submitted to the mailing list, along with
corrections and suggestions from all v3 reviewers, but in patch
form.

Signed-off-by: Al Stone <ahs3@...>
---
 introduction.adoc | 57 ++++++++++++++++++++++++++++++++++-----------
--
 1 file changed, 41 insertions(+), 16 deletions(-)

diff --git a/introduction.adoc b/introduction.adoc
index 322863c..e522474 100644
--- a/introduction.adoc
+++ b/introduction.adoc
@@ -1,23 +1,48 @@
-// SPDX-License-Indentifer: CC-BY-4.0
+// SPDX-License-Identifier: CC-BY-4.0
 //
-// introduction.adoc: describe the purpose of the document
+// introduction.adoc: provide an introduction to the document
 //
-// Provide a description of the overall intent and purpose of this
-// specifiction.
+// Provide a basic introduction to the overall document.
 //
 
-## Introduction
+# Introduction
 
-This document contains the RISC-V UNIX-class platform
specification.  This
-specification defines additional restrictions on implementations in
order to
-allow software to be compatible between these implementations. 
These
-restrictions are enumerated along with the least privileged level to
which they
-apply.  Implementations can be compatible with a subset of this
specification,
-but that subset must include all restrictions placed on a privilege
level as
-well as all less-privileged levels.  For example: implementations
can claim to
-be compatible with the "RISC-V Supervisor-Level UNIX Platform" if
they are
-compatible with the entire "User-Level Platform" and "Supervisor-
Level
-Platform" chapters of this document.
+This document is the RISC-V Profiles and Platform Specification
(RVP2S).
 
-### Versioning
+This specification defines the hardware and firmware required to be
able
+to install and use one or more operating environments (OEs) on a
computing
+system built around the RISC-V Instruction Set Architecture (ISA). 
The
+intent is to capture the constraints necessary for hardware so that
an
+operating environment can be assured it is compatible with that
hardware,
+if it is in compliance with the specification.
 
+For the purposes of this specification an _operating environment_
can
+range from a single application running on a bare metal system to a
full
+scale server operating system (OS) running a Linux distribution on a
+commercial off-the shelf (COTS) system.
+
+Constraints on the hardware and firmware comprising part of a
platform
+are key to this specification.  However, these constraints are only
meant
+to define a baseline set of functionality.  Vendors may add whatever
+advanced functionality they wish beyond that, as long as it is
discoverable
+in some way.  For example, any given platform may need an MMU or an
IRQ
+controller to boot, but may not require an I2C bus; the vendor can
of course
+add that bus if they wish, but it might not be part of the required
baseline
+for that platform.
+
+This specification also sets out any necessary constraints on the
RISC-V
+Instruction Set Architecture (ISA) -- at all privilege levels --
that are
+required to provide a consistent and predictable environment for
running
+operating systems.
+
+The intent is to provide only the constraints necessary, and not to
restrict
+creativity.
+
+The structure of the document is straightforward.  First, basic
terminology
+is defined, in particular the terms _profile_ and _platform_ that
form the
+basis for the structure of the rest of the specification.  Second,
the
+currently defined profiles are described, setting out the use of the
RISC-V
+architecture in a processor.  Third, the current defined platforms
are
+described with specific hardware, firmware, and software
requirements.
+And finally, checklists are provided in the appendices to make it
easier
+to determine if a new system meets a given platform specification.
--
2.26.2

+Kumar

--
Regards,
Atish

Join tech-unixplatformspec@lists.riscv.org to automatically receive all group messages.