Merge pull request #22 from ved-rivos/arc_review

rename sqoscfg to srmcfg

qos_bandwidth.adoc

@@ -5,7 +5,7 @@ Controllers, such as memory controllers, that support bandwidth allocation and
 bandwidth usage monitoring provide a memory-mapped bandwidth-controller QoS
 register interface.
 
-.Bandwidth-controller QoS register layout
+.Bandwidth-controller QoS Register Layout (size and offset are in bytes)
 [width=100%]
 [%header, cols="^3,10,^3, 18, 5"]
 |===
@@ -38,12 +38,12 @@ handling a request with a non-zero `RCID` value before configuring the bandwidth
 controller with bandwidth allocation for that `RCID` is also `UNSPECIFIED`.
 
 [[BC_CAP]]
-=== Capabilities (`bc_capabilities`)
+=== Bandwidth-controller Capabilities
 
 The `bc_capabilities` register is a read-only register that holds the
 bandwidth-controller capabilities.
 
-.Capabilities register fields
+.Bandwidth-controller Capabilities Register
 [wavedrom, , ]
 ....
 {reg: [
@@ -57,6 +57,8 @@ bandwidth-controller capabilities.
 ], config:{lanes: 4, hspace:1024}}
 ....
 
+<<<
+
 The `VER` field holds the version of the specification implemented by the
 bandwidth controller. The low nibble is used to hold the minor version of the
 specification and the upper nibble is used to hold the major version of the
@@ -92,13 +94,13 @@ from 0 to 12. If `RPFX` is 0, `P` is set to 0, and the effective `MCID` is the
 same as the `MCID` in the request.
 
 [[BC_MCTL]]
-=== Bandwidth usage monitoring control (`bc_mon_ctl`)
+=== Bandwidth Usage Monitoring Control
 
 The `bc_mon_ctl` register is used to control monitoring of bandwidth usage by a
 `MCID`. When the controller does not support bandwidth usage monitoring, the
 `bc_mon_ctl` register is read-only zero.
 
-.Bandwidth usage monitoring control (`bc_mon_ctl`)
+.Bandwidth Usage Monitoring Control Register (`bc_mon_ctl`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -127,8 +129,10 @@ The `OP`, `AT`, `MCID`, and `EVT_ID` fields of the register are WARL fields.
 The `OP` field is used to instruct the controller to perform an operation
 listed in <<BC_MON_OP>>.
 
+<<<
+
 [[BC_MON_OP]]
-.Usage monitoring operations (`OP`)
+.Bandwidth Usage Monitoring Operations (`OP`)
 [width=100%]
 [%header, cols="16,^12,70"]
 |===
@@ -152,9 +156,9 @@ indicated by the `ATV` field. When `ATV` is 0, the counter counts requests with
 all access-types, and the `AT` value is ignored.
 
 [[BC_EVT_ID]]
-.Bandwidth monitoring event ID (`EVT_ID`)
+.Bandwidth Monitoring Event ID (`EVT_ID`)
 [width=100%]
-[%header, cols="15,^10,40"]
+[%header, cols="30,^10,40"]
 |===
 |Event ID      | Encoding ^| Description
 |`None`        | 0         | Counter does not count and retains its value.
@@ -197,7 +201,7 @@ the register. The `STATUS` field remains valid until a subsequent write to the
 `bc_mon_ctl` register.
 
 [[BC_MON_STS]]
-.`bc_mon_ctl.STATUS` field encodings
+.`bc_mon_ctl.STATUS` Field Encodings
 [width=100%]
 [%header, cols="12,70"]
 |===
@@ -219,14 +223,14 @@ operation, software must first verify that the `BUSY` bit is 0 before writing
 the `bc_mon_ctl` register.
 
 [[BC_MCTR]]
-=== Bandwidth monitoring counter value (`bc_mon_ctr_val`)
+=== Bandwidth Monitoring Counter Value
 
 The `bc_mon_ctr_val` is a read-only register that holds a snapshot of the
 counter selected by a `READ_COUNTER` operation. When the controller does not
 support bandwidth usage monitoring, the `bc_mon_ctr_val` register always reads
 as zero.
 
-.Bandwidth monitoring counter value (`bc_mon_ctr_val`)
+.Bandwidth Monitoring Counter Value Register (`bc_mon_ctr_val`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -254,7 +258,7 @@ determined by reading the byte count value at two instances of time `T1` and
 time `T2` is `B2`, then the bandwidth can be calculated as follows. The
 frequency of the time source is represented by latexmath:[T_{freq}].
 
-[latexmath#eq-2,reftext="equation ({counter:eqs})"]
+[latexmath#eq-3,reftext="equation ({counter:eqs})"]
 ++++
 \begin{equation}
 Bandwidth = T_{freq} \times \frac{ B2 - B1 }{T2 - T1}
@@ -276,14 +280,14 @@ operation.
 ====
 
 [[BC_ALLOC]]
-=== Bandwidth allocation control (`bc_alloc_ctl`)
+=== Bandwidth Allocation Control
 
 The `bc_alloc_ctl` register is used to control the allocation of bandwidth to an
 `RCID` per `AT`. If a controller does not support bandwidth allocation, then the
 register is read-only zero. If the controller does not support bandwidth
 allocation per access-type, then the `AT` field is read-only zero.
 
-.Bandwidth allocation control (`bc_alloc_ctl`)
+.Bandwidth Allocation Control Register (`bc_alloc_ctl`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -305,7 +309,7 @@ first program the `bc_bw_alloc` register with the operands for the operation
 before requesting the operation.
 
 [[BC_ALLOC_OP]]
-.Bandwidth allocation operations (`OP`)
+.Bandwidth Allocation Operations (`OP`)
 [width=100%]
 [%header, cols="16,^12,70"]
 |===
@@ -324,6 +328,8 @@ before requesting the operation.
 | --           | 24-31     | Designated for custom use.
 |===
 
+<<<
+
 A bandwidth allocation must be configured for each access-type supported by 
 the controller. When differentiated bandwidth allocation based on access-type
 is not required, one of the access-types may be designated to hold a default
@@ -345,7 +351,7 @@ the register. The `STATUS` field remains valid until a subsequent write to the
 
 
 [[BC_ALLOC_STS]]
-.`bc_alloc_ctl.STATUS` field encodings
+.`bc_alloc_ctl.STATUS` Field Encodings
 [width=100%]
 [%header, cols="12,70"]
 |===
@@ -361,7 +367,7 @@ the register. The `STATUS` field remains valid until a subsequent write to the
 |===
 
 [[BC_BMASK]]
-=== Bandwidth allocation configuration (`bc_bw_alloc`)
+=== Bandwidth Allocation Configuration
 
 The `bc_bw_alloc` is used to program reserved bandwidth blocks (`Rbwb`) for an
 `RCID` for requests of access-type `AT` using the `CONFIG_LIMIT` operation. If a
@@ -377,7 +383,7 @@ operation fails with `STATUS=5`. Additionally, the sum of `Rbwb` allocated
 across all `RCIDs` must not exceed `MRBWB`, or the `CONFIG_LIMIT` operation
 fails with `STATUS=5`.
 
-.Bandwidth allocation configuration (`bc_bw_alloc`)
+.Bandwidth Allocation Configuration Register (`bc_bw_alloc`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -424,7 +430,7 @@ permitted to use unused bandwidth is determined by dividing the `Mweight` of
 `RCID=x` by the sum of the `Mweight` of all other contending `RCIDs`. This
 ratio `P` is determined by <<eq-3>>.
 
-[latexmath#eq-3,reftext="equation ({counter:eqs})"]
+[latexmath#eq-4,reftext="equation ({counter:eqs})"]
 ++++
 \begin{equation}
 P = \frac{Mweight_{x}}{\sum_{r=1}^{r=n} Mweight_{r}}

qos_capacity.adoc

@@ -45,7 +45,7 @@ workloads.
 ====
 
 [[CC_REG]]
-.Capacity-controller QoS register layout
+.Capacity-controller QoS Register Layout (size and offset are in bytes)
 [width=100%]
 [%header, cols="^3,10,^4, 18, 5"]
 |===
@@ -63,8 +63,6 @@ workloads.
                                     count>>                     | Yes
 |===
 
-The size and offset in <<CC_REG>> are specified in bytes.
-
 The size of the `cc_block_mask` register is determined by the `NCBLKS` field
 of the `cc_capabilities` register but is always a multiple of 8 bytes. The
 formula for determination of `BMW` is defined in <<CC_BMASK>>. The offset `N` is
@@ -86,12 +84,12 @@ value before configuring the capacity controller with capacity allocation for
 that `RCID` is `UNSPECIFIED`.
 
 [[CC_CAP]]
-=== Capacity-controller capabilities (`cc_capabilities`)
+=== Capacity-controller Capabilities
 
 The `cc_capabilities` register is a read-only register that holds the
 capacity-controller capabilities.
 
-.Capacity-controller capabilities register fields
+.Capacity-controller Capabilities Register
 [wavedrom, , ]
 ....
 {reg: [
@@ -129,20 +127,22 @@ units_ that can be occupied by an `RCID` in _capacity blocks_ allocated to it.
 If `FRCID` is 1, the controller supports an operation to flush and deallocate
 the _capacity blocks_ occupied by an `RCID`.
 
+<<<
+
 If `RPFX` is 1, the controller uses `RCID` in the requests along with `P` least
 significant bits of the `MCID` carried in the request to compute an effective
 `MCID` (<<EMCID>>) to identify the monitoring counter. Legal values of `P` range
 from 0 to 12. If `RPFX` is 0, `P` is set to 0, and the effective `MCID` is the
 same as the `MCID` in the request.
 
 [[CC_MCTL]]
-=== Capacity usage monitoring control (`cc_mon_ctl`)
+=== Capacity Usage Monitoring Control
 
 The `cc_mon_ctl` register is used to control monitoring of capacity usage by a
 `MCID`. When the controller does not support capacity usage monitoring the
 `cc_mon_ctl` register is read-only zero.
 
-.Capacity usage monitoring control (`cc_mon_ctl`)
+.Capacity Usage Monitoring Control Register (`cc_mon_ctl`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -171,7 +171,7 @@ The `OP` field is used to instruct the controller to perform an operation listed
 in <<CC_MON_OP>>.
 
 [[CC_MON_OP]]
-.Capacity usage monitoring operations (`OP`)
+.Capacity Usage Monitoring Operations (`OP`)
 [width=100%]
 [%header, cols="16,^12,70"]
 |===
@@ -194,8 +194,10 @@ used to program the access-type to count, and its validity is indicated by the
 `ATV` field. When `ATV` is 0, the counter counts requests with all access-types,
 and the `AT` value is ignored.
 
+<<<
+
 [[CC_EVT_ID]]
-.Capacity usage monitoring event ID (`EVT_ID`)
+.Capacity Usage Monitoring Event ID (`EVT_ID`)
 [width=100%]
 [%header, cols="12,^12,70"]
 |===
@@ -232,7 +234,7 @@ the register. The `STATUS` field remains valid until a subsequent write to the
 `cc_mon_ctl` register.
 
 [[CC_MON_STS]]
-.`cc_mon_ctl.STATUS` field encodings
+.`cc_mon_ctl.STATUS` Field Encodings
 [width=100%]
 [%header, cols="12,70"]
 |===
@@ -254,14 +256,14 @@ operation, software must first verify that the `BUSY` bit is 0 before writing
 the `cc_mon_ctl` register.
 
 [[CC_MCTR]]
-=== Capacity usage monitoring counter value (`cc_mon_ctr_val`)
+=== Capacity Usage Monitoring Counter Value
 
 The `cc_mon_ctr_val` is a read-only register that holds a snapshot of the
 counter selected by the `READ_COUNTER` operation. When the controller does not
 support capacity usage monitoring, the `cc_mon_ctr_val` register always reads as
 zero.
 
-.Capacity usage monitoring counter value (`cc_mon_ctr_val`)
+.Capacity Usage Monitoring Counter Value Register (`cc_mon_ctr_val`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -287,11 +289,7 @@ capacity initially allocated by the previous workload. In such cases, the
 counter shall not decrement below zero and shall remain at zero. After a brief
 period of execution for the new workload post-counter reset, the counter value is
 expected to stabilize to reflect the capacity usage of this new workload.
-====
 
-[NOTE]
-[%unbreakable]
-====
 Some implementations may not store the `MCID` of the request that caused the
 capacity to be allocated with every unit of capacity in the controller to
 optimize on the storage overheads. Such controllers may in turn rely on
@@ -318,15 +316,15 @@ processes.
 ====
 
 [[CC_ALLOC]]
-=== Capacity allocation control (`cc_alloc_ctl`)
+=== Capacity Allocation Control
 
 The `cc_alloc_ctl` register is used to configure allocation of capacity to an
 `RCID` per access-type (`AT`). The `OP`, `RCID` and `AT` fields in this register
 are WARL. If a controller does not support capacity allocation then this
 register is read-only zero. If the controller does not support capacity
 allocation per access-type then the `AT` field is read-only zero.
 
-.Capacity allocation control (`cc_alloc_ctl`)
+.Capacity Allocation Control Register (`cc_alloc_ctl`)
 [wavedrom, , ]
 ....
 {reg: [
@@ -351,7 +349,7 @@ program the `cc_block_mask` and/or the `cc_cunits` register, followed by
 initiating the operation via the `cc_alloc_ctl` register.
 
 [[CC_ALLOC_OP]]
-.Capacity allocation operations (`OP`)
+.Capacity Allocation Operations (`OP`)
 [width=100%]
 [%header, cols="16,^12,70"]
 |===
@@ -383,6 +381,8 @@ initiating the operation via the `cc_alloc_ctl` register.
 | --           | 24-31     | Designated for custom use.
 |===
 
+<<<
+
 Capacity controllers enumerate the allocatable _capacity blocks_ in the `NCBLKS`
 field of the `cc_capabilities` register. The `cc_block_mask` register is
 programmed with a bit-mask where each bit represents a _capacity block_ for the
@@ -439,6 +439,8 @@ capacity blocks represent 100 units and `RCID=3` has a 30-unit limit while
 blocks, respectively.
 ====
 
+<<<
+
 The `FLUSH_RCID` operation may incur a long latency to complete. New requests to
 the controller by the `RCID` being flushed are allowed. Additionally, the
 controller is allowed to deallocate capacity that was allocated after the
@@ -473,7 +475,7 @@ to a write to the register. The `STATUS` field remains valid until a subsequent
 write to the `cc_alloc_ctl` register.
 
 [[CC_ALLOC_STS]]
-.`cc_alloc_ctl.STATUS` field encodings
+.`cc_alloc_ctl.STATUS` Field Encodings
 [width=100%]
 [%header, cols="12,70"]
 |===
@@ -495,7 +497,7 @@ perform the operation determined by the second write. To ensure proper operation
 software must verify that `BUSY` bit  is 0 before writing any of these registers.
 
 [[CC_BMASK]]
-=== Capacity block mask (`cc_block_mask`)
+=== Capacity Block Mask (`cc_block_mask`)
 
 The `cc_block_mask` is a WARL register. If the controller does not support
 capacity allocation, i.e., `NCBLKS` is 0, then this register is read-only 0.
@@ -506,7 +508,7 @@ always a multiple of 64 bits. The bitmap width in bits (`BMW`) is determined by
 the equation below. The division operation in this equation is an integer
 division.
 
-[latexmath#eq-1,reftext="equation ({counter:eqs})"]
+[latexmath#eq-2,reftext="equation ({counter:eqs})"]
 ++++
 \begin{equation}
 BMW = \lfloor{\frac{NCBLKS + 63}{64}}\rfloor \times 64
@@ -543,7 +545,7 @@ provides the `READ_LIMIT` operation which can be requested by writing to the
 `cc_block_mask` register holds the configured _capacity block_ allocation.
 
 [[CC_CUNITS]]
-=== Capacity units (`cc_cunits`)
+=== Capacity Units
 
 The `cc_cunits` register is a read-write WARL register. If the controller does
 not support capacity allocation (i.e., `NCBLKS` is set to 0), this register
@@ -555,6 +557,8 @@ may be occupied in the allocated _capacity blocks_ (i.e.,
 cases the controller will allow utilization of all available _capacity units_ by
 an `RCID` within the _capacity blocks_ allocated to it.
 
+<<<
+
 If the controller supports configuring limits on _capacity units_ that may be
 occupied in the allocated _capacity blocks_ (i.e., `cc_capabilities.CUNITS=1`)
 then this register sets an upper limit on the number of _capacity units_ that

qos_hw_guidelines.adoc

@@ -30,7 +30,7 @@ support when requests are processed by multiple controllers, such as caches,
 fabrics, and memory controllers.
 ====
 
-=== Sizing monitoring counters
+=== Sizing Monitoring Counters
 
 Typically software samples the monitoring counters periodically to monitor
 capacity and bandwidth usage. The width of the monitoring counters is