diff --git a/images/mpxy-rpmi.png b/images/mpxy-rpmi.png new file mode 100644 index 0000000..687d318 Binary files /dev/null and b/images/mpxy-rpmi.png differ diff --git a/riscv-rpmi.adoc b/riscv-rpmi.adoc index 37c1a44..5ef8b02 100644 --- a/riscv-rpmi.adoc +++ b/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[] diff --git a/src/changelog.adoc b/src/changelog.adoc new file mode 100644 index 0000000..89d9368 --- /dev/null +++ b/src/changelog.adoc @@ -0,0 +1,4 @@ +== Changelog + + +[%hardbreaks] \ No newline at end of file diff --git a/src/intro.adoc b/src/intro.adoc index 87ec42d..0a1cff9 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 @@ -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. diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index 07e95b7..24013d2 100644 --- a/src/message-protocol.adoc +++ b/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 diff --git a/src/rpmi-mpxy.adoc b/src/rpmi-mpxy.adoc new file mode 100644 index 0000000..d367dd6 --- /dev/null +++ b/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) diff --git a/src/service-groups.adoc b/src/service-groups.adoc index e8117ed..4258022 100644 --- a/src/service-groups.adoc +++ b/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 diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index e7f9293..31042bd 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 @@ -81,7 +81,7 @@ The below table lists the services in this group: This service is used by the platform microcontroller to send the asynchronous message of type notification to the application processor. The message transfers the events defined by this service group. The events defined are -listed in the table below. +listed in the below table. [#table_base_srvgroup_events] .BASE Service Group Events @@ -160,7 +160,10 @@ the `MAJOR` and `MINOR` numbers. [#table_base_getimplversion_request_data] .Request Data -- NA +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== [#table_base_getimplversion_response_data] .Response Data @@ -211,7 +214,11 @@ unique and listed in the table <> [#table_base_getimplid_request_data] .Request Data -- NA +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== + [#table_base_getimplid_response_data] .Response Data @@ -250,7 +257,10 @@ version returned is a 32-bit composite number containing the `MAJOR` and [#table_base_getspecversion_request_data] .Request Data -- NA +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== [#table_base_getspecversion_response_data] .Response Data @@ -299,7 +309,10 @@ This service is used to get addition platform information if available. [#table_base_getplatinfo_request_data] .Request Data -- NA +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== [#table_base_getplatinfo_response_data] .Response Data @@ -341,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 @@ -358,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] @@ -388,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) @@ -402,7 +424,10 @@ service group. [#table_base_getbaseattrs_request_data] .Request Data -- NA +[cols="1", width=100%, align="center", options="header"] +|=== +| NA +|=== [#table_base_getbaseattrs_response_data] .Response Data @@ -437,8 +462,14 @@ service group. ! Bits ! Description -! [31:2] -! _Reserved_ and must be `0`. +! [31:3] +! _Reserved_, must be initialized to `0`. + +! [2] +! RPMI instance privilege level. + + 0b1: M-mode + 0b0: Non M-mode ! [1] ! EVENT_NOTIFICATION + @@ -456,17 +487,17 @@ service group. | 2 | FLAGS1 | uint32 -| _Reserved_ and must be `0`. +| _Reserved_, must be initialized to `0`. | 3 | FLAGS2 | uint32 -| _Reserved_ and must be `0`. +| _Reserved_, must be initialized to `0`. | 4 | FLAGS3 | uint32 -| _Reserved_ and must be `0`. +| _Reserved_, must be initialized to `0`. |=== ==== Service: BASE_SET_MSI (SERVICE_ID: 0x08) @@ -512,7 +543,7 @@ processor will take the wired interrupt. | 2 | MSI_DATA | uint32 -| 32-bit of MSI data. +| 32-bit MSI data |=== [#table_base_setmsi_response_data] @@ -529,7 +560,7 @@ processor will take the wired interrupt. | int32 | Return error code -[cols="5,5a", options="header"] +[cols="7,5a", options="header"] !=== ! Error Code ! Description @@ -538,8 +569,7 @@ processor will take the wired interrupt. ! MSI address and data are configured successfully. ! RPMI_ERR_NOT_SUPPORTED -! MSI is not supported. The implementation must use `BASE_GET_ATTRIBUTES` -service to discover this capability and then use this service. +! MSI is not supported. ! RPMI_ERR_INVALID_ADDR ! MSI address is not `4-byte` aligned. diff --git a/src/srvgrp-cppc.adoc b/src/srvgrp-cppc.adoc index 8ac18b8..a3e2e46 100644 --- a/src/srvgrp-cppc.adoc +++ b/src/srvgrp-cppc.adoc @@ -86,7 +86,8 @@ made through a fast-channel. If the fast-channels are implemented, the application processor will either write the desired performance level in case of normal mode or the minimum and maximum level in case of Autonomous (CPPC2) mode in the fast-channel. -Otherwise the application processor can call the service `CPPC_WRITE_REG` for the `DesiredPerformanceRegister` or `MinimumPerformanceRegister` and +Otherwise the application processor can call the service `CPPC_WRITE_REG` for the +`DesiredPerformanceRegister` or `MinimumPerformanceRegister` and `MaximumPerformanceRegister`. [#table_cppc_fastchan] @@ -680,4 +681,4 @@ may need to call this service again with the appropriate `START_INDEX` until the | HART_ID[N-1] | uint32 | Hart ID -|=== \ No newline at end of file +|=== diff --git a/src/srvgrp-system-reset.adoc b/src/srvgrp-system-reset.adoc index 91b7900..c9bf650 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 3c51651..67245a5 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"] @@ -149,7 +150,6 @@ if a `SUSPEND_TYPE` supports resume address. ! RPMI_ERR_INVALID_PARAM ! `SUSPEND_TYPE` is invalid. - !=== - Other errors <> @@ -166,13 +166,15 @@ if a `SUSPEND_TYPE` supports resume address. ! [31:2] ! _Reserved_ and must be `0`. -! [1] ! Resume Address Support + +! [1] +! Resume Address Support + If a `SUSPEND_TYPE` supports custom resume address which platform must configure for the resuming application processor. 0b1: Supported. 0b0: Not supported. -! [0] ! `SUSPEND_TYPE` Support +! [0] +! `SUSPEND_TYPE` Support 0b1: Supported 0b0: Not supported diff --git a/src/terms.adoc b/src/terms.adoc new file mode 100644 index 0000000..763c0a6 --- /dev/null +++ b/src/terms.adoc @@ -0,0 +1,11 @@ +== Terms and Abbreviations + +[cols="1,4", width=95%, options="header"] +|=== +| Term | Meaning + +| AP | Application Processor +| ACPI | Advanced Configuration and Power Interface Specification +| CPPC | Collaborative Processor Performance Control +| PuC | Platform Microcontroller +|=== \ No newline at end of file diff --git a/src/transport.adoc b/src/transport.adoc index 8b73f8a..3d19486 100644 --- a/src/transport.adoc +++ b/src/transport.adoc @@ -18,8 +18,8 @@ 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 of a set of application processors and a platform -microcontroller. A set of application processors can have multiple RPMI transport +a RISC-V privilege level a application processors and a platform +microcontroller. A application processors 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 <> shows different RPMI @@ -32,10 +32,10 @@ An RPMI transport instance consists of two logical bi-directional channels for message delivery. Each channel is capable to transfer messages in request-response pairs. A channel which transfers a request message from the application processor to the platform microcontroller and its -response/acknowledgement back to the application processor is called an A2P channel. -Similarly, the channel for request messages from the platform microcontroller to -the application processor is called a P2A channel. The P2A channel also transfers -notification messages to the application processor. +response/acknowledgement back to the application processor is called an A2P +channel. Similarly, the channel for request messages from the platform +microcontroller to the application processor is called a P2A channel. The P2A +channel also transfers notification messages to the application processor. An RPMI transport instance must implement the A2P channel. The P2A channel is optional if the system does not support requests and notification messages from @@ -70,9 +70,9 @@ hardware description mechanisms. image::highlevel-arch-queues.png[align="center"] ==== Shared Memory Queues -The RPMI shared memory based transport consists of four queues where each queue is -unidirectional. The type of message and the direction of message delivery is fixed -for each queue. +The RPMI shared memory based transport consists of four queues where each queue +is unidirectional. The type of message and the direction of message delivery is +fixed for each queue. .Shared Memory Transport Queues [cols="2,6,8a", width=100%, align="center", options="header"]