diff --git a/images/event-header.png b/images/event-header.png new file mode 100644 index 0000000..b7686fc Binary files /dev/null and b/images/event-header.png differ diff --git a/images/message-format.png b/images/message-format.png index 32459bb..ed22de0 100644 Binary files a/images/message-format.png and b/images/message-format.png differ diff --git a/images/notification-format.png b/images/notification-format.png index 193150a..79138c3 100644 Binary files a/images/notification-format.png and b/images/notification-format.png differ diff --git a/src/message-protocol.adoc b/src/message-protocol.adoc index 958d222..6b5ef80 100644 --- a/src/message-protocol.adoc +++ b/src/message-protocol.adoc @@ -10,235 +10,270 @@ ifndef::rootpath[] endif::rootpath[] == Message Protocol -Message Protocol supports a variety of system management and control tasks and -provides a message interface for such tasks. Each message which does a specific -task is called Service. Multiple messages or Services are grouped into Service -Groups like Clock, Voltage, Power management, etc. A service call results in a -message request being sent to the Platform Microcontroller for a specific -purpose. Each service may have an associated response message which enables the -Platform Microcontroller to provide the status or information for that request. +The RPMI protocol defines the message format and different messages +for system management and control tasks. Each message is called a *Service* +designated to perform a specific task. Multiple similar services are grouped +logically into a *Service Group* like Clock, Voltage, Power management, etc. +A service call results in a request message being sent on a transport +channel from the application processor to the platform microcontroller or +vice-versa. If the request has an associated response, the platform +microcontroller after processing and servicing the request can send the +response message with status and additional data. + + .Service Groups and Services image::servicegroups-service.png[400,400] === Message Types -A message can either be a request or an acknowledgement in response to a request -received by an client. +There are three categories of messages supported - *Request*, *Acknowledgement* +and *Notification*. ==== REQUEST -Messages which convey a command to the other entity/client, usually from the AP -from either S-Mode/M-mode client to the Platform Microcontroller (it may also send -REQUESTs to AP, but there are no use cases yet). Each command will have a -certain action that the Platform Microcontroller will take and it may -acknowledge the AP with another message in return which may contain some data or -just the status code. - -Not every request needs to be acknowledged because the action taken by the -Platform Microcontroller may leave the AP in a state where it is not able to -wait for the acknowledgment. For example, in the case when the AP asks the -Platform Microcontroller to perform a Reset, where an acknowledgment would not -be meaningful. - -* *Normal Requests*: Requests with Acknowledgement -* *Posted Requests*: Requests without Acknowledgement +Message that convey a command is called a request message. Each command is +associated with an action which the platform microcontroller will take and may +acknowledge the application processor with a response message if supported by +that request message. The response message will carry status code and +additional data if required. + +Not every request message needs an acknowledgement due to the nature of the +action requested by the application processor that may leave the application +processor in a state where it cannot receive the acknowledgment. For example, +when the application processor requests the platform microcontroller to +suspend the system or reset the application processor itself. + +Request messages based on the acknowledgement are further categorized as - + +===== Normal Requests +Request message with Acknowledgement. + +===== Posted Requests +Request message without Acknowledgement ==== ACKNOWLEDGEMENT -Messages sent from Platform Microcontroller to AP (or vice-versa) in a response -to any previous message request. Acknowledgment is dependent on the service and -each service dictates if acknowledgment is mandatory or not. +Acknowledgement is a message which carries the status of the request message +after it has been processed successfully. The acknowledgement messages may +also carry additional data depending on the service. -==== NOTIFICATIONS -Notifications are messages which are sent asynchronously from PuC to AP to -notify about the events happening in the system related to various service -groups. Notifications are covered in detail in below <>. +==== NOTIFICATION +Notification is a message sent asynchronously from the platform +microcontroller to the application processor to notify about the events +happened in the system related to various service groups. === Message Format -On the AP side, each call to a service results in a message request to the PuC. -The type of message depends upon the type of service and to which group that -particular service belongs. Each message, whether its Request or -Acknowledgement, consists of two main parts - Message Header and Data. +Each message regardless of its type consists of two parts - Message Header +and Data. The size of the message header is fixed, but the data size is +implementation-defined, based on the layout of transport queues. All the +messages must follow the byte order as defined by the RPMI transport. -Size of message header is fixed, but size of data is implementation defined, -based on the transport queues layout. All fields in the request and -acknowledgment must follow byte ordering defined by the RPMI transport. +image::message-format.png[700,900] -==== 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 an RPMI instance -through its header. +==== Message Layout Tables +The message layout which includes header and data is represented in the form +of tables as shown below. Some of the columns listed below may be omitted from +some of the tables as required. -Both REQUEST and ACKNOWLEDGEMENT messages have the same message format. +[#table_message_layout_table_example] +.Message Layout Table Example +[cols="4, 3, 3, 3", width=100%, align="center", options="header"] +|=== +| Word +| Name +| Type +| Description + +| Each message is split into multiple *Words* where each word is of `4-byte` +and indexed starting from `0`. This column represents the index of that word. +| Name of the word. Name may be omitted if not required. +| Type of field, eg: int32 or uint32, etc +| Description and interpretation of the fields present in the word. +|=== -image::message-format.png[700,900] +==== Message Header +The message header of `8-byte` has a fixed layout that consists of multiple +fields. Each message gets a unique identity in an RPMI instance through its +header. [#table_message_header] .Message Header [cols="2,3,15a", width=100%, align="center", options="header"] |=== -| Word | Name | Description -| 0 | *TOKEN* | Message identifier. Unique to each -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. -| 1 | *MESSAGE_ID* | -[cols="1,7a"] +| Word +| Name +| Description + +| 0 +| +| [cols="1,7a", options="header"] !=== -! *Bits* ! *Description* -! *[31:28]* ! *FLAGS* - - FLAGS[3]: RESERVED. - - FLAGS[2]: DOORBELL - 0: Doorbell interrupt enabled. - 1: Doorbell interrupt disabled. PuC will not ring the doorbell to AP. - This can be used by AP software in case of doorbell interrupts causing spurious interrupts while its also being polled. - - FLAGS[1:0]: MESSAGE_TYPE - 0b00: NORMAL_REQUEST - 0b01: POSTED_REQUEST - 0b10: ACKNOWLEDGEMENT - 0b11: NOTIFICATION -! *[27:8]* ! *SERVICEGROUP_ID* + -Services alike are grouped into Service Groups and each group is identified by `SERVICEGROUP_ID` which is a `20 bits` identifier. -! *[7:0]* ! *SERVICE_ID* + -`8-bits` identifier from LSB in the message identifier word, Services are the -functions which, when called, result in different message requests for different control and management tasks meant for Platform Microcontroller. Each service is identified by a `SERVICE_ID` +! Bits +! Description + +! [31:24] +! FLAGS + + FLAGS[7:4]: RESERVED. + + 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, must be 0. + +! [23:16] +! SERVICE_ID + +`8-bit` identifier which represents a service(message). This identifier is +unique in a particular service group. + +! [15:0] +! SERVICEGROUP_ID + +Services alike are grouped into service groups and each group is identified by +`SERVICEGROUP_ID` which is a `16-bit` identifier. !=== -| 2 | *DATALEN* | Encodes the size of the data in the message, data will also be in `32 bits` chunks. -If there is no data, then it must be initialized to zero. -|=== -Once a message request has been serviced and that service is of type Normal -Request which requires an acknowledgement, PuC must preserve the `TOKEN`, -`SERVICEGROUP_ID`, `SERVICE_ID` from the normal request message header and use -these fields in acknowledgement message header. PuC must mark the message type -in the `FLAGS` and also according to the data expected in the acknowledgement it -may change `DATALEN` in the message header. In case of notifications, PuC will -generate the `TOKEN` and set the `SERVICEGROUP_ID` and fixed `SERVICE_ID=0x00` -assigned for each notification message in every service group and set the -`FLAGS` with notification `MESSAGE_TYPE` marked. Notification messages do not -require any acknowledgement and how data from notification messages is utilized -is dependent on the implementation. - -==== Message Data -Request message data format and acknowledgement data format depends on each -service and details are present with each service section below in their -respective service groups. Size of data each message can accommodate depends on -the transport queues slot size. This specification already defines the data -layout for each size. For few services where the data exceeds the size which a -single message can accommodate, multipart messages are used. - -Message data formats in this specification are tabulated with a list of `32 bits` -wide Word in each of the service groups section as depicted below. - -[#table_message_hdr_data_layout] -.Message Header & Data Layout -[cols="3, 2, 4, 4", width=100%, align="center", options="header"] -|=== -| Word | Name | Type | Description -| Word index in message DATA field | Name of field | Type of field, eg: int32 or uint32, etc | Description and interpretation of the field +| 1 +| +| [cols="1,7a", options="header"] +!=== +! Bits +! Description + +! [31:16] +! TOKEN + +`16-bit` sequence number for a message. Used along with `SERVICEGROUP_ID` and +`SERVICE_ID` to match the request message with its corresponding +acknowledgement message. + +! [15:0] +! DATALEN + +Stores the size of the message data in bytes. Value stored in this field must +be multiple of `4-byte` or `0` if no data is present. +!=== |=== -The data in acknowledgment at least should contain a `32 bits` `STATUS` code. -Apart from status code, an acknowledgement may encode more data as response to -the request message and details are subsequently present in each service section -below. +In case of normal request messages which require acknowledgement, the +platform microcontroller must preserve the `TOKEN`, `SERVICEGROUP_ID`, +`SERVICE_ID` from the normal request message header and use these fields in the +acknowledgement message header. The platform microcontroller must mark the +message type as `ACKNOWLEDGEMENT` in the `FLAGS` and update the `DATALEN` +depending on the data supported by that acknowledgement. +In case of notification, the platform microcontroller will generate the `TOKEN` +and set the `SERVICEGROUP_ID` and fixed `SERVICE_ID=0x00` assigned for each +notification message in each service group and set the +`FLAGS` with message type as `NOTIFICATION`. The notification messages do not +require any acknowledgement. +==== Message Data +Message data in any message type if present must be multiple of `4-byte`. +Data format for the request and acknowledgement messages depends on each +service and details are present with each service section in their +respective service groups. The maximum size of data each message can +accommodate depends on the transport `slot-size` attribute. Services where the +data exceeds the size that a single message can accommodate, multipart messages +can be used. Some request messages may not have associated data and in that +case their `DATALEN` field in the message must be `0`. + +Acknowledgement message data contains `a 32-bit` `STATUS` code which represents +the error code. +Acknowledgement message may contain more data apart from the `STATUS` code +depending on the corresponding request message. === Notifications -Notifications are the messages from Platform Microcontroller to Application -Processor to notify about events taking place in the system. Notifications are -posted messages which do not require acknowledgement from the recipient. Events -can include the system states, power states, errors/faults in the system etc. -Action taken on behalf of any event notification is completely dependent on the -AP and they can be ignored. Platform Microcontroller may combine multiple events -into a single message depending on the available space in the message data. -Individual events may also have additional data associated. <> -shows the notification message format. - -Each service group will have a notification service with fixed `SERVICE_ID=0x00` -across every service group. Notifications are sent from PuC to AP with events -and associated data if any. AP has to subscribe to the supported events in each -service group to receive these notification messages. A notification message may -have one or more events with their associated data. -This service with `SERVICE_ID=0x00` is reserved in each service group even if -the service group does not support notifications or need to support any events. -These notifications will only be sent for those events only for which the AP -subscribes. When there are multiple events supported in each service group, AP -has to subscribe to each event and has to make multiple calls to notification -enable service. - -Notifications enable service is also present in each service group even if that -service group does not support notifications or implement any event support. - -Every event will have an Event Header which consists of two fields to identify -an event - `EVENT_ID (12 bits)` and `EVENT_DATALEN (20 bits)`. Events may have -data associated, if present, must be multiple of 4 bytes. - -The number of events which can be accommodated in the message data depends on -the message data field size. The `DATALEN` field in the message header will -encode how much size data is present in the message which is the aggregate of -all events. Then AP must parse each event and its data according to the Event -header. - -Event data and its format depend on the service group and details are present in -respective service group sections. +Notification messages are asynchronous messages that notify about the events +that occurred in the system. A notification message is a posted message which +does not require an acknowledgement. A notification message may combine +multiple events into a single message depending on the available space in the +message data. Individual events may also have additional data associated with +them. Any action required on behalf of any event notification is dependent on +the application processor. <> shows the notification +message format. + +Each service group has a service with a fixed `SERVICE_ID=0x00` to subscribe +to events. By default the event notification is disabled for each service +group and the application processor must subscribe to the supported events in +each service group to receive notification messages. Notification messages are +only sent for events to which the application processor has subscribed to. If +multiple events are supported in each service group, the application processor +must subscribe to each event individually through reserved +`ENABLE_NOTIFICATION` service in each service group. [#img-notification-format] .Notification Format image::notification-format.png[500,600] +==== Events +An event consists of a header containing two fields: `EVENT_ID (8-bit)` +and `EVENT_DATALEN (16-bit)`. +An event may also have associated data. If the event data is present, it must +be a multiple of `4-byte`. + +The number of events that can be stored in a notification message depends upon +the maximum message data size. The `DATALEN` field in the message header +represents the data size in bytes present in the message which is the aggregate +of all event sizes. The application processor must parse each event and +its data according to the event header. + +Event data and its format is specific to a service group and details are +given in the respective service group sections. + +[#img-event-header] +.Event Header +image::event-header.png[800,800] + [#table_notification_message_format] .Notification Message Format [cols="3,2,7a", width=100%, align="center", options="header"] |=== | Word | Name | Description -| 0 | *EVENT_HDR* | Event Header is a `32 bits` field which represents a -single event metadata +| 0 | *EVENT_HDR* | `32-bit` field represents a single event. [cols="1,7a"] !=== -! *Bits* ! *Description* -! *[31:20]* ! *EVENT_ID* + +! *Bits* ! *Description* +! [31:24] ! Reserved and must be initialized to `0`. +! [23:16] ! *EVENT_ID* + Unique identifier for an event in a service group. -! *[19:0]* ! *EVENT_DATALEN* + -20 bits field to encode the number words (`32 bits`) chunks of event data. +! [15:0] ! *EVENT_DATALEN* + +`16-bit` field to store event data size in bytes. !=== -| 1 : (*EVENT_DATALEN* - 1) | *EVENT_DATA* | Event Data +| 1:(*EVENT_DATALEN/4*) | *EVENT_DATA* | Event Data |=== -Above table represents the format for one event with its data. Subsequent events -will be packed in the same manner. This spec does not define any ordering of +The table above shows the format for an event and its data. Subsequent events +are packed in the same way. This specification does not define the order of packing of multiple events and its implementation defined. -=== Return Status Codes -Below table lists all the error codes which can be returned by any service. Few -probable error codes for each service are also provided in each service response -message format. AP must check for each error code and action based on that is -dependent on the AP. +=== Return Error Codes +The table below lists all the error codes that can be returned by any service +in the in the `STATUS` word of the acknowledgement message. [#table_error_codes] .Return Status Codes [cols="4, 2, 6", width=100%, align="center", options="header"] |=== | Name | Status Code | Description -| RPMI_SUCCESS | 0 | Successful operation +| RPMI_SUCCESS | 0 | Service has been completed successfully | RPMI_ERROR_FAILED | -1 | Failed due to general error | RPMI_ERROR_NOT_SUPPORTED | -2 | Service or feature not supported | RPMI_ERROR_INVALID_PARAMETER | -3 | One or more parameters passed are invalid -| RPMI_ERROR_DENIED | -4 | Requested operation denied due to insufficient permissions +| RPMI_ERROR_DENIED | -4 | Requested operation denied due to +insufficient permissions | RPMI_ERROR_NOT_FOUND | -5 | Requested resource not found | RPMI_ERROR_OUT_OF_RANGE | -6 | Index out of range | RPMI_ERROR_OUT_OF_RESOURCE | -7 | Resource limit reached | RPMI_ERROR_HW_FAULT | -8 | Operation failed due to hardware fault. | RPMI_ERROR_BUSY | -9 | System is currently busy and cannot -respond to request +respond to requests | RPMI_ERROR_TIMEOUT | -10 | Operation timed out | RPMI_ERROR_COMMS | -11 | Error in communication | RPMI_ERROR_ALREADY | -12 | Operation already in progress or state -changed already for which the operation was carried out. +changed already for which the operation was performed. | RPMI_ERROR_EXTENSION | -13 | Error in extension implementation that violates the extension specification or the extension version mismatch | | -14 to -127 | Reserved