From 70df31871de33e082ea03b860ba92cbbb0ce641c Mon Sep 17 00:00:00 2001 From: Al Stone Date: Sun, 22 Nov 2020 14:53:54 -0700 Subject: [PATCH] Provide a simple introduction 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 --- introduction.adoc | 292 ++++------------------------------------------ 1 file changed, 23 insertions(+), 269 deletions(-) diff --git a/introduction.adoc b/introduction.adoc index 4637433..e522474 100644 --- a/introduction.adoc +++ b/introduction.adoc @@ -2,8 +2,7 @@ // // introduction.adoc: provide an introduction to the document // -// Provide a basic introduction to the overall document, defining some -// key terms and usages. +// Provide a basic introduction to the overall document. // # Introduction @@ -11,11 +10,11 @@ This document is the RISC-V Profiles and Platform Specification (RVP2S). This specification defines the hardware and firmware required to be able -to install and use one or more operating environments (OEs) on a platform -built around the RISC-V Instruction Set Architecture (ISA). The intent -is to capture the constraints necessary for a hardware platform so that -an operating environment can be assured it is compatible with that platform, -if the platform is in compliance with this specification. +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 @@ -23,13 +22,15 @@ 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. For example, an OS needs to be able to -make some basic assumptions about the platform in order to boot; if there -are too many variations possible, it becomes unmanageable for the OS vendor -and could preclude using the platform at all. We would like to ensure this -does not happen. - -This specification also sets out any necessary constraints on the RISCV-V +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. @@ -37,258 +38,11 @@ operating systems. The intent is to provide only the constraints necessary, and not to restrict creativity. -## Platforms -The term _platform_ has already been used several times. The definition -used here is that a platform is the sum total of the hardware, firmware, -and software comprising a usable computer system. Examples include -smartphones, laptops, data center servers, single-board computers, tablets, -and almost anything in between. While this is not terribly precise, this -is intentional; this specification is not meant to constrain what a -platform is, but to clarify what software can expect of it. - -## Profiles -The term _profile_ is frequently used in the RISC-V world. It is time -to provide a reasonably precise definition of the term and how it -is to be used. We do this since the specification itself sets down -requirements on the basis of what a profile needs. - -Consider a platform as being built up by connecting together a number of -different interfaces -- the interfaces between hardware and firmware, or -firmware and software, or software and the end-user. - -What we would like to do is define just the interfaces between the objects -that constitute a platform. This allows the implementations to be whatever -they need to be, as long as they abide by the interface definition. For -example, we may need a UEFI Runtime Services interface. Whether that is -implemented via EDK2 source, or is an interface to linuxboot is irrelevant. -The functionality defined by the interface is the important part. - -Of particular interest in this specification are: - -* The User Interface: how the end-user of a system interacts with it. - Examples might be various Linux-, BSD- or Windows based systems; they - might also include a specific application developed for a specific use. - -* The Firmware Interface: how the User Interface makes use of S-mode. An - example is UEFI Runtime Services -- a list of the services needed in order - to allow the User Interface to work properly. - -* The Supervisor Interface: how the Firmware Interface interacts with RISC-V - hardware threads (_harts_), providing functionality to the Firmware - Interface to start and stop them, for example. There will likely be - cases, too, where the User Interface interacts directly with this - functionality, such as when it provides mechanims needed that are not - defined by the Firmware Interface. - -* The Hardware Interface: what the previously mentioned interfaces can expect - to be present; in a way this is the interface to the outside world, but most - likely it would be a list of the hardware components that are guaranteed - to be present, and what standards they comply with. - -* The Processor Interface: this interface defines what to expect of the - processor. In the case of RISC-V this would include the parts of the ISA - that and are not implemented. - -* The Boot Interface: this is what a user would see at a cold start of the - system -- for the most part these days, this includes U-Boot bootm/booti - or the UEFI Shell, though it could just as easily be linuxboot or coreboot. - This defines the functionality needed to boot the system, update the - firmware and possibly manage the system remotely; this will have to - interact closely with OS booting protocols. - -For the above interfaces, a platform must provide an instance of each one; -a platform would not be usable without all of them. There are some interfaces -that could be optional: - -* The Enumeration Interface: how the User Interface determine what hardware - is present on the platform; this will need to include mechanisms for finding - self-identifying hardware such as PCIe, and for hardware that does not - identify itself such as UARTs, the motherboard, or CPU topology. This - is typically ACPI in general purpose computing platforms, and Device Tree - in embedded systems. Note that this may include further information such - as SMBIOS data. At the same time, though, a very specific-use platform - may already encapsulate all of this knowledge in the software being run - so neither ACPI nor DT are needed. - -* The Secondary Boot Loader: not all OEs require this. For the ones that - do, it must behave correctly. GRUB2 is expected by all recent Linux - distributions, for example. - -For each of the interfaces listed above, there is a domain of possibilities. -Let us look at each domain of interfaces as an element in an n-tuple defined -as follows: - -``` - N = { user, firmware, supervisor, hardware, processor, boot, - enumeration, secondary-boot-loader } -``` - -Not all of the permutations of this set make sense. Not all of them are -necessarily useful. However, it does allow us to provide a more precise -definition of a profile -- a _profile_ is a value in **_N_**, a profile-tuple, -if you will. - -### An Example Profile -The test of any formalism is whether or not it is usable. So, let’s define -a general purpose Linux platform that could be used to run one of the various -Linux distributions such as RHEL, Fedora, SuSE, Debian, ArchLinux or maybe -even Gentoo and Slackware. The profile might be: - -``` - LinuxServer = { Linux, UEFI, OpenSBI, rack-mount, RV64GC, UEFI Shell, - ACPI, GRUB2} -``` - -This is just an example of what is possible; it is not definitive. A proper -profile for Linux server distributions will be provided later in this -specification. Regardless, this could tell us: - -* The User Interface is a Linux system of some flavor. -* The Firmware Interface is UEFI, built upon SBI. -* The Supervisor Interface is OpenSBI. -* The Hardware Interface is for rack-mount server systems -- defining - this is where we would have to list what devices that implies. -* The Processor Interface is RV64GC (U-mode, and S-mode) -* The Boot Interface is the UEFI Shell. -* The Enumeration Interface is ACPI, so we now know how to identify - all of the hardware being used. -* The Secondary Boot Loader is GRUB2, so Linux now has some idea of - how it will be booted. - -And, as long as the interface definitions are fairly clear, we can now -determine what would be in a platform that supports the ```LinuxServerDistro``` -profile. It is the purview of this platform specification to (a) define -the profiles of interest, and then (b) ensure that each of the terms -in the n-tuple -- the interfaces -- are clearly defined. - -### Other Distros -While the definition of a ```LinuxServerDistro``` profile used above would -seem to preclude non-Linux operating systems, defining a profile as an -n-tuple gives us a way of handling this. For example, let’s suppose we -define profiles for Windows and most BSD-based systems: - -``` - WindowsDistro = { Windows, UEFI, OpenSBI, rack-mount, RV64GC, UEFI Shell, - ACPI, WindowsLoader} - - BSDServer = { NetBSD, UEFI, OpenSBI, rack-mount, RV64GC, UEFI Shell, - ACPI, GPT} -``` - -Again, these are only examples, and not definitive. Given what we know -about these sorts of systems, we could assert the following: - -``` - LinuxServer = WindowsDistro = BSDServer -``` - -That is, all of these are essentially identical in the things that matter -to this specification. We know that’s not exactly true, of course, but this -does give us the tool to start reasoning about such things. - -### Notation -Whilst set notation is all well and good, we need something a bit more -practical. For that, we can borrow from the example provided by GCC. -A profile tuple would then be: - -``` - N = user-firmware-supervisor-hardware-processor-boot-enumeration-secondary -``` - -Or, for the example profiles listed above: - -``` - linux-server = linux-uefi-opensbi-rackmount-rv64gc-uefi-acpi-grub2 - windows-distro = windows-uefi-opensbi-rackmount-rv64gc-uefi-acpi-windows - bsd-server = bsd-uefi-opensbi-rackmount-rv64gc-uefi-acpi-gpt -``` - -For the long term, these could be converted into values and captured in -firmware to be relayed to the OS, perhaps as part of the Chosen node in -the DT used to pass information to the Linux kernel. In this manner, the -platform would describe itself, instead of the OS having to make an -educated guess. - -### Revisions -Over time, the definitions of the elements in this profile-tuple will -change. It’s simply the nature of the problem -- new hardware will be -defined, and ultimately will be assumed to be present, or old hardware -will get deprecated (e.g., CXL, and perhaps some day UARTs, respectively). -Hence, we will need to be able to note the revision of an element definition -for a profile definition to be complete. Again, we could have the firmware -convey this information to the OS as an additional byte string (how is TBD). -For practical use, we may wish to append the revisions to the tuple notation: - -``` - N = user-firmware-supervisor-hardware-processor-boot-enumeration-secondary \ - :ur-fr-sr-hr-pr-br-er-sr -``` - -Or, for the example profiles listed above: - -``` - linux-server = linux-uefi-opensbi-rackmount-rv64gc-uefi-acpi-grub2: \ - 0-0-0-0-0-0-0-0 - windows-distro = windows-uefi-opensbi-rackmount-rv64gc-uefi-acpi-windows: \ - 0-3-5-5-0-1-0-2 - bsd-server = bsd-uefi-opensbi-rackmount-rv64gc-uefi-acpi-gpt: \ - 1-0-3-4-0-1-0-2 -``` - -### Some Notes -* Profiles are _only_ a property of platforms, _not_ harts. -* This section uses example profiles; these are not intended to be definitive. - Proper profile definitions will appear in following sections of the - specification. -* This section presents the current definition of a platform-tuple. This - may change as we know more. - - -# Profiles -## Linux Profiles -### Linux Development SBC Profile -### Linux Laptop Profile -### Linux Desktop Profile -### Linux Server Profile -``` - linux-server = linux-uefi-opensbi-rackmount-rv64gc-uefi-acpi-grub2 -``` - -## BSD Profiles - -## Windows Profiles - -## Bare Metal SBC Profiles - -# Interface Specifications - -## User Interfaces -### Linux -### Windows -### BSD - -## Firmware Interfaces -### UEFI -### U-Boot - -## Supervisor Interfaces -### SBI - -## Hardware Interfaces -### Console -### I/O - -## Processor Interfaces - -## Boot Interfaces -### UEFI Shell -### U-Boot bootm/booti - -## Enumeration Interfaces -### ACPI -### Device Tree -### SMBIOS - -## Secondary Boot Loaders -### GRUB2 - +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.