Improvement

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]

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
@@ -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

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 <<clock-notifications>>.
 ==== 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 <<clock-rate-format-section>> 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

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 <<table_error_codes>>
 

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
@@ -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

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 <<table_error_codes>>
@@ -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.

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.
 

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

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 <<img-transport-topologies>> 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.