1*f334afcfSToomas Soome /** @file 2*f334afcfSToomas Soome This protocol provides services that allow NVM Express commands to be sent to an 3*f334afcfSToomas Soome NVM Express controller or to a specific namespace in a NVM Express controller. 4*f334afcfSToomas Soome This protocol interface is optimized for storage. 5*f334afcfSToomas Soome 6*f334afcfSToomas Soome Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> 7*f334afcfSToomas Soome SPDX-License-Identifier: BSD-2-Clause-Patent 8*f334afcfSToomas Soome 9*f334afcfSToomas Soome @par Revision Reference: 10*f334afcfSToomas Soome This Protocol was introduced in UEFI Specification 2.5. 11*f334afcfSToomas Soome 12*f334afcfSToomas Soome **/ 13*f334afcfSToomas Soome 14*f334afcfSToomas Soome #ifndef _UEFI_NVM_EXPRESS_PASS_THRU_H_ 15*f334afcfSToomas Soome #define _UEFI_NVM_EXPRESS_PASS_THRU_H_ 16*f334afcfSToomas Soome 17*f334afcfSToomas Soome #define EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL_GUID \ 18*f334afcfSToomas Soome { \ 19*f334afcfSToomas Soome 0x52c78312, 0x8edc, 0x4233, { 0x98, 0xf2, 0x1a, 0x1a, 0xa5, 0xe3, 0x88, 0xa5 } \ 20*f334afcfSToomas Soome } 21*f334afcfSToomas Soome 22*f334afcfSToomas Soome typedef struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL; 23*f334afcfSToomas Soome 24*f334afcfSToomas Soome typedef struct { 25*f334afcfSToomas Soome UINT32 Attributes; 26*f334afcfSToomas Soome UINT32 IoAlign; 27*f334afcfSToomas Soome UINT32 NvmeVersion; 28*f334afcfSToomas Soome } EFI_NVM_EXPRESS_PASS_THRU_MODE; 29*f334afcfSToomas Soome 30*f334afcfSToomas Soome // 31*f334afcfSToomas Soome // If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is 32*f334afcfSToomas Soome // for directly addressable namespaces. 33*f334afcfSToomas Soome // 34*f334afcfSToomas Soome #define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_PHYSICAL 0x0001 35*f334afcfSToomas Soome // 36*f334afcfSToomas Soome // If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is 37*f334afcfSToomas Soome // for a single volume logical namespace comprised of multiple namespaces. 38*f334afcfSToomas Soome // 39*f334afcfSToomas Soome #define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_LOGICAL 0x0002 40*f334afcfSToomas Soome // 41*f334afcfSToomas Soome // If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface 42*f334afcfSToomas Soome // supports non-blocking I/O. 43*f334afcfSToomas Soome // 44*f334afcfSToomas Soome #define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_NONBLOCKIO 0x0004 45*f334afcfSToomas Soome // 46*f334afcfSToomas Soome // If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface 47*f334afcfSToomas Soome // supports NVM command set. 48*f334afcfSToomas Soome // 49*f334afcfSToomas Soome #define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_CMD_SET_NVM 0x0008 50*f334afcfSToomas Soome 51*f334afcfSToomas Soome // 52*f334afcfSToomas Soome // FusedOperation 53*f334afcfSToomas Soome // 54*f334afcfSToomas Soome #define NORMAL_CMD 0x00 55*f334afcfSToomas Soome #define FUSED_FIRST_CMD 0x01 56*f334afcfSToomas Soome #define FUSED_SECOND_CMD 0x02 57*f334afcfSToomas Soome 58*f334afcfSToomas Soome typedef struct { 59*f334afcfSToomas Soome UINT32 Opcode : 8; 60*f334afcfSToomas Soome UINT32 FusedOperation : 2; 61*f334afcfSToomas Soome UINT32 Reserved : 22; 62*f334afcfSToomas Soome } NVME_CDW0; 63*f334afcfSToomas Soome 64*f334afcfSToomas Soome // 65*f334afcfSToomas Soome // Flags 66*f334afcfSToomas Soome // 67*f334afcfSToomas Soome #define CDW2_VALID 0x01 68*f334afcfSToomas Soome #define CDW3_VALID 0x02 69*f334afcfSToomas Soome #define CDW10_VALID 0x04 70*f334afcfSToomas Soome #define CDW11_VALID 0x08 71*f334afcfSToomas Soome #define CDW12_VALID 0x10 72*f334afcfSToomas Soome #define CDW13_VALID 0x20 73*f334afcfSToomas Soome #define CDW14_VALID 0x40 74*f334afcfSToomas Soome #define CDW15_VALID 0x80 75*f334afcfSToomas Soome 76*f334afcfSToomas Soome // 77*f334afcfSToomas Soome // Queue Type 78*f334afcfSToomas Soome // 79*f334afcfSToomas Soome #define NVME_ADMIN_QUEUE 0x00 80*f334afcfSToomas Soome #define NVME_IO_QUEUE 0x01 81*f334afcfSToomas Soome 82*f334afcfSToomas Soome typedef struct { 83*f334afcfSToomas Soome NVME_CDW0 Cdw0; 84*f334afcfSToomas Soome UINT8 Flags; 85*f334afcfSToomas Soome UINT32 Nsid; 86*f334afcfSToomas Soome UINT32 Cdw2; 87*f334afcfSToomas Soome UINT32 Cdw3; 88*f334afcfSToomas Soome UINT32 Cdw10; 89*f334afcfSToomas Soome UINT32 Cdw11; 90*f334afcfSToomas Soome UINT32 Cdw12; 91*f334afcfSToomas Soome UINT32 Cdw13; 92*f334afcfSToomas Soome UINT32 Cdw14; 93*f334afcfSToomas Soome UINT32 Cdw15; 94*f334afcfSToomas Soome } EFI_NVM_EXPRESS_COMMAND; 95*f334afcfSToomas Soome 96*f334afcfSToomas Soome typedef struct { 97*f334afcfSToomas Soome UINT32 DW0; 98*f334afcfSToomas Soome UINT32 DW1; 99*f334afcfSToomas Soome UINT32 DW2; 100*f334afcfSToomas Soome UINT32 DW3; 101*f334afcfSToomas Soome } EFI_NVM_EXPRESS_COMPLETION; 102*f334afcfSToomas Soome 103*f334afcfSToomas Soome typedef struct { 104*f334afcfSToomas Soome UINT64 CommandTimeout; 105*f334afcfSToomas Soome VOID *TransferBuffer; 106*f334afcfSToomas Soome UINT32 TransferLength; 107*f334afcfSToomas Soome VOID *MetadataBuffer; 108*f334afcfSToomas Soome UINT32 MetadataLength; 109*f334afcfSToomas Soome UINT8 QueueType; 110*f334afcfSToomas Soome EFI_NVM_EXPRESS_COMMAND *NvmeCmd; 111*f334afcfSToomas Soome EFI_NVM_EXPRESS_COMPLETION *NvmeCompletion; 112*f334afcfSToomas Soome } EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET; 113*f334afcfSToomas Soome 114*f334afcfSToomas Soome // 115*f334afcfSToomas Soome // Protocol function prototypes 116*f334afcfSToomas Soome // 117*f334afcfSToomas Soome 118*f334afcfSToomas Soome /** 119*f334afcfSToomas Soome Sends an NVM Express Command Packet to an NVM Express controller or namespace. This function supports 120*f334afcfSToomas Soome both blocking I/O and non-blocking I/O. The blocking I/O functionality is required, and the non-blocking 121*f334afcfSToomas Soome I/O functionality is optional. 122*f334afcfSToomas Soome 123*f334afcfSToomas Soome 124*f334afcfSToomas Soome @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. 125*f334afcfSToomas Soome @param[in] NamespaceId A 32 bit namespace ID as defined in the NVMe specification to which the NVM Express Command 126*f334afcfSToomas Soome Packet will be sent. A value of 0 denotes the NVM Express controller, a value of all 0xFF's 127*f334afcfSToomas Soome (all bytes are 0xFF) in the namespace ID specifies that the command packet should be sent to 128*f334afcfSToomas Soome all valid namespaces. 129*f334afcfSToomas Soome @param[in,out] Packet A pointer to the NVM Express Command Packet. 130*f334afcfSToomas Soome @param[in] Event If non-blocking I/O is not supported then Event is ignored, and blocking I/O is performed. 131*f334afcfSToomas Soome If Event is NULL, then blocking I/O is performed. If Event is not NULL and non-blocking I/O 132*f334afcfSToomas Soome is supported, then non-blocking I/O is performed, and Event will be signaled when the NVM 133*f334afcfSToomas Soome Express Command Packet completes. 134*f334afcfSToomas Soome 135*f334afcfSToomas Soome @retval EFI_SUCCESS The NVM Express Command Packet was sent by the host. TransferLength bytes were transferred 136*f334afcfSToomas Soome to, or from DataBuffer. 137*f334afcfSToomas Soome @retval EFI_BAD_BUFFER_SIZE The NVM Express Command Packet was not executed. The number of bytes that could be transferred 138*f334afcfSToomas Soome is returned in TransferLength. 139*f334afcfSToomas Soome @retval EFI_NOT_READY The NVM Express Command Packet could not be sent because the controller is not ready. The caller 140*f334afcfSToomas Soome may retry again later. 141*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR A device error occurred while attempting to send the NVM Express Command Packet. 142*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER NamespaceId or the contents of EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET are invalid. The NVM 143*f334afcfSToomas Soome Express Command Packet was not sent, so no additional status information is available. 144*f334afcfSToomas Soome @retval EFI_UNSUPPORTED The command described by the NVM Express Command Packet is not supported by the NVM Express 145*f334afcfSToomas Soome controller. The NVM Express Command Packet was not sent so no additional status information 146*f334afcfSToomas Soome is available. 147*f334afcfSToomas Soome @retval EFI_TIMEOUT A timeout occurred while waiting for the NVM Express Command Packet to execute. 148*f334afcfSToomas Soome 149*f334afcfSToomas Soome **/ 150*f334afcfSToomas Soome typedef 151*f334afcfSToomas Soome EFI_STATUS 152*f334afcfSToomas Soome (EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU)( 153*f334afcfSToomas Soome IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, 154*f334afcfSToomas Soome IN UINT32 NamespaceId, 155*f334afcfSToomas Soome IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET *Packet, 156*f334afcfSToomas Soome IN EFI_EVENT Event OPTIONAL 157*f334afcfSToomas Soome ); 158*f334afcfSToomas Soome 159*f334afcfSToomas Soome /** 160*f334afcfSToomas Soome Used to retrieve the next namespace ID for this NVM Express controller. 161*f334afcfSToomas Soome 162*f334afcfSToomas Soome The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNextNamespace() function retrieves the next valid 163*f334afcfSToomas Soome namespace ID on this NVM Express controller. 164*f334afcfSToomas Soome 165*f334afcfSToomas Soome If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first valid namespace 166*f334afcfSToomas Soome ID defined on the NVM Express controller is returned in the location pointed to by NamespaceId 167*f334afcfSToomas Soome and a status of EFI_SUCCESS is returned. 168*f334afcfSToomas Soome 169*f334afcfSToomas Soome If on input the value pointed to by NamespaceId is an invalid namespace ID other than 0xFFFFFFFF, 170*f334afcfSToomas Soome then EFI_INVALID_PARAMETER is returned. 171*f334afcfSToomas Soome 172*f334afcfSToomas Soome If on input the value pointed to by NamespaceId is a valid namespace ID, then the next valid 173*f334afcfSToomas Soome namespace ID on the NVM Express controller is returned in the location pointed to by NamespaceId, 174*f334afcfSToomas Soome and EFI_SUCCESS is returned. 175*f334afcfSToomas Soome 176*f334afcfSToomas Soome If the value pointed to by NamespaceId is the namespace ID of the last namespace on the NVM 177*f334afcfSToomas Soome Express controller, then EFI_NOT_FOUND is returned. 178*f334afcfSToomas Soome 179*f334afcfSToomas Soome @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. 180*f334afcfSToomas Soome @param[in,out] NamespaceId On input, a pointer to a legal NamespaceId for an NVM Express 181*f334afcfSToomas Soome namespace present on the NVM Express controller. On output, a 182*f334afcfSToomas Soome pointer to the next NamespaceId of an NVM Express namespace on 183*f334afcfSToomas Soome an NVM Express controller. An input value of 0xFFFFFFFF retrieves 184*f334afcfSToomas Soome the first NamespaceId for an NVM Express namespace present on an 185*f334afcfSToomas Soome NVM Express controller. 186*f334afcfSToomas Soome 187*f334afcfSToomas Soome @retval EFI_SUCCESS The Namespace ID of the next Namespace was returned. 188*f334afcfSToomas Soome @retval EFI_NOT_FOUND There are no more namespaces defined on this controller. 189*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER NamespaceId is an invalid value other than 0xFFFFFFFF. 190*f334afcfSToomas Soome 191*f334afcfSToomas Soome **/ 192*f334afcfSToomas Soome typedef 193*f334afcfSToomas Soome EFI_STATUS 194*f334afcfSToomas Soome (EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE)( 195*f334afcfSToomas Soome IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, 196*f334afcfSToomas Soome IN OUT UINT32 *NamespaceId 197*f334afcfSToomas Soome ); 198*f334afcfSToomas Soome 199*f334afcfSToomas Soome /** 200*f334afcfSToomas Soome Used to allocate and build a device path node for an NVM Express namespace on an NVM Express controller. 201*f334afcfSToomas Soome 202*f334afcfSToomas Soome The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.BuildDevicePath() function allocates and builds a single device 203*f334afcfSToomas Soome path node for the NVM Express namespace specified by NamespaceId. 204*f334afcfSToomas Soome 205*f334afcfSToomas Soome If the NamespaceId is not valid, then EFI_NOT_FOUND is returned. 206*f334afcfSToomas Soome 207*f334afcfSToomas Soome If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. 208*f334afcfSToomas Soome 209*f334afcfSToomas Soome If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned. 210*f334afcfSToomas Soome 211*f334afcfSToomas Soome Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of DevicePath are 212*f334afcfSToomas Soome initialized to describe the NVM Express namespace specified by NamespaceId, and EFI_SUCCESS is returned. 213*f334afcfSToomas Soome 214*f334afcfSToomas Soome @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. 215*f334afcfSToomas Soome @param[in] NamespaceId The NVM Express namespace ID for which a device path node is to be 216*f334afcfSToomas Soome allocated and built. Caller must set the NamespaceId to zero if the 217*f334afcfSToomas Soome device path node will contain a valid UUID. 218*f334afcfSToomas Soome @param[out] DevicePath A pointer to a single device path node that describes the NVM Express 219*f334afcfSToomas Soome namespace specified by NamespaceId. This function is responsible for 220*f334afcfSToomas Soome allocating the buffer DevicePath with the boot service AllocatePool(). 221*f334afcfSToomas Soome It is the caller's responsibility to free DevicePath when the caller 222*f334afcfSToomas Soome is finished with DevicePath. 223*f334afcfSToomas Soome @retval EFI_SUCCESS The device path node that describes the NVM Express namespace specified 224*f334afcfSToomas Soome by NamespaceId was allocated and returned in DevicePath. 225*f334afcfSToomas Soome @retval EFI_NOT_FOUND The NamespaceId is not valid. 226*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER DevicePath is NULL. 227*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the DevicePath node. 228*f334afcfSToomas Soome 229*f334afcfSToomas Soome **/ 230*f334afcfSToomas Soome typedef 231*f334afcfSToomas Soome EFI_STATUS 232*f334afcfSToomas Soome (EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH)( 233*f334afcfSToomas Soome IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, 234*f334afcfSToomas Soome IN UINT32 NamespaceId, 235*f334afcfSToomas Soome OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath 236*f334afcfSToomas Soome ); 237*f334afcfSToomas Soome 238*f334afcfSToomas Soome /** 239*f334afcfSToomas Soome Used to translate a device path node to a namespace ID. 240*f334afcfSToomas Soome 241*f334afcfSToomas Soome The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNamespace() function determines the namespace ID associated with the 242*f334afcfSToomas Soome namespace described by DevicePath. 243*f334afcfSToomas Soome 244*f334afcfSToomas Soome If DevicePath is a device path node type that the NVM Express Pass Thru driver supports, then the NVM Express 245*f334afcfSToomas Soome Pass Thru driver will attempt to translate the contents DevicePath into a namespace ID. 246*f334afcfSToomas Soome 247*f334afcfSToomas Soome If this translation is successful, then that namespace ID is returned in NamespaceId, and EFI_SUCCESS is returned 248*f334afcfSToomas Soome 249*f334afcfSToomas Soome @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. 250*f334afcfSToomas Soome @param[in] DevicePath A pointer to the device path node that describes an NVM Express namespace on 251*f334afcfSToomas Soome the NVM Express controller. 252*f334afcfSToomas Soome @param[out] NamespaceId The NVM Express namespace ID contained in the device path node. 253*f334afcfSToomas Soome 254*f334afcfSToomas Soome @retval EFI_SUCCESS DevicePath was successfully translated to NamespaceId. 255*f334afcfSToomas Soome @retval EFI_INVALID_PARAMETER If DevicePath or NamespaceId are NULL, then EFI_INVALID_PARAMETER is returned. 256*f334afcfSToomas Soome @retval EFI_UNSUPPORTED If DevicePath is not a device path node type that the NVM Express Pass Thru driver 257*f334afcfSToomas Soome supports, then EFI_UNSUPPORTED is returned. 258*f334afcfSToomas Soome @retval EFI_NOT_FOUND If DevicePath is a device path node type that the NVM Express Pass Thru driver 259*f334afcfSToomas Soome supports, but there is not a valid translation from DevicePath to a namespace ID, 260*f334afcfSToomas Soome then EFI_NOT_FOUND is returned. 261*f334afcfSToomas Soome **/ 262*f334afcfSToomas Soome typedef 263*f334afcfSToomas Soome EFI_STATUS 264*f334afcfSToomas Soome (EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE)( 265*f334afcfSToomas Soome IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, 266*f334afcfSToomas Soome IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 267*f334afcfSToomas Soome OUT UINT32 *NamespaceId 268*f334afcfSToomas Soome ); 269*f334afcfSToomas Soome 270*f334afcfSToomas Soome // 271*f334afcfSToomas Soome // Protocol Interface Structure 272*f334afcfSToomas Soome // 273*f334afcfSToomas Soome struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL { 274*f334afcfSToomas Soome EFI_NVM_EXPRESS_PASS_THRU_MODE *Mode; 275*f334afcfSToomas Soome EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU PassThru; 276*f334afcfSToomas Soome EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE GetNextNamespace; 277*f334afcfSToomas Soome EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; 278*f334afcfSToomas Soome EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE GetNamespace; 279*f334afcfSToomas Soome }; 280*f334afcfSToomas Soome 281*f334afcfSToomas Soome extern EFI_GUID gEfiNvmExpressPassThruProtocolGuid; 282*f334afcfSToomas Soome 283*f334afcfSToomas Soome #endif 284