Improve spec part2

src/message-protocol.adoc

@@ -13,7 +13,7 @@ endif::rootpath[]
 The RPMI protocol defines the message format and different messages
 for system management and control tasks. A message is called a Service if its
 designated to perform a specific task. Multiple similar services are grouped
-logically into a Service Group like Clock, Voltage, Perf Management, etc.
+logically into a Service Group like Clock, Voltage, Performance, etc.
 A service call results in a request message being sent on a transport
 channel from the application processor to the platform microcontroller or
 vice-versa. If the request has an associated response, the platform
@@ -291,19 +291,19 @@ condition.
 
 | RPMI_SUCCESS
 | 0
-| Service has been completed successfully
+| Service has been completed successfully.
 
 | RPMI_ERR_FAILED
 | -1
 | Failed due to general error.
 
 | RPMI_ERR_NOT_SUPPORTED
 | -2
-| Service or feature not supported
+| Service or feature is not supported.
 
 | RPMI_ERR_INVALID_PARAM
 | -3
-| One or more parameters passed are invalid
+| One or more parameters passed are invalid.
 
 | RPMI_ERR_DENIED
 | -4
@@ -334,20 +334,20 @@ violates the extension specification or the extension version mismatch.
 
 | RPMI_ERR_INVALID_STATE
 | -10
-| Invalid state
+| Invalid state.
 
 | RPMI_ERR_BAD_RANGE
 | -11
-| Index out of range
+| Index out of range.
 
 | RPMI_ERR_TIMEOUT
 | -12
-| Failed due to timeout
+| Failed due to timeout.
 
 | RPMI_ERR_IO
 | -13
 | Input/Output error.
 
-|	| -14 to -127 	| _Reserved_
-|	| < -127	| _Vendor specific_
+|	| -14 to -127 	| _Reserved_.
+|	| < -127	| _Vendor specific_.
 |===

src/service-groups.adoc

@@ -19,15 +19,15 @@ provision to add more service groups as required in the future. The
 service group ID namespace also provides a means to platform vendors to add
 their implementation-specific service groups.
 
-All service groups except the `BASE` service group are optional. If a service
+All service groups except the BASE service group are optional. If a service
 group is implemented, it must implement all its services except a dedicated
-notification service (SERVICE_ID: 0x00) meant to deliver events.
+notification service (`SERVICE_ID: 0x00`) meant to deliver events.
 A service group must not implement defined services partially unless it also
 defines a mechanism to discover its implemented services.
 If a service group defines events then it must also implement notification
-service (SERVICE_ID: 0x00).
+service (`SERVICE_ID: 0x00`).
 
-The following table lists the service group
+The following table lists the service groups.
 
 [#table_service_groups]
 .RPMI Service Groups
@@ -45,8 +45,8 @@ The following table lists the service group
 | 0x0009		| PERFORMANCE
 | 0x000A		| MANAGEMENT_MODE
 | 0x000B		| RAS_AGENT
-| 0x000C - 0x7FFF	| _Reserved for Future Use_
-| 0x8000 - 0xFFFF	| _Implementation Specific Service Groups_
+| 0x000C - 0x7FFF	| _Reserved for future use_
+| 0x8000 - 0xFFFF	| _Implementation specific service groups_
 |===
 NOTE: The services listed within each service group do not have a specific order.
 Additionally, the sequence in which services are defined in the specification

src/srvgrp-base.adoc

@@ -81,7 +81,7 @@ The below table lists the services in this group:
 This service is used by the platform microcontroller to send the asynchronous
 message of type notification to the application processor. The message
 transfers the events defined by this service group. The events defined are
-listed in the below table.
+listed in the table below.
 
 [#table_base_srvgroup_events]
 .BASE Service Group Events
@@ -142,13 +142,13 @@ in table <<table_base_srvgroup_events>>.
 ! Description
 
 ! RPMI_SUCCESS
-! Notifications are subscribed successfully.
+! Event is subscribed successfully.
 
 ! RPMI_ERR_INVALID_PARAM
 ! `EVENT_ID` is invalid.
 
 ! RPMI_ERR_NOT_SUPPORTED
-! Notifications not supported.
+! Notification is not supported.
 !===
 - Other errors <<table_error_codes>>
 |===

src/srvgrp-clock.adoc

@@ -70,14 +70,12 @@ The following table lists the services in the CLOCK service group:
 | NORMAL_REQUEST
 |===
 
-Clock Rate Representation::
+[#clock-rate-format-section]
+==== Clock Rate Format
 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`.
 
-[#clock-rate-format-section]
-Clock Rate Format::
-
 * Discrete Clock Format
 
 The following table shows the structure of the Discrete clock format.
@@ -302,7 +300,7 @@ the future, as needed.
 
 ! [31:30]	! CLOCK_FORMAT
 
-Refer to <<clock-rate-format-section, Clock Rate Format>> for more details.
+Refer to <<clock-rate-format-section>> for more details.
 ----
 0b00: Discrete Format
 0b01: Linear Range
@@ -419,7 +417,7 @@ RETURNED field will be set to `3`.
 | uint32[2]
 | Clock rate.
 
-Refer to <<clock-rate-format-section, Clock Rate Format>> for more details.
+Refer to <<clock-rate-format-section>> for more details.
 |===
 
 ==== Service: CLK_SET_CONFIG (SERVICE_ID: 0x05)
@@ -540,16 +538,19 @@ This serivce is used to get the configuration of a clock device.
 
 [cols="2,5a", options="header"]
 !===
-! Value
+! Bits
 ! Description
 
-! 0x0		! Disabled
-! 0x1		! Enabled
+! [31:1]	! _Reserved_
+! [0]		! Disable/enable
+
+	0b0: Clock is disabled.
+	0b1: Clock is enabled.
 !===
 |===
 
 ==== Service: CLK_SET_RATE (SERVICE_ID: 0x07)
-Set clock rate.
+This service is used to set the clock rate of a specific clock.
 
 [#table_clock_setrate_request_data]
 .Request Data
@@ -626,7 +627,7 @@ Platform autonomously choose rate closest to the requested rate.
 |===
 
 ==== Service: CLK_GET_RATE (SERVICE_ID: 0x08)
-Get the current clock rate value.
+This service is used to get the current clock rate.
 
 [#table_clock_getrate_request_data]
 .Request Data

src/srvgrp-device-power.adoc

@@ -31,25 +31,62 @@ The DEVICE_POWER services take a 32-bit integer identifier known as `DOMAIN_ID`
 to specify the device power domain. These `DOMAIN_ID` identifiers are sequential
 and start from 0.
 
+The following table lists the services in the DEVICE_POWER service group:
+
+[#table_devpower_services]
+.DEVICE_POWER Services
+[cols="1, 3, 2", width=100%, align="center", options="header"]
+|===
+| Service ID
+| Service Name
+| Request Type
+
+| 0x01
+| DPWR_ENABLE_NOTIFICATION
+| NORMAL_REQUEST
+
+| 0x02
+| DPWR_GET_NUM_DOMAINS
+| NORMAL_REQUEST
+
+| 0x03
+| DPWR_GET_ATTRIBUTES
+| NORMAL_REQUEST
+
+| 0x04
+| DPWR_SET_STATE
+| NORMAL_REQUEST
+
+| 0x05
+| DPWR_GET_STATE
+| NORMAL_REQUEST
+|===
+
+[#section-power-state]
+==== Power State Format
+
+The power state is represented as a 32-bit value. The following table shows the
+encoding for the power state.
+
 [#table_devpower_powerstate_data]
-.Power States Encoding
+.Power State Encoding
 [cols="2, 1, 5a", width=100%, align="center", options="header"]
 |===
-| POWER_STATE
-| Field
+| Bit
+| Name
 | Description
 
-| POWER_STATE[31]
+| [31]
 | CONTEX
 |
 	0b0: Context is preserved
 	0b1: Context is lost
 
-| POWER_STATE[30:16]
+| [30:16]
 | RESERVED
 | _Reserved_ and must be `0`.
 
-| POWER_STATE[15:0]
+| [15:0]
 | VALUE
 |
 [cols="2,5", options="header"]
@@ -77,35 +114,6 @@ and start from 0.
 !===
 |===
 
-[#table_devpower_services]
-.DEVICE_POWER Services
-[cols="1, 3, 2", width=100%, align="center", options="header"]
-|===
-| Service ID
-| Service Name
-| Request Type
-
-| 0x01
-| DPWR_ENABLE_NOTIFICATION
-| NORMAL_REQUEST
-
-| 0x02
-| DPWR_GET_NUM_DOMAINS
-| NORMAL_REQUEST
-
-| 0x03
-| DPWR_GET_ATTRIBUTES
-| NORMAL_REQUEST
-
-| 0x04
-| DPWR_SET_STATE
-| NORMAL_REQUEST
-
-| 0x05
-| DPWR_GET_STATE
-| NORMAL_REQUEST
-|===
-
 [#device-power-notifications]
 ==== Notifications
 This service group does not support any event for notification.
@@ -153,7 +161,7 @@ described in <<device-power-notifications>>.
 ! Description
 
 ! RPMI_SUCCESS
-! Notification is subscribed successfully.
+! Event is subscribed successfully.
 
 ! RPMI_ERR_INVALID_PARAM
 ! `EVENT_ID` is invalid.
@@ -166,8 +174,8 @@ described in <<device-power-notifications>>.
 
 ==== Service: DPWR_GET_NUM_DOMAINS (SERVICE_ID: 0x02)
 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.
+can be controlled by the client. The number of domains returned may be less than
+the actual number of domains present on the platform.
 
 [#table_devpower_getdomains_request_data]
 .Request Data
@@ -213,7 +221,7 @@ This service is used to query the attributes of a device power domain.
 
 [#table_devpower_getattrs_request_data]
 .Request Data
-[cols="1, 4, 1, 6", width=100%, align="center", options="header"]
+[cols="1, 3, 1, 6", width=100%, align="center", options="header"]
 |===
 | Word
 | Name
@@ -228,7 +236,7 @@ This service is used to query the attributes of a device power domain.
 
 [#table_devpower_getattrs_response_data]
 .Response Data
-[cols="1, 4, 2, 6a", width=100%, align="center", options="header"]
+[cols="1, 3, 2, 6a", width=100%, align="center", options="header"]
 |===
 | Word
 | Name
@@ -240,7 +248,7 @@ This service is used to query the attributes of a device power domain.
 | int32
 | Return error code
 
-[cols="7,5", options="header"]
+[cols="8,5", options="header"]
 !===
 ! Error Code
 ! Description
@@ -259,7 +267,7 @@ This service is used to query the attributes of a device power domain.
 | _Reserved_ and must be `0`.
 
 | 2
-| TRANSITION_LATENCY
+| TRANS_LATENCY
 | uint32
 | Worst case transition latency of domain from one power state to another, in microseconds (us).
 
@@ -293,8 +301,8 @@ This service is used to change the power state of a device power domain.
 | 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 description in the
-<<table_devpower_powerstate_data>>.
+and vendor specific power state. See <<section-power-state>>
+for more details.
 |===
 
 [#table_devpower_setstate_response_data]
@@ -384,6 +392,6 @@ This service is used to get the current power state of a device power domain.
 | 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
-<<table_devpower_powerstate_data>>.
+specific implementation. See <<section-power-state>>
+for more details.
 |===