message-protocol.adoc

Messaging Protocol

The RPMI messaging protocol includes all the RPMI messages exchanged over a RPMI transport channel.

Message Types

The RPMI messaging protocol defines three types of RPMI messages namely: REQUEST, ACKNOWLEDGEMENT and NOTIFICATION. The RPMI Message Types below summarize all RPMI message types.

An RPMI request message represents a specific control and management task which needs to be performed and it is also referred to as an RPMI service. Multiple related RPMI services are grouped logically into an RPMI service group such as Clock, Voltage, Performance, etc. Depending on the RPMI service, a RPMI request message may carry data required to perform the control and management task. An RPMI request message may have an associated response which is send back as an RPMI acknowledgement message on the same RPMI transport channel. The RPMI acknowledgement message carries the status and optional response data from an RPMI request after it has been processed.

An RPMI request message which has an associated RPMI acknowledgement message is referred to as a NORMAL REQUEST otherwise it is referred to as a POSTED REQUEST.

An RPMI notification message is an asynchronous message from the platform microcontroller to the application processors which is used to inform the later about certain events that have occurred in the system. There is no response required for an RPMI notification message from the application processors.

Table 1. RPMI Message Types

Message Type	Message Subtypes	Description
REQUEST	NORMAL REQUEST Request with Acknowledgement. POSTED REQUEST Request without Acknowledgement.	Messages for requesting a service from the platform microcontroller.
ACKNOWLEDGEMENT	Not applicable	Response message corresponding to a NORMAL REQUEST message.
NOTIFICATION	Not applicable	Asynchronous messages from the platform microcontroller representing system events.

Message Format

An RPMI message consists of a fixed 8-byte message header followed by a variable sized optional message data as show in the RPMI Message Format below. The byte ordering of an RPMI message is defined by the underlying RPMI transport.

Figure 1. RPMI Message Format

Message Layout Tables

The RPMI message header and message data are split into multiple words, where each word is 4-byte wide and indexed starting from 0. The RPMI message layout is presented throughout the RPMI specification in the form of tables as shown in the Message Layout Table Example below. Some of the columns listed below may be omitted in the layout tables if not required.

Table 2. Message Layout Table Example

Word	Name	Type	Description
Index of the 4-byte word at which the field starts in the message header or message data.	Name of the field. Name may be omitted if not required.	Type of field, eg: int32 or uint32, etc.	Description and interpretation of the field.

Message Header

The layout of the 8-byte wide RPMI message header is shown in the RPMI Message Header below. The RPMI message header provide a unique identity to the corresponding RPMI message withing an RPMI context.

Table 3. RPMI Message Header

Word	Description
0	Bits Description [31:24] FLAGS FLAGS[7:4]: Reserved and must be 0. FLAGS[3]: DOORBELL 0b0: Doorbell interrupt is enabled. 0b1: Doorbell interrupt is disabled. FLAGS[2:0]: MESSAGE_TYPE 0b000: NORMAL_REQUEST 0b001: POSTED_REQUEST 0b010: ACKNOWLEDGEMENT 0b011: NOTIFICATION 0b100 - 0b111: Reserved for future use. [23:16] SERVICE_ID 8-bit wide identifier representing a RPMI service. This identifier is unique within a given RPMI service group. [15:0] SERVICEGROUP_ID 16-bit wide unique identifier representing a RPMI service group.
1	Bits Description [31:16] TOKEN 16-bit sequence number for a RPMI message. [15:0] DATALEN Stores the size of the message data in bytes. The value stored in this 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 acknowledgement message must have the same values as corresponding fields in the RPMI request message. The DATALEN 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 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 maximum message data size of an RPMI message depends on the underlying RPMI transport implementation.

The message data carries different information based on the RPMI message type:

• An RPMI request message carries data required to perform the control and management task

• An RPMI acknowledgement message carries the status and optional response data

• An RPMI notification message carries an array of RPMI events

The message data format for RPMI request message and RPMI acknowledgement message is defined separately for each RPMI service. The message data format for RPMI notification message is defined in the Notifications.

An RPMI acknowledgement message must have a signed STATUS field as the first 4-byte word of the message data containing an error code defined in the Possible Error Codes. An RPMI service where the response data exceeds the maximum message data size can use multipart RPMI acknowledgement messages.

Notifications

The platform microcontroller can use RPMI notification message to notify application processors about system events which are also referred to as RPMI events. An RPMI notification message has no associated response or acknowledgement from application processors. Multiple RPMI events can be packed into a single RPMI notification message depending on the space available in the message data. Each RPMI event may have additional data associated with it based on the type of RPMI event. Any action required for handling an RPMI event depends on the application processors. The format of an RPMI notification message in shown in the RPMI Notification Message Format below.

The RPMI events are defined separately for each RPMI service group. An RPMI service group must have a ENABLE_NOTIFICATION service with a fixed SERVICE_ID=0x01 which can be used by the application processors to enable or disable notification messages for a particular RPMI event defined by the RPMI service groups. By default, notifications are disabled for all RPMI events of an RPMI service group. The platform microcontroller only sends RPMI notification messages for RPMI events which are enabled by the application processors. If multiple RPMI events are supported by an RPMI service group then the application processors must enable to each RPMI event individually.

Figure 2. RPMI Notification Message Format

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 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 message depends on the maximum RPMI message data size. The DATALEN field in the RPMI message header represents the aggregate size of all RPMI events included in RPMI message data.

The Event Format below defines the format of an RPMI event whereas the Event Header below shows a pictorial view of an RPMI event. The format of the event data for each RPMI event is defined separately by an RPMI service group. If multiple RPMI events are packed into a single RPMI notification message then the ordering of RPMI events within the RPMI notification message is implementation defined.

Table 4. Event Format

Word	Name	Description
0	EVENT_HDR	32-bit field represents a single event. Bits Description [31:24] Reserved and must be 0. [23:16] EVENT_ID Unique identifier for an event in a service group. [15:0] EVENT_DATALEN 16-bit field to store event data size in bytes.
1	EVENT_DATA	Event data whose size is specified by EVENT_DATALEN

Figure 3. Event Header

Possible Error Codes

The RPMI Error Codes below lists the error codes which can be returned by an RPMI service in the STATUS field of the RPMI acknowledgement message.

Table 5. RPMI Error Codes

Name	Error Code	Description
RPMI_SUCCESS	0	Service has been completed successfully.
RPMI_ERR_FAILED	-1	Failed due to general error.
RPMI_ERR_NOT_SUPPORTED	-2	Service or feature is not supported.
RPMI_ERR_INVALID_PARAM	-3	One or more parameters passed are invalid.
RPMI_ERR_DENIED	-4	Requested operation denied due to insufficient permissions or failed dependency check.
RPMI_ERR_INVALID_ADDR	-5	One or more addresses are invalid.
RPMI_ERR_ALREADY	-6	Operation already in progress or state changed already for which the operation was performed.
RPMI_ERR_EXTENSION	-7	Error in extension implementation that violates the extension specification or the extension version mismatch.
RPMI_ERR_HW_FAULT	-8	Failed due to hardware fault.
RPMI_ERR_BUSY	-9	Service cannot be completed due to system or device is busy.
RPMI_ERR_INVALID_STATE	-10	Invalid state.
RPMI_ERR_BAD_RANGE	-11	Bad or invalid range.
RPMI_ERR_TIMEOUT	-12	Failed due to timeout.
RPMI_ERR_IO	-13	Input/Output error.
RPMI_ERR_NO_DATA	-14	Data not available.
	-15 to -127	Reserved
	< -127	Vendor or Implementation specific.