From bbbba40273b2feeb58770128b4049b89d9df7b32 Mon Sep 17 00:00:00 2001 From: Rahul Pathak Date: Fri, 6 Sep 2024 09:26:56 +0530 Subject: [PATCH] Add service group versioning details Signed-off-by: Rahul Pathak --- src/intro.adoc | 26 ++++++---- src/rpmi-mpxy.adoc | 6 +-- src/service-groups.adoc | 93 +++++++++++++++++++++++++--------- src/srvgrp-base.adoc | 49 ++++++++++-------- src/srvgrp-system-reset.adoc | 3 +- src/srvgrp-system-suspend.adoc | 3 +- 6 files changed, 120 insertions(+), 60 deletions(-) diff --git a/src/intro.adoc b/src/intro.adoc index 6ed8fd1..3bf0ae4 100644 --- a/src/intro.adoc +++ b/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. diff --git a/src/rpmi-mpxy.adoc b/src/rpmi-mpxy.adoc index b726a2c..d210aa8 100644 --- a/src/rpmi-mpxy.adoc +++ b/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. diff --git a/src/service-groups.adoc b/src/service-groups.adoc index 94f690c..456a099 100644 --- a/src/service-groups.adoc +++ b/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 diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index 5832ebb..130271e 100644 --- a/src/srvgrp-base.adoc +++ b/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 <> 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 <> | 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 diff --git a/src/srvgrp-system-reset.adoc b/src/srvgrp-system-reset.adoc index 61a82dc..bd98c68 100644 --- a/src/srvgrp-system-reset.adoc +++ b/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"] diff --git a/src/srvgrp-system-suspend.adoc b/src/srvgrp-system-suspend.adoc index 523f109..95e0dcd 100644 --- a/src/srvgrp-system-suspend.adoc +++ b/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"]