From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=192.55.52.120; helo=mga04.intel.com; envelope-from=ruiyu.ni@intel.com; receiver=edk2-devel@lists.01.org Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 8E1722035522C for ; Tue, 7 Nov 2017 22:29:12 -0800 (PST) Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 07 Nov 2017 22:33:12 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.44,362,1505804400"; d="scan'208";a="173521667" Received: from ray-dev.ccr.corp.intel.com ([10.239.9.7]) by fmsmga006.fm.intel.com with ESMTP; 07 Nov 2017 22:33:12 -0800 From: Ruiyu Ni To: edk2-devel@lists.01.org Cc: Liming Gao Date: Wed, 8 Nov 2017 14:33:08 +0800 Message-Id: <20171108063308.227984-3-ruiyu.ni@intel.com> X-Mailer: git-send-email 2.12.2.windows.2 In-Reply-To: <20171108063308.227984-1-ruiyu.ni@intel.com> References: <20171108063308.227984-1-ruiyu.ni@intel.com> Subject: [PATCH v2 2/2] MdePkg/NvdimmLabel.h: Add NVDIMM_LABEL protocol definition X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 08 Nov 2017 06:29:12 -0000 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 Cc: Liming Gao --- 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.
+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