Add gentag exclusion-mask CSRs

src/mte_tag.adoc

@@ -102,15 +102,18 @@ Following are the instructions to place `pointer_tag` in the source register
 ==== Generate a tag - gentag rd
 
 If memory tagging is enabled in the current execution environment (see
-<<MEM_TAG_EN>>), hart clears `rd`, generates a `pointer_tag` value and places
+<<MEM_TAG_EN>>), hart clears `rd`, generates a `pointer_tag` value from the set
+of tag values permitted by the active tag generation exclusion mask, and places
 the result in `rd[XLEN:XLEN-pointer_tag_width+1]`.
 
 If memory tagging is disabled in the current execution environment (see
 <<MEM_TAG_EN>>), then `gentag` instruction falls back to zimop behavior and zeroes
 destination register.
 
-Even though entropy space is small, implementation must ensure that generated tag
-is pseudorandom and is uniformly distributed across all invocations of `gentag`.
+A tag value is permitted if the corresponding bit in the active tag generation
+exclusion mask is clear. Even though the entropy space is small, the
+implementation must ensure that the generated tag is pseudorandom and uniformly
+distributed over the permitted tag values across invocations of `gentag`.
 
 [wavedrom, ,svg]
 ....
@@ -499,6 +502,118 @@ If memory tagging is implemented, implementation must implement
 `__x__envcfg` CSR and read it back. If read back value is `0b11` then
 implementation supports both `pointer_tag` widths.
 
+==== Tag generation exclusion mask
+
+The active tag generation exclusion mask controls which `pointer_tag` values may
+be generated by `gentag`. The mask is 128 bits wide. Bit `i` corresponds to
+`pointer_tag` value `i`.
+
+If bit `i` of the active tag generation exclusion mask is set, `gentag` must not
+generate `pointer_tag` value `i`. If bit `i` is clear, `gentag` may generate
+`pointer_tag` value `i`.
+
+When `pointer_tag_width = 4`, only bits `[15:0]` of the mask are active. Bits
+`[127:16]` are ignored.
+
+When `pointer_tag_width = 7`, bits `[127:0]` of the mask are active.
+
+The tag generation exclusion mask affects only tag values generated by
+`gentag`. It does not affect `addtag`, `settag`, explicit tag checks, implicit
+tag checks, or tags constructed by other instruction sequences.
+
+For the purposes of syntactic dependencies in the memory model, `gentag` has the
+active tag generation exclusion mask CSRs as source operands and `rd` as its
+destination operand.
+
+The tag generation exclusion mask CSRs are WARL. A legal read-back value must
+leave at least one bit clear in bits `[15:0]`. The specific bit or bits left
+clear when legalizing an otherwise illegal write are implementation-defined.
+This constraint is independent of the currently active `pointer_tag_width` and
+is enforced when the exclusion mask CSRs are written; changing
+`pointer_tag_width` does not modify the exclusion mask CSRs. The reset value of
+the tag generation exclusion mask CSRs is zero.
+
+[NOTE]
+====
+Software can use this mask to prevent `gentag` from generating tag values with
+special software meaning, such as zero for untagged pointers or an all-ones
+`pointer_tag` value.
+
+Software that uses `addtag` to derive additional tags from a base tag generated
+by `gentag` is responsible for ensuring that the derived tags have the desired
+software properties. For example, if software wants to avoid a set of tag values
+`E` not only for the base tag but also for tags derived by increments `K`, it
+should exclude from `gentag` any base tag `b` for which
+`(b + k) mod (1 << pointer_tag_width)` is in `E` for any `k` in `K`.
+====
+
+.`gentag` exclusion mask source
+[width=100%]
+[%header, cols="^4,^12"]
+|===
+| Execution environment | Tag generation exclusion mask source
+
+| M
+| `mmtagexclude1:mmtagexclude0`
+
+| S/HS
+| `menvmtagexclude1:menvmtagexclude0`
+
+| U/HU
+| `senvmtagexclude1:senvmtagexclude0`
+
+| VS
+| `henvmtagexclude1:henvmtagexclude0`
+
+| VU
+| `senvmtagexclude1:senvmtagexclude0`
+|===
+
+==== Tag generation exclusion mask CSRs
+
+CSR addresses for these registers are to be allocated.
+
+The Zimt extension adds pairs of 64-bit CSRs to hold the 128-bit tag generation
+exclusion mask for each controlled execution environment listed below. The low
+CSR contains mask bits `[63:0]`. The high CSR contains mask bits `[127:64]`.
+
+When `pointer_tag_width = 7` is not supported by the implementation, bits
+`[127:16]` may be hardwired to zero.
+
+When `pointer_tag_width = 7` is supported by the implementation, bits `[127:0]`
+are writable subject to the WARL constraint above.
+
+Only the bits corresponding to the active `pointer_tag_width` affect `gentag`.
+When the active `pointer_tag_width = 4`, bits `[127:16]` are ignored by
+`gentag`, even if they are writable.
+
+.`gentag` exclusion mask CSRs
+[width=100%]
+[%header, cols="^4,^6,^6,^8"]
+|===
+| Controlled execution environment | Low CSR | High CSR | Active bits
+
+| M
+| `mmtagexclude0`
+| `mmtagexclude1`
+| `[15:0]` or `[127:0]`
+
+| S/HS
+| `menvmtagexclude0`
+| `menvmtagexclude1`
+| `[15:0]` or `[127:0]`
+
+| U/HU
+| `senvmtagexclude0`
+| `senvmtagexclude1`
+| `[15:0]` or `[127:0]`
+
+| VS
+| `henvmtagexclude0`
+| `henvmtagexclude1`
+| `[15:0]` or `[127:0]`
+|===
+
 ==== Machine Security Configuration Register(`mseccfg`)
 
 .Machine security configuration register(`mseccfg`)