diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e6ef639 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +riscv-platform-spec.html +riscv-platform-spec.md +riscv-platform-spec.pdf +riscv-platform-spec.xml diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..de5e0b0 --- /dev/null +++ b/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 + diff --git a/changelog.adoc b/changelog.adoc new file mode 100644 index 0000000..5e72f7e --- /dev/null +++ b/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. diff --git a/contributors.adoc b/contributors.adoc new file mode 100644 index 0000000..f499a1d --- /dev/null +++ b/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. diff --git a/introduction.adoc b/introduction.adoc new file mode 100644 index 0000000..322863c --- /dev/null +++ b/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 + diff --git a/licensing.adoc b/licensing.adoc new file mode 100644 index 0000000..e24cbd5 --- /dev/null +++ b/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 +(C) 2017-2019 Palmer Dabbelt +(C) 2017 Andrew Waterman +(C) 2020 Al Stone + +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/. + diff --git a/profiles.adoc b/profiles.adoc new file mode 100644 index 0000000..daae58a --- /dev/null +++ b/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. + diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc new file mode 100644 index 0000000..e223e65 --- /dev/null +++ b/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: tech-unixplatformspec@lists.riscv.org +: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[] + diff --git a/riscv-unix.adoc b/riscv-unix.adoc deleted file mode 100644 index 48e989e..0000000 --- a/riscv-unix.adoc +++ /dev/null @@ -1,72 +0,0 @@ -# RISC-V UNIX-Class Platform Specification - -## Copyright and license information - -This RISC-V Unix-class platform specification is - -[%hardbreaks] -(C) 2017 Krste Asanovic -(C) 2017-2019 Palmer Dabbelt -(C) 2017 Andrew Waterman - -It 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/. - -## 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 - -## 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.) - -## 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. - -## Machine-Level Platform - -## Profiles - -### Portable UNIX Platform Profile - -* Supervisor-mode environments must implement RV64GC. diff --git a/supervisor-level.adoc b/supervisor-level.adoc new file mode 100644 index 0000000..151d8b7 --- /dev/null +++ b/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. + diff --git a/user-level.adoc b/user-level.adoc new file mode 100644 index 0000000..c02f852 --- /dev/null +++ b/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.) +