diff --git a/src/srvgrp-clock.adoc b/src/srvgrp-clock.adoc index 4c4271b..a4b9e52 100644 --- a/src/srvgrp-clock.adoc +++ b/src/srvgrp-clock.adoc @@ -85,7 +85,7 @@ rate. The following table shows the structure of the Discrete clock format. [clock_rate1, clock_rate2, clock_rate3, ... , clock_rateN] where: -clock_rate1 < clock_rate2 < clock_rate3, < ... < clock_rateN +clock_rate1 < clock_rate2 < clock_rate3 < ... < clock_rateN ``` .Discrete Clock Format Structure diff --git a/src/srvgrp-performance.adoc b/src/srvgrp-performance.adoc index b2d9e92..c908ef3 100644 --- a/src/srvgrp-performance.adoc +++ b/src/srvgrp-performance.adoc @@ -13,15 +13,17 @@ endif::rootpath[] This PERFORMANCE service group is used to manage the performance of a group of devices or application processors that operate in the same performance domain. Unlike traditional performance control mechanisms, where the OS is -responsible to directly controlling voltages and clocks, this mechanism instead +responsible for directly controlling voltages and clocks, this mechanism instead operates on an metric less integer performance scale. Each integer value on this scale represents a performance operating point. What this scale represents and -the metric is entirely platform-dependent. Values on this scale are discrete, -and the platform has complete control over mapping these performance operating -points to performance states, which are eventually converted into hardware -parameters such as voltage and frequency. For example, the mapping between -levels and frequencies can be as straightforward as using a multiplication -factor of `1000`. +the metric is entirely platform-dependent. Values on this scale are represented +with `performance level index`, and the platform has complete control over +mapping these performance operating points to performance states, which are +eventually converted into hardware parameters such as voltage and frequency. The +level index does not need to be contiguous or to be on a linear scale. For +example, the mapping between levels index and frequencies can be as +straightforward as using a multiplication factor of `1000` or ascending index +number starting from `0`. The CPPC service group is designed for performance control, but it is only intended for application processors. This service group is primarily meant for @@ -39,25 +41,60 @@ The following table lists the services in the PERFORMANCE service group: .PERFORMANCE Services [cols="1, 3, 2", width=100%, align="center", options="header"] |=== -| Service ID | Service Name | Request Type -| 0x01 | PERF_ENABLE_NOTIFICATION | NORMAL_REQUEST -| 0x02 | PERF_GET_NUM_DOMAINS | NORMAL_REQUEST -| 0x03 | PERF_GET_ATTRIBUTES | NORMAL_REQUEST -| 0x04 | PERF_GET_SUPPORTED_LEVELS | NORMAL_REQUEST -| 0x05 | PERF_GET_LEVEL | NORMAL_REQUEST -| 0x06 | PERF_SET_LEVEL | NORMAL_REQUEST -| 0x07 | PERF_GET_LIMIT | NORMAL_REQUEST -| 0x08 | PERF_SET_LIMIT | NORMAL_REQUEST -| 0x09 | PERF_GET_FAST_CHANNEL_ATTRIBUTES | NORMAL_REQUEST +| Service ID +| Service Name +| Request Type + +| 0x01 +| PERF_ENABLE_NOTIFICATION +| NORMAL_REQUEST + +| 0x02 +| PERF_GET_NUM_DOMAINS +| NORMAL_REQUEST + +| 0x03 +| PERF_GET_ATTRIBUTES +| NORMAL_REQUEST + +| 0x04 +| PERF_GET_SUPPORTED_LEVELS +| NORMAL_REQUEST + +| 0x05 +| PERF_GET_LEVEL +| NORMAL_REQUEST + +| 0x06 +| PERF_SET_LEVEL +| NORMAL_REQUEST + +| 0x07 +| PERF_GET_LIMIT +| NORMAL_REQUEST + +| 0x08 +| PERF_SET_LIMIT +| NORMAL_REQUEST + +| 0x09 +| PERF_GET_FAST_CHANNEL_REGION +| NORMAL_REQUEST + +| 0x0A +| PERF_GET_FAST_CHANNEL_ATTRIBUTES +| NORMAL_REQUEST + |=== -[#section-perf-level] -==== Performance Level +[#section-perf-level-attribute] +==== Performance Level Attribute -The following table shows the structure of a single performance level. +The following table shows the structure of a single performance level and its' +attribute. -[#table_performance_level] -.Performance Level Structure +[#table_performance_level_attribute] +.Performance Level Attributes Structure [cols="1,2,5" width=100%, align="center", options="header"] |=== | Word @@ -65,14 +102,18 @@ The following table shows the structure of a single performance level. | Description | 0 +| INDEX +| Performance Level Index + +| 1 | CLOCK_FREQ | Clock frequency (kHz). -| 1 +| 2 | POWER_COST | Power cost (uW). -| 2 +| 3 | TRANSITION_LATENCY | Transition latency (us). |=== @@ -95,6 +136,17 @@ The fast-channel currently supports only the following PERFORMANCE services: * Support for fast-channel depends on the platform implementation. +*Performance Fast-channel Shared Memory Region*:: +* In the memory region designated by the platform for fast-channels, it is + essential that the Performance fast-channels are organized in a continuous + memory block. +* The shared memory region designated for fast-channels across performance + service group must be a `power-of-two` in size. The base address and size (in + bytes) of this shared memory region can be obtained through the service + `PERF_GET_FAST_CHANNEL_REGION`. The base address of the shared memory region + must be aligned to 8 bytes. + + *Discovering Fast-channel*:: * Fast-channels support are discoverable through PERFORMANCE service calls. * To determine if a platform supports fast-channel for a specific performance @@ -102,9 +154,23 @@ The fast-channel currently supports only the following PERFORMANCE services: * If fast-channel support is available, retrieve fast-channel attributes for specific PERFORMANCE service call using the `PERF_GET_FAST_CHANNEL_ATTRIBUTES` service call. +* The `PERF_GET_FAST_CHANNEL_REGION` provides physical memory for Performance + Service Group. The offset of the physical address retrieve in + `PERF_GET_FAST_CHANNEL_ATTRIBUTES` of the 'Performance Domain / + Service ID' paired is based on the starting address in + `PERF_GET_FAST_CHANNEL_REGION` service. *Doorbell Support*:: +* The doorbell details such as doorbell register address and preserve mask can + be discovered by the application processor through the + `PERF_GET_FAST_CHANNEL_ATTRIBUTES` service. +* The doorbell register address is the physical address of the register which + needs to be written to trigger the doorbell interrupt. The doorbell set mask + is the mask of bits which must be set when writing in the doorbell register. + The doorbell preserve mask is the mask of bits which must be preserved when + writing in the doorbell register. The width of the doorbell set mask and + doorbell preserve mask must be equal to the doorbell register width. * Doorbell support is not available for `PERF_GET_LEVEL` and `PERF_GET_LIMIT` service calls. * When fast-channels are implemented for `PERF_GET_LEVEL` and `PERF_GET_LIMIT` @@ -446,7 +512,8 @@ operating performance points (OPPs) for a specific performance domain. These represent different performance levels that can be set for the components in the domain, and are defined by a combination of frequency, power cost and other parameters. By using this information, the OS can select the optimal -performance level based on the system's workload and power constraints. +performance level based on the system's workload and power constraints using +`performance level index` returned in this service. ```c /* Pseudocode to retrieve the list of the supported performance levels. */ @@ -461,6 +528,7 @@ loop: entry_num = 0; for (i = 0; i < list.returned; i++, num++) { + opp[num].index = list.entry[entry_num++]; opp[num].freq = list.entry[entry_num++]; opp[num].power = list.entry[entry_num++]; opp[num].rate_limit = list.entry[entry_num++]; @@ -505,7 +573,7 @@ levels. | 1 | PERF_LEVEL_INDEX | uint32 -| Start array index to read. The first index starts at zero. +| Index of performance data array. The first index starts at zero. |=== [#table_perf_getdomainlevels_response_data] @@ -553,14 +621,15 @@ levels. | 4 | LEVEL[N] -| uint32[3] -| List of performance levels. + -Refer to <> for the structure of performance level. +| uint32[4] +| List of performance levels attributes. + +Refer to <> for the complete structure of performance +level attributes. |=== ==== Service: PERF_GET_LEVEL (SERVICE_ID: 0x05) -This service is used to obtain the current performance level of a specific +This service is used to obtain the current performance level index of a specific performance domain in the system. [#table_perf_getlevel_request_data] @@ -609,12 +678,12 @@ performance domain in the system. | 1 | LEVEL | uint32 -| Current performance level of the domain. +| Current performance level index of the domain. |=== ==== Service: PERF_SET_LEVEL (SERVICE_ID: 0x06) -This service is used to set the current performance level of a specific +This service is used to set the current performance level index of a specific performance domain in the system. [#table_perf_setlevel_request_data] @@ -634,7 +703,7 @@ performance domain in the system. | 1 | LEVEL | uint32 -| Performance level. +| Performance level index. |=== [#table_perf_setlevel_response_data] @@ -662,7 +731,7 @@ performance domain in the system. ! RPMI_ERR_INVALID_PARAM ! `DOMAIN_ID` or `LEVEL` is invalid. -! RPMI_ERR_DENIED +! RPMI_ERR_DENIED ! Denied due to no permission. ! RPMI_ERR_HW_FAULT @@ -723,12 +792,12 @@ performance domain in the system. | 1 | MAX_PERF_LEVEL | uint32 -| Maximum allowed performance level. +| Maximum allowed performance level index. | 2 | MIN_PERF_LEVEL | uint32 -| Minimum allowed performance level. +| Minimum allowed performance level index. |=== @@ -753,12 +822,12 @@ performance domain in the system. | 1 | MAX_PERF_LEVEL | uint32 -| Maximum allowed performance level. +| Maximum allowed performance level index. | 2 | MIN_PERF_LEVEL | uint32 -| Minimum allowed performance level. +| Minimum allowed performance level index. |=== [#table_perf_setlimit_response_data] @@ -800,7 +869,70 @@ performance domain in the system. |=== -==== Service: PERF_GET_FAST_CHANNEL_ATTRIBUTES (SERVICE_ID: 0x09) +==== Service: PERF_GET_FAST_CHANNEL_REGION (SERVICE_ID: 0x09) +This service retrieves the physical address of the fast-channel region used in +the performance service group. The fast-channel region is grouped in a continuous +block of memory to ease the configuration of memory region protection. + +[#table_perf_getfastchanregion_request_data] +.Request Data +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== + +[#table_perf_getfastchanregion_response_data] +.Response Data +[cols="1, 3, 1, 7a", width=100%, align="center", options="header"] +|=== +| Word +| Name +| Type +| Description + +| 0 +| STATUS +| int32 +| Return error code + +[cols="6,5", options="header"] +!=== +! Error Code +! Description + +! RPMI_SUCCESS +! Service completed successfully. + +! RPMI_ERR_NOT_SUPPORTED +! Fast-channel is not implemented. + +!=== +- Other errors <> + +| 1 +| REGION_PHYS_ADDR_LOW +| uint32 +| Lower 32-bit of the fast-channels shared memory region physical address. + +| 2 +| REGION_PHYS_ADDR_HIGH +| uint32 +| Upper 32-bit of the fast-channels shared memory region physical address. + +| 3 +| REGION_SIZE_LOW +| uint32 +| Lower 32-bit of the fast-channels shared memory region size. + +| 4 +| REGION_SIZE_HIGH +| uint32 +| Upper 32-bit of the fast-channels shared memory region size. + +|=== + + +==== Service: PERF_GET_FAST_CHANNEL_ATTRIBUTES (SERVICE_ID: 0x0A) This service allows clients to query attributes of the fast-channel for a specific performance domain and performance service. @@ -826,7 +958,7 @@ specific performance domain and performance service. [#table_perf_getfastchanaddr_response_data] .Response Data -[cols="1, 3, 1, 7a", width=100%, align="center", options="header"] +[cols="1, 4, 1, 6a", width=100%, align="center", options="header"] |=== | Word | Name @@ -882,45 +1014,57 @@ specific performance domain and performance service. !=== | 2 -|PHYS_ADDR_LOW +| FASTCHAN_OFFSET_LOW | uint32 -| Lower 32-bit of physical address. +| Lower 32-bit offset of fast-channel physical address region. | 3 -| PHYS_ADDR_HIGH +| FASTCHAN_OFFSET_HIGH | uint32 -| Upper 32-bit of physical address. +| Upper 32-bit offset of fast-channel physical address region. | 4 -| DB_ADDR_LOW +| FASTCHAN_SIZE | uint32 -| Lower 32-bit of doorbell address. This field is unused if the doorbell is not supported. +| The size of fast-channel physical address in bytes. | 5 -| DB_ADDR_HIGH +| DB_ADDR_LOW | uint32 -| Upper 32-bit of doorbell address. This field is unused if the doorbell is not supported. +| Lower 32-bit of doorbell register address for Performance Request fast-channel. +This field is unused if the doorbell is not supported. | 6 -|DB_ID_LOW +| DB_ADDR_HIGH | uint32 -| Lower 32-bit of doorbell ID. This field is unused if the doorbell is not supported. +| Upper 32-bit of doorbell register address for Performance Request fast-channel. +This field is unused if the doorbell is not supported. | 7 -| DB_ID_HIGH +| DB_ID_LOW | uint32 -| Upper 32-bit of doorbell ID. This field is unused if the doorbell is not supported. +| Lower 32-bit of doorbell ID. This represents the mask of bits which must be +set in the doorbell register. This field is unused if the doorbell is not supported. | 8 +| DB_ID_HIGH +| uint32 +| Upper 32-bit of doorbell ID. This represents the mask of bits which must be +set in the doorbell register. This field is unused if the doorbell is not supported. + +| 9 | DB_PRESERVED_LOW | uint32 | A lower 32-bit doorbell preserved mask to apply for this service before -ringing the doorbell. This field is unused if the doorbell is not supported. +ringing the doorbell. This represents the mask of bits which must be preserved +in the doorbell register. This field is unused if the doorbell is not supported. -| 9 +| 10 | DB_PRESERVED_HIGH | uint32 | An upper 32-bit doorbell preserved mask to apply for this service before -ringing the doorbell. This field is only valid if the doorbell register width -is 64-bit. This field is unused if the doorbell is not supported. +ringing the doorbell. This represents the mask of bits which must be preserved +in the doorbell register. This field is only valid if the doorbell register width +is 64-bit and unused if the doorbell is not supported. + |=== diff --git a/src/srvgrp-voltage.adoc b/src/srvgrp-voltage.adoc index 1898ece..0e0103b 100644 --- a/src/srvgrp-voltage.adoc +++ b/src/srvgrp-voltage.adoc @@ -62,14 +62,21 @@ The following table lists the services in the VOLTAGE service group: [#voltage-level-format-section] ==== Voltage Level Format -There are 4 types of voltage level formats supported in the VOLTAGE service +There are 2 types of voltage level formats supported in the VOLTAGE service group. The voltage levels are represented as a group. -===== Fixed Voltage Format -A constant voltage level. The following table shows the structure of the fixed -voltage format. +===== Discrete Format +A set of discrete voltage levels arranged in a sequence, starting from the +lowest value at the lowest index and increasing sequentially to higher levels. +The following table shows the structure of the discrete format. + +```c +[voltage1, voltage2, voltage3, ... , voltageN] + +where: +voltage1 < voltage2 < voltage3 < ... < voltageN +``` -.Fixed Voltage Structure [cols="1,2,5" width=100%, align="center", options="header"] |=== | Word @@ -78,12 +85,16 @@ voltage format. | 0 | VOLTAGE -| Fixed voltage in microvolts (uV). +| Discrete voltage level in microvolts (uV). |=== -===== Simple-Linear Format +===== Linear Format A linear range of voltage levels with a constant step size. The following table -shows the structure of the simple-linear voltage format. +shows the structure of the linear voltage format. + +```c +[voltage_minimum, voltage_maximum, voltage_step] +``` [cols="1,2,5" width=100%, align="center", options="header"] |=== @@ -104,49 +115,6 @@ shows the structure of the simple-linear voltage format. | Step size in microvolts (uV). |=== -===== Multi-Linear Format -Multiple linear ranges of voltage levels, each with its own step size. The -following table shows the structure of the multi-linear voltage format. - -[cols="1,2,5" width=100%, align="center", options="header"] -|=== -| Word -| Name -| Description - -| 0 -| VOLTAGE_MIN -| Lower boundary of voltage level in microvolts (uV). - -| 1 -| VOLTAGE_MIN_SEL -| Lowest selector for range. - -| 2 -| VOLTAGE_MAX_SEL -| Highest selector for range. - -| 3 -| STEP -| Step size in microvolts (uV). -|=== - -===== Discrete Format -A set of discrete voltage levels arranged in a sequence, starting from the -lowest value at the lowest index and increasing sequentially to higher levels. -The following table shows the structure of the discrete format. - -[cols="1,2,5" width=100%, align="center", options="header"] -|=== -| Word -| Name -| Description - -| 0 -| VOLTAGE -| Discrete voltage level in microvolts (uV). -|=== - [#voltage-notifications] ==== Notifications This service group does not support any events for notification. @@ -278,8 +246,9 @@ for operation. The number of levels indicates the total count of voltage levels supported within a voltage domain. Transition latency denotes the maximum time required for the voltage to stabilize upon a change in the regulator. Depending on the hardware, voltage levels can be of various formats, and the current -service supports Fixed voltage, Simple-linear, Multi-linear, and Discrete range -formats. Additional voltage formats can be accommodated in the future if required. +service supports discrete and linear formats. Each domain can support only one +voltage level format. Additional voltage formats can be accommodated in the +future if required. [#table_voltage_getdomainattrs_request_data] .Request Data @@ -337,11 +306,9 @@ formats. Additional voltage formats can be accommodated in the future if require ! Voltage format. + Refer to <> for more details. ---- -0b000: Fixed voltage. -0b001: Simple-linear. -0b010: Multi-linear. -0b011: Discrete range. -0b100 - 0b111: Reserved. +0b000: Discrete voltage. +0b001: Linear. +0b010 - 0b111: Reserved. ---- ! [0] @@ -349,24 +316,15 @@ Refer to <> for more details. ---- 0b0: Voltage domain can be enabled/disabled. -0b1: Voltage domain is always-on, voltage value can be changed in the supported voltage range. +0b1: Voltage domain is always-on, voltage value can be changed in the +supported voltage range. ---- !=== | 2 | NUM_LEVELS | uint32 -| Number of voltage levels (number of arrays) supported by the domain. - -[cols="2,5a", options="header"] -!=== -! Value -! Description - -! 1 -! Fixed voltage format only. -! N -! Simple-linear, Multi-linear and Discrete. -!=== +| Number of voltage levels (number of arrays) supported by the domain. Each +linear format voltage level represents 1 voltage level. | 3 | TRANS_LATENCY