diff --git a/arch/csr/Ssqosid/srmcfg.yaml b/arch/csr/Ssqosid/srmcfg.yaml new file mode 100644 index 000000000..74c86e85a --- /dev/null +++ b/arch/csr/Ssqosid/srmcfg.yaml @@ -0,0 +1,152 @@ +# yaml-language-server: $schema=../../../schemas/csr_schema.json +$schema: csr_schema.json# +kind: csr +name: srmcfg +long_name: Supervisor Resource Management Configuration +address: 0x181 +priv_mode: S +length: SXLEN +definedBy: Ssqosid +description: + - id: csr-srmcfg-purpose + normative: true + text: | + The `srmcfg` register is used to configure a Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). + Both `RCID` and `MCID` are WARL fields. + + - id: csr-`srmcfg`-field-usage + normative: true + text: | + The `RCID` and `MCID` accompany each request made by the hart to shared resource controllers. + The `RCID` is used to determine the resource allocations (e.g., cache occupancy limits, memory bandwidth limits, etc.) to enforce. + The `MCID` is used to identify a counter to monitor resource usage. + + - id: csr-srmcfg-default-scope + normative: true + text: | + The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege modes of software execution on that hart by default, + but this behavior may be overridden by future extensions. + + - id: csr-srmcfg-smstateen-interaction + normative: true + text: | + If extension `Smstateen` is implemented together with `Ssqosid`, then `Ssqosid` also requires the `SRMCFG` bit in `mstateen0` to be implemented. + If `mstateen0.SRMCFG` is `0`, attempts to access `srmcfg` in privilege modes less privileged than M-mode raise an illegal-instruction exception. + + - id: csr-srmcfg-vsmode-exception + normative: true + text: | + If `mstateen0.SRMCFG` is `1` or if extension `Smstateen` is not implemented, attempts to access `srmcfg` when `V=1` raise a virtual-instruction exception. + + - id: csr-srmcfg-rcid-reset + normative: false + text: | + A reset value of `0` is suggested for the `RCID` field, matching resource controllers' default behavior of associating all capacity with `RCID=0`. + + - id: csr-srmcfg-mcid-reset + normative: false + text: | + The `MCID` reset value does not affect functionality and may be implementation-defined. + + - id: csr-srmcfg-id-bit-allocation + normative: false + text: | + Typically, fewer bits are allocated for `RCID` (e.g., to support tens of `RCID`s) than for `MCID` (e.g., to support hundreds of `MCID`s). + + - id: csr-srmcfg-rcid-grouping + normative: false + text: | + A common `RCID` is usually used to group apps or VMs, pooling resource allocations to meet collective SLAs. + + - id: csr-srmcfg-mcid-granularity + normative: false + text: | + If an SLA breach occurs, unique `MCID`s enable granular monitoring, aiding decisions on resource adjustment, + associating a different `RCID` with a subset of members, or migrating members to other machines. + The larger pool of `MCID`s speeds up this analysis. + + - id: csr-srmcfg-privilege-behavior + normative: false + text: | + The `RCID` and `MCID` in `srmcfg` apply across all privilege levels on the hart. + Typically, higher-privilege modes don't modify `srmcfg`, as they often serve lower-privileged tasks. + If differentiation is needed, higher privilege code can update `srmcfg` and restore it before returning to a lower privilege level. + + - id: csr-srmcfg-vm-virtualization + normative: false + text: | + In VM environments, hypervisors usually manage resource allocations, keeping the Guest OS out of QoS flows. + If needed, the hypervisor can virtualize the `srmcfg` CSR for a VM using the virtual-instruction exceptions triggered upon Guest access. + + - id: csr-srmcfg-vs-mode-future + normative: false + text: | + If the direct selection of `RCID` and `MCID` by the VM becomes common and emulation overhead is an issue, + future extensions may allow VS-mode to use a selector for a hypervisor-configured set of CSRs holding `RCID` and `MCID` values designated for that Guest OS use. + + - id: csr-srmcfg-context-switch + normative: false + text: | + During context switches, the supervisor may choose to execute with the `srmcfg` of the outgoing context to attribute the execution to it. + Prior to restoring the new context, it switches to the new VM’s `srmcfg`. + The supervisor can also use a separate configuration for execution not to be attributed to either context. +fields: + RCID: + location: 11-0 + type: RW + long_name: Resource Control ID + description: | + The `RCID` is used to determine the resource allocations (e.g., cache occupancy limits, + memory bandwidth limits, etc.) to enforce. + reset_value: UNDEFINED_LEGAL + sw_write(csr_value): | + if (implemented?(ExtensionName::Smstateen)) { + if (mode() < PrivilegeMode::M && CSR[mstateen0].SRMCFG == 0) { + raise(ExceptionCode::IllegalInstruction, mode(), $encoding); + } + if (virtual_mode?() && CSR[mstateen0].SRMCFG == 1) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } else { + if (virtual_mode?()) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } + return csr_value.RCID & ((1 `<< RCID_WIDTH) - 1); + + MCID: + location: 27-16 + type: RW + long_name: Monitoring Counter ID + description: | + The `MCID` is used to identify a counter to monitor resource usage. + reset_value: UNDEFINED_LEGAL + sw_write(csr_value): | + if (implemented?(ExtensionName::Smstateen)) { + if (mode() < PrivilegeMode::M && CSR[mstateen0].SRMCFG == 0) { + raise(ExceptionCode::IllegalInstruction, mode(), $encoding); + } + if (virtual_mode?() && CSR[mstateen0].SRMCFG == 1) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } else { + if (virtual_mode?()) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } + return csr_value.MCID & ((1 `<< MCID_WIDTH) - 1); + +sw_read(): | + if (implemented?(ExtensionName::Smstateen)) { + if (mode() < PrivilegeMode::M && CSR[mstateen0].SRMCFG == 0) { + raise(ExceptionCode::IllegalInstruction, mode(), $encoding); + } + if (virtual_mode?() && CSR[mstateen0].SRMCFG == 1) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } else { + if (virtual_mode?()) { + raise(ExceptionCode::VirtualInstruction, mode(), $encoding); + } + } + return $bits(CSR[mstateen0]); diff --git a/arch/csr/mstateen0.yaml b/arch/csr/mstateen0.yaml index 314f9ace2..309884256 100644 --- a/arch/csr/mstateen0.yaml +++ b/arch/csr/mstateen0.yaml @@ -129,7 +129,7 @@ fields: SRMCFG: long_name: srmcfg access control location: 55 - #definedBy: Ssqosid + definedBy: Ssqosid description: | The SRMCFG bit in `mstateen0` controls access to the `srmcfg`` CSR introduced by the Ssqosid Chapter 18 extension. diff --git a/arch/csr/mstateen0h.yaml b/arch/csr/mstateen0h.yaml index 036910f19..39fdfa80f 100644 --- a/arch/csr/mstateen0h.yaml +++ b/arch/csr/mstateen0h.yaml @@ -111,7 +111,7 @@ fields: SRMCFG: long_name: srmcfg access control location: 23 - #definedBy: Ssqosid + definedBy: Ssqosid alias: mstateen0.SRMCFG sw_write(csr_value): | CSR[mstateen0].SRMCFG = csr_value.SRMCFG; diff --git a/arch/ext/Ssqosid.yaml b/arch/ext/Ssqosid.yaml new file mode 100644 index 000000000..49225dffb --- /dev/null +++ b/arch/ext/Ssqosid.yaml @@ -0,0 +1,55 @@ +# yaml-language-server: $schema=../../schemas/ext_schema.json + +$schema: "ext_schema.json#" +kind: extension +name: Ssqosid +type: privileged +long_name: Quality-of-Service Identifiers +description: | + Quality of Service (QoS) is defined as the minimal end-to-end performance guaranteed in advance by a service level agreement (SLA) to a workload. + Performance metrics might include measures such as instructions per cycle (IPC), latency of service, etc. + + When multiple workloads execute concurrently on modern processors—equipped with large core counts, multiple cache hierarchies, and multiple memory + controllers—the performance of any given workload becomes less deterministic, or even non-deterministic, due to shared resource contention. + + To manage performance variability, system software needs resource allocation and monitoring capabilities. + These capabilities allow for the reservation of resources like cache and bandwidth, thus meeting individual performance targets while minimizing interference. + For resource management, hardware should provide monitoring features that allow system software to profile workload resource consumption and allocate resources accordingly. + + To facilitate this, the QoS Identifiers extension (Ssqosid) introduces the srmcfg register, + which configures a hart with two identifiers: a Resource Control ID (RCID) and a Monitoring Counter ID (MCID). + These identifiers accompany each request issued by the hart to shared resource controllers. + + Additional metadata, like the nature of the memory access and the ID of the originating supervisor domain, + can accompany RCID and MCID. Resource controllers may use this metadata for differentiated service such as a different capacity allocation for code storage vs. data storage. + Resource controllers can use this data for security policies such as not exposing statistics of one security domain to another. + + These identifiers are crucial for the RISC-V Capacity and Bandwidth Controller QoS Register Interface (CBQRI) specification, + which provides methods for setting resource usage limits and monitoring resource consumption. + The RCID controls resource allocations, while the MCID is used for tracking resource usage. + +params: + RCID_WIDTH: + description: | + Number of bits used for the Resource Control ID field (RCID). + Default is 12. + schema: + type: integer + minimum: 1 + maximum: 12 + + MCID_WIDTH: + description: | + Number of bits used for the Monitoring Counter ID field (MCID). + Default is 12. + schema: + type: integer + minimum: 1 + maximum: 12 + +versions: + - version: "1.0.0" + state: ratified + ratification_date: "2024-06" + url: "https://github.com/riscv/riscv-isa-manual/releases/tag/riscv-isa-release-5308687-2025-04-22" + requires: { name: S, version: ~> 1.13 }