├── .github ├── dependabot.yml └── workflows │ └── build-pdf.yml ├── .gitignore ├── .gitmodules ├── LICENSE ├── Makefile ├── README.md ├── gap-analysis.adoc ├── media └── image1.png ├── pointer-masking-proposal.adoc ├── zjid ├── background.adoc ├── bibliography.adoc ├── colophon.adoc ├── header.adoc ├── id-consistency-proposal.pdf ├── index.adoc ├── instructions.adoc ├── introduction.adoc └── usage.adoc ├── zjpm-spec.pdf └── zjpm ├── background.adoc ├── bibliography.adoc ├── colophon.adoc ├── contributors.adoc ├── header.adoc ├── instructions.adoc └── introduction.adoc /.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 | -------------------------------------------------------------------------------- /.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 | create_release: 8 | description: 'Create a new RISC-V ISA release if set to true' 9 | required: false 10 | default: 'false' 11 | target_branch: 12 | description: 'Target Branch' 13 | required: true 14 | default: 'main' 15 | release_notes: 16 | description: 'Release Notes' 17 | required: false 18 | pull_request: 19 | push: 20 | branches: 21 | - main 22 | jobs: 23 | build: 24 | runs-on: ubuntu-latest 25 | 26 | steps: 27 | # Step 1: Checkout the repository 28 | - name: Checkout repository 29 | uses: actions/checkout@v3 30 | with: 31 | submodules: 'recursive' 32 | 33 | # Step 2: Pull the latest RISC-V Docs container image 34 | - name: Pull Container 35 | run: docker pull riscvintl/riscv-docs-base-container-image:latest 36 | 37 | # Step 3: Build Files 38 | - name: Build Files 39 | run: make 40 | env: 41 | VERSION: v${{ github.event.inputs.version }} 42 | REVMARK: ${{ github.event.inputs.revision_mark }} 43 | 44 | # Step 4: Upload the built PDF files as a single artifact 45 | - name: Upload Build Artifacts 46 | uses: actions/upload-artifact@v3 47 | with: 48 | name: Build Artifacts 49 | path: ${{ github.workspace }}/*.pdf 50 | retention-days: 30 51 | 52 | # Create Release 53 | - name: Create Release 54 | uses: softprops/action-gh-release@v1 55 | with: 56 | files: ${{ github.workspace }}/*.pdf 57 | tag_name: v${{ github.event.inputs.version }} 58 | name: Release ${{ github.event.inputs.version }} 59 | draft: ${{ github.event.inputs.draft }} 60 | prerelease: ${{ github.event.inputs.prerelease }} 61 | env: 62 | GITHUB_TOKEN: ${{ secrets.GHTOKEN }} 63 | if: github.event_name == 'workflow_dispatch' 64 | # This condition ensures this step only runs for workflow_dispatch events. 65 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | docs-templates 2 | docs-templates/** 3 | zjid-spec.pdf 4 | zjid/images/risc-v_logo.png 5 | zjid/images/backpage.png 6 | zjpm-spec.pdf 7 | zjpm/images/risc-v_logo.png 8 | zjpm/images/backpage.png 9 | -------------------------------------------------------------------------------- /.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 | 397 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ 2 | riscvintl/riscv-docs-base-container-image:latest 3 | 4 | HEADER_SOURCE := zjpm/header.adoc 5 | PDF_RESULT := zjpm-spec.pdf 6 | 7 | ASCIIDOCTOR_PDF := asciidoctor-pdf 8 | OPTIONS := --trace \ 9 | -a compress \ 10 | -a mathematical-format=svg \ 11 | -a pdf-fontsdir=docs-resources/fonts \ 12 | -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ 13 | --failure-level=ERROR 14 | REQUIRES := --require=asciidoctor-diagram 15 | 16 | .PHONY: all build clean build-container build-no-container 17 | 18 | all: build 19 | 20 | #zjid-spec.pdf: zjid/*.adoc 21 | # asciidoctor-pdf \ 22 | --attribute=mathematical-format=svg \ 23 | --attribute=pdf-fontsdir=docs-resources/fonts \ 24 | --attribute=pdf-theme=docs-resources/themes/riscv-pdf.yml \ 25 | --failure-level=ERROR \ 26 | --out-file=$@ \ 27 | zjid/header.adoc 28 | 29 | build: 30 | @echo "Checking if Docker is available..." 31 | @if command -v docker >/dev/null 2>&1 ; then \ 32 | echo "Docker is available, building inside Docker container..."; \ 33 | $(MAKE) build-container; \ 34 | else \ 35 | echo "Docker is not available, building without Docker..."; \ 36 | $(MAKE) build-no-container; \ 37 | fi 38 | 39 | build-container: 40 | @echo "Starting build inside Docker container..." 41 | $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" 42 | @echo "Build completed successfully inside Docker container." 43 | 44 | build-no-container: 45 | @echo "Starting build..." 46 | $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) 47 | @echo "Build completed successfully." 48 | 49 | clean: 50 | @echo "Cleaning up generated files..." 51 | rm -f $(PDF_RESULT) 52 | @echo "Cleanup completed." 53 | 54 | #zjpm-spec.pdf: zjpm/*.adoc 55 | # asciidoctor-pdf \ 56 | --attribute=mathematical-format=svg \ 57 | --attribute=pdf-fontsdir=docs-resources/fonts \ 58 | --attribute=pdf-theme=docs-resources/themes/riscv-pdf.yml \ 59 | --failure-level=ERROR \ 60 | --out-file=$@ \ 61 | zjpm/header.adoc 62 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # *RISC-V J Extension* 2 | 3 | ## Charter 4 | 5 | The RISC-V J extension aims to make RISC-V an attractive target for languages that are traditionally interpreted or JIT compiled, or which require large runtime libraries or language- level virtual machines. Examples include (but are not limited to) C#, Go, Haskell, Java, JavaScript, OCaml, PHP, Python, R, Ruby, Scala, Smalltalk or WebAssembly. 6 | 7 | Typical features of these languages include garbage collection, dynamic typing and dynamic dispatch, transparent boxing of primitive values, and reflection. This provides a very wide scope for possible approaches and, as such, the working group will follow a two-pronged strategy investigating both immediate gains and longer-term more experimental ideas concurrently. Existing attempts to implement JIT-compiled languages on RISC-V have highlighted some places where better instruction density is possible, and these should fall into an early version of the specification. 8 | 9 | Instructions intended to accelerate common JIT’d instruction sequences may be optional within the J extension, with the expectation that software will test for their presence before determining which code sequence to generate. This also provides scope for additions that are only appropriate for a subset of microarchitectures. For example, there is increasing interest in running JavaScript on IoT devices, but acceleration for simple low-power in-order pipelines with constrained memory may be wholly inappropriate for large application cores. 10 | -------------------------------------------------------------------------------- /gap-analysis.adoc: -------------------------------------------------------------------------------- 1 | # RISC-V J Extension Gap Analysis 2 | 3 | *Contributors*: Martin Maas, Adam Zabrocki, Members of the RISC-V J Extension Group 4 | 5 | *Status*: Development 6 | 7 | *Summary*: This document captures an analysis of how managed runtimes can benefit from support in RISC-V. The goal is to map these use cases to either existing RISC-V mechanisms such as memory tagging, or to propose new mechanisms. The document aims to cover a broad range of systems (not limited to managed runtimes but also including, e.g., the Linux kernel). 8 | 9 | ## How to Contribute 10 | 11 | To contribute, you or your company must be a RISC-V International member (see link:https://riscv.org/specifications/contribute/[here] for more details). Please submit changes to this document as pull request against this repository. Please feel free to add yourself to the list of contributors, right before "Members of the RISC-V J Extension Group". 12 | 13 | If you are planning to start working on an area, you can add a note to the section stating "NOTE: WIP - ". This will help others interested in this area find out who else is working on it. 14 | 15 | Each section includes a list of remaining TODO items that are not yet being worked on. This is a good starting point if you are interested in contributing. If you have any questions, please reach out to the group at tech-j-ext@lists.riscv.org. 16 | 17 | ## GC Barriers 18 | 19 | For each runtime system, we analyze which GC barriers are present, how they are implemented, and estimate what the relative benefit would be of optimizing them. 20 | 21 | ### OpenJDK 22 | 23 | NOTE: WIP - Rivos 24 | 25 | ### V8 26 | 27 | NOTE: WIP - Martin Maas 28 | 29 | ### BPF 30 | 31 | NOTE: WIP - Ian Rogers, Adam Zabrocki 32 | 33 | ### Remaining TODO Items 34 | 35 | BPF, SpiderMonkey, Mono, Golang, ART, Mojo Python JIT, R, Wasm, WAMR, OpenJ9 36 | 37 | ## Linux Kernel 38 | 39 | NOTE: WIP - Ian Rogers, Adam Zabrocki 40 | 41 | ### Remaining TODO Items 42 | 43 | RCU, Restartable Sequences 44 | 45 | ## Remaining TODO Areas 46 | 47 | Rust (unsafe, ownership management), Instruction barriers, Return barriers, Thread confinement, Type Checks, Dynamic Dispatch, Object Tagging for Debuggers, Distributed Shared Memory 48 | -------------------------------------------------------------------------------- /media/image1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscv/riscv-j-extension/e086fff37263399c6038440ada2805237a7d6e16/media/image1.png -------------------------------------------------------------------------------- /pointer-masking-proposal.adoc: -------------------------------------------------------------------------------- 1 | [[risc-v-pointer-masking-proposal]] 2 | 3 | # RISC-V Pointer Masking proposal 4 | 5 | RISC-V ISA Specification. Version: v0.1-draft. 6 | 7 | _Adam Zabrocki_, _Lee Campbell_, _Martin Maas_, _RISC-V TEE_ and _J Extension Task Groups_ 8 | 9 | **Contributors: ** Jecel Assumpcao, Allen Baum, Paul Donahue, Greg Favor, Andy Glew, John Ingalls, Christos Kotselidis, Ian Rogers, Josh Scheid, Kostya Serebryany, Boris Shingarov, Foivos Zakkak, Members of the TEE and J Extension Task Groups 10 | 11 | [[introduction]] 12 | ## Introduction 13 | 14 | RISC-V Pointer Masking (PM) is a feature which provides a possibility of implementing "memory tagging" by ignoring various bits (defined by mask) of the [.underline]#_effective address_# (virtual or physical) on RV128, RV64 and RV32. 15 | 16 | [.underline]#_Effective address_# is an address generated by the address generation logic before it is sent to the memory subsystem. As such, there is no special handling of physical vs. virtual memory at the software level. 17 | 18 | Memory tagging (MT) is a technique which can significantly improve the memory safety state of any application (including code running in more privileged modes). MT can be fully implemented in the hardware or partially hardware assisted. However, both implementations require a PM feature to be enabled to not overwhelm the performance. 19 | 20 | General idea of MT is based on assigning a tag to every granule of memory (a small, e.g. 16-byte, naturally aligned memory region). All accesses to memory must be made via a pointer with the correct tag. Use of an incorrect tag is noted and the monitor software can choose what to do with such a situation (e.g. could be killing the process, or just report it to the user immediately). To be able to store the tag in every memory pointer (poisoning the pointer) and correctly using it in running applications without significant performance impact, PM is necessary. 21 | 22 | This document proposes an extension for RISC-V called PM (Pointer Masking) which in the future might be enhanced for implementing a full hardware memory tagging. 23 | 24 | [[proposal]] 25 | ## Proposal 26 | 27 | We propose to add: 28 | 29 | * new PM configuration CSR register called _**MMTE**_ (Memory Tagging Extension) 30 | * new PM pointer masking CSR register for each privilege mode called _**MPMMASK**_ (Pointer Masking Mask) 31 | * new PM pointer base CSR register for each privilege mode called _**MPMBASE**_ (Pointer Masking Base) 32 | 33 | Restricted views of the _**mmte**_ register appear as the _**smte**_, _**vsmte**_ and _**umte**_ registers in the HS/S-mode, VS-mode and (V)U-mode ISAs respectively. 34 | 35 | Each privilege mode has own copy of pointer masking CSR register. It appears as the _**mpmmask**_, _**spmmask**_, _**vspmmask**_ and _**upmmask**_ registers in the M-mode, HS/S-mode, VS-mode and (V)U-mode ISAs, respectively. 36 | 37 | Each privilege mode has its own copy of pointer base CSR register. It appears as the _**mpmbase**_, _**spmbase**_, _**vspmbase**_ and _**upmbase**_ registers in the M-mode, HS/S-mode, VS-mode and (V)U-mode ISAs, respectively. 38 | 39 | The purpose of the _**mpmmask**_ register is to be able to precisely define a mask whose bits of the effective address are ignored. The actual address can be calculated by using requested address and _**mpmmask**_ register. 40 | 41 | Additionally, _**mpmbase**_ register can be defined, allowing to replace those bits of the actual_address which are defined to be masked by _**mpmmask**_. _**mpmbase**_ can be configured to replace only the subset of the masked bits, and the remaining are still ignored and can be used for any purpose (e.g. memory tagging). 42 | 43 | If _**mpmbase**_ register is set (has value other than zero), actual address can be calculated by using requested address, _**mpmmask**_ and _**mpmbase**_ register: 44 | 45 | [source] 46 | .Equation 1. 47 | ---- 48 | actual_address = (requested_address & ~mpmmask) | mpmbase 49 | ---- 50 | 51 | _**mpmbase**_ register can be read-only and hardwired to 0. In such case, the actual address will be calculated only by using requested address and _**mpmmask**_ register. 52 | 53 | When PM extension is enabled, _**mpmmask**_ and _**mpmbase**_ registers allow to implement in-process isolation feature. That feature allows for each thread to be isolated to a given block of the address space. It can be used to isolate untrusted code within a process. A high-level concept can be seen on Picture 1. 54 | 55 | .Picture 1: In-Process isolation leveraging _**mpmmask**_ and _**mpmbase**_ registers 56 | image:media/image1.png[image,width=451,height=394] 57 | 58 | _**MMTE**_ layout can be found in Figure 1a, 1b, 1c and 1d for M, HS/S, VS and (V)U-mode. + 59 | 60 | _**MPMMASK**_ layout can be found in Figure 2a, 2b, 2c and 2d for M, HS/S, VS and (V)U-mode. + 61 | 62 | _**MPMBASE**_ layout can be found in Figure 3a, 3b, 3c and 3d for M, HS/S, VS and (V)U-mode. + 63 | 64 | Table 1 explains the meaning of _PM_ bits for RV32, RV64 and RV128. + 65 | Table 2 explains the meaning of _XS_ bits for RV32, RV64 and RV128. + 66 | Table 3 contains the addresses for the **xMTE**, **xPMBASE** and **xPMMASK** CSRs. + 67 | _**Note**_: Addresses in the Table 3 are preliminary and could be changed during the Opcode and Consistency review. 68 | 69 | :table-caption!: 70 | 71 | [%header, cols=5*] 72 | .Figure 1a: Memory Tagging Extension register (_**mmte**_) M-mode 73 | ,=== 74 | mmte[XLEN-1:12],mmte[11:9],mmte[8:6],mmte[5:3],mmte[2:0] 75 | WPRI,M-mode PM,HS/S-mode PM,(V)U-mode PM,XS bits 76 | ,=== 77 | 78 | [%header, cols=4*] 79 | .Figure 1b: Memory Tagging Extension register (_**smte**_) HS/S-mode 80 | ,=== 81 | smte[XLEN-1:9],smte[8:6],smte[5:3],smte[2:0] 82 | WPRI,HS/S-mode PM,U-mode PM,XS bits 83 | ,=== 84 | 85 | [%header, cols=4*] 86 | .Figure 1c: Memory Tagging Extension register (_**vsmte**_) for VS-mode 87 | ,=== 88 | vsmte[XLEN-1:9],vsmte[8:6],vsmte[5:3],vsmte[2:0] 89 | WPRI,VS-mode PM,VU-mode PM,XS bits 90 | ,=== 91 | 92 | [%header, cols=3*] 93 | .Figure 1d: Memory Tagging Extension register (_**umte**_) for (V)U-mode 94 | ,=== 95 | umte[XLEN-1:6],umte[5:3],umte[2:0] 96 | WPRI,(V)U-mode PM,WPRI 97 | ,=== 98 | 99 | [cols="15%,15%,70%", options="header"] 100 | .Table 1: Meaning of _PM_ bits for RV32, RV64 and RV128 101 | |=========================================================================================================================== 102 | ^|*PM Bits* ^|*Name* ^|*Meaning* 103 | 104 | ^.^| PM[0:0] ^.^| PM.Enabled | 105 | 106 | 0 – PM is disabled (_default_) + 107 | 1 – PM is enabled 108 | 109 | ^.^| PM[1:1] ^.^| PM.Current | 110 | 111 | 0 – _**xPMMASK**_ and _**xPMBASE**_ registers can only be modified by the higher privilege mode (_default_) + 112 | 1 – _**xPMMASK**_ and _**xPMBASE**_ registers can be modified by the same privilege mode + 113 | + 114 | _**Note**_: _PM.Current_ bit for M-mode (mmte[10:10]) is hardwired to 1 115 | 116 | ^.^| PM[2:2] ^.^| PM.Instruction | 117 | 118 | 0 – PM applies to Data accesses only (_default_) + 119 | 1 – PM applies to Instruction and Data accesses + 120 | + 121 | _**Note**_: _PM.Instruction_ bit enables more use-cases. However, implementations can hardwire this bit to 0 if they choose not to implement instruction pointer masking 122 | 123 | |=========================================================================================================================== 124 | 125 | [cols="15%,70%", options="header"] 126 | .Table 2: Meaning of _XS_ bits for RV32, RV64 and RV128 127 | |=========================================================================================================================== 128 | ^|*Status* ^|*Meaning* 129 | ^.^| 0 | PM extension is not used (cannot write to any PM CSRs) 130 | ^.^| 1 | PM CSRs are writeable but have the initial value (0) 131 | ^.^| 2 | Some registers may have non-initial values, but those were saved before (clean) 132 | ^.^| 3 | Some registers have unsaved values (dirty) 133 | |=========================================================================================================================== 134 | 135 | [cols="15%,70%", options="header"] 136 | .Table 3: PM CSRs addresses 137 | |=========================================================================================================================== 138 | ^|*PM CSR name* ^|*Address* 139 | ^.^| MMTE | 0x3c0 140 | ^.^| SMTE | 0x1c0 141 | ^.^| UMTE | 0x4c0 142 | ^.^| VSMTE | 0x2c0 143 | ^.^| MPMMASK | 0x3c1 144 | ^.^| SPMMASK | 0x1c1 145 | ^.^| UPMMASK | 0x4c1 146 | ^.^| VSPMMASK | 0x2c1 147 | ^.^| MPMBASE | 0x3c2 148 | ^.^| SPMBASE | 0x1c2 149 | ^.^| UPMBASE | 0x4c2 150 | ^.^| VPMBASE | 0x2c2 151 | |=========================================================================================================================== 152 | 153 | 154 | [%header, cols=1*] 155 | .Figure 2a: Memory Tagging Extension register (_**mpmmask**_) for M-mode 156 | ,=== 157 | mpmmask[XLEN-1:0] 158 | MASK 159 | ,=== 160 | 161 | [%header, cols=1*] 162 | .Figure 2b: Memory Tagging Extension register (_**spmmask**_) for HS/S-mode 163 | ,=== 164 | spmmask[XLEN-1:0] 165 | MASK 166 | ,=== 167 | 168 | [%header, cols=1*] 169 | .Figure 2c: Memory Tagging Extension register (_**vspmmask**_) for VS-mode 170 | ,=== 171 | vspmmask[XLEN-1:0] 172 | MASK 173 | ,=== 174 | 175 | [%header, cols=1*] 176 | .Figure 2d: Memory Tagging Extension register (_**upmmask**_) for (V)U-mode 177 | ,=== 178 | upmmask[XLEN-1:0] 179 | MASK 180 | ,=== 181 | 182 | //- 183 | 184 | [%header, cols=1*] 185 | .Figure 3a: Memory Tagging Extension register (_**mpmbase**_) for M-mode 186 | ,=== 187 | mpmbase[XLEN-1:0] 188 | BASE 189 | ,=== 190 | 191 | [%header, cols=1*] 192 | .Figure 3b: Memory Tagging Extension register (_**spmbase**_) for HS/S-mode 193 | ,=== 194 | spmbase[XLEN-1:0] 195 | BASE 196 | ,=== 197 | 198 | [%header, cols=1*] 199 | .Figure 3c: Memory Tagging Extension register (_**vspmbase**_) for VS-mode 200 | ,=== 201 | vspmbase[XLEN-1:0] 202 | BASE 203 | ,=== 204 | 205 | [%header, cols=1*] 206 | .Figure 3d: Memory Tagging Extension register (_**upmbase**_) for (V)U-mode 207 | ,=== 208 | upmbase[XLEN-1:0] 209 | BASE 210 | ,=== 211 | 212 | 213 | [[explanation]] 214 | ## Explanation 215 | 216 | _**xMTE**_ register fulfills two-fold function: 217 | 218 | 1. Can only be programmable by more privileged mode (unless PM.Current bit is enabled) + 219 | 2. Performs status register function for the current privilege mode + 220 | 221 | _XS_ bits from **_MMTE_** register are only accessible in M, S and VS-mode. _XS_ field encodes the status of Pointer Masking extension in U and VU-mode. These bits can be checked by a context switch routine to quickly determine whether a state save or restore is required. _XS_ field is automatically updated by the hardware when PM CSR registers are modified. Privileged code can directly modify _XS_ bits to restore previously saved _XS_ status (e.g. by the context restore routine). 222 | _XS_ bits in M-mode are desired for implementation without S-mode for determining how to perform context switch in U-mode. Otherwise, _XS_ bits in M-mode might mirror _XS_ bits in (V)S-mode or can be hardwired to 0. 223 | Additionally, any changes to the PM CSRs affect global _XS_ bits in the **mstatus** register. 224 | 225 | _PM_ bits from **_MMTE_** register are accessible in all modes ((V)U/VS/HS/S/M) and can be read to query if the PM feature is currently enforced. By default, only higher privileged code can set the value for _PM_ bits. However, higher privileged code can enable _PM.Current_ bit for lower privileged code. In such scenario, current privilege code has a possibility to self-manage its own configuration of _PM_ bits. + 226 | 227 | By default, the current CPU mode is using _**xPMMASK**_, _**xPMBASE**_ and _PM_ bits corresponding to it. When CPU is switching the mode, corresponding pair of _**xPMMASK**_, _**xPMBASE**_ and _PM_ bits are used. 228 | Special carefulness is necessary when VU and U mode are available. If virtualization extension is enabled, and hypervisor is not using _**xPMMASK**_ / _**xPMBASE**_ CSRs for its U-mode then context switches these registers when it context switches between VMs. 229 | If a hypervisor is using _**xPMMASK**_ / _**xPMBASE**_ CSRs for its U-mode, then it switches in its own pair before dropping down to U-mode. Later, HS/S-mode context switches in the pair for the VM that it returns to. 230 | 231 | If higher privileged code needs to use _**xPMMASK**_ and _**xPMBASE**_ from the lower privilege mode, there are two possible solutions: 232 | 233 | 1. Emulate equation 1. purely in software using _**xPMMASK**_ and _**xPMBASE**_ CSRs from the desired privilege mode. + 234 | 2. If PM.Current is enabled it is possible to save the state of the current _**xPMMASK**_ and _**xPMBASE**_ CSRs and temporarily replace them with the desired one. At the end, original values can be restored. + 235 | 236 | 237 | _**MPMMASK**_ register fully two-fold function: 238 | 239 | 1. Based on PM bits configuration, it can be programmable by the higher privilege mode or by the current privilege mode + 240 | 2. Performs status register function for the current privilege mode + 241 | 242 | _**MPMBASE**_ register fully two-fold function: 243 | 244 | 1. Based on PM bits configuration, it can be programmable by the higher privilege mode or by the current privilege mode 245 | 2. Performs status register function for the current privilege mode 246 | 247 | Any write access would be ignored if performed to the current _**xPMMASK**_, _**xPMBASE**_ and **_MMTE_** CSR registers and PM.Current is disabled. + 248 | 249 | PM extension allows various flavors of implementation. If PM is not desired in specific RISC-V mode, appropriate CSRs could be read-only and hardwired to 0. + 250 | PM extension does not define the minimum supported maskable bits (it is defined in the profiles). However, there is no upper-bound limitation and XLEN-1 mask can be implemented. Unsupported maskable bits in _**xPMMASK**_ CSRs are hardwired to 0. 251 | Each privilege level must support the same variation of maskable bits. 252 | -------------------------------------------------------------------------------- /zjid/background.adoc: -------------------------------------------------------------------------------- 1 | [#background,reftext="Background"] 2 | == Background 3 | 4 | This section describes the history and requirements of I/D synchronization on RISC-V and contrasts the new mechanism to Zifencei. 5 | -------------------------------------------------------------------------------- /zjid/bibliography.adoc: -------------------------------------------------------------------------------- 1 | [bibliography] 2 | == Bibliography 3 | 4 | -------------------------------------------------------------------------------- /zjid/colophon.adoc: -------------------------------------------------------------------------------- 1 | [colophon] 2 | == Preface 3 | 4 | This document is released under the https://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License]. 5 | 6 | The proposed mechanism is an independent ISA extension developed as part of the RISC-V J Extension. The temporary identifier of this extension is `Zjid` (subject to change). 7 | -------------------------------------------------------------------------------- /zjid/header.adoc: -------------------------------------------------------------------------------- 1 | [[riscv-authoring]] 2 | = RISC-V Instruction/Data Synchronization Specification 3 | :description: RISC-V J Extension: Instruction/Data Synchronization 4 | :company: RISC-V.org 5 | :revdate: 01/2022 6 | :revnumber: 0.0 7 | :revremark: Development 8 | //development: assume everything can change 9 | //stable: assume everything could change 10 | //frozen: of you implement this version you assume the risk that something might change because of the public review cycle but we expect little to no change. 11 | //ratified: you can implement this and be assured nothing will change. if something needs to change due to an errata or enhancement, it will come out in a new extension. we do not revise extensions. 12 | :url-riscv: http://riscv.org 13 | :doctype: book 14 | //:doctype: report 15 | :preface-title: Preamble 16 | :colophon: 17 | :appendix-caption: Appendix 18 | :imagesdir: ../docs-resources/images 19 | :title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] 20 | //:page-background-image: image:draft.svg[opacity=20%] 21 | //:title-page-background-image: none 22 | //:back-cover-image: image:backpage.png[opacity=25%] 23 | // Settings: 24 | :experimental: 25 | :reproducible: 26 | :imagesoutdir: images 27 | :bibtex-file: resources/riscv-spec.bib 28 | :bibtex-order: alphabetical 29 | :bibtex-style: apa 30 | :icons: font 31 | :lang: en 32 | :listing-caption: Listing 33 | :sectnums: 34 | :toc: left 35 | :toclevels: 4 36 | :source-highlighter: pygments 37 | ifdef::backend-pdf[] 38 | :source-highlighter: coderay 39 | endif::[] 40 | :table-caption: Table 41 | :figure-caption: Figure 42 | :xrefstyle: full 43 | :chapter-refsig: Chapter 44 | :section-refsig: Section 45 | :appendix-refsig: Appendix 46 | :data-uri: 47 | :hide-uri-scheme: 48 | :stem: latexmath 49 | :footnote: 50 | 51 | include::colophon.adoc[] 52 | include::introduction.adoc[] 53 | include::background.adoc[] 54 | include::instructions.adoc[] 55 | include::usage.adoc[] 56 | include::index.adoc[] 57 | include::bibliography.adoc[] 58 | 59 | -------------------------------------------------------------------------------- /zjid/id-consistency-proposal.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscv/riscv-j-extension/e086fff37263399c6038440ada2805237a7d6e16/zjid/id-consistency-proposal.pdf -------------------------------------------------------------------------------- /zjid/index.adoc: -------------------------------------------------------------------------------- 1 | [index] 2 | == Index 3 | -------------------------------------------------------------------------------- /zjid/instructions.adoc: -------------------------------------------------------------------------------- 1 | [#instructions,reftext="Instructions"] 2 | == Instructions 3 | 4 | This section introduces the mechanism's new instructions and associated semantics. 5 | -------------------------------------------------------------------------------- /zjid/introduction.adoc: -------------------------------------------------------------------------------- 1 | [#introduction,reftext="Introduction"] 2 | == Introduction 3 | 4 | This chapter provides an introduction to instruction/data synchronization on RISC-V. 5 | 6 | -------------------------------------------------------------------------------- /zjid/usage.adoc: -------------------------------------------------------------------------------- 1 | [#usage,reftext="Usage"] 2 | == Usage Examples 3 | 4 | This section demonstrates different canonical use cases of the new mechanism. 5 | -------------------------------------------------------------------------------- /zjpm-spec.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscv/riscv-j-extension/e086fff37263399c6038440ada2805237a7d6e16/zjpm-spec.pdf -------------------------------------------------------------------------------- /zjpm/background.adoc: -------------------------------------------------------------------------------- 1 | [#background,reftext="Background"] 2 | == Background 3 | 4 | === Definitions 5 | 6 | We now define basic terms. Note that these rely on the definition of an “ignore” transformation, which is defined in Chapter 2.2. 7 | 8 | * **Effective address (as defined in the RISC-V Base ISA):** A load/store effective address sent to the memory subsystem (e.g., as generated during the execution of load/store instructions). This does not include addresses corresponding to implicit accesses, such as page table walks. 9 | 10 | * **Masked bits:** The upper PMLEN bits of an address, where PMLEN is a configurable parameter. We will use PMLEN consistently throughout this document to refer to this parameter. 11 | 12 | * **Transformed address:** An effective address after the ignore transformation has been applied. 13 | 14 | * **Address translation mode:** The MODE of the currently active address translation scheme as defined in the RISC-V privileged specification. This could, for example, refer to Bare, Sv39, Sv48, and Sv57. In accordance with the privileged specification, non-Bare translation modes are referred to as virtual-memory schemes. For the purpose of this specification, M-mode translation is treated as equivalent to Bare. 15 | 16 | * **Address validity:** The RISC-V privileged spec defines validity of addresses based on the address translation mode that is currently in use (e.g., Sv57, Sv48, Sv39, etc.). For a virtual address to be valid, all bits in the unused portion of the address must be the same as the Most Significant Bit (MSB) of the used portion. For example, when page-based 48-bit virtual memory (Sv48) is used, load/store effective addresses, which are 64 bits, must have bits 63–48 all set to bit 47, or else a page-fault exception will occur. For physical addresses, validity means that bits XLEN-1 to PABITS are zero, where PABITS is the number of physical address bits supported by the processor. 17 | 18 | * **NVBITS:** The upper bits within a virtual address that have no effect on addressing memory and are only used for validity checks. These bits depend on the currently active address translation mode. For example, in Sv48, these are bits 63-48. 19 | 20 | * **VBITS:** The bits within a virtual address that affect which memory is addressed. These are the bits of an address which are used to index into page tables. 21 | 22 | === The “Ignore” Transformation 23 | 24 | The ignore transformation differs depending on whether it applies to a virtual or physical address. For virtual addresses, it replaces the upper PMLEN bits with the sign extension of the PMLEN+1st bit. 25 | 26 | [source] 27 | ."Ignore" Transformation for virtual addresses, expressed in Verilog code. 28 | ---- 29 | transformed_effective_address = 30 | {{PMLEN{effective_address[XLEN-PMLEN-1]}}, effective_address[XLEN-PMLEN-1:0]} 31 | ---- 32 | 33 | [NOTE] 34 | ==== 35 | If PMLEN is less than or equal to NVBITS for the largest supported address translation mode on a given architecture, this is equivalent to ignoring a subset of NVBITS. This enables cheap implementations that modify validity checks in the CPU instead of performing the sign extension. 36 | ==== 37 | 38 | When applied to a physical address, including guest-physical addresses (i.e., all cases except when the active satp register's MODE field != Bare), the ignore transformation replaces the upper PMLEN bits with 0. This includes both the case of running in M-mode and running in other privilege modes with Bare address translation mode. 39 | 40 | [source] 41 | ."Ignore" Transformation for physical addresses, expressed in Verilog code. 42 | ---- 43 | transformed_effective_address = 44 | {{PMLEN{0}}, effective_address[XLEN-PMLEN-1:0]} 45 | ---- 46 | 47 | [NOTE] 48 | ==== 49 | This definition is consistent with the way that RISC-V already handles physical and virtual addresses differently. While the unused upper bits of virtual addresses are the sign-extension of the used bits (see the definition of "address validity" in <<_definitions>>), the equivalent bits in physical addresses are zero-extended. This is necessary due to their interactions with other mechanisms such as Physical Memory Protection (PMP). 50 | ==== 51 | 52 | When pointer masking is enabled, the ignore transformation will be applied to every explicit memory access (e.g., loads/stores, atomics operations, and floating point loads/stores). The transformation *does not* apply to implicit accesses such as page table walks or instruction fetches. The set of accesses that pointer masking applies to is described in <<_memory_accesses_subject_to_pointer_masking>>. 53 | 54 | [WARNING] 55 | ==== 56 | Pointer masking does not change the underlying address generation logic or permission checks. Under a fixed address translation mode, it is semantically equivalent to replacing a subset of instructions (e.g., loads and stores) with an instruction sequence that applies the ignore operation to the target address of this instruction and then applies the instruction to the transformed address. References to address translation and other implementation details in the text are primarily to explain design decisions and common implementation patterns. 57 | ==== 58 | 59 | Note that pointer masking is purely an arithmetic operation on the address that makes no assumption about the meaning of the addresses it is applied to. Pointer masking with the same value of PMLEN always has the same effect for the same type of address (virtual or physical). This ensures that code that relies on pointer masking does not need to be aware of the environment it runs in once pointer masking has been enabled, as long as the value of PMLEN is known, and whether or not addresses are virtual or physical. For example, the same application or library code can run in user mode, supervisor mode or M-mode (with different address translation modes) without modification. 60 | 61 | [NOTE] 62 | ==== 63 | A common scenario for such code is that addresses are generated by mmap system calls. This abstracts away the details of the underlying address translation mode from the application code. Software therefore needs to be aware of the value of PMLEN to ensure that its minimally required number of tag bits is supported. <<_determining_the_value_of_pmlen>> covers how this value is derived. 64 | ==== 65 | 66 | === Example 67 | 68 | Table 1 shows an example of the pointer masking transformation on a virtual address when PM is enabled for RV64 under Sv57 (PMLEN=7). 69 | 70 | [%header, cols="25%,75%", options="header"] 71 | .Example of PM address translation for RV64 under Sv57 72 | |=== 73 | |Page-based profile|Sv57 on RV64 74 | |Effective Address |0xABFFFFFF12345678 + 75 | NVBITS[1010101] VBITS[11111111111111111111111110001...000] 76 | |PMLEN|7 77 | |Mask|0x01FFFFFFFFFFFFFF + 78 | NVBITS[0000000] VBITS[11111111111111111111111111111...111] 79 | |PMLEN+1st bit from the top (i.e., bit XLEN-PMLEN-1)|1 80 | |Transformed effective address |0xFFFFFFFF12345678 + 81 | NVBITS[1111111] VBITS[11111111111111111111111110001...000] 82 | 83 | |=== 84 | 85 | If the address was a physical address rather than a virtual address with Sv57, the transformed address with PMLEN=7 would be 0x1FFFFFF12345678. 86 | 87 | === Determining the Value of PMLEN 88 | 89 | From an implementation perspective, ignoring bits is deeply connected to the maximum virtual and physical address space supported by the processor (e.g., Bare, Sv48, Sv57). In particular, applying the above transformation is cheap if it covers only bits that are not used by **any** supported address translation mode (as it is equivalent to switching off validity checks). Masking NVBITS beyond those bits is more expensive as it requires ignoring them in the TLB tag, and even more expensive if the masked bits extend into the VBITS portion of the address (as it requires performing the actual sign extension). Similarly, when running in Bare or M mode, it is common for implementations to not use a particular number of bits at the top of the physical address range and fix them to zero. Applying the ignore transformation to those bits is cheap as well, since it will result in a valid physical address with all the upper bits fixed to 0. 90 | 91 | The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards. In such future standards, different supported values of PMLEN may be defined for each privilege mode (U/VU, S/HS, and M). 92 | 93 | [NOTE] 94 | ==== 95 | Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN. The current extension does not define the behavior if PMLEN was different from the values defined above. In particular, there is no guarantee that a future pointer masking extension would define the ignore operation in the same way for those values of PMLEN. 96 | ==== 97 | 98 | === Pointer Masking and Privilege Modes 99 | 100 | Pointer masking is controlled separately for different privilege modes. The subset of supported privilege modes is determined by the set of supported pointer masking extensions. Different privilege modes may have different pointer masking settings active simultaneously and the hardware will automatically apply the pointer masking settings of the currently active privilege mode. A privilege mode's pointer masking setting is configured by bits in configuration registers of the next-higher privilege mode. 101 | 102 | Note that the pointer masking setting that is applied only depends on the active privilege mode, not on the address that is being masked. Some operating systems (e.g., Linux) may use certain bits in the address to disambiguate between different types of addresses (e.g., kernel and user-mode addresses). Pointer masking _does not_ take these semantics into account and is purely an arithmetic operation on the address it is given. 103 | 104 | [NOTE] 105 | ==== 106 | Linux places kernel addresses in the upper half of the address space and user addresses in the lower half of the address space. As such, the MSB is often used to identify the type of a particular address. With pointer masking enabled, this role is now played by bit XLEN-PMLEN-1 and code that checks whether a pointer is a kernel or a user address needs to inspect this bit instead. For backward compatibility, it may be desirable that the MSB still indicates whether an address is a user or a kernel address. An operating system's ABI may mandate this, but it does not affect the pointer masking mechanism itself. For example, the Linux ABI may choose to mandate that the MSB is not used for tagging and replicates bit XLEN-PMLEN-1 bit (note that for such a mechanism to be secure, the kernel needs to check the MSB of any user mode-supplied address and ensure that this invariant holds before using it; alternatively, it can apply the transformation from Listing 1 or 2 to ensure that the MSB is set to the correct value). 107 | ==== 108 | 109 | === Memory Accesses Subject to Pointer Masking 110 | 111 | Pointer masking applies to all explicit memory accesses. Currently, in the Base and Privileged ISAs, these are: 112 | 113 | * **Base Instruction Set**: LB, LH, LW, LBU, LHU, LWU, LD, SB, SH, SW, SD. 114 | * **Atomics**: All instructions in RV32A and RV64A. 115 | * **Floating Point**: FLW, FLD, FLQ, FSW, FSD, FSQ. 116 | * **Compressed**: All instructions mapping to any of the above, and C.LWSP, C.LDSP, C.LQSP, C.FLWSP, C.FLDSP, C.SWSP, C.SDSP, C.SQSP, C.FSWSP, C.FSDSP. 117 | * **Hypervisor Extension**: HLV.\*, HSV.* (in some cases; see <<_ssnpm>>). 118 | * **Cache Management Operations**: All instructions in Zicbom, Zicbop and Zicboz. 119 | * **Vector Extension**: All vector load and store instructions in the ratified RVV 1.0 spec. 120 | * **Assorted**: FENCE, FENCE.I (if the currently unused address fields become enabled in the future). 121 | 122 | [NOTE] 123 | ==== 124 | This list will grow over time as new extensions introduce new instructions that perform explicit memory accesses. 125 | ==== 126 | 127 | For other extensions, pointer masking applies to all explicit memory accesses by default. Future extensions may add specific language to indicate whether particular accesses are or are not included in pointer masking. 128 | 129 | [NOTE] 130 | ==== 131 | It is worth noting that pointer masking is not applied to SFENCE.\*, HFENCE.\*, SINVAL.\*, or HINVAL.\*. When such an operation is invoked, it is the responsibility of the software to provide the correct address. 132 | ==== 133 | 134 | MPRV and SPVP affect pointer masking as well, causing the pointer masking settings of the effective privilege mode to be applied. When MXR is in effect at the effective privilege mode where explicit memory access is performed, pointer masking does not apply. 135 | 136 | [NOTE] 137 | ==== 138 | Note that this includes cases where page-based virtual memory is not in effect; i.e., although MXR has no effect on permissions checks when page-based virtual memory is not in effect, it is still used in determining whether or not pointer masking should be applied. 139 | ==== 140 | 141 | [NOTE] 142 | ==== 143 | Cache Management Operations (CMOs) must respect and take into account pointer masking. Otherwise, a few serious security problems can appear, including: 144 | 145 | * CBO.ZERO may work as a STORE operation. If pointer masking is not respected, it would be possible to write to memory bypassing the mask enforcement. 146 | * If CMOs did not respect pointer masking, it would be possible to weaponize this in a side-channel attack. For example, U-mode would be able to flush a physical address (without masking) that it should not be permitted to. 147 | ==== 148 | 149 | Pointer masking only applies to accesses generated by instructions on the CPU (including CPU extensions such as an FPU). E.g., it does not apply to accesses generated by page table walks, the IOMMU, or devices. 150 | 151 | [NOTE] 152 | ==== 153 | Pointer Masking does not apply to DMA controllers and other devices. It is therefore the responsibility of the software to manually untag these addresses. 154 | ==== 155 | 156 | Misaligned accesses are supported, subject to the same limitations as in the absence of pointer masking. The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access. In other words, the accessed bytes should be identical to the bytes that would be accessed if the pointer masking transformation was individually applied to every byte of the access without pointer masking. This ensures that both hardware implementations and emulation of misaligned accesses in M-mode behave the same way, and that the M-mode implementation is identical whether or not pointer masking is enabled (e.g., such an implementation may leverage MPRV to apply the correct privilege mode's pointer masking setting). 157 | 158 | No pointer masking operations are applied when software reads/writes to CSRs, including those meant to hold addresses. If software stores tagged addresses into such CSRs, data load or data store operations based on those addresses are subject to pointer masking only if they are explicit (<<_memory_accesses_subject_to_pointer_masking>>) and pointer masking is enabled for the privilege mode that performs the access. The implemented WARL width of CSRs is unaffected by pointer masking (e.g., if a CSR supports 52 bits of valid addresses and pointer masking is supported with PMLEN=16, the necessary number of WARL bits remains 52 independently of whether pointer masking is enabled or disabled). 159 | 160 | In contrast to software writes, pointer masking **is applied** for hardware writes to a CSR (e.g., when the hardware writes the transformed address to `stval` when taking an exception). Pointer masking is also applied to the memory access address when matching address triggers in debug. 161 | 162 | For example, software is free to write a tagged or untagged address to `stvec`, but on trap delivery (e.g., due to an exception or interrupt), pointer masking **will not be applied** to the address of the trap handler. However, pointer masking **will be applied** by the hardware to any address written into `stval` when delivering an exception. 163 | 164 | [NOTE] 165 | ==== 166 | The rationale for this choice is that delivering the additional bits may add overheads in some hardware implementations. Further, pointer masking is configured per privilege mode, so all trap handlers in supervisor mode would need to be careful to configure pointer masking the same way as user mode or manually unmask (which is expensive). 167 | ==== 168 | 169 | === Pointer Masking Extensions 170 | 171 | Pointer masking refers to a number of separate extensions, all of which are privileged. This approach is used to capture optionality of pointer masking features. Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN. 172 | 173 | **Extensions**: 174 | 175 | * **Ssnpm**: A supervisor-level extension that provides pointer masking for the next lower privilege mode (U-mode), and for VS- and VU-modes if the H extension is present. 176 | * **Smnpm**: A machine-level extension that provides pointer masking for the next lower privilege mode (S/HS if S-mode is implemented, or U-mode otherwise). 177 | * **Smmpm**: A machine-level extension that provides pointer masking for M-mode. 178 | 179 | See <<_isa_extensions>> for details on how each of these extensions is configured. 180 | 181 | In addition, the pointer masking standard defines two extensions that describe an execution environment but have no bearing on hardware implementations. These extensions are intended to be used in profile specifications where a User profile or a Supervisor profile can only reference User level or Supervisor level pointer masking functionality, and not the associated CSR controls that exist at a higher privilege level (i.e., in the execution environment). 182 | 183 | * **Sspm**: An extension that indicates that there is pointer-masking support available in supervisor mode, with some facility provided in the supervisor execution environment to control pointer masking. 184 | * **Supm**: An extension that indicates that there is pointer-masking support available in user mode, with some facility provided in the application execution environment to control pointer masking. 185 | 186 | The precise nature of these facilities is left to the respective execution environment. 187 | 188 | Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits (see <<_isa_extensions>> for details). The same is the case on RV64 or larger systems when UXL/SXL/MXL is set to 1 for the corresponding privilege mode. Note that in RV32, the CSR bits introduced by pointer masking are still present, for compatibility between RV32 and larger systems with UXL/SXL/MXL set to 1. Setting UXL/SXL/MXL to 1 will clear the corresponding pointer masking configuration bits. 189 | 190 | [NOTE] 191 | ==== 192 | Note that setting UXL/SXL/MXL to 1 and back to 0 does not preserve the previous values of the PMM bits. This includes the case of entering an RV32 virtual machine from an RV64 hypervisor and returning. 193 | ==== 194 | 195 | -------------------------------------------------------------------------------- /zjpm/bibliography.adoc: -------------------------------------------------------------------------------- 1 | [bibliography] 2 | == Bibliography 3 | 4 | [1] Serebryany, Kostya, Evgenii Stepanov, Aleksey Shlyapnikov, Vlad Tsyrklevich, and Dmitry Vyukov. "Memory tagging and how it improves C/C++ memory safety." arXiv preprint arXiv:1802.09517 (2018). 5 | -------------------------------------------------------------------------------- /zjpm/colophon.adoc: -------------------------------------------------------------------------------- 1 | [colophon] 2 | == Copyright and license information 3 | 4 | This document is released under the https://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License]. 5 | 6 | The proposed mechanism is an independent set of ISA extensions developed as part of the RISC-V J Extension. This document defines a set of individual extensions (`Smmpm`, `Smnpm`, `Ssnpm`, `Sspm`, `Supm`) that are collectively referred to as *pointer masking*. 7 | 8 | -------------------------------------------------------------------------------- /zjpm/contributors.adoc: -------------------------------------------------------------------------------- 1 | [contributors] 2 | == Contributors 3 | 4 | **Authors:** Adam Zabrocki, Martin Maas, Lee Campbell, RISC-V Runtime Integrity and J Extension Task Groups 5 | 6 | **Contributors:** Krste Asanovic, Jecel Assumpcao, James Ball, Alexey Baturo, Allen Baum, Andrew Bresticker, Paul Donahue, Greg Favor, Andy Glew, Deepak Gupta, John Hauser, Samuel Holland, John Ingalls, James Kenney, Earl Killian, Christos Kotselidis, Dean Liberty, Philip Reames, Ian Rogers, Josh Scheid, Kostya Serebryany, Ved Shanbhogue, Boris Shingarov, Andrew Waterman, David Weaver, Foivos Zakkak, Members of the Runtime Integrity and J Extension Task Groups 7 | 8 | -------------------------------------------------------------------------------- /zjpm/header.adoc: -------------------------------------------------------------------------------- 1 | [[riscv-authoring]] 2 | = RISC-V Pointer Masking 3 | :description: RISC-V J Extension: Pointer Masking 4 | :company: RISC-V.org 5 | :revdate: 10/2024 6 | :revnumber: 1.0 7 | :revremark: Ratified 8 | //development: assume everything can change 9 | //stable: assume everything could change 10 | //frozen: of you implement this version you assume the risk that something might change because of the public review cycle but we expect little to no change. 11 | //ratified: you can implement this and be assured nothing will change. if something needs to change due to an errata or enhancement, it will come out in a new extension. we do not revise extensions. 12 | :url-riscv: http://riscv.org 13 | :doctype: book 14 | //:doctype: report 15 | :preface-title: Preamble 16 | :colophon: 17 | :appendix-caption: Appendix 18 | :imagesdir: ../docs-resources/images 19 | :title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] 20 | //:page-background-image: image:draft.svg[opacity=20%] 21 | //:title-page-background-image: none 22 | //:back-cover-image: image:backpage.png[opacity=25%] 23 | // Settings: 24 | :experimental: 25 | :reproducible: 26 | :imagesoutdir: images 27 | :bibtex-file: resources/riscv-spec.bib 28 | :bibtex-order: alphabetical 29 | :bibtex-style: apa 30 | :icons: font 31 | :lang: en 32 | :listing-caption: Listing 33 | :sectnums: 34 | :toc: left 35 | :toclevels: 4 36 | :source-highlighter: pygments 37 | ifdef::backend-pdf[] 38 | :source-highlighter: coderay 39 | endif::[] 40 | :table-caption: Table 41 | :figure-caption: Figure 42 | :xrefstyle: full 43 | :chapter-refsig: Chapter 44 | :section-refsig: Section 45 | :appendix-refsig: Appendix 46 | :data-uri: 47 | :hide-uri-scheme: 48 | :stem: latexmath 49 | :footnote: 50 | 51 | [WARNING] 52 | .This document is in the link:http://riscv.org/spec-state[Ratified state] 53 | ==== 54 | No changes are allowed. Any desired or needed changes can be the subject of a 55 | follow-on new extension. Ratified extensions are never revised. 56 | ==== 57 | 58 | [preface] 59 | include::colophon.adoc[] 60 | include::contributors.adoc[] 61 | include::introduction.adoc[] 62 | include::background.adoc[] 63 | include::instructions.adoc[] 64 | include::bibliography.adoc[] 65 | 66 | -------------------------------------------------------------------------------- /zjpm/instructions.adoc: -------------------------------------------------------------------------------- 1 | == ISA Extensions 2 | 3 | This section describes the pointer masking extensions `Smmpm`, `Smnpm` and `Ssnpm`. All of these extensions are privileged ISA extensions and do not add any new CSRs. For the definitions of `Sspm` and `Supm`, see <<_pointer_masking_extensions>>. 4 | 5 | [NOTE] 6 | ==== 7 | Future extensions may introduce additional CSRs to allow different privilege modes to modify their own pointer masking settings. This may be required for future use cases in managed runtime systems that are not currently addressed as part of this extension. 8 | ==== 9 | 10 | Each extension introduces a 2-bit WARL field (`PMM`) that may take on the following values to set the pointer masking settings for a particular privilege mode. 11 | 12 | [%header, cols="25%,75%", options="header"] 13 | .Possible values of `PMM` WARL field. 14 | |=== 15 | |Value|Description 16 | |00|Pointer masking is disabled (PMLEN=0) 17 | |01|Reserved 18 | |10|Pointer masking is enabled with PMLEN=XLEN-57 (PMLEN=7 on RV64) 19 | |11|Pointer masking is enabled with PMLEN=XLEN-48 (PMLEN=16 on RV64) 20 | |=== 21 | 22 | All of these fields are read-only 0 on RV32 systems. 23 | 24 | === Ssnpm 25 | 26 | `Ssnpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `senvcfg`. Setting `PMM` enables or disables pointer masking for the next lower privilege mode (U/VU mode), according to the values in Table 2. 27 | 28 | In systems where the H Extension is present, `Ssnpm` also adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `henvcfg`. Setting `PMM` enables or disables pointer masking for VS-mode, according to the values in Table 2. Further, a 2-bit WARL field (`HUPMM`) is added to bits 49:48 of `hstatus`. Setting `hstatus.HUPMM` enables or disables pointer masking for `HLV.\*` and `HSV.*` instructions in U-mode, according to the values in Table 2, when their explicit memory access is performed as though in VU-mode. In HS- and M-modes, pointer masking for these instructions is enabled or disabled by `senvcfg.PMM`, when their explicit memory access is performed as though in VU-mode. Setting `henvcfg.PMM` enables or disables pointer masking for `HLV.\*` and `HSV.*` when their explicit memory access is performed as though in VS-mode. 29 | 30 | [NOTE] 31 | ==== 32 | The hypervisor should copy the value written to `senvcfg.PMM` by the guest to the `hstatus.HUPMM` field prior to invoking `HLV.\*` or `HSV.*` instructions in U-mode. 33 | ==== 34 | 35 | The memory accesses performed by the `HLVX.*` instructions are not subject to pointer masking. 36 | 37 | [NOTE] 38 | ==== 39 | `HLVX.*` instructions, designed for emulating implicit access to fetch instructions from guest memory, perform memory accesses that are exempt from pointer masking to facilitate this emulation. For the same reason, pointer masking does not apply when MXR is set. 40 | ==== 41 | 42 | === Smnpm 43 | 44 | `Smnpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `menvcfg`. Setting `PMM` enables or disables pointer masking for the next lower privilege mode (S-/HS-mode if S-mode is implemented, or U-mode otherwise), according to the values in Table 2. 45 | 46 | [NOTE] 47 | ==== 48 | The type of address determines which type of pointer masking is applied. For example, when running with virtualization in VS/VU mode with `vsatp.MODE` = Bare, physical address pointer masking (zero extension) applies. 49 | ==== 50 | 51 | === Smmpm 52 | 53 | `Smmpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `mseccfg`. The presence of `Smmpm` implies the presence of the `mseccfg` register, even if it would not otherwise be present. Setting `PMM` enables or disables pointer masking for M mode, according to the values in Table 2. 54 | 55 | === Interaction with SFENCE.VMA 56 | 57 | Since pointer masking applies to the effective address only and does not affect any memory-management data structures, no SFENCE.VMA is required after enabling/disabling pointer masking. 58 | 59 | === Interaction with Two-Stage Address Translation 60 | 61 | Guest physical addresses (GPAs) are 2 bits wider than the corresponding virtual address translation modes, resulting in additional address translation schemes Sv32x4, Sv39x4, Sv48x4 and Sv57x4 for translating guest physical addresses to supervisor physical addresses. When running with virtualization in VS/VU mode with `vsatp.MODE` = Bare, this means that those two bits may be subject to pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply. 62 | 63 | [NOTE] 64 | ==== 65 | An implementation could mask those two bits on the TLB access path, but this can have a significant timing impact. Alternatively, an implementation may choose to "waste" TLB capacity by having up to 4 duplicate entries for each page. In this case, the pointer masking operation can be applied on the TLB refill path, where it is unlikely to affect timing. To support this approach, some TLB entries need to be flushed when PMLEN changes in a way that may affect these duplicate entries. 66 | ==== 67 | 68 | To support implementations where (XLEN-PMLEN) can be less than the GPA width supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with rs1=x0 if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN) is less than GPA width supported by the `hgatp` translation mode of that guest. Specifically, these cases are: 69 | 70 | * `PMLEN=7` and `hgatp.MODE=sv57x4` 71 | * `PMLEN=16` and `hgatp.MODE=sv57x4` 72 | * `PMLEN=16` and `hgatp.MODE=sv48x4` 73 | 74 | [NOTE] 75 | ==== 76 | `Smmpm` implementations need to satisfy max(largest supported virtual address size, largest supported supervisor physical address size) <= (XLEN - PMLEN) bits to avoid any masking logic on the TLB access path. 77 | ==== 78 | 79 | Implementation of an address-specific `HFENCE.GVMA` should either ignore the address argument, or should ignore the top masked GPA bits of entries when comparing for an address match. 80 | 81 | === Number of Masked Bits 82 | 83 | As described in <<_determining_the_value_of_pmlen>>, the supported values of PMLEN may depend on the effective privilege mode. The current standard only defines PMLEN=XLEN-48 and PMLEN=XLEN-57, but this assumption may be relaxed in future extensions and profiles. Trying to enable pointer masking in an unsupported scenario represents an illegal write to the corresponding pointer masking enable bit and follows WARL semantics. Future profiles may choose to define certain combinations of privilege modes and supported values of PMLEN as mandatory. 84 | 85 | [NOTE] 86 | ==== 87 | An option that was considered but discarded was to allow implementations to set PMLEN depending on the active addressing mode. For example, PMLEN could be set to 16 for Sv48 and to 25 for Sv39. However, having a single value of PMLEN (e.g., setting PMLEN to 16 for both Sv39 and Sv48 rather than 25) facilitates TLB implementations in designs that support Sv39 and Sv48 but not Sv57. 16 bits are sufficient for current pointer masking use cases but allow for a TLB implementation that matches against the same number of virtual tag bits independently of whether it is running with Sv39 or Sv48. However, if Sv57 is supported, tag matching may need to be conditional on the current address translation mode. 88 | ==== 89 | -------------------------------------------------------------------------------- /zjpm/introduction.adoc: -------------------------------------------------------------------------------- 1 | == Introduction 2 | 3 | RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address (these terms will be defined more precisely in the Background section). This allows these bits to be used in whichever way the application chooses. The version of the extension being described here specifically targets **tag checks**: When an address is accessed, the tag stored in the masked bits can be compared against a range-based tag. This is used for dynamic safety checkers such as HWASAN [1]. Such tools can be applied in all privilege modes (U, S and M). 4 | 5 | HWASAN leverages tags in the upper bits of the address to identify memory errors such as use-after-free or buffer overflow errors. By storing a *pointer tag* in the upper bits of the address and checking it against a *memory tag* stored in a side table, it can identify whether a pointer is pointing to a valid location. Doing this without hardware support introduces significant overheads since the pointer tag needs to be manually removed for every conventional memory operation. Pointer masking support reduces these overheads. 6 | 7 | Pointer masking only adds the ability to ignore pointer tags during regular memory accesses. The tag checks themselves can be implemented in software or hardware. If implemented in software, pointer masking still provides performance benefits since non-checked accesses do not need to transform the address before every memory access. Hardware implementations are expected to provide even larger benefits due to performing tag checks out-of-band and hardening security guarantees derived from these checks. We anticipate that future extensions may build on pointer masking to support this functionality in hardware. 8 | 9 | It is worth mentioning that while HWASAN is the primary use-case for the current pointer masking extension, a number of other hardware/software features may be implemented leveraging Pointer Masking. Some of these use cases include sandboxing, object type checks and garbage collection bits in runtime systems. Note that the current version of the spec does not explicitly address these use cases, but future extensions may build on it to do so. 10 | 11 | While we describe the high-level concepts of pointer masking as if it was a single extension, it is, in reality, a family of extensions that implementations or profiles may choose to individually include or exclude (see <<_pointer_masking_extensions>>). 12 | --------------------------------------------------------------------------------