From f4b8e13e5b239cdab8d1f7994e7006194d9f6852 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:22:57 +0800 Subject: [PATCH 01/10] base: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-base.adoc | 124 +++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 70 deletions(-) diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index b7c60a7..7de6577 100644 --- a/src/srvgrp-base.adoc +++ b/src/srvgrp-base.adoc @@ -80,9 +80,9 @@ listed in the below table. | Event Data | Description -| 0x001 -| REQUEST_HANDLE_ERROR -| NA +| 0x001 +| REQUEST_HANDLE_ERROR +| NA | This event indicates that the the platform microcontroller is unable to serve the message requests. |=== @@ -104,7 +104,7 @@ in table <>. | Type | Description -| 0 +| 0 | EVENT_ID | uint32 | The event to be subscribed for notification. @@ -119,7 +119,7 @@ in table <>. | Type | Description -| 0 +| 0 | STATUS | int32 | Return error code @@ -135,7 +135,7 @@ in table <>. ! RPMI_ERR_INVALID_PARAM ! `EVENT_ID` is invalid. -! RPMI_ERR_NOT_SUPPORTED +! RPMI_ERR_NOT_SUPPORTED ! Notifications not supported. !=== - Other errors <> @@ -143,21 +143,18 @@ in table <>. ==== Service: BASE_GET_IMPLEMENTATION_VERSION (SERVICE_ID: 0x02) This service is used to get the RPMI implementation version of the platform -microcontroller. The version returned is a `32-bit` composite number containing +microcontroller. The version returned is a 32-bit composite number containing the `MAJOR` and `MINOR` numbers. [#table_base_getimplversion_request_data] .Request Data -[cols="1", width=100%, align="center", options="header"] -|=== -| NA -|=== +- NA [#table_base_getimplversion_response_data] .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word +| Word | Name | Type | Description @@ -172,7 +169,7 @@ the `MAJOR` and `MINOR` numbers. ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! RPMI implementation version returned successfully. !=== - Other errors <> @@ -180,7 +177,7 @@ the `MAJOR` and `MINOR` numbers. | 1 | IMPL_VERSION | uint32 -| Implementation Version +| Implementation version [cols="2,5a", options="header"] !=== @@ -188,25 +185,21 @@ the `MAJOR` and `MINOR` numbers. ! Description ! [31:16] -! `MAJOR` Number +! `MAJOR` number ! [15:0] -! `MINOR` Number +! `MINOR` number !=== |=== ==== Service: BASE_GET_IMPLEMENTATION_ID (SERVICE_ID: 0x03) -This service is used to get a `32-bit` RPMI implementation ID assigned to the +This service is used to get a 32-bit RPMI implementation ID assigned to the software which implements the RPMI specification. Every implementation ID is unique and listed in the table <> [#table_base_getimplid_request_data] .Request Data -[cols="1", width=100%, align="center", options="header"] -|=== -| NA -|=== - +- NA [#table_base_getimplid_response_data] .Response Data @@ -227,7 +220,7 @@ unique and listed in the table <> ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! RPMI implementation ID returned successfully. !=== - Other errors <> @@ -240,15 +233,12 @@ unique and listed in the table <> ==== Service: BASE_GET_SPEC_VERSION (SERVICE_ID: 0x04) This service is used to get the implemented RPMI specification version. The -version returned is a `32-bit` composite number containing the `MAJOR` and +version returned is a 32-bit composite number containing the `MAJOR` and `MINOR` numbers. [#table_base_getspecversion_request_data] .Request Data -[cols="1", width=100%, align="center", options="header"] -|=== -| NA -|=== +- NA [#table_base_getspecversion_response_data] .Response Data @@ -277,7 +267,7 @@ version returned is a `32-bit` composite number containing the `MAJOR` and | 1 | SPEC_VERSION | uint32 -| RPMI Specification Version +| RPMI specification version [cols="2,5a", options="header"] !=== @@ -285,10 +275,10 @@ version returned is a `32-bit` composite number containing the `MAJOR` and ! Description ! [31:16] -! `MAJOR` Number +! `MAJOR` number ! [15:0] -! `MINOR` Number +! `MINOR` number !=== |=== @@ -297,10 +287,7 @@ This service is used to get addition platform information if available. [#table_base_getplatinfo_request_data] .Request Data -[cols="1", width=100%, align="center", options="header"] -|=== -| NA -|=== +- NA [#table_base_getplatinfo_response_data] .Response Data @@ -321,7 +308,7 @@ This service is used to get addition platform information if available. ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Platform information returned successfully. !=== - Other errors <> @@ -333,7 +320,7 @@ This service is used to get addition platform information if available. | 2 | PLATFORM_ID -| uint8[`PLATFORM_ID_LEN`] +| uint8[`PLATFORM_ID_LEN`] | Platform Identifier + Up to `PLATFORM_ID_LEN` bytes NULL terminated ASCII string. The use and interpretation of this field is implementation-defined. It can be @@ -357,25 +344,25 @@ not implemented or invalid then this service returns `0` in the | Description | 0 -| SERVICEGROUP_ID -| uint32 -| A `16-bit` ID assigned to each service group. + +| SERVICEGROUP_ID +| uint32 +| A 16-bit ID assigned to each service group. + Refer to table <> for defined service groups. + -The first `16-bit` of the `uint32` field will store the `SERVICEGROUP_ID`. +The first 16-bit of the `uint32` field will store the `SERVICEGROUP_ID`. |=== [#table_base_probesrvgrp_response_data] .Response Data [cols="1, 4, 1, 6a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="3,4a", options="header"] @@ -383,7 +370,7 @@ The first `16-bit` of the `uint32` field will store the `SERVICEGROUP_ID`. ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Service probed successfully. !=== - Other errors <> @@ -394,7 +381,7 @@ The first `16-bit` of the `uint32` field will store the `SERVICEGROUP_ID`. | Service group implementation status. 1: Implemented - 0: Not implemented. + 0: Not implemented |=== ==== Service: BASE_GET_ATTRIBUTES (SERVICE_ID: 0x07) @@ -403,10 +390,7 @@ service group. [#table_base_getbaseattrs_request_data] .Request Data -[cols="1", width=100%, align="center", options="header"] -|=== -| NA -|=== +- NA [#table_base_getbaseattrs_response_data] .Response Data @@ -419,7 +403,7 @@ service group. | 0 | STATUS -| int32 +| int32 | Return error code [cols="2,5a", options="header"] @@ -435,21 +419,21 @@ service group. | 1 | FLAGS0 | uint32 -| +| [cols="2,9a", options="header"] !=== ! Bits ! Description ! [31:2] -! _Reserved, must be initialized to_ `0`. +! _Reserved_ and must be `0`. ! [1] ! EVENT_NOTIFICATION + 0b1: Supported 0b0: Not supported - + ! [0] ! MSI + @@ -457,20 +441,20 @@ service group. 0b0: Not supported !=== -| 2 -| FLAGS1 +| 2 +| FLAGS1 | uint32 -| _Reserved, must be initialized to_ `0`. +| _Reserved_ and must be `0`. -| 3 +| 3 | FLAGS2 | uint32 -| _Reserved, must be initialized to_ `0`. +| _Reserved_ and must be `0`. -| 4 +| 4 | FLAGS3 | uint32 -| _Reserved, must be initialized to_ `0`. +| _Reserved_ and must be `0`. |=== ==== Service: BASE_SET_MSI (SERVICE_ID: 0x08) @@ -506,17 +490,17 @@ processor will take the wired interrupt. | 0 | MSI_ADDRESS_LOW | uint32 -| Lower `32 bits` of the MSI address +| Lower 32-bit of the MSI address. | 1 | MSI_ADDRESS_HIGH | uint32 -| Upper `32 bits` of the MSI address +| Upper 32-bit of the MSI address. | 2 | MSI_DATA | uint32 -| `32 bits` MSI data +| 32-bit of MSI data. |=== [#table_base_setmsi_response_data] @@ -533,15 +517,15 @@ processor will take the wired interrupt. | int32 | Return error code -[cols="7,5a", options="header"] +[cols="5,5a", options="header"] !=== ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! MSI address and data are configured successfully. -! RPMI_ERR_NOT_SUPPORTED +! RPMI_ERR_NOT_SUPPORTED ! MSI is not supported. The implementation must use `BASE_GET_ATTRIBUTES` service to discover this capability and then use this service. From 386748934e5591ff807711e6b4a141bb6982dd3f Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:23:15 +0800 Subject: [PATCH 02/10] system-reset: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-system-reset.adoc | 50 ++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/src/srvgrp-system-reset.adoc b/src/srvgrp-system-reset.adoc index 94b649c..61a82dc 100644 --- a/src/srvgrp-system-reset.adoc +++ b/src/srvgrp-system-reset.adoc @@ -36,8 +36,8 @@ Below table lists the services in this group: | Service Name | Request Type -| 0x01 -| SYSRST_ENABLE_NOTIFICATION +| 0x01 +| SYSRST_ENABLE_NOTIFICATION | NORMAL_REQUEST | 0x02 @@ -45,7 +45,7 @@ Below table lists the services in this group: | NORMAL_REQUEST | 0x03 -| SYSRST_RESET +| SYSRST_RESET | POSTED_REQUEST |=== @@ -113,7 +113,7 @@ to them. Supported events are described in <>. ==== Service: SYSRST_GET_ATTRIBUTES (SERVICE_ID: 0x02) This service is used to discover the attributes of a reset type. The attribute -flags indicates if a `RESET_TYPE` is supported or not apart from the +flags indicates if a `RESET_TYPE` is supported or not apart from the System Shutdown and System Cold Reset which are mandatory and supported by default. System Warm Reset support can be discovered with this service. @@ -121,14 +121,14 @@ default. System Warm Reset support can be discovered with this service. .Request Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| RESET_TYPE -| uint32 +| 0 +| RESET_TYPE +| uint32 | Reset type |=== @@ -136,33 +136,33 @@ default. System Warm Reset support can be discovered with this service. .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="5,5a", options="header"] !=== -! Error Code +! Error Code ! Description ! RPMI_SUCCESS ! Attributes returned successfully. ! RPMI_ERR_INVALID_PARAM -! `RESET_TYPE` is invalid +! `RESET_TYPE` is invalid. !=== - Other errors <> -| 1 -| FLAGS -| uint32 +| 1 +| FLAGS +| uint32 | `RESET_TYPE` Attributes [cols="2,5a", options="header"] @@ -170,10 +170,10 @@ default. System Warm Reset support can be discovered with this service. ! Bits ! Description -! [31:1] -! _Reserved, must be initialized to_ `0`. +! [31:1] +! _Reserved_ and must be `0`. -! [0] +! [0] ! `RESET_TYPE` support. 0b1: Supported. @@ -192,7 +192,7 @@ invalid state may result in the system entering a non-functional state. .Request Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word +| Word | Name | Type | Description From a8df5b6849f97370d3d1a5e47e47b04854fd1f2d Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:23:27 +0800 Subject: [PATCH 03/10] system-suspend: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-system-suspend.adoc | 66 +++++++++++++++++----------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/src/srvgrp-system-suspend.adoc b/src/srvgrp-system-suspend.adoc index 59c3f66..523f109 100644 --- a/src/srvgrp-system-suspend.adoc +++ b/src/srvgrp-system-suspend.adoc @@ -9,10 +9,10 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *SYSTEM_SUSPEND* (SERVICEGROUP_ID: 0x0003) +=== Service Group - SYSTEM_SUSPEND (SERVICEGROUP_ID: 0x0003) This service group defines services used to request platform microcontroller to transition the system into a suspend state, also called a sleep state. -The suspend state `SUSPEND_TO_RAM` is supported by default by the platform and +The suspend state `SUSPEND_TO_RAM` is supported by default by the platform and if the application processor requests for `SUSPEND_TO_RAM`, it's implicit for the platform microcontroller that all the application processors except the one requesting are in `STOPPED` state and necessary state saving in the RAM has @@ -62,12 +62,12 @@ to them. Supported events are described in <>. .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name +| Word +| Name | Type | Description -| 0 +| 0 | EVENT_ID | uint32 | Event to be subscribed for notification. @@ -113,8 +113,8 @@ if a `SUSPEND_TYPE` supports resume address. .Request Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name +| Word +| Name | Type | Description @@ -159,11 +159,11 @@ if a `SUSPEND_TYPE` supports resume address. [cols="2,5a", options="header"] !=== -! Bits +! Bits ! Description -! [31:2] -! _Reserved, must be initialized to_ `0`. +! [31:2] +! _Reserved_ and must be `0`. ! [1] ! Resume Address Support + If a `SUSPEND_TYPE` supports custom resume address @@ -175,7 +175,7 @@ which platform must configure for the resuming application processor. 0b1: Supported 0b0: Not supported - + !=== |=== @@ -206,42 +206,42 @@ after the `WFI` instruction. | Type | Description -| 0 -| HART_ID -| uint32 +| 0 +| HART_ID +| uint32 | Hart ID of the calling hart. -| 1 -| SUSPEND_TYPE -| uint32 -| Suspend type. +| 1 +| SUSPEND_TYPE +| uint32 +| Suspend type -| 2 -| RESUME_ADDR_LOW -| uint32 -| Lower `32 bits` address +| 2 +| RESUME_ADDR_LOW +| uint32 +| Lower 32-bit address. -| 3 -| RESUME_ADDR_HIGH -| uint32 -| Upper `32 bits` address +| 3 +| RESUME_ADDR_HIGH +| uint32 +| Upper 32-bit address. |=== [#table_syssuspend_syssuspend_response_data] .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code -[cols="6,5a", options="header"] +[cols="5,5a", options="header"] !=== ! Error Code ! Description From d5505aedd38a48b7a73f32cc5afe59bd0ebe2a66 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:23:39 +0800 Subject: [PATCH 04/10] voltage: Update for consistent description format Update for consistent description format. Signed-off-by: Joshua Yeong --- src/srvgrp-voltage.adoc | 66 ++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/src/srvgrp-voltage.adoc b/src/srvgrp-voltage.adoc index 3a4c9c5..3503c15 100644 --- a/src/srvgrp-voltage.adoc +++ b/src/srvgrp-voltage.adoc @@ -9,13 +9,13 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *VOLTAGE* (SERVICEGROUP_ID: 0x00006) +=== Service Group - VOLTAGE (SERVICEGROUP_ID: 0x00006) 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`. +Each domain is identified by `DOMAIN_ID` which is a 32-bit integer starting from `0`. *Voltage Levels Format*:: There are 4 types of voltage level formats supported in the voltage service @@ -30,15 +30,15 @@ group. The voltage levels are represented as a group. 3+| 3+| *Simple Linear Format* | *Word* | *Name* | *Description* -| 0 | min_uV | Lower boundary of voltage level (uV) -| 1 | max_uV | Upper boundary of voltage level (uV) +| 0 | min_uV | Lower boundary of voltage level (uV). +| 1 | max_uV | Upper boundary of voltage level (uV). | 2 | step_uV | Step size (uV) 3+| 3+| *Multi-Linear Format* | *Word* | *Name* | *Description* -| 0 | min_uV | Lower boundary of voltage level (uV) -| 1 | min_sel | Lowest selector for range -| 2 | max_sel | Highest selector for range +| 0 | min_uV | Lower boundary of voltage level (uV). +| 1 | min_sel | Lowest selector for range. +| 2 | max_sel | Highest selector for range. | 3 | step_uV | Step size (uV) 3+| 3+| *Discrete Format* @@ -88,7 +88,7 @@ notification. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="5,5"] !=== ! *Error Code* ! *Description* @@ -111,7 +111,7 @@ Request for the number of voltage domains available in the system. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="2,5"] !=== ! *Error Code* ! *Description* @@ -137,7 +137,7 @@ formats. Additional voltage formats can be accommodated in the future if require [cols="1, 3, 1, 7", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID |=== [#table_voltage_getdomainattrs_response_data] @@ -145,12 +145,12 @@ formats. Additional voltage formats can be accommodated in the future if require [cols="1, 3, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="5,5"] !=== ! *Error Code* ! *Description* ! RPMI_SUCCESS ! Service completed successfully. -! RPMI_ERROR_NOT_FOUND ! Voltage DOMAIN_ID not found +! RPMI_ERROR_NOT_FOUND ! Voltage DOMAIN_ID not found. !=== - Other errors <> | 1 | FLAGS | uint32 | @@ -160,12 +160,12 @@ formats. Additional voltage formats can be accommodated in the future if require ! [31:29] ! VOLTAGE_FORMAT (Refer to <>) ---- 0b000: Fixed voltage -0b001: Simple-linear. -0b010: Multi-linear. -0b011: Discrete range. -0b100 - 0b111: Reserved. +0b001: Simple-linear +0b010: Multi-linear +0b011: Discrete range +0b100 - 0b111: Reserved ---- -! [28:1] ! _Reserved_ +! [28:1] ! _Reserved_ and must be `0`. ! [0] ! ALWAYS_ON 0b0: Voltage domain can be enabled/disabled. @@ -176,8 +176,8 @@ supported by the domain. Get the voltage levels with VOLT_GET_SUPPORTED_LEVELS. [cols="2,5a"] !=== ! *Value* ! *Description* -! 1 ! Fixed voltage format only -! N ! Simple-linear, Multi-linear and Discrete +! 1 ! Fixed voltage format only. +! N ! Simple-linear, Multi-linear and Discrete. !=== | 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. @@ -206,7 +206,7 @@ calls may be necessary to retrieve all the voltage levels. [cols="1, 3, 1, 7", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID | 1 | VOLTAGE_LEVEL_INDEX | uint32 | Voltage level index |=== @@ -215,13 +215,13 @@ calls may be necessary to retrieve all the voltage levels. [cols="1, 3, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="7,5"] !=== ! *Error Code* ! *Description* ! RPMI_SUCCESS ! Service completed successfully and voltage levels returned. ! RPMI_ERROR_NOT_FOUND ! Voltage DOMAIN_ID not found. -! RPMI_ERROR_INVALID_PARAMETER ! VOLTAGE_LEVEL_INDEX is not valid +! RPMI_ERROR_INVALID_PARAMETER ! VOLTAGE_LEVEL_INDEX is not valid. !=== - Other errors <> | 1 | FLAGS | uint32 | _Reserved_ and must be `0`. @@ -245,16 +245,16 @@ processor to know the voltage level. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID | 1 | CONFIG | uint32 | Voltage domain config [cols="2,5a"] !=== ! *Bits* ! *Description* -! [31:1] ! _Reserved_ +! [31:1] ! _Reserved_ and must be `0`. ! [0] ! - 0b0: Disable voltage for domain - 0b1: Enable voltage for domain + 0b0: Disable voltage supply + 0b1: Enable voltage supply !=== |=== @@ -263,7 +263,7 @@ processor to know the voltage level. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="6,5"] !=== ! *Error Code* ! *Description* @@ -283,7 +283,7 @@ currently set. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID |=== [#table_voltage_getdomainconfig_response_data] @@ -291,7 +291,7 @@ currently set. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="5,5"] !=== ! *Error Code* ! *Description* @@ -317,7 +317,7 @@ Set the voltage level in microvolts (uV) of a voltage domain. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID | 1 | VOLTAGE_LEVEL | int32 | Voltage level, in microvolts (uV). |=== @@ -326,7 +326,7 @@ Set the voltage level in microvolts (uV) of a voltage domain. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="6,5"] !=== ! *Error Code* ! *Description* @@ -347,7 +347,7 @@ Get the current voltage level in microvolts (uV) of a voltage domain. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | DOMAIN_ID | uint32 | Voltage Domain ID +| 0 | DOMAIN_ID | uint32 | Voltage domain ID |=== [#table_voltage_getdomainlevel_response_data] @@ -355,7 +355,7 @@ Get the current voltage level in microvolts (uV) of a voltage domain. [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== | Word | Name | Type | Description -| 0 | STATUS | int32 | Return Status Code +| 0 | STATUS | int32 | Return error code [cols="5,5"] !=== ! *Error Code* ! *Description* From a8007f5cf584ec6a82e9da906542652031ece3eb Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:23:54 +0800 Subject: [PATCH 05/10] clock: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-clock.adoc | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/src/srvgrp-clock.adoc b/src/srvgrp-clock.adoc index 0d921c4..4f26181 100644 --- a/src/srvgrp-clock.adoc +++ b/src/srvgrp-clock.adoc @@ -9,7 +9,7 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *CLOCK* (SERVICEGROUP_ID: 0x00007) +=== Service Group - CLOCK (SERVICEGROUP_ID: 0x00007) 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. @@ -27,7 +27,7 @@ is designed and implementation specific. The OS can discover this topology through supported hardware description mechanisms. *Clock Rate Format*:: -Each clock rate is a array of two `32 bits` values `(uint32, uint32)` represented +Each clock rate is a array of two 32-bit 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`. @@ -38,17 +38,17 @@ as `(clock_rate_low, clock_rate_high)` and packed in the same order where |=== 3+| *Discrete Format* | *Word* | *Name* | *Description* -| 0 | rate_lower | Lower 32 bits clock rate in Hz -| 1 | rate_upper | Upper 32 bits clock rate in Hz +| 0 | rate_lower | Lower 32-bit clock rate in Hz. +| 1 | rate_upper | Upper 32-bit clock rate in Hz. 3+| 3+| *Linear Format* | *Word* | *Name* | *Description* -| 0 | min_lower | Lower 32 bits of the lowest clock rate in Hz -| 1 | min_upper | Upper 32 bits of the lowest clock rate in Hz -| 2 | max_lower | Lower 32 bits of the highest clock rate in Hz -| 3 | max_upper | Upper 32 bits of the highest clock rate in Hz -| 4 | step_lower | Lower 32 bits of the step between two successive rates in Hz -| 5 | step_upper | Upper 32 bits of the step between two successive rates in Hz +| 0 | min_lower | Lower 32-bit of the lowest clock rate in Hz. +| 1 | min_upper | Upper 32-bit of the lowest clock rate in Hz. +| 2 | max_lower | Lower 32-bit of the highest clock rate in Hz. +| 3 | max_upper | Upper 32-bit of the highest clock rate in Hz. +| 4 | step_lower | Lower 32-bit of the step between two successive rates in Hz. +| 5 | step_upper | Upper 32-bit of the step between two successive rates in Hz. |=== Below table lists the services in this group: @@ -262,7 +262,7 @@ the future, as needed. 0b01: Linear Range ---- -! [29:0] ! _Reserved_ +! [29:0] ! _Reserved_ and must be `0`. !=== | 2 | NUM_RATES @@ -292,8 +292,8 @@ 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. +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 clock rates which can be accommodated in one message and set the REMAINING field accordingly. The application processor, when REMAINING field is not `0` must @@ -401,7 +401,7 @@ Set clock config, enable or disable the clock. ! Bits ! Description -! [31:1] ! _Reserved_ +! [31:1] ! _Reserved_ and must be `0`. ! [0] ! 0b0: Disable clock @@ -526,25 +526,26 @@ Set clock rate. ! Bits ! Description -! [31:30] ! Clock rate roundup/rounddown +! [31:30] ! Clock rate round up/round down ---- 0b00: Round down 0b01: Round up -0b10: Auto. Platform autonomously choose rate closest to the requested rate. +0b10: Auto +Platform autonomously choose rate closest to the requested rate. ---- -! [29:0] ! _Reserved_ +! [29:0] ! _Reserved_ and must be `0`. !=== | 2 | CLOCK_RATE_LOW | uint32 -| Lower 32 bits of the clock rate in Hertz. +| Lower 32-bit of the clock rate in Hertz. | 3 | CLOCK_RATE_HIGH | uint32 -| Upper 32 bits of the clock rate in Hertz. +| Upper 32-bit of the clock rate in Hertz. |=== [#table_clock_setrate_response_data] @@ -625,10 +626,10 @@ Get the current clock rate value. | 1 | CLOCK_RATE_LOW | uint32 -| Lower 32 bits of the clock rate in Hertz. +| Lower 32-bit of the clock rate in Hertz. | 2 | CLOCK_RATE_HIGH | uint32 -| Upper 32 bits of the clock rate in Hertz. +| Upper 32-bit of the clock rate in Hertz. |=== From b4fab87dbff749d3db0fc98d8cc2f627fb3d4036 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:24:06 +0800 Subject: [PATCH 06/10] cppc: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-cppc.adoc | 412 +++++++++++++++++++++---------------------- 1 file changed, 206 insertions(+), 206 deletions(-) diff --git a/src/srvgrp-cppc.adoc b/src/srvgrp-cppc.adoc index c5e6467..05908c1 100644 --- a/src/srvgrp-cppc.adoc +++ b/src/srvgrp-cppc.adoc @@ -12,7 +12,7 @@ endif::rootpath[] === Service Group - CPPC (SERVICEGROUP_ID: 0x00005) This service group defines the services to control application processor performance by managing a set of registers per application processor -that are used for performance management and control. The ACPI CPPC +that are used for performance management and control. The ACPI CPPC (Collaborative Processor Performance Control) is an abstract and flexible mechanism that allows application processor to collaborate with the platform microcontroller to control the performance. @@ -20,7 +20,7 @@ microcontroller to control the performance. The CPPC extension defined in the RISC-V SBI specification cite:[SBI] defines the register IDs for the standard CPPC registers, along with additional registers also required by the application processor. - + The ACPI CPPC specification cite:[ACPI] provides the details of the CPPC registers and also provides details on the performance control mechanism through CPPC. @@ -42,36 +42,36 @@ The following table lists the services in the CPPC service group: .CPPC Services [cols="1, 3, 2", width=100%, align="center", options="header"] |=== -| Service ID -| Service Name +| Service ID +| Service Name | Request Type -| 0x01 -| CPPC_ENABLE_NOTIFICATION +| 0x01 +| CPPC_ENABLE_NOTIFICATION | NORMAL_REQUEST -| 0x02 -| CPPC_PROBE_REG +| 0x02 +| CPPC_PROBE_REG | NORMAL_REQUEST -| 0x03 -| CPPC_READ_REG +| 0x03 +| CPPC_READ_REG | NORMAL_REQUEST -| 0x04 -| CPPC_WRITE_REG +| 0x04 +| CPPC_WRITE_REG | NORMAL_REQUEST -| 0x05 -| CPPC_GET_FAST_CHANNEL_REGION +| 0x05 +| CPPC_GET_FAST_CHANNEL_REGION | NORMAL_REQUEST -| 0x06 -| CPPC_GET_FAST_CHANNEL_OFFSET +| 0x06 +| CPPC_GET_FAST_CHANNEL_OFFSET | NORMAL_REQUEST -| 0x07 -| CPPC_GET_HART_LIST +| 0x07 +| CPPC_GET_HART_LIST | NORMAL_REQUEST |=== @@ -97,7 +97,7 @@ Otherwise the application processor can call the service `CPPC_WRITE_REG` for th | Layout | Normal Mode -| +| [cols="1,2a", options="header"] !=== ! Offset @@ -106,20 +106,20 @@ Otherwise the application processor can call the service `CPPC_WRITE_REG` for th ! 0x0 ! Desired performance level ! 0x4 -! _Reserved_ +! _Reserved_ and must be `0`. !=== | Autonomous (CPPC2) mode -| +| [cols="1,2a", options="header"] !=== ! Offset ! Value (32-bit) ! 0x0 -! Minimum Performance Level +! Minimum performance level ! 0x4 -! Maximum Performance Level +! Maximum performance level !=== |=== @@ -135,9 +135,9 @@ autonomous mode can also be discovered through the same service. A fast-channel size for a application processor is of `8-byte` with two fields of `4-byte` each. A fast-channel must be naturally aligned to the size of the -fast-channel. +fast-channel. -The offset of a fast-channel entry belonging to a application processor in that +The offset of a fast-channel entry belonging to a application processor in that shared memory region can be discovered through service `CPPC_GET_FAST_CHANNEL_OFFSET`. The offset can be added into the `base-address` of the shared memory region to form the address of a application processor fast-channel. @@ -165,14 +165,14 @@ to them. Supported events are described in <>. .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| EVENT_ID -| uint32 +| 0 +| EVENT_ID +| uint32 | Event to be subscribed for notification. |=== @@ -180,34 +180,34 @@ to them. Supported events are described in <>. .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="5,5a", options="header"] !=== ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Event is subscribed successfully. -! RPMI_ERR_INVALID_PARAM +! RPMI_ERR_INVALID_PARAM ! `EVENT_ID` is invalid. -! RPMI_ERR_NOT_SUPPORTED +! RPMI_ERR_NOT_SUPPORTED ! Notification is not supported. !=== - Other errors <> |=== ==== Service: CPPC_PROBE_REG (SERVICE_ID: 0x02) -This service is used to probe a CPPC register implementation status for a +This service is used to probe a CPPC register implementation status for a application processor. If the CPPC register `reg_id` is implemented then the length in bits is returned in `REG_LENGTH` field. If the register is not supported or invalid then the `REG_LENGTH` will be `0`. @@ -221,12 +221,12 @@ supported or invalid then the `REG_LENGTH` will be `0`. | Type | Description -| 0 +| 0 | REG_ID | uint32 | CPPC register ID -| 1 +| 1 | HART_ID | uint32 | Hart ID @@ -236,14 +236,14 @@ supported or invalid then the `REG_LENGTH` will be `0`. .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="5,5a", options="header"] !=== @@ -261,7 +261,7 @@ supported or invalid then the `REG_LENGTH` will be `0`. !=== - Other errors <> -| 1 +| 1 | REG_LENGTH | uint32 | Register length (bits) @@ -271,27 +271,27 @@ supported or invalid then the `REG_LENGTH` will be `0`. This service is used to read a CPPC register. If the fast-channels are supported, a read of the `DesiredPerformanceRegister` or `MinimumPerformanceRegister` and `MaximumPerformanceRegister` through this -service will return the current desired performance level or -minimum and maximum performance level limit depending on the CPPC mode from the +service will return the current desired performance level or +minimum and maximum performance level limit depending on the CPPC mode from the fast-channel of a application processor. [#table_cppc_readreg_request_data] .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| REG_ID -| uint32 +| 0 +| REG_ID +| uint32 | CPPC register ID -| 1 -| HART_ID -| uint32 +| 1 +| HART_ID +| uint32 | Hart ID |=== @@ -299,21 +299,21 @@ fast-channel of a application processor. .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="6,5", options="header"] !=== -! Error Code +! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Service completed successfully. ! RPMI_ERR_INVALID_PARAM @@ -324,15 +324,15 @@ fast-channel of a application processor. !=== - Other errors <> -| 1 -| DATA_LOW -| uint32 -| Lower `32-bit` of the data. +| 1 +| DATA_LOW +| uint32 +| Lower 32-bit of the data. -| 2 -| DATA_HIGH -| uint32 -| Upper `32-bit` of data. This will be `0` if the register is of `32-bit` +| 2 +| DATA_HIGH +| uint32 +| Upper 32-bit of data. This will be `0` if the register is of 32-bit length. |=== @@ -345,57 +345,57 @@ desired performance level in the fast-channel instead of writing into the autonomous mode the application processor must write minimum and maximum limit levels into the fast-channel instead of calling this service for `MinimumPerformanceRegister` and `MaximumPerformanceRegister`. Otherwise the -writes to these registers may be ignored. +writes to these registers may be ignored. [#table_cppc_writereg_request_data] .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| REG_ID -| uint32 +| 0 +| REG_ID +| uint32 | CPPC register ID -| 1 -| HART_ID -| uint32 +| 1 +| HART_ID +| uint32 | Hart ID -| 2 -| DATA_LOW -| uint32 -| Lower `32-bit` of data. +| 2 +| DATA_LOW +| uint32 +| Lower 32-bit of data. -| 3 -| DATA_HIGH -| uint32 -| Upper `32-bit` of data. This is ignored if the register is of `32-bit` length. +| 3 +| DATA_HIGH +| uint32 +| Upper 32-bit of data. This is ignored if the register is of 32-bit length. |=== [#table_cppc_writereg_response_data] .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="6,5", options="header"] !=== ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Service completed successfully. ! RPMI_ERR_INVALID_PARAM @@ -419,14 +419,14 @@ doorbell. .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| HART_ID -| uint32 +| 0 +| HART_ID +| uint32 | Hart ID |=== @@ -434,115 +434,115 @@ doorbell. .Response Data [cols="1, 4, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="2,1", options="header"] !=== -! Error Code +! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Service completed successfully. -! RPMI_ERR_INVALID_PARAM +! RPMI_ERR_INVALID_PARAM ! `HART_ID` is invalid. -! RPMI_ERR_NOT_SUPPORTED +! RPMI_ERR_NOT_SUPPORTED ! Fast-channels not supported. !=== - Other errors <> -| 1 -| FLAGS -| uint32 +| 1 +| FLAGS +| uint32 | [cols="1,5a", options="header"] !=== ! Bits ! Description -! [31:5] -! _Reserved, must be initialized to_ `0`. +! [31:5] +! _Reserved_ and must be `0`. ! [4:3] ! CPPC mode - 0b00: Normal mode. + 0b00: Normal mode. Desired performance level for performance change. - - 0b01: Autonomous mode. + + 0b01: Autonomous mode. Performance limit change. Platform can choose the level in the requested limit. - 0b10 - 0b11: Reserved. + 0b10 - 0b11: Reserved -! [2:1] +! [2:1] ! Doorbell register width - 0b00: `8-bit` - 0b01: `16 bit` - 0b10: `32 bit` - 0b11: `64 bit` -! [0] + 0b00: 8-bit + 0b01: 16-bit + 0b10: 32-bit + 0b11: 64-bit +! [0] ! Doorbell support. 0b1: Supported 0b0: Not supported !=== -| 2 -| REGION_ADDR_LOW -| uint32 -| Lower `32-bit` of the fast-channels shared memory region physical address. +| 2 +| REGION_ADDR_LOW +| uint32 +| Lower 32-bit of the fast-channels shared memory region physical address. -| 3 +| 3 | REGION_ADDR_HIGH -| uint32 -| Upper `32-bit` of the fast-channels shared memory region physical address. +| uint32 +| Upper 32-bit of the fast-channels shared memory region physical address. | 4 | REGION_SIZE_LOW | uint32 -| Lower `32-bit` of the fast-channels shared memory region size. +| Lower 32-bit of the fast-channels shared memory region size. | 5 | REGION_SIZE_HIGH | uint32 -| Upper `32-bit` of the fast-channels shared memory region size. +| Upper 32-bit of the fast-channels shared memory region size. -| 6 -| DB_ADDR_LOW -| uint32 -| Lower `32-bit` of doorbell address. +| 6 +| DB_ADDR_LOW +| uint32 +| Lower 32-bit of doorbell address. -| 7 -| DB_ADDR_HIGH -| uint32 -| Upper `32-bit` of doorbell address. +| 7 +| DB_ADDR_HIGH +| uint32 +| Upper 32-bit of doorbell address. -| 8 -| DB_SETMASK_LOW -| uint32 -| Lower `32-bit` of doorbell set mask. +| 8 +| DB_SETMASK_LOW +| uint32 +| Lower 32-bit of doorbell set mask. -| 9 +| 9 | DB_SETMASK_HIGH -| uint32 -| Upper `32-bit` of doorbell set mask. +| uint32 +| Upper 32-bit of doorbell set mask. -| 10 +| 10 | DB_PRESERVEMASK_LOW -| uint32 -| Lower `32-bit` doorbell preserve mask. +| uint32 +| Lower 32-bit doorbell preserve mask. -| 11 +| 11 | DB_PRESERVEMASK_HIGH -| uint32 -| Upper `32-bit` doorbell preserve mask. +| uint32 +| Upper 32-bit doorbell preserve mask. |=== ==== Service: CPPC_GET_FAST_CHANNEL_OFFSET (SERVICE_ID: 0x06) @@ -553,14 +553,14 @@ processor in the shared memory region containing all the fast-channels. .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| HART_ID -| uint32 +| 0 +| HART_ID +| uint32 | Hart ID |=== @@ -568,27 +568,27 @@ processor in the shared memory region containing all the fast-channels. .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="1,1a", options="header"] !=== ! Error Code ! Description -! RPMI_SUCCESS +! RPMI_SUCCESS ! Service completed successfully. -! RPMI_ERR_INVALID_PARAM +! RPMI_ERR_INVALID_PARAM ! `HART_ID` is invalid. -! RPMI_ERR_NOT_SUPPORTED +! RPMI_ERR_NOT_SUPPORTED ! Fast-channels not supported. !=== - Other errors <> @@ -596,12 +596,12 @@ processor in the shared memory region containing all the fast-channels. | 1 | OFFSET_LOW | uint32 -| Lower `32-bit` of a fast-channel offset. +| Lower 32-bit of a fast-channel offset. | 2 | OFFSET_HIGH | uint32 -| Upper `32-bit` of a fast-channel offset. +| Upper 32-bit of a fast-channel offset. |=== ==== Service: CPPC_GET_HART_LIST (SERVICE_ID: 0x07) @@ -619,14 +619,14 @@ may need to call this service again with the appropriate `START_INDEX` until the .Request Data [cols="1, 2, 1, 7", width=100%, align="center", options="header"] |=== -| Word +| Word | Name -| Type +| Type | Description -| 0 -| START_INDEX -| uint32 +| 0 +| START_INDEX +| uint32 | Starting index of Hart ID. |=== @@ -634,17 +634,17 @@ may need to call this service again with the appropriate `START_INDEX` until the .Response Data [cols="1, 2, 1, 7a", width=100%, align="center", options="header"] |=== -| Word -| Name -| Type +| Word +| Name +| Type | Description -| 0 -| STATUS -| int32 +| 0 +| STATUS +| int32 | Return error code [cols="6,5", options="header"] -!=== +!=== ! Error Code ! Description @@ -656,28 +656,28 @@ may need to call this service again with the appropriate `START_INDEX` until the !=== - Other errors <> -| 1 -| REMAINING -| uint32 +| 1 +| REMAINING +| uint32 | Remaining number of Hart IDs to be returned. -| 2 -| RETURNED -| uint32 +| 2 +| RETURNED +| uint32 | Number of Hart IDs returned in this request. -| 3 -| HART_ID[0] -| uint32 +| 3 +| HART_ID[0] +| uint32 | Hart ID -| 4 -| HART_ID[1] +| 4 +| HART_ID[1] | uint32 | Hart ID -| N+2 -| HART_ID[N-1] -| uint32 +| N+2 +| HART_ID[N-1] +| uint32 | Hart ID |=== \ No newline at end of file From 5e8c5a6bc912081e2ad38d6840fe20ca500ec0e1 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:24:24 +0800 Subject: [PATCH 07/10] device-power: Update for consistent description format Update for consistent description format. Signed-off-by: Joshua Yeong --- src/srvgrp-device-power.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/srvgrp-device-power.adoc b/src/srvgrp-device-power.adoc index f293c0f..f9c4d58 100644 --- a/src/srvgrp-device-power.adoc +++ b/src/srvgrp-device-power.adoc @@ -9,7 +9,7 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *DEVICE_POWER* (SERVICEGROUP_ID: 0x00008) +=== 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 used only for device power management since System and CPU power management is handled by already defined @@ -47,7 +47,7 @@ and start from 0. | POWER_STATE[30:16] | RESERVED -| _Reserved_ +| _Reserved_ and must be `0`. | POWER_STATE[15:0] | VALUE @@ -61,16 +61,16 @@ and start from 0. ! ON with POWER_STATE[31] = 0 ! 0x0001 -! _Reserved_ +! _Reserved_ and must be `0`. ! 0x0002 -! _Reserved_ +! _Reserved_ and must be `0`. ! 0x0003 ! OFF with POWER_STATE[31] = 1 ! 0x0004 - 0x0FFF -! _Reserved_ +! _Reserved_ and must be `0`. ! 0x1000 - 0xFFFF ! Vendor specific states @@ -253,7 +253,7 @@ This service is used to query the attributes of a device power domain. | 1 | FLAGS | uint32 -| _Reserved_ +| _Reserved_ and must be `0`. | 2 | TRANSITION_LATENCY From 42d8ef4342229eb3c4fe6349b7644fc840d47505 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:24:39 +0800 Subject: [PATCH 08/10] mm: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/srvgrp-management.adoc | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/srvgrp-management.adoc b/src/srvgrp-management.adoc index 383f86b..e25b7d1 100644 --- a/src/srvgrp-management.adoc +++ b/src/srvgrp-management.adoc @@ -9,7 +9,7 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *MANAGEMENT_MODE* (SERVICEGROUP_ID: 0x0000A) +=== Service Group - MANAGEMENT_MODE (SERVICEGROUP_ID: 0x0000A) This MANAGEMENT_MODE service group is designed to be used for software invocation of Management Mode (MM) in a secure execution environment. For general background on Management Mode, refer to the Platform Initialization (PI) specifications @@ -151,10 +151,10 @@ This service returns the version of a Management Mode. ! Description ! [31:16] -! Major Version +! Major version ! [15:0] -! Minor Version +! Minor version !=== |=== @@ -178,22 +178,22 @@ world is signaled by the MM_COMPLETE call from the secure world. | 0 | MM_COMM_DATA_ADDR_LOW | uint32 -| Lower 32 bits of MM data's physical address from non-secure to secure world. +| Lower 32-bit of MM data's physical address from non-secure to secure world. | 1 | MM_COMM_DATA_ADDR_HIGH | uint32 -| Upper 32 bits of MM data's physical address from non-secure to secure world. +| Upper 32-bit of MM data's physical address from non-secure to secure world. | 2 | MM_COMM_DATA_SIZE_LOW | uint32 -| Lower 32 bits of MM data's length from non-secure to secure world. +| Lower 32-bit of MM data's length from non-secure to secure world. | 3 | MM_COMM_DATA_SIZE_HIGH | uint32 -| Upper 32 bits of MM data's length from non-secure to secure world. +| Upper 32-bit of MM data's length from non-secure to secure world. |=== [#table_mm_communicate_response_data] @@ -229,7 +229,7 @@ world is signaled by the MM_COMPLETE call from the secure world. ==== Service: MM_COMPLETE (SERVICE_ID: 0x04) Use this MM_COMPLETE as the “world-switch synchronous call” normally at the end -of a synchronous MM_COMMUNICATE call to signal the readiness for handling the +of a synchronous MM_COMMUNICATE call to signal the readiness for handling the synchronous request. The MM_COMM_DATA contains the returned data of the MM service invoked. @@ -274,20 +274,20 @@ service invoked. | 0 | MM_COMM_DATA_ADDR_LOW | uint32 -| Lower 32 bits of MM data's physical address from non-secure to secure world. +| Lower 32-bit of MM data's physical address from non-secure to secure world. | 1 | MM_COMM_DATA_ADDR_HIGH | uint32 -| Upper 32 bits of MM data's physical address from non-secure to secure world. +| Upper 32-bit of MM data's physical address from non-secure to secure world. | 2 | MM_COMM_DATA_SIZE_LOW | uint32 -| Lower 32 bits of MM data's length from non-secure to secure world. +| Lower 32-bit of MM data's length from non-secure to secure world. | 3 | MM_COMM_DATA_SIZE_HIGH | uint32 -| Upper 32 bits of MM data's length from non-secure to secure world. +| Upper 32-bit of MM data's length from non-secure to secure world. |=== From e67869fbe7c5baf9bc0beaca99b9b3668a78f9c9 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:24:48 +0800 Subject: [PATCH 09/10] ras: Update for consistent description format Update for consistent description format. Signed-off-by: Joshua Yeong --- src/srvgrp-ras-agent.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/srvgrp-ras-agent.adoc b/src/srvgrp-ras-agent.adoc index fc5889c..c854c95 100644 --- a/src/srvgrp-ras-agent.adoc +++ b/src/srvgrp-ras-agent.adoc @@ -9,7 +9,7 @@ ifndef::rootpath[] :rootpath: ./../ endif::rootpath[] -=== Service Group - *RAS_AGENT* (SERVICEGROUP_ID: 0x0000B) +=== Service Group - RAS_AGENT (SERVICEGROUP_ID: 0x0000B) 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. @@ -281,7 +281,7 @@ source descriptor is in GHESv2 format. Rest of the values (1-15) are implementation specific. ! [31:4] -! _Reserved_ +! _Reserved_ and must be `0`. !=== From 6a61e67fe47a751deddbd3144a38eb10de9ffca6 Mon Sep 17 00:00:00 2001 From: Joshua Yeong Date: Fri, 6 Sep 2024 01:25:30 +0800 Subject: [PATCH 10/10] message-protocol: Update for consistent description format Update for consistent description format and remove blank space after text. Signed-off-by: Joshua Yeong --- src/message-protocol.adoc | 123 +++++++++++++++++++------------------- 1 file changed, 61 insertions(+), 62 deletions(-) diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index 7b28ac8..2d6a8ce 100644 --- a/src/message-protocol.adoc +++ b/src/message-protocol.adoc @@ -22,7 +22,7 @@ response message with status and additional data. === Message Types Three categories of message are supported - REQUEST, ACKNOWLEDGEMENT -and NOTIFICATION. +and NOTIFICATION. A Request message represents a specific control and management task which needs to be performed. A Request message represents a service in RPMI. Depending on @@ -31,12 +31,12 @@ service. Not all request messages have an associated response message also called an acknowledgement. For example the request for system reset from the application processor to the platform microcontroller does not require a response message. If a request message has an associated acknowledgement message -then it is called a NORMAL REQUEST otherwise it is called a POSTED REQUEST. +then it is called a NORMAL REQUEST otherwise it is called a POSTED REQUEST. The Acknowledgement message indicates the status of the request message after it has been processed by the platform microcontroller. The acknowledgement messages may also contain additional data depending on the -defined service. +defined service. A Notification is an asynchronous message from the platform microcontroller to the application processor to inform it about the events that have occurred in @@ -63,7 +63,7 @@ the system. ! Request without Acknowledgement. !=== -| Messages for requesting a service from platform microcontroller. +| Messages for requesting a service from platform microcontroller. | ACKNOWLEDGEMENT | _Not applicable_ @@ -114,21 +114,21 @@ Each message is given a unique identity in an RPMI instance by its header. .Message Header [cols="2,3,15a", width=100%, align="center", options="header"] |=== -| Word -| Name +| Word +| Name | Description -| 0 -| +| 0 +| | [cols="1,7a", options="header"] !=== -! Bits +! Bits ! Description -! [31:24] +! [31:24] ! FLAGS - FLAGS[7:4]: RESERVED. + FLAGS[7:4]: Reserved and must be 0. FLAGS[3]: DOORBELL 0b0: Doorbell interrupt is enabled. @@ -139,33 +139,33 @@ Each message is given a unique identity in an RPMI instance by its header. 0b001: POSTED_REQUEST 0b010: ACKNOWLEDGEMENT 0b011: NOTIFICATION - 0b100 - 0b111: RESERVED, must be 0. + 0b100 - 0b111: Reserved and must be 0. -! [23:16] +! [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] +! [15:0] ! SERVICEGROUP_ID + Services are grouped into service groups and each group is identified by a -`SERVICEGROUP_ID` which is a `16-bit` identifier. +`SERVICEGROUP_ID` which is a 16-bit identifier. !=== -| 1 -| +| 1 +| | [cols="1,7a", options="header"] !=== -! Bits +! Bits ! Description -! [31:16] +! [31:16] ! TOKEN + -`16-bit` sequence number for a message. Used together with `SERVICEGROUP_ID` and +16-bit sequence number for a message. Used together with `SERVICEGROUP_ID` and `SERVICE_ID` to associate the request message with its corresponding acknowledgement message. -! [15:0] +! [15:0] ! DATALEN + Stores the size of the message data in bytes. The value stored in this field must be a multiple of `4-byte` or `0` if no data is present. @@ -181,21 +181,21 @@ according to the data carried by this acknowledgement. In the case of notification message, the platform microcontroller will generate the `TOKEN` and set the `SERVICEGROUP_ID` and the fixed `SERVICE_ID=0x00` -assigned to the notification message type in each service group and set the -`FLAGS` with the message type as `NOTIFICATION`. The notification messages do not +assigned to the notification message type in each service group and set the +`FLAGS` with the message type as `NOTIFICATION`. The notification messages do not require an acknowledgement. ==== Message Data Message data in a message of any type if present must be a multiple of `4-byte`. -The data format for the request and acknowledgement messages depends on the -individual service and details are defined in every service's section in their +The data format for the request and acknowledgement messages depends on the +individual service and details are defined in every service's section in their respective service group. The maximum size of data each message can accommodate depends on the transport `slot-size` attribute. Services where the data exceeds the size that a single message can accommodate, multipart messages can be used. Some request messages may not have associated data and in that case their `DATALEN` field in the message must be `0`. -The acknowledgement message data contains `a 32-bit` `STATUS` code which +The acknowledgement message data contains a 32-bit `STATUS` code which represents the error code. The acknowledgement message may contain other data in addition to the `STATUS` code depending on the corresponding request message. @@ -216,7 +216,7 @@ each service group to receive notification messages. Notification messages are only sent for events to which the application processor has subscribed to. If multiple events are supported in each service group, the application processor must subscribe to each event individually using reserved `ENABLE_NOTIFICATION` -service in every service group. +service in every service group. [#img-notification-format] .Notification Message Format @@ -229,7 +229,7 @@ An event may also have associated data. If the event data is present, it must be a multiple of `4-byte`. The number of events that can be stored in a notification message depends on -the maximum message data size. The `DATALEN` field in the message header +the maximum message data size. The `DATALEN` field in the message header represents the data size in bytes present in the message which is the aggregate of all event sizes. The application processor must parse each event and its data according to the event header. @@ -251,34 +251,34 @@ image::event-header.png[800,800, align="center"] | 0 | EVENT_HDR -| `32-bit` field represents a single event. +| 32-bit field represents a single event. [cols="1,7a", options="header"] !=== ! Bits ! Description -! [31:24] ! _Reserved, must be initialized to_ `0`. -! [23:16] ! EVENT_ID + +! [31:24] ! _Reserved_ and must be `0`. +! [23:16] ! EVENT_ID + Unique identifier for an event in a service group. ! [15:0] ! EVENT_DATALEN + -`16-bit` field to store event data size in bytes. +16-bit field to store event data size in bytes. !=== -| 1 : (EVENT_DATALEN/4) -| EVENT_DATA +| 1 : (EVENT_DATALEN/4) +| EVENT_DATA | Event Data |=== The table above shows the format for an event and its data. Subsequent events -are packed in the same way. This specification does not define the order of +are packed in the same way. This specification does not define the order of 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 a error condition. [#table_error_codes] @@ -286,69 +286,68 @@ condition. [cols="4, 2, 6", width=100%, align="center", options="header"] |=== | Name -| Error Code +| Error Code | Description -| RPMI_SUCCESS -| 0 +| RPMI_SUCCESS +| 0 | Service has been completed successfully -| RPMI_ERR_FAILED -| -1 +| RPMI_ERR_FAILED +| -1 | Failed due to general error. -| RPMI_ERR_NOT_SUPPORTED -| -2 +| RPMI_ERR_NOT_SUPPORTED +| -2 | Service or feature not supported -| RPMI_ERR_INVALID_PARAM -| -3 +| RPMI_ERR_INVALID_PARAM +| -3 | One or more parameters passed are invalid -| RPMI_ERR_DENIED -| -4 +| RPMI_ERR_DENIED +| -4 | Requested operation denied due to insufficient permissions or failed dependency check. -| RPMI_ERR_INVALID_ADDR -| -5 +| RPMI_ERR_INVALID_ADDR +| -5 | One or more addresses are invalid. -| RPMI_ERR_ALREADY +| RPMI_ERR_ALREADY | -6 | Operation already in progress or state changed already for which the operation was performed. -| RPMI_ERR_EXTENSION -| -7 +| RPMI_ERR_EXTENSION +| -7 | Error in extension implementation that violates the extension specification or the extension version mismatch. -| RPMI_ERR_HW_FAULT -| -8 +| RPMI_ERR_HW_FAULT +| -8 | Failed due to hardware fault. -| RPMI_ERR_BUSY -| -9 +| RPMI_ERR_BUSY +| -9 | Service cannot be completed due to system or device is busy. | RPMI_ERR_INVALID_STATE | -10 | Invalid state -| RPMI_ERR_BAD_RANGE +| RPMI_ERR_BAD_RANGE | -11 | Index out of range -| RPMI_ERR_TIMEOUT +| RPMI_ERR_TIMEOUT | -12 | Failed due to timeout -| RPMI_ERR_IO -| -13 +| RPMI_ERR_IO +| -13 | Input/Output error. | | -14 to -127 | _Reserved_ | | > -127 | _Vendor specific_ |=== -