/** @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>
SPDX-License-Identifier: BSD-2-Clause-Patent

  @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.
/// If NLabel is 1 then setting this flag is optional and it is implied that the
/// EFI_NVDIMM_LABEL_FLAGS_LOCAL flag is set as the complete label set is local to a single NVDIMM Label Storage Area.
///
#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

///
/// When set, the SPALocationCookie in the namespace label is valid and should match the
/// current value in the NFIT SPA Range Structure.
///
#define EFI_NVDIMM_LABEL_FLAGS_SPACOOKIE_BOUND  0x00000010

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;

  ///
  /// When creating the label, this value is set to the value from the NFIT SPA Range Structure if the
  /// SPALocationCookie flag (bit 2) is set. If EFI_NVDIMM_LABEL_FLAGS_SPACOOKIE_BOUND is set, the SPALocationCookie
  /// value stored in the namespace label should match the current value in the NFIT SPA Range Structure.
  /// Otherwise, the data may not be read correctly.
  ///
  UINT64      SPALocationCookie;

  ///
  /// Shall be 0.
  ///
  UINT8       Reserved1[80];

  ///
  /// 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