diff --git a/src/intro.adoc b/src/intro.adoc index cf1d035..f317b79 100644 --- a/src/intro.adoc +++ b/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,14 +40,14 @@ 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 defined 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. @@ -55,9 +55,9 @@ 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 <> below whereas the high-level architecture diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index b500822..3c579e8 100644 --- a/src/message-protocol.adoc +++ b/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 -<> below. The RPMI message header provide an +<> 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 diff --git a/src/rpmi-mpxy.adoc b/src/rpmi-mpxy.adoc index f4ca63d..d56d97c 100644 --- a/src/rpmi-mpxy.adoc +++ b/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. diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index dd0b262..e311349 100644 --- a/src/srvgrp-base.adoc +++ b/src/srvgrp-base.adoc @@ -95,7 +95,7 @@ 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. |=== @@ -156,7 +156,7 @@ in <>. ==== 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_getimplid_request_data] @@ -253,7 +253,7 @@ unique and listed in the <>. ==== 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 diff --git a/src/srvgrp-clock.adoc b/src/srvgrp-clock.adoc index 3da64e2..55427f0 100644 --- a/src/srvgrp-clock.adoc +++ b/src/srvgrp-clock.adoc @@ -146,7 +146,7 @@ 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 event notifications. ==== Service: CLK_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to CLOCK service diff --git a/src/srvgrp-cppc.adoc b/src/srvgrp-cppc.adoc index 0b9446d..2ed64ab 100644 --- a/src/srvgrp-cppc.adoc +++ b/src/srvgrp-cppc.adoc @@ -192,7 +192,7 @@ 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 event notifications. ==== Service: CPPC_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to `CPPC` diff --git a/src/srvgrp-device-power.adoc b/src/srvgrp-device-power.adoc index 1d9c62c..836c2d7 100644 --- a/src/srvgrp-device-power.adoc +++ b/src/srvgrp-device-power.adoc @@ -116,7 +116,7 @@ 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 event notifications. ==== Service: DPWR_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to DEVICE_POWER diff --git a/src/srvgrp-hart-state-management.adoc b/src/srvgrp-hart-state-management.adoc index 7324bb3..3118c44 100644 --- a/src/srvgrp-hart-state-management.adoc +++ b/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,7 +86,7 @@ this service group. [#hsm-notifications] ==== Notifications -This service group does not support any event for notification. +This service group does not support event notifications. ==== Service: HSM_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to the @@ -143,9 +143,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 diff --git a/src/srvgrp-management.adoc b/src/srvgrp-management.adoc index 64c8966..64674d8 100644 --- a/src/srvgrp-management.adoc +++ b/src/srvgrp-management.adoc @@ -47,12 +47,12 @@ 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 event notifications. ==== 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 +service group notifications. The platform can optionally support notifications +for events that may 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 <>. @@ -106,8 +106,8 @@ in <>. ==== 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 diff --git a/src/srvgrp-ras-agent.adoc b/src/srvgrp-ras-agent.adoc index bc1df68..5224c88 100644 --- a/src/srvgrp-ras-agent.adoc +++ b/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,7 +71,7 @@ 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 event notifications. ==== Service: RAS_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to RAS_AGENT service @@ -129,7 +129,7 @@ described in <>. |=== ==== 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] diff --git a/src/srvgrp-request-forward.adoc b/src/srvgrp-request-forward.adoc index efe09c0..5a41b45 100644 --- a/src/srvgrp-request-forward.adoc +++ b/src/srvgrp-request-forward.adoc @@ -48,7 +48,7 @@ service group: [#reqfwd-notifications] ==== Notifications -The <> below list the notification events +The <> below lists the notification events defined by the REQUEST_FORWARD service group. [#table_reqfwd_notification_events] diff --git a/src/srvgrp-system-reset.adoc b/src/srvgrp-system-reset.adoc index c9bf650..8c5169f 100644 --- a/src/srvgrp-system-reset.adoc +++ b/src/srvgrp-system-reset.adoc @@ -58,15 +58,16 @@ in the RISC-V SBI Specification cite:[SBI] for the `RESET_TYPE`. [#system-reset-notifications] ==== Notifications -This service group does not support any event for notifications. +This service group does not support event notifications. ==== Service: SYSRST_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) -This service allows the application processor to subscribe to `SYSTEM_RESET` -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 <>. +This service allows the application processor to subscribe to events defined +by the SYSTEM_RESET service group 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 +<>. [#table_sysreset_ennotification_request_data] .Request Data @@ -188,7 +189,7 @@ This service is used to initiate the system reset or system shutdown. The application processor must only request supported reset types, discovered using the `SYSRST_GET_ATTRIBUTES` service except for System Shutdown and System Cold Reset which are supported by default. Requesting an unsupported or -invalid state may result in the system entering a non-functional state. +invalid reset type may result in the system entering a non-functional state. [#table_sysreset_sysreset_request_data] .Request Data diff --git a/src/srvgrp-system-suspend.adoc b/src/srvgrp-system-suspend.adoc index c6c1ad4..e7b7934 100644 --- a/src/srvgrp-system-suspend.adoc +++ b/src/srvgrp-system-suspend.adoc @@ -50,11 +50,11 @@ in the RISC-V SBI Specification cite:[SBI] for the `SUSPEND_TYPE` definition. [#system-suspend-notifications] ==== Notifications -This service group does not support any event for notification. +This service group does not support event notifications. ==== Service: SYSSUSP_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) -This service allows the application processor to subscribe to `SYSTEM_SUSPEND` -service group defined events for notification. The platform can optionally +This service allows the application processor to subscribe to events defined by +the SYSTEM_SUSPEND service group for notification. 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 @@ -107,9 +107,10 @@ to them. Supported events are described in <>. |=== ==== Service: SYSSUSP_GET_ATTRIBUTES (SERVICE_ID: 0x02) -This service is used to discover the attributes of a suspend type. The attribute -flags for a suspend type indicate if a `SUSPEND_TYPE` is supported or not. Also, -if a `SUSPEND_TYPE` supports resume address. +This service is used to discover the attributes of a suspend type. The +attribute flags for a suspend type indicate whether a SUSPEND_TYPE is +supported. Additionally, the flags specify whether a SUSPEND_TYPE supports +a resume address. [#table_syssuspend_getsyssuspendattrs_request_data] .Request Data diff --git a/src/srvgrp-voltage.adoc b/src/srvgrp-voltage.adoc index 6563479..fc74d17 100644 --- a/src/srvgrp-voltage.adoc +++ b/src/srvgrp-voltage.adoc @@ -153,7 +153,7 @@ The following table shows the structure of the discrete format. [#voltage-notifications] ==== Notifications -This service group does not support any event for notification. +This service group does not support event notifications. ==== Service: VOLT_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) This service allows the application processor to subscribe to VOLTAGE service diff --git a/src/transport.adoc b/src/transport.adoc index 4f0cfc4..f03a4db 100644 --- a/src/transport.adoc +++ b/src/transport.adoc @@ -44,18 +44,19 @@ image::transport-bidirectional.png[400,400, align="center"] === Doorbell Interrupt An RPMI transport may also provide optional doorbell interrupts for application -processors and/or platform microcontroller to signal the arrival of new messages. +processors and/or the platform microcontroller to signal the arrival of new messages. This doorbell interrupt can be either a message-signaled interrupt (MSI) or a wired interrupt. The RPMI implementations may ignore the doorbell mechanism of -RPMI transport and always use polling mechanism to check arrival of new messages. +RPMI transport and always use a polling mechanism to check the arrival of new +messages. ==== A2P Doorbell The A2P doorbell is a signal for new messages from the application processors (APs) to the platform microcontroller (PuC). The platform should support A2P doorbell interrupt triggering from application -processors through a write operation or a read-modify-write sequence on a -memory-mapped register which can be easily discovered by the application +processors through either a write operation or a read-modify-write sequence on a +memory-mapped register, which can be easily discovered by the application processors using hardware description mechanisms such as device tree or ACPI. ==== P2A Doorbell @@ -72,8 +73,8 @@ the MSI on the platform microcontroller side using RPMI messages defined by the `BASE` service group. === Fast-channels -Fast-channels are special shared memory based channels for use cases that -require lower latency and faster processing of requests from application +Fast-channels are special shared memory-based channels used in scenarios +requiring lower latency and faster processing of requests from application processors to the platform microcontroller. The layout and request format of fast-channels are service group specific @@ -171,15 +172,15 @@ platform. The requirement of `power-of-2` slot size with minimum value of `power-of-2` value. The slots of the RPMI shared memory queue are assigned sequentially increasing -indices starting with `0`. The slot at index `0` is referred to as `head slot` -and the slot at index `1` is referred to as `tail slot`. The remaining `(M - 2)` -slots of the RPMI shared memory queue are message slots. The first `4 bytes` -of the head slot is used as the `head` of the circular queue which contains -a `slot index - 2` value pointing to the message slot from where the next -message can be dequeued. The first `4 bytes` of the tail slot is used as the -`tail` of the circular queue which contains a `slot index - 2` value pointing -to the message slot from where the next message can be enqueued. The pictorial -view of the RPMI shared memory queue internals is shown in the +indices starting with `0`. The slot at index `0` is referred to as the +`head slot` and the slot at index `1` is referred to as the `tail slot`. The +remaining `(M - 2)` slots of the RPMI shared memory queue are message slots. +The first `4 bytes` of the head slot is used as the `head` of the circular +queue which contains a `slot index - 2` value pointing to the message slot from +where the next message can be dequeued. The first `4 bytes` of the tail slot is +used as the `tail` of the circular queue which contains a `slot index - 2` value +pointing to the message slot from where the next message can be enqueued. The +pictorial view of the RPMI shared memory queue internals is shown in the <> below. NOTE: The requirement of keeping `head` and `tail` in separate slots is @@ -213,7 +214,7 @@ queues must be of the same size hence equal number of slots (or queue capacity). The size of each RPMI shared shared queue must be a multiple of the slot size. NOTE: A platform should provide sufficient shared memory for all RPMI shared -memory queues such that the number of slots (queue capacity) does not become +memory queues so that the number of slots (queue capacity) does not become a bottleneck in message communication. It is recommended that the number of slots in queues belonging to A2P channel should be proportional to the number of application processors accessing the A2P channel.