Reorder capability chapter to show cap layout first (#23)

Show the encoding first, then describe the fields. This is what many
other specs also do. When reading the specification, it gives a better
overview what the rest of the chapter is about as one can picture
something.

Signed-off-by: Axel Heider <[email protected]>
Co-authored-by: Axel Heider <[email protected]>

src/cap-description.adoc

@@ -19,6 +19,34 @@ current draft and expected to be part of privileged architecture 1.13.
 MXLEN without including the tag bit. The value of CLEN is always calculated
 based on MXLEN regardless of the effective XLEN value.
 
+[#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.
+endif::[]
+
+The components of a capability, except the tag, are encoded as shown in
+xref:cap_encoding_xlen32[xrefstyle=short] for MXLEN=32 and
+xref:cap_encoding_xlen64[xrefstyle=short] for MXLEN=64. 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.
+
+.Capability encoding for MXLEN=32
+[#cap_encoding_xlen32]
+include::img/cap-encoding-xlen32.edn[]
+
+.Capability encoding for MXLEN=64
+[#cap_encoding_xlen64]
+include::img/cap-encoding-xlen64.edn[]
+
+Reserved bits are available for future extensions to {cheri_base_ext_name}.
+
+NOTE: Reserved bits must be 0 in valid capabilities.
+
 === Components of a Capability
 
 Capabilities contain the software accessible fields described in this section.
@@ -41,9 +69,23 @@ 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.
 
+==== Address
+
+The byte-address of a memory location is encoded as MXLEN integer value.
+
+.Address widths depending on MXLEN
+[#address_bit_width,options=header,align="center",width="55%"]
+|==============================================================================
+^| MXLEN   ^| Address width
+^| 32      ^| {cap_rv32_addr_width}
+^| 64      ^| {cap_rv64_addr_width}
+|==============================================================================
+
 [#section_cap_perms]
 ==== Architectural Permissions (AP)
 
+===== Description
+
 ifdef::cheri_v9_annotations[]
 WARNING: *CHERI v9 Note:* The permissions are encoded differently in this
 specification.
@@ -221,7 +263,9 @@ also seals the return address capability (if any) since it is the entry point
 to the caller function.
 
 [#section_cap_bounds]
-==== Bounds
+==== Bounds (EF, T, TE, B, BE)
+
+===== Concept
 
 ifdef::cheri_v9_annotations[]
 NOTE: *CHERI v9 Note:* The bounds mantissa width is different in MXLEN=32.
@@ -291,49 +335,8 @@ xref:exp_bit_width[xrefstyle=short].
 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
-
-MXLEN integer value that encodes the byte-address of a memory location.
-
-.Address widths depending on MXLEN
-[#address_bit_width,options=header,align="center",width="55%"]
-|==============================================================================
-^| MXLEN   ^| 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.
-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 MXLEN=32 and MXLEN=64
-respectively.
-
-.Capability encoding when MXLEN=32
-[#cap_encoding_xlen32]
-include::img/cap-encoding-xlen32.edn[]
-
-.Capability encoding when MXLEN=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.
+[#section_cap_bounds_decoding]
+===== Decoding
 
 The metadata is encoded in a compressed format cite:[woodruff2019cheri]. It
 uses a floating point representation to encode the bounds relative to the
@@ -468,6 +471,26 @@ if ( (E < (CAP_MAX_E - 1)) & (t[MXLEN: MXLEN - 1] - b[MXLEN - 1] > 1) )
 That is, invert the most significant bit of _t_ if the decoded length of the
 capability is larger than E.
 
+[#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.
+
 [#section_special_caps]
 === Special Capabilities
 
@@ -534,6 +557,8 @@ or 'root' capability.
 [#section_cap_representable_check, reftext="Representable Range"]
 === Representable Range Check
 
+==== Concept
+
 The new address, after updating the address of a capability, is within the
 _representable range_ if decompressing the capability's bounds with the
 original and new addresses yields the same base and top addresses.
@@ -585,23 +610,3 @@ xref:section_cap_encoding[xrefstyle=short].
 This gives useful guarantees, such that if an executed instruction is in
 <<pcc>> bounds, then it is also guaranteed that the next linear instruction
 is _representable_.
-
-[#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.