Merge pull request #7 from ahs3/basics

Basics

.gitignore

@@ -0,0 +1,4 @@
+riscv-platform-spec.html
+riscv-platform-spec.md
+riscv-platform-spec.pdf
+riscv-platform-spec.xml

Makefile

@@ -0,0 +1,41 @@
+#
+#	Build usable docs
+#
+
+ASCIIDOCTOR = asciidoctor
+PLATFORM_SPEC = riscv-platform-spec
+PANDOC = pandoc
+PARTS = changelog.adoc contributors.adoc introduction.adoc licensing.adoc \
+	profiles.adoc supervisor-level.adoc user-level.adoc
+
+# Build the platform spec in several formats
+all: $(PLATFORM_SPEC).md $(PLATFORM_SPEC).pdf $(PLATFORM_SPEC).html
+
+$(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml
+	$(PANDOC) -f docbook -t markdown_strict $< -o $@ 
+
+$(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc
+	$(ASCIIDOCTOR) -d book -b docbook $<
+
+$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc
+	$(ASCIIDOCTOR) -d book -r asciidoctor-pdf -b pdf $<
+
+$(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc
+	$(ASCIIDOCTOR) -d book -b html $<
+
+$(PLATFORM_SPEC).adoc: $(PARTS)
+	touch $@
+
+clean:
+	rm -f $(PLATFORM_SPEC).xml
+	rm -f $(PLATFORM_SPEC).md
+	rm -f $(PLATFORM_SPEC).pdf
+	rm -f $(PLATFORM_SPEC).html
+
+# handy shortcuts for installing necessary packages: YMMV
+install-debs:
+	sudo apt-get install pandoc asciidoctor ruby-asciidoctor-pdf
+
+install-rpms:
+	sudo dnf install pandoc rubygem-asciidoctor rubygem-asciidoctor-pdf
+

changelog.adoc

@@ -0,0 +1,14 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// changelog.adoc: change log for the document
+//
+// Provide a list of changes made to each revision of the document.
+//
+[preface]
+## Change Log
+
+### Version 0.1-rc0
+* 2020-10-07:
+** Initial changes for structure and future maintenance.
+** Break content down into include files; more structure, but easier
+   to make changes down the line.

contributors.adoc

@@ -0,0 +1,31 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// contributors.adoc: acknowledge document contributors
+//
+// Provide a simple acknowledgement to all who have contributed to the
+// specifiction.
+//
+[appendix]
+## Contributors
+
+All of these individuals either wrote portions of this specification or
+contributed ideas and suggestions in some way:
+
+Krste Asanovic,
+Allen Baum,
+Palmer Dabbelt,
+Greg Favor,
+Mark Himelstein,
+David Kruckmeyer,
+Anup Patel,
+Atish Patra,
+Al Stone,
+Arun Thomas,
+Philipp Tomsich,
+Paul Walmsley,
+Andrew Waterman.
+
+If you have contributed and are not listed, do let us know.  We haven't
+forgotten you, but we may have forgotten to edit this list.
+
+Thank you.

introduction.adoc

@@ -0,0 +1,23 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// introduction.adoc: describe the purpose of the document
+//
+// Provide a description of the overall intent and purpose of this
+// specifiction.
+//
+
+## 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.
+
+### Versioning
+

licensing.adoc

@@ -0,0 +1,21 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// licensing.adoc: licensing information
+//
+// Copyright and licensing information for the specification.
+//
+[preface]
+## Copyright and License Information
+
+This RISC-V Profile and Platform Specification (P2S) is
+
+[%hardbreaks]
+(C) 2017 Krste Asanovic <krste@sifive.com>
+(C) 2017-2019 Palmer Dabbelt <palmer@sifive.com>
+(C) 2017 Andrew Waterman <andrew@sifive.com>
+(C) 2020 Al Stone <ahs3@redhat.com>
+
+The P2S is licensed under the Creative Commons Attribution 4.0 International
+License (CC-BY 4.0).  The full license text is available at
+https://creativecommons.org/licenses/by/4.0/.
+

profiles.adoc

@@ -0,0 +1,13 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// profiles.adoc: original Profiles content
+//
+// This is material from the very first draft of the spec.
+//
+
+## Profiles
+
+### Portable UNIX Platform Profile
+
+* Supervisor-mode environments must implement RV64GC.
+

riscv-platform-spec.adoc

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: CC-BY-4.0
+//
+// riscv-platform-spec.adoc: main file for the specification
+//
+// This file provides the primary structure and formatting for
+// the overal Profile and Platform Specification.
+//
+# RISC-V Profile and Platform Specification
+:author: RISC-V Platform Specification Task Group
+:email: [email protected]
+:revnumber: 0.1-rc0
+:revdate: October 2020
+:doctype: book
+:sectnums:
+:toc: macro
+
+// table of contents
+toc::[]
+
+// document copyright and licensing information
+include::licensing.adoc[]
+
+// changelog for the document
+include::changelog.adoc[]
+
+// Introduction: describe the intent and purpose of the document
+include::introduction.adoc[]
+
+// User-Level Platform (NB: content from very first version)
+include::user-level.adoc[]
+
+// Supervisor-Level Platform (NB: content from very first version)
+include::supervisor-level.adoc[]
+
+// Machine-Level Platform (NB: content from very first version)
+// This is the only line in that original content.
+## Machine-Level Platform
+
+// Profiles: (NB: content from very first version)
+include::profiles.adoc[]
+
+// acknowledge all of the contributors
+include::contributors.adoc[]
+

supervisor-level.adoc

@@ -0,0 +1,26 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// supervisor-level.adoc: original Supervisor Level Platform content
+//
+// This is material from the very first draft of the spec.
+//
+
+## Supervisor-Level Platform
+
+* Supervisor-mode environments must implement at least version 0.2.0 of the
+  RISC-V SBI specification, which can be found at
+  https://github.com/riscv/riscv-sbi-doc/blob/v0.2.0/riscv-sbi.adoc
+* Supervisor-mode environments must implement the Sv39 page-based
+  virtual-memory scheme.   Systems that support Sv48 must support Sv39, systems
+  that support Sv57 must support Sv48, and so forth.
+* Unless otherwise specified by a given I/O device, I/O regions are at least
+  point-to-point strongly ordered.  All devices attached to a given PCIe root
+  complex are on the same ordered channel (numbered 2 or above), though
+  different root complexes might not be on the same ordering channel.
+* On RV64I-based Unix-class systems the negative virtual addresses are reserved
+  for the kernel.
+* External devices (DMA engines, the debug unit, non RISC-V cores, etc) that
+  are visible to RISC-V harts must appear as coherent agents, just like any
+  RISC-V hart would.  If additional ordering constraints are necessary for a
+  device to function, those will be provide by a device-specific mechanism.
+

user-level.adoc

@@ -0,0 +1,23 @@
+// SPDX-License-Indentifer: CC-BY-4.0
+//
+// user-level.adoc: original User Level Platform content
+//
+// This is material from the very first draft of the spec.
+//
+
+## User-Level Platform
+
+* User-mode environments must implement at least version 2.2 of the RISC-V User
+  ISA specification, which can be found at
+  https://github.com/riscv/riscv-isa-manual/blob/master/release/riscv-spec-v2.2.pdf.  
+* User-mode programs may not execute the `fence.i` instruction.
+* User-mode environments may provide additional ISA extensions, but if those
+  extensions add user-visible state they must be initially disabled.
+* Within main-memory regions, aligned instruction fetch must be atomic, up to
+  the smaller of ILEN and XLEN bits.  In particular, if an aligned 4-byte word
+  is stored with the `sw` instruction, then any processor attempts to execute
+  that word, the processor either fetches the newly stored word, or some previous
+  value stored to that location.  (That is, the fetched instruction is not an
+  unpredictable value, nor is it a hybrid of the bytes of the old and new
+  values.)
+