├── .gitignore ├── .gitmodules ├── LICENSE ├── Makefile ├── README.md ├── changelog.adoc ├── contributors.adoc ├── introduction.adoc ├── licensing.adoc ├── pcie-topology.ditaa ├── pcie-topology.png ├── riscv-platform-spec.adoc └── riscv-platform-spec.pdf /.gitignore: -------------------------------------------------------------------------------- 1 | riscv-platform-spec.html 2 | riscv-platform-spec.md 3 | riscv-platform-spec.pdf 4 | riscv-platform-spec.xml 5 | pcie-topology.png 6 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "docs-resources"] 2 | path = docs-resources 3 | url = https://github.com/riscv/docs-resources.git 4 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # 2 | # Build usable docs 3 | # 4 | 5 | ASCIIDOCTOR = asciidoctor 6 | ASCIIDOCTOR_PDF = $(ASCIIDOCTOR)-pdf 7 | DITAA = ditaa 8 | IMAGES = pcie-topology.png 9 | PLATFORM_SPEC = riscv-platform-spec 10 | RISCV_DIR = docs-resources 11 | RISCV_YML = $(RISCV_DIR)/themes/riscv-pdf.yml 12 | RISCV_FONTS = $(RISCV_DIR)/fonts/ 13 | PANDOC = pandoc 14 | PARTS = changelog.adoc contributors.adoc introduction.adoc licensing.adoc 15 | 16 | # Build the platform spec in several formats 17 | all: $(IMAGES) $(PLATFORM_SPEC).md $(PLATFORM_SPEC).pdf $(PLATFORM_SPEC).html 18 | 19 | %.png: %.ditaa 20 | rm -f $@ 21 | $(DITAA) $< 22 | 23 | $(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml 24 | $(PANDOC) -f docbook -t markdown_strict $< -o $@ 25 | 26 | $(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc 27 | $(ASCIIDOCTOR) -d book -b docbook $< 28 | 29 | $(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(RISCV_YML) 30 | $(ASCIIDOCTOR_PDF) \ 31 | -a toc \ 32 | -a compress \ 33 | -a pdf-style=$(RISCV_YML) \ 34 | -a pdf-fontsdir=$(RISCV_FONTS) \ 35 | -o $@ $< 36 | 37 | $(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc $(IMAGES) 38 | $(ASCIIDOCTOR) -d book -b html $< 39 | 40 | $(PLATFORM_SPEC).adoc: $(PARTS) 41 | touch $@ 42 | 43 | clean: 44 | rm -f $(PLATFORM_SPEC).xml 45 | rm -f $(PLATFORM_SPEC).md 46 | rm -f $(PLATFORM_SPEC).pdf 47 | rm -f $(PLATFORM_SPEC).html 48 | 49 | # handy shortcuts for installing necessary packages: YMMV 50 | install-debs: 51 | sudo apt-get install pandoc asciidoctor ditaa ruby-asciidoctor-pdf 52 | 53 | install-rpms: 54 | sudo dnf install ditaa pandoc rubygem-asciidoctor rubygem-asciidoctor-pdf 55 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # RISC-V Platform Specification 2 | 3 | The files in this project are used to create the RISC-V 4 | Platform Specification. This specification defines the set of firmware 5 | and hardware required of a RISC-V platform so that it may install 6 | and run various operating systems. 7 | 8 | The content of the specification is created and controlled by the RISC-V 9 | Platform Horizontal Subcommittee (RISC-V Platform HSC). Information 10 | about the subcommittee can be found at 11 | https://lists.riscv.org/g/tech-unixplatformspec. 12 | Please note that membership in RISC-V International is required to post 13 | to the mailing list, but it is publicly readable. Membership in RISC-V 14 | International is free for individual community members. 15 | 16 | All discussion of this specification occurs on the task group mailing 17 | list. Please use github issues for bug reports. 18 | 19 | # Licensing 20 | 21 | The files in this repository are licensed under the Creative Commons 22 | Attribution 4.0 International License (CC-BY 4.0). The full license 23 | text is available at https://creativecommons.org/licenses/by/4.0/. 24 | 25 | # Repository Content 26 | * **Makefile** => 'make' in this directory will produce the HTML, markdown, 27 | and PDF versions of the current spec 28 | * **README.md** => this file 29 | * ```riscv-platform-spec.adoc``` => the spec in asciidoc format; there are 30 | several subsidiary asciidoc files that get included by this file. 31 | * ```docs-resources``` => Git Submodule with the RISC-V documentation theme, 32 | fonts, etc. for building the document 33 | 34 | # Repository Branches 35 | * All development occurs on ```main```; no content on main is to be 36 | considered TSC-approved content. 37 | * TSC-approved content will be clearly marked as such. 38 | 39 | # Dependencies 40 | The PDF built in this project uses AsciiDoctor (Ruby). For more information 41 | on AsciiDoctor, specification guidelines, or building locally, see the 42 | [RISC-V Documentation Developer Guide](https://github.com/riscv/docs-dev-guide). 43 | 44 | # Cloning the project 45 | This project uses 46 | [GitHub Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) 47 | to include the RISC-V 48 | [docs-resources project](https://github.com/riscv/docs-resources) 49 | to achieve a common look and feel. 50 | 51 | When cloning this repository for the first time, you must either use 52 | `git clone --recurse-submodules` or execute `git submodule init` and 53 | `git submodule update` after the clone to populate the `docs-resources` 54 | directory. Failure to clone the submodule, will result in the PDF build 55 | fail with an error message like the following: 56 | 57 | ``` 58 | $ make 59 | asciidoctor-pdf \ 60 | -a toc \ 61 | -a compress \ 62 | -a pdf-style=docs-resources/themes/riscv-pdf.yml \ 63 | -a pdf-fontsdir=docs-resources/fonts \ 64 | --failure-level=ERROR \ 65 | -o profiles.pdf profiles.adoc 66 | asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme 67 | No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts 68 | Use --trace for backtrace 69 | make: *** [Makefile:7: profiles.pdf] Error 1 70 | ``` 71 | -------------------------------------------------------------------------------- /changelog.adoc: -------------------------------------------------------------------------------- 1 | // SPDX-License-Identifier: CC-BY-4.0 2 | // 3 | // changelog.adoc: change log for the document 4 | // 5 | // Provide a list of changes made to each revision of the document. 6 | // 7 | [preface] 8 | ## Change Log 9 | 10 | ### version 0.3-draft 11 | * 2021-12-13: 12 | ** Restructure document into OS-A Common, OS-A Embedded and OS-A Server 13 | 14 | ### version 0.2-draft 15 | * 2021-09-01: 16 | ** Draft version for internal reviews 17 | 18 | ### version 0.1-draft 19 | * 2020-10-07: 20 | ** Initial changes for structure and future maintenance. 21 | ** Break content down into include files; more structure, but easier 22 | to make changes down the line. 23 | -------------------------------------------------------------------------------- /contributors.adoc: -------------------------------------------------------------------------------- 1 | // SPDX-License-Identifier: CC-BY-4.0 2 | // 3 | // contributors.adoc: acknowledge document contributors 4 | // 5 | // Provide a simple acknowledgement to all who have contributed to the 6 | // specification. 7 | // 8 | [appendix] 9 | ## Contributors 10 | 11 | All of these individuals either wrote portions of this specification or 12 | contributed ideas and suggestions in some way: 13 | 14 | Krste Asanovic, 15 | Allen Baum, 16 | Palmer Dabbelt, 17 | Greg Favor, 18 | Mark Himelstein, 19 | David Kruckmeyer, 20 | Anup Patel, 21 | Atish Patra, 22 | Al Stone, 23 | Arun Thomas, 24 | Philipp Tomsich, 25 | Paul Walmsley, 26 | Andrew Waterman, 27 | Kumar Sankaran, 28 | Alistair Francis, 29 | Sunil V L, 30 | Rahul Pathak, 31 | Mayuresh Chitale, 32 | Paul Donahue, 33 | Abner Chang 34 | 35 | If you have contributed and are not listed, do let us know. We haven't 36 | forgotten you, but we may have forgotten to edit this list. 37 | 38 | Thank you. 39 | -------------------------------------------------------------------------------- /introduction.adoc: -------------------------------------------------------------------------------- 1 | // SPDX-License-Indentifer: CC-BY-4.0 2 | // 3 | // introduction.adoc: describe the purpose of the document 4 | // 5 | // Provide a description of the overall intent and purpose of this 6 | // specifiction. 7 | // 8 | 9 | ## Introduction 10 | 11 | This document contains the RISC-V UNIX-class platform specification. This 12 | specification defines additional restrictions on implementations in order to 13 | allow software to be compatible between these implementations. 14 | The scope and definitions used in this document are defined in the platform 15 | policy specification. 16 | -------------------------------------------------------------------------------- /licensing.adoc: -------------------------------------------------------------------------------- 1 | // SPDX-License-Identifier: CC-BY-4.0 2 | // 3 | // licensing.adoc: licensing information 4 | // 5 | // Copyright and licensing information for the specification. 6 | // 7 | [preface] 8 | ## Copyright and License Information 9 | 10 | This RISC-V Profile and Platform Specification (P2S) is 11 | 12 | [%hardbreaks] 13 | (C) 2017 Krste Asanovic 14 | (C) 2017-2019 Palmer Dabbelt 15 | (C) 2017 Andrew Waterman 16 | (C) 2020 Al Stone 17 | (C) 2021 Kumar Sankaran 18 | 19 | The P2S is licensed under the Creative Commons Attribution 4.0 International 20 | License (CC-BY 4.0). The full license text is available at 21 | https://creativecommons.org/licenses/by/4.0/. 22 | 23 | -------------------------------------------------------------------------------- /pcie-topology.ditaa: -------------------------------------------------------------------------------- 1 | +----------+ +----------+ 2 | | CPU | | CPU | 3 | +-----+----+ +-----+----+ 4 | | | 5 | | | 6 | | | 7 | +-------------+------------+ +-------------+------------+ 8 | | | | | 9 | | Root Complex | | Root Complex | 10 | | | | | 11 | | +--------------+ | | +--------------+ | 12 | | | Host Bridge | | | | Host Bridge | | 13 | | +------+-------+ | | +------+-------+ | 14 | | | | | | | 15 | | | | | | Bus 0 | 16 | | +-------+------+ | | +-----+-------+ | 17 | | | Bus 0 | | | | Root Port | | 18 | | | | | | +-----+-------+ | 19 | | +---+---+ +---+---+ | | | | 20 | | | RCiEP | | RCEC | | | | PCIe Link | 21 | | +-------+ +-------+ | | | | 22 | | | | Bus 1 | | 23 | | | | | | 24 | +--------------------------+ +--------------------------+ 25 | 26 | +----------+ 27 | | CPU | 28 | +-----+----+ 29 | | 30 | | 31 | | 32 | +------------------------+-----------------------+ 33 | | | 34 | | Root Complex | 35 | | | 36 | | +--------------+ | 37 | | | Host Bridge | | 38 | | +------+-------+ | 39 | | | | 40 | | Bus 0 | | 41 | | +-----------------+--------------+ | 42 | | | | | | 43 | | | | | | 44 | | +-----+-------+ +---+---+ +---+---+ | 45 | | | Root Port | | RCiEP | | RCEC | | 46 | | +-----+-------+ +-------+ +-------+ | 47 | | | | 48 | | | | 49 | |Bus 1 | | 50 | | | | 51 | +------------------------------------------------+ 52 | 53 | RCiEP - Root complex integrated endpoint 54 | RCEC - Root complex event collector 55 | -------------------------------------------------------------------------------- /pcie-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscvarchive/riscv-platform-specs/1e93c488c78acd19572b3ae9ae3940ce12f32e23/pcie-topology.png -------------------------------------------------------------------------------- /riscv-platform-spec.adoc: -------------------------------------------------------------------------------- 1 | // SPDX-License-Identifier: CC-BY-4.0 2 | // 3 | // riscv-platform-spec.adoc: main file for the specification 4 | // 5 | // This file provides the primary structure and formatting for 6 | // the overall Profile and Platform Specification. 7 | // 8 | = RISC-V Platform Specification 9 | :author: RISC-V Platform Horizontal Subcommittee (RISC-V Platform HSC) 10 | :email: tech-unixplatformspec@lists.riscv.org 11 | :company: RISC-V 12 | :revnumber: 0.3-draft 13 | :revdate: December 2021 14 | :revremark: This document is in Development state. Change should be expected. 15 | :url-riscv: http://riscv.org 16 | :doctype: book 17 | :preface-title: Preamble 18 | :colophon: 19 | :appendix-caption: Appendix 20 | :title-logo-image: image:docs-resources/images/risc-v_logo.svg[pdfwidth=3.25in,align=center] 21 | // Settings: 22 | :experimental: 23 | :reproducible: 24 | :WaveDromEditorApp: wavedrom-cli 25 | :icons: font 26 | :lang: en 27 | :listing-caption: Listing 28 | :sectnums: 29 | :sectnumlevels: 5 30 | :xrefstyle: short 31 | :toc: left 32 | :toclevels: 5 33 | :source-highlighter: pygments 34 | ifdef::backend-pdf[] 35 | :source-highlighter: coderay 36 | endif::[] 37 | :data-uri: 38 | :hide-uri-scheme: 39 | :stem: latexmath 40 | :footnote: 41 | :xrefstyle: short 42 | 43 | // table of contents 44 | toc::[] 45 | 46 | // Preamble 47 | [WARNING] 48 | .This document is in the link:http://riscv.org/spec-state[Development state] 49 | ==== 50 | Assume everything can change. This draft specification 51 | will change before being accepted as standard, so 52 | implementations made to this draft specification will 53 | likely not conform to the future standard. 54 | ==== 55 | 56 | // document copyright and licensing information 57 | include::licensing.adoc[] 58 | 59 | // changelog for the document 60 | include::changelog.adoc[] 61 | 62 | [preface] 63 | == Terminology 64 | [cols="1,4", width=80%, align="left", options="header"] 65 | |=== 66 | |TERM | DESCRIPTION 67 | |SBI | Supervisor Binary Interface <> 68 | |UEFI | Unified Extensible Firmware Interface <> 69 | |ACPI | Advanced Configuration and Power Interface <> 70 | |APEI | ACPI Platform Error Interfaces <> 71 | |SMBIOS | System Management Basic I/O System <> 72 | |DTS | Devicetree source file <> 73 | |DTB | Devicetree binary <> 74 | |RVA22 | RISC-V Application 2022 <> 75 | |EE | Execution Environment 76 | |OSPM | Operating System Power Management 77 | |RVA22U64 | RISC-V 2022 user-mode profile <> 78 | |RVA22S64 | RISC-V 2022 supervisor-mode profile <> 79 | |RAS | Reliability, Availability, and Serviceability 80 | |CLINT | Legacy Core-Local Interrupt Controller 81 | |ACLINT | Advanced Core-Local Interrupt Controller <> 82 | |PLIC | Legacy Platform-Level Interrupt Controller <> 83 | |APLIC | Advanced Platform-Level Interrupt Controller <> 84 | |AIA | Advanced Interrupt Architecture <> 85 | |IMSIC | Incomning MSI Controller <> 86 | |L1D | L1 Data cache 87 | |LL | Last level cache 88 | |DTLB | DATA TLB cache 89 | |PCIe | PCI Express 90 | |ECAM | Enhanced Configuration Access Mechanism 91 | |BAR | Base Address Register 92 | |AER | Advanced Error Reporting 93 | |CRS | Configuration Request Retry Status 94 | |TLP | Transaction Layer Packet 95 | |RCiEP | Root Complex Integrated Endpoint 96 | |RCEC | Root Complex Event Collector 97 | |PME | Power Management Event 98 | |MSI | Message Signaled Interrupts 99 | |MSI-X | Enhanced Message Signaled Interrupts 100 | |INTx | PCIe Legacy Interrupts 101 | |PMA | Physical Memory Attributes 102 | |PRT | PCI Routing Table 103 | |EBBR | Embedded Base Boot Requirements <> 104 | |CSI | Common Software Interface 105 | |=== 106 | 107 | == Introduction 108 | The platform specification defines a set of platforms that specify requirements 109 | for interoperability between software and hardware. The Platform Policy <> 110 | defines the various terms used in this platform specification. The platform 111 | policy also provides the needed detail regarding the scope, coverage, naming, 112 | versioning, structure, life cycle and compatibility claims for the platform 113 | specification. It is recommended that readers get familiar with the platform 114 | policy while reading this specification. All the requirements in this 115 | specification are MANDATORY unless specifically called out in the relevant 116 | sections. Any hardware platform seeking compatibility with the platform 117 | specification has to be self certified by the platform compatibility test 118 | suite (PCT). More details about the PCT are available in the platform policy 119 | specification. 120 | 121 | The platform specification currently defines two platforms as shown below. 122 | Additional platforms are expected to be defined in the future for industry 123 | specific target market verticals like “mobile”, “edge computing”, 124 | “machine-learning” "desktop", “automotive” and more. 125 | 126 | * *OS-A Platform*: The OS-A platform specifies a category of rich-OS platforms 127 | that support operating systems like Linux, FreeBSD, Windows and more; 128 | flavors that run on enterprise and embedded class application processors. 129 | Each OS-A platform that is defined below is independent in its representation 130 | and is not dependent on any other platform for its features or specifications. 131 | Requirements common across multiple platforms are bundled together in the OS-A 132 | Common Requirements section in order to prevent duplication of content. The 133 | specific platform can include all or some of the requirements in the common 134 | section and add or modify these as per the specific requirements. 135 | The OS-A platforms that are currently defined are the following: + 136 | ** *OS-A Embedded Platform* 137 | ** *OS-A Server Platform* 138 | 139 | * *RVM-CSI Platform*: The RVM-CSI platform defines the Common Software Interface 140 | (CSI) for RISC-V microcontrollers. It specifies an RTOS platform for 141 | bare-metal applications and small operating systems running on a 142 | microcontroller. The RVM-CSI platform has a base feature set and extensions as 143 | shown below: + 144 | ** *Base* 145 | ** *Physical Memory Protection (PMP) Extension* 146 | 147 | The current version of this platform spec targets the standardization of 148 | functionality available in S, U, VS and VU modes, and the standardization of 149 | the SBI (Supervisory Binary Interface as defined in <>) between 150 | Supervisor level (S-mode/VS-mode) and M-mode/HS-mode respectively. 151 | 152 | // OS-A Platform Common requirements 153 | == OS-A Common Requirements 154 | 155 | === ISA Requirements 156 | ==== General 157 | 158 | * This OS-A platform must comply with the RVA22U and RVA22S ISA profiles as 159 | defined in the RISC-V ISA Profiles specification [11]. 160 | * A non-conforming extension that conflicts with a supported standard extensions 161 | must satisfy at least one of the following: 162 | ** It must be disabled by default. 163 | ** The supported standard extension must be declared as unsupported in all 164 | feature discovery structures used by software. This option is allowed only 165 | if the standard extension is not required. 166 | * All hart PMA regions for main memory must be marked as coherent. 167 | * Memory accesses by I/O masters can be coherent or non-coherent with respect 168 | to all hart-related caches. 169 | * Unless otherwise specified by a given I/O device, I/O devices are on ordering channel 0 (i.e., they are point-to-point strongly ordered). 170 | 171 | ==== Supervisor mode 172 | * sstatus 173 | ** sstatus.UBE must support the same access attribute (read-only or writable) 174 | as mstatus.UBE. 175 | 176 | * stvec 177 | ** Both direct and vectored modes must be supported. 178 | ** The alignment constraint for BASE fields must be at most 256B. 179 | 180 | * scounteren 181 | ** Writeable bits must be implemented for all supported (not hardwired to zero) 182 | hpmcounters. 183 | 184 | * stval 185 | ** stval must not be hardwired to 0 and in all cases must be written with 186 | non-zero and zero values as architecturally defined. 187 | 188 | * satp 189 | ** For RV32, Bare and Sv32 translation modes must be supported. 190 | ** For RV64, Bare and Sv39 translation modes must be supported. 191 | 192 | ==== Hypervisor extension 193 | * hstatus 194 | ** VTW bit must not be hardwired to 0. 195 | ** VTVM bit must not be hardwired to 0. 196 | 197 | * hcounteren 198 | ** Writeable bits must be implemented for all supported (not hardwired to zero) 199 | hpmcounters. 200 | 201 | * htval 202 | ** htval must not be hardwired to 0 and in all cases must be written with 203 | non-zero and zero values as architecturally defined. 204 | 205 | * htinst/mtinst 206 | ** htinst and mtinst must not be hardwired to 0 and must be written with a 207 | transformed instruction (versus zero) when defined and allowed architecturally. 208 | 209 | * hgatp 210 | ** For RV32, Bare and Sv32x4 translation modes must be supported. 211 | ** For RV64, Bare and Sv39x4 translation modes must be supported. 212 | 213 | * vstvec 214 | ** Both direct and vectored modes must be supported. 215 | ** The alignment constraint for BASE fields must be at most 256B. 216 | 217 | * vstval 218 | ** vstval must not be hardwired to 0 and in all cases must be written with 219 | non-zero and zero values as architecturally defined. 220 | 221 | * vsatp 222 | ** For RV32, Bare and Sv32 translation modes must be supported. 223 | ** For RV64, Bare and Sv39 translation modes must be supported. 224 | 225 | === Debug 226 | The OS-A platform common requirements are the following: 227 | 228 | - Implement resethaltreq 229 | * Rationale: Debugging immediately out of reset is a useful debug tool. 230 | The resethaltreq mechanism provides a standard way to do this. 231 | - Implement the program buffer 232 | * Rationale: The program buffer is easier for most implementations than 233 | abstract access. 234 | * Rationale: Debuggers need to be able to insert ebreak instructions into 235 | memory and make sure that the ebreak is visible to subsequent instruction 236 | fetches. Abstract access has no support for `fence.i` (or similar 237 | mechanisms). 238 | - abstractcs.relaxedpriv must be 0 239 | * Rationale: Doing otherwise is a potential security problem. 240 | - abstractauto must be implemented 241 | * Rationale: autoexecprogbuf allows faster instruction-stuffing. 242 | * Rationale: autoexecdata allows fast read/write of a region of memory. 243 | - dcsr.mprven must be tied to 1 244 | * Rationale: Emulating two-stage table walks and PMP checks and endianness 245 | swapping is a heavy burden on the debugger. 246 | - In textra, sselect must support the value 0 and either value 1 or 2 (or 247 | both) 248 | * Rationale: There must be some way to limit triggers to only match in a 249 | particular user context and a way to ignore user context. 250 | - If textra.sselect=1 is supported, the number of implemented bits of svalue 251 | must be at least the number of implemented bits of scontext 252 | * Rationale: This allows matching on every possible scontext. 253 | - If textra.sselect=2 is supported, the number of implemented bits of svalue 254 | must be at least ASIDLEN to match every possible ASID 255 | - In textra, mhselect must support the value 0. If the H extension is 256 | supported then mhselect must also support either values 1 and 5 or values 2 257 | and 6 (or all four) 258 | * Rationale: There must be some way to limit triggers to only match in a 259 | particular guest context and a way to ignore guest context. 260 | - If textra.mhselect=1,5 are supported and if H is the number of implemented 261 | bits of hcontext then, unless all bits of mhvalue are implemented, at least 262 | H-1 bits of mhvalue must be implemented 263 | * Rationale: This allows matching on every possible hcontext (up to the limit 264 | of the field width). It is H-1 bits instead of H because mhselect[2] 265 | provides one bit. 266 | - If textra.mhselect=2,6 are supported, the number of implemented bits of 267 | mhvalue must be at least VMIDLEN-1 268 | * Rationale: This allows matching on every possible VMID. It is VMIDLEN-1 269 | instead of VMIDLEN because mhselect[2] provides one bit. 270 | - Implement at least four mcontrol6 triggers that can support matching on PC 271 | (select=0, execute=1, match=0) with timing=0 and full support for mode 272 | filtering (vs, vu, m, s, u) for all supported modes and support for textra as 273 | above 274 | * Rationale: The debugger needs breakpoints and 4 is a sufficient baseline. 275 | - Implement at least four mcontrol6 triggers that can support matching on load 276 | and store addresses (select=0, match=0, and all combinations of load/store) 277 | with timing=0 and full support for mode filtering (vs, vu, m, s, u) for all 278 | supported modes and support for textra as above 279 | * Rationale: The debugger needs watchpoints and 4 is a sufficient baseline. 280 | - Implement at least one trigger capable of icount and support for textra as 281 | above for self-hosted single step needs this 282 | - Implement at least one trigger capable of etrigger and support for textra as 283 | above to catch exceptions 284 | - Implement at least one trigger capable of itrigger and support for textra as 285 | above to catch interrupts 286 | - The minimum trigger requirements must be met for action=0 and for action=1 287 | (possibly by the same triggers) 288 | * Rationale: The intent is to have full support for external debug and full 289 | support for self-hosted debug (though not necessarily at the same time). 290 | This can be provided via the same set of triggers or separate sets of 291 | triggers. External debug support for icount is unnecessary due to dcsr.step 292 | and is therefore called out separately. 293 | - For implementations with multiple cores, support for at least one halt group 294 | and one resume group (in addition to group 0) 295 | * Rationale: Allows stopping all harts (approximately) simultaneously which 296 | is useful for debugging MP software. 297 | - dcsr.stepie must support the 0 setting. It is optional to support the 1 298 | setting 299 | * Rationale: It is not generally useful to step into interrupt handlers. 300 | - dcsr.stopcount must be supported and the reset value must be 1 301 | * Rationale: The architecture has strict requirements on minstret which may 302 | be perturbed by an external debugger in a way that's visible to software. 303 | The default should allow code that's sensitive to these requirements to be 304 | debugged. 305 | 306 | === Timers 307 | * One or more ACLINT MTIMER devices are required for the OS-A platform. 308 | * Platform must support an ACLINT MTIME counter resolution of 100ns or less 309 | (corresponding to a clock tick frequency of at least 10 MHz). 310 | 311 | === Interrupts 312 | The OS-A platform must comply with one of the four interrupt support 313 | categories described in following sub-sections. The hardware must support at 314 | least one of the four interrupt categories while software must support all of 315 | the interrupt categories described below. Any hardware requirement for a specific 316 | privilege mode is only applicable for platforms supporting that privilege mode. 317 | 318 | [#legacy_wired_irqs] 319 | ==== Legacy wired IRQs - DEPRECATED 320 | ** One or more PLIC devices are required to support wired interrupts. 321 | ** One or more ACLINT MSWI devices are required to support M-mode software 322 | interrupts. 323 | ** Software interrupts for S-mode and VS-mode are supported using the 324 | SBI IPI extension. 325 | ** This category is compatibile with legacy platforms having PLIC plus CLINT 326 | devices. 327 | ** MSI external interrupts are not supported. 328 | ** MSI virtualization is not supported. 329 | 330 | [#only_wired_irqs] 331 | ==== Only Wired IRQs 332 | ** One or more AIA APLIC devices are required to support wired interrupts. 333 | ** One or more ACLINT MSWI devices are required to support M-mode software interrupts. 334 | ** One or more ACLINT SSWI devices are required to support S/HS-mode software interrupts. 335 | ** Software interrupts for VS-mode are supported using the SBI IPI extension. 336 | ** MSI external interrupts are not supported. 337 | ** MSI virtualization is not supported. 338 | 339 | [#msis_and_wired_irqs] 340 | ==== MSIs and Wired IRQs 341 | ** AIA local interrupt CSRs must be supported by each hart. 342 | *** `siselect` CSR must support holding 9-bit value. 343 | *** `vsiselect` CSR must support holding 9-bit value if H-extension is 344 | implemented. 345 | ** Per-hart AIA IMSIC devices must support MSIs for M-mode and S/HS-mode. 346 | *** Must support IPRIOLEN = 6 to 8. 347 | *** Must support at least 63 distinct interrupt identities. 348 | *** Must implement `seteipnum_le` memory-mapped register. 349 | ** One, or more AIA APLIC devices to support wired interrupts if the platform 350 | support wired irqs. 351 | *** EIID and IID fields must be 6 to 8 bits wide matching the number of 352 | interrrupt identities supported by AIA IMSIC. 353 | ** Software interrupts for M-mode and S/HS-mode are supported using AIA IMSIC 354 | devices. 355 | ** Software interrupts for VS-mode are supported using the SBI IPI extension. 356 | ** MSI virtualization is not supported. 357 | 358 | [#msis_virtual_msis_and_wired_irqs] 359 | ==== MSIs, Virtual MSIs, and Wired IRQs 360 | ** To support virtual MSIs, the H-extension must be implemented. 361 | *** GEILEN must be 3 or more. 362 | ** AIA local interrupt CSRs must be supported by each hart. 363 | *** `siselect` CSR must support holding 9-bit value. 364 | *** `vsiselect` CSR must support holding 9-bit value. 365 | ** Per-hart AIA IMSIC devices are required to support MSIs for M-mode, HS-mode and VS-mode. 366 | *** Must support IPRIOLEN = 6 to 8. 367 | *** Must support at least 63 distinct interrupt identities. 368 | *** Must implement `seteipnum_le` memory-mapped register. 369 | *** Must implement at least 3 guest interrupt files. 370 | ** One, or more AIA APLIC devices are required to support wired interrupts if the 371 | platform support wired irqs. 372 | *** EIID and IID fields must be 6 to 8 bits wide matching the number of 373 | interrrupt identities supported by AIA IMSIC. 374 | ** Software interrupts for M-mode, HS-mode and VS-mode are supported using 375 | AIA IMSIC devices. 376 | ** MSI virtualization is supported. 377 | 378 | ==== Summary 379 | 380 | The <> below summarizes the four 381 | categories of interrupt support and timer support allowed on an OS-A platorm. 382 | 383 | [#table_interrutps_and_timer_osa_platforms] 384 | .Interrupts and Timer support in OS-A platforms 385 | [stripes="none", width="100%", cols="^2s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s"] 386 | |=== 387 | .2+|+++OS-A Platform+++ 388 | 3+|+++MSIs+++ 389 | 3+|+++Wired Interrupts+++ 390 | 3+|+++Software Interrupts+++ 391 | 3+|+++Timer+++ 392 | |+++M-mode+++ 393 | |+++S-mode+++ 394 | |+++VS-mode+++ 395 | |+++M-mode+++ 396 | |+++S-mode+++ 397 | |+++VS-mode+++ 398 | |+++M-mode+++ 399 | |+++S-mode+++ 400 | |+++VS-mode+++ 401 | |+++M-mode+++ 402 | |+++S-mode+++ 403 | |+++VS-mode+++ 404 | 405 | |+++Legacy Wired IRQs+++ 406 | |+++NA+++ 407 | |+++NA+++ 408 | |+++NA+++ 409 | |+++PLIC+++ 410 | |+++PLIC+++ 411 | |+++PLIC (emulate)+++ 412 | |+++MSWI+++ 413 | |+++SBI IPI+++ 414 | |+++SBI IPI+++ 415 | |+++MTIMER+++ 416 | |+++SBI Timer+++ 417 | |+++SBI Timer+++ 418 | 419 | |+++Only Wired IRQs+++ 420 | |+++NA+++ 421 | |+++NA+++ 422 | |+++NA+++ 423 | |+++APLIC+++ 424 | |+++APLIC+++ 425 | |+++APLIC (emulate)+++ 426 | |+++MSWI+++ 427 | |+++SSWI+++ 428 | |+++SBI IPI+++ 429 | |+++MTIMER+++ 430 | |+++Priv Sstc+++ 431 | |+++Priv Sstc+++ 432 | 433 | |+++MSIs and Wired IRQs+++ 434 | |+++IMSIC+++ 435 | |+++IMSIC+++ 436 | |+++IMSIC (emulate)+++ 437 | |+++APLIC+++ 438 | |+++APLIC+++ 439 | |+++APLIC (emulate)+++ 440 | |+++IMSIC+++ 441 | |+++IMSIC+++ 442 | |+++SBI IPI+++ 443 | |+++MTIMER+++ 444 | |+++Priv Sstc+++ 445 | |+++Priv Sstc+++ 446 | 447 | |+++MSIs, Virtual MSIs and Wired IRQs+++ 448 | |+++IMSIC+++ 449 | |+++IMSIC+++ 450 | |+++IMSIC+++ 451 | |+++APLIC+++ 452 | |+++APLIC+++ 453 | |+++APLIC (emulate)+++ 454 | |+++IMSIC+++ 455 | |+++IMSIC+++ 456 | |+++IMSIC+++ 457 | |+++MTIMER+++ 458 | |+++Priv Sstc+++ 459 | |+++Priv Sstc+++ 460 | |=== 461 | 462 | === System Peripherals 463 | ==== UART/Serial Console 464 | 465 | In order to facilitate the bring-up and debug of the low level initial 466 | platform, hardware is required to implement a UART port that confirms to the 467 | following requirements and firmware must support the console using this UART: 468 | 469 | * The UART register addresses are required to be aligned to 4 byte boundaries. 470 | If the implemented register width is less than 4 bytes then the implemented 471 | bytes are required to be mapped starting at the smallest address. 472 | * The UART port implementation is required to be register-compatible with one 473 | of the following: 474 | ** UART 16550 - MANDATORY 475 | ** UART 8250 - DEPRECATED 476 | 477 | 478 | === Runtime Services 479 | 480 | ==== SBI 481 | 482 | * The M-mode runtime must implement SBI specification <> or higher. 483 | * Required SBI extensions include: 484 | ** SBI TIME 485 | ** SBI IPI 486 | ** SBI RFENCE 487 | ** SBI HSM 488 | ** SBI SRST 489 | ** SBI PMU 490 | 491 | ==== UEFI 492 | 493 | * Wherever applicable UEFI firmware must implement UEFI interfaces over 494 | similar interfaces and services present in the SBI specification. For 495 | example, the UEFI ResetSystem() service must be implemented via the 496 | SBI System Reset Extension. 497 | * The operating system should prioritize calling the UEFI interfaces before 498 | the SBI or platform specific mechanisms. 499 | 500 | === Software and ABIs 501 | The platform specification mandates the following requirements for 502 | software components: 503 | 504 | * All RISC-V software components must comply with the 505 | RISC-V Calling Convention specification <>. 506 | * All RISC-V software components that use ELF files must comply with the 507 | RISC-V ELF specification <>. 508 | * All RISC-V software components that use DWARF files must comply with the 509 | RISC-V DWARF specification <>. 510 | 511 | Rationale: The platform specification intends to avoid fragmentation and 512 | promotes interoperability. 513 | 514 | * To order older stores before younger instruction fetches, user-level programs must 515 | use system-supplied library calls (e.g. GNU libc's `__riscv_flush_icache`, which 516 | invokes the Linux kernel's corresponding vDSO routine), rather than executing 517 | the `fence.i` instruction directly. 518 | 519 | Rationale: The `fence.i` instruction only orders the current hart's instruction 520 | fetches - which is insufficient even for single-threaded programs since a thread 521 | may migrate to a different hart. 522 | 523 | === Security 524 | ** If M-mode is supported in the platform, all machine mode assets, such as 525 | code and data, shall be protected from all non-machine mode accesses from the 526 | harts in the system. Additionally, I/O agent access protection must be 527 | required within the system to protect machine mode assets. Therefore, the 528 | following requirements are mandatory for platforms with M-mode: 529 | 530 | *** Platform must provide a protection mechanism from non-machine mode hart 531 | transactions that precisely traps if violated. 532 | *** Platform must provide a protection mechanism from I/O agents manipulating 533 | or accessing machine mode assets. 534 | 535 | // OS-A Embedded Platform 536 | == OS-A Embedded Platform 537 | The OS-A Embedded Platform targets embedded class applications. The OS-A 538 | Embedded Platform inherits all the requirements as defined in the OS-A Platform 539 | Common Requirements section. Additional requirements are detailed in the 540 | following sections. 541 | 542 | === PMU 543 | The RVA22 profile defines 32 PMU counters out-of-which first three counters are 544 | defined by the privilege specification while other 29 counters are programmable. 545 | The SBI PMU extension defines a set of hardware events that can be monitored 546 | using these programmable counters. This section defines the minimum number of 547 | programmable counters and hardware events required for an OS-A Embedded 548 | compatible platform. 549 | 550 | * Counters 551 | ** The platform does not require to implement any of the programmable counters. 552 | * Events 553 | ** The platform does not require to implement any of the hardware events defined 554 | in SBI PMU extensions. 555 | 556 | === Boot Process 557 | - The OS-A Embedded Platform must comply with the EBBR specification 558 | <>. Any deviation from the EBBR will be explicitly mentioned in 559 | the requirements in this section. 560 | 561 | ==== Firmware 562 | ===== UEFI Protocol Support 563 | The UEFI protocols listed below are required to be implemented in addition to 564 | the requirements in EBBR. 565 | 566 | .Additional UEFI Protocols 567 | [cols="3,1,2", width=95%, align="center", options="header"] 568 | |=== 569 | |Protocol | UEFI Section | Note 570 | |RISCV_EFI_BOOT_PROTOCOL | <> | To pass boot hart ID 571 | |=== 572 | 573 | ===== Storage and Partitioning 574 | - GPT partitioning required for shared storage. 575 | - MBR support is not required. 576 | 577 | ==== Hardware Discovery Mechanisms 578 | - Platforms must support the Unified Discovery specification for all pre-boot 579 | information population <>. 580 | 581 | ===== Device Tree (DT) 582 | - Device Tree (DT) is the required mechanism for the hardware discovery and 583 | configuration. 584 | 585 | // OS-A Server Platform 586 | == OS-A Server Platform 587 | The OS-A Server Platform targets server class applications. The OS-A 588 | Server Platform inherits all the requirements as defined in the OS-A Platform 589 | Common Requirements section. Additional requirements are detailed in the 590 | following sections. 591 | 592 | === ISA Requirements 593 | ==== General 594 | * The hypervisor H-extension must be supported. 595 | * The Zam extension must be supported for misaligned addresses within at least aligned 16B regions. 596 | * The `time` CSR must be implemented in hardware. 597 | * The Sstc extension <> must be implemented. + 598 | 599 | [underline]*_Recommendation_* + 600 | There should be hardware support for all misaligned accesses; misaligned 601 | accesses should not take address misaligned exceptions. 602 | 603 | ==== Supervisor mode 604 | * satp 605 | ** For RV64, Sv48 translation mode must be supported. 606 | ** At least 8 ASID bits must be supported and not hardwired to 0. 607 | 608 | ==== Hypervisor extension 609 | * hgatp 610 | ** For RV64, Sv48x4 translation mode must be supported. 611 | ** At least 8 VMID bits must be supported and not hardwired to 0. 612 | 613 | * vsatp 614 | ** For RV64, Sv48 translation mode must be supported. 615 | ** At least 8 ASID bits must be supported and not hardwired to 0. 616 | 617 | === PMU 618 | The RVA22 profile defines 32 PMU counters out-of-which first three counters are 619 | defined by the privilege specification while other 29 counters are programmable. 620 | The SBI PMU extension defines a set of hardware events that can be monitored 621 | using these programmable counters. This section defines the minimum number of 622 | programmable counters and hardware events required for an OS-A Server 623 | compatible platform. 624 | 625 | * Counters 626 | ** The platform must implement at least 8 programmable counters. 627 | * Events 628 | ** Hardware general events 629 | *** The platform must implement all of the general hardware events defined by 630 | the SBI PMU extension. 631 | ** Hardware cache events 632 | *** The platform must implement READ operations for all of the hardware cache 633 | events except SBI_PMU_HW_CACHE_NODE and SBI_PMU_HW_CACHE_LL defined in the SBI 634 | PMU extension. 635 | *** The platform must implement WRITE operation for L1D, and DTLB caches. 636 | 637 | [sidebar] 638 | -- 639 | [underline]*_Implementation Note_* 640 | 641 | Any platform that does not implement the micro-architectural features related to 642 | a hardware event may hardwire the event value to zero. 643 | -- 644 | 645 | === Debug 646 | The OS-A Server platform includes all the requirements as specified in the 647 | OS-A Common Requirements section plus the following: 648 | 649 | - Implement at least six mcontrol6 triggers that can support matching on PC 650 | (select=0, execute=1, match=0) with timing=0 and full support for mode 651 | filtering (vs, vu, m, s, u) for all supported modes and support for textra as 652 | above 653 | * Rationale: Other architectures have found that 4 breakpoints are 654 | insufficient in more capable systems and recommend 6. 655 | - If system bus access is implemented then accesses must be coherent with 656 | respect to all harts connected to the DM 657 | * Rationale: Debuggers must be able to view memory coherently. 658 | 659 | === Interrupts 660 | The OS-A Server platform must support the interrupt requirements as specified 661 | in the OS-A Common Requirements Interrupts section 662 | <> plus the following: 663 | 664 | * The H-extension implemented by each hart must support GEILEN = 5 or more. 665 | * Per-hart AIA IMSIC devices. 666 | ** Must support at least 255 distinct interrupt identities. 667 | ** Must support IPRIOLEN = 8. 668 | * EIID and IID fields of AIA APLIC devices must be at least 8 bits wide 669 | matching the number of interrupt identities supported by AIA IMSIC. 670 | 671 | [underline]*_Recommendation_* + 672 | Platforms should implement at least 5 guest interrupt files. More guest 673 | interrupt files allow for better VM oversubscription on the same hart. 674 | 675 | === Boot Process 676 | ==== Firmware 677 | The boot and system firmware for the server platforms must support UEFI as 678 | defined in the section 2.6.1 of the UEFI Specification <> with some 679 | additional requirements described in following sub-sections. 680 | 681 | ===== UEFI Configuration Tables 682 | The platforms are required to provide following tables: 683 | 684 | * *EFI_ACPI_20_TABLE_GUID* ACPI configuration table which is at version 6.4+ or 685 | newer with HW-Reduced ACPI model. 686 | * *SMBIOS3_TABLE_GUID* SMBIOS table which conforms to version 3.4 or later. 687 | 688 | ===== UEFI Protocol Support 689 | The UEFI protocols listed below are required to be implemented. 690 | 691 | .Additional UEFI Protocols 692 | [cols="3,1,2", width=95%, align="center", options="header"] 693 | |=== 694 | |Protocol | UEFI Section | Note 695 | |EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL | 14 | For PCIe support 696 | |EFI_PCI_IO_PROTOCOL | 14.4 | For PCIe support 697 | |RISCV_EFI_BOOT_PROTOCOL | <> | To pass boot hart ID 698 | |=== 699 | 700 | ==== Hardware Discovery Mechanisms 701 | - Platforms must support the Unified Discovery specification for all pre-boot 702 | information population <>. 703 | 704 | ===== ACPI 705 | ACPI is the required mechanism for the hardware discovery and configuration. 706 | Server platforms are required to adhere to the RISC-V ACPI Platform Requirements 707 | Specification <>. Platform firmware must support ACPI and 708 | the runtime OS environment must use ACPI for device discovery and configuration. 709 | 710 | ===== SMBIOS 711 | The System Management BIOS (SMBIOS) table is required for the platform 712 | conforming to server extension. The SMBIOS records provide basic hardware and 713 | firmware configuration information used widely by the platform management 714 | applications. 715 | 716 | The SMBIOS table is identified using *SMBIOS3_TABLE_GUID* in UEFI configuration 717 | table. The memory type used for the SMBIOS table is required to be of type 718 | *EfiRuntimeServicesData*. 719 | 720 | In addition to the conformance guidelines as mentioned in *ANNEX A / 6.2* of 721 | the SMBIOS specification 3.4.0, below additional structures are required. 722 | 723 | .Required SMBIOS structures 724 | [cols="3,2,2", width=95%, align="center", options="header"] 725 | |=== 726 | |Structure Type | SMBIOS Section | Note 727 | |Management Controller Host Interface (Type 42) | 7.43 | Required for 728 | Redfish Host Interface. 729 | |Processor Additional Information (Type 44) | 7.45 | This 730 | structure provides the additional information of RISC-V processor 731 | characteristics and HART hardware features discovered during the firmware boot 732 | process. 733 | |=== 734 | 735 | === Runtime services 736 | The OS-A Server platform includes all the runtime services requirements as 737 | specified in the OS-A Common Requirements Runtime Services section plus the 738 | following. 739 | 740 | ==== UEFI 741 | The UEFI run time services listed below are required to be implemented. 742 | 743 | .Required UEFI Runtime Services 744 | [cols="3,2,3", width=95%, align="center", options="header"] 745 | |=== 746 | |Service | UEFI Section | Note 747 | |GetVariable | 8.2 | 748 | |GetNextVariableName | 8.2 | 749 | |SetVariable | 8.2 | A dedicated storage for firmware is 750 | required so that there is no conflict in access by both firmware and the OS. 751 | |QueryVariableInfo | 8.2 | 752 | |GetTime | 8.3 | System Date/Time accessed by the 753 | OS and firmware.<> 754 | |SetTime | 8.3 | System Date/Time set by the 755 | OS and firmware.<> 756 | |GetWakeupTime | 8.3 | Interface is required to be 757 | implemented but it can return EFI_UNSUPPORTED.<> 759 | |SetWakeupTime | 8.3 | Interface is required to be 760 | implemented but it can return EFI_UNSUPPORTED.<> 762 | |SetVirtualAddressMap | 8.4 | 763 | |ConvertPointer | 8.4 | 764 | |GetNextHighMonotonicCount | 8.5 | 765 | |ResetSystem | 8.5 | If SBI SRST implementation is 766 | also available, the OS should not use the SBI interface directly but use this 767 | UEFI interface. 768 | |UpdateCapsule | 8.5 | Interface is required to be 769 | implemented but it can return EFI_UNSUPPORTED. 770 | |QueryCapsuleCapabilities | 8.5 | Interface is required to be 771 | implemented but it can return EFI_UNSUPPORTED. 772 | |=== 773 | 774 | === System Peripherals 775 | The OS-A Server platform includes all the system peripheral requirements as 776 | specified in the OS-A Common Requirements System Peripherals section plus 777 | the added requirements in this section. 778 | 779 | ==== Watchdog Timers 780 | Implementation of a two-stage watchdog timer, as defined in the RISC-V Watchdog 781 | Timer Specification<> is required. Software must 782 | periodically refresh the watchdog timer, otherwise a first-stage watchdog 783 | timeout occurs. If the watchdog timer remains un-refreshed for a second period, 784 | then a second-stage watchdog timeout occurs. 785 | 786 | If a first-stage watchdog timeout occurs, a Supervisor-level interrupt request 787 | is generated and sent to the system interrupt controller, targeting a specific 788 | hart. 789 | 790 | If a second-stage watchdog timeout occurs, a system-level interrupt request is 791 | generated and sent to a system component more privileged than Supervisor-mode 792 | such as: 793 | 794 | - The system interrupt controller, with a Machine-level interrupt request 795 | targeting a specific hart. 796 | - A platform management processor. 797 | - Dedicated reset control logic. 798 | 799 | The resultant action taken is platform-specific. 800 | 801 | ==== System Date/Time[[SystemDateTime]] 802 | In order to facilitate server manageability, server extension platform is 803 | required to provide the mechanism to maintain system date/time for UEFI 804 | runtime Time service. + 805 | 806 | - UEFI Runtime Time Service 807 | * GetTime() + 808 | Must be implemented by firmware and is not allowed to return 809 | EFI_UNSUPPORTED. 810 | * SetTime(), GetWakeupTime() and SetWakeupTime() + 811 | These Time services must be implemented but allowed to return 812 | EFI_UNSUPPORTED if the platform doesn't require the features or the system 813 | date/time mechanism doesn’t have the capabilities. 814 | 815 | ==== PCIe 816 | Platforms are required to support at least PCIe Base Specification Revision 1.1 817 | <>. 818 | 819 | ===== PCIe Config Space 820 | * Platforms must support access to the PCIe config space via ECAM as described 821 | in the PCIe Base specification. 822 | * The entire config space for a single PCIe domain must be accessible via a 823 | single ECAM I/O region. 824 | * Platform firmware must implement the MCFG table as listed in the ACPI System 825 | Description Tables above to allow the operating systems to discover the 826 | supported PCIe domains and map the ECAM I/O region for each domain. 827 | * Platform software must configure ECAM I/O regions such that the effective 828 | memory attributes are that of a PMA I/O region (i.e. strongly-ordered, 829 | non-cacheable, non-idempotent). 830 | * If the platform software (for e.g OS) re-enumerates the PCIe topology then it 831 | is required that the underlying fabric routing is always correctly preserved. 832 | 833 | ===== PCIe Memory Space 834 | Platforms are required to map PCIe address space directly in the system address 835 | space. The physical addresses used by the hart for outbound accesses must not undergo 836 | any further translation/offsetting and must be sent to the PCIe device unmodified. 837 | 838 | The unmodified physical address in an inbound accesses may optionally be presented to an 839 | IOMMU for address tranlation. If no IOMMU is employed for address translation then the 840 | unmodified physical address sent by the device must be used for accessing system memory. 841 | If an IOMMU is employed then the unmodified translated address provided by the IOMMU must 842 | be used for accessing system memory. 843 | 844 | * PCIe Outbound Memory + 845 | PCIe devices and bridges/switches frequently implement BARs which only support 846 | 32-bit addressing or support 64 bit addressing but do not support prefetchable 847 | memory. To support mapping of such BARs, platforms are required to reserve 848 | some space below 4G for each root port present in the system. 849 | 850 | [sidebar] 851 | -- 852 | [underline]*_Implementation Note_* + 853 | Platform software would likely configure these per root port regions such that 854 | their effective memory attributes are that of a PMA I/O region (i.e. 855 | strongly-ordered, non-cacheable, non-idempotent). Platforms would likely also 856 | reserve some space above 4G to map BARs that support 64 bit addressing and 857 | prefetchable memory which could be configured by the platform software as either 858 | I/O or memory. 859 | -- 860 | 861 | * PCIe Inbound Memory + 862 | For security reasons, platforms with M-mode must provide a mechanism controlled 863 | by M-mode software to restrict inbound PCIe accesses from accessing regions of 864 | address space intended to be accessible only to M-mode software. 865 | 866 | [sidebar] 867 | -- 868 | [underline]*_Implementation Note_* + 869 | Such an access control mechanism could be analogous to the per-hart PMP 870 | as described in the RISC-V Privileged Architectures specification. 871 | -- 872 | 873 | ===== PCIe Interrupts 874 | * Platforms must support Message Signaled (MSI or MSI-X) Interrupts. 875 | * Platforms may optionally support INTx interrupt signaling. 876 | * Following are the requirements for INTx interrupt signaling if supported: 877 | ** For each root port in the system, the platform must map all the INTx 878 | virtual wires to four distinct sources at the APLIC. Each of these sources 879 | must be configured as Level0 as described in Table 4.2 (Encoding of the SM 880 | (Source Mode) field) of the RISC-V AIA specification. 881 | ** Platform firmware must implement the _PRT as described in section 6.2.13 of 882 | ACPI Specification to describe the mapping of interrupt pins and the 883 | corresponding interrupt minor identities at the Hart. 884 | ** If interrupt generation for correctable/fatal/non-fatal error messages is 885 | enabled via the root error command register of the AER capability and the root 886 | port does not support MSI/MSI-X capability, then the platform is required to 887 | generate an INTx interrupt via the APLIC. 888 | * Following are the requirements for MSI: 889 | ** As per the RISC-V AIA specification, since the number 0 is not a valid 890 | interrupt identity, the platform software is required to ensure that MSI data 891 | value assigned to a PCIe function is never 0. For e.g for a PCIe function which 892 | requests 16 MSI vectors the minimum MSI data value assigned by the platform 893 | software can be 0x10 so that the function can use lower 4 bits to assert each 894 | of the 16 vectors. 895 | 896 | ===== PCIe cache coherency 897 | Memory that is cacheable by harts may not be kept coherent by hardware when 898 | PCIe transactions to that memory are marked with a No_Snoop bit of one. 899 | On platforms that honor the No_Snoop bit, software must manage coherency on 900 | such memory, otherwise, software and DMA operations are hardware coherent and 901 | software coherency management is not required. 902 | 903 | ===== PCIe Topology 904 | Platforms are required to implement at least one of the following topologies 905 | and the components required in that topology. 906 | 907 | [#fig_intro1] 908 | .PCIe Topologies 909 | image::pcie-topology.png[width=524,height=218] 910 | 911 | * Host Bridge + 912 | Following are the requirements for host bridges: 913 | 914 | ** Any read or write access by a hart to an ECAM I/O region must be converted 915 | by the host bridge into the corresponding PCIe config read or config write 916 | request. 917 | ** Any read or write access by a hart to a PCIe outbound region must be 918 | forwarded by the host bridge to a BAR or prefetch/non-prefetch memory window, 919 | if the address falls within the region claimed by the BAR or prefetch/ 920 | non-prefetch memory window. Otherwise the host bridge must return an error. 921 | 922 | ** Host bridge must return all 1s in the following cases: 923 | *** Config read to non existent functions and devices on root bus. 924 | *** Config reads that receive Unsupported Request response from functions and 925 | devices on the root bus. 926 | * Root ports + 927 | Following are the requirements for root ports. 928 | ** Root ports must appear as PCI-PCI bridge to software. 929 | ** Root ports must implement all registers of Type 1 header. 930 | ** Root ports must implement all capabilities specified in the PCIe Base 931 | specification for a root port. 932 | ** Root ports must forward type 1 configuration access when the bus number in 933 | the TLP is greater than the root port's secondary bus number and less than or 934 | equal to the root port's subordinate bus number. 935 | ** Root ports must convert type 1 configuration access to a type 0 936 | configuration access when bus number in the TLP is equal to the root port's 937 | secondary bus number. 938 | ** Root ports must respond to any type 0 configuration accesses it receives. 939 | ** Root ports must forward memory accesses targeting its prefetch/non-prefetch 940 | memory windows to downstream components. If address of the transaction does not 941 | fall within the regions claimed by prefetch/non-prefetch memory windows then 942 | the root port must generate a Unsupported Request. 943 | ** Root port requester id or completer id must be formed using the bdf of the 944 | root port. 945 | ** The root ports must support the CRS software visibility. 946 | ** The root port must implement the AER capability. 947 | ** Root ports must return all 1s in the following cases: 948 | *** Config read to non existent functions and devices on secondary bus. 949 | *** Config reads that receive Unsupported Request from downstream components. 950 | *** Config read when root port's link is down. 951 | 952 | * RCiEP + 953 | All the requirements for RCiEP in the PCIe Base specification must be 954 | implemented. 955 | In addition the following requirements must be met: 956 | ** If RCiEP is implemented then RCEC must be implemented as well. All 957 | requirements for RCEC specified in the PCIe Base specification must be 958 | implemented. RCEC is required to terminate the AER and PME messages from RCiEP. 959 | 960 | ===== PCIe Device Firmware 961 | PCI expansion ROM code type 3 (UEFI) image must be provided by PCIe device 962 | platform according to PCI Firmware Specification <> if that 963 | PCIe device is utilized during UEFI firmware boot process. The image stored in 964 | PCI expansion ROM is a UEFI driver that must be compliant with UEFI 965 | specification <> 14.4.2 PCI Option ROMs. 966 | 967 | === Security 968 | The OS-A Server platform includes all the security requirements as 969 | specified in the OS-A Common Requirements security section plus the following: 970 | 971 | * Support for some form of Secure Boot, as a means to ensure the integrity of 972 | platform firmware and software, is required. Flexibility is provided as 973 | to the many details and implementation approaches. Future platform specs are 974 | expected to standardize some or many of these aspects. For now, it is 975 | recommended that the following security properties are met: 976 | ** The secure boot process is rooted in dedicated hardware. 977 | ** Cryptographic algorithms are independently validated or certified for 978 | implementation correctness. 979 | ** The combination of key length and cryptographic algorithm provides suitable 980 | security strength. 981 | ** A cryptographically secure entropy source (or multiple entropy sources) is 982 | used in key material generation and monitoring of entropy source’s health is 983 | implemented. 984 | ** Critical security parameters are securely stored and only accessible with 985 | appropriate privileges. 986 | ** Authorization is required for any modifications to the platform secure boot 987 | configuration. 988 | ** It is clearly understood what aspects of the platform boot process are 989 | protected by secure boot. 990 | 991 | ** If M-mode is supported in the platform, all machine mode assets, such as 992 | code and data, shall be protected from all non-machine mode accesses from the 993 | harts in the system. Additionally, I/O agent access protection must be 994 | required within the system to protect machine mode assets. Therefore, the 995 | following requirements are mandatory for platforms with M-mode: 996 | 997 | *** Platform must provide a protection mechanism from non-machine mode hart 998 | transactions that precisely traps if violated. 999 | *** Platform must provide a protection mechanism from I/O agents manipulating 1000 | or accessing machine mode assets. 1001 | 1002 | === RAS 1003 | All the below mentioned RAS features are required for the OS-A platform server 1004 | extension: 1005 | 1006 | * Main memory must be protected with SECDED-ECC or a stronger/advanced method of protection. + 1007 | * Cache structures must be protected. The protection mechanisms may include single-bit/multi-bit 1008 | error detection/correction schemes. 1009 | * There must be memory-mapped RAS registers associated with these protected 1010 | structures to log detected errors with information about the type and location 1011 | of the error. + 1012 | * The platform must support the APEI specification to convey all error 1013 | information to OSPM. + 1014 | * Correctable errors must be reported by hardware and either be corrected or 1015 | recovered by hardware, transparent to system operation and to software. + 1016 | * Hardware must provide status of these correctable errors via RAS registers. + 1017 | * Uncorrectable errors must be reported by the hardware via RAS error 1018 | registers for system software to take the needed corrective action. + 1019 | * Attempted use of corrupted uncorrectable data must result in an exception 1020 | with a distinguishing custom exception code; preferably a precise exception 1021 | on that instruction if possible. + 1022 | * The platform should provide the capability to configure RAS 1023 | errors to trigger firmware-first or OS-first error interrupt. + 1024 | * Errors logged in RAS registers must be able to generate an interrupt request 1025 | to the system interrupt controller that may be directed to either M-mode or 1026 | S/HS-mode for firmware-first or OS-first error reporting. + 1027 | * If the RAS error is handled by firmware, the firmware should be able 1028 | to choose to expose the error to S/HS mode for further processing or 1029 | just hide the error from S/HS software. + 1030 | * If the RAS event is configured as the firmware first model, the platform 1031 | should be able to trigger the highest priority of M-mode interrupt to all HARTs 1032 | in the physical RV processor. + 1033 | * Logging and/or reporting of errors can be masked. + 1034 | * PCIe AER capability is required. + 1035 | 1036 | // RVM-CSI Platform 1037 | == RVM-CSI Platform 1038 | 1039 | === Scope 1040 | The RVM-CSI Platform specification aims to apply to a range of embedded platforms. 1041 | In this case embedded platforms range from hand coded bare metal assembly 1042 | all the way to to embedded operating systems such as 1043 | https://www.zephyrproject.org[Zephyr] and embedded Linux. 1044 | 1045 | This specification has two competing interests. On one hand embedded software 1046 | will be easier to write and port if all the embedded hardware is similar. On 1047 | the other hand vendors want to differentiate their product and reuse existing 1048 | IP and SoC designs. 1049 | 1050 | Due to this, the RVM-CSI Platform specification has both required and 1051 | recommended components. All required components must be met in order to meet 1052 | this specification. 1053 | It's strongly encouraged that all recommended components are met as well, 1054 | although they do not have to in order to meet the specification. 1055 | 1056 | === Base 1057 | ==== Architecture 1058 | The RVM-CSI Platform must comply with the RVM22M profile defined by the RISC-V 1059 | profiles specification <>. 1060 | 1061 | ==== Interrupt Controller 1062 | Embedded systems are recommended to use a spec compliant PLIC <>, 1063 | a spec compliant CLIC <> or both a CLIC and and PLIC. 1064 | 1065 | If using just a PLIC the system must continue to use the original basic 1066 | `xsip`/`xtip`/`xeip` signals in the `xip` register to indicate pending 1067 | interrupts. 1068 | If using the CLIC then both the original basic and CLIC modes of interrupts 1069 | must be supported. 1070 | 1071 | Embedded systems cannot use a non-compliant interrupt controller and still 1072 | call it a PLIC or CLIC. 1073 | 1074 | ==== Timer Support 1075 | The RVM-CSI Platform must implement one or more RISC-V ACLINT MTIMER 1076 | <> devices. This will provide the `mtime` and `mtimecmp` memory 1077 | mapped registers as required by the RISC-V privilege specification 1078 | <>. 1079 | 1080 | The `mcounteren`.TM and `scounteren`.TM bits _must not_ be hardwired, 1081 | regardless as to whether accesses to the `time` CSR are implemented 1082 | directly or via traps. 1083 | 1084 | ==== Memory Map 1085 | It is recommended that main memory and loadable code (not ROM) start at 1086 | address `0x8000_0000`. 1087 | 1088 | // PMP extension for RVM-CSI Platform 1089 | === Physical Memory Protection (PMP) Extension 1090 | It is recommended that any system that implement more than just machine mode 1091 | also implement PMP support. 1092 | 1093 | When PMP is supported it is recommended to include at least 4 regions, although 1094 | if possible more should be supported to allow more flexibility. Hardware 1095 | implementations should aim for supporting at least 16 PMP regions. 1096 | 1097 | [bibliography] 1098 | == References 1099 | 1100 | * [[[spec_uefi,1]]] link:https://uefi.org/sites/default/files/resources/UEFI_Spec_2_9_2021_03_18.pdf[UEFI Specification], Version: v2.9 1101 | * [[[spec_dt,2]]] link:https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.3[Devicetree Specification], Version: v0.3 1102 | * [[[spec_unpriv,3]]] link:https://github.com/riscv/riscv-isa-manual/releases/download/draft-20210726-2026469/riscv-spec.pdf[RISC-V Unprivileged Architecture Specification], Version:20191214-draft 1103 | * [[[spec_priv,4]]] link:https://github.com/riscv/riscv-isa-manual/releases/download/draft-20210726-2026469/riscv-privileged.pdf[RISC-V Privileged Architecture Specification], Version: v1.12-draft 1104 | * [[[spec_priv_sstc,5]]] link:https://lists.riscv.org/g/tech-privileged/message/404[RISC-V Privleged Architecture Sstc Extension], Version: Draft 1105 | * [[[spec_sbi,6]]] link:https://github.com/riscv/riscv-sbi-doc/blob/master/riscv-sbi.adoc[RISC-V SBI Specification], Version: v0.3 1106 | * [[[spec_plic,7]]] link:https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc[RISC-V PLIC Specification], Version: v1.0-draft 1107 | * [[[spec_clic,8]]] link:https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.adoc[RISC-V CLIC Specification], Version: draft-bc89a5e3d61d 1108 | * [[[spec_aclint,9]]] link:https://github.com/riscv/riscv-aclint/releases/download/v1.0-draft2/riscv-aclint-1.0-draft2.pdf[RISC-V ACLINT Specification], Version: v1.0-draft2 1109 | * [[[spec_aia,10]]] link:https://github.com/riscv/riscv-aia/releases/download/0.2-draft.24/riscv-interrupts-024.pdf[RISC-V AIA Specification], Version: v0.2-draft.24 1110 | * [[[spec_profiles,11]]] link:https://github.com/riscv/riscv-profiles/blob/master/profiles.adoc[RISC-V Profiles Specification], Version: draft-8e8951987e2a 1111 | * [[[spec_proc_call,12]]] link:https://github.com/riscv/riscv-elf-psabi-doc[RISC-V Calling Convention specification], Version: 1.0-rc1 1112 | * [[[spec_elf,13]]] link:https://github.com/riscv/riscv-elf-psabi-doc[RISC-V ELF specification], Version: 1.0-rc1 1113 | * [[[spec_dwarf,14]]] link:https://github.com/riscv/riscv-elf-psabi-doc[RISC-V DWARF specification], Version: 1.0-rc1 1114 | * [[[spec_ebbr,15]]] link:https://arm-software.github.io/ebbr/[EBBR Specification], Version: v2.0.1 1115 | * [[[spec_acpi,16]]] link:https://uefi.org/sites/default/files/resources/ACPI_Spec_6_4_Jan22.pdf[ACPI Specification], Version: v6.4 1116 | * [[[spec_apei,17]]] link:https://uefi.org/specs/ACPI/6.4/18_ACPI_Platform_Error_Interfaces/ACPI_PLatform_Error_Interfaces.html[APEI Specification], Version: v6.4 1117 | * [[[spec_smbios,18]]] link:https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.4.0.pdf[SMBIOS Specification], Version: v3.4.0 1118 | * [[[spec_pci_firmware,19]]] https://pcisig.com/specifications/conventional/pci_firmware[PCI Firmware Specification], Version: 3.3 1119 | * [[[spec_unified_discovery,20]]] Unified Discovery Specification (TBD) 1120 | * [[[spec_riscv_acpi,21]]] link:https://github.com/riscv/riscv-acpi/blob/master/riscv-acpi-platform-req.adoc[RISC-V ACPI Platform Requirements Specification], Version: Draft-20210812 1121 | * [[[spec_riscv_watchdog,22]]] link:https://github.com/riscv-non-isa/riscv-watchdog/blob/main/riscv-watchdog.adoc[RISC-V Watchdog Timer Specification], Version: Version 1.0 1122 | * [[[spec_riscv_platform_policy,23]]] link:https://docs.google.com/document/d/1U5qLoztZpCRSnw2s8tx4rB0SFPMQ27Svrr9jWRsOziY/edit[RISC-V Platform Platform Policy], Version: 1.0 1123 | * [[[spec_pcie_sig,24]]] link:https://pcisig.com/specifications[PCIe Base Specification Revision], Revision: 1.1 1124 | * [[[spec_riscv_uefi,25]]] link:https://github.com/riscv-non-isa/riscv-uefi/releases/download/1.0-rc2/RISCV_UEFI_PROTOCOL-spec.pdf[RISC-V UEFI Protocol Specification], Version: 1.0-rc2 1125 | -------------------------------------------------------------------------------- /riscv-platform-spec.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscvarchive/riscv-platform-specs/1e93c488c78acd19572b3ae9ae3940ce12f32e23/riscv-platform-spec.pdf --------------------------------------------------------------------------------