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.