[Code First]: RAS2 PATROL_SCRUB Parameter Block Changes

[kvanshidhar]

Code First Item Overview

Title: RAS2 PATROL_SCRUB Parameter Block Changes

Status: Submitted to industry standard forum

Document: ACPI Specification Version 6.6

License

SPDX-License-Identifier: CC-BY-4.0

Submitter: TianoCore Community

• Vanshidhar Konda, Ampere Computing
• Daniel Ferguson, Ampere Computing

Summary of the change

This ECR:

• Updates the RAS2 Platform Communication Space to version 1.0 breaks backwards compatibility of the PATROL_SCRUB parameter block
• Deprecates the RAS2 Set Capabilities Status with the note that the field is used to return status of PATROL_SCRUB capability in prior versions
• Update PATROL_SCRUB parameter block version to 1.0 to sync with the change to RAS2 Platform Communication Space
• Add STATUS field to the PATROL_SCRUB parameter block
• Change description of fields in PATROL_SCRUB parameter block to refer to on-demand scrub vs patrol scrub explicitly
• Allow the usage of the Requested Address Range field to control the execution of STOP_PATROL_SCRUB command
• Add Extended Data Region Offset in PATROL_SCRUB parameter block to note where the Extended Data Region is present instead of relying on Length field of the data to determine size of region

Benefits of the change

There is a conflict in the definition of RAS2 Patrol Scrub Parameter Block in the changes between Mantis Issue #2344 and Mantis Issue #2482. #2344 was merged into ACPI 6.6 specification but #2482 did not account for these changes in definition of the PATROL_SCRUB parameter block. ACPI 6.6 has “Extended Scrub Parameters” field at offset 52 where #2482 put “Status” field at the same offset. This ECR resolves the conflict. This ECR will also replace the changes in #2482.

The PATROL_SCRUB parameter block in ACPI 6.6 specification is a variable sized structure with N number of scrub rate descriptors. The value of N is calculated by using the “Length” field of the parameter block. This prevents extending the structure with new fields at a later point of time. By adding a field that captures the value of N, we can allow the structure to be extended later without breaking backwards compatibility.

This ECR also makes some changes to the language where “patrol” scrub is used to refer to on-demand scrub configuration and information. This improves clarity where the capability is being used control the on-demand scrub operation requested by OSPM vs a background patrol scrub.

Impact of the change

Firmware can use the updated PATROL_SCRUB parameter block to provide relevant information. OSPM should be updated to handle the different versions of the RAS2 and PATROL_SCRUB Parameter Block.

Detailed description of the change [normative updates]

5.2.21.1.3 RAS2 Platform Communication Channel

The RAS2 platform communication channel format is defined below (Table 5.95).

Table 5.95: RAS2 Platform Communication Channel Shared Memory Region

Field	Byte Length	Byte Offset	Documentation
Signature	4	0	The PCC signature. The signature of a subspace is computed by a bitwise-or of the value 0x50434300 with the subspace ID. For example, subspace 3 has the signature 0x50434303.
Command	2	4	PCC command field; see PCC Command Codes used by RAS2. See Table 5.94 and Section 14.
Status	2	6	PCC status field. See Section 14.
Communication Space
Version	2	8	Byte 0 - Minor Version Byte 1 - Major Version For this revision, this field must be set to 0x0100.
RAS Features	16	10	Bitmap describing the platform RAS features as shown in Table 5.96. The definition of the bits is system component specific. For example, Table 5.98 shows the bitmap definitions for Memory RAS features. The Platform populates this field to indicate which RAS features for the given feature type are supported for this system component instance. The OSPM uses this field for RAS feature discovery.
Set RAS Capabilities	16	26	Bit Map of the RAS features for which the OSPM is invoking the command. The Bit Map is described in Section 5.2.21.1.4. OSPM sets the bit corresponding to a RAS capability to invoke a command on that capability. The bitmap implementation allows OSPM to invoke a command on each RAS feature supported by the platform at the same time.
Number of RAS2 Parameter Blocks	2	42	The Number of parameter blocks will depend on how many RAS Capabilities the Platform Supports. Typically, there will be one Parameter Block per RAS Feature, using which that feature can be managed by OSPM.
Set RAS Capabilities Status (DEPRECATED)	4	44	Must be Zero. Prior to version 0x0100 this field would return the status of the PATROL_SCRUB capability. This status is now reflected in the STATUS field of the PATROL_SCRUB Parameter Block. Status: 0000b = Success 0001b = Not Valid 0010b = Not Supported 0011b = Busy 0100b = Failed 0101b = Aborted 0110b = Invalid Data
Parameter Blocks	Varies (N bytes)	48	Start of the parameter blocks, the structure of which is shown in the Parameter Block Structure for PATROL_SCRUB. These parameter blocks are used as communication mailbox between the OSPM and the platform, and there is 1 parameter block for each RAS feature. NOTE: There can be only one parameter block per type.

5.2.21.2.1. Hardware-based Memory Scrubbing

Table 5.99 Parameter Block Structure for PATROL_SCRUB

Field	Byte Length	Byte Offset	Documentation
Type	2	0	0x0000 – Hardware-based memory scrub RAS feature.
Length	2	4	Byte 0 - Minor Version Byte 1 - Major Version For this revision, this field must be set to 0x0100.
Scrub Command (INPUT)	2	6	0x01 - GET_PATROL_PARAMETERS 0x02 - START_PATROL_SCRUBBER 0x03 - STOP_PATROL_SCRUBBER
Requested Address Range (INPUT)	16	8	OSPM specifies the BASE (Bytes 7-0) and SIZE (Bytes 15-8) of the address range to be patrol scrubbed. If OSPM requests default scrubbing through Bit 0 of the Configure Scrub Parameters field, then this field must be ignored by the platform. OSPM sets this parameter for the following commands: GET_PATROL_PARAMETERS, START_PATROL_SCRUBBER.
Actual Address Range (OUTPUT)	16	24	The platform returns this value in response to GET_PATROL_PARAMETERS. The platform calculates the nearest scrub boundary address from where it can start. This range should be a superset of the Requested Address Range. This field must be ignored by the OSPM if it is being returned in response to a request to enable default scrubbing through Bit 0 of the Configure Scrub Parameters field. BASE (Bytes 7-0) and SIZE (Bytes 15-8) of the address.
Flags (OUTPUT)	4	40	The platform returns this value in response to GET_PATROL_PARAMETERS: Bit [0]: Will be set if an on-demand memory scrubber is already running for address range specified in “Actual Address Range”. Bits [31:1]: Reserved, must be zero.
Scrub Parameters (OUTPUT)	4	44	The platform returns this value in response to GET_PATROL_PARAMETERS: If additional information in the Extended Data region is not present, the scrub rates returned by the platform in this field must be treated as integer values in the range {Minimum, Maximum}, where: Rate N < Rate N+1 and where each value in this range is an abstract value that represents a certain supported scrub rate. OSPM can select a rate from this abstract range based on a heuristics-based assessment of parameters such as power, bandwidth and error rates. For example, if the error rate is high, the OS can choose a higher (more aggressive) scrub rate, and vice versa. The physical scrub rates are not relevant to such schemes. If extended information is returned in the Extended data region, the Minimum and Maximum scrub rate fields must be used as indexes into an array of scrub rate descriptors, where each descriptor provides a set of parameters related to that scrub rate. The Minimum scrub rate field must always be 0 as it points to the first descriptor of the array, and the Maximum scrub rate field represents the index of the highest scrub rate descriptor in the array. The scrub rate descriptors provide information about the scrub rates impact on memory bandwidth. This format enables OSPM to perform precision-based scrub control. Bits [7:0]: Current scrub rate that is in effect on the memory region specified in “Actual Address Range”. If OSPM requested background scrubbing, then this field will reflect the current background patrol scrubbing rate. Bits [15:8]: Minimum scrub rate supported. Bits [23:16]: Maximum scrub rate supported. Bits [31:24]: Reserved, must be zero.
Configure Scrub Parameters	4	48	The OSPM Sets this field as follows, for the START_PATROL_SCRUBBER command: Bit[0]: Request background patrol scrubbing. Bits [7:1]: Reserved, must be zero. Bits [15:8]: Requested scrub rate, must be in the range (minimum scrub rate, maximum scrub rate). Bits [31:16]: Reserved, must be zero.
Status (OUTPUT)	4	52	The platform returns the status of the most recent command issued by the OSPM in this field. Status: 0000b = Success 0001b = Not Valid 0010b = Not Supported 0011b = Busy 0100b = Failed 0101b = Aborted 0110b = Invalid Data
Extended Data Region Byte Offset	2	56	Byte offset from the beginning of the PATROL_SCRUB parameter block where the Extended Region is present. OSPM can use the value in this field to determine the presence of the extended data region. If the value is 0, then the extended data region is not present. The extended data region is defined in Table 5.xx. <br. The size of the Extended Data Region is computed as (N + 1) + 4 bytes. N is the Maximum Scrub Rate supported sub-field of the Scrub Parameters field.

Table 5.xx Extended Data Region for PATROL_SCRUB Parameter Block

Field	Byte Length	Byte Offset	Documentation
Extended Scrub Parameters (OUTPUT)	4	0	This field is valid only for the response to GET_PATROL_PARAMETERS. Bits[7:0]: Nominal scrub rate index. Bits[23:8]: Nominal scrub rate in MB/s, for a maximum nominal scrub rate of 64GB/s. Bits[31:24]: Reserved, must be zero. The Nominal scrub rate index must satisfy the condition: Minimum <= Nominal <= Maximum The Nominal rate is defined as the rate at which all memory in this proximity domain is scrubbed in a 24-hour period.
Array of Scrub rate descriptors [N] (OUTPUT)	N	4	This field is valid only for the response to GET_PATROL_PARAMETERS. Each descriptor in this array is a BYTE that represents the fraction of total memory bandwidth consumed by the scrub engine when operating at that scrub rate, for a duration of 24 hours. Scrub rate fractions are expressed as n/255, where n is the value returned in this descriptor. A maximum of 256 distinct scrub rates can thus be specified. Descriptor[0] to Descriptor[Maximum scrub rate] are valid. The combination of the bandwidth consumed, the index of the nominal rate and the real value of the nominal scrub rate, allows the OS to make informed decisions regarding choice of scrub rates. Lower scrub rates consume less bandwidth at the cost of reliability, while higher scrub rates consume more bandwidth to offer improved reliability.

Special Instructions

None.

What specification(s) are directly related?

ACPI

Anything else?

No response