diff --git a/riscv-rpmi.adoc b/riscv-rpmi.adoc index ca253c4..fdda58f 100644 --- a/riscv-rpmi.adoc +++ b/riscv-rpmi.adoc @@ -20,7 +20,7 @@ :imagesoutdir: docs-resources/images :bibtex-file: src/rpmi.bib :bibtex-order: alphabetical -:bibtex-style: apa +:bibtex-style: ieee :icons: font :lang: en :listing-caption: Listing @@ -72,5 +72,5 @@ include::src/srvgrp-performance.adoc[] include::src/srvgrp-management.adoc[] // The index must precede the bibliography -include::src/index.adoc[] +//include::src/index.adoc[] include::src/bibliography.adoc[] diff --git a/src/intro.adoc b/src/intro.adoc index b57a257..6c31367 100644 --- a/src/intro.adoc +++ b/src/intro.adoc @@ -54,5 +54,5 @@ image::transport-topologies.png[width=800,height=800] RPMI is designed to work with a single or multi-tenant topology as depicted above. -NOTE: The discovery of the transport itself is out of scope for this document. Which can either be described in firmware through DT or ACPI. +NOTE: The discovery of the transport itself is out of scope for this document. Which can either be described in firmware through DT cite:[DT] or ACPI cite:[ACPI]. diff --git a/src/rpmi.bib b/src/rpmi.bib index 8b13789..9c76d3c 100644 --- a/src/rpmi.bib +++ b/src/rpmi.bib @@ -1 +1,12 @@ - +@electronic{SBI, + title = {RISC-V Supervisor Binary Interface Specification}, + url = {https://github.com/riscv-non-isa/riscv-sbi-doc} +} +@electronic{ACPI, + title = {Advanced Configuration and Power Interface Specification}, + url = {https://uefi.org/specifications} +} +@electronic{DT, + title = {DeviceTree}, + url = {https://www.devicetree.org/} +} diff --git a/src/srvgrp-clock.adoc b/src/srvgrp-clock.adoc index 3849cf4..f009322 100644 --- a/src/srvgrp-clock.adoc +++ b/src/srvgrp-clock.adoc @@ -3,21 +3,20 @@ This service group is for the management of system clocks. Services defined in this group are used to enable or disable clocks, and to set/get clock rates. -Each clock in the system is identified by the clock id which is an integer -identifier assigned to each clock. The mapping of clock_id and clock is known to -both AP and Platform Microcontroller. Clock ID identifiers are sequential and -start from `0`. +Each clock in the system is identified by the clock ID, which is an integer +identifier assigned to each clock. The mapping of CLOCK_ID and clock is known +to both the AP and the Platform Microcontroller. Clock ID identifiers are +sequential and starting from `0`. -The device or the group of devices which share the same clock source becomes a -single clock domain, which is identified by the clock_id. Any change in the -clock source affects the whole domain which can contain multiple devices. +The device or the group of devices sharing the same clock source form a +single clock domain, which is identified by the CLOCK_ID. Any change to the +clock source affects the entire domain which may contain multiple devices. -This topology of devices and clock source is dependent on how the system is -designed and implementation specific. OS can discover this topology through -firmware tables (DT/ACPI). +The topology of the devices and the clock source is dependent on how the system +is designed and implementation specific. The OS can discover this topology +through firmware tables (DT cite:[DT] / ACPI cite:[ACPI]). - -==== Clock rate format +*Clock Rate Format*:: Each clock rate is a tuple of two `32 bits` values `(uint32, uint32)` represented as `(clock_rate_low, clock_rate_high)` and packed in the same order where `clock_rate_low` is at the lower index than the `clock_rate_high`. @@ -42,9 +41,11 @@ Below table lists the services in this group: This service group does not support any event for notification ==== Service: *ENABLE_NOTIFICATION* -This service allows AP to subscribe to clock service group notifications. -Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented -and AP has subscribed to these. Events supported are described above in Clock Notifications. +This service allows the AP to subscribe to clock service group notifications. +The platform can optionally support notifications of events which might occur in +the platform. The PuC can send these notification messages to AP if they are +implemented and the AP has subscribed to these. The supported events are described +above in Clock Notifications. [#table_clock_ennotification_request_data] .Request Data @@ -72,8 +73,9 @@ notification. |=== ==== Service: *GET_NUM_CLOCKS* -Request for number of clocks available in the system. All supported clocks in -the system are designated by an integer identifier called clock_id. Clock_id are sequential starting from `0`. +This service is used to query the number of clocks available in the system. +All supported clocks in the system are designated by an integer identifier +called CLOCK_ID. CLOCK_ID are sequential starting from `0`. [#table_clock_getnumclocks_request_data] .Request Data @@ -95,16 +97,17 @@ the system are designated by an integer identifier called clock_id. Clock_id are |=== ==== Service: *GET_ATTRIBUTES* -This service returns the attributes of a clock like name of the clock which is -an array ASCII string of `16 byte`. Transition latency which is the worst case -latency for the clock to return to a stable state once clock configuration is -changed. Number of Clock rates supported by the requested clock. -FLAGS field encode the clock format supported by the clock. - -Current supported clock formats are discrete, which is an array of discrete -values where each value represents a clock rate. Another format is linear range -which is represented by `(min_Hz, max_Hz, step_Hz)`. In future more clock formats -can be supported if required. +This service provides detailed attributes of a clock, including its name, +represented as a 16-byte array of ASCII strings. It also specifies the +transition latency, which denotes the maximum time for the clock to stabilize +after a configuration change. Moreover, it indicates the number of clock rates +supported by the requested clock. The FLAGS field encodes the clock formats +supported by the clock. + +Currently supported clock formats include `discrete` format, represented as an +array where each value represents a clock rate, and `linear` format represented +as `(min_Hz, max_Hz, step_Hz)`. Additional clock formats may be supported in +the future, as needed. [#table_clock_getattrs_request_data] .Request Data @@ -134,8 +137,7 @@ can be supported if required. ! [31:30] ! CLOCK_FORMAT 0b00: Discrete Format - Each element in the CLOCK_RATE array is a supported discrete clock rate - value packed in ascending order. Each rate is in Hertz. + Each element in the CLOCK_RATE array is a supported discrete clock rate value packed in ascending order. Each rate is in Hertz. 0b01: Linear Range The CLOCK_RATE array contains the triplet (min_Hz, max_Hz, step_Hz). @@ -145,28 +147,28 @@ can be supported if required. CLOCK_RATE[2] = step_Hz (Step between two successive rates) ! [29:0] ! _Reserved_ !=== -| 2 |NUM_RATESS | uint32 | Number of Clock rates of type depending on CLOCK_FORMAT. -| 3 | TRANSITION_LATENCY | uint32 | Transition Latency +| 2 |NUM_RATESS | uint32 | Number of clock rates of type depending on CLOCK_FORMAT. +| 3 | TRANSITION_LATENCY | uint32 | Transition latency, in microseconds (us) | 4:7 | CLOCK_NAME | uint8[16] | Clock name |=== ==== Service: *GET_SUPPORTED_RATES* Each domain may support multiple clock rate values which are allowed by the -domain to operate. Message can also pass the `clock_rate_index` which is the index +domain to operate. Message can also pass the `CLOCK_RATE_INDEX` which is the index to the first rate value to be described in the return rate array. If all supported rate values are required then this index value can be `0`. If the CLOCK_FORMAT is discrete then the clock rate in the received data is an -array of supported discrete rate values packed in ascending order starting from +array of supported discrete rate values packed in ascending order starting from the lower index in the CLOCK_RATE field. If the CLOCK_FORMAT is a linear range, then the CLOCK_RATE array contains a triplet of `(min_Hz, max_Hz, step_Hz)` where each item in the triplet is a clock rate value. Total words required for the number of clock rates according to the format in one message cannot exceed the total words available in one message DATA field. -If they exceed then PuC will return the number of clock rates which can be -accommodated in one message and set the REMAINING field accordingly. AP, when -REMAINING field is not `0` must call this service again with appropriate +If they exceed then the PuC will return the number of clock rates which can be +accommodated in one message and set the REMAINING field accordingly. The AP, +when REMAINING field is not `0` must call this service again with appropriate CLOCK_RATE_INDEX set to get the remaining clock rates. It's possible that multiple service calls may be required to get all the clock rates. In case the CLOCK_FORMAT is a linear range the RETURNED field will be set to `3`. diff --git a/src/srvgrp-cppc.adoc b/src/srvgrp-cppc.adoc index f200306..6d17e7e 100644 --- a/src/srvgrp-cppc.adoc +++ b/src/srvgrp-cppc.adoc @@ -1,5 +1,5 @@ === Service Group - *CPPC* (servicegroup_id: 0x00005) -This service group defines the services to control CPU performance by managing a set of registers and a dedicated physical memory block, which will define fast channel access to each hart in the system. Hart writes a specific 32 bits desired performance number in fast channel memory. PuC decodes the request and performs the corresponding CPPC operations. +This service group defines the services to control CPU performance by managing a set of registers and a dedicated physical memory block, which will define Fast-channel access to each hart in the system. Hart writes a specific 32 bits desired performance number in Fast-channel memory. PuC decodes the request and performs the corresponding CPPC operations. CPPC physical memory will have enough space to accommodate all available harts. Hart can send an RPMI message GET_CPPC_PERF_CHAN_ADDR to query the physical address of that particular hart. @@ -9,11 +9,11 @@ PROBE_CPPC_REG service can be used to check if a particular CPPC register is imp For extra debugging, Hart can send a GET_CPPC_PERF_POKE message to exclusively request PuC to process the pending CPPC requests, if any. -For more information on CPPC, refer https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/index.html[ACPI] and https://github.com/riscv-non-isa/riscv-sbi-doc/[CPPC]. +For more information on CPPC, please refer to the ACPI Specification cite:[ACPI] and the CPPC Extension in the RISC-V SBI Specification cite:[SBI]. -CPPC Fast Channel REQ-ACK Memory Entry per Hart: +CPPC Fast-channel REQ-ACK Memory Entry per Hart: [#table_cppc_fastchan_mem] -.CPPC Fast Channel Memory Entry +.CPPC Fast-Channel Memory Entry [cols="1, 3, 2", width=100%, align="center", options="header"] |=== | Word | Description | Entity which writes the word @@ -28,14 +28,14 @@ Below table lists the services in this group: .CPPC Services [cols="1, 3, 2", width=100%, align="center", options="header"] |=== -| Service ID | Service Name | Request Type -| 0x01 | ENABLE_NOTIFICATION | NORMAL_REQUEST -| 0x02 | PROBE_REG | NORMAL_REQUEST -| 0x03 | READ_REG | NORMAL_REQUEST -| 0x04 | WRITE_REG | NORMAL_REQUEST -| 0x05 | GET_FAST_CHANNEL_ADDR | NORMAL_REQUEST -| 0x06 | POKE_FAST_CHANNEL | NORMAL_REQUEST -| 0x07 | GET_HART_LIST | NORMAL_REQUEST +| Service ID | Service Name | Request Type +| 0x01 | ENABLE_NOTIFICATION | NORMAL_REQUEST +| 0x02 | PROBE_REG | NORMAL_REQUEST +| 0x03 | READ_REG | NORMAL_REQUEST +| 0x04 | WRITE_REG | NORMAL_REQUEST +| 0x05 | GET_FAST_CHANNEL_ATTRIBUTES | NORMAL_REQUEST +| 0x06 | POKE_FAST_CHANNEL | NORMAL_REQUEST +| 0x07 | GET_HART_LIST | NORMAL_REQUEST |=== ==== CPPC Notifications @@ -175,9 +175,9 @@ probe the REG_ID before reading. -==== Service: *GET_FAST_CHANNEL_ADDR* -Request for physical address of CPPC fast channel for the hart ID specified, -this physical address shall be used to write the value of https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/08_Processor_Configuration_and_Control/declaring-processors.html?highlight=cppc#desired-performance-register[CPPC Desired +==== Service: *GET_FAST_CHANNEL_ATTRIBUTES* +This request retrieves attributes of the Fast-channel for a specified hart ID. +The physical address from this request shall be used to write the value of the https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/08_Processor_Configuration_and_Control/declaring-processors.html?highlight=desired-performance-register#desired-performance-register[CPPC Desired Performance Register]. [#table_cppc_getfastchanaddr_request_data] @@ -199,7 +199,7 @@ Performance Register]. ! *Error Code* ! *Description* ! RPMI_SUCCESS ! Service completed successfully. ! RPMI_ERROR_NOT_FOUND ! HART_ID not found -! RPMI_ERROR_NOT_SUPPORTED ! Fast channel not implemented +! RPMI_ERROR_NOT_SUPPORTED ! Fast-channel not implemented !=== - Other errors <> | 1 | FLAGS | uint32 | @@ -246,7 +246,7 @@ any. [cols="2,5"] !=== ! *Error Code* ! *Description* -! RPMI_SUCCESS ! Fast channel poked and service completed successfully. +! RPMI_SUCCESS ! Fast-channel poked and service completed successfully. !=== - Other errors <> |=== diff --git a/src/srvgrp-device-power.adoc b/src/srvgrp-device-power.adoc index 0eb1fc8..8020cff 100644 --- a/src/srvgrp-device-power.adoc +++ b/src/srvgrp-device-power.adoc @@ -1,26 +1,27 @@ === Service Group - *DEVICE_POWER* (servicegroup_id: 0x00008) -This device power service group provides messages to manage the power states of -a device power domain. This service group is only used for device power +This Device Power service group provides messages to manage the power states of +a device power domain. This service group is used only for device power management since System and CPU power management is handled by already defined -service groups like SYSTEM_RESET, SYSTEM_SUSPEND and HART_STATE_MANAGEMENT. +service groups such as SYSTEM_RESET, SYSTEM_SUSPEND and HART_STATE_MANAGEMENT. A domain can consist of one device if its power states can be controlled independently or it may also have multiple devices if they all share the same -power control lines and power state can only be changed collectively. +power control lines and power states can only be changed collectively. Each domain must support ON and OFF states along with custom power states which are discoverable. Domains may also have power states which may preserve the -context. Level of context preserved will depend on the level of power state. +context. The level of context preserved will depends on the level of power state. -Power states for domains will be discovered via DT or ACPI where the values for -ON and OFF are already fixed and known. Power state encodes both the power state -value and the context preserved or lost information corresponding to that state. +Power states for domains will be discovered via DT cite:[DT] or ACPI cite:[ACPI], +where the values for ON and OFF are already fixed and known. The power state encodes +both the power state value and the context preserved or lost information +corresponding to that state. [#table_devpower_powerstate_data] .Power States Encoding [cols="2, 2, 5a", width=100%, align="center", options="header"] |=== -| POWER_STATE(uint32) | Field | Description +| POWER_STATE (uint32) | Field | Description | POWER_STATE[31] | CONTEXT | 0b0: Context is preserved @@ -55,9 +56,10 @@ value and the context preserved or lost information corresponding to that state. This service group does not support any event for notification. ==== Service: *ENABLE_NOTIFICATION* -This service allows AP to subscribe to device power service group notifications. -Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented -and AP has subscribed to these. Events supported are described above in Device +This service allows the AP to subscribe to Device Power service group notifications. +The platform can optionally support notifications of events that may occur in the platform. +The PuC can send these notification messages to the AP if they are implemented +and the AP has subscribed to them. The supported events are described above in Device Power Notifications. [#table_devpower_ennotification_request_data] @@ -88,8 +90,7 @@ notification. ==== Service: *GET_NUM_DOMAINS* This service is used to query the number of device power domains available which can be controlled by the client. The number of domains returned can be less than -the actual number of domains present with the platform. The number of domains -returned are allowed to be managed by the client. +the actual number of domains present with the platform. [#table_devpower_getdomains_request_data] .Request Data @@ -107,7 +108,7 @@ returned are allowed to be managed by the client. ! RPMI_SUCCESS ! Service completed successfully. !=== - Other errors <> -| 1 | NUM_DOMAINS | uint32 | Number of domains +| 1 | NUM_DOMAINS | uint32 | Number of device power domains |=== @@ -137,9 +138,9 @@ This service is used to query the attributes of a device power domain. - Other errors <> | 1 | FLAGS | uint32 | _Reserved_ | 2 | TRANSITION_LATENCY | uint32 | Worst case transition latency -of domain from one power state to another +of domain from one power state to another, in microseconds (us) | 3:6 | DEVICE_POWER_DOMAIN_NAME | uint8[16] | Device power domain -name +name, a NULL-terminated ASCII string up to 16-bytes. |=== @@ -155,7 +156,7 @@ This service is used to change the power state of a device power domain. | 1 | POWER_STATE | uint32 | This field indicates the power state to which the power domain should transition. The specific power states and their meanings may vary depending on the implementation, but generally, they include values such as "ON", "OFF" and vendor specific power state. + -See Power States table in the service group description +See Power States description in the <>. |=== [#table_devpower_setstate_response_data] @@ -201,8 +202,8 @@ This service is used to get the current power state of a device power domain. ! RPMI_ERROR_DENIED ! Client does not have permissions to change the Device power domain power state. !=== - Other errors <> -| 1 | POWER_STATE | uint32 | This field indicates the power state to which the power domain should transition. The specific power states and their -meanings may vary depending on the implementation, but generally, they include -values such as "ON", "OFF" and vendor specific power state. + -See Power States table in the service group description -|=== \ No newline at end of file +| 1 | POWER_STATE | uint32 | This field indicates the current power state +of the specified domain. The power state can be one of several predefined values, +such as ON, OFF, or vendor specific implementation. +See Power States description in the <>. +|=== diff --git a/src/srvgrp-hart-state-management.adoc b/src/srvgrp-hart-state-management.adoc index 23d4822..43cbd0c 100644 --- a/src/srvgrp-hart-state-management.adoc +++ b/src/srvgrp-hart-state-management.adoc @@ -1,7 +1,7 @@ === Service Group - *HART_STATE_MANAGEMENT* (servicegroup_id: 0x00004) The Hart State Management (HSM) service group defines a set of Hart states and -functionality equivalent to the RISC-V SBI HSM extension. +functionality equivalent to the HSM extension in RISC-V SBI Specification cite:[SBI]. Below table lists the services in this group: [#table_hsm_services] @@ -131,7 +131,7 @@ success, the calling hart is suspended only after it executes WFI instruction. | Word | Name | Type | Description | 0 | HART_ID | uint32 | Hart ID of the calling hart. | 1 | SUSPEND_TYPE | uint32 | Hart suspend type as defined by RISC-V -SBI Extension[[TODO LINK HERE]] +SBI Specification cite:[SBI]. | 2 | RESUME_ADDR_LOW | uint32 | Lower `32 bits` of resume address. + _Only used for non-retentive suspend types._ | 3 | RESUME_ADDR_HIGH | uint32 | Upper `32 bits` of resume address. + diff --git a/src/srvgrp-performance.adoc b/src/srvgrp-performance.adoc index b644890..f5febae 100644 --- a/src/srvgrp-performance.adoc +++ b/src/srvgrp-performance.adoc @@ -1,18 +1,21 @@ === Service Group - *PERFORMANCE* (servicegroup_id: 0x00009) This performance domain extension is designed for managing the performance of a -group of devices or application processors that operate in the same performance domain. Unlike legacy performance control mechanisms where the OS was -responsible to directly control the voltage and clocks this mechanism instead -operates on an metric less integer performance scale. Each integer value on this +group of devices or application processors that operate in the same performance +domain. Unlike legacy performance control mechanisms where the OS was responsible +to directly control the voltage 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 completely platform dependent. Values on this scale are discrete and the platform is given complete control over mapping these performance operating points to performance states which eventually gets converted into -hardware parameters like voltage and frequency, etc. The mapping between levels +hardware parameters such as voltage and frequency, etc. The mapping between levels and frequencies can be as simple as using a multiplication factor of 1000. -CPPC service group is also meant for performance control but it's only for the application processors. This service group is primarily meant for devices like -GPUs, Accelerators, etc but can also be used for application processors. +The CPPC service group is also intended for performance control but it's only +for the application processors. This service group is primarily intended for +devices such as GPUs, accelerators, etc but can also be used for application +processors. It is important to note that performance domains should not be confused with power domains. A performance domain is defined as a set of devices that must @@ -23,7 +26,8 @@ purposes. The Performance service groups provide a set of services for managing performance domains. These services include retrieving performance domain information, setting the performance level, obtaining the current performance -level of a performance domain, and performing other related operations. These operations are described in more detail in the following section. +level of a performance domain, and performing other related operations. +These operations are described in more detail in the following section. [#table_perf_services] .Performance Services @@ -38,7 +42,7 @@ level of a performance domain, and performing other related operations. These op | 0x06 | SET_PERF_LEVEL | NORMAL_REQUEST | 0x07 | GET_PERF_LIMIT | NORMAL_REQUEST | 0x08 | SET_PERF_LIMIT | NORMAL_REQUEST -| 0x09 | GET_PERF_DOMAIN_FAST_CHANNEL_ADDR | NORMAL_REQUEST +| 0x09 | GET_PERF_FAST_CHANNEL_ATTRIBUTES | NORMAL_REQUEST |=== ==== Performance Notifications @@ -57,7 +61,7 @@ domain. This notification is typically sent by the platform control processor to !=== ! *Word* ! Type ! *Description* ! 0 ! uint32 ! Performance domain ID whose power changed. -! 1 ! uint32 ! New Power value(uW) +! 1 ! uint32 ! New power value (uW) !=== | Performance power changed notification. @@ -67,8 +71,8 @@ domain. This notification is typically sent by the platform control processor to ! *Word* ! Type ! *Description* ! 0 ! uint32 ! Performance domain ID whose performance limit changed. -! 1 ! uint32 ! New Max Perf Level. -! 2 ! uint32 ! New Min Perf Level. +! 1 ! uint32 ! New maximum performance level. +! 2 ! uint32 ! New minimum performance level. !=== | Performance limit changed notification. @@ -77,11 +81,58 @@ changed. !=== ! *Word* ! Type ! *Description* ! 0 ! uint32 ! Performance domain ID whose performance level changed. -! 1 ! uint32 ! New Perf Level. +! 1 ! uint32 ! New performance level. !=== | Performance level changed notification. |=== +==== Performance Fast-Channels +This section provides an overview of the properties associated with the Fast-channel +for Performance service group. + +*Supported Services*:: +The Fast-channel currently supports only the following Performance services: +* GET_PERF_LEVEL +* SET_PERF_LEVEL +* GET_PERF_LIMIT +* SET_PERF_LIMIT + + +*Platform Dependency*:: +* Not all Performance domains or Performance services are required to support + Fast-channel functionality. +* Support for Fast-channel depends on the platform implementation. + + +*Discovering Fast-channels*:: +* Fast-channels support are discoverable through Performance service calls. +* To determine if a platform supports Fast-channel for a specific performance + domain, use the `GET_PERF_DOMAIN_ATTRIBUTES` service call. +* If Fast-channel support is available, retrieve Fast-channel attributes for + specific Performance service call using the `GET_PERF_FAST_CHANNEL_ATTRIBUTES` + service call. + + +*Doorbell Support*:: +* Doorbell support is not available for `GET_PERF_LEVEL` and `GET_PERF_LIMIT` + service calls. +* When Fast-channels are implemented for `GET_PERF_LEVEL` and `GET_PERF_LIMIT` + service calls, the last known valid performance level or performance limits + are always accessible via the Fast-channel without requiring a doorbell + trigger. +* For other Performance service calls that support Fast-channel, doorbell + support is optional. + + +*Payload Requirements*:: +* The payload of a Fast-channel should exclusively include message specific + parameters and exclude the DOMAIN_ID. Given that a Fast-channel is specific + to both DOMAIN_ID and SERVICE_ID, there is no requirement to include + DOMAIN_ID or any other channel specific and message specific headers when + utilizing a Fast-channel. For instance, the payload of the `SET_PERF_LIMIT` + message should be represented as `'uint32 MAX_PERF_LEVEL'` and + `'uint32 MIN_PERF_LEVEL'`. + ==== Service: *ENABLE_NOTIFICATION* This service is to enable or disable the performance changed notification event. This notification is sent from the PuC when the performance level, performance @@ -116,7 +167,7 @@ notification. ==== Service: *GET_PERF_DOMAINS* -Returns the number of performance domains supported by the system. +This service returns the number of performance domains supported by the system. The number of performance domains can vary depending on the hardware platform and implementation. In general, performance domains are used to group related hardware components, such as CPUs, GPUs, memory, and peripherals, into separate @@ -140,7 +191,7 @@ important for optimizing system performance and power consumption. ! RPMI_SUCCESS ! Service completed successfully. !=== - Other errors <> -| 1 | NUM_DOMAINS | uint32 | Number of domains +| 1 | NUM_DOMAINS | uint32 | Number of performance domains |=== @@ -198,13 +249,16 @@ Total number of performance levels supported. ! [20:0] ! _Reserved_ !=== | 2 | RATE_LIMIT_US | uint32 | Minimum amount of time that needs to -pass between two consecutive requests, in microsecond(us). -| 3:6 | PERF_DOMAIN_NAME | uint8[16] | A NULL-terminated string for performance domain name. Up to 16-Bytes. +pass between two consecutive requests, in microseconds (us). +| 3:6 | PERF_DOMAIN_NAME | uint8[16] | Performance domain name, a NULL-terminated ASCII string up to 16-bytes. |=== ==== Service: *GET_PERF_DOMAIN_LEVELS* -This service provides a list of the available Performance levels or also called 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 utilizing this information, the OS can choose the optimal +This service provides a list of the available performance levels or also called +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 utilizing this information, the OS can choose the optimal performance level for the system workload and power constraints. ```c @@ -233,9 +287,18 @@ loop: ``` -The pseudocode above demonstrates the process for retrieving the level information for a specific performance domain. First, the number of performance levels is determined by checking the FLAGS[28:21] parameter returned by the GET_PERF_DOMAIN_ATTRIBUTES service. - -Total words required for the number of performance levels according to the format in one message cannot exceed the total words available in one message DATA field. If they exceed then PuC will return the number of levels which can be accommodated in one message and set the REMAINING field accordingly. AP, when REMAINING field is not 0 must call this service again with appropriate PERF_LEVEL_INDEX set to get the remaining levels. It's possible that multiple service calls may be required to get all the levels. +The pseudocode above demonstrates the process for retrieving the level +information for a specific performance domain. First, the number of +performance levels is determined by checking the FLAGS[28:21] parameter +returned by the GET_PERF_DOMAIN_ATTRIBUTES service. + +Total words required for the number of performance levels according to the +format in one message cannot exceed the total words available in one message +DATA field. If they exceed then PuC will return the number of levels which +can be accommodated in one message and set the REMAINING field accordingly. +AP, when REMAINING field is not 0 must call this service again with appropriate +PERF_LEVEL_INDEX set to get the remaining levels. It's possible that multiple +service calls may be required to get all the levels. [#table_perf_getdomainlevels_request_data] .Request Data @@ -267,7 +330,7 @@ First index starts from zero. | 2 | REMAINING | uint32 | Remaining number of levels. | 3 | RETURNED | uint32 | Number of levels returned. Each level compromises of three 32-bit words. -| 4 | LEVEL[0] | uint32[3] | Performance Level +| 4 | LEVEL[0] | uint32[3] | Performance level [cols="1,5"] !=== ! *Word* ! *Description* @@ -276,10 +339,10 @@ OPP table. ! 1 ! Power Cost in microwatt (uW). This is an optional parameter. Set to value of zero to indicate that power cost is not returned by the platform. -! 2 ! Transition latency in microsecond(us). +! 2 ! Transition latency, in microseconds (us). !=== -| 7 | LEVEL[1] | uint32[3] | Performance Level -| ... | LEVEL[N-1] | uint32[3] | Performance Level +| 7 | LEVEL[1] | uint32[3] | Performance level +| ... | LEVEL[N-1] | uint32[3] | Performance level |=== @@ -371,8 +434,8 @@ performance domain in the system. ! RPMI_ERROR_NOT_FOUND ! Performance domain not found. !=== - Other errors <> -| 1 | MAX_PERF_LEVEL | uint32 | Max allowed performance level. -| 2 | MIN_PERF_LEVEL | uint32 | Min allowed performance level. +| 1 | MAX_PERF_LEVEL | uint32 | Maximum allowed performance level. +| 2 | MIN_PERF_LEVEL | uint32 | Minimum allowed performance level. |=== @@ -386,8 +449,8 @@ performance domain in the system. |=== | Word | Name | Type | Description | 0 | DOMAIN_ID | uint32 | Performance Domain ID -| 1 | MAX_PERF_LEVEL | uint32 | Max allowed performance level -| 1 | MIN_PERF_LEVEL | uint32 | Min allowed performance level +| 1 | MAX_PERF_LEVEL | uint32 | Maximum allowed performance level +| 1 | MIN_PERF_LEVEL | uint32 | Minimum allowed performance level |=== [#table_perf_setlimit_response_data] @@ -411,16 +474,16 @@ performance level. |=== -==== Service: *GET_PERF_DOMAIN_FAST_CHANNEL_ADDR* -This service allows clients to query attributes of the fast channel for the specific performance domain and the specific function. +==== Service: *GET_PERF_FAST_CHANNEL_ATTRIBUTES* +This service allows clients to query attributes of the Fast-channel for a specific performance domain and performance service. [#table_perf_getfastchanaddr_request_data] .Request Data [cols="1, 3, 1, 7", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Performance domain ID -| 1 | SERVICE_ID | uint32 | Performance service ID, see service ID in <> +| 0 | DOMAIN_ID | uint32 | Performance Domain ID +| 1 | SERVICE_ID | uint32 | Performance Service ID, see service ID in <> |=== [#table_perf_getfastchanaddr_response_data] @@ -434,7 +497,7 @@ This service allows clients to query attributes of the fast channel for the spec ! *Error Code* ! *Description* ! RPMI_SUCCESS ! Service completed successfully. ! RPMI_ERROR_NOT_FOUND ! Performance domain not found -! RPMI_ERROR_NOT_SUPPORTED ! Fast channel not implemented +! RPMI_ERROR_NOT_SUPPORTED ! Fast-channel not implemented !=== - Other errors <> | 1 | FLAGS | uint32 | @@ -442,7 +505,8 @@ This service allows clients to query attributes of the fast channel for the spec !=== ! *Bits* ! *Description* ! [31:3] ! _Reserved_ -! [2:1] ! Doorbell Register Width +! [2:1] ! Doorbell register width. This field is unused if +doorbell is not supported. 0b00: 8 bits 0b01: 16 bits @@ -455,15 +519,19 @@ This service allows clients to query attributes of the fast channel for the spec !=== | 2 |PHYS_ADDR_LOW | uint32 | Lower `32 bits` of physical address | 3 |PHYS_ADDR_HIGH | uint32 | Upper `32 bits` of physical address -| 4 |DB_ADDR_LOW | uint32 | Lower `32 bits` of doorbell address -| 5 |DB_ADDR_HIGH | uint32 | Upper `32 bits` of doorbell address -| 6 |DB_ID_LOW | uint32 | Lower `32 bits` of doorbell ID -| 7 |DB_ID_HIGH | uint32 | Upper `32 bits` of doorbell ID +| 4 |DB_ADDR_LOW | uint32 | Lower `32 bits` of doorbell address. This field is unused if +doorbell is not supported. +| 5 |DB_ADDR_HIGH | uint32 | Upper `32 bits` of doorbell address. This field is unused if +doorbell is not supported. +| 6 |DB_ID_LOW | uint32 | Lower `32 bits` of doorbell ID. This field is unused if +doorbell is not supported. +| 7 |DB_ID_HIGH | uint32 | Upper `32 bits` of doorbell ID. This field is unused if +doorbell is not supported. | 8 |DB_PRESERVED_LOW | uint32 | A lower `32 bits` doorbell preserved -mask to apply for this service before ring the doorbell. This field is unused -if FLAGS[0] is zero. +mask to apply for this service before ring the doorbell. This field is unused if +doorbell is not supported. | 9 |DB_PRESERVED_HIGH | uint32 | An upper `32 bits` doorbell preserved mask to apply for this service before ring the doorbell. This field is only -valid if the doorbell register width is 64 bits. This field is unused if -FLAGS[0] is zero. -|=== \ No newline at end of file +valid if the doorbell register width is 64 bits. This field is unused if +doorbell is not supported. +|=== diff --git a/src/srvgrp-voltage.adoc b/src/srvgrp-voltage.adoc index fa18382..d878218 100644 --- a/src/srvgrp-voltage.adoc +++ b/src/srvgrp-voltage.adoc @@ -1,9 +1,11 @@ === Service Group - *VOLTAGE* (servicegroup_id: 0x00006) -The complete system can be classified into multiple domains for voltage control. Each domain is the logical group of one or more devices that have a single -voltage source. The action corresponding to the messages in this group controls -the voltage source which affects the device or the group of devices together -since those devices share the same voltage source. Each domain is identified by domain_id which is a `32 bits` integer starting from `0`. +The system can be classified into multiple domains for voltage control. +Each domain is the logical grouping of one or more devices powered by a single +voltage source. Actions associated with messages within each domain control the +voltage source, thereby influencing either the individual device or the collective +group of devices sharing the same voltage source. +Each domain is identified by `DOMAIN_ID` which is a `32 bits` integer starting from `0`. Below table lists the services in this group: [#table_voltage_services] @@ -25,9 +27,10 @@ Below table lists the services in this group: This service group does not support any event for notification. ==== Service: *ENABLE_NOTIFICATION* -This service allows AP to subscribe to voltage service group notifications. -Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented -and AP has subscribed to these. Events supported are described above in Voltage Notifications. +This service allows the AP to subscribe to voltage service group notifications. +The platform can optionally support notifications of events which might occur in the platform. +The PuC can send these notification messages to the AP if they are implemented +and the AP has subscribed to them. The supported events are described above in Voltage Notifications. [#table_voltage_ennotification_request_data] @@ -56,7 +59,7 @@ notification. |=== ==== Service: *GET_NUM_DOMAINS* -Request for number of domains available in the system. +Request for the number of voltage domains available in the system. [#table_voltage_getnumdomains_request_data] .Request Data @@ -75,19 +78,19 @@ Request for number of domains available in the system. as NUM_DOMAINS. !=== - Other errors <> -| 1 | NUM_DOMAINS | uint32 | Number of Domains +| 1 | NUM_DOMAINS | uint32 | Number of voltage domains |=== ==== Service: *GET_DOMAIN_ATTRIBUTES* -Each domain may have supported multiple voltage levels which are allowed by the -domain to operate. This message for each domain returns a domain name which is a -null terminated ASCII string of `16 byte`. -Number of levels represents the total number of voltage levels supported by a -voltage domain. Transition latency is the max time taken for voltage to -stabilize when changed on the regulator. Voltage levels depending on the -hardware can be of different formats and this service currently supports Simple -Linear, Multi-Linear and Discrete range. More voltage formats can be supported -in future if required. +Each domain may support multiple voltage levels, which are permitted by the domain +for operation. For each domain, this message returns a domain name, represented as +a NULL-terminated ASCII string of 16 bytes. 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 Simple-linear, Multi-linear, and Discrete range +formats. Additional voltage formats can be accommodated in the future if required. + [#table_voltage_getdomainattrs_request_data] .Request Data [cols="1, 3, 1, 7", width=100%, align="center", options="header"] @@ -115,13 +118,11 @@ in future if required. ! *Bits* ! *Description* ! [31:30] ! VOLTAGE_FORMAT - 0b00: Fixed Voltage + 0b00: Fixed voltage - 0b01: Simple Linear Range containing single triplet - (min_uV, max_uV, step_uV). + 0b01: Simple-linear range containing single triplet (min_uV, max_uV, step_uV). - 0b10: Multi-Linear range containing multiple linear ranges of type `0x1` - where each range contains (min_uV, min_sel, max_sel, step_uV). + 0b10: Multi-linear range containing multiple linear ranges of type `0x1` where each range contains (min_uV, min_sel, max_sel, step_uV). 0b11: Discrete range. ! [29:1] ! _Reserved_ @@ -129,39 +130,40 @@ in future if required. 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 supported by domain. Some values are dependent on the VOLTAGE_FORMAT. [cols="2,5a"] !=== ! *Value* ! *Description* -! 1 ! VOLTAGE_FORMAT=`0x0` -! 3 ! VOLTAGE_FORMAT=`0x1` -! N ! VOLTAGE_FORMAT=`0x2` or `0x3`. Based on the format here -each item can be a single voltage value or tuple of values. Check VOLTAGE_FORMAT +! 1 ! When VOLTAGE_FORMAT=`0x0` +! 3 ! When VOLTAGE_FORMAT=`0x1` +! N ! When VOLTAGE_FORMAT=`0x2` or `0x3`. Based on the format here +each item can be a single voltage value or tuple of values. Check the VOLTAGE_FORMAT field in FLAGS. !=== -| 3 | TRANSITION_LATENCY | uint32 | Transition Latency -| 4:7 | VOLTAGE_DOMAIN_NAME | uint8[16] | Voltage domain name +| 3 | TRANSITION_LATENCY | uint32 | Transition latency, in microsecond (us). +| 4:7 | VOLTAGE_DOMAIN_NAME | uint8[16] | Voltage domain name, a NULL-terminated ASCII string up to 16-bytes. |=== ==== Service: *GET_DOMAIN_LEVELS* Each domain may support multiple voltage levels which are allowed by the domain to operate. -Depending on the Power supply/Voltage Regulator the domain may support voltage -levels which can be either discrete or stepwise range. Discrete voltage range -will be in sequence starting from lower voltage value at the lowest index to -higher voltage level with increasing index. Number of voltage levels returned -depends on the format of the voltage level. Total words required for the number -levels according to the format in one message cannot exceed the total words -available in one message DATA field. If they exceed then PuC will return the -number of levels which can be accommodated in one message and set the REMAINING -field accordingly. AP, when REMAINING field is not 0 must call this service -again with appropriate VOLTAGE_LEVEL_INDEX set to get the remaining voltage -levels. It's possible that multiple service calls may be required to get all the -voltage levels. +Depending on the hardware, the voltage levels can be either discrete or stepwise range. +In a discrete voltage range, the voltages will be arranged in sequence, starting +from the lowest voltage value at the lowest index and increasing sequentially to +higher voltage levels. The number of voltage levels returned depends on the +format of the voltage level. + +The total number of words required to represent the voltage levels in one message +cannot exceed the total words available in one message DATA field. If the number +of levels exceeds this limit, the PuC will return the maximum number of levels +that can be accommodated in one message and adjust the REMAINING field accordingly. +When the REMAINING field is not zero, the AP must make subsequent service calls +with the appropriate VOLTAGE_LEVEL_INDEX set to retrieve the remaining voltage +levels. It is possible that multiple service calls may be necessary to retrieve +all the voltage levels. [#table_voltage_getdomainlevels_request_data] .Request Data @@ -189,23 +191,23 @@ voltage levels. | 1 | FLAGS | uint32 | _Reserved_ and must be `0`. | 2 | REMAINING | uint32 | Remaining number of levels. | 3 | RETURNED | uint32 | Number of levels returned in this request. -| 4 | VOLTAGE[0] | uint32 | Voltage array where each entry in the -array is a voltage level in microvolts(uV). +| 4 | VOLTAGE[0] | int32 | Voltage array where each entry in the +array is a voltage level in microvolts (uV). N is specified by the GET_DOMAIN_ATTRIBUTES.NUM_LEVELS. Voltage represented in microvolt (uV). -If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `0`, VOLTAGE[0] +If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `0` (Fixed voltage), VOLTAGE[0] contains a fixed voltage level in the array. + `VOLTAGE[0]: volt_uV` -If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `1`, it means that +If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `1` (Simple-linear), it means that the voltage array contains three entries as below: + `VOLTAGE[0]: min_uV + VOLTAGE[1]: max_uV + VOLTAGE[2]: step_uV` -If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `2`, it indicates +If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to `2` (Multi-linear), it indicates that the voltage array contains multiple groups of four entries. Each group represent a linear voltage range and consists of the following entries: + `VOLTAGE[0] = min_uV + @@ -213,9 +215,9 @@ VOLTAGE[1] = min_sel + VOLTAGE[2] = max_sel + VOLTAGE[3] = step_uV` -If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to 3, it means that +If the bits in GET_DOMAIN_ATTRIBUTES.FLAGS[31:30] are set to 3 (Discrete), it means that the entry array contains discrete voltage levels listed in ascending numeric -order(_Low index represents minimum voltage level, and high index represents +order (_Low index represents minimum voltage level, and high index represents maximum voltage level supported_). + `VOLTAGE[0]: Voltage0 + VOLTAGE[1]: Voltage1 + @@ -226,8 +228,8 @@ VOLTAGE[N - 1]: Voltage(N – 1)` |=== ==== Service: *SET_DOMAIN_CONFIG* -Set voltage config message enable or disable any domain. Enabling the voltage -means applying the domain with the voltage level to operate normally. AP can +Set voltage config message enable or disable any voltage domain. Enabling the voltage +means applying the domain with the voltage level to operate normally. The AP can enable the voltage to any domain without knowing the actual voltage levels. Disabling the voltage level means disabling the voltage supply to the domain. @@ -304,7 +306,7 @@ currently set. ==== Service: *SET_DOMAIN_LEVEL* -Set the voltage level in microvolts(uV) of a voltage domain +Set the voltage level in microvolts (uV) of a voltage domain. [#table_voltage_setdomainlevel_request_data] .Request Data @@ -312,7 +314,7 @@ Set the voltage level in microvolts(uV) of a voltage domain |=== | Word | Name | Type | Description | 0 | DOMAIN_ID | uint32 | Voltage Domain ID -| 1 | VOLTAGE_LEVEL | int32 | Voltage level +| 1 | VOLTAGE_LEVEL | int32 | Voltage level, in microvolts (uV). |=== [#table_voltage_setdomainlevel_response_data] @@ -334,7 +336,7 @@ voltage domain. ==== Service: *GET_DOMAIN_LEVEL* -Get the current voltage level in microvolts(uV) of a voltage domain. +Get the current voltage level in microvolts (uV) of a voltage domain. [#table_voltage_getdomainlevel_request_data] .Request Data @@ -357,5 +359,5 @@ Get the current voltage level in microvolts(uV) of a voltage domain. ! RPMI_ERROR_NOT_FOUND ! Voltage DOMAIN_ID not found. !=== - Other errors <> -| 1 | VOLTAGE_LEVEL | int32 | Voltage Level -|=== \ No newline at end of file +| 1 | VOLTAGE_LEVEL | int32 | Voltage level, in microvolts (uV). +|=== diff --git a/src/transport.adoc b/src/transport.adoc index a234068..4ae5562 100644 --- a/src/transport.adoc +++ b/src/transport.adoc @@ -58,7 +58,7 @@ transport discovery phase. The doorbell interrupt from APs to PuC is optional for RPMI shared memory transport and if available then it MUST be supported through a read-modify-write sequence to a memory mapped register. This read-modify-write mechanism can be -discovered by APs via DT or ACPI using properties such as register physical +discovered by APs via DT cite:[DT] or ACPI cite:[ACPI] using properties such as register physical address, mask, and value. The doorbell interrupt from the PuC to the APs for RPMI shared memory transport is @@ -67,7 +67,7 @@ platform specific. The subsequent sections describe the layout and attributes of shared memory which should be consistent across both Application Processor and Platform Microcontroller. These attributes can be static for the Platform Microcontroller -and discoverable via DT or ACPI for the Application Processor. +and discoverable via DT cite:[DT] or ACPI cite:[ACPI] for the Application Processor. ==== Attributes of Shared Memory