2 EFI NVDIMM Label Protocol Definition
4 The EFI NVDIMM Label Protocol is used to Provides services that allow management
5 of labels contained in a Label Storage Area that are associated with a specific
8 Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
9 This program and the accompanying materials are licensed and made available under
10 the terms and conditions of the BSD License that accompanies this distribution.
11 The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php.
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 @par Revision Reference:
18 This Protocol was introduced in UEFI Specification 2.7.
22 #ifndef __EFI_NVDIMM_LABEL_PROTOCOL_H__
23 #define __EFI_NVDIMM_LABEL_PROTOCOL_H__
25 #define EFI_NVDIMM_LABEL_PROTOCOL_GUID \
27 0xd40b6b80, 0x97d5, 0x4282, {0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 } \
30 typedef struct _EFI_NVDIMM_LABEL_PROTOCOL EFI_NVDIMM_LABEL_PROTOCOL
;
32 #define EFI_NVDIMM_LABEL_INDEX_SIG_LEN 16
33 #define EFI_NVDIMM_LABEL_INDEX_ALIGN 256
36 /// Signature of the Index Block data structure. Must be "NAMESPACE_INDEX\0".
38 CHAR8 Sig
[EFI_NVDIMM_LABEL_INDEX_SIG_LEN
];
41 /// Attributes of this Label Storage Area.
46 /// Size of each label in bytes, 128 bytes << LabelSize.
47 /// 1 means 256 bytes, 2 means 512 bytes, etc. Shall be 1 or greater.
52 /// Sequence number used to identify which of the two Index Blocks is current.
57 /// The offset of this Index Block in the Label Storage Area.
62 /// The size of this Index Block in bytes.
63 /// This field must be a multiple of the EFI_NVDIMM_LABEL_INDEX_ALIGN.
68 /// The offset of the other Index Block paired with this one.
73 /// The offset of the first slot where labels are stored in this Label Storage Area.
78 /// The total number of slots for storing labels in this Label Storage Area.
83 /// Major version number. Value shall be 1.
88 /// Minor version number. Value shall be 2.
93 /// 64-bit Fletcher64 checksum of all fields in this Index Block.
98 /// Array of unsigned bytes implementing a bitmask that tracks which label slots are free.
99 /// A bit value of 0 indicates in use, 1 indicates free.
100 /// The size of this field is the number of bytes required to hold the bitmask with NSlot bits,
101 /// padded with additional zero bytes to make the Index Block size a multiple of EFI_NVDIMM_LABEL_INDEX_ALIGN.
102 /// Any bits allocated beyond NSlot bits must be zero.
105 } EFI_NVDIMM_LABEL_INDEX_BLOCK
;
107 #define EFI_NVDIMM_LABEL_NAME_LEN 64
110 /// The label is read-only.
112 #define EFI_NVDIMM_LABEL_FLAGS_ROLABEL 0x00000001
115 /// When set, the complete label set is local to a single NVDIMM Label Storage Area.
116 /// When clear, the complete label set is contained on multiple NVDIMM Label Storage Areas.
118 #define EFI_NVDIMM_LABEL_FLAGS_LOCAL 0x00000002
121 /// This reserved flag is utilized on older implementations and has been deprecated.
124 #define EFI_NVDIMM_LABEL_FLAGS_RESERVED 0x00000004
127 /// When set, the label set is being updated.
129 #define EFI_NVDIMM_LABEL_FLAGS_UPDATING 0x00000008
133 /// Unique Label Identifier UUID per RFC 4122.
138 /// NULL-terminated string using UTF-8 character formatting.
140 CHAR8 Name
[EFI_NVDIMM_LABEL_NAME_LEN
];
143 /// Attributes of this namespace.
148 /// Total number of labels describing this namespace.
153 /// Position of this label in list of labels for this namespace.
158 /// The SetCookie is utilized by SW to perform consistency checks on the Interleave Set to verify the current
159 /// physical device configuration matches the original physical configuration when the labels were created
160 /// for the set.The label is considered invalid if the actual label set cookie doesn't match the cookie stored here.
165 /// This is the default logical block size in bytes and may be superseded by a block size that is specified
166 /// in the AbstractionGuid.
171 /// The DPA is the DIMM Physical address where the NVM contributing to this namespace begins on this NVDIMM.
176 /// The extent of the DPA contributed by this label.
181 /// Current slot in the Label Storage Area where this label is stored.
186 /// Alignment hint used to advertise the preferred alignment of the data from within the namespace defined by this label.
196 /// Range Type GUID that describes the access mechanism for the specified DPA range.
201 /// Identifies the address abstraction mechanism for this namespace. A value of 0 indicates no mechanism used.
203 EFI_GUID AddressAbstractionGuid
;
211 /// 64-bit Fletcher64 checksum of all fields in this Label.
212 /// This field is considered zero when the checksum is computed.
219 /// The Region Offset field from the ACPI NFIT NVDIMM Region Mapping Structure for a given entry.
224 /// The serial number of the NVDIMM, assigned by the module vendor.
229 /// The identifier indicating the vendor of the NVDIMM.
234 /// The manufacturing date of the NVDIMM, assigned by the module vendor.
236 UINT16 ManufacturingDate
;
239 /// The manufacturing location from for the NVDIMM, assigned by the module vendor.
241 UINT8 ManufacturingLocation
;
247 } EFI_NVDIMM_LABEL_SET_COOKIE_MAP
;
251 /// Array size is 1 if EFI_NVDIMM_LABEL_FLAGS_LOCAL is set indicating a Local Namespaces.
253 EFI_NVDIMM_LABEL_SET_COOKIE_MAP Mapping
[0];
254 } EFI_NVDIMM_LABEL_SET_COOKIE_INFO
;
257 Retrieves the Label Storage Area size and the maximum transfer size for the LabelStorageRead and
258 LabelStorageWrite methods.
260 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
261 @param SizeOfLabelStorageArea The size of the Label Storage Area for the NVDIMM in bytes.
262 @param MaxTransferLength The maximum number of bytes that can be transferred in a single call to
263 LabelStorageRead or LabelStorageWrite.
265 @retval EFI_SUCCESS The size of theLabel Storage Area and maximum transfer size returned are valid.
266 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible.
267 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.
271 (EFIAPI
*EFI_NVDIMM_LABEL_STORAGE_INFORMATION
) (
272 IN EFI_NVDIMM_LABEL_PROTOCOL
*This
,
273 OUT UINT32
*SizeOfLabelStorageArea
,
274 OUT UINT32
*MaxTransferLength
278 Retrieves the label data for the requested offset and length from within the Label Storage Area for
281 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
282 @param Offset The byte offset within the Label Storage Area to read from.
283 @param TransferLength Number of bytes to read from the Label Storage Area beginning at the byte
284 Offset specified. A TransferLength of 0 reads no data.
285 @param LabelData The return label data read at the requested offset and length from within
286 the Label Storage Area.
288 @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM was read successfully
289 at the specified Offset and TransferLength and LabelData contains valid data.
290 @retval EFI_INVALID_PARAMETER Any of the following are true:
291 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.
292 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the
293 LabelStorageInformation return data.
294 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return
296 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels
297 cannot be read at this time.
298 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.
302 (EFIAPI
*EFI_NVDIMM_LABEL_STORAGE_READ
) (
303 IN CONST EFI_NVDIMM_LABEL_PROTOCOL
*This
,
305 IN UINT32 TransferLength
,
310 Writes the label data for the requested offset and length in to the Label Storage Area for the NVDIMM.
312 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance.
313 @param Offset The byte offset within the Label Storage Area to write to.
314 @param TransferLength Number of bytes to write to the Label Storage Area beginning at the byte
315 Offset specified. A TransferLength of 0 writes no data.
316 @param LabelData The return label data write at the requested offset and length from within
317 the Label Storage Area.
319 @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM written read successfully
320 at the specified Offset and TransferLength.
321 @retval EFI_INVALID_PARAMETER Any of the following are true:
322 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data.
323 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the
324 LabelStorageInformation return data.
325 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return
327 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels
328 cannot be written at this time.
329 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete.
333 (EFIAPI
*EFI_NVDIMM_LABEL_STORAGE_WRITE
) (
334 IN CONST EFI_NVDIMM_LABEL_PROTOCOL
*This
,
336 IN UINT32 TransferLength
,
341 /// Provides services that allow management of labels contained in a Label Storage Area.
343 struct _EFI_NVDIMM_LABEL_PROTOCOL
{
344 EFI_NVDIMM_LABEL_STORAGE_INFORMATION LabelStorageInformation
;
345 EFI_NVDIMM_LABEL_STORAGE_READ LabelStorageRead
;
346 EFI_NVDIMM_LABEL_STORAGE_WRITE LabelStorageWrite
;
349 extern EFI_GUID gEfiNvdimmLabelProtocolGuid
;