[RFC PATCH v1 06/30] ArmVirtPkg: Add Arm CCA Realm Service Interface Library

["Sami Mujawar" <sami.mujawar@arm.com>]

The Realm Management Monitor (RMM) is a software component which
forms part of a system which implements the Arm Confidential Compute
Architecture (CCA) and is responsible for management of Realms.
The RMM specification defines a Realm Service Interface (RSI) that
the Guest can use to request services from the RMM.

Therefore, add a library that implements the RSI interfaces to:
  - query the RSI version
  - get the Realm configuration.

Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
---
 ArmVirtPkg/ArmVirtPkg.dec                        |   1 +
 ArmVirtPkg/Include/Library/ArmCcaRsiLib.h        |  72 ++++++++++
 ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsi.h      |  40 ++++++
 ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.c   | 145 ++++++++++++++++++++
 ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.inf |  29 ++++
 5 files changed, 287 insertions(+)

diff --git a/ArmVirtPkg/ArmVirtPkg.dec b/ArmVirtPkg/ArmVirtPkg.dec
index 4645c91a83756603141717baadd9f3e9b482cdb2..0bc7d697428636d42ffb27e8e92fca947665a79e 100644
--- a/ArmVirtPkg/ArmVirtPkg.dec
+++ b/ArmVirtPkg/ArmVirtPkg.dec
@@ -26,6 +26,7 @@ [Includes.common]
   Include                        # Root include for the package
 
 [LibraryClasses]
+  ArmCcaRsiLib|Include/Library/ArmCcaRsiLib.h
   ArmVirtMemInfoLib|Include/Library/ArmVirtMemInfoLib.h
 
 [Guids.common]
diff --git a/ArmVirtPkg/Include/Library/ArmCcaRsiLib.h b/ArmVirtPkg/Include/Library/ArmCcaRsiLib.h
new file mode 100644
index 0000000000000000000000000000000000000000..ab70240b3ab2979996f20190ddf669b53183556b
--- /dev/null
+++ b/ArmVirtPkg/Include/Library/ArmCcaRsiLib.h
@@ -0,0 +1,72 @@
+/** @file
+  Library that implements the Arm CCA Realm Service Interface calls.
+
+  Copyright (c) 2022 - 2023, Arm Limited. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+    - Rsi or RSI   - Realm Service Interface
+    - IPA          - Intermediate Physical Address
+
+  @par Reference(s):
+   - Realm Management Monitor (RMM) Specification, version A-bet0
+     (https://developer.arm.com/documentation/den0137/)
+**/
+
+#ifndef ARM_CCA_RSI_LIB_
+#define ARM_CCA_RSI_LIB_
+
+#include <Base.h>
+
+/**
+  A macro defining the size of a Realm Granule.
+  See Section A2.2, RMM Specification, version A-bet0
+  DNBXXX A Granule is a unit of physical memory whose size is 4KB.
+*/
+#define REALM_GRANULE_SIZE  SIZE_4KB
+
+/** A structure describing the Realm Configuration.
+  See Section B4.4.4 RsiRealmConfig type, RMM Specification, version A-bet0
+  The width of the RsiRealmConfig structure is 4096 (0x1000) bytes.
+*/
+typedef struct RealmConfig {
+  // Width of IPA in bits.
+  UINT64    IpaWidth;
+  // Unused bits of the RsiRealmConfig structure should be zero.
+  UINT8     Reserved[SIZE_4KB - sizeof (UINT64)];
+} REALM_CONFIG;
+
+/**
+  Read the Realm Configuration.
+
+  @param [out]  Config     Pointer to the address of the buffer to retrieve
+                           the Realm configuration.
+
+  Note: The buffer to retrieve the Realm configuration must be aligned to the
+        Realm granule size.
+
+  @retval RETURN_SUCCESS            Success.
+  @retval RETURN_INVALID_PARAMETER  A parameter is invalid.
+**/
+RETURN_STATUS
+EFIAPI
+RsiGetRealmConfig (
+  IN  REALM_CONFIG  *Config
+  );
+
+/**
+   Get the version of the RSI implementation.
+
+  @param [out] Major  The major version of the RSI implementation.
+  @param [out] Minor  The minor version of the RSI implementation.
+
+  @retval RETURN_SUCCESS            Success.
+  @retval RETURN_INVALID_PARAMETER  A parameter is invalid.
+ */
+RETURN_STATUS
+EFIAPI
+RsiGetVersion (
+  OUT UINT16 *CONST  Major,
+  OUT UINT16 *CONST  Minor
+  );
+
+#endif // ARM_CCA_RSI_LIB_
diff --git a/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsi.h b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsi.h
new file mode 100644
index 0000000000000000000000000000000000000000..90e9dbb609679c82cd8e8ee8081428fd97021f97
--- /dev/null
+++ b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsi.h
@@ -0,0 +1,40 @@
+/** @file
+  Definitions for Arm CCA Realm Service Interface.
+
+  Copyright (c) 2022 - 2023, ARM Ltd. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+  @par Glossary:
+    - Rsi or RSI   - Realm Service Interface
+    - IPA          - Intermediate Physical Address
+
+  @par Reference(s):
+   - Realm Management Monitor (RMM) Specification, version A-bet0
+     (https://developer.arm.com/documentation/den0137/)
+**/
+
+#ifndef ARM_CCA_RSI_H_
+#define ARM_CCA_RSI_H_
+
+// FIDs for Realm Service Interface calls.
+#define FID_RSI_REALM_CONFIG  0xC4000196
+#define FID_RSI_VERSION       0xC4000190
+
+/** RSI Command Return codes
+   See Section B4.4.1, RMM Specification, version A-bet0.
+   The width of the RsiCommandReturnCode enumeration is 64 bits.
+*/
+#define RSI_SUCCESS      0ULL
+#define RSI_ERROR_INPUT  1ULL
+#define RSI_ERROR_STATE  2ULL
+#define RSI_INCOMPLETE   3ULL
+
+/** RSI interface Version
+   See Section B4.4.3,  RMM Specification, version A-bet0.
+   The width of the RsiInterfaceVersion fieldset is 64 bits.
+*/
+#define RSI_VER_MINOR_MASK   0x00FFULL
+#define RSI_VER_MAJOR_MASK   0x7F00ULL
+#define RSI_VER_MAJOR_SHIFT  16
+
+#endif // ARM_CCA_RSI_H_
diff --git a/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.c b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.c
new file mode 100644
index 0000000000000000000000000000000000000000..42b99fb7a71c8b38512a2f7472f9bc8a034fe1e9
--- /dev/null
+++ b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.c
@@ -0,0 +1,145 @@
+/** @file
+  Library that implements the Arm CCA Realm Service Interface calls.
+
+  Copyright (c) 2022 - 2023, Arm Limited. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+  @par Glossary:
+    - Rsi or RSI   - Realm Service Interface
+    - IPA          - Intermediate Physical Address
+
+  @par Reference(s):
+   - Realm Management Monitor (RMM) Specification, version A-bet0
+     (https://developer.arm.com/documentation/den0137/)
+
+**/
+#include <Base.h>
+
+#include <Library/ArmCcaRsiLib.h>
+#include <Library/ArmLib.h>
+#include <Library/ArmSmcLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/DebugLib.h>
+#include "ArmCcaRsi.h"
+
+/**
+  Convert the RSI status code to EFI Status code.
+
+  @param [in]   RsiCommandReturnCode  RSI status code.
+
+  @retval RETURN_SUCCESS            Success.
+  @retval RETURN_INVALID_PARAMETER  A parameter is invalid.
+  @retval RETURN_ABORTED            The operation was aborted as the state
+                                    of the Realm or REC does not match the
+                                    state expected by the command.
+  @retval RETURN_NOT_READY          The operation requested by the command
+                                    is not complete.
+ **/
+STATIC
+RETURN_STATUS
+RsiCmdStatusToEfiStatus (
+  IN  UINT64  RsiCommandReturnCode
+  )
+{
+  switch (RsiCommandReturnCode) {
+    case RSI_SUCCESS:
+      return RETURN_SUCCESS;
+    case RSI_ERROR_INPUT:
+      return RETURN_INVALID_PARAMETER;
+    case RSI_ERROR_STATE:
+      return RETURN_ABORTED;
+    case RSI_INCOMPLETE:
+      return RETURN_NOT_READY;
+    default:
+      // Unknown error code.
+      ASSERT (0);
+      break;
+  } // switch
+
+  return RETURN_ABORTED;
+}
+
+/**
+  Check if the address is aligned to the size of the Realm granule.
+
+  @param [in] Address          Address to check granule alignment.
+
+  @retval TRUE  Address is aligned to the Realm granule size.
+  @retval FALSE Address is not aligned to the Realm granule size.
+**/
+STATIC
+BOOLEAN
+EFIAPI
+AddrIsGranuleAligned (
+  IN   UINT64  *Address
+  )
+{
+  if (((UINT64)Address & (REALM_GRANULE_SIZE - 1)) != 0) {
+    return FALSE;
+  }
+
+  return TRUE;
+}
+
+/**
+  Read the Realm Configuration.
+
+  @param [out]  Config     Pointer to the address of the buffer to retrieve
+                           the Realm configuration.
+
+  Note: The buffer to retrieve the Realm configuration must be aligned to the
+        Realm granule size.
+
+  @retval RETURN_SUCCESS            Success.
+  @retval RETURN_INVALID_PARAMETER  A parameter is invalid.
+**/
+RETURN_STATUS
+EFIAPI
+RsiGetRealmConfig (
+  OUT REALM_CONFIG  *Config
+  )
+{
+  ARM_SMC_ARGS  SmcCmd;
+
+  if ((Config == NULL) || (!AddrIsGranuleAligned ((UINT64 *)Config))) {
+    return RETURN_INVALID_PARAMETER;
+  }
+
+  ZeroMem (&SmcCmd, sizeof (SmcCmd));
+  SmcCmd.Arg0 = FID_RSI_REALM_CONFIG;
+  SmcCmd.Arg1 = (UINTN)Config;
+
+  ArmCallSmc (&SmcCmd);
+  return RsiCmdStatusToEfiStatus (SmcCmd.Arg0);
+}
+
+/**
+   Get the version of the RSI implementation.
+
+  @param [out] Major  The major version of the RSI implementation.
+  @param [out] Minor  The minor version of the RSI implementation.
+
+  @retval RETURN_SUCCESS            Success.
+  @retval RETURN_INVALID_PARAMETER  A parameter is invalid.
+ */
+RETURN_STATUS
+EFIAPI
+RsiGetVersion (
+  OUT UINT16 *CONST  Major,
+  OUT UINT16 *CONST  Minor
+  )
+{
+  ARM_SMC_ARGS  SmcCmd;
+
+  if ((Major == NULL) || (Minor == NULL)) {
+    return EFI_INVALID_PARAMETER;
+  }
+
+  ZeroMem (&SmcCmd, sizeof (SmcCmd));
+  SmcCmd.Arg0 = FID_RSI_VERSION;
+
+  ArmCallSmc (&SmcCmd);
+  *Minor = SmcCmd.Arg0 & RSI_VER_MINOR_MASK;
+  *Major = (SmcCmd.Arg0 & RSI_VER_MAJOR_MASK) >> RSI_VER_MAJOR_SHIFT;
+  return RETURN_SUCCESS;
+}
diff --git a/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.inf b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.inf
new file mode 100644
index 0000000000000000000000000000000000000000..1e2b72f312587f822dfca1b26b1910f75d4ec7b6
--- /dev/null
+++ b/ArmVirtPkg/Library/ArmCcaRsiLib/ArmCcaRsiLib.inf
@@ -0,0 +1,29 @@
+## @file
+#  Library that implements the Arm CCA Realm Service Interface calls.
+#
+#  Copyright (c) 2022 - 2023, Arm Limited. All rights reserved.<BR>
+#
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x0001001B
+  BASE_NAME                      = ArmCcaRsiLib
+  FILE_GUID                      = 5EF34A0A-28B5-4E57-A999-CC1528FC629A
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = ArmCcaRsiLib
+
+[Sources]
+  ArmCcaRsiLib.c
+  ArmCcaRsi.h
+
+[Packages]
+  ArmPkg/ArmPkg.dec
+  ArmVirtPkg/ArmVirtPkg.dec
+  MdePkg/MdePkg.dec
+
+[LibraryClasses]
+  ArmLib
+  ArmSmcLib
-- 
'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'