Improve Management Mode service group

Improve the management mode service group as follows:
1) Use MM shared memory to exchange data with MM service
2) Rename MM_VERSION service to MM_GET_ATTRIBUTES service
which returns MM version and MM shared memory location.

Signed-off-by: Anup Patel <[email protected]>

src/srvgrp-management.adoc

@@ -10,14 +10,17 @@ ifndef::rootpath[]
 endif::rootpath[]
 
 ===  Service Group - MANAGEMENT_MODE (SERVICEGROUP_ID: 0x000A)
-This MANAGEMENT_MODE service group is designed to be used for software invocation
-of Management Mode (MM) in a secure execution environment. For general background
-on Management Mode, refer to the Platform Initialization (PI) specifications
-cite:[PI], Volume 4: Management Mode Core Interface. Management Mode provides an
-environment for implementing OS agnostic services (MM services) like secure variable
-storage, and firmware updates in system firmware. This service group describes the
-interfaces for invoking MM services synchronously, the `MM_COMMUNICATE` serves as the
-world-switch synchronous call from the non-secure to the secure world.
+This MANAGEMENT_MODE service group provides RPMI client a mechanism to invoke the
+Management Mode (MM) in a secure execution environment. For general background on
+Management Mode, refer to the Platform Initialization (PI) specifications cite:[PI],
+Volume 4: Management Mode Core Interface.
+
+The Management Mode (MM) provides an environment for implementing OS agnostic
+MM services such as secure variable storage, and firmware updates in the platform
+firmware. The MANAGEMENT_MODE service group defines RPMI services for invoking an
+MM service synchronously where the `MM_COMMUNICATE` RPMI service is used as a
+synchronous call from the non-secure world to the secure world and the data exchanged
+with the MM service is passed via special Management Mode (MM) shared memory.
 
 The following table lists the services in the MANAGEMENT_MODE service group:
 
@@ -34,7 +37,7 @@ The following table lists the services in the MANAGEMENT_MODE service group:
 | NORMAL_REQUEST
 
 | 0x02
-| MM_VERSION
+| MM_GET_ATTRIBUTES
 | NORMAL_REQUEST
 
 | 0x03
@@ -102,19 +105,20 @@ in <<management-notifications>>.
 |===
 
 
-==== Service: MM_VERSION (SERVICE_ID: 0x02)
-This service returns the version of a Management Mode.
+==== 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.
 
-[#table_mm_version_request_data]
+[#table_mm_get_attributes_request_data]
 .Request Data
 [cols="1", width=100%, align="center", options="header"]
 |===
 | NA
 |===
 
-[#table_mm_version_response_data]
+[#table_mm_get_attributes_response_data]
 .Response Data
-[cols="1, 2, 1, 7a", width=100%, align="center", options="header"]
+[cols="1, 4, 1, 7a", width=100%, align="center", options="header"]
 |===
 | Word
 | Name
@@ -132,10 +136,6 @@ This service returns the version of a Management Mode.
 
 ! RPMI_SUCCESS
 ! Service completed successfully.
-
-! RPMI_ERR_DENIED
-! Denied due to no permission.
-
 !===
 - Other errors <<table_error_codes>>
 
@@ -155,47 +155,69 @@ This service returns the version of a Management Mode.
 ! [15:0]
 ! Minor version
 !===
+
+| 2
+| MM_SHMEM_ADDR_LOW
+| uint32
+| Lower 32-bit of the MM shared memory physical address.
+
+| 3
+| MM_SHMEM_ADDR_HIGH
+| uint32
+| Upper 32-bit of the MM shared memory physical address.
+
+| 4
+| MM_SHMEM_SIZE
+| uint32
+| The size of MM shared memory in bytes.
+
 |===
 
 
 ==== Service: MM_COMMUNICATE (SERVICE_ID: 0x03)
-This service invokes an MM service implemented in the secure execution
-environment. The `MM_COMM_DATA` contains data needed to identify and
-invoke the MM service.
+The `MM_COMMUNICATE` service invokes an MM service implemented in the secure
+execution environment. The input data needed to identify and invoke the MM
+service is referred to as `MM_COMM_INPUT_DATA` whereas the output data returned
+by the MM service is referred to as `MM_COMM_OUTPUT_DATA`. The RPMI client in
+the non-secure execution enviroment provides the location of `MM_COMM_INPUT_DATA`
+and `MM_COMM_OUTPUT_DATA` in the MM shared memory as parameters of `MM_COMMUNICATE`
+service.
 
 [#table_mm_communicate_request_data]
 .Request Data
-[cols="1, 5, 1, 7", width=100%, align="center", options="header"]
+[cols="1, 7, 1, 6", width=100%, align="center", options="header"]
 |===
 | Word
 | Name
 | Type
 | Description
 
 | 0
-| MM_COMM_DATA_ADDR_LOW
+| MM_COMM_INPUT_DATA_OFFSET
 | uint32
-| Lower 32-bit of the MM data's physical address from non-secure to secure world.
+| The offset in the MM shared memory where the input data is passed to the MM service.
 
 | 1
-| MM_COMM_DATA_ADDR_HIGH
+| MM_COMM_INPUT_DATA_SIZE
 | uint32
-| Upper 32-bit of the MM data's physical address from non-secure to secure world.
+| The size of the input data in the MM shared memory.
 
 | 2
-| MM_COMM_DATA_SIZE_LOW
+| MM_COMM_OUTPUT_DATA_OFFSET
 | uint32
-| Lower 32-bit of the MM data's length from non-secure to secure world.
+| The offset in the MM shared memory where the output data will be written by
+the MM service.
 
 | 3
-| MM_COMM_DATA_SIZE_HIGH
+| MM_COMM_OUTPUT_DATA_SIZE
 | uint32
-| Upper 32-bit of the MM data's length from non-secure to secure world.
+| The maximum size of the output data which can be written by the MM service in
+the MM shared memory.
 |===
 
 [#table_mm_communicate_response_data]
 .Response Data
-[cols="1, 2, 1, 7a", width=100%, align="center", options="header"]
+[cols="1, 6, 1, 7a", width=100%, align="center", options="header"]
 |===
 | Word
 | Name
@@ -207,17 +229,24 @@ invoke the MM service.
 | int32
 | Return error code
 
-[cols="4,5", options="header"]
+[cols="6,4", options="header"]
 !===
 ! Error Code
 ! Description
 
 ! RPMI_SUCCESS
 ! Service completed successfully.
 
+! RPMI_ERR_INVALID_ADDR
+! Input data end (or Output data end) is outside MM shared memory.
+
 ! RPMI_ERR_DENIED
 ! Denied due to no permission.
-
 !===
 - Other errors <<table_error_codes>>
+
+| 1
+| MM_COMM_RETURN_DATA_SIZE
+| uint32
+| Actual size of the output data written by the MM service in the MM shared memory.
 |===