[PATCH v2 2/2] MdePkg/NvdimmLabel.h: Add NVDIMM_LABEL protocol definition

[Ruiyu Ni <ruiyu.ni@intel.com>]

NVDIMM_LABEL protocol is defined in UEFI 2.7 spec, to provide
services that allow management of labels contained in a Label
Storage Area in NVDIMM.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
---
 MdePkg/Include/Protocol/NvdimmLabel.h | 351 ++++++++++++++++++++++++++++++++++
 MdePkg/MdePkg.dec                     |   3 +
 2 files changed, 354 insertions(+)
 create mode 100644 MdePkg/Include/Protocol/NvdimmLabel.h

diff --git a/MdePkg/Include/Protocol/NvdimmLabel.h b/MdePkg/Include/Protocol/NvdimmLabel.h
new file mode 100644
index 0000000000..0d70bdff74
--- /dev/null
+++ b/MdePkg/Include/Protocol/NvdimmLabel.h
@@ -0,0 +1,351 @@
+/** @file
+  EFI NVDIMM Label Protocol Definition
+
+  The EFI NVDIMM Label Protocol is used to Provides services that allow management
+  of labels contained in a Label Storage Area that are associated with a specific
+  NVDIMM Device Path.
+
+Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
+This program and the accompanying materials are licensed and made available under
+the terms and conditions of the BSD License that accompanies this distribution.
+The full text of the license may be found at
+http://opensource.org/licenses/bsd-license.php.
+
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+  @par Revision Reference:
+  This Protocol was introduced in UEFI Specification 2.7.
+
+**/
+
+#ifndef __EFI_NVDIMM_LABEL_PROTOCOL_H__
+#define __EFI_NVDIMM_LABEL_PROTOCOL_H__
+
+#define EFI_NVDIMM_LABEL_PROTOCOL_GUID \
+  { \
+    0xd40b6b80, 0x97d5, 0x4282, {0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 } \
+  }
+
+typedef struct _EFI_NVDIMM_LABEL_PROTOCOL EFI_NVDIMM_LABEL_PROTOCOL;
+
+#define EFI_NVDIMM_LABEL_INDEX_SIG_LEN 16
+#define EFI_NVDIMM_LABEL_INDEX_ALIGN   256
+typedef struct {
+  ///
+  /// Signature of the Index Block data structure. Must be "NAMESPACE_INDEX\0".
+  ///
+  CHAR8  Sig[EFI_NVDIMM_LABEL_INDEX_SIG_LEN];
+
+  ///
+  /// Attributes of this Label Storage Area.
+  ///
+  UINT8  Flags[3];
+
+  ///
+  /// Size of each label in bytes, 128 bytes << LabelSize.
+  /// 1 means 256 bytes, 2 means 512 bytes, etc. Shall be 1 or greater.
+  ///
+  UINT8  LabelSize;
+
+  ///
+  /// Sequence number used to identify which of the two Index Blocks is current.
+  ///
+  UINT32 Seq;
+
+  ///
+  /// The offset of this Index Block in the Label Storage Area.
+  ///
+  UINT64 MyOff;
+
+  ///
+  /// The size of this Index Block in bytes.
+  /// This field must be a multiple of the EFI_NVDIMM_LABEL_INDEX_ALIGN.
+  ///
+  UINT64 MySize;
+
+  ///
+  /// The offset of the other Index Block paired with this one.
+  ///
+  UINT64 OtherOff;
+
+  ///
+  /// The offset of the first slot where labels are stored in this Label Storage Area.
+  ///
+  UINT64 LabelOff;
+
+  ///
+  /// The total number of slots for storing labels in this Label Storage Area.
+  ///
+  UINT32 NSlot;
+
+  ///
+  /// Major version number. Value shall be 1.
+  ///
+  UINT16 Major;
+
+  ///
+  /// Minor version number. Value shall be 2.
+  ///
+  UINT16 Minor;
+
+  ///
+  /// 64-bit Fletcher64 checksum of all fields in this Index Block.
+  ///
+  UINT64 Checksum;
+
+  ///
+  /// Array of unsigned bytes implementing a bitmask that tracks which label slots are free.
+  /// A bit value of 0 indicates in use, 1 indicates free.
+  /// The size of this field is the number of bytes required to hold the bitmask with NSlot bits,
+  /// padded with additional zero bytes to make the Index Block size a multiple of EFI_NVDIMM_LABEL_INDEX_ALIGN.
+  /// Any bits allocated beyond NSlot bits must be zero.
+  ///
+  UINT8  Free[];
+} EFI_NVDIMM_LABEL_INDEX_BLOCK;
+
+#define EFI_NVDIMM_LABEL_NAME_LEN 64
+
+///
+/// The label is read-only.
+///
+#define EFI_NVDIMM_LABEL_FLAGS_ROLABEL 0x00000001
+
+///
+/// When set, the complete label set is local to a single NVDIMM Label Storage Area.
+/// When clear, the complete label set is contained on multiple NVDIMM Label Storage Areas.
+///
+#define EFI_NVDIMM_LABEL_FLAGS_LOCAL 0x00000002
+
+///
+/// This reserved flag is utilized on older implementations and has been deprecated.
+/// Do not use.
+//
+#define EFI_NVDIMM_LABEL_FLAGS_RESERVED 0x00000004
+
+///
+/// When set, the label set is being updated.
+///
+#define EFI_NVDIMM_LABEL_FLAGS_UPDATING 0x00000008
+
+typedef struct {
+  ///
+  /// Unique Label Identifier UUID per RFC 4122.
+  ///
+  EFI_GUID Uuid;
+
+  ///
+  /// NULL-terminated string using UTF-8 character formatting.
+  ///
+  CHAR8    Name[EFI_NVDIMM_LABEL_NAME_LEN];
+
+  ///
+  /// Attributes of this namespace.
+  ///
+  UINT32   Flags;
+
+  ///
+  /// Total number of labels describing this namespace.
+  ///
+  UINT16   NLabel;
+
+  ///
+  /// Position of this label in list of labels for this namespace.
+  ///
+  UINT16   Position;
+
+  ///
+  /// The SetCookie is utilized by SW to perform consistency checks on the Interleave Set to verify the current
+  /// physical device configuration matches the original physical configuration when the labels were created
+  /// for the set.The label is considered invalid if the actual label set cookie doesn't match the cookie stored here.
+  ///
+  UINT64   SetCookie;
+
+  ///
+  /// This is the default logical block size in bytes and may be superseded by a block size that is specified
+  /// in the AbstractionGuid.
+  ///
+  UINT64   LbaSize;
+
+  ///
+  /// The DPA is the DIMM Physical address where the NVM contributing to this namespace begins on this NVDIMM.
+  ///
+  UINT64   Dpa;
+
+  ///
+  /// The extent of the DPA contributed by this label.
+  ///
+  UINT64   RawSize;
+
+  ///
+  /// Current slot in the Label Storage Area where this label is stored.
+  ///
+  UINT32   Slot;
+
+  ///
+  /// Alignment hint used to advertise the preferred alignment of the data from within the namespace defined by this label.
+  ///
+  UINT8    Alignment;
+
+  ///
+  /// Shall be 0.
+  ///
+  UINT8    Reserved[3];
+
+  ///
+  /// Range Type GUID that describes the access mechanism for the specified DPA range.
+  ///
+  EFI_GUID TypeGuid;
+
+  ///
+  /// Identifies the address abstraction mechanism for this namespace. A value of 0 indicates no mechanism used.
+  ///
+  EFI_GUID AddressAbstractionGuid;
+
+  ///
+  /// Shall be 0.
+  ///
+  UINT8    Reserved1[88];
+
+  ///
+  /// 64-bit Fletcher64 checksum of all fields in this Label.
+  /// This field is considered zero when the checksum is computed.
+  ///
+  UINT64   Checksum;
+} EFI_NVDIMM_LABEL;
+
+typedef struct  {
+  ///
+  /// The Region Offset field from the ACPI NFIT NVDIMM Region Mapping Structure for a given entry.
+  ///
+  UINT64 RegionOffset;
+
+  ///
+  /// The serial number of the NVDIMM, assigned by the module vendor.
+  ///
+  UINT32 SerialNumber;
+
+  ///
+  /// The identifier indicating the vendor of the NVDIMM.
+  ///
+  UINT16 VendorId;
+
+  ///
+  /// The manufacturing date of the NVDIMM, assigned by the module vendor.
+  ///
+  UINT16 ManufacturingDate;
+
+  ///
+  /// The manufacturing location from for the NVDIMM, assigned by the module vendor.
+  ///
+  UINT8  ManufacturingLocation;
+
+  ///
+  /// Shall be 0.
+  ///
+  UINT8  Reserved[31];
+} EFI_NVDIMM_LABEL_SET_COOKIE_MAP;
+
+typedef struct {
+  ///
+  /// Array size is 1 if EFI_NVDIMM_LABEL_FLAGS_LOCAL is set indicating a Local Namespaces.
+  ///
+  EFI_NVDIMM_LABEL_SET_COOKIE_MAP Mapping[0];
+} EFI_NVDIMM_LABEL_SET_COOKIE_INFO;
+
+/**
+  Retrieves the Label Storage Area size and the maximum transfer size for the LabelStorageRead and
+  LabelStorageWrite methods.
+
+  @param  This                   A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
+  @param  SizeOfLabelStorageArea The size of the Label Storage Area for the NVDIMM in bytes.
+  @param  MaxTransferLength      The maximum number of bytes that can be transferred in a single call to
+                                 LabelStorageRead or LabelStorageWrite.
+
+  @retval EFI_SUCCESS            The size of theLabel Storage Area and maximum transfer size returned are valid.
+  @retval EFI_ACCESS_DENIED      The Label Storage Area for the NVDIMM device is not currently accessible.
+  @retval EFI_DEVICE_ERROR       A physical device error occurred and the data transfer failed to complete.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_INFORMATION) (
+  IN  EFI_NVDIMM_LABEL_PROTOCOL *This,
+  OUT UINT32                    *SizeOfLabelStorageArea,
+  OUT UINT32                    *MaxTransferLength
+  );
+
+/**
+  Retrieves the label data for the requested offset and length from within the Label Storage Area for
+  the NVDIMM.
+
+  @param  This                   A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
+  @param  Offset                 The byte offset within the Label Storage Area to read from.
+  @param  TransferLength         Number of bytes to read from the Label Storage Area beginning at the byte
+                                 Offset specified. A TransferLength of 0 reads no data.
+  @param  LabelData              The return label data read at the requested offset and length from within
+                                 the Label Storage Area.
+
+  @retval EFI_SUCCESS            The label data from the Label Storage Area for the NVDIMM was read successfully
+                                 at the specified Offset and TransferLength and LabelData contains valid data.
+  @retval EFI_INVALID_PARAMETER  Any of the following are true:
+                                 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.
+                                 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the
+                                   LabelStorageInformation return data.
+                                 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return
+                                   data.
+  @retval EFI_ACCESS_DENIED      The Label Storage Area for the NVDIMM device is not currently accessible and labels
+                                 cannot be read at this time.
+  @retval EFI_DEVICE_ERROR       A physical device error occurred and the data transfer failed to complete.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_READ) (
+  IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This,
+  IN UINT32                          Offset,
+  IN UINT32                          TransferLength,
+  OUT UINT8                          *LabelData
+  );
+
+/**
+  Writes the label data for the requested offset and length in to the Label Storage Area for the NVDIMM.
+
+  @param  This                   A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
+  @param  Offset                 The byte offset within the Label Storage Area to write to.
+  @param  TransferLength         Number of bytes to write to the Label Storage Area beginning at the byte
+                                 Offset specified. A TransferLength of 0 writes no data.
+  @param  LabelData              The return label data write at the requested offset and length from within
+                                 the Label Storage Area.
+
+  @retval EFI_SUCCESS            The label data from the Label Storage Area for the NVDIMM written read successfully
+                                 at the specified Offset and TransferLength.
+  @retval EFI_INVALID_PARAMETER  Any of the following are true:
+                                 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.
+                                 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the
+                                   LabelStorageInformation return data.
+                                 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return
+                                   data.
+  @retval EFI_ACCESS_DENIED      The Label Storage Area for the NVDIMM device is not currently accessible and labels
+                                 cannot be written at this time.
+  @retval EFI_DEVICE_ERROR       A physical device error occurred and the data transfer failed to complete.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_NVDIMM_LABEL_STORAGE_WRITE) (
+  IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This,
+  IN UINT32                          Offset,
+  IN UINT32                          TransferLength,
+  IN UINT8                           *LabelData
+  );
+
+///
+/// Provides services that allow management of labels contained in a Label Storage Area.
+///
+struct _EFI_NVDIMM_LABEL_PROTOCOL {
+  EFI_NVDIMM_LABEL_STORAGE_INFORMATION LabelStorageInformation;
+  EFI_NVDIMM_LABEL_STORAGE_READ        LabelStorageRead;
+  EFI_NVDIMM_LABEL_STORAGE_WRITE       LabelStorageWrite;
+};
+
+extern EFI_GUID gEfiNvdimmLabelProtocolGuid;
+
+#endif
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index c5279298e8..3ccd3dd5a9 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -1772,6 +1772,9 @@ [Protocols]
   ## Include/Protocol/HiiPopup.h
   gEfiHiiPopupProtocolGuid                  = { 0x4311edc0, 0x6054, 0x46d4, { 0x9e, 0x40, 0x89, 0x3e, 0xa9, 0x52, 0xfc, 0xcc }}
 
+  ## Include/Protocol/NvdimmLabel.h
+  gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80, 0x97d5, 0x4282, { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
+
   #
   # Protocols defined in Shell2.0
   #
-- 
2.12.2.windows.2