Merge pull request #49 from pathakraul/rpathak_mpxychapter

Add RPMI MPXY Integration chapter

riscv-rpmi.adoc

@@ -58,12 +58,20 @@ Copyright 2023 by RISC-V International.
 [preface]
 include::src/contributors.adoc[]
 
+[preface]
+include::src/changelog.adoc[]
+
+[preface]
+include::src/terms.adoc[]
+
 include::src/intro.adoc[]
 
 include::src/transport.adoc[]
 
 include::src/message-protocol.adoc[]
 
+include::src/rpmi-mpxy.adoc[]
+
 include::src/service-groups.adoc[]
 
 include::src/srvgrp-base.adoc[]

src/changelog.adoc

@@ -0,0 +1,4 @@
+== Changelog
+
+
+[%hardbreaks]

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
@@ -56,13 +56,24 @@ to add their own services.
 .High Level Architecture
 image::highlevel-arch.png[width=800,height=800, align="center"]
 
-An RPMI instance is an implementation of the RPMI messaging protocol and the
-transport which handles the packing and unpacking of RPMI messages, as well as
-the delivery of messages via the RPMI transport to the other side.
+RPMI is designed to work with a single or multi-tenant topology as shown
+below.
 
 [#img-transport-topologies]
 .Transport for M-Mode and S-Mode
 image::transport-topologies.png[width=800,height=800, align="center"]
 
-RPMI is designed to work with a single or multi-tenant topology as shown
-above.
+==== RPMI Client
+An RPMI client is a software or a driver which is capable of sending and
+receiving RPMI messages.
+
+==== RPMI Context
+An RPMI context consists of an RPMI transport instance with RPMI message protocol
+layer. Each RPMI context has a mandatory BASE service group enabled along with
+one or more optional service groups. 
+
+An RPMI context is specific to a RISC-V privilege level in an application
+processor. An RPMI context must only be accessible at a given privilege level.
+Each service group in RPMI defines the privilege level at which it can be accessed.
+An RPMI context must only enable service group which are allowed as per the
+service group privilege level requirement.

src/message-protocol.adoc

@@ -108,7 +108,7 @@ and indexed starting from `0`.
 
 ==== Message Header
 The `8-byte` message header has a fixed layout consisting of several fields.
-Each message is given a unique identity in an RPMI instance by its header.
+Each message is given a unique identity in an RPMI context by its header.
 
 [#table_message_header]
 .Message Header

src/rpmi-mpxy.adoc

@@ -0,0 +1,46 @@
+:path: src/
+:imagesdir: ../images
+
+ifdef::rootpath[]
+:imagesdir: {rootpath}{path}{imagesdir}
+endif::rootpath[]
+
+ifndef::rootpath[]
+:rootpath: ./../
+endif::rootpath[]
+
+== 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.
+
+.RPMI and MPXY Integration
+image::mpxy-rpmi.png[350,350, align="center"]
+
+RPMI service groups that are M-mode only, including BASE, which is an exception
+must not be accessible via SBI MPXY interface. A MPXY channel
+corresponds to a single RPMI service group bound to that MPXY channel.
+
+The following table lists the RPMI message protocol specific attributes for
+a MPXY channel.
+
+[#table_rpmi_mpxy_attributes]
+.RPMI Attributes for MPXY Channel
+[cols="3, 2, 1, 3", width=100%, align="center", options="header"]
+|===
+| Attribute Name
+| Attribute ID
+| Access
+| Description
+
+| SERVICEGROUP_ID
+| 0x80000000
+| RO
+| RPMI service group ID
+
+| SERVICEGROUP_VERSION
+| 0x80000001
+| RO
+| RPMI service group version
+|===
+
+TODO: Link to the MPXY Extension chapter in SBI spec (does not exist in SBI spec)

src/service-groups.adoc

@@ -21,33 +21,96 @@ 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.
+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`). Each service group has another dedicated
+service with (`SERVICE_ID = 0x01`) to subscribe to events for notification.
+
+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 groups.
 
 [#table_service_groups]
 .RPMI Service Groups
-[cols="2, 4", width=100%, align="center", options="header"]
+[cols="2, 2, 4, 3", 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
+| RISC-V Privilege Mode
+
+| 0x0001
+|
+| BASE
+| M-mode, S-mode
+
+| 0x0002
+|
+| SYSTEM_RESET
+| M-mode
+
+| 0x0003
+|
+| SYSTEM_SUSPEND
+| M-mode
+
+| 0x0004
+|
+| HART_STATE_MANAGEMENT
+| M-mode
+
+| 0x0005
+|
+| CPPC
+| M-mode, S-mode
+
+| 0x0006
+|
+| VOLTAGE
+| M-mode, S-mode
+
+| 0x0007
+|
+| CLOCK
+| M-mode, S-mode
+
+| 0x0008
+|
+| DEVICE_POWER
+| M-mode, S-mode
+
+| 0x0009
+|
+| PERFORMANCE
+| M-mode, S-mode
+
+| 0x000A
+|
+| MANAGEMENT_MODE
+| M-mode, S-mode
+
+| 0x000B
+|
+| RAS_AGENT
+| M-mode, S-mode
+
+| 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