diff --git a/src/intro.adoc b/src/intro.adoc index f94f1ae..b57a257 100644 --- a/src/intro.adoc +++ b/src/intro.adoc @@ -1,14 +1,14 @@ [[intro]] == Introduction -This document describes RISC-V Platform Management Interface (RPMI), which is +This document describes the RISC-V Platform Management Interface (RPMI), which is an extensible interface to manage and control the system using a dedicated microcontroller. Systems today pose challenges in terms of manageability and controllability where the OS may have to support a variety of hardware which -can be different in design and devices connected. The extra complexity and +can be different in design and connected devices. The extra complexity and demand to manage and control the system along with executing compute workloads -is challenging for Application Processors running the OS. To mitigate this, +is challenging for the Application Processors running the OS. To mitigate this, systems today contain one or more Platform Microcontrollers which abstract various platform specific system management and control related tasks. RPMI enables the communication between the application processors and the -Platform micro-controllers. It abstracts the system complexity and provides a message based interface for system management and control. +Platform micro-controllers. 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 Microcontroller. It can support multiple Application Processors and multiple Platform Microcontrollers. @@ -27,7 +27,7 @@ of new features and functions. This feature simplifies the integration of new co *Transport*: Describes the mechanism by which the messages are exchanged between the Application Processors and Platform Microcontrollers. -*Messaging Protocol*: Provides Messaging Interface between Application +*Messaging Protocol*: Provides the Messaging Interface between the Application Processors and 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 @@ -38,13 +38,13 @@ RPMI currently provides message interfaces to manage power, voltage, performance, idle states etc, along with extensibility for vendors to add their own interfaces. -Application Processor and A.P are used interchangeably in this document. +Application Processor and A.P are used interchangeably throughout this document. Similarly, Platform Microcontroller and PuC are used interchangeably. .High Level Architecture image::highlevel-arch.png[width=800,height=800] -An RPMI agent is an implementation instance of RPMI Messaging Protocol and Transport. It is necessary to implement the AP side RPMI agent for most RPMI services in M-mode. While it may be possible to implement the AP side RPMI +An RPMI agent is an implementation instance of the RPMI Messaging Protocol and Transport. It is necessary to implement the AP side RPMI agent for most RPMI services in M-mode. While it may be possible to implement the AP side RPMI agent in S-mode for some RPMI services, an M-mode RPMI agent also enhances security. diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index 2ee2dc4..152f3c7 100644 --- a/src/message-protocol.adoc +++ b/src/message-protocol.adoc @@ -53,7 +53,7 @@ acknowledgment must follow byte ordering defined by the RPMI transport. ==== Message Header Message header has a fixed size of `12-byte` which further contains three -fields each of `4-byte`. Each message gets a unique identity in a RPMI instance +fields each of `4-byte`. Each message gets a unique identity in an RPMI instance through its header. Both REQUEST and ACKNOWLEDGEMENT messages have the same message format. @@ -66,7 +66,7 @@ image::message-format.png[700,900] |=== | Word | Name | Description | 0 | *TOKEN* | Message identifier. Unique to each -request - acknowledgement transaction for a RPMI implementation instance. +request - acknowledgement transaction for an RPMI implementation instance. In case of Notifications, `SERVICE_ID` and `MESSAGE_TYPE` for notification messages are fixed which will contribute to the unique identity of the message in that RPMI instance implementation. diff --git a/src/srvgrp-base.adoc b/src/srvgrp-base.adoc index 5b71629..bb1e883 100644 --- a/src/srvgrp-base.adoc +++ b/src/srvgrp-base.adoc @@ -183,7 +183,7 @@ Get version of the implemented RPMI specification |=== ==== Service: *GET_HW_INFO* -This service is used to retrieve the Vendor ID and Name of the Vendor having a +This service is used to retrieve the Vendor ID and Name of the Vendor having an RPMI implementation on PuC. Each vendor will be assigned a unique Vendor ID. [#table_base_gethwinfo_request_data] .Request Data diff --git a/src/transport.adoc b/src/transport.adoc index ac38069..a234068 100644 --- a/src/transport.adoc +++ b/src/transport.adoc @@ -4,39 +4,39 @@ RPMI Transport is the abstraction over a physical medium used to send and receive messages between an Application Processor and Platform Microcontroller enabling bidirectional communication. -A RPMI transport instance provides a bidirectional communication channel between +An RPMI transport instance provides a bidirectional communication channel between a privilege level of a set of APs and one PuC. There can be multiple RPMI transport instances between a set of APs and one PuC. For example: there can be a separate transport instance between each privilege level of APs and one PuC. A platform can also have multiple PuCs with each having its own set of -RPMI transport to communicate with APs. The _Figure 1.2_ above shows different +RPMI transport to communicate with the APs. The _Figure 1.2_ above shows different topologies of RPMI transport. -The physical medium of a RPMI transport can be shared memory or I2C or SPI or +The physical medium of an RPMI transport can be shared memory or I2C or SPI or some other medium. This specification only defines a shared memory based RPMI transport but a platform can define its own RPMI transport. RISC-V S-Mode/M-Mode clients are responsible for the packing of the messages as per the message binary format requirements described later and sharing the message via the transport layer. The transport layer abstracts the mechanism of -how the message is physically delivered between Application Processor and -Platform Microcontroller or vice versa. +how the message is physically delivered between the Application Processor and +the Platform Microcontroller or vice versa. .Bidirectional Communication image::transport-bidirectional.png[400,400] === Doorbell Interrupt -A RPMI transport may also provide doorbell interrupts for either Application +An RPMI transport may also provide doorbell interrupts to either Application Processors or Platform Microcontrollers or both to signal new messages. -The doorbell mechanism is optional for a RPMI transport and implementations can +The doorbell mechanism is optional for an RPMI transport and implementations can always use a polling mechanism for checking the arrival of messages. -The doorbell interrupt from APs to PuC can be a MSI or a wired interrupt with a +The doorbell interrupt from the APs to the PuC can be a MSI or a wired interrupt with a RPMI transport specific way to trigger the interrupt. -The doorbell interrupt from PuC to APs can be either a wired interrupt or -message signaled interrupt (MSI). If the doorbell interrupt from PuC to APs is -a wired interrupt then RPMI transport must define a way to trigger the +The doorbell interrupt from the PuC to the APs can be either a wired interrupt or +message signaled interrupt (MSI). If the doorbell interrupt from the PuC to the APs is +a wired interrupt then the RPMI transport must define a way to trigger the interrupt. If the doorbell interrupt from PuC to APs is a MSI then RPMI messages can be used by APs to configure the MSI. @@ -44,7 +44,7 @@ can be used by APs to configure the MSI. The physical memory of the RPMI shared memory transport can be either a device memory or dedicated SRAM or some portion of DRAM. The RPMI shared memory transport does not specify where the shared memory resides, but it should be -accessible from both Application Processor and Platform Microcontroller and +accessible from both the Application Processor and the Platform Microcontroller and all necessary configuration needs to be done to make sure that side effects related to caching or anything else do not happen. @@ -61,7 +61,7 @@ sequence to a memory mapped register. This read-modify-write mechanism can be discovered by APs via DT or ACPI using properties such as register physical address, mask, and value. -The doorbell interrupt from PuC to APs for RPMI shared memory transport is +The doorbell interrupt from the PuC to the APs for RPMI shared memory transport is platform specific. The subsequent sections describe the layout and attributes of shared memory @@ -88,8 +88,8 @@ and ==== Layout of Shared Memory The shared memory RPMI Transport defines four shared memory based queues for bidirectional synchronous/asynchronous communication between an AP and PuC. -The detailed layout of shared memory and queues is shown in Figure 2.1. All -queues in shared memory are contiguous and of equal size. Sequence of queues is +The detailed layout of the shared memory and queues is shown in Figure 2.1. All +queues in the shared memory are contiguous and of equal size. Sequence of the queues is arranged such that queues which enable Request-Acknowledgement for a side either AP to PuC or vice versa are together. @@ -118,8 +118,8 @@ image::highlevel-flow.png[500,500] image::highlevel-arch-queues.png[] Each queue contains *M* number of slots and each slot stores a single message. -Slot size must be sufficient to store the biggest message in the framework. -Shared memory also contains the head and tail for the enqueuing and dequeuing +The slot size must be sufficient to store the biggest message in the framework. +The shared memory also contains the head and tail for the enqueuing and dequeuing of the messages for each queue. The RPMI specification expects a minimum size of `64 bytes` for each slot but bigger slots may also work depending on the implementation. @@ -132,17 +132,17 @@ Head will be used to dequeue the message and Tail will enqueue. Head and Tail will be owned and incremented by only a single entity depending on the role of that entity, whether that entity is enqueuing or dequeuing. -For example, on the A2P channel, Application Processor will enqueue the message -so it will own and increment the Tail, similarly, Platform Microcontroller will -own the head to dequeue the messages and only Platform Microcontroller will +For example, on the A2P channel, the Application Processor will enqueue the message +so it will own and increment the Tail, similarly, the Platform Microcontroller will +own the head to dequeue the messages and only the Platform Microcontroller will increment the head. Once the reader dequeues a message from the slot, it has to mark that slot to be usable by the writer to enqueue further messages into that slot. Message header flags are used to mark a message as invalid which makes that slot free to use. -Like a normal circular queue, it can either be empty, full or have valid -messages. Enqueue operation will check if the queue is not full by checking if +Like a normal circular queue, it can be either be empty, full or have valid +messages. The Enqueue operation will check if the queue is not full by checking if the head is equal to the tail and the slot referenced by the current tail has a valid message. Similarly, the dequeue operation will check for the empty state by validating if the slot referenced by the current head has an invalid message.