From e9c7ecccc27516df64173ad4eeba105325c9d648 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sat, 7 Sep 2024 22:54:44 +0800 Subject: [PATCH 01/11] Fix grammar Signed-off-by: Ley Foon Tan --- src/message-protocol.adoc | 14 +++++++------- src/srvgrp-base.adoc | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index 24013d2..d822ca6 100644 --- a/src/message-protocol.adoc +++ b/src/message-protocol.adoc @@ -11,7 +11,7 @@ endif::rootpath[] == Message Protocol The RPMI protocol defines the message format and different messages -for system management and control tasks. A message is called a Service if its +for system management and control tasks. A message is called a Service if it is designated to perform a specific task. Multiple similar services are grouped logically into a Service Group like Clock, Voltage, Performance, etc. A service call results in a request message being sent on a transport @@ -21,7 +21,7 @@ microcontroller after processing and servicing the request can send the response message with status and additional data. === Message Types -Three categories of message are supported - REQUEST, ACKNOWLEDGEMENT +Three categories of message are supported: REQUEST, ACKNOWLEDGEMENT and NOTIFICATION. A Request message represents a specific control and management task which needs @@ -63,7 +63,7 @@ the system. ! Request without Acknowledgement. !=== -| Messages for requesting a service from platform microcontroller. +| Messages for requesting a service from the platform microcontroller. | ACKNOWLEDGEMENT | _Not applicable_ @@ -76,9 +76,9 @@ application processor for sending events. |=== === Message Format -Each message regardless of its type consists of two parts - message header +Each message regardless of its type consists of two parts: message header and data. The size of the message header is fixed, but the size of the data -is implementation-defined, based on the layout of the transport queues. All the +is implementation-defined, based on the layout of the transport queues. All messages must follow the byte order as defined by the RPMI transport. .RPMI Message Format @@ -143,7 +143,7 @@ Each message is given a unique identity in an RPMI context by its header. ! [23:16] ! SERVICE_ID + -8-bit identifier representing a service(message). This identifier is +8-bit identifier representing a service (message). This identifier is unique within a given service group. ! [15:0] @@ -278,7 +278,7 @@ packing of multiple events and its implementation defined. === Return Error Codes The following table lists all the error codes that can be returned by a service in the `STATUS` field of the acknowledgement message. The `STATUS` field returns -`0` on success otherwise a negative 32-bit integer to indicate a error +`0` on success, otherwise a negative 32-bit integer to indicate an error condition. [#table_error_codes] diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index fb35939..5c151b4 100644 --- a/src/srvgrp-base.adoc +++ b/src/srvgrp-base.adoc @@ -506,7 +506,7 @@ microcontroller can use as a doorbell to the application processor. The application processor must first discover the MSI support via `BASE_GET_ATTRIBUTES` service. -If the MSI support is not present then this this service will be ignored with +If the MSI support is not present then this service will be ignored with appropriate `STATUS` returned. The platform microcontroller will enable MSI only if support is present and From a1d3e43b4a8459c78f4fbc4134ab77161b4c8602 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sat, 7 Sep 2024 22:55:06 +0800 Subject: [PATCH 02/11] transport: Change to "Fast-channel" Signed-off-by: Ley Foon Tan --- src/transport.adoc | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/src/transport.adoc b/src/transport.adoc index 3d19486..d5b1498 100644 --- a/src/transport.adoc +++ b/src/transport.adoc @@ -17,9 +17,9 @@ RPMI transport is the abstraction over a physical medium used to send and receive messages between the application processor and the platform microcontroller. -An RPMI transport instance provides bi-directional communication channels between -a RISC-V privilege level a application processors and a platform -microcontroller. A application processors can have multiple RPMI transport +An RPMI transport instance provides bi-directional communication channels +between a RISC-V privilege-level of an application processor and a platform +microcontroller. An application processor can have multiple RPMI transport instances with a platform microcontroller. Similarly, a system can have multiple platform microcontrollers each with its own RPMI transport instance to a set of application processors. The <> shows different RPMI @@ -231,20 +231,21 @@ trigger the interrupt. If the doorbell interrupt is a MSI then a RPMI message defined in the `BASE` service group can be used by the application processor to configure the MSI at the platform microcontroller side. -=== Fast Channels -Fast channels are shared memory based transport required for use cases -that require lower latency and faster processing of commands. A Fast channel -layout and message format are specific to service groups and not all service -group needs to support these. A service group that supports fast channels may -only enable some services to be used over fast channels. +=== Fast-channels +Fast-channels are shared memory based channel per application processor +required for use cases that require lower latency and faster processing +of commands. A Fast-channel layout and message format are specific to +service groups and not all service group needs to support these. A service +group that supports fast-channels may only enable some services to be used +over fast-channels. NOTE: To avoid the caching side-effects, the platform can configure the shared memory as IO or non-cacheable memory for both the application processor and the platform microcontroller. -If the support for fast channels is defined by a service group, its implementation +If the support for fast-channels is defined by a service group, its implementation and attributes like physical memory address are discovered dynamically through service defined by that particular service group. -Fast channels may support doorbells but its optional. Attributes of doorbell +Fast-channels may support doorbells but its optional. Attributes of doorbell if supported are discovered dynamically via a service defined by the service group. From 5f994bb207acc88dd3b584908fd6b63a8ce5a5c0 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sat, 7 Sep 2024 23:07:41 +0800 Subject: [PATCH 03/11] perf: Update Reserved must be 0 Signed-off-by: Ley Foon Tan --- src/srvgrp-performance.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/srvgrp-performance.adoc b/src/srvgrp-performance.adoc index 520d20d..5648f61 100644 --- a/src/srvgrp-performance.adoc +++ b/src/srvgrp-performance.adoc @@ -839,7 +839,7 @@ specific performance domain and performance service. ! Description ! [31:3] -! _Reserved_ +! _Reserved_ and must be `0`. ! [2:1] ! Doorbell register width. This field is unused if doorbell is not supported. From b52e0808926c505bb77b7381d44be968c7af0623 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sat, 7 Sep 2024 23:10:28 +0800 Subject: [PATCH 04/11] hsm: Fix server group name HART_STATE_MANAGEMENT Signed-off-by: Ley Foon Tan --- src/srvgrp-hart-state-management.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/srvgrp-hart-state-management.adoc b/src/srvgrp-hart-state-management.adoc index 303e0a8..51a4c9c 100644 --- a/src/srvgrp-hart-state-management.adoc +++ b/src/srvgrp-hart-state-management.adoc @@ -21,7 +21,7 @@ the entire hierarchical group in which the hart is located, requiring coordinati for the power state change. RPMI supports the coordination mechanisms and hart power states defined by the RISC-V SBI Specification cite:[SBI]. -The following table lists the services in the HSM service group: +The following table lists the services in the HART_STATE_MANAGEMENT service group: [#table_hsm_services] .HART_STATE_MANAGEMENT Services From 02ee98f4df15bfc0f99c62d8474a4ef7dcdf3cde Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sat, 7 Sep 2024 23:18:46 +0800 Subject: [PATCH 05/11] hsm: Add option "header" Signed-off-by: Ley Foon Tan --- src/srvgrp-hart-state-management.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/srvgrp-hart-state-management.adoc b/src/srvgrp-hart-state-management.adoc index 51a4c9c..7324bb3 100644 --- a/src/srvgrp-hart-state-management.adoc +++ b/src/srvgrp-hart-state-management.adoc @@ -234,7 +234,7 @@ may need to call this service again with the appropriate `START_INDEX` until the | STATUS | int32 | Return error code -[cols="6,5a"] +[cols="6,5a", options="header"] !=== ! Error Code ! Description @@ -307,7 +307,7 @@ items. | STATUS | int32 | Return error code -[cols="7,5a"] +[cols="7,5a", options="header"] !=== ! Error Code ! Description @@ -529,7 +529,7 @@ Once the hart is stopped, it can only be restarted by explicitly invoking the | STATUS | int32 | Return error code -[cols="6,5a"] +[cols="6,5a", options="header"] !=== ! Error Code ! Description @@ -609,7 +609,7 @@ _Only used for non-retentive suspend types._ | STATUS | int32 | Return error code -[cols="6,5a"] +[cols="6,5a", options="header"] !=== ! Error Code ! Description From 6526aa9457b2a7762f0548973cb93fc9d42a6e90 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:19:51 +0800 Subject: [PATCH 06/11] voltage: Move voltage format description to format section Signed-off-by: Ley Foon Tan --- src/srvgrp-voltage.adoc | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/srvgrp-voltage.adoc b/src/srvgrp-voltage.adoc index 5eeb132..cca8f48 100644 --- a/src/srvgrp-voltage.adoc +++ b/src/srvgrp-voltage.adoc @@ -67,7 +67,8 @@ group. The voltage levels are represented as a group. * Fixed Voltage Format -The following table shows the structure of the fixed voltage format. +A constant voltage level. The following table shows the structure of the fixed +voltage format. .Fixed Voltage Structure [cols="1,2,5" width=100%, align="center", options="header"] @@ -83,7 +84,8 @@ The following table shows the structure of the fixed voltage format. * Simple-Linear Format -The following table shows the structure of the simple-linear voltage format. +A linear range of voltage levels with a constant step size. The following table +shows the structure of the simple-linear voltage format. [cols="1,2,5" width=100%, align="center", options="header"] |=== @@ -106,7 +108,8 @@ The following table shows the structure of the simple-linear voltage format. * Multi-Linear Format -The following table shows the structure of the multi-linear voltage 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"] |=== @@ -133,6 +136,8 @@ The following table shows the structure of the multi-linear 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. [cols="1,2,5" width=100%, align="center", options="header"] @@ -356,11 +361,8 @@ supported by the domain. Get the voltage levels with `VOLT_GET_SUPPORTED_LEVELS` ==== Service: VOLT_GET_SUPPORTED_LEVELS (SERVICE_ID: 0x04) Each domain may support multiple voltage levels which are allowed by the domain -to operate. 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. +to operate. 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 From da90ec5d715c04a1f31ab2d811978ff7290414a2 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:22:15 +0800 Subject: [PATCH 07/11] perf: Improve performance chapter - Fix EventID to 1 byte - Fix typo and grammar - Update description for RPMI_ERR_DENIED Signed-off-by: Ley Foon Tan --- src/srvgrp-performance.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/srvgrp-performance.adoc b/src/srvgrp-performance.adoc index 5648f61..c818699 100644 --- a/src/srvgrp-performance.adoc +++ b/src/srvgrp-performance.adoc @@ -12,7 +12,7 @@ endif::rootpath[] === Service Group - PERFORMANCE (SERVICEGROUP_ID: 0x0009) 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 tranditional performance control mechanisms, where the OS is +domain. Unlike traditional performance control mechanisms, where the OS is responsible to 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 @@ -140,7 +140,7 @@ inform clients in the system about changes in the performance domain. | Event Data | Description -| 0x001 +| 0x01 | PERF_POWER_CHANGE | [cols="2,2,5", options="header"] @@ -160,7 +160,7 @@ inform clients in the system about changes in the performance domain. !=== | Performance power changed notification. -| 0x002 +| 0x02 | PERF_LIMIT_CHANGE | [cols="2,2,5", options="header"] @@ -184,7 +184,7 @@ inform clients in the system about changes in the performance domain. !=== | Performance limit changed notification. -| 0x003 +| 0x03 | PERF_LEVEL_CHANGE | [cols="2,2,5", options="header"] @@ -637,7 +637,7 @@ performance domain in the system. ! `DOMAIN_ID` or `LEVEL` is invalid. ! RPMI_ERR_DENIED -! The client does not have permission to change the performance level. +! Denied due to no permission. ! RPMI_ERR_HW_FAULT ! Operation failed due to hardware error. @@ -764,7 +764,7 @@ performance domain in the system. ! Performance limit change is not allowed. ! RPMI_ERR_DENIED -! Client does not have permission to change the performance level. +! Denied due to no permission. ! RPMI_ERR_HW_FAULT ! Operation failed due to hardware error. @@ -824,7 +824,7 @@ specific performance domain and performance service. ! `DOMAIN_ID` is invalid. ! RPMI_ERR_NOT_SUPPORTED -! Fast-channel not implemented. +! Fast-channel is not implemented. !=== - Other errors <> From 620e0a107871d8801019beb4f228a4005e2c5a8e Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:22:57 +0800 Subject: [PATCH 08/11] ras: Use RAS_AGENT service group name Signed-off-by: Ley Foon Tan --- src/srvgrp-ras-agent.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/srvgrp-ras-agent.adoc b/src/srvgrp-ras-agent.adoc index f86077b..6868ed3 100644 --- a/src/srvgrp-ras-agent.adoc +++ b/src/srvgrp-ras-agent.adoc @@ -10,7 +10,7 @@ ifndef::rootpath[] endif::rootpath[] === Service Group - RAS_AGENT (SERVICEGROUP_ID: 0x000B) -The RAS agent service group provides services to enumerate various error +The RAS_AGENT service group provides services to enumerate various error sources in a system and to get their descriptors. These services are provided by RAS Agent. From e3b09e2275b0885dd3aa9cd51f5c597d0c380f4e Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:24:35 +0800 Subject: [PATCH 09/11] devicepower: Update description for RPMI_ERR_DENIED - Update description for RPMI_ERR_DENIED - Remove RPMI_ERR_DENIED error for DPWR_GET_STATE. Signed-off-by: Ley Foon Tan --- src/srvgrp-device-power.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/srvgrp-device-power.adoc b/src/srvgrp-device-power.adoc index 0c46cfe..6ef16fc 100644 --- a/src/srvgrp-device-power.adoc +++ b/src/srvgrp-device-power.adoc @@ -331,7 +331,7 @@ for more details. ! `DOMAIN_ID` or `POWER_STATE` is invalid. ! RPMI_ERR_DENIED -! Client does not have permissions to change the device power domain power state. +! Denied due to no permission. ! RPMI_ERR_HW_FAULT ! Failed due to hardware error. @@ -382,8 +382,6 @@ This service is used to get the current power state of a device power domain. ! RPMI_ERR_INVALID_PARAM ! `DOMAIN_ID` is invalid. -! RPMI_ERR_DENIED -! Client does not have permissions to change the device power domain power state. !=== - Other errors <> From 779b28f2a9cc5a5110df2a6da67cfa3af915c930 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:25:29 +0800 Subject: [PATCH 10/11] clock: Move clock format description to Clock Format section Signed-off-by: Ley Foon Tan --- src/srvgrp-clock.adoc | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/src/srvgrp-clock.adoc b/src/srvgrp-clock.adoc index a5e60b1..24a4a21 100644 --- a/src/srvgrp-clock.adoc +++ b/src/srvgrp-clock.adoc @@ -78,7 +78,9 @@ as `(clock_rate_low, clock_rate_high)` and packed in the same order where * Discrete Clock Format -The following table shows the structure of the Discrete clock format. +A set of discrete clock rate arranged in a sequence, starting from the +lowest value at the lowest index and increasing sequentially to higher clock +rate. The following table shows the structure of the Discrete clock format. .Discrete Clock Format Structure [cols="1,2,5" width=100%, align="center", options="header"] @@ -98,6 +100,7 @@ The following table shows the structure of the Discrete clock format. * Linear Clock Format +A linear range of clock rate with a constant step size. The following table shows the structure of the Linear clock format. .Linear Clock Format Structure @@ -193,7 +196,7 @@ described in <>. ==== Service: CLK_GET_NUM_CLOCKS (SERVICE_ID: 0x02) 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`. +called `CLOCK_ID`. `CLOCK_ID` are sequential starting from `0`. [#table_clock_getnumclocks_request_data] .Request Data @@ -238,14 +241,9 @@ 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 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 [cols="1, 3, 1, 7", width=100%, align="center", options="header"] @@ -304,8 +302,8 @@ the future, as needed. Refer to <> for more details. ---- -0b00: Discrete Format -0b01: Linear Range +0b00: Discrete format +0b01: Linear format ---- !=== @@ -332,12 +330,6 @@ domain to operate. Message can also pass the `CLOCK_RATE_INDEX` which is the ind 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 -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 the platform microcontroller will return the number of From 3a19508a078cf777973d5605958f7d0120fc2f46 Mon Sep 17 00:00:00 2001 From: Ley Foon Tan Date: Sun, 8 Sep 2024 00:26:43 +0800 Subject: [PATCH 11/11] base: Update Event ID to 1 byte Event ID is only one byte. Signed-off-by: Ley Foon Tan --- src/srvgrp-base.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index 5c151b4..87a408e 100644 --- a/src/srvgrp-base.adoc +++ b/src/srvgrp-base.adoc @@ -92,7 +92,7 @@ listed in the below table. | Event Data | Description -| 0x001 +| 0x01 | REQUEST_HANDLE_ERROR | NA | This event indicates that the the platform microcontroller is unable to