Introduce GCTYPE to obtain the capability type

While the base CHERI specification only has unsealed capabilities and
one type of sentry capability, other extensions (e.g. CherIoT) that
will build upon the base CHERI-RISC-V standard have additional types of
capabilities. Defining the specification in terms of object types
instead of just having unsealed and sentry is one important step towards
allowing CherIoT to be a RV32E extension on top of the base standard.

See https://lists.riscv.org/g/tech-tg-cheri/message/6

src/cap-description.adoc

@@ -258,25 +258,20 @@ references if that SDP bit is set because it "owns" that object.
 |==============================================================================
 
 [#section_cap_sealed]
-==== Sealed (S) Bit
+==== Capability Type (CT) 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. Please note that this bit indicates the result of
-two instructions in CHERI v9: CSEAL for sealed capabilities and
-CSEALENTRY for sealed entry capabilities.
+WARNING: *CHERI v9:* There is now a 1-bit otype (sentry or unsealed) and the old CHERI v9 otype no longer exists.
+The base CHERI-RISC-V standard does not have support for CHERI v9 CSEAL for sealed capabilities with object types and only has CSEALENTRY for sealed entry (sentry) capabilities.
 endif::[]
 
-This bit indicates that a capability is sealed if the bit is 1 or unsealed if it is 0.
+This bit indicates the type of the capability: it is a sealed capability if the bit is 1 or unsealed if it is 0.
 
-The sealing bit conflates two concepts in one bit: Sealing data capabilities and
-creating sealed entry capabilities as described below.
-
-Sealed capabilities cannot be dereferenced to access memory and are immutable
+Sealed capabilities (`CT ≠ 0` ) cannot be dereferenced to access memory and are immutable
 such that modifying any of its fields clears the tag of the output capability.
 
 NOTE: Sealed capabilities might be useful to software as tokens that can be passed
-around. The only way of removing the seal bit of a capability is by rebuilding
+around. The only way of clearing the type bit of a capability is by rebuilding
 it via a superset capability with <<CBLD>>. {cheri_base_ext_name} does not offer
 an unseal instruction.
 
@@ -566,7 +561,7 @@ expanded base is 0 and top is 2^MXLEN^.
 | SDP      | zeros | Grants no permissions
 | AP       | zeros | Grants no permissions
 | M        | zero  | No meaning since non-executable (MXLEN=64 only)
-| S        | zero  | Unsealed
+| CT       | zero  | Unsealed
 | EF       | zero  | Internal exponent format
 | L~8~     | zero  | Top address reconstruction bit (MXLEN=32 only)
 | T        | zeros | Top address bits
@@ -598,7 +593,7 @@ or 'root' capability.
                         | Grants all permissions
 | AP (MXLEN=64) | 0x1F (see xref:cap_perms_encoding64[xrefstyle=short])
                         | Grants all permissions
-| S             | zero  | Unsealed
+| CT            | zero  | Unsealed
 | EF            | zero  | Internal exponent format
 | L~8~          | zero  | Top address reconstruction bit (MXLEN=32 only)
 | T             | zeros | Top address bits

src/img/cap-encoding-xlen32.edn

@@ -11,7 +11,7 @@
 (draw-box "SDP"         {:span 2})
 (draw-box "AP, M"       {:span 5})
 (draw-box "Reserved"    {:span 4})
-(draw-box "S"           {:span 1})
+(draw-box "CT"          {:span 1})
 (draw-box "EF"          {:span 1})
 (draw-box "L8"          {:span 1})
 (draw-box "T[7:2]"      {:span 6})

src/img/cap-encoding-xlen64.edn

@@ -13,7 +13,7 @@
 (draw-box "M"           {:span 1})
 (draw-box "AP"          {:span 3})
 (draw-box "Reserved"    {:span 7})
-(draw-box "S"           {:span 1})
+(draw-box "CT"          {:span 1})
 (draw-box "EF"          {:span 1})
 (draw-box "T[11:3]"     {:span 4})
 (draw-box "TE"          {:span 2})

src/insns/gctype_32bit.adoc

@@ -0,0 +1,47 @@
+<<<
+
+[#GCTYPE,reftext="GCTYPE"]
+==== GCTYPE
+
+include::new_encoding_note.adoc[]
+
+ifdef::cheri_v9_annotations[]
+NOTE: *CHERI v9 Note:* this instruction was called CGETTYPE.
+endif::[]
+
+Synopsis::
+Capability get type
+
+Mnemonic::
+`gctype rd, cs1`
+
+Encoding::
+include::wavedrom/gctype.adoc[]
+
+Description::
+Decode the architectural capability type from `cs1` and write the result to `rd`.
+It is not required that the input capability `cs1`  has its tag set to 1.
+
+NOTE: While the architectural capability type maps directly to the value of the `CT` capability bit in {cheri_base_ext_name}, future extensions may define an alternate mapping.
+Therefore, software should always use <<GCTYPE>> to obtain the capability type rather than directly reading the high bits of the capability using <<GCHI>>.
+
+
+.Capability types in {cheri_base_ext_name}
+|===
+|Type |Hardware interpretation
+
+|0    | Unsealed capability
+|1    | <<#section_cap_sealed,Sentry capability>>
+|===
+
+Exceptions::
+include::require_cre.adoc[]
+
+Prerequisites::
+{cheri_base_ext_name}
+
+Operation::
++
+--
+TODO
+--

src/insns/sentry_32bit.adoc

@@ -19,9 +19,8 @@ Encoding::
 include::wavedrom/sentry.adoc[]
 
 Description::
-Capability `cd`  is written with the capability in `cs1`  with its seal bit set
-to 1. Attempting to seal an already sealed capability will lead to the tag of `cd`
-being set to 0.
+Capability `cd` is written with the capability in `cs1` with its type bit set to 1.
+Attempting to seal an already sealed capability will lead to the tag of `cd` being set to 0.
 
 Exceptions::
 include::require_cre.adoc[]

src/insns/wavedrom/gctype.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', 'GCTYPE=000'], type: 8},
+  {bits: 5,  name: 'cs1',     attr: ['5', 'src'], type: 4},
+  {bits: 5,  name: 'funct5',  attr: ['5', 'GCTYPE=00010'], type: 3},
+  {bits: 7,  name: 'funct7',  attr: ['7', 'GCTYPE=0001000'], type: 3},
+]}
+....

src/instructions.adoc

@@ -54,6 +54,8 @@ include::insns/gcbase_32bit.adoc[]
 
 include::insns/gclen_32bit.adoc[]
 
+include::insns/gctype_32bit.adoc[]
+
 include::insns/scbnds_32bit.adoc[]
 
 include::insns/scbndsr_32bit.adoc[]

src/riscv-integration.adoc

@@ -117,6 +117,7 @@ bounds. These instructions do not cause exceptions.
 tag is set and 0 otherwise
 * <<GCPERM>>: outputs the architectural (AP) and software-defined (SDP)
 permission fields of the input capability
+* <<GCTYPE>>: outputs the type (e.g. unsealed or sentry) of the input capability
 * <<GCBASE>>: outputs the expanded base address of the input capability
 * <<GCLEN>>: outputs the length of the input capability. Length is defined as
 `top - base`. The output is 2^MXLEN^-1 when the capability's length is