You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

352 lines
12 KiB

4 years ago
/** @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>
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