move RV32 formats and extensions out of v1 ratification (#983)

This PR cleanly separates out content to be ratified now, from content
to be ratified later.
The different chapters are all in one of four categories:

1. Ready for freeze: put forwards for ratification _now_ (this is the
default)
2. Ready for freeze: will be put forwards for ratification _next_
3. Stable: Still need more review, prototyping or modelling work
4. Experimental: More thought or research required

riscv-privileged.pdf, riscv-unprivileged.pdf and riscv-cheri.pdf all
only contain extensions which we are putting forwards for ratification
in the first package.

riscv-cheri-full.pdf contains all extensions, including those which are
ready for freeze but being put forwards in future ratification packages,
which includes the RV32 formats.

---------

Co-authored-by: Alex Richardson <alexrichardson@google.com>

Author: tariqkurd-repo

Makefile

@@ -237,4 +237,5 @@ docker-pull-latest:
 clean:
 	@echo "Cleaning up generated files..."
 	rm -rf $(BUILD_DIR)
+	rm -rf $(CHERI_GEN_DIR)
 	@echo "Cleanup completed."

src/c-st-ext.adoc

@@ -298,7 +298,7 @@ always refers to the YLEN-bit capability version of the register.
 
 ==== Stack-Pointer-Based Loads and Stores
 
-include::images/wavedrom/c-sp-load-store.edn[]
+include::images/wavedrom/c-sp-load-store.adoc[]
 [[c-sp-load-store]]
 //.Stack-Pointer-Based Loads and Stores--these instructions use the CI format.
 
@@ -331,11 +331,14 @@ expands to `fld rd, offset(x2)`.
 <<C_LOAD_CAP_SP>> is an {cheri_base_ext_name}-only instruction that loads a
 capability from memory into capability
 register _{cd}_. It computes its effective address by adding the
-_zero_-extended offset, scaled by 8 (for {cheri_base32_ext_name}),
-or 16 (for {cheri_base64_ext_name}) to the capability stack pointer, `{creg}2`. It
-expands to `{load_cap_name_lc} {creg_ref}d, offset({creg}2)`.
-
-include::images/wavedrom/c-sp-load-store-css.edn[]
+_zero_-extended offset, scaled by
+ifndef::cheri_ratification_v1_only[]
+8 (for {cheri_base32_ext_name}), or
+endif::[]
+16 (for {cheri_base64_ext_name}) to the capability stack pointer, `{creg}2`. It
+expands to `{load_cap_name_lc} {creg}d, offset({creg}2)`.
+
+include::images/wavedrom/c-sp-load-store-css.adoc[]
 [[c-sp-load-store-css]]
 //.Stack-Pointer-Based Loads and Stores--these instructions use the CSS format.
 
@@ -365,8 +368,11 @@ expands to `fsd rs2, offset(x2)`.
 <<C_STORE_CAP_SP>> is an {cheri_base_ext_name}-only instruction that stores a
 capability in capability register _{cs2}_
 to memory. It computes an effective address by adding the
-_zero_-extended offset, scaled by 8 (for {cheri_base32_ext_name}),
-or 16 (for {cheri_base64_ext_name}), to the stack pointer, `{creg}2`. It
+_zero_-extended offset, scaled by
+ifndef::cheri_ratification_v1_only[]
+8 (for {cheri_base32_ext_name}), or
+endif::[]
+16 (for {cheri_base64_ext_name}), to the stack pointer, `{creg}2`. It
 expands to `{store_cap_name_lc} {cs2}, offset({creg}2)`.
 
 [NOTE]
@@ -413,7 +419,7 @@ attain the greatest code size reduction.
 ==== Register-Based Loads and Stores
 
 [[reg-based-ldnstr]]
-include::images/wavedrom/reg-based-ldnstr.edn[]
+include::images/wavedrom/reg-based-ldnstr.adoc[]
 //.Compressed, register-based load and stores--these instructions use the CL format.
 (((compressed, register-based load and store)))
 These instructions use the CL format.
@@ -446,13 +452,16 @@ _zero_-extended offset, scaled by 8, to the base address in register
 <<C_LOAD_CAP>> is an {cheri_base_ext_name} only instruction that loads a
 capability from memory into register `_{cd}′_`
 It computes an effective address by adding the
-_zero_-extended offset, scaled by 8 ({cheri_base32_ext_name})
-or 16 ({cheri_base64_ext_name}),
+_zero_-extended offset, scaled by
+ifndef::cheri_ratification_v1_only[]
+8 ({cheri_base32_ext_name}) or
+endif::[]
+16 ({cheri_base64_ext_name}),
 to the base address in register `_{cs1}′_`. It expands to
 `{c_load_cap_name_lc} {cd}′, offset({cs1}′)`.
 
 [[c-cs-format-ls]]
-include::images/wavedrom/c-cs-format-ls.edn[]
+include::images/wavedrom/c-cs-format-ls.adoc[]
 //.Compressed, CS format load and store--these instructions use the CS format.
 (((compressed, cs-format load and store)))
 
@@ -486,20 +495,27 @@ register `_rs1′_`. It expands to
 <<C_STORE_CAP>> is an {cheri_base_ext_name} only instruction that stores a
 capability in register `_{cs2}′_` to memory.
 It computes an effective address by adding the
-_zero_-extended offset, scaled by 8 ({cheri_base32_ext_name})
-or 16 ({cheri_base64_ext_name}),
+_zero_-extended offset, scaled by
+ifndef::cheri_ratification_v1_only[]
+8 ({cheri_base32_ext_name}) or
+endif::[]
+16 ({cheri_base64_ext_name}),
 to the base address in register `_{cs1}′_`. It expands to
 `{c_store_cap_name_lc} {cs2}′, offset({cs1}′)`
 
 ==== Compressed Load and Store summary
 
+ifndef::cheri_ratification_v1_only[]
+
 <<insn_remapping_16bit_rv32_a>> and <<insn_remapping_16bit_rv32_b>> summarize
 load/store encoding mappings for RV32 architectures.
 
 ==== RV32I / {cheri_base32_ext_name}
 
 include::cheri/rv32c_mapping_table.adoc[]
 
+endif::[]
+
 <<<
 ==== RV64I / {cheri_base64_ext_name}
 

src/cheri/app-cheri-instructions.adoc

@@ -3,11 +3,11 @@
 
 include::cheri_isa_tables.adoc[]
 
-ifdef::cheri_standalone_spec[]
+ifndef::cheri_ratification_v1_only[]
 
 === "Zcmp", "Zcmt" ({cheri_base_ext_name})
 
-IMPORTANT: {not_v1_ratification_package}
+IMPORTANT: {not_v1_ratification_package_stable}
 
 [#ZCMP_CHERI,reftext="Zcmp ({cheri_base32_ext_name})"]
 === "Zcmp" Standard Extension For Code-Size Reduction
@@ -104,11 +104,9 @@ Some instructions have been added as shown in <<ISA_added_095>>.
 [#ISA_added_095]
 [width="100%",options=header,cols="2,2,2",]
 |==============================================================================
-include::generated/new_instructions_table_body.adoc[]
+include::{generated_dir}/new_instructions_table_body.adoc[]
 |==============================================================================
 
-WARNING: {YSEAL} and {YUNSEAL} are not included in the v1.0 ratification package.
-
 [NOTE]
 ====
 
@@ -125,7 +123,7 @@ WARNING: {YSEAL} and {YUNSEAL} are not included in the v1.0 ratification package
 [NOTE]
 ====
 
-The following changes are for forwards compatibility with {cheriot_unpriv_ext_name}:
+The following changes are for forwards compatibility with CHERIoT:
 
 . Capability encodings and extensions are now the naming authorities for capability types (only 0/unsealed exists in the base architecture).
 . Capability encoding formats are now in separate base parameterizations.

src/cheri/attributes.adoc

@@ -1,12 +1,10 @@
 // Sail source code
 :sail-doc: src/cheri/generated/riscv_RV64.json
+:generated_dir: generated
 
-ifndef::cheri_standalone_spec[]
-:cheri_ratification_v1_only: 1
-endif::[]
-
-:not_v1_ratification_package: pass:quotes[#This chapter is not part of the v1.0 ratification package.#]
-
+:not_v1_ratification_package_freeze:       pass:quotes[#This chapter is not part of the v1.0 ratification package and is ready to freeze.#]
+:not_v1_ratification_package_stable:       pass:quotes[#This chapter is not part of the v1.0 ratification package and is stable.#]
+:not_v1_ratification_package_experimental: pass:quotes[#This chapter is not part of the v1.0 ratification package and is experimental.#]
 
 ///////////////////////////////////////////////////////////////////////////////
 // Top-level CHERI definitions

src/cheri/cheri-pte-ext.adoc

@@ -1,3 +1,4 @@
+
 [#section_cheri_priv_crg_ext]
 == "{cheri_priv_crg_ext}" Extension, Version 1.0 for {cheri_base64_ext_name}
 

src/cheri/cheri_csr_tables.adoc

@@ -3,7 +3,7 @@
 
 #this section includes debug CSRs#
 
-ifdef::cheri_ratification_v1_only[]
+ifndef::cheri_ratification_v1_only[]
 
 ifndef::cheri_standalone_spec[]
 
@@ -29,14 +29,14 @@ endif::[]
 [#aliased_CSRs]
 [width="100%",options=header,cols="1,1"]
 |==============================================================================
-include::generated/csr_aliases_table_body.adoc[]
+include::{generated_dir}/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[]
+include::{generated_dir}/csr_alias_action_table_body.adoc[]
 |==============================================================================
 
 ^*^ The vector range check is to ensure that vectored entry to the handler is within bounds of the capability written to `__x__tvec`.
@@ -53,7 +53,7 @@ is only possible when {cheri_default_ext_name} is implemented.
 [#new_cap_CSR_writing]
 [width="100%",options=header,cols="1,2,2"]
 |==============================================================================
-include::generated/new_csr_write_action_table_body.adoc[]
+include::{generated_dir}/new_csr_write_action_table_body.adoc[]
 |==============================================================================
 
 XLEN bits of YLEN-wide CSRs added in {cheri_default_ext_name} are
@@ -69,7 +69,7 @@ NOTE: Implementations which allow misa.C to be writable need to legalize `__x__e
 [#CSR_exevectors]
 [width="100%",options=header,cols="1,1,1,1"]
 |==============================================================================
-include::generated/csr_exevectors_table_body.adoc[]
+include::{generated_dir}/csr_exevectors_table_body.adoc[]
 |==============================================================================
 
 Some CSRs store code pointers or data pointers as shown in xref:CSR_exevectors[xrefstyle=short].
@@ -85,7 +85,7 @@ The tables below show all YLEN-wide CSRs.
 [#all_capability_CSRs]
 [width="100%",options=header,cols="2,1,1,2,2,4"]
 |==============================================================================
-include::generated/csr_permission_table_body.adoc[]
+include::{generated_dir}/csr_permission_table_body.adoc[]
 |==============================================================================
 
 Where reset values are specified in <<all_capability_CSRs>>, they are typically a maximum possible value.
@@ -94,25 +94,29 @@ For example, a <<root-rx-cap>> as specified for <<mtvec_y>> is the maximum, the
 {cheri_priv_m_ext} and {cheri_priv_s_ext} extend the CSRs listed in
 xref:dcsrnames-renamed[xrefstyle=short],
 xref:mcsrnames-renamed[xrefstyle=short],
-xref:scsrnames-renamed[xrefstyle=short],
-xref:vscsrnames-renamed[xrefstyle=short] and
-xref:ucsrnames-renamed[xrefstyle=short] from the base RISC-V ISA and its
-extensions.
+xref:scsrnames-renamed[xrefstyle=short]
+ifdef::cheri_ratification_v1_only[]
+, and xref:vscsrnames-renamed[xrefstyle=short]
+endif::[]
+ifndef::cheri_ratification_v1_only[]
+, xref:vscsrnames-renamed[xrefstyle=short] and xref:ucsrnames-renamed[xrefstyle=short]
+endif::[]
+from the base RISC-V ISA and its extensions.
 
 NOTE: If {cheri_default_ext_name} is supported then the <<cheri_execution_mode>> determines whether YLEN or XLEN bits are returned (see <<CSRRW_CHERI>>).
 
 [[dcsrnames-renamed]]
 .Extended debug-mode CSRs in {cheri_base_ext_name}
 [%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"]
 |===
-include::generated/csr_renamed_purecap_mode_d_table_body.adoc[]
+include::{generated_dir}/csr_renamed_purecap_mode_d_table_body.adoc[]
 |===
 
 [[mcsrnames-renamed]]
 .Extended machine-mode CSRs in {cheri_base_ext_name}
 [%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"]
 |===
-include::generated/csr_renamed_purecap_mode_m_table_body.adoc[]
+include::{generated_dir}/csr_renamed_purecap_mode_m_table_body.adoc[]
 |===
 
 [NOTE]
@@ -128,22 +132,25 @@ from which it can derive a capability to the address in this register.
 .Extended supervisor-mode CSRs in {cheri_base_ext_name}
 [%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"]
 |===
-include::generated/csr_renamed_purecap_mode_s_table_body.adoc[]
+include::{generated_dir}/csr_renamed_purecap_mode_s_table_body.adoc[]
 |===
 
 [[vscsrnames-renamed]]
 .Extended virtual supervisor-mode CSRs in {cheri_base_ext_name}
 [%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"]
 |===
-include::generated/csr_renamed_purecap_mode_vs_table_body.adoc[]
+include::{generated_dir}/csr_renamed_purecap_mode_vs_table_body.adoc[]
 |===
 
+// NOTE: This table only includes jvt_y
+ifndef::cheri_ratification_v1_only[]
 [[ucsrnames-renamed]]
 .Extended user-mode CSRs in {cheri_base_ext_name}
 [%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"]
 |===
-include::generated/csr_renamed_purecap_mode_u_table_body.adoc[]
+include::{generated_dir}/csr_renamed_purecap_mode_u_table_body.adoc[]
 |===
+endif::[]
 
 ifndef::cheri_standalone_spec[]