[edk2-platforms][PATCH v2 03/32] AmperePlatformPkg: Implement FailSafe library

["Nhi Pham" <nhi@os.amperecomputing.com>]

The Ampere Altra System Firmware provides a fail-safe feature to help
recover the system if there are setting changes such as Core voltage,
DRAM parameters that cause the UEFI failed to boot.

The FailSafeLib supports API calls to Secure World to:
* Get the FailSafe region information.
* Get the current FailSafe status.
* Inform to FailSafe monitor that the system boots successfully.
* Simulate UEFI boot failure due to config wrong NVPARAM for
  testing failsafe feature.

This library will be consumed by FailSafe DXE driver.

Cc: Thang Nguyen <thang@os.amperecomputing.com>
Cc: Chuong Tran <chuong@os.amperecomputing.com>
Cc: Phong Vo <phong@os.amperecomputing.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Ard Biesheuvel <ardb+tianocore@kernel.org>
Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>

Signed-off-by: Nhi Pham <nhi@os.amperecomputing.com>
---
 Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec               |   3 +
 Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.inf |  41 +++
 Platform/Ampere/AmperePlatformPkg/Include/Library/FailSafeLib.h       |  62 ++++
 Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.c   | 320 ++++++++++++++++++++
 4 files changed, 426 insertions(+)

diff --git a/Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec b/Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec
index 7c1d1f84f780..6e33d96c7ea5 100755
--- a/Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec
+++ b/Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec
@@ -22,7 +22,10 @@ [Defines]
 #
 ################################################################################
 [Includes]
+  Include                        # Root include for the package
 
 [LibraryClasses]
+  ##  @libraryclass  Provides functions to support FailSafe operations.
+  FailSafeLib|Platform/Ampere/AmperePlatformPkg/Include/Library/FailSafeLib.h
 
 [Guids]
diff --git a/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.inf b/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.inf
new file mode 100755
index 000000000000..456b9d5fc85b
--- /dev/null
+++ b/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.inf
@@ -0,0 +1,41 @@
+## @file
+#
+# Copyright (c) 2020 - 2021, Ampere Computing LLC. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x0001001B
+  BASE_NAME                      = FailSafeLib
+  FILE_GUID                      = 3403D080-6D76-11E7-907B-A6006AD3DBA0
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = FailSafeLib
+
+[Sources]
+  FailSafeLib.c
+
+[Protocols]
+  gEfiMmCommunicationProtocolGuid        ## CONSUMES
+
+[Packages]
+  ArmPkg/ArmPkg.dec
+  ArmPlatformPkg/ArmPlatformPkg.dec
+  MdePkg/MdePkg.dec
+  Platform/Ampere/AmperePlatformPkg/AmperePlatformPkg.dec
+  Silicon/Ampere/AmpereAltraPkg/AmpereAltraPkg.dec
+  Silicon/Ampere/AmpereSiliconPkg/AmpereSiliconPkg.dec
+
+[LibraryClasses]
+  ArmSmcLib
+  BaseLib
+  BaseMemoryLib
+  DebugLib
+  HobLib
+  IoLib
+  NVParamLib
+
+[Guids]
+  gSpiNorMmGuid
diff --git a/Platform/Ampere/AmperePlatformPkg/Include/Library/FailSafeLib.h b/Platform/Ampere/AmperePlatformPkg/Include/Library/FailSafeLib.h
new file mode 100644
index 000000000000..7ebd1c8a74a2
--- /dev/null
+++ b/Platform/Ampere/AmperePlatformPkg/Include/Library/FailSafeLib.h
@@ -0,0 +1,62 @@
+/** @file
+
+  Copyright (c) 2020 - 2021, Ampere Computing LLC. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef FAILSAFE_LIB_H_
+#define FAILSAFE_LIB_H_
+
+enum {
+  MM_SPINOR_FUNC_GET_INFO,
+  MM_SPINOR_FUNC_READ,
+  MM_SPINOR_FUNC_WRITE,
+  MM_SPINOR_FUNC_ERASE,
+  MM_SPINOR_FUNC_GET_NVRAM_INFO,
+  MM_SPINOR_FUNC_GET_NVRAM2_INFO,
+  MM_SPINOR_FUNC_GET_FAILSAFE_INFO
+};
+
+#define MM_SPINOR_RES_SUCCESS           0xAABBCC00
+#define MM_SPINOR_RES_FAIL              0xAABBCCFF
+
+enum {
+  FAILSAFE_BOOT_NORMAL = 0,
+  FAILSAFE_BOOT_LAST_KNOWN_SETTINGS,
+  FAILSAFE_BOOT_DEFAULT_SETTINGS,
+  FAILSAFE_BOOT_DDR_DOWNGRADE,
+  FAILSAFE_BOOT_SUCCESSFUL
+};
+
+/**
+  Get the FailSafe region information.
+**/
+EFI_STATUS
+EFIAPI
+FailSafeGetRegionInfo (
+  UINT64 *Offset,
+  UINT64 *Size
+  );
+
+/**
+  Inform to FailSafe monitor that the system boots successfully.
+**/
+EFI_STATUS
+EFIAPI
+FailSafeBootSuccessfully (
+  VOID
+  );
+
+/**
+  Simulate UEFI boot failure due to config wrong NVPARAM for
+  testing failsafe feature
+**/
+EFI_STATUS
+EFIAPI
+FailSafeTestBootFailure (
+  VOID
+  );
+
+#endif /* FAILSAFE_LIB_H_ */
diff --git a/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.c b/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.c
new file mode 100644
index 000000000000..a567ab91375f
--- /dev/null
+++ b/Platform/Ampere/AmperePlatformPkg/Library/FailSafeLib/FailSafeLib.c
@@ -0,0 +1,320 @@
+/** @file
+
+  Copyright (c) 2020 - 2021, Ampere Computing LLC. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <PiPei.h>
+#include <Uefi.h>
+
+#include <Library/ArmSmcLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/DebugLib.h>
+#include <Library/FailSafeLib.h>
+#include <Library/HobLib.h>
+#include <Library/NVParamLib.h>
+#include <Library/PcdLib.h>
+#include <Library/UefiBootServicesTableLib.h>
+#include <Library/UefiRuntimeLib.h>
+#include <Platform/Ac01.h>
+#include <Protocol/MmCommunication.h>
+
+#define EFI_MM_MAX_PAYLOAD_U64_E  10
+#define EFI_MM_MAX_PAYLOAD_SIZE   (EFI_MM_MAX_PAYLOAD_U64_E * sizeof (UINT64))
+
+EFI_MM_COMMUNICATION_PROTOCOL *mFlashLibMmCommProtocol = NULL;
+
+typedef struct {
+  /* Allows for disambiguation of the message format */
+  EFI_GUID HeaderGuid;
+  /*
+   * Describes the size of Data (in bytes) and does not include the size
+   * of the header
+   */
+  UINTN MsgLength;
+} EFI_MM_COMM_HEADER_NOPAYLOAD;
+
+typedef struct {
+  UINT64 Data[EFI_MM_MAX_PAYLOAD_U64_E];
+} EFI_MM_COMM_SPINOR_PAYLOAD;
+
+typedef struct {
+  EFI_MM_COMM_HEADER_NOPAYLOAD EfiMmHdr;
+  EFI_MM_COMM_SPINOR_PAYLOAD   PayLoad;
+} EFI_MM_COMM_REQUEST;
+
+typedef struct {
+  UINT64 Status;
+} EFI_MM_COMMUNICATE_SPINOR_RES;
+
+typedef struct {
+  UINT64 Status;
+  UINT64 FailSafeBase;
+  UINT64 FailSafeSize;
+} EFI_MM_COMMUNICATE_SPINOR_FAILSAFE_INFO_RES;
+
+EFI_MM_COMM_REQUEST mEfiMmSpiNorReq;
+
+#pragma pack(1)
+typedef struct {
+  UINT8  ImgMajorVer;
+  UINT8  ImgMinorVer;
+  UINT32 NumRetry1;
+  UINT32 NumRetry2;
+  UINT32 MaxRetry;
+  UINT8  Status;
+  /*
+   * Byte[3]: Reserved
+   * Byte[2]: Slave MCU Failure Mask
+   * Byte[1]: Reserved
+   * Byte[0]: Master MCU Failure Mask
+   */
+  UINT32 MCUFailsMask;
+  UINT16 CRC16;
+  UINT8  Reserved[3];
+} FAIL_SAFE_CONTEXT;
+
+#pragma pack()
+
+STATIC
+EFI_STATUS
+UefiMmCreateSpiNorReq (
+  VOID   *Data,
+  UINT64 Size
+  )
+{
+  CopyGuid (&mEfiMmSpiNorReq.EfiMmHdr.HeaderGuid, &gSpiNorMmGuid);
+  mEfiMmSpiNorReq.EfiMmHdr.MsgLength = Size;
+
+  if (Size != 0) {
+    ASSERT (Data);
+    ASSERT (Size <= EFI_MM_MAX_PAYLOAD_SIZE);
+
+    CopyMem (mEfiMmSpiNorReq.PayLoad.Data, Data, Size);
+  }
+
+  return EFI_SUCCESS;
+}
+
+STATIC
+INTN
+CheckCrc16 (
+  UINT8 *Pointer,
+  INTN  Count
+  )
+{
+  INTN Crc = 0;
+  INTN Index;
+
+  while (--Count >= 0) {
+    Crc = Crc ^ (INTN)*Pointer++ << 8;
+    for (Index = 0; Index < 8; ++Index) {
+      if ((Crc & 0x8000) != 0) {
+        Crc = Crc << 1 ^ 0x1021;
+      } else {
+        Crc = Crc << 1;
+      }
+    }
+  }
+
+  return Crc & 0xFFFF;
+}
+
+BOOLEAN
+FailSafeValidCRC (
+  FAIL_SAFE_CONTEXT *FailSafeBuf
+  )
+{
+  UINT8  Valid;
+  UINT16 Crc;
+  UINT32 Len;
+
+  Len = sizeof (FAIL_SAFE_CONTEXT);
+  Crc = FailSafeBuf->CRC16;
+  FailSafeBuf->CRC16 = 0;
+
+  Valid = (Crc == CheckCrc16 ((UINT8 *)FailSafeBuf, Len));
+  FailSafeBuf->CRC16 = Crc;
+
+  return Valid;
+}
+
+BOOLEAN
+FailSafeFailureStatus (
+  UINT8 Status
+  )
+{
+  if ((Status == FAILSAFE_BOOT_LAST_KNOWN_SETTINGS) ||
+      (Status == FAILSAFE_BOOT_DEFAULT_SETTINGS) ||
+      (Status == FAILSAFE_BOOT_DDR_DOWNGRADE))
+  {
+    return TRUE;
+  }
+
+  return FALSE;
+}
+
+EFI_STATUS
+EFIAPI
+FailSafeGetRegionInfo (
+  UINT64 *Offset,
+  UINT64 *Size
+  )
+{
+  EFI_MM_COMMUNICATE_SPINOR_FAILSAFE_INFO_RES *MmSpiNorFailSafeInfoRes;
+  UINT64                                      MmData[5];
+  UINTN                                       DataSize;
+  EFI_STATUS                                  Status;
+
+  if (mFlashLibMmCommProtocol == NULL) {
+    Status = gBS->LocateProtocol (
+                    &gEfiMmCommunicationProtocolGuid,
+                    NULL,
+                    (VOID **)&mFlashLibMmCommProtocol
+                    );
+    if (EFI_ERROR (Status)) {
+      DEBUG ((DEBUG_ERROR, "%a: Can't locate gEfiMmCommunicationProtocolGuid\n", __FUNCTION__));
+      return Status;
+    }
+  }
+
+  MmData[0] = MM_SPINOR_FUNC_GET_FAILSAFE_INFO;
+  UefiMmCreateSpiNorReq ((VOID *)&MmData, sizeof (MmData));
+
+  DataSize = sizeof (EFI_MM_COMM_HEADER_NOPAYLOAD) + sizeof (MmData);
+  Status = mFlashLibMmCommProtocol->Communicate (
+                                      mFlashLibMmCommProtocol,
+                                      (VOID *)&mEfiMmSpiNorReq,
+                                      &DataSize
+                                      );
+  ASSERT_EFI_ERROR (Status);
+
+  MmSpiNorFailSafeInfoRes = (EFI_MM_COMMUNICATE_SPINOR_FAILSAFE_INFO_RES *)&mEfiMmSpiNorReq.PayLoad;
+  if (MmSpiNorFailSafeInfoRes->Status != MM_SPINOR_RES_SUCCESS) {
+    DEBUG ((
+      DEBUG_ERROR,
+      "%a: Get flash information failed: 0x%llx\n",
+      __FUNCTION__,
+      MmSpiNorFailSafeInfoRes->Status
+      ));
+    return EFI_DEVICE_ERROR;
+  }
+
+  *Offset = MmSpiNorFailSafeInfoRes->FailSafeBase;
+  *Size   = MmSpiNorFailSafeInfoRes->FailSafeSize;
+
+  return EFI_SUCCESS;
+}
+
+EFI_STATUS
+EFIAPI
+FailSafeBootSuccessfully (
+  VOID
+  )
+{
+  EFI_MM_COMMUNICATE_SPINOR_RES *MmSpiNorRes;
+  UINT64                        MmData[5];
+  UINTN                         Size;
+  EFI_STATUS                    Status;
+  UINT64                        FailSafeStartOffset;
+  UINT64                        FailSafeSize;
+  FAIL_SAFE_CONTEXT             FailSafeBuf;
+
+  Status = FailSafeGetRegionInfo (&FailSafeStartOffset, &FailSafeSize);
+  if (EFI_ERROR (Status)) {
+    DEBUG ((DEBUG_ERROR, "%a: Failed to get context region information\n", __FUNCTION__));
+    return EFI_DEVICE_ERROR;
+  }
+
+  MmData[0] = MM_SPINOR_FUNC_READ;
+  MmData[1] = FailSafeStartOffset;
+  MmData[2] = (UINT64)sizeof (FAIL_SAFE_CONTEXT);
+  MmData[3] = (UINT64)&FailSafeBuf;
+  UefiMmCreateSpiNorReq ((VOID *)&MmData, sizeof (MmData));
+
+  Size = sizeof (EFI_MM_COMM_HEADER_NOPAYLOAD) + sizeof (MmData);
+  Status = mFlashLibMmCommProtocol->Communicate (
+                                      mFlashLibMmCommProtocol,
+                                      (VOID *)&mEfiMmSpiNorReq,
+                                      &Size
+                                      );
+  ASSERT_EFI_ERROR (Status);
+
+  MmSpiNorRes = (EFI_MM_COMMUNICATE_SPINOR_RES *)&mEfiMmSpiNorReq.PayLoad;
+  if (MmSpiNorRes->Status != MM_SPINOR_RES_SUCCESS) {
+    DEBUG ((
+      DEBUG_ERROR,
+      "%a: Read context failed: 0x%llx\n",
+      __FUNCTION__,
+      MmSpiNorRes->Status
+      ));
+    return EFI_DEVICE_ERROR;
+  }
+
+  /*
+   * If failsafe context is invalid, it is already indicate a successful boot
+   * and don't need to be cleared
+   */
+  if (!FailSafeValidCRC (&FailSafeBuf)) {
+    return EFI_SUCCESS;
+  }
+
+  /*
+   * If failsafe context is valid, and:
+   *    - The status indicate non-failure, then don't clear it
+   *    - The status indicate a failure, then go and clear it
+   */
+  if (!FailSafeFailureStatus (FailSafeBuf.Status)) {
+    return EFI_SUCCESS;
+  }
+
+  MmData[0] = MM_SPINOR_FUNC_ERASE;
+  MmData[1] = FailSafeStartOffset;
+  MmData[2] = FailSafeSize;
+  UefiMmCreateSpiNorReq ((VOID *)&MmData, sizeof (MmData));
+
+  Size = sizeof (EFI_MM_COMM_HEADER_NOPAYLOAD) + sizeof (MmData);
+  Status = mFlashLibMmCommProtocol->Communicate (
+                                      mFlashLibMmCommProtocol,
+                                      (VOID *)&mEfiMmSpiNorReq,
+                                      &Size
+                                      );
+  ASSERT_EFI_ERROR (Status);
+
+  MmSpiNorRes = (EFI_MM_COMMUNICATE_SPINOR_RES *)&mEfiMmSpiNorReq.PayLoad;
+  if (MmSpiNorRes->Status != MM_SPINOR_RES_SUCCESS) {
+    DEBUG ((
+      DEBUG_ERROR,
+      "%a: Erase context failed: 0x%llx\n",
+      __FUNCTION__,
+      MmSpiNorRes->Status
+      ));
+    return EFI_DEVICE_ERROR;
+  }
+
+  return EFI_SUCCESS;
+}
+
+EFI_STATUS
+EFIAPI
+FailSafeTestBootFailure (
+  VOID
+  )
+{
+  EFI_STATUS Status;
+  UINT32     Value = 0;
+
+  /*
+   * Simulate UEFI boot failure due to config wrong NVPARAM for
+   * testing failsafe feature
+   */
+  Status = NVParamGet (NV_UEFI_FAILURE_FAILSAFE_OFFSET, NV_PERM_ALL, &Value);
+  if (!EFI_ERROR (Status) && (Value == 1)) {
+    while (1) {
+    }
+  }
+
+  return EFI_SUCCESS;
+}
-- 
2.17.1