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
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel
© 2016 - 2024 Red Hat, Inc.