diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index b7be4ddc..0cfb97ff 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -55,14 +55,14 @@ jobs: uses: actions/upload-artifact@v3 with: name: Build Artifacts - path: ${{ github.workspace }}/*.pdf + path: ${{ github.workspace }}/build/*.pdf retention-days: 30 # Create Release - name: Create Release uses: softprops/action-gh-release@v1 with: - files: ${{ github.workspace }}/*.pdf + files: ${{ github.workspace }}/build/*.pdf tag_name: v${{ github.event.inputs.version }} name: Release ${{ github.event.inputs.version }} draft: ${{ github.event.inputs.draft }} diff --git a/.gitignore b/.gitignore index bd98a737..345f1a59 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ -*.pdf - +build +src/generated diff --git a/Makefile b/Makefile index a46d659c..99b31e9a 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# Makefile for RISC-V Doc Template +# Makefile for RISC-V specification for CHERI extensions # # This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 # International License. To view a copy of this license, visit @@ -8,38 +8,111 @@ # SPDX-License-Identifier: CC-BY-SA-4.0 # # Description: -# -# This Makefile is designed to automate the process of building and packaging -# the Doc Template for RISC-V Extensions. +# +# This Makefile is designed to automate the process of building and packaging +# the specification document. + +# Tools +DOCKER_IMAGE = riscvintl/riscv-docs-base-container-image:latest +GEN_SCRIPT = $(SCRIPTS_DIR)/generate_tables.py -DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= v0.0.0 +# Version and date +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.7.0 REVMARK ?= Draft -DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ -riscvintl/riscv-docs-base-container-image:latest - -HEADER_SOURCE := header.adoc -PDF_RESULT := spec-sample.pdf - -ASCIIDOCTOR_PDF := asciidoctor-pdf -OPTIONS := --trace \ - -a compress \ - -a mathematical-format=svg \ - -a revnumber=${VERSION} \ - -a revremark=${REVMARK} \ - -a revdate=${DATE} \ - -a pdf-fontsdir=docs-resources/fonts \ - -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR -REQUIRES := --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical - -.PHONY: all build clean build-container build-no-container - -all: build - -build: + +# URLs for downloaded CSV files +URL_BASE = https://docs.google.com/spreadsheets/d/1nyxKamsYZaeTyG8qP-JX4_oQwcuQ_4nZ_Ihm3RK0NEY/gviz/tq?tqx=out:csv +URL_ISA = $(URL_BASE)&gid=0 +URL_CSR = $(URL_BASE)&gid=1927549494 + +# Directories and files +BUILD_DIR = build +SRC_DIR = src +SRCS = $(wildcard $(SRC_DIR)/*.adoc) \ + $(wildcard $(SRC_DIR)/*/*.adoc) \ + $(wildcard $(SRC_DIR)/*/*.bib) \ + $(wildcard $(SRC_DIR)/*/*/*.adoc) \ + $(VERSION_FILE) +IMG_DIR = $(SRC_DIR)/img +IMGS = $(wildcard $(IMG_DIR)/*.png) \ + $(wildcard $(IMG_DIR)/*.svg) \ + $(wildcard $(IMG_DIR)/*.edn) +CSV_DIR = $(SRC_DIR)/csv +CSVS = $(wildcard $(CSV_DIR)/*.csv) +GEN_DIR = $(SRC_DIR)/generated +SCRIPTS_DIR = $(SRC_DIR)/scripts + +# Output file +PDF_RESULT := $(BUILD_DIR)/riscv-cheri.pdf + +# Top asciidoc file of the document +HEADER_SOURCE := $(SRC_DIR)/riscv-cheri.adoc + +# Generated files +GEN_SRC = $(GEN_DIR)/both_mode_insns_table_body.adoc \ + $(GEN_DIR)/cap_mode_insns_table_body.adoc \ + $(GEN_DIR)/csr_added_legacy_table_body.adoc \ + $(GEN_DIR)/csr_added_purecap_mode_d_table_body.adoc \ + $(GEN_DIR)/csr_added_purecap_mode_m_table_body.adoc \ + $(GEN_DIR)/csr_added_purecap_mode_s_table_body.adoc \ + $(GEN_DIR)/csr_added_purecap_mode_u_table_body.adoc \ + $(GEN_DIR)/csr_alias_action_table_body.adoc \ + $(GEN_DIR)/csr_aliases_table_body.adoc \ + $(GEN_DIR)/csr_exevectors_table_body.adoc \ + $(GEN_DIR)/csr_metadata_table_body.adoc \ + $(GEN_DIR)/csr_permission_table_body.adoc \ + $(GEN_DIR)/csr_removed_purecap_mode_d_table_body.adoc \ + $(GEN_DIR)/csr_removed_purecap_mode_m_table_body.adoc \ + $(GEN_DIR)/csr_removed_purecap_mode_s_table_body.adoc \ + $(GEN_DIR)/csr_removed_purecap_mode_u_table_body.adoc \ + $(GEN_DIR)/csr_replaced_purecap_mode_d_table_body.adoc \ + $(GEN_DIR)/csr_replaced_purecap_mode_m_table_body.adoc \ + $(GEN_DIR)/csr_replaced_purecap_mode_s_table_body.adoc \ + $(GEN_DIR)/csr_replaced_purecap_mode_u_table_body.adoc \ + $(GEN_DIR)/illegal_insns_table_body.adoc \ + $(GEN_DIR)/legacy_mnemonic_insns_table_body.adoc \ + $(GEN_DIR)/legacy_mode_insns_table_body.adoc \ + $(GEN_DIR)/xlen_dependent_encoding_insns_table_body.adoc \ + $(GEN_DIR)/Zbh_lr_sc_insns_table_body.adoc \ + $(GEN_DIR)/Zcheri_legacy_insns_table_body.adoc \ + $(GEN_DIR)/Zcheri_mode_insns_table_body.adoc \ + $(GEN_DIR)/Zcheri_purecap_insns_table_body.adoc + +# Docker command +DOCKER = docker run --rm -v $(PWD):/build -w /build $(DOCKER_IMAGE) + +# AsciiDoctor command +ASCIIDOC_PDF = asciidoctor-pdf +ASCIIDOC_OPTIONS = --trace \ + -a compress \ + -a mathematical-format=svg \ + -a revnumber=$(VERSION) \ + -a revremark=$(REVMARK) \ + -a revdate=$(DATE) \ + -a buildir=$(BUILD_DIR) \ + -a srcdir=$(SRC_DIR) \ + -a imagesdir=img \ + -a imagesoutdir=$(BUILD_DIR)/img \ + -a cheri_v9_annotations='' \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ + --failure-level=ERROR +ASCIIDOC_REQUIRES = --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical + +# Convenience targets +all: $(PDF_RESULT) +generate: $(GEN_SRC) +download: $(CSVS) + +$(BUILD_DIR): + @echo " DIR $@" + @mkdir -p $@ + +%.pdf: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR) + @echo " DOC $@" @echo "Checking if Docker is available..." @if command -v docker >/dev/null 2>&1 ; then \ echo "Docker is available, building inside Docker container..."; \ @@ -51,15 +124,29 @@ build: build-container: @echo "Starting build inside Docker container..." - $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" + $(DOCKER) /bin/sh -c "$(ASCIIDOC_PDF) $(ASCIIDOC_OPTIONS) $(ASCIIDOC_REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" @echo "Build completed successfully inside Docker container." build-no-container: @echo "Starting build..." - $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) + $(ASCIIDOC_PDF) $(ASCIIDOR_OPTIONS) $(ASCIIDOC_REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) @echo "Build completed successfully." +# Rule to generate all the src/generated/*.adoc from the downloaded CSVs using a Python script. +$(GEN_SRC) &: $(CSVS) $(GEN_SCRIPT) + @echo " GEN" + @$(GEN_SCRIPT) -o $(GEN_DIR) --csr $(CSV_DIR)/CHERI_CSR.csv --isa $(CSV_DIR)/CHERI_ISA.csv + +# Rule to download CSVs. These files are checked in and only re-downloaded when you `make download`. +$(CSVS) &: + @echo " DOWN CSV (isa)" + @curl -Lo src/csv/CHERI_ISA.csv "$(URL_ISA)" + @echo " DOWN CSV (csr)" + @curl -Lo src/csv/CHERI_CSR.csv "$(URL_CSR)" + +# Clean clean: - @echo "Cleaning up generated files..." - rm -f $(PDF_RESULT) - @echo "Cleanup completed." + @echo " CLEAN" + @$(RM) -r $(PDF_RESULT) $(GEN_SRC) + +.PHONY: all generate download clean diff --git a/chapter2.adoc b/chapter2.adoc deleted file mode 100644 index 8c118202..00000000 --- a/chapter2.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[[chapter2]] -== The Second Chapter - -. The first item. - -. The second item. -+ -.. The first sub item. - -.. The second sub item. -+ -[CAUTION] -==== -A moment of caution is required for this block of text must be read and apreciated for its importance. -==== - -. Yet another item. - -. Again, an item. - -.. A multi-line item. -+ -This item has multiple lines. -+ -By multiple lines, this is what we mean. -+ -Seriously, multiple. - -=== An example table - -[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] -|=== -4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area -|L|R|W|X|Quarter 1|Quarter 2 -|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors -|0|0|0|1|Thing 1|Thing 2 -|1|0|0|0|Thing 3|Thing 4 -|1|1|1|1 2+|Span Thing 1 and 2 -|=== - -=== Sub section - -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. - -=== Yet another subsection - -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. diff --git a/example.bib b/example.bib deleted file mode 100644 index 9da24b15..00000000 --- a/example.bib +++ /dev/null @@ -1,36 +0,0 @@ -@inproceedings{riscI-isca1981, - title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, - author = {David A. Patterson and Carlo H. S\'{e}quin}, - booktitle = {ISCA}, - location = {Minneapolis, Minnesota, USA}, - pages = {443-458}, - year = {1981} -} - -@inproceedings{Katevenis:1983, - author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin}, - title = {The {RISC II} micro-architecture}, - booktitle = {Proceedings VLSI 83 Conference}, - year = {1983}, - month = {August} -} - -@inproceedings{Ungar:1984, - author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson}, - title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, - booktitle = {ISCA}, - address = {Ann Arbor, MI}, - year = {1984}, - pages = {188-197} -} - -@article{spur-jsscc1989, - author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson}, - title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing}, - journal = {IEEE JSSC}, - year = {1989}, - volume = {24}, - number = {6}, - pages = {1688-1698}, - month = {December} -} \ No newline at end of file diff --git a/header.adoc b/header.adoc deleted file mode 100644 index 662789d9..00000000 --- a/header.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= RISC-V Example Specification Document (Zexmpl) -Authors: Author 1, Author 2 -:docgroup: RISC-V Task Group -:description: RISC-V Example Specification Document (Zexmpl) -:company: RISC-V.org -:revdate: 1/2023 -:revnumber: 1.0 -:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. -:revinfo: -:url-riscv: http://riscv.org -:doctype: book -:preface-title: Preamble -:colophon: -:appendix-caption: Appendix -:imagesdir: docs-resources/images -:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] -// Settings: -:experimental: -:reproducible: -//:WaveDromEditorApp: app/wavedrom-editor.app -:imagesoutdir: docs-resources/images -:bibtex-file: example.bib -:bibtex-order: alphabetical -:bibtex-style: apa -:icons: font -:lang: en -:listing-caption: Listing -:sectnums: -:toc: left -:toclevels: 4 -:source-highlighter: pygments -ifdef::backend-pdf[] -:source-highlighter: coderay -endif::[] -:data-uri: -:hide-uri-scheme: -:stem: latexmath -:footnote: -:xrefstyle: short - -[WARNING] -.This document is in the link:http://riscv.org/spec-state[Development state] -==== -Expect potential changes. This draft specification is likely to evolve before -it is accepted as a standard. Implementations based on this draft -may not conform to the future standard. -==== - -[preface] -== Copyright and license information -This specification is licensed under the Creative Commons -Attribution 4.0 International License (CC-BY 4.0). The full -license text is available at -https://creativecommons.org/licenses/by/4.0/. - -Copyright 2023 by RISC-V International. - -[preface] -include::contributors.adoc[] - -include::intro.adoc[] -include::chapter2.adoc[] - -// The index must precede the bibliography -include::index.adoc[] -include::bibliography.adoc[] diff --git a/intro.adoc b/intro.adoc deleted file mode 100644 index 0d623276..00000000 --- a/intro.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[[intro]] -== Introduction - -Lorem ipsum indexterm:[Lorem ipsum] dolor sit amet, consectetur adipiscing elit, sed do *eiusmod tempor* incididunt ut labore et dolore magna aliqua. Felis imperdiet proin fermentum leo vel orci porta. Volutpat lacus laoreet non curabitur indexterm:[curabitur] gravida indexterm:[gravida]. Posuere urna nec tincidunt praesent semper feugiat nibh. Elit ``ullamcorper`` dignissim cras tincidunt lobortis. Malesuada fames ac turpis egestas integer eget. Tristique sollicitudin nibh sit amet commodo. Sed felis eget velit aliquet. Sit amet aliquam id diam maecenas ultricies mi. Consectetur purus ut faucibus pulvinar. Lectus urna duis convallis convallis tellus id. Fermentum iaculis eu non diam. Feugiat in fermentum posuere urna nec tincidunt praesent semper feugiat. Urna nec tincidunt praesent semper feugiat nibh. - -Commodo viverra maecenas accumsan lacus. Vulputate odio ut enim blandit indexterm:[blandit] volutpat maecenas volutpat blandit. Urna porttitor rhoncus dolor purus non. Tellus mauris a diam maecenas sed. Vitae auctor eu augue ut lectus. Ridiculus mus mauris vitae ultricies leo integer. Consequat semper viverra nam *libero* justo laoreet sit amet. Pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus et. Ac placerat vestibulum lectus mauris ``ultrices`` eros in cursus turpis. Accumsan in nisl nisi scelerisque eu ultrices vitae. Cras ornare arcu dui vivamus. Vitae congue mauris rhoncus aenean. Consequat mauris nunc congue nisi vitae suscipit tellus. Tempus egestas sed sed risus pretium quam vulputate dignissim. Quis varius quam quisque id diam vel. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Amet mauris commodo quis imperdiet massa tincidunt nunc. - -[NOTE] -==== -The name RISC-V indexterm:[RISC-V] was chosen to represent the fifth major RISC ISA design from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first four). We also pun on the use of the Roman numeral "V" to signify "variations" and "vectors", as support for a range of architecture research, including various data-parallel accelerators, is an explicit goal of the ISA design. -==== - -=== Sub Section of Introduction - -Pellentesque habitant morbi *tristique* senectus et netus et. Aliquam purus sit amet luctus. Odio eu ``feugiat`` pretium nibh ipsum consequat nisl vel. Euismod lacinia at quis risus sed vulputate odio ut. Eu sem integer vitae justo eget. Cursus euismod quis viverra nibh. Tempus egestas sed sed risus. Quis imperdiet massa tincidunt nunc pulvinar. Id venenatis a condimentum vitae sapien pellentesque habitant. diff --git a/readme.adoc b/readme.adoc index d72b1a94..2dc1c3a6 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,6 +1,6 @@ -= RISC-V Cheri Specification += RISC-V Specification for CHERI Extensions -This repository contains the CHERI extension specification, adding hardware capabilities to RISC-V ISA to enable fine-grained memory protection and scalable compartmentalization. +This repository contains the CHERI extension specification, adding hardware capabilities to the RISC-V ISA to enable fine-grained memory protection and scalable compartmentalization. == License @@ -21,6 +21,7 @@ To build the document, you'll need the following tools installed on your system: * Make * asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical * Docker +* Python3 === Cloning the Repository @@ -28,7 +29,7 @@ To build the document, you'll need the following tools installed on your system: === Building the Documentation -To start the build process, run `cd ./docs-spec-template && make build`. +To start the build process, run `cd ./riscv-cheri && make all`. The Makefile script will check the availability of Docker on your system: diff --git a/bibliography.adoc b/src/bibliography.adoc similarity index 100% rename from bibliography.adoc rename to src/bibliography.adoc diff --git a/src/cap-description.adoc b/src/cap-description.adoc new file mode 100644 index 00000000..94f22d10 --- /dev/null +++ b/src/cap-description.adoc @@ -0,0 +1,523 @@ +[#section_cap_description] +== Anatomy of Capabilities in Zcheri_purecap + +RISC-V defines variants of the base integer instruction set characterized by +the width of the integer registers and the corresponding size of the address +space. There are two primary ISA variants, RV32I and RV64I, which provide +32-bit and 64-bit address spaces respectively. The term XLEN refers to the +width of an integer register in bits (either 32 or 64). The value of XLEN may +change dynamically at run-time depending on the values written to CSRs, so we +define XLENMAX to be widest XLEN that the implementation supports. + + +{cheri_base_ext_name} defines capabilities of size CLEN corresponding to 2 * +XLENMAX without including the tag bit. The value of CLEN is always calculated +based on XLENMAX regardless of the effective XLEN value. + +=== Components of a Capability + +Capabilities contain the software accessible fields described in this section. + +[#section_tag] +==== Tag + +An additional hardware managed bit added to addressable memory and registers. +It is stored separately and may be referred to as "out of band". It indicates +whether a register or CLEN-aligned memory location contains a valid capability. +If the tag is set, the capability is valid and can be dereferenced (contingent +on checks such as permissions or bounds). + +The capability is invalid if the tag is clear. Using an invalid capability to +dereference memory or authorize any operation gives rise to exceptions. All +capabilities derived from invalid capabilities are themselves invalid i.e. +their tags are 0. + + +All locations in registers or memory able to hold a capability are CLEN+1 bits +wide including the tag bit. Those locations are referred as being _CLEN-bit_ or +_capability_ wide in this specification. + +[#section_cap_perms] +==== Architectural Permissions (AP) + +ifdef::cheri_v9_annotations[] +WARNING: *CHERI v9 Note:* The permissions are encoded differently in this +specification. +endif::[] + +This field encodes architecturally defined permissions of the capability. +Permissions grant access subject to the tag being set, the capability being +unsealed (see xref:section_cap_sealed[xrefstyle=short]), and bounds checks (see +xref:section_cap_bounds[xrefstyle=short]). An operation is also contingent on +requirements imposed by other RISC-V architectural features, such as virtual +memory, PMP and PMAs, even if the capability grants sufficient permissions. The +permissions currently defined in {cheri_base_ext_name} are listed in +below. + +[#r_perm,reftext="R-permission"] +Read Permission \(R):: Allow reading integer data from memory. Tags are always +read as zero when reading integer data. + +[#w_perm,reftext="W-permission"] +Write Permission (W):: Allow writing integer data to memory. Tags are always +written as zero when writing integer data. Every CLEN aligned word in memory +has a tag, if any byte is overwritten with integer data then the tag for all +CLEN-bits is cleared. + +[#c_perm,reftext="C-permission"] +Capability Permission \(C):: Allow reading capability data from memory if the +authorising capability also grants <>. Allow writing capability data to +memory if the authorising capability also grants <>. + +[#x_perm,reftext="X-permission"] +Execute Permission (X):: Allow instruction execution. + +[#asr_perm,reftext="ASR-permission"] +Access System Registers Permission (ASR):: Allow access to privileged CSRs. + +===== Permission Encoding + +The bit width of the permissions field depends on the value of XLENMAX as shown +in xref:perms_bit_width[xrefstyle=short]. A {cap_rv32_perms_width}-bit vector +encodes the permissions when XLENMAX=32. For this case, the legal encodings of +permissions are listed in xref:cap_perms_encoding32[xrefstyle=short]. Certain +combinations of permissions are impractical. For example, <> is +superfluous when the capability does not grant either <> or <>. +Therefore, it is only possible to encode a subset of all combinations. + +.Permissions widths depending on XLENMAX +[#perms_bit_width,options=header,align="center",width="55%"] +|============================================================================== +^| XLENMAX ^| Permissions width +^| 32 ^| {cap_rv32_perms_width} +^| 64 ^| {cap_rv64_perms_width} +|============================================================================== + +.Encoding of architectural permissions for XLENMAX=32 +[#cap_perms_encoding32,width="60%",options=header,cols="^2,^1,^1,^1,^1,^1",align="center"] +|============================================================================== +| Encoding | R | W | C | X | ASR +| 0b0000 | | | | | +| 0b0001 5+| *reserved* +| 0b0010 | | ✔ | | | +| 0b0011 | | ✔ | ✔ | | +| 0b0100 | ✔ | | | | +| 0b0101 | ✔ | | ✔ | | +| 0b0110 | ✔ | ✔ | | | +| 0b0111 | ✔ | ✔ | ✔ | | +| 0b1000 | ✔ | | | ✔ | +| 0b1001 | ✔ | | ✔ | ✔ | +| 0b1010 | ✔ | ✔ | | ✔ | +| 0b1011 | ✔ | ✔ | ✔ | ✔ | +| 0b1100 | ✔ | | | ✔ | ✔ +| 0b1101 | ✔ | | ✔ | ✔ | ✔ +| 0b1110 | ✔ | ✔ | | ✔ | ✔ +| 0b1111 | ✔ | ✔ | ✔ | ✔ | ✔ +|============================================================================== + +The encoding in xref:cap_perms_encoding32[xrefstyle=short] is chosen to +facilitate hardware implementations. Therefore, it can be worked out if the +permissions are granted as follows: + +* <>: bit 0 is set +* <>: bit 1 is set +* <>: bit 3 is set +* <>: bits 3 or 2 are set +* <>: bits 3 and 2 are set + +A {cap_rv64_perms_width}-bit vector encodes the permissions when XLENMAX=64. In +this case, there is a bit per permission as shown in +xref:cap_perms_encoding64[xrefstyle=short]. A permission is granted if its +corresponding bit is set, otherwise the capability does not grant that +permission. + +.Encoding of architectural permissions for XLENMAX=64 +[#cap_perms_encoding64,align="center",options=header,cols="^10%,90%",width="55%"] +|============================================================================== +| Bit | Name +| 0 | <> +| 1 | <> +| 2 | <> +| 3 | <> +| 4 | <> +|============================================================================== + +WARNING: #TODO: Confirm that we need a separate permissions format for 32-bit +and 64-bit.# + +NOTE: Valid capabilities must not have the permissions field set to a reserved +value according to xref:cap_perms_encoding32[xrefstyle=short] when XLENMAX=32. + +[#section_cap_sdp] +==== Software-Defined Permissions (SDP) + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* CHERI v9 had no software-defined permissions for RV32 +endif::[] + +A bit vector used by the kernel or application programs for software-defined +permissions (SDP). + +NOTE: Software is completely free to define the usage of these bits. For +example, a program may decide to use an SDP bit to indicate the "ownership" of +objects. Therefore, a capability grants permission to free the memory it +references if that SDP bit is set because it "owns" that object. + +.SDP widths depending on XLENMAX +[#sdp_bit_width,options=header,align="center",width="55%"] +|============================================================================== +^| XLENMAX ^| SDP width +^| 32 ^| {cap_rv32_sdp_width} +^| 64 ^| {cap_rv64_sdp_width} +|============================================================================== + +[#section_cap_sealed] +==== Sealed (S) Bit + +ifdef::cheri_v9_annotations[] +WARNING: *CHERI v9:* The sealing bit is new (1-bit otype) and the old CHERI v9 otype no longer exists. +endif::[] + +Indicates that a capability is sealed if the bit is 1 or unsealed if it is 0. +Sealed capabilities cannot be dereferenced to access memory and are immutable +such that modifying any of its fields clears the tag of the output capability. + +In {cheri_base_ext_name}, the sealing bit is used to implement immutable +capabilities that describe function entry points. A program may jump to a +sealed capability to begin executing the instructions it references. The jump +instruction automatically unseals the capability and installs it to the +program counter capability (see +xref:section_riscv_programmers_model[xrefstyle=short]). The <> instruction +also seals the return address capability (if any) since it is the entry point +to the caller function. + +[#section_cap_bounds] +==== Bounds + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The bounds mantissa width is different in XLENMAX=32. +Also, the old IE bit is renamed to Exponent Format (EF); the function of IE +is the inverse of EF i.e. IE=0 has the same effect as EF=1. + +NOTE: *CHERI v9 Note:* The mantissa width for RV32 was increased to 10. + +NOTE: *CHERI v9 Note:* The sense of the exponent is reversed, so an encoded +value of 0 represents CAP_MAX_E, and CAP_MAX_E represents 0 from the previous +specification. +endif::[] + +The bounds encode the base and top addresses that constrain memory accesses. +The capability can be used to access any memory location A in the range base +≤ A < top. The bounds are encoded in compressed format, so it is not +possible to encode any arbitrary combination of base and top addresses. An +invalid capability with tag cleared is produced when attempting to construct a +capability that is not _representable_ because its bounds cannot be correctly +encoded. The bounds are decoded as described in +xref:section_cap_encoding[xrefstyle=short]. + +The bounds field has the following components: + +* *T:* Value substituted into the capability's address to decode the top +address +* *B:* Value substituted into the capability's address to decode the base +address +* *E:* Exponent that determines the position at which B and T are substituted +into the capability's address +* *EF:* Exponent format flag indicating the encoding for T, B and E + ** The exponent is stored in T and B if EF=0, so it is 'internal' + ** The exponent is zero if EF=1, so it is 'embedded' + +The bit width of T and B are defined in terms of the mantissa width (MW) which +is set depending on the value of XLENMAX as shown in +xref:mantissa_bit_width[xrefstyle=short]. + +.Mantissa width (MW) values depending on XLENMAX +[#mantissa_bit_width,options=header,align="center",width="55%"] +|============================================================================== +^| XLENMAX ^| MW +^| 32 ^| {cap_rv32_mw_width} +^| 64 ^| {cap_rv64_mw_width} +|============================================================================== + +The exponent E indicates the position of T and B within the capability's +address as described in xref:section_cap_encoding[xrefstyle=short]. The bit +width of the exponent (EW) is set depending on the value of XLENMAX. The +maximum value of the exponent is calculated as follows: + +``` +CAP_MAX_E = XLENMAX - MW + 2 +``` + +The possible values for EW and CAP_MAX_E are shown in +xref:exp_bit_width[xrefstyle=short]. + +.Exponent widths and CAP_MAX_E depending on XLENMAX +[#exp_bit_width,options=header,align="center",width="55%"] +|============================================================================== +^| XLENMAX ^| EW ^| CAP_MAX_E +^| 32 ^| {cap_rv32_exp_width} ^| 24 +^| 64 ^| {cap_rv64_exp_width} ^| 52 +|============================================================================== + +NOTE: The address and bounds must be representable in valid capabilities i.e. +when the tag is set (see xref:section_cap_malformed[xrefstyle=short]). + +==== Address + +XLENMAX integer value that encodes the byte-address of a memory location. + +.Address widths depending on XLENMAX +[#address_bit_width,options=header,align="center",width="55%"] +|============================================================================== +^| XLENMAX ^| Address width +^| 32 ^| {cap_rv32_addr_width} +^| 64 ^| {cap_rv64_addr_width} +|============================================================================== + +==== Reserved Bits + +Reserved bits available for future extensions to {cheri_base_ext_name}. + +NOTE: Reserved bits must be 0 in valid capabilities. + +[#section_cap_encoding] +=== Capability Encoding + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The encoding changes eliminate the concept of the +in-memory format, and also increase precision for RV32. When EF=0, T and B +are now shifted right rather than left within the address. Also, the bounds +decoding for XLENMAX=32 uses a trick (see bit T8) to save one bit when encoding +the exponent. +endif::[] + +The components of a capability are encoded as shown in +xref:cap_encoding_xlen32[xrefstyle=short] and +xref:cap_encoding_xlen64[xrefstyle=short] when XLENMAX=32 and XLENMAX=64 +respectively. + +.Capability encoding when XLENMAX=32 +[#cap_encoding_xlen32] +include::img/cap-encoding-xlen32.edn[] + +.Capability encoding when XLENMAX=64 +[#cap_encoding_xlen64] +include::img/cap-encoding-xlen64.edn[] + +Each memory location or register able to hold a capability must also store the +tag as out of band information that software cannot directly set or clear. The +capability metadata is held in the most significant bits and the address +is held in the least significant bits. + +The metadata is encoded in a compressed format cite:[woodruff2019cheri]. It +uses a floating point representation to encode the bounds relative to the +capability address. The base and top addresses from the bounds are decoded as +shown below. + +WARNING: #TODO: The pseudo-code below does not have a formal notation. It is +simply a place-holder while the Sail implementation is available. In this +notation, / means "integer division", [] are the bit-select operators, and +arithmetic is signed.# + +``` +EW = (XLENMAX == 32) ? 5 : 6 +CAP_MAX_E = XLENMAX - MW + 2 + +If EF = 1: + E = 0 + T[EW / 2 - 1:0] = TE + B[EW / 2 - 1:0] = BE + LCout = (T[MW - 3:0] < B[MW - 3:0]) ? 1 : 0 + LMSB = (XLENMAX == 32) ? T8 : 0 +else: + E = CAP_MAX_E - ( (XLENMAX == 32) ? { T8, TE, BE } : { TE, BE } ) + T[EW / 2 - 1:0] = 0 + B[EW / 2 - 1:0] = 0 + LCout = (T[MW - 3:EW / 2] < B[MW - 3:EW / 2]) ? 1 : 0 + LMSB = 1 +``` + +Reconstituting the top two bits of T: + +``` +T[MW - 1:MW - 2] = B[MW - 1:MW - 2] + LCout + LMSB +``` + +Decoding the bounds: + +``` +top: t = { a[XLENMAX - 1:E + MW] + ct, T[MW - 1:0] , {E{1'b0}} } +base: b = { a[XLENMAX - 1:E + MW] + cb, B[MW - 1:0] , {E{1'b0}} } +``` + +The corrections c~t~ and c~b~ are calculated as as shown below using the +definitions in xref:cap_encoding_ct[xrefstyle=short] and +xref:cap_encoding_cb[xrefstyle=short]. + +``` +Ac = a[E + MW - 1:E + MW - 3] +Bc = B[MW - 1:MW - 3] +Tc = T[MW - 1:MW - 3] +R = Bc - 1 +``` + +.Calculation of top address correction +[#cap_encoding_ct,options=header,cols="^1,^1,^1",width="40%",align="center"] +|============================================================================== +| A~c~ < R | T~c~ < R | c~t~ +| false | false | 0 +| false | true | +1 +| true | false | -1 +| true | true | 0 +|============================================================================== + +.Calculation of base address correction +[#cap_encoding_cb,options=header,cols="^1,^1,^1",width="40%",align="center"] +|============================================================================== +| A~c~ < R | B~c~ < R | c~b~ +| false | false | 0 +| false | true | +1 +| true | false | -1 +| true | true | 0 +|============================================================================== + +The base, _b_, and top, _t_, addresses are derived from the address by +substituting _a_[E + MW - 1:E] with B and T respectively and clearing the +lower E bits. The most significant bits of _a_ may be adjusted up or down by 1 +using corrections _c~b~_ and _c~t~_ to allow encoding memory regions that span +alignment boundaries. + +The EF bit selects between two cases: + +1. EF = 1: The exponent is 0 for regions less than 2^MW-2^ bytes long +2. EF = 0: The exponent is _internal_ with E stored in the lower bits of T and +B along with T~8~ when XLENMAX=32. E is chosen so that the most significant +non-zero bit of the length of the region aligns with T[MW - 2] in the decoded +top. Therefore, the most significant two bits of T can be derived from B using +the equality `T = B + L`, where L[MW - 2] is known from the values of EF and E +and a carry out is implied if `T[MW - 3:0] < B[MW - 3:0]` since it is +guaranteed that the top is larger than the base. + +The compressed bounds encoding allows the address to roam over a large +_representable_ region while maintaining the original bounds. This relies on +using the 'spare' encodings where `T < B` to define a space boundary R, +relative to the base, calculated by subtracting 1 from the top three bits of B. +If B, T or _a_[E + MW - 1:E] is less than R, it is inferred that they lie in the +2^E+MW^ aligned region above R labelled space~U~ in +xref:cap_bounds_map[xrefstyle=short] and the corrections _c~t~_ and _c~b~_ are +computed accordingly. The overall effect is that at least 2^E+MW^/8 bytes below +the base address and 2^E+MW^/4 bytes above the top address can roam +out-of-bounds while still allowing the bounds to be correctly decoded. + +[#cap_bounds_map] +.Memory address bounds encoded within a capability +image::cap-bounds-map.png[width=80%,align=center] + +A capability whose bounds cover the entire address space has 0 base and top +equals 2^XLENMAX^, i.e. _t_ is a XLENMAX + 1 bit value. However, _b_ is a +XLENMAX bit value and the size mismatch introduces additional complications +when decoding, so the following condition is required to correct _t_ for +capabilities whose representable region wraps the edge of the address +space: + +``` +if ( (E < (CAP_MAX_E - 1)) & (t[XLENMAX: XLENMAX - 1] - b[XLENMAX - 1] > 1) ) + t[XLENMAX] = !t[XLENMAX] +``` +That is, invert the most significant bit of _t_ if the decoded length of the +capability is larger than E. + +[#section_null_inf_cap] +=== NULL and Infinite Capabilities + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* Encoding <> as zeros removes the need for +the difference between in-memory and architectural format. +endif::[] + +The <> capability is represented with 0 in all fields. This implies +that <> has no permissions and its exponent E is CAP_MAX_E e.g. 52 +when XLENMAX=64, so its bounds cover the entire address space such that the +expanded base is 0 and top is 2^XLENMAX^. In contrast, the <> +capability grants all permissions while its bounds also cover the whole address +space. + +NOTE: The <> capability is also known as 'default', 'almighty', +or 'root' capability. + +.Field values of the NULL capability +[#null-cap,reftext="NULL",options=header,align=center,width="55%",cols="1,1,3"] +|============================================================================== +| Field | Value | Comment +| SDP | zeros | Grants no permissions +| AP | zeros | Grants no permissions +| S | zero | Unsealed +| EF | zero | Internal exponent format +| T~8~ | zeros | Top address bit (XLENMAX=32 only) +| T | zeros | Top address bits +| T~E~ | zeros | Exponent bits +| B | zeros | Base address bits +| B~E~ | zeros | Exponent bits +| Address | zeros | Capability address +|============================================================================== + +.Field values of the Infinite capability +[#infinite-cap,reftext="Infinity"] +[options=header,width="100%",align=center,width="55%",cols="1,1,3"] +|============================================================================== +| Field | Value | Comment +| SDP | ones | Grants all permissions +| AP | ones | Grants all permissions +| S | zero | Unsealed +| EF | zero | Internal exponent format +| T~8~ | zeros | Top address bit (XLENMAX=32 only) +| T | zeros | Top address bits +| T~E~ | zeros | Exponent bits +| B | zeros | Base address bits +| B~E~ | zeros | Exponent bits +| Address | zeros | Capability address +|============================================================================== + +[#section_cap_representable_check] +=== Representable Limit Check + +Pointer arithmetic on capabilities must be checked to ensure that the new +address is within the capability's representable region described in +xref:section_cap_encoding[xrefstyle=short]. The new address, after pointer +arithmetic, is within the representable region if decompressing the +capability's bounds with the original and new addresses yields the same base +and top addresses. In other words, given a capability with address _a_ and the +new address `a' = a + x`, the bounds _b_ and _t_ are decoded using _a_ and the +new bounds _b'_ and _t'_ are decoded using _a'_. The new address is within the +capability's representable region if `b == b' && t == t'`. + +Changing a capability's address to a value outside the representable region +unconditionally clears the capability's tag. + +NOTE: The encoding of the bounds depends upon the leading 1 of the address +which is used to determine the exponent. If the leading 1 of the address moves +then the bounds will need to be recalculated. Instructions like <> +and <> update the address field but do not recalculate the bounds. +Therefore, if the leading 1 moves relative to when the bounds were calculated +then the tag is cleared on the result as the encoding has been invalidated. + +[#section_cap_malformed] +=== Malformed Capability Bounds + +A capability is _malformed_ if its encoding does not describe a valid +capability because its bounds cannot be correctly decoded. The following check +indicates whether a capability is malformed. + +``` +malformedMSB = (E == CAP_MAX_E && B[MW - 1:MW - 2] != 0) + || (E == CAP_MAX_E - 1 && B[MW - 1] != 0) +malformedLSB = (E < 0) +malformed = !EF && (malformedMSB || malformedLSB) +``` + +NOTE: The check is for malformed _bounds_, so it does not include reserved +bits! + +Capabilities with malformed bounds are always invalid anywhere in the system +i.e. their tags are always 0. + diff --git a/src/cheri-pte-ext.adoc b/src/cheri-pte-ext.adoc new file mode 100644 index 00000000..62a478dc --- /dev/null +++ b/src/cheri-pte-ext.adoc @@ -0,0 +1,100 @@ +[#section_sv_cheri] +== "Zcheri_pte" Extension for CHERI Page-Based Virtual-Memory Systems + +CHERI is a security mechanism that is generally orthogonal to page-based +virtual-memory management as defined in cite:[riscv-priv-spec]. +However, it is helpful in CHERI harts to extend RISC-V's virtual-memory +management to control the flow of capabilities in memory at the page +granularity. For this reason, the {cheri_pte_ext_name} extension adds new bits +to RISC-V's Page Table Entry (PTE) format. + +=== Extending the Page Table Entry Format + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The current proposal is provisional and is missing +PTE bits when compared to CHERI v9. +endif::[] + +The page table entry format remains unchanged for Sv32. However, two new bits, +Capability Write (CW) and Capability Dirty (CD), are added to leaf PTEs in +Sv39, Sv48 and Sv57 as shown in xref:sv39pte[xrefstyle=short], +xref:sv48pte[xrefstyle=short] and xref:sv57pte[xrefstyle=short] respectively. + +.Sv39 page table entry +[#sv39pte] +include::img/sv39pte.edn[] + +.Sv48 page table entry +[#sv48pte] +include::img/sv48pte.edn[] + +.Sv57 page table entry +[#sv57pte] +include::img/sv57pte.edn[] + +The CW bit indicates whether writing capabilities with tag set to the virtual +page is permitted. Two schemes to manage the CW bit are permitted: + +* A store page fault exception is raised when a capability store or AMO +instruction is executed, the <> grants store capability permission and the +store address corresponds to a virtual page with the CW bit clear. +* When a capability store or AMO instruction is executed, the implementation +clears the tag bit of the capability written to a virtual page with the CW bit +clear. + +NOTE: The implementation of the CW bit does not force a dependency on the tag +bit's value of the capability written, so implementations must support this +feature. + +The CD bit indicates that a capability with tag set has been written to the +virtual page since the last time the CD bit was cleared. Implementations are +strongly encouraged, but not required, to support CD. If supported, two schemes +to manage the CD bit are permitted: + +* A store page fault exception is raised when a capability store or AMO +instruction is executed, the <> grants store capability permission, the +tag bit of the capability being written is set and the address written +corresponds to a virtual page with the CD bit clear. +* When a capability store or AMO instruction is execute, the <> grants store +capability permission, the tag bit of the capability being written is set and +the store address corresponds to a virtual page with the CD bit clear, the +implementation sets the corresponding bit in the PTE. The PTE update must be +atomic with respect to other accesses to the PTE, and must atomically check +that the PTE is valid and grants sufficient permissions. Updates to the CD bit +must be exact (i.e. not speculative), and observed in program order by the +local hart. Furthermore, the PTE update must appear in the global memory order +no later than the explicit memory access, or any subsequent explicit memory +access to that virtual page by the local hart. The ordering on loads and +stores provided by FENCE instructions and the acquire/release bits on atomic +instructions also orders the PTE updates associated with those loads and +stores as observed by remote harts. ++ +The PTE update is not required to be atomic with respect to the explicit memory +access that caused the update, and the sequence is interruptible. However, the +hart must not perform explicit memory access before the PTE update is globally +visible. + +NOTE: The behavior of the CW bit takes priority over the CD bit. Therefore, +implementations must not take action to change or raise an exception related to +the CD bit when the CW bit is clear. + +[#menvcfg_pte,reftext="menvcfg PTE bits"] +=== Extending the Machine Environment Configuration Register (menvcfg) + +The *menvcfg* register is extended to allow discovering whether the +implementation supports the CD bit. + +The *menvcfg* register operates as described in cite:[riscv-priv-spec]. {cheri_base_ext_name} adds a new enable bit as shown in +xref:menvcfgreg[xrefstyle=short] when XLEN=64. + +.Machine environment configuration register (*menvcfg*) +[#menvcfgreg] +include::img/menvcfgreg.edn[] + +The Capability Dirty Enable (CDE) bit controls whether the Capability Dirty +(CD) bit is available for use in S-mode address translation. When CDE=1, the CD +bit is available for S-mode address translation. When CDE=0, the implementation +behaves as though the CD bit were not implemented. If CD is not implemented, +CDE is read-only zero. If CD is implemented although not configurable, CDE is +read-only one. + diff --git a/contributors.adoc b/src/contributors.adoc similarity index 97% rename from contributors.adoc rename to src/contributors.adoc index 33b23737..ba8f2343 100644 --- a/contributors.adoc +++ b/src/contributors.adoc @@ -5,6 +5,7 @@ This RISC-V specification has been contributed to directly or indirectly by: [%hardbreaks] * Hesham Almatary * Andres Amaya Garcia +* John Baldwin * David Chisnall * Jessica Clarke * Brooks Davis diff --git a/src/csv/CHERI_CSR.csv b/src/csv/CHERI_CSR.csv new file mode 100644 index 00000000..764d7d29 --- /dev/null +++ b/src/csv/CHERI_CSR.csv @@ -0,0 +1,33 @@ +"Extended CSR","CLEN Address","Alias","XLEN Address","Mode","Permissions","Reset Value","Action on XLEN write","Action on CLEN write","Executable Vector","Unseal On Execution","Store full metadata","Zcheri_legacy","Zcheri_purecap","Prerequisites","Description","","","","","","","","","","","","","","","","","","","","","" +"dpcc","0x7b9","dpc","0x7b1","D","DRW, <>","<>","Apply <>. +Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, +direct write if address didn't change","✔","✔","","✔","✔","Sdext","Debug Program Counter Capability","","","","","","","","","","","","","","","","","","","","","" +"dscratch0c","0x7ba","dscratch0","0x7b2","D","DRW, <>","<>","Update the CSR using <>.","direct write","","","✔","✔","✔","Sdext","Debug Scratch Capability 0","","","","","","","","","","","","","","","","","","","","","" +"dscratch1c","0x7bb","dscratch1","0x7b3","D","DRW, <>","<>","Update the CSR using <>.","direct write","","","✔","✔","✔","Sdext","Debug Scratch Capability 1","","","","","","","","","","","","","","","","","","","","","" +"mtvecc","0x765","mtvec","0x305","M","MRW, <>","<>","Apply <>. +Always update the CSR with <> even if the address didn't change, including the MODE field in the address for simplicity. +Vector range check ^*^ if vectored mode is programmed.","Apply <>. +Always update the CSR with <> even if the address didn't change, including the MODE field in the address for simplicity. +Vector range check ^*^ if vectored mode is programmed.","✔","","","✔","✔","M-mode","Machine Trap-Vector Base-Address Capability","","","","","","","","","","","","","","","","","","","","","" +"mscratchc","0x760","mscratch","0x340","M","MRW, <>","<>","Update the CSR using <>.","direct write","","","✔","✔","✔","M-mode","Machine Scratch Capability","","","","","","","","","","","","","","","","","","","","","" +"mepcc","0x761","mepc","0x341","M","MRW, <>","<>","Apply <>. +Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, +direct write if address didn't change","✔","✔","","✔","✔","M-mode","Machine Exception Program Counter Capability","","","","","","","","","","","","","","","","","","","","","" +"stvecc","0x505","stvec","0x105","S","SRW, <>","<>","Apply <>. +Always update the CSR with <> even if the address didn't change, including the MODE field in the address for simplicity. +Vector range check ^*^ if vectored mode is programmed.","Apply <>. +Always update the CSR with <> even if the address didn't change, including the MODE field in the address for simplicity. +Vector range check ^*^ if vectored mode is programmed.","✔","","","✔","✔","S-mode","Supervisor Trap-Vector Base-Address Capability","","","","","","","","","","","","","","","","","","","","","" +"sscratchc","0x540","sscratch","0x140","S","SRW, <>","<>","Update the CSR using <>.","direct write","","","✔","✔","✔","S-mode","Supervisor Scratch Capability","","","","","","","","","","","","","","","","","","","","","" +"sepcc","0x541","sepc","0x141","S","SRW, <>","<>","Apply <>. +Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, +direct write if address didn't change","✔","✔","","✔","✔","S-mode","Supervisor Exception Program Counter Capability","","","","","","","","","","","","","","","","","","","","","" +"jvtc","0x417","jvt","0x017","U","URW","<>","Apply <>. +Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, +direct write if address didn't change","✔","","","✔","✔","Zcmt","Jump Vector Table Capability","","","","","","","","","","","","","","","","","","","","","" +"dddc","0x7bc","","","D","DRW, <>","<>","","","","","","✔","","Sdext","Debug Default Data Capabilty (saved/restored on debug mode entry/exit)","","","","","","","","","","","","","","","","","","","","","" +"mtdc","0x74c","","","M","MRW, <>","<>","","","","","","✔","","M-mode","Machine Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","","" +"stdc","0x163","","","S","SRW, <>","<>","","","","","","✔","","S-mode","Supervisor Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","","" +"ddc","0x416","","","U","URW","<>","","","","","","✔","","none","User Default Data Capability","","","","","","","","","","","","","","","","","","","","","" +"pcc","0xcb0","","","U","URO","<> +(address = boot address)","","","✔","","","✔","✔","none","User Program Counter Capability (to allow reading in legacy mode)","","","","","","","","","","","","","","","","","","","","","" \ No newline at end of file diff --git a/src/csv/CHERI_ISA.csv b/src/csv/CHERI_ISA.csv new file mode 100644 index 00000000..b89637a1 --- /dev/null +++ b/src/csv/CHERI_ISA.csv @@ -0,0 +1,176 @@ +"Mnemonic","RV32","RV64","Base ISA (I/E)","Zbhlrsc","Zcheri_mode","Zcheri_legacy","Zcheri_purecap","Valid Modes","A","Zicbo[mpz]","Zba","C or Zca","Zcb","Zcf","Zcd","Zcmp","Zcmt","Zfh","F","D","V","XLEN dependent encoding","funct3","major opcode","Format","Legacy mnemonic RV32","Legacy mnemonic RV64","Function","illegal insn if (1)","OR illegal insn if (2)","OR illegal insn if (3)","illegal insn if (4)","illegal insn if (5)","illegal insn if (6)","illegal insn if (7)","illegal insn if (8)" +"LC","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","✔","3","LOAD (RV32) / MISC_MEM (RV64)","I-type","","","Load cap via int pointer, authorise with DDC ","","","","","","","","" +"SC","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","✔","","STORE","S-type","","","Store cap via int pointer, authorise with DDC ","","","","","","","","" +"CLC","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","✔","3","LOAD (RV32) / MISC_MEM (RV64)","","LC","LC","Load cap via cap ","","","","","","","","" +"CSC","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","✔","","STORE","","SC","SC","Store cap via cap ","","","","","","","","" +"C.CLCSP","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","✔","","C2","","C.FLWSP","C.FLDSP","Load cap via cap, SP relative ","","","","","","","","" +"C.CSCSP","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","✔","","C2","","C.FSWSP","C.FSDSP","Store cap via cap, SP relative ","","","","","","","","" +"C.CLC","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","✔","","C0","","C.FLW","C.FLD","Load cap via cap","","","","","","","","" +"C.CSC","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","✔","","C0","","C.FSW","C.FSD","Store cap via cap ","","","","","","","","" +"C.CLWSP","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.LWSP","C.LWSP","Load word via cap, SP relative","","","","","","","","" +"C.CSWSP","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.SWSP","C.SWSP","Store word via cap, SP relative","","","","","","","","" +"C.CLW","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.LW","C.LW","Load word via cap","","","","","","","","" +"C.CSW","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.SW","C.SW","Store word via cap ","","","","","","","","" +"C.CLD","","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.LD","C.LD","Load word via cap","","","","","","","","" +"C.CSD","","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.SD","C.SD","Store word via cap ","","","","","","","","" +"C.CLDSP","","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.LDSP","C.LDSP","Load word via cap","","","","","","","","" +"C.CSDSP","","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.SDSP","C.SDSP","Store word via cap ","","","","","","","","" +"LB","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","0","LOAD","","","","Load signed byte ","","","","","","","","" +"LH","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","1","LOAD","","","","Load signed half ","","","","","","","","" +"C.LH","✔","✔","","","","✔","","Legacy","","","","","✔","","","","","","","","","","","C0","","","","Load signed half ","","","","","","","","" +"LW","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","2","LOAD","","","","Load signed word ","","","","","","","","" +"LBU","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","4","LOAD","","","","Load unsigned byte","","","","","","","","" +"C.LBU","✔","✔","","","","✔","","Legacy","","","","","✔","","","","","","","","","","","C0","","","","Load unsigned byte ","","","","","","","","" +"LHU","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","5","LOAD","","","","Load unsigned half ","","","","","","","","" +"C.LHU","✔","✔","","","","✔","","Legacy","","","","","✔","","","","","","","","","","","C0","","","","Load unsigned half ","","","","","","","","" +"LWU","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","6","LOAD","","","","Load unsigned word ","","","","","","","","" +"LD","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","3","LOAD","","","","Load double ","","","","","","","","" +"SB","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","STORE","","","","Store byte ","","","","","","","","" +"C.SB","✔","✔","","","","✔","","Legacy","","","","","✔","","","","","","","","","","","STORE","","","","Store byte ","","","","","","","","" +"SH","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","STORE","","","","Store half ","","","","","","","","" +"C.SH","✔","✔","","","","✔","","Legacy","","","","","✔","","","","","","","","","","","STORE","","","","Store half ","","","","","","","","" +"SW","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","STORE","","","","Store word ","","","","","","","","" +"SD","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","STORE","","","","Store double ","","","","","","","","" +"CLB","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","0","LOAD","","LB","LB","Load signed byte via cap","","","","","","","","" +"CLH","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","1","LOAD","","LH","LH","Load signed half via cap","","","","","","","","" +"C.CLH","✔","✔","","","","","✔","Capability","","","","","✔","","","","","","","","","","","C0","","C.LH","C.LH","Load signed half via cap","","","","","","","","" +"CLW","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","2","LOAD","","LW","LW","Load signed word via cap","","","","","","","","" +"CLBU","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","4","LOAD","","LBU","LBU","Load unsigned byte via cap","","","","","","","","" +"C.CLBU","✔","✔","","","","","✔","Capability","","","","","✔","","","","","","","","","","","C0","","C.LBU","C.LBU","Load unsigned byte via cap","","","","","","","","" +"CLHU","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","5","LOAD","","LHU","LHU","Load unsigned half via cap","","","","","","","","" +"C.CLHU","✔","✔","","","","","✔","Capability","","","","","✔","","","","","","","","","","","C0","","C.LHU","C.LHU","Load unsigned half via cap","","","","","","","","" +"CLWU","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","6","LOAD","","LWU","LWU","Load unsigned word via cap","","","","","","","","" +"CLD","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","3","LOAD","","LD","LD","Load double via cap","","","","","","","","" +"CSB","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","STORE","","SB","SB","Store byte via cap","","","","","","","","" +"C.CSB","✔","✔","","","","","✔","Capability","","","","","✔","","","","","","","","","","","STORE","","C.SB","C.SB","Store byte via cap","","","","","","","","" +"CSH","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","STORE","","SH","SH","Store half via cap","","","","","","","","" +"C.CSH","✔","✔","","","","","✔","Capability","","","","","✔","","","","","","","","","","","STORE","","C.SH","C.SH","Store half via cap","","","","","","","","" +"CSW","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","STORE","","SW","SW","Store word via cap","","","","","","","","" +"CSD","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","STORE","","SD","SD","Store double via cap","","","","","","","","" +"AUIPC","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","AUIPC","","","","Add immediate to PCC address","","","","","","","","" +"AUIPCC","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","AUIPC","","AUIPC","AUIPC","Add immediate to PCC address, representability check","","","","","","","","" +"CINCOFFSET","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Increment cap address by register, representability check","","","","","","","","" +"CINCOFFSETIMM","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","I-type","","","Increment cap address by immediate, representability check","","","","","","","","" +"CSETADDR","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Replace capability address, representability check","","","","","","","","" +"CGETTAG","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Get tag field","","","","","","","","" +"CGETPERM","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Get hperm and uperm fields as 1-bit per permission, packed together","","","","","","","","" +"CMOVE","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Move capability register","","","","","","","","" +"CANDPERM","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","AND capability permissions (expand to 1-bit per permission before ANDing)","","","","","","","","" +"CGETHIGH","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Get metadata","","","","","","","","" +"CSETHIGH","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Set metadata and clear tag","","","","","","","","" +"CSETEQUALEXACT","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Full capability bitwise compare","","","","","","","","" +"CSEAL","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Seal capability","","","","","","","","" +"CTESTSUBSET","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Set register bounds on capability with rounding, clear tag if rounding is required","","","","","","","","" +"CBUILDCAP","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Set cd to cs2 with its tag set after checking that cs2 is a subset of cs1","","","","","","","","" +"CSETBOUNDS","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Set register bounds on capability with rounding, clear tag if rounding is required","","","","","","","","" +"CSETBOUNDSIMM","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","I-type","","","Set immediate bounds on capability with rounding, clear tag if rounding is required","","","","","","","","" +"CSETBOUNDSINEXACT","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","R-type","","","Set bounds on capability with rounding up as required","","","","","","","","" +"CRAM","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Representable Alignment Mask: Return mask to apply to address to get the requested bounds","","","","","","","","" +"CGETBASE","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Get capability base","","","","","","","","" +"CGETLEN","✔","✔","","","","","✔","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Get capability length","","","","","","","","" +"CSETMODE","✔","✔","","","✔","","","Both","","","","","","","","","","","","","","","","OP","1-src 1-dst","","","Set the mode bit of a capability, no permissions required","","","","","","","","" +"CMODESWITCH","✔","✔","","","✔","","","Both","","","","","","","","","","","","","","","","OP","no operands","","","Directly switch mode (legacy / capability)","mode==D (optional)","","","","","","","" +"C.CMODESWITCH","✔","✔","","","✔","","","Both","","","","","","","","","","","","","","","","C1","no operands","","","Directly switch mode (legacy / capability)","mode==D (optional)","","","","","","","" +"C.ADDI16SP","✔","✔","","","","✔","","Legacy","","","","✔","","","","","","","","","","","","C0","","","","ADD immediate to stack pointer","","","","","","","","" +"C.CINCOFFSET16CSP","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.ADDI16SP","C.ADDI16SP","ADD immediate to stack pointer, representability check","","","","","","","","" +"C.ADDI4SPN","✔","✔","","","","✔","","Legacy","","","","✔","","","","","","","","","","","","C0","","C.ADDI4SPN","C.ADDI4SPN","ADD immediate to stack pointer, representability check","","","","","","","","" +"C.CINCOFFSET4CSPN","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C0","","C.ADDI4SPN","C.ADDI4SPN","ADD immediate to stack pointer, representability check","","","","","","","","" +"C.MV","✔","✔","","","","✔","","Legacy","","","","✔","","","","","","","","","","","","C2","","","","Register Move","","","","","","","","" +"C.CMOVE","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.MV","C.MV","Same as CMove","","","","","","","","" +"C.CJ","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.J","C.J","Jump to PC+offset, bounds check minimum size target instruction","mode==D (optional)","","","","","","","" +"C.CJAL","✔","","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.JAL","C.JAL","Jump to PC+offset, bounds check minimum size target instruction, link to cd","mode==D (optional)","","","","","","","" +"CJAL","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","JAL","","JAL","JAL","Jump to PC+offset, bounds check minimum size target instruction, link to cd","mode==D (optional)","","","","","","","" +"JALR.CAP","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","JALR","","JALR.PCC","JALR.PCC","CJALR available in legacy mode (with zero offset)","mode==D (optional)","","","","","","","" +"JALR.PCC","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","JALR","1-src 1-dst","","","RISC-V JALR available in capability modes (with zero offset)","mode==D (optional)","","","","","","","" +"CJALR","✔","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","JALR","","JALR","JALR","Indirect cap jump and link, bounds check minimum size target instruction, unseal target cap, seal link cap","mode==D (optional)","","","","","","","" +"C.CJALR","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.JALR","C.JALR","Indirect cap jump and link, bounds check minimum size target instruction, unseal target cap, seal link cap","mode==D (optional)","","","","","","","" +"C.CJR","✔","✔","","","","","✔","Capability","","","","✔","","","","","","","","","","","","C2","","C.JR","C.JR","Indirect cap jump, bounds check minimum size target instruction, unseal target cap","mode==D (optional)","","","","","","","" +"DRET","✔","✔","✔","","","","","Legacy","","","","","","","","","","","","","","","","SYSTEM","","","","Return from debug mode, sets DDC from DDDC and PCC from DPCC","MODE.W","✔","✔","","","","✔","","Legacy","✔","","","","","","","","","","","","","","","AMO","","","","Atomic op of word","","","","","","","","" +"CAMO.W","✔","✔","","","","","✔","Capability","✔","","","","","","","","","","","","","","","AMO","","AMO.W","AMO.W","Atomic op of word via cap","","","","","","","","" +"AMO.D","","✔","","","","✔","","Legacy","✔","","","","","","","","","","","","","","","AMO","","","","Atomic op of double","","","","","","","","" +"CAMO.D","","✔","","","","","✔","Capability","✔","","","","","","","","","","","","","","","AMO","","AMO.D","AMO.D","Atomic op of double via cap","","","","","","","","" +"C.FLW","✔","","","","","✔","","Legacy","","","","","","","","","","","✔","","","","","C0","","","","Load floating point word via cap","Xstatus.fs==0","","","","","","","" +"C.FLWSP","✔","","","","","✔","","Legacy","","","","","","","","","","","✔","","","","","C0","","","","Load floating point word, sp relative","Xstatus.fs==0","","","","","","","" +"C.FSW","✔","","","","","✔","","Legacy","","","","","","","","","","","✔","","","","","C0","","","","Store floating point word via cap","Xstatus.fs==0","","","","","","","" +"C.FSWSP","✔","","","","","✔","","Legacy","","","","","","","","","","","✔","","","","","C0","","","","Store floating point word, sp relative","Xstatus.fs==0","","","","","","","" +"C.FLD","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","✔","","","","C0","","","","Load floating point double","Xstatus.fs==0","","","","","","","" +"C.FLDSP","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","✔","","","","C0","","","","Load floating point double, sp relative","Xstatus.fs==0","","","","","","","" +"C.FSD","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","✔","","","","C0","","","","Store floating point double","Xstatus.fs==0","","","","","","","" +"C.FSDSP","✔","✔","","","","✔","","Legacy","","","","","","","","","","","","✔","","","","C0","","","","Store floating point double, sp relative","Xstatus.fs==0","","","","","","","" +"C.CFLD","✔","","","","","","✔","Capability","","","","","","","","","","✔","","✔","","","","C0","","C.FLD","","Load floating point double via cap","Xstatus.fs==0","","","","","","","" +"C.CFLDSP","✔","","","","","","✔","Capability","","","","","","","","","","","","✔","","","","C2","","C.FLDSP","","Load floating point double via cap, sp relative","Xstatus.fs==0","","","","","","","" +"C.CFSD","✔","","","","","","✔","Capability","","","","","","","","","","","","✔","","","","C2","","C.FSD","","Store floating point double via cap","Xstatus.fs==0","","","","","","","" +"C.CFSDSP","✔","","","","","","✔","Capability","","","","","","","","","","","","✔","","","","C2","","C.FSDSP","","Store floating point double via cap, sp relative","Xstatus.fs==0","","","","","","","" +"CFLH","✔","✔","","","","","✔","Capability","","","","","","","","","","✔","","","","","","LOAD-FP","","FLH","FLH","Load floating point half via cap","Xstatus.fs==0","","","","","","","" +"CFSH","✔","✔","","","","","✔","Capability","","","","","","","","","","✔","","","","","","STORE-FP","","FSH","FSH","Store floating point half via cap","Xstatus.fs==0","","","","","","","" +"CFLW","✔","✔","","","","","✔","Capability","","","","","","","","","","","✔","","","","","LOAD-FP","","FLW","FLW","Load floating point word via cap","Xstatus.fs==0","","","","","","","" +"CFSW","✔","✔","","","","","✔","Capability","","","","","","","","","","","✔","","","","","STORE-FP","","FSW","FSW","Store floating point word via cap","Xstatus.fs==0","","","","","","","" +"CFLD","✔","✔","","","","","✔","Capability","","","","","","","","","","","","✔","","","","LOAD-FP","","FLD","FLD","Load floating point double via cap","Xstatus.fs==0","","","","","","","" +"CFSD","✔","✔","","","","","✔","Capability","","","","","","","","","","","","✔","","","","STORE-FP","","FSD","FSD","Store floating point double via cap","Xstatus.fs==0","","","","","","","" +"CM.PUSH","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Push integer stack frame","","","","","","","","" +"CM.POP","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Pop integer stack frame","","","","","","","","" +"CM.POPRET","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Pop integer stack frame and return","","","","","","","","" +"CM.POPRETZ","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Pop integer stack frame and return zero","","","","","","","","" +"CM.MVSA01","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Move two integer registers","","","","","","","","" +"CM.MVA01S","✔","✔","","","","✔","","Legacy","","","","","","","","✔","","","","","","","","C2","","","","Move two integer registers","","","","","","","","" +"CM.CPUSH","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.PUSH","CM.PUSH","Push capability stack frame","","","","","","","","" +"CM.CPOP","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.POP","CM.POP","Pop capability stack frame","","","","","","","","" +"CM.CPOPRET","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.POPRET","CM.POPRET","Pop capability stack frame and return","","","","","","","","" +"CM.CPOPRETZ","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.POPRETZ","CM.POPRETZ","Pop capability stack frame and return zero","","","","","","","","" +"CM.CMVSA01","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.MVSA01","CM.MVSA01","Move two capability registers","","","","","","","","" +"CM.CMVA01S","✔","✔","","","","","✔","Capability","","","","","","","","✔","","","","","","","","C2","","CM.MVA01S","CM.MVA01S","Move two capability registers","","","","","","","","" +"CM.JALT","✔","✔","","","","✔","","Legacy","","","","","","","","","✔","","","","","","","C2","","","","Table jump and link","","","","","","","","" +"CM.JT","✔","✔","","","","✔","","Legacy","","","","","","","","","✔","","","","","","","C2","","","","Table jump","","","","","","","","" +"CM.CJALT","✔","✔","","","","","✔","Capability","","","","","","","","","✔","","","","","","","C2","","CM.JALT","CM.JALT","Table jump and link","","","","","","","","" +"CM.CJT","✔","✔","","","","","✔","Capability","","","","","","","","","✔","","","","","","","C2","","CM.JT","CM.JT","Table jump","","","","","","","","" +"CSH1ADD","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH1ADD","SH1ADD","shift and add, representability check on the result","","","","","","","","" +"CSH1ADD.UW","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH1ADD.UW","SH1ADD.UW","shift and add, representability check on the result","","","","","","","","" +"CSH2ADD","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH2ADD","SH2ADD","shift and add, representability check on the result","","","","","","","","" +"CSH2ADD.UW","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH2ADD.UW","SH2ADD.UW","shift and add, representability check on the result","","","","","","","","" +"CSH3ADD","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH3ADD","SH3ADD","shift and add, representability check on the result","","","","","","","","" +"CSH3ADD.UW","✔","✔","","","","","✔","Capability","","","✔","","","","","","","","","","","","","OP","","SH3ADD.UW","SH3ADD.UW","shift and add, representability check on the result","","","","","","","","" +"SH4ADD","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","OP","","","","shift and add","","","","","","","","" +"SH4ADD.UW","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","OP","","","","shift and add","","","","","","","","" +"CSH4ADD","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","OP","","SH4ADD","SH4ADD","shift and add, representability check on the result","","","","","","","","" +"CSH4ADD.UW","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","OP","","SH4ADD.UW","SH4ADD.UW","shift and add, representability check on the result","","","","","","","","" \ No newline at end of file diff --git a/src/debug-integration.adoc b/src/debug-integration.adoc new file mode 100644 index 00000000..f6623ee0 --- /dev/null +++ b/src/debug-integration.adoc @@ -0,0 +1,106 @@ +[#section_debug_integration] +== Integrating Zcheri_purecap with Sdext + +This section describes changes to integrate the Sdext ISA and +{cheri_base_ext_name}. It must be implemented to make external debug compatible +with {cheri_base_ext_name}. Modifications to Sdext are kept to a minimum. + +=== Debug Mode + +When executing code due to an abstract command, the hart stays in debug mode +and the rules outlined in Section 4.1 of cite:[riscv-debug-spec] +apply. + +=== Core Debug Registers + +{cheri_base_ext_name} removes debug CSRs that are designated to hold addresses +and replaces them with analogous CSRs able to hold capabilities. The removed +debug CSRs are listed in xref:dcsrnames-removed[xrefstyle=short] and the +new CSRs are listed in xref:dcsrnames-replaced[xrefstyle=short]. + +The <> must grant <> to access debug CSRs. This permission is +automatically provided when the hart enters debug mode as described +in the <> section. The <> metadata can only be changed if the +implementation supports executing control transfer instructions from the +program buffer -- this is an optional feature according to +cite:[riscv-debug-spec]. + +[#dpc,reftext="dpc"] +==== Debug Program Counter (dpc) + +The <> register is as defined in cite:[riscv-debug-spec]. It is a +DXLEN-bit register used as the PC saved when entering debug mode. <> is +extended into <>. + +.Debug program counter +include::img/dpcreg.edn[] + +[#dpcc,reftext="dpcc"] +==== Debug Program Counter Capability (dpcc) + +The <> register is a extension to <> that is able to hold a +capability. Its reset value is the <> capability. + +.Debug program counter capability +include::img/dpccreg.edn[] + +Upon entry to debug mode, cite:[riscv-debug-spec], does not specify how to +update the PC, and says PC relative instructions may be illegal. This concept +is extended to include any instruction which updates <>. + +<> (and consequently <>) are updated with the +capability in <> whose address field is set to the address of the next +instruction to be executed as described in cite:[riscv-debug-spec]. + +Additionally, the <> is updated as follows: + +* All metadata is set to the <> capability + ** The <> may be used as a source of the <> capability in +debug mode to allow other capabilities to be created and written into memory. + +When resuming, the hart's <> is updated to the capability stored in +<>. A debugger may write <> to change where the hart resumes and +its mode, permissions, sealing or bounds. + +[#dscratch0,reftext="dscratch0"] +==== Debug Scratch Register 0 (dscratch0) + +The <> register is as defined in cite:[riscv-debug-spec]. It is an +optional DXLEN-bit scratch register that can be used by implementations which +need it. Its reset value is the <> capability. <> is +extended into <>. + +.Debug scratch 0 register +include::img/dscratch0reg.edn[] + +[#dscratch0c,reftext="dscratch0c"] +==== Debug Scratch Register 0 (dscratch0c) + +The <> register is a CLEN-bit plus tag bit extension to +<> that is able to hold a capability. Its reset value is the +<> capability. + +.Debug scratch 0 capability register +include::img/dscratch0creg.edn[] + +[#dscratch1,reftext="dscratch1"] +==== Debug Scratch Register 1 (dscratch1) + +The <> register is as defined in cite:[riscv-debug-spec]. It is an +optional DXLEN-bit scratch register that can be used by implementations which +need it. Its reset value is the <> capability. <> is +extended into <>. + +.Debug scratch 0 register +include::img/dscratch1reg.edn[] + +[#dscratch1c,reftext="dscratch1c"] +==== Debug Scratch Register 1 (dscratch1c) + +The <> register is a CLEN-bit plus tag bit extension to +<> that is able to hold a capability. Its reset value is the +<> capability. + +.Debug scratch 1 capability register +include::img/dscratch1creg.edn[] + diff --git a/src/img/candperms_bit_field.edn b/src/img/candperms_bit_field.edn new file mode 100644 index 00000000..3c57c40e --- /dev/null +++ b/src/img/candperms_bit_field.edn @@ -0,0 +1,28 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "1" "2" "3" "4" "" "" "" "" "" "" "" "" "" "" "" "16" "" "" "SDPLEN+15" "" "" "" "" "" "" "" "" "" "" "" "XLEN-1"])}) + +(draw-box "Reserved" {:span 12}) +(draw-box "SDP" {:span 4}) +(draw-box "Reserved" {:span 11}) +(draw-box "ASR" {:span 1}) +(draw-box "X" {:span 1}) +(draw-box "C" {:span 1}) +(draw-box "W" {:span 1}) +(draw-box "R" {:span 1}) + +(draw-box "XLEN-SDPLEN-16" {:span 12 :borders {}}) +(draw-box "SDPLEN" {:span 4 :borders {}}) +(draw-box "11" {:span 11 :borders {}}) +(draw-box "1" {:span 1 :borders {}}) +(draw-box "1" {:span 1 :borders {}}) +(draw-box "1" {:span 1 :borders {}}) +(draw-box "1" {:span 1 :borders {}}) +(draw-box "1" {:span 1 :borders {}}) +---- diff --git a/src/img/cap-bounds-map.png b/src/img/cap-bounds-map.png new file mode 100644 index 00000000..8221b40c Binary files /dev/null and b/src/img/cap-bounds-map.png differ diff --git a/src/img/cap-encoding-xlen32-mode.edn b/src/img/cap-encoding-xlen32-mode.edn new file mode 100644 index 00000000..effd85b0 --- /dev/null +++ b/src/img/cap-encoding-xlen32-mode.edn @@ -0,0 +1,25 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 26 :labels (reverse ["0" "1" "2" "" "" "" "" "" "" "9" "10" "11" "12" "" "" "" "" "17" "18" "19" "20" "21" "" "" "24" "25" "26" "" "" "29" "30" "31"])}) + +(draw-box "SDP" {:span 2}) +(draw-box "AP" {:span 4}) +(draw-box "M" {:span 1}) +(draw-box "Reserved" {:span 4}) +(draw-box "S" {:span 1}) +(draw-box "EF" {:span 1}) +(draw-box "T8" {:span 1}) +(draw-box "T[7:2]" {:span 6}) +(draw-box "TE" {:span 2}) +(draw-box "B[9:2]" {:span 8}) +(draw-box "BE" {:span 2}) +(draw-box "Address" {:span 32}) + +(draw-box "32" {:span 32 :borders {}}) +---- diff --git a/src/img/cap-encoding-xlen32.edn b/src/img/cap-encoding-xlen32.edn new file mode 100644 index 00000000..c37fbe50 --- /dev/null +++ b/src/img/cap-encoding-xlen32.edn @@ -0,0 +1,24 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 26 :labels (reverse ["0" "1" "2" "" "" "" "" "" "" "9" "10" "11" "12" "" "" "" "" "17" "18" "19" "20" "21" "" "" "" "25" "26" "" "" "29" "30" "31"])}) + +(draw-box "SDP" {:span 2}) +(draw-box "AP" {:span 4}) +(draw-box "Reserved" {:span 5}) +(draw-box "S" {:span 1}) +(draw-box "EF" {:span 1}) +(draw-box "T8" {:span 1}) +(draw-box "T[7:2]" {:span 6}) +(draw-box "TE" {:span 2}) +(draw-box "B[9:2]" {:span 8}) +(draw-box "BE" {:span 2}) +(draw-box "Address" {:span 32}) + +(draw-box "32" {:span 32 :borders {}}) +---- diff --git a/src/img/cap-encoding-xlen64-mode.edn b/src/img/cap-encoding-xlen64-mode.edn new file mode 100644 index 00000000..b9dd8e07 --- /dev/null +++ b/src/img/cap-encoding-xlen64-mode.edn @@ -0,0 +1,25 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 26 :labels (reverse ["0" "2" "3" "" "" "" "13" "14" "16" "17" "" "" "25" "26" "27" "28" "" "" "" "" "" "" "46" "47" "48" "52" "53" "56" "57" "" "" "63"])}) + +(draw-box "Reserved" {:span 4}) +(draw-box "SDP" {:span 2}) +(draw-box "AP" {:span 2}) +(draw-box "M" {:span 1}) +(draw-box "Reserved" {:span 8}) +(draw-box "S" {:span 1}) +(draw-box "EF" {:span 1}) +(draw-box "T[11:3]" {:span 4}) +(draw-box "TE" {:span 2}) +(draw-box "B[13:3]" {:span 5}) +(draw-box "BE" {:span 2}) +(draw-box "Address" {:span 32}) + +(draw-box "64" {:span 32 :borders {}}) +---- diff --git a/src/img/cap-encoding-xlen64.edn b/src/img/cap-encoding-xlen64.edn new file mode 100644 index 00000000..50acae6d --- /dev/null +++ b/src/img/cap-encoding-xlen64.edn @@ -0,0 +1,24 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 30}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 26 :labels (reverse ["0" "2" "3" "" "" "" "13" "14" "16" "17" "" "" "25" "26" "27" "28" "" "" "" "" "" "" "" "47" "48" "52" "53" "56" "57" "" "" "63"])}) + +(draw-box "Reserved" {:span 4}) +(draw-box "SDP" {:span 2}) +(draw-box "AP" {:span 2}) +(draw-box "Reserved" {:span 9}) +(draw-box "S" {:span 1}) +(draw-box "EF" {:span 1}) +(draw-box "T[11:3]" {:span 4}) +(draw-box "TE" {:span 2}) +(draw-box "B[13:3]" {:span 5}) +(draw-box "BE" {:span 2}) +(draw-box "Address" {:span 32}) + +(draw-box "64" {:span 32 :borders {}}) +---- diff --git a/src/img/ddcreg.edn b/src/img/ddcreg.edn new file mode 100644 index 00000000..63674745 --- /dev/null +++ b/src/img/ddcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "ddc (Metadata)" {:span 32}) +(draw-box "ddc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/dddcreg.edn b/src/img/dddcreg.edn new file mode 100644 index 00000000..6f365935 --- /dev/null +++ b/src/img/dddcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "dddc (Metadata)" {:span 32}) +(draw-box "dddc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/dpccreg.edn b/src/img/dpccreg.edn new file mode 100644 index 00000000..2deb7433 --- /dev/null +++ b/src/img/dpccreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "dpcc (Metadata)" {:span 32}) +(draw-box "dpcc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/dpcreg.edn b/src/img/dpcreg.edn new file mode 100644 index 00000000..cde60c1a --- /dev/null +++ b/src/img/dpcreg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "DXLEN-1"])}) + +(draw-box "dpc" {:span 32}) + +(draw-box "DXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/dscratch0creg.edn b/src/img/dscratch0creg.edn new file mode 100644 index 00000000..5cd83e81 --- /dev/null +++ b/src/img/dscratch0creg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "dscratch0c (Metadata)" {:span 32}) +(draw-box "dscratch0c (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/dscratch0reg.edn b/src/img/dscratch0reg.edn new file mode 100644 index 00000000..06c6d97d --- /dev/null +++ b/src/img/dscratch0reg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "DXLEN-1"])}) + +(draw-box "dscratch0" {:span 32}) + +(draw-box "DXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/dscratch1creg.edn b/src/img/dscratch1creg.edn new file mode 100644 index 00000000..a83e0bc9 --- /dev/null +++ b/src/img/dscratch1creg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "dscratch1c (Metadata)" {:span 32}) +(draw-box "dscratch1c (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/dscratch1reg.edn b/src/img/dscratch1reg.edn new file mode 100644 index 00000000..b7711c05 --- /dev/null +++ b/src/img/dscratch1reg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "DXLEN-1"])}) + +(draw-box "dscratch1" {:span 32}) + +(draw-box "DXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/jvtcreg.edn b/src/img/jvtcreg.edn new file mode 100644 index 00000000..7b5108ca --- /dev/null +++ b/src/img/jvtcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "jvtc (Metadata)" {:span 32}) +(draw-box "jvtc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/mcausereg.edn b/src/img/mcausereg.edn new file mode 100644 index 00000000..f0117ebd --- /dev/null +++ b/src/img/mcausereg.edn @@ -0,0 +1,20 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 200) +(def right-margin 200) +(def boxes-per-row 32) + +(draw-box "MXLEN-1" {:span 4 :borders {}}) +(draw-box "MXLEN-2" {:span 14 :borders {} :text-anchor "start"}) +(draw-box "0" {:span 14 :borders {} :text-anchor "end"}) + +(draw-box "Interrupt" {:span 4}) +(draw-box "Exception Code " {:span 15 :text-anchor "end" :borders {:top :border-unrelated :bottom :border-unrelated :left :border-unrelated}}) +(draw-box (text "(WLRL)" {:font-weight "bold"}) {:span 13 :text-anchor "start" :borders {:top :border-unrelated :bottom :border-unrelated :right :border-unrelated}}) + +(draw-box "1" {:span 4 :borders {}}) +(draw-box "MXLEN-1" {:font-size 24 :span 28 :borders {}}) +---- diff --git a/src/img/menvcfgmodereg.edn b/src/img/menvcfgmodereg.edn new file mode 100644 index 00000000..d924f052 --- /dev/null +++ b/src/img/menvcfgmodereg.edn @@ -0,0 +1,30 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback"}]) +(def row-height 45) +(def row-header-fn nil) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "27" "28" "" "29" "" "" "" "" "" "" "61" "" "62" "" "63"])}) + +(draw-box "STCE" {:span 2}) +(draw-box "PBMTE" {:span 2}) +(draw-box (text "WPRI" {:font-weight "bold"}) {:span 8}) +(draw-box "CME" {:span 2}) +(draw-box (text "WPRI" {:font-weight "bold"}) {:span 8}) +(draw-box "CBZE" {:span 2}) +(draw-box "CBCFE" {:span 2}) +(draw-box "CBIE" {:span 2}) +(draw-box "WPRI" {:span 2}) +(draw-box "FIOM" {:span 2}) + +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "34" {:span 8 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "19" {:span 8 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "3" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +---- diff --git a/src/img/menvcfgreg.edn b/src/img/menvcfgreg.edn new file mode 100644 index 00000000..2fc83042 --- /dev/null +++ b/src/img/menvcfgreg.edn @@ -0,0 +1,29 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback"}]) +(def row-height 45) +(def row-header-fn nil) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "60" "" "61" "" "62" "" "63"])}) + +(draw-box "STCE" {:span 2}) +(draw-box "PBMTE" {:span 2}) +(draw-box "CDE" {:span 2}) +(draw-box (text "WPRI" {:font-weight "bold"}) {:span 16}) +(draw-box "CBZE" {:span 2}) +(draw-box "CBCFE" {:span 2}) +(draw-box "CBIE" {:span 2}) +(draw-box "WPRI" {:span 2}) +(draw-box "FIOM" {:span 2}) + +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "55" {:span 16 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "3" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +---- diff --git a/src/img/mepccreg.edn b/src/img/mepccreg.edn new file mode 100644 index 00000000..e7b9106d --- /dev/null +++ b/src/img/mepccreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "mepcc (Metadata, WARL)" {:span 32}) +(draw-box "mepcc (Address, WARL)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/mepcreg.edn b/src/img/mepcreg.edn new file mode 100644 index 00000000..77ed5335 --- /dev/null +++ b/src/img/mepcreg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1"])}) + +(draw-box "mepc (WARL)" {:span 32}) + +(draw-box "MXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/mscratchcreg.edn b/src/img/mscratchcreg.edn new file mode 100644 index 00000000..79c71ce5 --- /dev/null +++ b/src/img/mscratchcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "mscratchc (Metadata)" {:span 32}) +(draw-box "mscratchc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/mscratchreg.edn b/src/img/mscratchreg.edn new file mode 100644 index 00000000..85e946b2 --- /dev/null +++ b/src/img/mscratchreg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1"])}) + +(draw-box "mscratch" {:span 32}) + +(draw-box "MXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/mtdcreg.edn b/src/img/mtdcreg.edn new file mode 100644 index 00000000..d2d961a2 --- /dev/null +++ b/src/img/mtdcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "mtdc (Metadata)" {:span 32}) +(draw-box "mtdc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/mtvalreg.edn b/src/img/mtvalreg.edn new file mode 100644 index 00000000..ea6b2963 --- /dev/null +++ b/src/img/mtvalreg.edn @@ -0,0 +1,21 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "3" "4" "" "" "" "" "" "" "" "" "" "" "15" "16" "" "" "19" "20" "" "" "" "" "" "" "" "" "" "" "MXLEN-1"])}) + +(draw-box "Reserved" {:span 12}) +(draw-box "TYPE" {:span 4}) +(draw-box "Reserved" {:span 12}) +(draw-box "CAUSE" {:span 4}) + +(draw-box "MXLEN-20" {:span 12 :borders {}}) +(draw-box "4" {:span 4 :borders {}}) +(draw-box "12" {:span 12 :borders {}}) +(draw-box "4" {:span 4 :borders {}}) +---- + diff --git a/src/img/mtveccreg.edn b/src/img/mtveccreg.edn new file mode 100644 index 00000000..17fd7515 --- /dev/null +++ b/src/img/mtveccreg.edn @@ -0,0 +1,17 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "1" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "Metadata (WARL)" {:span 32}) +(draw-box "BASE [XLENMAX-1:2] (WARL)" {:span 24}) +(draw-box "MODE (WARL)" {:span 8}) + +(draw-box "XLENMAX-2" {:span 24 :borders {}}) +(draw-box "2" {:span 8 :borders {}}) +---- diff --git a/src/img/mtvecreg.edn b/src/img/mtvecreg.edn new file mode 100644 index 00000000..3c930db7 --- /dev/null +++ b/src/img/mtvecreg.edn @@ -0,0 +1,16 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "1" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1"])}) + +(draw-box "BASE [MXLEN-1:2] (WARL)" {:span 24}) +(draw-box "MODE (WARL)" {:span 8}) + +(draw-box "MXLEN-2" {:span 24 :borders {}}) +(draw-box "2" {:span 8 :borders {}}) +---- diff --git a/src/img/pccreg.edn b/src/img/pccreg.edn new file mode 100644 index 00000000..81eef625 --- /dev/null +++ b/src/img/pccreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "pcc (Metadata, WARL)" {:span 32}) +(draw-box "pcc (Address, WARL)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/images/risc-v_logo.png b/src/img/risc-v_logo.png old mode 100755 new mode 100644 similarity index 100% rename from images/risc-v_logo.png rename to src/img/risc-v_logo.png diff --git a/src/img/scausereg.edn b/src/img/scausereg.edn new file mode 100644 index 00000000..718114fd --- /dev/null +++ b/src/img/scausereg.edn @@ -0,0 +1,20 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 200) +(def right-margin 200) +(def boxes-per-row 32) + +(draw-box "SXLEN-1" {:span 4 :borders {}}) +(draw-box "SXLEN-2" {:span 14 :borders {} :text-anchor "start"}) +(draw-box "0" {:span 14 :borders {} :text-anchor "end"}) + +(draw-box "Interrupt" {:span 4}) +(draw-box "Exception Code " {:span 15 :text-anchor "end" :borders {:top :border-unrelated :bottom :border-unrelated :left :border-unrelated}}) +(draw-box (text "(WLRL)" {:font-weight "bold"}) {:span 13 :text-anchor "start" :borders {:top :border-unrelated :bottom :border-unrelated :right :border-unrelated}}) + +(draw-box "1" {:span 4 :borders {}}) +(draw-box "SXLEN-1" {:font-size 24 :span 28 :borders {}}) +---- diff --git a/src/img/senvcfgreg.edn b/src/img/senvcfgreg.edn new file mode 100644 index 00000000..a40dd90e --- /dev/null +++ b/src/img/senvcfgreg.edn @@ -0,0 +1,28 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 20}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 30) +(def right-margin 30) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "27" "28" "" "29" "" "" "SXLEN-1"])}) + +(draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 4}) +(draw-box "CME" {:span 2}) +(draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 16}) +(draw-box "CBZE" {:span 2}) +(draw-box "CBCFE" {:span 2}) +(draw-box "CBIE" {:span 2}) +(draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 2}) +(draw-box "FIOM" {:span 2}) + +(draw-box "SXLEN-29" {:span 4 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "20" {:span 16 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "3" {:span 2 :borders {}}) +(draw-box "1" {:span 2 :borders {}}) +---- diff --git a/src/img/sepccreg.edn b/src/img/sepccreg.edn new file mode 100644 index 00000000..79f6bc7c --- /dev/null +++ b/src/img/sepccreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "sepcc (Metadata, WARL)" {:span 32}) +(draw-box "sepcc (Address, WARL)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/sepcreg.edn b/src/img/sepcreg.edn new file mode 100644 index 00000000..24c74b74 --- /dev/null +++ b/src/img/sepcreg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "SXLEN-1"])}) + +(draw-box "sepc" {:span 32}) + +(draw-box "SXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/sscratchcreg.edn b/src/img/sscratchcreg.edn new file mode 100644 index 00000000..24453efc --- /dev/null +++ b/src/img/sscratchcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "sscratchc (Metadata)" {:span 32}) +(draw-box "sscratchc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/sscratchreg.edn b/src/img/sscratchreg.edn new file mode 100644 index 00000000..e2841b2b --- /dev/null +++ b/src/img/sscratchreg.edn @@ -0,0 +1,14 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "SXLEN-1"])}) + +(draw-box "sscratch" {:span 32}) + +(draw-box "SXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/stdcreg.edn b/src/img/stdcreg.edn new file mode 100644 index 00000000..56c1178e --- /dev/null +++ b/src/img/stdcreg.edn @@ -0,0 +1,15 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "stdc (Metadata)" {:span 32}) +(draw-box "stdc (Address)" {:span 32}) + +(draw-box "XLENMAX" {:span 32 :borders {}}) +---- diff --git a/src/img/stvalreg.edn b/src/img/stvalreg.edn new file mode 100644 index 00000000..31642298 --- /dev/null +++ b/src/img/stvalreg.edn @@ -0,0 +1,21 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "3" "4" "" "" "" "" "" "" "" "" "" "" "15" "16" "" "" "19" "20" "" "" "" "" "" "" "" "" "" "" "SXLEN-1"])}) + +(draw-box "Reserved" {:span 12}) +(draw-box "TYPE" {:span 4}) +(draw-box "Reserved" {:span 12}) +(draw-box "CAUSE" {:span 4}) + +(draw-box "SXLEN-20" {:span 12 :borders {}}) +(draw-box "4" {:span 4 :borders {}}) +(draw-box "12" {:span 12 :borders {}}) +(draw-box "4" {:span 4 :borders {}}) +---- + diff --git a/src/img/stveccreg.edn b/src/img/stveccreg.edn new file mode 100644 index 00000000..cd1a034e --- /dev/null +++ b/src/img/stveccreg.edn @@ -0,0 +1,17 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "1" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "XLENMAX-1"])}) + +(draw-box "Metadata (WARL)" {:span 32}) +(draw-box "BASE [XLENMAX-1:2] (WARL)" {:span 24}) +(draw-box "MODE (WARL)" {:span 8}) + +(draw-box "XLENMAX-2" {:span 24 :borders {}}) +(draw-box "2" {:span 8 :borders {}}) +---- diff --git a/src/img/stvecreg.edn b/src/img/stvecreg.edn new file mode 100644 index 00000000..c8fb175f --- /dev/null +++ b/src/img/stvecreg.edn @@ -0,0 +1,16 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 24}]) +(def row-height 40) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "1" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "SXLEN-1"])}) + +(draw-box "BASE (Address)[SXLEN-1:2] (WARL)" {:span 24}) +(draw-box "MODE (WARL)" {:span 8}) + +(draw-box "SXLEN-2" {:span 24 :borders {}}) +(draw-box "2" {:span 8 :borders {}}) +---- diff --git a/src/img/sv39pte.edn b/src/img/sv39pte.edn new file mode 100644 index 00000000..8dd0ff8d --- /dev/null +++ b/src/img/sv39pte.edn @@ -0,0 +1,69 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 18}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 30) +(def right-margin 30) +(def boxes-per-row 32) + +(draw-box "63" {:borders {}}) +(draw-box "62" {:borders {}}) +(draw-box "61" {:borders {}}) +(draw-box "60" {:borders {}}) +(draw-box "59" {:borders {}}) +(draw-box "58" {:span 1 :text-anchor "start" :borders {}}) +(draw-box "54" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "53" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "28" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "27" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "19" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "18" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "10" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "9" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "8" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "7" {:borders {}}) +(draw-box "6" {:borders {}}) +(draw-box "5" {:borders {}}) +(draw-box "4" {:borders {}}) +(draw-box "3" {:borders {}}) +(draw-box "2" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "0" {:borders {}}) + +(draw-box "N") +(draw-box "PBMT" {:span 2}) +(draw-box "CD" {:span 1}) +(draw-box "CW" {:span 1}) +(draw-box "Reserved" {:span 3}) +(draw-box "PPN[2]" {:span 4}) +(draw-box "PPN[1]" {:span 4}) +(draw-box "PPN[0]" {:span 4}) +(draw-box "RSW" {:span 4}) +(draw-box "D") +(draw-box "A") +(draw-box "G") +(draw-box "U") +(draw-box "X") +(draw-box "W") +(draw-box "R") +(draw-box "V") + +(draw-box "1" {:borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "5" {:span 3 :borders {}}) +(draw-box "26" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box "2" {:span 4 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +---- diff --git a/src/img/sv48pte.edn b/src/img/sv48pte.edn new file mode 100644 index 00000000..bc24c870 --- /dev/null +++ b/src/img/sv48pte.edn @@ -0,0 +1,88 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 18}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 30) +(def right-margin 30) +(def boxes-per-row 32) + +(draw-box "63" {:borders {}}) +(draw-box "62" {:borders {}}) +(draw-box "61" {:borders {}}) +(draw-box "60" {:borders {}}) +(draw-box "59" {:borders {}}) +(draw-box "58" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "54" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "53" {:span 4 :text-anchor "start" :borders {}}) +(draw-box "10" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "9" {:span 4 :text-anchor "start" :borders {}}) +(draw-box "8" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "7" {:borders {}}) +(draw-box "6" {:borders {}}) +(draw-box "5" {:borders {}}) +(draw-box "4" {:borders {}}) +(draw-box "3" {:borders {}}) +(draw-box "2" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "0" {:borders {}}) + +(draw-box "N") +(draw-box "PBMT" {:span 2}) +(draw-box "CD" {:span 1}) +(draw-box "CW" {:span 1}) +(draw-box "Reserved" {:span 5}) +(draw-box "PPN" {:span 7}) +(draw-box "RSW" {:span 7}) +(draw-box "D") +(draw-box "A") +(draw-box "G") +(draw-box "U") +(draw-box "X") +(draw-box "W") +(draw-box "R") +(draw-box "V") + +(draw-box "1" {:borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "5" {:span 5 :borders {}}) +(draw-box "44" {:span 7 :borders {}}) +(draw-box "2" {:span 7 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) + +(draw-box nil {:span 32 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "53" {:span 3 :text-anchor "start" :borders {}}) +(draw-box "37" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "36" {:span 3 :text-anchor "start" :borders {}}) +(draw-box "28" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "27" {:span 3 :text-anchor "start" :borders {}}) +(draw-box "19" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "18" {:span 3 :text-anchor "start" :borders {}}) +(draw-box "10" {:span 2 :text-anchor "end" :borders {}}) +(draw-box nil {:span 6 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "PPN[3]" {:span 5}) +(draw-box "PPN[2]" {:span 5}) +(draw-box "PPN[1]" {:span 5}) +(draw-box "PPN[0]" {:span 5}) +(draw-box nil {:span 6 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "17" {:span 5 :borders {}}) +(draw-box "9" {:span 5 :borders {}}) +(draw-box "9" {:span 5 :borders {}}) +(draw-box "9" {:span 5 :borders {}}) +(draw-box nil {:span 6 :borders {}}) +---- diff --git a/src/img/sv57pte.edn b/src/img/sv57pte.edn new file mode 100644 index 00000000..c30f14fe --- /dev/null +++ b/src/img/sv57pte.edn @@ -0,0 +1,92 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 20}]) +(def row-height 40 ) +(def row-header-fn nil) +(def left-margin 30) +(def right-margin 30) +(def boxes-per-row 32) + +(draw-box "63" {:borders {}}) +(draw-box "62" {:borders {}}) +(draw-box "61" {:borders {}}) +(draw-box "60" {:borders {}}) +(draw-box "59" {:borders {}}) +(draw-box "58" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "54" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "53" {:span 4 :text-anchor "start" :borders {}}) +(draw-box "10" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "9" {:span 4 :text-anchor "start" :borders {}}) +(draw-box "8" {:span 3 :text-anchor "end" :borders {}}) +(draw-box "7" {:borders {}}) +(draw-box "6" {:borders {}}) +(draw-box "5" {:borders {}}) +(draw-box "4" {:borders {}}) +(draw-box "3" {:borders {}}) +(draw-box "2" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "0" {:borders {}}) + +(draw-box "N") +(draw-box "PBMT" {:span 2}) +(draw-box "CD" {:span 1}) +(draw-box "CW" {:span 1}) +(draw-box "Reserved" {:span 5}) +(draw-box "PPN" {:span 7}) +(draw-box "RSW" {:span 7}) +(draw-box "D") +(draw-box "A") +(draw-box "G") +(draw-box "U") +(draw-box "X") +(draw-box "W") +(draw-box "R") +(draw-box "V") + +(draw-box "1" {:borders {}}) +(draw-box "2" {:span 2 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "5" {:span 5 :borders {}}) +(draw-box "44" {:span 7 :borders {}}) +(draw-box "2" {:span 7 :borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) +(draw-box "1" {:borders {}}) + +(draw-box nil {:span 32 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "53" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "46" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "45" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "37" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "36" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "28" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "27" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "19" {:span 2 :text-anchor "end" :borders {}}) +(draw-box "18" {:span 2 :text-anchor "start" :borders {}}) +(draw-box "10" {:span 2 :text-anchor "end" :borders {}}) +(draw-box nil {:span 6 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "PPN[4]" {:span 4}) +(draw-box "PPN[3]" {:span 4}) +(draw-box "PPN[2]" {:span 4}) +(draw-box "PPN[1]" {:span 4}) +(draw-box "PPN[0]" {:span 4}) +(draw-box nil {:span 6 :borders {}}) + +(draw-box nil {:span 6 :borders {}}) +(draw-box "8" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box "9" {:span 4 :borders {}}) +(draw-box nil {:span 6 :borders {}}) +---- diff --git a/index.adoc b/src/index.adoc similarity index 100% rename from index.adoc rename to src/index.adoc diff --git a/src/insns/addi16sp_16bit.adoc b/src/insns/addi16sp_16bit.adoc new file mode 100644 index 00000000..3f6f5958 --- /dev/null +++ b/src/insns/addi16sp_16bit.adoc @@ -0,0 +1,49 @@ +<<< +//[#insns-addi16sp-16bit,reftext="Stack pointer increment in blocks of 16 (C.CINCOFFSET16CSP, C.ADDI16SP), 16-bit encodings"] + +[#C_ADDI16SP, reftext="C.ADDI16SP"] +==== C.ADDI16SP + +See <>. + +[#C_CINCOFFSET16CSP, reftext="C.CINCOFFSET16CSP"] +==== C.CINCOFFSET16CSP + +Synopsis:: +Stack pointer increment in blocks of 16 (C.CINCOFFSET16CSP, C.ADDI16SP), 16-bit encodings + +Capability Mode Mnemonic:: +`c.cincoffset16csp imm` + +Capability Mode Expansion:: +`cincoffset csp, csp, imm` + +Legacy Mode Mnemonic:: +`c.addi16sp imm` + +Legacy Mode Expansion:: +`add sp, sp, imm` + +Encoding:: +include::wavedrom/c-int-reg-immed.adoc[] + +Capability Mode Description:: + +Add the non-zero sign-extended 6-bit immediate to the value in the stack pointer (csp=c2), where the immediate is scaled to represent multiples of 16 in the range (-512,496). Clear the tag if the resulting capability is +unrepresentable or `csp` is sealed. + +Legacy Mode Description:: + +Add the non-zero sign-extended 6-bit immediate to the value in the stack pointer (sp=x2), where the immediate is scaled to represent multiples of 16 in the range (-512,496). + +Prerequisites for C.CINCOFFSET16CSP:: +{c_cheri_base_ext_names} + +Prerequisites for C.ADDI16SP:: +{c_cheri_legacy_ext_names} + +Capability Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/addi4spn_16bit.adoc b/src/insns/addi4spn_16bit.adoc new file mode 100644 index 00000000..b938590e --- /dev/null +++ b/src/insns/addi4spn_16bit.adoc @@ -0,0 +1,48 @@ +<<< +//[#insns-addi4spn-16bit,reftext="Stack pointer increment in blocks of 4 (C.CINCOFFSET4CSPN, C.ADDI4SPN), 16-bit encodings"] + +[#C_ADDI4SPN,reftext="C.ADDI4SPN"] +==== C.ADDI4SPN + +See <>. + +[#C_CINCOFFSET4CSPN,reftext="C.CINCOFFSET4CSPN"] +==== C.CINCOFFSET4CSPN + +Synopsis:: +Stack pointer increment in blocks of 4 (C.CINCOFFSET4CSPN, C.ADDI4SPN), 16-bit encodings + +Capability Mode Mnemonic:: +`c.cincoffset4cspn rd', uimm` + +Capability Mode Expansion:: +`cincoffset rd', csp, uimm` + +Legacy Mode Mnemonic:: +`c.addi4spn rd', uimm` + +Legacy Mode Expansion:: +`add rd', sp, uimm` + +Encoding:: +include::wavedrom/c-ciw.adoc[] + +Capability Mode Description:: + +Add a zero-extended non-zero immediate, scaled by 4, to the stack pointer, `csp`, and writes the result to `rd'`. This instruction is used to generate pointers to stack-allocated variables. Clear the tag if the resulting capability is unrepresentable or `csp` is sealed. + +Legacy Mode Description:: + +Add a zero-extended non-zero immediate, scaled by 4, to the stack pointer, `sp`, and writes the result to `rd'`. This instruction is used to generate pointers to stack-allocated variables. + +Prerequisites for C.CINCOFFSET4CSPN:: +{c_cheri_base_ext_names} + +Prerequisites for C.ADDI4SPN:: +{c_cheri_legacy_ext_names} + +Capability Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/amo_32bit.adoc b/src/insns/amo_32bit.adoc new file mode 100644 index 00000000..999c3bc6 --- /dev/null +++ b/src/insns/amo_32bit.adoc @@ -0,0 +1,67 @@ +<<< +//[#insns-amo-32bit,reftext="Atomic (CAMO.W, CAMO.D, AMO.W, AMO.D), 32-bit encodings"] + + +[#CAMOOPW,reftext="CAMO.W"] +==== CAMO.W + +See <>. + +[#CAMOOPD,reftext="CAMO.D"] +==== CAMO.D + +See <>. + +[#AMOOPW,reftext="AMO.W"] +==== AMO.W + +See <>. + +<<< + +[#AMOOPD,reftext="AMO.D"] +==== CAMO.W + +Synopsis:: +Atomic Operations (CAMO.W, CAMO.D, AMO.W, AMO.D), 32-bit encodings + +Capability Mode Mnemonics (RV64):: +`camo.[w|d], offset(cs1)` + +Capability Mode Mnemonics (RV32):: +`camo.w, offset(cs1)` + +Legacy Mode Mnemonics (RV64):: +`amo.[w|d], offset(rs1)` + +Legacy Mode Mnemonics (RV32):: +`amo.w, offset(rs1)` + +Encoding:: +include::wavedrom/amo.adoc[] + +Capability Mode Description:: +Standard atomic instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Standard atomic instructions, authorised by the capability in <>. + +include::atomic_exceptions.adoc[] + +Prerequisites for CAMO.W, CAMO.D:: +{cheri_base_ext_name} + +Prerequisites for AMO.W, AMO.D:: +{cheri_legacy_ext_name} + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/amoswap_32bit_cap.adoc b/src/insns/amoswap_32bit_cap.adoc new file mode 100644 index 00000000..24ee122b --- /dev/null +++ b/src/insns/amoswap_32bit_cap.adoc @@ -0,0 +1,47 @@ +<<< + +[#AMOSWAP_C,reftext="AMOSWAP.C"] +==== AMOSWAP.C + +See <>. + +[#CAMOSWAP_C,reftext="CAMOSWAP.C"] +==== CAMOSWAP.C + +NOTE: The RV64 encoding is intended to also allocate the encoding for AMOSWAP.Q for RV128. + +Synopsis:: +Atomic Operations (CAMOSWAP.C, AMOSWAP.C), 32-bit encodings + +include::xlen_variable_warning.adoc[] + +Capability Mode Mnemonics:: +`camoswap.c, offset(cs1)` + +Legacy Mode Mnemonics:: +`amoswap.c, offset(rs1)` + +Encoding:: +include::wavedrom/amoswap_cap.adoc[] + +Capability Mode Description:: +Atomic swap of capability type, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Atomic swap of capability type, authorised by the capability in <>. + +:cap_atomic: + +include::atomic_exceptions.adoc[] + +Prerequisites for CAMOSWAP.C:: +{cheri_base_ext_name} + +Prerequisites for AMOSWAP.C:: +{cheri_legacy_ext_name} + +Operation:: ++ +-- +TODO +-- diff --git a/src/insns/atomic_exceptions.adoc b/src/insns/atomic_exceptions.adoc new file mode 100644 index 00000000..2a3d8862 --- /dev/null +++ b/src/insns/atomic_exceptions.adoc @@ -0,0 +1,33 @@ +Permissions:: +ifdef::cap_atomic[] +Requires the authorising capability to be tagged and not sealed. ++ +Requires <> and <> in the authorising capability. ++ +If <> is not granted then store the memory tag as zero, and load `cd.tag` as zero. ++ +(_This tag clearing behaviour may become a data dependent exception in future._) +endif::[] +ifndef::cap_atomic[] +Requires <> and <> in the authorising capability. +endif::[] ++ +Requires all bytes of the access to be in capability bounds. + +Exceptions:: +All misaligned atomics cause a store/AMO address misaligned exception to allow software emulation (if the Zam extension is supported, see cite:[riscv-unpriv-spec]), otherwise they take a store/AMO access fault exception. ++ +When these instructions cause CHERI exceptions, _CHERI data fault_ +is reported in the TYPE field and the following codes may be +reported in the CAUSE field of <> or <>: + +[width="50%",options=header,cols="2,^1",align=center] +|============================================================================== +| CAUSE | Reason +| Tag violation | Authority capability tag set to 0 +| Seal violation | Authority capability is sealed +| Permission violation | Authority capability does not grant <> or <> +| Length violation | At least one byte accessed is outside the authority capability bounds +|============================================================================== + +:!cap_atomic: \ No newline at end of file diff --git a/src/insns/auipcc_32bit.adoc b/src/insns/auipcc_32bit.adoc new file mode 100644 index 00000000..df3eb60b --- /dev/null +++ b/src/insns/auipcc_32bit.adoc @@ -0,0 +1,47 @@ +<<< + +[#AUIPC,reftext="AUIPC"] +==== AUIPC + +See <> + +[#AUIPCC,reftext="AUIPCC"] +==== AUIPCC + +Synopsis:: +Add upper immediate to *pc*/<> + +Capability Mode Mnemonic:: +`auipcc cd, imm` + +Legacy Mode Mnemonic:: +`auipc rd, imm` + +Encoding:: +include::wavedrom/rv64_lui-auipc.adoc[] + +Capability Mode Description:: +Form a 32-bit offset from the 20-bit immediate filling the lowest 12 bits with +zeros. Increment the address of the <> instruction's <> by the +32-bit offset, then write the output capability to `cd`. The tag bit of the +output capability is 0 if the incremented address is outside the <>'s +representable region. + +Legacy Mode Description:: +Form a 32-bit offset from the immediate, filling in the lowest 12 bits with +zeros, adds this offset to the address of the AUIPC instruction, then places +the result in register `rd`. + +include::pcrel_debug_warning.adoc[] + +Prerequisites for AUIPCC:: +{cheri_base_ext_name} + +Prerequisites for AUIPC:: +{cheri_legacy_ext_name} + +Operation for AUIPCC:: ++ +-- +TODO +-- diff --git a/src/insns/candperm_32bit.adoc b/src/insns/candperm_32bit.adoc new file mode 100644 index 00000000..5cc0e716 --- /dev/null +++ b/src/insns/candperm_32bit.adoc @@ -0,0 +1,49 @@ +<<< + +[#CANDPERM,reftext="CANDPERM"] +==== CANDPERM + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The implementation of this instruction changes +because the permission fields are encoded differently in the new +capability format. +endif::[] + +include::new_encoding_note.adoc[] + +Synopsis:: +Mask capability permissions + +Mnemonics:: +`candperm cd, cs1, rs2` + +Encoding:: +include::wavedrom/candperm.adoc[] + +Description:: +Converts the AP and SDP fields of capability `cs1` into a bit field; one bit +per permission as shown below. Then calculate the bitwise AND of the bit field +with the mask `rs2` . Set the AP and SDP fields of `cs1` as indicated in the +resulting bit field -- the capability grants a permission if the corresponding +bit is set in the bit field -- and write the output capability to `cd` . The +output capability has its tag set to 0 if `cs1` is sealed. + +include::../img/candperms_bit_field.edn[] + +NOTE: The AP field is not able to encode all combinations of permissions when +XLENMAX=32. If permissions that cannot be encoded are indicated, CANDPERM +outputs a capability with all architectural permissions cleared. + +CAUTION: TODO: this may not be correct - we should work through the + different combinations which are possible for removing a permission + for RV32, where it is restricted, and decide what to do in each case + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO: Sail does not have the new encoding of the permissions field. +-- + diff --git a/src/insns/cbo.clean.adoc b/src/insns/cbo.clean.adoc new file mode 100644 index 00000000..7b97acb0 --- /dev/null +++ b/src/insns/cbo.clean.adoc @@ -0,0 +1,56 @@ +<<< + +[#CBO_CLEAN,reftext="CBO.CLEAN"] +==== CBO.CLEAN + +See <>. + +[#CBO_CLEAN_CAP,reftext="CBO.CLEAN.CAP"] +==== CBO.CLEAN.CAP + +Synopsis:: +Perform a clean operation on a cache block + +Capability Mode Mnemonic:: +`cbo.clean.cap 0(cs1)` + +Legacy Mode Mnemonic:: +`cbo.clean 0(rs1)` + +Encoding:: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','MISC-MEM=0001111'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5','CBO=0000'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','CBO=010'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12','cap: CBO.CLEAN.CAP=00.001', 'leg: CBO.CLEAN=00.001'], type: 3}, +]} +.... + +Capability Mode Description:: +A CBO.CLEAN.CAP instruction performs a clean operation on the cache block +whose effective address is the base address specified in `cs1`. The authorising +capability for this operation is `cs1`. + +Legacy Mode Description:: +A CBO.CLEAN instruction performs a clean operation on the cache block whose +effective address is the base address specified in `rs1`. The authorising +capability for this operation is <>. + +:cbo_clean_flush: +include::cbo_exceptions.adoc[] + +Prerequisites for CBO.CLEAN.CAP:: +Zicbom, {cheri_base_ext_name} + +Prerequisites for CBO.CLEAN:: +Zicbom, {cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + diff --git a/src/insns/cbo.flush.adoc b/src/insns/cbo.flush.adoc new file mode 100644 index 00000000..23edf3b7 --- /dev/null +++ b/src/insns/cbo.flush.adoc @@ -0,0 +1,55 @@ +<<< + +[#CBO_FLUSH,reftext="CBO.FLUSH"] +==== CBO.FLUSH + +See <>. + +[#CBO_FLUSH_CAP,reftext="CBO.FLUSH.CAP"] +==== CBO.FLUSH.CAP + +Synopsis:: +Perform a flush operation on a cache block + +Capability Mode Mnemonic:: +`cbo.flush.cap 0(cs1)` + +Legacy Mode Mnemonic:: +`cbo.flush 0(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','MISC-MEM=0001111'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5','CBO=0000'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','CBO=010'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12','cap: CBO.FLUSH.CAP=00.0010', 'leg: CBO.FLUSH=00.0010'], type: 3}, +]} +.... + +Capability Mode Description:: +A CBO.FLUSH.CAP instruction performs a flush operation on the cache block +whose effective address is the base address specified in `cs1`. The authorising +capability for this operation is `cs1`. + +Legacy Mode Description:: +A CBO.FLUSH instruction performs a flush operation on the cache block whose +effective address is the base address specified in `rs1`. The authorising +capability for this operation is <>. + +:cbo_clean_flush: +include::cbo_exceptions.adoc[] + +Prerequisites for CBO.FLUSH.CAP:: +Zicbom, {cheri_base_ext_name} + +Prerequisites for CBO.FLUSH:: +Zicbom, {cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/cbo.inval.adoc b/src/insns/cbo.inval.adoc new file mode 100644 index 00000000..bc8ce6cc --- /dev/null +++ b/src/insns/cbo.inval.adoc @@ -0,0 +1,55 @@ +<<< + +[#CBO_INVAL,reftext="CBO.INVAL"] +==== CBO.INVAL + +See <>. + +[#CBO_INVAL_CAP,reftext="CBO.INVAL.CAP"] +==== CBO.INVAL.CAP + +Synopsis:: +Perform an invalidate operation on a cache block + +Capability Mode Mnemonic:: +`cbo.inval.cap 0(cs1)` + +Legacy Mode Mnemonic:: +`cbo.inval 0(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','MISC-MEM=0001111'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5','CBO=0000'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','CBO=010'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12','cap: CBO.INVAL.CAP=00.0000', 'leg: CBO.INVAL=00.0000'], type: 3}, +]} +.... + +Capability Mode Description:: +A CBO.INVAL.CAP instruction performs an invalidate operation on the cache block +whose effective address is the base address specified in `cs1`. The authorising +capability for this operation is `cs1`. + +Legacy Mode description:: +A CBO.INVAL instruction performs an invalidate operation on the cache block +whose effective address is the base address specified in `rs1`. The +authorising capability for this operation in <>. + +:cbo_inval: +include::cbo_exceptions.adoc[] + +Prerequisites for CBO.INVAL.CAP:: +Zicbom, {cheri_base_ext_name} + +Prerequisites for CBO.INVAL:: +Zicbom, {cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/cbo.zero.adoc b/src/insns/cbo.zero.adoc new file mode 100644 index 00000000..9d3a5e1b --- /dev/null +++ b/src/insns/cbo.zero.adoc @@ -0,0 +1,60 @@ +<<< + +[#CBO_ZERO,reftext="CBO.ZERO"] +==== CBO.ZERO + +See <>. + +[#CBO_ZERO_CAP,reftext="CBO.ZERO.CAP"] +==== CBO.ZERO.CAP + +Synopsis:: +Store zeros to the full set of bytes corresponding to a cache block + +Capability Mode Mnemonic:: +`cbo.zero.cap 0(cs1)` + +Legacy Mode Mnemonic:: +`cbo.zero 0(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','MISC-MEM=0001111'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5','CBO=0000'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','CBO=010'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12','cap: CBO.ZERO.CAP=00.0100', 'leg: CBO.ZERO=00.0100'], type: 3}, +]} +.... + +Capability Mode Description:: +A `cbo.zero.cap` instruction performs stores of zeros to the full set of bytes +corresponding to the cache block whose effective address is the base address +specified in `cs1`. An implementation may or may not update the entire set of +bytes atomically although each individual write must atomically clear the tag +bit of the corresponding aligned CLEN-bit location. The authorising capability +for this operation is `cs1`. + +Legacy Mode Description:: +A `cbo.zero` instruction performs stores of zeros to the full set of bytes +corresponding to the cache block whose effective address is the base address +specified in `cs1`. An implementation may or may not update the entire set of +bytes atomically although each individual write must atomically clear the tag +bit of the corresponding aligned CLEN-bit location. The authorising capability +for this operation is <>. + +include::store_exceptions.adoc[] + +Prerequisites for CBO.ZERO.CAP:: +Zicboz, {cheri_base_ext_name} + +Prerequisites for CBO.ZERO:: +Zicboz, {cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/cbo_exceptions.adoc b/src/insns/cbo_exceptions.adoc new file mode 100644 index 00000000..804625c5 --- /dev/null +++ b/src/insns/cbo_exceptions.adoc @@ -0,0 +1,51 @@ +Exceptions:: +CHERI fault exceptions when the authorising capability fails one of the checks +listed below; in this case, _CHERI data fault_ is reported in the <> or +<> TYPE field and the corresponding code is written to CAUSE. ++ +ifdef::cbo_inval[] +The CBIE bit in <> and <> indicates whether +CBO.INVAL.CAP and CBO.INVAL perform cache block flushes instead of +invalidations for less privileged modes. The instruction checks shown in the +table below remain unchanged regardless of the value of CBIE and the privilege +mode. +endif::[] + +[%autowidth,options=header,align=center] +|============================================================================== +| CAUSE | Reason +| Tag violation | The tag set to 0 +| Seal violation | It is sealed + +ifdef::cbo_clean_flush[] +| Permission violation | It does not grant <> and <> +| Length violation | At least one byte accessed is within the bounds +endif::cbo_clean_flush[] + +ifdef::cbo_inval[] +| Permission violation | It does not grant <>, <> or <> +| Length violation | At least one byte accessed is outside the bounds +endif::[] + +ifdef::prefetch_i[] +| Permission violation | It does not grant <> +| Length violation | At least one byte accessed is within the bounds +endif::[] + +ifdef::prefetch_r[] +| Permission violation | It does not grant <> +| Length violation | At least one byte accessed is within the bounds +endif::[] + +ifdef::prefetch_w[] +| Permission violation | It does not grant <> +| Length violation | At least one byte accessed is within the bounds +endif::[] +|============================================================================== + + +:!cbo_clean_flush: +:!cbo_inval: +:!prefetch_r: +:!prefetch_w: +:!prefetch_i: diff --git a/src/insns/cbuildcap_32bit.adoc b/src/insns/cbuildcap_32bit.adoc new file mode 100644 index 00000000..23c3e924 --- /dev/null +++ b/src/insns/cbuildcap_32bit.adoc @@ -0,0 +1,48 @@ +<<< + +[#CBUILDCAP,reftext="CBUILDCAP"] +==== CBUILDCAP + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability build + +Mnemonic:: +`cbuildcap cd, cs1, cs2` + +Encoding:: +include::wavedrom/cbuildcap.adoc[] + +Description:: +Copy `cs2` to `cd` and set the tag to 1 if `cs1.tag` is set, `cs1` is not +sealed, `cs1` 's permissions and bounds are equal or a superset of `cs2` 's, +`cs2` 's bounds are not malformed (see +xref:section_cap_malformed[xrefstyle=short]), and all reserved bits in `cs2` 's +metadata are 0. <> is typically used alongside <> to build +capabilities from integer values. + +Prerequisites:: +{cheri_base_ext_name} + +Simplified Operation TODO #not debugged much easier to read than the existing SAIL# :: +[source,SAIL,subs="verbatim,quotes"] +-- +let cs1_val = if unsigned(cs1) == 0 then DDC else C(cs1); +let cs2_val = C(cs2) [with tag=1]; +//isCapSubset includes derivability checks on both operands +let subset = isCapSubset(cs1_val, cs2_val); +//Clear cd.tag if cs1 isn't a subset of cs1, or if +//cs1 is untagged or sealed, or if either is underivable +C(cd) = clearTagIf(cs2_val, not(subset) | + not(cs1_val.tag) | + isCapSealed(cs1_val)); +RETIRE_SUCCESS +-- + +Operation:: ++ +-- +TODO: Original Sail looks at otype field, etc that don't exist +-- + diff --git a/src/insns/cclear_32bit.adoc b/src/insns/cclear_32bit.adoc new file mode 100644 index 00000000..edbc57e7 --- /dev/null +++ b/src/insns/cclear_32bit.adoc @@ -0,0 +1,24 @@ +<<< +[#insns-cclear-32bit,reftext="Capability sealing (CClear), 32-bit encoding"] +==== CClear + +Synopsis:: +Fast register clear (CClear), 32-bit encoding + +Mnemonics:: +`cclear q(uarter), m(ask)` + +Encoding:: +include::wavedrom/cclear.adoc[] + +Description:: +Capability registers 8 × q + i are each set to the <> (0) if mask[i]=1, with the exception that the mask[0] refers to <> when q is 0, rather than `c0`. + +Prerequisites:: +#Not available# + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/cgetbase_32bit.adoc b/src/insns/cgetbase_32bit.adoc new file mode 100644 index 00000000..56ce33e0 --- /dev/null +++ b/src/insns/cgetbase_32bit.adoc @@ -0,0 +1,30 @@ +<<< + +[#CGETBASE,reftext="CGETBASE"] +==== CGETBASE + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability get base address + +Mnemonic:: +`cgetbase rd, cs1` + +Encoding:: +include::wavedrom/cgetbase.adoc[] + +Description:: +Decode the base integer address from `cs1` 's bounds and write the result to +`rd`. It is not required that the input capability `cs1` has its tag set to 1. +<> outputs 0 if `cs1` 's bounds are malformed (see +xref:section_cap_malformed[xrefstyle=short]). + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: TODO #need to check that it returns 0 if malformed# ++ +-- +TODO +-- diff --git a/src/insns/cgethigh_32bit.adoc b/src/insns/cgethigh_32bit.adoc new file mode 100644 index 00000000..d47de6e1 --- /dev/null +++ b/src/insns/cgethigh_32bit.adoc @@ -0,0 +1,28 @@ +<<< + +[#CGETHIGH,reftext="CGETHIGH"] +==== CGETHIGH + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability get metadata + +Mnemonic:: +`cgethigh rd, cs1` + +Encoding:: +include::wavedrom/cgethigh.adoc[] + +Description:: +Copy the metadata (bits [CLEN-1:XLENMAX]) of capability `cs1` into `rd`. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: TODO #this is correct but capToMemBits is redundant, as it's now XORed with zero (null-cap)# ++ +-- +TODO +-- + diff --git a/src/insns/cgetlen_32bit.adoc b/src/insns/cgetlen_32bit.adoc new file mode 100644 index 00000000..5ddf29d8 --- /dev/null +++ b/src/insns/cgetlen_32bit.adoc @@ -0,0 +1,31 @@ +<<< + +[#CGETLEN,reftext="CGETLEN"] +==== CGETLEN + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability get length + +Mnemonic:: +`cgetlen rd, cs1` + +Encoding:: +include::wavedrom/cgetlen.adoc[] + +Description:: +Calculate the length of `cs1` 's bounds and write the result in `rd`. The length +is defined as the difference between the decoded bounds' top and base addresses +i.e. `top - base`. It is not required that the input capability `cs1` has its +tag set to 1. <> outputs 0 if `cs1` 's bounds are malformed (see +xref:section_cap_malformed[xrefstyle=short]). + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: TODO #need to check that it returns 0 if malformed# ++ +-- +TODO +-- diff --git a/src/insns/cgetperm_32bit.adoc b/src/insns/cgetperm_32bit.adoc new file mode 100644 index 00000000..cddbf7c5 --- /dev/null +++ b/src/insns/cgetperm_32bit.adoc @@ -0,0 +1,32 @@ +<<< + +[#CGETPERM,reftext="CGETPERM"] +==== CGETPERM + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability get permissions + +Mnemonic:: +`cgetperm rd, cs1` + +Encoding:: +include::wavedrom/cgetperm.adoc[] + +Description:: +Converts the AP and SDP fields of capability `cs1` into a bit field; one bit +per permission, as shown below, and write the result to `rd`. A bit set to 1 +in the bit field indicates that `cs1` grants the corresponding permission. + +include::../img/candperms_bit_field.edn[] + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO: The encoding of permissions changed. +-- + diff --git a/src/insns/cgettag_32bit.adoc b/src/insns/cgettag_32bit.adoc new file mode 100644 index 00000000..deafca63 --- /dev/null +++ b/src/insns/cgettag_32bit.adoc @@ -0,0 +1,26 @@ +<<< + +[#CGETTAG,reftext="CGETTAG"] +==== CGETTAG +include::new_encoding_note.adoc[] +Synopsis:: +Capability get tag + +Mnemonic:: +`cgettag rd, cs1` + +Encoding:: +include::wavedrom/cgettag.adoc[] + +Description:: +Zero extend the value of `cs1.tag` and write the result to `rd`. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/cincoffset_32bit.adoc b/src/insns/cincoffset_32bit.adoc new file mode 100644 index 00000000..47de686d --- /dev/null +++ b/src/insns/cincoffset_32bit.adoc @@ -0,0 +1,55 @@ +<<< + +[#CINCOFFSETIMM,reftext="CINCOFFSETIMM"] +==== CINCOFFSETIMM + +See <>. + +[#CINCOFFSET,reftext="CINCOFFSET"] +==== CINCOFFSET + +include::new_encoding_note.adoc[] + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* the immediate format has changed +endif::[] + +Synopsis:: +Capability pointer increment + +Mnemonic:: +`cincoffset cd, cs1, rs2` + +`cincoffsetimm cd, cs1, imm` + +Encoding:: +include::wavedrom/cincoffset.adoc[] + +NOTE: <> with `rs2=x0` is decoded as <> instead, the key +difference being that tagged and sealed capabilities do not have their tag +cleared by <>. + +Description:: +Increment the address field of the capability `cs1` and write the result to +`cd` . The tag bit of the output capability is 0 if `cs1` did not have its tag +set to 1, the incremented address is outside `cs1` 's representable region or +`cs1` is sealed. + +For <>, the address is incremented by the value in +`rs2` . + +For <>, the address is incremented by the immediate value +`imm`. + +Prerequisites:: +{cheri_base_ext_name} + +Operation (CINCOFFSET):: ++ +-- +TODO +-- + +Operation (CINCOFFSETIMM):: ++ +-- +TODO +-- + diff --git a/src/insns/cj_j_16bit.adoc b/src/insns/cj_j_16bit.adoc new file mode 100644 index 00000000..5e702241 --- /dev/null +++ b/src/insns/cj_j_16bit.adoc @@ -0,0 +1,46 @@ +<<< +//[#insns-cj_j-16bit,reftext="Conditional branches (C.CJ,C.J), 16-bit encodings"] + +[#C_J,reftext="C.J"] +==== C.J + +See <>. + +[#C_CJ,reftext="C.CJ"] +==== C.CJ + +Synopsis:: +Register based jumps without link, 16-bit encodings + +Capability Mode Mnemonic:: +`c.cj offset` + +Capability Mode Expansion:: +`cjal c0, offset` + +Legacy Mode Mnemonic:: +`c.j offset` + +Legacy Mode Expansion:: +`jal x0, offset` + +Encoding:: +include::wavedrom/c-cj-format-ls.adoc[] + +Description:: +Set the next PC following the standard `jal` definition. + Check a minimum length instruction is in <> bounds at the target PC, take a CHERI Length Violation exception on error. + *There is no difference in Capability Mode or Legacy Mode execution for this instruction.* + +Exceptions:: +CHERI Length Violation + +Prerequisites for C.CJ:: +{c_cheri_base_ext_names} + +Prerequisites for C.J:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <> + diff --git a/src/insns/cjal_jal_16bit.adoc b/src/insns/cjal_jal_16bit.adoc new file mode 100644 index 00000000..710068c0 --- /dev/null +++ b/src/insns/cjal_jal_16bit.adoc @@ -0,0 +1,40 @@ +<<< +//[#insns-cjal_jal-16bit,reftext="Conditional branches (C.CJAL,C.JAL), 16-bit encodings"] + +[#C_JAL,reftext="C.JAL"] +==== C.JAL + +See <>. + +[#C_CJAL,reftext="C.CJAL"] +==== C.CJAL + +Synopsis:: +Register based jumps with link, 16-bit encodings + +Capability Mode Mnemonic (RV32):: +`c.cjal c1, offset` + +Capability Mode Expansion (RV32):: +`cjal c1, offset` + +Legacy Mode Mnemonic (RV32):: +`c.jal x1, offset` + +Legacy Mode Expansion (RV32):: +`jal x1, offset` + +Encoding (RV32):: +include::wavedrom/c-cjal-format-ls.adoc[] + +include::cjal_jal_common.adoc[] + +Prerequisites for C.CJAL:: +{c_cheri_base_ext_names} + +Prerequisites for C.JAL:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <> + diff --git a/src/insns/cjal_jal_32bit.adoc b/src/insns/cjal_jal_32bit.adoc new file mode 100644 index 00000000..e3bed1f2 --- /dev/null +++ b/src/insns/cjal_jal_32bit.adoc @@ -0,0 +1,58 @@ +<<< +//[#insns-cjal_jal-32bit,reftext="Jumps (CJAL, JAL), 32-bit encodings"] + +[#CJAL,reftext="CJAL"] +==== CJAL + +See <> + +[#JAL,reftext="JAL"] +==== CJAL, JAL + +Synopsis:: +Jump and link + +Capability Mode Mnemonic:: +`cjal cd, offset` + +Legacy Mode Mnemonic:: +`jal rd, offset` + +Encoding:: +include::wavedrom/ct-unconditional.adoc[] + +Capability Mode Description:: +CJAL's immediate encodes a signed offset in multiple of 2 bytes. The <> is +incremented by the sign-extended offset to form the jump target capability. The +target capability is written to <>. The <> of the next instruction +following the jump (<> + 4) is sealed and written to `cd`. + +Legacy Mode Description:: +JAL's immediate encodes a signed offset in multiple of 2 bytes. The +sign-extended offset is added to the <>'s address to form the target +address which is written to the <>'s address field. The address of the +instruction following the jump (<> + 4) is written to `rd`. + +Exceptions:: +CHERI fault exceptions occur when a minimum length instruction at the target +address is not within the bounds of the <>. In this case, _CHERI jump or +branch fault_ is reported in the TYPE field and Length Violation is reported in +the CAUSE field of <> or <>. + +Prerequisites for CJAL:: +{cheri_base_ext_name} + +Prerequisites for JAL:: +{cheri_legacy_ext_name} + +CJAL Operation:: ++ +-- +TODO +-- + +JAL Operation TODO #where's the target check?# :: ++ +-- +TODO +-- diff --git a/src/insns/cjal_jal_common.adoc b/src/insns/cjal_jal_common.adoc new file mode 100644 index 00000000..43ec6fe2 --- /dev/null +++ b/src/insns/cjal_jal_common.adoc @@ -0,0 +1,8 @@ +Capability Mode Description:: +Link the next linear <> to `cd` and seal. Jump to <>.address+offset. + Check a minimum length instruction is in <> bounds at the target PC, take a CHERI Length Violation exception on error. + +Legacy Mode Description:: +Set the next PC and link to `rd` according to the standard <> definition. + Check a minimum length instruction is in <> bounds at the target PC, take a CHERI Length Violation exception on error. + diff --git a/src/insns/cjalr_jalr_16bit.adoc b/src/insns/cjalr_jalr_16bit.adoc new file mode 100644 index 00000000..601efe3e --- /dev/null +++ b/src/insns/cjalr_jalr_16bit.adoc @@ -0,0 +1,40 @@ +<<< +//[#insns-cjalr_jalr-16bit,reftext="Conditional branches (C.CJALR, C.JALR), 16-bit encodings"] + +[#C_JALR,reftext="C.JALR"] +==== C.JALR + +See <>. + +[#C_CJALR,reftext="C.CJALR"] +==== C.CJALR + +Synopsis:: +Register based jumps with link, 16-bit encodings + +Capability Mode Mnemonic:: +`c.cjalr c1, cs1` + +Capability Mode Expansion:: +`cjalr c1, 0(cs1)` + +Legacy Mode Mnemonic:: +`c.jalr x1, rs1` + +Legacy Mode Expansion:: +`jalr x1, 0(rs1)` + +Encoding:: +include::wavedrom/c-cjalr-format-ls.adoc[] + +include::cjalr_jalr_common.adoc[] + +Prerequisites C.CJALR:: +{c_cheri_base_ext_names} + +Prerequisites C.JALR:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <> + diff --git a/src/insns/cjalr_jalr_32bit.adoc b/src/insns/cjalr_jalr_32bit.adoc new file mode 100644 index 00000000..19624b7f --- /dev/null +++ b/src/insns/cjalr_jalr_32bit.adoc @@ -0,0 +1,75 @@ +<<< + +[#CJALR,reftext="CJALR"] +==== CJALR + +See <> + +[#JALR,reftext="JALR"] +==== CJAL, JALR + +Synopsis:: +Jump and link register + +Capability Mode Mnemonic:: +`cjalr cd, cs1, offset` + +Legacy Mode Mnemonic:: +`jalr rd, rs1, offset` + +Encoding:: +include::wavedrom/ct-unconditional-2.adoc[] + +Capability Mode Description:: +CJALR allows unconditional, indirect jumps to a target capability. The +target capability is obtained by unsealing `cs1` and incrementing its address by the +sign-extended 12-bit immediate, and then setting the least-significant bit of the +result to zero. The target capability may have +xref:section_invalid_addr_conv[xrefstyle=short] +performed and is then installed in <>. The <> +of the next instruction following the jump (<> + 4) is sealed and written +to `cd`. + +Legacy Mode Description:: +JALR allows unconditional, indirect jumps to a target address. The target +address is obtained by adding the sign-extended 12-bit immediate to `rs1`, then +setting the least-significant bit of the result to zero. The target address +is installed in the address field of the <> which may require +xref:section_invalid_addr_conv[xrefstyle=short]. +The address of the +instruction following the jump (<> + 4) is written to `rd`. + +Exceptions:: +When these instructions cause CHERI exceptions, _CHERI jump or branch fault_ +is reported in the TYPE field and the following codes may be +reported in the CAUSE field of <> or <>: + +[%autowidth,options=header,align=center] +|============================================================================== +| CAUSE | JALR | CJALR | Reason +| Tag violation | | ✔ | `cs1` has tag set to 0 +| Seal violation | | ✔ | `cs1` is sealed and the immediate is not 0 +| Permission violation | | ✔ | `cs1` does not grant <> +| Length violation | ✔ | ✔ | Minimum length instruction is not within the target capability's bounds +|============================================================================== + +include::pcrel_debug_warning.adoc[] + +Prerequisites CJALR:: +{cheri_base_ext_name} + +Prerequisites JALR:: +{cheri_legacy_ext_name} + +CJALR Operation:: ++ +-- +TBD +-- + +JALR Operation:: ++ +-- +TBD +-- + diff --git a/src/insns/cjalr_jalr_common.adoc b/src/insns/cjalr_jalr_common.adoc new file mode 100644 index 00000000..d2a19981 --- /dev/null +++ b/src/insns/cjalr_jalr_common.adoc @@ -0,0 +1,7 @@ + +Capability Mode Description:: +Link the next linear <> to `cd` and seal. Jump to `cs1.address+offset`. <> metadata is copied from `cs1`, and is unsealed if necessary. Note that execution has several exception checks. + +Legacy Mode Description:: +Set the next PC and link to `rd` according to the standard <> definition. + Check a minimum length instruction is in <> bounds at the target PC, take a CHERI Length Violation exception on error. diff --git a/src/insns/cjr_jr_16bit.adoc b/src/insns/cjr_jr_16bit.adoc new file mode 100644 index 00000000..6f98eeb8 --- /dev/null +++ b/src/insns/cjr_jr_16bit.adoc @@ -0,0 +1,50 @@ +<<< +//[#insns-cjr_jr-16bit,reftext="Conditional branches (C.CJR, C.JR), 16-bit encodings"] + +[#C_CJR,reftext="C.CJR"] +==== C.CJR + +See <>. + +[#C_JR,reftext="C.JR"] +==== C.JR + +Synopsis:: +Register based jumps without link, 16-bit encodings + +Capability Mode Mnemonic:: +`c.cjr cs1` + +Capability Mode Expansion:: +`cjalr c0, 0(cs1)` + +Legacy Mode Mnemonic:: +`c.jr rs1` + +Legacy Mode Expansion:: +`jalr x0, 0(rs1)` + +Encoding:: +include::wavedrom/c-cr-format-ls.adoc[] + +Capability Mode Description:: +Jump to `cs1.address+offset`. <> metadata is copied from `cs1`, and is unsealed if necessary. Note that execution has several exception checks. + +Legacy Mode Description:: +Set the next PC according to the standard `jalr` definition. + Check a minimum length instruction is in <> bounds at the target PC, take a CHERI Length Violation exception on error. + +Exceptions:: + See <>, <> + +include::pcrel_debug_warning.adoc[] + +Prerequisites for C.CJALR:: +{c_cheri_base_ext_names} + +Prerequisites for C.JALR:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <> + diff --git a/src/insns/cmove_32bit.adoc b/src/insns/cmove_32bit.adoc new file mode 100644 index 00000000..e9efcd42 --- /dev/null +++ b/src/insns/cmove_32bit.adoc @@ -0,0 +1,31 @@ +<<< + +[#CMOVE,reftext="CMOVE"] +==== CMOVE + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability move + +Mnemonic:: +`cmove cd, cs1` + +Encoding:: +include::wavedrom/cmove.adoc[] + +NOTE: <> is encoded as <> with `rs2=x0`. + +Description:: +The contents of capability register `cs1` are written to capability register +`cd`. <> unconditionally moves the whole capability to `cd` . + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/cmove_cmv_16bit.adoc b/src/insns/cmove_cmv_16bit.adoc new file mode 100644 index 00000000..34247af1 --- /dev/null +++ b/src/insns/cmove_cmv_16bit.adoc @@ -0,0 +1,42 @@ +<<< +//[#insns-cmove-16bit,reftext="Capability move (C.MV, CMove), 16-bit encoding"] + +[#C_MV,reftext="C.MV"] +==== C.MV +See <>. + +[#C_CMOVE,reftext="C.CMOVE"] +==== C.CMOVE + +Synopsis:: +Capability move (C.MV, C.CMOVE), 16-bit encoding + +Capability Mode Mnemonic:: +c.cmove cd, cs2` + +Capability Mode Expansion:: +cmove cd, cs2` + +Legacy Mode Mnemonic:: +c.mv rd, rs2` + +Legacy Mode Expansion:: +add rd, x0, rs2` + +Encoding:: +include::wavedrom/c_mv.adoc[] + +Capability Mode Description:: +Capability register cd is replaced with the contents of cs1. + +Legacy Mode Description:: +Standard RISC-V C.MV instruction. + +Prerequisites C.CMOVE:: +{c_cheri_base_ext_names} + +Prerequisites C.MV:: +{c_cheri_legacy_ext_names} + +Capability Mode Operation (after expansion to 32-bit encodings):: + See <> diff --git a/src/insns/condbr_16bit.adoc b/src/insns/condbr_16bit.adoc new file mode 100644 index 00000000..48689631 --- /dev/null +++ b/src/insns/condbr_16bit.adoc @@ -0,0 +1,26 @@ +<<< +[#insns-conbr-16bit,reftext="Conditional branches (C.BEQZ, C.BNEZ), 16-bit encodings"] +==== C.BEQZ, C.BNEZ + +Synopsis:: +Conditional branches (C.BEQZ, C.BNEZ), 16-bit encodings + +Mnemonics:: +`c.beqz/c.bnez rs1', offset` + +Expansions:: +`beq/bne rs1′, x0, offset` + +Encoding:: +include::wavedrom/c-cb-format-ls.adoc[] + +include::condbr_common.adoc[] + +include::pcrel_debug_warning.adoc[] + +Prerequisites:: +C or Zca + +Operation (after expansion to 32-bit encodings):: + See <> + diff --git a/src/insns/condbr_32bit.adoc b/src/insns/condbr_32bit.adoc new file mode 100644 index 00000000..22d08079 --- /dev/null +++ b/src/insns/condbr_32bit.adoc @@ -0,0 +1,36 @@ +<<< +[#insns-conbr-32bit,reftext="Conditional branches (BEQ, BNE, BLT[U], BGE[U])"] +==== BEQ, BNE, BLT[U], BGE[U] + +Synopsis:: +Conditional branches (BEQ, BNE, BLT[U], BGE[U]) + +Mnemonics:: +`beq rs1, rs2, imm` + +`bne rs1, rs2, imm` + +`blt rs1, rs2, imm` + +`bge rs1, rs2, imm` + +`bltu rs1, rs2, imm` + +`bgeu rs1, rs2, imm` + +Encoding:: +include::wavedrom/ct-conditional.adoc[] + +Description:: +Compare two integer registers `rs1` and `rs2` according to the indicated opcode +as described in cite:[riscv-unpriv-spec]. The 12-bit immediate encodes signed +offsets in multiples of 2 bytes. The offset is sign-extended and added to the +address of the branch instruction to give the target address. Then the target +address is written into the address field of <>. + +include::condbr_common.adoc[] + +include::pcrel_debug_warning.adoc[] + +ERROR: #TODO: Sail doesn't have target exceptions - wrong code included?# + +Operation:: ++ +-- +TODO +-- diff --git a/src/insns/condbr_common.adoc b/src/insns/condbr_common.adoc new file mode 100644 index 00000000..a8df852d --- /dev/null +++ b/src/insns/condbr_common.adoc @@ -0,0 +1,5 @@ +Exceptions:: +When the target address is not within the <>'s bounds, and the branch is taken, +a _CHERI jump or +branch fault_ is reported in the TYPE field and Length Violation is reported in +the CAUSE field of <> or <>: diff --git a/src/insns/cram_32bit.adoc b/src/insns/cram_32bit.adoc new file mode 100644 index 00000000..c9ed212f --- /dev/null +++ b/src/insns/cram_32bit.adoc @@ -0,0 +1,28 @@ +<<< + +[#CRAM,reftext="CRAM"] +==== CRAM + +Synopsis:: +Get Capability Representable Alignment Mask (CRAM) + +Mnemonic:: +`cram rd, rs1` + +Encoding:: +include::wavedrom/cram.adoc[] + +Description:: +Integer register `rd` is set to a mask that can be used to round addresses down +to a value that is sufficiently aligned to set exact bounds for the nearest +representable length of `rs1`. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/cseal_32bit.adoc b/src/insns/cseal_32bit.adoc new file mode 100644 index 00000000..1a5242a3 --- /dev/null +++ b/src/insns/cseal_32bit.adoc @@ -0,0 +1,29 @@ +<<< + +[#CSEAL,reftext="CSEAL"] +==== CSEAL + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability seal + +Mnemonics:: +`cseal cd, cs1` + +Encoding:: +include::wavedrom/cseal.adoc[] + +Description:: +Capability `cd` is written with the capability in `cs1` with its seal bit set +to 1. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO: The SAIL definition for CSEAL writes the OTYPE which does not exist anymore. +-- + diff --git a/src/insns/csetaddr_32bit.adoc b/src/insns/csetaddr_32bit.adoc new file mode 100644 index 00000000..2a39a4f5 --- /dev/null +++ b/src/insns/csetaddr_32bit.adoc @@ -0,0 +1,31 @@ +<<< + +[#CSETADDR,reftext="CSETADDR"] +==== CSETADDR + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability set address + +Mnemonic:: +`csetaddr cd, cs1, rs2` + +Encoding:: +include::wavedrom/csetaddr.adoc[] + +Description:: +Set the address field of capability `cs1` to `rs2` and write the output +capability to `cd`. The tag bit of the output capability is 0 if `cs1` did not +have its tag set to 1, `rs1` is outside the representable range of `cs1` +or if `cs1` is sealed. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/csetbounds_32bit.adoc b/src/insns/csetbounds_32bit.adoc new file mode 100644 index 00000000..51f77557 --- /dev/null +++ b/src/insns/csetbounds_32bit.adoc @@ -0,0 +1,59 @@ +<<< + +[#CSETBOUNDSIMM,reftext="CSETBOUNDSIMM"] +==== CSETBOUNDSIMM + +See <>. + +[#CSETBOUNDS,reftext="CSETBOUNDS"] +==== CSETBOUNDS + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* <> was CSETBOUNDSEXACT, +<> would have been CSETBOUNDSEXACTIMM if it had existed. +endif::[] + +include::new_encoding_note.adoc[] + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* the immediate format has changed +endif::[] + +Synopsis:: +Capability set bounds + +Mnemonic:: +`csetbounds cd, cs1, rs2` + +`csetboundsimm cd, cs1, uimm` + +Encoding:: +include::wavedrom/csetbounds_32bit.adoc[] + +Description:: +Capability register `cd` is set to capability register `cs1` with the base +address of its bounds replaced with the value of `cs1.address` and +the length of its bounds set to `rs2` (or `imm`). If the resulting capability +cannot be represented exactly then set `cd.tag` to 0. +In all cases, `cd.tag` is set to 0 if its bounds exceed `cs1` 's bounds, `cs1` 's +tag is 0 or `cs1` is sealed. ++ +<> uses the `s` bit to scale the immediate by 4 places ++ +`immediate = ZeroExtend(s ? uimm<<4 : uimm)` + +Prerequisites:: +{cheri_base_ext_name} + +TODO: #this is the CSetBoundsExact() function which will be renamed# + +Operation for CSETBOUNDS:: ++ +-- +TODO +-- + +Operation for CSETBOUNDSIMM:: ++ +-- +TODO +-- diff --git a/src/insns/csetboundsinexact_32bit.adoc b/src/insns/csetboundsinexact_32bit.adoc new file mode 100644 index 00000000..283305ed --- /dev/null +++ b/src/insns/csetboundsinexact_32bit.adoc @@ -0,0 +1,38 @@ +<<< + +[#CSETBOUNDSINEXACT,reftext="CSETBOUNDSINEXACT"] +==== CSETBOUNDSINEXACT + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This instruction was called CSETBOUNDS. +endif::[] + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability set bounds, rounding up if necessary + +Mnemonic:: +`csetboundsinexact cd, cs1, rs2` + +Encoding:: +include::wavedrom/csetboundsinexact_32bit.adoc[] + +Description:: +Capability register `cd` is set to capability register `cs1` with the base +address of its bounds replaced with the value of `cs1.address` field and +the length of its bounds set to `rs2`. The base is rounded down +and the length is rounded up by the smallest amount needed to form a representable +capability covering the requested bounds. In all cases, `cd.tag` is set to 0 +if its bounds exceed `cs1` 's bounds, `cs1` 's tag is 0 or `cs1` is sealed. + +Prerequisites:: +{cheri_base_ext_name} + +WARNING: TODO #this is the CSetBounds() function which will be renamed# + +Operation for CSETBOUNDSINEXACT:: ++ +-- +TODO +-- diff --git a/src/insns/csetequalexact_32bit.adoc b/src/insns/csetequalexact_32bit.adoc new file mode 100644 index 00000000..f60401bb --- /dev/null +++ b/src/insns/csetequalexact_32bit.adoc @@ -0,0 +1,29 @@ +<<< + +[#CSETEQUALEXACT,reftext="CSETEQUALEXACT"] +==== CSETEQUALEXACT + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability equals + +Mnemonics:: +`csetequalexact rd, cs1, cs2` + +Encoding:: +include::wavedrom/csetequalexact.adoc[] + +Description:: +`rd` is set to 1 if all bits (i.e. CLEN bits and the tag) of capabilities `cs1` +and `cs2` are equal, otherwise `rd` is set to 0. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/csethigh_32bit.adoc b/src/insns/csethigh_32bit.adoc new file mode 100644 index 00000000..24f511f8 --- /dev/null +++ b/src/insns/csethigh_32bit.adoc @@ -0,0 +1,29 @@ +<<< + +[#CSETHIGH,reftext="CSETHIGH"] +==== CSETHIGH + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability set metadata + +Mnemonic:: +`csethigh cd, cs1, rs2` + +Encoding:: +include::wavedrom/csethigh.adoc[] + +Description:: +Copy `cs1` to `cd` , replace the capability metadata (i.e. bits +[CLEN-1:XLENMAX]) with `rs2` and set `cd.tag` to 0. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: TODO #this is correct but capToMemBits is redundant, as it's now XORed with zero (null-cap)# ++ +-- +TODO +-- + diff --git a/src/insns/csetmode_32bit.adoc b/src/insns/csetmode_32bit.adoc new file mode 100644 index 00000000..a97e8649 --- /dev/null +++ b/src/insns/csetmode_32bit.adoc @@ -0,0 +1,33 @@ +<<< + +[#csetmode] +==== CSETMODE + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This instruction used to be CSetFlags. +endif::[] + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability set CHERI execution mode + +Mnemonic:: +`csetmode cd, cs1, rs2` + +Encoding:: +include::wavedrom/csetmode.adoc[] + +Description:: +Copy `cs1` to `cd` and set `cd.M` (the mode bit) to the least significant bit of +`rs2` . `cd.tag` is set to 0 if `cs1` is sealed. + +Prerequisites:: +{cheri_mode_ext_name} + +Operation :: +[source,SAIL,subs="verbatim,quotes"] +-- +TODO +-- + diff --git a/src/insns/csrr_32bit.adoc b/src/insns/csrr_32bit.adoc new file mode 100644 index 00000000..1c9f97f8 --- /dev/null +++ b/src/insns/csrr_32bit.adoc @@ -0,0 +1,71 @@ +<<< +//[#insns-csrr-32bit,reftext="CSR access (CSRRW[I], CSRRS[I], CSRRC[I]), 32-bit encoding"] + +[#CSRRWI,reftext="CSRRWI"] +==== CSRRWI +See <>. + +[#CSRRS,reftext="CSRRS"] +==== CSRRS +See <>. + +[#CSRRSI,reftext="CSRRSI"] +==== CSRRSI +See <>. + +[#CSRRC,reftext="CSRRC"] +==== CSRRC +See <>. + +<<< + +[#CSRRCI,reftext="CSRRCI"] +==== CSRRCI + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* CSpecialRW is removed and this functionality replaces it +endif::[] + + +Synopsis:: +CSR access (CSRRWI, CSRRS, CSRRSI, CSRRC, CSRRCI) 32-bit encodings + +Register Source Mnemonics:: +`csrr[s|c] rd, rs1, csr` + +Immediate Source Mnemonics:: +`csrr[w|s|c]i rd, imm, csr` + +Encoding:: +include::wavedrom/csr-instr.adoc[] + +Description:: +These are standard RISC-V CSR instructions with extended functionality for +accessing CLEN-wide CSRs, such as <>/<> which can be +accessed through either the RISC-V address or the capability address alias. ++ +Unlike <> these instruction perform the same update to CLEN-wide CSRs + to either the XLEN or CLEN-wide alias as they only every perform an XLEN-wide update. + Where a CLEN-wide CSR is updated, through either alias, the final address is determined + as defined by RISC-V for these instructions. The metadata and tag are updated + as defined in xref:extended_CSR_writing[xrefstyle=short]. ++ +See xref:aliased_CSRs[xrefstyle=short] for a list of CLEN-wide CSRs and +xref:extended_CSR_writing[xrefstyle=short] for the action taken on writing an XLEN-wide value to each one. ++ +Access to XLEN-wide CSRs from other extensions is as specified by RISC-V. + +Permissions:: +All non-user mode accessible CSRs require <>, including existing RISC-V CSRs. + +Prerequisites for capability address aliases:: +{cheri_base_ext_name} + +Prerequisites for legacy address aliases:: +{cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/csrrw_32bit.adoc b/src/insns/csrrw_32bit.adoc new file mode 100644 index 00000000..fe063732 --- /dev/null +++ b/src/insns/csrrw_32bit.adoc @@ -0,0 +1,52 @@ +<<< +//[#insns-csrr-32bit,reftext="CSR access (CSRRW[I], CSRRS[I], CSRRC[I]), 32-bit encoding"] + +[#CSRRW,reftext="CSRRW"] +==== CSRRW + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* CSpecialRW is removed and this functionality replaces it +endif::[] + + +Synopsis:: +CSR access (CSRRW) 32-bit encodings + +Mnemonic (XLEN-wide target, and XLEN-wide aliases of CLEN-wide CSRs):: +`csrrw rd, rs1, csr` + +Mnemonics (CLEN-wide target):: +`csrrw cd, cs1, csr` + +Encoding:: +include::wavedrom/csrw-instr.adoc[] + +Description:: +This is a standard RISC-V CSR instructions with extended functionality for +accessing CLEN-wide CSRs, such as <>/<> which can be +accessed through either the RISC-V address or the capability address alias. ++ +See xref:aliased_CSRs[xrefstyle=short] for a list of CLEN-wide CSRs and +xref:extended_CSR_writing[xrefstyle=short] for the action taken on writing each one. ++ +CSRRW writes `cs1` to the CLEN-wide alias of extended CSRs, and reads a full capability into `cd`. ++ +CSRRW writes `rs1` to the XLEN-wide alias of extended CSRs, and reads the address field into `rd`. ++ +Access to XLEN-wide CSRs from other extensions is as specified by RISC-V. + + +Permissions:: +All non-user mode accessible CSRs require <>, including existing RISC-V CSRs. + +Prerequisites for capability address aliases:: +{cheri_base_ext_name} + +Prerequisites for legacy address aliases:: +{cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/ctestsubset_32bit.adoc b/src/insns/ctestsubset_32bit.adoc new file mode 100644 index 00000000..d0f992f5 --- /dev/null +++ b/src/insns/ctestsubset_32bit.adoc @@ -0,0 +1,32 @@ +<<< + +[#CTESTSUBSET,reftext="CTESTSUBSET"] +==== CTESTSUBSET + +include::new_encoding_note.adoc[] + +Synopsis:: +Capability test subset + +Mnemonic:: +`ctestsubset rd, cs1, cs2` + +Encoding:: +include::wavedrom/ctestsubset.adoc[] + +Description:: +`rd` is set to 1 if the tag of capabilities `cs1` and `cs2` are equal and the +bounds and permissions of `cs2` are a subset of those of `cs1` . + +NOTE: The implementation of this instruction is similar to <>, although +<> does not include the sealed bit in the check. + +Prerequisites:: +{cheri_base_ext_name} + +Operation:: ++ +-- +TODO +-- + diff --git a/src/insns/cvl_nr_re_ew.adoc b/src/insns/cvl_nr_re_ew.adoc new file mode 100644 index 00000000..3fc9cfd7 --- /dev/null +++ b/src/insns/cvl_nr_re_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvl_nr_re_ew,reftext="Vector whole register load (CVLRE.V, VLRE.V)"] +==== CVLRE.V, VLRE.V + +Synopsis:: +Vector whole register load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlce_ew.adoc b/src/insns/cvlce_ew.adoc new file mode 100644 index 00000000..c73b2add --- /dev/null +++ b/src/insns/cvlce_ew.adoc @@ -0,0 +1,59 @@ +<<< +//[#insns-cvlce_ew,reftext="Vector load capability (CVLCE.V, VLCE.V)"] + +[#CVLCE_EW_V,reftext="CVLCE.V"] +==== CVLCE.V + +See <.V>>. + +[#VLCE_EW_V,reftext="VLCE.V"] +==== CVLCE.V, VLCE.V + +Synopsis:: +Vector load capability + +Capability Mode Mnemonics:: +`cvlce.v vd, (cs1)` + +Legacy Mode Mnemonics:: +`vlce.v vd, (rs1)` + +Encoding:: +include::wavedrom/cvlce_ew.adoc[] + +Description:: +Vector load, supporting CHERI capabilities. ++ +The base address (`cs1`/`rs1`) is required to be `CLEN`-aligned, if it is a not, a load address misaligned exception occurs. ++ +Other than the support for CHERI capabilities, these instructions operate in the same way as the corresponding +vector unit-stride load instruction. For each *complete* `CLEN`-bit subdivision of the destination that is +loaded, the associated tag bit is updated with the tag bit that is read from memory. +If (`vl` * `EEW`) is not a multiple of `CLEN` then the last `CLEN`-bit subdivision of +the destination that is updated with data from memory (which will be incomplete) has its associated tag bit +cleared. ++ +Traps on these instructions will always be reported with a value of `vstart` that is a multiple of `CLEN` / `EEW`, +and will raise an illegal instruction exception if `vstart` does not meet this condition. ++ +Implementations only provide the instructions dealing with the element widths they support. Instruction +encodings for unsupported element widths are reserved. + +include::load_exceptions.adoc[] + +Prerequisites for Capability Mode:: +{cheri_base_ext_name}, V, {cheri_vectorcap_ext_name} + +Prerequisites for Legacy Mode:: +{cheri_base_ext_name}, V, {cheri_vectorcap_ext_name} + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvle_ew.adoc b/src/insns/cvle_ew.adoc new file mode 100644 index 00000000..d46b5f18 --- /dev/null +++ b/src/insns/cvle_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvle_ew,reftext="Vector unit-stride load (CVLE.V, VLE.V)"] +==== CVLE.V, VLE.V + +Synopsis:: +Vector unit-stride load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvle_ew_ff.adoc b/src/insns/cvle_ew_ff.adoc new file mode 100644 index 00000000..4dd85e8e --- /dev/null +++ b/src/insns/cvle_ew_ff.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvle_ew_ff,reftext="Vector unit-stride fault-only-first load (CVLEFF.V, VLEFF.V)"] +==== CVLEFF.V, VLEFF.V + +Synopsis:: +Vector unit-stride fault-only-first load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlm.adoc b/src/insns/cvlm.adoc new file mode 100644 index 00000000..cc420ed0 --- /dev/null +++ b/src/insns/cvlm.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvlm,reftext="Vector load mask (CVLM.V, VLM.V)"] +==== CVLM.V, VLM.V + +Synopsis:: +Vector load mask + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvloxei_ew.adoc b/src/insns/cvloxei_ew.adoc new file mode 100644 index 00000000..47d50d89 --- /dev/null +++ b/src/insns/cvloxei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvloxei_ew,reftext="Vector indexed-ordered load (CVLOXEI.V, VLOXEI.V)"] +==== CVLOXEI.V, VLOXEI.V + +Synopsis:: +Vector indexed-ordered load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvloxseg_nf_ei_ew.adoc b/src/insns/cvloxseg_nf_ei_ew.adoc new file mode 100644 index 00000000..d1f37fe9 --- /dev/null +++ b/src/insns/cvloxseg_nf_ei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvloxseg_nf_ei_ew,reftext="Vector indexed-ordered segment load (CVLOXSEGEI.V, VLOXSEGEI.V)"] +==== CVLOXSEGEI.V, VLOXSEGEI.V + +Synopsis:: +Vector indexed-ordered segment load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlse_ew.adoc b/src/insns/cvlse_ew.adoc new file mode 100644 index 00000000..9ec3330d --- /dev/null +++ b/src/insns/cvlse_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvlse_ew,reftext="Vector strided load (CVLSE.V, VLSE.V)"] +==== CVLSE.V, VLSE.V + +Synopsis:: +Vector strided load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlseg_nf_e_ew.adoc b/src/insns/cvlseg_nf_e_ew.adoc new file mode 100644 index 00000000..56d2794f --- /dev/null +++ b/src/insns/cvlseg_nf_e_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvlseg_nf_e_ew,reftext="Vector unit-stride segment load (CVLSEGE.V, VLSEGE.V)"] +==== CVLSEGE.V, VLSEGE.V + +Synopsis:: +Vector unit-stride segment load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlseg_nf_e_ew_ff.adoc b/src/insns/cvlseg_nf_e_ew_ff.adoc new file mode 100644 index 00000000..c4cc0bcb --- /dev/null +++ b/src/insns/cvlseg_nf_e_ew_ff.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvlseg_nf_e_ew_ff,reftext="Vector unit-stride fault-only-first segment load (CVLSEGEFF.V, VLSEGEFF.V)"] +==== CVLSEGEFF.V, VLSEGEFF.V + +Synopsis:: +Vector unit-stride fault-only-first segment load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvlsseg_nf_e_ew.adoc b/src/insns/cvlsseg_nf_e_ew.adoc new file mode 100644 index 00000000..ee5c25e4 --- /dev/null +++ b/src/insns/cvlsseg_nf_e_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvlsseg_nf_e_ew,reftext="Vector strided segment load (CVLSSEGE.V, VLSSEGE.V)"] +==== CVLSSEGE.V, VLSSEGE.V + +Synopsis:: +Vector strided segment load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvluxei_ew.adoc b/src/insns/cvluxei_ew.adoc new file mode 100644 index 00000000..1d3f6988 --- /dev/null +++ b/src/insns/cvluxei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvluxei_ew,reftext="Vector indexed-unordered load (CVLUXEI.V, VLUXEI.V)"] +==== CVLUXEI.V, VLUXEI.V + +Synopsis:: +Vector indexed-unordered load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvluxseg_nf_ei_ew.adoc b/src/insns/cvluxseg_nf_ei_ew.adoc new file mode 100644 index 00000000..0bc43858 --- /dev/null +++ b/src/insns/cvluxseg_nf_ei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvluxseg_nf_ei_ew,reftext="Vector indexed-unordered segment load (CVLUXSEGEI.V, VLUXSEGEI.V)"] +==== CVLUXSEGEI.V, VLUXSEGEI.V + +Synopsis:: +Vector indexed-unordered segment load + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvmv_nr_r.adoc b/src/insns/cvmv_nr_r.adoc new file mode 100644 index 00000000..abaf0994 --- /dev/null +++ b/src/insns/cvmv_nr_r.adoc @@ -0,0 +1,33 @@ +<<< +//[#insns-cvm_nr_r,reftext="Whole vector register move (CVMVR.V)"] + +[#CVMV_NR_R_V],reftext="CVMVR.V"] +==== CVMVR.V + +Synopsis:: +Whole vector register move capabilities + +Mnemonics:: +`cvmvr.v vd, vs2` + +Encoding:: +include::wavedrom/cvmv_nr_r.adoc[] + +Description:: +Whole vector register move capabilities ++ +Other than the support for CHERI capabilities, these instructions operate in the same way as the corresponding +vector whole vector register move, `vmvr.v`. The tag bits associated with the destination are +updated by copying the corresponding tag bit associated with the source. ++ +Traps on these instructions will always be reported with a value of `vstart` that is a multiple of `CLEN` / `EEW`, +and will raise an illegal instruction exception if `vstart` does not meet this condition. + +Prerequisites:: +{cheri_base_ext_name}, V, {cheri_vectorcap_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/cvs_nr_r.adoc b/src/insns/cvs_nr_r.adoc new file mode 100644 index 00000000..39a5fb61 --- /dev/null +++ b/src/insns/cvs_nr_r.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvs_nr_r,reftext="Vector whole register store (CVSR.V, VSR.V)"] +==== CVSR.V, VSR.V + +Synopsis:: +Vector whole register store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsce_ew.adoc b/src/insns/cvsce_ew.adoc new file mode 100644 index 00000000..dc556429 --- /dev/null +++ b/src/insns/cvsce_ew.adoc @@ -0,0 +1,61 @@ +<<< +//[#insns-cvsce_ew,reftext="Vector store capability (CVLCE.V, VLCE.V)"] + +[#CVSCE_EW_V,reftext="CVSCE.V"] +==== CVSCE.V + +See <.V>>. + +[#VSCE_EW_V,reftext="VSCE.V"] +==== CVSCE.V, VSCE.V + +Synopsis:: +Vector store capability + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +include::wavedrom/cvsce_ew.adoc[] + +Description:: +Vector store, supporting CHERI capabilities. ++ +The base address (`cs1`/`rs1`) is required to be `CLEN`-aligned, if it is a not, a store/AMO address misaligned exception occurs. ++ +Other than the support for CHERI capabilities, these instructions operate in the same way as the corresponding +vector unit-stride load instruction. For each *complete* `CLEN`-bit subdivision of the source +that is stored, the associated tag bit is written to memory along with the data. +If (`vl` * `EEW`) is not a multiple of `CLEN` then the tag that is written to memory +along with the data from the last `CLEN`-bit subdivision of the source (which only partially be written) +has the value zero +(the tag bit associated with that `CLEN`-bit subdivision of the source vector +register group is ignored, but remains unmodified). ++ +Traps on these instructions will always be reported with a value of `vstart` that is a multiple of `CLEN` / `EEW`, +and will raise an illegal instruction exception if `vstart` does not meet this condition. ++ +Implementations only provide the instructions dealing with the element widths they support. Instruction +encodings for unsupported element widths are reserved. + +include::store_exceptions.adoc[] + +Prerequisites for Capability Mode:: +{cheri_base_ext_name}, V, {cheri_vectorcap_ext_name} + +Prerequisites for Legacy Mode:: +{cheri_base_ext_name}, V, {cheri_vectorcap_ext_name} + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvse_ew.adoc b/src/insns/cvse_ew.adoc new file mode 100644 index 00000000..22fe18b2 --- /dev/null +++ b/src/insns/cvse_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvse_ew,reftext="Vector unit-stride store (CVSE.V, VSE.V)"] +==== CVSE.V, VSE.V + +Synopsis:: +Vector unit-stride store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsm.adoc b/src/insns/cvsm.adoc new file mode 100644 index 00000000..825bc197 --- /dev/null +++ b/src/insns/cvsm.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsm,reftext="Vector store mask (CVSM.V, VSM.V)"] +==== CVSM.V, VSM.V + +Synopsis:: +Vector store mask + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsoxei_ew.adoc b/src/insns/cvsoxei_ew.adoc new file mode 100644 index 00000000..fe8f3ad9 --- /dev/null +++ b/src/insns/cvsoxei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsoxei_ew,reftext="Vector indexed-ordered store (CVSOXEI.V, VSOXEI.V)"] +==== CVSOXEI.V, VSOXEI.V + +Synopsis:: +Vector indexed-ordered store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsoxseg_nf_ei_ew.adoc b/src/insns/cvsoxseg_nf_ei_ew.adoc new file mode 100644 index 00000000..9068e16d --- /dev/null +++ b/src/insns/cvsoxseg_nf_ei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsoxseg_nf_ei_ew,reftext="Vector indexed-ordered segment store (CVSOXSEGEI.V, VSOXSEGEI.V)"] +==== CVSOXSEGEI.V, VSOXSEGEI.V + +Synopsis:: +Vector indexed-ordered segment store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsse_ew.adoc b/src/insns/cvsse_ew.adoc new file mode 100644 index 00000000..f2905c52 --- /dev/null +++ b/src/insns/cvsse_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsse_ew,reftext="Vector strided store (CVSSE.V, VSSE.V)"] +==== CVSSE.V, VSSE.V + +Synopsis:: +Vector strided store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsseg_nf_e_ew.adoc b/src/insns/cvsseg_nf_e_ew.adoc new file mode 100644 index 00000000..e0467684 --- /dev/null +++ b/src/insns/cvsseg_nf_e_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsseg_nf_e_ew,reftext="Vector unit-stride segment store (CVSSEGE.V, VSSEGE.V)"] +==== CVSSEGE.V, VSSEGE.V + +Synopsis:: +Vector unit-stride segment store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvssseg_nf_e_ew.adoc b/src/insns/cvssseg_nf_e_ew.adoc new file mode 100644 index 00000000..4c589f9a --- /dev/null +++ b/src/insns/cvssseg_nf_e_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvssseg_nf_e_ew,reftext="Vector strided segment store (CVSSSEGE.V, VSSSEGE.V)"] +==== CVSSSEGE.V, VSSSEGE.V + +Synopsis:: +Vector strided segment store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsuxei_ew.adoc b/src/insns/cvsuxei_ew.adoc new file mode 100644 index 00000000..0601d3d8 --- /dev/null +++ b/src/insns/cvsuxei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsuxei_ew,reftext="Vector indexed-unordered store (CVSUXEI.V, VSUXEI.V)"] +==== CVSUXEI.V, VSUXEI.V + +Synopsis:: +Vector indexed-unordered store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/cvsuxseg_nf_ei_ew.adoc b/src/insns/cvsuxseg_nf_ei_ew.adoc new file mode 100644 index 00000000..79d73ad7 --- /dev/null +++ b/src/insns/cvsuxseg_nf_ei_ew.adoc @@ -0,0 +1,37 @@ +<<< +[#insns-cvsuxseg_nf_ei_ew,reftext="Vector indexed-unordered segment store (CVSUXSEGEI.V, VSUXSEGEI.V)"] +==== CVSUXSEGEI.V, VSUXSEGEI.V + +Synopsis:: +Vector indexed-unordered segment store + +Capability Mode Mnemonics:: +`...` + +Legacy Mode Mnemonics:: +`...` + +Encoding:: +-- +TBD +-- + +Description:: +... + +Prerequisites for Capability Mode:: +V + +Prerequisites for Legacy Mode:: +V + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/dret.adoc b/src/insns/dret.adoc new file mode 100644 index 00000000..e1e026f5 --- /dev/null +++ b/src/insns/dret.adoc @@ -0,0 +1,31 @@ +<<< + +[#DRET,reftext="DRET"] +==== DRET + +Synopsis:: +Debug Return (DRET) + +Mnemonics:: +`dret` + +Encoding:: +include::wavedrom/dret.adoc[] + +Description:: +<> return from debug mode. It unseals <> and writes the result into +<>. + +NOTE: The <> instruction is the recommended way to exit debug mode. However, +it is a pseudo instruction to return that technically does not execute from the +program buffer or memory. It currently does not require the <> to grant +<> so it never excepts. + +Prerequisites:: +Sdext + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/jalr_cap_32bit.adoc b/src/insns/jalr_cap_32bit.adoc new file mode 100644 index 00000000..4ee92756 --- /dev/null +++ b/src/insns/jalr_cap_32bit.adoc @@ -0,0 +1,73 @@ +<<< + +[#JALR_PCC,reftext="JALR.PCC"] +==== JALR.PCC + +See <>. + +[#JALR_CAP,reftext="JALR.CAP"] +==== JALR.CAP + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* These instructions used to have separate encodings in +CHERI v9. The instructions depend on the CHERI execution mode and now +they share the same *new* encoding. +endif::[] + +Synopsis:: +Indirect jump and link (via integer address or capability) + +Capability Mode Mnemonic:: +`jalr.pcc rd, rs1` + +Legacy Mode Mnemonic:: +`jalr.cap cd, cs1` + +Encoding:: +include::wavedrom/ct-unconditional-jalr-cap.adoc[] + +Capability Mode Description:: +JALR.PCC allows unconditional jumps to a target integer address. The target +address in `rs1` is installed in the address field of the <>. The address +of the instruction following the jump (<> + 4) is written to `rd`. This is identical to the standard <> instruction, but with zero offset. + +Legacy Mode Description:: +JALR.CAP allows unconditional jumps to a target capability. The capability in +`cs1` is installed in <>. The <> of the next instruction following +the jump (<> + 4) is sealed and written to `cd`. This instruction can be +used to change the current CHERI execution mode and is identical to <> +but with zero offset. + +Exception:: +When these instructions cause CHERI exceptions, _CHERI jump or +branch_ fault is reported in the TYPE field and the following codes may be +reported in the CAUSE field of <> or <>: + +[%autowidth,options=header,align=center] +|============================================================================== +| CAUSE | JALR.PCC | JALR.CAP| Reason +| Tag violation | | ✔ | `cs1` has tag set to 0 +| Seal violation | | ✔ | `cs1` is sealed and the immediate is not 0 +| Permission violation | | ✔ | `cs1` does not grant <> +| Length violation | ✔ | ✔ | Minimum length instruction is not within the target capability's bounds +|============================================================================== + +include::pcrel_debug_warning.adoc[] + +Prerequisites JALR.PCC:: + {cheri_base_ext_name} + +Prerequisites JALR.CAP:: + {cheri_legacy_ext_name} + +Operation JALR.PCC:: ++ +-- +TODO +-- + +Operation JALR.CAP:: ++ +-- +TODO +-- diff --git a/src/insns/load_16bit.adoc b/src/insns/load_16bit.adoc new file mode 100644 index 00000000..b6c6b1d8 --- /dev/null +++ b/src/insns/load_16bit.adoc @@ -0,0 +1,74 @@ +<<< +//[#insns-load-16bit,reftext="Load (C.CLD, C.CLW, C.LD, C.LW), 16-bit encodings"] + +[#C_CLD,reftext="C.CLD"] +==== C.CLD +See <>. + +[#C_CLW,reftext="C.CLW"] +==== C.CLW +See <>. + +[#C_LD,reftext="C.LD"] +==== C.LD +See <>. + +<<< + +[#C_LW,reftext="C.LW"] +==== C.LW + +Synopsis:: +Load (C.CLD, C.CLW, C.LD, C.LW), 16-bit encodings + +Capability Mode Mnemonics (RV64):: +`c.cld/c.clw rd', offset(cs1')` + +Capability Mode Expansions (RV64):: +`cld/clw rd', offset(cs1')` + +Legacy Mode Mnemonics (RV64):: +`c.ld/c.lw rd', offset(rs1')` + +Legacy Mode Expansions (RV64):: +`ld/lw rd', offset(rs1')` + +Capability Mode Mnemonics (RV32):: +`c.clw rd', offset(cs1')` + +Capability Mode Expansions (RV32):: +`clw rd', offset(cs1')` + +Legacy Mode Mnemonics (RV32):: +`c.lw rd', offset(rs1')` + +Legacy Mode Expansions (RV32):: +`lw rd', offset(rs1')` + +Encoding:: +include::wavedrom/reg-based-ldnstr.adoc[] + +Capability Mode Description:: +Standard load instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Standard load instructions, authorised by the capability in <>. + +include::load_exceptions.adoc[] + +Prerequisites C.CLD:: +RV64, and {c_cheri_base_ext_names} + +Prerequisites C.CLW:: +{c_cheri_base_ext_names} + +Prerequisites C.LD:: +RV64, {c_cheri_legacy_ext_names} + +Prerequisites C.LW:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <> + + diff --git a/src/insns/load_16bit_Zcb.adoc b/src/insns/load_16bit_Zcb.adoc new file mode 100644 index 00000000..0647e75b --- /dev/null +++ b/src/insns/load_16bit_Zcb.adoc @@ -0,0 +1,67 @@ +<<< +//[#insns-load-16bit-Zcb,reftext="Load (C.CLH, C.CLHU, C.CLBU, C.LH, C.LHU, C.LBU), 16-bit encodings"] + + + +[#C_CLH,reftext="C.CLH"] +==== C.CLH +See <>. + +[#C_CLHU,reftext="C.CLHU"] +==== C.CLHU +See <>. + +[#C_CLBU,reftext="C.CLBU"] +==== C.CLBU +See <>. + +[#C_LH,reftext="C.LH"] +==== C.LH +See <>. + +[#C_LHU,reftext="C.LHU"] +==== C.LHU +See <>. + +<<< + +[#C_LBU,reftext="C.LBU"] +==== C.LBU + +Synopsis:: +Load (C.CLH, C.CLHU, C.CLBU, C.LH, C.LHU, C.LBU), 16-bit encodings + +Capability Mode Mnemonics:: +`c.clh/c.clhu/c.clbu rd', offset(cs1')` + +Capability Mode Expansions:: +`clh/clhu/clbu rd, offset(cs1)` + +Legacy Mode Mnemonics:: +`c.lh/c.lhu/c.lbu rd', offset(rs1')` + +Legacy Mode Expansions:: +`lh/lhu/lbu rd, offset(rs1)` + +Encoding:: + +include::wavedrom/reg-based-ldnstr-Zcb.adoc[] + +Capability Mode Description:: +Subword load instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Subword load instructions, authorised by the capability in <>. + +include::load_exceptions.adoc[] + +Prerequisites C.CLH, C.CLHU, C.CLBU:: +{c_cheri_base_ext_names}, and Zcb + +Prerequisites C.LH, C.LHU, C.LBU:: +{c_cheri_legacy_ext_names}, and Zcb + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <>, <>, <> + + diff --git a/src/insns/load_16bit_cap_sprel.adoc b/src/insns/load_16bit_cap_sprel.adoc new file mode 100644 index 00000000..ca10e3c7 --- /dev/null +++ b/src/insns/load_16bit_cap_sprel.adoc @@ -0,0 +1,35 @@ +<<< +//[#insns-load-16bit-cap-sprel,reftext="Load capability (C.CLC, C.CLCSP), 16-bit encodings"] + +[#C_CLC,reftext="C.CLC"] +==== C.CLC + +see <>. + +[#C_CLCSP,reftext="C.CLCSP"] +==== C.CLCSP + +Synopsis:: +Capability loads (C.CLC, C.CLCSP), 16-bit encodings + +Capability Mode Mnemonics:: +`c.clc cd', offset(cs1'/csp)` + +Capability Mode Expansions:: +`clc cd', offset(cs1'/csp)` + +Encoding:: +include::wavedrom/c-sp-load-cap.adoc[] + +include::load_cap_cap_description.adoc[] + +Legacy Mode Description:: +These mnemonics do not exist in Legacy Mode. The RV32 encodings map to <>/<> and the RV64 encodings map to <>/<>. + +include::load_exceptions.adoc[] + +Prerequisites:: +{c_cheri_base_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <> diff --git a/src/insns/load_16bit_fp_dp.adoc b/src/insns/load_16bit_fp_dp.adoc new file mode 100644 index 00000000..629dba78 --- /dev/null +++ b/src/insns/load_16bit_fp_dp.adoc @@ -0,0 +1,62 @@ +<<< +//[#insns-load-16bit-fp-sprel,reftext="Load (C.CFLD, C.FLD, C.CFLDSP, C.FLDSP), 16-bit encodings"] + +[#C_CFLD,reftext="C.CFLD"] +==== C.CFLD + +See <>. + +[#C_FLD,reftext="C.FLD"] +==== C.FLD + +See <>. + +[#C_CFLDSP,reftext="C.CFLDSP"] +==== C.CFLDSP + +See <>. + +<<< + +[#C_FLDSP,reftext="C.FLDSP"] +==== C.FLDSP + +Synopsis:: +Double precision floating point loads (C.CFLD, C.FLD, C.CFLDSP, C.FLDSP), 16-bit encodings + +Capability Mode Mnemonics (RV32):: +`c.cfld frd', offset(cs1'/csp)` + +Capability Mode Expansions (RV32):: +`cfld frd', offset(csp)` + +Legacy Mode Mnemonics (RV32):: +`c.fld fs2, offset(rs1'/sp)` + +Legacy Mode Expansions (RV32):: +`fld fs2, offset(rs1'/sp)` + +Legacy Mode Mnemonics (RV64):: +`c.fld fs2, offset(rs1'/sp)` + +Legacy Mode Expansion (RV64):: +`fld fs2, offset(rs1'/sp)` + +Encoding:: +include::wavedrom/c-sp-load-css-dp.adoc[] +include::wavedrom/c-sp-load-css-dp-sprel.adoc[] + +Legacy Mode Description:: +Standard floating point stack pointer relative load instructions, authorised by the capability in <>. Note that these instructions are not available in Capability Mode, as they have been remapped to <>, <>. + +include::load_exceptions.adoc[] + +Prerequisites for C.CFLD, C.CFLDSP:: +{c_cheri_base_ext_names}, and D + +Prerequisites for C.FLD, C.FLDSP:: +{c_cheri_legacy_ext_names}, and D + +Operation (after expansion to 32-bit encodings):: + See <> + diff --git a/src/insns/load_16bit_fp_sp.adoc b/src/insns/load_16bit_fp_sp.adoc new file mode 100644 index 00000000..920ff3be --- /dev/null +++ b/src/insns/load_16bit_fp_sp.adoc @@ -0,0 +1,34 @@ +<<< + +[#C_FLW,reftext="C.FLW"] +==== C.FLW + +See <>. + +[#C_FLWSP,reftext="C.FLWSP"] +==== C.FLWSP + +Synopsis:: +Floating point load (C.FLW, C.FLWSP), 16-bit encodings + +Legacy Mode Mnemonics (RV32):: +`c.flw rd', offset(rs1'/sp)` + +Legacy Mode Expansions (RV32):: +`flw rd', offset(rs1'/sp)` + +Encoding (RV32):: +include::wavedrom/c-sp-load-css-fp.adoc[] +include::wavedrom/c-sp-load-css-fp-sprel.adoc[] + +Legacy Mode Description:: +Standard floating point load instructions, authorised by the capability in <>. Note that these instructions are not available in Capability Mode, as they have been remapped to <>, <>. + +include::load_exceptions.adoc[] + +Prerequisites:: +{c_cheri_legacy_ext_names}, and F + +Operation (after expansion to 32-bit encodings):: + See <> + diff --git a/src/insns/load_16bit_sprel.adoc b/src/insns/load_16bit_sprel.adoc new file mode 100644 index 00000000..08360b3b --- /dev/null +++ b/src/insns/load_16bit_sprel.adoc @@ -0,0 +1,77 @@ +<<< +//[#insns-load-16bit-sprel,reftext="Load (C.CLWSP, C.CLDSP, C.LWSP, C.LDSP), 16-bit encodings"] + +[#C_CLWSP,reftext="C.CLWSP"] +==== C.CLWSP + +See <>. + +[#C_CLDSP,reftext="C.CLDSP"] +==== C.CLDSP + +See <>. + +[#C_LWSP,reftext="C.LWSP"] +==== C.LWSP + +See <>. + +<<< + +[#C_LDSP,reftext="C.LDSP"] +==== C.LDSP + +Synopsis:: +Load (C.CLWSP, C.CLDSP, C.LWSP, C.LDSP), 16-bit encodings + +Capability Mode Mnemonics (RV64):: +`c.cld/c.clw rd, offset(csp)` + +Capability Mode Expansions (RV64):: +`cld/clw rd, offset(csp)` + +Legacy Mode Mnemonics (RV64):: +`c.ld/c.lw rd, offset(sp)` + +Legacy Mode Expansions (RV64):: +`ld/lw rd, offset(sp)` + +Capability Mode Mnemonics (RV32):: +`c.clw rd, offset(csp)` + +Capability Mode Expansions (RV32):: +`clw rd, offset(csp)` + +Legacy Mode Mnemonics (RV32):: +`c.lw rd, offset(sp)` + +Legacy Mode Expansions (RV32):: +`lw rd, offset(sp)` + +Encoding:: +include::wavedrom/c-sp-load-store.adoc[] + +Capability Mode Description:: +Standard stack pointer relative load instructions, authorised by the capability in `csp`. + +Legacy Mode Description:: +Standard stack pointer relative load instructions, authorised by the capability in <>. + +include::load_exceptions.adoc[] + +Prerequisites for C.CLDSP:: +RV64, and {c_cheri_base_ext_names} + +Prerequisites for C.CLWSP:: +{c_cheri_base_ext_names} + +Prerequisites for C.LDSP:: +RV64, and {c_cheri_legacy_ext_names} + +Prerequisites for C.LWSP:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <> + + diff --git a/src/insns/load_32bit.adoc b/src/insns/load_32bit.adoc new file mode 100644 index 00000000..b18f569f --- /dev/null +++ b/src/insns/load_32bit.adoc @@ -0,0 +1,137 @@ +<<< + +[#CLWU,reftext="CLWU"] +==== CLWU + +See <>. + +[#CLW,reftext="CLW"] +==== CLW + +See <>. + +[#CLHU,reftext="CLHU"] +==== CLHU + +See <>. + +[#CLH,reftext="CLH"] +==== CLH + +See <>. + +[#CLBU,reftext="CLBU"] +==== CLBU + +See <>. + +[#CLB,reftext="CLB"] +==== CLB + +See <>. + +[#LD,reftext="LD"] +==== LD + +See <>. + +[#LWU,reftext="LWU"] +==== LWU + +See <>. + +[#LW,reftext="LW"] +==== LW + +See <>. + +[#LHU,reftext="LHU"] +==== LHU + +See <>. + +[#LH,reftext="LH"] +==== LH + +See <>. + +[#LBU,reftext="LBU"] +==== LBU + +See <>. + +[#LB,reftext="LB"] +==== LB + +See <>. + +<<< + +[#CLD,reftext="CLD"] +==== CLD + +Synopsis:: +Load (CLD, CLW[U], CLH[U], CLB[U], LD, LW[U], LH[U], LB[U]) + +Capability Mode Mnemonics (RV64):: +`cld rd, offset(cs1)` + +`clw[u] rd, offset(cs1)` + +`clh[u] rd, offset(cs1)` + +`clb[u] rd, offset(cs1)` + +Legacy Mode Mnemonics (RV64):: +`ld rd, offset(rs1)` + +`lw[u] rd, offset(rs1)` + +`lh[u] rd, offset(rs1)` + +`lb[u] rd, offset(rs1)` + +Capability Mode Mnemonics (RV32):: +`clw rd, offset(cs1)` + +`clh[u] rd, offset(cs1)` + +`clb[u] rd, offset(cs1)` + +Legacy Mode Mnemonics (RV32):: +`lw rd, offset(rs1)` + +`lh[u] rd, offset(rs1)` + +`lb[u] rd, offset(rs1)` + +Encoding:: +include::wavedrom/load.adoc[] + +Capability Mode Description:: +Load integer data of the indicated size (byte, halfword, word, double-word) +from memory. The effective address of the load is obtained by adding the +sign-extended 12-bit offset to the address of `cs1`. The authorising capability +for the operation is `cs1`. A copy of the loaded value is written to `rd`. + +Legacy Mode Description:: +Load integer data of the indicated size (byte, halfword, word, double-word) +from memory. The effective address of the load is obtained by adding the +sign-extended 12-bit offset to `rs1`. The authorising capability for the +operation is <>. A copy of the loaded value is written to `rd`. + +include::load_exceptions.adoc[] + +Prerequisites for CLD:: +RV64, {cheri_base_ext_name} + +Prerequisites for CLW[U], CLH[U], CLB[U]:: +{cheri_base_ext_name} + +Prerequisites for LD:: +RV64, {cheri_legacy_ext_name} + +Prerequisites for LW[U], LH[U], LB[U]:: +{cheri_legacy_ext_name} + +Capability Mode Operation:: ++ +-- +TBD +-- + +Legacy Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/load_32bit_cap.adoc b/src/insns/load_32bit_cap.adoc new file mode 100644 index 00000000..4cadcc55 --- /dev/null +++ b/src/insns/load_32bit_cap.adoc @@ -0,0 +1,58 @@ +<<< + +[#LC,reftext="LC"] +==== LC + +See <>. + +[#CLC,reftext="CLC"] +==== CLC + +include::new_encoding_note.adoc[] + +NOTE: The RV64 encoding is intended to also allocate the encoding for LQ for RV128. + +Synopsis:: +Load capability + +Capability Mode Mnemonics:: +`clc cd, offset(cs1)` + +Legacy Mode Mnemonics:: +`lc cd, offset(rs1)` + +include::xlen_variable_warning.adoc[] + +Encoding:: +include::wavedrom/loadcap.adoc[] + +Capability Mode Description:: +Load a CLEN+1 bit value from memory and writes it to `cd`. The capability in `cs1` authorizes the operation. The effective address of the memory access is obtained by adding the address of `cs1` to the sign-extended 12-bit offset. The tag value written to `cd` is 0 if the tag of the memory location loaded is 0 or `cs1` does not grant <>. + +Legacy Mode Description:: +Loads a CLEN+1 bit value from memory and writes it to `cd`. The capability +authorising the operation is <>. The effective address of the memory +access is obtained by adding `rs1` to the sign-extended 12-bit offset. +The tag value written to `cd` is 0 if the tag of the memory location loaded is +0 or <> does not grant <>. + +:has_cap_data: +include::load_exceptions.adoc[] + +Prerequisites for CLC:: +{cheri_base_ext_name} + +Prerequisites for LC:: +{cheri_legacy_ext_name} + +CLC Operation:: ++ +-- +TODO +-- + +LC Operation:: ++ +-- +TODO +-- diff --git a/src/insns/load_32bit_fp.adoc b/src/insns/load_32bit_fp.adoc new file mode 100644 index 00000000..2c9e9e97 --- /dev/null +++ b/src/insns/load_32bit_fp.adoc @@ -0,0 +1,72 @@ +<<< +//[#insns-load-32bit-fp,reftext="Floating point load (CFLD, CFLW, CFLH, FLD, FLW, FLH), 32-bit encodings"] + +[#CFLD,reftext="CFLD"] +==== CFLD +See <>. + +[#CFLW,reftext="CFLW"] +==== CFLW +See <>. + +[#CFLH,reftext="CFLH"] +==== CFLH +See <>. + +[#FLD,reftext="FLD"] +==== FLD +See <>. + +[#FLW,reftext="FLW"] +==== FLW +See <>. + +<<< + +[#FLH,reftext="FLH"] +==== FLH + +Synopsis:: +Floating point loads (CFLD, CFLW, CFLH, FLD, FLW, FLH), 32-bit encodings + +Capability Mode Mnemonics:: +`cfld/cflw/cflh frd, offset(cs1)` + +Legacy Mode Mnemonics:: +`fld/flw/flh rd, offset(rs1)` + +Encoding:: +include::wavedrom/fpload.adoc[] + +Capability Mode Description:: +Standard floating point load instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Standard floating point load instructions, authorised by the capability in <>. + +:!cap_load: +include::load_exceptions.adoc[] + +Prerequisites for CFLD:: +{cheri_base_ext_name}, and D + +Prerequisites for CFLW:: +{cheri_base_ext_name}, and F + +Prerequisites for CFLH:: +{cheri_base_ext_name}, and Zfhmin or Zfh + +Prerequisites for FLD:: +{cheri_legacy_ext_name}, and D + +Prerequisites for FLW:: +{cheri_legacy_ext_name}, and F + +Prerequisites for FLH:: +{cheri_legacy_ext_name}, and Zfhmin or Zfh + +Operation:: ++ +-- +TODO +-- diff --git a/src/insns/load_cap_cap_description.adoc b/src/insns/load_cap_cap_description.adoc new file mode 100644 index 00000000..85687bc8 --- /dev/null +++ b/src/insns/load_cap_cap_description.adoc @@ -0,0 +1,2 @@ +Capability Mode Description:: +Load capability instruction, authorised by the capability in `cs1`. Take a load address misaligned exception if not naturally aligned. diff --git a/src/insns/load_cap_int_description.adoc b/src/insns/load_cap_int_description.adoc new file mode 100644 index 00000000..7045d1bc --- /dev/null +++ b/src/insns/load_cap_int_description.adoc @@ -0,0 +1,2 @@ +Legacy Mode Description:: +Load capability instruction, authorised by the capability in <>. Take a load address misaligned exception if not naturally aligned. diff --git a/src/insns/load_exceptions.adoc b/src/insns/load_exceptions.adoc new file mode 100644 index 00000000..82cf64f2 --- /dev/null +++ b/src/insns/load_exceptions.adoc @@ -0,0 +1,25 @@ +Exceptions:: +ifdef::load_res[] +All misaligned load reservations cause a load address misaligned exception to allow software emulation (if the Zam extension is supported, see cite:[riscv-unpriv-spec]), otherwise they take a load access fault exception. ++ +endif::[] +ifdef::has_cap_data[] +Misaligned address fault exception when the effective address is not aligned +to CLEN/8. ++ +endif::[] +CHERI fault exception when the authorising capability fails one of the checks +listed below; in this case, _CHERI data fault_ is reported in the <> or +<> TYPE field and the corresponding code is written to CAUSE. + +[%autowidth,options=header,align=center] +|============================================================================== +| CAUSE | Reason +| Tag violation | Authority capability tag set to 0 +| Seal violation | Authority capability is sealed +| Permission violation | Authority capability does not grant <> +| Length violation | At least one byte accessed is outside the authority capability bounds +|============================================================================== + +:!load_res: +:!has_cap_data: \ No newline at end of file diff --git a/src/insns/load_res_32bit.adoc b/src/insns/load_res_32bit.adoc new file mode 100644 index 00000000..72c5dc1a --- /dev/null +++ b/src/insns/load_res_32bit.adoc @@ -0,0 +1,88 @@ +<<< +//[#insns-load-res-32bit,reftext="Load Reserved (CLR.D, CLR.W, CLR.H, CLR.B, LR.D, LR.W, LR.H, LR.B), 32-bit encodings"] + +[#CLR_D,reftext="CLR.D"] +==== CLR.D +See <>. + +[#CLR_W,reftext="CLR.W"] +==== CLR.W +See <>. + +[#CLR_H,reftext="CLR.H"] +==== CLR.H +See <>. + +[#CLR_B,reftext="CLR.B"] +==== CLR.B +See <>. + +[#LR_D,reftext="LR.D"] +==== LR.D +See <>. + +[#LR_W,reftext="LR.W"] +==== LR.W +See <>. + +[#LR_H,reftext="LR.H"] +==== LR.H +See <>. + +<<< + +[#LR_B,reftext="LR.B"] +==== LR.B + +Synopsis:: +Load Reserved (CLR.D, CLR.W, CLR.H, CLR.B, LR.D, LR.W, LR.H, LR.B), 32-bit encodings + +Capability Mode Mnemonics (RV64):: +`clr.[d|w|h|b] rd, 0(cs1)` + +Capability Mode Mnemonics (RV32):: +`clr.[w|h|b] rd, 0(cs1)` + +Legacy Mode Mnemonics (RV64):: +`lr.[d|w|h|b] rd, 0(rs1)` + +Legacy Mode Mnemonics (RV32):: +`lr.[w|h|b] rd, 0(rs1)` + +Encoding:: +include::wavedrom/load_res.adoc[] + +Capability Mode Description:: +Load reserved instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Load reserved instructions, authorised by the capability in <>. + +:load_res: + +include::load_exceptions.adoc[] + +Prerequisites for CLR.D:: +RV64, and {cheri_base_ext_name} + +Prerequisites for CLR.W:: +{cheri_base_ext_name} + +Prerequisites for CLR.H, CLR.B:: +{lr_sc_bh_ext_name} and {cheri_base_ext_name} + +Prerequisites for LR.D:: +RV64, and {cheri_legacy_ext_name} + +Prerequisites for LR.W:: +{cheri_legacy_ext_name} + +Prerequisites for LR.H, LR.B:: +{lr_sc_bh_ext_name} and {cheri_legacy_ext_name} + + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/load_res_cap_32bit.adoc b/src/insns/load_res_cap_32bit.adoc new file mode 100644 index 00000000..28612d02 --- /dev/null +++ b/src/insns/load_res_cap_32bit.adoc @@ -0,0 +1,56 @@ +<<< +//[#insns-load-res-cap-32bit,reftext="Load Reserved (CLR.C, LR.C), 32-bit encodings"] + +[#LR_C,reftext="LR.C"] +==== LR.C + +See <>. + +[#CLR_C,reftext="CLR.C"] +==== CLR.C + +NOTE: The RV64 encoding is intended to also allocate the encoding for LR.Q for RV128. + +Synopsis:: +Load Reserved (CLR.C, LR.C), 32-bit encodings + +include::xlen_variable_warning.adoc[] + +Capability Mode Mnemonics (RV64):: +`clr.c cd, 0(cs1)` + +Capability Mode Mnemonics (RV32):: +`clr.c cd, 0(cs1)` + +Legacy Mode Mnemonics (RV64):: +`lr.c cd, 0(rs1)` + +Legacy Mode Mnemonics (RV32):: +`lr.c cd, 0(rs1)` + +Encoding:: +include::wavedrom/load_res_cap.adoc[] + +Capability Mode Description:: +Load reserved instructions, authorised by the capability in `cs1`. + All misaligned load reservations cause a load address misaligned exception to allow software emulation (Zam extension, see cite:[riscv-unpriv-spec]). + +Legacy Mode Description:: +Load reserved instructions, authorised by the capability in <>. + All misaligned load reservations cause a load address misaligned exception to allow software emulation (Zam extension, see cite:[riscv-unpriv-spec]). + +:cap_load: + +include::load_exceptions.adoc[] + +Prerequisites for CLC:: +{cheri_base_ext_name} + +Prerequisites for LC:: +{cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/modeswitch_16bit.adoc b/src/insns/modeswitch_16bit.adoc new file mode 100644 index 00000000..2216d841 --- /dev/null +++ b/src/insns/modeswitch_16bit.adoc @@ -0,0 +1,38 @@ +<<< +//[#insns-modeswitch-16bit,reftext="Mode switching (C.CModeSwitch), 16-bit encodings"] + +[#C_CMODESWITCH,reftext="C.CMODESWITCH"] +==== C.CMODESWITCH + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This instruction is *new*. +endif::[] + +Synopsis:: +Capability/Legacy Mode switching (C.CMODESWITCH), 16-bit encodings + +Mnemonics:: +`c.cmodeswitch` + +Expansions:: +`cmodeswitch` + +Encoding:: +include::wavedrom/modeswitch_16bit.adoc[] + +Capability Mode Description:: +Directly switch to Legacy Mode. + +Legacy Mode Description:: +Directly switch to Capability Mode. + +Exceptions:: +None + +include::pcrel_debug_warning.adoc[] + +Prerequisites:: +{c_cheri_mode_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <> diff --git a/src/insns/modeswitch_32bit.adoc b/src/insns/modeswitch_32bit.adoc new file mode 100644 index 00000000..7d54a057 --- /dev/null +++ b/src/insns/modeswitch_32bit.adoc @@ -0,0 +1,31 @@ +<<< + +[#CMODESWITCH,reftext="CMODESWITCH"] +==== CMODESWITCH + +include::new_encoding_note.adoc[] + +Synopsis:: +Switch CHERI execution mode + +Mnemonics:: +`cmodeswitch` + +Encoding:: +include::wavedrom/modeswitch_32bit.adoc[] + +Description:: +Toggle the hart's current CHERI execution mode in <>. If the current mode in +<> is Legacy, then the mode bit (M) in <> is set to Capability. If the +current mode is Capability, then the mode bit (M) in <> is set to Legacy. + +include::pcrel_debug_warning.adoc[] + +Prerequisites:: +{cheri_mode_ext_name} + +CModeSwitch Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TODO +-- diff --git a/src/insns/mret_sret.adoc b/src/insns/mret_sret.adoc new file mode 100644 index 00000000..23dbf59f --- /dev/null +++ b/src/insns/mret_sret.adoc @@ -0,0 +1,37 @@ +<<< + +[#SRET,reftext="SRET"] +==== SRET + +See <>. + +[#MRET,reftext="MRET"] +==== MRET + +Synopsis:: +Trap Return (MRET, SRET) + +Mnemonics:: +`mret` + +`sret` + +Encoding:: +include::wavedrom/trap-return.adoc[] + +Description:: +Return from machine mode (<>) or supervisor mode (<>) trap handler +as defined by cite:[riscv-priv-spec]. MRET unseals <> and writes the +result into <>. SRET unseals <> and writes the result into <>. + +Exceptions:: +CHERI fault exceptions occur when <> does not grant <> because +<> and <> require access to privileged CSRs. When that exception +occurs, _CHERI instruction access fault_ is reported in the TYPE field and the +Permission Violation codes is reported in the CAUSE field of <> or +<>. + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/new_encoding_note.adoc b/src/insns/new_encoding_note.adoc new file mode 100644 index 00000000..83905e7d --- /dev/null +++ b/src/insns/new_encoding_note.adoc @@ -0,0 +1,4 @@ +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This page has *new* encodings. +endif::[] + diff --git a/src/insns/pcrel_debug_warning.adoc b/src/insns/pcrel_debug_warning.adoc new file mode 100644 index 00000000..dcbe4251 --- /dev/null +++ b/src/insns/pcrel_debug_warning.adoc @@ -0,0 +1,2 @@ +NOTE: The instructions on this page are either PC relative or may update the +<>. Therefore an implementation may make them illegal in debug mode. diff --git a/src/insns/prefetch.i.adoc b/src/insns/prefetch.i.adoc new file mode 100644 index 00000000..21dc1f5d --- /dev/null +++ b/src/insns/prefetch.i.adoc @@ -0,0 +1,62 @@ +<<< + +[#PREFETCH_I,reftext="PREFETCH.I"] +==== PREFETCH.I +See <>. + +[#PREFETCH_I_CAP,reftext="PREFETCH.I.CAP"] +==== PREFETCH.I.CAP + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by an +instruction fetch in the near future + +Capability Mode Mnemonic:: +`prefetch.i.cap offset(cs1)` + +Legacy Mode Mnemonic:: +`prefetch.i offset(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','OP-IMM=0010011'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5','zero'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','ORI=110'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5','cap: PREFETCH.I.CAP=00000', 'leg: PREFETCH.I=00000'], type: 3}, + {bits: 7, name: 'imm[11:5]', attr: ['7','offset[11:5]'], type: 3}, +]} +.... + +Capability Mode Description:: +A PREFETCH.I.CAP instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `cs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by an instruction fetch in the near future. The encoding +is only valid if imm[4:0]=0. The authorising capability for this operation is +`cs1`. + +Legacy Mode Description:: +A PREFETCH.I instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `rs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by an instruction fetch in the near future. The encoding +is only valid if imm[4:0]=0. The authorising capability for this operation is +<>. + +:prefetch_i: +include::cbo_exceptions.adoc[] + +Prerequisites for PREFETCH.I.CAP:: +Zicbop, {cheri_base_ext_name} + +Prerequisites for PREFETCH.I:: +Zicbop, {cheri_legacy_ext_name} + +Operation:: +[source,sail] +-- +TODO +-- diff --git a/src/insns/prefetch.r.adoc b/src/insns/prefetch.r.adoc new file mode 100644 index 00000000..03d3e916 --- /dev/null +++ b/src/insns/prefetch.r.adoc @@ -0,0 +1,62 @@ +<<< + +[#PREFETCH_R,reftext="PREFETCH.R"] +==== PREFETCH.R +See <>. + +[#PREFETCH_R_CAP,reftext="PREFETCH.R.CAP"] +==== PREFETCH.R.CAP + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by a +data read in the near future + +Capability Mode Mnemonic:: +`prefetch.r.cap offset(cs1)` + +Legacy Mode Mnemonic:: +`prefetch.r offset(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','OP-IMM=0010011'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5','zero'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','ORI=110'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5','cap: PREFETCH.R.CAP=00001', 'leg: PREFETCH.R=00001'], type: 3}, + {bits: 7, name: 'imm[11:5]', attr: ['7','offset[11:5]'], type: 3}, +]} +.... + +Capability Mode Description:: +A PREFETCH.R.CAP instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `cs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by a data read (i.e. load) in the near future. The +encoding is only valid if imm[4:0]=0. The authorising capability for this +operation is `cs1`. + +Legacy Mode Description:: +A PREFETCH.R instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `rs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by a data read (i.e. load) in the near future. The +encoding is only valid if imm[4:0]=0. The authorising capability for this +operation is <>. + +:prefetch_r: +include::cbo_exceptions.adoc[] + +Prerequisites for PREFETCH.R.CAP:: +Zicbop, {cheri_base_ext_name} + +Prerequisites for PREFETCH.R:: +Zicbop, {cheri_legacy_ext_name} + +Operation:: +[source,sail] +-- +TODO +-- diff --git a/src/insns/prefetch.w.adoc b/src/insns/prefetch.w.adoc new file mode 100644 index 00000000..1b2e8a34 --- /dev/null +++ b/src/insns/prefetch.w.adoc @@ -0,0 +1,59 @@ +<<< + +[#PREFETCH_W,reftext="PREFETCH.W"] +==== PREFETCH.W +See <>. + +[#PREFETCH_W_CAP,reftext="PREFETCH.W.CAP"] +==== PREFETCH.W.CAP + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by a +data write in the near future + +Capability Mode Mnemonic:: +`prefetch.w.cap offset(cs1)` + +Legacy Mode Mnemonic:: +`prefetch.w offset(rs1)` + +Encoding:: +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','OP-IMM=0010011'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5','zero'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','ORI=110'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5','base'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5','cap: PREFETCH.W.CAP=00011', 'leg: PREFETCH.W=00011'], type: 3}, + {bits: 7, name: 'imm[11:5]', attr: ['7','offset[11:5]'], type: 3}, +]} +.... + +Capability Mode Description:: +A PREFETCH.W.CAP instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `cs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by a data write (i.e. store) in the near future. The +encoding is only valid if imm[4:0]=0. The authorising capability for this +operation is `cs1`. + +Legacy Mode Description:: +A PREFETCH.W instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in `rs1` and the +sign-extended offset encoded in imm[11:0], where imm[4:0] equals 0b00000, is +likely to be accessed by a data write (i.e. store) in the near future. The +encoding is only valid if imm[4:0]=0. The authorising capability for this +operation is <>. + +Prerequisites for PREFETCH.W.CAP:: +{cheri_base_ext_name} + +Prerequisites for PREFETCH.W:: +{cheri_legacy_ext_name} + +Operation:: +[source,sail] +-- +TODO +-- diff --git a/src/insns/sh123add_32bit.adoc b/src/insns/sh123add_32bit.adoc new file mode 100644 index 00000000..4d70d032 --- /dev/null +++ b/src/insns/sh123add_32bit.adoc @@ -0,0 +1,73 @@ +<<< +//[#insns-sh123add-32bit,reftext="CSR access (CSH1ADD, CSH2ADD, CSH3ADD, SH1ADD, SH2ADD, SH3ADD), 32-bit encoding"] + +[#CSH1ADD,reftext="CSH1ADD"] +==== CSH1ADD +See <>. + +[#CSH2ADD,reftext="CSH2ADD"] +==== CSH2ADD +See <>. + +[#CSH3ADD,reftext="CSH3ADD"] +==== CSH3ADD +See <>. + +[#SH1ADD,reftext="SH1ADD"] +==== SH1ADD +See <>. + +[#SH2ADD,reftext="SH2ADD"] +==== SH2ADD +See <>. + +<<< + +[#SH3ADD,reftext="SH3ADD"] +==== SH3ADD + +Synopsis:: +Shift by _n_ and add for address generation + +Capability Mode Mnemonics:: +`csh[1|2|3]add cd, rs1, cs2` + +Legacy Mode Mnemonics:: +`sh[1|2|3]add rd, rs1, rs2` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x2, attr: ['SH1ADD=010', 'CSH1ADD=010', 'SH2ADD=100', 'CSH2ADD=100', 'SH3ADD=110', 'CSH3ADD=110'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH[1|2|3]ADD', 'CSH[1|2|3]ADD'] }, +]} +.... + +Capability Mode Description:: +Increment the address field of `cs1` by `rs2` shifted left by _n_ bit positions. Clear the tag if the resulting capability is unrepresentable or `cs1` is sealed. + +Legacy Mode Description:: +Increment the address field of `rs1` by `rs2` shifted left by _n_ bit positions. + +Prerequisites CSH[1|2|3]ADD:: +{cheri_base_ext_name}, Zba + +Prerequisites for SH[1|2|3]ADD:: +{cheri_legacy_ext_name}, Zba + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/sh123adduw_32bit.adoc b/src/insns/sh123adduw_32bit.adoc new file mode 100644 index 00000000..00b46229 --- /dev/null +++ b/src/insns/sh123adduw_32bit.adoc @@ -0,0 +1,73 @@ +<<< +//[#insns-sh123adduw-32bit,reftext="CSR access (CSH1ADD.UW, CSH2ADD.UW, CSH3ADD.UW, SH1ADD.UW, SH2ADD.UW, SH3ADD.UW), 32-bit encoding"] + +[#CSH1ADD_UW,reftext="CSH1ADD.UW"] +==== CSH1ADD.UW +See <>. + +[#CSH2ADD_UW,reftext="CSH2ADD.UW"] +==== CSH2ADD.UW +See <>. + +[#CSH3ADD_UW,reftext="CSH3ADD.UW"] +==== CSH3ADD.UW +See <>. + +[#SH1ADD_UW,reftext="SH1ADD.UW"] +==== SH1ADD.UW +See <>. + +[#SH2ADD_UW,reftext="SH2ADD.UW"] +==== SH2ADD.UW +See <>. + +<<< + +[#SH3ADD_UW,reftext="SH3ADD.UW"] +==== SH3ADD.UW + +Synopsis:: +Shift by _n_ and add unsigned word for address generation + +Capability Mode Mnemonic (RV64):: +`csh[1|2|3]add.uw cd, rs1, cs2` + +Legacy Mode Mnemonics (RV64):: +`sh[1|2|3]add.uw rd, rs1, rs2` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x2, attr: ['rv64: SH1ADD.UW=010', 'rv64: CSH1ADD.UW=010', 'rv64: SH2ADD.UW=100', 'rv64: CSH2ADD.UW=100', 'rv64: SH3ADD.UW=110', 'rv64: CSH3ADD.UW=110'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['rv64: SH[1|2|3]ADD.UW', 'rv64: CSH[1|2|3]ADD.UW'] }, +]} +.... + +Capability Mode Description:: +Increment the address field of `cs1` by the unsigned word in `rs2` shifted left by _n_ bit positions. Clear the tag if the resulting capability is unrepresentable or `cs1` is sealed. + +Legacy Mode Description:: +Increment the address field of `rs1` by the unsigned word in `rs2` shifted left by _n_ bit positions. + +Prerequisites CSH[1|2|3]ADD.UW:: +{cheri_base_ext_name}, Zba + +Prerequisites for SH[1|2|3]ADD.UW:: +{cheri_legacy_ext_name}, Zba + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: ++ +-- +TODO +-- diff --git a/src/insns/sh4add_32bit.adoc b/src/insns/sh4add_32bit.adoc new file mode 100644 index 00000000..e6d1804d --- /dev/null +++ b/src/insns/sh4add_32bit.adoc @@ -0,0 +1,59 @@ +<<< +//[#insns-sh4add-32bit,reftext="CSR access (CSH4ADD, SH4ADD), 32-bit encoding"] + +[#SH4ADD,reftext="SH4ADD"] +==== SH4ADD + +See <>. + +[#CSH4ADD,reftext="CSH4ADD"] +==== CSH4ADD + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This instruction is *new*. +endif::[] + +Synopsis:: +Shift by 4 and add for address generation (CSH4ADD, SH4ADD) + +Capability Mode Mnemonics:: +`csh4add cd, rs1, cs2` + +Legacy Mode Mnemonics:: +`sh4add rd, rs1, rs2` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['CSH4ADD','SH4ADD'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 16, attr: ['CSH4ADD','SH4ADD'] }, +]} +.... + +Capability Mode Description:: +Increment the address field of `cs1` by `rs2` shifted left by 4 bit positions. Clear the tag if the resulting capability is unrepresentable or `cs1` is sealed. + +Legacy Mode Description:: +Increment the address field of `rs1` by `rs2` shifted left by 4 bit positions. + +Prerequisites CSH4ADD:: +{cheri_base_ext_name} + +Prerequisites for SH4ADD:: +{cheri_legacy_ext_name} + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- diff --git a/src/insns/sh4adduw_32bit.adoc b/src/insns/sh4adduw_32bit.adoc new file mode 100644 index 00000000..854c834f --- /dev/null +++ b/src/insns/sh4adduw_32bit.adoc @@ -0,0 +1,56 @@ +<<< +//[#insns-sh4adduw-32bit,reftext="CSR access (CSH4ADD.UW, SH4ADD.UW), 32-bit encoding"] + +[#SH4ADD_UW,reftext="SH4ADD.UW"] +==== SH4ADD.UW + +See <>. + +[#CSH4ADD_UW,reftext="CSH4ADD.UW"] +==== CSH4ADD.UW + +Synopsis:: +Shift by 4 and add unsigned words for address generation (CSH4ADD.UW, SH4ADD.UW) + +Capability Mode Mnemonics:: +`csh4add.uw cd, rs1, cs2` + +Legacy Mode Mnemonics:: +`sh4add.uw rd, rs1, rs2` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0xe3, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['CSH4ADD.UW', 'SH4ADD.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 16, attr: ['CSH4ADD.UW', 'SH4ADD.UW'] }, +]} +.... + +Capability Mode Description:: +Increment the address field of `cs1` by the unsigned word in `rs2` shifted left by 4 bit positions. Clear the tag if the resulting capability is unrepresentable or `cs1` is sealed. + +Legacy Mode Description:: +Increment the address field of `rs1` by the unsigned word in `rs2` shifted left by 4 bit positions. + +Prerequisites CSH4ADD:: +{cheri_base_ext_name} + +Prerequisites for SH4ADD:: +{cheri_legacy_ext_name} + +Capability Mode Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- + +Legacy Mode Operation:: +-- +TBD +-- + diff --git a/src/insns/store_16bit.adoc b/src/insns/store_16bit.adoc new file mode 100644 index 00000000..d09adc19 --- /dev/null +++ b/src/insns/store_16bit.adoc @@ -0,0 +1,76 @@ +<<< +//[#insns-store-16bit,reftext="Store (C.CSD, C.CSW, C.SD, C.SW), 16-bit encodings"] + +[#C_CSD,reftext="C.CSD"] +==== C.CSD + +See <>. + +[#C_CSW,reftext="C.CSW"] +==== C.CSW + +See <>. + +[#C_SD,reftext="C.SD"] +==== C.SD + +See <>. + +<<< + +[#C_SW,reftext="C.SW"] +==== C.SW + +Synopsis:: +Stores (C.CSD, C.CSW, C.SD, C.SW), 16-bit encodings + +Capability Mode Mnemonics (RV64):: +`c.csd/c.csw rs2', offset(cs1')` + +Capability Mode Expansions (RV64):: +`csd/csw rs2', offset(cs1')` + +Legacy Mode Mnemonics (RV64):: +`c.sd/c.sw rs2', offset(rs1')` + +Legacy Mode Expansions (RV64):: +`sd/sw rs2', offset(rs1')` + +Capability Mode Mnemonics (RV32):: +`c.csw rs2', offset(cs1')` + +Capability Mode Expansion (RV32):: +`csw rs2', offset(cs1')` + +Legacy Mode Mnemonics (RV32):: +`c.sw rs2', offset(rs1')` + +Legacy Mode Expansion (RV32):: +`sw rs2', offset(rs1')` + +Encoding:: +include::wavedrom/c-cs-format-ls.adoc[] + +Capability Mode Description:: +Standard store instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Standard store instructions, authorised by the capability in <>. + +include::store_exceptions.adoc[] + +Prerequisites for C.CSD:: +RV64, and {c_cheri_base_ext_names} + +Prerequisites for C.CSW:: +{c_cheri_base_ext_names} + +Prerequisites for C.SD:: +RV64, and {c_cheri_legacy_ext_names} + +Prerequisites for C.SW:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <> + diff --git a/src/insns/store_16bit_Zcb.adoc b/src/insns/store_16bit_Zcb.adoc new file mode 100644 index 00000000..44f2e8ff --- /dev/null +++ b/src/insns/store_16bit_Zcb.adoc @@ -0,0 +1,54 @@ +<<< +//[#insns-store-16bit-Zcb,reftext="Store (C.CSH, C.CSB, C.SH, C.SB), 16-bit encodings"] + +[#C_CSH,reftext="C.CSH"] +==== C.CSH +See <>. + +[#C_CSB,reftext="C.CSB"] +==== C.CSB +See <>. + +[#C_SH,reftext="C.SH"] +==== C.SH +See <>. + +<<< + +[#C_SB,reftext="C.SB"] +==== C.CSH, C.CSB, C.SH, C.SB + +Synopsis:: +Stores (C.CSH, C.CSB, C.SH, C.SB), 16-bit encodings + +Capability Mode Mnemonics:: +`c.csh/c.csb rs2', offset(cs1')` + +Capability Mode Expansions:: +`csh/csb rs2', offset(cs1')` + +Legacy Mode Mnemonics:: +`c.sh/c.sb rs2', offset(rs1')` + +Legacy Mode Expansions:: +`sh/sb rs2', offset(rs1')` + +Encoding:: +include::wavedrom/reg-based-str-Zcb.adoc[] + +Capability Mode Description:: +Subword store instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Subword store instructions, authorised by the capability in <>. + +include::store_exceptions.adoc[] + +Prerequisites for C.CSH, C.CSB:: +{c_cheri_base_ext_names}, and Zcb + +Prerequisites for C.SH, C.SB:: +{c_cheri_legacy_ext_names}, and Zcb + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <> diff --git a/src/insns/store_16bit_cap_sprel.adoc b/src/insns/store_16bit_cap_sprel.adoc new file mode 100644 index 00000000..c961246a --- /dev/null +++ b/src/insns/store_16bit_cap_sprel.adoc @@ -0,0 +1,40 @@ +<<< +//[#insns-store-cap162bit-sprel,reftext="Store (C.CSC, C.CSCSP), 16-bit encodings"] + + +[#C_CSC,reftext="C.CSC"] +==== C.CSC + +see <>. + +[#C_CSCSP,reftext="C.CSCSP"] +==== C.CSC, C.CSCSP + +Synopsis:: +Stores (C.CSC, C.CSCSP), 16-bit encodings + +include::xlen_variable_warning.adoc[] + +Capability Mode Mnemonics:: +`c.csc cs2', offset(cs1'/csp)` + +Capability Mode Expansions:: +`csc cs2', offset(cs1'/csp)` + +Encoding:: +include::wavedrom/c-sp-store-cap.adoc[] + +include::store_cap_cap_description.adoc[] + +Legacy Mode Description:: +These mnemonics do not exist in Legacy Mode. The RV32 encodings map to <>/<> and the RV64 encodings map to <>/<>. + +:cap_store: +include::store_exceptions.adoc[] + +Prerequisites:: +{c_cheri_base_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <> + diff --git a/src/insns/store_16bit_fp_dp.adoc b/src/insns/store_16bit_fp_dp.adoc new file mode 100644 index 00000000..205b6612 --- /dev/null +++ b/src/insns/store_16bit_fp_dp.adoc @@ -0,0 +1,62 @@ +<<< +//[#insns-store-16bit-fp-dp,reftext="Store (C.CFSD, C.FSD, C.CFSDSP, C.FSDSP), 16-bit encodings"] + +[#C_CFSD,reftext="C.CFSD"] +==== C.CFSD +See <>. + +[#C_CFSDSP,reftext="C.CFSDSP"] +==== C.CFSDSP +See <>. + +[#C_FSD,reftext="C.FSD"] +==== C.FSD +See <>. + +<<< + +[#C_FSDSP,reftext="C.FSDSP"] +==== C.FSDSP + +Synopsis:: +Double precision floating point stores (C.CFSD, C.FSD, C.CFSDSP, C.FSDSP), 16-bit encodings + +Capability Mode Mnemonics (RV32CD/RV32D_Zca):: +`c.cfsd fs2, offset(cs1'/csp)` + +Capability Mode Expansions (RV32):: +`cfsd fs2, offset(csp)` + +Legacy Mode Mnemonics (RV32CD/RV32D_Zca):: +`c.fsd fs2, offset(rs1'/sp)` + +Legacy Mode Expansions (RV32):: +`fsd fs2, offset(rs1'/sp)` + +Legacy Mode Mnemonics (RV64CD/RV64D_Zca):: +`c.fsd fs2, offset(rs1'/sp)` + +Legacy Mode Expansion (RV64):: +`fsd fs2, offset(rs1'/sp)` + +Encoding:: +include::wavedrom/c-sp-store-css-fp-dp.adoc[] +include::wavedrom/c-sp-store-css-fp-dp-sprel.adoc[] + +Capability Mode Description:: +Standard floating point stack pointer relative store instructions, authorised by the capability in `cs1` or `csp`. + +Legacy Mode Description:: +Standard floating point stack pointer relative store instructions, authorised by the capability in <>. + +include::store_exceptions.adoc[] + +Prerequisites for C.CFSD, C.CFSDSP:: +{c_cheri_base_ext_names} + +Prerequisites for C.FSD, C.FSDSP:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <> + diff --git a/src/insns/store_16bit_fp_sp.adoc b/src/insns/store_16bit_fp_sp.adoc new file mode 100644 index 00000000..4d1d30ab --- /dev/null +++ b/src/insns/store_16bit_fp_sp.adoc @@ -0,0 +1,37 @@ +<<< +//[#insns-store-16bit-fp-sp,reftext="Store (C.FSW, C.FSWSP), 16-bit encodings"] + +[#C_FSW,reftext="C.FSW"] +==== C.FSW + +See <>. + +[#C_FSWSP,reftext="C.FSWSP"] +==== C.FSWSP + +Synopsis:: +Floating point stores (C.FSW, C.FSWSP), 16-bit encodings + +Legacy Mode Mnemonics (RV32):: +`c.fsw rs2', offset(rs1'/sp)` + +Legacy Mode Expansions (RV32):: +`fsw rs2', offset(rs1'/sp)` + +Encoding (RV32):: +include::wavedrom/c-sp-store-css-fp.adoc[] +include::wavedrom/c-sp-store-css-fp-sprel.adoc[] + +Legacy Mode Description:: +Standard floating point store instructions, authorised by the capability in <>. + +NOTE: these instructions are not available in Capability Mode, as they have been remapped to <>, <>. + +include::store_exceptions.adoc[] + +Prerequisites for C.FSW, C.FSWSP:: +{c_cheri_legacy_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <> + diff --git a/src/insns/store_16bit_sprel.adoc b/src/insns/store_16bit_sprel.adoc new file mode 100644 index 00000000..4f42d2dd --- /dev/null +++ b/src/insns/store_16bit_sprel.adoc @@ -0,0 +1,76 @@ +<<< +//[#insns-store-16bit-sprel,reftext="Store (C.CSWSP, C.CSDSP, C.SWSP, C.SDSP), 16-bit encodings"] + +[#C_CSWSP,reftext="C.CSWSP"] +==== C.CSWSP + +See <>. + +[#C_CSDSP,reftext="C.CSDSP"] +==== C.CSDSP + +See <>. + +[#C_SWSP,reftext="C.SWSP"] +==== C.SWSP + +See <>. + +<<< + +[#C_SDSP,reftext="C.SDSP"] +==== C.SDSP + +Synopsis:: +Stack pointer relative stores (C.CSWSP, C.CSDSP, C.SWSP, C.SDSP), 16-bit encodings + +Capability Mode Mnemonics (RV64):: +`c.csw/c.csd rs2, offset(csp)` + +Capability Mode Expansions (RV64):: +`csd/csw rs2, offset(csp)` + +Legacy Mode Mnemonics (RV64):: +`c.sd/c.sw rs2, offset(sp)` + +Legacy Mode Expansions (RV64):: +`sd/sw rs2, offset(sp)` + +Capability Mode Mnemonics (RV32):: +`c.csw rs2, offset(csp)` + +Capability Mode Expansion (RV32):: +`csw rs2, offset(csp)` + +Legacy Mode Mnemonics (RV32):: +`c.sw rs2, offset(sp)` + +Legacy Mode Expansion (RV32):: +`sw rs2, offset(sp)` + +Encoding:: +include::wavedrom/c-sp-load-store-css.adoc[] + +Capability Mode Description:: +Standard stack pointer relative store instructions, authorised by the capability in `csp`. + +Legacy Mode Description:: +Standard stack pointer relative store instructions, authorised by the capability in <>. + +include::store_exceptions.adoc[] + +Prerequisites for C.CSDSP:: +RV64, and {c_cheri_base_ext_names} + +Prerequisites for C.CSWSP:: +{c_cheri_base_ext_names} + +Prerequisites for C.SDSP:: +RV64, and {c_cheri_base_ext_names} + +Prerequisites for C.SWSP:: +{c_cheri_base_ext_names} + +Operation (after expansion to 32-bit encodings):: + See <>, <>, <>, <> + diff --git a/src/insns/store_32bit.adoc b/src/insns/store_32bit.adoc new file mode 100644 index 00000000..acc6a3e0 --- /dev/null +++ b/src/insns/store_32bit.adoc @@ -0,0 +1,105 @@ +<<< + +[#CSW,reftext="CSW"] +==== CSW + +See <> + +[#CSH,reftext="CSH"] +==== CSH + +See <> + +[#CSB,reftext="CSB"] +==== CSB + +See <> + +[#SD,reftext="SD"] +==== SD + +See <> + +[#SW,reftext="SW"] +==== SW + +See <> + +[#SH,reftext="SH"] +==== SH + +See <> + +[#SB,reftext="SB"] +==== SB + +See <> + +<<< + +[#CSD,reftext="CSD"] +==== CSD + +Synopsis:: +Stores (CSD, CSW, CSH, CSB, SD, SW, SH, SB) + +Capability Mode Mnemonics (RV64):: +`csd rs2, offset(cs1)` + +`csw rs2, offset(cs1)` + +`csh rs2, offset(cs1)` + +`csb rs2, offset(cs1)` + +Legacy Mode Mnemonics (RV64):: +`sd rs2, offset(rs1)` + +`sw rs2, offset(rs1)` + +`sh rs2, offset(rs1)` + +`sb rs2, offset(rs1)` + +Capability Mode Mnemonics (RV32):: +`csw rs2, offset(cs1)` + +`csh rs2, offset(cs1)` + +`csb rs2, offset(cs1)` + +Legacy Mode Mnemonics (RV32):: +`sw rs2, offset(rs1)` + +`sh rs2, offset(rs1)` + +`sb rs2, offset(rs1)` + +Encoding:: +include::wavedrom/store.adoc[] + +Capability Mode Description:: +Store integer data of the indicated size (byte, halfword, word, double-word) to +memory. The effective address of the store is obtained by adding the +sign-extended 12-bit offset to the address of `cs1`. The authorising capability +for the operation is `cs1`. A copy of `rs2` is written to memory at the +location indicated by the effective address and the tag bit of each block of +memory naturally aligned to CLEN/8 is cleared. + +Legacy Mode Description:: +Store integer data of the indicated size (byte, halfword, word, double-word) to +memory. The effective address of the store is obtained by adding the +sign-extended 12-bit offset to `rs1`. The authorising capability for the +operation is <>. A copy of `rs2` is written to memory at the location +indicated by the effective address and the tag bit of each block of memory +naturally aligned to CLEN/8 is cleared. + +include::store_exceptions.adoc[] + +Prerequisites for CSD:: +RV64, {cheri_base_ext_name} + +Prerequisites for CSW, CSH, CSB:: +{cheri_base_ext_name} + +Prerequisites for SD:: +RV64, {cheri_legacy_ext_name} + +Prerequisites for SW, SH, SB:: +{cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/store_32bit_cap.adoc b/src/insns/store_32bit_cap.adoc new file mode 100644 index 00000000..10b79d68 --- /dev/null +++ b/src/insns/store_32bit_cap.adoc @@ -0,0 +1,60 @@ +<<< + +[#SC,reftext="SC"] +==== SC + +See <>. + +[#CSC,reftext="CSC"] +==== CSC + +NOTE: The RV64 encoding is intended to also allocate the encoding for SQ for RV128. + +Synopsis:: +Store capability + +Capability Mode Mnemonics:: +`csc cs2, offset(cs1)` + +Legacy Mode Mnemonics:: +`sc cs2, offset(rs1)` + +include::xlen_variable_warning.adoc[] + +Encoding:: +include::wavedrom/storecap.adoc[] + +Capability Mode Description:: +Store the CLEN+1 bit value in `cs2` to memory. The capability in `cs1` +authorizes the operation. The effective address of the memory access is +obtained by adding the address of `cs1` to the sign-extended 12-bit offset. The +capability written to memory has the tag set to 0 if the tag of `cs2` is 0 or +`cs1` does not grant <>. + +Legacy Mode Description:: +Store the CLEN+1 bit value in `cs2` to memory. The capability +authorising the operation is <>. The effective address of the memory +access is obtained by adding `rs1` to the sign-extended 12-bit offset. The +capability written to memory has the tag set to 0 if `cs2` 's tag is 0 or +<> does not grant <>. + +:has_cap_data: +include::store_exceptions.adoc[] + +Prerequisites for CSC:: +{cheri_base_ext_name} + +Prerequisites for SC:: +{cheri_legacy_ext_name} + +CSC Operation:: ++ +-- +TODO +-- + +SC Operation:: ++ +-- +TODO +-- diff --git a/src/insns/store_32bit_fp.adoc b/src/insns/store_32bit_fp.adoc new file mode 100644 index 00000000..edc57c5c --- /dev/null +++ b/src/insns/store_32bit_fp.adoc @@ -0,0 +1,71 @@ +<<< +//[#insns-store-32bit-fp,reftext="Floating point store (CFSD, CFSW, CFSH, FSD, FSW, FSH), 32-bit encodings"] + +[#CFSD,reftext="CFSD"] +==== CFSD +See <>. + +[#CFSW,reftext="CFSW"] +==== CFSW +See <>. + +[#CFSH,reftext="CFSH"] +==== CFSH +See <>. + +[#FSD,reftext="FSD"] +==== FSD +See <>. + +[#FSW,reftext="FSW"] +==== FSW +See <>. + +<<< + +[#FSH,reftext="FSH"] +==== FSH + +Synopsis:: +Floating point stores (CFSD, CFSW, CFSH, FSD, FSW, FSH), 32-bit encodings + +Capability Mode Mnemonics:: +`cfsd/cfsw/cfsh fs2, offset(cs1)` + +Legacy Mode Mnemonics:: +`fsd/fsw/fsh fs2, offset(rs1)` + +Encoding:: +include::wavedrom/fpstore.adoc[] + +Capability Mode Description:: +Standard floating point store instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Standard floating point store instructions, authorised by the capability in <>. + +include::store_exceptions.adoc[] + +Prerequisites for CFSD:: +{cheri_base_ext_name}, and D + +Prerequisites for CFSW:: +{cheri_base_ext_name}, and F + +Prerequisites for CFSH:: +{cheri_base_ext_name}, and Zfh or Zfhmin + +Prerequisites for FSD:: +{cheri_legacy_ext_name}, and D + +Prerequisites for FSW:: +{cheri_legacy_ext_name}, and F + +Prerequisites for FSH:: +{cheri_legacy_ext_name}, and Zfh or Zfhmin + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/store_cap_cap_description.adoc b/src/insns/store_cap_cap_description.adoc new file mode 100644 index 00000000..4758a3fd --- /dev/null +++ b/src/insns/store_cap_cap_description.adoc @@ -0,0 +1,2 @@ +Capability Mode Description:: +Store capability instruction, authorised by the capability in `cs1`. Take a store/AMO address misaligned exception if not naturally aligned. diff --git a/src/insns/store_cap_int_description.adoc b/src/insns/store_cap_int_description.adoc new file mode 100644 index 00000000..b56ebd6a --- /dev/null +++ b/src/insns/store_cap_int_description.adoc @@ -0,0 +1,2 @@ +Legacy Mode Description:: +Store capability instruction, authorised by the capability in <>. Take a store/AMO address misaligned fault if not naturally aligned. diff --git a/src/insns/store_cond_32bit.adoc b/src/insns/store_cond_32bit.adoc new file mode 100644 index 00000000..8639a656 --- /dev/null +++ b/src/insns/store_cond_32bit.adoc @@ -0,0 +1,87 @@ +<<< +//[#insns-store-cond-32bit,reftext="store conditional (CSC.D, CSC.W, CSC.H, CSC.B, SC.D, SC.W, SC.H, SC.B), 32-bit encodings"] + +[#CSC_D,reftext="CSC.D"] +==== CSC.D +See <>. + +[#CSC_W,reftext="CSC.W"] +==== CSC.W +See <>. + +[#CSC_H,reftext="CSC.H"] +==== CSC.H +See <>. + +[#CSC_B,reftext="CSC.B"] +==== CSC.B +See <>. + +[#SC_D,reftext="SC.D"] +==== SC.D +See <>. + +[#SC_W,reftext="SC.W"] +==== SC.W +See <>. + +[#SC_H,reftext="SC.H"] +==== SC.H +See <>. + +<<< + +[#SC_B,reftext="SC.B"] +==== SC.B + +Synopsis:: +Store Conditional (CSC.D, CSC.W, CSC.H, CSC.B, SC.D, SC.W, SC.H, SC.B), 32-bit encodings + +Capability Mode Mnemonics (RV64):: +`csc.[d|w|h|b] rd, rs2, 0(cs1)` + +Capability Mode Mnemonics (RV32):: +`csc.[w|h|b] rd, rs2, 0(cs1)` + +Legacy Mode Mnemonics (RV64):: +`sc.[d|w|h|b] rd, rs2, 0(rs1)` + +Legacy Mode Mnemonics (RV32):: +`sc.[w|h|b] rd, rs2, 0(rs1)` + +Encoding:: +include::wavedrom/store_cond.adoc[] + +Capability Mode Description:: +Store conditional instructions, authorised by the capability in `cs1`. + +Legacy Mode Description:: +Store conditional instructions, authorised by the capability in <>. + +:store_cond: + +include::store_exceptions.adoc[] + +Prerequisites for CSC.D:: +RV64, and {cheri_base_ext_name} + +Prerequisites for CSC.W:: +{cheri_base_ext_name} + +Prerequisites for CSC.H, CSC.B:: +{cheri_base_ext_name}, and {lr_sc_bh_ext_name} + +Prerequisites for SC.D:: +RV64, and {cheri_legacy_ext_name} + +Prerequisites for SC.W:: +{cheri_legacy_ext_name} + +Prerequisites for SC.H, SC.B:: +{cheri_legacy_ext_name}, and {lr_sc_bh_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/store_cond_cap_32bit.adoc b/src/insns/store_cond_cap_32bit.adoc new file mode 100644 index 00000000..3329c1ae --- /dev/null +++ b/src/insns/store_cond_cap_32bit.adoc @@ -0,0 +1,50 @@ +<<< +//[#insns-store-cond-cap-32bit,reftext="store Conditional (CSC.C, SC.C), 32-bit encodings"] + +[#SC_C,reftext="SC.C"] +==== SC.C + +See <>. + +[#CSC_C,reftext="CSC.C"] +==== CSC.C + +NOTE: The RV64 encoding is intended to also allocate the encoding for SC.Q for RV128. + +Synopsis:: +Store Conditional (CSC.C, SC.C), 32-bit encodings + +include::xlen_variable_warning.adoc[] + +Capability Mode Mnemonics:: +`csc.c cd, cs2, 0(cs1)` + +Legacy Mode Mnemonics:: +`sc.c cd, cs2, 0(rs1)` + +Encoding:: +include::wavedrom/store_cond_cap.adoc[] + +Capability Mode Description:: +Store conditional instructions, authorised by the capability in `cs1`. + All misaligned store conditionals cause a store/AMO address misaligned exception to allow software emulation (Zam extension, see cite:[riscv-unpriv-spec]). + +Legacy Mode Description:: +Store conditional instructions, authorised by the capability in <>. + All misaligned store conditionals cause a store/AMO address misaligned exception to allow software emulation (Zam extension, see cite:[riscv-unpriv-spec]). + +:store_cond: + +include::store_exceptions.adoc[] + +Prerequisites for CSC.C:: +{cheri_base_ext_name} + +Prerequisites for SC.C:: +{cheri_legacy_ext_name} + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/store_exceptions.adoc b/src/insns/store_exceptions.adoc new file mode 100644 index 00000000..b8b8cd1e --- /dev/null +++ b/src/insns/store_exceptions.adoc @@ -0,0 +1,25 @@ +Exceptions:: +ifdef::store_cond[] +All misaligned store conditionals cause a store/AMO address misaligned exception to allow software emulation (if the Zam extension is supported, see cite:[riscv-unpriv-spec]), otherwise they take a store/AMO access fault exception. ++ +endif::[] +ifdef::has_cap_data[] +Misaligned address fault exception when the effective address is not aligned +to CLEN/8. ++ +endif::[] +CHERI fault exception when the authorising capability fails one of the checks +listed below; in this case, _CHERI data fault_ is reported in the <> or +<> TYPE field and the corresponding code is written to CAUSE. + +[%autowidth,options=header,align=center] +|============================================================================== +| CAUSE | Reason +| Tag violation | Authority capability tag set to 0 +| Seal violation | Authority capability is sealed +| Permission violation | Authority capability does not grant <> +| Length violation | At least one byte accessed is outside the authority capability bounds +|============================================================================== + +:!store_cond: +:!has_cap_data: diff --git a/src/insns/wavedrom/amo.adoc b/src/insns/wavedrom/amo.adoc new file mode 100644 index 00000000..37deb81c --- /dev/null +++ b/src/insns/wavedrom/amo.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', '.W=010', 'rv64: .D=011'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'SWAP=00001', 'ADD=00000', 'XOR=00100', 'AND=01100', 'OR=01000', 'MIN=10000', 'MAX=10100', 'MINU=11000', 'MAXU=11100'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/amoswap_cap.adoc b/src/insns/wavedrom/amoswap_cap.adoc new file mode 100644 index 00000000..be35e2fa --- /dev/null +++ b/src/insns/wavedrom/amoswap_cap.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'width', 'rv32: .C=011', 'rv64: .C=100'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'SWAP=00001'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/c-cb-format-ls.adoc b/src/insns/wavedrom/c-cb-format-ls.adoc new file mode 100644 index 00000000..63b783e3 --- /dev/null +++ b/src/insns/wavedrom/c-cb-format-ls.adoc @@ -0,0 +1,13 @@ +//c-cb-format-ls + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C1','C1']}, + {bits: 5, name: 'imm', type: 3, attr: ['5','offset[7:6|2:1|5]', 'offset[7:6|2:1|5]']}, + {bits: 3, name: 'rs1\'', type: 4, attr: ['3','src', 'src']}, + {bits: 3, name: 'imm', type: 3, attr: ['3','offset[8|4:3]', 'offset[8|4:3]'],}, + {bits: 3, name: 'funct3',type: 8, attr: ['3','C.BEQZ', 'C.BNEZ'],}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/c-ciw.adoc b/src/insns/wavedrom/c-ciw.adoc new file mode 100644 index 00000000..2aa675d1 --- /dev/null +++ b/src/insns/wavedrom/c-ciw.adoc @@ -0,0 +1,12 @@ +//c-ciw.adoc + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 3, attr: ['2','C0=00'],}, + {bits: 3, name: 'rd\'', type: 5, attr: ['3','dest'],}, + {bits: 8, name: 'nzimm', type: 5, attr: ['8','uimm[5:4|9:6|2|3]!=0']}, + {bits: 3, name: 'funct3',type: 5, attr: ['3','cap: C.CINCOFFSET4CSPN=000','leg: C.ADDI4SPN=000']}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/c-cj-format-ls.adoc b/src/insns/wavedrom/c-cj-format-ls.adoc new file mode 100644 index 00000000..3f59bbb5 --- /dev/null +++ b/src/insns/wavedrom/c-cj-format-ls.adoc @@ -0,0 +1,11 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C1=01']}, + {bits: 11, name: 'imm', type: 2, attr: ['11','offset[11|4|9:8|10|6|7|3:1|5]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3','cap: C.CJ=101','leg: C.J=101']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-cjal-format-ls.adoc b/src/insns/wavedrom/c-cjal-format-ls.adoc new file mode 100644 index 00000000..f7279c8a --- /dev/null +++ b/src/insns/wavedrom/c-cjal-format-ls.adoc @@ -0,0 +1,11 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C1=01']}, + {bits: 11, name: 'imm', type: 2, attr: ['11','offset[11|4|9:8|10|6|7|3:1|5]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3','cap rv32: C.CJAL=001','leg rv32: C.JAL=001']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-cjalr-format-ls.adoc b/src/insns/wavedrom/c-cjalr-format-ls.adoc new file mode 100644 index 00000000..83cbe671 --- /dev/null +++ b/src/insns/wavedrom/c-cjalr-format-ls.adoc @@ -0,0 +1,12 @@ +//These instructions use the CR format. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'rs2', type: 4, attr: ['5','0']}, + {bits: 5, name: 'rs1', type: 4, attr: ['5','src!=0']}, + {bits: 4, name: 'funct4', type: 8, attr: ['4', 'cap: C.CJALR=1001', 'leg: C.JALR=1001']}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/c-clc-clcsp.adoc b/src/insns/wavedrom/c-clc-clcsp.adoc new file mode 100644 index 00000000..e5878477 --- /dev/null +++ b/src/insns/wavedrom/c-clc-clcsp.adoc @@ -0,0 +1,24 @@ +//c-sp load and store, css format--is this correct? + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'rs2\'', type: 3, attr: ['3', 'src']}, + {bits: 2, name: 'imm', type: 2, attr: ['2', 'offset[7:6]']}, + {bits: 3, name: 'rs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'imm', types:3, attr: ['3', 'offset[5:3]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap rv64: C.CLC=001','cap rv32: C.CFLD=001']}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src',]}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:3|8:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3','cap rv64: C.CLCSP=001']}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/c-cr-format-ls.adoc b/src/insns/wavedrom/c-cr-format-ls.adoc new file mode 100644 index 00000000..24444be6 --- /dev/null +++ b/src/insns/wavedrom/c-cr-format-ls.adoc @@ -0,0 +1,12 @@ +//These instructions use the CR format. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'rs2', type: 4, attr: ['5','0']}, + {bits: 5, name: 'rs1', type: 4, attr: ['5','src!=0']}, + {bits: 4, name: 'funct4', type: 8, attr: ['4','cap: C.CJR=1000', 'leg: C.JR=1000']}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/c-cs-format-ls.adoc b/src/insns/wavedrom/c-cs-format-ls.adoc new file mode 100644 index 00000000..ead88c3b --- /dev/null +++ b/src/insns/wavedrom/c-cs-format-ls.adoc @@ -0,0 +1,16 @@ +//## 16.X Load and Store Instructions +//### c-cs-format-ls + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'rs2\'/cs2\'', type: 3, attr: ['3', 'src']}, + {bits: 2, name: 'uimm', type: 2, attr: ['2', 'offset[2|6]','offset[2|6]','offset[7:6]','offset[7:6]']}, + {bits: 3, name: 'rs1\'/cs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'uimm', types:3, attr: ['3', 'offset[5:3]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap: C.CSW=110', 'leg: C.SW=110', 'cap rv64: C.CSD=111', 'leg rv64: C.SD=111']}, +], config: {bits: 16}} +.... + + diff --git a/src/insns/wavedrom/c-int-reg-immed.adoc b/src/insns/wavedrom/c-int-reg-immed.adoc new file mode 100644 index 00000000..799aaa14 --- /dev/null +++ b/src/insns/wavedrom/c-int-reg-immed.adoc @@ -0,0 +1,12 @@ +//c-int-reg-immed.adoc + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 3, attr: ['2','C1=01']}, + {bits: 5, name: 'nzimm[4|6|8:7|5]', type: 1, attr: ['5','offset[4|6|8:7|5]']}, + {bits: 5, name: 'rd/rs1', type: 5, attr: ['5','2']}, + {bits: 1, name: 'nzimm[9]', type: 5, attr: ['1','[9]']}, + {bits: 3, name: 'funct3', type: 5, attr: ['3','cap: C.CINCOFFSET16CSP=011', 'leg: C.ADDI16SP=011']}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/c-sp-load-cap.adoc b/src/insns/wavedrom/c-sp-load-cap.adoc new file mode 100644 index 00000000..5ff0f84c --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-cap.adoc @@ -0,0 +1,25 @@ +//## 16.3 Load and Store Instructions +//### Stack-Pointer-Based Loads and Stores + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'imm', type: 5, attr: ['5','offset[4:3|8:6]','offset[4|9:6]']}, + {bits: 5, name: 'cd!=0', type: 5, attr: ['5','dest']}, + {bits: 1, name: 'imm', type: 1, attr: ['1','[5]',]}, + {bits: 3, name: 'funct3', type: 3, attr: ['3', 'cap rv32: C.CLCSP=011', 'cap rv64: C.CLCSP=001']}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'rd\'', type: 3, attr: ['3', 'dest']}, + {bits: 2, name: 'imm', type: 2, attr: ['2', 'offset[7:6]']}, + {bits: 3, name: 'cs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'imm', types:3, attr: ['3', 'offset[5:3]','offset[5:4|8]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap rv32: C.CLC=011','cap rv64: C.CLC=001']}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/c-sp-load-css-dp-sprel.adoc b/src/insns/wavedrom/c-sp-load-css-dp-sprel.adoc new file mode 100644 index 00000000..ded26743 --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-css-dp-sprel.adoc @@ -0,0 +1,13 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:3|8:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'leg: C.FLDSP=001', 'cap rv32: C.CFLDSP=001']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-sp-load-css-dp.adoc b/src/insns/wavedrom/c-sp-load-css-dp.adoc new file mode 100644 index 00000000..53e4f2de --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-css-dp.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'frd`', attr: ['3', 'dest'], type: 3}, + {bits: 2, name: 'imm', attr: ['2', 'offset[7:6]'], type: 2}, + {bits: 3, name: 'rs1`/cs1`', attr: ['3', 'base'], type: 2}, + {bits: 3, name: 'imm', attr: ['3', 'offset[5:3]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'C.FLD=001', 'cap rv32: C.CFLD=001'], type: 8}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/c-sp-load-css-fp-sprel.adoc b/src/insns/wavedrom/c-sp-load-css-fp-sprel.adoc new file mode 100644 index 00000000..9bd5c1c4 --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-css-fp-sprel.adoc @@ -0,0 +1,13 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:2|7:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'leg rv32: C.FLWSP=011']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-sp-load-css-fp.adoc b/src/insns/wavedrom/c-sp-load-css-fp.adoc new file mode 100644 index 00000000..5350f39b --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-css-fp.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'rd\'', type: 3, attr: ['3', 'dest']}, + {bits: 2, name: 'imm', type: 2, attr: ['2', 'offset[2|6]']}, + {bits: 3, name: 'rs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'imm', types:3, attr: ['3', 'offset[5:3]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'leg rv32: C.FLW=011']}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/c-sp-load-store-css.adoc b/src/insns/wavedrom/c-sp-load-store-css.adoc new file mode 100644 index 00000000..2d1da543 --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-store-css.adoc @@ -0,0 +1,14 @@ +//c-sp load and store, css format--is this correct? + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'rs2/cs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:3|8:6]', 'offset[5:3|8:6]', 'offset[5:2|7:6]','offset[5:2|7:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap rv64: C.CSDSP=111', 'leg rv64: C.SDSP=111', 'cap: C.CSWSP=110', 'leg: C.SWSP=110']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-sp-load-store-fp.adoc b/src/insns/wavedrom/c-sp-load-store-fp.adoc new file mode 100644 index 00000000..518e4a79 --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-store-fp.adoc @@ -0,0 +1,13 @@ +//## 16.3 Load and Store Instructions +//### Stack-Pointer-Based Loads and Stores + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'imm', type: 5, attr: ['5', 'offset[4:2|7:6]']}, + {bits: 5, name: 'rd', type: 5, attr: ['5','dest']}, + {bits: 1, name: 'imm', type: 1, attr: ['1','[5]']}, + {bits: 3, name: 'funct3', type: 3, attr: ['3', 'leg rv32: C.FLWSP=011']}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/c-sp-load-store.adoc b/src/insns/wavedrom/c-sp-load-store.adoc new file mode 100644 index 00000000..0ddf2f44 --- /dev/null +++ b/src/insns/wavedrom/c-sp-load-store.adoc @@ -0,0 +1,14 @@ +//## 16.3 Load and Store Instructions +//### Stack-Pointer-Based Loads and Stores +//C.CLWSP, C.CLDSP, C.LWSP, C.LDSP + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'imm', type: 5, attr: ['5', 'offset[4:2|7:6]','offset[4:2|7:6]','offset[4:3|8:6]','offset[4:3|8:6]']}, + {bits: 5, name: 'rd', type: 5, attr: ['5','dest!=0']}, + {bits: 1, name: 'imm', type: 1, attr: ['1','[5]']}, + {bits: 3, name: 'funct3', type: 3, attr: ['3', 'cap: C.CLWSP=010', 'leg: C.LWSP=010', 'cap rv64: C.CLDSP=011', 'leg rv64: C.LDSP=011']}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/c-sp-store-cap.adoc b/src/insns/wavedrom/c-sp-store-cap.adoc new file mode 100644 index 00000000..5e4e5ced --- /dev/null +++ b/src/insns/wavedrom/c-sp-store-cap.adoc @@ -0,0 +1,21 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'cs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:2|7:6]','offset[5:4|9:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap rv32: C.CSCSP=111', 'cap rv64: C.CSCSP=101']}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'cs2\'', type: 3, attr: ['3', 'src']}, + {bits: 2, name: 'imm', type: 2, attr: ['2', 'offset[2|6]','offset[7:6]']}, + {bits: 3, name: 'cs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'imm', types:3, attr: ['3', 'offset[5:3]','offset[5:4|8]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'cap rv32: C.CSC=111','cap rv64: C.CSC=101']}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/c-sp-store-css-fp-dp-sprel.adoc b/src/insns/wavedrom/c-sp-store-css-fp-dp-sprel.adoc new file mode 100644 index 00000000..458d5ea8 --- /dev/null +++ b/src/insns/wavedrom/c-sp-store-css-fp-dp-sprel.adoc @@ -0,0 +1,14 @@ +//c-sp load and store, css format--is this correct? + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:3|8:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'int C.FSDSP=101', 'cap rv32: C.CFSDSP=101']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-sp-store-css-fp-dp.adoc b/src/insns/wavedrom/c-sp-store-css-fp-dp.adoc new file mode 100644 index 00000000..f8c3d97f --- /dev/null +++ b/src/insns/wavedrom/c-sp-store-css-fp-dp.adoc @@ -0,0 +1,11 @@ +//c-sp load and store, css format--is this correct? + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C0=00']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:3|8:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'int C.FSD=101', 'cap rv32: C.CFSD=101']}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/c-sp-store-css-fp-sprel.adoc b/src/insns/wavedrom/c-sp-store-css-fp-sprel.adoc new file mode 100644 index 00000000..ee42c839 --- /dev/null +++ b/src/insns/wavedrom/c-sp-store-css-fp-sprel.adoc @@ -0,0 +1,14 @@ +//c-sp load and store, css format--is this correct? + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2','C2=10']}, + {bits: 5, name: 'fs2', type: 4, attr: ['5','src']}, + {bits: 6, name: 'imm', type: 3, attr: ['6','offset[5:2|7:6]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'leg rv32: C.FSWSP=111']}, +], config: {bits: 16}} +.... + + + diff --git a/src/insns/wavedrom/c-sp-store-css-fp.adoc b/src/insns/wavedrom/c-sp-store-css-fp.adoc new file mode 100644 index 00000000..0ee51f97 --- /dev/null +++ b/src/insns/wavedrom/c-sp-store-css-fp.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C0=00']}, + {bits: 3, name: 'rs2\'', type: 3, attr: ['3', 'src']}, + {bits: 2, name: 'uimm', type: 2, attr: ['2', 'offset[2|6]']}, + {bits: 3, name: 'rs1\'', type: 3, attr: ['3', 'base']}, + {bits: 3, name: 'uimm', types:3, attr: ['3', 'offset[5:3]']}, + {bits: 3, name: 'funct3', type: 8, attr: ['3', 'leg rv32: C.FSW=111']}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/c_mv.adoc b/src/insns/wavedrom/c_mv.adoc new file mode 100644 index 00000000..27bc94c8 --- /dev/null +++ b/src/insns/wavedrom/c_mv.adoc @@ -0,0 +1,11 @@ + +[wavedrom, ,svg] + +.... +{reg: [ + {bits: 2, name: 'op', type: 8, attr: ['2', 'C2=10'],}, + {bits: 5, name: 'rs2/cs2',type: 4, attr: ['5', 'src!=0'],}, + {bits: 5, name: 'rd/cd', type: 7, attr: ['5', 'dest!=0'],}, + {bits: 4, name: 'funct4', type: 8, attr: ['4', 'leg: C.MV=1000', 'cap: C.CMove=1000'],}, +], config: {bits: 16}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/candperm.adoc b/src/insns/wavedrom/candperm.adoc new file mode 100644 index 00000000..173def6d --- /dev/null +++ b/src/insns/wavedrom/candperm.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CANDPERM=010'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'mask'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CANDPERM=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cbuildcap.adoc b/src/insns/wavedrom/cbuildcap.adoc new file mode 100644 index 00000000..3309f271 --- /dev/null +++ b/src/insns/wavedrom/cbuildcap.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CBUILDCAP=101'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src2'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CBUILDCAP=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cclear.adoc b/src/insns/wavedrom/cclear.adoc new file mode 100644 index 00000000..8fdfde08 --- /dev/null +++ b/src/insns/wavedrom/cclear.adoc @@ -0,0 +1,13 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'm[4:0]', attr: ['5', 'mask'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CClear=000'], type: 8}, + {bits: 3, name: 'm[7:5]', attr: ['3', 'mask'], type: 4}, + {bits: 2, name: 'q[1:0]', attr: ['2', 'quarter'], type: 3}, + {bits: 5, name: 'funct5', attr: ['5', 'CClear=01110'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CClear=1111111'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cgetbase.adoc b/src/insns/wavedrom/cgetbase.adoc new file mode 100644 index 00000000..adffc243 --- /dev/null +++ b/src/insns/wavedrom/cgetbase.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CGETBASE=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CGETBASE=00101'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CGETBASE=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cgethigh.adoc b/src/insns/wavedrom/cgethigh.adoc new file mode 100644 index 00000000..399ccb7e --- /dev/null +++ b/src/insns/wavedrom/cgethigh.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CGETHIGH=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CGETHIGH=00100'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CGETHIGH=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cgetlen.adoc b/src/insns/wavedrom/cgetlen.adoc new file mode 100644 index 00000000..30b249d6 --- /dev/null +++ b/src/insns/wavedrom/cgetlen.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CGETLEN=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CGETLEN=00110'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CGETLEN=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cgetperm.adoc b/src/insns/wavedrom/cgetperm.adoc new file mode 100644 index 00000000..1d8dce4e --- /dev/null +++ b/src/insns/wavedrom/cgetperm.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CGETPERM=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CGETPERM=00001'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CGETPERM=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cgettag.adoc b/src/insns/wavedrom/cgettag.adoc new file mode 100644 index 00000000..2d17dd87 --- /dev/null +++ b/src/insns/wavedrom/cgettag.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CGETTAG=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CGETTAG=00000'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CGETTAG=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cincoffset.adoc b/src/insns/wavedrom/cincoffset.adoc new file mode 100644 index 00000000..6ecdf1d4 --- /dev/null +++ b/src/insns/wavedrom/cincoffset.adoc @@ -0,0 +1,24 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CINCOFFSET=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'rs2!=x0', attr: ['5', 'increment'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CINCOFFSET=0000110'], type: 3}, +]} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP-IMM-32=0011011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CINCOFFSETIMM=010'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type:4}, + {bits: 12, name: 'imm', attr: ['12','imm'], type: 4}, +]} +.... + diff --git a/src/insns/wavedrom/cmove.adoc b/src/insns/wavedrom/cmove.adoc new file mode 100644 index 00000000..e3038281 --- /dev/null +++ b/src/insns/wavedrom/cmove.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CINCOFFSET=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'zero', attr: ['5', 'rs2=x0'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CINCOFFSET=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cram.adoc b/src/insns/wavedrom/cram.adoc new file mode 100644 index 00000000..cd97df69 --- /dev/null +++ b/src/insns/wavedrom/cram.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CRAM=000'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CRAM=00111'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CRAM=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cseal.adoc b/src/insns/wavedrom/cseal.adoc new file mode 100644 index 00000000..6f0cc124 --- /dev/null +++ b/src/insns/wavedrom/cseal.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSEAL=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CSEAL=01000'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSEAL=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csetaddr.adoc b/src/insns/wavedrom/csetaddr.adoc new file mode 100644 index 00000000..bb5d7a17 --- /dev/null +++ b/src/insns/wavedrom/csetaddr.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETADDR=001'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'address'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETADDR=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csetbounds_32bit.adoc b/src/insns/wavedrom/csetbounds_32bit.adoc new file mode 100644 index 00000000..c5eade43 --- /dev/null +++ b/src/insns/wavedrom/csetbounds_32bit.adoc @@ -0,0 +1,25 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETBOUNDS=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src2'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETBOUNDS=0000111'], type: 3}, +]} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP-IMM=0010011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETBOUNDSIMM=101'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'uimm', attr: ['5', 'uimm'], type: 3}, + {bits: 1, name: 's', attr: ['1', 'scaled'], type: 3}, + {bits: 6, name: 'funct6', attr: ['6', 'CSETBOUNDSIMM','=000001'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csetboundsinexact_32bit.adoc b/src/insns/wavedrom/csetboundsinexact_32bit.adoc new file mode 100644 index 00000000..23093d2d --- /dev/null +++ b/src/insns/wavedrom/csetboundsinexact_32bit.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETBOUNDSINEX=001'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src2'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETBOUNDSINEX=0000111'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csetequalexact.adoc b/src/insns/wavedrom/csetequalexact.adoc new file mode 100644 index 00000000..cc1a07da --- /dev/null +++ b/src/insns/wavedrom/csetequalexact.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETEQUALEXACT=100'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src2'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETEQUALEXACT=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csethigh.adoc b/src/insns/wavedrom/csethigh.adoc new file mode 100644 index 00000000..513306d4 --- /dev/null +++ b/src/insns/wavedrom/csethigh.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETHIGH=011'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'metadata'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETHIGH=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csetmode.adoc b/src/insns/wavedrom/csetmode.adoc new file mode 100644 index 00000000..42e469ea --- /dev/null +++ b/src/insns/wavedrom/csetmode.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSETMODE=000'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'CSETMODE=0011'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CSETMODE=0001000'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/csr-instr.adoc b/src/insns/wavedrom/csr-instr.adoc new file mode 100644 index 00000000..32f82366 --- /dev/null +++ b/src/insns/wavedrom/csr-instr.adoc @@ -0,0 +1,24 @@ +//# 10 "Zicsr", Control and Status Register (CSR) Instructions, Version 2.0 +//## 10.1 CSR Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM=1110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSRRS=010', 'CSRRC=011', 'CSRRWI=101', 'CSRRSI=110', 'CSRRCI=111'], type: 8}, + {bits: 5, name: 'rs1/uimm', attr: ['5', 'source', 'source', 'uimm[4:0]', 'uimm[4:0]', 'uimm[4:0]'], type: 4}, + {bits: 12, name: 'csr', attr: ['12', 'source/dest CSR'], type: 4}, +]} +.... + +//[wavedrom, ,] +//.... +//{reg: [ +// {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM','SYSTEM','SYSTEM'], type: 8}, +// {bits: 5, name: 'rd', attr: ['3', 'dest','dest', 'dest' ], type: 2}, +// {bits: 3, name: 'funct3', attr: ['3', 'CSRRWI', 'CSRRSI', 'CSRRCI'], type: 8}, +// {bits: 5, name: 'rs1', attr: ['5', 'uimm[4:0]','uimm[4:0]', 'uimm[4:0]'], type: 3}, +// {bits: 12, name: 'csr', attr: ['12', 'source/dest','source/dest','source/dest'], type: 4}, +//]} +//.... diff --git a/src/insns/wavedrom/csrr.adoc b/src/insns/wavedrom/csrr.adoc new file mode 100644 index 00000000..c3a86f64 --- /dev/null +++ b/src/insns/wavedrom/csrr.adoc @@ -0,0 +1,11 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM=1110011 '], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest',], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSRRW', 'CSRRS', 'CSRRC', 'CSRRWI', 'CSRRSI', 'CSRRCI'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'source', 'source', 'source', 'uimm[4:0]', 'uimm[4:0]', 'uimm[4:0]'], type: 4}, + {bits: 12, name: 'csr', attr: ['12', 'source/dest'], type: 4}, +]} +.... diff --git a/src/insns/wavedrom/csrw-instr.adoc b/src/insns/wavedrom/csrw-instr.adoc new file mode 100644 index 00000000..d0590867 --- /dev/null +++ b/src/insns/wavedrom/csrw-instr.adoc @@ -0,0 +1,24 @@ +//# 10 "Zicsr", Control and Status Register (CSR) Instructions, Version 2.0 +//## 10.1 CSR Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM=1110011'], type: 8}, + {bits: 5, name: 'rd/cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CSRRW=001'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'source'], type: 4}, + {bits: 12, name: 'csr', attr: ['12', 'source/dest CSR'], type: 4}, +]} +.... + +//[wavedrom, ,] +//.... +//{reg: [ +// {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM','SYSTEM','SYSTEM'], type: 8}, +// {bits: 5, name: 'rd', attr: ['3', 'dest','dest', 'dest' ], type: 2}, +// {bits: 3, name: 'funct3', attr: ['3', 'CSRRWI', 'CSRRSI', 'CSRRCI'], type: 8}, +// {bits: 5, name: 'rs1', attr: ['5', 'uimm[4:0]','uimm[4:0]', 'uimm[4:0]'], type: 3}, +// {bits: 12, name: 'csr', attr: ['12', 'source/dest','source/dest','source/dest'], type: 4}, +//]} +//.... diff --git a/src/insns/wavedrom/ct-conditional.adoc b/src/insns/wavedrom/ct-conditional.adoc new file mode 100644 index 00000000..290a8c21 --- /dev/null +++ b/src/insns/wavedrom/ct-conditional.adoc @@ -0,0 +1,13 @@ +//### Conditional Branches + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'BRANCH=1100011'], type: 8}, + {bits: 5, name: 'imm[4:1|11]', attr: ['5', 'offset[4:1|11]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'BEQ=000','BNE=001','BLT=100','BGE=101','BLTU=110','BGEU=111'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src2'], type: 4}, + {bits: 7, name: 'imm[12|10:5]', attr: ['7', 'offset[12|10:5]'], type: 3}, +], config:{fontsize: 10}} +.... diff --git a/src/insns/wavedrom/ct-unconditional-2.adoc b/src/insns/wavedrom/ct-unconditional-2.adoc new file mode 100644 index 00000000..b4a17de5 --- /dev/null +++ b/src/insns/wavedrom/ct-unconditional-2.adoc @@ -0,0 +1,12 @@ +//ct-unconditional-2 + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'cap: CJALR=1100111', 'leg: JALR=1100111'], type: 8}, + {bits: 5, name: 'cd/rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', '0'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5', 'base'], type: 4}, + {bits: 12, name: 'imm[11:0]', attr: ['12', 'offset[11:0]'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/ct-unconditional-jalr-cap.adoc b/src/insns/wavedrom/ct-unconditional-jalr-cap.adoc new file mode 100644 index 00000000..bc5c9600 --- /dev/null +++ b/src/insns/wavedrom/ct-unconditional-jalr-cap.adoc @@ -0,0 +1,11 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'JALR=1100111'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'cap: JALR.PCC=001', 'leg: JALR.CAP=001'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5', 'base'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12', 'cap: JALR.PCC=00..00', 'leg: JALR.CAP=00..00'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/ct-unconditional.adoc b/src/insns/wavedrom/ct-unconditional.adoc new file mode 100644 index 00000000..06b53fcb --- /dev/null +++ b/src/insns/wavedrom/ct-unconditional.adoc @@ -0,0 +1,15 @@ +//## 2.5 Control Transfer Instructions +//### Unconditional Jumps + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'cap: CJAL=1101111', 'leg: JAL=1101111'], type: 8}, + {bits: 5, name: 'cd/rd', attr: ['5', 'dest'], type: 2}, + {bits: 8, name: 'imm[19:12]', attr: ['8', 'offset[19:12]'], type: 3}, + {bits: 1, name: '[11]', attr: ['1'], type: 3}, + {bits: 10, name: 'imm[10:1]', attr: ['10', 'offset[20:1]'], type: 3}, + {bits: 1, name: '[20]', attr: ['1'], type: 3}, +], config:{fontsize: 12}} +.... + diff --git a/src/insns/wavedrom/ctestsubset.adoc b/src/insns/wavedrom/ctestsubset.adoc new file mode 100644 index 00000000..bfff2219 --- /dev/null +++ b/src/insns/wavedrom/ctestsubset.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CTESTSUBSET=110'], type: 8}, + {bits: 5, name: 'cs1', attr: ['5', 'src1'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src2'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CTESTSUBSET=0000110'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/cvlce_ew.adoc b/src/insns/wavedrom/cvlce_ew.adoc new file mode 100644 index 00000000..16a6789d --- /dev/null +++ b/src/insns/wavedrom/cvlce_ew.adoc @@ -0,0 +1,16 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 7, '(LOADFP)'], type: 8}, + {bits: 5, name: 'vd', attr: ['5', 'destination of load'], type: 2}, + {bits: 3, name: 'width', attr: ['3', '08b = 000', '16b = 101', '32b = 110', '64b = 111'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'lumop', attr: ['5', 7, '(capability)'], type: 8}, + {bits: 1, name: 'vm', attr: ['1', 1], type: 8}, + {bits: 2, name: 'mop', attr: ['2', 0], type: 8}, + {bits: 1, name: 'mew', attr: ['1', 0], type: 8, rotate: -60}, + {bits: 3, name: 'nf', attr: ['3', 0], type: 8} +]} +.... + +NOTE: The value of `lumop` indicating unit-stride load capability is **TBC**. diff --git a/src/insns/wavedrom/cvmv_nr_r.adoc b/src/insns/wavedrom/cvmv_nr_r.adoc new file mode 100644 index 00000000..a3fc231a --- /dev/null +++ b/src/insns/wavedrom/cvmv_nr_r.adoc @@ -0,0 +1,17 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 87, '(VECTOR)'], type: 8}, + {bits: 5, name: 'vd', attr: ['5'], type: 2}, + {bits: 3, attr: ['3', 3, '(OPIVI)'], type: 8}, + {bits: 3, name: 'nr', attr: ['3', '1 = 000', '2 = 001', '4 = 011', '8 = 111'], type: 8}, + {bits: 2, attr: ['2', 3], type: 8}, + {bits: 5, name: 'vs2', attr: ['5'], type: 4}, + {bits: 1, name: 'vm', attr: ['1', 1], type: 8}, + {bits: 6, name: 'funct6', attr: ['6', 39], type: 8} +]} +.... + +NOTE: This encoding is **TBC**. The proposal here is to use essentially the same + encoding as `vmv.v`, where the lower 3 bits of the `imm[4:0]` field encode + ``. However, here the the upper 2 bits of the `imm[4:0]` are set to '11'. diff --git a/src/insns/wavedrom/cvsce_ew.adoc b/src/insns/wavedrom/cvsce_ew.adoc new file mode 100644 index 00000000..876bd48e --- /dev/null +++ b/src/insns/wavedrom/cvsce_ew.adoc @@ -0,0 +1,16 @@ +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 39, '(STOREFP)'], type: 8}, + {bits: 5, name: 'vs3', attr: ['5', 'store data'], type: 2}, + {bits: 3, name: 'width', attr: ['3', '08b = 000', '16b = 101', '32b = 110', '64b = 111'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'sumop', attr: ['5', 7, '(capability)'], type: 8}, + {bits: 1, name: 'vm', attr: ['1', 1], type: 8}, + {bits: 2, name: 'mop', attr: ['2', 0], type: 8}, + {bits: 1, name: 'mew', attr: ['1', 0], type: 8, rotate: -60}, + {bits: 3, name: 'nf', attr: ['3', 0], type: 8} +]} +.... + +NOTE: The value of `sumop` indicating unit-stride store capability is **TBC**. diff --git a/src/insns/wavedrom/dret.adoc b/src/insns/wavedrom/dret.adoc new file mode 100644 index 00000000..69a34cb5 --- /dev/null +++ b/src/insns/wavedrom/dret.adoc @@ -0,0 +1,13 @@ +// + +[wavedrom, ,svg] + +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','SYSTEM=111011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5','0'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3','PRIV=0'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5','0'], type: 4}, + {bits: 12, name: 'funct12', attr: ['12','DRET=011110110010'], type: 8}, +], config: {bits: 32}} +.... \ No newline at end of file diff --git a/src/insns/wavedrom/fpload.adoc b/src/insns/wavedrom/fpload.adoc new file mode 100644 index 00000000..557ab888 --- /dev/null +++ b/src/insns/wavedrom/fpload.adoc @@ -0,0 +1,14 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','LOAD-FP=0000111'], type: 8}, + {bits: 5, name: 'frd', attr: ['5','dest'], type: 2}, + {bits: 3, name: 'width', attr: ['3','cap: CFLD=011','cap: CFLW=010', 'cap: CFLH=001','leg: FLD=011','leg: FLW=010', 'leg: FLH=001'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5','base'], type: 4}, + {bits: 12, name: 'imm[11:0]', attr: ['12','offset[11:0]'], type: 3}, +]} +.... + + + diff --git a/src/insns/wavedrom/fpstore.adoc b/src/insns/wavedrom/fpstore.adoc new file mode 100644 index 00000000..9a2f31c6 --- /dev/null +++ b/src/insns/wavedrom/fpstore.adoc @@ -0,0 +1,13 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','STORE-FP=0100111'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5','offset[4:0]'], type: 3}, + {bits: 3, name: 'width', attr: ['3','cap: CFSD=011','cap: CFSW=010', 'cap: CFSH=001','leg: FSD=011','leg: FSW=010', 'leg: FSH=001'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5','base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5','src'], type: 4}, + {bits: 7, name: 'imm[11:5]', attr: ['7','offset[11:5]'], type: 3}, +]} +.... + diff --git a/src/insns/wavedrom/load.adoc b/src/insns/wavedrom/load.adoc new file mode 100644 index 00000000..f5cef8f1 --- /dev/null +++ b/src/insns/wavedrom/load.adoc @@ -0,0 +1,12 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'LOAD=0000011'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'width', 'cap: CLB=000', 'leg: LB=000', 'cap: CLH=001', 'leg: LH=001', 'cap: CLW=010', 'leg: LW=010', 'cap: CLBU=100', 'leg: LBU=100', 'cap: CLHU=101', 'leg: LHU=101', 'cap rv64: CLWU=110', 'leg rv64: LWU=110', 'cap rv64: CLD=011', 'leg rv64: LD=011'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 12, name: 'imm[11:0]', attr: ['12', 'offset[11:0]'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/load_res.adoc b/src/insns/wavedrom/load_res.adoc new file mode 100644 index 00000000..caffcd6f --- /dev/null +++ b/src/insns/wavedrom/load_res.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', '.B=000', '.H=001', '.W=010', 'rv64: .D=011'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'cap: CLR.*=00000', 'leg: LR.*=00000'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'cap: CLR.*=00010', 'leg: LR.*=00010'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/load_res_cap.adoc b/src/insns/wavedrom/load_res_cap.adoc new file mode 100644 index 00000000..8db8724d --- /dev/null +++ b/src/insns/wavedrom/load_res_cap.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'rv32: .C=011', 'rv64: .C=100'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'cap: CLR.*=00000', 'leg: LR.*=00000'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'cap: CLR.*=00010', 'leg: LR.*=00010'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/loadcap.adoc b/src/insns/wavedrom/loadcap.adoc new file mode 100644 index 00000000..75d2f91b --- /dev/null +++ b/src/insns/wavedrom/loadcap.adoc @@ -0,0 +1,12 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'MISCMEM=0001111', 'MISCMEM=0001111', 'LOAD=0000011', 'LOAD=0000011'], type: 8}, + {bits: 5, name: 'cd', attr: ['5', 'dest!=c0'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'cap rv64: CLC=100', 'leg rv64: LC=100', 'cap rv32: CLC=011','leg rv32: LC=011'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 12, name: 'imm[11:0]', attr: ['12', 'offset[11:0]'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/modeswitch_16bit.adoc b/src/insns/wavedrom/modeswitch_16bit.adoc new file mode 100644 index 00000000..7dde7997 --- /dev/null +++ b/src/insns/wavedrom/modeswitch_16bit.adoc @@ -0,0 +1,14 @@ +//ct-unconditional-2 + +[wavedrom, ,svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['2', 'C1=1'] }, + { bits: 3, name: 0x7, attr: ['3', 'C.CMODESWITCH'] }, + { bits: 2, name: 0x0, attr: ['2', 'FUNCT2'] }, + { bits: 3, name: 0x0, attr: ['3', 'FUNCT3'] }, + { bits: 3, name: 0x7, attr: ['3', 'FUNCT3'] }, + { bits: 3, name: 0x4, attr: ['3', 'FUNCT3'] }, +],config:{bits:16}} +.... + diff --git a/src/insns/wavedrom/modeswitch_32bit.adoc b/src/insns/wavedrom/modeswitch_32bit.adoc new file mode 100644 index 00000000..646669bf --- /dev/null +++ b/src/insns/wavedrom/modeswitch_32bit.adoc @@ -0,0 +1,12 @@ + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'OP=0110011'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5', 'CMS=000'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'CMS=001'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5', 'CMS=00000'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'CMS=00000'], type: 3}, + {bits: 7, name: 'funct7', attr: ['7', 'CMS=0001001'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/reg-based-ldnstr-Zcb.adoc b/src/insns/wavedrom/reg-based-ldnstr-Zcb.adoc new file mode 100644 index 00000000..86547cba --- /dev/null +++ b/src/insns/wavedrom/reg-based-ldnstr-Zcb.adoc @@ -0,0 +1,36 @@ +//Register-Based loads and Stores + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rd\'/cd\'', attr: ['3', 'dest'], type: 3}, + {bits: 1, name: 'uimm[1]', attr: ['1', 'offset[1]'], type: 2}, + {bits: 1, name: 'funct1', attr: ['1', '1'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 6, name: 'funct6', attr: ['6', 'cap: C.CLH=100001', 'leg: C.LH=100001'], type: 8}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rd\'/cd\'', attr: ['3', 'dest'], type: 3}, + {bits: 1, name: 'uimm[1]', attr: ['1', 'offset[1]'], type: 2}, + {bits: 1, name: 'funct1', attr: ['1', '0'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 6, name: 'funct6', attr: ['6', 'cap: C.CLHU=100001', 'leg: C.LHU=100001'], type: 8}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rd\'/cd\'', attr: ['3', 'dest'], type: 3}, + {bits: 2, name: 'uimm[0|1]', attr: ['2', 'offset[0|1]'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 6, name: 'funct6', attr: ['6', 'cap: C.CLBU=100000', 'leg: C.LBU=100000'], type: 8}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/reg-based-ldnstr.adoc b/src/insns/wavedrom/reg-based-ldnstr.adoc new file mode 100644 index 00000000..0216fbf3 --- /dev/null +++ b/src/insns/wavedrom/reg-based-ldnstr.adoc @@ -0,0 +1,14 @@ +//Register-Based loads and Stores + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rd\'', attr: ['3', 'dest'], type: 3}, + {bits: 2, name: 'imm', attr: ['2', 'offset[2|6]','offset[2|6]', 'offset[7:6]','offset[7:6]'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 3, name: 'imm', attr: ['3', 'offset[5:3]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'cap: C.CLW=010', 'leg: C.LW=010', 'cap rv64: C.CLD=011', 'leg rv64: C.LD=011'], type: 8}, +], config: {bits: 16}} +.... + diff --git a/src/insns/wavedrom/reg-based-str-Zcb.adoc b/src/insns/wavedrom/reg-based-str-Zcb.adoc new file mode 100644 index 00000000..85fceac4 --- /dev/null +++ b/src/insns/wavedrom/reg-based-str-Zcb.adoc @@ -0,0 +1,24 @@ +//Register-Based loads and Stores + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rs2\'/cs2\'', attr: ['3', 'src'], type: 3}, + {bits: 1, name: 'uimm[1]', attr: ['1', 'offset[1]'], type: 2}, + {bits: 1, name: 'funct1', attr: ['1', '0'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 6, name: 'funct6', attr: ['6', 'cap: C.CSH=100011', 'leg: C.SH=100011'], type: 8}, +], config: {bits: 16}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr: ['2', 'C0=00'], type: 8}, + {bits: 3, name: 'rs2\'/cs2\'', attr: ['3', 'src'], type: 3}, + {bits: 2, name: 'uimm[0|1]', attr: ['2', 'offset[0|1]'], type: 2}, + {bits: 3, name: 'rs1\'/cs1\'', attr: ['3', 'base'], type: 2}, + {bits: 6, name: 'funct6', attr: ['6', 'cap: C.CSB=100010', 'leg: C.SB=100010'], type: 8}, +], config: {bits: 16}} +.... diff --git a/src/insns/wavedrom/rv64_lui-auipc.adoc b/src/insns/wavedrom/rv64_lui-auipc.adoc new file mode 100644 index 00000000..d7a701ed --- /dev/null +++ b/src/insns/wavedrom/rv64_lui-auipc.adoc @@ -0,0 +1,10 @@ +//lui-auipc + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'cap: AUIPCC=0010111', 'leg: AUIPC=0010111'], type: 8}, + {bits: 5, name: 'cd/rd', attr: ['5', 'dest'], type: 2}, + {bits: 20, name: 'imm[31:12]', attr: ['20', 'U-immediate[31:12]'], type: 3} +]} +.... diff --git a/src/insns/wavedrom/store.adoc b/src/insns/wavedrom/store.adoc new file mode 100644 index 00000000..300e42e5 --- /dev/null +++ b/src/insns/wavedrom/store.adoc @@ -0,0 +1,13 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'STORE=0100011'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5', 'offset[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'cap: CSB=000','cap: CSH=001','cap: CSW=010','cap rv64: CSD=011','leg: SB=000','leg: SH=001','leg: SW=010','leg rv64: SD=011'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src'], type: 4}, + {bits: 7, name: 'imm[11:5]', attr: ['7', 'offset[11:5]'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/store_cond.adoc b/src/insns/wavedrom/store_cond.adoc new file mode 100644 index 00000000..57a76646 --- /dev/null +++ b/src/insns/wavedrom/store_cond.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'width', '.B=000','.H=001','.W=010', 'rv64: .D=011'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'cap: CSC=00011', 'leg: SC=00011'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/store_cond_cap.adoc b/src/insns/wavedrom/store_cond_cap.adoc new file mode 100644 index 00000000..74fbb690 --- /dev/null +++ b/src/insns/wavedrom/store_cond_cap.adoc @@ -0,0 +1,15 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO=0101111'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'rdest[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'width', 'rv32: .C=011','rv64: .C=100'], type: 8}, + {bits: 5, name: 'cs1/rs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'rl'], type: 4}, + {bits: 1, name: 'aq', attr: ['1', 'aq'], type: 4}, + {bits: 5, name: 'funct5', attr: ['5', 'op', 'cap: CSC=00011', 'leg: SC=00011'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/storecap.adoc b/src/insns/wavedrom/storecap.adoc new file mode 100644 index 00000000..5c63cc38 --- /dev/null +++ b/src/insns/wavedrom/storecap.adoc @@ -0,0 +1,13 @@ +//## 2.6 Load and Store Instructions + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'STORE=0100011'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['5', 'offset[4:0]'], type: 3}, + {bits: 3, name: 'funct3', attr: ['3', 'cap rv64: CSC=100', 'leg rv64: SC=100', 'cap rv32: CSC=011','leg rv32: SC=011'], type: 8}, + {bits: 5, name: 'rs1/cs1', attr: ['5', 'base'], type: 4}, + {bits: 5, name: 'cs2', attr: ['5', 'src'], type: 4}, + {bits: 7, name: 'imm[11:5]', attr: ['7', 'offset[11:5]'], type: 3}, +]} +.... diff --git a/src/insns/wavedrom/trap-return.adoc b/src/insns/wavedrom/trap-return.adoc new file mode 100644 index 00000000..04f510cb --- /dev/null +++ b/src/insns/wavedrom/trap-return.adoc @@ -0,0 +1,13 @@ +// + +[wavedrom, ,svg] + +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7','SYSTEM=111011'],type: 8}, + {bits: 5, name: 'rd', attr: ['5','0'],type: 2}, + {bits: 3, name: 'funct3', attr: ['3','PRIV=0'],type: 8}, + {bits: 5, name: 'rs1', attr: ['5','0'],type: 4}, + {bits: 12, name: 'funct12', attr: ['12','MRET=001100000010','SRET=000100000010',], type: 8}, +], config: {bits: 32}} +.... \ No newline at end of file diff --git a/src/insns/xlen_variable_warning.adoc b/src/insns/xlen_variable_warning.adoc new file mode 100644 index 00000000..80839775 --- /dev/null +++ b/src/insns/xlen_variable_warning.adoc @@ -0,0 +1 @@ +NOTE: These instructions have different encodings for RV64 and RV32. diff --git a/src/insns/zcmp_cmpop.adoc b/src/insns/zcmp_cmpop.adoc new file mode 100644 index 00000000..aece8bf9 --- /dev/null +++ b/src/insns/zcmp_cmpop.adoc @@ -0,0 +1,54 @@ +<<< + +[#CM_POP,reftext="CM.POP"] +==== CM.POP + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CPOP,reftext="CM.CPOP"] +==== CM.CPOP + +Synopsis:: +Destroy stack frame (CM.CPOP, CM.POP): load the return address register and 0 to 12 saved registers from the stack frame, deallocate the stack frame. 16-bit encodings. + +Capability Mode Mnemonic:: +`cm.cpop \{creg_list\}, -stack_adj` + +Legacy Mode Mnemonics:: +`cm.pop \{reg_list\}, -stack_adj` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm\[5:4\]', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1a, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + +_rlist_ values 0 to 3 are reserved for a future EABI variant + +Capability Mode Description:: +Load capability registers as specified in _creg_list_. Deallocate stack frame. All accesses are checked against `csp`. + +Legacy Mode Description:: +Load integer registers as specified in _reg_list_. Deallocate stack frame. All accesses are checked against <>. + +include::load_exceptions.adoc[] + +Prerequisites for CM.CPOP:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.POP:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmp_cmpopret.adoc b/src/insns/zcmp_cmpopret.adoc new file mode 100644 index 00000000..bbe412b1 --- /dev/null +++ b/src/insns/zcmp_cmpopret.adoc @@ -0,0 +1,77 @@ +<<< + +[#CM_POPRET,reftext="CM.POPRET"] +==== CM.POPRET + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CPOPRET,reftext="CM.CPOPRET"] +==== CM.CPOPRET + +Synopsis:: +Destroy stack frame (CM.CPOPRET, CM.POPRET): load the return address register and 0 to 12 saved registers from the stack frame, deallocate the stack frame. Return through the return address register. 16-bit encodings. + +Capability Mode Mnemonic:: +`cm.cpopret \{creg_list\}, -stack_adj` + +Legacy Mode Mnemonics:: +`cm.popret \{reg_list\}, -stack_adj` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm\[5:4\]', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1e, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + +_rlist_ values 0 to 3 are reserved for a future EABI variant + +Capability Mode Description:: +Load capability registers as specified in _creg_list_. Deallocate stack frame. Return by calling <> to `cra`. All data accesses are checked against `csp`. The return destination is checked against `cra`. + +Legacy Mode Description:: +Load integer registers as specified in _reg_list_. Deallocate stack frame. Return by calling <> to `ra`. All data accesses are checked against <>. The return destination is checked against <>. + +Permissions:: +Loads are checked as for <> for Capability Mode or <> for Legacy Mode. ++ +The return is checked as for <> for Capability Mode, or <> for Legacy Mode. + +Exceptions:: +When these instructions cause CHERI exceptions, _CHERI data fault_ +is reported in the TYPE field if a load causes an exception, or +_CHERI instruction access fault_ if the return causes an exception. +The following codes may be +reported in the CAUSE field of <> or <>: + +[width="50%",options=header,cols="2,^1",align=center] +|============================================================================== +| CAUSE | +| Tag violation | ✔ +| Seal violation | ✔ +| Permission violation | ✔ +| Length violation | ✔ +|============================================================================== + +:!cap_load: + +include::pcrel_debug_warning.adoc[] + +Prerequisites for CM.CPOPRET:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.POPRET:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmp_cmpopretz.adoc b/src/insns/zcmp_cmpopretz.adoc new file mode 100644 index 00000000..5c33fe62 --- /dev/null +++ b/src/insns/zcmp_cmpopretz.adoc @@ -0,0 +1,77 @@ +<<< + +[#CM_POPRETZ,reftext="CM.POPRETZ"] +==== CM.POPRETZ + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CPOPRETZ,reftext="CM.CPOPRETZ"] +==== CM.CPOPRETZ + +Synopsis:: +Destroy stack frame (CM.CPOPRETZ, CM.POPRETZ): load the return address register and 0 to 12 saved registers from the stack frame, deallocate the stack frame. Move zero into argument register zero. Return through the return address register. 16-bit encodings. + +Capability Mode Mnemonic:: +`cm.cpopretz \{creg_list\}, -stack_adj` + +Legacy Mode Mnemonics:: +`cm.popretz \{reg_list\}, -stack_adj` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm\[5:4\]', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1c, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + +_rlist_ values 0 to 3 are reserved for a future EABI variant + +Capability Mode Description:: +Load capability registers as specified in _creg_list_. Deallocate stack frame. Move zero into `ca0`. Return by calling <> to `cra`. All data accesses are checked against `csp`. The return destination is checked against `cra`. + +Legacy Mode Description:: +Load integer registers as specified in _reg_list_. Deallocate stack frame. Move zero into `a0`. Return by calling <> to `ra`. All data accesses are checked against <>. The return destination is checked against <>. + +Permissions:: +Loads are checked as for <> for Capability Mode or <> for Legacy Mode. ++ +The return is checked as for <> for Capability Mode, or <> for Legacy Mode. + +Exceptions:: +When these instructions cause CHERI exceptions, _CHERI data fault_ +is reported in the TYPE field if a load causes an exception, or +_CHERI instruction access fault_ if the return causes an exception. +The following codes may be +reported in the CAUSE field of <> or <>: + +[width="50%",options=header,cols="2,^1",align=center] +|============================================================================== +| CAUSE | +| Tag violation | ✔ +| Seal violation | ✔ +| Permission violation | ✔ +| Length violation | ✔ +|============================================================================== + +:!cap_load: + +include::pcrel_debug_warning.adoc[] + +Prerequisites for CM.CPOPRETZ:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.POPRETZ:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmp_cmpush.adoc b/src/insns/zcmp_cmpush.adoc new file mode 100644 index 00000000..0800f9b4 --- /dev/null +++ b/src/insns/zcmp_cmpush.adoc @@ -0,0 +1,54 @@ +<<< + +[#CM_PUSH,reftext="CM.PUSH"] +==== CM.PUSH + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CPUSH,reftext="CM.CPUSH"] +==== CM.CPUSH + +Synopsis:: +Create stack frame (CM.CPUSH, CM.PUSH): store the return address register and 0 to 12 saved registers to the stack frame, optionally allocate additional stack space. 16-bit encodings. + +Capability Mode Mnemonic:: +`cm.cpush \{creg_list\}, -stack_adj` + +Legacy Mode Mnemonics:: +`cm.push \{reg_list\}, -stack_adj` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm\[5:4\]', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x18, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + +_rlist_ values 0 to 3 are reserved for a future EABI variant + +Capability Mode Description:: +Create stack frame, store capability registers as specified in _creg_list_. Optionally allocate additional multiples of 16-byte stack space. All accesses are checked against `csp`. + +Legacy Mode Description:: +Create stack frame, store integer registers as specified in _reg_list_. Optionally allocate additional multiples of 16-byte stack space. All accesses are checked against <>. + +include::store_exceptions.adoc[] + +Prerequisites for CM.CPUSH:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.PUSH:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmp_cmva01s.adoc b/src/insns/zcmp_cmva01s.adoc new file mode 100644 index 00000000..f8950334 --- /dev/null +++ b/src/insns/zcmp_cmva01s.adoc @@ -0,0 +1,51 @@ +<<< + +[#CM_MVA01S,reftext="CM.MVA01S"] +==== CM.MVA01S + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CMVA01S,reftext="CM.CMVA01S"] +==== CM.CMVA01S + +Synopsis:: +CM.CMVA01S, CM.MVA01S: Move two saved registers into argument registers 0 and 1. + +Capability Mode Mnemonic:: +`cm.cmva01s cr1s', cr2s'` + +Legacy Mode Mnemonics:: +`cm.mva01s r1s', r2s'` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 3, name: 'r2s\'', attr: [] }, + { bits: 2, name: 0x3, attr: [] }, + { bits: 3, name: 'r1s\'', attr: [] }, + { bits: 3, name: 0x3, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +NOTE: The encoding uses sreg number specifiers instead of xreg number specifiers to save encoding space. The saved register encoding is shown in xref:saved_register_mapping[xrefstyle=short]. + +Capability Mode Description:: +Atomically move two capability registers `ca0` and `ca1` into `cs0-cs7`. + +Legacy Mode Description:: +Atomically move two integer registers `a0` and `a1` into `s0-s7`. + +Prerequisites for CM.CMVA01S:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.MVA01S:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmp_cmvsa01.adoc b/src/insns/zcmp_cmvsa01.adoc new file mode 100644 index 00000000..6f6a131f --- /dev/null +++ b/src/insns/zcmp_cmvsa01.adoc @@ -0,0 +1,51 @@ +<<< + +[#CM_MVSA01,reftext="CM.MVSA01"] +==== CM.MVSA01 + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CMVSA01,reftext="CM.CMVSA01"] +==== CM.CMVSA01 + +Synopsis:: +CM.CMVSA01, CM.MVSA01: Move argument registers 0 and 1 into two saved registers. + +Capability Mode Mnemonic:: +`cm.cmvsa01 cr1s', cr2s'` + +Legacy Mode Mnemonics:: +`cm.mvsa01 r1s', r2s'` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 3, name: 'r2s\'', attr: [] }, + { bits: 2, name: 0x1, attr: [] }, + { bits: 3, name: 'r1s\'', attr: [] }, + { bits: 3, name: 0x3, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +NOTE: The encoding uses sreg number specifiers instead of xreg number specifiers to save encoding space. The saved register encoding is shown in xref:saved_register_mapping[xrefstyle=short]. + +Capability Mode Description:: +Atomically move two saved capability registers `cs0-cs7` into `ca0` and `ca1`. + +Legacy Mode Description:: +Atomically move two saved integer registers `s0-s7` into `a0` and `a1`. + +Prerequisites for CM.CMVSA01:: +{c_cheri_base_ext_names}, Zcmp + +Prerequisites for CM.MVSA01:: +{c_cheri_legacy_ext_names}, Zcmp + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmt_cmjalt.adoc b/src/insns/zcmt_cmjalt.adoc new file mode 100644 index 00000000..720a3b57 --- /dev/null +++ b/src/insns/zcmt_cmjalt.adoc @@ -0,0 +1,70 @@ +<<< + +[#CM_JALT,reftext="CM.JALT"] +==== CM.JALT + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CJALT,reftext="CM.CJALT"] +==== CM.CJALT + +Synopsis:: +Jump via table with link (CM.CJALT, CM.JALT), 16-bit encodings + +Capability Mode Mnemonic:: +`cm.cjalt _index_` + +Legacy Mode Mnemonics:: +`cm.jalt _index_` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 8, name: 'index', attr: [] }, + { bits: 3, name: 0x0, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + + For this encoding to decode as <>/<>, _index>=32_, otherwise it decodes as <>/<>. + +Capability Mode Description:: +Redirect instruction fetch via the jump table defined by the indexing via `jvtc.address+ index*XLEN/8`, checking every byte of jump table access against <> bounds (not against <>) and requiring <>. Link to `cra`. + +Legacy Mode Description:: +Redirect instruction fetch via the jump table defined by the indexing via `jvtc.address+ index*XLEN/8`, checking every byte of jump table access against <> bounds (not against <>) and requiring <>. Link to `ra`. + +Permissions:: +Requires <> to be tagged, not sealed, have <> and for the full XLEN-wide access to be in <> bounds. + +Exceptions:: +When these instructions cause CHERI exceptions, _CHERI instruction access fault_ +is reported in the TYPE field and the following codes may be +reported in the CAUSE field of <> or <>: + +[width="50%",options=header,cols="2,^1",align=center] +|============================================================================== +| CAUSE | +| Tag violation | ✔ +| Seal violation | ✔ +| Permission violation | ✔ +| Length violation | ✔ +|============================================================================== + +include::pcrel_debug_warning.adoc[] + +Prerequisites for CM.CJALT:: +{c_cheri_base_ext_names}, Zcmt + +Prerequisites for CM.JALT:: +{c_cheri_legacy_ext_names}, Zcmt + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/insns/zcmt_cmjt.adoc b/src/insns/zcmt_cmjt.adoc new file mode 100644 index 00000000..7eb16660 --- /dev/null +++ b/src/insns/zcmt_cmjt.adoc @@ -0,0 +1,70 @@ +<<< + +[#CM_JT,reftext="CM.JT"] +==== CM.JT + +See <> and cite:[riscv-code-size-spec]. + +[#CM_CJT,reftext="CM.CJT"] +==== CM.CJT + +Synopsis:: +Jump via table with link (CM.CJT, CM.JT), 16-bit encodings + +Capability Mode Mnemonic:: +`cm.cjt _index_` + +Legacy Mode Mnemonics:: +`cm.jt _index_` + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 8, name: 'index', attr: [] }, + { bits: 3, name: 0x0, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] + + For this encoding to decode as <>/<>, _index<32_, otherwise it decodes as <>/<>. + +Capability Mode Description:: +Redirect instruction fetch via the jump table defined by the indexing via `jvtc.address+ index*XLEN/8`, checking every byte of jump table access against <> bounds (not against <>) and requiring <>. + +Legacy Mode Description:: +Redirect instruction fetch via the jump table defined by the indexing via `jvtc.address+ index*XLEN/8`, checking every byte of jump table access against <> bounds (not against <>) and requiring <>. + +Permissions:: +Requires <> to be tagged, not sealed, have <> and for the full XLEN-wide access to be in <> bounds. + +Exceptions:: +When these instructions cause CHERI exceptions, _CHERI instruction access fault_ +is reported in the TYPE field and the following codes may be +reported in the CAUSE field of <> or <>: + +[width="50%",options=header,cols="2,^1",align=center] +|============================================================================== +| CAUSE | +| Tag violation | ✔ +| Seal violation | ✔ +| Permission violation | ✔ +| Length violation | ✔ +|============================================================================== + +include::pcrel_debug_warning.adoc[] + +Prerequisites for CM.CJT:: +{c_cheri_base_ext_names}, Zcmt + +Prerequisites for CM.JT:: +{c_cheri_legacy_ext_names}, Zcmt + +Operation:: +[source,SAIL,subs="verbatim,quotes"] +-- +TBD +-- diff --git a/src/instructions.adoc b/src/instructions.adoc new file mode 100644 index 00000000..e8a78395 --- /dev/null +++ b/src/instructions.adoc @@ -0,0 +1,255 @@ +[#riscv-extensions] +== RISC-V Instructions and Extensions Reference + +These instruction pages are for the new CHERI instructions, and some existing RISC-V +instructions where the effect of CHERI needs specific details. + +For existing RISC-V instructions, note that: + +. In Legacy mode, every byte of each memory access access is bounds +checked against <> +. In Legacy mode, a minimum length instruction at the target of all indirect +jumps is bounds checked against <> +. In Capability mode a minimum length instruction at the target of all indirect +jumps is bounds checked against `cs1` (e.g. <>) +. A minimum length instruction at the taken target of all direct +jumps and conditional branches is bounds checked against <> regardless of +CHERI execution mode + +NOTE: Not all RISC-V extensions have been checked against CHERI. Compatible +extensions, will eventually be listed in a CHERI profile. + +<<< +=== "Zcheri_purecap", "Zcheri_legacy" and "Zcheri_mode" Extensions for CHERI + +include::insns/jalr_cap_32bit.adoc[] + +include::insns/cmove_32bit.adoc[] + +include::insns/modeswitch_32bit.adoc[] + +include::insns/cincoffset_32bit.adoc[] +include::insns/csetaddr_32bit.adoc[] +include::insns/candperm_32bit.adoc[] +include::insns/csetmode_32bit.adoc[] +include::insns/csethigh_32bit.adoc[] +include::insns/csetequalexact_32bit.adoc[] +include::insns/cseal_32bit.adoc[] + +include::insns/ctestsubset_32bit.adoc[] +include::insns/cbuildcap_32bit.adoc[] + +include::insns/cgettag_32bit.adoc[] +include::insns/cgetperm_32bit.adoc[] +include::insns/cgethigh_32bit.adoc[] +include::insns/cgetbase_32bit.adoc[] +include::insns/cgetlen_32bit.adoc[] + +include::insns/csetbounds_32bit.adoc[] +include::insns/csetboundsinexact_32bit.adoc[] +include::insns/cram_32bit.adoc[] + +include::insns/load_32bit_cap.adoc[] +include::insns/store_32bit_cap.adoc[] + +<<< +=== RV32I/E and RV64I/E Base Integer Instruction Sets + +include::insns/auipcc_32bit.adoc[] + +include::insns/condbr_32bit.adoc[] + +include::insns/cjalr_jalr_32bit.adoc[] +include::insns/cjal_jal_32bit.adoc[] + +include::insns/load_32bit.adoc[] +include::insns/store_32bit.adoc[] + +include::insns/mret_sret.adoc[] +include::insns/dret.adoc[] + +<<< +=== "A" Standard Extension for Atomic Instructions + +include::insns/amo_32bit.adoc[] +include::insns/amoswap_32bit_cap.adoc[] + +include::insns/load_res_32bit.adoc[] +include::insns/load_res_cap_32bit.adoc[] + +include::insns/store_cond_32bit.adoc[] +include::insns/store_cond_cap_32bit.adoc[] + +<<< +=== "Zicsr", Control and Status Register (CSR) Instructions + +include::insns/csrrw_32bit.adoc[] +include::insns/csrr_32bit.adoc[] + +<<< +=== "Zfh", "Zfhmin", "F" and "D" Standard Extension for Floating-Point + +include::insns/load_32bit_fp.adoc[] +include::insns/store_32bit_fp.adoc[] + +<<< +=== "C" Standard Extension for Compressed Instructions + +include::insns/condbr_16bit.adoc[] + +include::insns/cmove_cmv_16bit.adoc[] + +include::insns/addi16sp_16bit.adoc[] +include::insns/addi4spn_16bit.adoc[] + +include::insns/modeswitch_16bit.adoc[] + +include::insns/cjalr_jalr_16bit.adoc[] +include::insns/cjr_jr_16bit.adoc[] +include::insns/cjal_jal_16bit.adoc[] +include::insns/cj_j_16bit.adoc[] + +include::insns/load_16bit.adoc[] +include::insns/load_16bit_sprel.adoc[] +include::insns/load_16bit_fp_sp.adoc[] +include::insns/load_16bit_fp_dp.adoc[] +include::insns/load_16bit_cap_sprel.adoc[] + +include::insns/store_16bit.adoc[] +include::insns/store_16bit_sprel.adoc[] +include::insns/store_16bit_fp_sp.adoc[] +include::insns/store_16bit_fp_dp.adoc[] +include::insns/store_16bit_cap_sprel.adoc[] + +<<< +=== "Zicbom", "Zicbop", "Zicboz" Standard Extensions for Base Cache Management Operations + +include::insns/cbo.clean.adoc[] +include::insns/cbo.flush.adoc[] +include::insns/cbo.inval.adoc[] +include::insns/cbo.zero.adoc[] + +include::insns/prefetch.i.adoc[] +include::insns/prefetch.r.adoc[] +include::insns/prefetch.w.adoc[] + +<<< +=== "Zba" Extension for Bit Manipulation Instructions + +include::insns/sh123add_32bit.adoc[] +include::insns/sh123adduw_32bit.adoc[] +include::insns/sh4add_32bit.adoc[] +include::insns/sh4adduw_32bit.adoc[] + +<<< +=== "Zcb" Standard Extension For Code-Size Reduction + +include::insns/load_16bit_Zcb.adoc[] + +include::insns/store_16bit_Zcb.adoc[] + +<<< +=== "Zcmp" Standard Extension For Code-Size Reduction + +The push (<>) and pop (<>, <>, <>) instructions are redefined in capability mode to save/restore full capabilities. + +The double move instructions (<>, <>) are redefined in capability mode to move full capabilities between registers. The saved register mapping is as shown in + +.saved register mapping for Zcmp +[#saved_register_mapping] +[width="100%",options=header, align="center"] +|==================================== +| saved register specifier | xreg | integer ABI | CHERI ABI +| 0 | x8 | s0 | cs0 +| 1 | x9 | s1 | cs1 +| 2 | x18 | s2 | cs2 +| 3 | x19 | s3 | cs3 +| 4 | x20 | s4 | cs4 +| 5 | x21 | s5 | cs5 +| 6 | x22 | s6 | cs6 +| 7 | x23 | s7 | cs7 +|==================================== + + +All instructions are defined in cite:[riscv-code-size-spec]. + +include::insns/zcmp_cmpush.adoc[] +include::insns/zcmp_cmpop.adoc[] +include::insns/zcmp_cmpopret.adoc[] +include::insns/zcmp_cmpopretz.adoc[] +include::insns/zcmp_cmvsa01.adoc[] +include::insns/zcmp_cmva01s.adoc[] + + +<<< +=== "Zcmt" Standard Extension For Code-Size Reduction + +The table jump instructions (<>, <>) defined in cite:[riscv-code-size-spec] are _not_ redefined in capability mode to have capabilities in the jump table. This is to prevent the code-size growth caused by doubling the size of the jump table. + +In the future, new jump table modes or new encodings can be added to have capabilities in the jump table. + +The jump vector table CSR <> has a capability alias <> so that it can only be configured to point to accessible memory. All accesses to the jump table are checked against <>, and _not_ against <>. This allows the jump table to be accessed +when the <> bounds are set narrowly to the local function only. + +NOTE: the implementation doesn't need to expand and bounds check against <> on every access, it is sufficient to decode the valid accessible range of entries after every write to <>, and then check that the accessed entry is in that range. + +[#jvt,reftext="jvt"] +==== Jump Vector Table CSR (jvt) + +The JVT CSR is exactly as defined by cite:[riscv-code-size-spec]. It is aliased to <>. + +[#jvtc,reftext="jvtc"] +==== Jump Vector Table CSR (jvtc) + +<> extends <> to be a capability width CSR, as shown in xref:ucsrnames-replaced[xrefstyle=short]. + +.Jump Vector Table Capability register +include::img/jvtcreg.edn[] + +All instruction fetches from the jump vector table are checked against <>. + +See <>, <>, <>, <>. + +include::insns/zcmt_cmjalt.adoc[] +include::insns/zcmt_cmjt.adoc[] + +<<< + +ifdef::vector_section[] + +=== "V" Standard Extension for Vector Operations + +include::cheri-vector.adoc[] + +include::cheri-vectorcap-ext.adoc[] + +include::insns/cvle_ew.adoc[] +include::insns/cvse_ew.adoc[] +include::insns/cvlm.adoc[] +include::insns/cvsm.adoc[] +include::insns/cvlse_ew.adoc[] +include::insns/cvsse_ew.adoc[] +include::insns/cvluxei_ew.adoc[] +include::insns/cvsuxei_ew.adoc[] +include::insns/cvloxei_ew.adoc[] +include::insns/cvsoxei_ew.adoc[] +include::insns/cvle_ew_ff.adoc[] +include::insns/cvlseg_nf_e_ew.adoc[] +include::insns/cvsseg_nf_e_ew.adoc[] +include::insns/cvlseg_nf_e_ew_ff.adoc[] +include::insns/cvlsseg_nf_e_ew.adoc[] +include::insns/cvssseg_nf_e_ew.adoc[] +include::insns/cvluxseg_nf_ei_ew.adoc[] +include::insns/cvsuxseg_nf_ei_ew.adoc[] +include::insns/cvloxseg_nf_ei_ew.adoc[] +include::insns/cvsoxseg_nf_ei_ew.adoc[] +include::insns/cvl_nr_re_ew.adoc[] +include::insns/cvs_nr_r.adoc[] + +include::insns/cvlce_ew.adoc[] +include::insns/cvsce_ew.adoc[] +// Should whole vector register load capability be supported? +// Should whole vector register store capability be supported? +include::insns/cvmv_nr_r.adoc[] + +endif::[] diff --git a/src/introduction.adoc b/src/introduction.adoc new file mode 100644 index 00000000..08a010b5 --- /dev/null +++ b/src/introduction.adoc @@ -0,0 +1,204 @@ +== Introduction + +=== CHERI Concepts and Terminology + +Current CPU architectures (including RISC-V) allow memory access solely by +specifying and dereferencing a memory address stored as an integer value in +a register or in memory. Any accidental or malicious action that modifies +such an integer value can result in unrestricted access to the memory that +it addresses. Unfortunately, this weak memory protection model has resulted +in the majority of software security vulnerabilities present in software +today. + +CHERI enables software to efficiently implement fine-grained memory protection +and scalable software compartmentalization by providing strong, efficient +hardware mechanisms to support software execution and enable it to prevent +and mitigate vulnerabilities. + +Design goals include incremental adoptability from current ISAs and software +stacks, low performance overhead for memory protection, significant performance +improvements for software compartmentalization, formal grounding, and +programmer-friendly underpinnings. It has been designed to provide strong, +non-probabilistic protection rather than depending on short random numbers or +truncated cryptographic hashes that can be leaked and reinjected, or that could +be brute forced. + +CHERI enhances the CPU to add hardware memory access control. It has an +additional memory access mechanism that protects _references to code and data_ +(pointers), rather than the _location of code and data_ (integer addresses). +This mechanism is implemented by providing a new primitive, called a +*capability*, that software components can use to implement strongly protected +pointers within an address space. + +Capabilities are unforgeable and delegatable tokens of authority that grant +software the ability to perform a specific set of operations. In CHERI, +integer-based pointers can be replaced by capabilities to provide memory access +control. In this case, a memory access capability contains an integer memory +address that is extended with metadata to protect its integrity, limit how it +is manipulated, and control its use. This metadata includes: + +* an out-of-band _tag_ implementing strong integrity protection +(differentiating valid and invalid capabilities), This prevents confusion +between data and capabilities. +* _bounds_ limiting the range of addresses that may be dereferenced +* _permissions_ controlling the specific operations that may be performed +* _sealing_ which is used to support higher-level software encapsulation + +The CHERI model is motivated by the _principle of least privilege_, which +argues that greater security can be obtained by minimizing the privileges +accessible to running software. A second guiding principle is the _principle of +intentional use_, which argues that, where many privileges are available to a +piece of software, the privilege to use should be explicitly named rather than +implicitly selected. While CHERI does not prevent the expression of vulnerable +software designs, it provides strong vulnerability mitigation: attackers have a +more limited vocabulary for attacks, and should a vulnerability be successfully +exploited, they gain fewer rights, and have reduced access to further attack +surfaces. + +Protection properties for capabilities include the ISA ensuring that +capabilities are always derived via valid manipulations of other capabilities +(_provenance_), that corrupted in-memory capabilities cannot be dereferenced +(_integrity_), and that rights associated with capabilities shall only ever be +equal or less permissive (_monotonicity_).Tampering or modifying capabilities +in an attempt to elevate their rights will yield an invalid capability as the +tag will be cleared. Attempting to dereference via an invalid capability +will result in a hardware exception. + +CHERI capabilities may be held in registers or in memories, and are loaded, +stored, and dereferenced using CHERI-aware instructions that expect capability +operands rather than integer addresses. On hardware reset, initial capabilities +are made available to software via special and general-purpose capability +registers. All other capabilities will be derived from these initial valid +capabilities through valid capability transformations. + +Developers can use CHERI to build fine-grained spatial and temporal memory +protection into their system software and applications and significantly +improve their security. + +=== CHERI Extensions to RISC-V + +This specification is based on publicly available documentation including +cite:[cheri-v9-spec] and cite:[woodruff2019cheri]. It defines the following +extensions to support CHERI alongside RISC-V: + +{cheri_base_ext_name}:: Introduces key, minimal CHERI concepts and features to +the RISC-V ISA. The resulting extended ISA is not +backwards-compatible with RISC-V +{cheri_legacy_ext_name}:: Extends {cheri_base_ext_name} with features to ensure +that the ISA extended with CHERI allows backwards binary compatibility with +RISC-V +{cheri_mode_ext_name}:: Adds a mode bit in the encoding of capabilities to +allow changing the current CHERI execution mode using indirect jump +instructions +{cheri_pte_ext_name}:: CHERI extension for RISC-V harts supporting page-based +virtual-memory +{cheri_vectorcap_ext_name}:: CHERI extension for the RISC-V Vector (V) +extension. It adds support for storing CHERI capabilities in +vector registers, intended for vectorised memory copying + +CAUTION: The extension names are provisional and subject to change. + +{cheri_base_ext_name} is defined as the base extension which all CHERI RISC-V +implementations must support. {cheri_legacy_ext_name}, {cheri_mode_ext_name} +and {cheri_pte_ext_name} are optional extensions in addition to +{cheri_base_ext_name}. {cheri_mode_ext_name} requires supporting both +{cheri_base_ext_name} and {cheri_legacy_ext_name}. + +If a standard vector extension is present (indicated in this document as "V", +but it could equally be one of the subsets defined by a Zve* extension) then +{cheri_vectorcap_ext_name} may optionally be added in addition to +{cheri_base_ext_name}. + +We refer to software as _purecap_ if it utilizes CHERI capabilities for all +memory accesses -- including loads, stores and instruction fetches -- rather +than integer addresses. Purecap software requires the CHERI RISC-V hart to +support {cheri_base_ext_name}. We refer to software as _hybrid_ if it uses +integer addresses *or* CHERI capabilities for memory accesses. Hybrid software +requires the CHERI RISC-V hart to support {cheri_base_ext_name}, +{cheri_legacy_ext_name} and {cheri_mode_ext_name}. + +See xref:riscv-extensions[xrefstyle=short] for compatibility with other RISC-V +extensions. + +=== Risks and Known Uncertainty + +* All extensions could be divided up differently in future, including after +ratification +* The RISC-V Architecture Review Committee (ARC) are likely to update all +encodings +* The ARC are likely to update all CSR addresses +* Instruction mnemonics may be renamed + ** The instruction mnemonics could be the same regardless of CHERI mode + ** Any changes will affect assembly code, but assembler aliases can provide +backwards compatibility +* There is no clarity on how the new Page Table Entry (PTE) bits from +{cheri_pte_ext_name} will be implemented + ** The PTE bits introduce a dependency between exceptions and the stored +tag bit +* There is debate on whether different permission encodings are needed for +XLENMAX=32 and XLENMAX=64 + +==== Pending Extensions + +The base RISC-V ISAs, along with most extensions, have been reviewed for +compatibility with CHERI. However, the following extensions are yet to be +reviewed: + +* "V" Standard Extension for Vector Operations +* "H" Hypervisor Extension +* Core-Local Interrupt Controller (CLIC) + +CAUTION: The list above is not complete! + +==== Incompatible Extensions + +There are RISC-V extensions in development that may duplicate some aspects of +CHERI functionality or directly conflict with CHERI and should not be +available on a CHERI-enabled hart. These include: + +* RISC-V CFI specification +* "J" Pointer Masking + +CAUTION: The list above is not complete! + +==== Suggested Mnemonic Renaming + +xref:suggested_insn_names[xrefstyle=short] lists the currently proposed +renames. Please update the table when new renames are proposed or confirmed. + +.Suggested instruction names +[#suggested_insn_names] +[width="100%",options=header] +|============================= +| Current Name | Suggestion +| CMOVE | CMV +| CINCOFFSET | CADD +| CINCOFFSETIMM | CADDI +| C.CINCOFFSET16CSP | C.CADDI16SP +| C.CINCOFFSET4CSPN | C.CADDI4SPN +| CLC/LC | CLCAP/LCAP +| CSC/SC | CSCAP/SCAP +|============================= + +NOTE: Renaming SC is not a choice. The store capability instruction must be +renamed because it conflicts with store conditional from the RISC-V A +extension. + +Further to the new proposed mnemonics in +xref:suggested_insn_names[xrefstyle=short], the following general proposals +have been discussed: + +* Do not use the letter 'c' to indicate 'capability' or 'CHERI' because this +conflicts with the already ratified RISC-V C extension + ** We previously discussed using other letters like 'p' for 'pointer' or +'f' for 'fat pointer' although 'f' is already used for floating point +* Do not change instruction mnemonics based on the current CHERI execution mode + ** For example, LW is always load word regardless of the CHERI mode, so the +mnemonic CLW disappears + ** This facilitates writing the ISA specification as well as code +maintenance in systems software like Linux + ** However, it also goes against intentionality and can make assembly code +(which occurs very infrequently in real-world code) more difficult to +understand without additional context + ** Both options could be supported by using assembler aliases + diff --git a/src/riscv-cheri.adoc b/src/riscv-cheri.adoc new file mode 100644 index 00000000..b448a2b9 --- /dev/null +++ b/src/riscv-cheri.adoc @@ -0,0 +1,132 @@ += RISC-V Specification for CHERI Extensions +Authors: Hesham Almatary, Andres Amaya Garcia, John Baldwin, David Chisnall, Jessica Clarke, Brooks Davis, Nathaniel Wesley Filardo, Franz A. Fuchs, Timothy Hutt, Alexandre Joannou, Tariq Kurd, Ben Laurie, A. Theodore Markettos, David McKay, Jamie Melling, Stuart Menefy, Simon W. Moore, Peter G. Neumann, Robert Norton, Alexander Richardson, Michael Roe, Peter Rugg, Peter Sewell, Carl Shaw, Robert N. M. Watson, Jonathan Woodruff +:docgroup: CHERI Task Group +:description: RISC-V specification for CHERI extensions +:company: RISC-V.org +:revdate: 1/2023 +:revnumber: 1.0 +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: +:url-riscv: http://riscv.org +:doctype: book +:preface-title: Preamble +:colophon: +:appendix-caption: Appendix +:imagesdir: {imagesdir} +:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] +:experimental: +:reproducible: +:imagesoutdir: {imagesoutdir} +:bibtex-file: {srcdir}/riscv-cheri.bib +:bibtex-order: alphabetical +:bibtex-style: apa +:icons: font +:lang: en +:listing-caption: Listing +:sectnums: +:toc: left +:toclevels: 4 +:source-highlighter: pygments +ifdef::backend-pdf[] +:source-highlighter: coderay +endif::[] +:data-uri: +:hide-uri-scheme: +:stem: latexmath +:footnote: +:xrefstyle: short + +/////////////////////////////////////////////////////////////////////////////// +// Top-level CHERI definitions +/////////////////////////////////////////////////////////////////////////////// + +// Base CHERI extension without the mode bit in capability format +:cheri_base_ext_name: Zcheri_purecap +// CHERI extension adding support for legacy mode +:cheri_legacy_ext_name: Zcheri_legacy +// CHERI extension adding support for the mode bit in the capability format +:cheri_mode_ext_name: Zcheri_mode +// Extension for CHERI PTE bits +:cheri_pte_ext_name: Zcheri_pte +// Extension for CHERI capabilities in vector registers +:cheri_vectorcap_ext_name: Zcheri_vectorcap + +// Extension for supporting lr/sc.[bh] +:lr_sc_bh_ext_name: Zbhlrsc + +:c_cheri_base_ext_names: C or Zca, {cheri_base_ext_name} +:c_cheri_legacy_ext_names: C or Zca, {cheri_legacy_ext_name} +:c_cheri_mode_ext_names: C or Zca, {cheri_mode_ext_name} + +:non-csrrw-or: <>, <>, <>, <> or <> +:non-csrrw-and: <>, <>, <>, <> and <> + +/////////////////////////////////////////////////////////////////////////////// +// Cap definitions +/////////////////////////////////////////////////////////////////////////////// + +:cap_rv32_sdp_width: 2 +:cap_rv64_sdp_width: 4 +:cap_rv32_mw_width: 10 +:cap_rv64_mw_width: 14 +:cap_rv32_perms_width: 4 +:cap_rv64_perms_width: 5 +:cap_rv32_addr_width: 32 +:cap_rv64_addr_width: 64 +:cap_rv32_exp_width: 5 +:cap_rv64_exp_width: 6 + +:cheri_excep_mcause: 28 +:cheri_excep_type_pcc: 0 +:cheri_excep_type_data: 1 +:cheri_excep_type_jump: 2 +:cheri_excep_cause_tag: 0 +:cheri_excep_cause_seal: 1 +:cheri_excep_cause_perm: 2 +:cheri_excep_cause_length: 3 + +/////////////////////////////////////////////////////////////////////////////// +// Preface +/////////////////////////////////////////////////////////////////////////////// + +[WARNING] +.This document is in the link:http://riscv.org/spec-state[Development state] +==== +Expect potential changes. This draft specification is likely to evolve before +it is accepted as a standard. Implementations based on this draft +may not conform to the future standard. +==== + +[preface] +== Copyright and license information +This specification is licensed under the Creative Commons +Attribution 4.0 International License (CC-BY 4.0). The full +license text is available at +https://creativecommons.org/licenses/by/4.0/. + +Copyright 2024 by RISC-V International. + +[preface] +include::contributors.adoc[] + +/////////////////////////////////////////////////////////////////////////////// +// Document body +/////////////////////////////////////////////////////////////////////////////// + +include::introduction.adoc[] +include::cap-description.adoc[] +include::riscv-integration.adoc[] +include::debug-integration.adoc[] +include::cheri-pte-ext.adoc[] +include::riscv-legacy-integration.adoc[] +include::riscv-mode-integration.adoc[] +include::instructions.adoc[] +include::tables.adoc[] + +/////////////////////////////////////////////////////////////////////////////// +// Index and bibliography +/////////////////////////////////////////////////////////////////////////////// + +// The index must precede the bibliography +include::index.adoc[] +include::bibliography.adoc[] diff --git a/src/riscv-cheri.bib b/src/riscv-cheri.bib new file mode 100644 index 00000000..934c4374 --- /dev/null +++ b/src/riscv-cheri.bib @@ -0,0 +1,67 @@ +@article{woodruff2019cheri, + title={Cheri concentrate: Practical compressed capabilities}, + author={Woodruff, Jonathan and Joannou, Alexandre and Xia, Hongyan and Fox, Anthony and Norton, Robert M and Chisnall, David and Davis, Brooks and Gudka, Khilan and Filardo, Nathaniel W and Markettos, A Theodore and others}, + journal={IEEE Transactions on Computers}, + volume={68}, + number={10}, + pages={1455--1469}, + year={2019}, + publisher={IEEE} +} + +@TechReport{cheri-v9-spec, + author = {Watson, Robert N. M. and Neumann, Peter G. and Woodruff, + Jonathan and Roe, Michael and Almatary, Hesham and + Anderson, Jonathan and Baldwin, John and Barnes, Graeme and + Chisnall, David and Clarke, Jessica and Davis, Brooks and + Eisen, Lee and Filardo, Nathaniel Wesley and Fuchs, Franz + A. and Grisenthwaite, Richard and Joannou, Alexandre and + Laurie, Ben and Markettos, A. Theodore and Moore, Simon W. + and Murdoch, Steven J. and Nienhuis, Kyndylan and Norton, + Robert and Richardson, Alexander and Rugg, Peter and + Sewell, Peter and Son, Stacey and Xia, Hongyan}, + title = {{Capability Hardware Enhanced RISC Instructions: CHERI + Instruction-Set Architecture (Version 9)}}, + year = 2023, + month = sep, + url = {https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-987.pdf}, + institution = {University of Cambridge, Computer Laboratory}, + doi = {10.48456/tr-987}, + issn = {1476-2986}, + issn = {1476-2986}, + number = {UCAM-CL-TR-987} +} + +@misc{riscv-priv-spec, + author = {RISC-V}, + title = {RISC-V Privileged Specification}, + year = {2023}, + note = {Version 20211203, Revised 20230731}, + url = {https://github.com/riscv/riscv-isa-manual/releases/download/riscv-isa-release-056b6ff-2023-10-02/priv-isa-asciidoc.pdf} +} + +@misc{riscv-unpriv-spec, + author = {RISC-V}, + title = {RISC-V Unprivileged Specification}, + year = {2023}, + note = {Version 20191214, Revised 20230723}, + url = {https://github.com/riscv/riscv-isa-manual/releases/download/riscv-isa-release-056b6ff-2023-10-02/unpriv-isa-asciidoc.pdf} +} + +@misc{riscv-debug-spec, + author = {RISC-V}, + title = {RISC-V Debug Specification}, + year = {2022}, + note = {Version 1.0-STABLE}, + url = {https://github.com/riscv/riscv-debug-spec/raw/ +c93823ef349286dc71a00928bddb7254e46bc3b5/riscv-debug-stable.pdf} +} + +@misc{riscv-code-size-spec, + author = {RISC-V}, + title = {RISC-V Code-size Reduction Specification}, + year = {2023}, + note = {Version 1.0.4-3}, + url = {https://github.com/riscv/riscv-code-size-reduction/releases/download/v1.0.4-3/Zc-1.0.4-3.pdf} +} + diff --git a/src/riscv-integration.adoc b/src/riscv-integration.adoc new file mode 100644 index 00000000..1616e918 --- /dev/null +++ b/src/riscv-integration.adoc @@ -0,0 +1,1134 @@ +[#section_rv_integration] +== Integrating Zcheri_purecap with the RISC-V Base Integer Instruction Set + +{cheri_base_ext_name} is an extension to the RISC-V ISA. The extension adds a +carefully selected set of instructions and CSRs that are sufficient to +implement new security features in the ISA. To ensure compatibility, +{cheri_base_ext_name} also requires some changes to the primary base integer +variants: RV32I, providing 32-bit addresses with 64-bit capabilities, and +RV64I, providing 64-bit addresses with 128-bit capabilities. The remainder of +this chapter describes these changes for both the unprivileged and privileged +components of the base integer RISC-V ISAs. + +NOTE: The changes described in this specification also ensure that +{cheri_base_ext_name} is compatible with RV32E. + +=== Memory + +A hart supporting {cheri_base_ext_name} has a single byte-addressable address +space of 2^XLEN^ bytes for all memory accesses. Each memory region capable of +holding a capability also stores a tag bit for each naturally aligned CLEN bits +(e.g. 16 bytes in RV64), so that capabilities with their tag set can only be +stored in naturally aligned addresses. Tags must be atomically bound to the +data they protect. + +The memory address space is circular, so the byte at address +2^XLEN^ - 1 is adjacent to the byte at address zero. A capability's +representable region described in xref:section_cap_encoding[xrefstyle=short] is +also circular, so address 0 is within the representable region of a capability +where address 2^XLENMAX^ - 1 is within the bounds. + +[#section_riscv_programmers_model] +=== Programmer's Model for Zcheri_purecap + +For {cheri_base_ext_name}, the 32 unprivileged *x* registers of the base +integer ISA are extended so that they are able to hold a capability. Therefore, +each *x* register is CLEN bits wide and has an out of band tag bit. The *x* +notation refers to the address field of the capability in an unprivileged +register while the *c* notation is used to refer to the full capability (i.e. +address, metadata and tag) held in the same unprivileged register. + +Register *c0* is hardwired with all bits, including the capability metadata and +tag, equal to 0. In other words, *c0* is hardwired to the <> +capability. + +An authorising capability with appropriate permissions is required to execute +instructions in {cheri_base_ext_name}. Therefore, the unprivileged program +counter (*pc*) register is extended so that it is able to hold a capability. +The extended register is called the program counter capability (<>). The +<> address field is effectively the *pc* in the base RISC-V ISA that the +hardware automatically increments as instructions are executed. The <>'s +metadata and tag are reset to the <> capability metadata and tag. + +The hardware performs the following checks on <> for each instruction +executed in addition to the checks already required by the base RISC-V ISA. A +failing check causes a CHERI exception. + +* The tag must be set +* The capability must not be sealed +* The capability must grant execute permission +* All bytes of the instruction must be in bounds + +[#section_cap_instructions] +=== Capability Instructions + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* Some instructions from the original CHERI +specification were removed to save encoding space, or because they relate +to features which are not yet in this specification. Instructions were removed +if they do not harm performance and can be emulated using other instructions. +endif::[] + +{cheri_base_ext_name} introduces new instructions to the base RISC-V integer +ISA to inspect and operate on capabilities held in registers. + +==== Capability Inspection Instructions + +These instructions allow software to inspect the fields of a capability held +in a *c* register. The output is an integer value written to an *x* register +representing the decoded field of the capability, such as the permissions or +bounds. These instructions do not cause exceptions. + +* <>: inspects the tag of the input capability. The output is 1 if the +tag is set and 0 otherwise +* <>: outputs the architectural (AP) and software-defined (SDP) +permission fields of the input capability +* <>: outputs the expanded base address of the input capability +* <>: outputs the length of the input capability. Length is defined as +`top - base`. The output is 2^XLEN^-1 when the capability's length is +2^XLENMAX^ +* <>: outputs the nearest bounds alignment that a valid capability can +represent +* <>: outputs the compressed capability metadata +* <>: compares two capabilities including tag, metadata and +address +* <>: tests whether the bounds and permissions of a capability are a +subset of those from another capability + +NOTE: <> and <> output 0 when a capability with malformed +bounds is provided as an input (see +xref:section_cap_malformed[xrefstyle=short]). + +==== Capability Manipulation Instructions + +These instructions allow software to manipulate the fields of a capability held +in a *c* register. The output is a capability written to a *c* register with +its fields modified. The output capability has its tag set to 0 if the +input capability did not have a tag set, the output capability has more +permissions or larger bounds compared to the input capability, or the operation +results in a capability with malformed bounds. These instructions do not give +rise to exceptions. + +* <>: set the address of a capability to an arbitrary address +* <>, <>: increment the address of the input capability +by an arbitrary offset +* <>: replace a capability's metadata with an arbitrary value. The +output tag is always 0 +* <>: bitwise AND of a mask value with a bit map representation of the +architectural (AP) and software-defined (SDP) permissions fields +* <>: set the base and length of a capability. The tag is +cleared, if the encoding cannot represents the bounds exactly +* <>: set the base and length of a capability. The base will be +rounded down and/or the length will be rounded up if the encoding cannot represent +the bounds exactly +* <>: seal capability +* <>: replace the base, top, address, permissions and mode fields of a +capability with the fields from another capability +* <>: move a capability from a *c* register to another *c* register + +NOTE: <> outputs a capability with tag set to 0 if the input +capability's bounds are malformed. + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* <> and <> perform the role +of the old CSETBOUNDSEXACT while the new <> is the old +CSETBOUNDS. +endif::[] + +==== Capability Load and Store Instructions + +A load capability instruction, <>, reads CLEN bits from memory together with +its tag and writes the result to a *c* register. The capability authorising the +memory access is provided in a *c* source register, so the effective address is +obtained by incrementing that capability with the sign-extended 12-bit offset. + +A store capability instruction, <>, writes CLEN bits and the tag in a *c* register +to memory. The capability authorising the memory access is provided in a *c* +source register, so the effective address is obtained by incrementing that +capability with the sign-extended 12-bit offset. + +<> and <> instructions cause CHERI exceptions if the +authorising capability fails any of the following checks: + +* The tag is zero +* The capability is sealed +* At least one byte of the memory access is outside the capability's bounds +* For loads, the read permission must be set in AP +* For stores, the write permission must be set in AP + +Capability load and store instructions also cause load or store/AMO address +misaligned exceptions if the address is not naturally aligned to a CLEN +boundary. + +For loads, the tag of the capability loaded from memory is cleared if the +authorising capability does not grant permission to read capabilities (i.e. +both <> and <> must be set in AP). For stores, the tag of the +capability written to memory is cleared if the authorising capability does not +grant permission to write capabilities (i.e. both <> and <> +must be set in AP). + +WARNING: #TODO: these cases may cause exceptions in the future - we need a way +for software to discover and/or control the behaviour# + +[#section_uncond_integer_addr_jump] +==== Unconditional Integer Address Jumps + +The indirect jump and link <> (<>) instruction allows unconditional +jumps to a target address. The target address is provided in an *x* register; +the new address is installed in the address field of the <>. The address of +the instruction following the jump (*pc* + 4) is written to an *x* register. +<> causes an exceptions when a minimum sized instruction at the +target address is not within the bounds of the <> or the target address is +misaligned. + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This instruction is now modal and shares the same +encoding with <> when both {cheri_base_ext_name} and +{cheri_legacy_ext_name} are supported. +endif::[] + +[#section_existing_riscv_insns] +=== Existing RISC-V Instructions + +The operands or behavior of some instructions in the base RISC-V ISA changes in +{cheri_base_ext_name}. + +==== Integer Computational Instructions + +Most integer computational instructions operate on XLEN bits of values held in +*x* registers. Therefore, these instructions only operate on the address field +if the input register of the instruction holds a capability. The output is XLEN +bits written to an *x* register; the tag and capability metadata of that +register are zeroed. + +The add upper immediate to <> instruction (<>) replaces the add upper +immediate to *pc* instruction (<>) at the same encoding. <> is used to +build <>-relative capabilities. <> forms a 32-bit offset from the 20-bit +immediate and filling the lowest 12 bits with zeros. The <> address is then +incremented by the offset and a representability check is performed so the +capability's tag is cleared if the new address is outside the <>'s +representable region. The resulting CLEN value along with the new tag are +written to a *c* register. + +==== Control Transfer Instructions + +Control transfer instructions operate as described in the base RISC-V +ISA. They also may cause metadata updates and/or cause exceptions in addition +to the base behaviour as described below. + +===== Unconditional Jumps + +The capability jump and link (<>) instruction replaces jump and link (<>) at +the same encoding. <> sign-extends the offset and adds it to the address of +the jump instruction to form the target address. The target address is +installed in the address field of <>. The capability with the address of the +instruction following the jump (<> + 4) is written to a *c* register. + +The capability jump and link register (<>) instruction replaces the jump +and link register (<>) instruction at the same encoding. This instruction +allows unconditional jumps to a target capability. The target capability is +obtained by incrementing the capability in the *c* register operand by the +sign-extended 12-bit immediate, then setting the least significant bit of the +result to zero. The capability with the address of the instruction following +the jump (<> + 4) is written to a *c* register. + +All jumps cause CHERI exceptions when a minimum sized instruction +at the target address is not within the bounds of the <>. + +<> causes a CHERI exception when: + +* The target capability's tag is zero +* A minimum sized instruction at the target capability's address is not +within bounds +* The target capability does not grant execute permission + +<> and <> can also cause instruction address misaligned exceptions +following the standard RISC-V rules for <> and <>. + +[#condbr-purecap] +===== Conditional Branches + +Branch instructions (see xref:insns-conbr-32bit[xrefstyle=short]) encode signed +offsets in multiples of 2 bytes. The offset is sign-extended and added to the +address of the branch instruction to form the target address. + +Branch instructions compare two *x* registers as described in the base RISC-V +ISA, so the metadata and tag values are disregarded in the comparison if the +operand registers hold capabilities. If the comparison evaluates to true, then +the target address is installed in the <>'s address field. These instructions cause CHERI exceptions +when a minimum sized instruction at the target address is not within the +<>'s bounds. + +==== Integer Load and Store Instructions + +Integer load and store instructions transfer the amount of integer data described in +the base RISC-V ISA between the registers and memory. For example, <> and +<> load 64-bit and 32-bit values respectively from memory into an *x* +register. However, the address operands for load and store instructions are +interpreted differently in {cheri_base_ext_name}: the capability authorising +the access is in the *c* register operand and the memory address is given by +incrementing the address of that capability by the sign-extended 12-bit +immediate offset. For clarity, the mnemonics of these instructions are +prefixed with the letter 'C' (e.g. <> becomes <>, <> becomes +<>, etc) to distinguish them from the standard RISC-V instructions that do +not have a *c* register operand. + +All load and store instructions cause CHERI exceptions if the +authorising capability fails any of the following checks: + +* The tag is set +* The capability is unsealed +* All bytes of accessed memory are inside the capability's bounds +* For loads, the read permission must be set in AP +* For stores, the write permission must be set in AP + +Integer load instructions always zero the tag and metadata of the result register. + +Integer stores write zero to the tag associated with the memory locations that +are naturally aligned to CLEN. Therefore, misaligned stores may clear up to +two tag bits in memory. + +=== Zicsr, Control and Status Register (CSR) Instructions + +{cheri_base_ext_name} requires that RISC-V CSRs intended to hold addresses, +like <>, are now able to hold capabilities. Therefore, such registers are +removed in {cheri_base_ext_name} and analogous CLEN-bit +versions of those CSRs are added to the ISA as described in +xref:csr-numbers-section[xrefstyle=short]. + +Reading or writing any part of a CLEN-bit CSR may cause +side-effects. For example, the CSR's tag bit may be cleared if a new address +is outside the representable region of a CSR capability being written. + +This section describes how the CSR instructions operate on these CSRs in +{cheri_base_ext_name}. + +The CLEN-bit CSRs are summarised in xref:clen_csr_summary[xrefstyle=short]. + +[#zicsr-section-purecap] +==== CSR Instructions + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* CSpecialRW is removed. Its role is assumed by +<>. +endif::[] + +All CSR instructions atomically read-modify-write a single CSR. If the CSR +accessed is of capability size then the +capability's tag, metadata and address are all accessed atomically. + +When the <> instruction is accessing a capability width CSR, then the source +and destination operands are *c* registers and it atomically swaps the values in the +whole CSR with the CLEN width register operand. + +There are special rules for updating specific CLEN-wide CSRs as shown in <>. + +{non-csrrw-and} specify *x* registers and so only access the address field +of the capability when specifying a capability CSR such as <>. +They calculate the final address using the standard +RISC-V behaviour (set bits, clear bits etc.) and that final address is +updated in the capability. The update typically uses the semantics of a <> +instruction which clears the tag if the capability is sealed, or if the +updated address is not representable. <> shows the +exact action taken for each capability width CSR. + +All CSR instructions cause CHERI exceptions if the <> does not grant +<> and the CSR accessed is privileged. + +[#csr-numbers-section] +=== Control and Status Registers (CSRs) + +{cheri_base_ext_name} removes the CSRs listed in +xref:dcsrnames-removed[xrefstyle=short], +xref:mcsrnames-removed[xrefstyle=short], +xref:scsrnames-removed[xrefstyle=short] and +xref:ucsrnames-removed[xrefstyle=short] from the base RISC-V ISA and its +extensions. The CSRs are removed because they are designated to hold addresses, +but are only XLEN bits wide. The removed registers are replaced with CLEN+1 +bits wide registers. The new CSRs are analogous to the original, removed RISC-V +CSRs although at different CSR numbers as shown in +xref:dcsrnames-replaced[xrefstyle=short], +xref:mcsrnames-replaced[xrefstyle=short], +xref:scsrnames-replaced[xrefstyle=short] and +xref:ucsrnames-replaced[xrefstyle=short]. Therefore, the specification of the +address field for the new capability CSRs remains the same as the +corresponding, removed CSR which is described in cite:[riscv-priv-spec] and +the specifications of relevant RISC-V extensions. + +[[dcsrnames-removed]] +.Debug-mode CSRs removed in {cheri_base_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_removed_purecap_mode_d_table_body.adoc[] +|=== + +[[mcsrnames-removed]] +.Machine-mode CSRs removed in {cheri_base_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_removed_purecap_mode_m_table_body.adoc[] +|=== + +[[scsrnames-removed]] +.Supervisor-mode CSRs removed in {cheri_base_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_removed_purecap_mode_s_table_body.adoc[] +|=== + +[[ucsrnames-removed]] +.User-mode CSRs removed in {cheri_base_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_removed_purecap_mode_u_table_body.adoc[] +|=== + +[[dcsrnames-replaced]] +.New debug-mode CSRs in {cheri_base_ext_name} replacing RISC-V CSRs +[%autowidth,float="center",align="center",cols="<,<,<,<,<,<",options="header"] +|=== +include::generated/csr_replaced_purecap_mode_d_table_body.adoc[] +|=== + +[[mcsrnames-replaced]] +.New machine-mode CSRs in {cheri_base_ext_name} replacing RISC-V CSRs +[%autowidth,float="center",align="center",cols="<,<,<,<,<,<",options="header"] +|=== +include::generated/csr_replaced_purecap_mode_m_table_body.adoc[] +|=== + +[[scsrnames-replaced]] +.New supervisor-mode CSRs in {cheri_base_ext_name} replacing RISC-V CSRs +[%autowidth,float="center",align="center",cols="<,<,<,<,<,<",options="header"] +|=== +include::generated/csr_replaced_purecap_mode_s_table_body.adoc[] +|=== + +[[ucsrnames-replaced]] +.New user-mode CSRs in {cheri_base_ext_name} replacing RISC-V CSRs +[%autowidth,float="center",align="center",cols="<,<,<,<,<,<",options="header"] +|=== +include::generated/csr_replaced_purecap_mode_u_table_body.adoc[] +|=== + +{cheri_base_ext_name} also introduces the new unprivileged CSRs shown in +xref:ucsrnames-added[xrefstyle=short]. + +[[ucsrnames-added]] +.User-mode CSRs added in {cheri_base_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_added_purecap_mode_u_table_body.adoc[] +|=== + +=== Machine-Level CSRs + +{cheri_base_ext_name} adds new M-mode capability CSRs and extends some of the +existing RISC-V CSRs with new functions. <> must grant <> +to access M-mode CSRs regardless of the RISC-V privilege mode. + +==== Machine ISA Register (misa) + +The *misa* register operates as described in cite:[riscv-priv-spec] except for +the MXL (Machine XLEN) field. The MXL field encodes the native base integer ISA +width as shown in xref:misa_mxl_field[xrefstyle=short]. Only 1 and 2 are +supported values for MXL and the field must be read-only in implementations +supporting {cheri_base_ext_name}. The effective XLEN in M-mode, MXLEN, is given +by the setting of MXL, or has a fixed value if *misa* is zero. + +.Encoding of MXL field in *misa* +[#misa_mxl_field] +[float="center",align="center",cols="1,1",options="header",width=20%] +|============================================================================== +^| MXL | XLEN +^| 1 | 32 +^| 2 | 64 +^| 3 | [line-through]#128# +|============================================================================== + +NOTE: RV128 is not currently supported by any CHERI extension + +NOTE: A further CHERI extension, {cheri_legacy_ext_name}, optionally makes +MXL writeable, so implementations that support multiple base ISAs must support +both {cheri_base_ext_name} and {cheri_legacy_ext_name}. + +[#mstatus,reftext="mstatus"] +==== Machine Status Registers (mstatus and mstatush) + +The *mstatus* and *mstatush* registers operate as described in +cite:[riscv-priv-spec] except for the SXL and UXL fields that control the +value of XLEN for S-mode and U-mode, respectively. + +The encoding of the SXL and UXL fields is the same as the MXL field of *misa*, +shown in xref:misa_mxl_field[xrefstyle=short]. Only 1 and 2 are supported +values for SXL and UXL and the fields must be read-only in implementations +supporting {cheri_base_ext_name}. The effective XLEN in S-mode and U-mode are +termed SXLEN and UXLEN, respectively. + +NOTE: A further CHERI extension, {cheri_legacy_ext_name}, optionally makes SXL +and UXL writeable, so implementations that support multiple base ISAs must +support both {cheri_base_ext_name} and {cheri_legacy_ext_name}. + +[#mtvec, reftext="mtvec"] +==== Machine Trap-Vector Base-Address Registers (mtvec) + +The <> register is as defined in cite:[riscv-priv-spec]. It is an +MXLEN-bit register used as the executable vector jumped to when taking traps +into machine mode. It is extended into <>. + + +.Machine-mode trap-vector base-address register +include::img/mtvecreg.edn[] + +[#mtvecc,reftext="mtvecc"] +==== Machine Trap-Vector Base-Address Capability Registers (mtvecc) + +The <> register is an extension to <> that holds a capability. +Its reset value is the <> capability. The capability represents +an executable vector. + +.Machine-mode trap-vector base-capability register +include::img/mtveccreg.edn[] + +The metadata is WARL as not all fields need to be implemented, for example the +reserved fields will always read as zero. + +When interpreting <> as a capability, as for <>, address bits +[1:0] are always zero (as they are reused by the MODE field). + +When MODE=Vectored, all synchronous exceptions into machine mode +cause the <> to be set to the capability, whereas +interrupts cause the <> to be set to the capability with +its address incremented by four times the interrupt cause number. + +Capabilities written to <> also include writing the MODE field in +**mtvecc.address[1:0]**. As a result, a representability and sealing check is +performed on the capability with the legalized (WARL) MODE field included in +the address. The tag of the capability written to <> is cleared if +either check fails. + +Additionally, when MODE=Vectored the capability has its tag bit cleared if the +capability address + 4 x HICAUSE is not within the representable bounds. +HICAUSE is the largest exception cause value that the implementation can write +to to <> when an interrupt is taken. + +NOTE: When MODE=Vectored, it is only required that address + 4 x HICAUSE is +within representable bounds instead of the capability's bounds. This ensures +that software is not forced to allocate a capability granting access to more +memory for the trap-vector than necessary to handle the trap causes that +actually occur in the system. + +[#mscratch, reftext="mscratch"] +==== Machine Scratch Register (mscratch) + +The <> register is as defined in cite:[riscv-priv-spec]. It is an +MXLEN-bit read/write register dedicated for use by machine mode. Typically, it +is used to hold a pointer to a machine-mode hart-local context space and +swapped with a user register upon entry to an M-mode trap handler. <> +is extended into <>. + +.Machine-mode scratch register +include::img/mscratchreg.edn[] + +[#mscratchc, reftext="mscratchc"] +==== Machine Scratch Register Capability (mscratchc) + +The <> register is an extension to <> that is able to hold +a capability. Its reset value is the <> capability. + +It is not WARL, all capability fields must be implemented. + +.Machine-mode scratch capability register +include::img/mscratchcreg.edn[] + +[#mepc,reftext="mepc"] +==== Machine Exception Program Counter (mepc) + +The <> register is as defined in cite:[riscv-priv-spec]. It is extended +into <>. + +.Machine exception program counter register +include::img/mepcreg.edn[] + +[#mepcc,reftext="mepcc"] +==== Machine Exception Program Counter Capability (mepcc) + +The <> register is an extension to <> that is able to hold a +capability. Its reset value is the <> capability. + +.Machine exception program counter capability register +include::img/mepccreg.edn[] + +Capabilities written to <> must be legalised by implicitly zeroing bit +**mepcc[0]**. Additionally, if an implementation allows IALIGN to be +either 16 or 32, then whenever IALIGN=32, the capability read from <> +must be legalised by implicitly zeroing bit **mepcc[1]**. Therefore, the +capability read or written has its tag bit cleared if the legalised address is +not within the representable region. + +NOTE: When reading or writing a sealed capability in <>, the +tag is not cleared if the original address equals the legalized +address. + +When a trap is taken into M-mode, <> is written with the <> +including the virtual address of the instruction that was interrupted or that +encountered an exception. Otherwise, <> is never written by the +implementation, though it may be explicitly written by software. + +As shown in xref:CSR_exevectors[xrefstyle=short], <> is an executable +vector, so it need not be able to hold all possible invalid addresses. +Additionally the capability in <> is unsealed when it is installed in +<> on execution of an <> instruction. + +[#mcause,reftext="mcause"] +==== Machine Cause Register (mcause) + +{cheri_base_ext_name} adds a new exception code for CHERI exceptions that +<> must be able to represent. The new exception code and its +priority are listed in xref:mcauses[xrefstyle=short] and +xref:exception-priority[xrefstyle=short] respectively. The behavior and usage +of <> otherwise remains as described in cite:[riscv-priv-spec]. + +.Machine cause register +include::img/mcausereg.edn[] + +[[mcauses]] +.Machine cause register (mcause) values after trap. Entries added in {cheri_base_ext_name} are in *bold* +[%autowidth,float="center",align="center",cols=">,>,<",options="header",] +|=== +|Interrupt |Exception Code |Description +|1 + +1 + +1 + +1 +|0 + +1 + +2 + +3 +|_Reserved_ + +Supervisor software interrupt + +_Reserved_ + +Machine software interrupt + +|1 + +1 + +1 + +1 +|4 + +5 + +6 + +7 +|_Reserved_ + +Supervisor timer interrupt + +_Reserved_ + +Machine timer interrupt +|1 + +1 + +1 + +1 +|8 + +9 + +10 + +11 +|_Reserved_ + +Supervisor external interrupt + +_Reserved_ + +Machine external interrupt +|1 + +1 +|12-15 + +≥16 +|_Reserved_ + +_Designated for platform use_ +|0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +*0* + +0 + +0 + +0 +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10 + +11 + +12 + +13 + +14 + +15 + +16-23 + +24-27 + +*{cheri_excep_mcause}* + +29-31 + +32-47 + +48-63 + +≥64 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode + +Environment call from S-mode + +_Reserved_ + +Environment call from M-mode + +Instruction page fault + +Load page fault + +_Reserved_ + +Store/AMO page fault + +_Reserved_ + +_Designated for custom use_ + +*CHERI fault* + +_Designated for custom use_ + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ +|=== + +[[exception-priority]] +.Synchronous exception priority in decreasing priority order. Entries added in {cheri_base_ext_name} are in *bold* +[%autowidth,float="center",align="center",cols="<,>,<",options="header"] +|=== +|Priority |Exc.Code |Description +|_Highest_ |3 |Instruction address breakpoint +| .>|*{cheri_excep_mcause}* .<|*Prior to instruction address translation:* + +*CHERI fault* +| .>|12, 1 .<|During instruction address translation: + +First encountered page fault or access fault +| .>|1 .<|With physical address for instruction: + +Instruction access fault + +| .>|2 + +0 + +8,9,11 + +3 + +3 .<|Illegal instruction + +Instruction address misaligned + +Environment call + +Environment break + +Load/store/AMO address breakpoint + +| .>|*{cheri_excep_mcause}* .<|*Prior to address translation for an explicit memory access or jump:* + +*CHERI fault* +| .>|4,6 .<|Optionally: + +Load/store/AMO address misaligned +| .>|13, 15, 5, 7 .<|During address translation for an explicit memory access: + +First encountered page fault or access fault +| .>|5,7 .<|With physical address for an explicit memory access: + +Load/store/AMO access fault +.>|_Lowest_ .>|4,6 .<|If not higher priority: + +Load/store/AMO address misaligned +|=== + +[#medeleg,reftext="medeleg"] +==== Machine Trap Delegation Register (medeleg) + +Bit 28 of <> now refers to a valid exception and so can be used to +delegate CHERI exceptions to supervisor mode. + +[#mtval,reftext="mtval"] +==== Machine Trap Value Register (mtval) + +ifdef::cheri_v9_annotations[] +WARNING: *CHERI v9 Note:* Encoding and values changed, and generally were +simplified. +endif::[] + +The <> register is an MXLEN-bit read-write register. When a CHERI fault +is taken into M-mode, <> is written with additional CHERI-specific +exception information with the format shown in +xref:mtval-format[xrefstyle=short] to assist software in handling the trap. + +If the hardware platform specifies that no exceptions set <> to a +nonzero value, then <> is read-only zero. + +.Machine trap value register +[#mtval-format] +include::img/mtvalreg.edn[] + +TYPE is a CHERI-specific fault type that caused the exception while CAUSE +is the cause of the fault. The possible CHERI types and causes are encoded as +shown in xref:mtval-cheri-type[xrefstyle=short] and +xref:mtval-cheri-causes[xrefstyle=short] respectively. + +.Encoding of TYPE field +[#mtval-cheri-type,width=60%,float="center",align="center",options=header,cols="30%,70%"] +|============================================================================== +| CHERI Type Code | Description +| 0 | CHERI instruction access fault +| 1 | CHERI data fault due to load, store or AMO +| 2 | CHERI jump or branch fault +| 3-15 | Reserved +|============================================================================== + +.Encoding of CAUSE field +[#mtval-cheri-causes,width=40%,float="center",align="center",options=header] +|============================================================================== +| CHERI Cause Code | Description +| 0 | Tag violation +| 1 | Seal violation +| 2 | Permission violation +| 3 | Length violation +| 4-15 | Reserved +|============================================================================== + +[#supervisor-level-csrs-section] +=== Supervisor-Level CSRs + +{cheri_base_ext_name} adds new S-mode capability CSRs and extends some of the +existing RISC-V CSRs with new functions. <> must grant <> to +access S-mode CSRs regardless of the RISC-V privilege mode. + +[#stvec,reftext="stvec"] +==== Supervisor Trap Vector Base Address Registers (stvec) + +The <> register is as defined in cite:[riscv-priv-spec]. It is an +SXLEN-bit register used as the executable vector jumped to when taking traps +into supervisor mode. It is extended into <>. + +.Supervisor trap-vector base-address register +include::img/stvecreg.edn[] + +[#stvecc,reftext="stvecc"] +==== Supervisor Trap Vector Base Address Registers (stvecc) + +The <> register is an SXLEN-bit WARL read/write register that holds the +trap vector configuration, consisting of a vector base address (BASE) and a +vector mode (MODE). The <> register is an +extension to <> that is able to hold a capability. Its reset value is +the <> capability. + +.Supervisor trap-vector base-capability register +include::img/stveccreg.edn[] + +The handling of <> is otherwise identical to <>, but in +supervisor mode. + +[#sscratch, reftext="sscratch"] +==== Supervisor Scratch Register (sscratch) + +The <> register is as defined in cite:[riscv-priv-spec]. It is an +MXLEN-bit read/write register dedicated for use by supervisor mode. Typically, +it is used to hold a pointer to a supervisor-mode hart-local context space and +swapped with a user register upon entry to an S-mode trap handler. <> +is extended into <>. + +.Supervisor-mode scratch register +include::img/sscratchreg.edn[] + +[#sscratchc, reftext="sscratchc"] +==== Supervisor Scratch Registers (sscratchc) + +The <> register is an extension to <> that is able to hold +a capability. Its reset value is the <> capability. + +It is not WARL, all capability fields must be implemented. + +.Supervisor scratch capability register +include::img/sscratchcreg.edn[] + +[#sepc,reftext="sepc"] +==== Supervisor Exception Program Counter (sepc) + +The <> register is as defined in cite:[riscv-priv-spec]. It is extended +into <>. + +.Supervisor exception program counter register +include::img/sepcreg.edn[] + +[#sepcc,reftext="sepcc"] +==== Supervisor Exception Program Counter Capability (sepcc) + +The <> register is an extension to <> that is able to hold a +capability. Its reset value is the <> capability. + +As shown in xref:CSR_exevectors[xrefstyle=short], <> is an executable +vector, so it need not be able to hold all possible invalid addresses. +Additionally, the capability in <> is unsealed when it is installed in +<> on execution of an <> instruction. The handling of <> is +otherwise identical to <>, but in supervisor mode. + +.Supervisor exception program counter capability register +include::img/sepccreg.edn[] + +[#scause,reftext="scause"] +==== Supervisor Cause Register (scause) + +{cheri_base_ext_name} adds a new exception code for CHERI exceptions that +<> must be able to represent. The new exception code and its priority +are listed in xref:scauses[xrefstyle=short] and +xref:exception-priority[xrefstyle=short] respectively. The behavior and usage +of <> otherwise remains as described in cite:[riscv-priv-spec]. + +.Supervisor cause register +include::img/scausereg.edn[] + +[[scauses]] +.Supervisor cause register (scause) values after trap. Causes added in {cheri_base_ext_name} are in *bold* +[%autowidth,float="center",align="center",cols=">,>,3",options="header"] +|=== +|Interrupt |Exception Code |Description +|1 + +1 + +1 + +1 + +1 + +1 + +1 + +1 +|0 + +1 + +2-4 + +5 + +6-8 + +9 + +10-15 + +≥16 +|_Reserved_ + +Supervisor software interrupt + +_Reserved_ + +Supervisor timer interrupt + +_Reserved_ + +Supervisor external interrupt + +_Reserved_ + +_Designated for platform use_ + +|0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +*0* + +0 + +0 + +0 +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10-11 + +12 + +13 + +14 + +15 + +16-23 + +24-27 + +*28* + +29-31 + +32-47 + +48-63 + +≥64 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode + +Environment call from S-mode + +_Reserved_ + +Instruction page fault + +Load page fault + +_Reserved_ + +Store/AMO page fault + +_Reserved_ + +_Designated for custom use_ + +*CHERI fault* + +_Designated for custom use_ + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ +|=== + +[#stval,reftext="stval"] +==== Supervisor Trap Value Register (stval) + +The <> register is an SXLEN-bit read-write register. When a CHERI fault +is taken into S-mode, <> is written with additional CHERI-specific +exception information with the format shown in +xref:stval-format[xrefstyle=short] to assist software in handling the trap. + +.Supervisor trap value register +[#stval-format] +include::img/stvalreg.edn[] + +TYPE is a CHERI-specific fault type that caused the exception while CAUSE +is the cause of the fault. The possible CHERI types and causes are encoded as +shown in xref:mtval-cheri-type[xrefstyle=short] and +xref:mtval-cheri-causes[xrefstyle=short] respectively. + +=== Unprivileged CSRs + +Unlike machine and supervisor level CSRs, {cheri_base_ext_name} does not require +<> to grant <> to access privileged CSRs. + +[#pcc,reftext="pcc"] +==== Program Counter Capability (pcc) + +The <> is made visible in a CSR. This provides access to an +<> capability while in debug mode without executing <>. + +NOTE: It is common for implementations to not allow executing *pc* relative +instructions, such as <> or <>, in debug mode. + +.Program Counter Capability +[#pcc-format] +include::img/pccreg.edn[] + +As shown in xref:CSR_exevectors[xrefstyle=short], <> is an executable +vector, so it need not be able to hold all possible invalid addresses. + +=== CHERI Exception handling + +NOTE: `auth_cap` is <> for Legacy mode and `cs1` for Capability Mode + +.Valid CHERI exception combination description +[#cheri_exception_combs_descriptions] +[width="100%",options=header,cols="2,1,1,1,3,4"] +|========================================================================================= +| Instructions | Xcause | Xtval. TYPE | Xtval. CAUSE | Description | Check +6+| *All instructions have these exception checks first* +| All | {cheri_excep_mcause} | {cheri_excep_type_pcc} | {cheri_excep_cause_tag} | <> tag | not(<>.tag) +| All | {cheri_excep_mcause} | {cheri_excep_type_pcc} | {cheri_excep_cause_seal} | <> seal | isCapSealed(<>) +| All | {cheri_excep_mcause} | {cheri_excep_type_pcc} | {cheri_excep_cause_perm} | <> permission | not(<>.<>) +| All | {cheri_excep_mcause} | {cheri_excep_type_pcc} | {cheri_excep_cause_length} | <> length | Any byte of current instruction out of <> bounds +6+| *CSR/Xret additional exception check* +| CSR*, <>, <> | {cheri_excep_mcause} | {cheri_excep_type_pcc} | {cheri_excep_cause_perm} | <> permission | not(<>.<>) when required for CSR access or execution of <>/<> +6+| *direct jumps additional exception check* +| <>, <>, <> | {cheri_excep_mcause} | {cheri_excep_type_jump} | {cheri_excep_cause_length} | <> length | any byte of 16-bit instruction at target out of <> bounds +6+| *indirect jumps and conditional branches additional exception checks* +| indirect jumps and conditional branches | {cheri_excep_mcause} | {cheri_excep_type_jump} | {cheri_excep_cause_tag} |`cs1` tag | not(`cs1.tag`) +| indirect jumps and conditional branches | {cheri_excep_mcause} | {cheri_excep_type_jump} | {cheri_excep_cause_seal} |`cs1` seal | isCapSealed(`cs1`) +| indirect jumps and conditional branches | {cheri_excep_mcause} | {cheri_excep_type_jump} | {cheri_excep_cause_perm} |`cs1` permission| not(`cs1`.<>) +| indirect jumps and conditional branches | {cheri_excep_mcause} | {cheri_excep_type_jump} | {cheri_excep_cause_length} |`cs1` length | any byte of 16-bit instruction at target out of `cs1` bounds +6+| *Load additional exception checks* +| all loads | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_tag} | `auth_cap` tag | not(`auth_cap.tag`) +| all loads | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_seal} | `auth_cap` seal | isCapSealed(`auth_cap`) +| all loads | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_perm} | `auth_cap` permission | not(`auth_cap`.<>) +| all loads | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_length} | `auth_cap` length | Any byte of load access out of `auth_cap` bounds +| capability loads | 4 | N/A | N/A | load address misaligned | Misaligned capability load +6+| *Store/atomic/cache-block-operation additional exception checks* +| all stores, all atomics, all cbos | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_tag} |`auth_cap` tag | not(`auth_cap.tag`) +| all stores, all atomics, all cbos | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_seal} |`auth_cap` seal | isCapSealed(`auth_cap`) +| all atomics, all cbos | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_perm} |`auth_cap` permission | AMO only: not(`auth_cap`.<>) +| all stores, all atomics, all cbos | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_perm} |`auth_cap` permission | not(auto_cap.<>) +| all stores, all atomics | {cheri_excep_mcause} | {cheri_excep_type_data} | {cheri_excep_cause_length} |`auth_cap` length | any byte of access^!^ out of `auth_cap` bounds +| capability stores, all atomics |6 | N/A | N/A |Misaligned store/AMO| Misaligned capability store or AMO +|========================================================================================= + +NOTE: Indirect branches are <>, <>, <>, <>, conditional branches are <>. + +NOTE: <>, <> issues as a cache line wide store + +NOTE: ^1^Other CBOs (<>, <>, <>, <>, <>, <>) require at least one byte of the access to be in `auth_cap` bounds + +=== Physical Memory Attributes (PMA) + +Typically, the entire memory space need not support tagged data. Therefore, it +is desirable that harts supporting {cheri_base_ext_name} extend PMAs with a +_taggable_ attribute indicating whether a memory region allows storing tagged +data. + +When the hart attempts to store or load data with the tag set to memory regions +that are not taggable, the implementation may: + +* Cause an access fault exception +* Implicitly set the stored tag to 0 + +=== Page-Based Virtual-Memory Systems + +RISC-V's page-based virtual-memory management is generally orthogonal to CHERI. +In {cheri_base_ext_name}, capability addresses are interpreted with respect to +the privilege level of the processor in line with RISC-V's handling of integer +addresses. In machine mode, capability addresses are generally interpreted as +physical addresses; if the <> MPRV flag is asserted, then data +accesses (but not instruction accesses) will be interpreted as if performed by +the privilege mode in mstatus's MPP. In supervisor and user modes, capability +addresses are interpreted as dictated by the current *satp* configuration: +addresses are virtual if paging is enabled and physical if not. + +{cheri_base_ext_name} requires that the <> grants the <> to +change the page-table root *satp* and other virtual-memory parameters as +described in xref:supervisor-level-csrs-section[xrefstyle=short]. + +[#section_invalid_addr_conv,reftext="Invalid address conversion"] +==== Invalid Address Handling + +When address translation is in effect and XLEN=64, the upper bits of virtual +memory addresses must match for the address to be valid: + +* For Sv39, bits [63:39] must equal bit 38 +* For Sv48, bits [63:48] must equal bit 47 +* For Sv57, bits [63:57] must equal bit 56 + +RISC-V permits that some CSRs, such as <> and <> (see +xref:CSR_exevectors[xrefstyle=short]), need not be able to hold all possible +invalid addresses. Prior to writing these CSRs, implementations may convert an +invalid address into some other invalid address that the register is capable of +holding. However, these registers hold capabilities in {cheri_base_ext_name} +and the bounds encoding depends on the address value, so implementations must +not convert invalid addresses to other arbitrary invalid address in an +unrestricted manner. +The following procedure must be used instead when writing a capability A to +these CSRs: + +. If A's address cannot be held then convert it to another address that the CSR can +hold +. If conversion _was_ required, then A's tag is cleared if A is +sealed or if the new address is not representable -- this is equivalent to the +semantics of <> +. Write the final (potentially modified) version of capability A to the CSR e.g. +<>, <>, etc. + +This implies that sealed capabilities will always get their tags cleared when +written to these CSRs unless the specification explicitly states that the CSR +behaves otherwise (see <> and <>). Also notes that <> is +available in a read-only CSR. It can be written with <> instruction +which automatically unseals the capability _before_ the invalid address +conversion above. + diff --git a/src/riscv-legacy-integration.adoc b/src/riscv-legacy-integration.adoc new file mode 100644 index 00000000..6a1475fa --- /dev/null +++ b/src/riscv-legacy-integration.adoc @@ -0,0 +1,382 @@ +== "Zcheri_legacy" Extension for CHERI Legacy Mode + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* This feature is new and different from CHERI v9's +per-privilege enable bits. +endif::[] + +{cheri_legacy_ext_name} is an optional extension to {cheri_base_ext_name}. +Implementations that support {cheri_base_ext_name} and {cheri_legacy_ext_name} +define a variant of the CHERI ISA that is fully binary compatible with +existing RISC-V code. + +Key features in {cheri_legacy_ext_name} include a definition of a CHERI execution mode, a new +unprivileged register, additional instructions and extensions to some existing +CSRs enabling disable CHERI features. The remainder of this section describes +these features in detail as well as their integration with the primary base +integer variants of the the RISC-V ISA (RV32I and RV64I). + +=== CHERI Execution Mode + +{cheri_legacy_ext_name} adds CHERI execution modes to ensure backwards +compatibility with the base RISC-V ISA while saving instruction encoding space. +There are two execution modes: _Capability_ and _Legacy_. Additionally, there +is a new unprivileged register: the default data capability, <>, that is +used to authorise all data memory accesses when the current CHERI mode is +Legacy. + +The current CHERI execution mode is given by the current privilege level and +the value of the CME bit in <> and <> for S-mode and U-mode. +M-mode is always in Capability mode. + +The CHERI execution mode impacts the instruction set in the following ways: + +* The authorising capability used to execute memory access instructions. +In Legacy mode, <> is implicitly used. In Capability mode, the authorising +capability is supplied as an explicit *c* operand register to the instruction. +* The set of instructions that is available for execution. Some instructions +are available in Legacy mode but not Capability mode and vice-versa (see +xref:riscv-extensions[xrefstyle=short]). + +NOTE: The implication is that the CHERI execution mode is always Capability on +implementations that support {cheri_base_ext_name}, but not +{cheri_legacy_ext_name}. + +The CHERI execution mode is effectively an extension to some RISC-V instruction +encodings. For example, the encoding of an instruction like <> remains +unchanged, but the mode indicates whether the capability authorising the load +is the register operand `cs1` (Capability mode), so the instruction is <> +from {cheri_base_ext_name}, or <> (Legacy mode), so the instruction is +simply <>. + +The CHERI execution mode is key in providing backwards compatibility with the +base RISC-V ISA. RISC-V software is able to execute unchanged in +implementations supporting both {cheri_base_ext_name} and +{cheri_legacy_ext_name} provided that the configured CHERI execution mode is +Legacy by setting CME=0 in <> or <> as required, and the +<> capability is installed in the <> and <> such that: + +* Tags are set +* Capabilities are unsealed +* All permissions are granted +* The bounds authorise accesses to the entire address space i.e base is 0 and +top is 2^XLENMAX^ + +[#section_legacy_ext_instructions] +=== Zcheri_legacy Instructions + +{cheri_legacy_ext_name} does not introduce new instructions to the base RISC-V +integer ISA. However, the behavior of some existing instructions changes +depending on the current CHERI execution mode. + +==== Capability Load and Store Instructions + +The load and store capability instructions change behaviour depending on the +CHERI execution mode although the instruction's encoding remains unchanged. + +The load capability instruction is <> when the CHERI execution mode is +Capability; the instruction behaves as described in +xref:section_cap_instructions[xrefstyle=short]. That encoding is <> when +the mode is Legacy. In this case, the capability authorising the memory access +is <>, so the effective address is obtained by adding the *x* register to +the sign-extended offset. + +The store capability instruction is <> when the CHERI execution mode is +Capability; the instruction behaves as described in +xref:section_cap_instructions[xrefstyle=short]. That encoding is <> when +the mode is Legacy. In this case, the capability authorising the memory access +is <>, so the effective address is obtained by adding the *x* register to +the sign-extended offset. + +==== Unconditional Capability Jumps + +The indirect jump and link <> (<>) instruction shares the same +encoding with a new indirect jump and link capability (<>) instruction. +<> is a {cheri_base_ext_name} instruction executed when the mode is +Capability as described in +xref:section_uncond_integer_addr_jump[xrefstyle=short]. In Legacy mode, the +encoding is executed as <> which allows unconditional jumps to a target +capability. The target capability is provided in a *c* register and is written +to <>. The <> of the next instruction following the jump (<> + 4) is +written to a *c* register. <> cause CHERI exceptions when: + +* The target capability's tag is zero +* A minimum sized instruction at the target capability's address is not +within bounds +* The target capability does not grant execute permission + +<> causes an instruction address misaligned exception when the target +address is misaligned. + +NOTE: <> can be used to change the current CHERI execution mode when +the implementation supports {cheri_mode_ext_name}. + +=== Existing RISC-V Instructions + +The CHERI execution mode introduced in {cheri_legacy_ext_name} affects the +behaviour of instructions that have at least one memory address operand. When +in Capability mode, the address input or output operands may include *c* registers. +When in Legacy mode, the address input or output operands are *x/f/v* registers; +the tag and metadata of that register are implicitly set to 0. + +==== Control Transfer Instructions + +The unconditional jump instructions change behaviour depending on the CHERI +execution mode although the instruction's encoding remains unchanged. + +The jump and link instruction is <> when the CHERI execution mode is +Capability; the instruction behaves as described in +xref:section_existing_riscv_insns[xrefstyle=short]. That encoding is <> +when the mode is Legacy. In this case, the address of the instruction +following the jump (*pc* + 4) is written to an *x* register; that register's +tag and capability metadata are zeroed. + +The jump and link register instruction is <> when the CHERI execution mode +is Capability; the instruction behaves as described in +xref:section_existing_riscv_insns[xrefstyle=short]. That encoding is <> +when the mode is Legacy. In this case, the target address is obtained by adding +the sign-extended 12-bit immediate to the *x* register operand, then setting +the least significant bit of the result to zero. The target address is then +written to the <> address and a representability check is performed. The +address of the instruction following the jump (*pc* + 4) is written to an *x* +register; that register's tag and capability metadata are zeroed. + +<> and <> cause CHERI exceptions when a minimum sized instruction +at the target address are not within the bounds of the <>. An +instruction address misaligned exception is raised when the target address is +misaligned. + +==== Conditional Branches + +The behaviour is as shown in xref:condbr-purecap[xrefstyle=short]. + +==== Load and Store Instructions + +Load and store instructions change behavior depending on the CHERI execution +mode although the instruction's encoding remains unchanged. + +Loads and stores behave as described in +xref:section_existing_riscv_insns[xrefstyle=short] when the CHERI execution +mode is Capability. In Legacy mode, the instructions behave as described in +the RISC-V base ISA (i.e. without the 'C' prefix) and rely on *x* operands +only. The capability authorising the memory access is <> and the memory +address is given by sign-extending the 12-bit immediate offset and adding it to +the base address in the *x* register operand. + +The exception cases remain as described in +xref:section_existing_riscv_insns[xrefstyle=short] regardless of the CHERI +execution mode. + +[#zicsr-section-legacy] +==== CSR Instructions + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* CSpecialRW is removed. Its role is assumed by +<>. +endif::[] + +{cheri_legacy_ext_name} adds the concept of CSRs which contain a capability +where the address field is visible to legacy code (e.g. <>) and the +full capability is also visible through an alias (e.g. <>). These +are referred to as _extended CSRs_. + +Extended CSRs are accessible through two addresses, and the address determines +the access width. + +When the XLEN-bit alias is used by <>: + +* The register operand is an *x* register. +* Only XLEN bits from the *x* source are written to the capability address +field. + ** The tag and metadata are updated as specified in <>. +* Only XLEN bits are read from the capability address field, which is zero +extended to the destination *x* register. + +When the CLEN-bit alias is used by <>: + +* The register operand is a *c* register. +* The full capability in the *c* register source is written to the CSR. +** The capability may require modification before the final written value is +determined (see <>). +* The full capability is written to destination *c* register. + +When either alias is used by another CSR instruction (<>, <>, +<>, <>, <>):. + +* The final address is calculated according to the standard RISC-V CSR rules +(set bits, clear bits etc). +* The final address is updated as specified in <> for an +XLEN write. +* XLEN bits are read from the capability address field and written to an output +*x* register. + +There is _no distinction_ between accessing either alias in this case - the +XLEN access is always performed, and the assembly syntax always uses *x* +registers. + +All CSR instructions cause CHERI exceptions if the <> does not grant +<> and the CSR accessed is not user-mode accessible. + +[#section_legacy_debug_integration] +=== Integrating Zcheri_legacy with Sdext + +A new debug default data capability (<>) CSR is added at the CSR number +shown in xref:legacy-csrnames-added[xrefstyle=short]. + +[#dddc,reftext="dddc"] +=== Debug Default Data Capability (dddc) + +<> is a register that is able to hold a capability. Its reset value is +the <> capability. The address is shown in +xref:legacy-csrnames-added[xrefstyle=short]. + +.Debug default data capability +include::img/dddcreg.edn[] + +Upon entry to debug mode, <> is saved in <>. <>'s metadata is +set to the <> capability's metadata and <>'s address remains +unchanged. + +When debug mode is exited by executing <>, the hart's <> is updated to +the capability stored in <>. A debugger may write <> to change the +hart's context. + +[#section_cheri_disable] +=== Disabling CHERI Features + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The rules for excepting have been tightened here. Also, +it is not possible to disable CHERI checks completely. +endif::[] + +{cheri_legacy_ext_name} includes functions to disable most CHERI features. For +example, executing in a privilege mode where the effective XLEN is less than +XLENMAX. The following occurs when executing code in a privileged that has +CHERI disabled: + +* The CHERI instructions in xref:section_cap_instructions[xrefstyle=short] (and +xref:instruction-modes[xrefstyle=short] if {cheri_mode_ext_name} is supported) +cause illegal instruction exceptions +* Executing CSR instructions accessing any capability wide CSR +addresses (xref:csr-numbers-section[xrefstyle=short]) cause illegal +instruction exceptions +* All allowed instructions execute as if the CHERI execution mode is Legacy. +The CME bits in <> and <> have no effect whilst CHERI is +disabled. + +Security checks continue to be enforced when CHERI is disabled regardless of +the reason. The last capability installed in <> and <> before +disabling CHERI will be used to authorise instruction execution and data memory +accesses. + +=== Added CLEN-wide CSRs + +{cheri_legacy_ext_name} adds the CLEN-wide CSRs shown in +xref:legacy-csrnames-added[xrefstyle=short]. + +[[legacy-csrnames-added]] +.CLEN-wide CSRs added in {cheri_legacy_ext_name} +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +include::generated/csr_added_legacy_table_body.adoc[] +|=== + +==== Machine ISA Register (misa) + +{cheri_legacy_ext_name} eliminates some restrictions for MXL imposed in +{cheri_base_ext_name} to allow implementations supporting multiple base ISAs. +Namely, the MXL field, that encodes the native base integer ISA width as shown +in xref:misa_mxl_field[xrefstyle=short], may be writable. + +Setting the MXL field to a value that is not XLENMAX disables most CHERI +features and instructions as described in +xref:section_cheri_disable[xrefstyle=short]. + +==== Machine Status Registers (mstatus and mstatush) + +{cheri_legacy_ext_name} eliminates some restrictions for SXL and UXL imposed in +{cheri_base_ext_name} to allow implementations supporting multiple base ISAs. +Namely, the SXL and UXL fields may be writable. + +{cheri_legacy_ext_name} requires that lower-privilege modes have XLEN settings +less than or equal to the next-higher privilege mode. WARL field behaviour +restricts programming so that it is not possible to program MXL, SXL or UXL +to violate this rule. + +Setting the SXL or UXL field to a value that is not XLENMAX disables most +CHERI features and instructions, as described in +xref:section_cheri_disable[xrefstyle=short], while in that privilege mode. + +Whenever XLEN in any mode is set to a value less than XLENMAX, standard RISC-V +rules from cite:[riscv-unpriv-spec] are followed. This means that all operations +must ignore source operand register bits above the configured XLEN, and must +sign-extend results to fill the entire widest supported XLEN in the destination +register. Similarly, *pc* bits above XLEN are ignored, and when the *pc* is +written, it is sign-extended to fill XLENMAX. The integer writing rule from CHERI +is followed, so that every register write also zeroes the metadata and tag of +the destination register. + +However, CHERI operations and security checks will continue using the entire +hardware register (i.e. CLEN bits) to correctly decode capability bounds. + +[#mtdc,reftext="mtdc"] +==== Machine Trap Default Capability Register (mtdc) + +The <> register is capability width read/write register dedicated +for use by machine mode. Typically, it is used to hold a data capability to a +machine-mode hart-local context space, to load into <>. <>'s reset +value is the <> capability. + +.Machine-mode trap data capability register +include::img/mtdcreg.edn[] + +[#menvcfg,reftext="menvcfg"] +==== Machine Environment Configuration Register (menvcfg) + +{cheri_legacy_ext_name} adds a new enable bit to <> as shown in +xref:menvcfgmodereg[xrefstyle=short]. + +.Machine environment configuration register (*menvcfg*) +[#menvcfgmodereg] +include::img/menvcfgmodereg.edn[] + +The CHERI Mode Enable (CME) bit controls whether less privileged levels (e.g. +S-mode and U-mode) execute in Capability or Legacy mode. When CME=1, the +CHERI execution mode is Capability. When CME=0, the mode is Legacy. + +[#stdc,reftext="stdc"] +==== Supervisor Trap Default Capability Register (stdc) + +The <> register is capability width read/write register dedicated +for use by supervisor mode. Typically, it is used to hold a data capability to +a supervisor-mode hart-local context space, to load into <>. <>'s +reset value is the <> capability. + +.Supervisor trap data capability register (*stdc*) +include::img/stdcreg.edn[] + +[#senvcfg,reftext="senvcfg"] +==== Supervisor Environment Configuration Register (senvcfg) + +The *senvcfg* register operates as described in the RISC-V Privileged +Specification. {cheri_legacy_ext_name} adds one new enable bit as shown in +xref:senvcfgreg[xrefstyle=short]. + +.Supervisor environment configuration register (*senvcfg*) +[#senvcfgreg] +include::img/senvcfgreg.edn[] + +The CHERI Mode Enable (CME) bit controls whether U-mode executes in Capability +or Legacy mode. When CME=1, the CHERI execution mode is Capability. When CME=0, +the mode is Legacy. + +[#ddc,reftext="ddc"] +==== Default Data Capability (ddc) + +The <> CSR is a read-write capability register implicitly used as an +operand to authorise all data memory accesses when the current CHERI mode is +Legacy. This register must be readable in any implementation. Its reset value +is the <> capability. + +.Unprivileged default data capability register +include::img/ddcreg.edn[] diff --git a/src/riscv-mode-integration.adoc b/src/riscv-mode-integration.adoc new file mode 100644 index 00000000..b534a1b7 --- /dev/null +++ b/src/riscv-mode-integration.adoc @@ -0,0 +1,73 @@ +== "Zcheri_mode" Extension for CHERI Execution Mode + +{cheri_mode_ext_name} is an optional extension to {cheri_legacy_ext_name}. +Implementations that support {cheri_mode_ext_name} allow fine-grained switching +between Capability and Legacy modes using indirect jump instructions. + +[#section-cheri-execution-mode] +=== CHERI Execution Mode + +{cheri_mode_ext_name} adds a new CHERI execution mode bit (M) to capabilities. +The mode bit is encoded as shown in +xref:cap_encoding_xlen32_mode[xrefstyle=short] and +xref:cap_encoding_xlen64_mode[xrefstyle=short]. The current CHERI execution +mode is give by the M bit of the <> and the CME bits in <> and +<> as follows: + +* The mode is Capability when the M bit of the <> is 1 and the effective +CME=1 for the current privilege level +* The mode is Legacy when the effective CME=0 for the current privilege level +* The mode is Legacy when the M bit of the <> is 0 and the effective CME=1 +for the current privilege level + +.Capability encoding when XLENMAX=32 and {cheri_mode_ext_name} is supported +[#cap_encoding_xlen32_mode] +include::img/cap-encoding-xlen32-mode.edn[] + +.Capability encoding when XLENMAX=64 and {cheri_mode_ext_name} is supported +[#cap_encoding_xlen64_mode] +include::img/cap-encoding-xlen64-mode.edn[] + +{cheri_mode_ext_name} allows the M bit to be set to 1 when the capability does +not grant <>. In this case, the M bit is superfluous, so the encoding +may be used to support additional features in future extensions. + +[#section_mode_cap_instructions] +=== Zcheri_mode Instructions + +{cheri_mode_ext_name} introduces new instructions to the base RISC-V integer +ISA in addition to the instructions added in {cheri_base_ext_name}. The new +instructions in {cheri_mode_ext_name} allows inspecting the CHERI mode bit in +capabilities and changing the current CHERI execution mode. + +==== Capability Manipulation Instructions + +A new <> instruction allows setting a capability's CHERI execution +mode to the indicated value. The output is written to an unprivileged *c* +register, not <>. + +==== Mode Change Instructions + +A new CHERI execution mode switch (<>) instruction allows software +to toggle the hart's current CHERI execution mode. If the current mode in the +<> is Legacy, then the mode after executing <> is Capability +and vice-versa. This instruction effectively writes the CHERI execution mode +bit M of the capability currently installed in the <>. + +==== Unconditional Capability Jumps + +{cheri_mode_ext_name} allows changing the current CHERI execution mode when +executing <> or <>. + +=== Integrating Zcheri_mode with Sdext + +ifdef::cheri_v9_annotations[] +NOTE: *CHERI v9 Note:* The mode change instruction <> is new +and the requirement to optionally support it in debug mode is also new. +endif::[] + +In addition to the changes described in +xref:section_debug_integration[xrefstyle=short] and +xref:section_legacy_debug_integration[xrefstyle=short], {cheri_mode_ext_name} +allows <> to act as an illegal instruction when it is executed +while in debug mode. diff --git a/src/scripts/generate_tables.py b/src/scripts/generate_tables.py new file mode 100755 index 00000000..52c30067 --- /dev/null +++ b/src/scripts/generate_tables.py @@ -0,0 +1,799 @@ +#!/usr/bin/env python3 + +import os +import shutil +import csv +import argparse + +class table: + """ + virtual class used to define each table + """ + filename = "" + file = "" + header = [] + + def __init__(self, filename, header): + + self.filename = filename + if os.path.exists(self.filename): + os.remove(self.filename) + self.file = open(self.filename, 'w') + self.header = header + + def __del__(self): + self.file.close() + + def update(self, row): + pass + +class Zbh_lr_sc_insns(table): + cols = ["Mnemonic", "Zcheri_legacy", "Zcheri_purecap", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Zbhlrsc")] == "✔" + +class Zcheri_legacy_insns(table): + cols = ["Mnemonic", "RV32", "RV64", "A", "Zbhlrsc", "Zicbo[mpz]", "C or Zca", "Zba", "Zcb", "Zcmp", "Zcmt", "Zfh", "F", "D", "V", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Zcheri_legacy")] == "✔" + +class Zcheri_mode_insns(table): + cols = ["Mnemonic", "RV32", "RV64", "A", "Zbhlrsc", "Zicbo[mpz]", "C or Zca", "Zba", "Zcb", "Zcmp", "Zcmt", "Zfh", "F", "D", "V", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Zcheri_mode")] == "✔" + +class Zcheri_purecap_insns(table): + cols = ["Mnemonic", "RV32", "RV64", "A", "Zbhlrsc", "Zicbo[mpz]", "C or Zca", "Zba", "Zcb", "Zcmp", "Zcmt", "Zfh", "F", "D", "V", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Zcheri_purecap")] == "✔" + +class cap_mode_insns(table): + cols = ["Mnemonic", "Zcheri_mode", "Zcheri_legacy", "Zcheri_purecap", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Valid Modes")] == "Capability" + +class legacy_mode_insns(table): + cols = ["Mnemonic", "Zcheri_mode", "Zcheri_legacy", "Zcheri_purecap", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Valid Modes")] == "Legacy" + +class both_mode_insns(table): + cols = ["Mnemonic", "Zcheri_mode", "Zcheri_legacy", "Zcheri_purecap", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Valid Modes")] == "Both" + +class xlen_dependent_encoding_insns(table): + cols = ["Mnemonic", "Function"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("XLEN dependent encoding")] == "✔" + +class illegal_insns(table): + cols = ["Mnemonic", "illegal insn if (1)", "OR illegal insn if (2)", "OR illegal insn if (3)"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("illegal insn if (1)")] != "" + +class legacy_mnemonic_insns(table): + cols = ["Mnemonic", "Legacy mnemonic RV32", "Legacy mnemonic RV64"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + outStr += '|<<'+row[i]+'>>' + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Legacy mnemonic RV32")] != "" and row[self.header.index("Legacy mnemonic RV64")] != "" + +class csr_aliases(table): + cols = ["Extended CSR", "Alias", "Prerequisites"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i<=2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" + +class csr_removed_purecap_mode_d(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "D" + +def resolve_col_display_name(col_name): + col_display_names = { + "Extended CSR": "{cheri_base_ext_name} CSR", + "Alias": "Replaced CSR", + "CLEN Address": "Address", + "XLEN Address": "Address", + } + + return col_display_names[col_name] if col_name in col_display_names else col_name + +class csr_replaced_purecap_mode_d(table): + cols = ["Extended CSR", "CLEN Address", "Alias", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "D" + +class csr_added_legacy(table): + cols = ["Extended CSR", "CLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] == "" and row[self.header.index("Zcheri_purecap")] == "" + +class csr_added_purecap_mode_d(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] == "" and row[self.header.index("Mode")] == "D" + + +class csr_removed_purecap_mode_m(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "M" + +class csr_replaced_purecap_mode_m(table): + cols = ["Extended CSR", "CLEN Address", "Alias", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "M" + +class csr_added_purecap_mode_m(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] == "" and row[self.header.index("Mode")] == "M" + +class csr_removed_purecap_mode_s(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "S" + +class csr_replaced_purecap_mode_s(table): + cols = ["Extended CSR", "CLEN Address", "Alias", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "S" + +class csr_added_purecap_mode_s(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] == "" and row[self.header.index("Mode")] == "S" + +class csr_removed_purecap_mode_u(table): + cols = ["Alias", "XLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "U" + +class csr_replaced_purecap_mode_u(table): + cols = ["Extended CSR", "CLEN Address", "Alias", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(map(resolve_col_display_name, self.cols))+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" and row[self.header.index("Mode")] == "U" + +class csr_added_purecap_mode_u(table): + cols = ["Extended CSR", "CLEN Address", "Prerequisites", "Permissions", "Description"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0 or i==2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] == "" and row[self.header.index("Mode")] == "U" and row[self.header.index("Zcheri_purecap")] == "✔" + +class csr_alias_action(table): + cols = ["Extended CSR", "Action on XLEN write", "Action on CLEN write"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i<2: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Alias")] != "" + +class csr_perms(table): + cols = ["Extended CSR", "Zcheri_legacy", "Zcheri_purecap", "Prerequisites", "CLEN Address", "Permissions", "Reset Value"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Extended CSR")] != "" + +class csr_exevectors(table): + cols = ["Extended CSR", "Executable Vector", "Unseal On Execution"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Executable Vector")] == "✔" or row[self.header.index("Unseal On Execution")] == "✔" + +class csr_metadata(table): + cols = ["Extended CSR", "Store full metadata"] + indices = [] + + def __init__(self, filename, header): + super().__init__(filename, header) + self.file.write('|'+'|'.join(self.cols)+'\n') + self.indices=[] + for i in self.cols: + self.indices.append(self.header.index(i)) + + def update(self, row): + if self.check(row): + outStr = "" + for i in self.indices: + if i==0: + #make an xref + outStr += '|<<'+row[i]+'>>' + else: + outStr += '|'+row[i] + self.file.write(outStr+'\n') + + def check(self,row): + return row[self.header.index("Store full metadata")] == "✔" + +def parse_cmdline_args(): + parser = argparse.ArgumentParser(description="Generate tables for CHERI ISA specification") + + parser.add_argument("--output-dir", "-o", metavar="DIR", type=str, help="Output directory where generated files are written") + parser.add_argument("--csr", metavar="CSV", type=str, help="Input CSV file with list of CSRs") + parser.add_argument("--isa", metavar="CSV", type=str, help="Input CSV file with list of instructions") + + return parser.parse_args() + +if __name__ == "__main__": + args = parse_cmdline_args() + + if os.path.exists(args.output_dir) == 0: + os.mkdir(args.output_dir) + + with open(args.csr,newline='') as csrFile: + reader = csv.reader(csrFile, delimiter=',') + header = next(reader) + tables = [] + + tables.append(csr_alias_action (os.path.join(args.output_dir, "csr_alias_action_table_body.adoc"),header)) + tables.append(csr_aliases (os.path.join(args.output_dir, "csr_aliases_table_body.adoc"),header)) + tables.append(csr_removed_purecap_mode_d (os.path.join(args.output_dir, "csr_removed_purecap_mode_d_table_body.adoc"),header)) + tables.append(csr_removed_purecap_mode_m (os.path.join(args.output_dir, "csr_removed_purecap_mode_m_table_body.adoc"),header)) + tables.append(csr_removed_purecap_mode_s (os.path.join(args.output_dir, "csr_removed_purecap_mode_s_table_body.adoc"),header)) + tables.append(csr_removed_purecap_mode_u (os.path.join(args.output_dir, "csr_removed_purecap_mode_u_table_body.adoc"),header)) + tables.append(csr_replaced_purecap_mode_d(os.path.join(args.output_dir, "csr_replaced_purecap_mode_d_table_body.adoc"),header)) + tables.append(csr_replaced_purecap_mode_m(os.path.join(args.output_dir, "csr_replaced_purecap_mode_m_table_body.adoc"),header)) + tables.append(csr_replaced_purecap_mode_s(os.path.join(args.output_dir, "csr_replaced_purecap_mode_s_table_body.adoc"),header)) + tables.append(csr_replaced_purecap_mode_u(os.path.join(args.output_dir, "csr_replaced_purecap_mode_u_table_body.adoc"),header)) + tables.append(csr_added_purecap_mode_d (os.path.join(args.output_dir, "csr_added_purecap_mode_d_table_body.adoc"),header)) + tables.append(csr_added_purecap_mode_m (os.path.join(args.output_dir, "csr_added_purecap_mode_m_table_body.adoc"),header)) + tables.append(csr_added_purecap_mode_s (os.path.join(args.output_dir, "csr_added_purecap_mode_s_table_body.adoc"),header)) + tables.append(csr_added_purecap_mode_u (os.path.join(args.output_dir, "csr_added_purecap_mode_u_table_body.adoc"),header)) + tables.append(csr_added_legacy (os.path.join(args.output_dir, "csr_added_legacy_table_body.adoc"),header)) + tables.append(csr_perms (os.path.join(args.output_dir, "csr_permission_table_body.adoc"),header)) + tables.append(csr_exevectors (os.path.join(args.output_dir, "csr_exevectors_table_body.adoc"),header)) + tables.append(csr_metadata (os.path.join(args.output_dir, "csr_metadata_table_body.adoc"),header)) + + for row in reader: + for t in tables: + t.update(row) + + with open(args.isa,newline='') as isaFile: + reader = csv.reader(isaFile, delimiter=',') + header = next(reader) + tables = [] + + #same for rv32/rv64 + tables.append(Zbh_lr_sc_insns (os.path.join(args.output_dir, "Zbh_lr_sc_insns_table_body.adoc"), header)) + tables.append(Zcheri_mode_insns (os.path.join(args.output_dir, "Zcheri_mode_insns_table_body.adoc"), header)) + tables.append(Zcheri_legacy_insns (os.path.join(args.output_dir, "Zcheri_legacy_insns_table_body.adoc"), header)) + tables.append(Zcheri_purecap_insns (os.path.join(args.output_dir, "Zcheri_purecap_insns_table_body.adoc"), header)) + tables.append(xlen_dependent_encoding_insns(os.path.join(args.output_dir, "xlen_dependent_encoding_insns_table_body.adoc"), header)) + tables.append(legacy_mnemonic_insns (os.path.join(args.output_dir, "legacy_mnemonic_insns_table_body.adoc"), header)) + tables.append(illegal_insns (os.path.join(args.output_dir, "illegal_insns_table_body.adoc"), header)) + tables.append(cap_mode_insns (os.path.join(args.output_dir, "cap_mode_insns_table_body.adoc"), header)) + tables.append(legacy_mode_insns (os.path.join(args.output_dir, "legacy_mode_insns_table_body.adoc"), header)) + tables.append(both_mode_insns (os.path.join(args.output_dir, "both_mode_insns_table_body.adoc"), header)) + + for row in reader: + for t in tables: + t.update(row) \ No newline at end of file diff --git a/src/tables.adoc b/src/tables.adoc new file mode 100644 index 00000000..53d86e60 --- /dev/null +++ b/src/tables.adoc @@ -0,0 +1,160 @@ +== Extension summary + +=== Zbhlrsc + +{lr_sc_bh_ext_name} is a separate extension independent of CHERI, but is required for CHERI software. + +.{lr_sc_bh_ext_name} instruction extension +[#Zbh_lr_sc_instruction_extension] +[width="100%",options=header,cols="2,2,2,10"] +|============================================================================== +include::generated/Zbh_lr_sc_insns_table_body.adoc[] +|============================================================================== + +=== Zcheri_purecap + +{cheri_base_ext_name} defines the set of instructions used by a purecap core. + +Some instructions depend on the presence of other extensions, as listed in xref:Zcheri_purecap_instruction_extension[xrefstyle=short] + +.{cheri_base_ext_name} instruction extension - Pure Capability Mode instructions +[#Zcheri_purecap_instruction_extension] +[width="100%",options=header,cols="3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,4"] +|============================================================================== +include::generated/Zcheri_purecap_insns_table_body.adoc[] +|============================================================================== + +=== Zcheri_legacy + +{cheri_legacy_ext_name} defines the set of instructions added by the legacy mode, in addition to {cheri_base_ext_name}. + +NOTE: {cheri_legacy_ext_name} implies {cheri_base_ext_name} + +.{cheri_legacy_ext_name} instruction extension - legacy mode instructions +[#Zcheri_legacy_instruction_extension] +[width="100%",options=header,cols="3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,4"] +|============================================================================== +include::generated/Zcheri_legacy_insns_table_body.adoc[] +|============================================================================== + +=== Zcheri_mode + +{cheri_legacy_ext_name} defines the set of instructions added by the mode switching mode, in addition to {cheri_legacy_ext_name}. + +NOTE: {cheri_mode_ext_name} implies {cheri_legacy_ext_name} + +.{cheri_mode_ext_name} instruction extension - mode switching instructions +[#Zcheri_mode_instruction_extension] +[width="100%",options=header,cols="3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,4"] +|============================================================================== +include::generated/Zcheri_mode_insns_table_body.adoc[] +|============================================================================== + +[#instruction-modes] +=== Instruction Modes + +The tables summarise which operating modes each instruction may be executed in. + +.Instructions valid for execution in capability mode only +[#cap_mode_insns] +[width="100%",options=header,cols="3,1,1,1,3"] +|============================================================================== +include::generated/cap_mode_insns_table_body.adoc[] +|============================================================================== + +<<< + +.Instructions valid for execution in legacy mode only +[#legacy_mode_insns] +[width="100%",options=header,cols="3,1,1,1,3"] +|============================================================================== +include::generated/legacy_mode_insns_table_body.adoc[] +|============================================================================== + +.Instructions valid for execution in both capability and legacy modes +[#both_mode_insns] +[width="100%",options=header,cols="3,1,1,1,3"] +|============================================================================== +include::generated/both_mode_insns_table_body.adoc[] +|============================================================================== + +[#clen_csr_summary] +== Capability Width CSR Summary + +.CSRs extended to capability width, accessible through an alias +[#aliased_CSRs] +[width="100%",options=header,cols="1,1,1"] +|============================================================================== +include::generated/csr_aliases_table_body.adoc[] +|============================================================================== + +.Action taken on writing to extended CSRs. +[#extended_CSR_writing] +[width="100%",options=header,cols="1,2,2"] +|============================================================================== +include::generated/csr_alias_action_table_body.adoc[] +|============================================================================== + +^*^ The vector range check is to ensure that vectored entry to the handler + in within bounds of the capability written to `Xtvecc`. The check on writing + must include the lowest (0 offset) and highest possible offset (e.g. 64 * XLENMAX bits where HICAUSE=16). + +NOTE: Implementations which allow misa.C to be writable need to legalise *Xepcc* + on _reading_ if the misa.C value has changed since the value was written as this + can cause the read value of bit [1] to change state. + +NOTE: <> make an XLEN-wide access to the XLEN-wide CSR aliases or a CLEN-wide access to the CLEN-wide aliases for all extended CSRs. + {non-csrrw-and} only make XLEN-wide accesses even if the CLEN-wide alias is specified. + +.CLEN-wide CSRs storing executable vectors +[#CSR_exevectors] +[width="100%",options=header,cols="1,1,1"] +|============================================================================== +include::generated/csr_exevectors_table_body.adoc[] +|============================================================================== + +Some CSRs store executable vectors as shown in xref:CSR_exevectors[xrefstyle=short]. These CSRs do not need to store the full width address on RV64. +If they store fewer address bits then writes are subject to the invalid address +check in <>. + +.CLEN-wide CSRs which store all CLEN+1 bits +[#CSR_metadata] +[width="100%",options=header,cols="1,1"] +|============================================================================== +include::generated/csr_metadata_table_body.adoc[] +|============================================================================== + +xref:CSR_metadata[xrefstyle=short] shows which CLEN-wide CSRs store all CLEN+1 bits. No other CLEN-wide CSRs store any reserved bits. All CLEN-wide CSRs store _all_ non-reserved metadata fields. + +.All CLEN-wide CSRs +[#extended_CSRs] +[width="100%",options=header,cols="2,1,1,1,1,3,2"] +|============================================================================== +include::generated/csr_permission_table_body.adoc[] +|============================================================================== + +=== Other tables + +.Mnemonics with the same encoding but mapped to different instructions in Legacy and Capability Mode +[#legacy_mnemonics] +[width="100%",options=header] +|============================================================================== +include::generated/legacy_mnemonic_insns_table_body.adoc[] +|============================================================================== + +.Instruction encodings which vary depending on the current XLEN +[#xlen_dependent_encodings] +[width="100%",options=header,cols="1,3"] +|============================================================================== +include::generated/xlen_dependent_encoding_insns_table_body.adoc[] +|============================================================================== + +NOTE: <> and <> only exist in capability mode if legacy mode is _also_ present. A purecap core does not implement the mode bit in the capability. + +.Illegal instruction detect for CHERI instructions +[#cheri_illegals] +[width="100%",options=header,cols="2,2,2,2"] +|============================================================================== +include::generated/illegal_insns_table_body.adoc[] +|============================================================================== +