├── .gitignore ├── index.adoc ├── images └── risc-v_logo.svg ├── bibliography.adoc ├── .gitmodules ├── dependencies ├── README.md ├── package.json ├── apt_packages.txt └── Gemfile ├── CODE_OF_CONDUCT.md ├── .github ├── dependabot.yml └── workflows │ └── build-pdf.yml ├── GOVERNANCE.md ├── MAINTAINERS.md ├── non-normative ├── smbios.adoc ├── guidance.adoc ├── recipes.adoc ├── uefi.adoc └── acpi.adoc ├── contributors.adoc ├── hart.adoc ├── acpi-prop.adoc ├── sbi.adoc ├── acpi-id.adoc ├── brs_ts_header.adoc ├── header.adoc ├── Makefile ├── readme.adoc ├── recipes.adoc ├── brs_ts_intro.adoc ├── CONTRIBUTING.md ├── brs.bib ├── intro.adoc ├── smbios.adoc ├── acpi.adoc ├── brs_tests.adoc ├── uefi.adoc └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | *.pdf 2 | *.sw[op] 3 | -------------------------------------------------------------------------------- /index.adoc: -------------------------------------------------------------------------------- 1 | [index] 2 | == Index 3 | -------------------------------------------------------------------------------- /images/risc-v_logo.svg: -------------------------------------------------------------------------------- 1 | ../docs-resources/images/risc-v_logo.svg -------------------------------------------------------------------------------- /bibliography.adoc: -------------------------------------------------------------------------------- 1 | [bibliography] 2 | == Bibliography 3 | 4 | bibliography::[] 5 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "docs-resources"] 2 | path = docs-resources 3 | url = https://github.com/riscv/docs-resources.git 4 | -------------------------------------------------------------------------------- /dependencies/README.md: -------------------------------------------------------------------------------- 1 | Dependencies for the build environment for various package managers. Used in 2 | `.github/workflows/`. 3 | 4 | -------------------------------------------------------------------------------- /dependencies/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "local", 3 | "version": "0.0.1", 4 | "dependencies": { 5 | "wavedrom-cli": "^2.6.8" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # RISC-V Code of Conduct 2 | All RISC-V International projects are governed by the RISC-V Code of Conduct found at https://riscv.org/community/community-code-of-conduct/. 3 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | --- 2 | # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem 3 | version: 2 4 | updates: 5 | - package-ecosystem: gitsubmodule 6 | directory: / 7 | schedule: 8 | interval: daily 9 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Governance 2 | This project for the template specification is governed by the Boot and Runtime Services (BRS) SIG. 3 | 4 | The group can be joined by RISC-V members at: https://lists.riscv.org/g/tech-brs. 5 | 6 | Mailing list archives are available at: https://lists.riscv.org/g/tech-brs/topics. 7 | -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | This project is maintained by the following people: 3 | 4 | - Aaron Durbin ([adurbin-rivos](https://github.com/adurbin-rivos)) 5 | - Andrei Warkentin ([andreiw](https://github.com/andreiw)) 6 | - Anup Patel ([avpatel](https://github.com/avpatel)) 7 | - Sunil V L ([vlsunil](https://github.com/vlsunil)) 8 | -------------------------------------------------------------------------------- /dependencies/apt_packages.txt: -------------------------------------------------------------------------------- 1 | bison 2 | build-essential 3 | cmake 4 | curl 5 | flex 6 | fonts-lyx 7 | git 8 | graphviz 9 | # For wavedrom 10 | default-jre 11 | libcairo2-dev 12 | libffi-dev 13 | libgdk-pixbuf2.0-dev 14 | libpango1.0-dev 15 | libxml2-dev 16 | make 17 | pkg-config 18 | ruby 19 | ruby-dev 20 | # for mathematical 21 | libwebp-dev 22 | -------------------------------------------------------------------------------- /dependencies/Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | gem 'mathematical', '1.6.14' 3 | gem 'asciidoctor' 4 | gem 'asciidoctor-bibtex' 5 | gem 'asciidoctor-diagram' 6 | gem 'asciidoctor-mathematical' 7 | gem 'asciidoctor-pdf' 8 | gem 'citeproc-ruby' 9 | gem 'coderay' 10 | gem 'csl-styles' 11 | gem 'json' 12 | gem 'pygments.rb' 13 | gem 'rghost' 14 | gem 'rouge' 15 | gem 'ruby_dev' 16 | -------------------------------------------------------------------------------- /non-normative/smbios.adoc: -------------------------------------------------------------------------------- 1 | Note the DMTF requirements on the 64-bit SMBIOS 3.0 entry point (cite:[SMBIOS] Section 5.2.2), and the conformance guidelines (cite:[SMBIOS] Annex A). 2 | 3 | ==== Type 44 Processor-Specific Data 4 | 5 | The `Machine Vendor ID`, `Machine Architecture ID`, and `Machine Implementation ID` fields typically reflect the `mvendorid`, `marchid` and `mimpid` CSRs respectively. 6 | -------------------------------------------------------------------------------- /contributors.adoc: -------------------------------------------------------------------------------- 1 | == Contributors 2 | 3 | This RISC-V specification has been contributed to directly or indirectly by (in alphabetical order): 4 | 5 | [%hardbreaks] 6 | Aaron Durbin, Andrei Warkentin, Andrew Jones, Anup Patel, Atish Patra, Beeman Strong, Darius Rad, Heinrich Schuchardt, Haibo Xu, Jamie Iles, John Hauser, Radim Krčmář, Rahul Pathak, Paul Walmsley, Samuel Holland, Sia Jee Heng, Sunil V L, Vedvyas Shanbhogue 7 | -------------------------------------------------------------------------------- /non-normative/guidance.adoc: -------------------------------------------------------------------------------- 1 | [[guidance]] 2 | == Firmware Implementation Guidance 3 | 4 | The guidance section is non-normative, and covers certain 5 | implementation choices, suggestions, historical context, etc. 6 | 7 | [[recipes-guidance]] 8 | === Recipes Guidance 9 | include::recipes.adoc[] 10 | 11 | [[uefi-guidance]] 12 | === UEFI Implementation Guidance 13 | include::uefi.adoc[] 14 | 15 | [[acpi-guidance]] 16 | === ACPI Implementation Guidance 17 | include::acpi.adoc[] 18 | 19 | [[smbios-guidance]] 20 | === SMBIOS Implementation Guidance 21 | include::smbios.adoc[] 22 | -------------------------------------------------------------------------------- /non-normative/recipes.adoc: -------------------------------------------------------------------------------- 1 | [[recipe-brs-i-guidance]] 2 | ==== BRS-I Recipe Guidance 3 | 4 | Systems compliant to BRS-I can successfully boot an existing generic 5 | operating system image without system-specific customizations, yet 6 | this might result in an unoptimized experience and non-functioning 7 | I/O devices until further software updates are activated. 8 | 9 | The best analogy would be a typical Intel Architecture motherboard from 10 | the early 2000s: you could install an OS on it, but the built-in graphics 11 | might be low-resolution and the sound, built-in network port or power 12 | management might not work out of the box. You could subsequently load 13 | the right drivers from the media coming with the board or fetch newest 14 | ones using a well-supported network adapter. 15 | -------------------------------------------------------------------------------- /hart.adoc: -------------------------------------------------------------------------------- 1 | [[hart]] 2 | == Hart Requirements 3 | 4 | A compliant system includes a RISC-V application processor and the requirements in this section apply solely to harts in the application processors of a system. 5 | 6 | The BRS specification is minimally prescriptive on the RISC-V hart requirements. It is anticipated that detailed requirements will be driven by target market segment and product/solution requirements. 7 | 8 | [width=100%] 9 | [%header, cols="5,25"] 10 | |=== 11 | | ID# ^| Rule 12 | | `HR_010` | The RISC-V application processor harts MUST be compliant to `RVA20S64` profile cite:[Profile]. 13 | 2+| _The BRS governs the interactions between 64-bit OS supervisor-mode software and 64-bit firmware. These are minimum requirements allowing for the wide variety of existing and future hart implementations to be supported. It is expected that operating systems and hypervisors may impose additional profile/ISA requirements, depending on the use-case and application._ 14 | 15 | |=== 16 | -------------------------------------------------------------------------------- /acpi-prop.adoc: -------------------------------------------------------------------------------- 1 | [[acpi-props]] 2 | === RVI-specific ACPI Device Properties 3 | 4 | This section is used to define the `_DSD` device properties cite:[DSD] in the `rscv-` namespace. 5 | 6 | Where explicit values are provided in a property definition, only these values must be used. System behavior with any other values is undefined. 7 | 8 | [width=100%] 9 | [%header, cols="10,5,25"] 10 | |=== 11 | | Property ^| Type | Description 12 | 3+|_Currently, there are no properties defined in the `rscv-` namespace. Request for new property names in the `rscv-` namespace should be made as a git pull request to this table._ 13 | |=== 14 | 15 | 16 | [[acpi-props-uart]] 17 | === ACPI Device Properties for UART Devices 18 | Generic 16550-compatible UART devices can have device properties in the global name space 19 | since Operating Systems are already using them. 20 | 21 | [width=100%] 22 | [%header, cols="10,5,25"] 23 | |=== 24 | | Property ^| Type | Description 25 | | `clock-frequency` | Integer | Clock feeding the IP block in Hz. 26 | 3+| _A value of zero will preclude the ability to set the baud rate, or 27 | to configure a disabled device._ 28 | | `reg-offset` | Integer | Offset to apply to the register map base address from the start of the registers. 29 | | `reg-shift` | Integer | Quantity to shift the register offsets by. 30 | | `reg-io-width` | Integer | The size (in bytes) of the register accesses that should be performed on the device. 31 | 3+| _1, 2, 4 or 8._ 32 | | `fifo-size` | Integer | The FIFO size (in bytes). 33 | |=== 34 | 35 | -------------------------------------------------------------------------------- /sbi.adoc: -------------------------------------------------------------------------------- 1 | [[sbi]] 2 | == SBI Requirements 3 | 4 | The _RISC-V Supervisor Binary Interface Specification_ (SBI) cite:[SBI] defines an interface 5 | between the supervisor mode and the next higher privilege mode. This section 6 | defines the mandatory SBI version and extensions implemented by the higher 7 | privilege mode in order to be compatible with this specification. 8 | 9 | [width=100%] 10 | [%header, cols="5,25"] 11 | |=== 12 | | ID# ^| Rule 13 | | `SBI_010` | The SBI implementation MUST conform to SBI v2.0 or later. 14 | | `SBI_020` | The SBI implementation MUST implement the Hart State Management (HSM) extension. 15 | 2+| _HSM is used by an OS for starting up, stopping, suspending and querying the status of secondary harts._ 16 | |=== 17 | 18 | Certain requirements are conditional on the presence of RISC-V ISA extensions or system features. 19 | 20 | [width=100%] 21 | [%header, cols="5,25"] 22 | |=== 23 | | ID# ^| Rule 24 | | `SBI_030` | The Timer Extension (TIME) MUST be implemented, if the RISC-V "stimecmp / vstimecmp" Extension (Sstc, cite:[Sstc]) is not available. 25 | | `SBI_040` | The S-Mode IPI Extension (sPI) MUST be implemented, if the Incoming MSI Controller (IMSIC, cite:[Aia]) is not available. 26 | | `SBI_050` | The RFENCE Extension (RFNC) extension MUST be implemented, if the Incoming MSI Controller (IMSIC, cite:[Aia]) is not available. 27 | | `SBI_060` | The Performance Monitoring Extension (PMU) MUST be implemented, if the counter delegation-related S-Mode ISA extensions (Sscsrind cite:[Sscsrind] and Ssccfg cite:[Smcdeleg]) are not present. 28 | | `SBI_070` | The Debug Console Extension (DBCN) MUST be implemented if the ACPI SPCR table references Interface Type 0x15. 29 | |=== 30 | -------------------------------------------------------------------------------- /acpi-id.adoc: -------------------------------------------------------------------------------- 1 | [[acpi-ids]] 2 | === RVI-specific ACPI IDs 3 | 4 | ACPI ID is used in the `_HID` (Hardware ID), `_CID` (Compatible ID) or 5 | `_SUB` (Subsystem ID) objects as described in the ACPI Specification for 6 | devices, that do not have a standard enumeration mechanism. The ACPI ID 7 | consists of two parts: a vendor identifier followed by a product identifier. 8 | 9 | Vendor IDs consist of 4 characters, each character being either an 10 | uppercase letter (A-Z) or a numeral (0-9). The vendor ID SHOULD be 11 | unique across the Industry and registered by the UEFI forum. For RVI 12 | standard devices, `RSCV` is the vendor ID registered. Vendor-specific 13 | devices can use an appropriate vendor ID registered for the manufacturer. 14 | 15 | Product IDs are always four-character hexadecimal numbers (0-9 16 | and A-F). The device manufacturer is responsible for assigning this 17 | identifier to each product model. 18 | 19 | This document contains the canonical list of ACPI IDs for the namespace 20 | devices that adhere to the RVI specifications. The RVI task groups may 21 | make pull requests against this repository to request the allocation of 22 | ACPI ID for any new device. 23 | 24 | [width=100%] 25 | [%header, cols="5,25"] 26 | |=== 27 | | ACPI ID ^| Device 28 | | `RSCV0001` | RISC-V Platform-Level Interrupt Controller (PLIC) 29 | | `RSCV0002` | RISC-V Advanced Platform-Level Interrupt Controller (APLIC) 30 | | `RSCV0003` | NS16550 UART compatible with an SPCR definition using `Interface Type` 0x12 31 | | `RSCV0004` | RISC-V IOMMU implemented as a platform device 32 | | `RSCV0005` | RISC-V SBI Message Proxy (MPXY) Mailbox Controller 33 | | `RSCV0006` | RISC-V RPMI System MSI Interrupt Controller 34 | 2+| _Also see <>._ 35 | |=== 36 | -------------------------------------------------------------------------------- /brs_ts_header.adoc: -------------------------------------------------------------------------------- 1 | [[header]] 2 | :description: RISC-V Boot and Runtime Services Test Specification 3 | :company: RISC-V.org 4 | :url-riscv: http://riscv.org 5 | :revdate: 7th February 2024 6 | :revnumber: 0.1 7 | :revremark: This document is in Development state. Change should be expected. 8 | :doctype: book 9 | :preface-title: Preamble 10 | :colophon: 11 | :appendix-caption: Appendix 12 | :imagesdir: images 13 | :title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center] 14 | // Settings: 15 | :experimental: 16 | :reproducible: 17 | :imagesoutdir: images 18 | :bibtex-file: brs.bib 19 | :bibtex-order: appearance 20 | :bibtex-style: ieee 21 | :icons: font 22 | :lang: en 23 | :listing-caption: Listing 24 | :sectnums: 25 | :toc: left 26 | :toclevels: 4 27 | :source-highlighter: pygments 28 | ifdef::backend-pdf[] 29 | :source-highlighter: coderay 30 | endif::[] 31 | :data-uri: 32 | :hide-uri-scheme: 33 | :stem: latexmath 34 | :footnote: 35 | :xrefstyle: short 36 | 37 | = RISC-V Boot and Runtime Services Test Specification 38 | BRS Task Group 39 | 40 | // Preamble 41 | [WARNING] 42 | .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[Development state] 43 | ==== 44 | Assume everything can change. This draft specification will change before 45 | being accepted as standard, so implementations made to this draft 46 | specification will likely not conform to the future standard. 47 | ==== 48 | 49 | [preface] 50 | == Copyright and license information 51 | This specification is licensed under the Creative Commons 52 | Attribution 4.0 International License (CC-BY 4.0). The full 53 | license text is available at 54 | https://creativecommons.org/licenses/by/4.0/. 55 | 56 | Copyright 2024 by RISC-V International. 57 | 58 | [preface] 59 | include::contributors.adoc[] 60 | include::brs_ts_intro.adoc[] 61 | include::brs_tests.adoc[] 62 | include::bibliography.adoc[] 63 | -------------------------------------------------------------------------------- /header.adoc: -------------------------------------------------------------------------------- 1 | [[header]] 2 | :description: RISC-V Boot and Runtime Services Specification Document (BRS) 3 | :company: RISC-V.org 4 | :url-riscv: http://riscv.org 5 | :revdate: 29th August 2025 6 | :revnumber: 1.0 7 | :revremark: This document is Ratified. 8 | :doctype: book 9 | :preface-title: Preamble 10 | :colophon: 11 | :appendix-caption: Appendix 12 | :imagesdir: images 13 | :title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center] 14 | // Settings: 15 | :experimental: 16 | :reproducible: 17 | :imagesoutdir: images 18 | :bibtex-file: brs.bib 19 | :bibtex-order: appearance 20 | :bibtex-style: ieee 21 | :icons: font 22 | :lang: en 23 | :listing-caption: Listing 24 | :sectnums: 25 | :toc: left 26 | :toclevels: 4 27 | :source-highlighter: pygments 28 | ifdef::backend-pdf[] 29 | :source-highlighter: coderay 30 | endif::[] 31 | :data-uri: 32 | :hide-uri-scheme: 33 | :stem: latexmath 34 | :footnote: 35 | :xrefstyle: short 36 | 37 | = RISC-V Boot and Runtime Services Specification (BRS) 38 | BRS Task Group 39 | 40 | // Preamble 41 | [WARNING] 42 | .This document is in the link:https://riscv.org/specifications/ratified/[Ratified state] 43 | ==== 44 | No changes are allowed. Any necessary or desired modifications must be 45 | addressed through a follow-on extension. Ratified extensions are never 46 | revised. 47 | ==== 48 | 49 | [preface] 50 | == Copyright and license information 51 | This specification is licensed under the Creative Commons 52 | Attribution 4.0 International License (CC-BY 4.0). The full 53 | license text is available at 54 | https://creativecommons.org/licenses/by/4.0/. 55 | 56 | Copyright 2024-2025 by RISC-V International. 57 | 58 | [preface] 59 | include::contributors.adoc[] 60 | 61 | include::intro.adoc[] 62 | include::recipes.adoc[] 63 | include::hart.adoc[] 64 | include::sbi.adoc[] 65 | include::uefi.adoc[] 66 | include::acpi.adoc[] 67 | include::smbios.adoc[] 68 | include::non-normative/guidance.adoc[] 69 | 70 | //the index must precede the bibliography 71 | include::index.adoc[] 72 | include::bibliography.adoc[] 73 | -------------------------------------------------------------------------------- /.github/workflows/build-pdf.yml: -------------------------------------------------------------------------------- 1 | name: Create Specification Document 2 | 3 | # The workflow is triggered by pull request, push to main, and manual dispatch. 4 | on: 5 | workflow_dispatch: 6 | inputs: 7 | version: 8 | description: 'Release version, e.g. X.Y.Z:' 9 | required: true 10 | type: string 11 | revision_mark: 12 | description: 'Set revision mark as Draft, Release or Stable:' 13 | required: true 14 | type: string 15 | default: 'Draft' 16 | prerelease: 17 | description: 'Tag as a pre-release?' 18 | required: false 19 | type: boolean 20 | default: true 21 | draft: 22 | description: 'Create release as a draft?' 23 | required: false 24 | type: boolean 25 | default: false 26 | pull_request: 27 | push: 28 | branches: 29 | - main 30 | 31 | jobs: 32 | build: 33 | runs-on: ubuntu-latest 34 | 35 | steps: 36 | # Step 1: Checkout the repository 37 | - name: Checkout repository 38 | uses: actions/checkout@v3 39 | with: 40 | submodules: 'recursive' 41 | 42 | # Step 2: Pull the latest RISC-V Docs container image 43 | - name: Pull Container 44 | run: docker pull riscvintl/riscv-docs-base-container-image:latest 45 | 46 | # Step 3: Build Files 47 | - name: Build Files 48 | run: make 49 | env: 50 | VERSION: v${{ github.event.inputs.version }} 51 | REVMARK: ${{ github.event.inputs.revision_mark }} 52 | 53 | # Step 4: Upload the built PDF files as a single artifact 54 | - name: Upload Build Artifacts 55 | uses: actions/upload-artifact@v4 56 | with: 57 | name: Build Artifacts 58 | path: ${{ github.workspace }}/*.pdf 59 | retention-days: 30 60 | 61 | # Create Release 62 | - name: Create Release 63 | uses: softprops/action-gh-release@v1 64 | with: 65 | files: ${{ github.workspace }}/*.pdf 66 | tag_name: v${{ github.event.inputs.version }} 67 | name: Release ${{ github.event.inputs.version }} 68 | draft: ${{ github.event.inputs.draft }} 69 | prerelease: ${{ github.event.inputs.prerelease }} 70 | env: 71 | GITHUB_TOKEN: ${{ secrets.GHTOKEN }} 72 | if: github.event_name == 'workflow_dispatch' 73 | # This condition ensures this step only runs for workflow_dispatch events. 74 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for RISC-V Doc Template 2 | # 3 | # This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 4 | # International License. To view a copy of this license, visit 5 | # http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to 6 | # Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 7 | # 8 | # SPDX-License-Identifier: CC-BY-SA-4.0 9 | # 10 | # Description: 11 | # 12 | # This Makefile is designed to automate the process of building and packaging 13 | # the Doc Template for RISC-V Extensions. 14 | 15 | DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ 16 | riscvintl/riscv-docs-base-container-image:latest 17 | 18 | HEADER_SOURCE := header.adoc 19 | PDF_RESULT := riscv-brs-spec.pdf 20 | 21 | TS_HEADER_SOURCE := brs_ts_header.adoc 22 | TS_PDF_RESULT := riscv-brs-ts.pdf 23 | 24 | ASCIIDOCTOR_PDF := asciidoctor-pdf 25 | OPTIONS := --trace \ 26 | -a compress \ 27 | -a mathematical-format=svg \ 28 | -a pdf-fontsdir=docs-resources/fonts \ 29 | -a pdf-style=docs-resources/themes/riscv-pdf.yml \ 30 | --failure-level=ERROR 31 | REQUIRES := --require=asciidoctor-bibtex \ 32 | --require=asciidoctor-diagram \ 33 | --require=asciidoctor-mathematical 34 | 35 | .PHONY: all build clean build-container build-no-container 36 | 37 | all: build 38 | 39 | build: 40 | @echo "Checking if Docker is available..." 41 | @if command -v docker >/dev/null 2>&1 ; then \ 42 | echo "Docker is available, building inside Docker container..."; \ 43 | $(MAKE) build-container; \ 44 | else \ 45 | echo "Docker is not available, building without Docker..."; \ 46 | $(MAKE) build-no-container; \ 47 | fi 48 | 49 | build-container: 50 | @echo "Starting build inside Docker container..." 51 | $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" 52 | $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)" 53 | @echo "Build completed successfully inside Docker container." 54 | 55 | build-no-container: 56 | @echo "Starting build..." 57 | $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) 58 | $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE) 59 | @echo "Build completed successfully." 60 | 61 | clean: 62 | @echo "Cleaning up generated files..." 63 | rm -f $(PDF_RESULT) 64 | @echo "Cleanup completed." 65 | -------------------------------------------------------------------------------- /readme.adoc: -------------------------------------------------------------------------------- 1 | = RISC-V Boot and Runtime Services (BRS) Specification 2 | 3 | The Boot and Runtime Services (BRS) specification provides the software requirements for system vendors and Operating System Vendors (OSVs) to interoperate with one another by providing expectations for the Operating System (OS) to utilize in acts of device discovery, system management, and other rich operations provided in this specification. 4 | 5 | This specification is still a work in progress, based on an earlier draft available at https://docs.google.com/document/d/1X0TSbheEJjRGWhG2nzUnfIl_QcHWSuvd 6 | 7 | = License 8 | 9 | This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). 10 | See the https://github.com/riscv/docs-spec-template/blob/main/LICENSE[LICENSE] file for details. 11 | 12 | = Contributors 13 | 14 | Contributors to this specification are contained in the 15 | https://github.com/riscv-non-isa/riscv-brs/blob/main/contributors.adoc[contributors.adoc] file. 16 | 17 | = Dependencies 18 | 19 | This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on 20 | checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. 21 | 22 | For more information on AsciiDoctor, specification guidelines, or building locally, see the 23 | https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. 24 | 25 | = Cloning the project 26 | 27 | This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] 28 | to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] 29 | to achieve a common look and feel. 30 | 31 | When cloning this repository for the first time, you must either use 32 | `git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result 33 | in the PDF build fail with an error message like the following: 34 | 35 | $ make 36 | asciidoctor-pdf \ 37 | -a toc \ 38 | -a compress \ 39 | -a pdf-style=docs-resources/themes/riscv-pdf.yml \ 40 | -a pdf-fontsdir=docs-resources/fonts \ 41 | --failure-level=ERROR \ 42 | -o profiles.pdf profiles.adoc 43 | asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme 44 | No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts 45 | Use --trace for backtrace 46 | make: *** [Makefile:7: profiles.pdf] Error 1 47 | 48 | = Building the document 49 | 50 | The final specification form of PDF can be generated using the `make` command. 51 | -------------------------------------------------------------------------------- /non-normative/uefi.adoc: -------------------------------------------------------------------------------- 1 | UEFI implementations run in 64-bit S-Mode, VS-Mode or HS-Mode, 2 | depending on whether virtualization is supported or used. 3 | 4 | ==== Privilege Levels 5 | 6 | Different portions of system firmware might target a specific 7 | privilege level. In contrast, UEFI drivers, OS loaders and 8 | pre-boot applications need to operate in supervisor mode (either 9 | (V)S-Mode or HS-Mode), because they are UEFI-compliant executable 10 | images. 11 | 12 | As an implementation choice, a UEFI firmware implementation may 13 | start execution in M-Mode. However it must switch to supervisor 14 | mode as part of initializing boot and runtime services for UEFI 15 | drivers and applications. 16 | 17 | [[uefi-guidance-firmware-update]] 18 | ==== Firmware Update 19 | 20 | `UpdateCapsule()` is only required before `ExitBootServices()` is called. 21 | The `UpdateCapsule()` implementation is expected to be suitable for use by generic firmware update services like fwupd and Windows Update. Both fwupd and Windows Update read the ESRT table to determine what firmware can be updated and use an EFI helper application to call `UpdateCapsule()` before `ExitBootServices()` is called. 22 | 23 | [[uefi-guidance-pcie]] 24 | ==== PCIe 25 | 26 | Every implementation of the `EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL` provides the 27 | correct `Address Translation Offset` field to translate between the hart 28 | MMIO and bus addresses. 29 | 30 | `EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION` structures report resources 31 | produced by the PCIe root bridges, not resources consumed by their 32 | register maps. In the cases where there are unpopulated PCIe slots 33 | behind a root bridge, `EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION` 34 | reports valid resources assigned (e.g. for hot plug), or reports no 35 | resources assigned. 36 | 37 | Firmware MUST always initialize PCIe root complexes, even if booting from non-PCIe devices, 38 | and should not assume the OS knows how to configure root complex hardware (including, 39 | for example, inbound and outbound address translation windows). In fact, ECAM-compatible 40 | PCIe segments are assumed by operating systems to just work as per their hardware 41 | descriptions in ACPI and DT. Furthermore, firmware MUST perform BAR resource assignment, 42 | bridge bus number and window assignments and other reasonable device setting configuration 43 | (e.g. Max Payload Size) and not assume operating systems to be capable of full PCIe 44 | resource configuration, or to expect full reconfiguration to be necessary. 45 | 46 | [[uefi-guidance-rt]] 47 | ==== UEFI Runtime Services 48 | 49 | Systems without an RTC and with an equivalent alternate source for current time, 50 | that is not trivially accessible from a UEFI implementation after the 51 | UEFI boot services are shut down (e.g. network time), can implement `GetTime()` 52 | using the `time` CSR. The time, of course, needs to be synchronized 53 | before the boot services are shut down. -------------------------------------------------------------------------------- /recipes.adoc: -------------------------------------------------------------------------------- 1 | [[recipes]] 2 | == Recipes 3 | 4 | In this context, a recipe is a collection of firmware specification 5 | requirements that hardware, firmware, and software providers can 6 | implement to increase the likelihood that software written to the 7 | recipe will run predictably on all conforming devices. 8 | 9 | The BRS specification defines two recipes: BRS-I (for "Interoperable") 10 | and BRS-B (for "Bespoke"). 11 | 12 | === BRS-I Recipe 13 | 14 | The BRS-I recipe aims to simplify end-user experiences, software 15 | compatibility and OS distribution, by defining a common specification 16 | for boot and runtime interfaces. BRS-I is expected to be used by 17 | general-purpose compute devices such as servers, desktops, laptops and 18 | other devices with industry expectations on silicon vendor, OS and software 19 | ecosystem interoperability. BRS-I enables operating system 20 | providers to build a single *generic* operating system image that can be 21 | *successfully booted* on compliant systems. *Generic* means not requiring 22 | system-specific customizations - only an implementation of BRS-I 23 | requirements. *Successfully boot* means basic system configuration, 24 | sufficient for detecting the need for system-specific drivers and 25 | loading such drivers. 26 | 27 | It is understood that systems will deliver features beyond those covered 28 | by BRS-I. However, software written against a specific version of BRS-I 29 | must run, unaltered, without *anomalous and unexpected behavior* on 30 | systems that include such features and that are compliant to that specific 31 | version of BRS-I. Such behavior, caused by factors entirely unknown to 32 | a generic OS, is hard to diagnose and always results in a terrible user 33 | experience that negatively affects the value of the whole RISC-V 34 | standards-based ecosystem. *Anomalous and unexpected behavior* is taken 35 | to mean system instability and worst-case behavior for non-specialized 36 | workloads, but does not include suboptimal/unoptimized behavior or 37 | missing I/O or accelerator drivers. Any additional firmware features 38 | that cause anomalous and unexpected behavior must be disabled by 39 | default, and only enabled by opt-in. <>. 41 | 42 | .BRS-I Recipe Overview 43 | [width=100%] 44 | [%header, cols="10,10,10,10,10,10"] 45 | |=== 46 | | Profile | UEFI | ACPI | DT | SBI | SMBIOS 47 | | >= RVA20S64 | >= 2.10 | >= 6.6 | optional, >= v0.3 | >= 2.0 | >= 3.7.0 48 | |=== 49 | 50 | === BRS-B Recipe 51 | 52 | BRS-B is intended for cases where only a minimal level of firmware 53 | interaction is mandated, focusing primarily on the boot process. The 54 | BRS-B recipe is the simpler of the two BRS recipes. It is expected to 55 | be used by software that is tailored to specific devices. Examples 56 | include many types of mobile devices, devices with real time response 57 | requirements, or embedded devices running rich operating systems with 58 | custom distributions. 59 | 60 | .BRS-B Recipe Overview 61 | [width=100%] 62 | [%header, cols="10,10,20,20,10,20"] 63 | |=== 64 | | Profile | UEFI | ACPI | DT | SBI | SMBIOS 65 | | >= RVA20S64 | EBBR, >= 2.1.0 cite:[EBBR] | optional, >= 6.6 | optional, >= v0.3 | >= 2.0 | optional, >= 3.7.0 66 | |=== 67 | 68 | Either ACPI or DT may be used to describe hardware to the OS, but never both at the same time. 69 | -------------------------------------------------------------------------------- /brs_ts_intro.adoc: -------------------------------------------------------------------------------- 1 | [[intro]] 2 | 3 | == Introduction 4 | 5 | The RISC-V Boot and Runtime Services Test specification defines a set of tests to 6 | verify if the requirements specified in RISC-V BRS specification are implemented. 7 | The tests specified in this specification are not intended to exhaustively verify 8 | the implementation. In most cases the tests only check for existence of the feature. 9 | Future versions of this specification may include more exhaustive tests. 10 | 11 | The tests in this specification are documented use the following format: 12 | 13 | [width=100%] 14 | [%header, cols="8,20"] 15 | |=== 16 | | TEST_ID# ^| Test algorithm 17 | | AB_CAT_NNN_MMM a| The `CAT_NNN` identifies a requirement in the RISC-V BRS 18 | specification. Each requirement is associated with one or 19 | more tests identified by `MMM`. The test IDs are prefixed 20 | with two character prefix - `AB`. + 21 | + 22 | If character in position `A` is `M` then the test is for a 23 | requirement that MUST be supported and this test MUST pass. 24 | If character in position `A` is `O` then the test is for a 25 | requirement that SHOULD or MAY be supported; such tests may 26 | be skipped if the requirement is not implemented. The tests 27 | record if optional features were present in the test output 28 | log. + 29 | + 30 | The character in position `B` indicates the nature of the 31 | test. If this character is `F` then the test exercises some 32 | or all of the functionality associated with the feature. If 33 | the character is `E` then the test determines for evidence 34 | that the feature is implemented (e.g., check ACPI tables) 35 | but does not functionally exercise the feature. 36 | 37 | |=== 38 | 39 | This specification groups the tests in the following broad categories: 40 | 41 | * Hart 42 | * SBI 43 | * UEFI 44 | * ACPI 45 | * SMBIOS 46 | 47 | === Glossary 48 | 49 | Most terminology has the standard RISC-V meaning. This table captures other 50 | terms used in the document. 51 | 52 | .Terms and definitions 53 | [width=90%] 54 | [%header, cols="5,20"] 55 | |=== 56 | | Term ^| Definition 57 | | ACPI | Advanced Configuration and Power Interface cite:[ACPI]. 58 | | BRS | RISC-V Boot and Runtime Services Specification. 59 | | BRS-I | Boot and Runtime Services recipe targeting interoperation across different software suppliers. 60 | | BRS-B | Boot and Runtime Services recipe using a bespoke solution. 61 | | DT | DeviceTree cite:[DT]. 62 | | EBBR | Embedded Base Boot Requirements Specification cite:[EBBR]. 63 | | OSV | Operating System Vendor. 64 | | OS | Operating System or Hypervisor. 65 | | Profile | RISC-V Profile cite:[Profile]. 66 | | SBI | RISC-V Supervisor Binary Interface Specification cite:[SBI]. 67 | | SMBIOS | System Management BIOS (SMBIOS) Reference Specification cite:[SMBIOS]. 68 | | SoC | System on a chip, a combination of processor and supporting chipset logic in single package. 69 | | UEFI | Unified Extensible Firmware Interface Specification cite:[UEFI]. 70 | |=== 71 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contribution Guidelines 2 | 3 | As an open-source project, we appreciate and encourage community members to submit patches directly to the project. To maintain a well-organized development environment, we have established standards and methods for submitting changes. This document outlines the process for submitting patches to the project, ensuring that your contribution is swiftly incorporated into the codebase. 4 | 5 | # Licensing 6 | 7 | Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author. 8 | 9 | This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository. 10 | 11 | Licensing defines the rights granted to you as an author by the copyright holder. It is essential for contributors to fully understand and accept these licensing rights. In some cases, the copyright holder may not be the contributor, such as when the contributor is working on behalf of a company. 12 | 13 | # Developer Certificate of Origin (DCO) 14 | To uphold licensing criteria and demonstrate good faith, this project mandates adherence to the Developer Certificate of Origin (DCO) process. 15 | 16 | The DCO is an attestation appended to every contribution from each author. In the commit message of the contribution (explained in greater detail later in this document), the author adds a Signed-off-by statement, thereby accepting the DCO. 17 | 18 | When an author submits a patch, they affirm that they possess the right to submit the patch under the designated license. The DCO agreement is displayed below and at https://developercertificate.org. 19 | 20 | 21 | Developer's Certificate of Origin 1.1 22 | 23 | By making a contribution to this project, I certify that: 24 | 25 | (a) The contribution was created in whole or in part by me and I 26 | have the right to submit it under the open source license 27 | indicated in the file; or 28 | 29 | (b) The contribution is based upon previous work that, to the best 30 | of my knowledge, is covered under an appropriate open source 31 | license and I have the right under that license to submit that 32 | work with modifications, whether created in whole or in part 33 | by me, under the same open source license (unless I am 34 | permitted to submit under a different license), as indicated 35 | in the file; or 36 | 37 | (c) The contribution was provided directly to me by some other 38 | person who certified (a), (b), or (c), and I have not modified 39 | it. 40 | 41 | (d) I understand and agree that this project and the contribution 42 | are public and that a record of the contribution (including all 43 | personal information I submit with it, including my sign-off) is 44 | maintained indefinitely and may be redistributed consistent with 45 | this project or the open source license(s) involved. 46 | 47 | # DCO Sign-Off Methods 48 | The DCO necessitates the inclusion of a sign-off message in the following format for each commit within the pull request: 49 | ``` 50 | Signed-off-by: Stephano Cetola 51 | ``` 52 | Please use your real name in the sign-off message. 53 | 54 | You can manually add the DCO text to your commit body or include either -s or --signoff in your standard Git commit commands. If you forget to incorporate the sign-off, you can also amend a previous commit with the sign-off by executing git commit --amend -s. If you have already pushed your changes to GitHub, you will need to force push your branch afterward using git push -f. 55 | 56 | Note: 57 | 58 | Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message. 59 | -------------------------------------------------------------------------------- /brs.bib: -------------------------------------------------------------------------------- 1 | @electronic{EBBR, 2 | title = {Embedded Base Boot Requirements Specification 2.1.0}, 3 | url = {https://github.com/ARM-software/ebbr/releases/download/v2.1.0/ebbr-v2.1.0.pdf} 4 | } 5 | @electronic{ACPI, 6 | title = {Advanced Configuration and Power Interface Specification 6.6}, 7 | url = {https://uefi.org/specifications} 8 | } 9 | @electronic{UEFI, 10 | title = {Unified Extensible Firmware Interface Specification 2.11}, 11 | url = {https://uefi.org/specifications} 12 | } 13 | @electronic{UEFI-PI, 14 | title = {UEFI Platform Initialization Specification 1.9}, 15 | url = {https://uefi.org/specifications} 16 | } 17 | @electronic{SMBIOS, 18 | title = {System Management BIOS (SMBIOS) Reference Specification 3.7.0}, 19 | url = {https://www.dmtf.org/standards/smbios} 20 | } 21 | @electronic{DT, 22 | title = {DeviceTree}, 23 | url = {https://www.devicetree.org/} 24 | } 25 | @electronic{DSD, 26 | title = {_DSD (Device Specific Data) Implementation Guide}, 27 | url = {https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf} 28 | } 29 | @electronic{SBI, 30 | title = {RISC-V Supervisor Binary Interface Specification}, 31 | url = {https://github.com/riscv-non-isa/riscv-sbi-doc} 32 | } 33 | @electronic{SPCR, 34 | title = {Serial Port Console Redirection Table (SPCR)}, 35 | url = {https://learn.microsoft.com/en-us/windows-hardware/drivers/serports/serial-port-console-redirection-table} 36 | } 37 | @electronic{PCIFW, 38 | title = {PCI Firmware Specification Revision 3.3}, 39 | url = {https://members.pcisig.com/wg/PCI-SIG/document/folder/862} 40 | } 41 | @electronic{PRIV, 42 | title = {RISC-V Instruction Set Manual, Volume II: Privileged Architecture}, 43 | url = {https://github.com/riscv/riscv-isa-manual}, 44 | } 45 | @electronic{Profile, 46 | title = {RISC-V Profile}, 47 | url = {https://github.com/riscv/riscv-profiles} 48 | } 49 | @electronic{FFH, 50 | title = {RISC-V Functional Fixed Hardware Specification}, 51 | url = {https://github.com/riscv-non-isa/riscv-acpi-ffh} 52 | } 53 | @electronic{TcgEfiPlat, 54 | title = {TCG EFI Platform Specification}, 55 | url = {https://trustedcomputinggroup.org/resource/tcg-efi-platform-specification/}, 56 | } 57 | @electronic{TcgAcpi, 58 | title = {TCG ACPI Specification}, 59 | url = {https://trustedcomputinggroup.org/resource/tcg-acpi-specification/}, 60 | } 61 | @electronic{MSUefiCaRequirements, 62 | title = {UEFI memory mitigations}, 63 | url = {https://learn.microsoft.com/en-us/windows-hardware/drivers/bringup/uefi-ca-memory-mitigation-requirements}, 64 | } 65 | @electronic{RFC_2119, 66 | title = {Key words for use in RFCs to Indicate Requirement Levels}, 67 | url = {https://datatracker.ietf.org/doc/html/rfc2119} 68 | } 69 | @electronic{PCI, 70 | title = {PCI Express® Base Specification Revision 6.0}, 71 | url = {https://pcisig.com/pci-express-6.0-specification}, 72 | year = {} 73 | } 74 | @electronic{Sstc, 75 | title = {RISC-V "stimecmp / vstimecmp" Extension}, 76 | url = {https://github.com/riscv/riscv-time-compare}, 77 | year = {2021} 78 | } 79 | @electronic{Aia, 80 | title = {The RISC-V Advanced Interrupt Architecture}, 81 | url = {https://github.com/riscv/riscv-aia}, 82 | year = {2023} 83 | } 84 | @electronic{Sscsrind, 85 | title = {RISC-V Indirect CSR Access (Smcsrind/Sscsrind)}, 86 | url = {https://github.com/riscv/riscv-indirect-csr-access}, 87 | year = {2023} 88 | } 89 | @electronic{Smcdeleg, 90 | title = {RISC-V Supervisor Counter Delegation Specification (Smcdeleg/Ssccfg)}, 91 | url = {https://github.com/riscv/riscv-smcdeleg-ssccfg}, 92 | year = {2024} 93 | } 94 | @electronic{PerfAnalysis, 95 | title = {SIG: Performance Analysis}, 96 | url = {https://lists.riscv.org/g/sig-perf-analysis}, 97 | year = {2024} 98 | } 99 | @electronic{RPMI, 100 | title = {RISC-V Platform Management Interface Specification}, 101 | url = {https://github.com/riscv-non-isa/riscv-rpmi} 102 | } 103 | -------------------------------------------------------------------------------- /intro.adoc: -------------------------------------------------------------------------------- 1 | [[intro]] 2 | == Introduction 3 | 4 | The _RISC-V Boot and Runtime Services Specification_ (BRS) defines a standardized set of software capabilities, that portable system software, such as operating systems and hypervisors, can rely on being present in an implementation to utilize in acts of device discovery, OS boot and hand-off, system management, and other operations. 5 | 6 | The BRS specification is targeting systems that implement S/U privilege modes, and optionally the HS privilege mode. This is the expected deployment for OSVs and system vendors in a typical ecosystem covering client systems up through server systems where software is provided by different vendors than the system vendor. 7 | 8 | This specification standardizes the requirements for software interfaces and capabilities by building on top of relevant industry and ratified RISC-V standards. 9 | 10 | === Releases 11 | 12 | It is expected that the BRS will periodically release a new specification. The determination of a new release will be based on the evaluation of significant changes to its underlying dependencies. 13 | 14 | === Approach to Solutions 15 | 16 | The BRS focuses on two solutions in the form of what is deemed a recipe. Each recipe contains the requirements needed to fulfill each solution. The requirements of each recipe will be marked accordingly with a unique identifier. The recipes are BRS-I (Interoperable) and BRS-B (Bespoke). 17 | 18 | === Testing and Conformance 19 | 20 | To be compliant with this specification, an implementation MUST support all mandatory rules and MUST support the listed versions of the specifications. This standard set of capabilities MAY be extended by a specific implementation with additional standard or custom capabilities, including compatible later versions of listed standard specifications. Portable system software MUST support the specified mandatory capabilities to be compliant with this specification. 21 | 22 | The rules in this specification use the following format: 23 | 24 | [width=100%] 25 | [%header, cols="5,20"] 26 | |=== 27 | | ID# ^| Rule 28 | | `CAT_NNN` | The `CAT` is a category prefix that logically groups the 29 | rules and is followed by 3 digits - `NNN` - assigning a 30 | numeric ID to the rule. + 31 | + 32 | The rules use the key words "MUST", "MUST NOT", 33 | "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 34 | "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" that are 35 | to be interpreted as described in RFC 2119 cite:[RFC_2119] when, 36 | and only when, they appear in all capitals, as shown here. When 37 | these words are not capitalized, they have their normal English 38 | meanings. 39 | 2+| _A rule or a group of rules may be followed by non-normative 40 | text providing context or justification for the rule. The 41 | non-normative text may also be used to reference sources that are the 42 | origin of the rule._ 43 | |=== 44 | 45 | === Glossary 46 | 47 | Most terminology has the standard RISC-V meaning. This table captures other terms used in the document. Terms in the document prefixed by *PCIe* have the meaning defined in the _PCI Express Base Specification_ cite:[PCI] (even if they are not in this table). 48 | 49 | .Terms and definitions 50 | [width=90%] 51 | [%header, cols="5,20"] 52 | |=== 53 | | Term ^| Definition 54 | | ACPI | _Advanced Configuration and Power Interface Specification_ cite:[ACPI]. 55 | | BRS | _RISC-V Boot and Runtime Services Specification_. This document. 56 | | BRS-I | Boot and Runtime Services recipe targeting interoperation across different software suppliers. 57 | | BRS-B | Boot and Runtime Services recipe using a bespoke solution. 58 | | DT | _Device Tree_ cite:[DT]. 59 | | EBBR | _Embedded Base Boot Requirements Specification_ cite:[EBBR]. 60 | | OSV | Operating System Vendor. 61 | | OS | Operating System or Hypervisor. 62 | | Profile | _RISC-V Profile_ cite:[Profile]. 63 | | RPMI | _RISC-V Platform Management Interface_ cite:[RPMI]. 64 | | RVI | RISC-V International. 65 | | SBI | _RISC-V Supervisor Binary Interface Specification_ cite:[SBI]. 66 | | SMBIOS | _System Management BIOS (SMBIOS) Reference Specification_ cite:[SMBIOS]. 67 | | SoC | System on a chip, a combination of processor and supporting chipset logic in single package. 68 | | UEFI | _Unified Extensible Firmware Interface Specification_ cite:[UEFI]. 69 | |=== 70 | -------------------------------------------------------------------------------- /smbios.adoc: -------------------------------------------------------------------------------- 1 | [[smbios]] 2 | == BRS-I SMBIOS Requirements 3 | 4 | The _System Management BIOS (SMBIOS) Reference Specification_ defines a standard format for presenting management information about an implementation, mostly focusing on hardware components. 5 | 6 | This section defines the BRS-I mandatory and optional SMBIOS requirements 7 | on top of existing cite:[SMBIOS] specification requirements. Additional 8 | non-normative guidance may be found in the <> section. 10 | 11 | IMPORTANT: All content in this section is optional and recommended for BRS-B. 12 | 13 | NOTE: The structures and fields in this section are defined in a manner consistent with the DMTF specification language (cite:[SMBIOS]). 14 | 15 | [width=100%] 16 | [%header, cols="5,25"] 17 | |=== 18 | | ID# ^| Rule 19 | | `SMBIOS_010` | A Baseboard/Module Information (Type 02) structure SHOULD be implemented. 20 | 2+|_This relaxes the SMBIOS specification requirement._ 21 | | `SMBIOS_020` | Processor Information (Type 04) structures, meeting the additional <> clarifications, MUST be implemented. 22 | 2+|_This supersedes the RISC-V specific language in the SMBIOS specification (cite:[SMBIOS], Section 7.5.3.5)._ 23 | | `SMBIOS_030` | Port Connector Information (Type 08) structures SHOULD be implemented. 24 | | `SMBIOS_040` | BIOS Language Information (Type 13) structures SHOULD be implemented. 25 | | `SMBIOS_050` | An IPMI Device Information (Type 38) structure MUST be implemented, when an IPMIv1.0 host interface is present. 26 | | `SMBIOS_060` | System Power Supply (Type 39) structures SHOULD be implemented. 27 | | `SMBIOS_070` | Onboard Devices Extended Information (Type 41) structures SHOULD be implemented. 28 | | `SMBIOS_080` | A Redfish Host Interface (Type 42) structure MUST be implemented, when a Redfish host interface is present. 29 | | `SMBIOS_090` | A TPM Device (Type 43) structure MUST be implemented, when a TPM is present. 30 | | `SMBIOS_100` | Processor Additional Information (Type 44) structures MUST be implemented. 31 | 2+| _See the <>_. 32 | | `SMBIOS_110` | Firmware Inventory Information (Type 45) structures SHOULD be implemented. 33 | |=== 34 | 35 | [[smbios-type04]] 36 | === Type 04 Processor Information 37 | 38 | IMPORTANT: The information in this section supersedes the definitions in (cite:[SMBIOS], Section 7.5.3.4). 39 | 40 | A processor is a grouping of harts in a physical package. In modern designs this MAY mean an SoC. 41 | 42 | For RISC-V class CPUs, the `Processor ID` field contains two `DWORD`-formatted values describing 43 | the overall physical processor package vendor and version. For some implementations 44 | this may also be known as the SoC ID. The first `DWORD` (offsets 08h-0Bh) is the JEP-106 code for 45 | the vendor, where bits 6:0 is the ID without the parity and bits 31:7 represent the number of continuation codes. The second `DWORD` (offsets 0Ch-0Fh) reflects vendor-specific part versioning. 46 | 47 | For hart-specific vendor and revision information, please see <>. 48 | 49 | [[smbios-type44]] 50 | === Type 44 Processor-Specific Data 51 | 52 | The processor-specific data structure fields are defined to follow the standard Processor-Specific Block fields (cite:[SMBIOS], Section 7.45.1). 53 | 54 | The structure is valid for processors declared with `Processor Type` 07h (64-bit RISC-V) only. 55 | 56 | A Type 44 structure needs to be provided for every hart meeting <> requirements. 57 | 58 | [cols="2,2,3,2,2,4", width=95%, align="center", options="header"] 59 | |=== 60 | | Offset | Version | Name | Length | Value | Description 61 | | 00h| 0100h| `Revision`|`WORD`|Varies|See <>. 62 | | 02h| 0100h| `Hart ID`| `QWORD`| Varies| The ID of this RISC-V hart. 63 | | 0Ah| 0100h| `Machine Vendor ID` | `QWORD` | Varies| The vendor ID of this 64 | RISC-V hart. 65 | | 12h| 0100h| `Machine Architecture ID` | `QWORD` | Varies| Base 66 | microarchitecture of the hart. Value of 0 is possible to indicate the field is 67 | not implemented. The combination of `Machine Architecture ID` and `Machine Vendor 68 | ID` should uniquely identify the type of hart microarchitecture that is implemented. 69 | | 1Ah| 0100h| `Machine Implementation ID` | `QWORD`| Varies| Unique encoding 70 | of the version of the processor implementation. 71 | |=== 72 | 73 | [[smbios-psd-ver]] 74 | === Processor-Specific Data Structure Versioning 75 | 76 | The processor-specific data structure begins with a revision field to allow for future extensibility in a backwards-compatible manner. 77 | 78 | The minor revision is to be incremented anytime new fields are added in a backwards-compatible manner. The major revision is to be incremented on backwards-incompatible changes. 79 | 80 | [cols="1,1,1,1,3", width=95%, align="center", options="header"] 81 | |=== 82 | | Version | Bits 15:8+ 83 | Major revision 84 | | Bits 7:0+ 85 | Minor revision 86 | | Combined | Description 87 | | v1.0 | 01h | 00h | 0100h | First BRS-defined definition 88 | |=== 89 | -------------------------------------------------------------------------------- /acpi.adoc: -------------------------------------------------------------------------------- 1 | [[acpi]] 2 | == BRS-I ACPI Requirements 3 | 4 | The _Advanced Configuration and Power Interface Specification_ provides the OS-centric view of system configuration, various hardware resources, events and power management. 5 | 6 | This section defines the BRS-I mandatory and optional ACPI 7 | requirements on top of existing ACPI cite:[ACPI] and UEFI cite:[UEFI] 8 | specification requirements. Additional non-normative guidance may be 9 | found in the <> 10 | section. 11 | 12 | IMPORTANT: All content in this section is optional and recommended for BRS-B. 13 | 14 | [width=100%] 15 | [%header, cols="5,25"] 16 | |=== 17 | | ID# ^| Rule 18 | | [[acpi-64bit-clean]]`ACPI_010` a| Be 64-bits clean. 19 | 20 | * RSDT MUST NOT be implemented, with `RsdtAddress` in RSDP set to 0. 21 | * 32-bit address fields MUST be 0. 22 | 2+| _<>._ 23 | | [[acpi-hw-reduced]]`ACPI_020` a| MUST implement the hardware-reduced ACPI mode (no FACS table). 24 | 2+| _<>._ 25 | | [[acpi-pptt]]`ACPI_030` | The Processor Properties Table (PPTT) MUST be implemented, even on systems with a simple hart topology. 26 | | [[acpi-mcfg]]`ACPI_040` | The PCI Memory-mapped Configuration Space (MCFG) table MUST NOT be present if it violates cite:[PCIFW]. 27 | 2+| _Only compatible PCIe segments, exposed via ECAM (Enhanced Configuration Access Mechanism), may be described in the MCFG. The MCFG MUST NOT require vendor-specific OS support. See PCI Services (cite:[ACPI], Section 4) for more ACPI requirements relating to PCIe support. <>._ 28 | | `ACPI_050` | A Serial Port Console Redirection Table cite:[SPCR] MUST be present on systems, where the graphics hardware is not present or not made 29 | available to an OS loader via the standard `UEFI EFI_GRAPHICS_OUTPUT_PROTOCOL` interface. 30 | 2+|_In these cases, the table provides essential configuration for an early OS boot console._ 31 | | [[acpi-spcr]]`ACPI_060` a| An SPCR table, if present, MUST meet the following requirements: 32 | 33 | * Revision 4 or later of SPCR. 34 | * For NS16550-compatible UARTs: 35 | ** Use `Interface Type` 0x12 (16550-compatible with parameters defined in Generic Address Structure). 36 | ** There MUST be a matching AML device object with `_HID` (Hardware ID) or `_CID` (Compatible ID) `RSCV0003`. 37 | 2+| _See <>_. 38 | |=== 39 | 40 | [[acpi-aml]] 41 | === BRS-I ACPI Methods and Objects 42 | 43 | This section lists additional requirements for ACPI methods and 44 | objects. 45 | 46 | <>. 47 | 48 | [width=100%] 49 | [%header, cols="5,25"] 50 | |=== 51 | | ID# ^| Rule 52 | | `AML_010` | The Current Resource Setting (_CRS) device method for a PCIe Root Complex SHOULD NOT return any descriptors for I/O ranges (such as created by ASL macros WordIO, DWordIO, QWordIO, IO, FixedIO, or ExtendedIO). 53 | 2+| _Legacy PCI I/O BARs are uncommon in modern PCIe devices and support for PCI I/O space may complicate configuration of PCIe Root Complex hardware in a compliant manner._ 54 | | `AML_020` | The Possible Resource Settings (`_PRS`) and Set Resource Settings (`_SRS`) device method SHOULD NOT be implemented. 55 | 2+| _ACPI resource descriptors are typically used to describe devices with fixed I/O regions that do not change. Flexible resource assignment is not supported by most modern ACPI OSes._ 56 | | `AML_030` | Per-hart device objects MUST be defined under `\_SB` (System Bus) namespace and not in the deprecated `\_PR` (Processors) namespace. 57 | | `AML_040` | Systems supporting OS-directed hart performance control and power management MUST expose these via Collaborative Processor Performance Control (CPPC, cite:[ACPI] Section 8.4.6). 58 | | `AML_050` | Processor idle states MUST be described using Low Power Idle (`_LPI`, cite:[ACPI] Section 8.4.3). 59 | | [[acpi-tad]] `AML_060` | Systems with a Real-Time Clock on an OS-managed bus (e.g. I2C, subject to arbitration issues due to access to the bus by the OS) MUST implement the Time and Alarm Device (TAD) with functioning `_GRT` and `_SRT` methods, and the `_GCP` method returning bit 2 set (i.e. get/set real time features implemented). 60 | 2+| _Also see <>_. 61 | | `AML_070` | Systems implementing a TAD MUST be functional without additional system-specific OS drivers. 62 | 2+| _In situations where the Time and Alarm Device (TAD) depends on a 63 | vendor-specific OS driver for correct function (SPI, I2C, etc), the TAD MUST 64 | be functional if the OS driver is not loaded. That is, when a dependent 65 | driver is loaded, an AML method switches further accesses to go 66 | through the driver-backed `OperationRegion`._ 67 | | [[acpi-irq-gsb]] `AML_080` | PLIC and APLIC device objects MUST support 68 | the Global System Interrupt Base (`_GSB`, cite:[ACPI] Section 6.2.7) object. 69 | <>. 70 | | `AML_090` | UART device objects with ID `RSCV0003` MUST implement <>. 71 | | [[acpi-namespace-dev]]`AML_100` | PLIC/APLIC namespace devices MUST 72 | be present in the ACPI namespace whenever corresponding MADT entries are 73 | present. <>. 74 | 2+| _Also see <> and <>_. 75 | |=== 76 | 77 | include::acpi-id.adoc[] 78 | include::acpi-prop.adoc[] 79 | -------------------------------------------------------------------------------- /brs_tests.adoc: -------------------------------------------------------------------------------- 1 | == BRS Test Specification 2 | 3 | === Hart Requirements 4 | 5 | [width=100%] 6 | [%header, cols="8,25"] 7 | |=== 8 | | ID# ^| Algorithm 9 | | `ME_HR_010_010` a| For each application processor hart: 10 | 11 | . Determine the ISA string for that hart from 12 | .. RHCT table if ACPI was used 13 | .. riscv,isa-base and riscv,isa-extensions nodes if DT was used 14 | . Parse the ISA string and verify that all mandatory extensions 15 | in `RVA20S64` profile cite:[Profile] are supported. 16 | . Verify that the ISA string matches that of hart 0. 17 | . Report the ISA string of hart 0 into the test output log. 18 | |=== 19 | 20 | <<< 21 | 22 | === SBI Requirements 23 | 24 | [width=100%] 25 | [%header, cols="8,25"] 26 | |=== 27 | | ID# ^| Algorithm 28 | | `ME_SBI_010_010` | . Get the SBI version by sbi_get_sbi_spec_version(). 29 | . Verify that the version is v2.0 or later. 30 | . Report the version into the test output log. 31 | | `ME_SBI_020_010` | . See `ME_SBI_010_010`. 32 | . Probe the presence of HSM extension by sbi_probe_extension(). 33 | . Verify that the result is true. 34 | | `OE_SBI_030_010` | . If Sstc extension was present(See `ME_HR_010_010`) 35 | .. Report Sstc was present and Skip the test. 36 | . Else 37 | .. Probe the presence of TIME extension by sbi_probe_extension(). 38 | .. Verify that the result is true. 39 | | `OE_SBI_040_010` | . If Ssaia extension was present(See `ME_HR_010_010`) 40 | .. Report Ssaia was present and Skip the test. 41 | . Else 42 | .. Probe the presence of sPI extension by sbi_probe_extension(). 43 | .. Verify that the result is true. 44 | | `OE_SBI_050_010` | . If Ssaia extension was present(See `ME_HR_010_010`) 45 | .. Report Ssaia was present and Skip the test. 46 | . Else 47 | .. Probe the presence of RFNC extension by sbi_probe_extension(). 48 | .. Verify that the result is true. 49 | | `OE_SBI_060_010` | . If Smcsrind,Sscsrind,Smcdeleg,Ssccfg extensions 50 | were present(See `ME_HR_010_010`). 51 | .. Report Smcsrind,Sscsrind,Smcdeleg,Ssccfg was present and 52 | Skip the test. 53 | . Else 54 | .. Probe the presence of PMU extension by sbi_probe_extension(). 55 | .. Verify that the result is true. 56 | | `OE_SBI_070_010` | . If ACPI is used and the ACPI SPCR table references Interface Type 0x15 57 | .. Probe the presence of DBCN extension by sbi_probe_extension(). 58 | .. Verify that the result is true. 59 | . Else 60 | .. Report DBCN is not mandatory in this configuration and skip the test. 61 | |=== 62 | 63 | <<< 64 | 65 | === BRS-I UEFI Requirements 66 | 67 | [width=100%] 68 | [%header, cols="8,25"] 69 | |=== 70 | | ID# ^| Algorithm 71 | | `ME_UEFI_010_010` | _FIXME_. 72 | | `ME_UEFI_020_010` | _FIXME_. 73 | | `ME_UEFI_030_010` | _FIXME_. 74 | | `OE_UEFI_040_010` | _FIXME_. 75 | | `OE_UEFI_050_010` | _FIXME_. 76 | | `ME_UEFI_060_010` | _FIXME_. 77 | | `ME_UEFI_070_010` | _FIXME_. 78 | | `ME_UEFI_070_010` | _FIXME_. 79 | |=== 80 | 81 | <<< 82 | 83 | ==== BRS-I UEFI Security Requirements 84 | 85 | [width=100%] 86 | [%header, cols="8,25"] 87 | |=== 88 | | ID# ^| Algorithm 89 | | `OE_USEC_010_010` | _FIXME_. 90 | | `OE_USEC_020_010` | _FIXME_. 91 | | `OE_USEC_030_010` | _FIXME_. 92 | | `OE_USEC_040_010` | _FIXME_. 93 | | `OE_USEC_050_010` | _FIXME_. 94 | |=== 95 | 96 | <<< 97 | 98 | ==== BRS-I UEFI IO Requirements 99 | 100 | [width=100%] 101 | [%header, cols="8,25"] 102 | |=== 103 | | ID# ^| Algorithm 104 | | `OE_UIO_010_010` | _FIXME_. 105 | | `OE_UIO_020_010` | _FIXME_. 106 | |=== 107 | 108 | <<< 109 | 110 | ==== BRS-I UEFI Runtime Service Requirements 111 | 112 | [width=100%] 113 | [%header, cols="8,25"] 114 | |=== 115 | | ID# ^| Algorithm 116 | | `OE_URT_010_010` | _FIXME_. 117 | | `OE_URT_020_010` | _FIXME_. 118 | | `ME_URT_030_010` | _FIXME_. 119 | | `ME_URT_040_010` | _FIXME_. 120 | | `ME_URT_050_010` | _FIXME_. 121 | |=== 122 | 123 | <<< 124 | 125 | ==== BRS-I UEFI Firmware Update Requirements 126 | 127 | [width=100%] 128 | [%header, cols="8,25"] 129 | |=== 130 | | ID# ^| Algorithm 131 | | `OE_UFU_010_010` | _FIXME_. 132 | | `OE_UFU_020_010` | _FIXME_. 133 | | `OE_UFU_030_010` | _FIXME_. 134 | | `OE_UFU_040_010` | _FIXME_. 135 | |=== 136 | 137 | <<< 138 | 139 | === BRS-I ACPI Requirements 140 | 141 | [width=100%] 142 | [%header, cols="8,25"] 143 | |=== 144 | | ID# ^| Algorithm 145 | | `ME_ACPI_010_010` | _FIXME_. 146 | | `ME_ACPI_020_010` | _FIXME_. 147 | | `ME_ACPI_030_010` | _FIXME_. 148 | | `OE_ACPI_040_010` | _FIXME_. 149 | | `OE_ACPI_050_010` | _FIXME_. 150 | | `OE_ACPI_060_010` | _FIXME_. 151 | |=== 152 | 153 | <<< 154 | 155 | ==== BRS-I ACPI Methods and Objects Requirements 156 | 157 | [width=100%] 158 | [%header, cols="8,25"] 159 | |=== 160 | | ID# ^| Algorithm 161 | | `ME_AML_010_010` | _FIXME_. 162 | | `OE_AML_020_010` | _FIXME_. 163 | | `OE_AML_030_010` | _FIXME_. 164 | | `ME_AML_040_010` | _FIXME_. 165 | | `OE_AML_050_010` | _FIXME_. 166 | | `ME_AML_060_010` | _FIXME_. 167 | | `OE_AML_070_010` | _FIXME_. 168 | | `OE_AML_080_010` | _FIXME_. 169 | | `ME_AML_090_010` | _FIXME_. 170 | | `ME_AML_100_010` | _FIXME_. 171 | |=== 172 | 173 | <<< 174 | 175 | === SMBIOS Requirements 176 | 177 | [width=100%] 178 | [%header, cols="8,25"] 179 | |=== 180 | | ID# ^| Algorithm 181 | | `OE_SMBIOS_010_010` | _FIXME_ 182 | | `ME_SMBIOS_020_010` | _FIXME_ 183 | | `OE_SMBIOS_030_010` | _FIXME_ 184 | | `OE_SMBIOS_040_010` | _FIXME_ 185 | | `OE_SMBIOS_050_010` | _FIXME_ 186 | | `OE_SMBIOS_060_010` | _FIXME_ 187 | | `OE_SMBIOS_070_010` | _FIXME_ 188 | | `OE_SMBIOS_080_010` | _FIXME_ 189 | | `OE_SMBIOS_090_010` | _FIXME_ 190 | | `ME_SMBIOS_100_010` | _FIXME_ 191 | | `OE_SMBIOS_110_010` | _FIXME_ 192 | |=== 193 | 194 | <<< 195 | -------------------------------------------------------------------------------- /uefi.adoc: -------------------------------------------------------------------------------- 1 | [[uefi]] 2 | == BRS-I UEFI Requirements 3 | 4 | The _Unified Extensible Firmware Interface Specification_ (UEFI) describes the interface between the OS and the supervisor-mode firmware. 5 | 6 | This section defines the BRS-I mandatory and optional UEFI 7 | rules on top of existing cite:[UEFI] specification 8 | requirements. Additional non-normative guidance may be found in the 9 | <> section. 10 | 11 | IMPORTANT: All content in this section is optional and recommended for BRS-B. 12 | 13 | [width=100%] 14 | [%header, cols="5,25"] 15 | |=== 16 | | ID# ^| Rule 17 | | `UEFI_010` | MUST implement a 64-bit UEFI firmware. 18 | | `UEFI_020` | MUST meet the 3rd Party UEFI Certificate Authority (CA) requirements on UEFI memory mitigations cite:[MSUefiCaRequirements]. 19 | | `UEFI_030` a| MUST meet the following memory map rules: 20 | 21 | * The default memory space attribute is `EFI_MEMORY_WB`. 22 | * Paged virtual-memory scheme MUST be configured by the firmware with identity mapping and MUST support `EFI_MEMORY_ATTRIBUTE_PROTOCOL` protocol. 23 | * Only use `EfiRuntimeServicesData` memory type for describing any SMBIOS data structures. 24 | 2+| _Paged virtual memory scheme is required for platform protection use cases before handing off to the OS._ 25 | | `UEFI_040` | An implementation MAY comply with the _UEFI Platform Initialization Specification_ cite:[UEFI-PI]. 26 | | `UEFI_050` | All hart manipulation internal to a firmware implementation SHOULD be done before completion of the `EFI_EVENT_GROUP_READY_TO_BOOT` event. Firmware MUST place all secondary harts in an offline state before completion of the EFI_EVENT_GROUP_READY_TO_BOOT event. 27 | 2+| _This ensures an OS loader is entered with an OS-compatible state for all harts.The OS loader and/or the OS may resume the secondary harts, if required, as part of their boot and join sequence._ 28 | | `UEFI_060` | The implementation MUST declare the `EFI_CONFORMANCE_PROFILES_UEFI_SPEC_GUID` conformance profile. 29 | 2+| _The `EFI_CONFORMANCE_PROFILES_UEFI_SPEC_GUID` conformance profile MUST be declared, as the BRS requirements are a superset of UEFI cite:[UEFI] (Section 2.6)._ 30 | | `UEFI_070` | The implementation MUST declare the `EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID` conformance profile `({ 0x05453310, 0x0545, 0x0545, { 0x05, 0x45, 0x33, 0x05, 0x45, 0x33, 0x05, 0x45 }})`. 31 | 2+| _Only a system fully compliant to the requirements in this section MUST declare the `EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID` conformance profile._ 32 | | `UEFI_080` | A Device Tree MUST only be exposed to the OS if no actual hardware description is included in the DT. 33 | 2+|_Such a "dummy" DT could be installed by firmware, as a UEFI configuration table entry of type `EFI_DTB_TABLE_GUID`, to provide necessary 34 | hand-off info to an OS, for example, to provide RAM disk information 35 | (e.g. via `/chosen/linux,initrd-start`)._ 36 | |=== 37 | 38 | === BRS-I I/O-specific Requirements 39 | 40 | [width=100%] 41 | [%header, cols="5,25"] 42 | |=== 43 | | ID# ^| Rule 44 | | `UIO_010` | Systems implementing PCIe MUST always initialize all root complex hardware and perform resource assignment for all endpoints and usable hotplug-capable switches in the system, even in a boot scenario from a non-PCIe boot device. 45 | 2+| _This is a stronger requirement than the PCI Firmware Specification firmware/OS device hand-off state (cite:[PCIFW] Section 3.5). <>._ 46 | | `UIO_020` | Systems implementing `EFI_GRAPHICS_OUTPUT_PROTOCOL` SHOULD configure the frame buffer to be directly accessible. 47 | 2+| _That is, `EFI_GRAPHICS_PIXEL_FORMAT` is not `PixelBltOnly` and `FrameBufferBase` is reported as a valid hart memory-mapped I/O address._ 48 | |=== 49 | 50 | [[uefi-rt]] 51 | === BRS-I UEFI Runtime Services 52 | 53 | [width=100%] 54 | [%header, cols="5,25"] 55 | |=== 56 | | ID# ^| Rule 57 | | `URT_010` a| Systems without a Real-Time Clock (RTC), but with an equivalent alternate source for the current time, MUST meet the following requirements: 58 | 59 | * `GetTime()` MUST be implemented. 60 | * `SetTime()` MUST return `EFI_UNSUPPORTED`, and be appropriately described in the `EFI_RT_PROPERTIES_TABLE`. 61 | 2+| _<>_. 62 | | [[uefi-rtc]] `URT_020` a| Systems with a Real-Time Clock on an OS-managed bus (e.g. I2C, subject to arbitration issues due to access to the bus by the OS) MUST meet the following requirements: 63 | 64 | * `GetTime()` and `SetTime()` MUST return `EFI_UNSUPPORTED`, when called after the UEFI boot services have been exited, and must 65 | operate on the same hardware as the <> before UEFI boot services are exited. 66 | * `GetTime()` and `SetTime()` MUST be appropriately described in the `EFI_RT_PROPERTIES_TABLE`. 67 | | `URT_030` a| The UEFI `ResetSystem()` runtime service MUST be implemented. 68 | 2+| _The OS MUST call the `ResetSystem()` runtime service call to reset or shutdown the system, preferring this to SBI, ACPI or other system-specific mechanisms. This allows for systems to perform any required system tasks on the way out (e.g. servicing `UpdateCapsule()` or persisting non-volatile variables in some systems)._ 69 | | `URT_040` | The non-volatile UEFI variables MUST persist across calls to the `ResetSystem()` runtime service call. 70 | 2+| _This rule is included in this specification to address a common mistake in implementing the UEFI requirements for non-volatile variables, even though it may appear redundant with the existing UEFI specification._ 71 | | `URT_050` | UEFI runtime services MUST be able to update the UEFI variables directly without the aid of an OS. 72 | 2+| _UEFI variables are normally saved in a dedicated storage which is not directly accessible by the operating system._ 73 | |=== 74 | 75 | === BRS-I Security Requirements 76 | 77 | [width=100%] 78 | [%header, cols="5,25"] 79 | |=== 80 | | ID# ^| Rule 81 | | `USEC_010` | Systems implementing a TPM MUST implement the _TCG EFI Protocol Specification_ cite:[TcgEfiPlat]. 82 | | `USEC_020` | Systems with UEFI secure boot MUST support a minimum of 128 KiB of non-volatile storage for UEFI variables. 83 | | `USEC_030` | For systems with UEFI secure boot, the maximum supported variable size MUST be at least 64 KiB. 84 | | `USEC_040` | For systems with UEFI secure boot, the `db` signature database variable (`EFI_IMAGE_SECURITY_DATABASE`) MUST be created with `EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS`, to prevent rollback attacks. 85 | | `USEC_050` | For systems with UEFI secure boot, the `dbx` signature database variable (`EFI_IMAGE_SECURITY_DATABASE1`) MUST be created with `EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS`, to prevent rollback attacks. 86 | |=== 87 | 88 | See additional <>. 89 | 90 | === BRS-I Firmware Update 91 | 92 | [width=100%] 93 | [%header, cols="5,25"] 94 | |=== 95 | | ID# ^| Rule 96 | | `UFU_010` | Systems with in-band firmware updates MUST do so either via `UpdateCapsule()` UEFI runtime service (cite:[UEFI] Section 8.5.3) or via _Delivery of Capsules via file on Mass Storage Device_ (cite:[UEFI] Section 8.5.5). 97 | 2+| _In-band means the firmware running on a hart updates itself._ 98 | | `UFU_020` | Systems implementing in-band firmware updates via `UpdateCapsule()` MUST accept updates in the _Firmware Management Protocol Data Capsule Structure_ format as described in _Delivering Capsules Containing Updates to Firmware Management Protocol_ cite:[UEFI] (Section 23.3). 99 | | `UFU_030` | Systems implementing in-band firmware updates via `UpdateCapsule()` MUST provide an ESRT cite:[UEFI] (Section 23.4) describing every firmware image that is updated in-band. 100 | | `UFU_040` | Systems implementing in-band firmware updates via `UpdateCapsule()` MAY return `EFI_UNSUPPORTED`, when called after the UEFI boot services have been exited. 101 | 2+| _<>_. 102 | |=== 103 | -------------------------------------------------------------------------------- /non-normative/acpi.adoc: -------------------------------------------------------------------------------- 1 | ACPI information is structured as tables with the address of the root of these 2 | tables known as Root System Description Table (RSDP) passed to the OS 3 | via a `EFI_ACPI_20_TABLE_GUID` configuration table in the UEFI firmware. 4 | The Operating System uses this address to locate all other ACPI tables. 5 | 6 | Certain implementations may make use of the _RISC-V Functional Fixed Hardware Specification_ cite:[FFH]. 7 | 8 | [[acpi-guidance-64bit-clean]] 9 | ==== 64-bits Clean 10 | 11 | ACPI started as a specification for 32-bit systems, 12 | so certain tables with physical address pointers (e.g. RSDP, FADT) allow for reporting 13 | either 32-bit or 64-bit values using different fields. For the sake of simplicity 14 | and consistency, the BRS disallows the use 32-bit address fields in such structures 15 | and disallows the use of 32-bit only structures (thus, RSDT must not be implemented, 16 | as the XSDT is a direct replacement). Thus, the ACPI tables are allowed to be 17 | located in any part of the physical address space. 18 | 19 | [[acpi-guidance-hw-reduced]] 20 | ==== Hardware-Reduced ACPI 21 | 22 | Compliant RISC-V systems only implement the hardware-reduced ACPI model cite:[ACPI] (Section 4.1). 23 | This means the hardware portion of cite:[ACPI] (Section 4) is not required or 24 | supported. All functionality is instead provided through equivalent 25 | software-defined interfaces and the complexity in supporting ACPI is reduced. 26 | 27 | ==== Table Guidance 28 | <> summarizes the minimum set of structures 29 | that must exist to support basic booting of RISC-V system with ACPI 30 | support. <> lists additional possible ACPI 31 | tables based on the optional features that can be supported. The 32 | latter is not meant to be exhaustive and mostly focuses on tables that 33 | have specific guidance or that are expected to be frequently 34 | implemented. 35 | 36 | .*Minimum required ACPI System Description Tables* 37 | [[acpi-guidance-tab-min]] 38 | [cols="3,2,2", width=95%, align="center", options="header"] 39 | |=== 40 | |ACPI Table |ACPI Section|Note 41 | |Root System Description Pointer (RSDP) |5.2.5 | See <>. 42 | |Extended System Description Table (XSDT) |5.2.8 | Contains pointers to other tables. 43 | |Fixed ACPI Description Table (FADT) |5.2.9 | See <>, <> and <>. 44 | |Differentiated System Description Table (DSDT)|5.2.11.1 | See <> and <>. 45 | |Multiple APIC Description Table (MADT) |5.2.12 | See <> 46 | |RISC-V Hart Capabilities Table (RHCT) |New | Communicates 47 | information about certain capabilities like ISA string, cache and MMU info. 48 | |Processor Properties Topology Table (PPTT) |5.2.29 | See <> 49 | |=== 50 | 51 | // Add RIMT for IOMMU here. 52 | 53 | .*Additional ACPI System Description Tables based on feature support.* 54 | [[acpi-guidance-tab-opt]] 55 | [cols="3,2,2", width=95%, align="center", options="header"] 56 | |=== 57 | |ACPI Table |ACPI Section |Note 58 | |Memory-mapped Configuration space (MCFG) |cite:[PCIFW] |See <> and <> 59 | |Secondary System Description Table (SSDT) |5.2.11.2 |See <> and <>. 60 | |Serial Port Console Redirection (SPCR) |cite:[SPCR] |See <> and <> 61 | |ACPI Table for TPM 2.0 (TPM2) |cite:[TcgAcpi]|If the system supports TPM 2.0 62 | |System Resource Affinity Table (SRAT) |5.2.16 |If the system supports NUMA 63 | |System Locality Information Table (SLIT) |5.2.17 |If the system supports NUMA 64 | |Boot Error Record Table (BERT) |18.3.1 |If APEI is supported 65 | |Error Injection Table (EINJ) |18.6.1 |If APEI is supported 66 | |Error Record Serialization Table (ERST) |18.5 |If APEI is supported 67 | |Hardware Error Source Table (HEST) |18.3.2 |If APEI is supported 68 | |RISC-V IO Mapping Table (RIMT) |New |If the system supports IOMMU 69 | |=== 70 | 71 | [[acpi-guidance-aml]] 72 | ==== DSDT and SSDTs 73 | 74 | The ACPI name space describes devices which cannot be enumerated by any other standard ways. These typically include SoC embedded memory-mapped I/O devices, such as UARTs, <> or CXL root complexes, GPIO controllers, etc. 75 | 76 | It's an implementation choice if the ACPI name space is defined solely with a DSDT or with any additional SSDTs. For example, a UEFI implementation 77 | may choose to use SSDTs to: 78 | 79 | * describe devices that vary across SoC SKUs, revisions or variants. 80 | * describe devices, where the backing AML is generated or patched at boot time. 81 | 82 | // Provide guidance here for converting existing device tree node definitions to ACPI. 83 | 84 | // Provide guidance here for describing NS16550-compatible UARTs. 85 | 86 | // Provide guidance here for PCIe RCs, perhaps leverage some of https://www.infradead.org/~mchehab/rst_conversion/PCI/acpi-info.html 87 | 88 | [[acpi-guidance-fadt]] 89 | ==== FADT 90 | 91 | cite:[ACPI] (Section 5.2.9) provides guidance on filling the 92 | Fixed ACPI Description Table for HW-reduced ACPI. 93 | 94 | Don't forget to select an appropriate Preferred PM Profile. 95 | 96 | [[acpi-guidance-madt]] 97 | ==== MADT 98 | 99 | RINTC (per-hart) structures are mandatory. Depending on the interrupt controller implemented by the system, the MADT will also contain either PLIC or APLIC structures. 100 | 101 | Entry ordering can be correlated with initialization order by an OS, but 102 | should not be taken to reflect affinity in resource sharing, 103 | e.g. sockets, caches, etc. RINTC hart ID and ACPI Processor UID should 104 | not be decoded in a system-specific manner to divine CPU topology. 105 | The PPTT Processor Properties Topology Table (PPTT) is to be used to 106 | describe affinities. 107 | 108 | [[acpi-guidance-gsi-namespace]] 109 | ==== PLIC/APLIC Namespace Devices 110 | 111 | Here's an example of an ASL excerpt satisfying <> 112 | and <> requirements. 113 | 114 | Scope (\_SB) 115 | { 116 | Device (IC00) 117 | { 118 | Name (_HID, "RSCV0001") // _HID: Hardware ID 119 | Name (_UID, Zero) // _UID: Unique ID 120 | Method(_GSB) { 121 | Return (0x10) // Global System Interrupt Base for this PLIC starts at 16 122 | } 123 | Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings 124 | { 125 | Memory32Fixed (ReadWrite, 126 | 0x0C000000, // Address Base. 127 | 0x00220000, // Address Length 128 | ) 129 | }) 130 | } 131 | Device (DEV1) 132 | { 133 | ... 134 | Name (_CRS, ResourceTemplate () // _CRS: Current Resource Settings 135 | { 136 | Memory32Fixed (ReadWrite, 137 | 0x10010000, // Address Base. 138 | 0x00010000, // Address Length 139 | ) 140 | Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive, ,,) 141 | { 142 | 0x10, 143 | } 144 | }) 145 | } 146 | } 147 | 148 | [[acpi-guidance-pcie]] 149 | ==== PCIe 150 | 151 | On some architectures, it became an industry accepted norm to describe PCIe implementations not compliant to the _PCI Firmware Specification_ cite:[PCIFW] 152 | using specification-defined ACPI tables and objects. RISC-V systems compliant to the BRS must only expose ECAM-compatible implementations using the 153 | MCFG and the standard AML Hardware ID (`_HID`) `PNP0A08` and Compatible ID (`_CID`) `PNP0A03`, and must not rely on ACPI table header information or other out-of-band means of detecting quirked behavior. 154 | 155 | Some minor incompatibilities, such as incorrect CFG0 filtering, broken BARs/capabilities for RCs, embedded switches/bridges 156 | or embedded endpoints can be handled by emulating ECAM accesses in privileged firmware (e.g. M-mode) or similar facilities (e.g. a hypervisor). 157 | 158 | Non-compliant implementations must be exposed using vendor-specific mechanisms (e.g. AML object with custom `_HID`, custom vendor-specific ACPI table if necessary). 159 | In cases where such PCIe implementations are only used to expose a fixed non-removable device (e.g. USB host controller or NVMe), the device could be exposed via 160 | a DSDT/SSDT MMIO device object without making the OS aware of the underlying PCIe connection. 161 | 162 | // Provide guidance here on AML object used, including interrupt routing, why I/O space is not included. 163 | 164 | [[acpi-guidance-spcr]] 165 | ==== SPCR 166 | 167 | Early serial console can be implemented using either an NS16550 UART (SPCR `Interface Type` 0x12), 168 | a PL011 UART (SPCR `Interface Type` 0x03), 169 | or an SBI console (SPCR `Interface Type` 0x15). When SPCR describes SBI console, the OS must use 170 | the SBI Probe extension (`FID #3`) to detect the Debug Console Extension 171 | (`DBCN`). 172 | 173 | The new `Precise Baud Rate` field, introduced in cite:[SPCR] rev. 4, allows describing rates faster 174 | than 115200 baud for NS16550-compatible UARTS. 175 | 176 | Hardware not capable of interrupt-driven operation and SBI console should be described with 177 | `Interrupt Type` of 0 and `Global System Interrupt` of 0. 178 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | --------------------------------------------------------------------------------