Add service group versioning details

Signed-off-by: Rahul Pathak <[email protected]>

src/intro.adoc

@@ -26,12 +26,12 @@ tasks. RPMI enables the communication between the application processors and the
 platform microcontrollers. It abstracts the system complexity and provides a
 message-based interface for system management and control.
 
-RPMI is not limited to a single application processor and platform 
+RPMI is not limited to a single application processor and platform
 microcontroller. It can support multiple application processors and multiple
 platform microcontrollers.
 
 The platform microcontroller or in short PuC abstracts low-level platform
-control and management from the application processor. 
+control and management from the application processor.
 
 In addition, RPMI provides a OS-agnostic scalable and extensible interface that
 can support the addition of new capabilities and services over time. This
@@ -40,14 +40,14 @@ existing systems, making it easier for system designers to keep up with changing
 requirements and adapt to evolving industry standards.
 
 === Abstractions provided by RPMI
-*Transport*: Describes the mechanism by which the messages are exchanged 
-between the application processor and the platform microcontroller. 
+*Transport*: Describes the mechanism by which the messages are exchanged
+between the application processor and the platform microcontroller.
 
 *Messaging Protocol*: Provides the messaging interface between the application
-processors and the platform microcontrollers to communicate with each other via 
-messages to make requests for various services supported by the hardware 
-platform. This is accomplished by grouping each management interface into 
-service groups. With each service group implementing several individual 
+processors and the platform microcontrollers to communicate with each other via
+messages to make requests for various services supported by the hardware
+platform. This is accomplished by grouping each management interface into
+service groups. With each service group implementing several individual
 services within.
 
 In addition to the standard services, RPMI can also be extended to allow vendors
@@ -63,19 +63,23 @@ below.
 .Transport for M-Mode and S-Mode
 image::transport-topologies.png[width=800,height=800, align="center"]
 
+==== RPMI Client
+An RPMI client is a software or a driver which is capable of sending and
+receiving RPMI messages.
+
 ==== RPMI Instance
 An RPMI instance consists of an RPMI transport instance with message protocol
 layer. Each RPMI instance has mandatory BASE service group enabled along with one
 or more optional service groups. An RPMI instance implementation is specific to
 a RISC-V privilege level in the application processor. A system can implement
 one or more RPMI instances at a privilege level shared by one or more application
-processors. 
+processors.
 
 For example, an application processor may implement one RPMI instance
-in M-mode and another instance in S-mode and both RPMI instances are 
+in M-mode and another instance in S-mode and both RPMI instances are
 independent. Also, both RPMI instances may have separate service groups enabled
 to enable different control and management interfaces as required.
 
-Details of the RPMI transport and service groups are given in the following 
+Details of the RPMI transport and service groups are given in the following
 chapters.
 

src/rpmi-mpxy.adoc

@@ -9,7 +9,7 @@ ifndef::rootpath[]
 :rootpath: ./../
 endif::rootpath[]
 
-== RPMI Integration with SBI MPXY extension.
+== RPMI Integration with SBI MPXY Extension
 The SBI MPXY (Message Proxy) extension is defined by the RISC-V SBI Specification
 cite:[SBI] for sending and receiving the message data from the S-mode when
 the RPMI instance is implemented in M-mode.
@@ -29,8 +29,8 @@ exposed to the S-mode over SBI MPXY interface and RPMI message protocol specific
 attributes for MPXY channel.
 
 The service groups that have dedicated SBI extension cannot be
-used by the S-mode via MPXY interface. For example the SYSTEM_RESET service
-group can only be accessed via the SBI System Reset extension. If S-mode
+used by the S-mode RPMI client via MPXY interface. For example the SYSTEM_RESET
+service group can only be accessed via the SBI System Reset extension. If S-mode
 attempts to access any service of such service group via MPXY, the request will
 be denied.
 

src/service-groups.adoc

@@ -16,38 +16,83 @@ related services are collectively called the Voltage service group.
 
 This specification defines standard service groups and services with the
 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
+service group ID namespace also provides a means for platform vendors to add
 their implementation-specific service groups.
 
-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.
-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).
+All service groups except the `BASE` service group are optional. A service group
+must not implement defined services partially unless it also defines a mechanism
+for discovering its implemented services. If the `BASE_PROBE_SERVICE_GROUP` service
+indicates that a service group is implemented and returns the implemented
+version, then the service group version must conform to the version returned by
+the `BASE_GET_SPEC_VERSION`.
 
-The following table lists the service group
+In each service group the `SERVICE_ID = 0x00` is dedicated to a notification type
+service used to send events notification and a `SERVICE_ID = 0x01` dedicated for
+a service used to subscribe to events for notification.
+
+The following table lists the RPMI service groups:
 
 [#table_service_groups]
 .RPMI Service Groups
-[cols="2, 4", width=100%, align="center", options="header"]
+[cols="2, 2, 4", width=100%, align="center", options="header"]
 |===
-| Service Group ID	| Service Group Name
-| 0x0001		| BASE
-| 0x0002		| SYSTEM_RESET
-| 0x0003		| SYSTEM_SUSPEND
-| 0x0004		| HART_STATE_MANAGEMENT
-| 0x0005		| CPPC
-| 0x0006		| VOLTAGE
-| 0x0007		| CLOCK
-| 0x0008		| DEVICE_POWER
-| 0x0009		| PERFORMANCE
-| 0x000A		| MANAGEMENT_MODE
-| 0x000B		| RAS_AGENT
-| 0x000C - 0x7FFF	| _Reserved for Future Use_
-| 0x8000 - 0xFFFF	| _Implementation Specific Service Groups_
+| Service Group ID
+| Version (Major:Minor)
+| Service Group Name
+
+| 0x0001
+|
+| BASE
+
+| 0x0002
+|
+| SYSTEM_RESET
+
+| 0x0003
+|
+| SYSTEM_SUSPEND
+
+| 0x0004
+|
+| HART_STATE_MANAGEMENT
+
+| 0x0005
+|
+| CPPC
+
+| 0x0006
+|
+| VOLTAGE
+
+| 0x0007
+|
+| CLOCK
+
+| 0x0008
+|
+| DEVICE_POWER
+
+| 0x0009
+|
+| PERFORMANCE
+
+| 0x000A
+|
+| MANAGEMENT_MODE
+
+| 0x000B
+|
+| RAS_AGENT
+
+| 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
 does not necessarily reflect the order in which they should be called in the

src/srvgrp-base.adoc

@@ -21,7 +21,7 @@ microcontroller.
 
 * Discovering platform specific information.
 
-The below table lists the services in this group:
+The following table lists the services in the BASE service group:
 
 [#table_base_services]
 .BASE Services
@@ -200,10 +200,10 @@ the `MAJOR` and `MINOR` numbers.
 ! Description
 
 ! [31:16]
-! `MAJOR` Number
+! `MAJOR` number
 
 ! [15:0]
-! `MINOR` Number
+! `MINOR` number
 !===
 |===
 
@@ -354,10 +354,13 @@ model, revision, or configuration of the hardware.
 |===
 
 ==== Service: BASE_PROBE_SERVICE_GROUP (SERVICE_ID: 0x06)
-This service is used to probe the implementation of a service group. All
-service groups except `BASE` are optional. If the `SERVICEGROUP_ID` is
-not implemented or invalid then this service returns `0` in the
-`SERVICE_GROUP_STATUS` field instead of the error code in `STATUS`.
+This service is used to probe the implementation of a service group and to
+obtain the implemented service group version. The service group version is a
+32-bit composite number containing the `MAJOR` and `MINOR` numbers.
+
+If the service group is successfully probed then the implemented service group
+version is returned in the `SERVICE_GROUP_VERSION` field. Otherwise it returns
+`0`.
 
 [#table_base_probesrvgrp_request_data]
 .Request Data
@@ -371,9 +374,7 @@ not implemented or invalid then this service returns `0` in the
 | 0
 | SERVICEGROUP_ID
 | uint32
-| A 16-bit ID assigned to each service group. +
-Refer to table <<table_service_groups>> for defined service groups. +
-The first 16-bit of the `uint32` field will store the `SERVICEGROUP_ID`.
+| Service group ID
 |===
 
 [#table_base_probesrvgrp_response_data]
@@ -401,12 +402,20 @@ The first 16-bit of the `uint32` field will store the `SERVICEGROUP_ID`.
 - Other errors <<table_error_codes>>
 
 | 1
-| SERVICE_GROUP_STATUS
+| SERVICE_GROUP_VERSION
 | uint32
-| Service group implementation status.
+| Service group version.
+[cols="2,5a", options="header"]
+!===
+! Bits
+! Description
+
+! [31:16]
+! `MAJOR` number
 
-	1: Implemented
-	0: Not implemented
+! [15:0]
+! `MINOR` number
+!===
 |===
 
 ==== Service: BASE_GET_ATTRIBUTES (SERVICE_ID: 0x07)
@@ -454,7 +463,7 @@ service group.
 ! Description
 
 ! [31:3]
-! _Reserved, must be initialized to_ `0`.
+! _Reserved_, must be initialized to `0`.
 
 ! [2]
 ! The RISC-V privilege level to which the RPMI instance belong.
@@ -478,17 +487,17 @@ service group.
 | 2
 | FLAGS1
 | uint32
-| _Reserved, must be initialized to_ `0`.
+| _Reserved_, must be initialized to `0`.
 
 | 3
 | FLAGS2
 | uint32
-| _Reserved, must be initialized to_ `0`.
+| _Reserved_, must be initialized to `0`.
 
 | 4
 | FLAGS3
 | uint32
-| _Reserved, must be initialized to_ `0`.
+| _Reserved_, must be initialized to `0`.
 |===
 
 ==== Service: BASE_SET_MSI (SERVICE_ID: 0x08)
@@ -524,12 +533,12 @@ processor will take the wired interrupt.
 | 0
 | MSI_ADDRESS_LOW
 | uint32
-| Lower 32-bit of the MSI address
+| Lower 32-bit of the MSI address.
 
 | 1
 | MSI_ADDRESS_HIGH
 | uint32
-| Upper 32-bit of the MSI address
+| Upper 32-bit of the MSI address.
 
 | 2
 | MSI_DATA

src/srvgrp-system-reset.adoc

@@ -27,7 +27,8 @@ necessary to categorize it as a graceful or forceful shutdown. In the case of
 a shutdown request, it is implicit for the platform microcontroller that the
 application processor has prepared itself for a successful shutdown.
 
-Below table lists the services in this group:
+The following table lists the services in the SYSTEM_RESET service group:
+
 [#table_sysreset_services]
 .SYSTEM_RESET Services
 [cols="1, 3, 2", width=100%, align="center", options="header"]

src/srvgrp-system-suspend.adoc

@@ -18,7 +18,8 @@ platform microcontroller that all the application processors except the one
 requesting are in `STOPPED` state and necessary state saving in the RAM has
 been complete.
 
-Below if the list of services in this group:
+The following table lists the services in the SYSTEM_SUSPEND service group:
+
 [#table_syssuspend_services]
 .SYSTEM_SUSPEND Services
 [cols="1, 3, 2", width=100%, align="center", options="header"]