MdePkg/Include/Protocol/NvdimmLabel.h

   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