1 /** @file 2 EFI NVDIMM Label Protocol Definition 3 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 6 NVDIMM Device Path. 7 8 Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> 9 SPDX-License-Identifier: BSD-2-Clause-Patent 10 11 @par Revision Reference: 12 This Protocol was introduced in UEFI Specification 2.7. 13 14 **/ 15 16 #ifndef __EFI_NVDIMM_LABEL_PROTOCOL_H__ 17 #define __EFI_NVDIMM_LABEL_PROTOCOL_H__ 18 19 #define EFI_NVDIMM_LABEL_PROTOCOL_GUID \ 20 { \ 21 0xd40b6b80, 0x97d5, 0x4282, {0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 } \ 22 } 23 24 typedef struct _EFI_NVDIMM_LABEL_PROTOCOL EFI_NVDIMM_LABEL_PROTOCOL; 25 26 #define EFI_NVDIMM_LABEL_INDEX_SIG_LEN 16 27 #define EFI_NVDIMM_LABEL_INDEX_ALIGN 256 28 typedef struct { 29 /// 30 /// Signature of the Index Block data structure. Must be "NAMESPACE_INDEX\0". 31 /// 32 CHAR8 Sig[EFI_NVDIMM_LABEL_INDEX_SIG_LEN]; 33 34 /// 35 /// Attributes of this Label Storage Area. 36 /// 37 UINT8 Flags[3]; 38 39 /// 40 /// Size of each label in bytes, 128 bytes << LabelSize. 41 /// 1 means 256 bytes, 2 means 512 bytes, etc. Shall be 1 or greater. 42 /// 43 UINT8 LabelSize; 44 45 /// 46 /// Sequence number used to identify which of the two Index Blocks is current. 47 /// 48 UINT32 Seq; 49 50 /// 51 /// The offset of this Index Block in the Label Storage Area. 52 /// 53 UINT64 MyOff; 54 55 /// 56 /// The size of this Index Block in bytes. 57 /// This field must be a multiple of the EFI_NVDIMM_LABEL_INDEX_ALIGN. 58 /// 59 UINT64 MySize; 60 61 /// 62 /// The offset of the other Index Block paired with this one. 63 /// 64 UINT64 OtherOff; 65 66 /// 67 /// The offset of the first slot where labels are stored in this Label Storage Area. 68 /// 69 UINT64 LabelOff; 70 71 /// 72 /// The total number of slots for storing labels in this Label Storage Area. 73 /// 74 UINT32 NSlot; 75 76 /// 77 /// Major version number. Value shall be 1. 78 /// 79 UINT16 Major; 80 81 /// 82 /// Minor version number. Value shall be 2. 83 /// 84 UINT16 Minor; 85 86 /// 87 /// 64-bit Fletcher64 checksum of all fields in this Index Block. 88 /// 89 UINT64 Checksum; 90 91 /// 92 /// Array of unsigned bytes implementing a bitmask that tracks which label slots are free. 93 /// A bit value of 0 indicates in use, 1 indicates free. 94 /// The size of this field is the number of bytes required to hold the bitmask with NSlot bits, 95 /// padded with additional zero bytes to make the Index Block size a multiple of EFI_NVDIMM_LABEL_INDEX_ALIGN. 96 /// Any bits allocated beyond NSlot bits must be zero. 97 /// 98 UINT8 Free[]; 99 } EFI_NVDIMM_LABEL_INDEX_BLOCK; 100 101 #define EFI_NVDIMM_LABEL_NAME_LEN 64 102 103 /// 104 /// The label is read-only. 105 /// 106 #define EFI_NVDIMM_LABEL_FLAGS_ROLABEL 0x00000001 107 108 /// 109 /// When set, the complete label set is local to a single NVDIMM Label Storage Area. 110 /// When clear, the complete label set is contained on multiple NVDIMM Label Storage Areas. 111 /// 112 #define EFI_NVDIMM_LABEL_FLAGS_LOCAL 0x00000002 113 114 /// 115 /// This reserved flag is utilized on older implementations and has been deprecated. 116 /// Do not use. 117 // 118 #define EFI_NVDIMM_LABEL_FLAGS_RESERVED 0x00000004 119 120 /// 121 /// When set, the label set is being updated. 122 /// 123 #define EFI_NVDIMM_LABEL_FLAGS_UPDATING 0x00000008 124 125 typedef struct { 126 /// 127 /// Unique Label Identifier UUID per RFC 4122. 128 /// 129 EFI_GUID Uuid; 130 131 /// 132 /// NULL-terminated string using UTF-8 character formatting. 133 /// 134 CHAR8 Name[EFI_NVDIMM_LABEL_NAME_LEN]; 135 136 /// 137 /// Attributes of this namespace. 138 /// 139 UINT32 Flags; 140 141 /// 142 /// Total number of labels describing this namespace. 143 /// 144 UINT16 NLabel; 145 146 /// 147 /// Position of this label in list of labels for this namespace. 148 /// 149 UINT16 Position; 150 151 /// 152 /// The SetCookie is utilized by SW to perform consistency checks on the Interleave Set to verify the current 153 /// physical device configuration matches the original physical configuration when the labels were created 154 /// for the set.The label is considered invalid if the actual label set cookie doesn't match the cookie stored here. 155 /// 156 UINT64 SetCookie; 157 158 /// 159 /// This is the default logical block size in bytes and may be superseded by a block size that is specified 160 /// in the AbstractionGuid. 161 /// 162 UINT64 LbaSize; 163 164 /// 165 /// The DPA is the DIMM Physical address where the NVM contributing to this namespace begins on this NVDIMM. 166 /// 167 UINT64 Dpa; 168 169 /// 170 /// The extent of the DPA contributed by this label. 171 /// 172 UINT64 RawSize; 173 174 /// 175 /// Current slot in the Label Storage Area where this label is stored. 176 /// 177 UINT32 Slot; 178 179 /// 180 /// Alignment hint used to advertise the preferred alignment of the data from within the namespace defined by this label. 181 /// 182 UINT8 Alignment; 183 184 /// 185 /// Shall be 0. 186 /// 187 UINT8 Reserved[3]; 188 189 /// 190 /// Range Type GUID that describes the access mechanism for the specified DPA range. 191 /// 192 EFI_GUID TypeGuid; 193 194 /// 195 /// Identifies the address abstraction mechanism for this namespace. A value of 0 indicates no mechanism used. 196 /// 197 EFI_GUID AddressAbstractionGuid; 198 199 /// 200 /// Shall be 0. 201 /// 202 UINT8 Reserved1[88]; 203 204 /// 205 /// 64-bit Fletcher64 checksum of all fields in this Label. 206 /// This field is considered zero when the checksum is computed. 207 /// 208 UINT64 Checksum; 209 } EFI_NVDIMM_LABEL; 210 211 typedef struct { 212 /// 213 /// The Region Offset field from the ACPI NFIT NVDIMM Region Mapping Structure for a given entry. 214 /// 215 UINT64 RegionOffset; 216 217 /// 218 /// The serial number of the NVDIMM, assigned by the module vendor. 219 /// 220 UINT32 SerialNumber; 221 222 /// 223 /// The identifier indicating the vendor of the NVDIMM. 224 /// 225 UINT16 VendorId; 226 227 /// 228 /// The manufacturing date of the NVDIMM, assigned by the module vendor. 229 /// 230 UINT16 ManufacturingDate; 231 232 /// 233 /// The manufacturing location from for the NVDIMM, assigned by the module vendor. 234 /// 235 UINT8 ManufacturingLocation; 236 237 /// 238 /// Shall be 0. 239 /// 240 UINT8 Reserved[31]; 241 } EFI_NVDIMM_LABEL_SET_COOKIE_MAP; 242 243 typedef struct { 244 /// 245 /// Array size is 1 if EFI_NVDIMM_LABEL_FLAGS_LOCAL is set indicating a Local Namespaces. 246 /// 247 EFI_NVDIMM_LABEL_SET_COOKIE_MAP Mapping[0]; 248 } EFI_NVDIMM_LABEL_SET_COOKIE_INFO; 249 250 /** 251 Retrieves the Label Storage Area size and the maximum transfer size for the LabelStorageRead and 252 LabelStorageWrite methods. 253 254 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. 255 @param SizeOfLabelStorageArea The size of the Label Storage Area for the NVDIMM in bytes. 256 @param MaxTransferLength The maximum number of bytes that can be transferred in a single call to 257 LabelStorageRead or LabelStorageWrite. 258 259 @retval EFI_SUCCESS The size of theLabel Storage Area and maximum transfer size returned are valid. 260 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible. 261 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. 262 **/ 263 typedef 264 EFI_STATUS 265 (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_INFORMATION) ( 266 IN EFI_NVDIMM_LABEL_PROTOCOL *This, 267 OUT UINT32 *SizeOfLabelStorageArea, 268 OUT UINT32 *MaxTransferLength 269 ); 270 271 /** 272 Retrieves the label data for the requested offset and length from within the Label Storage Area for 273 the NVDIMM. 274 275 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. 276 @param Offset The byte offset within the Label Storage Area to read from. 277 @param TransferLength Number of bytes to read from the Label Storage Area beginning at the byte 278 Offset specified. A TransferLength of 0 reads no data. 279 @param LabelData The return label data read at the requested offset and length from within 280 the Label Storage Area. 281 282 @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM was read successfully 283 at the specified Offset and TransferLength and LabelData contains valid data. 284 @retval EFI_INVALID_PARAMETER Any of the following are true: 285 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data. 286 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the 287 LabelStorageInformation return data. 288 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return 289 data. 290 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels 291 cannot be read at this time. 292 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. 293 **/ 294 typedef 295 EFI_STATUS 296 (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_READ) ( 297 IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This, 298 IN UINT32 Offset, 299 IN UINT32 TransferLength, 300 OUT UINT8 *LabelData 301 ); 302 303 /** 304 Writes the label data for the requested offset and length in to the Label Storage Area for the NVDIMM. 305 306 @param This A pointer to the EFI_NVDIMM_LABEL_PROTOCOL instance. 307 @param Offset The byte offset within the Label Storage Area to write to. 308 @param TransferLength Number of bytes to write to the Label Storage Area beginning at the byte 309 Offset specified. A TransferLength of 0 writes no data. 310 @param LabelData The return label data write at the requested offset and length from within 311 the Label Storage Area. 312 313 @retval EFI_SUCCESS The label data from the Label Storage Area for the NVDIMM written read successfully 314 at the specified Offset and TransferLength. 315 @retval EFI_INVALID_PARAMETER Any of the following are true: 316 - Offset > SizeOfLabelStorageArea reported in the LabelStorageInformation return data. 317 - Offset + TransferLength is > SizeOfLabelStorageArea reported in the 318 LabelStorageInformation return data. 319 - TransferLength is > MaxTransferLength reported in the LabelStorageInformation return 320 data. 321 @retval EFI_ACCESS_DENIED The Label Storage Area for the NVDIMM device is not currently accessible and labels 322 cannot be written at this time. 323 @retval EFI_DEVICE_ERROR A physical device error occurred and the data transfer failed to complete. 324 **/ 325 typedef 326 EFI_STATUS 327 (EFIAPI *EFI_NVDIMM_LABEL_STORAGE_WRITE) ( 328 IN CONST EFI_NVDIMM_LABEL_PROTOCOL *This, 329 IN UINT32 Offset, 330 IN UINT32 TransferLength, 331 IN UINT8 *LabelData 332 ); 333 334 /// 335 /// Provides services that allow management of labels contained in a Label Storage Area. 336 /// 337 struct _EFI_NVDIMM_LABEL_PROTOCOL { 338 EFI_NVDIMM_LABEL_STORAGE_INFORMATION LabelStorageInformation; 339 EFI_NVDIMM_LABEL_STORAGE_READ LabelStorageRead; 340 EFI_NVDIMM_LABEL_STORAGE_WRITE LabelStorageWrite; 341 }; 342 343 extern EFI_GUID gEfiNvdimmLabelProtocolGuid; 344 345 #endif 346