├── .github ├── dependabot.yml └── workflows │ └── build-pdf.yml ├── .gitignore ├── .gitmodules ├── CONTRIBUTING.md ├── LICENSE ├── Makefile ├── bibliography.adoc ├── body.adoc ├── chapter2.adoc ├── contributors.adoc ├── dependencies ├── Gemfile ├── README.md ├── apt_packages.txt └── package.json ├── example.bib ├── header.adoc ├── index.adoc ├── intro.adoc └── readme.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 | version: 8 | description: 'Release version, e.g. X.Y.Z:' 9 | required: true 10 | type: string 11 | revision_mark: 12 | description: 'Set revision mark as Draft or Release:' 13 | required: true 14 | type: string 15 | default: 'Draft' 16 | prerelease: 17 | description: 'Tag as a pre-release?' 18 | required: false 19 | type: boolean 20 | default: true 21 | draft: 22 | description: 'Create release as a draft?' 23 | required: false 24 | type: boolean 25 | default: false 26 | pull_request: 27 | push: 28 | branches: 29 | - main 30 | 31 | jobs: 32 | build: 33 | runs-on: ubuntu-latest 34 | 35 | steps: 36 | # Step 1: Checkout the repository 37 | - name: Checkout repository 38 | uses: actions/checkout@v4 39 | with: 40 | submodules: 'recursive' 41 | 42 | # Step 2: Pull the latest RISC-V Docs container image 43 | - name: Pull Container 44 | run: docker pull riscvintl/riscv-docs-base-container-image:latest 45 | 46 | # Step 3: Build Files 47 | - name: Build Files 48 | run: make 49 | env: 50 | VERSION: v${{ github.event.inputs.version }} 51 | REVMARK: ${{ github.event.inputs.revision_mark }} 52 | 53 | # Step 4: Upload the built PDF files as a single artifact 54 | - name: Upload Build Artifacts 55 | uses: actions/upload-artifact@v4 56 | with: 57 | name: Build Artifacts 58 | path: ${{ github.workspace }}/*.pdf 59 | retention-days: 30 60 | 61 | # Create Release 62 | - name: Create Release 63 | uses: softprops/action-gh-release@v1 64 | with: 65 | files: ${{ github.workspace }}/*.pdf 66 | tag_name: v${{ github.event.inputs.version }} 67 | name: Release ${{ github.event.inputs.version }} 68 | draft: ${{ github.event.inputs.draft }} 69 | prerelease: ${{ github.event.inputs.prerelease }} 70 | env: 71 | GITHUB_TOKEN: ${{ secrets.GHTOKEN }} 72 | if: github.event_name == 'workflow_dispatch' 73 | # This condition ensures this step only runs for workflow_dispatch events. 74 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.pdf 2 | 3 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "docs-resources"] 2 | path = docs-resources 3 | url = https://github.com/riscv/docs-resources.git 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contribution Guidelines 2 | 3 | As an open-source project, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. 4 | 5 | This document explains how to submit patches to the project so your patch will be accepted quickly in the codebase. 6 | 7 | ## Licensing 8 | 9 | Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired. 10 | 11 | This project uses the Creative Commons Attribution 4.0 International license, as found in the [LICENSE](https://github.com/riscv/docs-spec-template/blob/main/LICENSE) file in the project's repo. 12 | 13 | A license tells you what rights you have as an author, as provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company. 14 | 15 | ## Developer Certification of Origin (DCO) 16 | 17 | To make a good faith effort to ensure licensing criteria are met, this project requires the Developer Certificate of Origin (DCO) process to be followed. 18 | 19 | The DCO is an attestation attached to every contribution made by every author. In the commit message of the contribution (described more fully later in this document), the author simply adds a ``Signed-off-by`` statement and thereby agrees to the DCO. 20 | 21 | When an author submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and at https://developercertificate.org. 22 | 23 | ``` 24 | Developer's Certificate of Origin 1.1 25 | 26 | By making a contribution to this project, I certify that: 27 | 28 | (a) The contribution was created in whole or in part by me and I 29 | have the right to submit it under the open source license 30 | indicated in the file; or 31 | 32 | (b) The contribution is based upon previous work that, to the best 33 | of my knowledge, is covered under an appropriate open source 34 | license and I have the right under that license to submit that 35 | work with modifications, whether created in whole or in part 36 | by me, under the same open source license (unless I am 37 | permitted to submit under a different license), as indicated 38 | in the file; or 39 | 40 | (c) The contribution was provided directly to me by some other 41 | person who certified (a), (b) or (c) and I have not modified 42 | it. 43 | 44 | (d) I understand and agree that this project and the contribution 45 | are public and that a record of the contribution (including all 46 | personal information I submit with it, including my sign-off) is 47 | maintained indefinitely and may be redistributed consistent with 48 | this project or the open source license(s) involved. 49 | ``` 50 | 51 | ### DCO Sign-Off Methods 52 | 53 | The DCO requires that a sign-off message, in the following format, appears on each commit in the pull request: 54 | 55 | `Signed-off-by: Stephano Cetola ` 56 | 57 | You are required to use your real name in the sign-off message. 58 | 59 | The DCO text can either be manually added to your commit body, or you can add either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running ``git commit --amend -s``. If you've pushed your changes to GitHub already you'll need to force push your branch after this with ``git push -f``. 60 | 61 | 62 | **Note:** 63 | 64 | The name and email address of the account you use to submit your PR must match the name and email address on the ``Signed-off-by`` line in your commit message. 65 | -------------------------------------------------------------------------------- /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 | # Makefile for RISC-V Doc Template 2 | # 3 | # This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 4 | # International License. To view a copy of this license, visit 5 | # http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to 6 | # Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 7 | # 8 | # SPDX-License-Identifier: CC-BY-SA-4.0 9 | # 10 | # Description: 11 | # 12 | # This Makefile is designed to automate the process of building and packaging 13 | # the Doc Template for RISC-V Extensions. 14 | 15 | DATE ?= $(shell date +%Y-%m-%d) 16 | VERSION ?= v1.0 17 | REVMARK ?= Ratified 18 | DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ 19 | riscvintl/riscv-docs-base-container-image:latest 20 | 21 | HEADER_SOURCE := header.adoc 22 | PDF_RESULT := riscv-ctr-latest.pdf 23 | 24 | ASCIIDOCTOR_PDF := asciidoctor-pdf 25 | OPTIONS := --trace \ 26 | -a compress \ 27 | -a mathematical-format=svg \ 28 | -a revnumber=${VERSION} \ 29 | -a revremark=${REVMARK} \ 30 | -a revdate=${DATE} \ 31 | -a pdf-fontsdir=docs-resources/fonts \ 32 | -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ 33 | --failure-level=ERROR 34 | REQUIRES := --require=asciidoctor-bibtex \ 35 | --require=asciidoctor-diagram \ 36 | --require=asciidoctor-mathematical 37 | 38 | .PHONY: all build clean build-container build-no-container 39 | 40 | all: build 41 | 42 | build: 43 | @echo "Checking if Docker is available..." 44 | @if command -v docker >/dev/null 2>&1 ; then \ 45 | echo "Docker is available, building inside Docker container..."; \ 46 | $(MAKE) build-container; \ 47 | else \ 48 | echo "Docker is not available, building without Docker..."; \ 49 | $(MAKE) build-no-container; \ 50 | fi 51 | 52 | build-container: 53 | @echo "Starting build inside Docker container..." 54 | $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" 55 | @echo "Build completed successfully inside Docker container." 56 | 57 | build-no-container: 58 | @echo "Starting build..." 59 | $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) 60 | @echo "Build completed successfully." 61 | 62 | clean: 63 | @echo "Cleaning up generated files..." 64 | rm -f $(PDF_RESULT) 65 | @echo "Cleanup completed." 66 | -------------------------------------------------------------------------------- /bibliography.adoc: -------------------------------------------------------------------------------- 1 | [bibliography] 2 | == Bibliography 3 | 4 | bibliography::[] 5 | -------------------------------------------------------------------------------- /body.adoc: -------------------------------------------------------------------------------- 1 | [[body]] 2 | == CSRs 3 | 4 | [NOTE] 5 | [%unbreakable] 6 | ==== 7 | _CSR field specifications (such as WARL and WPRI) can be found in the link:https://riscv.org/technical/specifications/[RISC-V Instruction Set Manual] vol. II (Privileged Architecture), section 2.3._ 8 | ==== 9 | 10 | === Machine Control Transfer Records Control Register (`mctrctl`) 11 | 12 | The `mctrctl` register is a 64-bit read/write register that enables and configures the CTR capability. 13 | 14 | .Machine Control Transfer Records Control Register Format 15 | [%unbreakable] 16 | [wavedrom, , svg] 17 | .... 18 | {reg: [ 19 | {bits: 1, name: 'U'}, 20 | {bits: 1, name: 'S'}, 21 | {bits: 1, name: 'M'}, 22 | {bits: 4, name: 'WPRI'}, 23 | {bits: 1, name: 'RASEMU'}, 24 | {bits: 1, name: 'STE'}, 25 | {bits: 1, name: 'MTE'}, 26 | {bits: 1, name: 'WPRI'}, 27 | {bits: 1, name: 'BPFRZ'}, 28 | {bits: 1, name: 'LCOFIFRZ'}, 29 | {bits: 20, name: 'WPRI'}, 30 | {bits: 1, name: 'EXCINH'}, 31 | {bits: 1, name: 'INTRINH'}, 32 | {bits: 1, name: 'TRETINH'}, 33 | {bits: 1, name: 'NTBREN'}, 34 | {bits: 1, name: 'TKBRINH'}, 35 | {bits: 2, name: 'WPRI'}, 36 | {bits: 1, name: 'INDCALLINH'}, 37 | {bits: 1, name: 'DIRCALLINH'}, 38 | {bits: 1, name: 'INDJMPINH'}, 39 | {bits: 1, name: 'DIRJMPINH'}, 40 | {bits: 1, name: 'CORSWAPINH'}, 41 | {bits: 1, name: 'RETINH'}, 42 | {bits: 1, name: 'INDLJMPINH'}, 43 | {bits: 1, name: 'DIRLJMPINH'}, 44 | {bits: 12, name: 'WPRI'}, 45 | {bits: 4, name: 'Custom'}, 46 | ], config:{lanes: 8, hspace:1024}} 47 | .... 48 | 49 | .Machine Control Transfer Records Control Register Field Definitions 50 | [%unbreakable] 51 | [width="100%",cols="20%,80%",options="header",] 52 | |=== 53 | |Field |Description 54 | |M, S, U |Enable transfer recording in the selected privileged mode(s). 55 | 56 | |RASEMU |Enables RAS (Return Address Stack) Emulation Mode. See <>. 57 | 58 | |MTE |Enables recording of traps to M-mode when M=0. See <>. 59 | 60 | |STE |Enables recording of traps to S-mode when S=0. See <>. 61 | 62 | |BPFRZ |Set `sctrstatus`.FROZEN on a breakpoint exception that traps to M-mode or S-mode. See <>. 63 | 64 | |LCOFIFRZ |Set `sctrstatus`.FROZEN on local counter overflow interrupt (LCOFI) that traps to M-mode or S-mode. See <>. 65 | 66 | |EXCINH |Inhibit recording of exceptions. See <>. 67 | 68 | |INTRINH |Inhibit recording of interrupts. See <>. 69 | 70 | |TRETINH |Inhibit recording of trap returns. See <>. 71 | 72 | |NTBREN |Enable recording of not-taken branches. See <>. 73 | 74 | |TKBRINH |Inhibit recording of taken branches. See <>. 75 | 76 | |INDCALLINH |Inhibit recording of indirect calls. See <>. 77 | 78 | |DIRCALLINH |Inhibit recording of direct calls. See <>. 79 | 80 | |INDJMPINH |Inhibit recording of indirect jumps (without linkage). See <>. 81 | 82 | |DIRJMPINH |Inhibit recording of direct jumps (without linkage). See <>. 83 | 84 | |CORSWAPINH |Inhibit recording of co-routine swaps. See <>. 85 | 86 | |RETINH |Inhibit recording of function returns. See <>. 87 | 88 | |INDLJMPINH |Inhibit recording of other indirect jumps (with linkage). See <>. 89 | 90 | |DIRLJMPINH |Inhibit recording of other direct jumps (with linkage). See <>. 91 | |Custom[3:0] | WARL bits designated for custom use. The value 0 must correspond to standard behavior. See <>. 92 | |=== 93 | 94 | [%unbreakable] 95 | -- 96 | All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable. 97 | -- 98 | 99 | === Supervisor Control Transfer Records Control Register (`sctrctl`) 100 | 101 | The `sctrctl` register provides supervisor mode access to a subset of <<_machine_control_transfer_records_control_mctrctl, `mctrctl`>>. 102 | 103 | Bits 2 and 9 in `sctrctl` are read-only 0. As a result, the M and MTE fields in `mctrctl` are not accessible through `sctrctl`. All other `mctrctl` fields are accessible through `sctrctl`. 104 | 105 | === Virtual Supervisor Control Transfer Records Control Register (`vsctrctl`) 106 | 107 | If the H extension is implemented, the `vsctrctl` register is a 64-bit read/write register that is VS-mode's version of supervisor register `sctrctl`. When V=1, `vsctrctl` substitutes for the usual `sctrctl`, so instructions that normally read or modify `sctrctl` actually access `vsctrctl` instead. 108 | 109 | .Virtual Supervisor Control Transfer Records Control Register Format 110 | [%unbreakable] 111 | [wavedrom, , svg] 112 | .... 113 | {reg: [ 114 | {bits: 1, name: 'U'}, 115 | {bits: 1, name: 'S'}, 116 | {bits: 5, name: 'WPRI'}, 117 | {bits: 1, name: 'RASEMU'}, 118 | {bits: 1, name: 'STE'}, 119 | {bits: 2, name: 'WPRI'}, 120 | {bits: 1, name: 'BPFRZ'}, 121 | {bits: 1, name: 'LCOFIFRZ'}, 122 | {bits: 20, name: 'WPRI'}, 123 | {bits: 1, name: 'EXCINH'}, 124 | {bits: 1, name: 'INTRINH'}, 125 | {bits: 1, name: 'TRETINH'}, 126 | {bits: 1, name: 'NTBREN'}, 127 | {bits: 1, name: 'TKBRINH'}, 128 | {bits: 2, name: 'WPRI'}, 129 | {bits: 1, name: 'INDCALLINH'}, 130 | {bits: 1, name: 'DIRCALLINH'}, 131 | {bits: 1, name: 'INDJMPINH'}, 132 | {bits: 1, name: 'DIRJMPINH'}, 133 | {bits: 1, name: 'CORSWAPINH'}, 134 | {bits: 1, name: 'RETINH'}, 135 | {bits: 1, name: 'INDLJMPINH'}, 136 | {bits: 1, name: 'DIRLJMPINH'}, 137 | {bits: 12, name: 'WPRI'}, 138 | {bits: 4, name: 'Custom'}, 139 | ], config:{lanes: 8, hspace:1024}} 140 | .... 141 | 142 | .Virtual Supervisor Control Transfer Records Control Register Field Definitions 143 | [%unbreakable] 144 | [width="100%",cols="20%,80%",options="header",] 145 | |=== 146 | |Field |Description 147 | |S |Enable transfer recording in VS-mode. 148 | |U |Enable transfer recording in VU-mode. 149 | |STE |Enables recording of traps to VS-mode when S=0. See <>. 150 | |BPFRZ |Set `sctrstatus`.FROZEN on a breakpoint exception that traps to VS-mode. See <>. 151 | |LCOFIFRZ |Set `sctrstatus`.FROZEN on local counter overflow interrupt (LCOFI) that traps to VS-mode. See <>. 152 | 2+|Other field definitions match those of <<_supervisor_control_transfer_records_control_sctrctl, `sctrctl`>>. The optional fields implemented in `vsctrctl` should match those implemented in `sctrctl`. 153 | |=== 154 | 155 | [NOTE] 156 | [%unbreakable] 157 | ==== 158 | _Unlike the CTR status register or the CTR entry registers, the CTR control register has a VS-mode version. This allows a guest to manage the CTR configuration directly, without requiring traps to HS-mode, while ensuring that the guest configuration (most notably the privilege mode enable bits) do not impact CTR behavior when V=0._ 159 | ==== 160 | 161 | === Supervisor Control Transfer Records Depth Register (`sctrdepth`) 162 | 163 | The 32-bit `sctrdepth` register specifies the depth of the CTR buffer. 164 | 165 | .Supervisor Control Transfer Records Depth Register Format 166 | [%unbreakable] 167 | [wavedrom, , svg] 168 | .... 169 | {reg: [ 170 | {bits: 3, name: 'DEPTH'}, 171 | {bits: 29, name: 'WPRI'}, 172 | ], config:{lanes: 1, hspace:1024}} 173 | .... 174 | 175 | .Supervisor Control Transfer Records Depth Register Field Definitions 176 | [%unbreakable] 177 | [width="100%",cols="15%,85%",options="header",] 178 | |=== 179 | |Field |Description 180 | |DEPTH |WARL field that selects the depth of the CTR buffer. Encodings: 181 | 182 | ‘000 - 16 183 | 184 | ‘001 - 32 185 | 186 | ‘010 - 64 187 | 188 | ‘011 - 128 189 | 190 | ‘100 - 256 191 | 192 | '11x - reserved 193 | 194 | The depth of the CTR buffer dictates the number of entries to which the hardware records transfers. For a depth of N, the hardware records transfers to entries 0..N-1. All <<_entry_registers, Entry Registers>> read as '0' and are read-only when the selected entry is in the range N to 255. When the depth is increased, the newly accessible entries contain unspecified but legal values. 195 | 196 | It is implementation-specific which DEPTH value(s) are supported. 197 | |=== 198 | 199 | Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply. See <>. 200 | 201 | [NOTE] 202 | [%unbreakable] 203 | ==== 204 | _It is expected that operating systems (OSs) will access `sctrdepth` only at boot, to select the maximum supported depth value. More frequent accesses may result in reduced performance in virtualization scenarios, as a result of traps from VS-mode incurred._ 205 | 206 | _There may be scenarios where software chooses to operate on only a subset of the entries, to reduce overhead. In such cases tools may choose to read only the lower entries, and OSs may choose to save/restore only on the lower entries while using SCTRCLR to clear the others._ 207 | 208 | _The value in configurable depth lies in supporting VM migration. It is expected that a platform spec may specify that one or more CTR depth values must be supported. A hypervisor may wish to restrict guests to using one of these required depths, in order to ensure that such guests can be migrated to any system that complies with the platform spec. The trapping behavior specified for VS-mode accesses to `sctrdepth` ensures that the hypervisor can impose such restrictions._ 209 | ==== 210 | 211 | === Supervisor Control Transfer Records Status Register (`sctrstatus`) 212 | 213 | The 32-bit `sctrstatus` register grants access to CTR status information and is updated by the hardware whenever CTR is active. CTR is active when the current privilege mode is enabled for recording and CTR is not frozen. 214 | 215 | .Supervisor Control Transfer Records Status Register Format 216 | [%unbreakable] 217 | [wavedrom, , svg] 218 | .... 219 | {reg: [ 220 | {bits: 8, name: 'WRPTR'}, 221 | {bits: 23, name: 'WPRI'}, 222 | {bits: 1, name: 'FROZEN'}, 223 | ], config:{lanes: 2, hspace:1024}} 224 | .... 225 | 226 | .Supervisor Control Transfer Records Status Register Field Definitions 227 | [%unbreakable] 228 | [width="100%",cols="15%,85%",options="header",] 229 | |=== 230 | |Field |Description 231 | |WRPTR |WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value. 232 | |FROZEN |Inhibit transfer recording. See <>. 233 | |=== 234 | 235 | Undefined bits in `sctrstatus` are WPRI. Status fields may be added by future extensions, 236 | and software should ignore but preserve any fields that it does not recognize. Undefined bits must be implemented as read-only 0, unless a custom extension is implemented and enabled (see <>). 237 | 238 | [NOTE] 239 | [%unbreakable] 240 | ==== 241 | _Logical entry 0, accessed via `sireg*` when `siselect`=0x200, is always the physical buffer entry preceding the WRPTR entry. More generally, the physical buffer entry Y associated with logical entry X (X < depth) can be determined using the formula Y = (WRPTR - X - 1) % depth, where depth = 2^(DEPTH+4)^. Logical entries >= depth are read-only 0._ 242 | ==== 243 | [NOTE] 244 | [%unbreakable] 245 | ==== 246 | _Because the `sctrstatus` register is updated by hardware, writes should be performed with caution. If a multi-instruction read-modify-write to `sctrstatus` is performed while CTR is active, and between the read and write a qualified transfer or trap that causes CTR freeze completes, a hardware update could be lost. Software may wish to ensure that CTR is inactive before performing a read-modify-write, by ensuring that either `sctrstatus`.FROZEN=1, or that the current privilege mode is not enabled for recording._ 247 | 248 | _When restoring CTR state, `sctrstatus` should be written before CTR entry state is restored. This ensures that the software writes to logical CTR entries modify the proper physical entries._ 249 | ==== 250 | 251 | [NOTE] 252 | [%unbreakable] 253 | ==== 254 | _Exposing the WRPTR provides a more efficient means for synthesizing CTR entries. If a qualified control transfer is emulated, the emulator can simply increment the WRPTR, then write the synthesized record to logical entry 0. If a qualified function return is emulated while RASEMU=1, the emulator can clear `ctrsource`.V for logical entry 0, then decrement the WRPTR._ 255 | 256 | _Exposing the WRPTR may also allow support for Linux perf's https://lwn.net/Articles/802821[[.underline]#stack stitching#] capability._ 257 | ==== 258 | 259 | === CSR Listing 260 | 261 | .CTR CSR List 262 | [%unbreakable] 263 | [width="100%",cols="^12%,18%,70%",options="header",] 264 | |=== 265 | | CSR Number | Name | Description 266 | | 0x14E | `sctrctl` | Supervisor Control Transfer Records Control Register 267 | | 0x14F | `sctrstatus` | Supervisor Control Transfer Records Status Register 268 | | 0x15F | `sctrdepth` | Supervisor Control Transfer Records Depth Register 269 | | 0x24E | `vsctrctl` | Virtual Supervisor Control Transfer Records Control Register 270 | | 0x34E | `mctrctl` | Machine Control Transfer Records Control Register 271 | |=== 272 | 273 | [NOTE] 274 | ==== 275 | _Because the ROI of CTR is perceived to be low for RV32 implementations, CTR does not fully support RV32. While control flow transfers in RV32 can be recorded, RV32 cannot access_ `x__ctrctl__` _bits 63:32. A future extension could add support for RV32 by adding 3 new CSRs (`mctrctlh`, `sctrctlh`, and `vsctrctlh`) to provide this access._ 276 | ==== 277 | 278 | [NOTE] 279 | [%unbreakable] 280 | ==== 281 | _Smctr/Ssctr depends upon implementation of S-mode because much of CTR state is accessible only through S-mode CSRs. If, in the future, it becomes desirable to remove this dependency, an extension could add `mctrdepth` and `mctrstatus` CSRs that reflect the same state as `sctrdepth` and `sctrstatus`, respectively. Further, such an extension should make CTR entries accessible via `miselect`/`mireg*`. See <>._ 282 | ==== 283 | 284 | 285 | == Entry Registers 286 | 287 | Control transfer records are stored in a CTR buffer, such that each buffer entry stores information about a single transfer. The CTR buffer entries are logically accessed via the indirect register access mechanism defined by the 288 | https://github.com/riscv/riscv-indirect-csr-access/releases[[.underline]#Sscsrind#] 289 | extension. The `siselect` index range 0x200 through 0x2FF is reserved for CTR 290 | logical entries 0 through 255. When `siselect` holds a value in this range, `sireg` provides access to <<_control_transfer_record_source_ctrsource, `ctrsource`>>, `sireg2` provides access to <<_control_transfer_record_target_ctrtarget, `ctrtarget`>>, and `sireg3` provides access to <<_control_transfer_record_source_ctrdata, `ctrdata`>>. `sireg4`, `sireg5`, and `sireg6` are read-only 0. 291 | 292 | When `vsiselect` holds a value in 0x200..0x2FF, the `vsireg*` registers provide access to the same CTR entry register state as the analogous `sireg*` registers. There is not a separate set of entry registers for V=1. 293 | 294 | See <> for cases where CTR accesses from S-mode and VS-mode may be restricted. 295 | 296 | === Control Transfer Record Source Register (`ctrsource`) 297 | 298 | The `ctrsource` register contains the source program counter, which is the `pc` of the recorded control transfer instruction, or the epc of the recorded trap. The valid (V) bit is set by the hardware when a transfer is recorded in the selected CTR buffer entry, and implies that 299 | data in `ctrsource`, `ctrtarget`, and `ctrdata` is valid for this entry. 300 | 301 | `ctrsource` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implict writes (for recorded transfers) will be zero-extended. 302 | 303 | .Control Transfer Record Source Register Format for MXLEN=64 304 | [%unbreakable] 305 | [wavedrom, , svg] 306 | .... 307 | {reg: [ 308 | {bits: 1, name: 'V'}, 309 | {bits: 63, name: 'PC[63:1]'}, 310 | ], config:{lanes: 1, hspace: 1024}} 311 | .... 312 | 313 | [NOTE] 314 | [%unbreakable] 315 | ==== 316 | _CTR entry registers are defined as MXLEN, despite the_ `x__ireg*__` _CSRs used to access them being XLEN, to ensure that entries recorded in RV64 are not truncated, as a result of CSR Width Modulation, on a transition to RV32._ 317 | ==== 318 | 319 | === Control Transfer Record Target Register (`ctrtarget`) 320 | 321 | The `ctrtarget` register contains the target (destination) program counter 322 | of the recorded transfer. The optional MISP bit is set by the hardware 323 | when the recorded transfer is an instruction whose target or 324 | taken/not-taken direction was mispredicted by the branch predictor. MISP 325 | is read-only 0 when not implemented. 326 | 327 | `ctrtarget` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implict writes (by recorded transfers) will be zero-extended. 328 | 329 | .Control Transfer Record Target Register Format for MXLEN=64 330 | [%unbreakable] 331 | [wavedrom, , svg] 332 | .... 333 | {reg: [ 334 | {bits: 1, name: 'MISP'}, 335 | {bits: 31, name: 'PC[31:1]'}, 336 | {bits: 32, name: 'PC[63:32]'}, 337 | ], config:{lanes: 2, hspace: 1024}} 338 | .... 339 | 340 | === Control Transfer Record Metadata Register (`ctrdata`) 341 | 342 | The `ctrdata` register contains metadata for the recorded transfer. This 343 | register must be implemented, though all fields within it are optional. 344 | Unimplemented fields are read-only 0. `ctrdata` is a 64-bit register. 345 | 346 | .Control Transfer Record Metadata Register Format 347 | [%unbreakable] 348 | [wavedrom, , svg] 349 | .... 350 | {reg: [ 351 | {bits: 4, name: 'TYPE'}, 352 | {bits: 11, name: 'WPRI'}, 353 | {bits: 1, name: 'CCV'}, 354 | {bits: 16, name: 'CC'}, 355 | {bits: 32, name: 'WPRI'}, 356 | ], config:{lanes: 2, hspace: 1024}} 357 | .... 358 | 359 | .Control Transfer Record Metadata Register Field Definitions 360 | [%unbreakable] 361 | [width="100%",cols="15%,75%,10%",options="header",] 362 | |=== 363 | |Field |Description |Access 364 | |TYPE[3:0] a| 365 | Identifies the type of the control flow transfer recorded in the entry, using the encodings listed in xref:transfer-type-defs[xrefstyle=short]. Implementations that do not support this field will report 0. 366 | |WARL 367 | 368 | |CCV |Cycle Count Valid. See <>. |WARL 369 | 370 | |CC[15:0] |Cycle Count, composed of the Cycle Count Exponent (CCE, in 371 | CC[15:12]) and Cycle Count Mantissa (CCM, in CC[11:0]). See 372 | <>. |WARL 373 | |=== 374 | 375 | Undefined bits in `ctrdata` are WPRI. Undefined bits must be implemented as read-only 0, unless a <<_custom_extensions, custom extension>> is implemented and enabled. 376 | 377 | [NOTE] 378 | [%unbreakable] 379 | ==== 380 | _Like the <<_transfer_type_filtering, Transfer Type Filtering>> bits in `mctrctl`, the `ctrdata`.TYPE bits leverage the E-trace itype encodings._ 381 | ==== 382 | 383 | == Instructions 384 | === Supervisor CTR Clear Instruction 385 | 386 | [wavedrom, ,svg] 387 | .... 388 | {reg: [ 389 | {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM'], type: 8}, 390 | {bits: 5, name: 'rd', attr: ['5', '0'], type: 2}, 391 | {bits: 3, name: 'funct3', attr: ['3', '0'], type: 8}, 392 | {bits: 5, name: 'rs1', attr: ['5', '0'], type: 4}, 393 | {bits: 12, name: 'func12', attr: ['12', 'SCTRCLR (0x104)'], type: 8}, 394 | ]} 395 | .... 396 | 397 | The SCTRCLR instruction performs the following operations: 398 | 399 | * Zeroes all CTR <<_entry_registers, Entry Registers>>, for all DEPTH values 400 | * Zeroes the CTR cycle counter and CCV (see <>) 401 | 402 | Any read of `ctrsource`, `ctrtarget`, or `ctrdata` that follows SCTRCLR, such that it precedes the next qualified control transfer, will return the value 0. Further, the first recorded transfer following SCTRCLR will have `ctrdata`.CCV=0. 403 | 404 | SCTRCLR raises an illegal-instruction exception in U-mode, and a virtual-instruction exception in VU-mode, unless CTR state enable access restrictions apply. See <>. 405 | 406 | == State Enable Access Control 407 | 408 | When Smstateen is implemented, the `mstateen0`.CTR bit controls access to CTR register state from privilege modes less privileged than M-mode. When `mstateen0`.CTR=1, accesses to CTR register state behave as described in <> and <> above, while SCTRCLR behaves as described in <>. When `mstateen0`.CTR=0 and the privilege mode is less privileged than M-mode, the following operations raise an illegal-instruction exception: 409 | 410 | * Attempts to access `sctrctl`, `vsctrctl`, `sctrdepth`, or `sctrstatus` 411 | * Attempts to access `sireg*` when `siselect` is in 0x200..0x2FF, or `vsireg*` when `vsiselect` is in 0x200..0x2FF 412 | * Execution of the SCTRCLR instruction 413 | 414 | When `mstateen0`.CTR=0, qualified control transfers executed in privilege modes less privileged than M-mode will continue to implicitly update entry registers and `sctrstatus`. 415 | 416 | If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1. This state includes `sctrctl` (really `vsctrctl`), `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF. `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0. 417 | 418 | When `mstateen0`.CTR=1 and `hstateen0`.CTR=1, VS-mode accesses to supervisor CTR state behave as described in <> and <> above, while SCTRCLR behaves as described in <>. When `mstateen0`.CTR=1 and `hstateen0`.CTR=0, both VS-mode accesses to supervisor CTR state and VS-mode execution of SCTRCLR raise a virtual-instruction exception. 419 | 420 | [NOTE] 421 | [%unbreakable] 422 | ==== 423 | `__sctrdepth__` _is not included in the above list of supervisor CTR state controlled by `hstateen0`.CTR since accesses to `sctrdepth` from VS-mode raise a virtual-instruction exception regardless of the value of `hstateen0`.CTR._ 424 | ==== 425 | 426 | When `hstateen0`.CTR=0, qualified control transfers executed while V=1 will continue to implicitly update entry registers and `sctrstatus`. 427 | 428 | The CTR bit is bit 54 in `mstateen0` and `hstateen0`. 429 | 430 | [NOTE] 431 | [%unbreakable] 432 | ==== 433 | _See the https://github.com/riscv/riscv-indirect-csr-access[[.underline]#Sscsrind spec#] for how bit 60 in `mstateen0` and `hstateen0` can also restrict access to `sireg*`/`siselect` and `vsireg*`/`vsiselect` from privilege modes less privileged than M-mode._ 434 | ==== 435 | 436 | == Behavior 437 | 438 | CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria: 439 | 440 | * The current privilege mode is enabled 441 | * The transfer type is not inhibited 442 | * `sctrstatus`.FROZEN is not set 443 | * The transfer completes/retires 444 | 445 | Such qualified transfers update the <<_entry_registers, Entry Registers>> at logical entry 0. As a result, older entries are pushed down the stack; the record previously in logical entry 0 moves to logical entry 1, the record in logical entry 1 moves to logical entry 2, and so on. If the CTR buffer is full, the oldest recorded entry (previously at entry depth-1) is lost. 446 | 447 | Recorded transfers will set the `ctrsource`.V bit to 1, and will update all implemented record fields. 448 | 449 | [NOTE] 450 | [%unbreakable] 451 | ==== 452 | _In order to collect accurate and representative performance profiles while using CTR, it is recommended that hardware recording of control transfers incurs no added performance overhead, e.g., in the form of retirement or instruction execution restrictions that are not present when CTR is not active._ 453 | ==== 454 | 455 | === Privilege Mode Transitions 456 | 457 | Transfers that change the privilege mode are a special case. What is 458 | recorded, if anything, depends on whether the source privilege mode 459 | and/or target privilege mode are enabled for recording, and on the transfer type (trap 460 | or trap return). 461 | 462 | Traps between enabled privilege modes are recorded as normal. Traps from a disabled privilege mode to an enabled privilege mode are partially recorded, such that the `ctrsource`.PC is 0. Traps from an enabled mode to a disabled mode, known as external traps, are not recorded by default. See <> for how they can be recorded. 463 | 464 | Trap returns have similar treatment. Trap returns between enabled privilege modes are recorded as normal. Trap returns from an enabled mode back to a disabled mode are partially recorded, such that `ctrtarget`.PC is 0. Trap returns from a disabled mode to an enabled mode are not recorded. 465 | 466 | [NOTE] 467 | ==== 468 | _If privileged software is configuring CTR on behalf of less privileged software, it should ensure that its privilege mode enable bit (e.g., `sctrctl`.S for Supervisor software) is cleared before a trap return to the less privileged mode. Otherwise the trap return will be recorded, leaking the privileged source `pc`._ 469 | ==== 470 | 471 | Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded. 472 | 473 | The table below provides details on recording of privilege mode transitions. Standard dependencies on FROZEN and transfer type inhibits also apply, but are not covered by the table. 474 | 475 | .Trap and Trap Return Recording 476 | [%unbreakable] 477 | [width="100%",cols="18%,17%,30%,35%",] 478 | |=== 479 | .2+|*Transfer Type* .2+| *Source Mode* 2+|*Target Mode* 480 | |*Enabled* |*Disabled* 481 | .2+|*Trap* |*Enabled* |Recorded. | External trap. Not recorded by default, but see <>. 482 | 483 | |*Disabled* |Recorded, `ctrsource`.PC is 0. |Not recorded. 484 | 485 | .2+|*Trap Return* |*Enabled* |Recorded. |Recorded, `ctrtarget`.PC is 0. 486 | 487 | |*Disabled* |Not recorded. |Not recorded. 488 | |=== 489 | 490 | ==== Virtualization Mode Transitions 491 | 492 | Transitions between VS/VU-mode and M/HS-mode are unique in that they effect a change in the active CTR control register, and hence the CTR configuration. What is recorded, if anything, on these virtualization mode transitions depends upon fields from both `[ms]ctrctl` and `vsctrctl`. 493 | 494 | * `mctrctl`.M, `sctrctl`.S, and `vsctrctl`.{S,U} are used to determine whether the source and target modes are enabled; 495 | * `mctrctl`.MTE, `sctrctl`.STE, and `vsctrctl`.STE are used to determine whether an external trap is recorded (see <>); 496 | * `sctrctl`.LCOFIFRZ and `sctrctl`.BPFRZ determine whether CTR becomes frozen (see <>) 497 | * For all other `__x__ctrctl` fields, the value in `vsctrctl` is used. 498 | 499 | [NOTE] 500 | ==== 501 | _Consider an exception that traps from VU-mode to HS-mode, with `vsctrctl`.U=1 and `sctrctl`.S=1. Because both the source mode and target mode are enabled for recording, whether the trap is recorded then depends on the CTR configuration (e.g., the <<_transfer_type_filtering, transfer type filter>> bits) in `vsctrctl`, not in `sctrctl`._ 502 | ==== 503 | 504 | ==== External Traps 505 | 506 | External traps are traps from a privilege mode enabled for CTR recording to a privilege mode that is not enabled for CTR recording. By default external traps are not recorded, but privileged software running in the target mode of the trap can opt-in to allowing CTR to record external traps into that mode. The `__x__ctrctl`.__x__TE bits allow M-mode, S-mode, and VS-mode to opt-in separately. 507 | 508 | External trap recording depends not only on the target mode, but on any intervening modes, which are modes that are more privileged than the source mode but less privileged than the target mode. Not only must the external trap enable bit for the target mode be set, but the external trap enable bit(s) for any intervening modes must also be set. See the table below for details. 509 | 510 | [NOTE] 511 | [%unbreakable] 512 | ==== 513 | _Requiring intervening modes to be enabled for external traps simplifies software management of CTR. Consider a scenario where S-mode software is configuring CTR for U-mode contexts A and B, such that external traps (to any mode) are enabled for A but not for B. When switching between the two contexts, S-mode can simply toggle `sctrctl`.STE, rather than requiring a trap to M-mode to additionally toggle `mctrctl`.MTE._ 514 | 515 | _This method does not provide the flexibility to record external traps to a more privileged mode but not to all intervening mode(s). Because it is expected that profiling tools generally wish to observe all external traps or none, this is not considered a meaningful limitation._ 516 | ==== 517 | 518 | .External Trap Enable Requirements 519 | [%unbreakable] 520 | [options="header", width="85%", cols="23%,23%,54%"] 521 | |=== 522 | |Source Mode |Target Mode |External Trap Enable(s) Required 523 | .2+|U-mode | S-mode | `sctrctl`.STE 524 | |M-mode | `mctrctl`.MTE, `sctrctl`.STE 525 | |S-mode | M-mode | `mctrctl`.MTE 526 | .3+|VU-mode | VS-mode | `vsctrctl`.STE 527 | | HS-mode | `sctrctl`.STE, `vsctrctl`.STE 528 | | M-mode | `mctrctl`.MTE, `sctrctl`.STE, `vsctrctl`.STE 529 | .2+| VS-mode | HS-mode | `sctrctl`.STE 530 | | M-mode | `mctrctl`.MTE, `sctrctl`.STE 531 | |=== 532 | 533 | In records for external traps, the `ctrtarget`.PC is 0. 534 | 535 | [NOTE] 536 | [%unbreakable] 537 | ==== 538 | _No mechanism exists for recording external trap returns, because 539 | the external trap record includes all relevant information, and gives 540 | the trap handler (e.g., an emulator) the opportunity to modify the 541 | record._ 542 | ==== 543 | 544 | [NOTE] 545 | [%unbreakable] 546 | ==== 547 | _Note that external trap recording does not depend on EXCINH/INTRINH. Thus, when external traps are enabled, both external interrupts and external exceptions are recorded._ 548 | 549 | _STE allows recording of traps from U-mode to S-mode as well as from VS/VU-mode to HS-mode. The hypervisor can flip `sctrctl`.STE before entering a guest if it wants different behavior for U-to-S vs VS/VU-to-HS._ 550 | ==== 551 | 552 | If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented. 553 | 554 | === Transfer Type Filtering 555 | 556 | Default CTR behavior, when all transfer type filter bits (`__x__ctrctl`[47:32]) are unimplemented or 0, is to record all control transfers within enabled privileged modes. By setting transfer type filter bits, software can opt out of recording select transfer types, or opt into recording non-default operations. All transfer type filter bits are optional. 557 | 558 | [NOTE] 559 | [%unbreakable] 560 | ==== 561 | _Because not-taken branches are not recorded by default, the polarity of the associated enable bit (NTBREN) is the opposite of other bits associated with transfer type filtering (TKBRINH, RETINH, etc). Non-default operations require opt-in rather than opt-out._ 562 | ==== 563 | 564 | The transfer type filter bits leverage the type definitions specified 565 | in the 566 | https://github.com/riscv-non-isa/riscv-trace-spec/releases/download/v2.0rc2/riscv-trace-spec.pdf[[.underline]#RISC-V Efficient Trace Spec v2.0#] (Table 4.4 and Section 4.1.1). For completeness, the definitions are reproduced below. 567 | 568 | [NOTE] 569 | ==== 570 | _Here "indirect" is used interchangeably with "uninferrable", which is used in the trace spec. Both imply that the target of the jump is not encoded in the opcode._ 571 | ==== 572 | 573 | .Control Transfer Type Definitions 574 | [#transfer-type-defs] 575 | [%unbreakable] 576 | [width="60%", cols="22%,78%", options="header",] 577 | |=== 578 | | Encoding | Transfer Type Name 579 | | 0 | _Not used by CTR_ 580 | | 1 | Exception 581 | | 2 | Interrupt 582 | | 3 | Trap return 583 | | 4 | Not-taken branch 584 | | 5 | Taken branch 585 | | 6 | _reserved_ 586 | | 7 | _reserved_ 587 | | 8 | Indirect call 588 | | 9 | Direct call 589 | | 10 | Indirect jump (without linkage) 590 | | 11 | Direct jump (without linkage) 591 | | 12 | Co-routine swap 592 | | 13 | Function return 593 | | 14 | Other indirect jump (with linkage) 594 | | 15 | Other direct jump (with linkage) 595 | |=== 596 | 597 | Encodings 8 through 15 refer to various encodings of jump instructions. The types are distinguished as described below. 598 | 599 | .Control Transfer Type Definitions 600 | [%unbreakable] 601 | [cols="37%,63%", options="header",] 602 | |=== 603 | | Transfer Type Name | Associated Opcodes 604 | .3+| Indirect call | JALR _x1_, _rs_ where _rs_ != _x5_ 605 | | JALR _x5_, _rs_ where _rs_ != _x1_ 606 | | C.JALR _rs1_ where _rs1_ != _x5_ 607 | .4+| Direct call | JAL _x1_ 608 | | JAL _x5_ 609 | | C.JAL 610 | | CM.JALT _index_ 611 | .2+| Indirect jump (without linkage) | JALR _x0_, _rs_ where _rs_ != (_x1_ or _x5_) 612 | | C.JR _rs1_ where _rs1_ != (_x1_ or _x5_) 613 | .3+| Direct jump (without linkage) | JAL _x0_ 614 | | C.J 615 | | CM.JT _index_ 616 | .3+| Co-routine swap | JALR _x1_, _x5_ 617 | | JALR _x5_, _x1_ 618 | | C.JALR _x5_ 619 | .3+| Function return | JALR _rd_, _rs_ where _rs_ == (_x1_ or _x5_) and _rd_ != (_x1_ or _x5_) 620 | | C.JR _rs1_ where _rs1_ == (_x1_ or _x5_) 621 | | CM.POPRET(Z) 622 | | Other indirect jump (with linkage) | JALR _rd_, _rs_ where _rs_ != (_x1_ or _x5_) and _rd_ != (_x0_, _x1_, or _x5_) 623 | | Other direct jump (with linkage) | JAL _rd_ where _rd_ != (_x0_, _x1_, or _x5_) 624 | |=== 625 | 626 | 627 | [NOTE] 628 | [%unbreakable] 629 | ==== 630 | _If implementation of any transfer type filter bit results in reduced software performance, perhaps due to additional retirement restrictions, it is strongly recommended that this reduced performance apply only when the bit is set. Alternatively, support for the bit may be omitted. Maintaining software performance for the default CTR configuration, when all transfer type bits are cleared, is recommended._ 631 | ==== 632 | 633 | === Cycle Counting 634 | 635 | The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record. The elapsed cycle count value is represented by the CC field, which has a 12-bit mantissa component (Cycle Count Mantissa, or CCM) and a 4-bit exponent component (Cycle Count Exponent, or CCE). 636 | 637 | The elapsed cycle counter (CtrCycleCounter) increments at the same rate as the `mcycle` counter. Only cycles while CTR is active are counted, where active implies that the current privilege mode is enabled for recording and CTR is not frozen. The CC field is encoded such that CCE holds 0 if the CtrCycleCounter value is less than 4096, otherwise it holds the index of the most significant one bit in the CtrCycleCounter value, minus 11. CCM holds CtrCycleCounter bits CCE+10:CCE-1. 638 | 639 | The elapsed cycle count can then be calculated by software using the following formula: 640 | 641 | [subs="specialchars,quotes"] 642 | [%unbreakable] 643 | ---- 644 | if (CCE==0): 645 | return CCM 646 | else: 647 | return (2^12^ + CCM) << CCE-1 648 | endif 649 | ---- 650 | 651 | The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch. 652 | 653 | An implementation that supports cycle counting must implement CCV and all 654 | CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE 655 | bits are read-only 0. For implementations that support transfer type 656 | filtering, it is recommended to implement at least 3 exponent bits. This 657 | allows capturing the full latency of most functions, when recording only 658 | calls and returns. 659 | 660 | The size of the CtrCycleCounter required to support each CCE width is given in the table below. 661 | 662 | .Cycle Counter Size Options 663 | [%unbreakable] 664 | [width="70%", cols="20%,38%,42%", options="header",] 665 | |=== 666 | | CCE bits | CtrCycleCounter bits | Max elapsed cycle value 667 | | 0 | 12 | 4095 668 | | 1 | 13 | 8191 669 | | 2 | 15 | 32764 670 | | 3 | 19 | 524224 671 | | 4 | 27 | 134201344 672 | |=== 673 | 674 | [NOTE] 675 | [%unbreakable] 676 | ==== 677 | _When CCE>1, the granularity of the reported cycle count is reduced. For example, when CCE=3, the bottom 2 bits of the cycle counter are not reported, and thus the reported value increments only every 4 cycles. As a result, the reported value represents an undercount of elapsed cycles for most cases (when the unreported bits are non-zero). On average, the undercount will be (2^CCE-1^-1)/2. Software can reduce the average undercount to 0 by adding (2^CCE-1^-1)/2 to each computed cycle count value when CCE>1._ 678 | 679 | _Though this compressed method of representation results in some imprecision for larger cycle count values, it produces meaningful area savings, reducing storage per entry from 27 bits to 16._ 680 | ==== 681 | 682 | The CC value saturates when all implemented bits in CCM and CCE are 1. 683 | 684 | The CC value is only valid when the Cycle Count Valid (CCV) bit is set. If CCV=0, the CC value might not hold the correct count of elapsed active cycles since the last recorded transfer. The next record will have CCV=0 after a write to `__x__ctrctl`, or execution of SCTRCLR, since CtrCycleCounter is reset. CCV should additionally be cleared after any other implementation-specific scenarios where active cycles might not be counted in CtrCycleCounter. 685 | 686 | === RAS (Return Address Stack) Emulation Mode 687 | 688 | When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS). 689 | 690 | * Indirect and direct calls are recorded as normal 691 | * Function returns pop the most recent call, by decrementing the WRPTR then invalidating the WRPTR entry (by setting ctrsource.V=0). As a result, logical entry 0 is invalidated and moves to logical entry depth-1, while logical entries 1..depth-1 move to 0..depth-2. 692 | * Co-routine swaps affect both a return and a call. Logical entry 0 is 693 | overwritten, and WRPTR is not modified. 694 | * Other transfer types are inhibited 695 | * Transfer type filtering bits (`__x__ctrctl`[47:32]) and external trap enable bits (`__x__ctrctl`.__x__TE) are ignored 696 | 697 | [NOTE] 698 | [%unbreakable] 699 | ==== 700 | _Profiling tools often collect call stacks along with each sample. Stack 701 | walking, however, is a complex and often slow process that may require 702 | recompilation (e.g., -fno-omit-frame-pointer) to work reliably. With RAS 703 | emulation, tools can ask CTR hardware to save call stacks even for 704 | unmodified code._ 705 | 706 | _CTR RAS emulation has limitations. The CTR buffer will contain only partial stacks in cases where the call stack depth was greater than the CTR depth, CTR recording was enabled at a lower point in the call stack than main(), or where the CTR buffer was cleared since main()._ 707 | 708 | _The CTR stack may be corrupted in cases where calls and returns are not symmetric, such as with stack unwinding (e.g., setjmp/longjmp, C++ exceptions), where stale call entries may be left on the CTR stack, or user stack switching, where calls from multiple stacks may be intermixed._ 709 | ==== 710 | 711 | [NOTE] 712 | [%unbreakable] 713 | ==== 714 | _As described in <>, 715 | when CCV=1, the CC field provides the elapsed cycles since the prior CTR 716 | entry was recorded. This introduces implementation challenges when 717 | RASEMU=1 because, for each recorded call, there may have been several 718 | recorded calls (and returns which “popped” them) since the prior 719 | remaining call entry was recorded (see <>). The implication is that returns that 720 | pop a call entry not only do not reset the cycle counter, but instead 721 | add the CC field from the popped entry to the counter. For simplicity, 722 | an implementation may opt to record CCV=0 for all calls, or those whose parent call was popped, when RASEMU=1._ 723 | ==== 724 | 725 | === Freeze 726 | 727 | When `sctrstatus`.FROZEN=1, transfer recording is inhibited. This bit can be set by hardware, as described below, or by software. 728 | 729 | When `sctrctl`.LCOFIFRZ=1 and a local counter overflow interrupt 730 | (LCOFI) traps (as a result of an HPM counter overflow) to M-mode or to S-mode, `sctrstatus`.FROZEN is set by hardware. This inhibits CTR recording until software clears FROZEN. The LCOFI trap itself is not recorded. 731 | [NOTE] 732 | [%unbreakable] 733 | ==== 734 | _Freeze on LCOFI ensures that the execution path leading to the sampled instruction (`xepc`) is preserved, and that the local counter overflow interrupt (LCOFI) and associated Interrupt Service Routine (ISR) do not displace any recorded transfer history state. It is the responsibility of the ISR to clear FROZEN before xRET, if continued control transfer recording is desired._ 735 | 736 | _LCOFI refers only to architectural traps directly caused by a local counter overflow. If a local counter overflow interrupt is recognized without a trap, FROZEN is not automatically set. For instance, no freeze occurs if the LCOFI is pended while interrupts are masked, and software recognizes the LCOFI (perhaps by reading `stopi` or `sip`) and clears `sip`.LCOFIP before the trap is raised. As a result, some or all CTR history may be overwritten while handling the LCOFI. Such cases are expected to be very rare; for most usages (e.g., application profiling) privilege mode filtering is sufficient to ensure that CTR updates are inhibited while interrupts are handled in a more privileged mode._ 737 | ==== 738 | Similarly, on a breakpoint exception that traps to M-mode or S-mode with `sctrctl`.BPFRZ=1, FROZEN is set by hardware. The breakpoint exception itself is not recorded. 739 | 740 | [NOTE] 741 | [%unbreakable] 742 | ==== 743 | _Breakpoint exception refers to synchronous exceptions with a cause value of Breakpoint (3), regardless of source (ebreak, c.ebreak, Sdtrig); it does not include entry into Debug Mode, even in cores where this is implemented as an exception._ 744 | ==== 745 | 746 | If the H extension is implemented, freeze behavior for LCOFIs and breakpoint exceptions that trap to VS-mode is determined by the LCOFIFRZ and BPFRZ values, respectively, in `vsctrctl`. This includes virtual LCOFIs pended by a hypervisor. 747 | 748 | [NOTE] 749 | [%unbreakable] 750 | ==== 751 | _When a guest uses the SBI Supervisor Software Events (SSE) extension, the LCOFI will trap to HS-mode, which will then invoke a registered VS-mode LCOFI handler routine. If `vsctrctl`.LCOFIFRZ=1, the HS-mode handler will need to emulate the freeze by setting `sctrstatus`.FROZEN=1 before invoking the registered handler routine._ 752 | ==== 753 | 754 | 755 | == Custom Extensions 756 | 757 | Any custom CTR extension must be associated with a non-zero value within the designated custom bits in `__x__ctrctl`. When the custom bits hold a non-zero value that enables a custom extension, the extension may alter standard CTR behavior, and may define new custom status fields within <<_supervisor_control_transfer_records_status_sctrstatus, `sctrstatus`>> or the CTR <<_entry_registers, Entry Registers>>. All custom status fields, and standard status fields whose behavior is altered by the custom extension, must revert to standard behavior when the custom bits hold zero. This includes read-only 0 behavior for any bits undefined by any implemented standard extensions. 758 | 759 | -------------------------------------------------------------------------------- /chapter2.adoc: -------------------------------------------------------------------------------- 1 | [[chapter2]] 2 | == The Second Chapter 3 | 4 | . The first item. 5 | 6 | . The second item. 7 | + 8 | .. The first sub item. 9 | 10 | .. The second sub item. 11 | + 12 | [CAUTION] 13 | ==== 14 | A moment of caution is required for this block of text must be read and apreciated for its importance. 15 | ==== 16 | 17 | . Yet another item. 18 | 19 | . Again, an item. 20 | 21 | .. A multi-line item. 22 | + 23 | This item has multiple lines. 24 | + 25 | By multiple lines, this is what we mean. 26 | + 27 | Seriously, multiple. 28 | 29 | === An example table 30 | 31 | [cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] 32 | |=== 33 | 4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area 34 | |L|R|W|X|Quarter 1|Quarter 2 35 | |{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors 36 | |0|0|0|1|Thing 1|Thing 2 37 | |1|0|0|0|Thing 3|Thing 4 38 | |1|1|1|1 2+|Span Thing 1 and 2 39 | |=== 40 | 41 | === Sub section 42 | 43 | Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet. 44 | 45 | === Yet another subsection 46 | 47 | Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur. 48 | -------------------------------------------------------------------------------- /contributors.adoc: -------------------------------------------------------------------------------- 1 | == Contributors 2 | 3 | This RISC-V specification has been contributed to directly or indirectly by: 4 | 5 | [%hardbreaks] 6 | * Beeman Strong 7 | * Bruce Ableidinger 8 | * Snehasish Kumar 9 | * Robert Chyla 10 | * John Simpson 11 | * Ved Shanbhogue 12 | * Stefan O'Rear 13 | * Allen Baum 14 | -------------------------------------------------------------------------------- /dependencies/Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | gem 'asciidoctor' 3 | gem 'asciidoctor-bibtex' 4 | gem 'asciidoctor-diagram' 5 | gem 'asciidoctor-mathematical' 6 | gem 'asciidoctor-pdf' 7 | gem 'citeproc-ruby' 8 | gem 'coderay' 9 | gem 'csl-styles' 10 | gem 'json' 11 | gem 'pygments.rb' 12 | gem 'rghost' 13 | gem 'rouge' 14 | gem 'ruby_dev' 15 | -------------------------------------------------------------------------------- /dependencies/README.md: -------------------------------------------------------------------------------- 1 | Dependencies for the build environment for various package managers. Used in 2 | `.github/workflows/`. 3 | 4 | -------------------------------------------------------------------------------- /dependencies/apt_packages.txt: -------------------------------------------------------------------------------- 1 | bison 2 | build-essential 3 | cmake 4 | curl 5 | flex 6 | fonts-lyx 7 | git 8 | graphviz 9 | # For wavedrom 10 | default-jre 11 | libcairo2-dev 12 | libffi-dev 13 | libgdk-pixbuf2.0-dev 14 | libpango1.0-dev 15 | libxml2-dev 16 | make 17 | pkg-config 18 | ruby 19 | ruby-dev 20 | -------------------------------------------------------------------------------- /dependencies/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "local", 3 | "version": "0.0.1", 4 | "dependencies": { 5 | "wavedrom-cli": "^2.6.8" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /example.bib: -------------------------------------------------------------------------------- 1 | @inproceedings{riscI-isca1981, 2 | title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, 3 | author = {David A. Patterson and Carlo H. S\'{e}quin}, 4 | booktitle = {ISCA}, 5 | location = {Minneapolis, Minnesota, USA}, 6 | pages = {443-458}, 7 | year = {1981} 8 | } 9 | 10 | @InProceedings{Katevenis:1983, 11 | author = {Katevenis, Manolis G.H. and Sherburne,Jr., Robert W. and Patterson, David A. and S{\'e}quin, Carlo H.}, 12 | title = {The {RISC II} micro-architecture}, 13 | booktitle = {Proceedings VLSI 83 Conference}, 14 | year = 1983, 15 | month = {August}} 16 | 17 | @inproceedings{Ungar:1984, 18 | author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples 19 | and David Patterson}, 20 | title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, 21 | booktitle = {ISCA}, 22 | address = {Ann Arbor, MI}, 23 | year = {1984}, 24 | pages = {188--197} 25 | } 26 | 27 | @Article{spur-jsscc1989, 28 | author = {David D. Lee and Shing I. Kong and Mark D. Hill and 29 | George S. Taylor and David A. Hodges and Randy 30 | H. Katz and David A. Patterson}, 31 | title = {A {VLSI} Chip Set for a Multiprocessor 32 | Workstation--{Part I}: An {RISC} Microprocessor with 33 | Coprocessor Interface and Support for Symbolic 34 | Processing}, 35 | journal = {IEEE JSSC}, 36 | year = 1989, 37 | volume = 24, 38 | number = 6, 39 | pages = {1688--1698}, 40 | month = {December}} 41 | -------------------------------------------------------------------------------- /header.adoc: -------------------------------------------------------------------------------- 1 | [[header]] 2 | :description: RISC-V Control Transfer Records (Smctr/Ssctr) 3 | :company: RISC-V.org 4 | :revdate: 11/22/2024 5 | :revnumber: 1.0 6 | :revremark: This document is Ratified. 7 | :url-riscv: http://riscv.org 8 | :doctype: book 9 | :preface-title: Preamble 10 | :colophon: 11 | :appendix-caption: Appendix 12 | :imagesdir: docs-resources/images 13 | :title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center] 14 | // Settings: 15 | :experimental: 16 | :reproducible: 17 | // needs to be changed? bug discussion started 18 | //:WaveDromEditorApp: app/wavedrom-editor.app 19 | :imagesoutdir: docs-resources/images 20 | :bibtex-file: example.bib 21 | :bibtex-order: alphabetical 22 | :bibtex-style: apa 23 | :icons: font 24 | :lang: en 25 | :listing-caption: Listing 26 | :sectnums: 27 | :toc: left 28 | :toclevels: 4 29 | :source-highlighter: pygments 30 | ifdef::backend-pdf[] 31 | :source-highlighter: coderay 32 | endif::[] 33 | :data-uri: 34 | :hide-uri-scheme: 35 | :stem: latexmath 36 | :footnote: 37 | :xrefstyle: short 38 | 39 | = RISC-V Control Transfer Records (Smctr/Ssctr) 40 | RISC-V Control Transfer Records TG 41 | 42 | // Preamble 43 | [WARNING] 44 | .This document is in the link:http://riscv.org/spec-state[Ratified state] 45 | ==== 46 | No changes are allowed. Any desired or needed changes can be the subject of a follow-on new extension. Ratified extensions are never revised. 47 | ==== 48 | 49 | [preface] 50 | == Copyright and license information 51 | This specification is licensed under the Creative Commons 52 | Attribution 4.0 International License (CC-BY 4.0). The full 53 | license text is available at 54 | https://creativecommons.org/licenses/by/4.0/. 55 | 56 | Copyright 2024 by RISC-V International. 57 | 58 | [preface] 59 | include::contributors.adoc[] 60 | 61 | include::intro.adoc[] 62 | include::body.adoc[] 63 | //the index must precede the bibliography 64 | //include::index.adoc[] 65 | //include::bibliography.adoc[] 66 | -------------------------------------------------------------------------------- /index.adoc: -------------------------------------------------------------------------------- 1 | [index] 2 | == Index 3 | -------------------------------------------------------------------------------- /intro.adoc: -------------------------------------------------------------------------------- 1 | [[intro]] 2 | == Introduction 3 | 4 | A method for recording control flow transfer history is valuable not only for performance profiling but also for debugging. Control flow transfers refer to jump instructions (including function calls and returns), taken branch instructions, traps, and trap returns. Profiling tools, such as Linux perf, collect control transfer history when sampling software execution, thereby enabling tools, like AutoFDO, to identify hot paths for optimization. 5 | 6 | Control flow trace capabilities offer very deep transfer history, but the volume of data produced can result in significant performance overheads due to memory bandwidth consumption, buffer management, and decoder overhead. The Control Transfer Records (CTR) extension provides a method to record a limited history in register-accessible internal chip storage, with the intent of dramatically reducing the performance overhead and complexity of collecting transfer history. 7 | 8 | CTR defines a circular (FIFO) buffer. Each buffer entry holds a record for a single recorded control flow transfer. The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth). 9 | 10 | [NOTE] 11 | [%unbreakable] 12 | ==== 13 | _Software may opt to use a depth less than the maximum supported in order to reduce the latency of saving and restoring CTR state, or to emulate the maximum depth supported by other implementations, e.g. in cases of VM-migration._ 14 | ==== 15 | 16 | Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type. 17 | 18 | Recorded transfers are inserted at the write pointer, which is then incremented, while older recorded transfers may be overwritten once the buffer is full. Or the user can enable RAS (Return Address Stack) emulation mode, where only function calls are recorded, and function returns pop the last call record. The source PC, target PC, and some optional metadata (transfer type, elapsed cycles) are stored for each recorded transfer. 19 | 20 | The CTR buffer is accessible through an indirect CSR interface, such that software can specify which logical entry in the buffer it wishes to read or write. Logical entry 0 always corresponds to the youngest recorded transfer, followed by entry 1 as the next youngest, and so on. 21 | 22 | The machine-level extension, *Smctr*, encompasses all newly added 23 | Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all 24 | privilege levels. The corresponding supervisor-level extension, *Ssctr*, is essentially 25 | identical to Smctr, except that it excludes machine-level CSRs and behaviors not 26 | intended to be directly accessible at the supervisor level. 27 | 28 | Smctr and Ssctr depend on both the implementation of S-mode and the Sscsrind extension. -------------------------------------------------------------------------------- /readme.adoc: -------------------------------------------------------------------------------- 1 | = RISC-V Control Transfer Records (CTR) 2 | 3 | The CTR TG was established to develop an ISA extension to record recent control transfers. See the group charter https://github.com/riscv-admin/control-transfer-records/blob/main/CHARTER.md[[.underline]#here#]. 4 | 5 | = License 6 | 7 | This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). 8 | See the link:LICENSE[LICENSE] file for details. 9 | 10 | = Contributors 11 | 12 | Contributors to this specification are contained in the link:contributors.adoc[contributors] file. 13 | 14 | For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. 15 | 16 | = Dependencies 17 | 18 | This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on 19 | checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. 20 | 21 | For more information on AsciiDoctor, specification guidelines, or building locally, see the 22 | https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. 23 | 24 | = Cloning the project 25 | 26 | This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] 27 | to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] 28 | to achieve a common look and feel. 29 | 30 | When cloning this repository for the first time, you must either use 31 | `git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result 32 | in the PDF build fail with an error message like the following: 33 | 34 | $ make 35 | asciidoctor-pdf \ 36 | -a toc \ 37 | -a compress \ 38 | -a pdf-style=docs-resources/themes/riscv-pdf.yml \ 39 | -a pdf-fontsdir=docs-resources/fonts \ 40 | --failure-level=ERROR \ 41 | -o profiles.pdf profiles.adoc 42 | asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme 43 | No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts 44 | Use --trace for backtrace 45 | make: *** [Makefile:7: profiles.pdf] Error 1 46 | 47 | = Building the document 48 | 49 | The final specification form of PDF can be generated using the `make` command. 50 | --------------------------------------------------------------------------------