Merge pull request #75 from lftan/improve

Improves all chapters

src/intro.adoc

@@ -11,9 +11,9 @@ endif::rootpath[]
 
 [[intro]]
 == Introduction
-Today's platform pose challenges in terms of manageability and controllability
-where the operating system (OS) need to support a variety of hardware with
-variety of connected devices. The extra complexity and demand to manage and
+Today's platforms pose challenges in terms of manageability and controllability,
+where the operating system (OS) needs to support a variety of hardware with
+a variety of connected devices. The extra complexity and demand to manage and
 control the platform along with executing sophisticated workloads is a challenge
 for the application processors (APs) running a general purpose OS. To address
 this challenge, platforms today contain one or more microcontrollers which can
@@ -40,24 +40,24 @@ microcontroller. An RPMI transport instance is associated to a particular
 RISC-V privilege level of the application processors and it must be accessed
 only by that RISC-V privilege level.
 
-*RPMI Messaging Protocol*: The RPMI messaging protocol includes different
-types of RPMI messages and the format each RPMI message type.
+*RPMI Messaging Protocol*: The RPMI messaging protocol defines different
+types of RPMI messages and the format for each RPMI message type.
 
 *RPMI Service Groups*: The services provided by the platform microcontrollers
 to the application processors are grouped based functionality into RPMI service
-groups. Each RPMI service group specifies the RISC-V privilege levels of the
-application processor which can be access it. Platform vendors can implement
-their own custom RPMI service groups.
+groups. Each RPMI service group specifies the RISC-V privilege levels from which
+the application processor can be access it. Platform vendors can implement
+custom RPMI service groups.
 
 *RPMI Client*: An RPMI client is a software or a driver running on the
 application processor which is capable of sending and receiving RPMI messages.
 
 *RPMI Context*: An RPMI context consists of an RPMI transport instance, RPMI
 message protocol layer, a mandatory RPMI BASE service group and other optional
 RPMI service groups. An RPMI context is associated with a RISC-V privilege level
-which matches the included RPMI transport instance. The RPMI services groups
+which matches the included RPMI transport instance. The RPMI service groups
 included in an RPMI context must be accessible from the RISC-V privilege level
-associated with the RPMI context.
+associated with that RPMI context.
 
 The RPMI is designed to work with a single or multi-tenant topology as shown
 in the <<fig_intro_trans_topology>> below whereas the high-level architecture

src/message-protocol.adoc

@@ -100,7 +100,7 @@ or message data.
 
 ==== Message Header
 The layout of the `8-byte` wide RPMI message header is shown in the
-<<table_message_header>> below. The RPMI message header provide an
+<<table_message_header>> below. The RPMI message header provide a
 unique identity to the corresponding RPMI message withing an RPMI
 context.
 
@@ -161,14 +161,14 @@ field must be a multiple of `4-byte` or `0` if no message data is present.
 |===
 
 For an RPMI normal request message, the `TOKEN`, `SERVICEGROUP_ID`, and
-`SERVICE_ID` fields of the RPMI acknowledgment message must have the same
+`SERVICE_ID` fields of the RPMI acknowledgement message must have the same
 values as corresponding fields in the RPMI request message. The `DATALEN`
-field of the RPMI acknowledgment message must be set according to the data
+field of the RPMI acknowledgement message must be set according to the data
 carried by this acknowledgement.
 
 For an RPMI notification message, the platform microcontroller will set
 appropriate values for the `TOKEN`, `SERVICEGROUP_ID`, and `DATALEN` fields
-whereas `SERVICE_ID` field must be always set to `0x0`.
+whereas the `SERVICE_ID` field must be always set to `0x0`.
 
 ==== Message Data
 The message data of an RPMI message is optional and variable sized. The
@@ -219,8 +219,8 @@ image::notification-format.png[500,600, align="center"]
 
 ==== Events
 An RPMI event consists of a header containing two fields: `EVENT_ID (8-bit)`
-and `EVENT_DATALEN (16-bit)`. An RPMI event may have associated data who's
-size is specified in the `EVENT_DATALEN` field of header and this data size
+and `EVENT_DATALEN (16-bit)`. An RPMI event may have associated data whose
+size is specified in the `EVENT_DATALEN` field of the header and this data size
 must be a multiple of `4-byte`.
 
 The number of RPMI events that can be stored in a single RPMI notification

src/rpmi-mpxy.adoc

@@ -10,7 +10,7 @@ ifndef::rootpath[]
 endif::rootpath[]
 
 == Integration with SBI MPXY Extension
-A platform with limited number of RPMI transport instances can share an M-mode
+A platform with a limited number of RPMI transport instances can share an M-mode
 RPMI transport instance with the supervisor software using the SBI MPXY extension
 cite:[SBI]. An M-mode firmware or hypervisor can also virtualize RPMI message
 communication for the supervisor software using the SBI MPXY extension. As shown
@@ -21,7 +21,7 @@ for the supervisor software when sending RPMI messages through an SBI MPXY chann
 .RPMI and SBI MPXY Integration
 image::mpxy-rpmi.png[350,350, align="center"]
 
-The RPMI communication using the SBI MPXY extension must satisfy the following
+The RPMI communication via the SBI MPXY extension must satisfy the following
 requirements:
 
 . The SBI MPXY channel must correspond to a single RPMI service group which is
@@ -41,7 +41,7 @@ must match the request data format of the RPMI service represented by the
 by the `sbi_mpxy_send_message_with_response()` must match the response data format
 of the RPMI service represented by the `message_id` parameter.
 
-. The format of the protocol specific data returned in the SBI MPXY shared memory
+. The format of the protocol-specific data returned in the SBI MPXY shared memory
 by the `sbi_mpxy_get_notification_events()` must match the RPMI notifications message
 data format.
 

src/srvgrp-base.adoc

@@ -95,17 +95,17 @@ listed in the below table.
 | 0x01
 | REQUEST_HANDLE_ERROR
 | NA
-| This event indicates that the the platform microcontroller is unable to
+| This event indicates that the platform microcontroller is unable to
 serve the message requests.
 |===
 
 ==== Service: BASE_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to BASE service
-group notifications. The platform can optionally support notifications of
-events that might occur in the platform. The platform microcontroller can send
-the supported events through notification message if the application processor
-has subscribed to them. The supported events are described
-in <<table_base_srvgroup_events>>.
+This service allows the application processor to subscribe to `BASE`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
+described in <<base-notifications>>.
 
 [#table_base_ennotification_request_data]
 .Request Data
@@ -156,7 +156,7 @@ in <<table_base_srvgroup_events>>.
 ==== 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
-the `MAJOR` and `MINOR` numbers.
+the `MAJOR` and `MINOR` version numbers.
 
 [#table_base_getimplversion_request_data]
 .Request Data
@@ -209,7 +209,7 @@ the `MAJOR` and `MINOR` numbers.
 
 ==== Service: BASE_GET_IMPLEMENTATION_ID (SERVICE_ID: 0x03)
 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
+software that implements the RPMI specification. Every implementation ID is
 unique and listed in the <<table_base_rpmi_impl_id>>.
 
 [#table_base_getimplid_request_data]
@@ -253,7 +253,7 @@ unique and listed in the <<table_base_rpmi_impl_id>>.
 ==== 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
-`MINOR` numbers.
+`MINOR` version numbers.
 
 [#table_base_getspecversion_request_data]
 .Request Data
@@ -305,7 +305,7 @@ version returned is a 32-bit composite number containing the `MAJOR` and
 |===
 
 ==== Service: BASE_GET_PLATFORM_INFO (SERVICE_ID: 0x05)
-This service is used to get addition platform information if available.
+This service is used to get additional platform information if available.
 
 [#table_base_getplatinfo_request_data]
 .Request Data

src/srvgrp-clock.adoc

@@ -146,14 +146,14 @@ The following table shows the structure of the Linear clock format.
 
 [#clock-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: CLK_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to CLOCK service
-group notifications. The platform can optionally support notifications of
-events which might occur in the platform. The platform microcontroller can send
-these notification messages to application processor if they are implemented
-and the application processor has subscribed to these. The supported events are
+This service allows the application processor to subscribe to `CLOCK`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
 described in <<clock-notifications>>.
 
 [#table_clock_ennotification_request_data]

src/srvgrp-cppc.adoc

@@ -192,15 +192,15 @@ processor through the `CPPC_GET_FAST_CHANNEL_REGION` service.
 
 [#cppc-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: CPPC_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
 This service allows the application processor to subscribe to `CPPC`
-service group defined events for notifications. The platform can optionally
-support notifications of events that may occur in the platform. The platform
-microcontroller can send these notification messages to the application
-processor if they are implemented and the application processor has subscribed
-to them. Supported events are described in <<cppc-notifications>>.
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
+described in <<cppc-notifications>>.
 
 [#table_cppc_ennotification_request_data]
 .Request Data

src/srvgrp-device-power.adoc

@@ -116,14 +116,14 @@ encoding for the power state.
 
 [#device-power-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: DPWR_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to DEVICE_POWER
-service group notifications. The platform can optionally support notifications
-of events that may occur in the platform. The platform microcontroller can send
-these notification messages to the application processor if they are implemented
-and the application processor has subscribed to them. The supported events are
+This service allows the application processor to subscribe to `DEVICE_POWER`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
 described in <<device-power-notifications>>.
 
 [#table_devpower_ennotification_request_data]

src/srvgrp-hart-state-management.adoc

@@ -11,7 +11,7 @@ endif::rootpath[]
 
 === Service Group - HART_STATE_MANAGEMENT (SERVICEGROUP_ID: 0x0004)
 This service group defines services to control and manage the application
-processor (hart) power states. A hart power states includes power on, power off,
+processor (hart) power states. Hart power states include power on, power off,
 suspend modes, etc. A hart is identified by a 32-bit identifier called `HART_ID`.
 
 In a platform, depending on the sharing of power controls and common
@@ -86,16 +86,15 @@ this service group.
 
 [#hsm-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: HSM_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to the
-`HART_STATE_MANAGEMENT` service group defined events for notifications.
-The platform can optionally support notifications of events that may occur in
-the platform. The platform microcontroller can send these notification messages
-to the application processor if they are implemented and the application
-processor has subscribed to them. Supported events are described in
-<<hsm-notifications>>.
+This service allows the application processor to subscribe to `HART_STATE_MANAGEMENT`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
+described in <<hsm-notifications>>.
 
 [#table_hsm_ennotification_request_data]
 .Request Data
@@ -143,9 +142,9 @@ processor has subscribed to them. Supported events are described in
 |===
 
 ==== Service: HSM_GET_HART_STATUS (SERVICE_ID: 0x02)
-This service returns the current HSM state of a hart. In case if a hart is
-in a invalid state which is not a defined HSM state then error code will be
-set in `STATUS` field. 
+This service returns the current HSM state of a hart. If a hart is in an
+invalid state that is not a defined HSM state, an error code will be set
+in the `STATUS` field.
 
 [#table_hsm_gethartstatus_request_data]
 .Request Data

src/srvgrp-management.adoc

@@ -47,15 +47,15 @@ The following table lists the services in the MANAGEMENT_MODE service group:
 
 [#management-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: MM_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to MANAGEMENT_MODE
-service group notifications. Platform can optionally support notifications of
-events which might occur in the platform. Platform microcontroller can send
-these notification messages to application processor if they are implemented
-and application processor has subscribed to these. Events supported are described
-in <<management-notifications>>.
+This service allows the application processor to subscribe to `MANAGEMENT_MODE`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
+described in <<management-notifications>>.
 
 [#table_mm_ennotification_request_data]
 .Request Data
@@ -106,8 +106,8 @@ in <<management-notifications>>.
 
 
 ==== Service: MM_GET_ATTRIBUTES (SERVICE_ID: 0x02)
-This RPMI service gets the attributes about Management Mode such as MM version,
-MM shared memory location, etc.
+This RPMI service gets the attributes about Management Mode, including MM
+version, MM shared memory location, etc.
 
 [#table_mm_get_attributes_request_data]
 .Request Data

src/srvgrp-performance.adoc

@@ -206,12 +206,12 @@ inform clients in the system about changes in the performance domain.
 |===
 
 ==== Service: PERF_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service is to enable or disable the performance changed notification event.
-The notification is sent from the platform microcontroller when the performance
-level, performance limit or performance power of a performance domain has changed.
-This allows the system to adjust its behavior in response to performance changes
-and ensure that it is operating within its desired performance level. The
-supported events are described in <<performance-notifications>>.
+This service allows the application processor to subscribe to `PERFORMANCE`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
+notification messages to the application processor if they are implemented and
+the application processor has subscribed to them. The supported events are
+described in <<performance-notifications>>.
 
 [#table_perf_ennotification_request_data]
 .Request Data

src/srvgrp-ras-agent.adoc

@@ -11,10 +11,10 @@ endif::rootpath[]
 
 ===  Service Group - RAS_AGENT (SERVICEGROUP_ID: 0x000B)
 The RAS_AGENT service group provides services to enumerate various error
-sources in a system and to get their descriptors.
+sources in a system and to retrieve their descriptors.
 
-Each error source in a system has a unique 32-bit identification number called
-as `RAS_ERR_SRC_ID`.
+Each error source in a system is assigned a unique 32-bit identification number,
+referred to as `RAS_ERR_SRC_ID`.
 
 The following table lists the services in the RAS_AGENT service group:
 
@@ -71,12 +71,12 @@ values from `1` to `15` are reserved for the custom format types.
 
 [#ras-notifications]
 ==== Notifications
-This service group does not support any event for notification.
+This service group does not support any events for notification.
 
 ==== Service: RAS_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)
-This service allows the application processor to subscribe to RAS_AGENT service
-group notifications. The platform can optionally support notifications of events
-that may occur in the platform. The platform microcontroller can send these
+This service allows the application processor to subscribe to `RAS_AGENT`
+service group notifications. The platform may optionally support notifications
+for events that may occur. The platform microcontroller can send these
 notification messages to the application processor if they are implemented and
 the application processor has subscribed to them. The supported events are
 described in <<ras-notifications>>.
@@ -129,7 +129,7 @@ described in <<ras-notifications>>.
 |===
 
 ==== Service: RAS_GET_NUM_ERR_SRCS (SERVICE_ID: 0x02)
-This service is used to query number of error sources available in the system.
+This service queries number of error sources available in the system.
 
 [#table_ras_agent_getnum_err_srcs_request_data]
 .Request Data
@@ -245,7 +245,7 @@ N is equal to `RETURNED` number of error source IDs in this request.
 |===
 
 ==== Service: RAS_GET_ERR_SRC_DESC (SERVICE_ID: 0x04)
-This service returns the error source descriptor of an error source specified
+This service retrieves the error source descriptor of an error source specified
 by `RAS_ERR_SRC_ID`.
 
 [#table_ras_agent_get_err_src_desc_request_data]