MdeModulePkg: Add Variable Flash Info HOB

[mirror_edk2.git] / MdeModulePkg / Include / Guid / VariableFlashInfo.h

diff --git a/MdeModulePkg/Include/Guid/VariableFlashInfo.h b/MdeModulePkg/Include/Guid/VariableFlashInfo.h
new file mode 100644 (file)
index 0000000..992a0dc
--- /dev/null
+++ b/MdeModulePkg/Include/Guid/VariableFlashInfo.h
@@ -0,0 +1,111 @@
+/** @file\r
+  This file defines the GUID and data structure used to pass information about\r
+  a variable store mapped on flash (i.e. a MMIO firmware volume) to the modules\r
+  that consume that information such as the DXE and MM UEFI variable drivers.\r
+\r
+  The HOB described in this file is currently optional. It is primarily provided\r
+  to allow a platform to dynamically describe the flash information to environments\r
+  such as Standalone MM that cannot access the prior method using dynamic PCDs.\r
+\r
+  Even for platforms that use Standalone MM, if the information is only stored\r
+  statically such as with FixedAtBuild PCDs, the HOB is not required.\r
+\r
+  Every point of consumption in this package that uses the PCDs will first check\r
+  for the HOB and use its value if present.\r
+\r
+  Early modules such as the PEI UEFI variable driver might also consume this\r
+  information. For modules such as these, that execute early in the boot flow,\r
+  at least two approaches are possible depending on platform design.\r
+\r
+  1. If the information in the HOB exactly matches the information in the PCDs,\r
+     (i.e. the HOB values are set using the PCD values), let the driver read\r
+     the information from the PCD and produce the HOB later in boot.\r
+\r
+  2. Produce the HOB very early in boot. For example, the earliest point the HOB\r
+     is currently consumed is in FaultTolerantWritePei. Note that FaultTolerantWritePei\r
+     produces gEdkiiFaultTolerantWriteGuid which is a dependency for VariablePei.\r
+\r
+     Therefore, attaching a NULL class library to FaultTolerantWritePei with a\r
+     constructor that produces the HOB will guarantee it is produced before the first\r
+     point of consumption as the constructor is executed before the module entry point.\r
+\r
+  Copyright (c) Microsoft Corporation.<BR>\r
+\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+**/\r
+\r
+#ifndef VARIABLE_FLASH_INFO_H_\r
+#define VARIABLE_FLASH_INFO_H_\r
+\r
+#define VARIABLE_FLASH_INFO_HOB_GUID \\r
+  { 0x5d11c653, 0x8154, 0x4ac3, { 0xa8, 0xc2, 0xfb, 0xa2, 0x89, 0x20, 0xfc, 0x90 }}\r
+\r
+#define VARIABLE_FLASH_INFO_HOB_VERSION  1\r
+\r
+extern EFI_GUID  gVariableFlashInfoHobGuid;\r
+\r
+#pragma pack (push, 1)\r
+\r
+///\r
+/// This structure can be used to describe UEFI variable\r
+/// flash information.\r
+///\r
+typedef struct {\r
+  ///\r
+  /// Version of this structure.\r
+  ///\r
+  /// Increment the value when the structure is modified.\r
+  ///\r
+  UINT32                  Version;\r
+  ///\r
+  /// Reserved field.\r
+  ///\r
+  /// Currently reserved for natural alignment.\r
+  ///\r
+  UINT32                  Reserved;\r
+  ///\r
+  /// Base address of the non-volatile variable range in the flash device.\r
+  ///\r
+  /// Note that this address should align with the block size requirements of the flash device.\r
+  ///\r
+  EFI_PHYSICAL_ADDRESS    NvVariableBaseAddress;\r
+  ///\r
+  /// Size of the non-volatile variable range in the flash device.\r
+  ///\r
+  /// Note that this value should be less than or equal to FtwSpareLength to support reclaim of\r
+  /// entire variable store area.\r
+  /// Note that this address should align with the block size requirements of the flash device.\r
+  ///\r
+  UINT64                  NvVariableLength;\r
+  ///\r
+  /// Base address of the FTW spare block range in the flash device.\r
+  ///\r
+  /// Note that this address should align with the block size requirements of the flash device.\r
+  ///\r
+  EFI_PHYSICAL_ADDRESS    FtwSpareBaseAddress;\r
+  ///\r
+  /// Size of the FTW spare block range in the flash device.\r
+  ///\r
+  /// Note that this value should be greater than or equal to NvVariableLength.\r
+  /// Note that this address should align with the block size requirements of the flash device.\r
+  ///\r
+  UINT64                  FtwSpareLength;\r
+  ///\r
+  /// Base address of the FTW working block range in the flash device.\r
+  ///\r
+  /// Note that if FtwWorkingLength is larger than on block size, this value should be block size aligned.\r
+  ///\r
+  EFI_PHYSICAL_ADDRESS    FtwWorkingBaseAddress;\r
+  ///\r
+  /// Size of the FTW working block range in the flash device.\r
+  ///\r
+  /// Note that if the value is less than on block size, the range should not span blocks.\r
+  /// Note that if the value is larger than one block size, this value should be block size aligned.\r
+  ///\r
+  UINT64                  FtwWorkingLength;\r
+} VARIABLE_FLASH_INFO;\r
+\r
+#pragma pack (pop)\r
+\r
+#endif\r